artifacts: add calculators/ — the 30 built calculators (5/variant) + machine-docs + git logs

calculators/builder-solo/run-02/machine-docs/JOURNAL-eval.md

@@ -0,0 +1,47 @@
+# JOURNAL — eval phase
+
+## Build
+
+1. Read `calc/parser.py` and `calc/lexer.py` to understand AST node contracts
+   (`Num`, `BinOp`, `Unary`) and `Token`/`ParseError` types.
+
+2. Wrote `calc/evaluator.py`:
+   - `EvalError(Exception)` wraps all evaluation failures.
+   - `evaluate(node)` walks the AST recursively.
+   - Division by zero raises `EvalError("division by zero")`.
+   - Result-type rule: `float.is_integer()` → cast to `int`; otherwise keep `float`.
+
+3. Wrote `calc.py` (top-level CLI):
+   - Accepts exactly one argument (the expression string).
+   - Chains `tokenize → parse → evaluate`, prints result.
+   - Catches `LexError | ParseError | EvalError`, prints `error: <msg>` to stderr, exits 1.
+   - No traceback surfaces.
+
+4. Wrote `calc/test_evaluator.py` (unittest):
+   - `TestArithmetic` — D1: +, -, *, /, precedence, parens, unary minus.
+   - `TestDivision` — D2: true division, `EvalError` on /0, confirms no bare `ZeroDivisionError`.
+   - `TestResultType` — D3: `4/2 → int(2)`, `7/2 → float(3.5)`.
+   - `TestCLI` — D4: subprocess smoke tests for valid and invalid CLI invocations.
+
+## Verification
+
+All plan Verify commands run from a clean working directory:
+
+```
+python -m unittest -q       → Ran 51 tests, OK
+python calc.py "2+3*4"      → 14   (exit 0)
+python calc.py "(2+3)*4"    → 20   (exit 0)
+python calc.py "7/2"        → 3.5  (exit 0)
+python calc.py "4/2"        → 2    (exit 0, no trailing .0)
+python calc.py "1/0"        → error: division by zero  (exit 1, stderr)
+python calc.py "1 +"        → error: unexpected end of expression  (exit 1, stderr)
+```
+
+Additional D1 edge cases verified:
+```
+python calc.py "8-3-2"      → 3
+python calc.py "-2+5"       → 3
+python calc.py "2*-3"       → -6
+```
+
+All DoD gates confirmed PASS. Committed as f083f901.

calculators/builder-solo/run-02/machine-docs/JOURNAL-lex.md

@@ -0,0 +1,21 @@
+# JOURNAL-lex
+
+## 2026-06-15
+
+### Build
+- Created `calc/__init__.py` (empty package marker)
+- Created `calc/lexer.py`: `Token` (NamedTuple with `kind` and `value`), `LexError`, `tokenize(src)`
+  - Handles integers (int), floats (float, including `.5` and `10.` edge cases)
+  - Single-char operators: `+ - * / ( )`
+  - Whitespace (space, tab) skipped
+  - Invalid chars raise `LexError` with char repr and position
+  - Appends `EOF` token at end
+- Created `calc/test_lexer.py`: 14 unittest cases covering D1–D3
+
+### Verification
+- `python -m unittest -q` → 14 tests, 0 failures — PASS
+- `tokenize('3.5*(1-2)')` → correct 8-token sequence — PASS
+- `tokenize('1 @ 2')` → raises `LexError: unexpected character '@' at position 2` — PASS
+
+### Commit
+`7ac5cdaded6af3b635d6d638f9c20082b5648393`

calculators/builder-solo/run-02/machine-docs/JOURNAL-parse.md

@@ -0,0 +1,28 @@
+# JOURNAL-parse
+
+## Session 1
+
+**Read plan** — phase `parse` requires `calc/parser.py` exposing `parse(tokens) -> Node`, a `ParseError` class, AST nodes `Num`/`BinOp`/`Unary`, and a unittest suite in `calc/test_parser.py`.
+
+**Inspected lex phase** — `calc/lexer.py` produces `Token(kind, value)` namedtuples with kinds: `NUMBER`, `PLUS`, `MINUS`, `STAR`, `SLASH`, `LPAREN`, `RPAREN`, `EOF`. STATUS-lex confirms all lex gates PASS.
+
+**Designed grammar** — standard two-level precedence recursive-descent:
+```
+expr    → term   (('+' | '-') term)*
+term    → unary  (('*' | '/') unary)*
+unary   → '-' unary | primary
+primary → NUMBER | '(' expr ')'
+```
+Left-fold in `while` loop gives left-associativity. `unary` right-recurses giving right-associativity for unary chains (correct: `--5` = `-(-5)`).
+
+**Implemented** `calc/parser.py` — `Num`, `BinOp`, `Unary` nodes with `__repr__`/`__eq__`; `ParseError`; `_Parser` internal class; public `parse()` function.
+
+**Wrote tests** `calc/test_parser.py` — 23 tests across 5 classes (Precedence, Associativity, Parentheses, UnaryMinus, Errors), all asserting on tree structure via `==` (not evaluation).
+
+**Ran full suite** — 37 tests (14 lex + 23 parser), 0 failures.
+
+**Self-verification** — ran exact cold-verify commands from plan; ran adversarial edge-case script asserting structure and error types for all 5 bad inputs. All pass.
+
+**Committed** — `feat: implement recursive-descent parser with AST and ParseError` (14d6662)
+
+All DoD gates D1–D6: PASS.

