adding the summaries for every step

docs/summary_step1.md

@@ -0,0 +1,44 @@
+# Step 1 — Phase-0 scaffolding (tag: `step1`)
+
+Commit `18e40b8` — "Phase-0 scaffolding — M2c module-skeleton compiler,
+4/4 tests green" (29 files, +2756).
+
+## Goal
+
+Prove the toolchain end to end before any language work: Coco/R grammar
+→ generated scanner/parser/driver → `gm2 -fiso` build → test runner,
+all inside a new `m2c/` folder.
+
+## What was built
+
+- `m2c/M2c.atg` — module skeleton only:
+  `MODULE <name> ; [ BEGIN ] END <name> .`, with an inline
+  closing-name check (error 202). No declarations, statements, or
+  symbol table.
+- `m2c/compiler.frm` — minimal driver (listing + `StoreError`,
+  `ChangeExtension`, `FileIO`-based main), custom message for 202.
+- `m2c/scanner.frm`, `m2c/parser.frm` — proven FileIO-based Coco/R
+  frames, reused from the earlier CocoGm2 work.
+- `m2c/FileIO.def/.mod` — I/O library, reused as-is.
+- `m2c/build.sh` — regenerate (`CRFRAMES=. $CRBIN -m -C M2c.atg`,
+  `CRBIN` overridable), compile with `gm2 -fiso`, link via the
+  two-phase module-list workaround; produces `./M2c`.
+- `m2c/run_tests.sh` — `expect_ok` / `expect_fail` (checks `.LST`
+  message text, since listings show messages, not codes).
+
+## Tests — 4/4
+
+| test | result |
+| ---- | ------ |
+| ok_minimal | `MODULE M; BEGIN END M.` accepted |
+| ok_nobegin | `MODULE M; END M.` accepted |
+| bad_mismatch | `END N` rejected with 202 |
+| bad_syntax | missing `.` rejected with syntax error |
+
+Both `SemError` (202) and `SynError` paths verified working.
+
+## Notes
+
+- Grammar name `M2c` keeps generated modules short
+  (`M2cS`/`M2cP`/`M2c`, no Coco/R truncation surprises).
+- `m2comp/coco-chatgpt-doesntwork/` explicitly excluded from all work.

docs/summary_step2.1.md

@@ -0,0 +1,32 @@
+# Step 2.1 — Image extension `.MCD` → `.MC4` (tag: `step2.1`)
+
+Commit `5c56c9f` — "step2.1: rename 64-bit images .MCD -> .MC4 per
+spec sections 8 and 14" (57 files, pure rename + 8 one-line edits).
+
+## Rationale
+
+The spec already mandates `.MC4` (§8 file format, §14 migration
+row), and the tree was inconsistent (`boot.mc4` vs `example.MCD`).
+The rename also disambiguates formats: legacy 16-bit inputs stay
+`.MCD`, 64-bit outputs become `.MC4`, so the `trans8to64` flow
+(`in.MCD` → `out.MC4`) is self-documenting.
+
+## What changed
+
+- Producers: `mkdemo`→`boot.MC4`, `mkdtest`→`example.MC4`,
+  `mkread`→`readtest.MC4`, `mkdep`→`STAK/DEP.MC4`,
+  `MGen` emits `<Mod>.MC4`, `trans8to64` usage (input side kept
+  `.MCD`).
+- `Loader2` dependency suffix, `MC64.mod` boot name, `mcint`
+  usage text (all `.MC4`, uppercase per spec).
+- Docs (surgical): `SESSION.md`, `session-summary.md`, spec §16
+  boot note. Historical `.MCD` mentions kept on purpose (16-bit
+  doc, §14 migration row, translator input side).
+- Tracked binaries renamed via `git mv` + full rebuild.
+
+## Verification after the rename
+
+- mc64: `example.MC4` 24/24 exit 0, `boot.MC4` → Hello,
+  `readtest.MC4` stdin echo, `mcint DEP.MC4` → cross-module ok
+  (proves the loader suffix change), `mc64` → `[vm end]`.
+- m2c: 25/25, `.MC4` files regenerated by the suite.

docs/summary_step2.md

