wdi-method 0.5.0 → 0.5.2

package/kit/.constitution/method/scripts/validate.py

@@ -21,6 +21,7 @@ from __future__ import annotations
 
 import argparse
 import datetime as dt
+import os
 import re
 import subprocess
 import sys
@@ -482,7 +483,16 @@ FRONTMATTER_KEYS = ("reviewed:", "date:", "sha:", "lenses:", "updated:")
 
 
 def _reviewed_ok(r: Result, rel: str, block: object, need: set[str]) -> None:
-    if not isinstance(block, dict) or not block.get("sha") or not block.get("date"):
+    # str() before the truth test: an unquoted sha of all digits — `0000000`, and roughly one
+    # short sha in twenty-seven is all digits — is read by YAML as the INTEGER 0, which is falsy.
+    # The old test then reported "carries no reviewed trace" about a file that plainly carries one,
+    # which is the worst kind of finding: correct-looking, and wrong.
+    if not isinstance(block, dict):
+        r.fail("V13", rel, "carries no `reviewed` trace with a date and sha")
+        return
+    # NOT `block.get("sha") or ""` — for the integer 0 that yields "" and reintroduces the very
+    # bug this guards. `.get(key, "")` returns the 0, and str(0) is "0", which is truthy.
+    if not str(block.get("sha", "")).strip() or not str(block.get("date", "")).strip():
         r.fail("V13", rel, "carries no `reviewed` trace with a date and sha")
         return
     lenses = {str(x) for x in (block.get("lenses") or [])}
@@ -713,7 +723,12 @@ def v19(c: Corpus, r: Result) -> None:
 
 PLATFORM = "_platform"
 CROSS_CUTTING = ".how/_platform/cross-cutting.md"
-PLATFORM_DATA_HEADING = "Milik platform"
+# The section heading V21 looks for. A heading a SCRIPT matches is a machine-facing key, and
+# `language-guide.md` says a key is always English — so the template writes the English one and
+# this is what a new corpus carries. The Indonesian form is kept as a READER-side alias, exactly
+# like `yes|ya`: a corpus written before this MUST NOT be migrated for a regex.
+PLATFORM_DATA_HEADINGS = ("Platform-owned", "Milik platform")
+PLATFORM_DATA_HEADING = PLATFORM_DATA_HEADINGS[0]
 
 
 def v21(c: Corpus, r: Result) -> None:
@@ -797,7 +812,7 @@ def _platform_documented(c: Corpus, r: Result, entities: list[str]) -> None:
         return
     path = c.root / CROSS_CUTTING
     text = path.read_text(encoding="utf-8", errors="replace") if path.exists() else ""
-    if PLATFORM_DATA_HEADING.lower() not in text.lower():
+    if not any(h.lower() in text.lower() for h in PLATFORM_DATA_HEADINGS):
         r.skip("V21", f"`{CROSS_CUTTING}` has no `{PLATFORM_DATA_HEADING}` section yet — "
                       f"{len(entities)} entities with platform_owns are not documented yet: "
                       + ", ".join(sorted(entities)))
@@ -906,6 +921,40 @@ CITE_RE = re.compile(
     r"/[A-Za-z0-9_./-]+\.(?:md|yaml|yml|py|go|tsx|ts|js|mjs|sql|html|css|json))`")
 
 
+# Directories that MUST be pruned DURING traversal, not filtered afterwards.
+#
+# The old form was `c.root.rglob("*.md")` plus a `rel.startswith(...)` filter, and it had two faults
+# that only showed up on a real machine:
+#
+#   The filter ran too late. rglob had already walked in, so a dangling symlink inside
+#   node_modules — an npm workspace link left behind by an abandoned git worktree — raised
+#   FileNotFoundError and took the whole run down. A validator that CRASHES on somebody's build
+#   output reports nothing about the corpus at all.
+#
+#   `node_modules/` matched only at the ROOT. `web/node_modules/` sailed straight through, which is
+#   where a monorepo actually keeps it.
+PRUNE_DIRS = frozenset({
+    ".git", "node_modules", "__pycache__", ".venv", "venv", "dist", "build",
+    ".pytest_cache", ".mypy_cache", ".ruff_cache", ".next", ".turbo", ".idea", ".vscode",
+    "worktrees",   # .claude/worktrees/ — another checkout's tree is not this corpus
+})
+
+
+def _walk_corpus(root: Path, suffixes: tuple[str, ...]) -> list[Path]:
+    """Every file under `root` with one of `suffixes`, sorted, pruning PRUNE_DIRS as it goes.
+
+    Sorted because determinism is this script's contract: two runs over the same tree MUST report the
+    same thing in the same order.
+    """
+    out: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(root, onerror=lambda _e: None):
+        dirnames[:] = sorted(d for d in dirnames if d not in PRUNE_DIRS)
+        for name in filenames:
+            if name.endswith(suffixes):
+                out.append(Path(dirpath) / name)
+    return sorted(out)
+
+
 def v24(c: Corpus, r: Result) -> None:
     """A path citation inside a document that STATES what currently holds MUST resolve.
 
@@ -921,9 +970,9 @@ def v24(c: Corpus, r: Result) -> None:
     there names a file nobody is allowed to fix.
     """
     scanned = 0
