wdi-method 0.6.8 → 0.6.18

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]:
@@ -1079,18 +1135,64 @@ def _dec_date(c: Corpus, dec: dict) -> dt.date | None:
     return None
 
 
+# A mandate whose authority ONCE stood. `accepted` and `applied` are live; `superseded` is retired,
+# and retirement is NOT retroactive — the owner accepted it in person, and what was taken under it
+# while it stood stays accepted. Reading this status as present tense is what turned a whole run's
+# decisions red the day the owner changed one setting of the mandate, with no repair available that
+# does not falsify the record: the decisions are frozen, and the supersession really happened.
+MANDATE_STOOD = ("accepted", "applied", "superseded")
+
+
+def _dec_fm(c: Corpus, dec: dict) -> dict:
+    """The frontmatter of a decision's own file — `supersedes`/`superseded_by` live there in the
+    template, and a product that wrote them only in the file is not wrong."""
+    did = str(dec.get("id") or "")
+    if not did:
+        return {}
+    for path in sorted(c.root.glob(f".control/decisions/{did}-*.md")):
+        return frontmatter(path) or {}
+    return {}
+
+
+def _revoked_on(c: Corpus, mandate: dict, by_id: dict[str, dict]) -> dt.date | None:
+    """The day a superseded mandate stopped delegating: the date of the decision that replaced it.
+
+    For a mandate, supersession IS revocation — `wdi-autopilot` names it as the way a run is ended
+    for good, and the way a setting is changed. So it binds tighter than `expires`, and the window
+    ends at whichever of the two came first.
+    """
+    if str(mandate.get("status") or "") != "superseded":
+        return None
+    ref = str(mandate.get("superseded_by") or _dec_fm(c, mandate).get("superseded_by") or "").strip()
+    if not ref:
+        return None
+    return _dec_date(c, by_id.get(ref) or {})
+
+
 def mandate_accept(c: Corpus, r: Result) -> None:
-    """A decision accepted BY DELEGATION points at a real mandate that had not lapsed when it was taken.
+    """A decision accepted BY DELEGATION points at a mandate that stood, and had not ended, when it was taken.
 
     `wdi-autopilot` lets the agent accept decisions the owner would have accepted, and that is legal
     only because the owner accepted the MANDATE in person. So three things hold: a mandate is never
