two-phase slice 1: link AST + build NkIntLit alongside emit

Flag twoPhase (grammar-level BOOLEAN) and wire the AST module into the
compiler build.  The M2 root production runs AST.Init; twoPhase := TRUE;
and the integer expression leaf also builds an NkIntLit node.  Nothing
reads the nodes yet, so emitted output is unchanged.

Gates: suite 178/178; fixpoint OK (stage2 == stage3, 2957466 bytes).

See docs/summary_two-phase-slice1.md.

compiler/build.sh

@@ -24,16 +24,16 @@ mkdir -p gen_ssa
 
 echo "=== Compiling ==="
 rm -f ./*.o
-for m in FileIO SymTab QbeGen M2S M2P M2; do
+for m in FileIO AST SymTab QbeGen M2S M2P M2; do
   gm2 -fiso -I src -c "src/$m.mod" || exit 1
 done
 
 echo "=== Phase 1: generating the module list ==="
 gm2 -fiso -I src -fgen-module-list=src/modules.lst -o /dev/null \
-    M2S.o M2P.o FileIO.o SymTab.o QbeGen.o src/M2.mod || exit 1
+    M2S.o M2P.o FileIO.o AST.o SymTab.o QbeGen.o src/M2.mod || exit 1
 
 echo "=== Phase 2: compiling main module and linking ==="
 gm2 -fiso -I src -fuse-list=src/modules.lst -o M2 \
-    M2S.o M2P.o FileIO.o SymTab.o QbeGen.o src/M2.mod || exit 1
+    M2S.o M2P.o FileIO.o AST.o SymTab.o QbeGen.o src/M2.mod || exit 1
 
 echo "=== M2 built ==="

compiler/src/M2.atg

@@ -51,9 +51,15 @@ COMPILER M2
    init; DISPOSE shallow and nils, deviating from Wirth-undefined);
    nil-deref is raw (no check). *)
 
-IMPORT SymTab, QbeGen;
+IMPORT SymTab, QbeGen, AST;
 
 VAR
+  (* Two-phase frontend (docs/plan-two-phase.md).  When TRUE the
+     productions ALSO build AST nodes alongside the legacy emit path.
+     Slice 1: the nodes are inert scaffolding — nothing reads them, so
+     the emitted output is unchanged. *)
+  twoPhase: BOOLEAN;
+
   (* Class of the method named by the last `obj.Method` designator
      (InvalidType when the callee is an ordinary procedure). Set by
      Design, consumed by the following ArgList. *)
@@ -150,7 +156,8 @@ TOKENS
 
 PRODUCTIONS
   M2
-    = Unit "." .
+    = (. AST.Init; twoPhase := TRUE; .)
+      Unit "." .
   (* Units: program modules compile fully; DEFINITION and
      IMPLEMENTATION modules parse + check now but lower in step 4
      (each ends with one 230); same for nested local modules. *)
@@ -2549,9 +2556,9 @@ PRODUCTIONS
                                              isMax: BOOLEAN;
                                              called, isHigh, sfx, isCh,
                                              isU, uok, isStr: BOOLEAN;
-                                             ucp: INTEGER; .)
+                                             ucp: INTEGER; astScratch: AST.Node; .)
     = integer                           (. LexString(s);
-                                           QbeGen.NormInt(s, q);
+                                           QbeGen.NormInt(s, q); IF twoPhase THEN astScratch := AST.MakeLeaf(AST.NkIntLit, s) END;
                                            t := SymTab.IntType(); .)
     | charConst                         (. LexString(s);
                                            QbeGen.NormLit(s, q, isCh);

docs/plan-two-phase.md

@@ -65,9 +65,10 @@ machinery and the `Design` placeholder path are deleted.
 Suggested slices, each ending in `build.sh` + `run_tests.sh` +
 `fixpoint.sh` (revert the slice if either fails):
 
-1. **Flag + scaffolding**: `TWO_PHASE` flag; parser builds AST nodes for
-   one trivial production (e.g. `Ident`/`NkIdent`) alongside emission.
-   Nothing consumes them.  Green.
+1. **Flag + scaffolding** — DONE (branch `ast-stage-c`,
+   `docs/summary_two-phase-slice1.md`): `twoPhase` flag; `AST` linked
+   into the compiler build; the `integer` leaf also builds `NkIntLit`.
+   Nothing consumes it.  Green (178/178, fixpoint OK).
 2. **Expressions → AST**: `Expr`/`SimExpr`/`Term`/`Fact` build
    `NkBinExpr`/`NkUnary`/`NkIdent`/literals, *in addition* to emitting.
    Add `Lower` for expressions, exercised in a test-only compare.

docs/summary_two-phase-slice1.md

@@ -0,0 +1,41 @@
+# Two-phase refactor — slice 1 (`twoPhase` flag + AST scaffolding)
+
+Branch `ast-stage-c` off `1c93f19` (`v3-two-phase-plan`).
+Suite **178/178**; self-hosting fixpoint **OK** (**2,957,466 bytes**;
++56,684 vs 2,900,782 — the AST module is now linked into the compiler).
+
+## What landed
+
+`docs/plan-two-phase.md` §4 slice 1: the parser now builds AST nodes
+**alongside** the legacy emit path, and the AST module is part of the
+compiler build.  The nodes are **inert** — nothing reads them, so the
+generated `.ssa` is unchanged (stage2 == stage3 byte-for-byte).
+
+| File | Change |
+| --- | --- |
+| `compiler/src/M2.atg` | `IMPORT … , AST`; `VAR twoPhase : BOOLEAN`; the `M2` root production runs `AST.Init; twoPhase := TRUE;`; the `integer` expression leaf also builds `NkIntLit` via `AST.MakeLeaf`; `Fact` gets a throwaway `astScratch : AST.Node` |
+| `compiler/build.sh` | compile and link `AST` (after `FileIO`) |
+| `compiler/src/M2.lst` | regenerated CR listing |
+
+`M2P.mod` now imports `AST` and calls `AST.Init` once per parsed unit
+(the root production runs per source file), so every unit starts with a
+fresh arena.  The new `AST.def/.mod` are picked up transitively by
+M2make during stages 2/3 of the fixpoint.
+
+## Notes
+
+- `twoPhase` is a grammar-level BOOLEAN, set TRUE in the root
+  production.  Later slices gate the new lowering walk on it; for now it
+  only guards the inert `NkIntLit` build.
+- `Compilation ended with LL(1) errors.` from CR is **pre-existing**
+  (benign) and unchanged.
+- No new test: every existing test already exercises the path (each
+  integer literal builds a node), and there is no observable behaviour to
+  assert yet.
+
+## Next
+
+Slice 2 (`docs/plan-two-phase.md` §4): `Expr` / `SimExpr` / `Term` /
+`Fact` build `NkBinExpr` / `NkUnary` / `NkIdent` / literals in addition
+to emitting; add `Lower` for expressions, exercised by a test-only
+`.ssa` byte-compare.