wdi-method 0.3.0

package/kit/skills/wdi-systematic-debugging/references/root-cause-tracing.md

@@ -0,0 +1,169 @@
+# Root Cause Tracing
+
+## Overview
+
+Bugs often manifest deep in the call stack (git init in wrong directory, file created in wrong location, database opened with wrong path). Your instinct is to fix where the error appears, but that's treating a symptom.
+
+**Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Bug appears deep in stack?" [shape=diamond];
+    "Can trace backwards?" [shape=diamond];
+    "Fix at symptom point" [shape=box];
+    "Trace to original trigger" [shape=box];
+    "BETTER: Also add defense-in-depth" [shape=box];
+
+    "Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
+    "Can trace backwards?" -> "Trace to original trigger" [label="yes"];
+    "Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
+    "Trace to original trigger" -> "BETTER: Also add defense-in-depth";
+}
+```
+
+**Use when:**
+- Error happens deep in execution (not at entry point)
+- Stack trace shows long call chain
+- Unclear where invalid data originated
+- Need to find which test/code triggers the problem
+
+## The Tracing Process
+
+### 1. Observe the Symptom
+```
+Error: git init failed in ~/project/packages/core
+```
+
+### 2. Find Immediate Cause
+**What code directly causes this?**
+```typescript
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
+
+### 3. Ask: What Called This?
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  → called by Session.initializeWorkspace()
+  → called by Session.create()
+  → called by test at Project.create()
+```
+
+### 4. Keep Tracing Up
+**What value was passed?**
+- `projectDir = ''` (empty string!)
+- Empty string as `cwd` resolves to `process.cwd()`
+- That's the source code directory!
+
+### 5. Find Original Trigger
+**Where did empty string come from?**
+```typescript
+const context = setupCoreTest(); // Returns { tempDir: '' }
+Project.create('name', context.tempDir); // Accessed before beforeEach!
+```
+
+## Adding Stack Traces
+
+When you can't trace manually, add instrumentation:
+
+```typescript
+// Before the problematic operation
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  console.error('DEBUG git init:', {
+    directory,
+    cwd: process.cwd(),
+    nodeEnv: process.env.NODE_ENV,
+    stack,
+  });
+
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
+```
+
+**Critical:** Use `console.error()` in tests (not logger - may not show)
+
+**Run and capture:**
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+**Analyze stack traces:**
+- Look for test file names
+- Find the line number triggering the call
+- Identify the pattern (same test? same parameter?)
+
+## Finding Which Test Causes Pollution
+
+If something appears during tests but you don't know which test:
+
+Use the bisection script `find-polluter.sh` in this directory:
+
+```bash
+./find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+Runs tests one-by-one, stops at first polluter. See script for usage.
+
+## Real Example: Empty projectDir
+
+**Symptom:** `.git` created in `packages/core/` (source code)
+
+**Trace chain:**
+1. `git init` runs in `process.cwd()` ← empty cwd parameter
+2. WorktreeManager called with empty projectDir
+3. Session.create() passed empty string
+4. Test accessed `context.tempDir` before beforeEach
+5. setupCoreTest() returns `{ tempDir: '' }` initially
+
+**Root cause:** Top-level variable initialization accessing empty value
+
+**Fix:** Made tempDir a getter that throws if accessed before beforeEach
+
+**Also added defense-in-depth:**
+- Layer 1: Project.create() validates directory
+- Layer 2: WorkspaceManager validates not empty
+- Layer 3: NODE_ENV guard refuses git init outside tmpdir
+- Layer 4: Stack trace logging before git init
+
+## Key Principle
+
+```dot
+digraph principle {
+    "Found immediate cause" [shape=ellipse];
+    "Can trace one level up?" [shape=diamond];
+    "Trace backwards" [shape=box];
+    "Is this the source?" [shape=diamond];
+    "Fix at source" [shape=box];
+    "Add validation at each layer" [shape=box];
+    "Bug impossible" [shape=doublecircle];
+    "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+    "Found immediate cause" -> "Can trace one level up?";
+    "Can trace one level up?" -> "Trace backwards" [label="yes"];
+    "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
+    "Trace backwards" -> "Is this the source?";
+    "Is this the source?" -> "Trace backwards" [label="no - keeps going"];
+    "Is this the source?" -> "Fix at source" [label="yes"];
+    "Fix at source" -> "Add validation at each layer";
+    "Add validation at each layer" -> "Bug impossible";
+}
+```
+
+**NEVER fix just where the error appears.** Trace back to find the original trigger.
+
+## Stack Trace Tips
+
+**In tests:** Use `console.error()` not logger - logger may be suppressed
+**Before operation:** Log before the dangerous operation, not after it fails
+**Include context:** Directory, cwd, environment variables, timestamps
+**Capture stack:** `new Error().stack` shows complete call chain
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- Found root cause through 5-level trace
+- Fixed at source (getter validation)
+- Added 4 layers of defense
+- 1847 tests passed, zero pollution

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

