aw-spec-cli 0.1.10 → 0.1.11

package/assets/.appweaver/scripts/powershell/aw-spec-actions.ps1

@@ -453,7 +453,8 @@ function Invoke-CreateChecklist {
 - [ ] Requirements are testable and unambiguous
 - [ ] Success criteria are measurable
 - [ ] Success criteria are technology-agnostic (no implementation details)
-- [ ] All acceptance scenarios are defined
+- [ ] Every requirement carries a stable id, and no retired id has been re-issued
+- [ ] The newest Change History row names every requirement id this version added or changed
 - [ ] Edge cases are identified
 - [ ] Scope is clearly bounded
 - [ ] Dependencies and assumptions identified
@@ -474,8 +475,8 @@ function Invoke-CreateChecklist {
 
 ## Feature Readiness
 
-- [ ] All functional requirements have clear acceptance criteria
-- [ ] User scenarios cover primary flows
+- [ ] Every functional requirement is stated in EARS form, which is its acceptance criterion
+- [ ] The requirements cover the aggregate's primary flows, so a story can be sliced from them without inventing behaviour
 - [ ] Feature meets measurable outcomes defined in Success Criteria
 - [ ] No implementation details leak into specification
 
@@ -775,6 +776,7 @@ $PyActiveVersion = @'
 import json, os, re, datetime, sys
 fd = os.environ["AW_FD"]; op = os.environ["AW_OP"]; cr = os.environ.get("AW_CR", "")
 force = os.environ.get("AW_FORCE", "")
+boot = os.environ.get("AW_BOOT", "")
 path = os.path.join(fd, "active_version.json")
 feature = os.path.basename(fd.rstrip("/"))
 def now(): return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -799,7 +801,23 @@ out = {"feature": d["feature"], "version": d["version"], "active_change": d.get(
 if op == "read":
     pass
 elif op == "init":
-    if not existed: save(d)
+    # BOOTSTRAP IN PROGRESS, and ONLY when the caller says it is authoring a first draft
+    # (--bootstrap). A first run that dies after writing spec.md but before its ledger row
+    # leaves a document that looks, to the next FRESH invocation, exactly like a spec
+    # written before the ledger existed — `unstamped`, which passes. specify then took the
+    # EXTEND path and applied the same input a second time, on top of a v1.0 that was never
+    # finished, and bumped it to v1.1. Checkpoint resume was always fine; a fresh invocation
+    # was not, and nothing distinguished the two. This marker does. Only ledger-ids clears
+    # it, and only once the v1.0 row actually names ids read out of the finished document —
+    # so a bootstrap whose row never landed is re-run and REPAIRED rather than being frozen
+    # behind a v1.1 that can never go back and fix it.
+    #
+    # The flag is the CALLER's, not this primitive's: adopt inits the same file after
+    # reversing a spec out of existing code, and a marker raised there would tell the next
+    # specify that a finished reversal was a crashed first draft and to overwrite it.
+    if boot:
+        d["bootstrap_pending"] = True
+    save(d)
     out["created"] = (not existed)
 elif op == "open":
     cur = d.get("active_change", "")
@@ -820,6 +838,7 @@ elif op == "close":
     d["active_change"] = ""; save(d)
     out["version"] = d["version"]; out["active_change"] = ""
     out["previous"] = prev; out["closed_change"] = closed
+out["bootstrap_pending"] = bool(d.get("bootstrap_pending"))
 out["has_change"] = bool(out.get("active_change", ""))   # clean branch signal for design
 # What a close from THIS state would produce. One bump() authority, read by BOTH
 # finalize-delta (to write the right number into the Change History rows it appends)
@@ -831,24 +850,748 @@ print(json.dumps(out))
 '@
 
 function Invoke-ActiveVersion {
-    param([string]$FeatureDir, [string]$Op, [string]$CrId = '', [string]$Force = '')
+    param([string]$FeatureDir, [string]$Op, [string]$CrId = '', [string]$Force = '', [string]$Boot = '')
     $py = Get-Py; if (-not $py) { Write-Error "version-$Op`: python3 required"; exit 1 }
     $env:AW_FD = $FeatureDir; $env:AW_OP = $Op; $env:AW_CR = $CrId; $env:AW_FORCE = $Force
+    $env:AW_BOOT = $Boot
     $PyActiveVersion | & $py -   # sets $LASTEXITCODE=3 when op=open is refused (guard)
 }
 
-function Invoke-VersionState {   # op in read|init (feature-dir only)
+function Invoke-VersionState {   # op in read|init (feature-dir, plus --bootstrap on init)
     param([string]$Op, [string[]]$Rest)
-    $fdArg = ''
-    for ($i = 0; $i -lt $Rest.Count; $i++) { if ($Rest[$i] -in '--feature-dir','-FeatureDir') { $fdArg = $Rest[++$i] } }
+    $fdArg = ''; $boot = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        if ($Rest[$i] -in '--feature-dir','-FeatureDir') { $fdArg = $Rest[++$i] }
+        elseif ($Rest[$i] -in '--bootstrap','-Bootstrap') { $boot = '1' }
+    }
     $repo = Get-RepoRoot
     $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
     if (-not $fd) { Write-Error "version-$Op`: no feature set and no --feature-dir"; exit 1 }
-    Invoke-ActiveVersion -FeatureDir $fd -Op $Op
+    Invoke-ActiveVersion -FeatureDir $fd -Op $Op -Boot $boot
 }
 
 
 
+# ═════════════════════════ the spec version ledger ══════════════════════════
+# spec.md's `## Change History` is the sync anchor between the spec and its story
+# backlog: each row names the requirement ids that version touched, and each story
+# records the version it last synced at, so "is this story stale" is one integer
+# comparison rather than a diff. update-stories reads the rows; specify and
+# update-spec append them.
+#
+# The ledger is hand-writable, which is the point — a spec can be edited by hand —
+# and also its one weakness: a body edited with no row leaves every affected story
+# quietly stale and nothing says so. active_version.json therefore carries a sha256
+# of spec.md as of the last kit-authored write, and three states follow from
+# comparing it against the document:
+#
+#   hash matches                    clean — nothing has been hand-edited since
+#   hash differs, version stands    a hand edit that skipped the ledger -> REFUSE
+#   hash differs, version advanced  a hand edit that wrote its own row  -> accept
+#
+# The middle case is the only silent failure the ledger has, which is why it is the
+# one thing checked before any workflow writes.
+$PySpecLedger = @'
+import json, os, re, hashlib, datetime, sys
+fd = os.environ["AW_FD"]; op = os.environ["AW_OP"]
+ids = os.environ.get("AW_IDS", "").strip(); summary = os.environ.get("AW_SUM", "").strip()
+spec = os.path.join(fd, "spec.md"); avp = os.path.join(fd, "active_version.json")
+feature = os.path.basename(fd.rstrip("/\\"))
+
+def now(): return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+def vtuple(v):
+    m = re.match(r'v?(\d+)(?:\.(\d+))?', (v or "").strip())
+    return (int(m.group(1)), int(m.group(2) or 0)) if m else (0, 0)
+def bump(v):
+    maj, mnr = vtuple(v or "v1.0")
+    return "v%d.%d" % (maj, mnr + 1)
+
+out = {"feature": feature, "op": op, "ok": True, "spec_exists": os.path.isfile(spec)}
+
+# A non-zero exit is reported by the orchestrator from STDERR alone, so anything that
+# stops a run has to say why there as well as in the JSON — otherwise the operator sees
+# "script failed (ledger-append):" and nothing else.
+def bail(msg, code):
+    out.update(ok=False, error=msg)
+    print(json.dumps(out)); sys.stderr.write(msg + "\n"); sys.exit(code)
+
+if not out["spec_exists"]:
+    bail("no spec.md at %s" % fd, 1)
+
+text = open(spec, encoding="utf-8", errors="replace").read()
+
+# The Story Coverage block is a projection of the backlog, not contract, and it is written
+# by the story workflows rather than by whoever owns the spec. Cutting it out before
+# hashing is what lets both be true at once: creating a story rewrites this document
+# without that reading as an unledgered edit of the requirements.
+COV = re.compile(r'<!--\s*AW:COVERAGE:BEGIN\s*-->.*?<!--\s*AW:COVERAGE:END\s*-->', re.S)
+def contract_of(t): return COV.sub("", t)
+actual = hashlib.sha256(contract_of(text).encode("utf-8")).hexdigest()
+av = {}
+if os.path.isfile(avp):
+    try: av = json.load(open(avp, encoding="utf-8"))
+    except Exception: av = {}
+recorded_hash = av.get("spec_sha256", "")
+recorded_ver = av.get("version", "v1.0")
+
+# The document's own header is what a hand edit bumps; active_version.json is what the
+# kit last wrote. They agree except across a hand edit, and the disagreement is the signal.
+m = re.search(r'^\*\*Version\*\*:\s*(v[\d.]+)', text, re.M)
+doc_ver = m.group(1) if m else ""
+
+# THE LEDGER TABLE, located once: its heading, its separator rule, and the data rows under
+# it. Every op that touches a version row works from this, and `check` refuses a document
+# that has none — because ledger-append discovers a missing table only AFTER the spec has
+# been rewritten, and a rewritten spec with no row is exactly the state the next run's
+# tripwire refuses. Finding it at entry turns a wedged feature into a message.
+lines = text.split("\n")
+hi = next((i for i, l in enumerate(lines)
+           if re.match(r'^##\s+Change History\s*$', l.strip())), -1)
+sec_end = (next((i for i in range(hi + 1, len(lines)) if lines[i].startswith("## ")),
+                len(lines)) if hi >= 0 else -1)
+sep = (next((i for i in range(hi + 1, sec_end)
+             if re.match(r'^\|[\s\-:|]+\|$', lines[i].strip())), -1) if hi >= 0 else -1)
+rows = [i for i in range(sep + 1, sec_end) if lines[i].lstrip().startswith("|")] if sep >= 0 else []
+has_ledger = hi >= 0 and sep >= 0
+
+def cell(s, limit=160):
+    """One markdown table cell. A newline ENDS a row and a bare pipe STARTS a column, so
+    free text dropped into a cell silently rewrites the row's shape — a summary carrying
+    either one produced a version row whose 'Requirements changed' cell had moved or
+    vanished, which is a change no story can ever be reconciled against."""
+    s = re.sub(r'\s+', ' ', (s or "")).strip().replace("|", "\\|")
+    return (s[:limit - 1] + "\u2026") if len(s) > limit else s
+
+# IS A DELTA ACTUALLY MEASURED AGAINST THIS MASTER. cr-setup scaffolds delta-spec.md AND
+# delta-design.md for EVERY change it opens, so the file existing proves nothing. Since
+# specify lost its delta branch nothing authors a delta-spec at all, and the only changes
+# opened today are design-only ones carrying an untouched copy of the template — for which
+# editing spec.md strands nothing. Authored means the bytes have moved off the template;
+# with no template resolvable, a non-empty file counts.
+cr = av.get("active_change", "")
+dtpl = os.environ.get("AW_DTPL", "")
+dspec = os.path.join(fd, "changes", cr, "delta-spec.md") if cr else ""
+delta_authored = False
+if dspec and os.path.isfile(dspec) and os.path.getsize(dspec) > 0:
+    try:
+        delta_authored = (not (dtpl and os.path.isfile(dtpl))
+                          or open(dspec, "rb").read() != open(dtpl, "rb").read())
+    except Exception:
+        delta_authored = True
+
+out.update(open_change=cr, delta_authored=delta_authored)
+out.update(version=recorded_ver, doc_version=doc_ver, spec_sha256=actual,
+           recorded_sha256=recorded_hash, body_changed=(recorded_hash != actual),
+           has_ledger=has_ledger, ledger_rows=len(rows),
+           first_stamp=(not recorded_hash))
+
+if op == "check":
+    # An AUTHORED delta-spec was computed against THIS master. Writing the master directly
+    # would leave that delta measured from a baseline that no longer exists, and nothing
+    # downstream re-checks it. The two families overlap only until the delta set is deleted,
+    # so this guard is temporary by design — but while both exist it is the one silent way
+    # they collide. Narrowed to an authored delta on purpose: gating on `active_change`
+    # alone refused every extend for the whole life of a DESIGN-only change, which strands
+    # nothing, and told the operator to finish a chain they may be retiring.
+    if cr and delta_authored:
+        out["state"] = "delta_open"
+        out.update(ok=False, active_change=cr,
+                   error="change '%s' is open on this feature and its delta-spec has been "
+                   "authored, so a delta is measured against this master. Editing spec.md "
+                   "directly would leave that delta computed from a baseline that no longer "
+                   "exists. Either finish the change (finalize-delta -> analyze-slice -> "
+                   "close-delta), or abandon it: "
+                   "`.appweaver/scripts/bash/aw-spec-actions.sh cr-archive --cr-id %s` moves "
+                   "changes/%s/ into changes/archive/ and clears the flag. Abandoning also "
+                   "bumps the minor version, so the number moves even though nothing shipped."
+                   % (cr, cr, cr))
+    elif not has_ledger:
+        out["state"] = "no_ledger"
+        out.update(ok=False,
+                   error="spec.md has no '## Change History' table. That table is where a "
+                   "story learns a requirement it cites has moved, so a spec without one "
+                   "cannot be kept in step with its backlog. Add the section with its "
+                   "header row and separator (see the spec template), then re-run.")
+    elif not recorded_hash:
+        out["state"] = "unstamped"          # pre-ledger spec; stamp adopts it
+    elif recorded_hash == actual:
+        out["state"] = "clean"
+    elif vtuple(doc_ver) > vtuple(recorded_ver):
+        out["state"] = "ledgered_edit"      # hand-edited AND a row was written
+    elif vtuple(doc_ver) < vtuple(recorded_ver):
+        out["state"] = "rollback"
+        out.update(ok=False, error="spec.md reads %s but the kit last wrote %s — the "
+                   "document is behind its own ledger" % (doc_ver or "no version", recorded_ver))
+    else:
+        out["state"] = "unledgered_edit"
+        out.update(ok=False, error="spec.md has changed since %s but no Change History row "
+                   "was added. Every story citing an edited requirement is now silently "
+                   "stale. Add a row naming the ids you changed, then re-run."
+                   % recorded_ver)
+elif op == "stamp":
+    av.setdefault("feature", feature); av.setdefault("active_change", "")
+    av["version"] = doc_ver or recorded_ver
+    av["spec_sha256"] = actual; av["updated"] = now()
+    open(avp, "w", encoding="utf-8").write(json.dumps(av, indent=2) + "\n")
+    out.update(version=av["version"], state="stamped")
+elif op == "append":
+    if not ids:
+        # A version that names no ids is a bump nothing can reconcile against: every
+        # story keeps its old stamp and the gap compounds at the next real change.
+        bail("ledger-append: --ids is required — a version row that names no requirement "
+             "ids leaves update-stories nothing to act on", 2)
+    # The next number comes from the highest of all three places a version is written —
+    # what the kit last recorded, what the document's header claims, and the newest row
+    # actually in the table. A hand edit routinely moves one and not the others, and
+    # taking the maximum is what stops the ledger re-issuing a number it has already used.
+    row_vers = re.findall(r'^\|\s*(v\d+(?:\.\d+)?)\s*\|', text, re.M)
+    new_ver = bump(max([recorded_ver, doc_ver] + row_vers, key=vtuple))
+    today = datetime.date.today().isoformat()
+    # Both free-text cells go through cell(): the summary is whatever the operator typed on
+    # the command line, and one newline or one pipe in it destroys the row.
+    row = "| %s | %s | %s | %s | — |" % (
+        new_ver, today, cell(summary) or "Requirements updated", cell(ids))
+
+    # Bounded to the Change History section, not "the last table row in the file". Any
+    # section below it — Story Coverage today — carries its own table, and an unbounded
+    # search would file the version row into whichever one happened to come last.
+    if not has_ledger:
+        bail("spec.md has no '## Change History' table to append to — the ledger is "
+             "where a story learns a requirement moved, so a spec without one cannot be "
+             "kept in step with its backlog. spec.md HAS ALREADY BEEN WRITTEN by this run: "
+             "add the section, then re-run to record what it changed", 2)
+    last = rows[-1] if rows else sep
+    # Duplicate version = two writers reached the same number, which is the collision the
+    # integer buys for free. Refuse rather than append a second row nothing can order.
+    if re.search(r'^\|\s*%s\s*\|' % re.escape(new_ver), text, re.M):
+        bail("the ledger already carries a %s row — another write reached this version "
+             "first; re-read spec.md and retry" % new_ver, 3)
+    lines.insert(last + 1, row)
+
+    stamped = re.sub(r'^(\*\*Version\*\*:\s*)v[\d.]+', r'\g<1>' + new_ver,
+                     "\n".join(lines), count=1, flags=re.M)
+    open(spec, "w", encoding="utf-8").write(stamped)
+
+    av.setdefault("feature", feature); av.setdefault("active_change", "")
+    av["version"] = new_ver
+    av["spec_sha256"] = hashlib.sha256(contract_of(stamped).encode("utf-8")).hexdigest()
+    av["updated"] = now()
+    open(avp, "w", encoding="utf-8").write(json.dumps(av, indent=2) + "\n")
+    out.update(version=new_ver, previous=recorded_ver, row=row, ids=ids,
+               spec_sha256=av["spec_sha256"], state="appended")
+elif op == "rowids":
+    # THE FIRST ROW, COMPUTED. Every other version row is derived from a before/after diff,
+    # for the reason the header of this file gives: a row the model DECLARED can omit an id
+    # it moved, and an omitted id is silent. The v1.0 row was the one exception — written by
+    # the author from a template whose placeholder literally reads "FR-001…FR-00n", which
+    # update-stories then has to be told not to trust. This op closes that gap: the caller
+    # diffs the finished document against nothing and hands the ids in, exactly as the
+    # extend path does, so the first row is observed like all the rest.
+    if not ids:
+        bail("ledger-ids: --ids is required", 2)
+    if not has_ledger:
+        bail("spec.md has no '## Change History' table to write the initial row into", 2)
+    ver = doc_ver if re.match(r'^v\d+(\.\d+)?$', doc_ver or "") else (recorded_ver or "v1.0")
+    today = datetime.date.today().isoformat()
+    if rows:
+        # Rewrite the newest row's cells in place. A cell split has to respect \| , which is
+        # how cell() escapes a pipe the operator typed — splitting on every pipe would treat
+        # an escaped one as a column break and shift every cell after it.
+        parts = re.split(r'(?<!\\)\|', lines[rows[-1]])
+        body = [c.strip() for c in parts[1:-1]] if len(parts) >= 3 else []
+        while len(body) < 5: body.append("")
+        if not re.match(r'^v\d+(\.\d+)?$', body[0]): body[0] = ver
+        if not re.match(r'^\d{4}-\d{2}-\d{2}$', body[1]): body[1] = today
+        if not body[2] or body[2].startswith("["): body[2] = "Initial specification"
+        body[3] = cell(ids)
+        if not body[4]: body[4] = "—"
+        lines[rows[-1]] = "| " + " | ".join(body[:5]) + " |"
+    else:
+        lines.insert(sep + 1, "| %s | %s | Initial specification | %s | — |"
+                     % (ver, today, cell(ids)))
+    stamped = re.sub(r'^(\*\*Version\*\*:\s*)v[\d.]+', r'\g<1>' + ver,
+                     "\n".join(lines), count=1, flags=re.M)
+    open(spec, "w", encoding="utf-8").write(stamped)
+    # The v1.0 row now names ids read out of the finished document, which is the moment the
+    # bootstrap is complete. Clearing the marker here and NOWHERE else is what makes an
+    # incomplete first run re-runnable: spec-stamp still re-baselines the hash on every path,
+    # so gating on the hash would have frozen a placeholder row as clean forever.
+    av.pop("bootstrap_pending", None)
+    av.setdefault("feature", feature); av.setdefault("active_change", "")
+    av["version"] = ver; av["updated"] = now()
+    open(avp, "w", encoding="utf-8").write(json.dumps(av, indent=2) + "\n")
+    out.update(version=ver, ids=ids, row=lines[rows[-1]] if rows else lines[sep + 1],
+               bootstrap_pending=False, state="rowids")
+print(json.dumps(out))
+'@
+
+# What a run CHANGED, observed rather than declared. specify snapshots spec.md before
+# it authors and diffs after the converge loop has finished with it, so the Change
+# History row is computed from the document's own requirement ids. A row the model
+# declares can omit a requirement the converge loop rewrote on its way past — and an
+# omitted id is the silent case the whole ledger exists to prevent.
+$PySpecDiff = @'
+import json, os, re, hashlib, sys
+snap = os.environ.get("AW_SNAP", ""); spec = os.environ["AW_SPEC"]
+# ASKING FOR NO BEFORE-STATE IS NOT THE SAME AS LOSING ONE. An empty --snapshot is the
+# bootstrap path saying "there was nothing before this run", and every id is legitimately
+# added. A path that was given and is not there is the before-state having been LOST, and
+# answering that with "everything is new" is the loudest possible wrong answer: it marks
+# every story in the feature stale for a change that touched none of them.
+if snap and not os.path.isfile(snap):
+    msg = ("spec-diff: the before-state at %s is gone, so this run cannot tell what it "
+           "changed. spec.md HAS been written. Recover by hand: put the ids you changed "
+           "into a new Change History row, then re-run spec-stamp to re-baseline."
+           % snap)
+    print(json.dumps({"ok": False, "error": msg, "had_snapshot": False, "snapshot": snap}))
+    sys.stderr.write(msg + "\n"); sys.exit(2)
+# An id is keyed to the line that DEFINES it, never to a line that merely mentions it.
+# The four shapes are scored, best wins, earliest line breaks a tie:
+#   3  a leading table cell          | DC-001 | … |
+#   3  a bold id opening a bullet    - **FR-001**: THE SYSTEM SHALL …
+#   2  a bold id opening a line      **FR-001** …            (a definition missing its colon)
+#   1  a bold id anywhere            … narrowing **FR-001**. (a cross-reference)
+# Scoring rather than "first bold id on the line, last line wins": a note that OPENS with
+# a cross-reference — "**FR-005** remains in force; **FR-006** narrows it" — re-keyed
+# FR-005 to that note, so a requirement restored character-for-character was reported as
+# MODIFIED. That is the worst possible misreading here, because the additive path exists
+# precisely to leave such a requirement alone, and its own instructions ask the author to
+# name the id in the new requirement's text.
+DEF_CELL = re.compile(r'^\s*\|\s*([A-Z]{2}-\d+)\s*\|')
+DEF_BULL = re.compile(r'^\s*(?:[-*+]\s+)?\*\*([A-Z]{2}-\d+)\*\*\s*[:\u2014\u2013-]')
+DEF_OPEN = re.compile(r'^\s*(?:[-*+]\s+)?\*\*([A-Z]{2}-\d+)\*\*')
+ANY_BOLD = re.compile(r'\*\*([A-Z]{2}-\d+)\*\*')
+# The Story Coverage block lists requirement ids in a table, so it reads exactly like the
+# Data Classification section to DEF_CELL. Left in, every story raised against FR-003 would
+# show up here as FR-003 having CHANGED — a version row, and every story citing it stale,
+# because somebody wrote a story.
+COV = re.compile(r'<!--\s*AW:COVERAGE:BEGIN\s*-->.*?<!--\s*AW:COVERAGE:END\s*-->', re.S)
+# The ledger's own rows name ids in prose cells; they record history, they do not define a
+# requirement, and the table is stripped before the scan for the same reason as coverage.
+HIST = re.compile(r'^##\s+Change History\s*$', re.M)
+def is_def(l):
+    return bool(DEF_CELL.match(l) or DEF_BULL.match(l) or DEF_OPEN.match(l))
+def scan(path):
+    """{id: (score, line_no, hash)} for every id the document mentions."""
+    best = {}
+    if not path or not os.path.isfile(path): return best
+    text = COV.sub("", open(path, encoding="utf-8", errors="replace").read())
+    hm = HIST.search(text)
+    if hm: text = text[:hm.start()]
+    lines = text.split("\n")
+    for n, line in enumerate(lines):
+        hits = []
+        m = DEF_CELL.match(line)
+        if m: hits.append((3, m.group(1)))
+        m = DEF_BULL.match(line)
+        if m: hits.append((3, m.group(1)))
+        else:
+            m = DEF_OPEN.match(line)
+            if m: hits.append((2, m.group(1)))
+        for rid in ANY_BOLD.findall(line):
+            hits.append((1, rid))
+        for score, rid in hits:
+            if rid not in best or score > best[rid][0]:
+                best[rid] = (score, n)
+    # THE WHOLE REQUIREMENT, not the line its id sits on. A requirement that wraps carries
+    # half its meaning on the continuation lines, and hashing only the id's own line made an
+    # edit below the fold invisible: change_count 0, no ledger row appended, and spec-stamp
+    # re-baselining the new body as clean — the ledger's own silent failure, for every story
+    # citing that id. The block runs to the next definition, heading or blank line, and is
+    # whitespace-normalised as ONE string, so a rewrap across lines is still not a change.
+    out = {}
+    for rid, (score, n) in best.items():
+        block = [lines[n]]
+        for m2 in range(n + 1, len(lines)):
+            nxt = lines[m2]
+            if not nxt.strip() or nxt.lstrip().startswith("#") or is_def(nxt): break
+            block.append(nxt)
+        h = hashlib.sha256(" ".join(" ".join(block).split()).encode()).hexdigest()[:16]
+        out[rid] = (score, n, h)
+    return out
+def ids(path):
+    return {k: v[2] for k, v in scan(path).items()}
+# Ids the ledger has already spent. An id is PERMANENT: re-issuing one silently re-points
+# stories, designs and code that have already shipped. Read from the SNAPSHOT's history, so
+# it is what the ledger said before this run, and only meaningful when there is a snapshot.
+def spent(path):
+    if not path or not os.path.isfile(path): return set()
+    text = open(path, encoding="utf-8", errors="replace").read()
+    hm = HIST.search(text)
+    if not hm: return set()
+    return set(re.findall(r'[A-Z]{2}-\d+', text[hm.end():]))
+before, after = ids(snap), ids(spec)
+added    = sorted(k for k in after if k not in before)
+removed  = sorted(k for k in before if k not in after)
+modified = sorted(k for k in after if k in before and before[k] != after[k])
+changed  = sorted(set(added) | set(removed) | set(modified))
+reissued = sorted(set(added) & spent(snap))
+# THE STORY-FACING SUBSET. A story cites FR- and BR- ids and nothing else, so those are the
+# only classes the backlog can act on — the same scoping spec-coverage applies, for the same
+# reason. The scan is deliberately class-blind (CN-/DC-/IC-/UX-/SC- all move the contract and
+# all belong in the ledger row), but handing that whole set to update-stories as "the
+# requirements this run touched" asks it to raise a story for a success criterion.
+STORY_CLASS = ("FR-", "BR-")
+story_ids = [c for c in changed if c.startswith(STORY_CLASS)]
+print(json.dumps({
+    "ok": True, "had_snapshot": bool(snap and os.path.isfile(snap)),
+    "added": added, "removed": removed, "modified": modified,
+    "changed": changed, "changed_csv": ", ".join(changed),
+    "change_count": len(changed),
+    "added_csv": ", ".join(added),
+    # removed ids orphan every story citing them (E1) — carried out so the caller can say so
+    "removed_csv": ", ".join(removed),
+    "modified_csv": ", ".join(modified),
+    # What an existing story would feel. An ADDED requirement disturbs nobody: no story
+    # cites an id that did not exist a moment ago. Modifying or removing one moves ground
+    # somebody may already be standing on, which is the set worth asking about.
+    "disturbing": sorted(set(modified) | set(removed)),
+    "disturbing_csv": ", ".join(sorted(set(modified) | set(removed))),
+    # An id this run introduced that the ledger has already spent. Detected, not blocked:
+    # the document is written by the time we can see it, and refusing here would leave a
+    # spec on disk that the next run's entry check would refuse too.
+    "reissued": reissued, "reissued_csv": ", ".join(reissued),
+    "reissued_any": bool(reissued),
+    # changed, narrowed to the classes a story can cite — what update-stories works from.
+    "story_ids": story_ids, "story_ids_csv": ", ".join(story_ids),
+    "story_id_count": len(story_ids),
+}))
+'@
+
+# Which requirements have live work against them. A read-only scan of the feature's
+# stories/ directory, reading only frontmatter — which is why §6.1 puts everything the
+# gates need there rather than in the body. Only OPEN stories count: a closed story is
+# history and a cancelled one was abandoned, and neither is disturbed by the contract
+# moving. in_flight is the narrower set — an open story that already has a stories/<ID>/
+# directory, so someone is working from a projection of the requirement as it reads today.
+$PyStoryRefs = @'
+import json, os, re
+fd = os.environ["AW_FD"]; want = os.environ.get("AW_IDS", "")
+sdir = os.path.join(fd, "stories")
+queried = [s.strip() for s in re.split(r'[,\s]+', want) if s.strip()]
+
+def parse_fm(text):
+    """Frontmatter as a flat dict. A value may be inline (`exercises: [FR-001, BR-002]`) or
+    a YAML block list under an empty key — both are valid YAML and a hand edit produces
+    either, so a parser that read only the inline form saw a perfectly good story as citing
+    nothing, and a story citing nothing is invisible to every gate that exists to protect
+    it. Block items are folded into the inline shape so every caller stays regex-simple."""
+    m = re.match(r'^---\s*\n(.*?)\n---\s*\n', text, re.S)
+    if not m: return {}
+    fm, key, block = {}, None, set()
+    for line in m.group(1).split("\n"):
+        km = re.match(r'^([A-Za-z_]+):\s*(.*)$', line)
+        if km:
+            key = km.group(1); fm[key] = km.group(2).strip(); continue
+        im = re.match(r'^\s+-\s+(.*)$', line) if key else None
+        if im and (key in block or not fm[key]):
+            block.add(key)
+            fm[key] = (fm[key] + ", " + im.group(1).strip()) if fm[key] else im.group(1).strip()
+    return fm
+
+def frontmatter(path):
+    try: return parse_fm(open(path, encoding="utf-8", errors="replace").read())
+    except Exception: return {}
+
+stories = []
+if os.path.isdir(sdir):
+    for name in sorted(os.listdir(sdir)):
+        if not name.endswith(".md"): continue
+        path = os.path.join(sdir, name)
+        if not os.path.isfile(path): continue
+        fm = frontmatter(path)
+        sid = fm.get("id") or name[:-3]
+        # An unparseable story is reported as open rather than skipped: a story the scan
+        # cannot read is exactly the one whose requirements must not move unannounced.
+        status = (fm.get("status") or "open").strip().lower()
+        cites = [c.strip() for c in re.findall(r'[A-Z]{2}-\d+', fm.get("exercises", ""))]
+        stories.append({"id": sid, "status": status, "exercises": cites,
+                        "in_flight": os.path.isdir(os.path.join(sdir, sid))})
+
+open_stories = [s for s in stories if s["status"] == "open"]
+covered = sorted({c for s in open_stories for c in s["exercises"]})
+
+# ASKING ABOUT NOTHING IS NOT ASKING ABOUT EVERYTHING. `--ids ""` is a caller saying "this
+# run disturbed no requirement" — a pure addition — and the answer is an empty set. Only
+# the absence of the flag means "tell me about the whole backlog". Conflating the two made
+# an enhancement that touched nothing existing prompt about every requirement with a story.
+targets = queried if os.environ.get("AW_IDS_GIVEN") else covered
+
+affected, aff_ids, aff_stories, inflight = [], [], [], []
+for rid in targets:
+    hit = [s for s in open_stories if rid in s["exercises"]]
+    if not hit: continue
+    aff_ids.append(rid)
+    names = [s["id"] for s in hit]
+    flying = [s["id"] for s in hit if s["in_flight"]]
+    aff_stories += names; inflight += flying
+    affected.append({"id": rid, "stories": names, "in_flight": flying})
+
+print(json.dumps({
+    "ok": True, "stories_dir": sdir, "stories_exist": os.path.isdir(sdir),
+    "story_count": len(stories), "open_count": len(open_stories),
+    "queried": queried, "covered": covered, "covered_csv": ", ".join(covered),
+    "affected": affected, "affected_ids": aff_ids, "affected_csv": ", ".join(aff_ids),
+    "story_csv": ", ".join(sorted(set(aff_stories))),
+    "in_flight_csv": ", ".join(sorted(set(inflight))),
+    "any": bool(aff_ids), "any_in_flight": bool(inflight),
+}))
+'@
+
+function Invoke-StoryRefs {
+    param([string[]]$Rest)
+    $fdArg = ''; $ids = ''; $idsGiven = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            '--feature-dir' { $fdArg = $Rest[++$i] }
+            '--ids'         { $ids = $Rest[++$i]; $idsGiven = '1' }
+        }
+    }
+    $repo = Get-RepoRoot
+    $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    if (-not $fd) { Write-Error 'story-refs: no feature set and no --feature-dir'; exit 1 }
+    $py = Get-Py; if (-not $py) { Write-Error 'story-refs: python3 required'; exit 1 }
+    $env:AW_FD = $fd; $env:AW_IDS = $ids; $env:AW_IDS_GIVEN = $idsGiven
+    $PyStoryRefs | & $py -
+}
+
+# Rewrite the spec's Story Coverage block from the stories/ directory: every FR- and BR-
+# in the document, and the stories that deliver it. The relation is stored ONCE, in each
+# story's `exercises:` frontmatter; this is that relation read the other way round, which
+# is why the block is regenerated wholesale rather than patched.
+#
+# Fenced out of the ledger on purpose — spec-check, spec-diff and ledger-append all cut
+# the block out before they look, so writing it is not a spec edit and a story raised
+# against FR-003 does not read as FR-003 having changed.
+$PySpecCoverage = @'
+import json, os, re, sys
+fd = os.environ["AW_FD"]
+spec = os.path.join(fd, "spec.md"); sdir = os.path.join(fd, "stories")
+BEGIN, END = "<!-- AW:COVERAGE:BEGIN -->", "<!-- AW:COVERAGE:END -->"
+COV = re.compile(r'<!--\s*AW:COVERAGE:BEGIN\s*-->.*?<!--\s*AW:COVERAGE:END\s*-->', re.S)
+def parse_fm(text):
+    """Frontmatter as a flat dict. A value may be inline (`exercises: [FR-001, BR-002]`) or
+    a YAML block list under an empty key — both are valid YAML and a hand edit produces
+    either, so a parser that read only the inline form saw a perfectly good story as citing
+    nothing, and a story citing nothing is invisible to every gate that exists to protect
+    it. Block items are folded into the inline shape so every caller stays regex-simple."""
+    m = re.match(r'^---\s*\n(.*?)\n---\s*\n', text, re.S)
+    if not m: return {}
+    fm, key, block = {}, None, set()
+    for line in m.group(1).split("\n"):
+        km = re.match(r'^([A-Za-z_]+):\s*(.*)$', line)
+        if km:
+            key = km.group(1); fm[key] = km.group(2).strip(); continue
+        im = re.match(r'^\s+-\s+(.*)$', line) if key else None
+        if im and (key in block or not fm[key]):
+            block.add(key)
+            fm[key] = (fm[key] + ", " + im.group(1).strip()) if fm[key] else im.group(1).strip()
+    return fm
+out = {"ok": True, "written": False}
+if not os.path.isfile(spec):
+    out.update(ok=False, error="no spec.md at %s" % fd); print(json.dumps(out)); sys.exit(1)
+text = open(spec, encoding="utf-8", errors="replace").read()
+if not COV.search(text):
+    # A spec from before the block existed, or one whose markers were deleted. Not an
+    # error: the coverage view is an aid, and refusing to run would block the change the
+    # caller actually came to make.
+    out.update(reason="no AW:COVERAGE block in spec.md"); print(json.dumps(out)); sys.exit(0)
+
+body = COV.sub("", text)
+rids = []
+for line in body.split("\n"):
+    m = re.search(r'\*\*((?:FR|BR)-\d+)\*\*', line)
+    if m and m.group(1) not in rids: rids.append(m.group(1))
+rids.sort(key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
+
+stories = []
+if os.path.isdir(sdir):
+    for name in sorted(os.listdir(sdir)):
+        if not name.endswith(".md"): continue
+        p = os.path.join(sdir, name)
+        if not os.path.isfile(p): continue
+        d = parse_fm(open(p, encoding="utf-8", errors="replace").read())
+        sid = d.get("id") or name[:-3]
+        stories.append({"id": sid, "status": (d.get("status") or "open").strip().lower(),
+                        "cites": re.findall(r'[A-Z]{2}-\d+', d.get("exercises", "")),
+                        "flying": os.path.isdir(os.path.join(sdir, sid))})
+
+rows, uncovered, delivered = [], [], []
+for rid in rids:
+    live = [s for s in stories if rid in s["cites"] and s["status"] == "open"]
+    done = [s for s in stories if rid in s["cites"] and s["status"] != "open"]
+    if not live and not done: uncovered.append(rid)
+    # DELIVERED is "no OPEN stories", never "a story closed" — a follow-on can still carry
+    # the remainder, and keying on a closed story would read a half-built requirement as done.
+    elif not live: delivered.append(rid)
+    rows.append("| %s | %s | %s |" % (
+        rid,
+        ", ".join(s["id"] + (" (in flight)" if s["flying"] else "") for s in live) or "—",
+        ", ".join(s["id"] for s in done) or "—"))
+
+table = ["| Requirement | Open stories | Closed / cancelled |",
+         "|-------------|--------------|--------------------|"]
+table += rows or ["| _(no FR- or BR- requirements yet)_ | | |"]
+open(spec, "w", encoding="utf-8").write(COV.sub(BEGIN + "\n" + "\n".join(table) + "\n" + END, text, count=1))
+out.update(written=True, requirements=len(rids), stories=len(stories),
+           uncovered=uncovered, uncovered_csv=", ".join(uncovered),
+           delivered=delivered, delivered_csv=", ".join(delivered))
+print(json.dumps(out))
+'@
+
+# Set subtraction with a purpose: of the requirements this run disturbed, which ones was
+# it NOT given permission to change. The approved list comes from a multi-select ask, so
+# the complement is what the re-author has to restore. Its own subcommand because the
+# orchestrator has no expressions — a workflow can bind a value, never compute one.
+$PySpecPreserve = @'
+import json, os, re
+def ids(s):
+    seen, out = set(), []
+    for t in re.findall(r'[A-Z]{2}-\d+', s or ""):
+        if t not in seen: seen.add(t); out.append(t)
+    return out
+mode = os.environ.get("AW_MODE", "complement")
+dist, ok = ids(os.environ.get("AW_DIST", "")), ids(os.environ.get("AW_OK", ""))
+if mode == "verify":
+    # DID THE RESTORE ACTUALLY HOLD. The re-author is a model asked to put requirements back
+    # to their earlier wording; nothing until now checked that it did. The diff taken after
+    # it is the proof: a requirement the author refused to move must no longer appear in the
+    # disturbing set. One that still does was amended WITHOUT approval — and the run would
+    # otherwise report it, in the same breath, as having been left alone.
+    pre = ids(os.environ.get("AW_PRE", ""))
+    violated = [d for d in pre if d in dist]
+    held = [d for d in pre if d not in dist]
+    print(json.dumps({"ok": not violated, "mode": "verify", "preserved": pre,
+                      "held": held, "held_csv": ", ".join(held), "held_count": len(held),
+                      "violated": violated, "violated_csv": ", ".join(violated),
+                      "violated_count": len(violated), "restore_ok": not violated}))
+else:
+    preserve = [d for d in dist if d not in ok]
+    print(json.dumps({"ok": True, "mode": "complement", "disturbing": dist, "approved": ok,
+                      "preserve": preserve,
+                      "preserve_csv": ", ".join(preserve), "preserve_count": len(preserve),
+                      "approved_csv": ", ".join(ok)}))
+'@
+
+function Invoke-SpecCoverage {
+    param([string[]]$Rest)
+    $fdArg = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) { if ($Rest[$i] -eq '--feature-dir') { $fdArg = $Rest[++$i] } }
+    $repo = Get-RepoRoot
+    $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    if (-not $fd) { Write-Error 'spec-coverage: no feature set and no --feature-dir'; exit 1 }
+    $py = Get-Py; if (-not $py) { Write-Error 'spec-coverage: python3 required'; exit 1 }
+    $env:AW_FD = $fd
+    $PySpecCoverage | & $py -
+}
+
+function Invoke-SpecPreserve {
+    param([string[]]$Rest)
+    $dist = ''; $ok = ''; $pre = ''; $mode = 'complement'
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            '--disturbing' { $dist = $Rest[++$i] }
+            '--approved'   { $ok = $Rest[++$i] }
+            '--preserved'  { $pre = $Rest[++$i] }
+            '--verify'     { $mode = 'verify' }
+        }
+    }
+    $py = Get-Py; if (-not $py) { Write-Error 'spec-preserve: python3 required'; exit 1 }
+    $env:AW_DIST = $dist; $env:AW_OK = $ok; $env:AW_PRE = $pre; $env:AW_MODE = $mode
+    $PySpecPreserve | & $py -
+}
+
+# ────────────────────────────── spec-markers ───────────────────────────────
+# Are there any [NEEDS CLARIFICATION] markers to resolve. Deterministic and free, which is
+# the point: asking a model "are there any markers" costs a full round trip on every run to
+# hear "no" on most of them. The model is still what turns a marker into a question with
+# answerable options — this only decides whether to call it at all.
+$PySpecMarkers = @'
+import json, os, re
+spec = os.environ["AW_SPEC"]
+text = open(spec, encoding="utf-8", errors="replace").read() if os.path.isfile(spec) else ""
+found = [" ".join(f.split()) for f in re.findall(r'\[NEEDS CLARIFICATION:\s*(.*?)\]', text, re.S)]
+print(json.dumps({"ok": True, "spec_exists": bool(text), "markers": found,
+                  "marker_count": len(found), "any": bool(found)}))
+'@
+
+function Invoke-SpecMarkers {
+    param([string[]]$Rest)
+    $fdArg = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) { if ($Rest[$i] -eq '--feature-dir') { $fdArg = $Rest[++$i] } }
+    $repo = Get-RepoRoot
+    $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    if (-not $fd) { Write-Error 'spec-markers: no feature set and no --feature-dir'; exit 1 }
+    $py = Get-Py; if (-not $py) { Write-Error 'spec-markers: python3 required'; exit 1 }
+    $env:AW_SPEC = (Join-Path $fd 'spec.md')
+    $PySpecMarkers | & $py -
+}
+
+function Invoke-SpecLedger {   # op in check|stamp|append|rowids
+    param([string]$Op, [string[]]$Rest)
+    $fdArg = ''; $ids = ''; $summary = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            '--feature-dir' { $fdArg = $Rest[++$i] }
+            '--ids'         { $ids = $Rest[++$i] }
+            '--summary'     { $summary = $Rest[++$i] }
+        }
+    }
+    $repo = Get-RepoRoot
+    $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    if (-not $fd) { Write-Error "$Op`: no feature set and no --feature-dir"; exit 1 }
+    $py = Get-Py; if (-not $py) { Write-Error "$Op`: python3 required"; exit 1 }
+    # The delta-spec template, so `check` can tell an AUTHORED delta from the untouched copy
+    # cr-setup scaffolds for every change it opens.
+    $dtpl = @(Resolve-NamedTemplate -Name 'delta-spec-template' -RepoRoot $repo) | Select-Object -Last 1
+    $env:AW_FD = $fd; $env:AW_OP = $Op; $env:AW_IDS = $ids; $env:AW_SUM = $summary
+    $env:AW_DTPL = if ($dtpl) { [string]$dtpl } else { '' }
+    $PySpecLedger | & $py -
+}
+
+function Invoke-SpecSnapshot {
+    param([string[]]$Rest)
+    $fdArg = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) { if ($Rest[$i] -eq '--feature-dir') { $fdArg = $Rest[++$i] } }
+    $repo = Get-RepoRoot
+    $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    if (-not $fd) { Write-Error 'spec-snapshot: no feature set and no --feature-dir'; exit 1 }
+    $spec = Join-Path $fd 'spec.md'
+    $snap = ''
+    if (Test-Path $spec) {
+        # BESIDE THE SPEC, not in the system temp directory. Only the PATH is replay-cached,
+        # and the step is not re-run on resume — so a checkpointed run paused for a human
+        # answer could outlive the temp file. A cleaned temp dir then left spec-diff with no
+        # before-state at all: every id read as ADDED, nothing MODIFIED, so the E38 ask never
+        # fired, the ledger row named every requirement in the document, and every open story
+        # went stale for a change that touched none of them. Beside the spec it shares the
+        # file's lifetime and travels with the repository.
+        #
+        # One snapshot per feature, overwritten each run: a run diffs against it TWICE, once
+        # to see what changed and again after re-authoring a change made additively.
+        $snap = Join-Path $fd '.aw-snapshot.md'
+        Copy-Item $spec $snap -Force
+    }
+    Write-Json ([ordered]@{ snapshot = $snap; taken = [bool]$snap })
+}
+
+function Invoke-SpecDiff {
+    param([string[]]$Rest)
+    $fdArg = ''; $snap = ''
+    for ($i = 0; $i -lt $Rest.Count; $i++) {
+        switch ($Rest[$i]) {
+            '--feature-dir' { $fdArg = $Rest[++$i] }
+            '--snapshot'    { $snap = $Rest[++$i] }
+        }
+    }
+    $repo = Get-RepoRoot
+    $fd = Resolve-FeatureDir -Arg $fdArg -RepoRoot $repo
+    if (-not $fd) { Write-Error 'spec-diff: no feature set and no --feature-dir'; exit 1 }
+    $py = Get-Py; if (-not $py) { Write-Error 'spec-diff: python3 required'; exit 1 }
+    $env:AW_SNAP = $snap; $env:AW_SPEC = (Join-Path $fd 'spec.md')
+    $PySpecDiff | & $py -
+}
+
 # ─────────────────────────── feature-paths ─────────────────────────────────
 function Invoke-FeaturePaths {
     param([string[]]$Rest)
@@ -875,6 +1618,14 @@ function Invoke-FeaturePaths {
     $spec = Join-Path $fd 'spec.md'
     $design = Join-Path $fd 'design.md'
     $uiDesign = Join-Path $fd 'design.ui.md'
+    # needs_bootstrap, not spec_exists, is what picks specify's branch. A crashed first run
+    # leaves spec.md on disk with the marker still up, and branching on the file alone read
+    # that as a spec to EXTEND — re-applying the same input over an unfinished v1.0.
+    $bootstrapPending = $false
+    $avFile = Join-Path $fd 'active_version.json'
+    if (Test-Path $avFile) {
+        try { $bootstrapPending = [bool](Get-Content $avFile -Raw | ConvertFrom-Json).bootstrap_pending } catch { $bootstrapPending = $false }
+    }
     Write-Json ([ordered]@{
         feature          = $feature
         feature_dir      = $fd
@@ -884,6 +1635,8 @@ function Invoke-FeaturePaths {
         spec_exists      = (Test-Path $spec)
         design_exists    = (Test-Path $design)
         ui_design_exists = (Test-Path $uiDesign)
+        bootstrap_pending = $bootstrapPending
+        needs_bootstrap  = ((-not (Test-Path $spec)) -or $bootstrapPending)
     })
 }
 
@@ -925,10 +1678,15 @@ function Invoke-ChecklistRead {
 
 function Invoke-ChecklistApply {
     param([string[]]$Rest)
-    $file = ''; $resultsRaw = '{}'
+    $file = ''; $resultsRaw = '{}'; $allPassRaw = ''
     for ($i = 0; $i -lt $Rest.Count; $i++) {
-        switch ($Rest[$i]) { '--file' { $file = $Rest[++$i] } '--results' { $resultsRaw = $Rest[++$i] } }
+        switch ($Rest[$i]) { '--file' { $file = $Rest[++$i] } '--results' { $resultsRaw = $Rest[++$i] } '--all-pass' { $allPassRaw = $Rest[++$i] } }
     }
+    # The per-item map is the model's, and a model that judged the document to pass routinely
+    # returns only the items it looked hard at — or none at all. Scoring that map alone then
+    # reported "0/25 items passing" for a spec the same call had just passed, which is the one
+    # quality signal this phase emits and the fastest way to teach people to ignore it.
+    $allPass = @('true', '1', 'yes') -contains $allPassRaw.Trim().ToLower()
     if (-not $file) { Write-Error 'checklist-apply: --file required'; exit 1 }
     if (-not (Test-Path $file)) { Write-Json ([ordered]@{ exists = $false; before_checked = 0; after_checked = 0; total = 0; newly_passing = @(); regressions = @() }); return }
     $results = @{}
@@ -938,7 +1696,7 @@ function Invoke-ChecklistApply {
     $before = @($items | Where-Object { $_.checked }).Count
     $newly = @(); $regress = @(); $after = 0
     foreach ($it in $items) {
-        $desired = if ($results.ContainsKey($it.n)) { $results[$it.n] } else { $it.checked }
+        $desired = if ($allPass) { $true } elseif ($results.ContainsKey($it.n)) { $results[$it.n] } else { $it.checked }
         if ($desired -ne $it.checked) { if ($desired) { $newly += $it.n } else { $regress += $it.n } }
         if ($desired) { $after++ }
         $marker = if ($desired) { 'x' } else { ' ' }
@@ -2203,6 +2961,16 @@ switch ($sub) {
     'set-feature'      { Invoke-SetFeature       -Rest $rest }
     'version-read'     { Invoke-VersionState 'read'  $rest }
     'version-init'     { Invoke-VersionState 'init'  $rest }
+    'spec-check'       { Invoke-SpecLedger 'check'  $rest }
+    'spec-stamp'       { Invoke-SpecLedger 'stamp'  $rest }
+    'ledger-append'    { Invoke-SpecLedger 'append' $rest }
+    'ledger-ids'       { Invoke-SpecLedger 'rowids' $rest }
+    'spec-snapshot'    { Invoke-SpecSnapshot    -Rest $rest }
+    'spec-diff'        { Invoke-SpecDiff        -Rest $rest }
+    'story-refs'       { Invoke-StoryRefs       -Rest $rest }
+    'spec-coverage'    { Invoke-SpecCoverage    -Rest $rest }
+    'spec-preserve'    { Invoke-SpecPreserve    -Rest $rest }
+    'spec-markers'     { Invoke-SpecMarkers     -Rest $rest }
     'feature-paths'    { Invoke-FeaturePaths     -Rest $rest }
     'design-scaffold'  { Invoke-DesignScaffold   -Rest $rest }
     'build-compile'    { Invoke-BuildCompile     -Rest $rest }