T-430T-migrate-corpus-to-aa-nnnn-identifier-shape

Status: closed/done · Impact: high · Complexity: large

Goal

D-0002-entity-identifier-shape fixes the canonical filename/id shape as AA-NNNN-<optional-slug>. The corpus still carries the pre-reshape forms: catalogued entities concatenated (D0001-…, MML68), the 15 T0001-form tasks, 219 date-prefixed tasks (YYYY-MM-DD-<slug>.md, no id), and 19 slug-named backlog items. This task performs the full one-time reshape of every entity to the canonical shape and sweeps every inbound reference, so the corpus matches the decision. Extracted from T-87GH-new-scripts-derive-schema-bound-values §4 so it runs independently of the op-registry / authoring-pipeline substrate — the migration needs only the settled shape, not the new scaffolder.

Today

Location	Role today
docs/planning/{decisions,standards,principles,milestones}/	40 catalogued instances in the concatenated form (D0001-…, S0005-…, P0001-…, M0001-…, MML68); frontmatter id: matches.
docs/planning/tasks/T0001.md … T0015.md	15 tasks already in T<NNNN> id form.
docs/planning/tasks/YYYY-MM-DD-<slug>.md	219 date-prefixed tasks with no id: — the date is the de-facto identifier.
docs/planning/backlog/<slug>.md	19 slug-named backlog items with no id:.
docs/planning/**/*.md, plugin/** prose	Inbound … references in every form ([D-0001-project-structure](/planning/decisions/project-structure/), D0001-slug, [T-0001](/planning/tasks/T-0001/), 2026-05-19-foo, [M-ML68](/planning/milestones/M-ML68/)).
plugin/lib/model/entities/*/schema.json	The wikilink-shaped patterns (id, related, depends_on, parent_key) admit the concatenated form, not the dashed AA-NNNN.
docs/index.md	Generated front-door; transcludes entities by their current names.

Proposed

Every entity is renamed to AA-NNNN-<slug> per D-0002-entity-identifier-shape — the abbreviation registry and numbering style live there and in D-ORMG-data-model; this task consumes them. Two cases:

• Id-bearing entities (catalogued D/S/P/M, the 15 T0001-form tasks): insert the abbreviation dash, id preserved (D0001-slug → D-0001-slug; MML68 → M-ML68; T0001 → T-0001).
• Id-less entities (219 date-prefixed tasks, 19 backlog items): mint a new id per the type’s numbering style in D0002 (T/B are base-36), collision-checked against the existing id space, and keep the existing slug for readability (2026-05-19-foo → T-<id>-foo). The created: date is preserved in frontmatter; it simply leaves the filename.

Frontmatter id: is set/updated to the dashed form on every file, every inbound wikilink is swept in lockstep, the entity schema.json patterns are widened to the canonical shape, and the generated index + audit come back clean.

Approach

Delivered as a deterministic, idempotent migration script (plugin/scripts/migrate_identifier_shape.ts) with a --dry-run that prints the full rename map + wikilink-sweep plan before any write. Run on a branch; apply only after the dry-run is reviewed.

1. Discover instances by scoped location (docs/planning/<plural>/), not by guessing names; classify id-bearing vs id-less.
2. Build the rename map. Id-bearing: insert the dash. Id-less: mint a collision-free base-36 id per D0002, keep the slug. Record old→new for both the filename and every wikilink form the old name takes.
3. Widen schema.json patterns (id, related, depends_on, parent_key, milestone id) to accept AA-NNNN[.N][-slug].
4. Apply: git mv each file, set frontmatter id:, then sweep every old → new across docs/ and plugin/ prose.
5. Regenerate docs/index.md via /sdlc:index.
6. Verify: audit_entities.ts + /project-check clean; zero broken wikilinks; no id↔filename mismatch; no duplicate ids.

Files to touch

Location	Kind	Change
plugin/scripts/migrate_identifier_shape.ts	new	The deterministic migration (dry-run + apply)
docs/planning/{decisions,standards,principles,milestones,tasks,backlog}/*	modify	git mv to AA-NNNN-<slug>; set/update frontmatter id:
docs/planning/**/*.md, plugin/** prose	modify	Sweep inbound wikilinks to the dashed names
plugin/lib/model/entities/*/schema.json	modify	Widen id/related/depends_on/parent_key patterns to AA-NNNN
docs/index.md	modify	Regenerate from the renamed corpus

Acceptance criteria

• AC-1: Every entity instance filename matches AA-NNNN[-slug].md per D-0002-entity-identifier-shape (catalogued + all 234 tasks + 19 backlog).
• AC-2: Each file’s frontmatter id: equals its dashed filename id (no id↔filename mismatch); id-less entities gained a minted, unique id.
• AC-3: No broken … wikilink anywhere under docs/ or plugin/ after the sweep.
• AC-4: audit_entities.ts reports no new drift attributable to the rename; /project-check passes.
• AC-5: docs/index.md regenerates clean and every ^summary transclusion resolves.
• AC-6: The entity schema.json wikilink patterns accept the dashed shape and reject the old concatenated form.
• AC-7: migrate_identifier_shape.ts --dry-run prints the full rename map and is a no-op; a second apply run is idempotent (zero further renames).

Out of scope

• Proto-instances of types whose schema has not shipped (cap-*, drv-*, prod-*, …) — they reshape when their type ships.
• The legacy plugin/entities/ tree — M-ML68 handles the legacy surface.
• The authoring pipeline / scaffolder rewrite and the per-type id minter for new entities — T-87GH-new-scripts-derive-schema-bound-values (this task mints ids only for the one-time migration).

Dependencies

• D-0002-entity-identifier-shape settles the target shape (accepted). No hard task dependency — the migration consumes only the shape, not the substrate.

Discovery context

Extracted 2026-06-03 from T-87GH-new-scripts-derive-schema-bound-values §4 so the corpus reshape can run independently of the substrate/pipeline work. Scope set to the full corpus (catalogued + Tasks + Backlog) by user decision 2026-06-03, overriding D0002’s interim task-migration deferral. Supersedes T-0002 (the prior “Option E” migration, closed). Belongs under M-ML68.

---

← Back to Tasks