-    for path in sorted(c.root.rglob("*.md")) + sorted(c.root.rglob("*.yaml")):
+    for path in _walk_corpus(c.root, (".md", ".yaml")):
         rel = path.relative_to(c.root).as_posix()
-        if rel.startswith((".git/", "node_modules/", "_bmad-output/", ".claude/skills/bmad-")):
+        if rel.startswith(("_bmad-output/", ".claude/skills/bmad-")):
             continue
         if rel.startswith(PAST_RECORD) or rel.startswith(FROZEN) or rel.startswith(DERIVED):
             continue

package/kit/.constitution/method/why/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/.constitution/project/README.md

@@ -1,68 +1,68 @@
----
-status: Accepted
-scope: project-room
----
-
-# `.constitution/project/` — this product's custom rules
-
-**This folder belongs to the product, not to the method.** It is seeded once at install, and after
-that `wdi-method update` **never** writes over a file in it. `wdi-method promote` **skips it entirely**,
-so nothing you write here can reach the public package.
-
-This README is the one exception: it is authored in the package and `promote` never carries it home.
-You MAY edit it, but the edit will not survive the next install elsewhere — so **your rules MUST be
-other files.**
-
-## What goes here
-
-Normative rules that hold **only in this product**, and are not code conventions:
-
-- a review policy a client requires
-- a process rule that came out of a contract
-- a naming or language policy that differs from the method default
-- a prohibition or obligation specific to this domain
-
-## What does not
-
-| The thing | Its home |
-|---|---|
-| Product or client name | `.control/registry/index.yaml` → `product:` |
-| Code conventions, stack, brownfield patterns | `.constitution/codebase/*-guide.md` — already protected once `Accepted` |
-| Scope, method ownership, repo checklist | `constitution.md` Articles 1, 2, 5 — already protected |
-| Agent instructions for this product | `AGENTS.md`, **outside** the marked `wdi-method` block |
-| BMad overrides for this product | `_bmad/custom/*.user.toml` |
-| State, promises, design | `.control/` · `.what/` · `.how/` |
-
-**A generic rule MUST NOT be moved here.** If it holds in any project, it belongs to the package — fix
-it there, then `promote`. Using this room to bypass the package is how a method stops being generic
-with nobody deciding it, and **an empty room is a valid state**: filling it so that it gets used is the
-very failure this rule prevents.
-
-## The shape of a file here
-
-Frontmatter is required, and `V27` checks it:
-
-```yaml
----
-scope: project              # REQUIRED, and exactly this value
-purpose: ""                 # REQUIRED, one line: what this rule protects
-overrides: null             # optional: the kit file it narrows or contradicts
-decision: null              # REQUIRED when `overrides:` is set — the DEC- that decided it
----
-```
-
-- A file here MAY **narrow** or **add to** a generic rule with no `overrides:` at all.
-- To **contradict** a generic rule it MUST name that rule in `overrides:` and carry `decision:`.
-  Without both, this room becomes the place where generic rules are broken with no trace — and that is
-  what stops a method being trustworthy in the next repo.
-- An `overrides:` pointing at a file that does not exist is a finding, not a typo: it means the rule
-  being contradicted is gone, and the contradiction may no longer have a reason.
-
-## Why whole files, and not marked blocks
-
-`AGENTS.md` uses a marked block because it is **one** file. `.constitution/` has fifty-odd, and marked
-blocks inside them would make `update` perform surgery in every file — one broken marker and either
-the product's rule is erased, or the generic rule freezes forever.
-
-Whole files in their own room avoid both, and they keep a product's rules **readable in one place**
-instead of scattered inside fifty files that belong to somebody else.
+---
+status: Accepted
+scope: project-room
+---
+
+# `.constitution/project/` — this product's custom rules
+
+**This folder belongs to the product, not to the method.** It is seeded once at install, and after
+that `wdi-method update` **never** writes over a file in it. `wdi-method promote` **skips it entirely**,
+so nothing you write here can reach the public package.
+
+This README is the one exception: it is authored in the package and `promote` never carries it home.
+You MAY edit it, but the edit will not survive the next install elsewhere — so **your rules MUST be
+other files.**
+
+## What goes here
+
+Normative rules that hold **only in this product**, and are not code conventions:
+
+- a review policy a client requires
+- a process rule that came out of a contract
+- a naming or language policy that differs from the method default
+- a prohibition or obligation specific to this domain
+
+## What does not
+
+| The thing | Its home |
+|---|---|
+| Product or client name | `.control/registry/index.yaml` → `product:` |
+| Code conventions, stack, brownfield patterns | `codebase-*-guide.md`, here in this room — protected at **any** `status:` |
+| Scope, method ownership, repo checklist | `constitution.md` Articles 1, 2, 5, here in this room |
+| Agent instructions for this product | `AGENTS.md`, **outside** the marked `wdi-method` block |
+| BMad overrides for this product | `_bmad/custom/*.user.toml` |
+| State, promises, design | `.control/` · `.what/` · `.how/` |
+
+**A generic rule MUST NOT be moved here.** If it holds in any project, it belongs to the package — fix
+it there, then `promote`. Using this room to bypass the package is how a method stops being generic
+with nobody deciding it, and **an empty room is a valid state**: filling it so that it gets used is the
+very failure this rule prevents.
+
+## The shape of a file here
+
+Frontmatter is required, and `V27` checks it:
+
+```yaml
+---
+scope: project              # REQUIRED, and exactly this value
+purpose: ""                 # REQUIRED, one line: what this rule protects
+overrides: null             # optional: the kit file it narrows or contradicts
+decision: null              # REQUIRED when `overrides:` is set — the DEC- that decided it
+---
+```
+
+- A file here MAY **narrow** or **add to** a generic rule with no `overrides:` at all.
+- To **contradict** a generic rule it MUST name that rule in `overrides:` and carry `decision:`.
+  Without both, this room becomes the place where generic rules are broken with no trace — and that is
+  what stops a method being trustworthy in the next repo.
+- An `overrides:` pointing at a file that does not exist is a finding, not a typo: it means the rule
+  being contradicted is gone, and the contradiction may no longer have a reason.
+
+## Why whole files, and not marked blocks
+
+`AGENTS.md` uses a marked block because it is **one** file. `.constitution/` has fifty-odd, and marked
+blocks inside them would make `update` perform surgery in every file — one broken marker and either
+the product's rule is erased, or the generic rule freezes forever.
+
+Whole files in their own room avoid both, and they keep a product's rules **readable in one place**
+instead of scattered inside fifty files that belong to somebody else.

