aw-spec-cli 0.1.10 → 0.1.11

package/assets/.appweaver/scripts/bash/aw-spec-actions.sh

@@ -45,7 +45,29 @@
 #   list-features    [--preselect <name>] [--bundle <dir>]  -> {features[], names[], count, select_options[], sentinel}   (specs/ ∪ OKF aggregates)
 #   set-feature      --feature <name>              -> {feature, feature_dir, spec_file, existed, created, spec_exists}
 #   version-read     [--feature-dir <path>]        -> {feature, version, active_change, exists}
-#   version-init     [--feature-dir <path>]        -> {feature, version, active_change, created}   (create active_version.json v1.0)
+#   version-init     [--feature-dir <path>] [--bootstrap]
+#                                                  -> {feature, version, active_change, created, bootstrap_pending}
+#                    (create active_version.json v1.0; --bootstrap marks a first draft in progress)
+#   spec-check       [--feature-dir <path>]        -> {ok, state, version, doc_version, body_changed, spec_sha256, error}
+#                    (the ledger tripwire: clean | unstamped | ledgered_edit | unledgered_edit | rollback.
+#                     ok:false on an edit that skipped the Change History — the ledger's only silent case)
+#   spec-stamp       [--feature-dir <path>]        -> {ok, state, version, spec_sha256}
+#                    (record spec.md's hash as the new baseline; used after a bootstrap authors it)
+#   ledger-append    [--feature-dir <path>] --ids <ids> [--summary <text>]
+#                                                  -> {ok, version, previous, row, spec_sha256}
+#                    (bump, append the Change History row, stamp the **Version** header and
+#                     re-hash — ONE call, so a row can never exist without its hash)
+#   story-refs       [--feature-dir <path>] [--ids <FR-001, BR-002>]
+#                                                  -> {covered_csv, affected[], affected_csv, story_csv,
+#                                                      in_flight_csv, any, any_in_flight, story_count}
+#                    (which requirements have OPEN stories against them; no --ids = all of them.
+#                     Read-only frontmatter scan — the backlog's view of what is being built)
+#   spec-coverage    [--feature-dir <path>]        -> {written, requirements, stories, uncovered_csv, delivered_csv}
+#                    (regenerate the spec's AW:COVERAGE block — every FR-/BR- and the stories
+#                     delivering it. Fenced out of the hash and the diff, so writing it is not
+#                     a spec edit. Called by specify, user-story and update-stories alike)
+#   spec-preserve    --disturbing <csv> --approved <csv>  -> {preserve_csv, preserve_count, approved_csv}
+#                    (the complement: which disturbed requirements were NOT approved for change)
 #   feature-paths                                  -> {feature, feature_dir, spec_file, design_file, spec_exists, design_exists}
 #   checklist-read   --file <path>                 -> {exists, total, checked, items[]}
 #   checklist-apply  --file <path> --results <json>-> {exists, before_checked, after_checked, total, newly_passing[], regressions[]}
@@ -558,7 +580,7 @@ EOF
 - [ ] 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
 - [ ] Edge cases are identified
 - [ ] Scope is clearly bounded
 - [ ] Dependencies and assumptions identified
@@ -579,8 +601,8 @@ EOF
 
 ## 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
 
@@ -964,11 +986,12 @@ _resolve_feature_dir() {   # $1 = --feature-dir arg (may be empty), $2 = repo_ro
 # one is already open fails (exit 3, ok:false) unless force ("1") is passed — this
 # stops a second concurrent CR on the same aggregate from silently overwriting the
 # first. (Concurrency is ACROSS features; changes to one feature are serialized.)
-_active_version() {   # $1 = abs feature_dir, $2 = op, $3 = cr_id (open only), $4 = force ("1" overrides open-guard)
-    AW_FD="$1" AW_OP="$2" AW_CR="${3:-}" AW_FORCE="${4:-}" python3 - <<'PY'
+_active_version() {   # $1 = abs feature_dir, $2 = op, $3 = cr_id (open only), $4 = force ("1" overrides open-guard), $5 = bootstrap ("1", init only)
+    AW_FD="$1" AW_OP="$2" AW_CR="${3:-}" AW_FORCE="${4:-}" AW_BOOT="${5:-}" python3 - <<'PY'
 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")
@@ -993,7 +1016,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", "")
@@ -1014,6 +1053,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)
@@ -1029,17 +1069,762 @@ cmd_version_read()  { _version_cmd "read"  "$@"; }
 cmd_version_init()  { _version_cmd "init"  "$@"; }
 _version_cmd() {   # $1 = op (read|init), then --feature-dir arg
     local op="$1"; shift
-    local fd_arg=""
+    local fd_arg="" boot=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --feature-dir) fd_arg="$2"; shift 2 ;;
-            --help|-h) echo "version-$op [--feature-dir <path>]"; return 0 ;;
+            --bootstrap) boot=1; shift ;;   # init only: this caller is authoring a FIRST draft
+            --help|-h) echo "version-$op [--feature-dir <path>] [--bootstrap]"; return 0 ;;
             *) echo "version-$op: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
     local repo_root; repo_root=$(get_repo_root)
     local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "version-$op: no feature set and no --feature-dir" >&2; return 1; }
