# Decision migration map (legacy heading → active record / archive)

The full corpus (`docs/decisions.md` and the `docs/decisions/*.md` topic files) was **fully migrated
to the lifecycle schema on 2026-07-21 (#520/#521)**: `PYTHONPATH=. python3 scripts/decisions_validate.py`
reports 0 `legacy-unmigrated` headings, and the catalog (`docs/decisions/README.md`, built by
`scripts/build_decisions_catalog.py`) lists 108 active records. Every active decision heading now
carries a metadata block (`key:`/`status:`/`since:`/`supersedes:`/`superseded-by:`). Most headings were
migrated **in place** — the heading text is unchanged, only the metadata block was added — so their key
is discoverable via the catalog or `rg '^\`key:\`' docs/decisions/`, not via this file. This table
records only the **non-trivial** mappings produced during the migration: splits, supersessions, and
prose-only reversal notes. It is not, and was never meant to be, a 1:1 index of all 108 records.

| Legacy heading | Key | Status | Location |
| --- | --- | --- | --- |
| 2026-07-17 — No persistent compiler servers in CI; every `services:` container gets an explicit cap; #390's small-lane move reversed (#406) | `ci.runner-placement` | active | `docs/decisions.md` |
| 2026-07-19 — CI `test` job reports a sampled true peak-anon, not cache-inflated `memory.peak` (#412) | `ci.peak-anon-measurement` | active | `docs/decisions.md` |
| 2026-07-12 — decisions.md is append-only, enforced; root-screenshot guard (#303 H9/H3) — heading kept identical to the pre-split original (only the body/metadata were split) so the lifecycle validator's relocation check matches it | `docs.append-only-guard` | superseded (`superseded-by: docs.decision-lifecycle@2026-07-21`) | `docs/decisions/archive/release-ci-governance.md` |
| 2026-07-12 — Root-screenshot guard: pre-commit refuses root-level `*.png` (#303 H3) — split from the original H9/H3 bundle | `ci.root-screenshot-guard` | active | `docs/decisions/release-ci-governance.md` |
| 2026-07-21 — Decision records carry a lifecycle schema, validated by a script; append-only-by-diff is retired (#521) | `docs.decision-lifecycle` | active (`supersedes: docs.append-only-guard@2026-07-12`) | `docs/decisions.md` |
| 2026-07-11 — Queue state lives in the pinned Gitea tracker (#237), not in the handoff file | `docs.queue-state-gitea-tracker` | superseded (`superseded-by: startup.parallel-orientation@2026-07-21`) | `docs/decisions/archive/startup.md` |
| 2026-07-21 — Parallel orientation + selection is the startup protocol; #237 retired (#520) | `startup.parallel-orientation` | active (`supersedes: docs.queue-state-gitea-tracker@2026-07-11`) | `docs/decisions.md` |

## Migration conventions

A legacy `##` entry that bundles an active sub-decision with a superseded/retired one is SPLIT during
migration — the superseded half moves to `archive/`, the active half becomes its own `status: active`
record in the active files. Never relocate an active decision to `archive/`. First applied to the
#303 H9/H3 bundle (below): H9 (docs.decisions.md append-only) is genuinely superseded and archived as
`docs.append-only-guard`; H3 (the root-screenshot pre-commit guard) is independent and still active, so
it was split out into its own active record, `ci.root-screenshot-guard`, in
`docs/decisions/release-ci-governance.md` rather than being carried into archive with its superseded
sibling.

## Notes on records considered but NOT given a standalone entry

- **#390 (small-lane move for `api-docs`/`format`).** Investigated whether #390's reversal (described
  in #406's prose, point 3: "#390's `small`-lane move ... reversed") ever existed as its own `##`
  record. It did not — grep for `#390` across `docs/decisions.md` and `docs/decisions/*.md` finds it
  only inside #406's own body text (and one other unrelated mention of #390's apt-ffmpeg estimate,
  also inside #406). #390 was **prose-only**: no separate heading, so nothing to mark `superseded` or
  move to archive. `ci.runner-placement` (#406) therefore carries `supersedes: none`; the reversal is
  recorded only in its `**Signals:**` line (`#390 (prose-reversed, no standalone record)`) and in this
  note.
- **#411 (the earlier `memory.peak`-headline measurement).** Investigated the "#411 obsolescence" the
  brief references. #411 is mentioned twice in `docs/decisions.md`, both inside #412's own body
  ("the `test` job's memory instrument (added in #411) now reports ..." and "the older #411 probe
  ... is superseded"). Like #390, #411 never had its own `##` heading — its "decision" was
  narrated retroactively inside #406 (the "Measurement is now continuous" paragraph, which describes
  the instrument #411 actually shipped) and explicitly marked obsolete inside #412's own prose. Since
  there is no standalone #411 record, there is nothing to move to `archive/`; `ci.peak-anon-measurement`
  (#412) — the record that supersedes #411's approach — carries `supersedes: none` and documents the
  prose reversal in its `**Signals:**` line. The governed surface (CI memory measurement) still exists
  and is very much active, so this is a straightforward **supersession of an unnamed predecessor**, not
  a retirement — there's no case to make for `retired` here since the surface it measures is live.

## Still open

- **DONE**: `docs.queue-state-gitea-tracker` (#237) — superseded by `startup.parallel-orientation`
  (2026-07-21, #520), archived at `docs/decisions/archive/startup.md`. See the table above.
- Nothing else is open from this migration — the corpus is fully migrated (0 legacy-unmigrated). Future
  new decisions are simply added directly in the lifecycle schema; there is no further migration pass
  to track here.