wdi-method 0.4.6 → 0.5.2

package/kit-overlay/portability.md

@@ -22,14 +22,14 @@ them only an *example* does — not a rule.
 
 | File | What is this product's | What to do when carrying it |
 |---|---|---|
-| `constitution.md` | Articles 1, 2, and 5 | **Rewrite 2 and 5.** Article 1 cites `index.yaml` `product.name`. Articles 3, 4, 6, 7 travel unchanged. `wdi-method promote` already replaces this file with the kit template |
-| `document/architecture-guide.md` | Seed examples of stack and tree shape | Re-point the examples. Every rule around them travels |
-| `document/corpus-guide.md` | Worked examples of `_platform` ownership | Re-point the examples. **Keep both kinds**: they teach the trap better than the rule alone |
+| `../constitution.md` | Articles 1, 2, and 5 | **Rewrite 2 and 5.** Article 1 cites `index.yaml` `product.name`. Articles 3, 4, 6, 7 travel unchanged. `wdi-method promote` already replaces this file with the kit template |
+| `../document/architecture-guide.md` | Seed examples of stack and tree shape | Re-point the examples. Every rule around them travels |
+| `../document/corpus-guide.md` | Worked examples of `_platform` ownership | Re-point the examples. **Keep both kinds**: they teach the trap better than the rule alone |
 | `templates/design-system.md` | The pointer to wherever this project keeps its tokens | Re-point at that project's token file |
 | `templates/oq.md` | One example of a bad question title | Cosmetic |
 
 Everything else — the five gates, the two fields, the fifteen skills, the templates, `validate.py`,
-`inventory.py`, `method-glossary.md`, and the three files beside this one — carries without edit.
+`inventory.py`, `../method-glossary.md`, and the three files beside this one — carries without edit.
 
 ## What does NOT travel
 
@@ -37,7 +37,7 @@ Everything else — the five gates, the two fields, the fifteen skills, the temp
 |---|---|
 | `.control/` | This product's state. A new project scaffolds its own through `wdi-init` intent `setup`, or receives empty stubs on first `install` |
 | `.what/` · `.how/` | This product's promises and build |
-| `.constitution/codebase/*-guide.md` | Written by the **project**, not the method. They ship as empty `Draft` stubs |
+| `.constitution/project/codebase-*-guide.md` | Written by the **project**, not the method. They ship as empty `Draft` stubs |
 | `_bmad-output/` | Run workspace |
 | The `bmad-*` skills themselves | BMad's, installed by BMad. Only `_bmad/custom/*.toml` is ours |
 
@@ -75,7 +75,7 @@ the steps that a runbook used to carry are now `wdi-init` intent `setup`. The or
 
 1. `npx bmad-method install` in the product repo.
 2. `npx wdi-method install` (optionally `--agents …`).
-3. Set `product.name` in `.control/registry/index.yaml`. Rewrite `constitution.md` Articles 2 and 5.
+3. Set `product.name` in `.control/registry/index.yaml`. Rewrite `../constitution.md` Articles 2 and 5.
 4. Merge the method routing into `AGENTS.md` if that file already existed.
 5. Run `wdi-init` intent `setup`.
 6. Sort what already existed. A file that is already the artifact one slot asks for goes into that

package/kit-overlay/repo-guide.md

