Add Canon loop scaffolding and reporter/cli sample modules

.codex/bo4_runs.jsonl

@@ -0,0 +1,2 @@
+{"task_id":"task_e_68eb0ffa43d88320bad9f2faa2889687","env":"LexLattice/true-modules","base":"main","best_of":4,"prompt_file":"prompts/wave3/c6-implementer-pack.md","cards":["C6"],"timestamp":"2025-10-12T02:19:12Z"}
+{"task_id":"task_e_68eb1001d8488320970fdaf8e6efc4eb","env":"LexLattice/true-modules","base":"main","best_of":4,"prompt_file":"prompts/wave3/c7-meta-pack.md","cards":["C7"],"timestamp":"2025-10-12T02:19:12Z"}

.codex/prompts/amr_merge.md

@@ -0,0 +1,24 @@
+# SYSTEM — AMR Meta-Reviewer (merge slates into Canon)
+
+You are the **Meta-Reviewer**. Given 3–4 architecture slates (no code), MERGE them into a single Canon and justify the choice.
+
+## Inputs
+- `rcm/rcm.json` — Requirement Coverage Matrix
+- `amr/slates/var*/{architecture.json,schemas.json,acceptance.json,notes.md}`
+
+## Score each slate (0..1); weights:
+- RCM coverage (0.35) — % of `must:true` linked by module+test
+- SSD (0.25) — per-layer spec density (architecture/data_schemas/error_model/cli_surface)
+- Complexity (0.15) — edges/modules; penalize fan-in/out > 3
+- Testability (0.15) — # acceptance cases + oracles
+- Risk (0.10) — rollbacks, error taxonomy, timeouts
+
+## Produce (REQUIRED)
+- `amr/architecture.json`, `amr/schemas.json`, `amr/acceptance.json`
+- `amr/traceability.map.json` — REQ → {modules, interfaces, tests}
+- `amr/amr_winner.md` — why chosen, why not others, residual risks
+- Raise any layer with SSD < 0.75 by adding explicit contracts/schemas.
+
+## Rules
+- Every `must:true` in RCM must have ≥1 module **and** ≥1 test in the Canon.
+- Resolve ambiguity; keep fan-out ≤ 3; prefer simpler wiring.

.codex/prompts/bo4A_architect.md

@@ -0,0 +1,39 @@
+# SYSTEM — Bo4-A Architect (no code; canon slate)
+
+You are the **Architect**. Produce ONLY these files in your output:
+- `architecture.json` — modules, interfaces, invariants, edges
+- `schemas.json` — JSON Schemas for all interface inputs/outputs
+- `acceptance.json` — REQ-* → test cases with oracle names
+- `notes.md` — assumptions, risks, open choices
+
+## Constraints
+- Use `rcm/rcm.json` as source of truth; each module/interface/test MUST reference ≥1 `REQ-*`.
+- Interfaces MUST include: `name`, `input`, `output`, `errors[]`, `pre[]`, `post[]`.
+- Keep modules cohesive, edges minimal; target fan-out ≤ 3.
+- Declare invariants (e.g., idempotence, determinism); link each to tests.
+
+## Output format hints
+- `architecture.json`:
+  ```json
+  {
+    "modules":[
+      {
+        "id":"reporter",
+        "purpose":"Emit report.json",
+        "interfaces":[
+          {
+            "name":"Reporter.write",
+            "input":{"$ref":"schema.RunSummary"},
+            "output":{"path":"string"},
+            "errors":["E_IO","E_VALIDATION"],
+            "pre":["RunSummary.valid == true"],
+            "post":["file.exists(output.path)"]
+          }
+        ],
+        "invariants":["idempotent(Reporter.write)"]
+      }
+    ],
+    "edges":[{"from":"cli","to":"reporter","contract":"Reporter.write"}],
+    "schemas_ref":"schemas.json"
+  }
+  ```

.codex/selfcheck.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+COMPOSE=${1:-runs/current/meta/compose.json}
+LOCK=${2:-amr/canon.lock.json}
+MODROOT=${3:-modules}
+ARTIFACTS_DIR=${4:-artifacts}
+
+echo ">>> Canon check ..."
+if [[ ! -f "$COMPOSE" ]]; then
+  echo "Compose file not found: $COMPOSE" >&2
+  exit 1
+fi
+if [[ ! -f "$LOCK" ]]; then
+  echo "Canon lock not found: $LOCK" >&2
+  exit 1
+fi
+if [[ ! -d "$MODROOT" ]]; then
+  echo "Modules root not found: $MODROOT" >&2
+  exit 1
+fi
+
+mkdir -p "$ARTIFACTS_DIR"
+
+EVENTS_FILE="${ARTIFACTS_DIR%/}/events.ndjson"
+
+node tm.mjs gates shipping \
+  --compose "$COMPOSE" \
+  --modules-root "$MODROOT" \
+  --emit-events \
+  --events-out "$EVENTS_FILE" \
+  --events-truncate \
+  --strict-events
+
+node scripts/canon-verify.mjs \
+  --lock "$LOCK" \
+  --modules-root "$MODROOT" \
+  --compose "$COMPOSE"
+
+echo ">>> PASS: Canon stamp verified."

