wdi-method 0.6.7 → 0.6.15

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

@@ -185,6 +185,27 @@ def git(root: Path, *args: str) -> str | None:
 REQUIREMENT_KEYS = ("goals", "capabilities", "functional", "nonfunctional", "journeys")
 
 
+def is_withdrawn(row: dict) -> bool:
+    """`status: withdrawn` — the product stopped promising this, and the row STAYED.
+
+    Deleting it is what a repo used to do, and the cost was measured: two capabilities withdrawn by
+    decision, their rows removed, and twelve `refs-resolve` findings — eight `DEC-` rows still named
+    them, six of which genuinely served them at the time. `corpus-guide.md` forbids the other repair:
+    a retired name in a record of what happened is a fact about the past, and a `DEC-` is exactly
+    that record.
+
+    So a withdrawn row is read TWO ways. It is still **defined** — every old reference resolves and
+    `id-allocated-once` still refuses the number to anyone else. It is no longer **promised** — no UC
+    is owed, no ticket, no RTM row, and `promise_progress` is not dragged down by something nobody
+    promises.
+    """
+    return str(row.get("status") or "").strip().lower() == "withdrawn"
+
+
+def promised(items: list[dict]) -> list[dict]:
+    return [row for row in items if not is_withdrawn(row)]
+
+
 @dataclass
 class Corpus:
     root: Path
@@ -253,23 +274,23 @@ class Corpus:
     # --- shortcuts used repeatedly
     @property
     def goals(self) -> list[dict]:
-        return rows(self.requirements, "goals")
+        return promised(rows(self.requirements, "goals"))
 
     @property
     def caps(self) -> list[dict]:
-        return rows(self.requirements, "capabilities")
+        return promised(rows(self.requirements, "capabilities"))
 
     @property
     def frs(self) -> list[dict]:
-        return rows(self.requirements, "functional")
+        return promised(rows(self.requirements, "functional"))
 
     @property
     def nfrs(self) -> list[dict]:
-        return rows(self.requirements, "nonfunctional")
+        return promised(rows(self.requirements, "nonfunctional"))
 
     @property
     def ucs(self) -> list[dict]:
-        return rows(self.usecases, "usecases")
+        return promised(rows(self.usecases, "usecases"))
 
     @property
     def decs(self) -> list[dict]:
@@ -282,6 +303,15 @@ class Corpus:
             return own
         return str(self.index.get("mode") or "").strip() or "catalog"
 
+    @property
+    def withdrawn_rows(self) -> list[dict]:
+        """Every withdrawn requirement row, with the key it came from — the id side of the split."""
+        out = []
+        for key in REQUIREMENT_KEYS:
+            out += [(key, row) for row in rows(self.requirements, key) if is_withdrawn(row)]
+        out += [("usecases", row) for row in rows(self.usecases, "usecases") if is_withdrawn(row)]
+        return [row for _, row in out]
+
     @property
     def lcs(self) -> list[dict]:
         return rows(self.components, "logical_components")
