From d8a433fff34e4a3e52c07632b93c510e7f0e6671 Mon Sep 17 00:00:00 2001 From: Guy Corbaz Date: Wed, 29 Jul 2026 09:39:32 +0200 Subject: [PATCH] chore: track the architecture-views.md staleness as issue #50, and measure the drift MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The debt lived only in CLAUDE.md, docs/project-context.md and the sprint notes. This project's own rule is that GitHub Issues are the single source of truth for work items outside the BMad story flow, so a milestone task tracked in prose was the one most likely to be forgotten — and it already had been: the milestone the notes named (the close of Epic 4) passed on 2026-07-25 without it. Both notes now point at #50, and both carry what was MEASURED rather than what was assumed: · the drift is two commits, 59 insertions / 11 deletions — `7d4b1bd` (the D65 post-completion section) and `da23f9f` (the source-tree diagram freshness pass). NEITHER touches a decision body, a dissent or a renunciation, which is what the views file gathers, so the content drift is smaller than the hash suggests; · there is NO generator. `cargo xtask` exposes only `ci`, whose views-hash check merely VERIFIES the frontmatter hash. "DERIVED — never edit by hand" has always meant "not independently of the source", not "a tool does it"; · the bulk of the real work is re-checking that the 883-line view file's line citations still resolve, since architecture.md grew by 236 lines. project-context.md's note also stops naming Epic 4's close as the milestone: a sentence that describes a plan the project did not carry out reads as a fact and sends the next reader to the wrong place. No code changes. `cargo xtask ci` green. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 2 +- docs/project-context.md | 16 +++++++++++++--- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 6fb25a1..f717cf8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,7 +11,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co - **Build:** `cargo build --workspace --locked` (Cargo.lock is committed; always `--locked`). - **Test:** `cargo test --workspace`. - **Lint:** `cargo clippy --workspace -- -D warnings` · **Format:** `cargo fmt --all`. -- **Project gates:** `cargo xtask ci` — every gate lives here in Rust, never in YAML (D56/D65): the dependency-frontier check (D47), the DDL binary-collation grep (D64 cond. 1), the retired-vocabulary check (D65), and the fixture corpus lock (sha256 **and** orphan detection, both directions). The `architecture-views.md` staleness hash reports `ℹ STALE` and still exits 0 — that is by design, and **it must not be regenerated inside a story**; regenerate at a milestone. *(Some other xtask subcommands are still stubs.)* +- **Project gates:** `cargo xtask ci` — every gate lives here in Rust, never in YAML (D56/D65): the dependency-frontier check (D47), the DDL binary-collation grep (D64 cond. 1), the retired-vocabulary check (D65), and the fixture corpus lock (sha256 **and** orphan detection, both directions). The `architecture-views.md` staleness hash reports `ℹ STALE` and still exits 0 — that is by design, and **it must not be regenerated inside a story**; regenerate at a milestone. **Tracked as GitHub issue #50**, which carries the measured drift (two commits, 59 insertions, no decision body touched) — the debt no longer lives only in these notes. *(Some other xtask subcommands are still stubs.)* - **Toolchain:** Rust 1.96+, edition 2024. **Stack:** axum 0.8 · askama 0.16 · sqlx `=0.9.0` (MariaDB-only, `mysql`+`tls-rustls-ring`) · tokio · `config` · `rust-i18n` (YAML) · `prometheus` (raw) · Tailwind standalone CLI via `cargo xtask css`. **Never invent a version — pin from the real `Cargo.lock`.** ### The dependency frontier is load-bearing (D47), and it is a gate diff --git a/docs/project-context.md b/docs/project-context.md index e729795..a2b3032 100644 --- a/docs/project-context.md +++ b/docs/project-context.md @@ -86,7 +86,14 @@ the MANIFEST, dated notes in `epics.md`, and `_bmad-output/implementation-artifacts/epic-4-correct-course-2026-07-25.md`. ⚠️ **The one milestone task now DUE and not done: regenerating `architecture-views.md`** (its `sourceSha256` has not matched since commit `da23f9f`, which predates Epic 4 — the staleness is inherited, not -caused by this epic; the end of Epic 4 is the milestone the project chose for it). +caused by this epic; the end of Epic 4 is the milestone the project chose for it, and it passed). +**Now tracked as GitHub issue #50** rather than in these notes alone. The drift was MEASURED on +2026-07-29 and is smaller than the hash suggests: **two commits, 59 insertions / 11 deletions**, and +neither touches a decision body, a dissent or a renunciation — one corrects the source-tree diagram +(D64 fallout), the other adds a D65 post-completion section. ⚠️ **There is no generator** — `cargo +xtask` exposes only `ci`, whose `views-hash` check merely VERIFIES the frontmatter hash. The bulk of +the real work is re-checking that the 883 view file's line citations still resolve, since the source +grew by 236 lines. **The fixture corpus was the epic's centre of gravity.** `fixtures/` at the workspace root is a SPEC, not test data, locked by `MANIFEST.toml` in both directions. A replay stream carries @@ -142,8 +149,11 @@ one. The two sqlx traps it warned about were both real and are both handled in t > **Note on `architecture-views.md`:** it is STILL stale, deliberately — `cargo xtask ci` reports > `ℹ views-hash STALE` and exits 0, because the mismatch IS the staleness signal. Regenerate it at a -> MILESTONE (the end of Epic 4 is the natural one), not per-decision or per-story. **Do not -> regenerate it inside a story**; several story files say so explicitly. +> MILESTONE, not per-decision or per-story. **Do not regenerate it inside a story**; several story +> files say so explicitly. **Tracked as GitHub issue #50**, which carries the measured scope. +> _(This note named "the end of Epic 4" as the natural milestone. Epic 4 closed on 2026-07-25 and +> the regeneration did not happen, so that sentence had become a plan rather than a fact — which is +> exactly why it is now an issue and not only a note.)_ ## Locked, non-negotiable decisions (do not reopen)