.github/workflows/ci.yml

@@ -120,6 +120,7 @@ jobs:
             --npm-pack \
             --emit-events \
             --events-out artifacts/events.ndjson \
+            --events-truncate \
             --strict-events
           echo "::endgroup::"
 

.gitignore

@@ -27,8 +27,8 @@ target
 .env
 
 artifacts/
+!artifacts/events.ndjson
 !runs/**/artifacts/
 tmp/
 cloud-prompt-*.md
-.codex/
 runs/ci-headless/

amr/canon.lock.json

@@ -0,0 +1,42 @@
+{
+  "schema": "tm-canon-lock@1",
+  "modules": {
+    "reporter": {
+      "ports": {
+        "ReporterPort@1": {
+          "export": {
+            "file": "src/index.js",
+            "symbol": "reporterWrite"
+          }
+        }
+      },
+      "invariants": {
+        "idempotent(Reporter.write)": {
+          "test": "tests/invariants/idempotent.json"
+        }
+      },
+      "acceptance": {
+        "T-001": "tests/T-001.json",
+        "T-002": "tests/T-002.json"
+      }
+    },
+    "cli": {
+      "ports": {
+        "CLIPort@1": {
+          "export": {
+            "file": "src/cli.js",
+            "symbol": "cliParse"
+          }
+        }
+      },
+      "invariants": {
+        "deterministic(CLI.parse)": {
+          "test": "tests/invariants/deterministic.json"
+        }
+      },
+      "acceptance": {
+        "T-010": "tests/T-010.json"
+      }
+    }
+  }
+}

artifacts/events.ndjson

