diff --git a/AGENTS.md b/AGENTS.md index 7e19b22..97d54f4 100644 --- a/AGENTS.md +++ b/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 #` so the issue auto‑closes on merge. + - Keep PRs single‑purpose: 1 PR = 1 thing. Avoid bundling unrelated changes. +- Branch naming: prefer `echo/` or `timeline/` 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. diff --git a/docs/ISSUES_MATRIX.md b/docs/ISSUES_MATRIX.md new file mode 100644 index 0000000..ba81862 --- /dev/null +++ b/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. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..3c4ad3a --- /dev/null +++ b/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. diff --git a/docs/echo-total.md b/docs/echo-total.md index fb564b4..3fbf868 100644 --- a/docs/echo-total.md +++ b/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