package/kit/.constitution/project/constitution.md

@@ -44,18 +44,19 @@ What is particular to this repo, and therefore lives here:
 
 This is the **consumer** article. Use it in every product repo.
 
-`.constitution/` guides and templates (except this file's Articles 1, 2, and 5,
-`codebase/*-guide.md`, 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`.
+Everything in `.constitution/method/`, the `wdi-*` skills, and
+`_bmad/custom/*.toml` arrive from the public WDI Method package via
+`npx wdi-method install` / `update`. Everything in `.constitution/project/` —
+this file, `codebase-*-guide.md`, and any rule this repo adds — is **ours**: it is
+seeded once and never written again.
 
 - 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`.
-- `wdi-method update` MUST overwrite method files and MUST NOT touch `.what/`,
-  `.how/`, `.control/` product state, this file's Articles 1–2 and 5,
-  `codebase/*-guide.md` once `Accepted`, extra constitution files this repo
-  added, or `_bmad/custom/*.user.toml`.
+- `wdi-method update` MUST overwrite everything in `.constitution/method/` and
+  MUST NOT touch `.what/`, `.how/`, `.control/` product state, anything in
+  `.constitution/project/` — at **any** `status:`, `Draft` included, which is when
+  a codebase guide is actually written — or `_bmad/custom/*.user.toml`.
 - A rule particular to this repo MUST be written out in full in this file or a
   sibling, and MUST NOT be replaced by a pointer into another repository.