@@ -0,0 +1,23 @@
+{"schema":"tm-events@1","event":"GATES_START","ts":"2025-10-19T02:35:59.889Z","seq":1,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"compose_path":"/workspace/true-modules/runs/canon-loop-demo/meta/compose.json","modules_total":2}}
+{"schema":"tm-events@1","event":"LINT_START","ts":"2025-10-19T02:35:59.960Z","seq":2,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"lint_tool":"eslint"}}
+{"schema":"tm-events@1","event":"LINT_PASS","ts":"2025-10-19T02:36:00.798Z","seq":3,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"lint_tool":"eslint","dur_ms":838}}
+{"schema":"tm-events@1","event":"TEST_START","ts":"2025-10-19T02:36:00.800Z","seq":4,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"module":"reporter","test":"tests/T-001.json"}}
+{"schema":"tm-events@1","event":"TEST_PASS","ts":"2025-10-19T02:36:00.934Z","seq":5,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"module":"reporter","test":"tests/T-001.json","dur_ms":134,"side_effects":{"declared":["FS:write"],"observed_operations":["FS:write"],"undeclared_operations":[],"fs_write":{"count":5,"outside_module_root":false,"sample_paths":[{"path":".tmp","inside_module_root":true},{"path":".tmp/case-t0cphL","inside_module_root":true},{"path":".tmp/case-t0cphL/reporter.log","inside_module_root":true},{"path":".tmp/case-t0cphL","inside_module_root":true},{"path":".tmp/case-t0cphL/reporter.log","inside_module_root":true}],"outside_samples":[]},"processes":{"total":0,"categories":{}}}}}
+{"schema":"tm-events@1","event":"TEST_START","ts":"2025-10-19T02:36:00.935Z","seq":6,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"module":"reporter","test":"tests/T-002.json"}}
+{"schema":"tm-events@1","event":"TEST_PASS","ts":"2025-10-19T02:36:01.088Z","seq":7,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"module":"reporter","test":"tests/T-002.json","dur_ms":153,"side_effects":{"declared":["FS:write"],"observed_operations":["FS:write"],"undeclared_operations":[],"fs_write":{"count":7,"outside_module_root":false,"sample_paths":[{"path":".tmp","inside_module_root":true},{"path":".tmp/case-XI63ZD","inside_module_root":true},{"path":".tmp/case-XI63ZD/reporter.log","inside_module_root":true},{"path":".tmp/case-XI63ZD","inside_module_root":true},{"path":".tmp/case-XI63ZD/reporter.log","inside_module_root":true}],"outside_samples":[]},"processes":{"total":0,"categories":{}}}}}
+{"schema":"tm-events@1","event":"TEST_START","ts":"2025-10-19T02:36:01.089Z","seq":8,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"module":"reporter","test":"tests/invariants/idempotent.json"}}
+{"schema":"tm-events@1","event":"TEST_PASS","ts":"2025-10-19T02:36:01.226Z","seq":9,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"module":"reporter","test":"tests/invariants/idempotent.json","dur_ms":137,"side_effects":{"declared":["FS:write"],"observed_operations":["FS:write"],"undeclared_operations":[],"fs_write":{"count":8,"outside_module_root":false,"sample_paths":[{"path":".tmp","inside_module_root":true},{"path":".tmp/case-dW6Efo","inside_module_root":true},{"path":".tmp/case-dW6Efo/reporter.log","inside_module_root":true},{"path":".tmp/case-dW6Efo","inside_module_root":true},{"path":".tmp/case-dW6Efo/reporter.log","inside_module_root":true}],"outside_samples":[]},"processes":{"total":0,"categories":{}}}}}
+{"schema":"tm-events@1","event":"TEST_START","ts":"2025-10-19T02:36:01.227Z","seq":10,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"module":"cli","test":"tests/T-010.json"}}
+{"schema":"tm-events@1","event":"TEST_PASS","ts":"2025-10-19T02:36:01.358Z","seq":11,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"module":"cli","test":"tests/T-010.json","dur_ms":131,"side_effects":{"declared":[],"observed_operations":[],"undeclared_operations":[],"fs_write":{"count":0,"outside_module_root":false,"sample_paths":[],"outside_samples":[]},"processes":{"total":0,"categories":{}}}}}
+{"schema":"tm-events@1","event":"TEST_START","ts":"2025-10-19T02:36:01.359Z","seq":12,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"module":"cli","test":"tests/invariants/deterministic.json"}}
+{"schema":"tm-events@1","event":"TEST_PASS","ts":"2025-10-19T02:36:01.488Z","seq":13,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"module":"cli","test":"tests/invariants/deterministic.json","dur_ms":129,"side_effects":{"declared":[],"observed_operations":[],"undeclared_operations":[],"fs_write":{"count":0,"outside_module_root":false,"sample_paths":[],"outside_samples":[]},"processes":{"total":0,"categories":{}}}}}
+{"schema":"tm-events@1","event":"PORT_CHECK_START","ts":"2025-10-19T02:36:01.492Z","seq":14,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"module":"reporter","port":"ReporterPort@1"}}
+{"schema":"tm-events@1","event":"PORT_CHECK_START","ts":"2025-10-19T02:36:01.495Z","seq":15,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"module":"cli","port":"CLIPort@1"}}
+{"schema":"tm-events@1","event":"TSC_START","ts":"2025-10-19T02:36:01.500Z","seq":16,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"artifact":".tm/tsc.log"}}
+{"schema":"tm-events@1","event":"TSC_PASS","ts":"2025-10-19T02:36:02.866Z","seq":17,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"dur_ms":1364,"artifact":".tm/tsc.log"}}
+{"schema":"tm-events@1","event":"PORT_CHECK_PASS","ts":"2025-10-19T02:36:02.867Z","seq":18,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"module":"reporter","port":"ReporterPort@1"}}
+{"schema":"tm-events@1","event":"PORT_CHECK_PASS","ts":"2025-10-19T02:36:02.867Z","seq":19,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"module":"cli","port":"CLIPort@1"}}
+{"schema":"tm-events@1","event":"SIDEEFFECTS_SUMMARY","ts":"2025-10-19T02:36:02.880Z","seq":20,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"module":"cli","side_effects":{"declared":[],"observed_operations":[],"undeclared_operations":[],"fs_write":{"count":0,"outside_module_root":false,"sample_paths":[],"outside_samples":[]},"processes":{"total":0,"categories":{}}}}}
+{"schema":"tm-events@1","event":"SIDEEFFECTS_SUMMARY","ts":"2025-10-19T02:36:02.880Z","seq":21,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"module":"reporter","side_effects":{"declared":["FS:write"],"observed_operations":["FS:write"],"undeclared_operations":[],"fs_write":{"count":20,"outside_module_root":false,"sample_paths":[{"path":".tmp","inside_module_root":true},{"path":".tmp/case-t0cphL","inside_module_root":true},{"path":".tmp/case-t0cphL/reporter.log","inside_module_root":true},{"path":".tmp/case-XI63ZD","inside_module_root":true},{"path":".tmp/case-XI63ZD/reporter.log","inside_module_root":true}],"outside_samples":[]},"processes":{"total":0,"categories":{}}}}}
+{"schema":"tm-events@1","event":"GATES_SUMMARY","ts":"2025-10-19T02:36:02.881Z","seq":22,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"phases":[{"name":"manifest_validation","dur_ms":62,"status":"pass"},{"name":"lint","dur_ms":840,"status":"pass"},{"name":"tests","dur_ms":689,"status":"pass"},{"name":"typecheck","dur_ms":1370,"status":"pass"},{"name":"oracles","dur_ms":0,"status":"skipped"},{"name":"npm_pack","dur_ms":0,"status":"skipped"}],"dur_ms":2992,"passed":5,"failed":0,"skipped":0}}
+{"schema":"tm-events@1","event":"GATES_PASS","ts":"2025-10-19T02:36:02.881Z","seq":23,"source":{"cli":"tm","version":"0.1.0"},"context":{"run_id":"canon-demo","mode":"shipping","compose_sha256":"6809b66c0ea846ca9467f763b91e73b3cd9ccf87e462bf5e1beae3ccd2de1af0"},"detail":{"passed":5,"failed":0,"skipped":0,"dur_ms":2992}}

