aw-spec-cli 0.1.13 → 0.1.15

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

@@ -49,15 +49,45 @@
 #                                                  -> {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)
+#                    (the ledger tripwire: clean | unstamped | ledgered_edit | header_behind |
+#                     unrowed_edit | unledgered_edit | rollback | no_ledger | delta_open.
+#                     A recorded edit is one with a version ROW above the recorded version — the
+#                     **Version** header is a claim, not evidence. ok:false on an edit that skipped
+#                     the Change History row, which is the ledger's only silent case)
+#   spec-stamp       [--feature-dir <path>]        -> {ok, state, version, spec_sha256, header_rewritten}
+#                    (record spec.md's hash as the new baseline; used after a bootstrap authors it.
+#                     The version recorded is the highest of the recorded one, the document header
+#                     and the newest ledger row, and a header behind that is rewritten up to 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>]
+#   slice-mode       [--input <text>]              -> {strategy, guidance, single, note}
+#                    (the strategy word off the front of the launch line, and the guidance
+#                     left behind it — `single-run` asks for one story over the work set)
+#   backlog-plan     --groups <json> --work <csv> [--strategy single|auto] [--ceiling <n>]
+#                    [--plan --approved <ids> --version <v>]
+#   story-stamp      --story <id> [--ids <csv>] [--version <v>] [--follows <id>]
+#                    [--depends-on <csv>] [--wave <n>]
+#   ledger-read      [--feature-dir <path>]      -> {rows, work_csv, work_source, gap, ...}
+#   story-plan-check [--story <id>] [--input <text>] [--feature-dir <p>]
+#                                                  -> {resolved, needs_pick, open_ids, story, story_open, status_msg,
+#                                                      exercises_csv, constraints_csv, stale_csv, stale_note,
+#                                                      be_doc_path/fe_doc_path, be_doc_exists/fe_doc_exists,
+#                                                      be_next_pass/fe_next_pass, be_last_pass/fe_last_pass,
+#                                                      be_pass_tmp/fe_pass_tmp,
+#                                                      be_doc_spec_version/fe_doc_spec_version, be_doc_stale/fe_doc_stale,
+#                                                      legacy_doc, legacy_doc_exists, if_tmp, adr_path, if_path}
+#                    (resolve WHICH story a story-plan run works on + everything its gates read)
+#   story-plan-doc   --story <id> --pass-file <p> [--lane backend|frontend] [--spec-version <v>]
+#                                                  -> {ok, doc, lane, pass, created}
+#                    (the only writer of stories/<ID>/story-<lane>-plan.md: scaffold on first use, append
+#                     the pass under a script-written '## Design pass N' header, stamp frontmatter)
+#   log-append       --log adr|interfaces --entries-file <p> [--status <s>]
+#                                                  -> {ok, appended, ids_csv, unknown_ids_csv, bad_supersedes_csv}
+#                    (append-only feature logs; the script assigns ADR-nnn/IF-nnn ids, dates and
+#                     status — entries arrive as '## IF-NEW — <title>' blocks, 'none' is a no-op)
 #                                                  -> {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.
@@ -65,10 +95,27 @@
 #   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)
+#                     a spec edit. Called by specify, user-story and sync-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}
+#   feature-paths                                  -> {feature, feature_dir, spec_file, design_file, spec_exists, design_exists,
+#                                                      backend_plan_file, frontend_plan_file, backend_plan_exists, frontend_plan_exists}
+#   plan-check       --doc <path> [--feature-dir <p>] -> {state, derived_version, current_version, changed_csv, changed_summary, body_changed}
+#                    (the plan doc's derivation record vs the spec ledger: fresh | untracked |
+#                     clean | behind | edited | edited_behind; behind's changed_csv is the update's work list)
+#   plan-stamp       --doc <path> [--feature-dir <p>] [--ids <csv>] [--note <text>] [--no-row]
+#                                                  -> {ok, version, row, warnings[]}
+#                    (the ONLY writer of a plan doc's version identity: **Version** header := the
+#                     spec version derived from, a Change History row unless --no-row, and the body
+#                     hash into the doc's own .aw-plan-track.<doc>.json — refuses, writing no baseline, when the doc has
+#                     no Change History section left)
+#   gate-result      --gate <name> --ok <true|false> [--feature-dir <p>] [--spec-version <v>]
+#                    [--story <id>] [--report <path>] [--out <path>] [--gap-count <n>]
+#                    [--gap-refs <csv>] [--note <text>] [--field k=v]...
+#                                                  -> {ok, result_file, status, gap_count}
+#                    (the machine-readable verdict every analyze gate writes beside its markdown
+#                     report, so CI branches on a value instead of prose. `ok` means the file was
+#                     WRITTEN; the verdict is `status`. Fixed core keys + gate-specific --field)
 #   checklist-read   --file <path>                 -> {exists, total, checked, items[]}
 #   checklist-apply  --file <path> --results <json>-> {exists, before_checked, after_checked, total, newly_passing[], regressions[]}
 #   detect-project                                 -> {scaffolded, markers[]}
