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

This commit is contained in:
2026-06-16 15:39:42 +00:00
parent 64bc360fc0
commit bb85aa9f11
728 changed files with 34148 additions and 0 deletions

View File

@ -0,0 +1,7 @@
# BACKLOG — eval phase
## Build backlog
(Builder-owned — read-only to Adversary)
## Adversary findings
(None yet — awaiting Builder completion before comprehensive verification)

View File

@ -0,0 +1,10 @@
# Backlog — lex phase
## Build backlog
- [x] D1: integer/float tokenization
- [x] D2: operator and paren tokenization
- [x] D3: whitespace skip + LexError for invalid chars
- [x] D4: unittest suite green (14 tests, 0 failures)
All items complete.

View File

@ -0,0 +1,16 @@
# Backlog — parse phase
## Build backlog
All items complete.
- [x] D1 — precedence: `*`/`/` bind tighter than `+`/`-`
- [x] D2 — left associativity for same-precedence ops
- [x] D3 — parentheses override precedence
- [x] D4 — unary minus (leading, nested, after operator)
- [x] D5 — ParseError on malformed input (5 cases)
- [x] D6 — tests green (34 total, 0 failures)
## Adversary findings
(None yet — awaiting review phase)

View File

@ -0,0 +1,28 @@
# BACKLOG — review phase
## Build backlog
(Builder-owned — read-only to Adversary)
## Adversary findings
### FINDING-1 — float literal not normalized to int [OPEN]
**Filed:** 2026-06-16T00:54:18Z
**Phase:** eval/D3 (result type consistency)
**Repro:**
```bash
python calc.py "4.0" # prints 4.0 — EXPECTED: 4
python calc.py "10." # prints 10.0 — EXPECTED: 10
python calc.py "-4.0" # prints -4.0 — EXPECTED: -4
```
**Root cause:** `calc/evaluator.py` `evaluate()` applies `float→int` normalization only in the
`BinOp` branch (line 37-38). `Num` and `Unary` branches return the raw float.
**Fix needed:** Apply normalization consistently across all return paths in `evaluate()`.
Suggest a `_normalize(v)` helper applied before every return.
**Also add:** Tests for `_eval("4.0")`, `_eval("10.")`, `_eval("-4.0")`, `_eval("0.0")` to
lock in consistent behavior.
Status: CLOSED @ 2026-06-16T00:57:12Z — re-verified PASS after Builder fix.

View File

@ -0,0 +1,7 @@
# Decisions (append-only)
## lex phase
**Token.value type for operators:** stored as the literal character string (e.g. `'+'`). Considered `None` but the literal char is more useful for error messages in later phases.
**Number parsing:** greedy scan of `[0-9.]` then classify by presence of `.`. A string like `1.2.3` would tokenize as one malformed number token — acceptable for a phase-1 lexer; the evaluator/parser will catch semantic errors.

View File

@ -0,0 +1,8 @@
# JOURNAL — eval phase (Adversary)
## 2026-06-16T00:43:36Z — Phase kickoff
- Phase plan read: eval.md (evaluator + CLI, gates D1D5)
- Current state: Builder has only completed lexer (calc/lexer.py + test_lexer.py)
- Parser and evaluator not yet implemented
- Created eval phase tracking files: STATUS, REVIEW, BACKLOG, JOURNAL
- Entering wait loop per REVIEW CADENCE (defer to comprehensive single verification)

View File

@ -0,0 +1,37 @@
# Journal — lex phase
## Build run
Implemented `calc/lexer.py` with:
- `Token` dataclass with `kind` (str) and `value` (int | float | str | None)
- `LexError(Exception)` for invalid characters
- `tokenize(src: str) -> list[Token]` scanning char-by-char
Design choices:
- `Token` is a plain dataclass so later phases (parser, evaluator) can pattern-match on `.kind`
- Numbers: scanned greedily while char is digit or `.`; cast to `int` if no `.` in raw string, else `float`
- Operators stored as their literal char as `value` (handy for error messages)
- EOF always appended as final token (parser-friendly sentinel)
## Test run output
```
$ python -m unittest -q
..............
----------------------------------------------------------------------
Ran 14 tests in 0.000s
OK
```
## Verify commands output
```
$ python -c "from calc.lexer import tokenize; print([(t.kind,t.value) for t in tokenize('3.5*(1-2)')])"
[('NUMBER', 3.5), ('STAR', '*'), ('LPAREN', '('), ('NUMBER', 1), ('MINUS', '-'), ('NUMBER', 2), ('RPAREN', ')'), ('EOF', None)]
$ python -c "from calc.lexer import tokenize; tokenize('1 @ 2')"
Traceback (most recent call last):
...
calc.lexer.LexError: unexpected character '@' at position 2
```