-    itself accepted by another decision — the chain of authority has a person at its root; an accepted
-    mandate names the day it ends, or it is standing permission; and a decision whose `accepted_by` is
-    a `DEC-` names one that is `type: mandate`, accepted, and unexpired on the decision's own date.
+    itself accepted by another decision — the chain of authority has a person at its root; a mandate
+    that stood names the day it ends, or it is standing permission; and a decision whose `accepted_by`
+    is a `DEC-` names one that is `type: mandate`, stood on the decision's own date, and had not ended
+    by then — expired, or superseded, whichever came first.
+
+    Every question it asks is about the PAST, so every answer is read from the past. A mandate's
+    status today says when its authority ENDED, never that it was never granted: `superseded` is a
+    retired mandate, and the decisions taken under it while it stood are still accepted. The one
+    thing supersession does change is the window — see `_revoked_on`.
 
     It says nothing about WHAT was decided — that is the ledger's job and the owner's review.
     """
     by_id = {str(d.get("id")): d for d in c.decs}
+    # Which mandates were actually USED. A retired mandate's obligations are read from what was taken
+    # under it, not from its status: superseding one that delegated nothing owes no account of a run
+    # that never happened, and superseding one that delegated forty decisions owes exactly what it
+    # owed the day before — otherwise supersession is a way to make the ledger demand disappear.
+    delegated_under = {str(d.get("accepted_by") or "").strip() for d in c.decs
+                       if str(d.get("type") or "") != "mandate"}
     for dec in c.decs:
         did = str(dec.get("id"))
         ref = str(dec.get("accepted_by") or "").strip()
@@ -1100,7 +1202,7 @@ def mandate_accept(c: Corpus, r: Result) -> None:
                 r.fail("mandate-accept", did,
                        f"is a mandate accepted by delegation (`accepted_by: {ref}`) — the mandate is the one "
                        f"decision the owner accepts in person")
-            if status in ("accepted", "applied"):
+            if status in ("accepted", "applied") or (status == "superseded" and did in delegated_under):
                 if not ref:
                     r.fail("mandate-accept", did, "is an accepted mandate and `accepted_by` names nobody — "
                                                   "a person and a date is enough")
@@ -1121,6 +1223,17 @@ def mandate_accept(c: Corpus, r: Result) -> None:
                     # silently disables the lapse comparison for every decision taken under this mandate.
                     r.fail("mandate-accept", did, f"`mandate.expires: {raw}` is not a date — write `YYYY-MM-DD`. "
                                                   f"An expiry nothing can read stops nothing")
+                if status == "superseded" and _revoked_on(c, dec, by_id) is None:
+                    # Retiring a mandate and not dating the retirement leaves the delegation reading as
+                    # good until `expires` — the opposite of what superseding it was for. Same failure as
+                    # the unparseable expiry above: a bound that looks present and compares nothing.
+                    r.fail("mandate-accept", did,
+                           "is a superseded mandate with decisions accepted under it, and nothing dates the "
+                           "supersession — `superseded_by` naming the decision that replaced it, and "
+                           "`supersedes` back on that one (both sides, decision-guide.md), is what says when "
+                           "the delegation was revoked. Until it is there the mandate reads as delegating "
+                           "right up to its `expires`. Recording a supersession is the one edit an applied "
+                           "decision allows")
             continue
         if not ref.startswith("DEC-"):
             continue
@@ -1132,19 +1245,26 @@ def mandate_accept(c: Corpus, r: Result) -> None:
             r.fail("mandate-accept", did, f"`accepted_by: {ref}` is not a `type: mandate` decision — only a mandate "
                                           f"delegates acceptance")
             continue
-        if str(target.get("status") or "") not in ("accepted", "applied"):
-            r.fail("mandate-accept", did, f"`accepted_by: {ref}` is `{target.get('status')}`, not accepted — "
-                                          f"nothing was delegated yet")
+        if str(target.get("status") or "") not in MANDATE_STOOD:
+            r.fail("mandate-accept", did, f"`accepted_by: {ref}` is `{target.get('status')}` — nothing was ever "
+                                          f"delegated. A mandate delegates from `accepted` onward, and a "
+                                          f"`superseded` one still stands for what was taken before it ended")
             continue
         params = target.get("mandate") if isinstance(target.get("mandate"), dict) else {}
         expires = _dec_date(c, {"date": params.get("expires")})
+        revoked = _revoked_on(c, target, by_id)
         when = _dec_date(c, dec)
+        # Whichever end came first is the one that counts.
+        limit, ended, tail = expires, "expired on", "the delegation had lapsed"
+        if revoked and (expires is None or revoked < expires):
+            limit, ended, tail = (revoked, "was superseded on",
+                                  "the delegation was revoked then, whatever its `expires` still says")
         if when is None:
             r.fail("mandate-accept", did, f"is accepted under `{ref}` but no date says when — `date:` in its "
-                                          f"frontmatter is what the expiry is checked against")
-        elif expires and when > expires:
-            r.fail("mandate-accept", did, f"was taken on {when.isoformat()}, after `{ref}` expired on "
-                                          f"{expires.isoformat()} — the delegation had lapsed")
+                                          f"frontmatter is what the mandate's window is checked against")
+        elif limit and when > limit:
+            r.fail("mandate-accept", did, f"was taken on {when.isoformat()}, after `{ref}` {ended} "
+                                          f"{limit.isoformat()} — {tail}")
 
 
 def defect_root_cause(c: Corpus, r: Result) -> None:  # was V20
@@ -1246,18 +1366,62 @@ PRUNE_DIRS = frozenset({
 })
 
 
+_IGNORED: dict[Path, frozenset[str]] = {}
+
+
+def _git_ignored(root: Path) -> frozenset[str]:
+    """What git ignores in this tree, repo-relative posix — a whole ignored directory as `name/`.
+
+    ONE call for the whole run. `git check-ignore` per folder inside `os.walk` is one subprocess per
+    folder, and on a big tree that costs more than the walk it is protecting.
+
+    Git answers rather than a hand-written parser, for the reason `_ignore_rule` sets out: nested
+    `.gitignore` files, negation with `!`, and `core.excludesFile` are exactly where a parser of this
+    one repo is wrong. `--directory` collapses a wholly-ignored folder into a single entry, which is
+    the granularity the walker prunes at — and a folder holding TRACKED files is never collapsed, so
+    corpus that is in git cannot be pruned away by this.
+
+    Outside a repo, or with no git, this is empty and PRUNE_DIRS carries the walk alone. That is why
+    PRUNE_DIRS stays: it is the fallback, and a `node_modules/` nobody remembered to ignore still has
+    to be pruned — a dangling symlink in one took a whole run down once.
+    """
+    got = _IGNORED.get(root)
+    if got is None:
+        out = git(root, "ls-files", "--others", "--ignored", "--exclude-standard", "--directory", "-z")
+        got = frozenset(x for x in (out or "").split("\0") if x)
+        _IGNORED[root] = got
+    return got
+
+
 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.
+    """Every file under `root` with one of `suffixes`, sorted, pruning PRUNE_DIRS and what git ignores.
+
+    Ignored material is not this product's corpus: it is not in the clone, nobody reviews it, and
+    nothing in it can be repaired by the reader of a finding. A vendored upstream checkout under
+    `.temp/` produced 172 `cites-resolve` findings in one repo, every one of them about somebody
+    else's source tree.
 
     Sorted because determinism is this script's contract: two runs over the same tree MUST report the
     same thing in the same order.
     """
+    ignored = _git_ignored(root)
+
+    def rel(path: Path) -> str:
+        try:
+            return path.relative_to(root).as_posix()
+        except ValueError:  # a walk that left the tree — treat it as unignored and let PRUNE_DIRS rule
+            return ""
+
     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)
+        here = Path(dirpath)
+        dirnames[:] = sorted(d for d in dirnames
+                             if d not in PRUNE_DIRS and f"{rel(here / d)}/" not in ignored)
         for name in filenames:
-            if name.endswith(suffixes):
-                out.append(Path(dirpath) / name)
+            # An ignored FILE inside a folder that is otherwise corpus: git lists it on its own,
+            # because `--directory` only collapses folders that are ignored whole.
+            if name.endswith(suffixes) and rel(here / name) not in ignored:
+                out.append(here / name)
     return sorted(out)
 
 
@@ -1619,6 +1783,47 @@ def engines_invocable(c: Corpus, r: Result) -> None:
                        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.
 
@@ -1653,7 +1858,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, engines_invocable, 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
@@ -1856,7 +2061,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 = 27  # 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),

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

@@ -25,7 +25,8 @@ awake to refuse them — and the run would renew its own authority. The lapsed d
 expiry ends the run instead of restarting it.
 
 Typing `/wdi-autopilot` while a mandate is active opens the iteration door, not the preflight. To change a
-setting, the owner supersedes the mandate with a new one — `wdi-decision` owns supersession.
+setting, the owner supersedes the mandate with a new one — `wdi-decision` owns supersession. A superseded
+mandate keeps everything it already accepted: the delegation ends that day, it does not unwind.
 
 ## Door 1 — Preflight
 
@@ -237,7 +238,7 @@ Stated on the preflight page, because a run nobody can stop is not a run anybody
 |---|---|---|
 | Pause | Cancel the loop, or interrupt the session | The current iteration finishes its step and lands its ledger row. Nothing is left half-written |
 | Resume | `/wdi-autopilot` again, or start the loop again | The mandate is still active, so it comes in through the iteration door and continues from `## Resume` |
-| End it for good | Supersede the mandate through `wdi-decision`, or let `expires` pass | **Cancelling the loop does NOT revoke the mandate.** Until it is superseded or lapses, any later firing resumes the run |
+| End it for good | Supersede the mandate through `wdi-decision`, or let `expires` pass | **Cancelling the loop does NOT revoke the mandate.** Until it is superseded or lapses, any later firing resumes the run. The supersession names its replacement on both sides — that date is what revoked the delegation, and `mandate-accept` asks for it once the mandate has accepted anything |
 
 ## The ledger