wdi-method 0.5.13 → 0.6.0

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

@@ -1,26 +1,28 @@
 ---
 name: wdi-report
-description: Use when someone needs numbers about this project — progress for a client update, an estimate before the work is committed, or task rows ready to paste into a tracker. Three intents, progress and estimate and dispatch. Never invents a number.
+description: Use when someone needs numbers about this project — progress for a client update, an estimate before the work is committed, task rows ready to paste into a tracker, or a self-contained brief/PRD deliverable. Four intents, progress and estimate and dispatch and render. Never invents a number.
 ---
 
 # WDI Report
 
-Three intents, and the first is deliberately fenced off from the other two **because their rules are opposite**.
+Four intents. The first three are fenced off from each other **because their rules are opposite**; `render`
+answers a different question from all three — not a number, a document.
 
 | Intent | Answers | Rule |
 |---|---|---|
 | `progress` | What has moved, what is late, how much is proven | **Entirely derived.** MUST NOT write one number, date, or percentage that did not come from the registry or from git |
 | `estimate` | How big this is, what the tasks are, how much load, what the timeline looks like | **Forward-facing.** MUST state which inputs exist and how precise that makes it, and MUST be labelled an estimate |
 | `dispatch` | Task rows ready for an outside tracker | Reads the same table as `estimate`; recomputes nothing |
+| `render` | The page a human reads at each gate — brief, PRD, blueprint, SDD — and a complete SRS per component | **A projection.** Assembles the working document verbatim plus what the registry and `.control/questions/` complete; adds no fact and no sentence of its own |
 
-Confusing the first two is the failure this split exists to prevent: a forward-looking figure presented in the
+Confusing the first two is the failure that split exists to prevent: a forward-looking figure presented in the
 voice of a derived one is the most expensive kind of wrong.
 
 ## What owns what
 
 | Owner | Produces |
 |---|---|
-| `.constitution/method/scripts/validate.py` | `generated/rtm` · `dag` · `status` · `risks` · `components` · `decisions` · `blueprint` · `estimate` |
+| `.constitution/method/scripts/validate.py` | `generated/rtm` · `dag` · `status` · `risks` · `components` · `decisions` · `estimate` — and every page under `.what-rendered/` and `.how-rendered/` |
 | `.constitution/method/scripts/timeline.py` | `generated/timeline` · `generated/report` · `.control/reports/<period>.md` |
 | `.constitution/method/scripts/inventory.py` | The three inventories, derived from code |
 | `wdi-reconcile` | Drift between corpus and registry — read-only, no file |
@@ -47,16 +49,16 @@ it prints before reading anything else:
 | `rtm/status not yet generated` (exit 3) | Stop. The tables cannot be built, so there is nothing honest to report |
 | `git did not respond` (exit 3) | Stop. Every actual date comes from git; without it there is no time dimension |
 | `the registry has uncommitted changes` | Say so in the report header. The numbers describe a working tree, not `main` |
-| `story with no git history` | Name those stories. They count toward promise progress but cannot appear under Proven |
+| `tickets with no git history` | Name those tickets. They count toward promise progress but cannot appear under Proven |
 | `n findings` | Report the count and, if any are red, say which gate they block |
 
 A report built on stale tables is worse than no report: it looks authoritative and is not.
 
 ## Step 2 — Read the derived time dimension
 
-You MUST NOT derive dates yourself. `timeline.py` reads each story file's history and takes the first commit whose
-frontmatter status left `draft` as the start, and the commit where it became `done` as the end. `FR` spans its
-stories; `CAP` spans its `FR`, and closes only when every story under it is closed.
+You MUST NOT derive dates yourself. `timeline.py` reads each ticket file's history and takes the first commit whose
+status left the not-started set as the start, and the commit where it became `done` as the end. `FR` spans its
+tickets; `CAP` spans its `FR`, and closes only when every ticket under it is closed.
 
 None of this is written back into any registry. A stored copy would be a second home for one fact, and the stored
 copy is the one that goes wrong.
@@ -64,7 +66,7 @@ copy is the one that goes wrong.
 ## Step 3 — Read `generated/timeline` and `generated/report`
 
 `timeline` gives one row per `CAP`, plan beside actual, plus a gantt. `state` is `not-started`, `in-progress`,
-`done`, or **`overdue`** — the last being V14.
+`done`, or **`overdue`** — the last being `plan-dates`.
 
 You MUST list every overdue row **by name**, with what it is waiting on. The script prints them individually for
 the same reason: aggregating them into a count is how a slipping plan stays comfortable.
@@ -98,11 +100,11 @@ overwrite one (exit 4) rather than trusting anyone to remember.
 | Measure | Formula | Answers |
 |---|---|---|
 | **Progres janji** | green RTM rows ÷ total RTM rows | How much is **proven** |
-| Progres kerja | stories `done` ÷ stories in wave | How much was worked on |
+| Progres kerja | tickets `done` ÷ tickets in spec | How much was worked on |
 | Kesiapan gate | green validators ÷ applicable validators | Whether the next gate can open |
 
 You MUST present **progres janji** first and label it as the one that counts. Progres kerja MUST NOT lead a
-client-facing report: a story can be `done` while its RTM row is still red because the test has no name or the `UC`
+client-facing report: a ticket can be `done` while its RTM row is still red because the test has no name or the `UC`
 does not exist — and that gap is exactly what the client is entitled to know.
 
 ---
@@ -121,13 +123,13 @@ one thing this intent can get badly wrong.
 |---|---|---|
 | **G1** — the brief | T-shirt size · rough capability count · the first risk list | very rough |
 | **+ G2** — the PRD | **The candidate task list = the `FR` list** · `estimate_mandays` per `CAP` · `must/should/could/wont` · order from `depends_on` between `CAP` | rough |
-| **+ tail of G2** — components born | Tasks grouped per component = per Epic · **`mode` per component, so document load is counted too** · `risk_accepted` marks exposure | medium |
+| **+ tail of G2** — components born | Tasks grouped per Product Component · **`mode` per component, so document load is counted too** · `risk_accepted` marks exposure | medium |
 | **+ G3** — the blueprint | Table, endpoint, and screen counts → real implementation load, not load guessed from an `FR` count | good |
-| **+ G4** — component depth | Stories and test names → measured load | best |
+| **+ G4** — component depth | Tickets and test names → measured load | best |
 
 ## Step 2 — Inputs
 
-`requirements.yaml` (`estimate_mandays`, `priority`, `depends_on`, `target_release`) · `components.yaml` (`mode`,
+`goals.yaml` (the `BG` list) · every `requirements-<slug>.yaml` (`CAP` with `estimate_mandays`, `priority`, `depends_on`, `target_release`, plus its `FR`) · `components.yaml` (`mode`,
 `risk_accepted`, `risk_note`) · the three `inventory-*.md` when they exist.
 
 `estimate_mandays` on `CAP` is the **source**, and it is used for real here rather than being decoration. When it is
@@ -136,13 +138,13 @@ absent, say so — an estimate with no mandays input is a T-shirt size, and it M
 ## Step 3 — The output: one task table
 
 Written to `.control/generated/estimate.md` by `validate.py --generate`. **Default one row per `FR`**, because that
-is the ideal shape of a wave and because an `FR` has had a proof of done since birth.
+is the ideal shape of a spec and because an `FR` has had a proof of done since birth.
 
 | Column | Content |
 |---|---|
 | Task | The title, from the `FR` |
 | `FR` | Its id |
-| Epic | The Product Component |
+| Component | The Product Component |
 | `mode` | That component's depth — this is what makes document load visible |
 | Exposure | `risk_accepted` + `risk_note` |
 | Effort | Mandays, derived from the parent `CAP`'s `estimate_mandays`, divided among its `FR` |
@@ -152,11 +154,11 @@ is the ideal shape of a wave and because an `FR` has had a proof of done since b
 
 ## Step 4 — Say what it is, and what it is not
 
-> A row in the estimate table is a **candidate** task. A wave in `waves.yaml` is a **real** one. The first missing
+> A row in the estimate table is a **candidate** task. A spec in `specs.yaml` is a **real** one. The first missing
 > is normal; the second is not.
 
-The table is planning, not commitment. One row MAY become one wave, and three neighbouring rows MAY be merged into
-one. **That merge is a human decision made when the wave opens**, and this intent MUST NOT pretend to already know
+The table is planning, not commitment. One row MAY become one spec, and three neighbouring rows MAY be merged into
+one. **That merge is a human decision made when the spec opens**, and this intent MUST NOT pretend to already know
 the answer.
 
 - Every output MUST carry the word estimate, visibly, at the top.
@@ -168,11 +170,12 @@ the answer.
 
 # Intent `dispatch`
 
-Reads `.control/generated/estimate.md` and `waves.yaml`. **It recomputes nothing.**
+Reads `.control/generated/estimate.md` and `specs.yaml`. **It recomputes nothing.**
 
-It emits rows in a form that can be pasted into an outside tracker: Epic (the Product Component), Task (the wave, or
-the candidate row where no wave exists yet), Sub-task (the story, where one exists), labels for `FR` and `CAP`, and
-Fix Version from the release.
+It emits rows in a form that can be pasted into an outside tracker: a **parent issue** for the spec — or the
+candidate row where no spec exists yet — an **issue** per ticket where tickets exist, with its blocking edges,
+labels for `FR` and `CAP`, and Fix Version from the release. A ticket is an issue and not a sub-task, because a
+sub-task cannot carry the blocking relation the frontier is read from; `delivery-flow-guide.md` owns that mapping.
 
 - Output goes **to the screen**. This intent MUST NOT write a file, and MUST NOT write to the tracker — entering it
   is a human act.
@@ -182,12 +185,59 @@ Fix Version from the release.
 
 ---
 
+# Intent `render`
+
+Produces a self-contained reader's copy of the brief or a PRD — the shape that used to be written by hand,
+now assembled instead of duplicated. `brief-guide.md` § The generated deliverable and `prd-guide.md` § The
+generated deliverable own what each page assembles; this intent is the one place either is actually run.
+
+Both working templates point here by name, so this is what an owner will type:
+
+| They ask for | They run |
+|---|---|
+| The full, readable brief | `/wdi-report render brief` |
+| The full, readable PRD | `/wdi-report render prd` |
+
+Either form runs the same single command in Step 1 — the argument says which page they came for, and
+which path to lead the report with. It does NOT narrow what gets regenerated, and you MUST NOT pretend
+it did.
+
+## Step 1 — Generate
+
+```bash
+uv run .constitution/method/scripts/validate.py --generate
+```
+
+This regenerates the machine tables in `.control/generated/` AND every human page in `.what-rendered/` and
+`.how-rendered/` — the brief, every PRD, the blueprint, every SRS, and the SDD of every component above
+`catalog`. One run, not a per-document command, because the pages cite each other's ids.
+
+## Step 2 — Report what changed
+
+`generate()` writes `brief.md` unconditionally and one `prd-<slug>.md` per folder found under
+`.what/_prd/`. Name the paths written. If a working document does not exist yet, its page says so instead
+of a crash — report that as "not started" rather than a failure.
+
+## Step 3 — Say what the page is, and is not
+
+> This is a **projection**, assembled from `brief.md` / `prd.md`, the requirement registry,
+> `.control/product-glossary.md`, and `.control/questions/`. It carries no fact the working documents and
+> the registry do not already hold, and it MUST NOT be edited by hand — the next `render` overwrites it.
+
+- You MUST NOT hand-patch a generated page to "fix" something that reads wrong. The defect is in the
+  working document or the registry, and that is where it MUST be fixed.
+- A reader asking for "the full brief" or "the complete PRD" wants this page, not `.what/_product-brief/brief.md`
+  or `.what/_prd/<slug>/prd.md` read directly — those are now pointer-heavy working documents, not the
+  deliverable.
+
+---
+
 ## Rules
 
 - You MUST NOT invent progress. When a table is missing or stale, name it and stop.
-- You MUST NOT report `progress` in stories. The planning layer speaks in `CAP`, `FR`, and defects; stories are the
+- You MUST NOT report `progress` in tickets. The planning layer speaks in `CAP`, `FR`, and defects; tickets are the
   execution layer and are born too late to plan against.
-- You MUST NOT hand-write anything under `generated/`. There is no exception.
+- You MUST NOT hand-write anything under `generated/`, `.what-rendered/`, or `.how-rendered/`. There is no exception.
 - You MUST NOT re-run `--publish` to "fix" a report. The refusal is the rule working.
 - When plan dates have moved since the last report, you MUST say so and point at the commit.
 - When there is no previous report, say the period is unbounded on the left rather than picking a date.
@@ -203,3 +253,5 @@ individually, never counted away.
 a commitment.
 
 **`dispatch`:** the paste-ready rows, on screen, with candidates marked.
+
+**`render`:** the paths written, which working documents were missing, and the projection notice above.

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

@@ -1,118 +1,201 @@
----
-name: wdi-review
-description: Use to review any corpus document at any time, and always before a gate on the four artifacts no doc_standards covers — the architecture spine, SRS, SDD, and SPEC. Reads the lens set from the component's risk_accepted, dispatches bmad-review, and stamps the V13 trace on those four only. Not for code review.
----
-
-# WDI Review
-
-Five BMad skills review their own output through `doc_standards`. Four artifacts have no such trigger,
-and they are the most binding ones in the corpus. This skill covers exactly those four.
-
-It exists for two reasons `bmad-review` cannot serve on its own: the lens set is not a property of the
-artifact but of the component's `risk_accepted`, and defaulting to structure + prose silently drops the
-one lens that matters for behaviour; and `bmad-review` is class D — it writes nothing, so nothing proves
-it ran.
-
-You MUST NOT use this for code or diffs. That is `bmad-code-review` and the two-family Review Panel.
-
-## What it covers
-
-| Artifact | Trace lands in |
-|---|---|
-| `.how/_platform/ARCHITECTURE-SPINE.md` | `reviewed:` in its frontmatter |
-| `SRS-<pc>.md` + slots `02`–`05` | `reviewed:` in the SRS frontmatter |
-| `SDD-<pc>.md` + slots `01`–`06` | `reviewed:` in the SDD frontmatter |
-| `SPEC.md` | `spec_reviewed:` on the wave in `waves.yaml` |
-
-**The lens set comes from the component's `risk_accepted`, never from `mode` and never from the artifact
-type.** `delivery-flow-guide.md` owns the mapping and it MUST NOT be restated as a second copy here; what
-this skill owns is reading it and refusing to run a lighter set than it names.
-
-| `risk_accepted` | Lenses | And on the code |
-|---|---|---|
-| `low` | structure · prose · **edge-case-hunter** | a two-reviewer panel is required |
-| `medium` | structure · prose · **edge-case-hunter** | — |
-| `high` | structure · prose | — |
-
-`SPEC.md` always carries `edge-case-hunter`: it is the contract a builder works from, and a branch missed
-there surfaces as a bug at G5 instead.
-
-**V13 stamps only components at `risk_accepted` `low` or `medium`.** At `high` the owner has already said
-they accept the risk, and demanding the trace there is bookkeeping with no buyer.
-
-SPEC keeps its trace in the registry because `bmad-spec` is its sole author and overwrites hand
-edits. A trace written into `SPEC.md` disappears on the next run.
-
-**Anything in the corpus MAY be reviewed here, at any time** — a `DEC-`, minutes, an `OQ-`, a guide, a
-brief, a PRD, a `DESIGN.md`. What is restricted is the **stamp**, not the reading: only the four rows
-above have a trace V13 reads, and only they MAY be stamped.
-
-The five artifacts carrying `doc_standards` review themselves at finalize, so a review here is never
-required for them. Asking for one anyway is legitimate — after hand edits, before a gate, when a
-finding is suspected — and it MUST NOT leave a `reviewed:` block behind. A second trace on an
-artifact whose first review is automatic implies that first one was optional.
-
-## Step 1 — Read the lens set off the component
-
-Find the artifact's component, read its `risk_accepted` from `components.yaml`, and state the lens set in
-one line before dispatching. Do not ask the user which lenses to run — the field decides, and it is the
-owner's field.
-
-For an artifact with no component — a guide, minutes, the spine — use structure · prose.
-
-The adversarial lens is in no table. It MAY be added when the artifact touches money, personal data, or a
-third-party integration. It demands at least ten concrete findings and treats an empty result as a signal
-to re-check, so adding it to a routine review buys noise.
-
-## Step 2 — Dispatch
-
-Invoke `bmad-review` with the artifact path and the chosen lenses. Slots are part of the artifact:
-reviewing `SRS-<pc>.md` without `04-usecases/` and `05-scenarios/` reviews the kernel and misses
-where the branches live.
-
-## Step 3 — Resolve before stamping
-
-Findings MUST be resolved or explicitly deferred before the trace is written. A deferred finding
-MUST be filed through `wdi-question`, or opened as a `DEC-` through `wdi-decision` — never a note in the
-chat that dies with the session.
-
-You MUST NOT stamp an artifact whose findings are still open. A trace on unresolved findings is
-worse than no trace: V13 goes green and the gate opens on a review nobody acted on.
-
-## Step 4 — Stamp
-
-Write the trace, and nothing else:
-
-```yaml
-reviewed:
-  date: '<YYYY-MM-DD>'
-  sha: '<commit sha at review time>'
-  lenses: [structure, prose, edge-case-hunter]
-```
-
-- `sha` MUST be the commit the artifact was reviewed at. Without it staleness cannot be measured, only
-  felt — the same reason a structure map requires one. V13 no longer reads the stamping commit itself as
-  a change, so a fresh stamp does not make its own review look stale.
-- You MUST NOT write the trace unless `bmad-review` actually ran in this session. Filling it as a
-  formality turns V13 into a rubber stamp, which is worse than having no validator.
-- You MUST NOT touch `status:` while stamping. `status: reviewed` states a **stage**; the `reviewed:`
-  block states an **event**. Raising the status is a separate act.
-- You MUST NOT edit the artifact's content. Fixing a finding is the author's act, not the
-  reviewer's — say what is wrong and stop.
-
-## Rules
-
-- You MUST NOT stamp anything outside the four rows in the table. Brief, PRD, `DESIGN.md`,
-  `EXPERIENCE.md`, and research MAY be reviewed on request; the finding report is the whole output,
-  and no `reviewed:` block is written.
-- You MUST NOT stamp on behalf of a review someone else ran earlier. Re-run it; the run is cheap and
-  the claim is not.
-- When the artifact changed after the review, the trace is stale by definition. You MUST re-run
-  rather than bump the date.
-- When findings reveal the requirement itself is wrong rather than the writing, this stops being a
-  review. Route to `wdi-decision`, and let the `DEC-` change the artifact.
-
-## Output
-
-One short report: artifact, lenses run, findings by severity, what was resolved, what was deferred
-and where it landed, and whether the trace was written — with the reason when it was not.
+---
+name: wdi-review
+description: Use to review any corpus document at any time, and always before a gate on the four artifacts no doc_standards covers — the architecture spine, SRS, SDD, and SPEC. Reads the lens set from the component's risk_accepted, dispatches bmad-review, and stamps the `review-trace` trace on those four only. Not for code review.
+---
+
+# WDI Review
+
+Five BMad skills review their own output through `doc_standards`. Four artifacts have no such trigger,
+and they are the most binding ones in the corpus. This skill covers exactly those four.
+
+It exists for two reasons `bmad-review` cannot serve on its own: the lens set is not a property of the
+artifact but of the component's `risk_accepted`, and defaulting to structure + prose silently drops the
+one lens that matters for behaviour; and `bmad-review` is class D — it writes nothing, so nothing proves
+it ran.
+
+You MUST NOT use this for code or diffs. That is `code-review`, dispatched by `wdi-build` as Step 3 of its pipeline.
+
+## What it covers
+
+| Artifact | Trace lands in |
+|---|---|
+| `.how/_platform/ARCHITECTURE-SPINE.md` | `reviewed:` in its frontmatter |
+| `SRS-<pc>.md` + slots `02`–`05` | `reviewed:` in the SRS frontmatter |
+| `SDD-<pc>.md` + slots `01`–`06` | `reviewed:` in the SDD frontmatter |
+| the contract — `SPEC.md`, or the ticket set as one artifact at size `S` | `spec_reviewed:` on the spec in `specs.yaml` |
+
+**The lens set comes from the component's `risk_accepted`, never from `mode` and never from the artifact
+type.** The mapping lives in `delivery-flow-guide.md` § Two fields, and it is **read from there, not copied
+here** — this file carried a second copy of that table until it was noticed that the sentence forbidding
+the copy sat directly above it.
+
+What this skill owns is three things the mapping does not say:
+
+- **Refusing a lighter set than it names.** The lens set is not negotiable down, whatever the artifact.
+- **The contract is the exception:** it always carries `edge-case-hunter`, first run and re-run alike. It
+  is what a builder works from, and a branch missed there surfaces as a bug at G5 instead.
+- **Reading `risk_accepted` off the component, not off the artifact** — Step 1 below.
+
+## When a review has to run again — and when it does not
+
+Four rules, and together they are what keeps this skill from becoming a treadmill. Every one of them has a
+precedent elsewhere in the method; none of them lowers what a review looks for.
+
+- **The trace has to be fresh at a gate and at spec close. Between those points a stale trace is
+  advisory.** `review-trace` reports it and does not fail; what catches a
+  gate opening on a stale review is G4's ★ question — *validators green **and** the review leaving no open
+  finding* — not a validator firing on every commit.
+- **A wording-only change MUST NOT trigger a re-run.** The split is `prd-guide.md`'s: an `FR`'s
+  **promise** reopens gates, its **wording** costs one Revision History row. Re-stamping `date` and `sha`
+  without re-running is allowed **here and nowhere else**, and that row is what makes it checkable.
+  Behaviour, a rule, a boundary, a contract, or a use case flow is material, and material changes re-run.
+- **A re-review covers the delta, not the artifact.** Read what changed since the reviewed `sha`, and
+  whatever it reaches. G3 already reopens over the delta when a new PRD arrives; same principle.
+- **One apply, one review.** A `DEC-` or an answered `OQ-` applied across several artifacts is **one**
+  review of the delta across all of them, never one review per artifact. The trace lands on each artifact
+  touched, naming the same `sha`.
+
+## Stale is not a finding. Load-bearing stale is.
+
+**Triggers are a gate, a spec close, and an explicit ask — nothing else.** You MUST NOT offer a review
+because a document was touched. An offer declined five times teaches the owner to decline the sixth,
+which is the one that mattered.
+
+Three things look like a review and are not: a document the owner has already **decided against** — an
+edit, `delivery-flow-guide.md` owns it; a document **merely behind the code**, its expected state; and a
+machine contract, which nobody reads.
+
+**The test — one question, and it decides:**
+
+> Would a reader who believes this sentence make the wrong repair?
+
+| Load-bearing — repair NOW | Not load-bearing — leave it |
+|---|---|
+| A binding guide describing a stack the repo left — `npm` commands that all fail | A count, a date, a section that reads a little old |
+| A guard that greps a language this repo no longer writes | Wording that is merely less good than it could be |
+| A cite that resolves to nothing | A section whose file has moved but whose point still holds |
+| A claim contradicting an `AD-N` or an `applied` `DEC-` | An artifact the next spec will rewrite anyway |
+
+Everything in the right column is corrected **when someone next touches that section**, or it dies with
+the document. It MUST NOT be raised as a finding, MUST NOT open an `OQ-`, and MUST NOT hold a stamp.
+
+**A missing history line is never a finding.** Not a rationale, not a note saying why something changed,
+not an account of a conflict already resolved. `corpus-guide.md` § The corpus is written in the present
+tense says history is written when someone judges it worth writing, and that skipping it is not a gap —
+a review that reports it as one turns a record into a ritual.
+
+**Where substance actually is.** On the evidence of a real pass of twenty-one findings: a document checked
+against **the code**, and against an **`AD-N`** or an `applied` `DEC-`. Those two found the only two that
+changed what was true. Document-versus-document bookkeeping found thirteen and changed nothing. When the
+budget is tight — it always is — spend it on the first two and skip the third.
+
+## A restated derived fact is one finding, and its remedy is deletion
+
+The cheapest class to produce is the one worth least: a document disagreeing with a registry it could
+have read. It was **thirteen of the twenty-one** in the pass above — `mode` restated in prose, a slot
+list denying files on disk, "no applied `DEC-` binds this component", a Gate Checklist counting four use
+cases where the registry held six.
+
+Handled as follows, and it is not a judgement call:
+
+- **One finding, not one per site.** Report the class and list its locations. Thirteen rows for one
+  cause spends the budget above on a single problem and buries whatever else the pass found.
+- **The remedy is DELETION.** You MUST NOT correct the restated value. A corrected copy is a *second*
+  stale fact on a slower clock — one real SRS carried three claims about its own `mode` on one page,
+  one of them a correction block fixing an older value, and none of the three was right.
+- **It is a `structure` finding**, never `edge-case-hunter`. It costs no thinking to find and MUST NOT
+  consume the lens bought for reasoning about behaviour.
+- If the document's **template** invited it, say so and route to the maintainer. `corpus-guide.md` §
+  A derived fact has exactly one home is the list; the templates were cleaned once already, and an
+  invitation still standing is a package defect, not a product one.
+
+## Findings have a budget, and it is not a new one
+
+A review with no upper bound produced two hundred findings from one pass. The budget is the one
+`wdi-question` already carries, so nothing new is invented:
+
+| Class | Where it goes | Target |
+|---|---|---|
+| Holds the gate | `.control/questions/blocking.md` | **≤3 per Product Component** |
+| Does not hold anything | `.control/questions/assumptions.md`, one line each | **≤15** |
+
+**A review that exceeds both MUST stop and say so.** What it reports is not a finding list but a verdict:
+this artifact needs rewriting, not reviewing. Sixty findings is not thoroughness — it is a review that
+failed to reach a conclusion, and the owner pays for it twice. You MUST NOT register a finding as
+blocking to be safe.
+
+**`review-trace` stamps only components at `risk_accepted` `low` or `medium`.** At `high` the owner has already
+accepted the risk, and demanding the trace there is bookkeeping with no buyer. The contract keeps its
+trace in the registry rather than in itself: `to-spec` and `to-tickets` overwrite hand edits.
+
+**Anything in the corpus MAY be reviewed here when asked** — a `DEC-`, minutes, a guide, a brief, a PRD,
+a `DESIGN.md`. What is restricted is the **stamp**, not the reading: only the four rows above carry a
+trace `review-trace` reads. The five artifacts with `doc_standards` review themselves at finalize; a review here is
+never required for them and MUST NOT leave a `reviewed:` block, because a second trace implies the first
+was optional.
+
+## Step 1 — Read the lens set off the component
+
+Find the artifact's component, read its `risk_accepted` from `components.yaml`, and state the lens set in
+one line before dispatching. Do not ask the user which lenses to run — the field decides, and it is the
+owner's field.
+
+For an artifact with no component — a guide, minutes, the spine — use structure · prose.
+
+The adversarial lens is in no table. It MAY be added when the artifact touches money, personal data, or a
+third-party integration. It demands at least ten concrete findings and treats an empty result as a signal
+to re-check, so adding it to a routine review buys noise.
+
+## Step 2 — Dispatch
+
+Invoke `bmad-review` with the artifact path and the chosen lenses. Slots are part of the artifact:
+reviewing `SRS-<pc>.md` without `04-usecases/` and `05-scenarios/` reviews the kernel and misses
+where the branches live.
+
+## Step 3 — Resolve before stamping
+
+Findings MUST be resolved or explicitly deferred before the trace is written. A deferred finding
+MUST be filed through `wdi-question`, or opened as a `DEC-` through `wdi-decision` — never a note in the
+chat that dies with the session.
+
+You MUST NOT stamp an artifact whose findings are still open. A trace on unresolved findings is
+worse than no trace: `review-trace` goes green and the gate opens on a review nobody acted on.
+
+## Step 4 — Stamp
+
+Write the trace, and nothing else:
+
+```yaml
+reviewed:
+  date: '<YYYY-MM-DD>'
+  sha: '<commit sha at review time>'
+  lenses: [structure, prose, edge-case-hunter]
+```
+
+- `sha` MUST be the commit the artifact was reviewed at. Without it staleness cannot be measured, only
+  felt — the same reason a structure map requires one. `review-trace` no longer reads the stamping commit itself as
+  a change, so a fresh stamp does not make its own review look stale.
+- You MUST NOT write the trace unless `bmad-review` actually ran in this session. Filling it as a
+  formality turns `review-trace` into a rubber stamp, which is worse than having no validator.
+- You MUST NOT touch `status:` while stamping. `status: reviewed` states a **stage**; the `reviewed:`
+  block states an **event**. Raising the status is a separate act.
+- You MUST NOT edit the artifact's content. Fixing a finding is the author's act, not the
+  reviewer's — say what is wrong and stop.
+
+## Rules
+
+- You MUST NOT stamp anything outside the four rows in the table. Brief, PRD, `DESIGN.md`,
+  `EXPERIENCE.md`, and research MAY be reviewed on request; the finding report is the whole output,
+  and no `reviewed:` block is written.
+- You MUST NOT stamp on behalf of a review someone else ran earlier. Re-run it; the run is cheap and
+  the claim is not.
+- When the artifact changed **materially** after the review, the trace is stale and you MUST re-run
+  rather than bump the date. A wording-only change is the one exception, and §*When a review has to run
+  again* owns it.
+- When findings reveal the requirement itself is wrong rather than the writing, this stops being a
+  review. Route to `wdi-decision`, and let the `DEC-` change the artifact.
+
+## Output
+
+One short report: artifact, lenses run, findings by severity, what was resolved, what was deferred
+and where it landed, and whether the trace was written — with the reason when it was not.

package/kit/skills/wdi-systematic-debugging/SKILL.md

@@ -5,7 +5,7 @@ description: Use when encountering any bug, test failure, build failure, or unex
 
 # Systematic Debugging
 
-BMad has no debugging workflow — `bmad-build` assumes you already know what to build. This skill
+No engine below G5 has a debugging workflow — `/implement` assumes you already know what to build. This skill
 covers the gap: something is broken and the cause is unknown.
 
 ## The Iron Law
@@ -21,9 +21,9 @@ Use for any technical issue: test failure, production bug, unexpected behavior,
 build failure, integration failure.
 
 **Its home is G5, but its trigger is not positional.** Most invocations happen while coding, and
-that is why `AGENTS.md`, `bmad-build`, and the ship-story orchestration carry this rule in their
-worker context. What actually fires it is a pair of conditions — *something is broken* **and** *the
-cause is unknown* — so it MAY be invoked in any stage, by anyone, to investigate: a red
+that is why `AGENTS.md` and `wdi-build`'s builder brief both carry this rule.
+What actually fires it is a pair of conditions — *something is broken* **and** *the cause is
+unknown* — so it MAY be invoked in any stage, by anyone, to investigate: a red
 `validate.py` while writing an SRS at G3, a `wdi-reconcile` report that makes no sense, a
 generator producing an empty timeline. None of those wait for G5, and none of them are a
 misuse of this skill.
@@ -109,8 +109,8 @@ defect; refusing to work until the paperwork is right is how the file becomes a
 | Field | Where it comes from |
 |---|---|
 | `root_cause` | Your Phase 1–3 conclusion, in the four categories of the table above |
-| `violates` | The `FR-` or `UC-` the defect breaks. MUST be filled for `requirement` and `architecture`: a defect that violates something without naming what cannot be traced back to the corpus, and V20 fails it |
-| `fix` | `fastpath` for a pure code defect, the wave id otherwise. The table above already decides this — `requirement` and `architecture` MUST NOT be `fastpath` |
+| `violates` | The `FR-` or `UC-` the defect breaks. MUST be filled for `requirement` and `architecture`: a defect that violates something without naming what cannot be traced back to the corpus, and `defect-root-cause` fails it |
+| `fix` | `fastpath` for a pure code defect, the spec id otherwise. The table above already decides this — `requirement` and `architecture` MUST NOT be `fastpath` |
 
 You MUST NOT write a closure date. It is derived from the history of `defects.yaml` itself by
 `.constitution/method/scripts/timeline.py`, and a hand-written date would be a second home for one fact —
@@ -128,7 +128,7 @@ own `root_cause`:
 |---|---|
 | `code` | The failing test from Phase 4 passes and the fix is merged |
 | `requirement` | The `FR-` or `UC-` in `violates` has actually changed — the code alone MUST NOT close it |
-| `architecture` | The `DEC-` is `accepted` and named on the row. V20 fails a `fixed` row without one |
+| `architecture` | The `DEC-` is `accepted` and named on the row. `defect-root-cause` fails a `fixed` row without one |
 | `environment` | The handling is in place and the monitoring exists |
 
 Setting `fixed` before its row's condition is met is the failure this whole registry exists to