@@ -184,7 +231,8 @@ cmd_resolve_domain() {
 # stack_mismatch when it is not a stack this repo declares, because a map pinned to the
 # wrong corpus is how a Java project ends up being handed C# rules.
 cmd_resolve_tech() {
-    local command_name="aw-spec-design"
+    local command_name="aw-spec-plan"   # inert: every caller passes --command. Kept current
+                                        # so a hand-run defaults to a LIVE command, not a dead one.
     while [ $# -gt 0 ]; do
         case "$1" in
             --command) command_name="$2"; shift 2 ;;
@@ -1087,7 +1135,7 @@ _version_cmd() {   # $1 = op (read|init), then --feature-dir arg
 # 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
+# comparison rather than a diff. sync-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 —
@@ -1165,6 +1213,14 @@ 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
+# THE VERSIONS THE TABLE ACTUALLY CARRIES, read from the rows located above rather than by
+# an unbounded scan, so a version-looking cell in another section's table cannot be counted
+# as history. This is the EVIDENCE that a change was recorded; the document's **Version**
+# header is only the CLAIM, and hand editing parts the two in both directions.
+row_versions = [m.group(1) for m in
+                (re.match(r'^\|\s*(v\d+(?:\.\d+)?)\s*\|', lines[i].lstrip()) for i in rows)
+                if m]
+newest_row = max(row_versions, key=vtuple) if row_versions else ""
 
 def cell(s, limit=160):
     """One markdown table cell. A newline ENDS a row and a bare pipe STARTS a column, so
@@ -1194,7 +1250,7 @@ if dspec and os.path.isfile(dspec) and os.path.getsize(dspec) > 0:
 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),
+           has_ledger=has_ledger, ledger_rows=len(rows), newest_row=newest_row,
            first_stamp=(not recorded_hash))
 
 if op == "check":
@@ -1228,8 +1284,28 @@ if op == "check":
         out["state"] = "unstamped"          # pre-ledger spec; stamp adopts it
     elif recorded_hash == actual:
         out["state"] = "clean"
+    # THE ROW IS THE EVIDENCE; THE HEADER IS ONLY THE CLAIM. The body has moved since the
+    # kit last stamped, and what makes that edit legible downstream is a version ROW naming
+    # the ids it touched: sync-stories reads rows, story-plan's staleness check reads rows,
+    # and neither ever opens the **Version** header. Taking the header as proof accepted the
+    # commonest hand-edit mistake there is — bump the number, forget the row — and that one
+    # passed every tripwire in the kit, raised no work anywhere, and was then buried for good
+    # by the next run's stamp adopting its hash. So the test is a row ABOVE the version the
+    # kit last recorded, and the header is only asked whether it kept up.
+    elif newest_row and vtuple(newest_row) > vtuple(recorded_ver):
+        out["state"] = ("ledgered_edit" if vtuple(doc_ver) >= vtuple(newest_row)
+                        else "header_behind")   # recorded; stamp reconciles the header
     elif vtuple(doc_ver) > vtuple(recorded_ver):
-        out["state"] = "ledgered_edit"      # hand-edited AND a row was written
+        # The header claims a version the table never recorded. Refused for the same reason
+        # an unrowed edit is: without the row nothing can say WHICH requirements moved, so
+        # every story citing one is stale with nothing able to detect it.
+        out["state"] = "unrowed_edit"
+        out.update(ok=False, error="spec.md's header reads %s but the Change History carries "
+                   "no row above %s — the version was bumped and what it changed was never "
+                   "recorded. The row is what a story reads to learn that a requirement it "
+                   "cites has moved; the header is read by nobody. Add a row naming the ids "
+                   "you changed (keep the header at %s), then re-run."
+                   % (doc_ver or "no version", recorded_ver, doc_ver))
     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 "
@@ -1241,8 +1317,23 @@ if op == "check":
                    "stale. Add a row naming the ids you changed, then re-run."
                    % recorded_ver)
 elif op == "stamp":
+    # THE VERSION IS THE HIGHEST OF THE THREE PLACES ONE IS WRITTEN, and the document's
+    # header is reconciled up to it. Taking the header alone let a hand edit that DID write
+    # its row — without bumping the header — leave the kit recording a version below the
+    # newest row; the next hand edit then read as a `rollback`, the document behind its own
+    # ledger, when nothing had rolled back. Rewriting the header is the authority
+    # ledger-append already exercises: the kit owns the number, the row is what it is
+    # computed from, and re-hashing after the rewrite is what keeps the baseline honest.
+    stamp_ver = max([recorded_ver or "v1.0", doc_ver or "v1.0"] +
+                    ([newest_row] if newest_row else []), key=vtuple)
+    if doc_ver and vtuple(doc_ver) < vtuple(stamp_ver):
+        text = re.sub(r'^(\*\*Version\*\*:\s*)v[\d.]+', r'\g<1>' + stamp_ver,
+                      text, count=1, flags=re.M)
+        open(spec, "w", encoding="utf-8").write(text)
+        actual = hashlib.sha256(contract_of(text).encode("utf-8")).hexdigest()
+        out.update(header_rewritten=True, doc_version=stamp_ver, spec_sha256=actual)
     av.setdefault("feature", feature); av.setdefault("active_change", "")
-    av["version"] = doc_ver or recorded_ver
+    av["version"] = stamp_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")
@@ -1251,7 +1342,7 @@ elif op == "append":
         # 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)
+             "ids leaves sync-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
@@ -1296,7 +1387,7 @@ elif op == "rowids":
     # 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
+    # sync-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:
@@ -1352,7 +1443,7 @@ PY
 # 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
+# so someone has run story-plan and is working from a design 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() {
@@ -1409,6 +1500,11 @@ if os.path.isdir(sdir):
         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,
+                        "cites_csv": ", ".join(cites),
+                        "title": (fm.get("title") or "").strip().strip("[]"),
+                        "spec_version": (fm.get("spec_version") or "").strip(),
+                        "type": (fm.get("type") or "functional").strip().lower(),
+                        "follows": (fm.get("follows") or "").strip(),
                         "in_flight": os.path.isdir(os.path.join(sdir, sid))})
 
 open_stories = [s for s in stories if s["status"] == "open"]
@@ -1430,11 +1526,30 @@ for rid in targets:
     aff_stories += names; inflight += flying
     affected.append({"id": rid, "stories": names, "in_flight": flying})
 
+# THE COMPLEMENT, NAMED. `affected` is "these ids have live work"; its complement is
+# "these ids have nobody on them", and that is the set sync-stories raises new stories for.
+# Derived here rather than in the caller because the orchestrator binds values and never
+# computes them, and a subtraction done in a prompt is a subtraction nothing can check.
+unlinked = [rid for rid in targets if rid not in aff_ids]
+
+# One line per open story, for a prompt that has to ask about them. A story id on its own
+# is not something an author can answer about: what it cites and whether someone is already
+# implementing it are the whole basis of the decision.
+digest = "\n".join(
+    "  %-16s %-9s %-11s cites %s%s" % (
+        s["id"], s["status"], "IN FLIGHT" if s["in_flight"] else "not started",
+        s["cites_csv"] or "nothing",
+        ("  @ " + s["spec_version"]) if s["spec_version"] else "")
+    for s in open_stories) or "  (no open stories)"
+
 print(json.dumps({
     "ok": True, "stories_dir": sdir, "stories_exist": os.path.isdir(sdir),
     "story_count": len(stories), "open_count": len(open_stories),
+    "stories": stories, "digest": digest,
     "queried": queried, "covered": covered, "covered_csv": ", ".join(covered),
     "affected": affected, "affected_ids": aff_ids, "affected_csv": ", ".join(aff_ids),
+    "unlinked": unlinked, "unlinked_csv": ", ".join(unlinked),
+    "unlinked_count": len(unlinked), "any_unlinked": bool(unlinked),
     "story_csv": ", ".join(sorted(set(aff_stories))),
     "in_flight_csv": ", ".join(sorted(set(inflight))),
     "any": bool(aff_ids), "any_in_flight": bool(inflight),
@@ -1450,7 +1565,7 @@ PY
 # 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,
+# user-story and sync-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
@@ -1543,6 +1658,1030 @@ print(json.dumps(out))
 PY
 }
 
+# ─────────────────────────────── ledger-read ───────────────────────────────
+# THE WORK SET: which requirements this sync has to account for. The ledger records what
+# each version touched and every story records the version it last synced at, so the
+# question "what has moved since the backlog was last in step" is answerable by reading
+# rows — no diffing, no hashing, no model.
+#
+# The set is the union of the ids named by every row ABOVE THE LOWEST spec_version across
+# the OPEN stories, not the ids of the newest row alone. Those are the same set whenever
+# the backlog is one version behind, which is the ordinary case; they diverge only when a
+# sync was skipped, and that is exactly the case worth getting right. Two specify runs
+# without a sync between them leave the middle version named by no row anyone reads, and
+# its requirements would get no story with nothing to say so — a silent gap, in the one
+# mechanism built to make gaps loud.
+#
+# THE v1.0 CASE (E42). At v1.0 nothing has moved yet: there is no "since" to read from. So
+# when no open story carries a readable spec version — an empty backlog, or stories written
+# before the field existed — the work set is every FR-/BR- the DOCUMENT declares, and the
+# per-id four-case table does the rest. A second run over the same spec then creates
+# nothing, because by then every id has a story.
+#
+# Scoped to FR-/BR- throughout, the same scoping spec-coverage applies: those are the only
+# classes a story's `exercises:` can name. CN-/DC-/IC-/UX- move the contract and belong in
+# the ledger row, but they are constraints a story CARRIES, not slices of work it delivers.
+cmd_ledger_read() {
+    local fd_arg=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --help|-h) echo "ledger-read [--feature-dir <path>]"; return 0 ;;
+            *) echo "ledger-read: 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 "ledger-read: 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")
+
+def bail(msg, code=1):
+    print(json.dumps({"ok": False, "error": msg}))
+    sys.stderr.write(msg + "\n"); sys.exit(code)
+
+if not os.path.isfile(spec): bail("no spec.md at %s" % fd)
+text = open(spec, encoding="utf-8", errors="replace").read()
+
+COV = re.compile(r'<!--\s*AW:COVERAGE:BEGIN\s*-->.*?<!--\s*AW:COVERAGE:END\s*-->', re.S)
+
+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 rids(s):
+    """FR-/BR- ids in order of appearance, deduped, then sorted by class and number so
+    two callers reading the same row always produce the same csv."""
+    seen, out = set(), []
+    for t in re.findall(r'\b(?:FR|BR)-\d+', s or ""):
+        if t not in seen: seen.add(t); out.append(t)
+    return sorted(out, key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
+
+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
+
+# THE LEDGER TABLE, located the same way _spec_ledger locates it — heading, separator rule,
+# then the rows under it, bounded by the next `## `. Any other section carries its own
+# table (Story Coverage does), and an unbounded search would read one of those as history.
+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)
+row_lines = [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 cells(line):
+    parts = re.split(r'(?<!\\)\|', line)
+    return [c.strip().replace("\\|", "|") for c in parts[1:-1]] if len(parts) >= 3 else []
+
+rows = []
+for i in row_lines:
+    c = cells(lines[i]); c += [""] * (5 - len(c))
+    # A row whose first cell is not a version is the template's own placeholder line, or a
+    # note somebody left in the table. It records no version, so it orders against nothing.
+    if not re.match(r'^v\d', c[0]): continue
+    rows.append({"version": c[0], "date": c[1], "change": c[2], "ids_cell": c[3],
+                 "stories": c[4], "requirements": rids(c[3])})
+rows.sort(key=lambda r: vtuple(r["version"]))
+
+# WHAT THE DOCUMENT STILL DECLARES. Read from the requirement's DEFINING line — the bolded
+# id the template gives every requirement — and with the Change History cut away, so the
+# ids named in a row's own cell are never mistaken for requirements the spec carries.
+body = COV.sub("", text).split("\n## Change History")[0]
+declared = []
+for line in body.split("\n"):
+    m = re.search(r'\*\*((?:FR|BR)-\d+)\*\*', line)
+    if m and m.group(1) not in declared: declared.append(m.group(1))
+declared.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
+        fm = parse_fm(open(p, encoding="utf-8", errors="replace").read())
+        sid = fm.get("id") or name[:-3]
+        stories.append({"id": sid, "status": (fm.get("status") or "open").strip().lower(),
+                        "spec_version": (fm.get("spec_version") or "").strip(),
+                        "follows": (fm.get("follows") or "").strip(),
+                        "in_flight": os.path.isdir(os.path.join(sdir, sid)),
+                        "cites": rids(fm.get("exercises", ""))})
+open_stories = [s for s in stories if s["status"] == "open"]
+
+# THE FLOOR is the oldest version any open story is still sitting at, and everything above
+# it is unsynced. A story whose spec_version is missing or unreadable counts as v0.0 rather
+# than being skipped: it has demonstrably never synced, and putting the whole ledger above
+# it is the same answer enumerating from the document would give.
+floors = [vtuple(s["spec_version"]) for s in open_stories]
+readable = [s for s in open_stories if re.match(r'^v?\d', s["spec_version"] or "")]
+# A BACKLOG THAT IS ENTIRELY CLOSED IS NOT A BACKLOG THAT NEVER SYNCED. Reading the floor
+# from open stories alone made the last story closing look exactly like a feature nobody has
+# ever sliced: no floor took the enumerate-the-whole-document branch below, so one idle
+# re-run after finishing a feature raised a fresh story for every requirement in the spec —
+# each one reported as work the contract had moved on, when nothing had moved at all. A
+# CLOSED story carries a stamp too, and it records which version its work was measured
+# against. CANCELLED ones are excluded: abandoned work delivered nothing and settles nothing,
+# so it establishes no floor and leaves its requirements to be sliced again.
+closed_stories = [s for s in stories if s["status"] == "closed"]
+floor_source = "open" if floors else ("closed" if closed_stories else "none")
+floor = (min(floors) if floors
+         else (min(vtuple(s["spec_version"]) for s in closed_stories) if closed_stories
+               else None))
+
+latest = rows[-1] if rows else None
+out = {"ok": True, "feature_dir": fd, "has_ledger": has_ledger,
+       "row_count": len(rows), "ledger_empty": len(rows) == 0,
+       "rows": rows,
+       "latest_version": latest["version"] if latest else "",
+       "latest_change": latest["change"] if latest else "",
+       "latest_ids_csv": ", ".join(latest["requirements"]) if latest else "",
+       "spec_ids_csv": ", ".join(declared), "spec_id_count": len(declared),
+       "story_count": len(stories), "open_count": len(open_stories),
+       "unversioned_open": len(open_stories) - len(readable)}
+
+if not has_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.")
+    print(json.dumps(out)); sys.stderr.write(out["error"] + "\n"); sys.exit(2)
+
+if not rows:
+    # An empty ledger is not corruption — it is a spec that has never been versioned, which
+    # means specify has not finished with it. Reported, not raised: the caller warns and
+    # stops, because there is no "since" to sync from and inventing one would raise a
+    # backlog against a document nobody has committed to.
+    out.update(work_csv="", work_count=0, work_source="none", span_versions_csv="",
+               gap=False, removed_csv="",
+               work_note="the Change History table carries no version row")
+    print(json.dumps(out)); sys.exit(0)
+
+if floor is None:
+    # E42 — nothing has moved because nothing has synced. Enumerate from the document.
+    source, span = "spec", []
+    candidates = list(declared)
+    note = ("nothing has synced against this spec yet — no open story records a version and "
+            "nothing has closed against it — so there is no 'since' to read from: the work "
+            "set is every requirement the document declares, and the per-id rules then "
+            "create only what has no story")
+else:
+    span = [r for r in rows if vtuple(r["version"]) > floor]
+    seen, candidates = set(), []
+    for r in span:
+        for rid in r["requirements"]:
+            if rid not in seen: seen.add(rid); candidates.append(rid)
+    candidates.sort(key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
+    source = "ledger"
+    note = ("%d version row(s) above the oldest %s story's v%d.%d: %s"
+            % (len(span), floor_source, floor[0], floor[1],
+               ", ".join(r["version"] for r in span) or "none"))
+
+# THE SPAN IS A PREFILTER; STALENESS IS PER ID. The floor is the oldest version any open
+# story sits at, and a story whose requirements never move sits there forever — Order-001
+# holding v1.0 keeps v1.1 and v1.2 in the span long after everything they named has been
+# synced. Reading the span alone therefore re-offered the same requirements on every run,
+# and each re-offer is a model call rewriting a story that was already in step.
+#
+# So the span says which ids are WORTH CHECKING and this says which have actually moved
+# under someone: an id is stale when it has no open story at all, or when some open story
+# citing it is stamped BELOW the newest version that touched it. An id whose every open
+# story is at or above that version is in step, whatever the floor says.
+moved_at = {}
+for r in rows:
+    for rid in r["requirements"]:
+        v = vtuple(r["version"])
+        if v > moved_at.get(rid, (0, 0)): moved_at[rid] = v
+
+def carried_on(story_id, rid, at):
+    """Has a follow-on already taken this requirement off that story's hands, at or above
+    the version that moved it. The `follows` link is the whole record of that hand-off."""
+    return any(s["follows"] == story_id and rid in s["cites"]
+               and vtuple(s["spec_version"]) >= at for s in open_stories)
+
+work, in_step = [], []
+for rid in candidates:
+    holders = [s for s in open_stories if rid in s["cites"]]
+    at = moved_at.get(rid, (0, 0))
+    behind = []
+    for s in holders:
+        if vtuple(s["spec_version"]) >= at: continue
+        # AN IN-FLIGHT STORY CANNOT BE BROUGHT UP TO DATE, BY DESIGN. It is never rewritten
+        # (§5.5), so its spec_version can never rise, so reading it as a staleness signal
+        # gives a signal that never clears — and a sync that mints a fresh follow-on for the
+        # same requirement on every run. What clears it is the follow-on itself: once one
+        # exists carrying this id at or above the version that moved it, the hand-off has
+        # happened and the original is history in progress, not unfinished business.
+        if s["in_flight"] and carried_on(s["id"], rid, at): continue
+        behind.append(s["id"])
+    # A CLOSED STORY STAMPED AT OR ABOVE THE VERSION THAT LAST MOVED THIS REQUIREMENT
+    # DELIVERED THE WORDING THE SPEC ASKS FOR TODAY, so the requirement is FINISHED rather
+    # than unsliced. Reading "no open story cites it" as work on its own could not tell those
+    # two apart, which is what let a fully delivered feature re-raise its entire backlog.
+    # A closed story stamped BELOW that version is the other case and stays work: the
+    # contract moved after it shipped, so what shipped is no longer what the spec asks for,
+    # and backlog-plan names the closed story it is re-opening against.
+    delivered = any(rid in s["cites"] and vtuple(s["spec_version"]) >= at
+                    for s in closed_stories)
+    (in_step if ((holders and not behind) or (not holders and delivered))
+     else work).append(rid)
+
+# A row names what a version TOUCHED, and that includes ids it REMOVED. A removed
+# requirement has no wording left to write a story from, so it leaves the work set — but it
+# is reported, because every open story citing one is orphaned and that is a decision for a
+# person, not a default (E1).
+removed = [i for i in work if i not in declared]
+work = [i for i in work if i in declared]
+
+out.update(work_csv=", ".join(work), work_count=len(work), work_source=source,
+           work_note=note, work_any=bool(work),
+           candidates_csv=", ".join(candidates), candidate_count=len(candidates),
+           in_step_csv=", ".join(in_step), in_step_count=len(in_step),
+           floor_source=floor_source,
+           span_versions_csv=", ".join(r["version"] for r in span),
+           span_count=len(span), gap=len(span) > 1,
+           removed_csv=", ".join(removed), removed_count=len(removed),
+           synced_floor=("v%d.%d" % floor) if floor else "")
+print(json.dumps(out))
+PY
+}
+
+# ─────────────────────────────── slice-mode ────────────────────────────────
+# Which slicing strategy the launch line asked for, and what is left of the input once that
+# word is taken out of it. Its own op rather than a `condition:` in the workflow, because
+# the engine compares a whole rendered value: `{{USER_INPUT}} == single-run` only matches an
+# input carrying the strategy and no guidance at all, and `sync-stories single-run keep the
+# payment rules together` — the form the launch line documents — would silently slice by
+# default while looking as though it had been told not to.
+#
+# ONLY THE FIRST WORD IS A STRATEGY. Guidance is free prose, and "keep the single sign-on
+# requirements in one story" is a slicing instruction with the token sitting in the middle
+# of it. Reading the token anywhere in the string would turn that sentence into the opposite
+# of what it asks, with nothing to say so.
+cmd_slice_mode() {
+    local input=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --input) input="$2"; shift 2 ;;
+            --help|-h) echo "slice-mode [--input <text>]  -> {strategy, guidance, note}"; return 0 ;;
+            *) echo "slice-mode: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    AW_INPUT="$input" python3 - <<'PY'
+import json, os, re
+raw = (os.environ.get("AW_INPUT", "") or "").strip()
+
+# `single-run` is the spelling the launch line documents; the others are what people write
+# when they mean it. `auto` is the default and is accepted explicitly so a launch line can
+# say so — a strategy nobody can name is one nobody can turn off.
+TOKENS = {"single-run": "single", "single-story": "single", "single": "single",
+          "one-story": "single", "auto": "auto", "per-slice": "auto", "default": "auto"}
+
+strategy, guidance = "auto", raw
+m = re.match(r'^([A-Za-z][A-Za-z0-9_-]*)\s*[:,]?\s*(.*)$', raw, re.S)
+if m and m.group(1).lower() in TOKENS:
+    strategy = TOKENS[m.group(1).lower()]
+    guidance = m.group(2).strip()
+
+if strategy == "single":
+    note = ("one story was asked for (single-run): the whole work set goes into a single "
+            "slice unless it is too heavy to be picked up as one piece of work, in which "
+            "case it is split along its dependencies and the split is reported")
+else:
+    note = "the slicing is decided from the requirements themselves"
+
+print(json.dumps({"ok": True, "strategy": strategy, "guidance": guidance,
+                  "single": strategy == "single", "note": note,
+                  "raw": raw, "tokens": sorted(TOKENS)}))
+PY
+}
+
+# ─────────────────────────────── backlog-plan ──────────────────────────────
+# The grouping is a judgment; everything that follows from it is arithmetic. This op does
+# the arithmetic, in two modes over the same inputs so the two passes cannot disagree about
+# what a group contains:
+#
+#   scan   which OPEN stories already stand in front of a group's requirements — the
+#          candidates the author is asked about, and the wording of that question.
+#   plan   given the author's answer, the flat list of story files to write: one entry per
+#          file, each already carrying its id, its path, and the ids it must end up citing.
+#
+# THE FOUR CASES (§5.4) resolve per group, not per requirement, because a group IS the story:
+#
+#   no open story cites anything in the group        -> create
+#   an open story does, no stories/<ID>/ yet         -> update in place (asked)
+#   an open story does, a story plan already exists  -> mint a follow-on (asked); the
+#                                                       original is never rewritten (§5.5)
+#   the author declines                              -> that story is left alone AND the ids
+#                                                       it covers leave the group; whatever
+#                                                       remains becomes a new story
+#
+# The last line is the one worth reading twice. Declining does not abandon the group — it
+# withdraws the requirements that story is already carrying and creates a story for the
+# rest. A group of three where one id has a story the author will not touch still delivers
+# the other two.
+#
+# ONE GROUP, ONE ABSORBING STORY. Where the author approves two stories in the same group,
+# the first by id takes the group's unclaimed requirements and the others keep exactly the
+# ids they already cite. Two stories both claiming the same new requirement is not a state
+# the completeness rule can read.
+#
+# IN FLIGHT IS TESTED PER STORY, NOT ONLY ON THE FIRST. An approved story that already has
+# a story with a story plan is never rewritten wherever it sits in the group — it gets its own follow-on
+# carrying what it covers, exactly as it would if it were the only story there.
+#
+# AND THE ORDER. Plan mode also resolves the dependency edges the grouping declared between
+# slices, folds in the `depends_on:` an updated story already carries, breaks any cycle, and
+# lays the result out in WAVES: wave N holds the stories whose every dependency sits below N,
+# so one wave is a set with no ordering between its members — they may be picked up in
+# parallel. The plan comes back sorted by wave, which is also the order the stories are
+# written in, so meeting the cap costs the LAST wave rather than an arbitrary slice of the
+# backlog. See the block above the wave computation for why `follows:` is not an edge.
+cmd_backlog_plan() {
+    local fd_arg="" groups="" approved="" work="" version="" mode="scan" cap="" strategy="" ceiling=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --groups)   groups="$2";   shift 2 ;;
+            --approved) approved="$2"; shift 2 ;;
+            --work)     work="$2";     shift 2 ;;
+            --version)  version="$2";  shift 2 ;;
+            --cap)      cap="$2";      shift 2 ;;
+            --strategy) strategy="$2"; shift 2 ;;
+            --ceiling)  ceiling="$2";  shift 2 ;;
+            --plan)     mode="plan";   shift ;;
+            --help|-h) echo "backlog-plan --groups <json> --work <csv> [--strategy single|auto] [--ceiling <n>] [--feature-dir <p>]"; echo "backlog-plan --plan --groups <json> --work <csv> --approved <story ids> --version <v> [--cap <n>] [--strategy single|auto] [--ceiling <n>]"; return 0 ;;
+            *) echo "backlog-plan: 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 "backlog-plan: no feature set and no --feature-dir" >&2; return 1; }
+    AW_FD="$fd" AW_GROUPS="$groups" AW_OK="$approved" AW_WORK="$work" AW_VER="$version" AW_MODE="$mode" AW_CAP="$cap" AW_STRATEGY="$strategy" AW_CEILING="$ceiling" python3 - <<'PY'
+import json, os, re, sys
+fd = os.environ["AW_FD"]; mode = os.environ.get("AW_MODE", "scan")
+sdir = os.path.join(fd, "stories")
+feature = os.path.basename(fd.rstrip("/\\"))
+
+def bail(msg, code=2):
+    print(json.dumps({"ok": False, "error": msg}))
+    sys.stderr.write(msg + "\n"); sys.exit(code)
+
+def rids(s):
+    seen, out = set(), []
+    for t in re.findall(r'\b(?:FR|BR)-\d+', s or ""):
+        if t not in seen: seen.add(t); out.append(t)
+    return sorted(out, key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
+
+def sids(s):
+    """Story ids out of a csv, a JSON list or a YAML inline list. A story id is a feature
+    name and a number; a template placeholder (`[]`, `[STORY-ID]`) is neither, and must
+    never become a dependency edge nobody can resolve."""
+    seen, out = set(), []
+    for t in re.split(r'[,\s\[\]"\']+', s or ""):
+        t = t.strip()
+        if re.match(r'^[A-Za-z][\w.]*-\d+$', t) and t not in seen:
+            seen.add(t); out.append(t)
+    return out
+
+def wave_of(s):
+    """A story's declared wave. Absent — a story written before the field existed — reads
+    as 1, the conservative floor: nothing is KNOWN to have to land before it."""
+    m = re.match(r'^\s*(\d+)\s*$', (s or "").strip())
+    return int(m.group(1)) if m else 1
+
+def names(s):
+    """Story ids out of a csv or a JSON list. A multi-select answer arrives as the engine's
+    JSON rendering of a list, so both spellings have to read the same."""
+    seen, out = set(), []
+    for t in re.split(r'[,\s\[\]"\']+', s or ""):
+        t = t.strip()
+        if t and t not in seen: seen.add(t); out.append(t)
+    return out
+
+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
+
+# ---- the backlog -----------------------------------------------------------------
+stories, used_numbers = [], []
+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
+        fm = parse_fm(open(p, encoding="utf-8", errors="replace").read())
+        sid = fm.get("id") or name[:-3]
+        # Numbers come from the FILENAME as well as the id, and from CLOSED and CANCELLED
+        # stories as well as open ones. An id is permanent once minted: re-issuing the
+        # number of a story that shipped re-points its execution artefacts at new work.
+        for cand in (sid, name[:-3]):
+            m = re.search(r'-(\d+)$', cand)
+            if m: used_numbers.append(int(m.group(1)))
+        stories.append({"id": sid, "status": (fm.get("status") or "open").strip().lower(),
+                        "title": (fm.get("title") or "").strip().strip("[]"),
+                        "spec_version": (fm.get("spec_version") or "").strip(),
+                        "cites": rids(fm.get("exercises", "")),
+                        "wave": wave_of(fm.get("wave", "")),
+                        "deps": sids(fm.get("depends_on", "")),
+                        "in_flight": os.path.isdir(os.path.join(sdir, sid)),
+                        "path": p})
+open_stories = [s for s in stories if s["status"] == "open"]
+# Closed and cancelled stories hold no requirement — completeness is "no OPEN stories" —
+# but they are the reason a create can look like duplicated work, so they are read in
+# order to say so. See the create branch below.
+done_stories = [s for s in stories if s["status"] != "open"]
+by_id = {s["id"]: s for s in stories}
+_next = [max(used_numbers) + 1 if used_numbers else 1]
+
+def mint():
+    n = _next[0]; _next[0] += 1
+    return "%s-%03d" % (feature, n)
+
+# ---- the groups ------------------------------------------------------------------
+raw = (os.environ.get("AW_GROUPS") or "").strip()
+try:
+    parsed = json.loads(raw) if raw else []
+except Exception as e:
+    bail("backlog-plan: --groups is not valid JSON (%s)" % e)
+if isinstance(parsed, dict): parsed = parsed.get("groups") or []
+if not isinstance(parsed, list):
+    bail("backlog-plan: --groups must be a JSON list of groups")
+
+# Ids are read from the group's OWN requirements field, never scraped from its prose. A
+# rationale that mentions FR-004 as the reason two others belong together would otherwise
+# pull a third requirement into the story, and nothing downstream would question it.
+work = rids(os.environ.get("AW_WORK", ""))
+groups, dropped = [], []
+for i, g in enumerate(parsed):
+    if not isinstance(g, dict): continue
+    src = g.get("requirements")
+    if isinstance(src, list): src = ", ".join(str(x) for x in src)
+    ids = rids(src if src is not None else g.get("requirements_csv", ""))
+    if work:
+        outside = [x for x in ids if x not in work]
+        dropped += outside
+        ids = [x for x in ids if x in work]
+    if not ids: continue
+    # `depends_on` names OTHER GROUPS by key, or open stories already in the backlog by
+    # id. Kept as raw tokens: a group key only becomes a story id once the plan has minted
+    # one, so resolving here would have to guess at a name that does not exist yet.
+    dep_src = g.get("depends_on")
+    if dep_src is None: dep_src = g.get("depends_on_csv")
+    if isinstance(dep_src, list): dep_src = ", ".join(str(x) for x in dep_src)
+    deps_raw = [x for x in re.split(r'[,\s\[\]"\']+', str(dep_src or "")) if x.strip()]
+    groups.append({"key": g.get("id") or ("g%d" % (i + 1)),
+                   "title": (g.get("title") or "").strip(),
+                   "rationale": (g.get("rationale") or "").strip(),
+                   "complexity": (g.get("complexity") or "").strip().lower(),
+                   "deps_raw": deps_raw,
+                   "ids": ids, "ids_csv": ", ".join(ids)})
+
+# Every work-set id must land in exactly one group. One the model left out gets no story
+# and nothing says so; one it repeated gets two, each claiming the same requirement.
+placed = [x for g in groups for x in g["ids"]]
+repeated = sorted({x for x in placed if placed.count(x) > 1})
+
+# A REPEATED ID IS RESOLVED HERE, not merely reported. Two groups both claiming one
+# requirement become two stories both claiming it, and "does this requirement still have
+# open stories" — the completeness rule — then answers for work that was never really
+# duplicated. The grouping is a judgment; the arithmetic over it is not. So the id stays in
+# the FIRST group that claimed it and leaves the rest, which is deterministic (the same
+# grouping always yields the same slices) and loses no coverage, because the id still
+# reaches exactly one story. repeated_notice reports what that touched.
+if repeated:
+    seen_ids = set()
+    for g in groups:
+        keep_ids = [x for x in g["ids"] if x not in seen_ids]
+        seen_ids.update(keep_ids)
+        g["ids"], g["ids_csv"] = keep_ids, ", ".join(keep_ids)
+    groups = [g for g in groups if g["ids"]]
+    placed = [x for g in groups for x in g["ids"]]
+
+missed = [x for x in work if x not in placed]
+
+def candidates_of(g):
+    """Open stories standing in front of this group, each with what it already covers OF
+    THIS GROUP — the intersection, not its whole citation list, because that is what the
+    author is being asked to move."""
+    out = []
+    for s in open_stories:
+        shared = [x for x in g["ids"] if x in s["cites"]]
+        if not shared: continue
+        out.append({"story": s["id"], "title": s["title"], "in_flight": s["in_flight"],
+                    "spec_version": s["spec_version"], "cites_csv": ", ".join(s["cites"]),
+                    "shared_csv": ", ".join(shared), "shared": shared,
+                    "group": g["key"], "group_title": g["title"], "group_ids_csv": g["ids_csv"],
+                    "action": "followon" if s["in_flight"] else "update"})
+    return sorted(out, key=lambda c: c["story"])
+
+base = {"ok": True, "feature": feature, "feature_dir": fd, "stories_dir": sdir,
+        "group_count": len(groups), "groups": groups,
+        "work_csv": ", ".join(work),
+        "unplaced_csv": ", ".join(missed), "unplaced_count": len(missed),
+        "repeated_csv": ", ".join(repeated), "repeated_count": len(repeated),
+        "dropped_csv": ", ".join(sorted(set(dropped))),
+        "groups_digest": "\n".join(
+            "  [%s] %s\n      requirements: %s%s%s"
+            % (g["key"], g["title"] or "(untitled)", g["ids_csv"],
+               ("\n      stands behind: " + ", ".join(g["deps_raw"])) if g["deps_raw"] else "",
+               ("\n      " + g["rationale"]) if g["rationale"] else "")
+            for g in groups) or "  (no groups)"}
+
+# THE STRATEGY IS THE AUTHOR'S; THE ARITHMETIC OVER IT IS NOT. `single` asked for one story
+# covering the whole work set, and the grouping may still have returned several — because a
+# slice nobody can pick up is not a story, and splitting it is the honest answer. So the
+# split is REPORTED rather than refused or hidden: quietly handing six stories to someone
+# who asked for one is the kind of silent disobedience that makes an option not worth having.
+strategy = (os.environ.get("AW_STRATEGY") or "").strip().lower() or "auto"
+try:
+    ceiling = int((os.environ.get("AW_CEILING") or "").strip() or 8)
+except ValueError:
+    ceiling = 8
+oversized = [g["key"] for g in groups if len(g["ids"]) > ceiling]
+split_note, split_count = "", 0
+if strategy == "single" and len(groups) > 1:
+    split_count = len(groups)
+    split_note = ("one story was asked for and the work set was too heavy for one: it is "
+                  "split into %d, in dependency order — %s" % (len(groups), "; ".join(
+                      "[%s] %s (%s)" % (g["key"], g["title"] or "untitled", g["ids_csv"])
+                      for g in groups)))
+elif strategy == "single" and len(groups) == 1:
+    split_note = ("one story was asked for and one covers the whole work set: %s"
+                  % groups[0]["ids_csv"])
+base.update(strategy=strategy, ceiling=ceiling, split_count=split_count,
+            split_note=split_note, oversized_csv=", ".join(oversized))
+
+if mode == "scan":
+    cands = [c for g in groups for c in candidates_of(g)]
+    lines = []
+    for c in cands:
+        lines.append(
+            "  %s  (%s)\n"
+            "      group [%s] %s covers %s\n"
+            "      this story already covers %s of it, and cites %s in total\n"
+            "      %s"
+            % (c["story"], c["title"] or "untitled",
+               c["group"], c["group_title"] or "", c["group_ids_csv"],
+               c["shared_csv"], c["cites_csv"],
+               ("ALREADY IN FLIGHT (story plan exists) — picking it mints a FOLLOW-ON "
+                "carrying the change; this story is never rewritten"
+                if c["in_flight"] else
+                "not started (no story plan yet) — picking it rewrites this story to "
+                "cover the whole group")))
+    base.update(candidates=cands, candidate_count=len(cands),
+                candidate_ids=[c["story"] for c in cands],
+                candidate_csv=", ".join(c["story"] for c in cands),
+                any_candidates=bool(cands),
+                ask_digest="\n".join(lines) or "  (no existing story covers any of these)")
+    print(json.dumps(base)); sys.exit(0)
+
+# ---- plan ------------------------------------------------------------------------
+approved = set(names(os.environ.get("AW_OK", "")))
+version = (os.environ.get("AW_VER") or "").strip()
+plan, skipped, notes = [], [], []
+for g in groups:
+    cands = candidates_of(g)
+    declined = [c for c in cands if c["story"] not in approved]
+    # A declined story keeps its requirements: the author said do not disturb it, and
+    # raising a second story over the same ids disturbs it just as thoroughly.
+    held = {x for c in declined for x in c["shared"]}
+    skipped += [c["story"] for c in declined]
+    remaining = [x for x in g["ids"] if x not in held]
+    taken = [c for c in cands if c["story"] in approved]
+
+    if taken:
+        # ONE APPROVED STORY ABSORBS THE GROUP'S UNCLAIMED REQUIREMENTS — the first by id.
+        # Every OTHER approved story keeps exactly the ids it already cites, so those ids
+        # are RESERVED out of what the carrier gains: two open stories both claiming one
+        # requirement is not a state the completeness rule can read, and the run would have
+        # created that state itself rather than merely reporting it.
+        carrier = taken[0]; s = by_id[carrier["story"]]
+        reserved = {x for c in taken[1:] for x in c["shared"]}
+        gained = [x for x in remaining if x not in reserved]
+        if carrier["in_flight"]:
+            # §5.5 — the original stays open and unchanged, and closes having delivered
+            # what it was written to deliver. The follow-on carries the remainder.
+            carry = [x for x in g["ids"] if x in s["cites"] or x in gained]
+            carry = [x for x in carry if x not in held]
+            sid = mint()
+            plan.append({"action": "followon", "story": sid, "follows": carrier["story"],
+                         "path": os.path.join(sdir, sid + ".md"),
+                         "requirements_csv": ", ".join(carry), "existing_csv": "",
+                         "prior_csv": ", ".join(s["cites"]), "prior_title": s["title"],
+                         "prior_path": s["path"],
+                         "group": g["key"], "group_title": g["title"],
+                         "group_ids_csv": g["ids_csv"], "complexity": g["complexity"],
+                         "rationale": g["rationale"], "spec_version": version})
+        else:
+            keep = sorted(set(s["cites"]) | set(gained),
+                          key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
+            plan.append({"action": "update", "story": s["id"], "follows": "",
+                         "path": s["path"],
+                         "requirements_csv": ", ".join(keep),
+                         "existing_csv": ", ".join(s["cites"]),
+                         "prior_csv": ", ".join(s["cites"]), "prior_title": s["title"],
+                         "prior_path": s["path"],
+                         "group": g["key"], "group_title": g["title"],
+                         "group_ids_csv": g["ids_csv"], "complexity": g["complexity"],
+                         "rationale": g["rationale"], "spec_version": version})
+        carrier_sid = plan[-1]["story"]
+        for c in taken[1:]:
+            s2 = by_id[c["story"]]
+            if c["in_flight"]:
+                # AN IN-FLIGHT STORY IS NEVER REWRITTEN, whatever position it holds in the
+                # group. Its story plan was derived from this body, and
+                # rewriting the body leaves the three disagreeing with nothing to say so —
+                # which is the whole reason §5.5 exists. Being second in a group is not a
+                # different situation from being first, so it gets the same answer: its own
+                # follow-on, carrying the ids it already covers of this group.
+                #
+                # That link is also what clears its staleness. ledger-read discounts an
+                # in-flight story once an open story whose `follows` names it cites the same
+                # id; skipping it instead would leave it stale forever and re-offered on
+                # every run.
+                carry2 = [x for x in c["shared"] if x not in held]
+                if not carry2:
+                    notes.append("%s was approved and is in flight, but every requirement "
+                                 "it covers of group [%s] is held by a story left "
+                                 "untouched; nothing to carry" % (c["story"], g["key"]))
+                    continue
+                sid2 = mint()
+                notes.append("%s was approved and is IN FLIGHT, so it is not rewritten; "
+                             "%s carries %s forward from it, while %s takes the group's "
+                             "unclaimed requirements"
+                             % (c["story"], sid2, ", ".join(carry2), carrier_sid))
+                plan.append({"action": "followon", "story": sid2, "follows": c["story"],
+                             "path": os.path.join(sdir, sid2 + ".md"),
+                             "requirements_csv": ", ".join(carry2), "existing_csv": "",
+                             "prior_csv": ", ".join(s2["cites"]), "prior_title": s2["title"],
+                             "prior_path": s2["path"],
+                             "group": g["key"], "group_title": g["title"],
+                             "group_ids_csv": g["ids_csv"], "complexity": g["complexity"],
+                             "rationale": g["rationale"], "spec_version": version})
+                continue
+            notes.append("%s was approved but %s takes the group's unclaimed requirements; "
+                         "%s is refreshed against the current spec without gaining ids"
+                         % (c["story"], carrier_sid, c["story"]))
+            plan.append({"action": "update", "story": s2["id"], "follows": "",
+                         "path": s2["path"],
+                         "requirements_csv": ", ".join(s2["cites"]),
+                         "existing_csv": ", ".join(s2["cites"]),
+                         "prior_csv": ", ".join(s2["cites"]), "prior_title": s2["title"],
+                         "prior_path": s2["path"],
+                         "group": g["key"], "group_title": g["title"],
+                         "group_ids_csv": g["ids_csv"], "complexity": g["complexity"],
+                         "rationale": g["rationale"], "spec_version": version})
+    elif remaining:
+        sid = mint()
+        # A REQUIREMENT WHOSE ONLY STORIES ARE CLOSED RE-ENTERS THE WORK SET, and that is
+        # right: a version row above the closed story's stamp means the contract moved
+        # AFTER it shipped, so what shipped is no longer what the spec asks for. It reads
+        # as duplicated work to anyone who remembers delivering it, so the run names the
+        # story it is re-opening against rather than leaving them to find it.
+        shipped = ["%s (%s)" % (d["id"], ", ".join(x for x in remaining if x in d["cites"]))
+                   for d in done_stories if any(x in d["cites"] for x in remaining)]
+        if shipped:
+            notes.append("%s covers requirements already delivered by %s — the spec moved "
+                         "after those closed, so this is the change, not a repeat"
+                         % (sid, "; ".join(shipped)))
+        plan.append({"action": "create", "story": sid, "follows": "",
+                     "path": os.path.join(sdir, sid + ".md"),
+                     "requirements_csv": ", ".join(remaining), "existing_csv": "",
+                     "prior_csv": "", "prior_title": "", "prior_path": "",
+                     "group": g["key"], "group_title": g["title"],
+                     "group_ids_csv": g["ids_csv"], "complexity": g["complexity"],
+                     "rationale": g["rationale"], "spec_version": version})
+    else:
+        notes.append("group [%s] (%s) is entirely covered by stories left untouched; "
+                     "nothing to write" % (g["key"], g["ids_csv"]))
+
+# ---- waves: the order these stories can actually be picked up in -------------------
+# The grouping declared which slices stand behind which; turning that into an order is
+# arithmetic, so it happens here and not in the prompt — the same grouping always yields
+# the same waves.
+#
+# A WAVE IS AN ELIGIBILITY LEVEL, NOT A SCHEDULE. Wave N means every story this one depends
+# on sits in a wave below N. Two stories in the SAME wave therefore have no dependency
+# between them and may be picked up in parallel; it does not say they start together, and
+# nothing waits for a whole wave to finish. That is also why the number is not a priority:
+# wave 1 is "nothing blocks this", not "do this first".
+#
+# THE EDGE SET IS A UNION of what the grouping declared and what an updated story already
+# carries in `depends_on:`. The sync sees one feature's spec; an edge someone added by hand
+# may name work it has no view of, and dropping it would silently un-order real work. Both
+# are claims about CODE ordering, and the union is exactly what the story ends up citing —
+# so the wave and the frontmatter cannot disagree about what stands in front of what.
+#
+# `follows:` is NOT an edge. A follow-on carries the remainder of a story in flight, and the
+# remainder is often buildable alongside it — §5.5 asks the author to say in Notes which
+# half has to land first. Making it an implicit edge would put an ordering in the waves that
+# no frontmatter field explains.
+entries_of, by_story = {}, {}
+for e in plan:
+    entries_of.setdefault(e["group"], []).append(e["story"]); by_story[e["story"]] = e
+preds = {e["story"]: set() for e in plan}
+external, unresolved = {}, []      # stories outside this run, at the wave they declare
+
+for g in groups:
+    tgt = entries_of.get(g["key"], [])
+    if not tgt: continue           # the group wrote nothing; its edges order nothing
+    for tok in g["deps_raw"]:
+        tok = tok.strip()
+        if not tok or tok == g["key"]: continue
+        if tok in entries_of:
+            src = entries_of[tok]
+        elif tok in by_id and by_id[tok]["status"] == "open":
+            external[tok] = by_id[tok]["wave"]; src = [tok]
+        else:
+            unresolved.append("%s (named by group [%s])" % (tok, g["key"])); continue
+        for x in tgt: preds[x].update(s for s in src if s != x)
+
+for e in plan:
+    if e["action"] != "update": continue
+    for d in by_id.get(e["story"], {}).get("deps", []):
+        if d == e["story"] or d in preds[e["story"]]: continue
+        if d not in preds: external[d] = by_id[d]["wave"] if d in by_id else 1
+        preds[e["story"]].add(d)
+
+# A CYCLE IS REJECTED AT AUTHORING TIME (§6.1), and this is where it would be authored.
+# Depth-first over a sorted node order, dropping the one edge that closes each cycle: only
+# edges that actually close one are lost, and the choice is deterministic — the same
+# grouping always breaks the same edge. Reported, because a dropped edge was a real claim
+# about ordering and the cycle it sat in is a fact about the slicing, not a glitch.
+cycles, state = [], {}
+def walk(node):
+    state[node] = 1
+    for m in sorted(preds.get(node, ())):
+        if state.get(m) == 1:
+            preds[node].discard(m); cycles.append("%s -> %s" % (node, m)); continue
+        if state.get(m) != 2 and m in preds: walk(m)
+    state[node] = 2
+for node in sorted(preds):
+    if state.get(node) != 2: walk(node)
+
+# Longest path from a root, relaxed to a fixed point. A story with no dependency is wave 1,
+# which is what puts every independent story in the same wave.
+wave = dict(external)
+for _ in range(len(preds) + 1):
+    moved = False
+    for node in sorted(preds):
+        w = 1 + max([wave.get(m, 1) for m in preds[node]] or [0])
+        if wave.get(node) != w: wave[node] = w; moved = True
+    if not moved: break
+for e in plan:
+    e["wave"] = wave.get(e["story"], 1)
+    e["depends_on_csv"] = ", ".join(sorted(preds.get(e["story"], ())))
+
+# Written in wave order, so a run that meets the cap writes the stories that can be STARTED
+# rather than an arbitrary prefix of them. The story id is not the order — the wave is.
+plan.sort(key=lambda e: (e["wave"], e["story"]))
+for i, e in enumerate(plan): e["seq"] = i + 1
+
+waves = {}
+for e in plan: waves.setdefault(e["wave"], []).append(e["story"])
+wave_digest = "\n".join("  wave %d: %s" % (w, ", ".join(waves[w]))
+                        for w in sorted(waves)) or "  (nothing to write)"
+if unresolved:
+    notes.append("the grouping named dependencies matching no slice and no open story, so "
+                 "they set no order: %s" % "; ".join(sorted(set(unresolved))))
+if cycles:
+    notes.append("slices were declared to depend on each other in a cycle; the edge closing "
+                 "each one is dropped, because a backlog with no order at all is worse than "
+                 "one missing an edge someone can re-add: %s" % ", ".join(cycles))
+
+# THE WRITE LOOP HAS A CEILING AND THE ENGINE DOES NOT SAY WHEN IT HITS IT — `over:` stops
+# at max_iterations with no message, so plan entries past it are simply never written and
+# the run reports success. The caller passes its own ceiling here so the overflow is named
+# while the story ids still exist to name. Nothing is dropped from the plan: the ids are
+# reported and the entries stay, so raising the cap and re-running writes them.
+try:
+    cap = int((os.environ.get("AW_CAP") or "").strip() or 0)
+except ValueError:
+    cap = 0
+overflow = [e["story"] for e in plan[cap:]] if cap > 0 else []
+
+counts = {a: sum(1 for e in plan if e["action"] == a) for a in ("create", "update", "followon")}
+base.update(plan=plan, plan_count=len(plan), any_plan=bool(plan),
+            cap=cap, overflow_csv=", ".join(overflow), overflow_count=len(overflow),
+            create_count=counts["create"], update_count=counts["update"],
+            followon_count=counts["followon"],
+            skipped_csv=", ".join(sorted(set(skipped))),
+            stories_csv=", ".join(e["story"] for e in plan),
+            wave_digest=wave_digest, wave_count=len(waves),
+            max_wave=(max(waves) if waves else 0),
+            cycle_csv=", ".join(cycles),
+            unresolved_deps_csv=", ".join(sorted(set(unresolved))),
+            notes=notes, notes_text="\n".join("  - " + n for n in notes),
+            plan_digest="\n".join(
+                "  w%-3d %-9s %-16s %s%s%s"
+                % (e["wave"], e["action"], e["story"], e["requirements_csv"],
+                   ("  (follows %s)" % e["follows"]) if e["follows"] else "",
+                   ("  [after %s]" % e["depends_on_csv"]) if e["depends_on_csv"] else "")
+                for e in plan) or "  (nothing to write)")
+print(json.dumps(base))
+PY
+}
+
+# ─────────────────────────────── story-stamp ───────────────────────────────
+# The story's frontmatter is the gate surface — `exercises:`, `spec_version:`, `status:`
+# and `follows:` are what spec-coverage, check-stories, analyze-slice and close-story read,
+# and none of them opens the body. So those fields are OBSERVED and written by the kit, not
+# declared by the model that wrote the prose, for the same reason the Change History row is
+# computed rather than announced: a model that drops one id from `exercises:` produces a
+# story that reads perfectly and is invisible to every gate built to protect it. Silent,
+# and in the one field where silence costs the most.
+#
+# Everything else in the block is left exactly as the author wrote it, and a key the file
+# is missing is appended in template order rather than the block being rebuilt — a story
+# carrying a work_item or a depends_on must not lose it to a stamp.
+cmd_story_stamp() {
+    local fd_arg="" story="" ids="" version="" follows="" ids_given="" title="" deps="" wave=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --story)   story="$2";   shift 2 ;;
+            --ids)     ids="$2"; ids_given=1; shift 2 ;;
+            --version) version="$2"; shift 2 ;;
+            --follows) follows="$2"; shift 2 ;;
+            --title)   title="$2";   shift 2 ;;
+            --depends-on) deps="$2"; shift 2 ;;
+            --wave)    wave="$2";    shift 2 ;;
+            --help|-h) echo "story-stamp --story <id> [--ids <csv>] [--version <v>] [--follows <id>] [--title <t>] [--depends-on <csv>] [--wave <n>] [--feature-dir <p>]"; return 0 ;;
+            *) echo "story-stamp: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$story" ] || { echo "story-stamp: --story is required" >&2; return 1; }
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "story-stamp: no feature set and no --feature-dir" >&2; return 1; }
+    AW_FD="$fd" AW_STORY="$story" AW_IDS="$ids" AW_IDS_GIVEN="$ids_given" \
+    AW_VER="$version" AW_FOLLOWS="$follows" AW_TITLE="$title" \
+    AW_DEPS="$deps" AW_WAVE="$wave" python3 - <<'PY'
+import json, os, re, sys, datetime
+fd = os.environ["AW_FD"]; story = os.environ["AW_STORY"].strip()
+path = os.path.join(fd, "stories", story + ".md")
+
+def bail(msg, code=2):
+    print(json.dumps({"ok": False, "story": story, "path": path, "error": msg}))
+    sys.stderr.write(msg + "\n"); sys.exit(code)
+
+if not os.path.isfile(path):
+    bail("story-stamp: no story file at %s — the authoring step did not write it" % path)
+
+def rids(s):
+    seen, out = set(), []
+    for t in re.findall(r'\b(?:FR|BR)-\d+', s or ""):
+        if t not in seen: seen.add(t); out.append(t)
+    return sorted(out, key=lambda r: (r.split("-")[0], int(r.split("-")[1])))
+
+def sids(s):
+    """Story ids out of a csv or an inline list. A story id is a feature name and a number;
+    the template's placeholders are neither, and must not become a dependency edge."""
+    seen, out = set(), []
+    for t in re.split(r'[,\s\[\]"\']+', s or ""):
+        t = t.strip()
+        if re.match(r'^[A-Za-z][\w.]*-\d+$', t) and t not in seen:
+            seen.add(t); out.append(t)
+    return out
+
+text = open(path, encoding="utf-8", errors="replace").read()
+m = re.match(r'^---\s*\n(.*?)\n---\s*\n', text, re.S)
+if m:
+    block, body = m.group(1), text[m.end():]
+else:
+    # A model that returned the prose and no frontmatter leaves a story every gate skips.
+    # Synthesised rather than refused: the body is the expensive half and it is already on
+    # disk, and the fields below are exactly the ones this op is authoritative for.
+    block, body = "", text.lstrip("\n")
+
+# The block as an ordered list of (key, rendered line), so an unrecognised key and its
+# continuation lines survive untouched.
+lines = block.split("\n") if block else []
+order, seen_key = [], None
+for line in lines:
+    km = re.match(r'^([A-Za-z_]+):\s*(.*)$', line)
+    if km:
+        seen_key = km.group(1); order.append([seen_key, [line]])
+    elif order and (line.startswith(" ") or line.startswith("\t")):
+        order[-1][1].append(line)          # a block-list item under the key above
+    elif line.strip():
+        order.append([None, [line]])
+
+def put(key, value):
+    """Set a key to a single-line value, collapsing a block list into the inline form."""
+    line = ("%s: %s" % (key, value)) if value != "" else ("%s:" % key)
+    for entry in order:
+        if entry[0] == key:
+            entry[1] = [line]
+            return "set"
+    order.append([key, [line]])
+    return "added"
+
+TEMPLATE_ORDER = ["id", "type", "status", "title", "exercises", "spec_version",
+                  "depends_on", "wave", "follows", "work_item", "created"]
+def get(key):
+    for entry in order:
+        if entry[0] == key: return entry[1][0].split(":", 1)[1].strip()
+    return ""
+
+changed = {}
+changed["id"] = put("id", story)
+
+if os.environ.get("AW_IDS_GIVEN"):
+    ids = rids(os.environ.get("AW_IDS", ""))
+    changed["exercises"] = put("exercises", "[" + ", ".join(ids) + "]")
+else:
+    ids = rids(get("exercises"))
+
+ver = (os.environ.get("AW_VER") or "").strip()
+if ver: changed["spec_version"] = put("spec_version", ver)
+
+fol = (os.environ.get("AW_FOLLOWS") or "").strip()
+if fol: changed["follows"] = put("follows", fol)
+
+ttl = (os.environ.get("AW_TITLE") or "").strip()
+if ttl and (not get("title") or get("title").startswith("[")):
+    changed["title"] = put("title", ttl)
+
+# Placeholders the template ships. Left alone once a real value is in them, so a story
+# CLOSED between the plan and the write is not quietly re-opened by a stamp.
+if not get("type") or get("type").startswith("["):
+    changed["type"] = put("type", "functional" if ids else "technical")
+if not get("status") or get("status").startswith("["):
+    changed["status"] = put("status", "open")
+# ORDERING IS A UNION, NEVER A REPLACEMENT. The edges passed in are what this run's slicing
+# declared; the ones already in the file may name work outside this feature, which the sync
+# cannot see. Dropping either loses a real claim about what has to land first, and a lost
+# edge is silent — no later stage re-derives it.
+deps = sorted(set(sids(get("depends_on")) + sids(os.environ.get("AW_DEPS", ""))) - {story})
+if deps or not get("depends_on") or get("depends_on").startswith("["):
+    changed["depends_on"] = put("depends_on", "[" + ", ".join(deps) + "]")
+
+# THE WAVE IS AN ELIGIBILITY LEVEL, NOT A PRIORITY: every story this one depends on sits in
+# a lower one, so stories sharing a wave have no ordering between them and may be picked up
+# in parallel. Computed by backlog-plan from `depends_on`, and written here for the same
+# reason `exercises:` is — a field the gates and the listings read is observed, not declared.
+# A story stamped without one floors at 1: nothing is KNOWN to have to land before it.
+wv = (os.environ.get("AW_WAVE") or "").strip()
+if wv.isdigit():
+    changed["wave"] = put("wave", wv)
+elif not get("wave").isdigit():
+    changed["wave"] = put("wave", "1")
+if not get("created") or get("created").startswith("["):
+    changed["created"] = put("created", datetime.date.today().isoformat())
+for k in ("title", "follows", "work_item"):
+    if not any(e[0] == k for e in order): put(k, "")
+
+# Rendered back in template order, with anything unrecognised kept after it in the order it
+# was written. A story is read by people as well as by gates.
+rank = {k: i for i, k in enumerate(TEMPLATE_ORDER)}
+order.sort(key=lambda e: rank.get(e[0], len(TEMPLATE_ORDER)))
+out_block = "\n".join(l for e in order for l in e[1])
+open(path, "w", encoding="utf-8").write("---\n" + out_block + "\n---\n\n" + body.lstrip("\n"))
+
+print(json.dumps({"ok": True, "story": story, "path": path,
+                  "exercises": ids, "exercises_csv": ", ".join(ids),
+                  "spec_version": get("spec_version"), "status": get("status"),
+                  "depends_on": get("depends_on"), "wave": get("wave"),
+                  "follows": get("follows"), "title": get("title"),
+                  "type": get("type"), "had_frontmatter": bool(m),
+                  "fields": sorted(changed)}))
+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
@@ -1624,7 +2763,7 @@ PY
 #
 # 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
+# the silent case the whole ledger exists to prevent, since sync-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
@@ -1772,7 +2911,7 @@ 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
+# all belong in the ledger row), but handing that whole set to sync-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)]
@@ -1795,7 +2934,7 @@ print(json.dumps({
     # 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.
+    # changed, narrowed to the classes a story can cite — what sync-stories works from.
     "story_ids": story_ids, "story_ids_csv": ", ".join(story_ids),
     "story_id_count": len(story_ids),
 }))
@@ -1857,6 +2996,7 @@ 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"
+    local backend_plan="$fd/backend-plan.md" frontend_plan="$fd/frontend-plan.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.
@@ -1865,12 +3005,15 @@ cmd_feature_paths() {
     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
+    local backend_plan_exists=false;  [ -f "$backend_plan" ]  && backend_plan_exists=true
+    local frontend_plan_exists=false; [ -f "$frontend_plan" ] && frontend_plan_exists=true
     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' \
+    printf '{"feature":"%s","feature_dir":"%s","spec_file":"%s","design_file":"%s","ui_design_file":"%s","backend_plan_file":"%s","frontend_plan_file":"%s","spec_exists":%s,"design_exists":%s,"ui_design_exists":%s,"backend_plan_exists":%s,"frontend_plan_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")" "$(json_escape "$backend_plan")" "$(json_escape "$frontend_plan")" \
+        "$spec_exists" "$design_exists" "$ui_design_exists" "$backend_plan_exists" "$frontend_plan_exists" \
         "$bootstrap_pending" "$needs_bootstrap"
 }
 
@@ -2920,15 +4063,21 @@ cmd_design_scaffold() {
             # Priority-1), so the defaults already yield the as-built structure for
             # forward `design` and adopt alike, and this is rarely needed.
             --template) template_arg="$2"; shift 2 ;;
-            --help|-h) echo "design-scaffold --feature-dir <path> [--lane service|ui] [--template <name>]"; return 0 ;;
+            --help|-h) echo "design-scaffold --feature-dir <path> [--lane service|ui|backend|frontend] [--template <name>]"; return 0 ;;
             *) echo "design-scaffold: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
