wdi-method 0.6.30 → 0.6.31

package/kit/skills/wdi-upgrade/SKILL.md

@@ -1,215 +1,234 @@
----
-name: wdi-upgrade
-description: Use right after `wdi-method update` moved this repo to a newer method version. Finds every document and registry file still in the OLD shape, re-homes their content into the new one — registry rows out of prose, pointers where copies were, the rendered trees born — and verifies green. Runs once per version jump; safe to re-run.
----
-
-# WDI Upgrade
-
-`wdi-method update` does the mechanical half of a version jump: it overwrites the kit, renames files whose
-content needs no judgment, seeds what is new, prunes what is retired. It stops exactly where a decision
-about **content** begins — which PRD an `FR` belongs to, whether a sentence in the old brief was an
-assumption or a constraint. Those are this skill's half.
-
-**This skill's content is `.what/` and `.how/`** — the corpus a human reads. It does NOT cover
-`.control/memlog/` or a registry row: an autopilot ledger's filename is `update`'s own mechanical rename
-(the same way `waves.yaml` became `specs.yaml`), a stale mandate setting is a printed warning at `update`
-time because overwriting it would be overwriting a value the owner already chose, and a ledger's internal
-shape is healed by `wdi-autopilot` itself on its next run, because only it can read git and the registry to
-know where that run actually stands. Route those three there; this skill's report would have nothing to say
-about any of them.
-
-**This is the one skill allowed to edit `brief.md`, `prd.md`, an SRS, an SDD, or a C4 file directly.**
-Every other skill is forbidden, because a hand edit makes the memlog lie about how the document was
-produced. An upgrade produces nothing: it moves sentences that already exist into the home the new
-version gives them, word for word. The memlog stays true, and this skill's report is the record.
-
-## Inputs
-
-| Source | What it answers |
-|---|---|
-| `.control/wdi-method.yaml` | The version now installed — the shape everything below MUST end in |
-| The `update` run's own output | The `upgrade` line lists what it detected as pending; start there |
-| `.control/registry/` | What is already a row, so nothing is landed twice |
-| `.what/_product-brief/brief.md` · `.what/_prd/*/prd.md` | The two documents whose shape changed most |
-| `.what/<pc>/SRS-<pc>.md` · `.how/<pc>/SDD-<pc>.md` · `.how/_platform/c4-l2-containers.md` | The three that used to carry a copy of a registry table |
-| `.constitution/method/document/templates/` | The target shape of every document above |
-
-## Step 1 — Detect, and show the list before touching anything
-
-Probe each item below; a probe is a file or heading that exists only in the old shape. List every hit
-to the owner as a checklist, in the order below — it is a dependency order, and doing a later item
-before an earlier one lands content in a file that the earlier item is about to change.
-
-| # | Probe | Old shape | New home |
-|---|---|---|---|
-| 1 | `.control/registry/requirements.yaml` exists | one file for `BG` · `CAP` · `FR` · `NFR` · `UJ` | `goals.yaml` (`BG`) · `requirements-<slug>.yaml` per PRD (`CAP` · `FR` · `NFR` · `UJ`) |
-| 2 | a spec with a `W<n>` id, or carrying `epics:` / `stories:`, that is **not `closed`** | pre-rename plan | flattened in place — **this skill's**, and § *The pre-rename plan* below is the mapping. A `closed` spec is left alone: `Corpus.tickets()` reads it correctly and its ticket files are already allowed to be gone |
-| 3 | `brief.md` has `## Executive Summary`, `## Vision`, `## Assumptions`, or `## Prerequisites`; or `## Goals` lists `BG-` statements | 14-section brief | 8 sections: `Why` merges Summary + Vision; Goals is a pointer, its rows in `goals.yaml`; Assumptions → `questions/assumptions.md`; Prerequisites → `questions/external.md` |
-| 4 | any `prd.md` has a section **named** Document Purpose, Glossary, Non-Goals, Open Questions, or Assumptions Index — under whatever number that kit gave it — or `**Proof of done:**` under a feature | 12-section PRD with `FR` blocks | 7 sections; `FR`/`NFR` text → `requirements-<slug>.yaml`, the PRD keeps `Realizes:` ids; Glossary → `product-glossary.md`; §8/§9 → `questions/`; §1 becomes a delta |
-| 5 | any `SRS-<pc>.md` `## UC Catalogue` has `\| UC-` rows | catalogue copied from `usecases.yaml` | one pointer line; the rows live in `usecases.yaml` |
-| 6 | any `SDD-<pc>.md` `## Inherited Constraints` has a `Quoted rule` column, or `> ` blockquote lines under an `**AD-N — …**` heading, or the sentence `Quoted verbatim from` | `AD-N` text copied from the spine, in either of the two shapes SDDs were written in | ids only; the rendered SDD shows the text |
-| 7 | `c4-l2-containers.md` has a `\| Container \| Product Components living in it \|` table | matrix copied from `components.yaml` | one pointer line |
-| 8 | `.control/generated/brief.md`, `blueprint.md`, or `prd-*.md` exist | human pages in the machine folder | `.what-rendered/` · `.how-rendered/` — `render` clears the old ones |
-| 9 | `.what-rendered/` or `.how-rendered/` absent | no reader's tree yet | born by `render` |
-| 10 | any `.md` outside `.constitution/` cites `.control/generated/brief.md`, `blueprint.md`, or `prd-<slug>.md` | a pointer at a page that moved | `.what-rendered/_product-brief/brief.md` · `.how-rendered/blueprint.md` · `.what-rendered/_prd/<slug>/prd.md` — `cites-resolve` fails until it is repointed |
-| 11 | `docs/agents/issue-tracker.md` does not contain the words `seeded by ``wdi-method``` | the engines' config as `/setup-matt-pocock-skills` wrote it: everything in `.scratch/` with no registry behind it, `specs.yaml` never mentioned | the method's own answer. **`npx wdi-method engines --fix`** rewrites it and keeps the old text as `issue-tracker.md.bak`. Two of four live repos still had upstream's, which is why their tickets landed wherever the engine guessed |
-| 12 | a spec that is **not `closed`** has a `spec_folder` outside `.scratch/`, or a leaf that does not begin with its own id | spec folders under `_bmad-output/specs/`, leaf named freely — four repos wrote it four ways, one of them all four inside itself | `.scratch/<spec-id>-<slug>/`. Move the directory, rewrite the `spec_folder` row, then repoint every cite — `cites-resolve` is red until you do, and it is how you find them all. **A `closed` spec is left alone**: its folder is a record, moving it churns finished work, and its ticket files are already allowed to be gone |
-| 13 | `validate.py` reports `refs-resolve` on a `BG-` · `CAP-` · `FR-` · `NFR-` · `UC-` id — the finding itself is the probe | the row was **deleted** when the product stopped promising it, leaving every `DEC-` that served it pointing at nothing | the row comes BACK, marked `status: withdrawn` with `withdrawn_by` naming the decision that took it. Recover its text from git rather than retyping it — `git log -S"id: CAP-8" -- .control/registry/` finds the commit that held it. You MUST NOT edit the references instead: a `DEC-` records what happened, and it did serve that promise at the time. `corpus-guide.md` § *A withdrawn promise STAYS in the registry* owns the rule, `wdi-product` the procedure |
-| 14 | a `type: mandate` `DEC-` at `status: superseded` that some other `DEC-` names in its `accepted_by`, and neither side of the supersession is written | the mandate was retired — a setting changed, or the run ended — and nothing recorded which decision replaced it. Before 0.6.16 the validator read that status as present tense and turned every decision the run had taken red instead, with no legal repair | `superseded_by: DEC-<replacement>` on the retired mandate's row and `supersedes:` back on the replacement. That date is what revoked the delegation, and it is the one edit an `applied` decision allows. If nothing replaced it, the decision that ENDED the run is the replacement — open it through `wdi-decision`. You MUST NOT repair this by editing the decisions taken under the mandate: they were accepted while it stood |
-
-Items 11 and 12 are the engines' half of a version jump, and they come FIRST when both are hit:
-item 11 writes where a spec's files belong, item 12 moves them there. Doing 12 first means moving
-folders to a location the engines have not been told about, and the next `to-tickets` writes to the old
-one anyway.
-
-Anything not in the list is not this skill's. A brief that already has `## Why` is done; skip it.
-
-## Step 2 — Registry first
-
-**1 — the requirement split.** A row written under an older kit carries `text:` where a newer one
-carries `title:`; both are the short label, the renderer and `timeline.py` read either, and one MUST
-NOT be copied into the other — that is two homes for one fact. Which PRD a row belongs to is read from
-the rows before it is read from the prose. A `CAP` or `UJ` with a `prd:` field goes to `requirements-<that slug>.yaml`; an `FR`
-follows its `capability:` to that CAP's file; an `NFR` follows its `component:` to the PRD whose CAPs
-own that component — a `BG` is product-level and never decides an NFR's home on its own, so `goal:` is
-only a tie-breaker when that component's CAPs span two PRDs. On a product with exactly **one** PRD every row belongs to that
-PRD by construction — write them all to its file and skip the citation scan. Otherwise, only a row with
-none of those fields falls back to the PRD whose prose cites its id — and an id cited by **two** PRDs
-is reported, not placed. The citation scan still runs on every row as a cross-check: a row whose
-structural home and citing PRD disagree is reported with both names. Write the row, unchanged, into
-its file; `goals:` rows go to `goals.yaml`. A sentence moved into a YAML value keeps its punctuation
-and its markup: when it holds `: ` or `#` or starts with a quote, wrap the value in double quotes or a
-`>-` block — never trade a colon for a dash or strip `**` and backticks to make it a plain scalar. A row with no home is reported by id, not guessed: the
-owner names it. When every row has moved, delete `requirements.yaml`; `id-allocated-once` fails if a
-row was copied instead of moved.
-
-**2 — the pre-rename plan.** A spec still shaped `epics: → stories:` is flattened into the one
-`tickets:` list the validator reads. Every part of this is a mapping; nothing here is a judgment, and
-nothing is invented:
-
-| Old | New |
-|---|---|
-| `waves:` as the file's top-level key | `specs:`. The rows below it do not otherwise change shape from this rename alone |
-| the spec's `W<n>` id | **unchanged.** It is a retired alias, and every memlog, `DEC-`, report and RTM row that names it MUST keep resolving. Renaming it to `SPEC-<n>` is the one thing this step MUST NOT do |
-| `epics:` → `stories:` nesting | one flat `tickets:` list, in the order the stories appear, epic by epic. The `epics` level is repealed: it grouped rows and bought nothing |
-| a story's own id (`"1"`, `"1-2"`) | `<spec-id>-<NN>`, renumbered from `01` in dependency order — `W3-01`, `W3-02`. A story id only ever promised uniqueness inside one epic, and this method keys tickets globally |
-| `depends_on: ["1-1"]` on a story | `blocked_by: [W3-01]` — the same edge, the new key, pointing at the new id |
-| `{spec_folder}/stories/1-2-<slug>.md` | `{spec_folder}/issues/<NN>-<slug>.md`, the `<NN>` matching the ticket's new id. `git mv`, so the file's history follows it |
-| a story's `touches:` | kept as `touches:`. A story never carried `component:`, and this step MUST NOT invent one — `wdi-init` owns that field |
-
-Two things stay untouched even here. The **status** of each ticket is read from its file and MUST NOT
-be copied into `specs.yaml` — `ticket-status-one-home` is what refuses that. And a `closed` spec is
-skipped whole: `validate.py` already flattens it in memory on every run, so rewriting the file changes
-no reading and only churns the record of finished work.
-
-Run `validate.py --check`. Green here means the registry is whole before any document starts pointing
-at it.
-
-## Step 3 — Documents, oldest gate first
-
-**3 — brief.** Merge `## Executive Summary` and `## Vision` into one `## Why`, keeping every sentence
-that says something the other did not. Each `BG-N` statement under `## Goals` MUST already be a row in
-`goals.yaml` (Step 2); replace the list with the pointer line from the template. Each `## Assumptions`
-item becomes a row in `.control/questions/assumptions.md` with `Whose: owner`; each `## Prerequisites`
-item a row in `external.md` — **after** checking that no `OQ-` row already states it, because a brief
-written under an earlier kit usually landed them already and a second row is a copy. A prerequisite
-the brief itself marks satisfied is dropped, not landed as open. A `questions/` table written before
-the `Whose` column existed (`| id | Assumption | Cost if wrong | Taken | By |`) gets the column added —
-header and separator, and an empty cell on every existing row, which the validator counts as
-`unstated`, which is what they are. The rows this skill lands say `owner`. `Cost if wrong` is `—` when
-the source never stated one; it is not invented. An open question the source never marked blocking is
-filed in `assumptions.md`, as the template's three tests say. Delete both sections, and say how many
-items were already rows. Check `## Success Criteria` names one measurable
-figure — if it does not, that is a finding for the owner, not a sentence for this skill to invent.
-
-**4 — each PRD.** Sections are matched **by name, never by number**: the numbers moved between kits
-(one kit numbers Non-Goals §5 and Open Questions §8; an older one numbers Non-Goals §7, MVP Scope §8,
-Open Questions §10), so a step that says "delete §8" deletes MVP Scope on the wrong corpus. Delete
-`Document Purpose`. Every `Glossary` term not yet in `.control/product-glossary.md` is added there,
-verbatim; then delete `Glossary`. Every `Non-Goals` item MUST already be in the brief's Scope Out or
-this PRD's `MVP Scope → Out of Scope` — if neither holds it, add it to the one it belongs to; then
-delete `Non-Goals`. Every `Open Questions` and `Assumptions Index` item becomes a `questions/` row
-(after the same already-a-row check as the brief's); delete both.
-Under each feature, every `FR` block is folded into its row in `requirements-<slug>.yaml` (Step 2)
-before the block goes: the block's description paragraph — the prose between the `#### FR-N` heading
-and the first `**…:**` label — becomes the row's `statement:` when the row has none (the row's `title`
-stays). **This is the one move with no validator behind it**, so count it: blocks with a paragraph
-versus rows that now carry `statement:` MUST match, and Step 5 reports both numbers. A run that deletes
-the blocks and lands zero statements has thrown the requirement's own sentence away; its `**Consequences (testable):**` bullets move verbatim to
-`addendum.md` under `## Technical how — testable consequences per FR`, appended **after** the sections
-already there, one `### FR-N — title` each,
-because `prd-guide.md` repealed the double proof of done and that is where the technical restatement
-lives now; its `**Proof of done:**` is compared with the row's `proof` — when they differ, the
-**registry is kept** (it is the declared SSOT), the PRD's is dropped, and both texts are reported side
-by side for the owner, never merged. Then the block becomes `**Realizes:** FR-a, FR-b, NFR-c`, and a
-`**Functional Requirements:**` label left with nothing under it is deleted — the rendered page rebuilds
-the blocks from the rows. When the deletions are done, **put the surviving `##` sections in the
-template's order and renumber them** — moving a whole section is a move, not an edit, and a file whose
-`## 6` sits above its `## 4` tells the AI reader the numbers lie. The order — 1 Why This Initiative · 2 Target User · 3 Features · 4 MVP Scope · 5 Success
-Metrics · 6 Cross-Cutting NFRs · 7 Constraints and Guardrails — and the `###` beneath them to match
-(`### 8.2` → `### 4.2`). Numbers are not sentences; leaving `## 4. Features` beside `## 8. MVP Scope`
-tells the next reader two sections went missing. A `UJ-N` the prose names that has no row in any requirement file is
-not given one — it is marked with an HTML comment where it stands and reported; `wdi-product`
-allocates ids. A moved sentence that cites a section number (`§ 8`) of a section this step deletes
-keeps the number — it is reported as wording for the owner, not repointed, because its new home is a
-judgment. `## 1. Vision` becomes `## 1. Why This Initiative`: delete only the sentences
-that also appear, word for word, in the brief's `Why`; what remains is left whole under an HTML comment
-saying the new shape wants a delta, because deciding which paraphrases are copies is the owner's. On a
-single-initiative product that is one line pointing at the brief — write it and say so.
-
-**5 — each SRS.** Every `| UC-` row MUST already be in `usecases.yaml` with the same `critical`. A row
-missing there is landed first. Then the table becomes the template's pointer line.
-
-**6 — each SDD.** In `## Inherited Constraints`, drop the `Quoted rule` column; keep `AD` and `How it
-lands here`. In the blockquote shape, drop the `> ` lines and the `Quoted verbatim from` sentence; keep
-the `**AD-N — title**` heading and the landing prose under it, each heading on its own line. An `AD-N`
-cited here that is not in the spine is a finding.
-
-**7 — C4 L2.** Every PC listed in the table MUST have that container in its `containers:`. Then the
-table becomes the pointer line.
-
-**8 — pointers at the moved pages.** Every `.md` that cites `.control/generated/brief.md`,
-`blueprint.md`, or `prd-<slug>.md` **and that `cites-resolve` reads** is repointed to the new path — a
-path substitution, nothing else in the sentence changes. That includes a product's own scratch and
-issue notes. It excludes what the validator excludes: `.control/memlog/`, `.control/decisions/`,
-`.control/reports/`, `questions/answered.md`, and `_bmad-output/` — those describe the past, and a
-path rewritten there falsifies a record; the installer's probe skips them for the same reason.
-
-## Step 4 — Render, then validate
-
-```bash
-uv run .constitution/method/scripts/validate.py --generate
-```
-
-This writes every reader's page into `.what-rendered/` and `.how-rendered/`, and clears the human pages
-that used to sit in `.control/generated/`. Then `--check` MUST be green. Every finding at this point is
-either a row that moved wrong in Step 2 or a pointer that points at nothing — both are this skill's to
-fix before it reports done.
-
-## Step 5 — Report, and commit once
-
-What moved, file by file · what was landed into the registry, by id · what could not be placed and
-needs the owner · the rendered pages now waiting to be read, one per gate · validators green. Then
-**one** commit: `chore(method): upgrade <from> → <to>`. Not one per document — the upgrade is one
-event.
-
-## Rules
-
-- You MUST NOT change a sentence while moving it. Wording that reads wrong in its new home is a
-  finding for the owning skill, later.
-- You MUST NOT invent a home. An `FR` no PRD cites, a Non-Goal neither boundary holds, an `AD-N` not
-  in the spine — each is reported by id and left where it was.
-- You MUST NOT write your findings into the corpus. A registry file carries rows and nothing about
-  the upgrade that produced them; a gap in this skill goes in the Step 5 report. The one exception is
-  the HTML comment the steps above name, placed where the owner will read the document.
-- You MUST NOT re-cut `specs.yaml`. That is `wdi-build`'s, where a human can see it.
-- You MUST NOT touch `.control/decisions/` or `.control/reports/`. A frozen `DEC-` that cites `V26` or
-  `W3` is history; the alias rule in `corpus-guide.md` covers it.
-- Re-running on an upgraded repo MUST find nothing and say so. Every probe in Step 1 is idempotent.
-
-## Output
-
-The Step 1 checklist with each item marked done · skipped (already new shape) · left for the owner, with
-the id list for the last · the registry rows landed · **statements landed / FR blocks that had a
-paragraph** · consequences moved · `questions/` rows added and rows found already present · proof-of-done
-divergences, both texts · the path of every rendered page · the validator result · the commit.
+---
+name: wdi-upgrade
+description: Use right after `wdi-method update` moved this repo to a newer method version. Finds every document and registry file still in the OLD shape, re-homes their content into the new one — registry rows out of prose, pointers where copies were, the rendered trees born — and verifies green. Runs once per version jump; safe to re-run.
+---
+
+# WDI Upgrade
+
+`wdi-method update` does the mechanical half of a version jump: it overwrites the kit, renames files whose
+content needs no judgment, seeds what is new, prunes what is retired. It stops exactly where a decision
+about **content** begins — which PRD an `FR` belongs to, whether a sentence in the old brief was an
+assumption or a constraint. Those are this skill's half.
+
+**This skill's content is `.what/` and `.how/`** — the corpus a human reads. It does NOT cover
+`.control/memlog/` or a registry row: an autopilot ledger's filename is `update`'s own mechanical rename
+(the same way `waves.yaml` became `specs.yaml`), a stale mandate setting is a printed warning at `update`
+time because overwriting it would be overwriting a value the owner already chose, and a ledger's internal
+shape is healed by `wdi-autopilot` itself on its next run, because only it can read git and the registry to
+know where that run actually stands. Route those three there; this skill's report would have nothing to say
+about any of them.
+
+**This is the one skill allowed to edit `brief.md`, `prd.md`, an SRS, an SDD, or a C4 file directly.**
+Every other skill is forbidden, because a hand edit makes the memlog lie about how the document was
+produced. An upgrade produces nothing: it moves sentences that already exist into the home the new
+version gives them, word for word. The memlog stays true, and this skill's report is the record.
+
+## Inputs
+
+| Source | What it answers |
+|---|---|
+| `.control/wdi-method.yaml` | The version now installed — the shape everything below MUST end in |
+| `upgrade_pending` in `.control/wdi-method.yaml` | What `update` detected as pending, numbered by the rows of Step 1; start there. `npx wdi-method upgrade-check` re-probes it at any time |
+| `.control/registry/` | What is already a row, so nothing is landed twice |
+| `.what/_product-brief/brief.md` · `.what/_prd/*/prd.md` | The two documents whose shape changed most |
+| `.what/<pc>/SRS-<pc>.md` · `.how/<pc>/SDD-<pc>.md` · `.how/_platform/c4-l2-containers.md` | The three that used to carry a copy of a registry table |
+| `.constitution/method/document/templates/` | The target shape of every document above |
+
+## Step 1 — Detect, and show the list before touching anything
+
+Probe each item below; a probe is a file or heading that exists only in the old shape. List every hit
+to the owner as a checklist, in the order below — it is a dependency order, and doing a later item
+before an earlier one lands content in a file that the earlier item is about to change.
+
+| # | Probe | Old shape | New home |
+|---|---|---|---|
+| 1 | `.control/registry/requirements.yaml` exists | one file for `BG` · `CAP` · `FR` · `NFR` · `UJ` | `goals.yaml` (`BG`) · `requirements-<slug>.yaml` per PRD (`CAP` · `FR` · `NFR` · `UJ`) |
+| 2 | a spec with a `W<n>` id, or carrying `epics:` / `stories:`, that is **not `closed`** | pre-rename plan | flattened in place — **this skill's**, and § *The pre-rename plan* below is the mapping. A `closed` spec is left alone: `Corpus.tickets()` reads it correctly and its ticket files are already allowed to be gone |
+| 3 | `brief.md` has `## Executive Summary`, `## Vision`, `## Assumptions`, or `## Prerequisites`; or `## Goals` lists `BG-` statements | 14-section brief | 8 sections: `Why` merges Summary + Vision; Goals is a pointer, its rows in `goals.yaml`; Assumptions → `questions/assumptions.md`; Prerequisites → `questions/external.md` |
+| 4 | any `prd.md` has a section **named** Document Purpose, Glossary, Non-Goals, Open Questions, or Assumptions Index — under whatever number that kit gave it — or `**Proof of done:**` under a feature | 12-section PRD with `FR` blocks | 7 sections; `FR`/`NFR` text → `requirements-<slug>.yaml`, the PRD keeps `Realizes:` ids; Glossary → `product-glossary.md`; §8/§9 → `questions/`; §1 becomes a delta |
+| 5 | any `SRS-<pc>.md` `## UC Catalogue` has `\| UC-` rows | catalogue copied from `usecases.yaml` | one pointer line; the rows live in `usecases.yaml` |
+| 6 | any `SDD-<pc>.md` `## Inherited Constraints` has a `Quoted rule` column, or `> ` blockquote lines under an `**AD-N — …**` heading, or the sentence `Quoted verbatim from` | `AD-N` text copied from the spine, in either of the two shapes SDDs were written in | ids only; the rendered SDD shows the text |
+| 7 | `c4-l2-containers.md` has a `\| Container \| Product Components living in it \|` table | matrix copied from `components.yaml` | one pointer line |
+| 8 | `.control/generated/brief.md`, `blueprint.md`, or `prd-*.md` exist | human pages in the machine folder | `.what-rendered/` · `.how-rendered/` — `render` clears the old ones |
+| 9 | `.what-rendered/` or `.how-rendered/` absent | no reader's tree yet | born by `render` |
+| 10 | any `.md` outside `.constitution/` cites `.control/generated/brief.md`, `blueprint.md`, or `prd-<slug>.md` | a pointer at a page that moved | `.what-rendered/_product-brief/brief.md` · `.how-rendered/blueprint.md` · `.what-rendered/_prd/<slug>/prd.md` — `cites-resolve` fails until it is repointed |
+| 11 | `docs/agents/issue-tracker.md` does not contain the words `seeded by ``wdi-method``` | the engines' config as `/setup-matt-pocock-skills` wrote it: everything in `.scratch/` with no registry behind it, `specs.yaml` never mentioned | the method's own answer. **`npx wdi-method engines --fix`** rewrites it and keeps the old text as `issue-tracker.md.bak`. Two of four live repos still had upstream's, which is why their tickets landed wherever the engine guessed |
+| 12 | a spec that is **not `closed`** has a `spec_folder` outside `.scratch/`, or a leaf that does not begin with its own id | spec folders under `_bmad-output/specs/`, leaf named freely — four repos wrote it four ways, one of them all four inside itself | `.scratch/<spec-id>-<slug>/`. Move the directory, rewrite the `spec_folder` row, then repoint every cite — `cites-resolve` is red until you do, and it is how you find them all. **A `closed` spec is left alone**: its folder is a record, moving it churns finished work, and its ticket files are already allowed to be gone |
+| 13 | **validator** — `validate.py` reports `refs-resolve` on a `BG-` · `CAP-` · `FR-` · `NFR-` · `UC-` id — the finding itself is the probe | the row was **deleted** when the product stopped promising it, leaving every `DEC-` that served it pointing at nothing | the row comes BACK, marked `status: withdrawn` with `withdrawn_by` naming the decision that took it. Recover its text from git rather than retyping it — `git log -S"id: CAP-8" -- .control/registry/` finds the commit that held it. You MUST NOT edit the references instead: a `DEC-` records what happened, and it did serve that promise at the time. `corpus-guide.md` § *A withdrawn promise STAYS in the registry* owns the rule, `wdi-product` the procedure |
+| 14 | **validator** — `mandate-accept` reports a `type: mandate` `DEC-` at `status: superseded` that some other `DEC-` names in its `accepted_by`, and neither side of the supersession is written | the mandate was retired — a setting changed, or the run ended — and nothing recorded which decision replaced it. Before 0.6.16 the validator read that status as present tense and turned every decision the run had taken red instead, with no legal repair | `superseded_by: DEC-<replacement>` on the retired mandate's row and `supersedes:` back on the replacement. That date is what revoked the delegation, and it is the one edit an `applied` decision allows. If nothing replaced it, the decision that ENDED the run is the replacement — open it through `wdi-decision`. You MUST NOT repair this by editing the decisions taken under the mandate: they were accepted while it stood |
+| 15 | `.how/_platform/design-system.md` has a section named Foundation, Information architecture, Voice and Tone, Flow map, or Cross-component behaviour | cross-component EXPERIENCE parked in the product's design system, because until `.what/experience.md` existed it had no home | `.what/experience.md`, section by section and word for word — the split is `ux-guide.md` § *Product level*. What stays in `design-system.md` is build: tokens, base elements, state patterns, interaction primitives, the surfaces that are not screens. A section that holds both is split at the sentence, by the redesign test |
+| 16 | a file in `.what/` or `.how/` cites `_bmad-output/ux/**/DESIGN.md`, `EXPERIENCE.md`, or `design-system.md` | the corpus pointing back at the UX run after it landed — a behaviour reference to the run, or a *landed from* line at the top of a landed document | the cite names the landed copy instead; a *landed from* line becomes the landed document's frontmatter `landed_from` (item 18). Reported only once components exist — before that the run is the only copy. `ux-landed` is red until every one is gone |
+| 17 | a container in `components.yaml` whose `repo:` is filled and whose id still has a heading in the code map, or `repo:` on a `built: false` container. A `repo:` naming THIS repository is `container-built`'s — it reads the `origin` remote | a product split across repositories, recorded before `repo:` had a meaning | `repo:` is filled only where the code lives in ANOTHER repository, and that container's heading leaves this repo's code map — it belongs in the map of the repo that holds it. A `repo:` naming THIS repo is removed. `wdi-init` intent `structure` re-derives the map |
+| 18 | components exist, a UX run is in `_bmad-output/ux/`, and a landed `DESIGN.md` or `EXPERIENCE.md` has no `landed_from` in its frontmatter | landed before `landed_from` existed, so `ux-landed` cannot tell which run a landing discharged and reads every run as owed | `landed_from:` lists the run file(s) it came from, read off the old *landed from* line or `.control/memlog/ux.md`. A run that was never landed is landed now through `wdi-ux`, or marked `status: superseded` if the owner abandoned it |
+
+**Gates passed before they were recorded** are not a numbered item — nothing moves, the owner answers.
+Where `wdi-reconcile` or `wdi-help` shows downstream work for a gate `gates_passed` does not list, ask the
+owner once per gate whether it passed, and write it on a yes (`delivery-flow-guide.md` § *Recording a gate
+that passed*). The report says which were recorded and which the owner left open.
+
+Items 11 and 12 are the engines' half of a version jump, and they come FIRST when both are hit:
+item 11 writes where a spec's files belong, item 12 moves them there. Doing 12 first means moving
+folders to a location the engines have not been told about, and the next `to-tickets` writes to the old
+one anyway.
+
+Anything not in the list is not this skill's. A brief that already has `## Why` is done; skip it.
+
+## Step 2 — Registry first
+
+**1 — the requirement split.** A row written under an older kit carries `text:` where a newer one
+carries `title:`; both are the short label, the renderer and `timeline.py` read either, and one MUST
+NOT be copied into the other — that is two homes for one fact. Which PRD a row belongs to is read from
+the rows before it is read from the prose. A `CAP` or `UJ` with a `prd:` field goes to `requirements-<that slug>.yaml`; an `FR`
+follows its `capability:` to that CAP's file; an `NFR` follows its `component:` to the PRD whose CAPs
+own that component — a `BG` is product-level and never decides an NFR's home on its own, so `goal:` is
+only a tie-breaker when that component's CAPs span two PRDs. On a product with exactly **one** PRD every row belongs to that
+PRD by construction — write them all to its file and skip the citation scan. Otherwise, only a row with
+none of those fields falls back to the PRD whose prose cites its id — and an id cited by **two** PRDs
+is reported, not placed. The citation scan still runs on every row as a cross-check: a row whose
+structural home and citing PRD disagree is reported with both names. Write the row, unchanged, into
+its file; `goals:` rows go to `goals.yaml`. A sentence moved into a YAML value keeps its punctuation
+and its markup: when it holds `: ` or `#` or starts with a quote, wrap the value in double quotes or a
+`>-` block — never trade a colon for a dash or strip `**` and backticks to make it a plain scalar. A row with no home is reported by id, not guessed: the
+owner names it. When every row has moved, delete `requirements.yaml`; `id-allocated-once` fails if a
+row was copied instead of moved.
+
+**2 — the pre-rename plan.** A spec still shaped `epics: → stories:` is flattened into the one
+`tickets:` list the validator reads. Every part of this is a mapping; nothing here is a judgment, and
+nothing is invented:
+
+| Old | New |
+|---|---|
+| `waves:` as the file's top-level key | `specs:`. The rows below it do not otherwise change shape from this rename alone |
+| the spec's `W<n>` id | **unchanged.** It is a retired alias, and every memlog, `DEC-`, report and RTM row that names it MUST keep resolving. Renaming it to `SPEC-<n>` is the one thing this step MUST NOT do |
+| `epics:` → `stories:` nesting | one flat `tickets:` list, in the order the stories appear, epic by epic. The `epics` level is repealed: it grouped rows and bought nothing |
+| a story's own id (`"1"`, `"1-2"`) | `<spec-id>-<NN>`, renumbered from `01` in dependency order — `W3-01`, `W3-02`. A story id only ever promised uniqueness inside one epic, and this method keys tickets globally |
+| `depends_on: ["1-1"]` on a story | `blocked_by: [W3-01]` — the same edge, the new key, pointing at the new id |
+| `{spec_folder}/stories/1-2-<slug>.md` | `{spec_folder}/issues/<NN>-<slug>.md`, the `<NN>` matching the ticket's new id. `git mv`, so the file's history follows it |
+| a story's `touches:` | kept as `touches:`. A story never carried `component:`, and this step MUST NOT invent one — `wdi-init` owns that field |
+
+Two things stay untouched even here. The **status** of each ticket is read from its file and MUST NOT
+be copied into `specs.yaml` — `ticket-status-one-home` is what refuses that. And a `closed` spec is
+skipped whole: `validate.py` already flattens it in memory on every run, so rewriting the file changes
+no reading and only churns the record of finished work.
+
+Run `validate.py --check`. Green here means the registry is whole before any document starts pointing
+at it.
+
+## Step 3 — Documents, oldest gate first
+
+**3 — brief.** Merge `## Executive Summary` and `## Vision` into one `## Why`, keeping every sentence
+that says something the other did not. Each `BG-N` statement under `## Goals` MUST already be a row in
+`goals.yaml` (Step 2); replace the list with the pointer line from the template. Each `## Assumptions`
+item becomes a row in `.control/questions/assumptions.md` with `Whose: owner`; each `## Prerequisites`
+item a row in `external.md` — **after** checking that no `OQ-` row already states it, because a brief
+written under an earlier kit usually landed them already and a second row is a copy. A prerequisite
+the brief itself marks satisfied is dropped, not landed as open. A `questions/` table written before
+the `Whose` column existed (`| id | Assumption | Cost if wrong | Taken | By |`) gets the column added —
+header and separator, and an empty cell on every existing row, which the validator counts as
+`unstated`, which is what they are. The rows this skill lands say `owner`. `Cost if wrong` is `—` when
+the source never stated one; it is not invented. An open question the source never marked blocking is
+filed in `assumptions.md`, as the template's three tests say. Delete both sections, and say how many
+items were already rows. Check `## Success Criteria` names one measurable
+figure — if it does not, that is a finding for the owner, not a sentence for this skill to invent.
+
+**4 — each PRD.** Sections are matched **by name, never by number**: the numbers moved between kits
+(one kit numbers Non-Goals §5 and Open Questions §8; an older one numbers Non-Goals §7, MVP Scope §8,
+Open Questions §10), so a step that says "delete §8" deletes MVP Scope on the wrong corpus. Delete
+`Document Purpose`. Every `Glossary` term not yet in `.control/product-glossary.md` is added there,
+verbatim; then delete `Glossary`. Every `Non-Goals` item MUST already be in the brief's Scope Out or
+this PRD's `MVP Scope → Out of Scope` — if neither holds it, add it to the one it belongs to; then
+delete `Non-Goals`. Every `Open Questions` and `Assumptions Index` item becomes a `questions/` row
+(after the same already-a-row check as the brief's); delete both.
+Under each feature, every `FR` block is folded into its row in `requirements-<slug>.yaml` (Step 2)
+before the block goes: the block's description paragraph — the prose between the `#### FR-N` heading
+and the first `**…:**` label — becomes the row's `statement:` when the row has none (the row's `title`
+stays). **This is the one move with no validator behind it**, so count it: blocks with a paragraph
+versus rows that now carry `statement:` MUST match, and Step 5 reports both numbers. A run that deletes
+the blocks and lands zero statements has thrown the requirement's own sentence away; its `**Consequences (testable):**` bullets move verbatim to
+`addendum.md` under `## Technical how — testable consequences per FR`, appended **after** the sections
+already there, one `### FR-N — title` each,
+because `prd-guide.md` repealed the double proof of done and that is where the technical restatement
+lives now; its `**Proof of done:**` is compared with the row's `proof` — when they differ, the
+**registry is kept** (it is the declared SSOT), the PRD's is dropped, and both texts are reported side
+by side for the owner, never merged. Then the block becomes `**Realizes:** FR-a, FR-b, NFR-c`, and a
+`**Functional Requirements:**` label left with nothing under it is deleted — the rendered page rebuilds
+the blocks from the rows. When the deletions are done, **put the surviving `##` sections in the
+template's order and renumber them** — moving a whole section is a move, not an edit, and a file whose
+`## 6` sits above its `## 4` tells the AI reader the numbers lie. The order — 1 Why This Initiative · 2 Target User · 3 Features · 4 MVP Scope · 5 Success
+Metrics · 6 Cross-Cutting NFRs · 7 Constraints and Guardrails — and the `###` beneath them to match
+(`### 8.2` → `### 4.2`). Numbers are not sentences; leaving `## 4. Features` beside `## 8. MVP Scope`
+tells the next reader two sections went missing. A `UJ-N` the prose names that has no row in any requirement file is
+not given one — it is marked with an HTML comment where it stands and reported; `wdi-product`
+allocates ids. A moved sentence that cites a section number (`§ 8`) of a section this step deletes
+keeps the number — it is reported as wording for the owner, not repointed, because its new home is a
+judgment. `## 1. Vision` becomes `## 1. Why This Initiative`: delete only the sentences
+that also appear, word for word, in the brief's `Why`; what remains is left whole under an HTML comment
+saying the new shape wants a delta, because deciding which paraphrases are copies is the owner's. On a
+single-initiative product that is one line pointing at the brief — write it and say so.
+
+**5 — each SRS.** Every `| UC-` row MUST already be in `usecases.yaml` with the same `critical`. A row
+missing there is landed first. Then the table becomes the template's pointer line.
+
+**6 — each SDD.** In `## Inherited Constraints`, drop the `Quoted rule` column; keep `AD` and `How it
+lands here`. In the blockquote shape, drop the `> ` lines and the `Quoted verbatim from` sentence; keep
+the `**AD-N — title**` heading and the landing prose under it, each heading on its own line. An `AD-N`
+cited here that is not in the spine is a finding.
+
+**7 — C4 L2.** Every PC listed in the table MUST have that container in its `containers:`. Then the
+table becomes the pointer line.
+
+**8 — pointers at the moved pages.** Every `.md` that cites `.control/generated/brief.md`,
+`blueprint.md`, or `prd-<slug>.md` **and that `cites-resolve` reads** is repointed to the new path — a
+path substitution, nothing else in the sentence changes. That includes a product's own scratch and
+issue notes. It excludes what the validator excludes: `.control/memlog/`, `.control/decisions/`,
+`.control/reports/`, `questions/answered.md`, and `_bmad-output/` — those describe the past, and a
+path rewritten there falsifies a record; the installer's probe skips them for the same reason.
+
+## Step 4 — Render, then validate
+
+```bash
+uv run .constitution/method/scripts/validate.py --generate
+```
+
+This writes every reader's page into `.what-rendered/` and `.how-rendered/`, and clears the human pages
+that used to sit in `.control/generated/`. Then `--check` MUST be green. Every finding at this point is
+either a row that moved wrong in Step 2 or a pointer that points at nothing — both are this skill's to
+fix before it reports done.
+
+Then close the record:
+
+```bash
+npx wdi-method upgrade-check
+```
+
+It re-runs the probes and rewrites `upgrade_pending` in `.control/wdi-method.yaml`. It MUST exit 0 —
+the field is then gone, which is what tells `wdi-help` and the next session that nothing is owed. An
+item still listed is either not moved yet or needs the owner, and the report says which.
+
+## Step 5 — Report, and commit once
+
+What moved, file by file · what was landed into the registry, by id · what could not be placed and
+needs the owner · the rendered pages now waiting to be read, one per gate · validators green. Then
+**one** commit: `chore(method): upgrade <from> → <to>`. Not one per document — the upgrade is one
+event.
+
+## Rules
+
+- You MUST NOT change a sentence while moving it. Wording that reads wrong in its new home is a
+  finding for the owning skill, later.
+- You MUST NOT invent a home. An `FR` no PRD cites, a Non-Goal neither boundary holds, an `AD-N` not
+  in the spine — each is reported by id and left where it was.
+- You MUST NOT write your findings into the corpus. A registry file carries rows and nothing about
+  the upgrade that produced them; a gap in this skill goes in the Step 5 report. The one exception is
+  the HTML comment the steps above name, placed where the owner will read the document.
+- You MUST NOT re-cut `specs.yaml`. That is `wdi-build`'s, where a human can see it.
+- You MUST NOT touch `.control/decisions/` or `.control/reports/`. A frozen `DEC-` that cites `V26` or
+  `W3` is history; the alias rule in `corpus-guide.md` covers it.
+- Re-running on an upgraded repo MUST find nothing and say so. Every probe in Step 1 is idempotent.
+
+## Output
+
+The Step 1 checklist with each item marked done · skipped (already new shape) · left for the owner, with
+the id list for the last · the registry rows landed · **statements landed / FR blocks that had a
+paragraph** · consequences moved · `questions/` rows added and rows found already present · proof-of-done
+divergences, both texts · the path of every rendered page · the validator result · the commit.