-    _active_version "$fd" "$op"
+    _active_version "$fd" "$op" "" "" "$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.
+_spec_ledger() {   # $1 = abs feature_dir, $2 = op, $3 = ids, $4 = summary, $5 = delta-spec template
+    AW_FD="$1" AW_OP="$2" AW_IDS="${3:-}" AW_SUM="${4:-}" AW_DTPL="${5:-}" python3 - <<'PY'
+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))
+PY
+}
+
+# ──────────────────────────────── story-refs ───────────────────────────────
+# 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.
+#
+# specify asks this twice, for two different purposes. Before authoring, with no --ids,
+# to tell the author which requirements someone is currently building. After the diff,
+# with the ids the run actually MODIFIED, to decide whether to ask before changing a
+# contract under someone's feet.
+#
+# Only OPEN stories count. A closed story is history and a cancelled one was abandoned;
+# neither is disturbed by the contract moving (E4).
+#
+# in_flight is the narrower set: an open story that already has a stories/<ID>/ directory,
+# so someone has run story-spec and is working from a projection of the requirement as it
+# reads today. That is the same directory-existence predicate change-story-id uses for its
+# legality boundary — one test, serving three workflows.
+cmd_story_refs() {
+    local fd_arg="" ids="" ids_given=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --ids) ids="$2"; ids_given=1; shift 2 ;;
+            --help|-h) echo "story-refs [--feature-dir <path>] [--ids <FR-001, BR-002>]"; return 0 ;;
+            *) echo "story-refs: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "story-refs: no feature set and no --feature-dir" >&2; return 1; }
+    AW_FD="$fd" AW_IDS="$ids" AW_IDS_GIVEN="$ids_given" python3 - <<'PY'
+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),
+}))
+PY
+}
+
+# ────────────────────────────── spec-coverage ──────────────────────────────
+# 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. Hand edits to it are
+# discarded by design — the story is where delivery is declared.
+#
+# Every workflow that changes either side calls this: specify when the requirements move,
+# user-story and update-stories when the backlog does. It is deterministic and model-free,
+# so calling it more often than necessary costs nothing and drift is not possible.
+#
+# Scoped to FR-/BR- — the ids a story cites. CN-/DC-/IC-/UX- are constraints the design
+# traces, not slices of work, and listing them would show permanent gaps as coverage holes.
+cmd_spec_coverage() {
+    local fd_arg=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --help|-h) echo "spec-coverage [--feature-dir <path>]"; return 0 ;;
+            *) echo "spec-coverage: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "spec-coverage: no feature set and no --feature-dir" >&2; return 1; }
+    AW_FD="$fd" python3 - <<'PY'
+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))
+PY
+}
+
+# ────────────────────────────── spec-preserve ──────────────────────────────
+# 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. Kept as its own subcommand because
+# the orchestrator has no expressions — a workflow can bind a value, never compute one.
+cmd_spec_preserve() {
+    local disturbing="" approved="" preserved="" mode="complement"
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --disturbing) disturbing="$2"; shift 2 ;;
+            --approved) approved="$2"; shift 2 ;;
+            --preserved) preserved="$2"; shift 2 ;;
+            --verify) mode="verify"; shift ;;
+            --help|-h) echo "spec-preserve --disturbing <csv> --approved <csv>"; echo "spec-preserve --verify --preserved <csv> --disturbing <csv>"; return 0 ;;
+            *) echo "spec-preserve: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    AW_DIST="$disturbing" AW_OK="$approved" AW_PRE="$preserved" AW_MODE="$mode" python3 - <<'PY'
+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)}))
+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.
+cmd_spec_markers() {
+    local fd_arg=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --help|-h) echo "spec-markers [--feature-dir <path>]"; return 0 ;;
+            *) echo "spec-markers: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "spec-markers: no feature set and no --feature-dir" >&2; return 1; }
+    AW_SPEC="$fd/spec.md" python3 - <<'PY'
+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)}))
+PY
+}
+
+# ───────────────────────── spec-snapshot / spec-diff ───────────────────────
+# 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.
+#
+# Deriving the row this way is what makes it trustworthy. 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, since update-stories would never
+# learn that requirement moved. A row computed from the diff cannot omit one.
+#
+# Ids are read in both shapes the template uses: the bold form of the list sections
+# (`- **FR-001**: …`) and the leading-cell form of the Data Classification table
+# (`| DC-001 | … |`). The line is normalised on whitespace before hashing, so a rewrap
+# is not a change.
+cmd_spec_snapshot() {
+    local fd_arg=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --help|-h) echo "spec-snapshot [--feature-dir <path>]"; return 0 ;;
+            *) echo "spec-snapshot: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "spec-snapshot: no feature set and no --feature-dir" >&2; return 1; }
+    local spec="$fd/spec.md"
+    local snap=""
+    if [ -f "$spec" ]; then
+        # 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="$fd/.aw-snapshot.md"
+        cp "$spec" "$snap"
+    fi
+    printf '{"snapshot":"%s","taken":%s}\n' "$(json_escape "$snap")" "$([ -n "$snap" ] && echo true || echo false)"
+}
+
+cmd_spec_diff() {
+    local fd_arg="" snap=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --snapshot) snap="$2"; shift 2 ;;
+            --help|-h) echo "spec-diff --snapshot <path> [--feature-dir <path>]"; return 0 ;;
+            *) echo "spec-diff: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "spec-diff: no feature set and no --feature-dir" >&2; return 1; }
+    AW_SNAP="$snap" AW_SPEC="$fd/spec.md" python3 - <<'PY'
+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),
+}))
+PY
+    return 0
+}
+
+cmd_spec_check()    { _spec_ledger_cmd "check"  "$@"; }
+cmd_spec_stamp()    { _spec_ledger_cmd "stamp"  "$@"; }
+cmd_ledger_append() { _spec_ledger_cmd "append" "$@"; }
+cmd_ledger_ids()    { _spec_ledger_cmd "rowids" "$@"; }
+_spec_ledger_cmd() {   # $1 = op, then --feature-dir / --ids / --summary
+    local op="$1"; shift
+    local fd_arg="" ids="" summary=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --ids) ids="$2"; shift 2 ;;
+            --summary) summary="$2"; shift 2 ;;
+            --help|-h) echo "$op [--feature-dir <path>] [--ids <FR-001, BR-002>] [--summary <text>]"; return 0 ;;
+            *) echo "$op: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "$op: no feature set and no --feature-dir" >&2; return 1; }
+    # The delta-spec template, so `check` can tell an AUTHORED delta from the untouched copy
+    # cr-setup scaffolds for every change it opens.
+    local dtpl; dtpl=$(resolve_template "delta-spec-template" "$repo_root") || true
+    _spec_ledger "$fd" "$op" "$ids" "$summary" "$dtpl"
 }
 
 