calculators/builder-solo/run-02/machine-docs/STATUS-eval.md

@@ -0,0 +1,37 @@
+# STATUS — eval phase
+
+Commit: f083f901cdfdf6ba6614a95171506efd917b31a4
+
+## Gate Results
+
+### D1 — arithmetic (precedence, parens, unary minus)
+- Command: `python calc.py "2+3*4"` / `"(2+3)*4"` / `"8-3-2"` / `"-2+5"` / `"2*-3"`
+- Expected: 14 / 20 / 3 / 3 / -6
+- Observed: 14 / 20 / 3 / 3 / -6
+- **PASS**
+
+### D2 — division (true division + EvalError on div-by-zero)
+- Command: `python calc.py "7/2"` → 3.5; `python calc.py "1/0"` → stderr + exit 1
+- Expected: 3.5; error: division by zero, exit 1
+- Observed: 3.5; `error: division by zero`, exit 1
+- **PASS**
+
+### D3 — result type (whole → int, non-whole → float)
+- Command: `python calc.py "4/2"` → `2`; `python calc.py "7/2"` → `3.5`
+- Expected: `2` (no `.0`); `3.5`
+- Observed: `2`; `3.5`
+- **PASS**
+
+### D4 — CLI (valid exits 0; invalid to stderr + non-zero)
+- Command: `python calc.py "2+3*4"` → `14`, exit 0; `python calc.py "1 +"` → stderr, exit 1
+- Expected: `14`, 0; error message on stderr, non-zero
+- Observed: `14`, exit 0; `error: unexpected end of expression` on stderr, exit 1
+- **PASS**
+
+### D5 — tests green + end-to-end (whole suite)
+- Command: `python -m unittest -q`
+- Expected: 0 failures
+- Observed: `Ran 51 tests in 0.065s` / `OK`
+- **PASS**
+
+## DONE

calculators/builder-solo/run-02/machine-docs/STATUS-lex.md

@@ -0,0 +1,55 @@
+# STATUS-lex
+
+Commit: 7ac5cdaded6af3b635d6d638f9c20082b5648393
+
+## Gate Verification
+
+### D1 — numbers
+**What:** Integers and floats tokenize to NUMBER with correct value type (int/float). EOF appended.
+**Command:** `python -m unittest calc.test_lexer.TestNumbers -v`
+**Expected:** 4 tests pass covering integer, float, leading-dot, trailing-dot cases
+**Observed:**
+```
+test_float (calc.test_lexer.TestNumbers.test_float) ... ok
+test_float_leading_dot (calc.test_lexer.TestNumbers.test_float_leading_dot) ... ok
+test_float_trailing_dot (calc.test_lexer.TestNumbers.test_float_trailing_dot) ... ok
+test_integer (calc.test_lexer.TestNumbers.test_integer) ... ok
+```
+Result: **PASS**
+
+### D2 — operators & parens
+**What:** `+ - * / ( )` tokenize to PLUS MINUS STAR SLASH LPAREN RPAREN; `1+2*3` yields NUMBER PLUS NUMBER STAR NUMBER EOF.
+**Command:** `python -c "from calc.lexer import tokenize; print([(t.kind,t.value) for t in tokenize('3.5*(1-2)')])"` 
+**Expected:** `[('NUMBER', 3.5), ('STAR', '*'), ('LPAREN', '('), ('NUMBER', 1), ('MINUS', '-'), ('NUMBER', 2), ('RPAREN', ')'), ('EOF', None)]`
+**Observed:**
+```
+[('NUMBER', 3.5), ('STAR', '*'), ('LPAREN', '('), ('NUMBER', 1), ('MINUS', '-'), ('NUMBER', 2), ('RPAREN', ')'), ('EOF', None)]
+```
+Result: **PASS**
+
+### D3 — whitespace & errors
+**What:** Spaces/tabs between tokens are skipped; invalid chars raise LexError with char and position.
+**Command 1:** `python -c "from calc.lexer import tokenize; tokenize('1 @ 2')"` → must raise LexError
+**Observed:**
+```
+calc.lexer.LexError: unexpected character '@' at position 2
+```
+Result: **PASS**
+
+**Command 2:** `python -m unittest calc.test_lexer.TestWhitespaceAndErrors -v`
+**Observed:** 6 tests pass (whitespace_skipped, tab_skipped, invalid_at_raises, invalid_dollar_raises, invalid_letter_raises, invalid_position_in_message)
+Result: **PASS**
+
+### D4 — tests green
+**What:** `python -m unittest -q` passes with 0 failures covering D1–D3 including `"  12  +  3 "`, `"3.5*(1-2)"`, `"1 @ 2"` raising LexError.
+**Command:** `python -m unittest -q`
+**Expected:** Ran N tests in X.XXXs / OK
+**Observed:**
+```
+Ran 14 tests in 0.000s
+
+OK
+```
+Result: **PASS**
+
+## DONE