-    local doc_name
+    # backend/frontend are the PLAN-phase pairs: the same templates, the plan document
+    # names, and a MIGRATION — a legacy design.md / design.ui.md is RENAMED into the
+    # plan name so a feature never carries both spellings of the same master.
+    # service/ui stay byte-identical for their existing callers (adopt, the delta chain).
+    local doc_name legacy_name=""
     case "$lane_arg" in
-        service) doc_name="design.md";    [ -n "$template_arg" ] || template_arg="design-template" ;;
-        ui)      doc_name="design.ui.md"; [ -n "$template_arg" ] || template_arg="ui-design-template" ;;
-        *) echo "design-scaffold: unknown --lane '$lane_arg' (service|ui)" >&2; return 1 ;;
+        service)  doc_name="design.md";         [ -n "$template_arg" ] || template_arg="design-template" ;;
+        ui)       doc_name="design.ui.md";      [ -n "$template_arg" ] || template_arg="ui-design-template" ;;
+        backend)  doc_name="backend-plan.md";   legacy_name="design.md";    [ -n "$template_arg" ] || template_arg="design-template" ;;
+        frontend) doc_name="frontend-plan.md";  legacy_name="design.ui.md"; [ -n "$template_arg" ] || template_arg="ui-design-template" ;;
+        *) echo "design-scaffold: unknown --lane '$lane_arg' (service|ui|backend|frontend)" >&2; return 1 ;;
     esac
     local repo_root; repo_root=$(get_repo_root)
     local fd="$feature_dir_arg"