@@ -341,6 +371,18 @@ def _legacy_tickets(spec: dict) -> list[dict]:
     yet scheduled, and a closed wave has nothing left to schedule.
     """
     sid = str(spec.get("id") or "")
+
+    def scoped(raw: str) -> str:
+        """`W7-S2` under wave `W7` stays `W7-S2`, not `W7-W7-S2`.
+
+        The prefix exists so two waves both naming a story `"1"` cannot collide into one node. A
+        story already scoped to its wave has nothing to collide with, and prefixing it again produces
+        an id that matches no file, no memlog line, and nothing a person would search for. Measured on
+        a live repo whose RTM read `W7-W7-S2`.
+        """
+        sub = str(raw)
+        return sub if sid and sub.startswith(f"{sid}-") else f"{sid}-{sub}"
+
     out = []
     for epic in spec.get("epics") or []:
         if not isinstance(epic, dict):
@@ -349,8 +391,8 @@ def _legacy_tickets(spec: dict) -> list[dict]:
             if not isinstance(story, dict):
                 continue
             ticket = {k: v for k, v in story.items() if k not in ("id", "depends_on")}
-            ticket["id"] = f"{sid}-{story.get('id')}"
-            ticket["blocked_by"] = [f"{sid}-{d}" for d in (story.get("depends_on") or [])]
+            ticket["id"] = scoped(story.get("id"))
+            ticket["blocked_by"] = [scoped(d) for d in (story.get("depends_on") or [])]
             # The story's OWN id is kept because the file on disk is named after it, not after the
             # synthesized ticket id — see `_ticket_files`.
             ticket["_legacy_story_id"] = str(story.get("id") or "")
@@ -461,6 +503,8 @@ def refs_resolve(c: Corpus, r: Result) -> None:  # was V6
         defined.add(str(spec.get("id")))
     for _, ticket in c.tickets():
         defined.add(str(ticket.get("id")))
+    # Withdrawn, therefore still defined. This is the whole point of keeping the row.
+    defined |= {str(row.get("id")) for row in c.withdrawn_rows if row.get("id") is not None}
 
     refs: list[tuple[str, str]] = []
     for cap in c.caps:
@@ -482,9 +526,21 @@ def refs_resolve(c: Corpus, r: Result) -> None:  # was V6
         refs += [(str(ticket.get("id")), u) for u in listy(ticket, "satisfies")]
         refs += [(str(ticket.get("id")), b) for b in listy(ticket, "blocked_by")]
 
+    # A promise's id going missing has one likely cause and one wrong-looking-obvious repair. The
+    # cause: the row was DELETED when the product stopped promising it. The wrong repair: edit the
+    # reference — which `corpus-guide.md` refuses, because a `DEC-` records what happened and it did
+    # serve that promise at the time. One repo carried twelve of these before anyone worked out that
+    # the row was meant to stay, so the route travels with the finding.
+    promise_id = re.compile(r"^(BG|CAP|FR|NFR|UC)-\d+$")
     for owner, target in sorted(set(refs)):
         if target and target not in defined:
-            r.fail("refs-resolve", owner, f"points to `{target}` which does not exist in any registry")
+            hint = ""
+            if promise_id.match(target):
+                hint = (" — if it was withdrawn, the row STAYS with `status: withdrawn` and a "
+                        "`withdrawn_by`, and deleting it is what broke this reference (corpus-guide.md). "
+                        "Editing the reference instead rewrites a record of the past")
+            r.fail("refs-resolve", owner,
+                   f"points to `{target}` which does not exist in any registry{hint}")
 
 
 def _cycles(graph: dict[str, list[str]]) -> list[str]:
@@ -1490,7 +1546,8 @@ def custom_room_declared(c: Corpus, r: Result) -> None:  # was V27
 #
 # The two rendered trees are DELIBERATELY absent from this list. They are regenerated by this
 # script, so a product that declines to commit derived output is making a choice the method allows.
-COMMITTED_DIRS = (".constitution", ".control", ".what", ".how", "_bmad-output", ".work")
+COMMITTED_DIRS = (".constitution", ".control", ".what", ".how", "_bmad-output", ".work",
+                  ".scratch")
 
 # Probed inside each directory above, and named so that no honest pattern would ever mean to match
 # it. The distinction this draws is the entire point of the check: `.work/upstream/` or
@@ -1548,6 +1605,117 @@ def corpus_in_git(c: Corpus, r: Result) -> None:
                    f"so no clone has what is in it")
 
 
+ENGINE_HOMES = (".claude", ".agents", ".agent", ".cursor", ".codex")
+ENGINE_FLAGGED = ("to-spec", "to-tickets", "implement")
+ENGINE_SKILLS = ENGINE_FLAGGED + ("tdd", "code-review", "domain-modeling")
+FLAG_RE = re.compile(r"^disable-model-invocation\s*:\s*true", re.M)
+
+
+def _engine_files(root: Path, name: str) -> list[Path]:
+    """Every copy of one engine, de-duplicated by what it resolves to.
+
+    `npx skills add` can symlink one SKILL.md into several platform folders, so the same file is
+    reachable under `.claude/skills/` and `.agents/skills/` at once. Reporting it twice would make
+    one finding read as two.
+    """
+    seen: dict[Path, Path] = {}
+    for home in ENGINE_HOMES:
+        path = root / home / "skills" / name / "SKILL.md"
+        if not path.is_file():
+            continue
+        try:
+            seen.setdefault(path.resolve(), path)
+        except OSError:
+            seen.setdefault(path, path)
+    return list(seen.values())
+
+
+def _frontmatter(text: str) -> str:
+    m = FM.match(text)
+    return m.group(1) if m else ""
+
+
+def engines_invocable(c: Corpus, r: Result) -> None:
+    """The three flagged engines MUST be invocable in the repo's own copies.
+
+    `to-spec`, `to-tickets` and `implement` ship with `disable-model-invocation: true`. Nothing
+    outside the file lifts it — Claude Code's gate reads the frontmatter and consults no setting,
+    and `skillOverrides` only ever tightens — so `wdi-method` strips the key from the copies the
+    repo owns and writes one guard line in its place. That is what lets `wdi-build` invoke an engine
+    and `wdi-autopilot` run an iteration with nobody watching.
+
+    Two things put the key back, both routine: `npx skills update`, which restores the author's file
+    byte for byte, and a fresh `npx skills add`. Neither says anything, and the failure surfaces
+    hours later as an unattended run that stalled at Phase 2 with no explanation. This is the check
+    that turns that into a line of output.
+
+    Checked in the FRONTMATTER, not the file: the guard line is prose about the key, and matching
+    the whole file would fail on the fix rather than on the defect.
+
+    A repo with no engines at all is SKIPPED, not failed. `--skip-engines-check` is a supported
+    install — CI, and a repo that will never reach G5 — and a validator that is permanently red
+    there is a validator that gets ignored everywhere else.
+    """
+    installed = {name: _engine_files(c.root, name) for name in ENGINE_SKILLS}
+    if not any(installed.values()):
+        r.skip("engines-invocable", "no engines in this repo — G5 cannot run until they are "
+                            "installed (`npx skills@latest add mattpocock/skills`), and until then "
+                            "there is nothing here to check")
+        return
+    for name in ENGINE_SKILLS:
+        if not installed[name]:
+            r.fail("engines-invocable", name, "is not installed in this repo — G5 needs all six, and "
+                              "a user-level plugin does not count: its files are not this repo's to unlock")
+    for name in ENGINE_FLAGGED:
+        for path in installed[name]:
+            if FLAG_RE.search(_frontmatter(path.read_text(encoding="utf-8", errors="replace"))):
+                r.fail("engines-invocable", name,
+                       f"{path.relative_to(c.root).as_posix()} carries `disable-model-invocation` "
+                       f"again — no skill can invoke it, so wdi-build stops at Phase 2. `npx skills "
+                       f"update` restores it; `npx wdi-method engines --fix` strips it back out")
+
+
+def withdrawn_recorded(c: Corpus, r: Result) -> None:
+    """Two things, and without either one `withdrawn` is just a word that quiets a validator.
+
+    **It names the decision.** Withdrawing a promise is decision-worthy on the method's own terms —
+    `corpus-guide.md` lists "no `BG`/`CAP`/`FR`/`NFR`/`UC`/`LC` id is born, renamed, or retired" as a
+    test for whether something is a `DEC-`. So `withdrawn_by` MUST name one that exists.
+
+    **It does not orphan what is left.** A live `FR` whose capability is withdrawn still promises
+    something whose capability nobody promises any more. Withdrawal that takes half a chain with it
+    silently is worse than the deletion this replaced, because at least deletion went red.
+    """
+    dec_ids = {str(d.get("id")) for d in c.decs}
+    for row in c.withdrawn_rows:
+        rid = str(row.get("id") or "")
+        by = str(row.get("withdrawn_by") or "").strip()
+        if not by:
+            r.fail("withdrawn-recorded", rid, "is `status: withdrawn` and names no `withdrawn_by`. "
+                            "Withdrawing a promise is a decision — name the `DEC-` that took it, or the "
+                            "word is only silencing a validator")
+        elif by not in dec_ids:
+            r.fail("withdrawn-recorded", rid, f"names `withdrawn_by: {by}`, which is not a decision in "
+                            f"`decisions.yaml`")
+
+    withdrawn_ids = {str(row.get("id")) for row in c.withdrawn_rows}
+    if not withdrawn_ids:
+        return
+    for row, parent_key, what in ([(x, "goal", "goal") for x in c.caps]
+                                  + [(x, "capability", "capability") for x in c.frs]
+                                  + [(x, "capability", "capability") for x in c.nfrs]):
+        parent = str(row.get(parent_key) or "").strip()
+        if parent and parent in withdrawn_ids:
+            r.fail("withdrawn-recorded", str(row.get("id")),
+                   f"is live, and the {what} it hangs off (`{parent}`) is withdrawn. Withdraw this row "
+                   f"too, or move it under something still promised")
+    for uc in c.ucs:
+        for fr in listy(uc, "satisfies"):
+            if fr in withdrawn_ids:
+                r.fail("withdrawn-recorded", str(uc.get("id")),
+                       f"is live and satisfies `{fr}`, which is withdrawn")
+
+
 def id_allocated_once(c: Corpus, r: Result) -> None:  # was V28
     """One id, one row — across every file the requirement registry is split into.
 