@@ -1,97 +1,120 @@
----
-status: Accepted
----
-
-# Repo Guide
-
-**Loaded when:** adding a file that is neither code nor corpus, or unsure whether something may be
-kept in this repo
-
-Every other guide answers *where in the corpus does this go*. This one answers the question that
-comes before it: **does it belong in this repository at all?**
-
-## What this repository is
-
-One product, built for one owner. It holds what is needed to build and run that product, and
-nothing that merely relates to it commercially or organisationally.
-
-| MAY be here | MUST NOT be here |
-|---|---|
-| Application code, configuration, migrations, tests | Proposals, contracts, meeting notes with the client |
-| The corpus — `.constitution/` `.control/` `.what/` `.how/` | Contract values, pricing strategy, margins, rate cards |
-| Technical documentation, ADR, diagrams | Real customer data, production credentials, tokens |
-| Synthetic seed data | Anything whose leak would harm a bargaining position |
-| Built deliverables | An archive of commercial documents |
-
-The test is not "is it secret". It is **what changes when this file changes** — a commitment, or how
-the thing is built. Only the second belongs here.
-
-## Two failure modes, and why the second is worse
-
-The obvious one is a credential in a commit. It is loud, it is caught, and it has a known remedy.
-
-The quiet one is a **commercial fact restated as a technical one** — a limit that exists because of
-what was negotiated, written into an ADR as though it were an engineering constraint. It survives
-every scan, it is never noticed as a leak, and it teaches the next reader that the boundary is
-soft.
-
-When a technical decision genuinely follows from a commercial one, the ADR MUST state the technical
-fact and MUST NOT state the commercial one. *"Retention is 90 days"* is a technical fact.
-*"Retention is 90 days because the client would not pay for more"* is a commercial one wearing a
-technical coat.
-
-## `.work/` — scratch that is committed
-
-`.work/` holds work in progress that has no home yet: notes while reading an unfamiliar system,
-drafts, exploratory output, a working paper for a change spanning several sessions.
-
-It is **committed**, so that a session picked up on another machine finds it, and so a reviewer can
-see what a change was actually reasoning about.
-
-It is **ephemeral**, and the two together are what make its rules matter:
-
-- Any durable outcome MUST be moved out before the task closes — to the corpus if it is truth, to
-  `_bmad-output/` if it is a run's byproduct.
-- Obsolete scratch MUST be deleted when its task closes. `.work/` that only grows stops being
-  scratch and becomes a second, unindexed corpus that nobody trusts and nobody deletes.
-- Secrets and commercial figures MUST NOT be written here. Being scratch is not an exemption; it is
-  the reason people assume it is one.
-- Nothing MUST be read from `.work/` as authority. If something there is right, it belongs
-  somewhere with an owner.
-
-`.work/` MUST NOT be confused with `_bmad-output/`. That folder holds the output of skill runs, is
-never curated, and is cited by path. `.work/` holds what a human or agent wrote by hand while
-working, and is meant to empty out.
-
-## Referring to things outside this repository
-
-Engagement context — who the client is, what was agreed, what is due — lives elsewhere. This repo
-MUST work without it. An agent MUST be able to act on the rules stated here without opening any
-other repository.
-
-When an artifact genuinely needs external context:
-
-- MUST state the technical fact locally, in full.
-- MAY name the external source by **repository and path**, as provenance.
-- MUST NOT paste the external content in, and MUST NOT replace a technical statement with a pointer
-  to a commercial document.
-
-A pointer where a specification should be is the failure this rule exists to stop: the reader who
-cannot open that path is left with nothing, and the reader who can is reading the wrong kind of
-document.
-
-## How the method arrives
-
-Method files in `.constitution/` (except this product's Articles 1, 2, and 5, `codebase/*-guide.md`
-once `Accepted`, and any extra file this repo added), the `wdi-*` skills, and `_bmad/custom/*.toml`
-arrive from the public WDI Method package via `npx wdi-method install` / `update`.
-
-At **read time** this repo is self-contained: every file the rules need is here, readable with the
-repo alone. At **change time** the method has one published writer — the WDI Method package. Two
-rules follow:
-
-- A method file MUST NOT be invented or patched here to improve the method. If a rule is wrong, it
-  is fixed in the WDI Method package, then brought here with `update`.
-- A rule particular to this repo MUST be written out in full, and MUST NOT be replaced by a pointer
-  into another repository.
-
+---
+status: Accepted
+---
+
+# Repo Guide
+
+**Loaded when:** adding a file that is neither code nor corpus, or unsure whether something may be
+kept in this repo
+
+Every other guide answers *where in the corpus does this go*. This one answers the question that
+comes before it: **does it belong in this repository at all?**
+
+## What this repository is
+
+One product, built for one owner. It holds what is needed to build and run that product, and
+nothing that merely relates to it commercially or organisationally.
+
+| MAY be here | MUST NOT be here |
+|---|---|
+| Application code, configuration, migrations, tests | Proposals, contracts, meeting notes with the client |
+| The corpus — `.constitution/` `.control/` `.what/` `.how/` | Contract values, pricing strategy, margins, rate cards |
+| Technical documentation, ADR, diagrams | Real customer data, production credentials, tokens |
+| Synthetic seed data | Anything whose leak would harm a bargaining position |
+| Built deliverables | An archive of commercial documents |
+
+The test is not "is it secret". It is **what changes when this file changes** — a commitment, or how
+the thing is built. Only the second belongs here.
+
+## Two failure modes, and why the second is worse
+
+The obvious one is a credential in a commit. It is loud, it is caught, and it has a known remedy.
+
+The quiet one is a **commercial fact restated as a technical one** — a limit that exists because of
+what was negotiated, written into an ADR as though it were an engineering constraint. It survives
+every scan, it is never noticed as a leak, and it teaches the next reader that the boundary is
+soft.
+
+When a technical decision genuinely follows from a commercial one, the ADR MUST state the technical
+fact and MUST NOT state the commercial one. *"Retention is 90 days"* is a technical fact.
+*"Retention is 90 days because the client would not pay for more"* is a commercial one wearing a
+technical coat.
+
+## `.work/` — scratch that is committed
+
+`.work/` holds work in progress that has no home yet: notes while reading an unfamiliar system,
+drafts, exploratory output, a working paper for a change spanning several sessions.
+
+It is **committed**, so that a session picked up on another machine finds it, and so a reviewer can
+see what a change was actually reasoning about.
+
+It is **ephemeral**, and the two together are what make its rules matter:
+
+- Any durable outcome MUST be moved out before the task closes — to the corpus if it is truth, to
+  `_bmad-output/` if it is a run's byproduct.
+- Obsolete scratch MUST be deleted when its task closes. `.work/` that only grows stops being
+  scratch and becomes a second, unindexed corpus that nobody trusts and nobody deletes.
+- Secrets and commercial figures MUST NOT be written here. Being scratch is not an exemption; it is
+  the reason people assume it is one.
+- Nothing MUST be read from `.work/` as authority. If something there is right, it belongs
+  somewhere with an owner.
+
+`.work/` MUST NOT be confused with `_bmad-output/`. That folder holds the output of skill runs, is
+never curated, and is cited by path. `.work/` holds what a human or agent wrote by hand while
+working, and is meant to empty out.
+
+## Referring to things outside this repository
+
+Engagement context — who the client is, what was agreed, what is due — lives elsewhere. This repo
+MUST work without it. An agent MUST be able to act on the rules stated here without opening any
+other repository.
+
+When an artifact genuinely needs external context:
+
+- MUST state the technical fact locally, in full.
+- MAY name the external source by **repository and path**, as provenance.
+- MUST NOT paste the external content in, and MUST NOT replace a technical statement with a pointer
+  to a commercial document.
+
+A pointer where a specification should be is the failure this rule exists to stop: the reader who
+cannot open that path is left with nothing, and the reader who can is reading the wrong kind of
+document.
+
+## How the method arrives
+
+Method files in `.constitution/`, the `wdi-*` skills, and `_bmad/custom/*.toml` arrive from the
+public WDI Method package via `npx wdi-method install` / `update`.
+
+`.constitution/` holds **exactly two folders**, and which one a file is in decides who owns it:
+
+| Folder | Owner | On `update` | On `promote` |
+|---|---|---|---|
+| `method/` | the method | **overwritten** in full | carried into the package |
+| `project/` | this product | **never touched** — seeded once when absent | **never carried**, so a product's rules cannot be published |
+
+Everything in the room is yours: `project/constitution.md` (Articles 1, 2, 5),
+`project/codebase-*-guide.md` (stack, conventions, brownfield — protected at **any** `status:`,
+including `Draft`, which is when they are actually written), and any rule file you add.
+
+**A file this product adds belongs in `project/`.** `.constitution/` holds two folders and nothing
+else the method knows about, so a loose `.md` at its root is in a state no rule describes: `update`
+leaves it (it is not the method's) and no guide names it. Migration deliberately does NOT move one —
+it may already be pointed at by its current path from `AGENTS.md` or an editor rule the installer
+cannot see — so it prints the filename and leaves the choice to you. Either move it into `project/`
+and fix those pointers, or name it from Article 2 so the next reader knows why it is there. Leaving
+it unnamed is the only wrong answer.
+
+The seam is the **folder**, never a marked region inside a generic file. `AGENTS.md` uses a marked
+block because it is one file with no alternative; `.constitution/` has fifty-odd, and blocks inside
+them would make every update perform surgery in every file. Prose has no merge algebra — only a path
+can say, unambiguously, whose a file is.
+
+At **read time** this repo is self-contained: every file the rules need is here, readable with the
+repo alone. At **change time** the method has one published writer — the WDI Method package. Two
+rules follow:
+
+- A method file MUST NOT be invented or patched here to improve the method. If a rule is wrong, it
+  is fixed in the WDI Method package, then brought here with `update`.
+- A rule particular to this repo MUST be written out in full, and MUST NOT be replaced by a pointer
+  into another repository.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wdi-method",
-  "version": "0.4.6",
+  "version": "0.5.2",
   "description": "WDI Method — software delivery method that wraps BMad",
   "type": "module",
   "bin": {
@@ -20,7 +20,9 @@
   },
   "scripts": {
     "test": "node --test tests/*.test.mjs",
-    "prepublishOnly": "node --test tests/*.test.mjs"
+    "prepublishOnly": "node --test tests/*.test.mjs",
+    "overlay": "node scripts/apply-overlay.mjs",
+    "pretest": "node scripts/apply-overlay.mjs"
   },
   "dependencies": {
     "@clack/prompts": "^0.11.0"

package/scaffold/.control/questions/blocking.md

@@ -3,7 +3,7 @@
 **Loaded when:** every gate.
 
 Only this file holds a gate. Written through `wdi-question`, never by hand directly; the row shape
-lives in `.constitution/document/templates/questions.md`.
+lives in `.constitution/method/document/templates/questions.md`.
 
 Target **<=3 rows per Product Component**. A question rises to here only through three tests, one is
 enough:

package/kit/.constitution/README.md

@@ -1,66 +0,0 @@
----
-status: Reference
----
-
-# `.constitution/` — index
-
-Method files arrive from the public WDI Method package via `npx wdi-method install`
-or `update`. Load [`constitution.md`](constitution.md) before acting. Guides are
-loaded **lazily** — only when the task matches, and every guide states when on its
-own **Loaded when:** line.
-
-Every file here carries a `status:` — Article 4 owns the five values. Only `Accepted` binds;
-`Reference` explains and MUST NOT be cited to reject a change. A template carries no status of its
-own, because its frontmatter belongs to the artifact it produces.
-
-A file this product added (one that is not in the snapshot) stays here across `update` and MUST be
-listed from `constitution.md` Article 2 or from `AGENTS.md` routing — this index is overwritten on
-every update.
-
-## `method/` — the explanation, `status: Reference`
-
-Never a rule. When it disagrees with a guide, the guide wins and the disagreement is a defect.
-
-| File | Opened when |
-|---|---|
-| [`method/README.md`](method/README.md) | You want the whole shape in five minutes — five gates, two settings, fifteen skills, WDI ↔ BMad |
-| [`method/artifact-map.md`](method/artifact-map.md) | "Where does this file go", or "does this document exist at my `mode`" |
-| [`method/rationale.md`](method/rationale.md) | Before changing a rule, to know what you would break |
-| [`method/portability.md`](method/portability.md) | Which files are the method and which are the product; how promote and install move them |
-
-## Cross-domain
-
-| File | Loaded when |
-|---|---|
-| [`repo-guide.md`](repo-guide.md) | Adding a file that is neither code nor corpus; the content boundary, `.work/`, cross-repo references |
-| [`language-guide.md`](language-guide.md) | Naming anything — a code identifier, a code file, a document file |
-| [`method-glossary.md`](method-glossary.md) | Unsure what a method term means — layer, wave, Product Component, ID code |
-| [`structure-guide.md`](structure-guide.md) | Writing or checking the two structure maps in `.control/` |
-
-## `document/` — document rules
-
-| File | Governs |
-|---|---|
-| [`corpus-guide.md`](document/corpus-guide.md) | Where a file lives. Read before the other guides |
-| [`delivery-flow-guide.md`](document/delivery-flow-guide.md) | Five gates, `mode`, `risk_accepted`, the gate checklists, units of work, wave size, Fast Path, the story-closing checklist, change control |
-| [`bmad-guide.md`](document/bmad-guide.md) | How BMad skills are used here; classes A–D, the read-write map, memlog |
-| [`bmad-skill-register.md`](document/bmad-skill-register.md) | The installed BMad skills with the documents each reads and writes |
-| [`brief-guide.md`](document/brief-guide.md) · [`prd-guide.md`](document/prd-guide.md) · [`ux-guide.md`](document/ux-guide.md) | The G1 and G2 artifacts |
-| [`srs-guide.md`](document/srs-guide.md) · [`sdd-guide.md`](document/sdd-guide.md) | The G3 and G4 artifacts, per Product Component |
-| [`architecture-guide.md`](document/architecture-guide.md) | The architecture spine, `AD-N`, C4, and the three inventories |
-| [`decision-guide.md`](document/decision-guide.md) | `DEC-`: the one test for recording at all, shape, global numbering, the `draft → accepted → applied` ladder, supersession |
-| [`templates/`](document/templates/) | Templates, one per kind of document; they MUST be copied, and MUST NOT be reproduced from memory |
-
-## `codebase/` — code rules
-
-All three are written by the **project**, not the kit. While `Draft`, their contents MAY be read as
-guidance but MUST NOT be used to reject a change.
-
-[`stack-guide.md`](codebase/stack-guide.md) · [`conventions-guide.md`](codebase/conventions-guide.md) · [`brownfield-guide.md`](codebase/brownfield-guide.md)
-
-## `scripts/`
-
-`validate.py` — registry gates and the `.control/generated/` generator. `timeline.py` — the time
-dimension from git history. `inventory.py` — derives the three inventories from code and reports the
-difference against the plan; it MUST NOT patch either side into agreement. All three run through
-`uv run`.