docs(AGENTS): PR↔Issue linkage policy

AGENTS.md

@@ -26,6 +26,15 @@ Welcome to the **Echo** project. This file captures expectations for any LLM age
 - Respect determinism: preferably no random seeds without going through the Echo PRNG.
 - Run `cargo clippy --all-targets -- -D missing_docs` and `cargo test` before every PR; CI will expect a zero-warning, fully documented surface.
 
+### PRs & Issues (Linkage Policy)
+- Every PR must be tied to a GitHub Issue.
+  - If no suitable issue exists, open one before you open the PR.
+  - Use explicit closing keywords in the PR body: include a line like `Closes #<issue-number>` so the issue auto‑closes on merge.
+  - Keep PRs single‑purpose: 1 PR = 1 thing. Avoid bundling unrelated changes.
+- Branch naming: prefer `echo/<short-feature-name>` or `timeline/<experiment>` and include the issue number in the PR title.
+- Docs Guard: when a PR touches non‑doc code, update `docs/execution-plan.md` and `docs/decision-log.md` in the same PR.
+- Project hygiene: assign the PR’s linked issue to the correct Milestone and Board column (Blocked/Ready/Done) as part of the PR.
+
 ### Git Hooks & Local CI
 - Install repo hooks once with `make hooks` (configures `core.hooksPath`).
 - Formatting: pre-commit auto-fixes with `cargo fmt` by default. Set `ECHO_AUTO_FMT=0` to run check-only instead.

docs/ISSUES_MATRIX.md

@@ -0,0 +1,21 @@
+# Echo Issues Matrix (Active Plan)
+
+This table mirrors the current state of active issues in Project 9 with our plan-aligned milestones and relationships. Native GitHub dependencies represent "blocked by"/"blocking"; we no longer use custom text fields for these. The Project board remains the live system of record for status.
+
+| Issue Name | Issue # | Milestone | Priority | Estimate | Blocked By | Blocking | Parent | Children | Remarks |
+| --- | ---: | --- | --- | --- | --- | --- | --- | --- | --- |
+| Benchmarks & CI Regression Gates | 22 | M1 – Golden Tests | P1 | 13h+ |  | #42,#43,#44,#45,#46 |  | 42,43,44,45,46 | Umbrella for perf pipeline |
+| Create benches crate | 42 | M1 – Golden Tests | P1 | 3h | #22 | #43,#44,#45,#46 | #22 |  | Criterion + scaffolding |
+| Snapshot hash microbench | 43 | M1 – Golden Tests | P1 | 5h | #22,#42 |  | #22 |  | Reachable hash microbench |
+| Scheduler drain microbench | 44 | M1 – Golden Tests | P1 | 5h | #22,#42 |  | #22 |  | Deterministic rule‑order/drain |
+| JSON report + CI upload | 45 | M1 – Golden Tests | P2 | 3h | #22,#42 | #46 | #22 |  | Upload Criterion JSON |
+| Regression thresholds gate | 46 | M1 – Golden Tests | P1 | 8h | #22,#42,#45 |  | #22 |  | Fail on P50/P95/P99 regress |
+| CLI: verify/bench/inspect | 23 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  | Grouping placeholder; break down in PRs |
+| Scaffold CLI subcommands | 47 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  |  |
+| Implement 'verify' | 48 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  |  |
+| Implement 'bench' | 49 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  |  |
+| Implement 'inspect' | 50 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  |  |
+| Docs/man pages | 51 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  | Tie docs to CLI UX |
+| README+docs (defaults & toggles) | 41 | M4 – Determinism Proof & Publish 0.1 | P2 | 3h |  |  |  |  | Docs polish before 0.1 |
+
+Backlog issues are labeled `backlog` and kept visible in the Project; they will be prioritized into milestones as needed.

docs/ROADMAP.md

