docs: Blaise phase sync map + plan refresh (0x-only, no AST, two grammars, step-3 progress)

docs/blaise-phases-map.md

@@ -0,0 +1,70 @@
+# Blaise phase sync map (checked 2026-09-20 against graemeg/blaise master)
+
+Blaise's 10 phases (README status: 1–5 + 7 complete, 6 ongoing,
+8–10 planned). This file tracks where m2compiler-V3 stands against
+each, and records deliberate divergences so they aren't
+rediscovered. Refresh after every major step.
+
+## Phase table
+
+| Blaise | Status there | Us | Status here |
+|---|---|---|---|
+| 1 Bootstrap pipeline | ✅ | Step 1 (M2→QBE hello) | ✅ done (`v3-step1`) |
+| 2 Type system (classes, records, ARC, exceptions) | ✅ | Steps 2–3 (scalars ✅, arrays ✅, sets ✅, records/pointers pending) + 1.10 Clarion classes | ⚠️ partial |
+| 3 Generics + interfaces | ✅ | Explicitly OUT (R10 blueprints rejected) | ❌ deliberate |
+| 4 OPDF debug info | ✅ | Deferred (listing only) | ❌ deferred |
+| 5 Self-hosting | ✅ | Step 8 (last) | ⚠️ same mechanism, later slot |
+| 6 RTL/StdLib expansion | 🔄 ongoing | Step 5 (Benjamin stdlib) | Not started |
+| 7 Native backend | ✅ | Not planned (QBE is terminal) | ❌ deliberate |
+| 8 Windows/macOS ARM64 | Planned | Out of scope (amd64_sysv) | ❌ |
+| 9 LSP + VS Code | Planned | Deferred vaguely | ❌ |
+| 10 Migration analyser | Planned | 1.12 TopSpeed grammar, 662-file corpus parse-clean | ✅ convergent |
+
+## What "in sync" means here
+
+Process, not phases: phased steps with per-step design docs (their
+`design.adoc` rhythm → our `summary_stepN.md`), test-guarded
+progress, QBE-first backend for speed-to-hosting (their stated
+reason, ours too), fixpoint verification (their 3-stage
+byte-identical bootstrap → our planned `bootstrap/fixpoint.sh`
+over `.ssa`).
+
+Two places we're ahead of their learning curve, per graemeg's own
+v0.12.0 retrospective: our harness has been end-to-end
+(`qbe→cc→run`) since step 1 — exactly the gap (IR-only tests
+missing link/runtime bugs) he's now closing. Keep it that way:
+no step lands on IR inspection alone.
+
+## Warnings adopted from Blaise experience
+
+- **Rolling bootstrap.** Their `scripts/rolling-bootstrap.sh` exists
+  because new parser features break old binaries: once M2 compiles
+  itself (step 8), a grammar extension can strand the stage-1
+  binary. Our `fixpoint.sh` must rebuild commit-by-commit from the
+  last green binary, not just diff three stages. (Recorded pre-emptively;
+  hits at step 8.)
+- **Stabilisation cycles.** Their v0.12.0 goes thin-on-features to
+  harden the suite. After step 3.4 (composites complete), do the
+  same before step 4 calls: a hardening pass over the 50+ suite
+  (fuzz bounds, cross-span copies, trap paths) instead of new syntax.
+- **Turnkey gap.** Self-hosting ≠ turnkey: they still need GCC/FPC
+  scaffolding. Our step 8 must define "done" as: pinned `qbe`+`cc`
+  plus documented host-gm2 bootstrap, nothing else.
+
+## Deliberate divergences (do not relitigate without cause)
+
+- No ARC/GC, no exceptions, no generics, no native backend, no
+  second platform: Modula-2 scope discipline, not Pascal parity.
+- Self-hosting last, not middle: full-language-first was locked;
+  the cost is accepted (hygiene rules from step 1 pay it down).
+- Two grammars, not one: modern `M2.atg` + legacy
+  `TopSpeed-V3-M2.atg` (1.12). This mirrors their phase-10
+  split (modern core + migration sidecar) and quarantines the
+  opposite dialect decisions (`_`, `<>`, `H`/`C`/`B` suffixes).
+  Never merge them; the modern grammar stays Redux-clean.
+
+## Drift log
+
+- 2026-09-20: map created. `plan.md` refreshed (0x-only,
+  no-AST-module reality, two-grammar strategy, step-3 substeps).
+- Next refresh: after 3.4 (pointers) or any Blaise phase flip.

docs/plan.md

@@ -13,8 +13,12 @@ phased process, self-hosting with byte-identical `.ssa` fixpoint.
   `vendor/qbe-pin.txt`.
 - Modern syntax base: PIM4/ISO core + Kowarsch/Redux cleanups —
   `#` only (no `<>`), `NOT/AND/OR` only (no `~/&`), no `B/C` octal
-  literals, `H` hex kept, unary minus takes a Factor. Evolved from
-  V2 `M2comp.atg` (1290 lines), not pasted verbatim.
+  literals, `0x`-only hex, unary minus at expression start.
+  Evolved from V2 `M2comp.atg` (1290 lines), not pasted verbatim.
+  A second, fenced legacy grammar (`TopSpeed-V3-M2.atg`, step 1.12)
+  covers the historical dialect (`_`, `<>`, `H`/`C`/`B`) for corpus
+  ingestion — never merged into the modern grammar (see
+  `docs/blaise-phases-map.md`: our phase-10 sidecar).
 - Test convention (from Test2): global `VAR ExitCode : INTEGER`
   selects process exit code; otherwise return 0.
 
