aw-spec-cli 0.1.33 → 0.1.34

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

@@ -12,8 +12,10 @@
 #   aw-spec-actions.sh <subcommand> [options]
 #
 # Subcommands:
-#   resolve-domain   --command <name>              -> {domain, rulemap_exists, candidates[]}
-#   resolve-tech     --command <name>              -> {domain, techrulemap_exists, candidates[]}
+#   resolve-domain   --command <name>              -> {domain, rulemap_exists, heading_found, candidates[], missing[]}
+#   resolve-tech     --command <name>              -> {domain, techrulemap_exists, heading_found, candidates[], missing[],
+#                                                      missing_elsewhere[], absent_corpora[], absent_corpora_text, absent_files,
+#                                                      skipped[], unknown_placeholders[], declared_stacks[], stack_mismatch, mismatched_stacks[]}
 #   scaffold         --feature-dir <path> [--allow-existing]
 #                                                  -> {feature_dir, spec_file, template, created, spec_created}
 #   resolve-hooks    --phase <before_specify|after_specify>
@@ -30,6 +32,9 @@
 #                     --profile builds root_options for the stack already chosen)
 #   stack-detect     [--kind <k>] [--exclude-root <p>]…  -> {matches[], backend, frontend, count}
 #                    (matches the repo's OWN files against the profiles; writes nothing)
+#   stack-rules      --kind <k> [--declared]       -> {project, map, map_exists, kind, profiles[], note,
+#                                                      declared, lane_profile, verdict, lane_coverage, ok, warning}
+#                    (which stacks the active project's technical map has rule files for; read-only)
 #   lane-declare     --profile <id|label|none|detected> [--kind <k>] [--id <lane>] [--source-path|--root <p>]
 #                    [--stack <label>] [--origin declared|reverse-engineered] [--require-existing-root]
 #                    [--build <c>] [--test <c>] [--run <c>] [--prototype-root <p>] [--prototype-run <c>] [--no-prototype]
@@ -55,17 +60,32 @@
 #   lane-probe       [--kind <k>] [--hint <text>]  -> {declared, declared_profile, hint_profile, hint_terms[], signals[], any, evidence}
 #                    (the FILE signals for "does this lane exist"; resolve-tech carries the rule signal)
 #   lane-set         (--id <lane>|--kind <k>) [--set KEY=VALUE]… [--unset KEY]…  -> {ok, lane_id, set, removed, written}
-#                    (KEY: contract_run, contract, client; an empty VALUE changes nothing)
-#   contract-export  [--timeout <s>]               -> {ok, ran, cmd, url, doc, doc_exists, operations, unnamed, already_running, reason, log_tail}
-#                    (start the service lane with contract_run, save the document at contract, stop it)
-#   contract-draft   --feature-dir <p>             -> {ok, written, removed, path, plan, operations, ids[], ids_csv, unread_count, reason}
-#                    (the feature's api-draft.json, drafted by script from its backend plan's API section)
-#   contract-combine                               -> {ok, doc, export, export_exists, drafts[], added, added_csv, served_csv, clashes_csv, status, reason}
-#                    (.appweaver/contracts/openapi.combined.json: the export plus every drafted operation it does not serve)
+#                    (KEY: contract_write, contract_run, contract, client; an empty VALUE changes nothing)
+#   contract-export  [--timeout <s>]               -> {ok, way, cause, ran, cmd, url, doc, doc_exists, operations, unnamed, already_running, reason, log_tail}
+#                    (the service lane's API document as built: its contract_write command, or contract_run + contract)
+#   contract-draft   --feature-dir <p> [--cr <id>] -> {ok, written, removed, path, plan, operations, ids[], ids_csv, unread[], unread_count, dropped[], dropped_text, reason}
+#                    (the feature's api-draft.json from its api-plan.md — its backend plan's API section before it has one;
+#                     with --cr, the change's from its delta-api-plan.md; dropped = operations the replaced draft had)
+#   contract-combine                               -> {ok, doc, planned, changes_csv, removed_csv, unserved_csv, unplanned_csv, clashes_csv, export, status, reason}
+#                    (.appweaver/contracts/openapi.combined.json: every planned operation with the open changes applied,
+#                     plus the served operations no plan describes)
 #   contract-requests --feature-dir <p>            -> {count, open_count, open_csv, declined_csv, rebind_csv, backend_text, frontend_text, summary, requests[]}
-#                    (the frontend plan's RQ-n requests and the backend plan's answers)
+#                    (the frontend plan's RQ-n requests and the API plan's answers)
 #   contract-client  [--doc <d>]                   -> run-phase result for the frontend lane's `client` command ({{contract}} = --doc)
-#   contract-check   --plan <p> [--doc <d>]        -> {ok, cited, ids[], missing[], drafted[], uncited, doc_exists, reason}
+#   contract-check   --plan <p> [--doc <d>]        -> {ok, cited, ids[], missing[], removed_csv, unserved_csv, unplanned_csv, uncited, doc_exists, reason}
+#   contract-verify  --feature-dir <p> [--cr <id>] [--doc <d>] [--check]
+#                                                  -> {ok, checked, planned, missing[], moved[], renamed[], still_served[], fields[], unplanned[], findings[], issues_text, warning, note}
+#                    (the as-built document vs the operations the feature's plan — or one change — names;
+#                     --check reads no document -> {ok, check, mode, cr, planned, removed, changes_applied[], needed, note}: is there anything to check)
+#   contract-merge   --feature-dir <p> --cr <id> [--check]
+#                                                  -> {ok, merged, written, split, path, delta, added[], changed[], removed[], from_table[], block_kept[],
+#                                                      id_added[], not_found[], requests[], history_row, draft, draft_operations, dropped_text, warning, reason}
+#                    (finalize-delta: the change's delta-api-plan.md merged into the feature's api-plan.md, by endpoint block;
+#                     --check writes nothing -> {ok, check, cr, path, delta, has_delta, merged, needed, reason}, close-delta's guard)
+#   api-split        --feature-dir <p> [--check] [--cr <id>]
+#                                                  -> {ok, split, needed, path, backend_plan, endpoints, requests_moved, draft_operations, dropped_text, reason}
+#                    (a feature planned before api-plan.md: its endpoint blocks and requests table moved out of its backend plan;
+#                     --check only reports `needed`, and --cr checks a change's delta backend plan the same way)
 #   contract-impact  --delta-backend <p> --frontend-plan <p> [--delta-frontend <p>]
 #                                                  -> {changes[], affected[], addressed[], unaddressed[], unaddressed_csv, warn}
 #                    (operations a change's service delta changes or removes that the frontend binds to,