@@ -0,0 +1,145 @@
+---
+name: wdi-ux
+description: Use when UX is produced or landed — dispatching bmad-ux for a PRD scope, then landing DESIGN.md, EXPERIENCE.md, the design system, and the screen registry into the layers they belong to. Optional, and it rides on G2. Never writes UX content itself.
+---
+
+# WDI UX
+
+`bmad-ux` writes the UX. This skill decides whether it should run, hands it the scope, checks what
+came back, and — because `bmad-ux` is **class B** — lands its output into the two layers it splits
+across. No other skill MAY land these files.
+
+Two acts, and a pass MAY do either or both: **run** the UX, and **land** it. They are separated because
+they become possible at different moments. A run belongs to G2, where the PRD is fresh. Landing needs a
+Product Component to land into, and that list is not born until the tail of G2.
+
+You MUST NOT write or edit `DESIGN.md` or `EXPERIENCE.md` yourself. If a check fails, name what is
+missing and re-dispatch — a hand-patched UX document makes the memlog lie about how it got that way.
+The content rules are in `ux-guide.md` and MUST NOT be restated here.
+
+## Inputs
+
+| Source | What it answers |
+|---|---|
+| `.what/_prd/<initiative>/prd.md` | The promises the UX has to make usable — `FR`, `NFR`, `UJ-N` |
+| `.what/_product-brief/brief.md` | The primary user, and the boundary the UX MUST respect |
+| `.constitution/document/ux-guide.md` | The rules the result is checked against |
+| `.constitution/document/templates/ux.md` | The required shape of each half |
+| `.control/registry/components.yaml` | Whether the Product Components and containers a landing needs exist |
+| `.constitution/document/templates/design-system.md` | The shape of the product-level tokens file |
+| `.control/product-glossary.md` | Terms already fixed, so the screens do not invent competing ones |
+| `_bmad-output/ux/` | An earlier run — the input to *land*, and to intent *update* |
+| `.how/_platform/design-system.md` | Tokens and base components already agreed |
+
+## Step 1 — Position
+
+- UX is **optional**. It earns a run when the interface is a substantial part of what the PRD
+  promises; it MUST NOT be run to fill a slot. Say so and stop when a run buys nothing.
+- The order is `wdi-product` → `wdi-ux`. A UX run with no PRD in scope is designing a promise nobody
+  made; route to `wdi-product` first.
+- If the ask is a new capability rather than how an agreed one feels, this is the wrong skill — route
+  to `wdi-product` intent `update`.
+- If the ask is how the system behaves internally, route to `wdi-blueprint` for the catalogue, or
+  `wdi-component` for a full flow.
+
+## Step 2 — Mode
+
+Read `_bmad-output/ux/` and `components.yaml`, then state the mode in one line before acting.
+
+| State | Mode |
+|---|---|
+| No run for this scope | **run** — Step 3, then Step 5 for whatever is landable |
+| A run exists, finalised, nothing landed | **land** — Step 5 only |
+| A run exists and the PRD has changed under it | **run** intent *update*, then Step 5 |
+| A run exists, landed, and a `<pc>` has since been born | **land** — the deferred half, Step 5 |
+
+## Step 3 — Dispatch
+
+Invoke `bmad-ux` with the detected intent. Do not restate the rules to it — they arrive through
+`doc_standards` and `persistent_facts` in `_bmad/custom/bmad-ux.toml`, and a second copy here would
+drift.
+
+State the scope as **one PRD initiative**, and name the input files explicitly; the skill globs its
+own default locations, which this project redirects. A scope spanning several initiatives MUST be
+split into one run each — the run folder is a singleton per scope, and two initiatives in one folder
+cannot be landed separately later.
+
+## Step 4 — Verify
+
+Check what came back against the guide. Report every failure; fix none of them by hand.
+
+| # | Check | Fails when |
+|---|---|---|
+| 1 | Landing zone | Anything was written into `.what/` or `.how/` by the run itself |
+| 2 | Two documents, split correctly | A layout, component, or token sits in `EXPERIENCE.md`; a promise sits first in `DESIGN.md` |
+| 3 | Journeys reference `UJ-N` | The PRD's journeys were restated under new names |
+| 4 | Every screen has an empty and an error state | Only the populated state was designed |
+| 5 | Every user-facing noun is in the glossary | A new noun appeared — route it through `wdi-blueprint`, which owns the glossary, in this pass |
+| 6 | No new capability | The run designed something no `FR` promises — route to `wdi-product`, and MUST NOT land it |
+| 7 | Every `[ASSUMPTION]` filed | An assumption sits in the text with nothing in `.control/questions/` behind it |
+| 8 | Memlog at `.control/memlog/ux.md` | A `.memlog.md` appeared inside the corpus — `--workspace` was used |
+| 9 | `bmad-review` structure + prose ran at finalize | `doc_standards` did not fire |
+
+Check 8 is the one that MUST be fixed immediately rather than reported. A `.memlog.md` inside `.what/`
+or `.how/` is corpus pollution, and V16 rejects it.
+
+## Step 5 — Land, at two speeds
+
+Nothing is landed until the run is finalised. The homes are in `corpus-guide.md`; what is decided
+here is **when each one becomes possible**.
+
+| Output | Lands into | Possible once |
+|---|---|---|
+| Tokens and base components | `.how/_platform/design-system.md` | The run is final — it crosses components by definition |
+| `EXPERIENCE.md` | `.what/<pc>/04-usecases/` | The `<pc>` is registered in `components.yaml` |
+| `DESIGN.md` | `.how/<pc>/01-ux/` | The `<pc>` is registered **and** its container exists |
+| Each screen | an `LC` of type `ui-screen` in `components.yaml` | Same as `DESIGN.md` — an `LC` MUST name its container. Registration is checked at wave close, V12 |
+
+- A half that is not yet landable MUST stay in `_bmad-output/ux/` and be reported as deferred. At G2
+  that is the normal outcome, not a failure: the slicing is born at the tail of G2 and containers at G3.
+- You MUST NOT create a Product Component or a container to make a landing possible. A PC comes from
+  `wdi-init` intent `component` and a container from `wdi-blueprint` intent `platform`.
+- One run MAY land across several Product Components. Split by which `<pc>` the content serves; a
+  screen whose `<pc>` is ambiguous MUST be raised through `wdi-question`, not assigned by guess.
+- Registering the screens is part of landing `DESIGN.md`, in the same act. A screen in `01-ux/`
+  without its `components.yaml` entry has been half-landed, and V12 catches it at a worse moment.
+- `.how/_platform/` otherwise belongs to `wdi-blueprint`. `design-system.md` is the one file in it you
+  own, and it has its own template; you MUST NOT touch any other.
+- The run folder MUST NOT be deleted after landing. Intent *update* reads it again.
+
+## Step 6 — Impact
+
+A landed UX changes what other documents can still claim. Check, and **report** — never edit.
+
+| Found | Where it goes |
+|---|---|
+| A flow the PRD does not promise | `wdi-product` intent `update`, before it is designed |
+| A behaviour the SRS never stated | `wdi-blueprint` for a catalogue line, `wdi-component` for a flow |
+| A pattern that forces a technology choice | `wdi-decision` — a `DEC-`, not a note in `DESIGN.md` |
+| A screen contradicting an `applied` `DEC-` | `wdi-decision` — a new `DEC-`, never an edit to one already applied |
+
+`wdi-reconcile` is the read-only sweep across all layers. Run it rather than reimplementing it.
+
+## Step 7 — Memlog
+
+Everything in a UX pass — the run and the landing — logs to `.control/memlog/ux.md`, through
+`memlog.py --path`. `--workspace` MUST NOT be used.
+
+## Rules
+
+- Content MUST NOT be edited while it is being landed. Splitting one document across the homes its
+  row names is not editing; changing a sentence to fit its new home is, and it goes back through
+  `bmad-ux`.
+- You MUST NOT open G2 on UX that has not been through check 9. Gate time is for deciding.
+- You MUST NOT raise `status:` as part of landing. Status is a stage; the `reviewed:` block is an
+  event, and `wdi-review` writes it.
+- You MUST NOT land anything into a wave that is already closed. The wave is reopened through
+  `wdi-build`, or the gap is filed through `wdi-question`.
+- When the UX concludes the PRD promised something that cannot be made usable, say so and stop. Route
+  to `wdi-product`; do not quietly narrow the promise in `EXPERIENCE.md`.
+
+## Output
+
+A short report: mode taken, scope run, the result of all nine checks naming the failures, what landed
+and where, what was deferred and what has to exist before it can land, screens registered, impact
+found and where it was routed, and open questions raised.