@@ -27,8 +31,9 @@ Blaise (`graemeg/blaise`) uses `compiler/`, `runtime/`, `stdlib/`,
 ```text
 m2compiler-V3/
   README.md  build.sh  run_tests.sh
-  compiler/src/      M2.atg, compiler.frm, parser.frm, scanner.frm,
-                     FileIO, SymTab, AST, QbeGen, generated M2S/M2P/M2 (gitignored)
+  compiler/src/      M2.atg (+ TopSpeed-V3-M2.atg legacy sidecar),
+                     frames, FileIO, SymTab, QbeGen, generated
+                     scanner/parser/driver (gitignored)
   compiler/tests/    accept / reject (.LST) / run (exit-code) tests
   runtime/syslib/    SYSTEM, Storage, SysIO, SysClock, Trap, Utf8
                      always-linked, self-hostable, NO gm2-only imports
@@ -39,8 +44,8 @@ m2compiler-V3/
   vendor/qbe-pin.txt
   bootstrap/         stage1/ (gm2-built), stage2/, stage3/ (V3-built),
                      fixpoint.sh (rebuild 2x, diff -r *.ssa)
-  docs/              plan.md (this file), spec.md, blaise-phases-map.md,
-                     summary_stepN.md
+  docs/              plan.md (this file), blaise-phases-map.md,
+                     summary_stepN.md (one file per step)
 ```
 
 Build outputs (`.o`, `.ssa`, `.s`, binaries) are never committed.
@@ -59,10 +64,10 @@ Build outputs (`.o`, `.ssa`, `.s`, binaries) are never committed.
 
 | Step | Goal | Acceptance |
 |------|------|------------|
-| 1 pipeline | minimal `M2.atg` + fresh `QbeGen` hello → `.ssa` → `qbe → cc → run` | 3 run tests |
-| 2 scalars | scalar type system, SymTab errors 200–224 + 230/232/233 (+234 unicode) | ~20 tests |
-| 3 composites | length-prefixed arrays/records/sets/pointers (§5) | layout tests green |
-| 4 modules/procs | DEFINITION/IMPLEMENTATION, opaque `TYPE T;`, nested/display, separate compilation | ADT tests (V2 goal_step8 scope) |
+| 1 pipeline | minimal `M2.atg` + fresh `QbeGen` hello → `.ssa` → `qbe → cc → run` | ✅ done (5/5 → grown since) |
+| 2 scalars | scalar type system, SymTab errors 200–224 + 230/232/233 (+234 unicode) | ✅ done (30/30: ints, bools, chars, REALs, control flow) |
+| 3 composites | length-prefixed arrays/records/sets/pointers (§5) | 🔄 3.1 arrays ✅, 3.2 showcase ✅, 3.3 sets ✅, 3.4 pointers next |
+| 4 modules/procs | DEFINITION/IMPLEMENTATION, opaque `TYPE T;`, nested/display, separate compilation | not started (syntax parses; lowering pending) |
 | 5 stdlib | Strings/TextIO/WholeIO/Math/Files per Benjamin | I/O + file tests |
 | 6 harden | CASE/WITH/LOOP/EXIT/FOR-BY, conversions, traps | full-suite green |
 | 7 syslib port | rewrite FileIO on SysIO+Storage only; ban `Environment, FileSysOp, TextIO, RawIO, WholeIO, IOChan, SysClock, ProgramArgs` via `grep` gate | compiler sources syslib-clean; Stage1 still gm2-built |
@@ -113,16 +118,18 @@ self-hosting is the last phase. Hygiene from step 1: deterministic
 - `TextIO.UWriteChar/UWriteString/UWriteLn`: encode to UTF-8, emit via
   `SysIO` byte descriptors. Raw `WriteChar` stays byte-oriented.
 
-## 7. Interactive ATG order (next)
-
-1. `COMPILER M2` header + `CHARACTERS/IGNORE/COMMENTS/TOKENS`
-   (incl. `ustring`, grown `LexString` buffer).
-2. Module / Definition / Implementation / Import (+ opaque hook).
-3. `CONST/TYPE/VAR/ProcHeading` + error codes (200–234).
-4. Types (scalars → UCHAR → composites → proc types).
-5. Statements (IF/CASE/WHILE/REPEAT/LOOP/EXIT/FOR/WITH/RETURN).
-6. Expressions (precedence, `IN`, set/pointer/UCHAR ops).
-7. Action wiring (`SymTab/AST/QbeGen` hooks) + `compiler.frm` driver.
+## 7. Interactive ATG order (done through §6; UCHAR/UString pending)
+
+1. `COMPILER M2` header + `CHARACTERS/IGNORE/COMMENTS/TOKENS` ✅
+   (`0x`, `E`-exponents, `//` decided interactively; `ustring`
+   token spelling locked, implementation pending with step 6).
+2. Module / Definition / Implementation / Import (+ opaque hook) ✅
+3. `CONST/TYPE/VAR/ProcHeading` + error codes (200–234) ✅
+4. Types (scalars ✅, UCHAR pending, composites 🔄 arrays+sets ✅,
+   records/pointers next, proc types with step 4).
+5. Statements ✅ (all but `WITH`, which rides with records).
+6. Expressions ✅ (relations, `IN`, set ops; pointer ops with 3.4).
+7. Action wiring ✅ (driver reports `file:line:col`).
 
 Each section: proposed snippet → user approve/tweak → append to
 `compiler/src/M2.atg` → `CR -m -C` syntax check before moving on.