docs(#6423): document extract-to-living-doc pattern for ADRs

docs/contributing/adrs.md

@@ -4,6 +4,8 @@ These rules apply whenever you touch `docs/ADRs/` or review a PR that does. Full
 
 **Immutability:** Once an ADR on `main` has status **Accepted**, it is a point-in-time record. Do not substantially rewrite its Context, Decision, or Consequences sections. When circumstances change, write a **new** ADR that supersedes the old one. Minor annotations are welcome: cross-references to related ADRs, short notes linking to newer decisions, typo and broken-link fixes, and status changes (e.g., to Deprecated or Superseded). Call out any edits to accepted ADRs in the PR description.
 
+**Extracting evolving details to living docs:** When operational details mentioned in an accepted ADR evolve over time (field tables, struct definitions, merge rules, configuration examples), do not update the ADR. Instead, extract those details to a living reference document under `docs/contributing/` and link from the ADR to the new document. The ADR records the decision; the living doc tracks the current state. See [`docs/contributing/harness-fields.md`](harness-fields.md) for a concrete example — it holds the evolving field tables while [ADR-0045](../../docs/ADRs/0045-forge-portable-harness-schema.md) records the original decision.
+
 **New ADRs in pull requests:** Approval happens at **merge**, not when the branch is created. If the decision is made, set status to **Accepted** in the ADR you are proposing — not a lesser status merely because the PR is open. Valid statuses are **Accepted**, **Deprecated**, and **Superseded**. When status is Accepted, update `docs/architecture.md` and related problem docs in the same PR per the writing-adrs skill. When editing an ADR that has not yet merged to `main`, change the content directly — do not add "Revised" annotations, revision dates, or revision history sections. The ADR is still being authored; treat edits as normal authoring, not post-acceptance amendments.
 
-**When reviewing PRs:** Flag substantial rewrites to Context, Decision, or Consequences on Accepted ADRs already on `main` as a policy violation. Allow minor annotations (cross-references, short notes, typo fixes), status updates, and supersession links. For brand-new ADR files on the PR branch, evaluate whether the recorded decision matches the diff — do not treat **Accepted** on a new file as a mistake if the ADR is ready for human review at merge.
+**When reviewing PRs:** Flag substantial rewrites to Context, Decision, or Consequences on Accepted ADRs already on `main` as a policy violation. Allow minor annotations (cross-references, short notes, typo fixes), status updates, and supersession links. Flag PRs that add evolving operational detail (field tables, struct definitions, merge rules, configuration examples) to an accepted ADR — the correct approach is to extract those details to a living doc under `docs/contributing/` and link back. For brand-new ADR files on the PR branch, evaluate whether the recorded decision matches the diff — do not treat **Accepted** on a new file as a mistake if the ADR is ready for human review at merge.

skills/writing-adrs/SKILL.md

@@ -45,6 +45,17 @@ If a decision turned out to be wrong, that is what supersession is for. The
 original ADR remains as a historical record of what was decided and why. For
 ongoing design narrative, use `docs/architecture.md`.
 
+**When operational details evolve:** ADRs sometimes describe operational details
+that change over time — field tables, struct definitions, merge rules, or
+configuration examples. When those details need updating, do not modify the
+ADR. Instead, extract them to a living reference document under
+`docs/contributing/` and add a link from the ADR to the new document. The ADR
+records the decision; the living doc tracks the current state. For example,
+[`docs/contributing/harness-fields.md`](../../docs/contributing/harness-fields.md)
+holds the evolving field classifications while
+[ADR-0045](../../docs/ADRs/0045-forge-portable-harness-schema.md) records the
+original schema decision.
+
 ### docs/architecture.md is always current
 
 Unlike ADRs, `docs/architecture.md` is a **living document**. It must always
@@ -204,6 +215,9 @@ If the ADR partially answers a question, add a parenthetical:
   accepted ADR -- write a new superseding ADR instead
 - You're turning an old ADR into a running changelog -- use
   `docs/architecture.md` for evolving design narrative
+- You're adding evolving operational details (field tables, struct definitions,
+  merge rules) to an accepted ADR -- extract them to a living doc under
+  `docs/contributing/` and link back
 
 ## Common Mistakes
 
@@ -219,5 +233,6 @@ If the ADR partially answers a question, add a parenthetical:
 | Substantially rewriting an accepted ADR | Write a new ADR that supersedes it |
 | Omitting cross-references to related ADRs | Link older ADRs to newer related decisions |
 | Treating old ADRs as evolving design docs | Use `docs/architecture.md` for living narrative |
+| Adding evolving operational details to an accepted ADR | Extract to a living doc under `docs/contributing/` and link back |
 | Forgetting to update architecture.md | It must always reflect current decisions |
 | Leading zeros in title number | Use `"1. Title"` not `"0001. Title"` — zero-padded numbers are only for filenames |