@@ -0,0 +1,59 @@
+# Step 2 — Scalars + MC64 backend (tag: `step2`)
+
+Commit `eee1504` — "step2: scalars + MC64 backend — SymTab, MGen
+emitter, 25/25 tests green; fix bit_in operand order"
+(88 files, +4980/−132).
+
+## Goal
+
+Full scalar subset of Modula-2 compiling to runnable MC64 images:
+`CONST`/`TYPE`/`VAR`, complete expression hierarchy, all structured
+statements, static type checking, exact error codes.
+
+## What was built
+
+- `m2c/SymTab.def/.mod` — symbol table + type checker, ported from
+  the proven Test1 design: scopes, aliases/subranges/enums/arrays/
+  records/sets/pointers descriptors, `InvalidType` cascade
+  suppression; codes 200/201/202, 210–224; plus `PendCount`/
+  `PendName` for VAR-list emission.
+- `m2c/MGen.def/.mod` — MC64 image emitter: one 8-byte slot per
+  global, literal `CONST`s as startup stores, stack-machine
+  expressions (`A6/A7/A8/B8/A9/AA/B9`, signed `B2–B5` compares,
+  `D5–D9` reals, `E6/E8/B6` logic), `E0/E1` jumps with fixups,
+  `LOOP/EXIT` stack, `CASE` as compare-chains, `FOR` with hidden
+  temp global, `SET`s via `power2`/`build_field_mask`/`bit_in`/`A0`,
+  embedded decimal-print helper. Test convention: a global
+  `VAR ExitCode : INTEGER` is printed as decimal + CRLF.
+- `m2c/M2c.atg` — full scalar grammar (~900 lines): type checking
+  identical to the reference rules; backend lowers scalars + sets,
+  everything else parses but gets error 230.
+- `m2c/run_tests.sh` — extended: `expect_run` compiles, runs the
+  `.MC4` (name derived from the `MODULE` line, not `ls -t`) under
+  `mcint`, and compares the printed value.
+
+## Tests — 25/25
+
+14 run tests (7, 15, 42, 20, 103, 55, 55, 7, 85, 31, 97, 1, 74,
+sets 15) + 6 rejections (one 210, rest 230-only, no cascades) +
+4 phase-0 + 1 silent-minimal. All negatives produce exactly one
+error each.
+
+## Bugs found and fixed
+
+1. Image writer skipped the 64-byte file header (shifted image).
+2. `ParseCard` used `10H`/`16H` (hex 16/22!) for decimal bases —
+   multi-digit literals wrong, single digits accidentally right.
+3. `ParseReal` overlaid 8 bytes of gm2's 80-bit-extended `LONGREAL`
+   — switched to 8-byte `REAL` like the VM's own `Stack.mod`.
+4. **`bit_in` (`0E7H`) operands swapped in `mc64/Interpreter.mod`**
+   vs both the spec prose and the original Turbo MCode
+   (`op := Pop(); Push(Pop() IN BITSET(op))`) — fixed (2 lines),
+   MC64 suite re-verified 24/24.
+5. Runner used same-second `ls -t` ties + non-portable `$'\r'`
+   stripping — deterministic names + `tr -d '\r'`.
+
+## Known limits (in `M2c.atg` header)
+
+Truncating DIV/MOD, signed compares for CARDINAL, eager AND/OR,
+literal-only CONST/BY, REAL as binary64, no procedures yet.

docs/summary_step3.md

@@ -0,0 +1,61 @@
+# Step 3 — Procedures (tag: `step3`)
+
+Commit `c0f1924` — "step3: procedures — nested, params, recursion,
+FORWARD, RETURN; 49/49 tests green" (91 files, +2730/−548).
+
+## Goal
+
+Procedures (Phase 2 of the plan): declarations incl. nesting, value
+and VAR parameters, functions, `RETURN`, recursion, forward
+declarations; frames per spec §5.2; calls via ED/EC/EE.
+
+## What was built
+
+- `SymTab`: frame slots (`SymSlot`), proc depths
+  (`SymDepth`/`CurDepth`), proc records numbered 1..64, forward +
+  define signatures with `VerifyProc`, return-type stack
+  (`CurRet`/`InFunction`), new kinds `Proc/Param/VarPar`.
+- `MGen`: N-entry proc table (print helper moved to last slot),
+  `ProcEntry`/`Leave`, calls via `ED` (global), `EC` (directly
+  nested), `EE` + display walk (`11H`); actuals evaluated
+  left-to-right into temps, pushed reversed (nested-call-safe
+  frame stack in `ActBegin/Value/End`, which also own arity/type/
+  VAR-actual checks); frame-aware loads/stores/addresses.
+- `M2c.atg`: `ProcedureDecl` (nested, `FORWARD;` form verified
+  against gm2 — caret form rejected), `Design` split into
+  `Head`+`Tail` with `AssignOrCall`, `CallTail`, `ReturnStat`,
+  `v/vn` attributes threading "is plain variable" for VAR-actual
+  checks.
+- Codes 231 (forward mismatch/missing body), 232 (bad RETURN),
+  233 (invalid call); proc `END`-name reuse 202 (text widened to
+  "module/procedure name mismatch").
+
+## Tests — 49/49 (25 step-2 regressions + 24 new)
+
+14 run: proper/value-params (incl. 6 params)/functions/factorial/
+fib/VAR-swap/nested display/forward mutual recursion/early RETURN/
+shadowing/nested calls/dropped results/VAR chains/empty bodies/
+REAL functions. 10 rejections, each exactly one error: non-proc
+call, arity, actual type, proper-in-expression, 3× RETURN misuse,
+forward mismatch, missing body, undeclared callee.
+
+## Bugs found and fixed
+
+1. `FORWARD;` double-semicolon — the branch must not consume `;`
+   (it belongs to `Declaration`).
+2. Bare `P;` calls need no parens — empty-call branch in statements
+   (expressions still require parens).
+3. `2EH` pops an address off the stack — same-frame indirect access
+   must go through `2CH`+`60H`; deleted `LoadStk`.
+4. Dead callee value on expression calls
+   (`Double(10)+Double(11)` → 22) — `CallTail` drops it on entry.
+
+## Research notes
+
+- Forward syntax confirmed empirically (`PROCEDURE P(...);
+  FORWARD;` compiles under gm2; `^` and heading-alone do not).
+- Decoder-verified before use: `2E/3E` unsigned (outer locals need
+  the `41H/51H` path), `11H np=0` valid, `EC/EE/ED` semantics.
+- Limits: 64 procedures, 64 actuals/call, 16 names per FP-section,
+  8-deep nested calls; truncating DIV/MOD and eager AND/OR carry
+  over from step 2.