@@ -1072,12 +1857,21 @@ cmd_feature_paths() {
     # design.ui.md (adopt today) enrolls the feature in the UI half of the delta loop
     # by the act of writing the file.
     local spec="$fd/spec.md" design="$fd/design.md" ui_design="$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.
+    local av_file="$fd/active_version.json" bootstrap_pending=false
+    grep -q '"bootstrap_pending"[[:space:]]*:[[:space:]]*true' "$av_file" 2>/dev/null && bootstrap_pending=true
     local spec_exists=false;      [ -f "$spec" ]      && spec_exists=true
     local design_exists=false;    [ -f "$design" ]    && design_exists=true
     local ui_design_exists=false; [ -f "$ui_design" ] && ui_design_exists=true
-    printf '{"feature":"%s","feature_dir":"%s","spec_file":"%s","design_file":"%s","ui_design_file":"%s","spec_exists":%s,"design_exists":%s,"ui_design_exists":%s}\n' \
+    local needs_bootstrap=false
+    [ "$spec_exists" = false ] && needs_bootstrap=true
+    [ "$bootstrap_pending" = true ] && needs_bootstrap=true
+    printf '{"feature":"%s","feature_dir":"%s","spec_file":"%s","design_file":"%s","ui_design_file":"%s","spec_exists":%s,"design_exists":%s,"ui_design_exists":%s,"bootstrap_pending":%s,"needs_bootstrap":%s}\n' \
         "$(json_escape "$feature")" "$(json_escape "$fd")" "$(json_escape "$spec")" "$(json_escape "$design")" \
-        "$(json_escape "$ui_design")" "$spec_exists" "$design_exists" "$ui_design_exists"
+        "$(json_escape "$ui_design")" "$spec_exists" "$design_exists" "$ui_design_exists" \
+        "$bootstrap_pending" "$needs_bootstrap"
 }
 
 # ────────────────────────── checklist-read / -apply ────────────────────────
