docs(commands): make arch-decide examples timeless, standardize ADR statuses

Two audit fixes. Sample ADRs asserted technical claims as timeless fact (MongoDB transactions). The example is now dated and sourced, and a "cite, don't assert" rule requires a link, version, or checked-date for any concrete technical claim. The status vocabulary was mixed (Accepted, Decided, Superseded, Not Accepted). It's now a canonical five (Proposed, Accepted, Rejected, Deprecated, Superseded) with an explicit immutability rule: an accepted ADR's body is frozen, and a changed decision gets a new superseding ADR while the old one stays as the record.

1 files changed, 9 insertions, 4 deletions

diff --git a/.claude/commands/arch-decide.md b/.claude/commands/arch-decide.md
index 887e082..5398f88 100644
--- a/.claude/commands/arch-decide.md
+++ b/.claude/commands/arch-decide.md
@@ -94,7 +94,8 @@ compliance for financial transactions.
 ### Option 3: MongoDB
 
 - **Pros**: Flexible schema, native JSON, horizontal scaling
-- **Cons**: No ACID for multi-document transactions (at decision time),
+- **Cons**: As of the evaluation in 2024-01, multi-document transactions
+  carried constraints we wanted to avoid (see vendor docs cited below);
   team has limited experience, requires schema design discipline
 
 ## Decision
@@ -150,6 +151,7 @@ additional services (no separate Elasticsearch needed).
 
 - [PostgreSQL JSON Documentation](https://www.postgresql.org/docs/current/datatype-json.html)
 - [PostgreSQL Full Text Search](https://www.postgresql.org/docs/current/textsearch.html)
+- [MongoDB Transactions](https://www.mongodb.com/docs/manual/core/transactions/) — backs the multi-document-transaction note in Option 3 (checked 2024-01)
 - Internal: Performance benchmarks in `/docs/benchmarks/database-comparison.md`
 ```
 
@@ -363,11 +365,13 @@ This directory contains Architecture Decision Records (ADRs) for [Project Name].
 
 ## ADR Status
 
+These five are the canonical status set. Use exactly these labels — no synonyms (no "Decided", "Not Accepted", "Active"):
+
 - **Proposed**: Under discussion
 - **Accepted**: Decision made, implementing
-- **Deprecated**: No longer relevant
-- **Superseded**: Replaced by another ADR
 - **Rejected**: Considered but not adopted
+- **Deprecated**: No longer relevant
+- **Superseded**: Replaced by another ADR (link forward to the replacement)
 ```
 
 ### Automation (adr-tools)
@@ -428,12 +432,13 @@ adr link 2 "Complements" 1 "Is complemented by"
 - **Write ADRs early** - Before implementation starts
 - **Keep them short** - 1-2 pages maximum
 - **Be honest about trade-offs** - Include real cons
+- **Cite, don't assert** - Every concrete technical claim about a tool, version, or platform (a missing feature, a benchmark number, a limit) carries a reference: a link, a doc, a version, or a "checked YYYY-MM" date. Capabilities change between releases, so an unsourced "X can't do Y" reads as timeless fact and rots. Scope claims to the date and version they were true for, or replace the specific with a domain-neutral placeholder.
 - **Link related decisions** - Build decision graph
 - **Update status** - Deprecate when superseded
 
 ### Don'ts
 
-- **Don't change accepted ADRs** - Write new ones to supersede
+- **Don't change accepted ADRs** - An accepted ADR's body is immutable. The only edits allowed after acceptance are to status/link metadata: flipping the Status line (to Deprecated or Superseded) and adding a forward link to the ADR that replaces it. When a decision changes, write a NEW ADR that supersedes the old one — set the new ADR's status to `Accepted (Supersedes ADR-NNNN)` and the old ADR's status to `Superseded by ADR-MMMM`. The old ADR stays in the directory as the historical record; never delete or rewrite it.
 - **Don't skip context** - Future readers need background
 - **Don't hide failures** - Rejected decisions are valuable
 - **Don't be vague** - Specific decisions, specific consequences