docs/briefs.md

@@ -1,3 +1,12 @@
+## Canon Loop Quick Reference
+
+- System prompt: copy the “Canon instructions excerpt” from `docs/implementation-briefs.md` into Codex Cloud before launching an implementation run.
+- Self-check: `.codex/selfcheck.sh <compose> <canon-lock> <modules-root>` wraps shipping gates plus canon verification and emits `artifacts/events.ndjson`.
+- Reports: after a PASS, duplicate `implementation_report.json.template`, fill the run metadata, and commit it with the new `artifacts/events.ndjson`.
+- MUST block: every C/E/F card now inherits the shared requirements list (ports bound, tests present, selfcheck run, report completed, no failing gates).
+
+---
+
 ## C1 — Add Type-Safe Shipping (TS compile in gates)
 
 **Why:** catch broken types in the winner workspace, not just schema/test issues.

docs/headless-bo4-runbook.md

@@ -102,6 +102,18 @@ cat <<'EOF' > runs/2024-07-01-demo/meta/followup.txt
 EOF
 ```
 
+## Canon failure remediation
+
+When `.codex/selfcheck.sh` or direct `tm gates shipping` runs fail, inspect the first error code in stderr and apply the matching fix before re-running.
+
+- **E_CANON_MISSING_MODULE**: generate the module scaffold with `node tm.mjs module --new <id>` (or create `modules/<id>/` manually), then implement the required files/tests from the canon lock.
+- **E_CANON_MISSING_INTERFACE**: add the missing `"port_exports"` entry in `modules/<id>/module.json` and expose the correct symbol/file.
+- **E_CANON_PORT_MISMATCH**: ensure the exported symbol matches the port contract (TypeScript/JS signature); update both the implementation and `port_exports`.
+- **E_CANON_MISSING_INVARIANT_TEST**: create the JSON spec or script listed in the lock, register it in `module.json/tests`, and wire it into the runner.
+- **E_CANON_MISSING_ACCEPTANCE**: scaffold `T-xxx` acceptance specs under the module’s `tests/` folder and make sure the runner executes them.
+- **E_TSC / E_LINT**: resolve TypeScript or lint diagnostics (missing types, cross-imports) highlighted in the gate output.
+- **Other errors** (`E_REQUIRE_UNSAT`, `E_HOOK`, etc.): follow the message guidance, fix the underlying issue, and rerun the self-check until PASS.
+
 ## References
 
 - `docs/headless-cloud.md` — automation details for watch/harvest/meta/compose/gates.

docs/headless-cloud.md

@@ -156,6 +156,22 @@ The command prints grouped logs for each stage, updates `runs/<slug>/run.json`,
 and leaves variant exports under `.codex-cloud/variants/...` ready for meta
 review or application.
 
+## Canon preflight hook (optional)
+
+If the Codex Cloud environment supports post-run hooks, wire in the canon
+verifier so failed stamps never surface as “ready”:
+
+```bash
+node tm.mjs gates shipping \
+  --compose runs/<slug>/meta/compose.json \
+  --modules-root modules \
+  --canon-lock amr/canon.lock.json \
+  --emit-events --events-out artifacts/events.ndjson --strict-events
+```
+
+The hook exits non-zero on canon or gating violations, keeping headless runs
+blocked until the local self-check loop produces a PASS.
+
 ## References
 
 - Codex Cloud CLI: run `codex cloud --help` for command trees and flags.