@@ -1582,7 +1750,7 @@ def run_checks(c: Corpus, asof: dt.date) -> Result:
     # no two copies left to compare.
     # V19 is REPEALED. It checked one line item — an `RTR-` file in .control/reports/ — and the
     # retrospective it archived was the only thing spec size `L` ever decided. Both went together.
-    for fn in (goal_has_fr, fr_has_uc, uc_scheduled, ticket_has_test, nfr_has_enforcer, refs_resolve, no_cycles, applied_dec_touches, locked_gate_passed, parallel_tickets_blocked, lc_registered, review_trace, chain_links, memlog_home, spec_names_release_prd, ticket_status_one_home, defect_root_cause, entity_one_writer, spec_after_g4, high_risk_named, mandate_accept, cites_resolve, container_built, custom_room_declared, corpus_in_git, id_allocated_once):
+    for fn in (goal_has_fr, fr_has_uc, uc_scheduled, ticket_has_test, nfr_has_enforcer, refs_resolve, no_cycles, applied_dec_touches, locked_gate_passed, parallel_tickets_blocked, lc_registered, review_trace, chain_links, memlog_home, spec_names_release_prd, ticket_status_one_home, defect_root_cause, entity_one_writer, spec_after_g4, high_risk_named, mandate_accept, cites_resolve, container_built, custom_room_declared, corpus_in_git, engines_invocable, withdrawn_recorded, id_allocated_once):
         fn(c, r)
     plan_dates(c, r, asof)
     return r
@@ -1785,7 +1953,7 @@ def gen_status(c: Corpus, rtm: dict, result: Result) -> dict:
         per_spec.append({"spec": wid, "status": spec.get("status"),
                          "tickets_done": done, "tickets_total": len(items),
                          "work_progress": _pct(done, len(items))})
-    applicable = 26  # goal-has-fr..id-allocated-once minus V10 and V19, both repealed
+    applicable = 28  # goal-has-fr..id-allocated-once minus V10 and V19, both repealed
     return {
         "promise_progress": _pct(green, len(counted)),
         "rtm_rows": {"green": green, "counted": len(counted),