@@ -1113,17 +1907,18 @@ PY
 }
 
 cmd_checklist_apply() {
-    local file="" results="{}"
+    local file="" results="{}" all_pass=""
     while [ $# -gt 0 ]; do
         case "$1" in
             --file) file="$2"; shift 2 ;;
             --results) results="$2"; shift 2 ;;
-            --help|-h) echo "checklist-apply --file <path> --results <json>"; return 0 ;;
+            --all-pass) all_pass="$2"; shift 2 ;;
+            --help|-h) echo "checklist-apply --file <path> --results <json> [--all-pass true|false]"; return 0 ;;
             *) echo "checklist-apply: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
     [ -n "$file" ] || { echo "checklist-apply: --file required" >&2; return 1; }
-    AW_FILE="$file" AW_RESULTS="$results" python3 - <<'PY'
+    AW_FILE="$file" AW_RESULTS="$results" AW_ALLPASS="$all_pass" python3 - <<'PY'
 import json, os, re
 f = os.environ["AW_FILE"]
 if not os.path.exists(f):
@@ -1133,6 +1928,11 @@ try:
     results = {int(k): bool(v) for k, v in json.loads(os.environ["AW_RESULTS"] or "{}").items()}
 except Exception:
     results = {}
+# 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.
+all_pass = os.environ.get("AW_ALLPASS", "").strip().lower() in ("true", "1", "yes")
 lines = open(f, encoding="utf-8").read().splitlines(keepends=True)
 n, fence = 0, False
 before = after = 0
@@ -1147,7 +1947,7 @@ for line in lines:
         n += 1
         cur = m.group(2) in "xX"
         before += 1 if cur else 0
-        desired = results.get(n, cur)
+        desired = True if all_pass else results.get(n, cur)
         if desired != cur:
             if desired: newly.append(n)
             else: regress.append(n)
@@ -2592,6 +3392,16 @@ case "$sub" in
     set-feature)      cmd_set_feature "$@" ;;
     version-read)     cmd_version_read "$@" ;;
     version-init)     cmd_version_init "$@" ;;
+    spec-check)       cmd_spec_check "$@" ;;
+    spec-stamp)       cmd_spec_stamp "$@" ;;
+    ledger-append)    cmd_ledger_append "$@" ;;
+    ledger-ids)       cmd_ledger_ids "$@" ;;
+    spec-snapshot)    cmd_spec_snapshot "$@" ;;
+    spec-diff)        cmd_spec_diff "$@" ;;
+    story-refs)       cmd_story_refs "$@" ;;
+    spec-coverage)    cmd_spec_coverage "$@" ;;
+    spec-preserve)    cmd_spec_preserve "$@" ;;
+    spec-markers)     cmd_spec_markers "$@" ;;
     feature-paths)    cmd_feature_paths "$@" ;;
     design-scaffold)  cmd_design_scaffold "$@" ;;
     build-compile)    cmd_build_compile "$@" ;;