package/kit-overlay/AGENTS.md

@@ -0,0 +1,196 @@
+# Agent Rules — {product}
+
+<!-- BEGIN:wdi-method -->
+This repo uses **WDI Method**. It wraps BMad; it does not replace it. This marked
+block is owned by the WDI Method package and is **replaced on every update**.
+Product rules belong **outside** it (extra boundaries, `## Code`, stack notes).
+A fact written inside this block will be overwritten.
+
+Product identity lives in `.control/registry/index.yaml` (`product.name`, optional
+`product.client`). G1 confirms it. This file MUST NOT become a second source of the name.
+
+## Install and update
+
+BMad first, then WDI Method. In the product repo:
+
+```bash
+npx bmad-method install
+npx github:wiradigitalid/wdi-method
+```
+
+No subcommand opens the installer TUI. It detects an existing install and offers
+**update**. Non-interactive:
+
+```bash
+npx github:wiradigitalid/wdi-method install --yes
+npx github:wiradigitalid/wdi-method update --yes
+```
+
+BMad: https://github.com/bmad-code-org/BMAD-METHOD
+WDI Method: https://github.com/wiradigitalid/wdi-method
+
+A method file MUST NOT be invented here. If a rule is wrong, fix it in the WDI
+Method package, then update.
+
+This file is loaded every session; everything else is loaded **lazily**, only when
+the task matches.
+
+## Language
+
+Prose in this repo is Bahasa Indonesia; a technical term the industry writes in English MUST be left
+in English — an Indonesian equivalent MUST NOT be invented. Which language a **name** is written in —
+code identifiers, files, database columns — is governed by `.constitution/language-guide.md`.
+
+The agent-instruction files are the exception the Rule-Writing Standard already claims: `AGENTS.md`,
+`CLAUDE.md`, and everything under `.constitution/`. Nothing else in this repo is one — `.control/`,
+`.what/`, and `.how/` are product content and MUST stay Bahasa Indonesia, and translating them MUST
+NOT be proposed as tidying. A literal value written into an Indonesian document — a marker such as
+`[TIDAK ADA]`, an answer option such as `ya / tidak / ubah` — stays Indonesian wherever it appears,
+including inside an English guide.
+
+A **registry value** is a machine-facing key and stays English: `mode: catalog`, `status: applied`,
+`risk_accepted: low`. Those names are used as written in prose too — one thing, one name.
+
+## The thing in your hand → its folder
+
+Read this instead of reasoning about what `.what/` and `.how/` mean.
+
+| The thing in your hand | Its folder |
+|---|---|
+| A rule, a guide, a template — how we work | `.constitution/` |
+| The explanation of a rule, never a rule itself | `.constitution/method/` |
+| A decision, an open question, a registry, a structure map, minutes | `.control/` |
+| The brief, a PRD, a use case, a business rule — what is promised | `.what/` |
+| The spine, C4, an inventory, an SDD, a contract — how it is built | `.how/` |
+| A skill run's working output, and documents that predate the method | `_bmad-output/` |
+| Scratch that empties when the task closes | `.work/` |
+| The application | named under `## Code` below |
+
+## Layer boundaries
+
+| Layer | Answers | MUST NOT hold |
+|---|---|---|
+| `.constitution/` | How we work | State, decisions, product content |
+| `.control/` | What currently holds and what has been decided | Rules |
+| `.what/` | What is promised | Solution shape — tables, endpoints, technology |
+| `.how/` | How it is built | Promises to the user |
+| `_bmad-output/` | Work in progress; committed, not curated | Anything still correct after its wave has passed |
+| `.work/` | Scratch; emptied when a task closes | Secrets, commercial figures, anything meant as authority |
+
+The placement test: **is this file still correct after its wave has passed?** Yes → the corpus. No →
+`_bmad-output/`. In doubt → `document/corpus-guide.md`.
+
+The method does not use a `docs/` layer for corpus or rules. A leftover `docs/` folder is inventory
+to sort, not a second home.
+
+## Depth and review intensity — two fields, never merged
+
+| Field | Where | Controls |
+|---|---|---|
+| `mode` | `index.yaml` globally, `components.yaml` per component | **Document depth**, and only that. `catalog` · `outline` · `guarded` · `deep`; default `catalog` |
+| `risk_accepted` | `components.yaml` per component | **Review intensity**, and only that. `low` · `medium` · `high` |
+
+Per-component `mode` wins over global, and there is no third scope — `mode` MUST NOT be overridden per
+wave or per `SPEC.md`. A component at `mode: catalog` **skips G4 entirely**. Neither field MUST be
+derived from the other: one component MAY be thin on purpose and reviewed the hardest.
+`document/delivery-flow-guide.md` owns both; `method/rationale.md` says why they are separate.
+
+## The five gates and the fifteen 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` |
+
+Before G1 and at the tail of G2: `wdi-init`, five intents — `setup` · `component` · `mode` · `risk` ·
+`structure`.
+
+Any time: `wdi-decision` · `wdi-question` · `wdi-log` · `wdi-help` · `wdi-reconcile` · `wdi-review` ·
+`wdi-report` · `wdi-systematic-debugging`.
+
+**No BMad skill is invoked directly.** Each has a wrapper, and the wrapper is what checks position,
+verifies the result, and lands the memlog.
+
+## What MUST NOT be done
+
+- 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 `npx wdi-method update`.
+- A file in `_bmad-output/prior-knowledge/` MUST NOT be copied into `.what/` or `.how/`. It enters
+  the corpus only through the skill that owns the slot.
+- `.control/generated/` MUST NOT be written by hand — it is the output of `validate.py` and
+  `timeline.py`.
+- The two structure maps in `.control/` MUST NOT be edited by hand — `wdi-init` intent `structure`
+  re-derives them.
+- A `DEC-` with status `applied` MUST NOT be edited, except to record its supersession — status moves
+  to `superseded` and names its replacement. A change of mind produces a new `DEC-`.
+- A file in `.constitution/method/` MUST NOT be cited as the reason to reject a change. It is
+  `status: Reference` — it explains, it does not bind, and where it disagrees with a guide the guide
+  wins and the disagreement is a defect.
+- More than the component's `mode` demands MUST NOT be written. Exceeding the depth the owner set is
+  not diligence.
+- `.claude/skills/bmad-*/customize.toml` MUST NOT be edited — it is overwritten on every BMad update;
+  customise through `_bmad/custom/`.
+
+## Routing — load a guide when the task matches
+
+| Task | Load |
+|---|---|
+| Wanting the whole method in five minutes | `.constitution/method/README.md` |
+| About to change a rule, and needing to know what breaks | `.constitution/method/rationale.md` |
+| Asking whether a document exists at this `mode`, or where a file goes | `.constitution/method/artifact-map.md` |
+| Unsure whether a file may exist in this repo | `.constitution/repo-guide.md` |
+| Unsure where a file lives | `.constitution/document/corpus-guide.md` |
+| Unsure what a method term means | `.constitution/method-glossary.md` |
+| Unsure about a domain term | `.control/product-glossary.md` |
+| Looking for a non-technical fact — a domain, an account, a legal entity, a locked date | `.control/project-non-technical-log.md` |
+| Naming anything — a code identifier, a file, a database column | `.constitution/language-guide.md` |
+| Asking "which gate now, what next" | `.constitution/document/delivery-flow-guide.md` · skill `wdi-help` |
+| Setting or changing `mode` or `risk_accepted` | `.constitution/document/delivery-flow-guide.md` · skill `wdi-init` |
+| Invoking a BMad skill | `.constitution/document/bmad-guide.md` · `document/bmad-skill-register.md` |
+| Writing or reviewing a product brief | `.constitution/document/brief-guide.md` |
+| Writing or reviewing a PRD | `.constitution/document/prd-guide.md` |
+| Writing or reviewing UX | `.constitution/document/ux-guide.md` |
+| Writing or reviewing an SRS | `.constitution/document/srs-guide.md` |
+| Writing or reviewing an SDD | `.constitution/document/sdd-guide.md` |
+| Writing the spine, an `AD-N`, C4, or one of the three inventories | `.constitution/document/architecture-guide.md` |
+| Opening, accepting, or applying a `DEC-` | `.constitution/document/decision-guide.md` |
+| Writing or reading a structure map | `.constitution/structure-guide.md` |
+| Looking for where code lives, or placing new code | `.control/structure-codebase.md` |
+| Looking for where a document lives | `.control/structure-document.md` |
+| Writing or reviewing code | `.constitution/codebase/stack-guide.md` · `conventions-guide.md` · `brownfield-guide.md` |
+
+All three `codebase/*-guide.md` start as `status: Draft`. While they are, their contents MAY be read
+as guidance but MUST NOT be used to reject a change.
+
+The two structure maps MUST NOT be installed as `doc_standards` — they are facts, not standards. Nor
+MUST anything in `.constitution/method/`; `status: Reference` forbids it.
+
+## Bugs, decisions, questions
+
+- A bug, a failing test, or unexpected behaviour → skill `wdi-systematic-debugging`, **before** any
+  fix is proposed.
+- A decision worth remembering → skill `wdi-decision` → `.control/decisions/`. Recording is **not
+  mandatory**: if the answer to *why is it like this* is readable from the code, it MUST NOT be
+  recorded. One case is mandatory — contradicting an `AD-N`.
+- Something that cannot be decided now → skill `wdi-question` → `.control/questions/`. The default
+  class is `assumptions.md`, not `blocking.md`; filing something as blocking "to be safe" is the
+  habit that produced unreadable question lists.
+- A non-technical fact that constrains the build → skill `wdi-log` intent `fact` →
+  `.control/project-non-technical-log.md`.
+
+## Method policy
+
+- A skill MUST NOT be invoked automatically. Name the one that fits and wait for the owner's
+  go-ahead — this holds even when the skill's own description says it must be used. Reading a
+  skill as reference is fine.
+- `.work/` is not production code. It MUST NOT be imported by the application, and MUST be
+  excluded when searching for code.
+<!-- END:wdi-method -->
+
+## Code
+
+Rewrite this section for the product. Stack, how to run tests, and known pitfalls belong here.
+`wdi-init` intent `structure` derives `.control/structure-codebase.md`; do not duplicate that map.

package/kit-overlay/README.md

@@ -0,0 +1,66 @@
+---
+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`.