diff --git a/AGENTS.md b/AGENTS.md index bb66048..58b7fb9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -107,6 +107,9 @@ Prefer a **single `INV-NNN-slug.md`** when the finding fits in one file. When da ### Guidebook maintenance Altering a component that is documented in `guidebooks/` **requires updating that guidebook page in the same change**. A code/infra change that leaves its guidebook stale is incomplete. +### Milestone closure & doc freshness +Docs describe intent; **STATUS.md + git describe reality**. Writer's half: a milestone is closed only after the closure sweep, which **opens with a QA gate** (acceptance criteria re-verified with evidence, test suites green, status flips backed by eval results — nothing documented as done before it is proven done) and **ends with doc-surface QA** (link/anchor check, deprecation grep for the claims the milestone retired, fresh-reader smoke test by a context-free subagent); in between: flip the PRD `STATUS.md` phase row, re-baseline the roadmap at the boundary, truth-pass every leaf/`AGENTS.md`/`SKILL.md` claim the increment invalidated (no-tombstone, bump Last Updated on changed files only). Canonical checklist: the [ai-back-office STATUS closure protocol](vibe/PRD/ai-back-office/STATUS.md). Continuously: a PR that makes a documented claim false updates that doc **in the same PR**. Reader's half: before acting on any versionable claim, verify in trust order — **live system > code/git log > STATUS > leaves > memories/plans**; a page whose Last Updated predates the newest closed milestone in its area is suspect. + ### Language policy **English** for everything in `vibe/` and for `AGENTS.md`/`CLAUDE.md` (this tree is for LLM agents). The single exception: **shareouts handouts are FRENCH**. diff --git a/vibe/PRD/ai-back-office/STATUS.md b/vibe/PRD/ai-back-office/STATUS.md index 2c9df18..a0cfe08 100644 --- a/vibe/PRD/ai-back-office/STATUS.md +++ b/vibe/PRD/ai-back-office/STATUS.md @@ -30,6 +30,23 @@ Every phase is decomposed into **self-contained issues** (context, deliverables, | [telegram-gateway](https://gitea.arcodange.lab/arcodange/telegram-gateway/issues) | #1 Postgres durable queue (D1) · #2 daily digest + approval cards | | [factory](https://gitea.arcodange.lab/arcodange-org/factory/issues) | #22 ADRs as decisions close (D1/D2/D4/D6/D7) | +## Closure protocol — per milestone + +The resume protocol tells a session where to pick up work; this one keeps the doc surface **currently true** when work lands. Docs describe intent; **this file + git describe reality**. A Gitea milestone is closed only after the sweep — and the sweep starts with QA, because nothing gets documented as done before it is *proven* done: + +1. **QA gate — verify before documenting.** (a) Every closed issue's **acceptance criteria re-verified** with evidence linked (eval scores, run journals, exit-gate results — not memory of them); (b) the milestone's **test suites green**: golden-set regressions at their bars, injection fixtures quarantined, linter suites behaving (forbidden manifests rejected, seeded-wrong provenance fixtures FAIL), idempotency replay no-op, watchdog/heartbeat checks where the milestone ships standing loops ([QA strategy](qa-strategy.md)); (c) any 🧪→✅ flip in the [agent-catalog](agent-catalog.md) backed by its proving-protocol evidence. A milestone that can't pass its own QA doesn't close — it sheds scope back into open issues. +2. **Flip the phase row** above (✅ + date + PR links) and prune the backlog map of closed issues. +3. **Re-baseline the [roadmap](roadmap.md)** at the boundary: mark the stream done, re-date downstream engineering bars if they slipped — regulatory diamonds never move; slips shed scope instead. Bump its Last Updated. +4. **Truth-pass the affected leaves** (no-tombstone — rewrite as currently true, no "previously/now"): the [task inventory](task-inventory.md) `Today:`/`Target:` lines the milestone changed; the agent-catalog matrix; `not yet`/candidate claims in [architecture](agent-architecture.md), [model-fleet](model-fleet.md), [compliance](compliance.md). Bump Last Updated **only on files whose claims changed**. +5. **Sweep the orientation layer**: repo `AGENTS.md` files (map rows, "not yet landed" pointers), touched `SKILL.md`s, and any [guidebook](../../guidebooks/erp/README.md) page mapping a changed component (house same-change rule). +6. **Doc-surface QA — mechanical + fresh-reader.** (a) Run the link/anchor/convention check over the PRD tree (the `prd_check` pattern: every relative link + heading anchor resolves, breadcrumbs, stamps) — zero broken; (b) **deprecation grep**: list the claims the milestone retired (read them off the closed issues — e.g. `frequency=0`, "not yet landed", "no fleet wiring") and grep `vibe/` + the repos' `AGENTS.md`/`SKILL.md` for them — zero hits or fixed; (c) **fresh-reader smoke test**: a context-free subagent reads only STATUS + the repo `AGENTS.md` and must answer "what shipped, what's next, what would you verify before trusting?" correctly — if it lands on a stale claim, real sessions will too. +7. **Close the loop outward**: ADRs for decisions the milestone settled ([factory#22](https://gitea.arcodange.lab/arcodange-org/factory/issues/22)), agent memories updated or pruned, a REX note into the second brain (T17 once live). +8. Only then **close the Gitea milestone**. + +Between milestones, the continuous rule stands: **a PR that makes any documented claim false updates that doc in the same PR** — a change that leaves its docs stale is an incomplete change. + +**Reader's half — trust order.** Any session, before acting on a versionable claim (a path exists, a flag's value, a status emoji): verify against **live system > code/git log > this STATUS > PRD leaves > agent memories/plans**. A page whose Last Updated predates the newest closed milestone in its area is suspect — verify before relying on it. + ## Foundation ledger (shipped pre-PRD) The bricks this PRD builds on, in the [erp](https://gitea.arcodange.lab/arcodange-org/erp), [factory](https://gitea.arcodange.lab/arcodange-org/factory) and [tools](https://gitea.arcodange.lab/arcodange-org/tools) repos: