npm - wdi-method - Versions diffs - 0.6.5 → 0.6.7 - Mend

wdi-method 0.6.5 → 0.6.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md +495 -495
package/bin/wdi-method.js +1641 -1636
package/kit/.constitution/method/constitution.md +2 -2
package/kit/.constitution/method/repo-guide.md +5 -0
package/kit/.constitution/method/scripts/validate.py +2700 -2561
package/kit-overlay/constitution.md +2 -2
package/kit-overlay/repo-guide.md +5 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,495 +1,495 @@
-# WDI Method
-**The review layer BMad leaves thin — documents a human reads to check a decision before code gets written, sized to what the change actually deserves.**
-[BMad](https://github.com/bmad-code-org/BMAD-METHOD) decides *what* to build and *how* to build it well. WDI Method wraps it — it does not replace it — and adds the part between those two decisions and the code: inventories, a use case catalogue, a component design record, and a way to choose how much of that a given change actually needs.
-> This repository is **public and generic**. It MUST NOT carry a client name, a product name, or a
-> link to a private repository — product identity lives entirely in the repo that installs it.
----
-## Prerequisites — two engines, and both are required
-| Engine | What it does here | Source |
-|---|---|---|
-| **BMad Method** | Writes the documents behind G1–G4 — brief, PRD, architecture, UX | [github.com/bmad-code-org/BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) |
-| **mattpocock/skills** | Cuts the work at G5 — `to-spec`, `to-tickets`; runs the Fast Path and every `wdi-autopilot` iteration — `implement` | [github.com/mattpocock/skills](https://github.com/mattpocock/skills) |
-**The installer refuses without either.** BMad has always been checked. The ticket engines are checked
-too, since 0.6.4: G1–G4 genuinely run without them, and every repo that relied on that learned they were
-missing inside `wdi-build` with a spec already open. `--skip-engines-check` is the escape for the two
-cases that earn it — CI, and a repo that will never reach G5.
-No engine skill is invoked on its own. Each has a wrapper (`wdi-*`) that checks where the project is,
-runs the engine, verifies what came back, and records it. The engine is the pen; the wrapper knows what
-page it is on.
----
-## Install
-Three steps, in this order. The first is required before step 3 will run; the second can wait until
-**Both are required, and the installer refuses without either.** BMad has always been checked; the ticket
-engines are checked too, because every repo that learned they were missing learned it inside `wdi-build`
-with a spec already open. `--skip-engines-check` is the escape for the two cases that earn it: CI, and a
-repo that will never reach G5.
-**1. BMad Method** — in the product repo, picking the same agents you will give this installer:
-```bash
-cd /path/to/your/product-repo
-npx bmad-method install
-```
-**2. mattpocock/skills** — one of the two paths, not both (both leaves every skill twice):
-```bash
-# Claude Code — a managed bundle that updates when its author ships
-claude plugins install mattpocock-skills      # or, inside a session:  /plugin install mattpocock-skills
-# Codex, Cursor, OpenCode, other agents — copies the skills into this repo; keep setup-matt-pocock-skills selected
-npx skills@latest add mattpocock/skills
-```
-**You do not need to run `/setup-matt-pocock-skills` to get started.** Step 3 seeds `docs/agents/` with
-the two answers WDI Method actually has a requirement on, so the engines are aligned from the first
-install. Run the setup skill only to *change* something — to point at GitHub or Jira instead of local
-markdown — and keep the three invariants the seeded `issue-tracker.md` names.
-The seeding exists because the interview's own defaults are wrong here in one specific way: they send every
-engineering skill looking for a root `CONTEXT.md` and `docs/adr/`, and Article 3 says this method has no
-`docs/` layer for corpus or rules — `wdi-reconcile` reports both as findings. A repo that ran the setup
-before installing this package keeps its own file, and the installer names the contradiction rather than
-overwriting it.
-**3. WDI Method:**
-```bash
-npx wdi-method
-```
-This opens a TUI: it checks BMad, reports whether it found the ticket engines, detects install versus
-update, asks the product name and the document language, lets you pick agents, shows what it will
-write, and prints what to do next.
-**Every field arrives with an answer already in it, and Enter accepts it.** On an update that answer is
-what the repo already says; on a first install the product name is the folder name made readable —
-`acme-billing-portal` offers `Acme Billing Portal`. Nothing is validated as required: a prompt that
-refuses an empty submission while already holding a sensible default is asking you to retype something
-the installer knows.
-A value only changes when you actually answer. A run that does not mention language keeps the language the
-repo already chose, and says so.
-```bash
-npx wdi-method@latest update      # later, to take a newer method — @latest, or npx may reuse a cached one
-npx wdi-method verify             # check the method files are all present
-```
-**Upgrading from 0.5.x to 0.6** is two halves. `update` does the mechanical one — overwrites the kit,
-renames files whose content needs no judgment, seeds what is new — and then prints an `upgrade` line
-naming what is still in the old shape: a single `requirements.yaml`, a 14-section brief, a PRD carrying
-its FR text. The second half is a decision about content, so it belongs to a skill:
-```bash
-npx wdi-method@latest update --yes      # 1 — mechanical; read the `upgrade` line it prints
-# 2 — in your agent, run the wdi-upgrade skill: it moves every sentence into its new home, word for
-#     word, invents nothing, reports what it could not place, and ends in one commit.
-```
-Run the skill before any other skill. `wdi-help` and the validators read the new shape; a corpus half
-in the old one answers them wrongly.
-Non-interactive, for CI:
-```bash
-npx wdi-method install --yes --agents claude,codex --product "Your Product" \
-  --doc-language "Bahasa Indonesia"
-```
-Then invoke the **`wdi-help`** skill and ask what to do next. It reads where the project actually is and
-answers with the gate you are at, not with a menu.
----
-## What to do right after install, and right after update
-Two questions, and the honest answer to most of them is *nothing*. `wdi-help` answers them from the
-registry at any time; this table is the same answer written down.
-### After `install`
-| | |
-|---|---|
-| Engines missing | You never get here — `install` refuses, and names both install paths. Install them, run it again |
-| `/setup-matt-pocock-skills`? | **No.** The installer seeded `docs/agents/` already answered for this method. Run that interview only to *change* tracker |
-| So what is first? | **`wdi-init` intent `setup`** — it sets the global `mode`, and nothing has started until it is |
-| Then? | `wdi-problem` for G1. Or ask `wdi-help`, which reads the registry rather than this table |
-### After `update`
-| The summary said | Do |
-|---|---|
-| an **`upgrade`** line, naming content still in the old shape | **`wdi-upgrade`, before any other skill.** It moves every sentence into its new home, invents nothing, reports what it could not place, and ends in one commit. `wdi-help` and the validators read the new shape; a corpus half in the old one answers them wrongly |
-| **no** `upgrade` line | Nothing. The update was mechanical and complete — carry on from wherever the gates say you are |
-| `seeded docs/agents/` | Nothing. An older repo just received the engines' config, pre-answered. Read it if you like; do not run the setup interview to redo it |
-| a warning that `domain.md` still points at a root `CONTEXT.md` | Add the correction that warning names to the top of that file. It was written by the setup interview before this package was installed, and it sends every engineering skill at two paths Article 3 forbids |
-| a warning naming a **mandate** and `ad-n` | Only if you run `wdi-autopilot`. Decide whether that mandate should now park `AD-N` contradictions, and edit its `parked` list yourself — `update` never edits an authority you granted |
-**`wdi-upgrade` is only ever about corpus content** — a brief, a PRD, an SRS, registry rows in the old
-shape. It is not the answer to a missing engine, a missing tracker config, or anything under
-`.control/memlog/`; each of those is handled by the installer itself or by the skill that owns it.
----
-## How to use it — the walk
-A gate is a moment where a human reads **one page** and decides. Between gates the AI works in a
-pointer-heavy working set it does not need you to read. So the walk is: run a skill, read the page it
-renders, decide — advance or refine.
-| # | You run | You read | You decide |
-|---|---|---|---|
-| 0 | `wdi-init` intent `setup` | — | the global `mode`: how deep this product goes by default |
-| 1 | `wdi-problem` | `.what-rendered/_product-brief/brief.md` | **G1** — is this the problem, whose is it, and does it earn the work? |
-| 2 | `wdi-product` intent `prd` — `wdi-ux` first when the interface *is* the promise | `.what-rendered/_prd/<slug>/prd.md` | **G2** — is this what we build, and how does it feel? |
-| 3 | `wdi-init` intent `component` | the rows it adds to `components.yaml` | each component's `mode` and `risk_accepted` |
-| 4 | `wdi-blueprint` — `catalog`, then `platform` | `.how-rendered/blueprint.md` | **G3** — does the whole hold together? **Once per product** |
-| 5 | `wdi-component` — one component | `.how-rendered/<pc>/SDD-<pc>.md` | **G4** — is this how we build it? **Skipped at `mode: catalog`** |
-| 6 | `wdi-report` intent `estimate` | `.control/generated/estimate.md` | which candidate row becomes the next spec |
-| 7 | `wdi-build` — for that row | nothing: tickets are machine contracts. You answer `to-tickets`' quiz on granularity and blocking edges | **G5** — is it done and proven? Once per spec |
-| 8 | `wdi-report` intent `progress` | the report it writes | what has moved, what is late, what is proven |
-| 9 | `wdi-autopilot` — when you would rather review the result than walk steps 6–8 yourself | its preflight page, then its final report and ledger | one **mandate**: scope, what stays parked for you, smoke test by the agent or by you, loop interval, expiry |
-**Unattended, on request.** `wdi-autopilot` moves owner time from the gates to two points: the mandate before,
-the review after. From the gate you name it runs the same skills, answers what they would have asked, records
-every answer in `.control/memlog/autopilot-<mandate-id>.md`, and returns at one of three stops — done,
-at capacity, or blocked. It finishes when every `FR` in scope is closed, when nothing left is runnable, or
-when the mandate expires. It needs three things from the session: permission prompts bypassed (one prompt halts the
-loop), a loop to fire it — `/loop 5m /wdi-autopilot` in Claude Code — and a way past the ticket engines'
-`disable-model-invocation`, which the preflight names: a builder that reads and follows the engine's `SKILL.md`,
-or a copy of the engines inside the repo. The validator `mandate-accept` keeps the one thing the method never
-gives up: a person, dated, at the root of every delegated acceptance.
-**Refine, do not advance.** When a page does not convince you, run the same skill again and say what is
-wrong — it updates the document it owns. Nothing downstream exists yet, so nothing breaks. Advancing past a
-page you did not believe is how every later page inherits the doubt.
-**After the first pass**, steps 0–4 never run again for that product. The next component enters at step 5
-(or 6, at `catalog`); a new initiative enters at step 2; a small fix touching no `FR`, `UC`, `AD-N`, or
-domain model skips every gate and runs `/implement` directly — and **stops to become a spec `S`** the
-moment it touches an `FR`. `wdi-help` tells you which of these you are in; it reads the registry, not you.
----
-## Why the steps are in this order
-- **One question per gate.** The brief answers *why*, the PRD *what*, the blueprint *the whole*, the SDD
-  *how one part*, the spec *is it done*. Every document that grew unreadable did so by answering a
-  neighbour's question too. A gate that asks one question can be passed in ten minutes.
-- **The page you read is rendered; the page the AI edits points.** A goal lives once, in
-  `goals.yaml`; the working brief says `Goals — see goals.yaml`; the rendered brief shows the goals in
-  full. So the human gets a complete document and the corpus has no copies — and the validators check
-  **drift against the code**, never whether two copies agree, because there are none to compare.
-- **Cost follows the unit of change.** G3 is once per product because the portrait is one thing. G4 is per
-  component because that is what changes when you build. G5 is per spec because that is what ships.
-  Repeating the blueprint per component was the single largest waste the earlier shape carried.
-- **Two knobs that never merge.** `mode` decides which gates *exist* for a component (`catalog` skips G4
-  outright); `risk_accepted` decides how much *proof* a gate demands. Merged into one "rigor" dial, a
-  low-risk component either drowns in ceremony or a high-risk one escapes it.
-- **Estimate before build.** Step 6 derives the candidate tasks from the promises already made —
-  `CAP` and `FR` — so nobody invents a backlog. One candidate row becomes one spec, three neighbours
-  may merge into one, and the estimate page says so about itself: it is forward-looking, never a record.
-- **The engine cuts; the wrapper frames.** `to-spec` and `to-tickets` are the best ticket-cutting
-  engine we found: vertical tracer-bullet slices, blocking edges, a quiz with the owner. What a cutter
-  cannot know, `wdi-build` supplies: that every component the spec touches passed G4; that every ticket
-  names the `UC` it `satisfies`, so `FR → UC → ticket → test` stays one chain; that a spec restates
-  promises and never makes new ones; that code is judged by the test suite going red then green, from a
-  fresh context per step, never by a builder's report; and that a closed spec leaves the registry caught
-  up and the inventories re-derived from code.
-- **Documents follow the code.** At spec close the inventories are regenerated from what was built and
-  the difference is *reported*, never patched into agreement. A record that contradicts the code is
-  corrected; code is never changed to match a record.
----
-## The file tree, and why
-```
-.constitution/
-  method/            the method — overwritten by every update; never edit here
-  project/           your own rules and readers — kept by every update
-.control/
-  registry/          SSOT for every ROW: goals.yaml · requirements-<slug>.yaml · components.yaml
-                     usecases.yaml · specs.yaml · risks.yaml · defects.yaml · index.yaml
-  questions/         open questions, assumptions, external prerequisites — one row each
-  decisions/         DEC-N files; frozen once applied
-  generated/         machine tables: rtm · dag · status · estimate · timeline — regenerated, never edited
-.what/               what is PROMISED — the AI's working set, pointer-heavy, few files
-  _product-brief/brief.md
-  _prd/<slug>/prd.md · addendum.md
-  <pc>/SRS-<pc>.md + 02-rules · 03-domain · 04-usecases · 05-scenarios
-.how/                how it is BUILT — same discipline
-  _platform/         ARCHITECTURE-SPINE.md · c4-l2-containers.md · inventories
-  <pc>/SDD-<pc>.md + 01-ux · 02-contracts · 04-components · 05-model · 06-flows
-.what-rendered/      the human's tree: brief · _prd/<slug>/prd.md · <pc>/SRS-<pc>.md — one complete page each
-.how-rendered/       blueprint.md (root — it spans every component) · <pc>/SDD-<pc>.md
-_bmad-output/        a skill run's working output; empties as its spec closes
-.work/               scratch; empties when the task closes
-<spec_folder>/issues/  one file per ticket — the tracker's payload, not yours to read
-```
-Three layers, and the rule that keeps them honest:
-| Layer | Holds | Who writes | Who reads |
-|---|---|---|---|
-| **Registry** | every row — a goal, a requirement, a component, a ticket index | the skill that owns the gate | validators, renderers, every other skill |
-| **Working documents** (`.what/`, `.how/`) | the prose that reasons — why, boundaries, what makes it different — and **pointers** at the rows | the owning skill | the AI |
-| **Rendered pages** (`*-rendered/`) | one complete page per gate, rows filled in from their homes | `validate.py --generate`, never a hand | the human, and the client |
-Why split the human's tree from the AI's: a document that is both the AI's working surface and the
-human's deliverable ends up serving neither — too long to point, too gappy to hand over. Why the
-registry is per initiative (`requirements-<slug>.yaml`) but goals are per product: a capability is
-declared by one feature in one PRD; a goal belongs to the product before any PRD exists. Why
-`blueprint.md` sits at the root of `.how-rendered/` and not under `_platform/`: `_platform` means
-"belongs to no component"; the blueprint spans all of them. Why rendered pages are never a skill's
-input: a skill that read a projection would be reading a copy, and the copy would start to drift the
-day someone edited it. A test in this package fails if any `SKILL.md` lists a `-rendered` path as an
-Input.
----
-## Why WDI Method?
-- **Depth separate from scrutiny.** `mode` sets how much gets written; `risk_accepted` sets how hard it
-  gets reviewed. Neither is derived from the other, so a component MAY be thin on purpose and reviewed the
-  hardest.
-- **Ground truth over plan.** Once code exists, the tables, endpoints, and screens are **derived from it**
-  — the gap between plan and reality is a finding to resolve, not an argument to have.
-- **Containers that match what actually ships.** C4's containers follow deployability, not folders, and a
-  component view is drawn for every container that carries more than one Product Component.
-- **A gate that can be skipped honestly.** `mode: catalog` skips the component gate entirely — a fast
-  default is fast because the work is genuinely gone, not nominally trimmed.
-- **Decisions that don't rot.** A `DEC-` is recorded only when the reason would not survive reading the
-  code, and it freezes the moment it is applied — a change of mind writes a new one rather than editing
-  the old.
-- **Wraps BMad, never forks it.** Every `wdi-*` skill is a wrapper around a BMad skill. Upgrading BMad
-  does not strand you, and no BMad skill is meant to be invoked directly.
----
-## The gap this fills
-A gate is only as good as the artifact it reads. Between *"the architecture is decided"* and *"the code
-is written"* there is a set of questions that decide whether a build goes straight or crooked, and they
-are all **list-shaped**:
-- Which use cases exist, and which of them touch money, personal data, or something irreversible?
-- Which tables exist, and which component is allowed to **write** each one?
-- Which endpoints exist, on which host, and which promise does each serve?
-- Which screens exist, in which application?
-- When a boundary fails halfway — the other side slow, absent, or lying — what does the user see?
-Those questions have answers inside an architecture document and a build spec. What they usually do not
-have is a **place where a person can read all of one kind at once** and notice the row that is missing,
-the table with two owners, or the endpoint nobody promised.
-WDI Method's whole contribution is that place, plus the discipline that keeps it honest:
-| | |
-|---|---|
-| **Inventories** | Tables, endpoints, and screens as three flat lists — **derived from the code**, not hand-written, so the difference between plan and reality is a finding rather than an argument |
-| **Use case catalogue** | One line per use case with its actor, the requirement it satisfies, and whether it is `critical` |
-| **SRS / SDD** | What a component promises, and how it is built — one pair per component, in human language |
-| **C4** | Context, containers, and one component view per container that carries more than one domain slice |
-| **Robustness** | For the deepest mode: boundary, control, and entity objects per critical use case, before code |
-| **Invariants** | A spine of `AD-N` rules that constrain every component, separate from the decisions that produced them |
----
-## Two knobs, never merged
-The reason a method like this usually fails is that it asks for the same depth everywhere, so people
-either drown in it or abandon it. WDI splits depth from scrutiny into **two independent fields**:
-| Field | Controls | Values |
-|---|---|---|
-| `mode` | **Document depth**, and nothing else | `catalog` · `outline` · `guarded` · `deep` |
-| `risk_accepted` | **Review intensity**, and nothing else | `low` · `medium` · `high` |
-| `mode` | What is written per component | G4 |
-|---|---|---|
-| `catalog` | Nothing. Code is written from the use case catalogue, the three inventories, and C4 | **skipped** |
-| `outline` | + a decision summary and the component list in the SDD, full flows for at most 3 use cases, local rules | 20 min |
-| `guarded` | + **failure behaviour for every boundary**, inherited invariants quoted verbatim, integration documents | 20 min |
-| `deep` | + robustness analysis, a contract per endpoint, data dictionary, flow diagrams, state machines | 30 min |
-Neither field is derived from the other, and that is the point: **a component MAY be thin on purpose and
-reviewed the hardest.** A component at `catalog` skips the component gate entirely — which is what makes
-a shallow default genuinely fast rather than nominally fast.
-Depth is a preference and needs no defence. Accepting risk on something that touches money, personal
-data, or an irreversible action is **not** free: it requires a recorded decision, and a validator checks
-that the decision exists.
-All twelve combinations are legal. The installed kit carries
-`.constitution/method/why/mode-risk-map.md`, which puts them side by side — what each cell costs at G4,
-which review lenses run, and which review traces a validator will demand.
----
-## Five gates, eighteen skills
-| Gate | Decides | Skill |
-|---|---|---|
-| **G1 Problem** | What the problem is, whose it is, why it earns work | `wdi-problem` |
-| **G2 Product** | What is built, and how it feels to use | `wdi-product` · optional `wdi-ux` |
-| **G3 Blueprint** | The whole portrait, once per product | `wdi-blueprint` |
-| **G4 Component** | How one component is built — **skipped at `catalog`** | `wdi-component` |
-| **G5 Release** | Whether it is done and proven | `wdi-build` |
-Around them: `wdi-init` (scaffold, component birth, depth and risk settings, structure maps),
-`wdi-decision`, `wdi-question`, `wdi-log`, `wdi-help`, `wdi-explain-to-me`, `wdi-autopilot`, `wdi-reconcile`, `wdi-review`, `wdi-report`,
-`wdi-systematic-debugging`, and `wdi-upgrade` (moves a corpus written under an older kit into the current
-shape — content moves, nothing is invented).
-**No BMad skill is invoked directly.** Each has a wrapper, and the wrapper is what checks position,
-verifies the result, and records what happened.
-### Decisions, not ADRs
-A decision is a `DEC-`, and **recording one is not mandatory.** The test is one sentence: *if somebody
-asks in three months why it is like this, is the answer readable from the code?* If yes, it MUST NOT be
-recorded — a register nobody trusts is worse than no register. One case is mandatory: contradicting an
-invariant on the spine.
-A `DEC-` freezes when it is applied. A change of mind produces a new one; it never edits the old.
----
-## The mechanical half
-`validate.py` runs twenty-six named validators — `goal-has-fr`, `cites-resolve`, `no-cycles`,
-`id-allocated-once`, and the rest, each named for the thing it checks — over the registries and the
-corpus, and `inventory.py` derives the three inventories from code and reports the difference against the
-plan without patching either side. There is no validator that compares two copies of one fact, because
-the corpus keeps no copies.
-The validators exist because prose that nothing checks is prose that gets contradicted by the first
-person in a hurry. Every one of them also states **the state in which it does not apply** — a rule that
-demands a trace before the trace can exist is a rule that gets switched off, and a validator nobody
-reads guards nothing.
----
-## What is generic, and where your own rules live
-`.constitution/` holds **exactly two folders**, and the folder is the whole answer to who owns a file:
-| Folder | Owner | `update` | `promote` |
-|---|---|---|---|
-| `.constitution/method/` | the method | **overwritten** in full | carries it into the package |
-| **`.constitution/project/`** | you | **never touched** — seeded once when absent | never carries it, so your rules cannot be published |
-Everything in the room is yours: `project/constitution.md` (Articles 1, 2, 5 — scope, repo checklist,
-method ownership), `project/codebase-*-guide.md` (stack, conventions, brownfield, protected at **any**
-`status:` — `Draft` is when they actually get written), and any rule file you add.
-**The seam is a folder, never a marked region inside a generic file.** Prose has no merge algebra: you
-cannot "merge" your paragraph with the method's, so only a path can say unambiguously whose a file is.
-`AGENTS.md` is the one exception, and only because it is a single file with nowhere else to go.
-Two more things are yours, outside `.constitution/`:
-| Yours | Because |
-|---|---|
-| `.control/registry/index.yaml` → `product:` | The product and client name live in exactly one place |
-| `_bmad/custom/*.user.toml` | Your BMad overrides — TOML, so these genuinely merge: a string replaces, a list appends, a table merges per key |
-`.control/` `.what/` `.how/` are never touched by an update at all — they are your state, your promises,
-and your design.
-The custom room takes whole files, not marked blocks inside generic ones: `AGENTS.md` can use a marked
-block because it is *one* file, while `.constitution/` has fifty-odd, and blocks inside them would make
-an update perform surgery in every file. A file there declares `scope: project` and a one-line
-`purpose:`; to **contradict** a generic rule it must name that rule and carry the decision that allowed
-it. **An empty room is a valid state** — filling it so that it gets used is the failure the rule prevents.
-### Language
-Two settings, both free text, both defaulting to English:
-```yaml
-policy:
-  doc_language: "English"           # prose of working documents
-  doc_filename_language: "English"  # the slug part of a document filename
-```
-Write whatever names the language — `English`, `Bahasa Indonesia`, `id`. What reads the value is a model,
-and a model does not need a lookup table.
-Always English, and never asked: method terminology, document code prefixes (`UC-`, `DEC-`), machine
-markers (`[NEEDS CONFIRMATION]`, `[MISSING]`), and code identifiers. `.constitution/` itself is always
-English, whatever the settings say — it travels to every repo through this package.
----
-## What update does
-| | |
-|---|---|
-| Overwrites | everything in `.constitution/method/` · the eighteen wrappers · `_bmad/custom/*.toml` · the marked block in `AGENTS.md` |
-| Renames | a file whose content needs no judgment to move — `waves.yaml` → `specs.yaml`, the pre-0.5 registry names, and a pre-0.6.2 autopilot ledger to `autopilot-<mandate-id>.md`. Content is never rewritten |
-| Seeds | `docs/agents/` — the ticket engines' own config, already answered for this method, so `/setup-matt-pocock-skills` is not part of getting started. Seeded once; a file you already wrote is never touched |
-| Removes | Wrappers the method has retired — a `wdi-*` folder with a `SKILL.md` that is no longer one of the eighteen. Each removal is printed |
-| Reports | what is still in the OLD shape, as an `upgrade` line — and names `wdi-upgrade` as the next step. The installer does not move content; that is a decision, and the skill's |
-| Keeps | All of `.constitution/project/`, plus your initiative slug and your language choice. A setting somebody already chose is not the installer's to change behind their back |
-| Never resurrects | A folder you retired. On update, absence is treated as a decision |
-| Warns, never edits | An open `wdi-autopilot` mandate written before `ad-n` was parked by default, and a `docs/agents/domain.md` still pointing at a root `CONTEXT.md`. Both are values you chose; the installer names them and leaves them alone |
-It prints the version it replaced, what it wrote, what it kept, and what to do next.
----
-## Changing the method
-**This repository is where a method change is authored** — a guide, a template, a skill wrapper, a
-validator. It is proven here before publishing, against a fixture corpus the three registry scripts
-actually run against:
-```bash
-npm test        # includes validate.py, timeline.py and inventory.py over tests/fixture/
-```
-The fixture is small but complete, and kept **green**, so a new finding is a regression rather than
-noise. One test plants a defect in a copy and requires the matching validator to name it — a green
-baseline is worthless if it is green because every check is broken.
-A consuming repo then takes the change with `npx wdi-method update`, and that is where the judgement
-half gets tested: whether a guide actually helps a person at G3 is only provable in use.
-`promote` — pulling the method back out of a consumer — is a **rescue tool**, not the workflow. It
-overwrites the whole kit from one copy, so it refuses to run without `--rescue`.
-[`CONTRIBUTING.md`](CONTRIBUTING.md) records why the direction was reversed and what it cost.
-**Patch releases are routine; minor and major are the maintainer's call.** This package overwrites files
-in repos that already hold months of work, and the version is the only signal a reader has for how
-carefully to read the diff. [`CONTRIBUTING.md`](CONTRIBUTING.md) has the detail, and
-[`AGENTS.md`](AGENTS.md) states it for agents working on the package.
----
-## Support and Contributing
-Open an [issue](https://github.com/wiradigitalid/wdi-method/issues) for a bug or a proposal. Read
-[`CONTRIBUTING.md`](CONTRIBUTING.md) before sending a pull request — it explains where a change belongs,
-how versioning works here, and what to check before publishing.
-## License
-MIT — see [LICENSE](LICENSE). Requires Node 20+ and [uv](https://docs.astral.sh/uv/) for the Python
-scripts.
-[![Version](https://img.shields.io/npm/v/wdi-method?color=blue&label=version)](https://www.npmjs.com/package/wdi-method)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+# WDI Method
+**The review layer BMad leaves thin — documents a human reads to check a decision before code gets written, sized to what the change actually deserves.**
+[BMad](https://github.com/bmad-code-org/BMAD-METHOD) decides *what* to build and *how* to build it well. WDI Method wraps it — it does not replace it — and adds the part between those two decisions and the code: inventories, a use case catalogue, a component design record, and a way to choose how much of that a given change actually needs.
+> This repository is **public and generic**. It MUST NOT carry a client name, a product name, or a
+> link to a private repository — product identity lives entirely in the repo that installs it.
+---
+## Prerequisites — two engines, and both are required
+| Engine | What it does here | Source |
+|---|---|---|
+| **BMad Method** | Writes the documents behind G1–G4 — brief, PRD, architecture, UX | [github.com/bmad-code-org/BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) |
+| **mattpocock/skills** | Cuts the work at G5 — `to-spec`, `to-tickets`; runs the Fast Path and every `wdi-autopilot` iteration — `implement` | [github.com/mattpocock/skills](https://github.com/mattpocock/skills) |
+**The installer refuses without either.** BMad has always been checked. The ticket engines are checked
+too, since 0.6.4: G1–G4 genuinely run without them, and every repo that relied on that learned they were
+missing inside `wdi-build` with a spec already open. `--skip-engines-check` is the escape for the two
+cases that earn it — CI, and a repo that will never reach G5.
+No engine skill is invoked on its own. Each has a wrapper (`wdi-*`) that checks where the project is,
+runs the engine, verifies what came back, and records it. The engine is the pen; the wrapper knows what
+page it is on.
+---
+## Install
+Three steps, in this order. The first is required before step 3 will run; the second can wait until
+**Both are required, and the installer refuses without either.** BMad has always been checked; the ticket
+engines are checked too, because every repo that learned they were missing learned it inside `wdi-build`
+with a spec already open. `--skip-engines-check` is the escape for the two cases that earn it: CI, and a
+repo that will never reach G5.
+**1. BMad Method** — in the product repo, picking the same agents you will give this installer:
+```bash
+cd /path/to/your/product-repo
+npx bmad-method install
+```
+**2. mattpocock/skills** — one of the two paths, not both (both leaves every skill twice):
+```bash
+# Claude Code — a managed bundle that updates when its author ships
+claude plugins install mattpocock-skills      # or, inside a session:  /plugin install mattpocock-skills
+# Codex, Cursor, OpenCode, other agents — copies the skills into this repo; keep setup-matt-pocock-skills selected
+npx skills@latest add mattpocock/skills
+```
+**You do not need to run `/setup-matt-pocock-skills` to get started.** Step 3 seeds `docs/agents/` with
+the two answers WDI Method actually has a requirement on, so the engines are aligned from the first
+install. Run the setup skill only to *change* something — to point at GitHub or Jira instead of local
+markdown — and keep the three invariants the seeded `issue-tracker.md` names.
+The seeding exists because the interview's own defaults are wrong here in one specific way: they send every
+engineering skill looking for a root `CONTEXT.md` and `docs/adr/`, and Article 3 says this method has no
+`docs/` layer for corpus or rules — `wdi-reconcile` reports both as findings. A repo that ran the setup
+before installing this package keeps its own file, and the installer names the contradiction rather than
+overwriting it.
+**3. WDI Method:**
+```bash
+npx wdi-method
+```
+This opens a TUI: it checks BMad, reports whether it found the ticket engines, detects install versus
+update, asks the product name and the document language, lets you pick agents, shows what it will
+write, and prints what to do next.
+**Every field arrives with an answer already in it, and Enter accepts it.** On an update that answer is
+what the repo already says; on a first install the product name is the folder name made readable —
+`acme-billing-portal` offers `Acme Billing Portal`. Nothing is validated as required: a prompt that
+refuses an empty submission while already holding a sensible default is asking you to retype something
+the installer knows.
+A value only changes when you actually answer. A run that does not mention language keeps the language the
+repo already chose, and says so.
+```bash
+npx wdi-method@latest update      # later, to take a newer method — @latest, or npx may reuse a cached one
+npx wdi-method verify             # check the method files are all present
+```
+**Upgrading from 0.5.x to 0.6** is two halves. `update` does the mechanical one — overwrites the kit,
+renames files whose content needs no judgment, seeds what is new — and then prints an `upgrade` line
+naming what is still in the old shape: a single `requirements.yaml`, a 14-section brief, a PRD carrying
+its FR text. The second half is a decision about content, so it belongs to a skill:
+```bash
+npx wdi-method@latest update --yes      # 1 — mechanical; read the `upgrade` line it prints
+# 2 — in your agent, run the wdi-upgrade skill: it moves every sentence into its new home, word for
+#     word, invents nothing, reports what it could not place, and ends in one commit.
+```
+Run the skill before any other skill. `wdi-help` and the validators read the new shape; a corpus half
+in the old one answers them wrongly.
+Non-interactive, for CI:
+```bash
+npx wdi-method install --yes --agents claude,codex --product "Your Product" \
+  --doc-language "Bahasa Indonesia"
+```
+Then invoke the **`wdi-help`** skill and ask what to do next. It reads where the project actually is and
+answers with the gate you are at, not with a menu.
+---
+## What to do right after install, and right after update
+Two questions, and the honest answer to most of them is *nothing*. `wdi-help` answers them from the
+registry at any time; this table is the same answer written down.
+### After `install`
+| | |
+|---|---|
+| Engines missing | You never get here — `install` refuses, and names both install paths. Install them, run it again |
+| `/setup-matt-pocock-skills`? | **No.** The installer seeded `docs/agents/` already answered for this method. Run that interview only to *change* tracker |
+| So what is first? | **`wdi-init` intent `setup`** — it sets the global `mode`, and nothing has started until it is |
+| Then? | `wdi-problem` for G1. Or ask `wdi-help`, which reads the registry rather than this table |
+### After `update`
+| The summary said | Do |
+|---|---|
+| an **`upgrade`** line, naming content still in the old shape | **`wdi-upgrade`, before any other skill.** It moves every sentence into its new home, invents nothing, reports what it could not place, and ends in one commit. `wdi-help` and the validators read the new shape; a corpus half in the old one answers them wrongly |
+| **no** `upgrade` line | Nothing. The update was mechanical and complete — carry on from wherever the gates say you are |
+| `seeded docs/agents/` | Nothing. An older repo just received the engines' config, pre-answered. Read it if you like; do not run the setup interview to redo it |
+| a warning that `domain.md` still points at a root `CONTEXT.md` | Add the correction that warning names to the top of that file. It was written by the setup interview before this package was installed, and it sends every engineering skill at two paths Article 3 forbids |
+| a warning naming a **mandate** and `ad-n` | Only if you run `wdi-autopilot`. Decide whether that mandate should now park `AD-N` contradictions, and edit its `parked` list yourself — `update` never edits an authority you granted |
+**`wdi-upgrade` is only ever about corpus content** — a brief, a PRD, an SRS, registry rows in the old
+shape. It is not the answer to a missing engine, a missing tracker config, or anything under
+`.control/memlog/`; each of those is handled by the installer itself or by the skill that owns it.
+---
+## How to use it — the walk
+A gate is a moment where a human reads **one page** and decides. Between gates the AI works in a
+pointer-heavy working set it does not need you to read. So the walk is: run a skill, read the page it
+renders, decide — advance or refine.
+| # | You run | You read | You decide |
+|---|---|---|---|
+| 0 | `wdi-init` intent `setup` | — | the global `mode`: how deep this product goes by default |
+| 1 | `wdi-problem` | `.what-rendered/_product-brief/brief.md` | **G1** — is this the problem, whose is it, and does it earn the work? |
+| 2 | `wdi-product` intent `prd` — `wdi-ux` first when the interface *is* the promise | `.what-rendered/_prd/<slug>/prd.md` | **G2** — is this what we build, and how does it feel? |
+| 3 | `wdi-init` intent `component` | the rows it adds to `components.yaml` | each component's `mode` and `risk_accepted` |
+| 4 | `wdi-blueprint` — `catalog`, then `platform` | `.how-rendered/blueprint.md` | **G3** — does the whole hold together? **Once per product** |
+| 5 | `wdi-component` — one component | `.how-rendered/<pc>/SDD-<pc>.md` | **G4** — is this how we build it? **Skipped at `mode: catalog`** |
+| 6 | `wdi-report` intent `estimate` | `.control/generated/estimate.md` | which candidate row becomes the next spec |
+| 7 | `wdi-build` — for that row | nothing: tickets are machine contracts. You answer `to-tickets`' quiz on granularity and blocking edges | **G5** — is it done and proven? Once per spec |
+| 8 | `wdi-report` intent `progress` | the report it writes | what has moved, what is late, what is proven |
+| 9 | `wdi-autopilot` — when you would rather review the result than walk steps 6–8 yourself | its preflight page, then its final report and ledger | one **mandate**: scope, what stays parked for you, smoke test by the agent or by you, loop interval, expiry |
+**Unattended, on request.** `wdi-autopilot` moves owner time from the gates to two points: the mandate before,
+the review after. From the gate you name it runs the same skills, answers what they would have asked, records
+every answer in `.control/memlog/autopilot-<mandate-id>.md`, and returns at one of three stops — done,
+at capacity, or blocked. It finishes when every `FR` in scope is closed, when nothing left is runnable, or
+when the mandate expires. It needs three things from the session: permission prompts bypassed (one prompt halts the
+loop), a loop to fire it — `/loop 5m /wdi-autopilot` in Claude Code — and a way past the ticket engines'
+`disable-model-invocation`, which the preflight names: a builder that reads and follows the engine's `SKILL.md`,
+or a copy of the engines inside the repo. The validator `mandate-accept` keeps the one thing the method never
+gives up: a person, dated, at the root of every delegated acceptance.
+**Refine, do not advance.** When a page does not convince you, run the same skill again and say what is
+wrong — it updates the document it owns. Nothing downstream exists yet, so nothing breaks. Advancing past a
+page you did not believe is how every later page inherits the doubt.
+**After the first pass**, steps 0–4 never run again for that product. The next component enters at step 5
+(or 6, at `catalog`); a new initiative enters at step 2; a small fix touching no `FR`, `UC`, `AD-N`, or
+domain model skips every gate and runs `/implement` directly — and **stops to become a spec `S`** the
+moment it touches an `FR`. `wdi-help` tells you which of these you are in; it reads the registry, not you.
+---
+## Why the steps are in this order
+- **One question per gate.** The brief answers *why*, the PRD *what*, the blueprint *the whole*, the SDD
+  *how one part*, the spec *is it done*. Every document that grew unreadable did so by answering a
+  neighbour's question too. A gate that asks one question can be passed in ten minutes.
+- **The page you read is rendered; the page the AI edits points.** A goal lives once, in
+  `goals.yaml`; the working brief says `Goals — see goals.yaml`; the rendered brief shows the goals in
+  full. So the human gets a complete document and the corpus has no copies — and the validators check
+  **drift against the code**, never whether two copies agree, because there are none to compare.
+- **Cost follows the unit of change.** G3 is once per product because the portrait is one thing. G4 is per
+  component because that is what changes when you build. G5 is per spec because that is what ships.
+  Repeating the blueprint per component was the single largest waste the earlier shape carried.
+- **Two knobs that never merge.** `mode` decides which gates *exist* for a component (`catalog` skips G4
+  outright); `risk_accepted` decides how much *proof* a gate demands. Merged into one "rigor" dial, a
+  low-risk component either drowns in ceremony or a high-risk one escapes it.
+- **Estimate before build.** Step 6 derives the candidate tasks from the promises already made —
+  `CAP` and `FR` — so nobody invents a backlog. One candidate row becomes one spec, three neighbours
+  may merge into one, and the estimate page says so about itself: it is forward-looking, never a record.
+- **The engine cuts; the wrapper frames.** `to-spec` and `to-tickets` are the best ticket-cutting
+  engine we found: vertical tracer-bullet slices, blocking edges, a quiz with the owner. What a cutter
+  cannot know, `wdi-build` supplies: that every component the spec touches passed G4; that every ticket
+  names the `UC` it `satisfies`, so `FR → UC → ticket → test` stays one chain; that a spec restates
+  promises and never makes new ones; that code is judged by the test suite going red then green, from a
+  fresh context per step, never by a builder's report; and that a closed spec leaves the registry caught
+  up and the inventories re-derived from code.
+- **Documents follow the code.** At spec close the inventories are regenerated from what was built and
+  the difference is *reported*, never patched into agreement. A record that contradicts the code is
+  corrected; code is never changed to match a record.
+---
+## The file tree, and why
+```
+.constitution/
+  method/            the method — overwritten by every update; never edit here
+  project/           your own rules and readers — kept by every update
+.control/
+  registry/          SSOT for every ROW: goals.yaml · requirements-<slug>.yaml · components.yaml
+                     usecases.yaml · specs.yaml · risks.yaml · defects.yaml · index.yaml
+  questions/         open questions, assumptions, external prerequisites — one row each
+  decisions/         DEC-N files; frozen once applied
+  generated/         machine tables: rtm · dag · status · estimate · timeline — regenerated, never edited
+.what/               what is PROMISED — the AI's working set, pointer-heavy, few files
+  _product-brief/brief.md
+  _prd/<slug>/prd.md · addendum.md
+  <pc>/SRS-<pc>.md + 02-rules · 03-domain · 04-usecases · 05-scenarios
+.how/                how it is BUILT — same discipline
+  _platform/         ARCHITECTURE-SPINE.md · c4-l2-containers.md · inventories
+  <pc>/SDD-<pc>.md + 01-ux · 02-contracts · 04-components · 05-model · 06-flows
+.what-rendered/      the human's tree: brief · _prd/<slug>/prd.md · <pc>/SRS-<pc>.md — one complete page each
+.how-rendered/       blueprint.md (root — it spans every component) · <pc>/SDD-<pc>.md
+_bmad-output/        a skill run's working output; empties as its spec closes
+.work/               scratch; empties when the task closes
+<spec_folder>/issues/  one file per ticket — the tracker's payload, not yours to read
+```
+Three layers, and the rule that keeps them honest:
+| Layer | Holds | Who writes | Who reads |
+|---|---|---|---|
+| **Registry** | every row — a goal, a requirement, a component, a ticket index | the skill that owns the gate | validators, renderers, every other skill |
+| **Working documents** (`.what/`, `.how/`) | the prose that reasons — why, boundaries, what makes it different — and **pointers** at the rows | the owning skill | the AI |
+| **Rendered pages** (`*-rendered/`) | one complete page per gate, rows filled in from their homes | `validate.py --generate`, never a hand | the human, and the client |
+Why split the human's tree from the AI's: a document that is both the AI's working surface and the
+human's deliverable ends up serving neither — too long to point, too gappy to hand over. Why the
+registry is per initiative (`requirements-<slug>.yaml`) but goals are per product: a capability is
+declared by one feature in one PRD; a goal belongs to the product before any PRD exists. Why
+`blueprint.md` sits at the root of `.how-rendered/` and not under `_platform/`: `_platform` means
+"belongs to no component"; the blueprint spans all of them. Why rendered pages are never a skill's
+input: a skill that read a projection would be reading a copy, and the copy would start to drift the
+day someone edited it. A test in this package fails if any `SKILL.md` lists a `-rendered` path as an
+Input.
+---
+## Why WDI Method?
+- **Depth separate from scrutiny.** `mode` sets how much gets written; `risk_accepted` sets how hard it
+  gets reviewed. Neither is derived from the other, so a component MAY be thin on purpose and reviewed the
+  hardest.
+- **Ground truth over plan.** Once code exists, the tables, endpoints, and screens are **derived from it**
+  — the gap between plan and reality is a finding to resolve, not an argument to have.
+- **Containers that match what actually ships.** C4's containers follow deployability, not folders, and a
+  component view is drawn for every container that carries more than one Product Component.
+- **A gate that can be skipped honestly.** `mode: catalog` skips the component gate entirely — a fast
+  default is fast because the work is genuinely gone, not nominally trimmed.
+- **Decisions that don't rot.** A `DEC-` is recorded only when the reason would not survive reading the
+  code, and it freezes the moment it is applied — a change of mind writes a new one rather than editing
+  the old.
+- **Wraps BMad, never forks it.** Every `wdi-*` skill is a wrapper around a BMad skill. Upgrading BMad
+  does not strand you, and no BMad skill is meant to be invoked directly.
+---
+## The gap this fills
+A gate is only as good as the artifact it reads. Between *"the architecture is decided"* and *"the code
+is written"* there is a set of questions that decide whether a build goes straight or crooked, and they
+are all **list-shaped**:
+- Which use cases exist, and which of them touch money, personal data, or something irreversible?
+- Which tables exist, and which component is allowed to **write** each one?
+- Which endpoints exist, on which host, and which promise does each serve?
+- Which screens exist, in which application?
+- When a boundary fails halfway — the other side slow, absent, or lying — what does the user see?
+Those questions have answers inside an architecture document and a build spec. What they usually do not
+have is a **place where a person can read all of one kind at once** and notice the row that is missing,
+the table with two owners, or the endpoint nobody promised.
+WDI Method's whole contribution is that place, plus the discipline that keeps it honest:
+| | |
+|---|---|
+| **Inventories** | Tables, endpoints, and screens as three flat lists — **derived from the code**, not hand-written, so the difference between plan and reality is a finding rather than an argument |
+| **Use case catalogue** | One line per use case with its actor, the requirement it satisfies, and whether it is `critical` |
+| **SRS / SDD** | What a component promises, and how it is built — one pair per component, in human language |
+| **C4** | Context, containers, and one component view per container that carries more than one domain slice |
+| **Robustness** | For the deepest mode: boundary, control, and entity objects per critical use case, before code |
+| **Invariants** | A spine of `AD-N` rules that constrain every component, separate from the decisions that produced them |
+---
+## Two knobs, never merged
+The reason a method like this usually fails is that it asks for the same depth everywhere, so people
+either drown in it or abandon it. WDI splits depth from scrutiny into **two independent fields**:
+| Field | Controls | Values |
+|---|---|---|
+| `mode` | **Document depth**, and nothing else | `catalog` · `outline` · `guarded` · `deep` |
+| `risk_accepted` | **Review intensity**, and nothing else | `low` · `medium` · `high` |
+| `mode` | What is written per component | G4 |
+|---|---|---|
+| `catalog` | Nothing. Code is written from the use case catalogue, the three inventories, and C4 | **skipped** |
+| `outline` | + a decision summary and the component list in the SDD, full flows for at most 3 use cases, local rules | 20 min |
+| `guarded` | + **failure behaviour for every boundary**, inherited invariants quoted verbatim, integration documents | 20 min |
+| `deep` | + robustness analysis, a contract per endpoint, data dictionary, flow diagrams, state machines | 30 min |
+Neither field is derived from the other, and that is the point: **a component MAY be thin on purpose and
+reviewed the hardest.** A component at `catalog` skips the component gate entirely — which is what makes
+a shallow default genuinely fast rather than nominally fast.
+Depth is a preference and needs no defence. Accepting risk on something that touches money, personal
+data, or an irreversible action is **not** free: it requires a recorded decision, and a validator checks
+that the decision exists.
+All twelve combinations are legal. The installed kit carries
+`.constitution/method/why/mode-risk-map.md`, which puts them side by side — what each cell costs at G4,
+which review lenses run, and which review traces a validator will demand.
+---
+## Five gates, eighteen skills
+| Gate | Decides | Skill |
+|---|---|---|
+| **G1 Problem** | What the problem is, whose it is, why it earns work | `wdi-problem` |
+| **G2 Product** | What is built, and how it feels to use | `wdi-product` · optional `wdi-ux` |
+| **G3 Blueprint** | The whole portrait, once per product | `wdi-blueprint` |
+| **G4 Component** | How one component is built — **skipped at `catalog`** | `wdi-component` |
+| **G5 Release** | Whether it is done and proven | `wdi-build` |
+Around them: `wdi-init` (scaffold, component birth, depth and risk settings, structure maps),
+`wdi-decision`, `wdi-question`, `wdi-log`, `wdi-help`, `wdi-explain-to-me`, `wdi-autopilot`, `wdi-reconcile`, `wdi-review`, `wdi-report`,
+`wdi-systematic-debugging`, and `wdi-upgrade` (moves a corpus written under an older kit into the current
+shape — content moves, nothing is invented).
+**No BMad skill is invoked directly.** Each has a wrapper, and the wrapper is what checks position,
+verifies the result, and records what happened.
+### Decisions, not ADRs
+A decision is a `DEC-`, and **recording one is not mandatory.** The test is one sentence: *if somebody
+asks in three months why it is like this, is the answer readable from the code?* If yes, it MUST NOT be
+recorded — a register nobody trusts is worse than no register. One case is mandatory: contradicting an
+invariant on the spine.
+A `DEC-` freezes when it is applied. A change of mind produces a new one; it never edits the old.
+---
+## The mechanical half
+`validate.py` runs twenty-seven named validators — `goal-has-fr`, `cites-resolve`, `no-cycles`,
+`id-allocated-once`, and the rest, each named for the thing it checks — over the registries and the
+corpus, and `inventory.py` derives the three inventories from code and reports the difference against the
+plan without patching either side. There is no validator that compares two copies of one fact, because
+the corpus keeps no copies.
+The validators exist because prose that nothing checks is prose that gets contradicted by the first
+person in a hurry. Every one of them also states **the state in which it does not apply** — a rule that
+demands a trace before the trace can exist is a rule that gets switched off, and a validator nobody
+reads guards nothing.
+---
+## What is generic, and where your own rules live
+`.constitution/` holds **exactly two folders**, and the folder is the whole answer to who owns a file:
+| Folder | Owner | `update` | `promote` |
+|---|---|---|---|
+| `.constitution/method/` | the method | **overwritten** in full | carries it into the package |
+| **`.constitution/project/`** | you | **never touched** — seeded once when absent | never carries it, so your rules cannot be published |
+Everything in the room is yours: `project/constitution.md` (Articles 1, 2, 5 — scope, repo checklist,
+method ownership), `project/codebase-*-guide.md` (stack, conventions, brownfield, protected at **any**
+`status:` — `Draft` is when they actually get written), and any rule file you add.
+**The seam is a folder, never a marked region inside a generic file.** Prose has no merge algebra: you
+cannot "merge" your paragraph with the method's, so only a path can say unambiguously whose a file is.
+`AGENTS.md` is the one exception, and only because it is a single file with nowhere else to go.
+Two more things are yours, outside `.constitution/`:
+| Yours | Because |
+|---|---|
+| `.control/registry/index.yaml` → `product:` | The product and client name live in exactly one place |
+| `_bmad/custom/*.user.toml` | Your BMad overrides — TOML, so these genuinely merge: a string replaces, a list appends, a table merges per key |
+`.control/` `.what/` `.how/` are never touched by an update at all — they are your state, your promises,
+and your design.
+The custom room takes whole files, not marked blocks inside generic ones: `AGENTS.md` can use a marked
+block because it is *one* file, while `.constitution/` has fifty-odd, and blocks inside them would make
+an update perform surgery in every file. A file there declares `scope: project` and a one-line
+`purpose:`; to **contradict** a generic rule it must name that rule and carry the decision that allowed
+it. **An empty room is a valid state** — filling it so that it gets used is the failure the rule prevents.
+### Language
+Two settings, both free text, both defaulting to English:
+```yaml
+policy:
+  doc_language: "English"           # prose of working documents
+  doc_filename_language: "English"  # the slug part of a document filename
+```
+Write whatever names the language — `English`, `Bahasa Indonesia`, `id`. What reads the value is a model,
+and a model does not need a lookup table.
+Always English, and never asked: method terminology, document code prefixes (`UC-`, `DEC-`), machine
+markers (`[NEEDS CONFIRMATION]`, `[MISSING]`), and code identifiers. `.constitution/` itself is always
+English, whatever the settings say — it travels to every repo through this package.
+---
+## What update does
+| | |
+|---|---|
+| Overwrites | everything in `.constitution/method/` · the eighteen wrappers · `_bmad/custom/*.toml` · the marked block in `AGENTS.md` |
+| Renames | a file whose content needs no judgment to move — `waves.yaml` → `specs.yaml`, the pre-0.5 registry names, and a pre-0.6.2 autopilot ledger to `autopilot-<mandate-id>.md`. Content is never rewritten |
+| Seeds | `docs/agents/` — the ticket engines' own config, already answered for this method, so `/setup-matt-pocock-skills` is not part of getting started. Seeded once; a file you already wrote is never touched |
+| Removes | Wrappers the method has retired — a `wdi-*` folder with a `SKILL.md` that is no longer one of the eighteen. Each removal is printed |
+| Reports | what is still in the OLD shape, as an `upgrade` line — and names `wdi-upgrade` as the next step. The installer does not move content; that is a decision, and the skill's |
+| Keeps | All of `.constitution/project/`, plus your initiative slug and your language choice. A setting somebody already chose is not the installer's to change behind their back |
+| Never resurrects | A folder you retired. On update, absence is treated as a decision |
+| Warns, never edits | An open `wdi-autopilot` mandate written before `ad-n` was parked by default, and a `docs/agents/domain.md` still pointing at a root `CONTEXT.md`. Both are values you chose; the installer names them and leaves them alone |
+It prints the version it replaced, what it wrote, what it kept, and what to do next.
+---
+## Changing the method
+**This repository is where a method change is authored** — a guide, a template, a skill wrapper, a
+validator. It is proven here before publishing, against a fixture corpus the three registry scripts
+actually run against:
+```bash
+npm test        # includes validate.py, timeline.py and inventory.py over tests/fixture/
+```
+The fixture is small but complete, and kept **green**, so a new finding is a regression rather than
+noise. One test plants a defect in a copy and requires the matching validator to name it — a green
+baseline is worthless if it is green because every check is broken.
+A consuming repo then takes the change with `npx wdi-method update`, and that is where the judgement
+half gets tested: whether a guide actually helps a person at G3 is only provable in use.
+`promote` — pulling the method back out of a consumer — is a **rescue tool**, not the workflow. It
+overwrites the whole kit from one copy, so it refuses to run without `--rescue`.
+[`CONTRIBUTING.md`](CONTRIBUTING.md) records why the direction was reversed and what it cost.
+**Patch releases are routine; minor and major are the maintainer's call.** This package overwrites files
+in repos that already hold months of work, and the version is the only signal a reader has for how
+carefully to read the diff. [`CONTRIBUTING.md`](CONTRIBUTING.md) has the detail, and
+[`AGENTS.md`](AGENTS.md) states it for agents working on the package.
+---
+## Support and Contributing
+Open an [issue](https://github.com/wiradigitalid/wdi-method/issues) for a bug or a proposal. Read
+[`CONTRIBUTING.md`](CONTRIBUTING.md) before sending a pull request — it explains where a change belongs,
+how versioning works here, and what to check before publishing.
+## License
+MIT — see [LICENSE](LICENSE). Requires Node 20+ and [uv](https://docs.astral.sh/uv/) for the Python
+scripts.
+[![Version](https://img.shields.io/npm/v/wdi-method?color=blue&label=version)](https://www.npmjs.com/package/wdi-method)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)