@@ -79,14 +99,18 @@
 #   version-bootstrap-done [--feature-dir <path>]  -> {…, cleared}   (the ONLY clearer of the --bootstrap marker; call it when the first draft is finished)
 #   feature-lanes    [--feature-dir <path>] [--set backend|frontend|backend,frontend] [--clear]  -> {…, lanes[]}
 #                    (the declared lanes this feature has a surface in; empty = every declared lane)
-#   feature-paths                                  -> {feature, feature_slug, feature_dir, spec_file, backend_plan, frontend_plan, *_exists,
+#   feature-paths                                  -> {feature, feature_slug, feature_dir, spec_file, backend_plan, frontend_plan, api_plan, *_exists,
 #                                                      design_file/ui_design_file (aliases of the two plans), spec_exists, bootstrap_pending, needs_bootstrap}
 #   checklist-read   --file <path>                 -> {exists, total, checked, items[]}
 #   checklist-apply  --file <path> --results <json>-> {exists, before_checked, after_checked, total, newly_passing[], regressions[]}
-#   plan-coverage    --plan <path> --kind backend|frontend [--mode bootstrap|delta] [--source-path <p>]
-#                    [--test-path <p>] [--reported <json list>]... [--list-only]
+#   plan-coverage    --plan <path> --kind backend|frontend [--mode bootstrap|delta] [--api-plan <path>]
+#                    [--source-path <p>] [--test-path <p>] [--reported <json list>]... [--list-only]
 #                                                  -> {ok, total, names[], names_csv, elements[], gaps[], gap_count, gaps_text}
 #                    (which plan elements the lane's code names and the model reported done)
+#   test-citations   --plan <path> --kind backend|frontend [--mode bootstrap|delta] [--paths <json list>]...
+#                    [--source-path <p>] [--test-path <p>] [--spec <p>] [--model <p>] [--known-gaps <json>]...
+#                                                  -> {ok, all_cited, clean, required[], uncited[], uncited_csv, findings[], warning}
+#                    (which of the plan's FR-/BR- ids no test of the slice names)
 #   detect-project                                 -> {scaffolded, markers[]}
 #   foundation-list  [--kind <k>] [--profile <id>] [--ecosystem <e>] [--lane-id <id>] [--args '<F> <A>']
 #                                                  -> {options[], entries[], count, foundations[], specs[], preselect_option, preselect_app, rejected_out}
@@ -119,12 +143,14 @@
 #                                                  -> {ok, exists, issues, placeholders, placeholder_check, version_body, version_report, version_match, bad_dates}
 #   agent-context-update [--plan <path>]           -> {ok, ran, message}
 #
-#   plan-scaffold    --feature-dir <path> [--lane backend|frontend|service|ui] [--template <name>]
-#                    (alias: design-scaffold)      -> {feature_dir, plan_doc, design_doc, lane, created, migrated, override_active, template, template_source}
+#   plan-scaffold    --feature-dir <path> [--lane backend|frontend|api|service|ui] [--template <name>]
+#                    (alias: design-scaffold)      -> {feature_dir, plan_doc, design_doc, lane, created, migrated, blocked, override_active, template, template_source}
+#                    (--lane api: api-plan.md; blocked while the backend plan still carries the API — run api-split)
 #                    (backend|frontend write backend-plan.md / frontend-plan.md and MIGRATE a
 #                     legacy design.md / design.ui.md by renaming it; service|ui keep the legacy names)
-#   delta-plan-scaffold --cr-id <id> [--lane backend|frontend] [--feature-dir <path>] [--template <name>]
-#                                                  -> {cr_id, cr_dir, lane, delta_plan, created, migrated, override_active, template}
+#   delta-plan-scaffold --cr-id <id> [--lane backend|frontend|api] [--feature-dir <path>] [--template <name>]
+#                                                  -> {cr_id, cr_dir, lane, delta_plan, created, migrated, blocked, override_active, template}
+#                    (--lane api: delta-api-plan.md; blocked while the delta backend plan still carries the change's API)
 #   (design-extract / design-reconcile / design-paths are RETIRED — the path-tagged
 #    four-document model is gone. "Which files is this slice made of" is now an OKF
 #    query: aw-xref concept-paths / concept-upsert --merge.)
@@ -151,7 +177,7 @@
 #                    (--lane lists only the changes touching one of those lanes; none = every open change)
 #   cr-paths         --cr-id <id> [--feature-dir <path>]
 #                                                  -> {cr_dir, delta_spec, delta_model, delta_backend_plan, delta_frontend_plan,
-#                                                      wave, lanes[], lanes_csv, lanes_recorded, touches_backend,
+#                                                      delta_api_plan, wave, lanes[], lanes_csv, lanes_recorded, touches_backend,
 #                                                      touches_frontend, predecessor_files[], predecessor_specs[],
 #                                                      predecessor_docs[], sibling_files[], domain_model}
 #   cr-overlap       --cr-id <id> [--feature-dir <path>]
@@ -164,7 +190,7 @@
 #                                                      lanes[], lanes_csv, backend, frontend, source, stamped}
 #                    (the lanes a change touches, on its delta-spec's **Lanes** line; no line = every declared lane)
 #   slice-gate-stamp --cr-id <id> --lane backend|frontend [--feature-dir <path>] [--tests-green true|false]
-#                    [--tests-ran true|false] [--requirements-ok true|false] [--findings <json list>]
+#                    [--tests-ran true|false] [--requirements-ok true|false] [--findings <json list>]...
 #                                                  -> {file, lane, cr_id, verdict, tests_green, tests_ran,
 #                                                      requirements_ok, findings, high_findings, gated}
 #                    (one lane's analyze-slice-delta result, as changes/<id>/.aw-slice-gate.<lane>.json;
@@ -179,6 +205,11 @@
 #   context-version-bump  [--feature-dir <path>] [--cr-id <id>] [--touched-model true|false]
 #                                                  -> {ok, bumped, previous, version, model,
 #                                                      model_exists, context, reason}
+#   model-guard-snapshot --model <path>            -> {ok, model, before, exists, aggregates[], rules, cross_rules, guarded}
+#   model-guard-check --model <path>               -> {ok, checked, skipped, model, rejected, restored, losses[],
+#                                                      loss_count, losses_text, reason}
+#                    (bracket a whole-file rewrite of domain-model.md; on a loss the check
+#                     restores the model and keeps the rewrite as domain-model.rejected.md)
 #
 # All subcommands accept --help.
 