@@ -2937,7 +4086,10 @@ cmd_design_scaffold() {
     [[ "$fd" != /* ]] && fd="$repo_root/$fd"
     mkdir -p "$fd"
 
-    local target="$fd/$doc_name" created="false" tpl
+    local target="$fd/$doc_name" created="false" tpl migrated="false"
+    if [ ! -f "$target" ] && [ -n "$legacy_name" ] && [ -f "$fd/$legacy_name" ]; then
+        mv "$fd/$legacy_name" "$target"; migrated="true"
+    fi
     if [ -f "$target" ]; then
         created="false"
     else
@@ -2954,8 +4106,8 @@ cmd_design_scaffold() {
     local override_active="false"
     [ -f "$repo_root/.appweaver/templates/overrides/${template_arg}.md" ] && override_active="true"
     local template_source; template_source=$(resolve_template "$template_arg" "$repo_root") || true
-    printf '{"feature_dir":"%s","design_doc":"%s","lane":"%s","created":%s,"override_active":%s,"template":"%s","template_source":"%s"}\n' \
-        "$(json_escape "$fd")" "$(json_escape "$target")" "$(json_escape "$lane_arg")" "$created" "$override_active" \
+    printf '{"feature_dir":"%s","design_doc":"%s","lane":"%s","created":%s,"migrated":%s,"override_active":%s,"template":"%s","template_source":"%s"}\n' \
+        "$(json_escape "$fd")" "$(json_escape "$target")" "$(json_escape "$lane_arg")" "$created" "$migrated" "$override_active" \
         "$(json_escape "$template_arg")" "$(json_escape "${template_source:-}")"
 }
 
@@ -3137,6 +4289,189 @@ print(json.dumps({
         "$scoped" "$matched" "$fence_green" "$(json_escape "$cmd")" "$(json_escape "$t")"
 }
 
+# ─────────────────────────────── test-diff ─────────────────────────────────
+# The TECHNICAL-STORY ORACLE. A technical story delivers no requirement, so there is no
+# FR- to trace it to and the existing test suite is the only thing that can say whether
+# it changed behaviour: a test that HAD to be edited means behaviour moved, and the work
+# was a functional story citing a requirement. This reports the suite's diff against a
+# baseline and lets the caller decide — it never judges.
+#
+# Read-only, always exits 0, and reports `checked` so an unreadable oracle (no git) is
+# distinguishable from a clean one. A gate that treats "could not look" as "nothing
+# found" is the exact false green the kit refuses everywhere else.
+cmd_test_diff() {
+    local fd_arg="" base=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --base) base="$2"; shift 2 ;;
+            --help|-h) echo "test-diff [--feature-dir <path>] [--base <git ref>]"; return 0 ;;
+            *) echo "test-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") || fd=""
+    AW_ROOT="$repo_root" AW_FD="$fd" AW_BASE="$base" python3 - <<'PY'
+import json, os, re, subprocess
+root = os.environ.get("AW_ROOT") or "."
+fd   = os.environ.get("AW_FD", "")
+want = (os.environ.get("AW_BASE") or "").strip()
+agg  = os.path.basename(fd.rstrip("/\\"))
+
+def git(*a):
+    """A git read that never raises. A working copy this command cannot interrogate is a
+    FACT TO REPORT — the caller decides what an unreadable oracle means — never a crash
+    that takes the gate down with it."""
+    try:
+        p = subprocess.run(["git", "-C", root] + list(a), capture_output=True, text=True)
+    except Exception:
+        return 1, ""
+    return p.returncode, (p.stdout or "").strip()
+
+DIR_RE = re.compile(r'(^|/)(tests?|specs?|__tests__|testing|test-suite)(/|$)', re.I)
+
+# The kit's OWN trees, which hold documents and configuration and never tests. The spec
+# tree is derived rather than assumed: `specs/` matches the RSpec directory convention
+# exactly, so without this every requirement document — and this gate's own verdict file,
+# written before the diff is taken — counted as a modified test.
+SKIP = [".appweaver/"]
+if fd:
+    _rel = os.path.relpath(fd, root).replace("\\", "/")
+    SKIP.append((_rel.rsplit("/", 1)[0] if "/" in _rel else _rel).rstrip("/") + "/")
+
+def is_test(path):
+    """A path is a TEST when a directory on it says so, or its own filename does — the
+    four conventions every shipped stack uses between them: a tests/ directory, a
+    Name.Tests.cs / NameTest.java suffix, a test_name.py / name_test.go affix, and a
+    name.test.ts / name.spec.ts infix. Deliberately GENEROUS: over-calling a file a test
+    costs a louder message, under-calling one costs a technical story that changed
+    behaviour and passed its own oracle."""
+    p = path.replace("\\", "/")
+    if any(p.startswith(s) for s in SKIP):
+        return False
+    stem, ext = os.path.splitext(os.path.basename(p))
+    # Prose is never a test, wherever it sits. A tests/ directory holds its own README
+    # and a docs tree holds files named for testing; counting either would fail a
+    # technical story over a paragraph.
+    if ext.lower() in (".md", ".markdown", ".txt", ".rst", ".adoc"):
+        return False
+    if DIR_RE.search(os.path.dirname(p)):
+        return True
+    stem = stem.lower()
+    if stem.startswith(("test", "spec")) or stem.endswith(("test", "tests", "spec", "specs")):
+        return True
+    return any(k in stem for k in (".test", ".spec", "_test", "_spec", "-test", "-spec"))
+
+out = {"ok": True, "aggregate": agg, "git": False, "checked": False,
+       "base": "", "base_ref": "", "base_kind": "none", "files_changed": 0,
+       "tests_changed": [], "tests_changed_csv": "", "tests_changed_count": 0,
+       "tests_deleted": [], "tests_deleted_csv": "",
+       "tests_added": [], "tests_added_csv": "", "tests_added_count": 0,
+       "slice_tests_changed": [], "slice_tests_changed_csv": "", "slice_tests_changed_count": 0,
+       "any_test_changed": False, "clean": True, "oracle": "clean",
+       "note": "", "digest": ""}
+
+if git("rev-parse", "--is-inside-work-tree")[1] != "true":
+    out["oracle"] = "unverified"
+    out["note"] = ("Not a git working copy, so the test suite's history cannot be read. The "
+                   "unchanged-suite oracle is UNVERIFIED for this run — not passed.")
+    out["digest"] = out["note"]
+    print(json.dumps(out)); raise SystemExit(0)
+out["git"] = out["checked"] = True
+
+# WHICH BASELINE. An explicit --base wins. Otherwise the fork point from the integration
+# branch, which is what a story's work sits on top of; falling back to HEAD, which sees
+# the working tree alone. The kind is reported because it changes what the answer MEANS:
+# a `head` baseline cannot see a test modified in a commit this branch already made.
+head = git("rev-parse", "HEAD")[1]
+if want and git("rev-parse", "--verify", want + "^{commit}")[0] == 0:
+    out["base"], out["base_ref"], out["base_kind"] = git("rev-parse", want)[1], want, "given"
+if not out["base"]:
+    cands = []
+    rc, ref = git("symbolic-ref", "--quiet", "refs/remotes/origin/HEAD")
+    if rc == 0 and ref:
+        cands.append(ref.split("refs/remotes/", 1)[-1])
+    cands += ["origin/main", "origin/master", "main", "master"]
+    seen = set()
+    for c in cands:
+        if c in seen:
+            continue
+        seen.add(c)
+        if git("rev-parse", "--verify", c + "^{commit}")[0] != 0:
+            continue
+        rc, mb = git("merge-base", "HEAD", c)
+        if rc != 0 or not mb:
+            continue
+        out["base"], out["base_ref"] = mb, c
+        out["base_kind"] = "head" if mb == head else "merge-base"
+        break
+if not out["base"]:
+    out["base"], out["base_kind"] = head or "HEAD", "head"
+
+rc, diff = git("diff", "--name-status", "--find-renames", out["base"])
+changed, added, deleted, files = [], [], [], 0
+for line in diff.splitlines():
+    parts = line.split("\t")
+    if len(parts) < 2:
+        continue
+    code, paths = parts[0].strip(), parts[1:]
+    files += 1
+    hits = [p for p in paths if is_test(p)]
+    if not hits:
+        continue
+    p = hits[-1]
+    if code.startswith("A") or code.startswith("C"):
+        # A NEW test is not a changed one. A refactor that adds characterisation tests is
+        # exactly the work a technical story exists to do.
+        added.append(p)
+    elif code.startswith("R"):
+        # A pure rename moves a test without changing what it asserts; anything less than
+        # a 100% match carries an edit inside it.
+        (added if code == "R100" else changed).append(p)
+    elif code.startswith("D"):
+        deleted.append(p); changed.append(p)
+    else:
+        changed.append(p)
+
+# Untracked files are ADDITIONS the diff cannot see — reported as such so a new test
+# written in the working tree is not mistaken for a missing one.
+for p in git("ls-files", "--others", "--exclude-standard")[1].splitlines():
+    p = p.strip()
+    if p and is_test(p) and p not in added:
+        added.append(p); files += 1
+
+changed = sorted(set(changed)); added = sorted(set(added)); deleted = sorted(set(deleted))
+low = agg.lower()
+slice_changed = [p for p in changed if low and low in p.lower()]
+out.update(files_changed=files,
+           tests_changed=changed, tests_changed_csv=", ".join(changed),
+           tests_changed_count=len(changed),
+           tests_deleted=deleted, tests_deleted_csv=", ".join(deleted),
+           tests_added=added, tests_added_csv=", ".join(added), tests_added_count=len(added),
+           slice_tests_changed=slice_changed, slice_tests_changed_csv=", ".join(slice_changed),
+           slice_tests_changed_count=len(slice_changed),
+           any_test_changed=bool(changed), clean=not changed,
+           # The DIFF's state in one word — clean | changed | unverified — so a caller can
+           # branch on it without recombining a boolean with a "could I even look" flag.
+           # It says what the suite did, never what that means for a story.
+           oracle="changed" if changed else "clean")
+
+kindnote = {"given": "the ref given on the command line",
+            "merge-base": "the fork point from %s — every commit this branch added is in view" % out["base_ref"],
+            "head": "HEAD — only uncommitted work is in view, so a test modified in a commit "
+                    "already made on this branch is NOT counted"}[out["base_kind"]]
+lines = ["Test-suite diff against %s (%s): %s" % (out["base"][:12], out["base_kind"], kindnote),
+         "  files changed: %d" % files,
+         "  tests MODIFIED or DELETED (%d): %s" % (len(changed), ", ".join(changed) or "none"),
+         "  tests ADDED (%d): %s" % (len(added), ", ".join(added) or "none")]
+if slice_changed:
+    lines.append("  of those, on this aggregate (%s): %s" % (agg, ", ".join(slice_changed)))
+out["note"] = kindnote
+out["digest"] = "\n".join(lines)
+print(json.dumps(out))
+PY
+}
+
 cmd_run_migrate() {
     while [ $# -gt 0 ]; do
         case "$1" in
@@ -3374,6 +4709,701 @@ print(json.dumps({"ok": True, "version": ver, "stamped": stamped,
 PY
 }
 
+
+# ─────────────────────────── plan-check / plan-stamp ────────────────────────
+# The plan documents' derivation tracking. Each plan doc (backend-plan.md /
+# frontend-plan.md) derives from ONE spec version and carries its OWN track file
+# beside the spec — .aw-plan-track.backend-plan.json / .aw-plan-track.frontend-plan.json
+# — recording {spec_version, sha256}, so the two lanes' stamps never share a write.
+# plan-check reads the record back against the spec's Change History ledger;
+# plan-stamp is the only writer.
+# Both always exit 0 with an ok/state field — the workflow's verify_context owns
+# the stop (the lane-verify convention).
+cmd_plan_check() {
+    local fd_arg="" doc=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --doc) doc="$2"; shift 2 ;;
+            --help|-h) echo "plan-check --doc <path> [--feature-dir <path>]"; return 0 ;;
+            *) echo "plan-check: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$doc" ] || { echo "plan-check: --doc required" >&2; return 1; }
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "plan-check: no feature set and no --feature-dir" >&2; return 1; }
+    AW_DOC="$doc" AW_FD="$fd" python3 - <<'PY'
+import json, os, re, sys, hashlib
+doc = os.environ["AW_DOC"]; fd = os.environ["AW_FD"]
+spec = os.path.join(fd, "spec.md")
+# One track file per plan document (.aw-plan-track.backend-plan.json /
+# .aw-plan-track.frontend-plan.json) — parallel lane stamps never contend on a shared file.
+stem = os.path.splitext(os.path.basename(doc))[0]
+track_path = os.path.join(fd, ".aw-plan-track.%s.json" % stem)
+def vtuple(v):
+    try: return tuple(int(x) for x in v.lstrip("vV").split("."))
+    except Exception: return (0,)
+out = {"doc": doc, "doc_exists": os.path.isfile(doc), "state": "", "derived_version": "",
+       "current_version": "", "changed_csv": "", "changed_summary": "", "body_changed": False}
+# Current version = the widest of the ledger's rows and the **Version** header — the
+# same widest-wins rule ledger-append uses, so a hand-moved header cannot hide a row.
+rows = []; cur = ""; idcol = -1
+if os.path.isfile(spec):
+    text = open(spec, encoding="utf-8", errors="replace").read()
+    m = re.search(r'^##\s+Change History\s*$', text, re.M)
+    if m:
+        for line in text[m.end():].splitlines():
+            if idcol < 0 and line.lstrip().startswith("|") and "requirements changed" in line.lower():
+                hdr = [c.strip().lower() for c in line.strip().strip("|").split("|")]
+                idcol = next((i for i, c in enumerate(hdr) if "requirements changed" in c), -1)
+            rm = re.match(r'^\|\s*(v\d+(?:\.\d+)?)\s*\|', line)
+            if rm: rows.append((rm.group(1), line))
+    hv = re.search(r'^\*\*Version\*\*:\s*(v[\d.]+)', text, re.M)
+    cands = [r[0] for r in rows] + ([hv.group(1)] if hv else [])
+    if cands: cur = max(cands, key=vtuple)
+out["current_version"] = cur
+if not out["doc_exists"]:
+    out["state"] = "fresh"; print(json.dumps(out)); sys.exit(0)
+try: track = json.load(open(track_path, encoding="utf-8"))
+except Exception: track = {}
+entry = track.get(os.path.basename(doc))
+if not entry:
+    # A document with no derivation record — a migrated legacy master, or a baseline
+    # lost by hand. There is no stamp to diff against, so the caller reconciles the
+    # WHOLE document once and plan-stamp baselines it.
+    out["state"] = "untracked"; print(json.dumps(out)); sys.exit(0)
+derived = entry.get("spec_version", "")
+out["derived_version"] = derived
+body = open(doc, encoding="utf-8", errors="replace").read()
+out["body_changed"] = hashlib.sha256(body.encode("utf-8")).hexdigest() != entry.get("sha256", "")
+moved = [r for r in rows if vtuple(r[0]) > vtuple(derived)]
+# Scrape ONLY the ledger's "Requirements changed" cell when it names one. The
+# Stories cell holds ids of the form <Aggregate>-nnn, which read as requirement ids
+# whenever the aggregate is spelled in caps (EDI-001, HR-002) — those would arrive
+# as requirements for the plan to conform, and there is no such requirement.
+def _scope(line):
+    if idcol >= 0:
+        cells = [c.strip() for c in line.strip().strip("|").split("|")]
+        if idcol < len(cells): return cells[idcol]
+    return line
+ids = sorted({i for _v, line in moved for i in re.findall(r'[A-Z]{2}-\d+', _scope(line))})
+out["changed_csv"] = ", ".join(ids)
+out["changed_summary"] = "  //  ".join(line.strip() for _v, line in moved)
+behind = bool(moved) or bool(cur and vtuple(cur) > vtuple(derived))
+if out["body_changed"] and behind: out["state"] = "edited_behind"
+elif out["body_changed"]:          out["state"] = "edited"
+elif behind:                       out["state"] = "behind"
+else:                              out["state"] = "clean"
+print(json.dumps(out))
+PY
+}
+
+cmd_plan_stamp() {
+    local fd_arg="" doc="" ids="" note="" no_row="false"
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --doc) doc="$2"; shift 2 ;;
+            --ids) ids="$2"; shift 2 ;;
+            --note) note="$2"; shift 2 ;;
+            --no-row) no_row="true"; shift ;;
+            --help|-h) echo "plan-stamp --doc <path> [--feature-dir <path>] [--ids <csv>] [--note <text>] [--no-row]"; return 0 ;;
+            *) echo "plan-stamp: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$doc" ] || { echo "plan-stamp: --doc required" >&2; return 1; }
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "plan-stamp: no feature set and no --feature-dir" >&2; return 1; }
+    AW_DOC="$doc" AW_FD="$fd" AW_IDS="$ids" AW_NOTE="$note" AW_NOROW="$no_row" python3 - <<'PY'
+import json, os, re, sys, hashlib, datetime
+doc = os.environ["AW_DOC"]; fd = os.environ["AW_FD"]
+ids = os.environ.get("AW_IDS", "").strip(); note = os.environ.get("AW_NOTE", "").strip()
+no_row = os.environ.get("AW_NOROW", "false") == "true"
+spec = os.path.join(fd, "spec.md")
+# One track file per plan document (.aw-plan-track.backend-plan.json /
+# .aw-plan-track.frontend-plan.json) — parallel lane stamps never contend on a shared file.
+stem = os.path.splitext(os.path.basename(doc))[0]
+track_path = os.path.join(fd, ".aw-plan-track.%s.json" % stem)
+def vtuple(v):
+    try: return tuple(int(x) for x in v.lstrip("vV").split("."))
+    except Exception: return (0,)
+if not os.path.isfile(doc):
+    print(json.dumps({"ok": False, "error": "plan document %s does not exist" % doc, "version": ""})); sys.exit(0)
+cur = ""
+if os.path.isfile(spec):
+    st = open(spec, encoding="utf-8", errors="replace").read()
+    m = re.search(r'^##\s+Change History\s*$', st, re.M)
+    rows = re.findall(r'^\|\s*(v\d+(?:\.\d+)?)\s*\|', st[m.end():] if m else "", re.M)
+    hv = re.search(r'^\*\*Version\*\*:\s*(v[\d.]+)', st, re.M)
+    cands = rows + ([hv.group(1)] if hv else [])
+    if cands: cur = max(cands, key=vtuple)
+text = open(doc, encoding="utf-8", errors="replace").read()
+# The ledger-survival fence: a plan whose update dropped the Change History section is
+# NOT baselined — a lost ledger silently baselined over could never be noticed again.
+hist = re.search(r'^##+\s*(?:\d+\.\s*)?Change History\s*$', text, re.M)
+if not hist:
+    print(json.dumps({"ok": False, "version": cur,
+        "error": "the plan document has no 'Change History' section — the write dropped the ledger; nothing was baselined"}))
+    sys.exit(0)
+warnings = []
+if not re.search(r'^##+.*Assumptions', text, re.M):
+    warnings.append("no 'Assumptions' section found")
+if not re.search(r'^##+.*(Workarounds|Deviations)', text, re.M):
+    warnings.append("no 'Workarounds/Deviations' section found")
+row_txt = ""
+if not no_row:
+    # Bounded to the Change History section; the row's cell count follows the section's
+    # own table so the append fits the greenfield, UI and onboard-generated shapes alike.
+    lines = text.split("\n")
+    hline = text[:hist.start()].count("\n")
+    end = len(lines)
+    for i in range(hline + 1, len(lines)):
+        if re.match(r'^##', lines[i]): end = i; break
+    tbl = [i for i in range(hline + 1, end) if lines[i].lstrip().startswith("|")]
+    ncells = 5
+    if tbl: ncells = max(3, lines[tbl[0]].strip().strip("|").count("|") + 1)
+    change = note or ("Conformed to spec %s" % (cur or "(unversioned)"))
+    if ids: change = "%s — %s" % (change, ids)
+    change = change.replace("|", "/").replace("\n", " ")
+    cells = [cur or "v?", datetime.date.today().isoformat(), change] + ["—"] * (ncells - 3)
+    row_txt = "| " + " | ".join(cells[:ncells]) + " |"
+    lines.insert((tbl[-1] + 1) if tbl else end, row_txt)
+    text = "\n".join(lines)
+if cur:
+    text = re.sub(r'^(\*\*Version\*\*:\s*)v[\d.]+', r'\g<1>' + cur, text, count=1, flags=re.M)
+open(doc, "w", encoding="utf-8").write(text)
+try: track = json.load(open(track_path, encoding="utf-8"))
+except Exception: track = {}
+track[os.path.basename(doc)] = {
+    "spec_version": cur,
+    "sha256": hashlib.sha256(text.encode("utf-8")).hexdigest(),
+    "updated": datetime.datetime.now().isoformat(timespec="seconds")}
+open(track_path, "w", encoding="utf-8").write(json.dumps(track, indent=2) + "\n")
+print(json.dumps({"ok": True, "version": cur, "row": row_txt, "warnings": warnings}))
+PY
+}
+
+
+# ───────────────────────────────── gate-result ──────────────────────────────
+# The machine-readable verdict every analyze gate writes beside its markdown
+# report. CI cannot branch on prose, and a verdict is exactly the kind of dated,
+# derived record the model must never write — so the script writes it.
+#
+# Shared by design: analyze-design writes one per feature, and analyze-slice /
+# analyze-code will write one per story and per run. The CORE keys are fixed
+# (gate, status, feature, spec_version, story, gap_count, gap_refs, report,
+# generated_at) so a pipeline can read any gate's result with one expression;
+# everything gate-specific arrives through repeatable --field k=v and lands under
+# "fields", where it cannot destabilise that core.
+#
+# NOTE the returned `ok` means THE FILE WAS WRITTEN. The pass/fail verdict is
+# `status` — binding a workflow gate to `ok` would pass on every run.
+cmd_gate_result() {
+    local fd_arg="" gate="" ok="" version="" story="" report="" out="" gaps="" refs="" note="" fields=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --gate) gate="$2"; shift 2 ;;
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --ok) ok="$2"; shift 2 ;;
+            --spec-version) version="$2"; shift 2 ;;
+            --story) story="$2"; shift 2 ;;
+            --report) report="$2"; shift 2 ;;
+            --out) out="$2"; shift 2 ;;
+            --gap-count) gaps="$2"; shift 2 ;;
+            --gap-refs) refs="$2"; shift 2 ;;
+            --note) note="$2"; shift 2 ;;
+            --field) fields="${fields}$2"$'\n'; shift 2 ;;
+            --help|-h) echo "gate-result --gate <name> --ok <true|false> [--feature-dir <p>] [--spec-version <v>] [--story <id>] [--report <path>] [--out <path>] [--gap-count <n>] [--gap-refs <csv>] [--note <text>] [--field k=v]..."; return 0 ;;
+            *) echo "gate-result: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$gate" ] || { echo "gate-result: --gate required" >&2; return 1; }
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "gate-result: no feature set and no --feature-dir" >&2; return 1; }
+    AW_GATE="$gate" AW_FD="$fd" AW_OK="$ok" AW_VERSION="$version" AW_STORY="$story" \
+    AW_REPORT="$report" AW_OUT="$out" AW_GAPS="$gaps" AW_REFS="$refs" AW_NOTE="$note" \
+    AW_FIELDS="$fields" python3 - <<'PY'
+import json, os, sys, datetime
+gate   = (os.environ.get("AW_GATE", "") or "").strip() or "gate"
+fd     = os.environ.get("AW_FD", "")
+report = (os.environ.get("AW_REPORT", "") or "").strip()
+out    = (os.environ.get("AW_OUT", "") or "").strip()
+# "pass" only on an explicit affirmative. An absent or unreadable verdict is a FAIL,
+# because a result that defaults green turns every broken run into a passing one.
+ok = (os.environ.get("AW_OK", "") or "").strip().lower() in ("true", "1", "yes", "pass", "ok")
+# Written BESIDE the markdown report and named after it, so a job holding either path
+# holds the other. --out overrides; with no report named at all it falls back to a
+# dotfile in the feature directory under the gate's own name.
+if not out:
+    out = (os.path.splitext(report)[0] + ".json") if report else os.path.join(fd, ".aw-gate-%s.json" % gate)
+try: gap_count = int((os.environ.get("AW_GAPS", "") or "").strip() or 0)
+except ValueError: gap_count = 0
+refs = [r.strip() for r in (os.environ.get("AW_REFS", "") or "").replace(";", ",").split(",") if r.strip()]
+# A fail reporting zero findings reads as green to anything that sums the number
+# rather than reading the status, so a red verdict always carries at least one.
+if not ok and gap_count < 1: gap_count = max(1, len(refs))
+# --field k=v, repeatable, arriving newline-separated. Keeps the CORE schema below
+# fixed for every gate while each one carries its own detail underneath.
+fields = {}
+for line in (os.environ.get("AW_FIELDS", "") or "").splitlines():
+    k, sep, v = line.partition("=")
+    if sep and k.strip(): fields[k.strip()] = v.strip()
+res = {"gate": gate,
+       "status": "pass" if ok else "fail",
+       "feature": os.path.basename(fd.rstrip("/\\")),
+       "feature_dir": fd,
+       "spec_version": (os.environ.get("AW_VERSION", "") or "").strip(),
+       "story": (os.environ.get("AW_STORY", "") or "").strip(),
+       "gap_count": gap_count,
+       "gap_refs": refs,
+       "report": report,
+       "note": (os.environ.get("AW_NOTE", "") or "").strip(),
+       "fields": fields,
+       "generated_at": datetime.datetime.now().isoformat(timespec="seconds")}
+d = os.path.dirname(out)
+if d and not os.path.isdir(d): os.makedirs(d, exist_ok=True)
+open(out, "w", encoding="utf-8").write(json.dumps(res, indent=2) + "\n")
+print(json.dumps({"ok": True, "result_file": out, "status": res["status"], "gap_count": gap_count}))
+PY
+}
+
+# ─────────────── story-plan-check / story-plan-doc / log-append ───────────────
+# The per-story execution design ("story design") — SHORT-LIVED scaffolding, ONE
+# DOCUMENT PER LANE beside the story: stories/<ID>/story-backend-plan.md and
+# stories/<ID>/story-frontend-plan.md. Every /appweaver story-plan run
+# APPENDS a dated "## Design pass N" section; the LATEST pass wins and nothing is
+# edited in place, so a manual edit to an earlier pass survives a re-run. The
+# document's identity is positional (its directory): no story id appears in its
+# text. Writing into stories/<ID>/ is what flips the story IN-FLIGHT for
+# sync-stories' follow-on rule — the same isdir test story-spec's projection used
+# to trip.
+#
+# story-plan-check resolves WHICH story (an explicit --story, an id found in the
+# free-text input, or the open backlog for an ask), and reports everything the
+# workflow gates on: status, cited ids, the Constraints section's bound ids, ledger
+# rows above the story's stamp (staleness), doc/pass state and the feature's
+# append-only log paths. Always exits 0 with ok/flag fields — the workflow's
+# verify_context owns every stop (the lane-verify convention).
+#
+# story-plan-doc is the ONLY writer of either lane's design: --lane picks the file,
+# and it scaffolds the shell (frontmatter + contract comment) on first use, appends
+# the authored pass under a SCRIPT-written header (the model writes no pass number,
+# date or version), stamps the frontmatter and removes the temp pass file. Pass
+# numbers are per lane. A pre-split story-plan.md is reported by story-plan-check as
+# legacy_doc and touched by nothing.
+#
+# log-append owns the feature's two append-only logs: interfaces.md (IF-nnn — the
+# FE/BE contract anchor; BE design appends status:proposed, story close verifies
+# against the as-built and flips to live) and adr.md (ADR-nnn — ratified decisions).
+# The script assigns ids, dates and status; entries are never edited afterwards,
+# only superseded by later entries naming `supersedes:`.
+cmd_story_plan_check() {
+    local fd_arg="" input="" story=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir) fd_arg="$2"; shift 2 ;;
+            --input) input="$2"; shift 2 ;;
+            --story) story="$2"; shift 2 ;;
+            --help|-h) echo "story-plan-check [--story <id>] [--input <free text>] [--feature-dir <path>]"; return 0 ;;
+            *) echo "story-plan-check: 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-plan-check: no feature set and no --feature-dir" >&2; return 1; }
+    AW_FD="$fd" AW_INPUT="$input" AW_STORY="$story" python3 - <<'PY'
+import json, os, re, sys
+fd = os.environ["AW_FD"]
+sdir = os.path.join(fd, "stories")
+spec = os.path.join(fd, "spec.md")
+
+def parse_fm(text):
+    """Frontmatter as a flat dict — inline and block-list values both fold to the
+    inline shape (same reader story-refs uses, for the same reason)."""
+    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 vtuple(v):
+    try: return tuple(int(x) for x in v.lstrip("vV").split("."))
+    except Exception: return (0,)
+
+# ---- the backlog ------------------------------------------------------------
+stories = []
+if os.path.isdir(sdir):
+    for name in sorted(os.listdir(sdir)):
+        # stories.md is the GENERATED index beside the stories, not a story
+        if not name.endswith(".md") or name == "stories.md": continue
+        p = os.path.join(sdir, name)
+        if not os.path.isfile(p): continue
+        text = open(p, encoding="utf-8", errors="replace").read()
+        fm = parse_fm(text)
+        sid = fm.get("id") or name[:-3]
+        stories.append({"id": sid, "file_id": name[:-3],
+                        "status": (fm.get("status") or "open").strip().lower(),
+                        "type": (fm.get("type") or "functional").strip().lower(),
+                        "title": (fm.get("title") or "").strip().strip("[]"),
+                        "spec_version": (fm.get("spec_version") or "").strip(),
+                        "cites": re.findall(r'\b(?:FR|BR)-\d+', fm.get("exercises", "")),
+                        "path": p, "text": text})
+open_stories = [s for s in stories if s["status"] == "open"]
+open_ids = [s["id"] for s in open_stories]
+digest = "\n".join("  %-16s %s%s" % (s["id"], s["title"] or "(untitled)",
+                                     ("  cites " + ", ".join(s["cites"])) if s["cites"] else "")
+                   for s in open_stories) or "  (no open stories)"
+
+# ---- which story ------------------------------------------------------------
+want = (os.environ.get("AW_STORY") or "").strip()
+free = os.environ.get("AW_INPUT") or ""
+target, reason = None, ""
+if want:
+    hit = [s for s in stories if s["id"] == want or s["file_id"] == want]
+    target = hit[0] if hit else None
+    if not target: reason = "not-found"
+else:
+    # every known story id appearing as a whole token in the free text; one match
+    # resolves, several is a question, none is a question
+    named = [s for s in stories
+             if re.search(r'(?<![\w-])' + re.escape(s["id"]) + r'(?![\w-])', free)]
+    if len(named) == 1: target = named[0]
+    else: reason = "ambiguous" if named else "none-given"
+
+out = {"ok": True, "stories_dir": sdir, "stories_exist": os.path.isdir(sdir),
+       "open_count": len(open_stories), "any_open": bool(open_stories),
+       "open_ids": open_ids, "open_ids_csv": ", ".join(open_ids), "digest": digest,
+       "resolved": bool(target), "needs_pick": not target, "pick_reason": reason,
+       "story": "", "story_path": "", "story_status": "", "story_open": False,
+       "story_type": "", "is_technical": False,
+       "status_msg": "", "story_title": "", "exercises_csv": "", "constraints_csv": "",
+       "story_spec_version": "", "current_version": "", "stale_csv": "", "stale_note": "",
+       "story_dir": "", "if_tmp": "", "legacy_doc": "", "legacy_doc_exists": False,
+       "be_doc_path": "", "be_doc_exists": False, "be_next_pass": 1, "be_pass_tmp": "",
+       "be_last_pass": 0, "be_doc_spec_version": "", "be_doc_stale": False,
+       "fe_doc_path": "", "fe_doc_exists": False, "fe_next_pass": 1, "fe_pass_tmp": "",
+       "fe_last_pass": 0, "fe_doc_spec_version": "", "fe_doc_stale": False,
+       "adr_path": os.path.join(fd, "adr.md"), "adr_exists": os.path.isfile(os.path.join(fd, "adr.md")),
+       "if_path": os.path.join(fd, "interfaces.md"), "if_exists": os.path.isfile(os.path.join(fd, "interfaces.md")),
+       "spec_exists": os.path.isfile(spec)}
+
+# ---- the ledger (widest-wins current version, same rule ledger-append uses) --
+rows, cur = [], ""
+if os.path.isfile(spec):
+    stext = open(spec, encoding="utf-8", errors="replace").read()
+    m = re.search(r'^##\s+Change History\s*$', stext, re.M)
+    if m:
+        for line in stext[m.end():].splitlines():
+            rm = re.match(r'^\|\s*(v\d+(?:\.\d+)?)\s*\|', line)
+            if rm: rows.append((rm.group(1), line))
+    hv = re.search(r'^\*\*Version\*\*:\s*(v[\d.]+)', stext, re.M)
+    cands = [r[0] for r in rows] + ([hv.group(1)] if hv else [])
+    if cands: cur = max(cands, key=vtuple)
+out["current_version"] = cur
+
+if not target:
+    print(json.dumps(out)); sys.exit(0)
+
+# ---- the resolved story -----------------------------------------------------
+status = target["status"]
+out.update(story=target["id"], story_path=target["path"], story_status=status,
+           story_open=(status == "open"), story_title=target["title"],
+           story_type=target["type"], is_technical=(target["type"] == "technical"),
+           exercises_csv=", ".join(target["cites"]),
+           story_spec_version=target["spec_version"])
+if status != "open":
+    verb = {"closed": "was closed — its plan is history. Remaining work needs its own story "
+                      "(sync-stories mints a follow-on when the spec moves)",
+            "cancelled": "was cancelled — cancelled work is not planned; open a new story if the need returns",
+            "draft": "is a draft proposal — run /appweaver sync-spec to merge it into the contract first; "
+                     "story-plan designs only against merged requirements"}
+    out["status_msg"] = "Story %s %s." % (
+        target["id"], verb.get(status, "has status '%s', not open" % status))
+
+# bound constraint ids come from the story BODY's ## Constraints section (they are
+# barred from exercises: by design — met, not delivered)
+cm = re.search(r'^##\s+Constraints\s*$(.*?)(?=^##\s|\Z)', target["text"], re.M | re.S)
+cons = sorted(set(re.findall(r'\b(?:CN|DC|IC|UX)-\d+', cm.group(1)))) if cm else []
+out["constraints_csv"] = ", ".join(cons)
+
+# staleness: ledger rows ABOVE the story's stamp naming an id the story carries —
+# exercises: AND the Constraints section, so a moved bound is announced too
+sv = target["spec_version"]
+if sv:
+    carried = set(target["cites"]) | set(cons)
+    moved = [r for r in rows if vtuple(r[0]) > vtuple(sv)]
+    stale = sorted({i for _v, l in moved for i in re.findall(r'[A-Z]{2}-\d+', l) if i in carried})
+    out["stale_csv"] = ", ".join(stale)
+    if stale:
+        out["stale_note"] = (
+            "CAUTION: the spec moved above this story's stamp (%s -> %s) on ids this story "
+            "carries: %s. Design against the CURRENT spec text, record the divergence under "
+            "Risks, and consider /appweaver sync-stories to bring the backlog back in step."
+            % (sv, cur or "?", ", ".join(stale)))
+
+# doc / pass state + the temp paths the workflow writes through. ONE DOCUMENT PER
+# LANE: the service design and the UI design are authored by different steps, under
+# different rule sets, from different code, and are read by different implement
+# commands — folded into one file, every one of those becomes a section boundary the
+# next reader has to trust. Pass numbers are per file, so a run that designs only the
+# backend leaves the frontend's count exactly where it was.
+#
+# legacy_doc is the pre-split story-plan.md. It is REPORTED, never read and never
+# written: a design nobody consumes must not sit silently beside two that are.
+stdir = os.path.join(sdir, target["id"])
+legacy = os.path.join(stdir, "story-plan.md")
+out.update(story_dir=stdir, if_tmp=os.path.join(stdir, ".if-entries.tmp.md"),
+           legacy_doc=legacy, legacy_doc_exists=os.path.isfile(legacy))
+for lane, stem in (("be", "backend"), ("fe", "frontend")):
+    doc = os.path.join(stdir, "story-%s-plan.md" % stem)
+    out[lane + "_doc_path"] = doc
+    out[lane + "_doc_exists"] = os.path.isfile(doc)
+    out[lane + "_pass_tmp"] = os.path.join(stdir, ".%s-pass.tmp.md" % stem)
+    if out[lane + "_doc_exists"]:
+        d = open(doc, encoding="utf-8", errors="replace").read()
+        nums = [int(n) for n in re.findall(r'^##\s+Design pass\s+(\d+)', d, re.M)]
+        out[lane + "_next_pass"] = (max(nums) + 1) if nums else 1
+        # What implement needs on top of the path: WHICH pass it builds from (the last
+        # one — earlier passes are superseded history) and the spec version that pass was
+        # designed against. A design behind the current spec is ANNOUNCED at implement,
+        # never refused: the story is legitimately in flight, and the spec may well have
+        # moved on ids this story does not carry. stale_csv is the sharper signal and it
+        # is already computed above.
+        out[lane + "_last_pass"] = max(nums) if nums else 0
+        dv = (parse_fm(d).get("spec_version") or "").strip().strip('"')
+        out[lane + "_doc_spec_version"] = dv
+        out[lane + "_doc_stale"] = bool(dv and cur and vtuple(dv) < vtuple(cur))
+print(json.dumps(out))
+PY
+}
+
+cmd_story_plan_doc() {
+    local fd_arg="" story="" pass_file="" spec_version="" lane="backend"
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir)   fd_arg="$2"; shift 2 ;;
+            --story)         story="$2"; shift 2 ;;
+            --lane)          lane="$2"; shift 2 ;;
+            --pass-file)     pass_file="$2"; shift 2 ;;
+            --spec-version)  spec_version="$2"; shift 2 ;;
+            --help|-h) echo "story-plan-doc --story <id> --pass-file <path> [--lane backend|frontend] [--spec-version <v>] [--feature-dir <path>]"; return 0 ;;
+            *) echo "story-plan-doc: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$story" ] || { echo "story-plan-doc: --story is required" >&2; return 1; }
+    [ -n "$pass_file" ] || { echo "story-plan-doc: --pass-file is required" >&2; return 1; }
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "story-plan-doc: no feature set and no --feature-dir" >&2; return 1; }
+    AW_FD="$fd" AW_STORY="$story" AW_LANE="$lane" AW_PASS="$pass_file" AW_VER="$spec_version" python3 - <<'PY'
+import json, os, re, sys, datetime
+fd = os.environ["AW_FD"]; story = os.environ["AW_STORY"].strip()
+pf = os.environ["AW_PASS"]; ver = (os.environ.get("AW_VER") or "").strip()
+lane = (os.environ.get("AW_LANE") or "backend").strip().lower()
+sdir = os.path.join(fd, "stories", story)
+doc = os.path.join(sdir, "story-%s-plan.md" % lane)
+
+def bail(msg, code=2):
+    print(json.dumps({"ok": False, "doc": doc, "error": msg}))
+    sys.stderr.write(msg + "\n"); sys.exit(code)
+
+if lane not in ("backend", "frontend"):
+    bail("story-plan-doc: --lane must be backend or frontend, not '%s'" % lane)
+if not os.path.isfile(os.path.join(fd, "stories", story + ".md")):
+    bail("story-plan-doc: no story file for '%s' — the plan lives beside a story that exists" % story)
+if not os.path.isfile(pf):
+    bail("story-plan-doc: pass file missing at %s — the authoring step wrote nothing" % pf)
+content = open(pf, encoding="utf-8", errors="replace").read().strip()
+if not content:
+    bail("story-plan-doc: the authored pass is empty — nothing appended")
+# the pass header is SCRIPT-written; strip one the model wrote anyway rather than
+# letting the doc double-number
+content = re.sub(r'^##\s+Design pass\b[^\n]*\n+', '', content, count=1)
+
+LANE_WORD = "SERVICE" if lane == "backend" else "UI"
+LANE_READER = "/appweaver implement" if lane == "backend" else "/appweaver implement-ui"
+os.makedirs(sdir, exist_ok=True)
+today = datetime.date.today().isoformat()
+created = not os.path.isfile(doc)
+if created:
+    open(doc, "w", encoding="utf-8").write("""---
+created: %s
+updated: %s
+passes: 0
+spec_version: ""
+---
+
+<!--
+  STORY DESIGN (%s LANE) — the ephemeral execution design for ONE story, read by
+  %s.
+
+  Identity is positional: the file lives in the story's directory and carries no
+  story id in its text. Every /appweaver story-plan run APPENDS a "## Design pass N"
+  section to THIS lane's file — nothing is edited in place, so a manual edit to an
+  earlier pass survives a re-run. THE LATEST PASS WINS; earlier passes are the
+  iteration history.
+
+  EDIT IT BEFORE YOU IMPLEMENT. This is the document a design is corrected in by
+  hand: change the latest pass and implement builds what you changed. Re-running
+  story-plan instead appends a fresh pass that supersedes it, so hand-edit to
+  adjust, re-run to redesign.
+
+  It is scaffolding for confirming the implementation strategy — archived with the
+  story at close, never maintained afterwards. Durable decisions do not live here:
+  the latest pass PROPOSES ADRs (ratified into the feature's adr.md at close), and
+  published-surface changes are appended to the feature's interfaces.md as proposed
+  entries at design time. spec_version below is the spec the LATEST pass was
+  designed against. The other lane's design, where the project has one, sits beside
+  this file — the two are written apart on purpose and neither restates the other.
+-->
+""" % (today, today, LANE_WORD, LANE_READER))
+text = open(doc, encoding="utf-8", errors="replace").read()
+nums = [int(n) for n in re.findall(r'^##\s+Design pass\s+(\d+)', text, re.M)]
+n = (max(nums) + 1) if nums else 1
+header = "## Design pass %d — %s%s" % (n, today, (" (spec %s)" % ver) if ver else "")
+text = text.rstrip("\n") + "\n\n" + header + "\n\n" + content + "\n"
+# frontmatter stamps — first match only, which is the frontmatter by position
+text = re.sub(r'^(updated:).*$', r'\g<1> ' + today, text, count=1, flags=re.M)
+text = re.sub(r'^(passes:).*$', r'\g<1> %d' % n, text, count=1, flags=re.M)
+if ver:
+    text = re.sub(r'^(spec_version:).*$', r'\g<1> %s' % ver, text, count=1, flags=re.M)
+open(doc, "w", encoding="utf-8").write(text)
+os.remove(pf)
+print(json.dumps({"ok": True, "doc": doc, "lane": lane, "pass": n, "created": created,
+                  "spec_version": ver, "story_dir": sdir}))
+PY
+}
+
+cmd_log_append() {
+    local fd_arg="" log="" entries_file="" status=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir)  fd_arg="$2"; shift 2 ;;
+            --log)          log="$2"; shift 2 ;;
+            --entries-file) entries_file="$2"; shift 2 ;;
+            --status)       status="$2"; shift 2 ;;
+            --help|-h) echo "log-append --log adr|interfaces --entries-file <path> [--status <s>] [--feature-dir <path>]"; return 0 ;;
+            *) echo "log-append: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    case "$log" in adr|interfaces) ;; *) echo "log-append: --log must be adr or interfaces" >&2; return 1 ;; esac
+    [ -n "$entries_file" ] || { echo "log-append: --entries-file is required" >&2; return 1; }
+    local repo_root; repo_root=$(get_repo_root)
+    local fd; fd=$(_resolve_feature_dir "$fd_arg" "$repo_root") || { echo "log-append: no feature set and no --feature-dir" >&2; return 1; }
+    AW_FD="$fd" AW_LOG="$log" AW_ENTRIES="$entries_file" AW_STATUS="$status" python3 - <<'PY'
+import json, os, re, sys, datetime
+fd = os.environ["AW_FD"]; log = os.environ["AW_LOG"]
+ef = os.environ["AW_ENTRIES"]; status = (os.environ.get("AW_STATUS") or "").strip()
+fname, prefix, default_status, title = {
+    "interfaces": ("interfaces.md", "IF", "proposed", "Interface Log"),
+    "adr":        ("adr.md", "ADR", "accepted", "Architecture Decision Log")}[log]
+status = status or default_status
+path = os.path.join(fd, fname)
+
+def bail(msg, code=2):
+    print(json.dumps({"ok": False, "log": path, "error": msg}))
+    sys.stderr.write(msg + "\n"); sys.exit(code)
+
+if not os.path.isfile(ef):
+    bail("log-append: entries file missing at %s — the authoring step wrote nothing" % ef)
+raw = open(ef, encoding="utf-8", errors="replace").read().strip()
+if not raw or raw.lower().rstrip(".") == "none":
+    os.remove(ef)
+    print(json.dumps({"ok": True, "log": path, "appended": 0, "ids_csv": "",
+                      "unknown_ids_csv": "", "bad_supersedes_csv": "", "none": True}))
+    sys.exit(0)
+
+# every entry must arrive as '## <PREFIX>-NEW — <title>': the script is the only id
+# authority, so a model-numbered entry is refused rather than trusted
+blocks = [b.strip() for b in re.split(r'(?=^##\s)', raw, flags=re.M) if b.strip()]
+bad = [b.splitlines()[0] for b in blocks
+       if not re.match(r'^##\s+%s-NEW\s+[—-]+\s+\S' % prefix, b)]
+if bad:
+    bail("log-append: every entry must start '## %s-NEW — <title>' (the script assigns "
+         "ids); got: %s" % (prefix, " | ".join(bad[:3])))
+
+SCAFFOLD = {
+    "interfaces": """<!--
+  INTERFACE LOG — this feature's published-surface contract. APPEND-ONLY.
+
+  WHO WRITES: /appweaver plan publishes this feature's surface whenever it authors or
+  conforms backend-plan.md; a BE story plan appends an entry only where its slice
+  changes that surface. Both land as status: proposed, and story close verifies each
+  against the as-built and flips it to live.
+  WHO READS: /appweaver plan-ui and the FE story designs — this log is the BE-to-FE
+  contract anchor, and the plan documents CITE these ids rather than restating them.
+  The current surface per interface is the LATEST entry — one that names an earlier
+  id in `supersedes:` replaces it. Never edit an existing entry; publish a
+  superseding one. status: proposed -> live -> superseded | retired.
+  `serves:` cites the FR-/BR- ids the interface exists for, so a spec change to
+  those ids flags the contract for review.
+-->
+
+# Interface Log
+""",
+    "adr": """<!--
+  ADR LOG — this feature's durable decisions. APPEND-ONLY.
+
+  A story plan PROPOSES ADRs in its latest design pass; they are ratified into this
+  log at story close, or the architect appends directly. Never rewrite an entry —
+  supersede it with a new one naming `supersedes:`. An ADR records ONLY what neither
+  the code nor the rules can say: a deliberate choice among rule-compliant
+  alternatives, a rejected alternative and why, or a trade-off with its revisit
+  trigger. It never restates what code shows or a rule mandates.
+-->
+
+# Architecture Decision Log
+"""}
+created = not os.path.isfile(path)
+if created:
+    open(path, "w", encoding="utf-8").write(SCAFFOLD[log])
+text = open(path, encoding="utf-8", errors="replace").read()
+existing = set(re.findall(r'^##\s+(%s-\d+)' % prefix, text, re.M))
+nums = [int(i.split("-")[1]) for i in existing]
+nxt = (max(nums) + 1) if nums else 1
+today = datetime.date.today().isoformat()
+
+spec = os.path.join(fd, "spec.md")
+known = set(re.findall(r'\b[A-Z]{2}-\d+\b',
+                       open(spec, encoding="utf-8", errors="replace").read())) \
+        if os.path.isfile(spec) else set()
+
+assigned, unknown, badsup, out_blocks = [], [], [], []
+for b in blocks:
+    bid = "%s-%03d" % (prefix, nxt); nxt += 1
+    lines = b.splitlines()
+    lines[0] = lines[0].replace("%s-NEW" % prefix, bid, 1)
+    body = "\n".join(lines[1:]).strip("\n")
+    # status and date are script-stamped, whatever the model wrote
+    body = re.sub(r'^status:.*\n?', '', body, flags=re.M)
+    body = re.sub(r'^date:.*\n?', '', body, flags=re.M)
+    body = ("status: %s\ndate: %s" % (status, today)) + ("\n" + body if body else "")
+    for line in body.splitlines():
+        if line.startswith("serves:"):
+            unknown += [i for i in re.findall(r'\b[A-Z]{2}-\d+\b', line)
+                        if known and i not in known]
+        if line.startswith("supersedes:"):
+            badsup += [i for i in re.findall(r'\b%s-\d+\b' % prefix, line)
+                       if i not in existing]
+    out_blocks.append(lines[0] + "\n\n" + body)
+    assigned.append(bid)
+
+text = text.rstrip("\n") + "\n\n" + "\n\n".join(out_blocks) + "\n"
+open(path, "w", encoding="utf-8").write(text)
+os.remove(ef)
+print(json.dumps({"ok": True, "log": path, "appended": len(assigned),
+                  "ids_csv": ", ".join(assigned),
+                  "unknown_ids_csv": ", ".join(sorted(set(unknown))),
+                  "bad_supersedes_csv": ", ".join(sorted(set(badsup))),
+                  "none": False, "created_log": created}))
+PY
+}
+
 case "$sub" in
     resolve-domain)   cmd_resolve_domain "$@" ;;
     resolve-tech)     cmd_resolve_tech "$@" ;;
@@ -3399,13 +5429,24 @@ case "$sub" in
     spec-snapshot)    cmd_spec_snapshot "$@" ;;
     spec-diff)        cmd_spec_diff "$@" ;;
     story-refs)       cmd_story_refs "$@" ;;
+    slice-mode)       cmd_slice_mode "$@" ;;
+    backlog-plan)     cmd_backlog_plan "$@" ;;
+    story-stamp)      cmd_story_stamp "$@" ;;
+    story-plan-check) cmd_story_plan_check "$@" ;;
+    story-plan-doc)   cmd_story_plan_doc "$@" ;;
+    log-append)       cmd_log_append "$@" ;;
+    ledger-read)      cmd_ledger_read "$@" ;;
     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 "$@" ;;
+    plan-check)       cmd_plan_check "$@" ;;
+    plan-stamp)       cmd_plan_stamp "$@" ;;
+    gate-result)      cmd_gate_result "$@" ;;
     build-compile)    cmd_build_compile "$@" ;;
     test-run)         cmd_test_run "$@" ;;
+    test-diff)        cmd_test_diff "$@" ;;
     run-migrate)      cmd_run_migrate "$@" ;;
     deploy-dispatch)  cmd_deploy_dispatch "$@" ;;
     cr-setup)         cmd_cr_setup "$@" ;;