docs(commands): add Q42 scenarios and staleness metadata to arch-document

Two audit fixes. Section 10's thin quality-scenario template becomes the arc42/Q42 six-part form (source, stimulus, environment, artifact, response, response measure), making each scenario testable. Generated docs now carry staleness and ownership metadata: a per-section header (owner, generated-against commit and date, review cadence, stale-when conditions) and a whole-document Doc Status table, so a reader can tell whether a section still matches the code.

1 files changed, 52 insertions, 5 deletions

diff --git a/.claude/commands/arch-document.md b/.claude/commands/arch-document.md
index c22032a..d6a29bf 100644
--- a/.claude/commands/arch-document.md
+++ b/.claude/commands/arch-document.md
@@ -42,6 +42,30 @@ If `.architecture/brief.md` is absent, stop and tell the user to run `arch-desig
 5. **Cross-link** — ensure every ADR is referenced; every diagram has a narrative
 6. **Output** — one file per section under `docs/architecture/`, plus an index
 
+## Section Metadata (staleness and ownership)
+
+arc42 docs are living documents — they rot the moment the code moves on without them. So a reader can tell whether a section is still authoritative, prepend every generated section file with a metadata block, and surface the same fields in the README index. Use an HTML comment header followed by a visible note:
+
+```markdown
+<!--
+owner: <team or person responsible for this section>
+generated-against: <commit SHA> (<YYYY-MM-DD>)
+review-cadence: <e.g. quarterly, per-release, on ADR change>
+stale-when: <conditions that invalidate this section — e.g. "the checkout service is split", "a new datastore is added", "ADR-0007 is superseded">
+-->
+
+> **Doc status** — Owner: <owner>. Generated against `<short-SHA>` on <YYYY-MM-DD>. Review: <cadence>. Treat as stale when: <stale-when>.
+```
+
+Fill the fields from real inputs, not guesses:
+
+- **owner** — from the brief's stakeholder list or the team's CODEOWNERS; if unknown, write `TODO: assign owner` rather than inventing one.
+- **generated-against** — the current `HEAD` SHA and date at generation time (`git rev-parse --short HEAD` + the date). This pins the doc to the code it describes.
+- **review-cadence** — match the section's volatility: building blocks and runtime (§5, §6) churn with the code, so per-release; constraints and glossary (§2, §12) drift slowly, so quarterly or on-change.
+- **stale-when** — the specific structural changes that would make this section wrong. This is the most useful field: it tells a future reader exactly what to check before trusting the section. Phrase as observable conditions, not vague "if things change."
+
+A reader who hits a section whose `stale-when` condition has already happened knows to regenerate before relying on it.
+
 ## The Twelve arc42 Sections
 
 For each: what it's for, what goes in it, where the content comes from, and what to dispatch.
@@ -164,11 +188,19 @@ Plus a one-sentence summary of *why this set of decisions, not others*. The meta
 
 **Content:**
 - **Quality tree** — the ranked quality attributes from brief §4, each with refinements
-- **Quality scenarios** — specific, testable. Format: "Under [condition], the system should [response] within [measure]."
+- **Quality scenarios** — specific, testable, written to the arc42/Q42 six-part template. Each scenario names all six parts so it can be turned into a test or an SLO check without further interpretation:
+  - **Source** — who or what triggers the stimulus (user, upstream service, scheduler, attacker, operator)
+  - **Stimulus** — the event that arrives (a request spike, a node failure, a config change, a malformed payload)
+  - **Environment** — the system state when it happens (normal load, degraded mode, mid-deploy, peak traffic)
+  - **Artifact** — the part of the system affected (a service, the database, an interface, the whole system)
+  - **Response** — what the system does in reaction
+  - **Response measure** — the testable threshold that decides pass or fail
+
+A compact way to write it out:
 
-Example:
+> **Source:** an authenticated shopper. **Stimulus:** submits a cart checkout. **Environment:** peak traffic, 10,000 concurrent users. **Artifact:** the checkout service. **Response:** the order is confirmed and the payment authorized. **Response measure:** completes in under 2 seconds at the 95th percentile.
 
-> Under peak traffic (10,000 concurrent users), a cart checkout should complete in under 2 seconds at the 95th percentile.
+A one-line prose form is fine once all six parts are present and recoverable — favor the explicit breakdown when the scenario will drive a test or an SLO.
 
 Minimum 1 scenario per top-3 quality attribute.
 
@@ -253,9 +285,21 @@ specific section via the index.
 - Brief: [`.architecture/brief.md`](../../.architecture/brief.md)
 - Decisions: [`../adr/`](../adr/)
 
-## Last Updated
+## Doc Status
+
+Each section carries its own staleness header (owner, source commit, review
+cadence, stale-when conditions). This index records the whole-document
+provenance:
+
+| Field | Value |
+|---|---|
+| Owner | <team or person> |
+| Generated against | `<short-SHA>` (<YYYY-MM-DD>) |
+| Review cadence | <e.g. per-release> |
+| Stale when | <repo-wide conditions — e.g. "brief is revised", "any new ADR lands", "a new service is added"> |
 
-<YYYY-MM-DD> — regenerate by running `arch-document` after brief or ADR changes.
+Regenerate by running `arch-document` after brief or ADR changes; the headers
+re-pin to the current commit on each run.
 ```
 
 ## Dispatch to C4 Skills
@@ -290,6 +334,8 @@ Before marking the documentation complete:
 - [ ] Risks (§11) include likelihood and mitigation
 - [ ] Glossary (§12) captures domain terms, not just jargon
 - [ ] README index lists all sections with correct relative links
+- [ ] Every section file carries a staleness header (owner, generated-against SHA + date, review cadence, stale-when conditions)
+- [ ] README Doc Status table is filled with real provenance, not placeholders
 
 ## Anti-Patterns
 
@@ -299,6 +345,7 @@ Before marking the documentation complete:
 - **Uncurated ADR dump.** Section 9 should be a curated index with the *reason* these decisions hang together, not just a directory listing.
 - **Vague quality requirements.** "The system should be fast" is useless. Specify scenarios with measurable bounds.
 - **Risk-free architecture.** Every real system has risks. A blank risks section means you didn't look.
+- **Undated docs.** A section with no staleness header gives a reader no way to judge whether it still matches the code. Always pin to the generating commit and name the conditions that invalidate it.
 
 ## Maintenance