@@ -228,22 +259,34 @@ cmd_resolve_domain() {
     [ -n "$domain" ] && [ -f "$rulemap" ] && rulemap_exists=true
 
     # Collect bullet paths under "## /<command>" in the domain's domain-rule-bindings.md.
-    local -a candidates=()
+    # A mapped file that is not on disk goes to `missing`, never to `candidates`, so a
+    # caller can say so instead of loading nothing in its place without a word.
+    # heading_found tells a heading that is deliberately empty (a `_None_` line) apart
+    # from one that is absent or misspelled — both give no candidates.
+    local -a candidates=() missing=()
+    local heading_found=false
     if [ "$rulemap_exists" = true ]; then
-        # awk: capture "- path" bullets between the target "## <heading>" and the next "## "
+        grep -qxF "## /$command_name" "$rulemap" && heading_found=true
+        # awk: capture "- path" bullets between the target "## <heading>" and the next "## ".
+        # A path written as code (- `path`) is read without its backticks.
         while IFS= read -r line; do
-            [ -n "$line" ] && candidates+=("$line")
+            [ -n "$line" ] || continue
+            if [ -f "$repo_root/$line" ]; then candidates+=("$line"); else missing+=("$line"); fi
         done < <(awk -v h="## /$command_name" '
             $0==h {grab=1; next}
             /^## / {grab=0}
             grab && /^[[:space:]]*-[[:space:]]+/ {
-                sub(/^[[:space:]]*-[[:space:]]+/,""); sub(/[[:space:]]+$/,""); print
+                sub(/^[[:space:]]*-[[:space:]]+/,""); sub(/[[:space:]]+$/,"")
+                if ($0 ~ /^`[^`]+`$/) $0 = substr($0, 2, length($0) - 2)
+                print
             }
         ' "$rulemap")
     fi
 
-    printf '{"domain":"%s","rulemap_exists":%s,"candidates":%s}\n' \
-        "$(json_escape "$domain")" "$rulemap_exists" "$(json_str_array "${candidates[@]}")"
+    printf '{"domain":"%s","rulemap_exists":%s,"heading_found":%s,"candidates":%s,"missing":%s}\n' \
+        "$(json_escape "$domain")" "$rulemap_exists" "$heading_found" \
+        "$(json_str_array "${candidates[@]+"${candidates[@]}"}")" \
+        "$(json_str_array "${missing[@]+"${missing[@]}"}")"
 }
 
 # ──────────────────────────────── resolve-tech ─────────────────────────────
@@ -332,28 +375,39 @@ def expand(line):
     return HOLE.sub(lambda m: subs[m.group(1)], line), ""
 
 bullets = []
+# Whether the command's heading is in the map at all. A heading with no bullets (a
+# `_None_` line) is a deliberate choice; an absent or misspelled one loads the same
+# nothing, and only this tells the caller which of the two it is.
+heading_found = False
 if exists:
     text = open(techmap, encoding="utf-8").read().splitlines()
     for heading in ("## /" + command, "## /" + command.replace("decl-", "")):
         found, grab = [], False
         for line in text:
             if line.strip() == heading:
-                grab = True; continue
+                grab = True; heading_found = True; continue
             if line.startswith("## "):
                 grab = False; continue
             if grab:
                 m = re.match(r"^\s*-\s+(.*?)\s*$", line)
                 if m:
-                    found.append(m.group(1))
+                    # A path written as code (- `path`) is read without its backticks.
+                    found.append(re.sub(r"^`([^`]+)`$", r"\1", m.group(1)))
         if found:
             bullets = found
             break
 
 candidates, missing, skipped, mismatched = [], [], [], []
+# A placeholder the kit does not know is a typo in the map, unlike one for a lane
+# this repo does not declare, which is skipped because its rules do not apply.
+unknown = []
 for b in bullets:
     path, why = expand(b)
     if why:
-        skipped.append({"bullet": b, "why": why}); continue
+        skipped.append({"bullet": b, "why": why})
+        if why.startswith("unknown placeholder"):
+            unknown.append(b)
+        continue
     (candidates if os.path.isfile(os.path.join(repo, path)) else missing).append(path)
     # A LITERAL stack directory that is not one this repo declares. Reported, never
     # dropped: the file exists and the project chose it, so it may be a deliberate
@@ -364,12 +418,32 @@ for b in bullets:
         if m.group(1) not in mismatched:
             mismatched.append(m.group(1))
 
+# A STACK WITH NO RULE FOLDER AT ALL. Every file the map names under it is missing, and
+# that is a supported setup rather than a typo (STACK-PROFILES.md §7), so those files are
+# reported as the folder they belong to. A file missing from a folder that DOES exist is
+# a gap to fix, and stays listed one by one in missing_elsewhere. `missing` keeps both.
+absent, absent_files, elsewhere = [], 0, []
+for p in missing:
+    m = re.match(r"^(guardrails/technology/[^/]+/)", p)
+    if m and not os.path.isdir(os.path.join(repo, m.group(1))):
+        if m.group(1) not in absent:
+            absent.append(m.group(1))
+        absent_files += 1
+    else:
+        elsewhere.append(p)
+
 print(json.dumps({
     "domain": domain,
     "techrulemap_exists": exists,
+    "heading_found": heading_found,
     "candidates": candidates,
     "missing": missing,
+    "missing_elsewhere": elsewhere,
+    "absent_corpora": absent,
+    "absent_corpora_text": " and ".join(absent),
+    "absent_files": absent_files,
     "skipped": skipped,
+    "unknown_placeholders": unknown,
     "declared_stacks": sorted(declared),
     "stack_mismatch": bool(mismatched),
     "mismatched_stacks": mismatched,
@@ -842,6 +916,22 @@ cmd_stack_detect() {
     _aw_stack_py detect "${fwd[@]}"
 }
 
+# Which stacks the active project's technical map has rule files for (aw-stack.py rules).
+# A stack without them is a supported setup; select-stack reports it in the menu and
+# warns for a declared lane, so the operator learns it where the stack is chosen.
+cmd_stack_rules() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --kind) fwd+=("--kind" "$2"); shift 2 ;;
+            --declared) fwd+=("--declared"); shift ;;
+            --help|-h) echo "stack-rules --kind backend|frontend [--declared]  -> {project, map, map_exists, kind, profiles[], note, declared, lane_profile, verdict, lane_coverage, ok, warning}"; return 0 ;;
+            *) echo "stack-rules: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py rules "${fwd[@]}"
+}
+
 cmd_lane_declare() {
     local -a fwd=()
     while [ $# -gt 0 ]; do
@@ -875,45 +965,47 @@ cmd_lane_resolve() {
     _aw_stack_py resolve "${fwd[@]}"
 }
 
-# Change the API-contract keys (contract_run, contract, client) on a lane already
-# declared, leaving the rest of it alone. `--set KEY=` with an empty value changes
-# nothing; `--unset KEY` removes one. Callers: foundation (a pack's lane settings) and
-# implement (the client command a developer supplies).
+# Change the API-contract keys (contract_write, contract_run, contract, client) on a lane
+# already declared, leaving the rest of it alone. `--set KEY=` with an empty value changes
+# nothing; `--unset KEY` removes one. Callers: foundation (a pack's or a spec's lane
+# settings) and implement (the client command a developer supplies).
 cmd_lane_set() {
     local -a fwd=()
     while [ $# -gt 0 ]; do
         case "$1" in
             --id|--kind|--set|--unset) fwd+=("$1" "$2"); shift 2 ;;
-            --help|-h) echo "lane-set (--id <lane>|--kind backend|frontend) [--set KEY=VALUE]… [--unset KEY]…  (KEY: contract_run, contract, client)"; return 0 ;;
+            --help|-h) echo "lane-set (--id <lane>|--kind backend|frontend) [--set KEY=VALUE]… [--unset KEY]…  (KEY: contract_write, contract_run, contract, client)"; return 0 ;;
             *) echo "lane-set: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
     _aw_stack_py set "${fwd[@]}"
 }
 
-# ─────────────── contract-export / -draft / -combine / -requests / -client / -check ───────────────
-# The API contract between the lanes: export the service lane's API document from the
-# running service, draft a feature's document from its backend plan, combine the two for
-# the frontend, read the request ledger between the plans, generate the frontend lane's
-# client, and check the operation ids a frontend plan cites. All delegate to aw-stack.py.
+# ─────── contract-export / -draft / -combine / -requests / -client / -check / -verify / -merge, api-split ───────
+# The API contract between the lanes: the API plans' drafts are the contract, combined for
+# the frontend with the open changes applied, and each change's delta API plan is merged
+# into its feature's API plan when the change is finalized; the request ledger runs between
+# the plans; the frontend lane's client is generated from the combined document, and the
+# operation ids its plan cites are checked against it. The service lane's document as
+# built is written by its own way and checked against the plan. All delegate to aw-stack.py.
 cmd_contract_export() {
     local -a fwd=()
     while [ $# -gt 0 ]; do
         case "$1" in
             --timeout) fwd+=("$1" "$2"); shift 2 ;;
-            --help|-h) echo "contract-export [--timeout <seconds>]  -> {ok, ran, cmd, url, doc, doc_exists, operations, unnamed, already_running, reason, log_tail}"; return 0 ;;
+            --help|-h) echo "contract-export [--timeout <seconds>]  -> {ok, way, cause, ran, cmd, url, doc, doc_exists, operations, unnamed, already_running, reason, log_tail}"; return 0 ;;
             *) echo "contract-export: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
