wdi-method 0.4.5 → 0.5.0

package/kit/.constitution/{document → method/document}/templates/structure-codebase.md

@@ -1,129 +1,129 @@
----
-type: structure
-scope: codebase
-verified: '{YYYY-MM-DD}'      # the day the tree was actually read
-commit: '{sha}'               # the commit it was read at — staleness is measured against this
----
-
-# Codebase Structure
-
-<!-- TEMPLATE GUIDE — act on these comments, then delete them.
-
-     This file is DESCRIPTIVE. It states what the code tree looks like today. It MUST NOT carry
-     naming rules (conventions-guide.md), versions (stack-guide.md), or ratified legacy shapes
-     (brownfield-guide.md) — reference them instead.
-
-     Written and refreshed only by `wdi-init` intent `structure`, never by hand. Rules for both maps live in
-     .constitution/structure-guide.md.
-
-     THE SHAPE: annotated trees, not prose. Folders are complete; files are marked ★ inline and only
-     when they earn it. A tree that lists every file is unmaintainable, and an unmaintainable map
-     stops being read — that is how every source-tree document before this one died.
-
-     THREE SECTIONS, and the split is by DEPLOYABILITY, not by size or importance:
-       Top level   every base folder in the repo root
-       Container   runs or deploys on its own — the same word C4 L2 and components.yaml use
-       Library     an includable artifact — compiled or imported into something else, never run
-
-     "Container" is the kit's word, defined in templates/c4.md and carried by every LC's `container`
-     field. It MUST NOT be swapped for "application", "service", or "app" here — a synonym for a
-     term that already has a glossary entry is drift, and `wdi-reconcile` hunts for it. It does not
-     mean a Docker image; packaging is a separate question.
-
-     A unit that is neither is not a unit; it stays a line in Top level. When a unit stops being
-     separately deployable, it MUST move sections rather than keep its old heading. -->
-
-## Verified
-
-<!-- One line: date, commit SHA, and how the tree was read. If the commit is no longer an ancestor
-     of HEAD, this map is stale and MUST be refreshed before a gate reads it. -->
-
-## Top level
-
-<!-- Every base folder in the repo root, COMPLETE — including the dull ones. An unlisted folder is
-     the one people misuse, because nothing told them what it was for. Tag each entry so the two
-     sections below are predictable: [container] · [lib] · [docs] · [tooling] · [generated]. One
-     line of purpose per entry; no second line. -->
-
-```text
-{repo-root}/
-├── {unit}/                   # [container] what it is answerable for
-├── {unit}/                   # [lib] ...
-└── {folder}/                 # [docs] ...
-```
-
-## Containers
-
-<!-- One subsection per unit that runs or deploys on its own. Repeat the block below verbatim per
-     unit; if there is only one, there is still a subsection — a repo grows a second container
-     without warning.
-
-     Heading names MUST match the `container` values used in components.yaml, so an LC's container
-     can be checked against this map instead of trusted. A container with no code in this repo MUST
-     NOT get a subsection — it belongs to c4-l2-containers.md. A folder that builds more than one
-     container MUST say which. -->
-
-### {container}
-
-<!-- One line: what it is, and how it ships. Then the tree: folder convention first, ★ on the files
-     that earn it. Descend only until directories stop carrying distinct roles, and describe a
-     repeating shape ONCE with a placeholder such as <feature>/ rather than per instance. -->
-
-```text
-{container}/
-├── {entry-file}              # ★ ENTRY: what execution actually does first
-├── {folder}/                 # convention: what belongs here
-│   └── {file}                # ★ why this one is key
-└── {folder}/<feature>/       # the shape every feature repeats
-    ├── {sub}/                #   what goes in it
-    └── {sub}/                #   ...
-```
-
-<!-- One line, only when the unit has one: the authoritative call direction through those folders.
-     A builder who gets this wrong writes code that works and is still wrong. Cut if there is none;
-     do not invent one to fill the slot. -->
-
-**Flow:** {layer} → {layer} → {layer}
-
-## Libraries
-
-<!-- One subsection per includable artifact — compiled into or imported by something else, never
-     deployed on its own. A library is deliberately NOT a container, and MUST NOT appear at C4 L2.
-
-     Same block shape as a container, minus the entry point: a library that has one is a container
-     wearing the wrong label. -->
-
-### {library}
-
-<!-- One line: what it holds, and who consumes it. Then the annotated tree. -->
-
-```text
-{library}/
-├── {folder}/                 # convention: what belongs here
-│   └── {file}                # ★ why this one is key
-└── {folder}/
-```
-
-**Consumed by:** {units}
-
-## Generated
-
-<!-- Anything not written by hand, with its generator: codegen output, vendored trees, migration
-     snapshots. A generated folder edited by hand is a defect, so it MUST be named here even when it
-     looks like ordinary source. Cut the section if there is none. -->
-
-| Path | Generated by |
-| --- | --- |
-
-## Unclaimed
-
-<!-- Folders that exist but no one can state a purpose for. These are findings, not layout. Leave
-     them here, named, until they are claimed or deleted — inventing a purpose to empty this section
-     is the failure mode it exists to catch. Cut the section only when it is genuinely empty. -->
-
----
-
-<!-- Keep this legend last, and keep it one line. -->
-
-★ = key file: entry point, wiring root, the single place a rule is enforced, or a file that must be
-opened before behaviour in its folder can be changed.
+---
+type: structure
+scope: codebase
+verified: '{YYYY-MM-DD}'      # the day the tree was actually read
+commit: '{sha}'               # the commit it was read at — staleness is measured against this
+---
+
+# Codebase Structure
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     This file is DESCRIPTIVE. It states what the code tree looks like today. It MUST NOT carry
+     naming rules (conventions-guide.md), versions (stack-guide.md), or ratified legacy shapes
+     (brownfield-guide.md) — reference them instead.
+
+     Written and refreshed only by `wdi-init` intent `structure`, never by hand. Rules for both maps live in
+     .constitution/method/structure-guide.md.
+
+     THE SHAPE: annotated trees, not prose. Folders are complete; files are marked ★ inline and only
+     when they earn it. A tree that lists every file is unmaintainable, and an unmaintainable map
+     stops being read — that is how every source-tree document before this one died.
+
+     THREE SECTIONS, and the split is by DEPLOYABILITY, not by size or importance:
+       Top level   every base folder in the repo root
+       Container   runs or deploys on its own — the same word C4 L2 and components.yaml use
+       Library     an includable artifact — compiled or imported into something else, never run
+
+     "Container" is the kit's word, defined in templates/c4.md and carried by every LC's `container`
+     field. It MUST NOT be swapped for "application", "service", or "app" here — a synonym for a
+     term that already has a glossary entry is drift, and `wdi-reconcile` hunts for it. It does not
+     mean a Docker image; packaging is a separate question.
+
+     A unit that is neither is not a unit; it stays a line in Top level. When a unit stops being
+     separately deployable, it MUST move sections rather than keep its old heading. -->
+
+## Verified
+
+<!-- One line: date, commit SHA, and how the tree was read. If the commit is no longer an ancestor
+     of HEAD, this map is stale and MUST be refreshed before a gate reads it. -->
+
+## Top level
+
+<!-- Every base folder in the repo root, COMPLETE — including the dull ones. An unlisted folder is
+     the one people misuse, because nothing told them what it was for. Tag each entry so the two
+     sections below are predictable: [container] · [lib] · [docs] · [tooling] · [generated]. One
+     line of purpose per entry; no second line. -->
+
+```text
+{repo-root}/
+├── {unit}/                   # [container] what it is answerable for
+├── {unit}/                   # [lib] ...
+└── {folder}/                 # [docs] ...
+```
+
+## Containers
+
+<!-- One subsection per unit that runs or deploys on its own. Repeat the block below verbatim per
+     unit; if there is only one, there is still a subsection — a repo grows a second container
+     without warning.
+
+     Heading names MUST match the `container` values used in components.yaml, so an LC's container
+     can be checked against this map instead of trusted. A container with no code in this repo MUST
+     NOT get a subsection — it belongs to c4-l2-containers.md. A folder that builds more than one
+     container MUST say which. -->
+
+### {container}
+
+<!-- One line: what it is, and how it ships. Then the tree: folder convention first, ★ on the files
+     that earn it. Descend only until directories stop carrying distinct roles, and describe a
+     repeating shape ONCE with a placeholder such as <feature>/ rather than per instance. -->
+
+```text
+{container}/
+├── {entry-file}              # ★ ENTRY: what execution actually does first
+├── {folder}/                 # convention: what belongs here
+│   └── {file}                # ★ why this one is key
+└── {folder}/<feature>/       # the shape every feature repeats
+    ├── {sub}/                #   what goes in it
+    └── {sub}/                #   ...
+```
+
+<!-- One line, only when the unit has one: the authoritative call direction through those folders.
+     A builder who gets this wrong writes code that works and is still wrong. Cut if there is none;
+     do not invent one to fill the slot. -->
+
+**Flow:** {layer} → {layer} → {layer}
+
+## Libraries
+
+<!-- One subsection per includable artifact — compiled into or imported by something else, never
+     deployed on its own. A library is deliberately NOT a container, and MUST NOT appear at C4 L2.
+
+     Same block shape as a container, minus the entry point: a library that has one is a container
+     wearing the wrong label. -->
+
+### {library}
+
+<!-- One line: what it holds, and who consumes it. Then the annotated tree. -->
+
+```text
+{library}/
+├── {folder}/                 # convention: what belongs here
+│   └── {file}                # ★ why this one is key
+└── {folder}/
+```
+
+**Consumed by:** {units}
+
+## Generated
+
+<!-- Anything not written by hand, with its generator: codegen output, vendored trees, migration
+     snapshots. A generated folder edited by hand is a defect, so it MUST be named here even when it
+     looks like ordinary source. Cut the section if there is none. -->
+
+| Path | Generated by |
+| --- | --- |
+
+## Unclaimed
+
+<!-- Folders that exist but no one can state a purpose for. These are findings, not layout. Leave
+     them here, named, until they are claimed or deleted — inventing a purpose to empty this section
+     is the failure mode it exists to catch. Cut the section only when it is genuinely empty. -->
+
+---
+
+<!-- Keep this legend last, and keep it one line. -->
+
+★ = key file: entry point, wiring root, the single place a rule is enforced, or a file that must be
+opened before behaviour in its folder can be changed.