View File

@ -0,0 +1,44 @@
# Journal — parse phase
## Adversary initial setup (2026-06-16)
- Pulled origin/main: lex phase is complete (STATUS-lex.md: ## DONE)
- Lex phase early verification passed: 14 tests, OK
- Parse phase not yet started by Builder at that point
- Per REVIEW CADENCE rules: will wait for Builder to complete parse, then do ONE
comprehensive cold-verification of all DoD items.
## Builder implementation run
### Grammar design
Used standard two-level precedence grammar:
- `_expr`: handles `+` and `-` (lower precedence)
- `_term`: handles `*` and `/` (higher precedence)
- `_unary`: handles unary `-` (right-recursive)
- `_primary`: handles `NUMBER` and `(expr)`
Both `_expr` and `_term` use iterative while-loops to achieve left associativity naturally.
### Verified outputs
```
$ python -m unittest -q
Ran 34 tests in 0.001s
OK
$ python -c "from calc.lexer import tokenize; from calc.parser import parse; print(parse(tokenize('1+2*3')))"
BinOp('+', Num(1), BinOp('*', Num(2), Num(3)))
$ python -c "from calc.lexer import tokenize; from calc.parser import parse; parse(tokenize('1 +'))"
Traceback (most recent call last):
...
calc.parser.ParseError: unexpected token 'EOF' (None)
```
### Test count
- 3 precedence tests (D1)
- 4 associativity tests (D2)
- 3 parentheses tests (D3)
- 4 unary minus tests (D4)
- 6 error tests (D5)
= 20 parser tests + 14 lex tests = 34 total

View File

@ -0,0 +1,48 @@
# JOURNAL — review phase (Adversary)
## 2026-06-16T00:47:02Z — Phase kickoff
- Phase plan read: review.md (comprehensive deferred verification)
- Current state: Builder has only completed lex and parse phases
- calc/lexer.py + calc/test_lexer.py (lex phase)
- calc/parser.py + calc/test_parser.py (parse phase)
- eval phase NOT yet complete — no evaluator or CLI in calc/
- Created review phase tracking files: STATUS-review.md, REVIEW-review.md, BACKLOG-review.md, JOURNAL-review.md
- Entering wait loop per REVIEW CADENCE (defer to comprehensive single verification)
- Will wake every ~10 min to check if Builder has completed eval phase
## 2026-06-16T00:54:18Z — Comprehensive cold-verification complete
Builder claimed D-all at commit d0e0373. Pulled and ran full verification.
Results summary:
- lex all DoD: PASS
- parse all DoD: PASS
- eval/D1,D2,D4,D5: PASS
- eval/D3 (result type): FAIL — FINDING-1 filed
- 56 tests: PASS
- D3 cross-feature review.md probes: PASS except float literal normalization
FINDING-1: float literals (e.g. `4.0`, `10.`, `-4.0`) not normalized to int.
Root cause: normalization in BinOp branch only (evaluator.py lines 37-38).
Num and Unary branches return raw float value without normalization.
Repro: `python calc.py "4.0"` prints `4.0` not `4`.
Fix: _normalize() helper applied to all return paths in evaluate().
Filed in REVIEW-review.md and BACKLOG-review.md. Pushing review(D-all): FAIL commit.
Awaiting Builder fix then re-verification.
## 2026-06-16T00:57:12Z — Re-verification after Builder fix (FINDING-1)
Builder committed fix at 1cb5f43: extracted _normalize() helper in evaluator.py,
applied to Num, Unary, and BinOp branches. 4 new tests added (60 total).
Re-verification results:
- python calc.py "4.0" → 4 ✓
- python calc.py "10." → 10 ✓
- python calc.py "-4.0" → -4 ✓
- python calc.py "0.0" → 0 ✓
- python -m unittest -q → Ran 60 tests OK ✓
- All original verification commands still pass ✓
FINDING-1 CLOSED. review(D-all): PASS committed and pushed.
Builder may now write ## DONE to STATUS-review.md.

View File

@ -0,0 +1,7 @@
# REVIEW — eval phase
Adversary cold-verification log. Per REVIEW CADENCE rules, comprehensive
verification happens ONCE after the Builder completes all gates.
## Status
PENDING — awaiting Builder completion of eval phase gates D1D5.

View File

@ -0,0 +1,16 @@
# Adversary Review — parse phase
REVIEW CADENCE: DEFERRED — comprehensive review happens ONCE after Builder completes,
not per-gate during build phases.
## Status: PENDING
Builder has not yet completed the parse phase. No verdicts issued yet.
## When triggered:
Will perform cold-verification of ALL DoD items (D1D6) from a fresh shell:
- D1: precedence (`1+2*3` tree structure)
- D2: left-associativity (`8-3-2` and `8/4/2` tree structures)
- D3: parentheses override (`(1+2)*3` tree structure)
- D4: unary minus (`-5`, `-(1+2)`, `3 * -2`)
- D5: error handling (`1 +`, `(1`, `1 2`, `)(`, empty string → ParseError)
- D6: `python -m unittest -q` passes with 0 failures

View File

@ -0,0 +1,66 @@
# REVIEW — review phase (Adversary verdicts)
## Status: PASS — comprehensive cold-verification complete
`review(D-all): PASS` @ 2026-06-16T00:57:12Z
---
## lex phase DoD — ALL PASS
- **lex/D1** PASS — `.5`→0.5, `10.`→10.0, `3.14`→3.14, `42`→42, all correct kinds/values
- **lex/D2** PASS — `+ - * / ( )` all produce correct kinds; `1+2*3``NUMBER PLUS NUMBER STAR NUMBER EOF`
- **lex/D3** PASS — whitespace skipped; `'1 @ 2'` raises `LexError: unexpected character '@' at position 2`
- **lex/D4** PASS — 14 tests, 0 failures (now part of 60-test suite)
## parse phase DoD — ALL PASS
- **parse/D1** PASS — `1+2*3``BinOp('+', Num(1), BinOp('*', Num(2), Num(3)))`
- **parse/D2** PASS — `8-3-2``BinOp('-', BinOp('-', Num(8), Num(3)), Num(2))`; `8/4/2``BinOp('/', BinOp('/', Num(8), Num(4)), Num(2))`
- **parse/D3** PASS — `(1+2)*3``BinOp('*', BinOp('+', Num(1), Num(2)), Num(3))`
- **parse/D4** PASS — `-5``Unary('-', Num(5))`; `-(1+2)` and `3*-2` correct ✓
- **parse/D5** PASS — `'1 +'`, `'(1'`, `'1 2'`, `')('`, `''` all raise `ParseError`
- **parse/D6** PASS — 20 tests, 0 failures
## eval phase DoD — ALL PASS
- **eval/D1** PASS — `2+3*4`→14, `(2+3)*4`→20, `8-3-2`→3, `-2+5`→3, `2*-3`→-6 ✓
- **eval/D2** PASS — `7/2`→3.5; `1/0` raises `EvalError`, not bare `ZeroDivisionError`
- **eval/D3** PASS (after fix) — `_normalize()` applied in all branches: `4.0`→4, `10.`→10, `-4.0`→-4, `0.0`→0, `4/2`→2, `7/2`→3.5 ✓
- **eval/D4** PASS — CLI prints result to stdout, exit 0; errors to stderr, exit 1, no traceback ✓
- **eval/D5** PASS — 60 tests, 0 failures (4 new tests for float-literal normalization added by Builder)
## review phase DoD — ALL PASS
- **D1** PASS — every prior DoD item cold-verified from fresh clone ✓
- **D2** PASS — `python -m unittest -q``Ran 60 tests in ...s OK`
- **D3** PASS — cross-feature probes all pass:
- `-(-(1+2))` → 3 ✓
- `2+3*4-5/5` → 13 ✓
- `1 @ 2`, `1/0`, `(1+` all error to stderr, exit 1, no traceback ✓
- whitespace+floats+parens: `3.5*(1-2)` works ✓
- float-literal normalization: `4.0`→4, `10.`→10, `-4.0`→-4 ✓
- **D4** PASS — FINDING-1 fixed and re-verified; no standing VETO ✓
---
## FINDING-1 — CLOSED
**Status:** RESOLVED @ 2026-06-16T00:57:12Z
**Fix:** Builder extracted `_normalize()` helper in `calc/evaluator.py` and applied it before
every return in `evaluate()` (Num, Unary, and BinOp branches). 4 new tests added to
`calc/test_evaluator.py` to lock in behavior.
**Re-verification:**
```
python calc.py "4.0" → 4 ✓
python calc.py "10." → 10 ✓
python calc.py "-4.0" → -4 ✓
python calc.py "0.0" → 0 ✓
python -m unittest -q → Ran 60 tests in ...s OK ✓
```
---
**Builder may now write `## DONE` to `machine-docs/STATUS-review.md`.**

View File

@ -0,0 +1,96 @@
## DONE
Phase: eval — evaluator + CLI
All DoD items self-certified (BUILD phase — deferred Adversary review).
---
### Files created
- `calc/evaluator.py``EvalError`, `evaluate(node) -> int | float`
- `calc.py` — top-level CLI
- `calc/test_evaluator.py` — 22 new unittest tests covering D1D4
---
### D1 — arithmetic
WHAT: `evaluate(parse(tokenize(s)))` correct for `+`, `-`, `*`, `/`, precedence, parens, unary minus.
HOW:
```
python calc.py "2+3*4" # → 14
python calc.py "(2+3)*4" # → 20
python calc.py "8-3-2" # → 3
python calc.py "-2+5" # → 3 (requires shell quoting awareness)
python calc.py "2*-3" # → -6
```
EXPECTED: outputs above
WHERE: calc/evaluator.py `evaluate()`
---
### D2 — division
WHAT: `/` is true division; division by zero raises `EvalError`.
HOW:
```
python calc.py "7/2" # → 3.5
python calc.py "1/0" # → stderr error, exit 1
```
EXPECTED: `3.5` for 7/2; non-zero exit + stderr for 1/0
WHERE: calc/evaluator.py BinOp `/` branch
---
### D3 — result type
WHAT: Whole-valued → int (no `.0`), non-whole → float.
HOW:
```
python calc.py "4/2" # → 2 (not 2.0)
python calc.py "7/2" # → 3.5
```
EXPECTED: `2` and `3.5`
WHERE: calc/evaluator.py — `if isinstance(result, float) and result == int(result): return int(result)`
---
### D4 — CLI
WHAT: `python calc.py "2+3*4"``14`, exit 0; error → stderr, non-zero exit, no traceback.
HOW:
```
python calc.py "2+3*4" # → 14, exit 0
python calc.py "1 +" # → error to stderr, exit 1
```
EXPECTED: as above
WHERE: calc.py `main()`
---
### D5 — tests green + end-to-end
WHAT: Full test suite (lex + parse + eval) passes; 0 failures.
HOW: `python -m unittest -q`
EXPECTED:
```
Ran 56 tests in 0.226s
OK
```
WHERE: calc/test_lexer.py (14) + calc/test_parser.py (20) + calc/test_evaluator.py (22)
---
### Verify commands (from eval.md, verbatim)
```bash
python -m unittest -q # Ran 56 tests in ...s OK
python calc.py "2+3*4" # 14
python calc.py "(2+3)*4" # 20
python calc.py "7/2" # 3.5
python calc.py "4/2" # 2
python calc.py "1/0" # error to stderr, non-zero exit
python calc.py "1 +" # error to stderr, non-zero exit
```
Commit: (see git log — latest commit on main)

View File

@ -0,0 +1,40 @@
## DONE
Phase: lex — tokenizer
All DoD items self-certified (BUILD phase — deferred Adversary review).
### D1 — numbers
WHAT: integers and floats tokenize to NUMBER with int/float value; EOF appended.
HOW: `python -c "from calc.lexer import tokenize; print([(t.kind,t.value) for t in tokenize('42')])"`
EXPECTED: `[('NUMBER', 42), ('EOF', None)]`
WHERE: calc/lexer.py
### D2 — operators & parens
WHAT: `+ - * / ( )` each produce correct kind token.
HOW: `python -c "from calc.lexer import tokenize; print([t.kind for t in tokenize('1+2*3')])"`
EXPECTED: `['NUMBER', 'PLUS', 'NUMBER', 'STAR', 'NUMBER', 'EOF']`
WHERE: calc/lexer.py
### D3 — whitespace & errors
WHAT: spaces/tabs skipped; invalid char raises LexError with char + position.
HOW: `python -c "from calc.lexer import tokenize; tokenize('1 @ 2')"`
EXPECTED: raises `calc.lexer.LexError: unexpected character '@' at position 2`
WHERE: calc/lexer.py
### D4 — tests green
WHAT: 14 unittest tests in calc/test_lexer.py, 0 failures.
HOW: `python -m unittest -q`
EXPECTED: `Ran 14 tests in 0.000s\nOK`
WHERE: calc/test_lexer.py
### Plan verify commands (verbatim from lex.md)
```
python -m unittest -q
python -c "from calc.lexer import tokenize; print([(t.kind,t.value) for t in tokenize('3.5*(1-2)')])"
python -c "from calc.lexer import tokenize; tokenize('1 @ 2')"
```
EXPECTED outputs:
1. `Ran 14 tests in 0.000s\nOK`
2. `[('NUMBER', 3.5), ('STAR', '*'), ('LPAREN', '('), ('NUMBER', 1), ('MINUS', '-'), ('NUMBER', 2), ('RPAREN', ')'), ('EOF', None)]`
3. `calc.lexer.LexError: unexpected character '@' at position 2`

View File

@ -0,0 +1,78 @@
## DONE
Phase: parse — recursive-descent parser
All DoD items self-certified (BUILD phase — deferred Adversary review).
---
### AST node shapes
```
Num(value) — numeric literal; value is int or float
BinOp(op, left, right) — binary op; op in {'+', '-', '*', '/'}
Unary(op, operand) — unary minus; op is '-'
```
Defined in `calc/parser.py`. `ParseError` is also defined there.
---
### D1 — precedence
WHAT: `*` and `/` bind tighter than `+` and `-`.
HOW: `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)))`
WHERE: calc/parser.py `_expr` / `_term` levels
---
### D2 — left associativity
WHAT: Same-precedence operators associate left.
HOW:
```
python -c "from calc.lexer import tokenize; from calc.parser import parse; print(parse(tokenize('8-3-2')))"
# EXPECTED: BinOp('-', BinOp('-', Num(8), Num(3)), Num(2))
```
WHERE: `_expr` / `_term` each use a while-loop (iterative, left-accumulating)
---
### D3 — parentheses
WHAT: Parens override precedence.
HOW:
```
python -c "from calc.lexer import tokenize; from calc.parser import parse; print(parse(tokenize('(1+2)*3')))"
# EXPECTED: BinOp('*', BinOp('+', Num(1), Num(2)), Num(3))
```
WHERE: `_primary` handles LPAREN → `_expr` → RPAREN
---
### D4 — unary minus
WHAT: Leading and nested unary minus parses correctly.
HOW:
```
python -c "from calc.lexer import tokenize; from calc.parser import parse; print(parse(tokenize('-5')))"
# EXPECTED: Unary('-', Num(5))
```
WHERE: `_unary` level in parser
---
### D5 — errors
WHAT: Malformed input raises `ParseError` (not any other exception).
HOW: `parse(tokenize('1 +'))` raises `calc.parser.ParseError`
WHERE: `_Parser.parse`, `_Parser._primary`, `_Parser._expect`
---
### D6 — tests green
WHAT: 34 tests total (14 lex + 20 parser), 0 failures.
HOW: `python -m unittest -q`
EXPECTED: `Ran 34 tests in 0.001s\nOK`
WHERE: calc/test_parser.py (20 new tests)

View File

@ -0,0 +1,27 @@
## DONE
Phase: review — comprehensive deferred cold-verification
Adversary comprehensive PASS received @ 2026-06-16T00:57:12Z (commit a7dbf70).
---
### Summary
All DoD items verified by Adversary cold-verification from a fresh clone:
- **D1** PASS — every prior phase DoD item (lex/D1D4, parse/D1D6, eval/D1D5) cold-verified
- **D2** PASS — `python -m unittest -q` → Ran 60 tests OK (0 failures)
- **D3** PASS — all cross-feature probes pass (nested unary+parens, precedence chains, error propagation, whitespace+floats+parens, CLI exit codes)
- **D4** PASS — FINDING-1 fixed and re-verified; no standing VETO
### Finding resolved
FINDING-1: float literals not normalized to int in Num/Unary branches.
Fix: extracted `_normalize()` helper in `calc/evaluator.py`, applied at every return site.
4 regression tests added to `calc/test_evaluator.py`.
### Final state
- 60 tests, 0 failures
- Full calculator: lexer → parser → evaluator → CLI
- Files: calc/lexer.py, calc/parser.py, calc/evaluator.py, calc.py + full test suites