docs(#4910): ADR-4910 — the PlanningDoc parse → mutate → serialize seam — Phase 0 of #4906 (#4911)

* docs(#4910): ADR-4910 — the PlanningDoc parse → mutate → serialize seam — Phase 0 of #4906

Design lock for epic #4906. Docs-only; no production code lands here.

Eight decisions: one PlanningDoc seam composing markdown-sectionizer,
markdown-table and frontmatter as layers; node-replacement writes so a field
write cannot reach past its own value; byte-stable serialization for untouched
regions; escape-or-refuse shared between each artifact's writer and its reader,
with an explicit accepted-superset-of-emittable split; a typed parse error
scoped to the node rather than the document; a type-narrowed write boundary
paired with a lint; a positive control per accepted grammar; and one
implementation per shared pattern.

Two corrections to the epic's stated mechanism, both load-bearing for later
phases:

- The epic asks for a ratchet where a reintroduced content.replace() "does not
  typecheck". It cannot: fs.writeFileSync(p, s.replace(...)) typechecks fine
  because fs has never heard of PlanningDoc. Enforcement is type-narrowing plus
  a lint that owns the bypass, and the ADR says so rather than shipping a
  guarantee one require() defeats.
- The epic names scripts/lint-planning-artifact-writer-drift.cjs as the drain
  point. That script is a registry-completeness guard that states "No ratchet /
  no baseline" by design and never inspects how a write is performed. It is
  correct on its own axis and left untouched; the right home is
  local/no-adhoc-markdown-parsing.

ADR-2143's Phase 4 already shipped the table-regex and replace-mutation
detectors, so the ADR scopes the remaining gap precisely rather than asking for
that work twice: adhocReplaceMutation keys on a table-or-section regex, and
#4852's pattern is a bold-label field regex — which is why the defect sits in
src/phase.cts, a file the rule does lint, with lint:ci green.

Per docs/adr/README.md lifecycle rule 3, ADR-1372 and ADR-2143 are NOT given
the reciprocal `Subsumed by` back-link here: a Proposed ADR's Subsumes claim is
prospective, so its targets are not marked until ratification. Both back-links
land in the Phase 6 ratification PR. ADR index regenerated.

Refs #4906
Closes #4910

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(#4910): apply review findings — link every ADR cross-reference and state the node-scoping interpretation

Three review passes ran against the ADR: an isolated adversarial fact-check of
every citation, and both axes of /code-review as separate sub-agents.

Standards axis (hard violation of docs/adr/README.md lifecycle rule 2): 14 bare
ADR-1372 / ADR-2143 / ADR-1411 references in body prose. gen-adr-index.cjs does
not catch this — its bare-id check runs only over relation-field values, never
body prose — so a green lint:generated-sync did not clear it. Every bare
cross-reference is now a file link; only the self-reference ADR-4910 remains
bare, which is not a cross-reference.

Spec axis: §5 scopes the parse error to the node, while #4906's criterion reads
"an unparseable shape surfaces could-not-parse with the offending span" with no
document-or-node qualifier. Both readings are faithful to that sentence and they
produce materially different Phase 1 and Phase 4 work. §5 now records the
distributive reading explicitly, names the document-scoped alternative, states
what it would cost (one bad table failing phase list and init.progress alongside
roadmap.analyze), and names what changes if the epic meant the other one. A
silent narrowing became a stated one.

Refs #4906
Closes #4910

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(#4910): make each phase's acceptance a structural property, not a list of fixed issues

Phases 2-5 read as "fixes #4852, #4862, #4499" — a point-fix list with a seam
attached. That is the failure the epic names in its own words: "an
implementation that does that has not closed this epic, even with every symptom
gone and CI green."

New section "What makes a phase done" locks three criteria every phase carries:

- Census -> zero. A phase enumerates every instance of its anti-pattern in the
  tree, publishes the count in its PR, and closes when it is zero. Not "the
  reported ones".
- Deletion, not coexistence. Bespoke implementations are removed, not kept in
  sync beside the seam — including src/roadmap.cts:1196's three-arm
  planCountPattern, which is correct today and still goes, because a correct
  copy of a rule the seam owns is the two-copies-that-agree case.
- Unrepresentable by construction. Each phase ships one property that makes its
  class impossible rather than currently absent: a property over generated
  documents, a type that does not admit the wrong shape, or a drift guard.

The absorbed issues are demoted to fail-first regression evidence. A phase may
not close on those tests alone.

Each phase restated accordingly, with its own census / deletion /
unrepresentable / evidence breakdown.

The six community point-fix PRs and their issues were closed unmerged
(#4762/#4736, #4897/#4837, #4848/#4661, #4610/#4605, #4609/#4606,
#4530/#4499). The ADR now records that as executed rather than pending, which
is what lets census-to-zero be an acceptance criterion at all — a landed point
fix would make the tree look healthier than it is. Phase PRs reference those
six with Refs, since CONTRIBUTING forbids a closing keyword against an
already-closed issue.

Refs #4906
Closes #4910

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: sim <sim@local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

docs/adr/README.md

@@ -292,6 +292,7 @@ Decided in principle, not yet ratified. Do not cite as settled architecture.
 | [ADR-3942](3942-emitted-drift-ack-commit-trailer.md) | The emitted-drift acknowledgment is PR-lifetime data — it belongs in a commit trailer, not the working tree | Proposed | — |
 | [ADR-4629](4629-state-write-intent-beyond-frontmatter.md) | STATE.md write intent beyond frontmatter — bounded, verified writes | Proposed | — |
 | [ADR-4650](4650-path-containment-and-filename-classification-seam.md) | One path-containment predicate and one filename-classification helper | Proposed | — |
+| [ADR-4910](4910-planning-document-seam.md) | Planning documents are read and written through one parse → mutate → serialize seam | Proposed | — |
 
 ### Superseded, Retired, and Legacy