-    _aw_stack_py contract-export "${fwd[@]}"
+    _aw_stack_py contract-export "${fwd[@]+"${fwd[@]}"}"
 }
 
 cmd_contract_draft() {
     local -a fwd=()
     while [ $# -gt 0 ]; do
         case "$1" in
-            --feature-dir) if [ -n "$2" ]; then fwd+=("$1" "$2"); fi; shift 2 ;;
-            --help|-h) echo "contract-draft --feature-dir <path>  -> {ok, written, removed, path, plan, operations, ids, ids_csv, unread_count, reason}"; return 0 ;;
+            --feature-dir|--cr) if [ -n "$2" ]; then fwd+=("$1" "$2"); fi; shift 2 ;;
+            --help|-h) echo "contract-draft --feature-dir <path> [--cr <id>]  -> {ok, written, removed, path, plan, operations, ids, ids_csv, unread, unread_count, dropped, dropped_text, reason}"; return 0 ;;
             *) echo "contract-draft: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -923,7 +1015,7 @@ cmd_contract_draft() {
 cmd_contract_combine() {
     while [ $# -gt 0 ]; do
         case "$1" in
-            --help|-h) echo "contract-combine  -> {ok, doc, export, export_exists, drafts, added, added_csv, served_csv, clashes_csv, status, reason}"; return 0 ;;
+            --help|-h) echo "contract-combine  -> {ok, doc, planned, changes_csv, removed_csv, unserved_csv, unplanned_csv, clashes_csv, export, export_exists, status, reason}"; return 0 ;;
             *) echo "contract-combine: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -962,13 +1054,58 @@ cmd_contract_check() {
     while [ $# -gt 0 ]; do
         case "$1" in
             --plan|--doc) fwd+=("$1" "$2"); shift 2 ;;
-            --help|-h) echo "contract-check --plan <frontend plan> [--doc <api document>]  -> {ok, cited, ids, missing, uncited, doc_exists, reason}"; return 0 ;;
+            --help|-h) echo "contract-check --plan <frontend plan> [--doc <api document>]  -> {ok, cited, ids, missing, removed_csv, unserved_csv, unplanned_csv, uncited, doc_exists, reason}"; return 0 ;;
             *) echo "contract-check: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
     _aw_stack_py contract-check "${fwd[@]}"
 }
 
+# Does the built service serve what its plan names — the feature's operations, or with --cr
+# one change's; with --check, only whether the plan names anything to check. Each value is
+# forwarded only when it is not empty.
+cmd_contract_verify() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir|--cr|--doc) if [ -n "$2" ]; then fwd+=("$1" "$2"); fi; shift 2 ;;
+            --check) fwd+=("$1"); shift ;;
+            --help|-h) echo "contract-verify --feature-dir <path> [--cr <id>] [--doc <as-built document>] [--check]  -> {ok, checked, planned, missing, moved, renamed, still_served, fields, unplanned, findings, issues_text, warning, note}; --check reads no document -> {ok, check, mode, cr, planned, removed, changes_applied, needed, note}"; return 0 ;;
+            *) echo "contract-verify: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py contract-verify "${fwd[@]+"${fwd[@]}"}"
+}
+
+# A change's delta API plan, merged into its feature's API plan (finalize-delta); with
+# --check, only whether it is still to merge (close-delta).
+cmd_contract_merge() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir|--cr) if [ -n "$2" ]; then fwd+=("$1" "$2"); fi; shift 2 ;;
+            --check) fwd+=("$1"); shift ;;
+            --help|-h) echo "contract-merge --feature-dir <path> --cr <id> [--check]  -> {ok, merged, written, split, path, delta, added, changed, removed, from_table, block_kept, id_added, not_found, requests, history_row, draft, draft_operations, dropped_text, warning, reason}; --check writes nothing -> {ok, check, cr, path, delta, has_delta, merged, needed, reason}"; return 0 ;;
+            *) echo "contract-merge: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py contract-merge "${fwd[@]+"${fwd[@]}"}"
+}
+
+# A feature's endpoints and requests table, moved out of its backend plan into an API plan.
+cmd_api_split() {
+    local -a fwd=()
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --feature-dir|--cr) if [ -n "$2" ]; then fwd+=("$1" "$2"); fi; shift 2 ;;
+            --check) fwd+=("$1"); shift ;;
+            --help|-h) echo "api-split --feature-dir <path> [--check] [--cr <id>]  -> {ok, split, needed, path, backend_plan, endpoints, requests_moved, draft_operations, dropped_text, reason}"; return 0 ;;
+            *) echo "api-split: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    _aw_stack_py api-split "${fwd[@]+"${fwd[@]}"}"
+}
+
 # What a change's service delta changes or removes that the frontend master plan binds to,
 # and whether the change's frontend delta plan carries it. Each path is forwarded only when
 # it is not empty.