package/kit/.constitution/{document → method/document}/templates/structure-document.md

@@ -1,90 +1,90 @@
----
-type: structure
-scope: document
-verified: '{YYYY-MM-DD}'      # the day the tree was actually read
-commit: '{sha}'               # the commit it was read at — staleness is measured against this
----
-
-# Document Structure
-
-<!-- TEMPLATE GUIDE — act on these comments, then delete them.
-
-     This file is DESCRIPTIVE. It states which parts of the corpus actually carry content today.
-     The layers themselves, the placement test, the naming scheme, and slot numbering all belong to
-     corpus-guide.md and MUST NOT be restated here.
-
-     Written and refreshed only by `wdi-init` intent `structure`, never by hand. Rules for both maps live in
-     .constitution/structure-guide.md.
-
-     Same shape as the codebase map: annotated trees, folders complete, ★ inline on the documents
-     that earn it. What differs is the split — the codebase map splits by deployability, this one
-     splits by LAYER, because that is the axis a reader is lost on.
-
-     The five roots are fixed, so the top-level tree is not a discovery. Which sub-folders carry
-     content, which Product Component folders exist, and which slots have been split out of a kernel
-     ARE, and that is what this map is for. -->
-
-## Verified
-
-<!-- One line: date, commit SHA, and how the tree was read. If the commit is no longer an ancestor
-     of HEAD, this map is stale and MUST be refreshed before a gate reads it. -->
-
-## Top level
-
-<!-- The five roots, one line each, with the state of each: populated, or still empty. Mark an empty
-     root as empty rather than dropping it — a dropped root reads as a root that does not exist. -->
-
-```text
-.constitution/                # how we work — {state}
-.control/                     # what currently holds — {state}
-.what/                        # what was promised — {state}
-.how/                         # how it is built — {state}
-_bmad-output/                 # work in progress, not curated — {state}
-```
-
-## Per layer
-
-<!-- One subsection per root that carries content. Annotated tree: sub-folders complete, ★ on the
-     single-copy documents a reader must find first. Per-Product-Component folders are NOT expanded
-     here — the table below owns them, and expanding both means maintaining both. -->
-
-### {layer}
-
-```text
-{layer}/
-├── {folder}/                 # what belongs here
-│   └── {file}                # ★ why this one is key
-└── {folder}/                 # {state}
-```
-
-## Product Components
-
-<!-- One row per PC that actually exists. Both sides are expected: a PC with an SRS and no SDD, or
-     the reverse, is drift and MUST be listed under Findings rather than normalised here. List only
-     the slots that have been split out of a kernel; empty slots stay unlisted. -->
-
-| Product Component | `.what/<pc>/` | `.how/<pc>/` | Slots split out |
-| --- | --- | --- | --- |
-
-## Registries and generated
-
-<!-- Which registry files carry entries and which are still empty skeletons, and which generated
-     tables have been produced. Generated output is never written by hand; naming it here is what
-     makes a hand edit visible. -->
-
-| File | State |
-| --- | --- |
-
-## Findings
-
-<!-- Drift this map surfaced while being derived: a PC on one side only, a supplement with no
-     citation, a folder outside the five roots, a document whose home contradicts corpus-guide.md.
-     Findings are reported, never fixed here — fixing them is `wdi-reconcile` work, or the owning
-     skill's.
-     Cut the section only when it is genuinely empty. -->
-
----
-
-<!-- Keep this legend last, and keep it one line. -->
-
-★ = key document: single-copy, referenced from elsewhere, or the first thing a reader must find.
+---
+type: structure
+scope: document
+verified: '{YYYY-MM-DD}'      # the day the tree was actually read
+commit: '{sha}'               # the commit it was read at — staleness is measured against this
+---
+
+# Document Structure
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them.
+
+     This file is DESCRIPTIVE. It states which parts of the corpus actually carry content today.
+     The layers themselves, the placement test, the naming scheme, and slot numbering all belong to
+     corpus-guide.md and MUST NOT be restated here.
+
+     Written and refreshed only by `wdi-init` intent `structure`, never by hand. Rules for both maps live in
+     .constitution/method/structure-guide.md.
+
+     Same shape as the codebase map: annotated trees, folders complete, ★ inline on the documents
+     that earn it. What differs is the split — the codebase map splits by deployability, this one
+     splits by LAYER, because that is the axis a reader is lost on.
+
+     The five roots are fixed, so the top-level tree is not a discovery. Which sub-folders carry
+     content, which Product Component folders exist, and which slots have been split out of a kernel
+     ARE, and that is what this map is for. -->
+
+## Verified
+
+<!-- One line: date, commit SHA, and how the tree was read. If the commit is no longer an ancestor
+     of HEAD, this map is stale and MUST be refreshed before a gate reads it. -->
+
+## Top level
+
+<!-- The five roots, one line each, with the state of each: populated, or still empty. Mark an empty
+     root as empty rather than dropping it — a dropped root reads as a root that does not exist. -->
+
+```text
+.constitution/                # how we work — {state}
+.control/                     # what currently holds — {state}
+.what/                        # what was promised — {state}
+.how/                         # how it is built — {state}
+_bmad-output/                 # work in progress, not curated — {state}
+```
+
+## Per layer
+
+<!-- One subsection per root that carries content. Annotated tree: sub-folders complete, ★ on the
+     single-copy documents a reader must find first. Per-Product-Component folders are NOT expanded
+     here — the table below owns them, and expanding both means maintaining both. -->
+
+### {layer}
+
+```text
+{layer}/
+├── {folder}/                 # what belongs here
+│   └── {file}                # ★ why this one is key
+└── {folder}/                 # {state}
+```
+
+## Product Components
+
+<!-- One row per PC that actually exists. Both sides are expected: a PC with an SRS and no SDD, or
+     the reverse, is drift and MUST be listed under Findings rather than normalised here. List only
+     the slots that have been split out of a kernel; empty slots stay unlisted. -->
+
+| Product Component | `.what/<pc>/` | `.how/<pc>/` | Slots split out |
+| --- | --- | --- | --- |
+
+## Registries and generated
+
+<!-- Which registry files carry entries and which are still empty skeletons, and which generated
+     tables have been produced. Generated output is never written by hand; naming it here is what
+     makes a hand edit visible. -->
+
+| File | State |
+| --- | --- |
+
+## Findings
+
+<!-- Drift this map surfaced while being derived: a PC on one side only, a supplement with no
+     citation, a folder outside the five roots, a document whose home contradicts corpus-guide.md.
+     Findings are reported, never fixed here — fixing them is `wdi-reconcile` work, or the owning
+     skill's.
+     Cut the section only when it is genuinely empty. -->
+
+---
+
+<!-- Keep this legend last, and keep it one line. -->
+
+★ = key document: single-copy, referenced from elsewhere, or the first thing a reader must find.