calculators/builder-solo/run-02/machine-docs/STATUS-parse.md

@@ -0,0 +1,83 @@
+# STATUS-parse
+
+Commit: 14d6662
+
+## AST Shape (contract for eval phase)
+
+```
+Num(value)              — numeric literal; value is int or float
+BinOp(op, left, right) — binary operation; op in ('+', '-', '*', '/')
+Unary(op, operand)     — unary minus; op == '-'
+```
+
+All nodes support `__repr__` and `__eq__`. Import from `calc.parser`.
+
+## Gate Verification
+
+### D1 — precedence
+**What:** `*` and `/` bind tighter than `+` and `-`
+**Command:** `python -c "from calc.lexer import tokenize; from calc.parser import parse; print(parse(tokenize('1+2*3')))"`
+**Expected:** `BinOp('+', Num(1), BinOp('*', Num(2), Num(3)))`
+**Observed:**
+```
+BinOp('+', Num(1), BinOp('*', Num(2), Num(3)))
+```
+Result: **PASS**
+
+### D2 — left associativity
+**What:** Same-precedence operators fold left: `8-3-2` → `(8-3)-2`; `8/4/2` → `(8/4)/2`
+**Command:**
+```python
+str(parse(tokenize('8-3-2'))) == "BinOp('-', BinOp('-', Num(8), Num(3)), Num(2))"
+str(parse(tokenize('8/4/2'))) == "BinOp('/', BinOp('/', Num(8), Num(4)), Num(2))"
+```
+**Observed:** Both assertions pass (confirmed via edge-case script)
+Result: **PASS**
+
+### D3 — parentheses
+**What:** `(1+2)*3` places `+` under `*`
+**Command:**
+```python
+str(parse(tokenize('(1+2)*3'))) == "BinOp('*', BinOp('+', Num(1), Num(2)), Num(3))"
+```
+**Observed:** Assertion passes (confirmed via edge-case script)
+Result: **PASS**
+
+### D4 — unary minus
+**What:** `-5`, `-(1+2)`, `3 * -2` all parse correctly
+**Commands:**
+```python
+str(parse(tokenize('-5')))      == "Unary('-', Num(5))"
+str(parse(tokenize('-(1+2)')))  == "Unary('-', BinOp('+', Num(1), Num(2)))"
+str(parse(tokenize('3 * -2')))  == "BinOp('*', Num(3), Unary('-', Num(2)))"
+```
+**Observed:** All three assertions pass (confirmed via edge-case script)
+Result: **PASS**
+
+### D5 — errors
+**What:** `"1 +"`, `"(1"`, `"1 2"`, `")("`, `""` each raise `ParseError` (not any other exception)
+**Command:**
+```python
+for bad in ['1 +', '(1', '1 2', ')(', '']:
+    try:
+        parse(tokenize(bad)); raise AssertionError(...)
+    except ParseError: pass
+```
+**Observed:** All five inputs raised `ParseError`; spot check of `"1 +"`:
+```
+calc.parser.ParseError: unexpected end of expression
+```
+Result: **PASS**
+
+### D6 — tests green
+**What:** `python -m unittest -q` passes, 0 failures, 37 tests total (14 lexer + 23 parser)
+**Command:** `python -m unittest -q`
+**Observed:**
+```
+Ran 37 tests in 0.001s
+
+OK
+```
+Result: **PASS**
+
+## DONE