wdi-method 0.6.1 → 0.6.4

package/kit-overlay/portability.md

@@ -1,98 +1,98 @@
----
-status: Reference
----
-
-# Portability — what is method, what is product
-
-**Opened when:** carrying a method change into the WDI Method package, or installing
-the method in a product repo.
-
-This file **explains**. It does not bind. Installing is the act, and that act lives in
-the WDI Method package README plus `wdi-method` (`install` · `update` · `promote` ·
-`verify`). Where this file and that README disagree, the README wins and the
-disagreement is a defect.
-
-It exists so that "promote the method, leave the product" is not a fresh re-reading of
-fifty files every time.
-
-## The seam
-
-Most of `.constitution/` is portable as it stands. A handful name **this product**, and in most of
-them only an *example* does — not a rule.
-
-| File | What is this product's | What to do when carrying it |
-|---|---|---|
-| `../../project/constitution.md` | Articles 1, 2, and 5 | **Rewrite 2 and 5.** Article 1 cites `index.yaml` `product.name`. Articles 3, 4, 6, 7 are NOT here — they are the method's, in `../constitution.md`, and `update` replaces them. `promote` never touches this file: the room is skipped, so the package's copy is a seed and nothing more |
-| `../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 seventeen skills, the templates, `validate.py`,
-`inventory.py`, `../method-glossary.md`, and the three files beside this one — carries without edit.
-
-One half-exception, and it is by design: `inventory.py` is the generic engine and carries whole, but
-it reads no code itself. The three readers live in `../../project/inventory-readers.py`, which ships
-as a skeleton and belongs to the product. A new project runs `wdi-init` intent `readers` once and
-rewrites that file, nothing else. No example ships, deliberately — an example is a guess about a
-stack nobody here has seen.
-
-## What does NOT travel
-
-| Stays behind | Why |
-|---|---|
-| `.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/project/codebase-*-guide.md` | Written by the **project**, not the method. They ship as empty `Draft` stubs |
-| `.constitution/project/inventory-readers.py` | How THIS product's code is read. Seeded as a SKELETON — no patterns and no stack. `wdi-init` intent `readers` writes it against the repo in front of it |
-| `_bmad-output/` | Run workspace |
-| The `bmad-*` skills themselves | BMad's, installed by BMad. Only `_bmad/custom/*.toml` is ours |
-
-## What travels beside `.constitution/`
-
-The method is not `.constitution/` alone. Three sets move together, and carrying one without the
-others leaves a method that cannot run:
-
-| Set | Note |
-|---|---|
-| `.constitution/` | Minus the product articles; `promote` / `install` handle the seam |
-| `.claude/skills/wdi-*/` (and `.agents/skills/wdi-*/` when those agents are selected) | Every wrapper. A wrapper without its guide, or a guide without its wrapper, is half a method |
-| `_bmad/custom/*.toml` | The one most likely to be forgotten. `*.user.toml` stays behind |
-| `AGENTS.md` | The routing table is the method; from `## Code` down is the product. `install` / `update` MUST NOT overwrite an existing `AGENTS.md` |
-
-## Two directions
-
-```
-a product repo with a newer working copy of the method
-        --promote-->
-WDI Method (this package)
-        --install / update-->
-product repos
-```
-
-- **Promote** copies the method *up* once it has settled in a working copy.
-- **Install / update** copies that snapshot *out* to a repo that consumes it.
-- Do not run `update` against a repo you are about to promote from — that would overwrite the newer copy.
-- There is no SHA lock and no per-file increment. The snapshot is the unit. The package version on npm / GitHub is the name of that snapshot.
-
-## Installing in a fresh repo
-
-BMad first (`npx bmad-method install`), then WDI Method. There is no numbered install runbook:
-the steps that a runbook used to carry are now `wdi-init` intent `setup`. The order the acts come in:
-
-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 `../../project/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
-   slot through the skill that owns it; everything else goes to `_bmad-output/prior-knowledge/`.
-   `corpus-guide.md` owns that test.
-7. Then G1 — which confirms `product.name` and writes the brief under that name.
-
-**Two things a fresh install MUST NOT do:**
-
-- Set `mode` and `risk_accepted` before the components exist. They are per-component fields, and the
-  components are born at the tail of G2.
-- Fill `.control/generated/` by hand. It is script output, and a hand-written table there is the one
-  lie no validator catches.
+---
+status: Reference
+---
+
+# Portability — what is method, what is product
+
+**Opened when:** carrying a method change into the WDI Method package, or installing
+the method in a product repo.
+
+This file **explains**. It does not bind. Installing is the act, and that act lives in
+the WDI Method package README plus `wdi-method` (`install` · `update` · `promote` ·
+`verify`). Where this file and that README disagree, the README wins and the
+disagreement is a defect.
+
+It exists so that "promote the method, leave the product" is not a fresh re-reading of
+fifty files every time.
+
+## The seam
+
+Most of `.constitution/` is portable as it stands. A handful name **this product**, and in most of
+them only an *example* does — not a rule.
+
+| File | What is this product's | What to do when carrying it |
+|---|---|---|
+| `../../project/constitution.md` | Articles 1, 2, and 5 | **Rewrite 2 and 5.** Article 1 cites `index.yaml` `product.name`. Articles 3, 4, 6, 7 are NOT here — they are the method's, in `../constitution.md`, and `update` replaces them. `promote` never touches this file: the room is skipped, so the package's copy is a seed and nothing more |
+| `../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 eighteen skills, the templates, `validate.py`,
+`inventory.py`, `../method-glossary.md`, and the three files beside this one — carries without edit.
+
+One half-exception, and it is by design: `inventory.py` is the generic engine and carries whole, but
+it reads no code itself. The three readers live in `../../project/inventory-readers.py`, which ships
+as a skeleton and belongs to the product. A new project runs `wdi-init` intent `readers` once and
+rewrites that file, nothing else. No example ships, deliberately — an example is a guess about a
+stack nobody here has seen.
+
+## What does NOT travel
+
+| Stays behind | Why |
+|---|---|
+| `.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/project/codebase-*-guide.md` | Written by the **project**, not the method. They ship as empty `Draft` stubs |
+| `.constitution/project/inventory-readers.py` | How THIS product's code is read. Seeded as a SKELETON — no patterns and no stack. `wdi-init` intent `readers` writes it against the repo in front of it |
+| `_bmad-output/` | Run workspace |
+| The `bmad-*` skills themselves | BMad's, installed by BMad. Only `_bmad/custom/*.toml` is ours |
+
+## What travels beside `.constitution/`
+
+The method is not `.constitution/` alone. Three sets move together, and carrying one without the
+others leaves a method that cannot run:
+
+| Set | Note |
+|---|---|
+| `.constitution/` | Minus the product articles; `promote` / `install` handle the seam |
+| `.claude/skills/wdi-*/` (and `.agents/skills/wdi-*/` when those agents are selected) | Every wrapper. A wrapper without its guide, or a guide without its wrapper, is half a method |
+| `_bmad/custom/*.toml` | The one most likely to be forgotten. `*.user.toml` stays behind |
+| `AGENTS.md` | The routing table is the method; from `## Code` down is the product. `install` / `update` MUST NOT overwrite an existing `AGENTS.md` |
+
+## Two directions
+
+```
+a product repo with a newer working copy of the method
+        --promote-->
+WDI Method (this package)
+        --install / update-->
+product repos
+```
+
+- **Promote** copies the method *up* once it has settled in a working copy.
+- **Install / update** copies that snapshot *out* to a repo that consumes it.
+- Do not run `update` against a repo you are about to promote from — that would overwrite the newer copy.
+- There is no SHA lock and no per-file increment. The snapshot is the unit. The package version on npm / GitHub is the name of that snapshot.
+
+## Installing in a fresh repo
+
+BMad first (`npx bmad-method install`), then WDI Method. There is no numbered install runbook:
+the steps that a runbook used to carry are now `wdi-init` intent `setup`. The order the acts come in:
+
+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 `../../project/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
+   slot through the skill that owns it; everything else goes to `_bmad-output/prior-knowledge/`.
+   `corpus-guide.md` owns that test.
+7. Then G1 — which confirms `product.name` and writes the brief under that name.
+
+**Two things a fresh install MUST NOT do:**
+
+- Set `mode` and `risk_accepted` before the components exist. They are per-component fields, and the
+  components are born at the tail of G2.
+- Fill `.control/generated/` by hand. It is script output, and a hand-written table there is the one
+  lie no validator catches.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wdi-method",
-  "version": "0.6.1",
+  "version": "0.6.4",
   "description": "WDI Method — software delivery method that wraps BMad",
   "type": "module",
   "bin": {

package/scaffold/docs/agents/domain.md

@@ -0,0 +1,36 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+**This repo does not use `CONTEXT.md`, `CONTEXT-MAP.md`, or `docs/adr/`, and none of them MUST be
+created.** WDI Method already owns every home they would occupy, and a second home for the same fact is
+drift rather than tidiness. `.constitution/method/constitution.md` Article 3 states it outright: this
+method has no `docs/` layer for corpus or rules, and `wdi-reconcile` reports a root `CONTEXT.md` or a
+`docs/adr/` as a finding against that article.
+
+This file is seeded by `wdi-method` so the answer is right from the first install. `/setup-matt-pocock-skills`
+would otherwise write its own default here — one that points at exactly the two paths above — and every
+repo that ran it has had to hand-correct this file afterwards.
+
+## Where each thing actually lives
+
+| Looking for | Read |
+|---|---|
+| What a domain term means | `.control/product-glossary.md` |
+| What is promised — a capability, an `FR`, a use case, a business rule | `.what/` |
+| How it is built — the spine, C4, an inventory, an SDD, a contract | `.how/` |
+| Why it is like this — a decision worth remembering | `.control/decisions/`, indexed by the generated decision table under `.control/generated/` |
+| An architectural invariant | an `AD-N` in the architecture spine, under `.how/_platform/` |
+| Which contexts exist and what each owns | `.control/registry/components.yaml` |
+| Where code lives | `.control/structure-codebase.md` |
+| Where documents live | `.control/structure-document.md` |
+
+`AGENTS.md` § *The thing in your hand → its folder* is the short version of this table and is the
+authority. Where this file and `AGENTS.md` disagree, `AGENTS.md` wins.
+
+## A decision is a `DEC-`, never an ADR
+
+`decision-guide.md` owns the shape, the one test that decides whether a decision is recorded at all, and
+the `draft → accepted → applied` ladder. An ADR file under `docs/adr/` MUST NOT be written in its place:
+the numbering is global and lives in `.control/registry/decisions.yaml`, and a decision recorded outside
+it is invisible to `refs-resolve`, to the RTM, and to the generated decision table.

package/scaffold/docs/agents/issue-tracker.md

@@ -0,0 +1,43 @@
+# Issue tracker
+
+Where issues live for this repo, and what `to-spec`, `to-tickets`, and `triage` read and write.
+
+This file is seeded by `wdi-method`. It is the product's from here on: change the tracker whenever you
+like, but keep the three invariants below, because `wdi-build` and the validators read them.
+
+## Two places, and they are not the same place
+
+| | Owned by | Lives at |
+|---|---|---|
+| **A spec's tickets** — the work behind an `FR` | `wdi-build`, at G5 | `{spec_folder}/issues/<NN>-<slug>.md`, `spec_folder` from `.control/registry/specs.yaml` |
+| **Ad hoc work** — a quick bug report, a small idea, engineering-skill scratch | this file's convention | `.scratch/<slug>/` |
+
+`.scratch/` MUST NOT become a second place to plan a feature that already has an `FR`. The moment ad hoc
+work turns out to touch an `FR`, it stops and becomes a spec through `wdi-build` — the Fast Path rule in
+`delivery-flow-guide.md` owns that boundary.
+
+## The three invariants
+
+Whatever tracker this repo uses — local markdown, GitHub, GitLab, Jira — these MUST hold:
+
+1. **One parent per spec, one issue per ticket.** A ticket is an issue, never a sub-task: only an issue
+   carries native blocking edges, and the frontier is read from them.
+2. **Status lives on the ticket itself and nowhere else.** A `**Status:**` line near the top of the
+   ticket file, or `status:` in its frontmatter. `ticket-status-one-home` reads it there, and copying it
+   into `specs.yaml` is what that validator exists to refuse.
+3. **Every ticket names what it `satisfies`** — the `UC` or `FR` behind it. Without it the chain
+   `FR → UC → ticket → test` breaks and the RTM cannot say which promise went green.
+
+## Conventions — local markdown
+
+- One effort per directory: `.scratch/<slug>/`
+- One file per ticket at `.scratch/<slug>/issues/<NN>-<slug>.md`, numbered from `01`, never a single
+  combined file
+- Blocking edges as a `Blocked by: NN, NN` line near the top
+- Comments append at the bottom under a `## Comments` heading
+
+## Switching to a real tracker
+
+Re-run `/setup-matt-pocock-skills` and pick it, then keep the three invariants above. The mapping WDI
+Method expects is in `delivery-flow-guide.md` § *Mapping to a tracker*: parent issue is the spec, issue is
+the ticket, Fix Version is the release, and the `CAP`/`FR` travel as labels.