docs(deed): mapping spec family 3 — STATE v1 decision spec (options + recommendation)

1-formats/deed/mappings/state-v1-decision.adoc

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+= Decision spec — `STATE.a2ml` v1 → deed era (family 3)
+Campaign: standards#837 · Frame: link:README.adoc[mappings/README] ·
+Status: **DECISION REQUIRED (owner)** — options + recommendation only;
+no STATE translation is executable until ruled
+
+Unlike families 1/2/4, STATE v1 is not a clean table-mapping problem:
+the file mixes three epistemically different things, and the owner already
+moved to a v2 thin-journal model whose doctrine discards most of v1's
+content by design. A literal translation would encode into the deed era
+the exact content v2 exists to stop tracking.
+
+== 1. What v1 actually contains (rsr-template instance, 2026-02-28)
+
+[cols="2,2,3"]
+|===
+| Section | Content kind | v2 doctrine verdict
+
+| `[metadata] status="active"`, `[position] phase/maturity` | **repo state** (a registry-style claim about today) | KEEP — but it *duplicates* CLADE `[status] phase` (see §3 collision)
+| `[project-context] purpose`, `completion-percentage` | identity-ish prose + a self-scored number | purpose duplicates ECOSYSTEM/CLADE identity; % is derivable from milestone rows (drop-the-derivable applies)
+| `[route-to-mvp]` milestone rows, `[blockers-and-issues]`, `[critical-next-actions]`, `[maintenance-status]` | **journal** (history of the work, narrative next steps) | v2 already says: these live in the journal, not in state — they are entries with dates, not properties of the repo
+|===
+
+== 2. The options on the table
+
+**A. Literal full translation** — every v1 field into a `(state …)` clause
+on `repo-deed`, milestone arrays as repeated `(milestone …)` clauses.
+(+ Zero review needed per repo. − Exactly what the pin-generator trap looks
+like at campaign scale: 100%-and-shipped "Phase 0–2" rows frozen into the
+deed era as if they were present-tense state; contradicts the v2 doctrine
+in the repo the campaign is supposed to serve.)
+
+**B. Extract-the-state, archive-the-journal (RECOMMENDED)** —
+the genuinely-statal fields ([position] phase/maturity) translate onto the
+repo deed **via the CLADE status clause** (deduped, §3); the journal
+sections do NOT translate — v1 files are renamed into an archive surface
+(e.g. `.machine_readable/archive/state-v1.a2ml`) with a tombstone comment,
+and *current* journal entries continue in the v2 journal the owner already
+runs. The deed carries state; the journal carries history; nothing is
+double-tracked.
+(+ Faithful to v2 doctrine. + Kills the double-track hazard in §4 of the
+groundwork doc at the source rather than per-repo. − Needs per-family
+judgement per repo at convert time → slower, but the conformance lane is
+exactly where that slowness is paid once.)
+
+**C. `praxis-deed` home** — rules-shaped? No. STATE does not state what a
+tool does; `repo-deed` is the noun here. Recorded so it does not keep
+re-appearing.
+
+== 3. The collisions this decision must name (found during recon)
+
+* `[metadata] status="active"` (STATE) duplicates `phase="active"` (CLADE).
+  One truth survives: CLADE's `[status]` clause is the registry surface
+  (its enums and lifecycle vocabulary were *ruled on* in #726/#728);
+  STATE's status string dies with the v1 era. The mapping above in B
+  extracts phase/maturity only where they are NOT already covered.
+* `completion-percentage = 95` is computable from the milestone rows it
+  sits above and drifts the moment either side is edited — the v2 doctrine
+  ("discard the derivable") deletes it *by extension*, and this decision
+  spec records that.
+* `maturity` (experimental|alpha|beta|production|lts) has NO clean CLADE
+  home today: it is real state not covered by `phase`. B proposes a
+  one-field addition to the status clause at translate time:
+  `(status … :maturity production)` — symbol, closed set as the comment
+  taxon says. This is the single v1-vocabulary extension this family asks
+  for, deliberately minimal and ruled-on-visible.
+
+== 4. What is executable NOW without a ruling
+
+* A dry-run extractor that classifies every estate STATE file into
+  state/journal/duplicate buckets and emits the proposed per-repo diff
+  WITHOUT writing anything (part of the conformance lane tooling PR).
+  It turns the ruling from an abstract choice into a reviewable artefact:
+  the owner can see exactly what B would do to, say, `rsr-template-repo`.
+
+== 5. Acceptance (once ruled)
+
+* Zero `STATE.a2ml` v1 files remain in any live `.machine_readable/` tree
+  (archive surface excluded, tombstoned).
+* Zero `(:.*-)?status`/`phase` double-tracks: one grep finds each repo's
+  lifecycle claim, in its CLADE clause, verbatim enum.
+* Every milestone row dropped is matched by an archive-file line holding
+  the same text (nothing silently lost — the ledger discipline from the
+  estate-residue-ledger pattern).