diff --git a/1-formats/deed/mappings/state-v1-decision.adoc b/1-formats/deed/mappings/state-v1-decision.adoc new file mode 100644 index 000000000..abd5be74a --- /dev/null +++ b/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).