package/kit/.constitution/{language-guide.md → method/language-guide.md}

@@ -6,7 +6,7 @@ status: Accepted
 
 **Loaded when:** naming anything — a code identifier, a database field, a file, a folder.
 
-Which language a name is written in, and nothing else. Case style → `codebase/conventions-guide.md`;
+Which language a name is written in, and nothing else. Case style → `../project/codebase-conventions-guide.md`;
 legal characters → `structure-guide.md`; the right domain word → `.control/product-glossary.md`.
 
 ## Code MUST be English
@@ -71,4 +71,4 @@ and they travel to every repo through the `wdi-method` package.
 ## A wrong name MUST NOT be fixed inside an unrelated change
 
 A rename reaches the schema, the API, and every caller. It gets a change of its own, or a ratified
-row in `codebase/brownfield-guide.md`. A **new** name MUST NOT copy a wrong neighbour.
+row in `../project/codebase-brownfield-guide.md`. A **new** name MUST NOT copy a wrong neighbour.

package/kit/.constitution/{repo-guide.md → method/repo-guide.md}

@@ -82,9 +82,22 @@ 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`.
+Method files in `.constitution/`, the `wdi-*` skills, and `_bmad/custom/*.toml` arrive from the
+public WDI Method package via `npx wdi-method install` / `update`.
+
+**Three paths inside `.constitution/` are this product's, not the method's.** Each is seeded once
+when absent and then never written again — an update MUST NOT touch one, and `promote` MUST NOT
+carry one back into the package:
+
+| Path | Holds |
+|---|---|
+| `constitution.md` | This product's Articles 1, 2, and 5 |
+| `codebase/*-guide.md` | This product's stack, conventions, and brownfield rules — at **any** `status:`, including `Draft`, which is when they are being written |
+| `project/` | Any rule that binds only this product |
+
+The seam is the **path**, 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.
 
 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