@@ -0,0 +1,77 @@
+# Echo Roadmap (Milestones + Issue Map)
+
+This roadmap reconciles our current plan with GitHub milestones, issues, and the Project board (Project 9). It is the single source of truth for “what’s next”.
+
+---
+
+## Milestones
+
+- M1 – Golden Tests
+  - Bit‑exact golden vectors for state_root/commit_id (genesis, merge, empty)
+  - Math kernel goldens (rotation/multiply/sin/cos)
+  - CI matrix: macOS + Ubuntu (glibc) + Alpine (musl)
+- M2.0 – Scalar Foundation
+  - Scalar trait; F32Scalar deterministic wrappers; DFix64 Q32.32
+  - Deterministic transcendentals (LUT + refinement); tables checked‑in
+  - Motion rule → Scalar; v2 payload (6×i64 Q32.32), dual decode v1/v2
+- M2.1 – Lattice Joins
+  - Lattice trait; scheduler fold order
+  - Exemplar lattices: tags union, cap/max
+  - ACI property + replay determinism tests
+- M2.2 – Playground Slice
+  - Minimal WASM demo; CLI run/diff showing replay‑identical hashes
+- M2.5 – Accumulator Joins
+  - Delta‑style joins; deterministic rounding/saturation; ACI + replay
+- M3 – Sweep‑and‑Prune v1
+  - Integerized endpoints; stable tie‑breakers; ordering/stability property tests
+- M4 – Determinism Proof & Publish 0.1
+  - Prove determinism across OSes; finalize docs; publish rmg‑core/geom 0.1
+
+---
+
+## Issue Table (live snapshot)
+
+Rows are GitHub issues. Priority/Estimate reflect Project 9 fields. Block/parent relationships use native GitHub issue dependencies; no custom text fields are used.
+
+| Issue Name | # | Milestone | Priority | Estimate | Blocked By | Blocking | Parent | Children | Remarks |
+| --- | ---: | --- | --- | --- | --- | --- | --- | --- | --- |
+| Benchmarks & CI Regression Gates | 22 | M1 – Golden Tests | P1 | 13h+ |  | #42,#43,#44,#45,#46 |  | 42,43,44,45,46 | Umbrella for perf pipeline |
+| Create benches crate | 42 | M1 – Golden Tests | P1 | 3h | #22 | #43,#44,#45,#46 | #22 |  | Criterion + scaffolding |
+| Snapshot hash microbench | 43 | M1 – Golden Tests | P1 | 5h | #22,#42 |  | #22 |  | Reachable hash microbench |
+| Scheduler drain microbench | 44 | M1 – Golden Tests | P1 | 5h | #22,#42 |  | #22 |  | Deterministic rule‑order/drain |
+| JSON report + CI upload | 45 | M1 – Golden Tests | P2 | 3h | #22,#42 |  | #22 |  | Upload Criterion JSON |
+| Regression thresholds gate | 46 | M1 – Golden Tests | P1 | 8h | #22,#42,#45 |  | #22 |  | Fail on P50/P95/P99 regress |
+| CLI: verify/bench/inspect | 23 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  | Grouping placeholder; break down in PRs |
+| Scaffold CLI subcommands | 47 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  |  |
+| Implement 'verify' | 48 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  |  |
+| Implement 'bench' | 49 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  |  |
+| Implement 'inspect' | 50 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  |  |
+| Docs/man pages | 51 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  | Tie docs to CLI UX |
+| README+docs (defaults & toggles) | 41 | M4 – Determinism Proof & Publish 0.1 | P2 | 3h |  |  |  |  | Docs polish before 0.1 |
+| Spec: Commit/Manifest Signing | 20 | Backlog |  |  |  |  |  |  | Keep under Backlog until publish plan is firm |
+| Spec: Security Contexts (FFI/WASM/CLI) | 21 | Backlog |  |  |  |  |  |  | Backlog (security track) |
+| Plugin ABI (C) v0 | 26 | Backlog |  |  |  |  |  |  | Track in separate ABI milestone later |
+| Example plugin + tests | 89 | Backlog |  |  |  |  |  |  | Depends on ABI |
+| Capability tokens | 88 | Backlog |  |  |  |  |  |  | — |
+| Version negotiation | 87 | Backlog |  |  |  |  |  |  | — |
+| C header + host loader | 86 | Backlog |  |  |  |  |  |  | — |
+| Draft C ABI spec | 85 | Backlog |  |  |  |  |  |  | — |
+| Importer + store tasks | 80–84 | Backlog |  |  |  |  |  |  | Import flow (spec/loader/reader) |
+
+Note: Backlog means “not part of the current M1/M2 trajectory”; issues remain visible in the Project with the `backlog` label and can be re‑prioritized later.
+
+---
+
+## Immediate Plan (Next PRs)
+
+- PR‑11 (Closes #42): benches crate skeleton (Criterion + harness)
+- PR‑12 (Closes #43): snapshot hash microbench
+- PR‑13 (Closes #44): scheduler drain microbench
+- PR‑14 (Closes #45): JSON artifact + upload
+- PR‑15 (Closes #46): regression thresholds gate
+
+In parallel (when ready): seed M2.0 – Scalar Foundation umbrella and child issues, then start the first scalar PR (trait + backends skeleton).
+
+---
+
+Maintainers: keep this file in sync when re‑prioritizing or moving issues between milestones. This roadmap complements the Project board, which carries Priority/Estimate fields and live status.

docs/echo-total.md

@@ -719,6 +719,118 @@ The following entries use a heading + bullets format for richer context.
 ---
 
 
+# File: ISSUES_MATRIX.md
+
+# Echo Issues Matrix (Active Plan)
+
+This table mirrors the current state of active issues in Project 9 with our plan-aligned milestones and relationships. Native GitHub dependencies represent "blocked by"/"blocking"; we no longer use custom text fields for these. The Project board remains the live system of record for status.
+
+| Issue Name | Issue # | Milestone | Priority | Estimate | Blocked By | Blocking | Parent | Children | Remarks |
+| --- | ---: | --- | --- | --- | --- | --- | --- | --- | --- |
+| Benchmarks & CI Regression Gates | 22 | M1 – Golden Tests | P1 | 13h+ |  | #42,#43,#44,#45,#46 |  | 42,43,44,45,46 | Umbrella for perf pipeline |
+| Create benches crate | 42 | M1 – Golden Tests | P1 | 3h | #22 | #43,#44,#45,#46 | #22 |  | Criterion + scaffolding |
+| Snapshot hash microbench | 43 | M1 – Golden Tests | P1 | 5h | #22,#42 |  | #22 |  | Reachable hash microbench |
+| Scheduler drain microbench | 44 | M1 – Golden Tests | P1 | 5h | #22,#42 |  | #22 |  | Deterministic rule‑order/drain |
+| JSON report + CI upload | 45 | M1 – Golden Tests | P2 | 3h | #22,#42 | #46 | #22 |  | Upload Criterion JSON |
+| Regression thresholds gate | 46 | M1 – Golden Tests | P1 | 8h | #22,#42,#45 |  | #22 |  | Fail on P50/P95/P99 regress |
+| CLI: verify/bench/inspect | 23 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  | Grouping placeholder; break down in PRs |
+| Scaffold CLI subcommands | 47 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  |  |
+| Implement 'verify' | 48 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  |  |
+| Implement 'bench' | 49 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  |  |
+| Implement 'inspect' | 50 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  |  |
+| Docs/man pages | 51 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  | Tie docs to CLI UX |
+| README+docs (defaults & toggles) | 41 | M4 – Determinism Proof & Publish 0.1 | P2 | 3h |  |  |  |  | Docs polish before 0.1 |
+
+Backlog issues are labeled `backlog` and kept visible in the Project; they will be prioritized into milestones as needed.
+
+
+---
+
+
+# File: ROADMAP.md
+
+# Echo Roadmap (Milestones + Issue Map)
+
+This roadmap reconciles our current plan with GitHub milestones, issues, and the Project board (Project 9). It is the single source of truth for “what’s next”.
+
+---
+
+## Milestones
+
+- M1 – Golden Tests
+  - Bit‑exact golden vectors for state_root/commit_id (genesis, merge, empty)
+  - Math kernel goldens (rotation/multiply/sin/cos)
+  - CI matrix: macOS + Ubuntu (glibc) + Alpine (musl)
+- M2.0 – Scalar Foundation
+  - Scalar trait; F32Scalar deterministic wrappers; DFix64 Q32.32
+  - Deterministic transcendentals (LUT + refinement); tables checked‑in
+  - Motion rule → Scalar; v2 payload (6×i64 Q32.32), dual decode v1/v2
+- M2.1 – Lattice Joins
+  - Lattice trait; scheduler fold order
+  - Exemplar lattices: tags union, cap/max
+  - ACI property + replay determinism tests
+- M2.2 – Playground Slice
+  - Minimal WASM demo; CLI run/diff showing replay‑identical hashes
+- M2.5 – Accumulator Joins
+  - Delta‑style joins; deterministic rounding/saturation; ACI + replay
+- M3 – Sweep‑and‑Prune v1
+  - Integerized endpoints; stable tie‑breakers; ordering/stability property tests
+- M4 – Determinism Proof & Publish 0.1
+  - Prove determinism across OSes; finalize docs; publish rmg‑core/geom 0.1
+
+---
+
+## Issue Table (live snapshot)
+
+Rows are GitHub issues. Priority/Estimate reflect Project 9 fields. Block/parent relationships use native GitHub issue dependencies; no custom text fields are used.
+
+| Issue Name | # | Milestone | Priority | Estimate | Blocked By | Blocking | Parent | Children | Remarks |
+| --- | ---: | --- | --- | --- | --- | --- | --- | --- | --- |
+| Benchmarks & CI Regression Gates | 22 | M1 – Golden Tests | P1 | 13h+ |  | #42,#43,#44,#45,#46 |  | 42,43,44,45,46 | Umbrella for perf pipeline |
+| Create benches crate | 42 | M1 – Golden Tests | P1 | 3h | #22 | #43,#44,#45,#46 | #22 |  | Criterion + scaffolding |
+| Snapshot hash microbench | 43 | M1 – Golden Tests | P1 | 5h | #22,#42 |  | #22 |  | Reachable hash microbench |
+| Scheduler drain microbench | 44 | M1 – Golden Tests | P1 | 5h | #22,#42 |  | #22 |  | Deterministic rule‑order/drain |
+| JSON report + CI upload | 45 | M1 – Golden Tests | P2 | 3h | #22,#42 |  | #22 |  | Upload Criterion JSON |
+| Regression thresholds gate | 46 | M1 – Golden Tests | P1 | 8h | #22,#42,#45 |  | #22 |  | Fail on P50/P95/P99 regress |
+| CLI: verify/bench/inspect | 23 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  | Grouping placeholder; break down in PRs |
+| Scaffold CLI subcommands | 47 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  |  |
+| Implement 'verify' | 48 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  |  |
+| Implement 'bench' | 49 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  |  |
+| Implement 'inspect' | 50 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  |  |
+| Docs/man pages | 51 | M2.2 – Playground Slice | P2 | 5h |  |  |  |  | Tie docs to CLI UX |
+| README+docs (defaults & toggles) | 41 | M4 – Determinism Proof & Publish 0.1 | P2 | 3h |  |  |  |  | Docs polish before 0.1 |
+| Spec: Commit/Manifest Signing | 20 | Backlog |  |  |  |  |  |  | Keep under Backlog until publish plan is firm |
+| Spec: Security Contexts (FFI/WASM/CLI) | 21 | Backlog |  |  |  |  |  |  | Backlog (security track) |
+| Plugin ABI (C) v0 | 26 | Backlog |  |  |  |  |  |  | Track in separate ABI milestone later |
+| Example plugin + tests | 89 | Backlog |  |  |  |  |  |  | Depends on ABI |
+| Capability tokens | 88 | Backlog |  |  |  |  |  |  | — |
+| Version negotiation | 87 | Backlog |  |  |  |  |  |  | — |
+| C header + host loader | 86 | Backlog |  |  |  |  |  |  | — |
+| Draft C ABI spec | 85 | Backlog |  |  |  |  |  |  | — |
+| Importer + store tasks | 80–84 | Backlog |  |  |  |  |  |  | Import flow (spec/loader/reader) |
+
+Note: Backlog means “not part of the current M1/M2 trajectory”; issues remain visible in the Project with the `backlog` label and can be re‑prioritized later.
+
+---
+
+## Immediate Plan (Next PRs)
+
+- PR‑11 (Closes #42): benches crate skeleton (Criterion + harness)
+- PR‑12 (Closes #43): snapshot hash microbench
+- PR‑13 (Closes #44): scheduler drain microbench
+- PR‑14 (Closes #45): JSON artifact + upload
+- PR‑15 (Closes #46): regression thresholds gate
+
+In parallel (when ready): seed M2.0 – Scalar Foundation umbrella and child issues, then start the first scalar PR (trait + backends skeleton).
+
+---
+
+Maintainers: keep this file in sync when re‑prioritizing or moving issues between milestones. This roadmap complements the Project board, which carries Priority/Estimate fields and live status.
+
+
+---
+
+
 # File: branch-merge-playbook.md
 
 # Branch Merge Conflict Playbook