@@ -1434,6 +1571,39 @@ cmd_model_scaffold() {
         "$(json_escape "$tpl")" "$created"
 }
 
+# ──────────────────── model-guard-snapshot / model-guard-check ─────────────────────
+# specify (bootstrap) and adopt write the context's WHOLE domain-model.md, and from a
+# context's second feature on that file holds the aggregates, BR-/XBR- rules and ledger rows
+# other features rely on. These two bracket that step: the snapshot copies the model aside,
+# the check compares the rewrite with the copy and, on a loss, puts the model back and keeps
+# the rewrite as domain-model.rejected.md. THE RULE LIVES IN python/aw-model-guard.py, which
+# both shells invoke — these are thin wrappers that resolve the path and hand over. Both
+# exit 0 with `ok` in the JSON; the workflow's gate owns the stop.
+cmd_model_guard() {
+    local op="$1"; shift
+    local model=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --model) model="$2"; shift 2 ;;
+            --help|-h)
+                if [ "$op" = "snapshot" ]; then
+                    echo "model-guard-snapshot --model <path>  -> {ok, model, before, exists, aggregates[], rules, cross_rules, guarded}"
+                else
+                    echo "model-guard-check --model <path>  -> {ok, checked, skipped, model, rejected, restored, losses[], loss_count, losses_text, reason}"
+                fi
+                return 0 ;;
+            *) echo "model-guard-$op: unknown arg '$1'" >&2; return 1 ;;
+        esac
+    done
+    [ -n "$model" ] || { echo "model-guard-$op: --model required" >&2; return 1; }
+    local repo_root; repo_root=$(get_repo_root)
+    [[ "$model" != /* ]] && model="$repo_root/$model"
+    local core="$SCRIPT_DIR/../python/aw-model-guard.py"
+    if [ ! -f "$core" ]; then echo "model-guard-$op: core not found at $core" >&2; return 1; fi
+    if ! command -v python3 >/dev/null 2>&1; then echo "model-guard-$op: python3 is required" >&2; return 1; fi
+    python3 "$core" "$op" --model "$model" --root "$repo_root"
+}
+
 # ─────────────────────────────── list-features ─────────────────────────────
 # Enumerate the aggregates a user can pick as the active feature. Two sources,
 # MERGED (deduped by feature name, case-insensitive):
@@ -2015,6 +2185,11 @@ cmd_feature_paths() {
     local spec="$fd/spec.md" design="$fd/backend-plan.md" ui_design="$fd/frontend-plan.md"
     [ ! -f "$design" ]    && [ -f "$fd/design.md" ]    && design="$fd/design.md"
     [ ! -f "$ui_design" ] && [ -f "$fd/design.ui.md" ] && ui_design="$fd/design.ui.md"
+    # The API plan beside the backend plan: the service's published endpoints, a master that
+    # finalize-delta merges each change's API into. A feature planned before it existed has
+    # none, and keeps its endpoints in its backend plan until `api-split` moves them.
+    local api_plan="$fd/api-plan.md" api_plan_exists=false
+    [ -f "$api_plan" ] && api_plan_exists=true
     # 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.
@@ -2026,9 +2201,10 @@ cmd_feature_paths() {
     local needs_bootstrap=false
     [ "$spec_exists" = false ] && needs_bootstrap=true
     [ "$bootstrap_pending" = true ] && needs_bootstrap=true
-    printf '{"feature":"%s","feature_slug":"%s","feature_dir":"%s","spec_file":"%s","backend_plan":"%s","frontend_plan":"%s","backend_plan_exists":%s,"frontend_plan_exists":%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_slug":"%s","feature_dir":"%s","spec_file":"%s","backend_plan":"%s","frontend_plan":"%s","backend_plan_exists":%s,"frontend_plan_exists":%s,"api_plan":"%s","api_plan_exists":%s,"design_file":"%s","ui_design_file":"%s","spec_exists":%s,"design_exists":%s,"ui_design_exists":%s,"bootstrap_pending":%s,"needs_bootstrap":%s}\n' \
         "$(json_escape "$feature")" "$(json_escape "$feature_slug")" "$(json_escape "$fd")" "$(json_escape "$spec")" \
         "$(json_escape "$design")" "$(json_escape "$ui_design")" "$design_exists" "$ui_design_exists" \
+        "$(json_escape "$api_plan")" "$api_plan_exists" \
         "$(json_escape "$design")" "$(json_escape "$ui_design")" "$spec_exists" "$design_exists" "$ui_design_exists" \
         "$bootstrap_pending" "$needs_bootstrap"
 }
@@ -3251,7 +3427,7 @@ cmd_design_scaffold() {
             # Priority-1), so the defaults already yield the as-built structure for
             # forward `plan` and adopt alike, and this is rarely needed.
             --template) template_arg="$2"; shift 2 ;;
-            --help|-h) echo "plan-scaffold --feature-dir <path> [--lane backend|frontend|service|ui] [--template <name>]"; return 0 ;;
+            --help|-h) echo "plan-scaffold --feature-dir <path> [--lane backend|frontend|api|service|ui] [--template <name>]"; return 0 ;;
             *) echo "design-scaffold: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -3259,14 +3435,16 @@ cmd_design_scaffold() {
     # names, and a MIGRATION — a legacy design.md / design.ui.md is RENAMED into the plan
     # name, so a feature never carries two spellings of one master and the rename costs
     # no flag day. service / ui stay byte-identical for the callers that still write the
-    # legacy names (adopt's reverse pass).
+    # legacy names (adopt's reverse pass). api is the backend lane's API plan, beside its
+    # plan — one template for every project, since its endpoint block form is fixed.
     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" ;;
         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' (backend|frontend|service|ui)" >&2; return 1 ;;
+        api)      doc_name="api-plan.md";      [ -n "$template_arg" ] || template_arg="api-plan-template" ;;
+        *) echo "design-scaffold: unknown --lane '$lane_arg' (backend|frontend|api|service|ui)" >&2; return 1 ;;
     esac
     local repo_root; repo_root=$(get_repo_root)
     local fd="$feature_dir_arg"
@@ -3282,7 +3460,17 @@ cmd_design_scaffold() {
     if [ ! -f "$target" ] && [ -n "$legacy_name" ] && [ -f "$fd/$legacy_name" ]; then
         mv "$fd/$legacy_name" "$target"; migrated="true"
     fi
-    if [ -f "$target" ]; then
+    # An API plan is never scaffolded beside a backend plan that still carries the API: the
+    # empty template would be read in its place and the draft would lose every endpoint.
+    # `api-split` moves them first.
+    local blocked="false"
+    if [ "$lane_arg" = "api" ] && [ ! -f "$target" ]; then
+        blocked=$(_aw_stack_py api-split --feature-dir "$fd" --check 2>/dev/null \
+            | python3 -c 'import json,sys
+try: print("true" if json.load(sys.stdin).get("needed") else "false")
+except Exception: print("false")' 2>/dev/null) || blocked="false"
+    fi
+    if [ -f "$target" ] || [ "$blocked" = "true" ]; then
         created="false"
     else
         tpl=$(resolve_template "$template_arg" "$repo_root") || true
@@ -3298,9 +3486,9 @@ 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","plan_doc":"%s","lane":"%s","created":%s,"migrated":%s,"override_active":%s,"template":"%s","template_source":"%s"}\n' \
+    printf '{"feature_dir":"%s","design_doc":"%s","plan_doc":"%s","lane":"%s","created":%s,"migrated":%s,"blocked":%s,"override_active":%s,"template":"%s","template_source":"%s"}\n' \
         "$(json_escape "$fd")" "$(json_escape "$target")" "$(json_escape "$target")" "$(json_escape "$lane_arg")" \
-        "$created" "$migrated" "$override_active" \
+        "$created" "$migrated" "$blocked" "$override_active" \
         "$(json_escape "$template_arg")" "$(json_escape "${template_source:-}")"
 }
 
@@ -3324,7 +3512,7 @@ cmd_delta_plan_scaffold() {
             --feature-dir) feature_dir_arg="$2"; shift 2 ;;
             --lane) lane_arg="$2"; shift 2 ;;
             --template) template_arg="$2"; shift 2 ;;
-            --help|-h) echo "delta-plan-scaffold --cr-id <id> [--lane backend|frontend] [--feature-dir <path>] [--template <name>]"; return 0 ;;
+            --help|-h) echo "delta-plan-scaffold --cr-id <id> [--lane backend|frontend|api] [--feature-dir <path>] [--template <name>]"; return 0 ;;
             *) echo "delta-plan-scaffold: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -3336,7 +3524,9 @@ cmd_delta_plan_scaffold() {
                   [ -n "$template_arg" ] || template_arg="delta-design-template" ;;
         frontend) doc_name="delta-frontend-plan.md"; legacy_name="delta-design.ui.md"
                   [ -n "$template_arg" ] || template_arg="ui-delta-design-template" ;;
-        *) echo "delta-plan-scaffold: unknown --lane '$lane_arg' (backend|frontend)" >&2; return 1 ;;
+        api)      doc_name="delta-api-plan.md"
+                  [ -n "$template_arg" ] || template_arg="delta-api-plan-template" ;;
+        *) echo "delta-plan-scaffold: unknown --lane '$lane_arg' (backend|frontend|api)" >&2; return 1 ;;
     esac
     local repo_root; repo_root=$(get_repo_root)
     local fd; fd=$(_resolve_feature_dir "$feature_dir_arg" "$repo_root") || { echo "delta-plan-scaffold: no feature set and no --feature-dir" >&2; return 1; }
@@ -3344,10 +3534,19 @@ cmd_delta_plan_scaffold() {
     [ -d "$cr_dir" ] || { echo "delta-plan-scaffold: no such open change '$cr_id' (looked in $cr_dir)" >&2; return 1; }
 
     local target="$cr_dir/$doc_name" created="false" migrated="false" tpl
-    if [ ! -f "$target" ] && [ -f "$cr_dir/$legacy_name" ]; then
+    if [ ! -f "$target" ] && [ -n "$legacy_name" ] && [ -f "$cr_dir/$legacy_name" ]; then
         mv "$cr_dir/$legacy_name" "$target"; migrated="true"
     fi
-    if [ ! -f "$target" ]; then
+    # A change planned before the delta API plan existed keeps its API in its delta backend
+    # plan, which is read in its place; an empty delta API plan beside it would hide it.
+    local blocked="false"
+    if [ "$lane_arg" = "api" ] && [ ! -f "$target" ]; then
+        blocked=$(_aw_stack_py api-split --feature-dir "$fd" --cr "$cr_id" 2>/dev/null \
+            | python3 -c 'import json,sys
+try: print("true" if json.load(sys.stdin).get("needed") else "false")
+except Exception: print("false")' 2>/dev/null) || blocked="false"
+    fi
+    if [ ! -f "$target" ] && [ "$blocked" != "true" ]; then
         tpl=$(resolve_template "$template_arg" "$repo_root") || true
         if [ -n "$tpl" ] && [ -f "$tpl" ]; then cp "$tpl" "$target"; else touch "$target"; fi
         created="true"
@@ -3357,15 +3556,15 @@ cmd_delta_plan_scaffold() {
     # readable wave the template's `[N]` is left standing, which is what the merge and recall
     # fences read as "not ordered yet" and refuse on, with the command that stamps it.
     local scaffold_wave; scaffold_wave=$(_wave_of_readable "$fd" "$cr_id" "$repo_root")
-    if [ -n "$scaffold_wave" ]; then
+    if [ -n "$scaffold_wave" ] && [ -f "$target" ]; then
         _stamp_header "$target" "Wave" "$scaffold_wave"
     fi
     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 '{"cr_id":"%s","cr_dir":"%s","lane":"%s","delta_plan":"%s","created":%s,"migrated":%s,"override_active":%s,"template":"%s","template_source":"%s"}\n' \
+    printf '{"cr_id":"%s","cr_dir":"%s","lane":"%s","delta_plan":"%s","created":%s,"migrated":%s,"blocked":%s,"override_active":%s,"template":"%s","template_source":"%s"}\n' \
         "$(json_escape "$cr_id")" "$(json_escape "$cr_dir")" "$(json_escape "$lane_arg")" "$(json_escape "$target")" \
-        "$created" "$migrated" "$override_active" \
+        "$created" "$migrated" "$blocked" "$override_active" \
         "$(json_escape "$template_arg")" "$(json_escape "${template_source:-}")"
 }
 
@@ -3899,7 +4098,7 @@ cmd_slice_gate_stamp() {
             --feature-dir) fd_arg="$2"; shift 2 ;;
             # --flag=value: the findings are a JSON list, and any value may be empty.
             --lane|--tests-green|--tests-ran|--requirements-ok|--findings) fwd+=("$1=$2"); shift 2 ;;
-            --help|-h) echo "slice-gate-stamp --cr-id <id> --lane backend|frontend [--feature-dir <path>] [--tests-green true|false] [--tests-ran true|false] [--requirements-ok true|false] [--findings <json list>]  -> {file, lane, cr_id, verdict, tests_green, tests_ran, requirements_ok, findings, high_findings, gated}"; return 0 ;;
+            --help|-h) echo "slice-gate-stamp --cr-id <id> --lane backend|frontend [--feature-dir <path>] [--tests-green true|false] [--tests-ran true|false] [--requirements-ok true|false] [--findings <json list>]...  -> {file, lane, cr_id, verdict, tests_green, tests_ran, requirements_ok, findings, high_findings, gated}"; return 0 ;;
             *) echo "slice-gate-stamp: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -4465,7 +4664,7 @@ cmd_cr_paths() {
         case "$1" in
             --cr-id) cr_id="$2"; shift 2 ;;
             --feature-dir) feature_dir_arg="$2"; shift 2 ;;
-            --help|-h) echo "cr-paths --cr-id <id> [--feature-dir <path>]  -> {cr_id, cr_dir, delta_spec, delta_model, delta_backend_plan, delta_frontend_plan, wave, lanes[], lanes_csv, lanes_recorded, touches_backend, touches_frontend, predecessor_files[], predecessor_specs[], predecessor_docs[], sibling_files[], domain_model}"; return 0 ;;
+            --help|-h) echo "cr-paths --cr-id <id> [--feature-dir <path>]  -> {cr_id, cr_dir, delta_spec, delta_model, delta_backend_plan, delta_frontend_plan, delta_api_plan, wave, lanes[], lanes_csv, lanes_recorded, touches_backend, touches_frontend, predecessor_files[], predecessor_specs[], predecessor_docs[], sibling_files[], domain_model}"; return 0 ;;
             *) echo "cr-paths: unknown arg '$1'" >&2; return 1 ;;
         esac
     done
@@ -4489,6 +4688,7 @@ dspec  = os.path.join(cr_dir, "delta-spec.md")
 dmodel = os.path.join(ctx, "domain-model.%s.delta.md" % cr)
 be     = os.path.join(cr_dir, "delta-backend-plan.md")
 fe     = os.path.join(cr_dir, "delta-frontend-plan.md")
+api    = os.path.join(cr_dir, "delta-api-plan.md")
 master = os.path.join(ctx, "domain-model.md")
 wave = wave_of(dspec, wave_of(dmodel, 1))
 # The lanes a change touches: read_change_lanes in python/aw-stack.py, the one reader of a
@@ -4531,6 +4731,8 @@ print(json.dumps({
     "delta_model": rel(dmodel), "delta_model_exists": os.path.isfile(dmodel),
     "delta_backend_plan": rel(be), "delta_backend_plan_exists": os.path.isfile(be),
     "delta_frontend_plan": rel(fe), "delta_frontend_plan_exists": os.path.isfile(fe),
+    # The change's API delta — merged into the feature's api-plan.md by finalize-delta.
+    "delta_api_plan": rel(api), "delta_api_plan_exists": os.path.isfile(api),
     "wave": wave,
     # The lanes this change touches, from its delta-spec's **Lanes** line — every lane when
     # it records none (lanes_recorded false).
@@ -4947,10 +5149,19 @@ snap = os.path.join(fd, "changes", cr, "pre-merge")
 os.makedirs(snap, exist_ok=True)
 spec  = os.path.join(fd, "spec.md")
 model = os.path.join(ctx, "domain-model.md")
+# Every document finalize-delta may rewrite: the two masters it merges into, the API plan it
+# merges the change's API into, the backend plan the first such merge moves the endpoints out
+# of, and the API draft it redraws.
+backend = next((os.path.join(fd, n) for n in ("backend-plan.md", "design.md")
+                if os.path.isfile(os.path.join(fd, n))), os.path.join(fd, "backend-plan.md"))
+docs = ((spec, "spec.md"), (model, "domain-model.md"),
+        (os.path.join(fd, "api-plan.md"), "api-plan.md"),
+        (backend, os.path.basename(backend)),
+        (os.path.join(fd, "api-draft.json"), "api-draft.json"))
 copied = []
-# Flat names, not the source tree's shape: there are exactly two masters and they live at
-# different levels, so a nested copy would encode the layout of the day it was taken.
-for src, name in ((spec, "spec.md"), (model, "domain-model.md")):
+# Flat names, not the source tree's shape: the documents live at different levels, so a
+# nested copy would encode the layout of the day it was taken.
+for src, name in docs:
     if os.path.isfile(src):
         shutil.copy2(src, os.path.join(snap, name))
         copied.append(name)
@@ -4967,7 +5178,7 @@ manifest = {
     "version": version,
     "context_version": header(model, "Context version"),
     "files": copied,
-    "sources": {"spec.md": rel(spec), "domain-model.md": rel(model)},
+    "sources": {name: rel(src) for src, name in docs if name in copied},
     # Stated in the file itself, because the restore is the reader's whole reason for
     # opening it and the condition on it is not obvious from the content.
     "note": ("Masters as they stood immediately before finalize-delta merged %s. "
@@ -5411,7 +5622,7 @@ cmd_gap_route() {
 # (python/aw-plan-coverage.py), called identically by both shells.
 cmd_plan_coverage() {
     case "${1:-}" in
-        --help|-h) echo "plan-coverage --plan <path> --kind backend|frontend [--mode bootstrap|delta] [--source-path <p>] [--test-path <p>] [--reported <json list>]... [--generated <json list>] [--list-only]  -> {ok, outcome, total, names[], names_csv, elements[], gaps[], gap_names[], gap_count, gaps_text, message}"; return 0 ;;
+        --help|-h) echo "plan-coverage --plan <path> --kind backend|frontend [--mode bootstrap|delta] [--api-plan <path>] [--source-path <p>] [--test-path <p>] [--reported <json list>]... [--generated <json list>] [--list-only]  -> {ok, outcome, total, names[], names_csv, elements[], gaps[], gap_names[], gap_count, gaps_text, message}"; return 0 ;;
     esac
     local repo_root; repo_root=$(get_repo_root)
     local core="$SCRIPT_DIR/../python/aw-plan-coverage.py"
@@ -5424,6 +5635,27 @@ cmd_plan_coverage() {
     python3 "$core" --repo "$repo_root" "$@"
 }
 
+# ──────────────────────────────── test-citations ────────────────────────────
+# Which of a lane plan's requirement ids no test of the slice names. A requirement whose
+# test was never written leaves the suite green, so analyze-slice and analyze-slice-delta
+# read the plan's FR- and BR- ids and look for each one in the slice's test files. Same
+# core as plan-coverage (python/aw-plan-coverage.py --citations), called identically by
+# both shells.
+cmd_test_citations() {
+    case "${1:-}" in
+        --help|-h) echo "test-citations --plan <path> --kind backend|frontend [--mode bootstrap|delta] [--paths <json list>]... [--source-path <p>] [--test-path <p>] [--spec <spec.md>] [--model <domain-model.md>] [--known-gaps <json list>]...  -> {ok, all_cited, clean, outcome, checked, readable, advisory, required[], uncited[], uncited_csv, uncited_text, other_uncited[], stale[], findings[], tests_scanned, scoped, warning, message}"; return 0 ;;
+    esac
+    local repo_root; repo_root=$(get_repo_root)
+    local core="$SCRIPT_DIR/../python/aw-plan-coverage.py"
+    if [ ! -f "$core" ]; then
+        echo "test-citations: core not found at $core" >&2; return 1
+    fi
+    if ! command -v python3 >/dev/null 2>&1; then
+        echo "test-citations: python3 is required" >&2; return 1
+    fi
+    python3 "$core" --repo "$repo_root" --citations "$@"
+}
+
 # Stamp a version into the MASTER documents' `**Version**:` headers — the
 # deterministic twin of cr-archive's active_version.json bump. close-delta calls
 # this with the version cr-archive just computed, so all THREE carriers of the
@@ -5476,8 +5708,9 @@ pat = re.compile(r'^(\*\*Version\*\*:[ \t]*)(\S+)(.*)$', re.M)
 # spine cannot tolerate. A lane the feature does not have reports `missing` and nothing
 # fails, which is also how the legacy names are carried — a feature not yet migrated to
 # the plan names still gets stamped, and one that has been migrated reports the legacy
-# pair missing.
-for name in ("spec.md", "backend-plan.md", "frontend-plan.md", "design.md", "design.ui.md"):
+# pair missing. The API plan is a master too, and moves with them.
+for name in ("spec.md", "backend-plan.md", "frontend-plan.md", "design.md", "design.ui.md",
+             "api-plan.md"):
     p = os.path.join(fd, name)
     if not os.path.isfile(p):
         missing.append(name); continue
@@ -5495,12 +5728,16 @@ for name in ("spec.md", "backend-plan.md", "frontend-plan.md", "design.md", "des
 # found by its CR cell, not by position: rows are appended newest-last and a feature may
 # carry many, so "the last row" would be right only until two changes were open at once.
 # Only a cell still reading `(pending)` is written — a row already carrying a version
-# belongs to a change that closed, and re-stamping it would rewrite history.
+# belongs to a change that closed, and re-stamping it would rewrite history. The API plan's
+# row, which finalize-delta's API merge wrote, is completed the same way.
 row_filled = False
 row_version = ""
+rows_filled = []
 if cr:
-    p = os.path.join(fd, "spec.md")
-    if os.path.isfile(p):
+    for name in ("spec.md", "api-plan.md"):
+        p = os.path.join(fd, name)
+        if not os.path.isfile(p):
+            continue
         src = open(p, encoding="utf-8").read()
         out_lines, changed = [], False
         for line in src.splitlines(True):
@@ -5508,14 +5745,17 @@ if cr:
             if (not changed) and cr in line and line.lstrip().startswith("|"):
                 cells = line.split("|")
                 if len(cells) > 2 and cells[1].strip().lower() in ("(pending)", "pending", "—", "-", ""):
-                    row_version = cells[1].strip()
+                    if name == "spec.md":
+                        row_version = cells[1].strip()
                     cells[1] = " %s " % ver
                     line = "|".join(cells)
                     changed = True
             out_lines.append(line)
         if changed:
             open(p, "w", encoding="utf-8").write("".join(out_lines))
-            row_filled = True
+            rows_filled.append(name)
+            if name == "spec.md":
+                row_filled = True
 
 print(json.dumps({"ok": True, "version": ver, "stamped": stamped,
                   "unchanged": unchanged, "missing": missing,
@@ -5524,7 +5764,10 @@ print(json.dumps({"ok": True, "version": ver, "stamped": stamped,
                   # the ordinary outcome for a re-run (already filled) and for a change
                   # whose merge predates the pending convention.
                   "cr_id": cr, "history_row_filled": row_filled,
-                  "history_row_was": row_version}))
+                  "history_row_was": row_version,
+                  # Every document whose pending row was completed: spec.md, and the API
+                  # plan when the change merged an API delta into it.
+                  "history_rows_filled": rows_filled}))
 PY
 }
 
@@ -5538,6 +5781,7 @@ case "$sub" in
     set-domain)       cmd_set_domain "$@" ;;
     stack-list)       cmd_stack_list "$@" ;;
     stack-detect)     cmd_stack_detect "$@" ;;
+    stack-rules)      cmd_stack_rules "$@" ;;
     lane-declare)     cmd_lane_declare "$@" ;;
     lane-resolve)     cmd_lane_resolve "$@" ;;
     lane-verify)      cmd_lane_verify "$@" ;;
@@ -5551,6 +5795,9 @@ case "$sub" in
     contract-client)  cmd_contract_client "$@" ;;
     contract-check)   cmd_contract_check "$@" ;;
     contract-impact)  cmd_contract_impact "$@" ;;
+    contract-verify)  cmd_contract_verify "$@" ;;
+    contract-merge)   cmd_contract_merge "$@" ;;
+    api-split)        cmd_api_split "$@" ;;
     list-contexts)    cmd_list_contexts "$@" ;;
     set-context)      cmd_set_context "$@" ;;
     list-features)    cmd_list_features "$@" ;;
@@ -5588,11 +5835,14 @@ case "$sub" in
     context-version-bump) cmd_context_version_bump "$@" ;;
     context-paths)    cmd_context_paths "$@" ;;
     model-scaffold)   cmd_model_scaffold "$@" ;;
+    model-guard-snapshot) cmd_model_guard snapshot "$@" ;;
+    model-guard-check) cmd_model_guard check "$@" ;;
     version-stamp)    cmd_version_stamp "$@" ;;
     plan-gaps)        cmd_plan_gaps "$@" ;;
     plan-gate-stamp)  cmd_plan_gate_stamp "$@" ;;
     plan-gate-check)  cmd_plan_gate_check "$@" ;;
     plan-coverage)    cmd_plan_coverage "$@" ;;
+    test-citations)   cmd_test_citations "$@" ;;
     gap-route)        cmd_gap_route "$@" ;;
     checklist-read)   cmd_checklist_read "$@" ;;
     checklist-apply)  cmd_checklist_apply "$@" ;;