aw-spec-cli 0.1.32 → 0.1.34

package/assets/.appweaver/scripts/python/aw-stack.py

@@ -2,7 +2,7 @@
 """
 aw-stack — the lane model's deterministic core.
 
-Backs seventeen aw-spec-actions subcommands, called identically by the bash and the
+Backs twenty-one aw-spec-actions subcommands, called identically by the bash and the
 powershell twin so the two stay in parity by construction rather than by review:
 
     list      enumerate .appweaver/stack-profiles/ — the candidate list
@@ -18,51 +18,66 @@ powershell twin so the two stay in parity by construction rather than by review:
     slice-gate-stamp  one lane's analyze-slice-delta result, written into the change
     run-phase run a phase's command for EVERY declared lane, not just the first
     probe     is there evidence of a lane of this kind — read-only, never fatal
-    contract-export  start the service lane, fetch its API document, stop it
-    contract-draft   draft a feature's API document from its backend plan's API section
-    contract-combine the exported document plus every draft operation it does not serve
-    contract-requests  the frontend plan's contract requests and the backend plan's answers
+    rules     which stacks the active project's technical map has rule files for, and
+              the warning for a declared lane whose stack lacks them — read-only
+    contract-export  write the service lane's API document as built, the way the lane says
+    contract-draft   draft a feature's API document from its API plan, or a change's from
+                     its delta API plan
+    contract-combine every planned operation — the drafts, with the open changes applied —
+                     plus the operations the built service serves that no plan describes
+    contract-requests  the frontend plan's contract requests and the API plan's answers
     contract-check   the operation ids a frontend plan cites vs that document
     contract-impact  operations a change's service delta changes or removes that the
                      frontend binds to, with no matching frontend change
+    contract-verify  the API the built service serves vs the operations its plan names
+    contract-merge   a change's delta API plan, merged into its feature's API plan
+    api-split        a feature's API, moved out of its backend plan into an API plan
 
 This file is the only code that writes stacks.json, through two subcommands with
 different jobs. `declare` creates or replaces a whole lane and has exactly one caller —
 `select-stack`, where a person picks. `set` changes only the keys in CONTRACT_KEYS on a lane that is
 already there, and never its root, profile or phase commands: `foundation` records the
-API-export settings the pack it unpacked carries, and `implement` records the client
-command a developer supplies. Re-declaring a lane to change one key would reset every
+API-document settings the pack it unpacked or the spec it built from carries, and
+`implement` records the client command a developer supplies. Re-declaring a lane to change one key would reset every
 other command to the profile's default, which is why the two are separate. The `origin`
 key stays optional in the schema for a future caller that proposes a lane without a
 person in the loop; a reader that branches on it keeps working either way.
 
-THE API CONTRACT BETWEEN THE LANES. The service lane publishes an API document and the
-frontend lane generates its client from it. Three lane keys carry that, each read from
-the lane first and from its stack profile when the lane does not set it, so a lane
-declared before the keys existed answers them too:
-
-    contract_run  (backend)  the command that starts the service for the export
-    contract      (backend)  the URL the running service serves its document at
-    client        (frontend) the command that generates the client; `{{contract}}` in
-                             it is the exported document, as seen from where it runs
-
-The document is written to CONTRACT_DOC under the service lane root folder, so it is
-committed with the service that publishes it.
-
-THE BACKEND PUBLISHES, THE FRONTEND READS. The export runs where the service is worked on —
-implement's backend half, and build after a green compile — and never from a frontend run:
-a frontend developer may have neither the service's code built nor its runtime installed.
-What a frontend run reads is the committed document, plus a DRAFT for what is planned and
-not built yet: `contract-draft` turns each backend plan's API section into DRAFT_NAME beside
-the plan, by script, and `contract-combine` writes COMBINED_DOC — the exported document with
-every draft operation it does not serve yet added and marked `x-aw-draft`. The client is
-generated from the combined document, so a frontend can bind to an endpoint the backend has
-planned and not built; the draft operation drops out of it once the service serves its id.
+THE API CONTRACT BETWEEN THE LANES IS THE API PLAN. Each feature's API_PLAN_NAME, beside
+its backend plan, names the endpoints the service publishes, and `contract-draft` turns it
+into DRAFT_NAME, by script, so it exists on every stack and before any code does. A change
+that alters the API drafts its own, from its DELTA_API_PLAN_NAME, into its change folder,
+and `contract-merge` merges that delta into the API plan when the change is finalized —
+the API plan is a master, like spec.md, while the backend plan stays derived. A feature
+planned before the API plan existed keeps its endpoints in its backend plan's API section,
+which every reader here falls back to until `api-split` moves them out.
+The frontend lane binds to those: `contract-combine` writes COMBINED_DOC from every
+feature's draft with the open changes applied over it, and the frontend's client is
+generated from that. The frontend never needs the service built, started or installed.
+
+THE CODE IS CHECKED AGAINST THE PLAN, NOT READ FROM. `contract-export` writes the API the
+built service actually serves to CONTRACT_DOC under the service lane root folder, and
+`contract-verify` compares it with the operations the plan names — the backend gates run
+both, after their fix loops. The as-built document reaches the frontend only for the
+operations no plan describes, marked `x-aw-unplanned`: the endpoints of a brownfield
+feature nobody has adopted yet. Four lane keys carry the settings, each read from the lane
+first and from its stack profile when the lane does not set it:
+
+    contract_write (backend)  a command that writes the service's API document to
+                              `{{contract}}` — the stack's own generator, a script, any
+                              way that does not need the service running
+    contract_run   (backend)  the command that starts the service, when the document can
+                              only be fetched from it running …
+    contract       (backend)  … and the URL it serves the document at
+    client         (frontend) the command that generates the client; `{{contract}}` in
+                              it is the combined document, as seen from where it runs
+
+A lane that sets none of the backend keys writes no as-built document, and its API is not
+checked: no profile assumes a way, because starting a service runs its startup code.
 
 THE REQUEST LEDGER. A frontend plan asks for what the service does not offer in its §5
-"Contract deltas needed" table, one RQ-n row each; the backend plan answers in its API
-section's "Requests from the frontend lane" table, published as an operation id or declined
-with the reason. Each developer writes only their own plan, and `contract-requests` reads
+"Contract deltas needed" table, one RQ-n row each; the API plan answers in its "Requests
+from the frontend lane" table, published as an operation id or declined with the reason. Each developer writes only their own plan, and `contract-requests` reads
 both to say which requests are open, answered, declined, or answered and not re-bound yet.
 
 A person editing stacks.json in a text editor is the other way a lane arrives,
@@ -125,22 +140,31 @@ PROFILES_REL = ".appweaver/stack-profiles"
 LANE_REL = ".appweaver/lane.json"
 WORKING_LANES = ("backend", "frontend", "both")
 
-# Where the exported API document lands, relative to the service lane root folder.
+# Where the as-built API document lands, relative to the service lane root folder.
 CONTRACT_DOC = "contracts/openapi.json"
 
-# A feature's draft API document, beside the plans it is drafted from, and the combined
-# document a frontend generates its client from (repository-relative, not committed).
+# A feature's draft API document, beside the plans it is drafted from — and a change's,
+# in its change folder — and the combined document a frontend generates its client from
+# (repository-relative, not committed).
 DRAFT_NAME = "api-draft.json"
 COMBINED_DOC = ".appweaver/contracts/openapi.combined.json"
+# Where a `contract_write` command writes, before the document is checked and moved to
+# CONTRACT_DOC: a command that fails halfway leaves the committed document as it was.
+EXPORT_SCRATCH = ".appweaver/contracts/openapi.export.json"
 
 # Each lane's plan document, under its current name and its pre-lane-split one.
 BACKEND_PLAN_NAMES = ("backend-plan.md", "design.md")
 FRONTEND_PLAN_NAMES = ("frontend-plan.md", "design.ui.md")
 
+# The service's published API — its endpoint blocks and its answers to the frontend lane's
+# requests — beside the backend plan, and a change's API delta in its change folder.
+API_PLAN_NAME = "api-plan.md"
+DELTA_API_PLAN_NAME = "delta-api-plan.md"
+
 # The API-contract keys: the only ones `set` may change, and the ones read from the
 # stack profile when the lane does not set them (lane_value). Everything else on a lane
 # is the declaration itself and changes only through `declare`.
-CONTRACT_KEYS = ("contract_run", "contract", "client")
+CONTRACT_KEYS = ("contract_write", "contract_run", "contract", "client")
 
 # A lane id names the ROLE in the project; the profile names the technology.
 # Keeping them separate is what lets a project re-stack a lane without renaming
@@ -788,10 +812,11 @@ def lane_command(lane, phase, repo=None, contract=""):
     several. It is looked up when the command is read, so a project scaffolded after the
     lane was declared is found; with no single match it falls back to `{{root}}`.
 
-    `{{contract}}` is the API document a frontend lane's `client` command generates from,
-    named as seen from where THIS lane's command runs: `contract` when the caller passes
-    one (implement passes the combined document), else the service lane's exported
-    document (contract_doc). With neither it is left as written.
+    `{{contract}}` is the API document the command reads or writes, named as seen from
+    where THIS lane's command runs: `contract` when the caller passes one (implement passes
+    the combined document a `client` command generates from, contract-export the scratch
+    path a `contract_write` command writes to), else the service lane's as-built document
+    (contract_doc). With neither it is left as written.
     """
     if phase in CONTRACT_KEYS:
         cmd = lane_value(repo, lane, phase)
@@ -829,7 +854,7 @@ def lane_value(repo, lane, key):
 
 
 def contract_doc(repo, lanes=None):
-    """The service lane's exported API document, repo-relative; "" with no service lane."""
+    """The service lane's as-built API document, repo-relative; "" with no service lane."""
     if lanes is None:
         lanes = (read_stacks(repo) or {}).get("lanes") or []
     lane = next((l for l in lanes if l.get("kind") == "backend"), {})
@@ -1205,8 +1230,9 @@ def kind_block(repo, lanes, kind):
         kind + "_run": lane_command(lane, "run", repo),
         kind + "_migrate": lane_command(lane, "migrate", repo) or prof.get("migrate", ""),
         # The API-contract settings, the lane's own or its profile's (lane_value). A
-        # service lane uses the first two and a frontend lane the third; the others read
+        # service lane uses the first three and a frontend lane the last; the others read
         # empty on each.
+        kind + "_contract_write": lane_command(lane, "contract_write", repo),
         kind + "_contract_run": lane_command(lane, "contract_run", repo),
         kind + "_contract": lane_value(repo, lane, "contract"),
         kind + "_client": lane_command(lane, "client", repo),
@@ -1611,14 +1637,20 @@ def cmd_slice_gate_stamp(args):
     lane = args.lane
     truthy = lambda v: str(v or "").strip().lower() == "true"
     tests_green, requirements_ok = truthy(args.tests_green), truthy(args.requirements_ok)
-    # The findings are the lane check's own list. One that cannot be read is recorded as
-    # unreadable, never as none.
-    try:
-        findings = json.loads(args.findings) if (args.findings or "").strip() else []
-        if not isinstance(findings, list):
-            raise ValueError("not a list")
-    except ValueError:
-        findings = None
+    # The findings are the lane's own lists — the requirement check's and the test-citation
+    # check's — joined. One that cannot be read makes the count unreadable, never none.
+    findings = []
+    for raw in args.findings or []:
+        if not (raw or "").strip():
+            continue
+        try:
+            got = json.loads(raw)
+            if not isinstance(got, list):
+                raise ValueError("not a list")
+        except ValueError:
+            findings = None
+            break
+        findings.extend(got)
     high = (sum(1 for f in findings if isinstance(f, dict)
                 and str(f.get("severity", "")).strip().lower() == "high")
             if findings is not None else None)
@@ -1716,7 +1748,7 @@ def cmd_resolve(args):
         "language": profile_of(args.repo, match).get("language", ""),
         "ecosystem": profile_of(args.repo, match).get("ecosystem", ""),
         "prototype": data.get("prototype", {}),
-        # The service lane's exported API document, and whether an export has written it.
+        # The service lane's as-built API document, and whether contract-export has written it.
         "contract_doc": doc,
         "contract_doc_exists": bool(doc) and os.path.isfile(os.path.join(args.repo, doc)),
         "path": STACKS_REL,
@@ -2018,12 +2050,17 @@ def cmd_run_phase(args):
 
 
 # ─────────────────────────── contract-export ───────────────────────────────
-# The service lane's API document, taken from the service itself. A document served by a
-# running service is the one thing every web stack can produce the same way — Swagger,
-# springdoc, FastAPI and the rest all serve one — so the export starts the service with
-# the lane's `contract_run`, fetches `contract`, and stops it. How a stack (or the pack
-# the lane was scaffolded from) has to be started is the command's business, not this
-# code's.
+# The API the built service actually serves, written to CONTRACT_DOC so the backend gates
+# can check it against the plan (contract-verify). How a stack produces its document is the
+# lane's business, in one of two ways:
+#   WRITE  `contract_write` — a command that writes the document to `{{contract}}`: the
+#          stack's own generator, or a script that loads the application and dumps its
+#          document with no server started. Preferred: nothing of the service runs.
+#   FETCH  `contract_run` + `contract` — start the service, fetch the document from its URL,
+#          stop it and everything it started. For a stack that can only serve its document.
+# A lane that sets neither writes nothing, and says so. No profile assumes a way, because
+# starting a service runs its startup code — migrations, seeding, connections — wherever its
+# configuration points.
 
 CONTRACT_HTTP_METHODS = ("get", "put", "post", "delete", "options", "head", "patch", "trace")
 
@@ -2130,51 +2167,126 @@ def cmd_contract_export(args):
     lane = next((l for l in lanes if l.get("kind") == "backend"), {})
     doc_rel = contract_doc(repo, lanes)
     doc_abs = os.path.join(repo, doc_rel) if doc_rel else ""
-    cmd = lane_command(lane, "contract_run", repo)
+    write = lane_command(lane, "contract_write", repo, contract=EXPORT_SCRATCH) if lane else ""
+    cmd = lane_command(lane, "contract_run", repo) if lane else ""
     url = lane_value(repo, lane, "contract")
     result = {
-        "ok": False, "ran": False, "lane": lane.get("id", ""), "cmd": cmd, "url": url,
+        "ok": False, "ran": False, "lane": lane.get("id", ""),
+        # HOW the document was to be had — write | fetch | none — and, when it was not,
+        # WHY in one word: exited | timeout | http | not-openapi | not-written | no-way |
+        # no-lane | no-root. A caller words its message by the cause, never by the text.
+        "way": "none", "cause": "", "cmd": write or cmd, "url": url,
         "cwd": "", "doc": doc_rel, "doc_exists": bool(doc_abs) and os.path.isfile(doc_abs),
         "operations": 0, "unnamed": 0, "seconds": 0, "already_running": False,
         "reason": "", "log_tail": "",
-        # The placeholder a `client` command names the document by, spelled out for a
-        # prompt that asks for one — a workflow cannot write it literally, since the
-        # engine would read it as a variable.
+        # The placeholder a `client` or `contract_write` command names the document by,
+        # spelled out for a prompt that asks for one — a workflow cannot write it
+        # literally, since the engine would read it as a variable.
         "placeholder": "{{contract}}",
     }
 
     def done(**kw):
         result.update(kw)
         result["doc_exists"] = bool(doc_abs) and os.path.isfile(doc_abs)
+        if result["ok"]:
+            result["cause"] = "ok"
         # One line on which document a reader now has, for a prompt to quote.
         if result["ok"]:
-            result["status"] = "%s, exported from the built service in this run" % doc_rel
+            result["status"] = "%s, written from the built service in this run" % doc_rel
         elif result["doc_exists"]:
-            result["status"] = ("%s, from an earlier export — this run's failed, so it may "
-                                "be older than the code" % doc_rel)
+            result["status"] = ("%s, from an earlier run — this run's failed, so it may be "
+                                "older than the code" % doc_rel)
         else:
             result["status"] = ""
         emit(result)
 
+    def save(doc, seconds, note=""):
+        os.makedirs(os.path.dirname(doc_abs), exist_ok=True)
+        with open(doc_abs, "w", encoding="utf-8") as fh:
+            json.dump(doc, fh, indent=2)
+            fh.write("\n")
+        ops = _operations(doc)
+        done(ok=True, seconds=seconds, operations=len(ops),
+             unnamed=sum(1 for o in ops if not o["id"]), reason=note, log_tail="")
+
+    kept = lambda: " — the last written document is kept" if result["doc_exists"] else ""
     if not lane:
-        return done(reason="no service lane is declared in %s" % STACKS_REL)
+        return done(cause="no-lane", reason="no service lane is declared in %s" % STACKS_REL)
     if not root_on_disk(repo, lane.get("root", "")):
-        return done(reason="the service lane root folder '%s' is not on disk yet"
+        return done(cause="no-root", reason="the service lane root folder '%s' is not on disk yet"
                     % lane.get("root", ""))
-    if not url:
-        return done(reason="the service lane has no `contract` URL — set it in %s, or in "
-                           "its stack profile" % STACKS_REL)
+    workdir = lane_workdir(repo, lane)
 
-    # A service already answering at the URL is used as it is: a second instance could
-    # not bind the port anyway. It may be running older code than this run built, which
-    # the caller is told.
+    # WRITE — the command writes the document to the scratch path; only a document that
+    # reads as OpenAPI replaces the committed one.
+    if write:
+        result.update(way="write", cmd=write)
+        result["cwd"] = os.path.relpath(workdir, repo).replace("\\", "/")
+        scratch = os.path.join(repo, EXPORT_SCRATCH)
+        os.makedirs(os.path.dirname(scratch), exist_ok=True)
+        if os.path.isfile(scratch):
+            os.remove(scratch)
+        fd, log_path = tempfile.mkstemp(prefix="aw-contract-", suffix=".log")
+        log = os.fdopen(fd, "wb")
+        proc, started, exited = None, time.time(), None
+        try:
+            proc = _start(write, workdir, log)
+            result["ran"] = True
+            deadline = started + args.timeout
+            while time.time() < deadline:
+                if proc.poll() is not None:
+                    exited = proc.returncode
+                    break
+                time.sleep(0.5)
+        finally:
+            if proc is not None:
+                _stop(proc)
+            log.close()
+        seconds = int(time.time() - started)
+        tail = _tail(log_path)
+        try:
+            os.remove(log_path)
+        except OSError:
+            pass
+        if exited is None:
+            return done(cause="timeout", seconds=seconds, log_tail=tail,
+                        reason="`%s` did not finish within %d s%s" % (write, args.timeout, kept()))
+        if exited != 0:
+            return done(cause="exited", seconds=seconds, log_tail=tail,
+                        reason="`%s` exited (code %s)%s" % (write, exited, kept()))
+        if not os.path.isfile(scratch):
+            return done(cause="not-written", seconds=seconds, log_tail=tail,
+                        reason="`%s` finished but wrote nothing at {{contract}} (%s)%s"
+                        % (write, EXPORT_SCRATCH, kept()))
+        with open(scratch, "rb") as fh:
+            doc = _api_document(fh.read())
+        os.remove(scratch)
+        if doc is None:
+            return done(cause="not-openapi", seconds=seconds, log_tail=tail,
+                        reason="`%s` wrote a file that is not an OpenAPI or Swagger JSON "
+                               "document%s" % (write, kept()))
+        return save(doc, seconds)
+
+    if not url:
+        why = ("the service lane has a `contract_run` command but no `contract` URL to fetch "
+               "the document from" if cmd else
+               "the service lane sets no way to write its API document")
+        return done(cause="no-way", reason=why + " — set `contract_write` (a command that "
+                    "writes it to {{contract}}), or `contract_run` and `contract`, on the lane "
+                    "in %s" % STACKS_REL)
+
+    # FETCH — a service already answering at the URL is used as it is: a second instance
+    # could not bind the port anyway. It may be running older code than this run built,
+    # which the caller is told.
+    result["way"] = "fetch"
     status, body, _err = _fetch(url)
     proc, log_path, started, exited = None, "", time.time(), None
     if status != 200 or _api_document(body) is None:
         if not cmd:
-            return done(reason="the service lane has no `contract_run` command to start it "
-                               "— set it in %s, or in its stack profile" % STACKS_REL)
-        workdir = lane_workdir(repo, lane)
+            return done(cause="no-way",
+                        reason="nothing answers at %s and the service lane has no "
+                               "`contract_run` command to start it — set it in %s"
+                               % (url, STACKS_REL))
         result["cwd"] = os.path.relpath(workdir, repo).replace("\\", "/")
         fd, log_path = tempfile.mkstemp(prefix="aw-contract-", suffix=".log")
         log = os.fdopen(fd, "wb")
@@ -2208,31 +2320,25 @@ def cmd_contract_export(args):
     doc = _api_document(body) if status == 200 else None
     if doc is None:
         if exited is not None:
-            why = "`%s` exited (code %s) before %s answered" % (cmd, exited, url)
+            cause, why = "exited", "`%s` exited (code %s) before %s answered" % (cmd, exited, url)
         elif status == 200:
-            why = "%s answered, but not with an OpenAPI or Swagger JSON document" % url
+            cause, why = "not-openapi", ("%s answered, but not with an OpenAPI or Swagger JSON "
+                                         "document" % url)
         elif status:
-            why = "%s answered HTTP %d for %d s" % (url, status, seconds)
+            cause, why = "http", "%s answered HTTP %d for %d s" % (url, status, seconds)
         else:
-            why = "nothing answered at %s within %d s" % (url, args.timeout)
-        return done(seconds=seconds, log_tail=tail,
-                    reason=why + (" — the last exported document is kept" if result["doc_exists"] else ""))
-
-    os.makedirs(os.path.dirname(doc_abs), exist_ok=True)
-    with open(doc_abs, "w", encoding="utf-8") as fh:
-        json.dump(doc, fh, indent=2)
-        fh.write("\n")
-    ops = _operations(doc)
+            cause, why = "timeout", "nothing answered at %s within %d s" % (url, args.timeout)
+        return done(cause=cause, seconds=seconds, log_tail=tail, reason=why + kept())
     note = ("fetched from a service that was already running at %s — it may be older than "
-            "the code this run built" % url) if result["already_running"] else ""
-    done(ok=True, seconds=seconds, operations=len(ops),
-         unnamed=sum(1 for o in ops if not o["id"]), reason=note, log_tail="")
+            "the code being checked" % url) if result["already_running"] else ""
+    save(doc, seconds, note)
 
 
 # ─────────────────────────── contract-draft ────────────────────────────────
-# A feature's API document as its backend plan DESCRIBES it, for a frontend that binds
-# before the service is built. Read by script from the plan's API section, so it says
-# exactly what the plan says and is redrawn whenever plan or analyze-plan writes the plan.
+# A feature's API document as its API plan DESCRIBES it, for a frontend that binds before
+# the service is built. Read by script from the whole API plan — or, for a feature planned
+# before the API plan existed, from its backend plan's API section — so it says exactly what
+# the plan says and is redrawn whenever plan, analyze-plan or finalize-delta writes it.
 #
 # What it reads, in the plan template's own shapes:
 #   ### `VERB /route` — purpose · Serves …     one endpoint per heading
@@ -2241,7 +2347,8 @@ def cmd_contract_export(args):
 #   - **Success**: `201` → `{ field: type, … }`
 #   - **Errors** table: | Status | When | Body shape |
 #   - **Maps to**: `UseCase` (§2.2), whose Request / Response (DTO) stands in for a shape
-#     the endpoint names instead of spelling out
+#     the endpoint names instead of spelling out — read from the backend plan too, where
+#     the use cases live when the endpoints are in the API plan
 # Conceptual types become JSON schema: string, int, decimal, money, bool, date, datetime,
 # id<T>, enum(A|B), list<T>, map<K,V> and nested `{ … }`. A shape it cannot read is kept as
 # an untyped schema carrying the plan's text, and counted as unread.
@@ -2249,6 +2356,11 @@ def cmd_contract_export(args):
 _ENDPOINT = re.compile(r"^(#{2,6})\s+`?\s*(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+(/[^\s`]*)\s*`?\s*(.*)$",
                        re.I)
 _HEADING = re.compile(r"^#{1,6}\s+(.*)$")
+# An endpoint block's `- **Name**: value` bullet — the colon inside the bold, after it, or
+# absent; an optional `(…)` note after the name. The keys that name its operation id, first
+# match wins.
+_BULLET_FIELD = re.compile(r"^\s*[-*]\s+\*\*([^*]+)\*\*\s*(?:\([^)]*\))?\s*:?\s*(.*)$")
+_OP_ID_KEYS = ("operation id", "operationid", "operation")
 _FIELD = re.compile(r"^\s*([A-Za-z_][A-Za-z0-9_]*)\s*(\?)?\s*:\s*(.+?)\s*$", re.S)
 _RQ_ID = re.compile(r"\bRQ-\d+\b")
 
@@ -2333,18 +2445,25 @@ def _is_placeholder(s):
 
 
 class _Drafter(object):
-    """One backend plan's endpoints, as OpenAPI operations."""
+    """One plan's endpoints, as OpenAPI operations. `uses` is the text of another document
+    whose use cases the endpoints map to — the backend plan, beside an API plan."""
 
-    def __init__(self, text):
+    def __init__(self, text, uses=""):
         self.text = _strip_comments(text)
         self.unread = []
-        self.dtos = self._dto_index()
-
-    def _dto_index(self):
+        # Set while an error body is read: the template writes those by field name alone
+        # (`{ errors: [{ field, message }] }`), so a name with no type is what is expected
+        # there, not a shape the plan left unfinished.
+        self.lenient = False
+        self.dtos = self._dto_index(_strip_comments(uses))
+        self.dtos.update(self._dto_index(self.text))
+
+    @staticmethod
+    def _dto_index(text):
         """Request / Response (DTO) shapes by use-case name ("Name:request"), and by the
         type name a DTO is given when it is written `Name { … }`."""
         dtos, current = {}, ""
-        for line in self.text.splitlines():
+        for line in text.splitlines():
             h = _HEADING.match(line)
             if h:
                 ticks = re.findall(r"`([^`]+)`", h.group(1))
@@ -2379,6 +2498,11 @@ class _Drafter(object):
             return {"type": "array", "items": self.schema(m.group(2))}
         if s.endswith("[]"):
             return {"type": "array", "items": self.schema(s[:-2])}
+        # `[ … ]` is a list of what it holds — but only around an object, a base type or a
+        # named DTO, so a template placeholder such as `[type]` stays unread.
+        inner = s[1:-1].strip() if s.startswith("[") and s.endswith("]") else ""
+        if inner and (inner.startswith("{") or inner.lower() in _BASE_TYPES or inner in self.dtos):
+            return {"type": "array", "items": self.schema(inner)}
         m = re.match(r"^(map|dict|dictionary|record)\s*<\s*(.+)\s*>$", s, re.I)
         if m:
             parts = _split_top(m.group(2))
@@ -2403,8 +2527,10 @@ class _Drafter(object):
             return dict(base)
         if s in self.dtos:
             return self.schema(self.dtos[s])
-        # A named type the plan does not spell out, or prose — kept, never guessed.
-        self.unread.append(raw)
+        # A named type the plan does not spell out, or prose — kept, never guessed. In an
+        # error body it is not counted: a client reads an error by its status and code.
+        if not self.lenient:
+            self.unread.append(raw)
         return {"description": raw}
 
     def object_schema(self, body):
@@ -2414,7 +2540,16 @@ class _Drafter(object):
                 continue
             m = _FIELD.match(item)
             if not m:
-                self.unread.append(item)
+                # A field named with no type is still a field the client must send or read,
+                # so it is kept, untyped. Outside an error body it is also counted unread:
+                # the frontend's client gets no type for it.
+                bare = re.fullmatch(r"([A-Za-z_][A-Za-z0-9_]*)(\?)?", item.strip())
+                if bare:
+                    props[bare.group(1)] = {}
+                    if not bare.group(2):
+                        required.append(bare.group(1))
+                if not (bare and self.lenient):
+                    self.unread.append(item)
                 continue
             name, q, typ = m.groups()
             optional = bool(q) or typ.rstrip().endswith("?") or "(optional)" in typ.lower()
@@ -2453,9 +2588,10 @@ class _Drafter(object):
             return self.object_schema(fallback[1:-1])
         return self.schema(word)
 
-    def operations(self, plan_rel):
-        """[(path, method, operation)] in plan order."""
-        section = api_section(self.text)
+    def operations(self, plan_rel, whole=False):
+        """[(path, method, operation)] in plan order — from the whole text when it is an API
+        plan (`whole`), else from the plan's API section when it has one."""
+        section = None if whole else api_section(self.text)
         lines = (section if section is not None else self.text).splitlines()
         blocks, cur = [], None
         for line in lines:
@@ -2481,19 +2617,15 @@ class _Drafter(object):
         summary = re.split(r"\s+·\s+|\s+\|\s+", title)[0].strip()
         fields, errors = {}, []
         for line in b["lines"]:
-            m = re.match(r"^\s*[-*]\s+\*\*([^*]+)\*\*\s*(?:\([^)]*\))?\s*:?\s*(.*)$", line)
+            m = _BULLET_FIELD.match(line)
             if m:
                 fields[m.group(1).strip().rstrip(":").strip().lower()] = m.group(2).strip()
                 continue
             cells = _cells(line)
             if cells and re.fullmatch(r"[1-5]\d\d", cells[0].strip("` ")):
-                errors.append((cells[0].strip("` "), cells[1] if len(cells) > 1 else ""))
-        oid = ""
-        for key in ("operation id", "operationid", "operation"):
-            if key in fields:
-                ids = _op_ids(fields[key])
-                oid = ids[0] if ids else ""
-                break
+                errors.append((cells[0].strip("` "), cells[1] if len(cells) > 1 else "",
+                               cells[2] if len(cells) > 2 else ""))
+        oid = _fields_operation_id(fields)
         maps = ""
         if "maps to" in fields:
             ticks = re.findall(r"`([^`]+)`", fields["maps to"])
@@ -2506,8 +2638,8 @@ class _Drafter(object):
             op["operationId"] = oid
         if summary:
             op["summary"] = summary
-        op["description"] = ("Drafted from %s — what the backend plan says this endpoint will "
-                             "serve, not what the service serves." % plan_rel)
+        op["description"] = ("Drafted from %s — what the plan says this endpoint "
+                             "serves. The backend gates check the code against it." % plan_rel)
         op["x-aw-draft"] = True
 
         path_names = re.findall(r"\{([^}]+)\}", path)
@@ -2553,9 +2685,16 @@ class _Drafter(object):
         responses = {code: {"description": "Success"}}
         if result is not None and code != "204":
             responses[code]["content"] = {"application/json": {"schema": result}}
-        for err, when in errors:
+        for err, when, shape in errors:
             if err not in responses:
                 responses[err] = {"description": re.sub(r"\s+", " ", when).strip() or "Error"}
+                self.lenient = True
+                try:
+                    body = self.shape(shape) if shape.strip() else None
+                finally:
+                    self.lenient = False
+                if body:
+                    responses[err]["content"] = {"application/json": {"schema": body}}
         op["responses"] = responses
         return path, method, op
 
@@ -2589,35 +2728,203 @@ def _is_draft_file(path):
         return False
 
 
-def _draft_ids(doc):
-    """The operation ids a document carries only as draft operations."""
-    out = set()
-    for item in (doc.get("paths") or {}).values():
-        if isinstance(item, dict):
-            for method in CONTRACT_HTTP_METHODS:
-                op = item.get(method)
-                if isinstance(op, dict) and op.get("x-aw-draft") and op.get("operationId"):
-                    out.add(str(op["operationId"]))
+def api_source(fd):
+    """(path, whole) — where a feature's API is read from: its API plan, all of it, or the
+    backend plan of a feature planned before the API plan existed, its API section only.
+    ("", False) with neither."""
+    p = os.path.join(fd, API_PLAN_NAME)
+    if os.path.isfile(p):
+        return p, True
+    return _first_file(fd, BACKEND_PLAN_NAMES), False
+
+
+def delta_api_source(cr_dir):
+    """(path, whole) — where a change's API delta is read from: its delta API plan, or the
+    delta backend plan of a change planned before the delta API plan existed."""
+    p = os.path.join(cr_dir, DELTA_API_PLAN_NAME)
+    if os.path.isfile(p):
+        return p, True
+    return _first_file(cr_dir, DELTA_PLAN_NAMES["backend"]), False
+
+
+def _delta_contract_rows(text):
+    """[{id, change, method, path, shape}] from a change's "Contract deltas for the frontend
+    lane" table — one per operation the change adds, changes or removes."""
+    out, seen = [], set()
+    for header, rows in _tables(text):
+        ic, cc = _col(header, "operation id"), _col(header, "change")
+        if ic < 0 or cc < 0:
+            continue
+        kc, sc = _col(header, "contract"), _col(header, "shape")
+        for row in rows:
+            ids = _op_ids(row[ic]) if ic < len(row) else []
+            change = row[cc].lower() if cc < len(row) else ""
+            kind = ("removed" if re.search(r"remov|delet|retir", change)
+                    else "changed" if re.search(r"chang|modif|narrow|renam", change)
+                    else "added" if re.search(r"add|new|introduc", change) else "")
+            if not ids or not kind or ids[0] in seen or _is_placeholder(ids[0]):
+                continue
+            seen.add(ids[0])
+            m = re.search(r"\b(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+`?(/[^\s`|]*)",
+                          row[kc] if 0 <= kc < len(row) else "", re.I)
+            out.append({"id": ids[0], "change": kind,
+                        "method": m.group(1).lower() if m else "",
+                        "path": m.group(2).rstrip(".,;") if m else "",
+                        "shape": row[sc] if 0 <= sc < len(row) else ""})
     return out
 
 
-def cmd_contract_draft(args):
-    repo = args.repo
-    fd = args.feature_dir if os.path.isabs(args.feature_dir) else os.path.join(repo, args.feature_dir)
-    rel = lambda p: os.path.relpath(p, repo).replace("\\", "/") if p else ""
-    draft = os.path.join(fd, DRAFT_NAME)
-    # No feature named means no plan, never the repository root's.
-    plan = _first_file(fd, BACKEND_PLAN_NAMES) if args.feature_dir else ""
-    out = {"ok": True, "written": False, "removed": False, "path": rel(draft), "plan": rel(plan),
-           "operations": 0, "ids": [], "ids_csv": "", "unnamed": 0, "unread": [],
-           "unread_count": 0, "duplicates": [], "reason": ""}
+def _draft_change(repo, fd, cr, out, rel):
+    """The change's draft: changes/<cr>/DRAFT_NAME, from its delta API plan — or, for a
+    change planned before that existed, from its delta backend plan's API section.
+
+    An endpoint the change adds or changes is read from its block, written exactly as the
+    API plan writes one; the "Contract deltas" table says which of the two it is, and which
+    operations the change removes. A row with no block is drafted from the table alone —
+    its shapes then only as precise as that one cell."""
+    cr_dir = os.path.join(fd, "changes", cr)
+    draft = os.path.join(cr_dir, DRAFT_NAME)
+    out.update(cr=cr, path=rel(draft), added_ids=[], changed_ids=[], removed_ids=[],
+               from_table=[])
+    if not os.path.isdir(cr_dir):
+        out["reason"] = "change %s has no folder in %s" % (cr, rel(fd))
+        return emit(out)
+    plan, whole = delta_api_source(cr_dir)
+    out["plan"] = rel(plan)
     if not plan:
-        out["reason"] = "no backend plan in %s — nothing to draft" % rel(fd)
+        out["reason"] = ("change %s has no delta API plan and no delta backend plan — nothing "
+                         "to draft" % cr)
         return emit(out)
     text = _read(plan)
-    drafter = _Drafter(text)
+    # The use cases an endpoint maps to are the backend plans', the change's and the master's.
+    uses = "\n".join(_read(p) for p in (_first_file(cr_dir, DELTA_PLAN_NAMES["backend"]),
+                                        _first_file(fd, BACKEND_PLAN_NAMES)) if p) if whole else ""
+    rows = _delta_contract_rows(_strip_comments(text))
+    kinds = {r["id"]: r["change"] for r in rows}
+    master = {}
+    master_path = os.path.join(fd, DRAFT_NAME)
+    if os.path.isfile(master_path):
+        try:
+            master = {o["id"] for o in _operations(json.load(open(master_path, encoding="utf-8")))
+                      if o["id"]}
+        except Exception:
+            master = set()
+    section = text if whole else api_section(text)
+    drafter = _Drafter(section if section is not None else "", uses)
+    paths, seen, dupes, blocks = {}, set(), [], set()
+    for path, method, op in (drafter.operations(rel(plan), whole) if section is not None else []):
+        if (path, method) in seen:
+            dupes.append("%s %s" % (method.upper(), path))
+            continue
+        seen.add((path, method))
+        oid = op.get("operationId", "")
+        kind = kinds.get(oid) or ("changed" if oid in master else "added")
+        if kind == "removed":
+            continue
+        op["x-aw-change"], op["x-aw-cr"] = kind, cr
+        paths.setdefault(path, {})[method] = op
+        blocks.add(oid)
+        out["%s_ids" % kind].append(oid or "%s %s" % (method.upper(), path))
+    removed = []
+    for r in rows:
+        if r["change"] == "removed":
+            removed.append({k: r[k] for k in ("id", "method", "path")})
+            out["removed_ids"].append(r["id"])
+            continue
+        if r["id"] in blocks or not r["method"] or not r["path"]:
+            continue
+        # No block: the row's `request → response` cell is all there is to draft from.
+        parts = re.split(r"→|->", r["shape"], maxsplit=1)
+        op = {"operationId": r["id"],
+              "description": ("Drafted from %s, its Contract deltas table — the change gives "
+                              "this endpoint no block, so its shapes are only as precise as "
+                              "that table cell." % rel(plan)),
+              "x-aw-draft": True, "x-aw-change": r["change"], "x-aw-cr": cr}
+        body = drafter.shape(parts[0]) if len(parts) > 1 and r["method"] in ("post", "put", "patch") else None
+        if body is not None:
+            op["requestBody"] = {"required": True, "content": {"application/json": {"schema": body}}}
+        result_shape = drafter.shape(parts[-1]) if r["shape"].strip() else None
+        op["responses"] = {"200": {"description": "Success"}}
+        if result_shape is not None:
+            op["responses"]["200"]["content"] = {"application/json": {"schema": result_shape}}
+        path = re.sub(r":([A-Za-z_]\w*)", r"{\1}", r["path"])
+        names = re.findall(r"\{([^}]+)\}", path)
+        if names:
+            op["parameters"] = [{"name": n, "in": "path", "required": True,
+                                 "schema": {"type": "string"}} for n in names]
+        paths.setdefault(path, {})[r["method"]] = op
+        out["%s_ids" % r["change"]].append(r["id"])
+        out["from_table"].append(r["id"])
+    count = sum(len(v) for v in paths.values())
+    ids = [op["operationId"] for v in paths.values() for op in v.values() if op.get("operationId")]
+    out.update(operations=count, ids=ids, ids_csv=", ".join(ids), unnamed=count - len(ids),
+               unread=drafter.unread[:20], unread_count=len(drafter.unread),
+               unread_text="; ".join(drafter.unread[:20]) or "none", duplicates=dupes)
+    if not count and not removed:
+        if os.path.isfile(draft) and _is_draft_file(draft):
+            os.remove(draft)
+            out["removed"] = True
+        out["reason"] = ("%s changes no endpoint — its Contract deltas table names none, and it "
+                         "has no endpoint block such as ### `POST /route`" % rel(plan))
+        return emit(out)
+    doc = {
+        "openapi": "3.0.3",
+        "info": {
+            "title": "%s — API draft of change %s" % (os.path.basename(os.path.normpath(fd)), cr),
+            "version": "draft",
+            "description": ("Drafted by script from %s — the operations change %s adds or "
+                            "changes, and the ones it removes (x-aw-removed). Applied over the "
+                            "feature's draft while the change is open; finalize-delta merges "
+                            "the change into the feature's API plan. Rewritten by plan and "
+                            "analyze-plan-delta; do not edit." % (rel(plan), cr)),
+        },
+        "x-aw-draft": {"source": rel(plan), "source_sha": _sha_text(text), "cr": cr},
+        "paths": paths,
+    }
+    if removed:
+        doc["x-aw-removed"] = removed
+    body = json.dumps(doc, indent=2) + "\n"
+    if _read(draft) != body:
+        with open(draft, "w", encoding="utf-8") as fh:
+            fh.write(body)
+        out["written"] = True
+    emit(out)
+
+
+def _draft_result(rel, draft):
+    return {"ok": True, "written": False, "removed": False, "path": rel(draft), "plan": "",
+            "operations": 0, "ids": [], "ids_csv": "", "unnamed": 0, "unread": [],
+            "unread_count": 0, "unread_text": "none", "duplicates": [],
+            "dropped": [], "dropped_count": 0, "dropped_text": "none", "reason": ""}
+
+
+def _op_labels(doc):
+    """{key: label} for every operation of a document — keyed by operation id, or by verb and
+    route for one without an id."""
+    out = {}
+    for p, m, op in _doc_ops(doc):
+        oid = str(op.get("operationId") or "")
+        out[oid or _route_key(p, m)] = ("%s (%s %s)" % (oid, m.upper(), p)) if oid \
+            else "%s %s" % (m.upper(), p)
+    return out
+
+
+def _draft_master(repo, fd, rel):
+    """Redraw a feature's DRAFT_NAME from its API plan — or its backend plan's API section —
+    and return what it drafted, with every operation the draft it replaced had and this one
+    does not (`dropped`): the frontend may be bound to each."""
+    draft = os.path.join(fd, DRAFT_NAME)
+    out = _draft_result(rel, draft)
+    plan, whole = api_source(fd)
+    out["plan"] = rel(plan)
+    if not plan:
+        out["reason"] = "no API plan and no backend plan in %s — nothing to draft" % rel(fd)
+        return out
+    text = _read(plan)
+    uses = _read(_first_file(fd, BACKEND_PLAN_NAMES)) if whole else ""
+    drafter = _Drafter(text, uses)
     paths, ids, dupes, seen = {}, [], [], set()
-    for path, method, op in drafter.operations(rel(plan)):
+    for path, method, op in drafter.operations(rel(plan), whole):
         if (path, method) in seen:
             dupes.append("%s %s" % (method.upper(), path))
             continue
@@ -2626,28 +2933,35 @@ def cmd_contract_draft(args):
         if op.get("operationId"):
             ids.append(op["operationId"])
     count = sum(len(v) for v in paths.values())
+    before = _op_labels(_load_doc(draft)) if _is_draft_file(draft) else {}
+    now = _op_labels({"paths": paths})
+    dropped = [label for key, label in before.items() if key not in now]
     out.update(operations=count, ids=ids, ids_csv=", ".join(ids),
                unnamed=count - len(ids), unread=drafter.unread[:20],
-               unread_count=len(drafter.unread), duplicates=dupes)
+               unread_count=len(drafter.unread),
+               unread_text="; ".join(drafter.unread[:20]) or "none", duplicates=dupes,
+               dropped=dropped, dropped_count=len(dropped),
+               dropped_text=", ".join(dropped) or "none")
     if not count:
         # A draft this script wrote earlier would now describe endpoints the plan dropped.
         if os.path.isfile(draft) and _is_draft_file(draft):
             os.remove(draft)
             out["removed"] = True
-        out["reason"] = ("%s names no endpoint — no heading such as ### `POST /route` in its "
-                         "API section — so there is nothing to draft" % rel(plan))
-        return emit(out)
-    section = api_section(text)
+        out["reason"] = ("%s names no endpoint — no heading such as ### `POST /route`%s — so "
+                         "there is nothing to draft"
+                         % (rel(plan), "" if whole else " in its API section"))
+        return out
+    section = text if whole else api_section(text)
     doc = {
         "openapi": "3.0.3",
         "info": {
             "title": "%s — API draft" % os.path.basename(os.path.normpath(fd)),
             "version": "draft",
-            "description": ("Drafted by script from %s, its API section — what the backend "
-                            "plan says the service will serve, not what it serves. The "
-                            "service's exported document replaces each operation once it "
-                            "serves its id. Rewritten by plan and analyze-plan; do not edit."
-                            % rel(plan)),
+            "description": ("Drafted by script from %s%s — what the plan says the service "
+                            "serves. It is the contract the frontend lane binds to, and the "
+                            "one the backend gates check the code against. Rewritten by plan, "
+                            "analyze-plan, finalize-delta and adopt; do not edit."
+                            % (rel(plan), "" if whole else ", its API section")),
         },
         "x-aw-draft": {"source": rel(plan),
                        "source_sha": _sha_text(section if section is not None else text)},
@@ -2658,15 +2972,35 @@ def cmd_contract_draft(args):
         with open(draft, "w", encoding="utf-8") as fh:
             fh.write(body)
         out["written"] = True
-    emit(out)
+    return out
+
+
+def cmd_contract_draft(args):
+    repo = args.repo
+    fd = args.feature_dir if os.path.isabs(args.feature_dir) else os.path.join(repo, args.feature_dir)
+    rel = lambda p: os.path.relpath(p, repo).replace("\\", "/") if p else ""
+    if not args.feature_dir:
+        out = _draft_result(rel, os.path.join(fd, DRAFT_NAME))
+        out["reason"] = "no feature named — nothing to draft"
+        return emit(out)
+    if args.cr:
+        return _draft_change(repo, fd, args.cr, _draft_result(rel, os.path.join(fd, DRAFT_NAME)),
+                             rel)
+    emit(_draft_master(repo, fd, rel))
 
 
 # ─────────────────────────── contract-combine ──────────────────────────────
-# What a frontend generates its client from: the service's exported document, plus every
-# operation a backend plan has drafted that the document does not serve yet. A draft whose
-# id the service serves is dropped — the export is the truth for it — and one whose route
-# and verb the service already answers under another id is left out and reported, since
-# adding it would describe one endpoint twice.
+# What a frontend generates its client from. THE PLAN WINS: every operation a backend plan
+# drafts, with each OPEN change's draft applied over its feature's — an operation it adds
+# appears, one it changes is replaced, one it removes is kept and marked `deprecated` with
+# the change that removes it, so a frontend still bound to it is told rather than broken.
+# An operation an open change serves on the route of one an open change removes takes that
+# route: the removed one leaves `paths` for the document's `x-aw-removed` list, with its
+# route and the change, so a binding to it still reads as removed rather than missing.
+# The as-built document, when there is one, adds only what no plan describes, marked
+# `x-aw-unplanned`, and marks every planned operation it does not serve `x-aw-unserved`.
+# A clash — one operation drafted twice, or a route the service answers under another id —
+# is left out and reported, since adding it would describe one endpoint twice.
 
 def _draft_files(repo):
     base = os.path.join(repo, "specs")
@@ -2675,11 +3009,144 @@ def _draft_files(repo):
     return sorted(set(found))
 
 
+def _change_draft_files(repo):
+    """Every OPEN change's draft, oldest change first — changes/<cr>/DRAFT_NAME, never one
+    under changes/archive/. A change id carries its creation time, so its name orders it."""
+    base = os.path.join(repo, "specs")
+    found = glob.glob(os.path.join(base, "*", "changes", "*", DRAFT_NAME)) + \
+        glob.glob(os.path.join(base, "*", "*", "changes", "*", DRAFT_NAME))
+    found = [f for f in set(found) if os.path.basename(os.path.dirname(f)) != "archive"]
+    return sorted(found, key=lambda f: os.path.basename(os.path.dirname(f)))
+
+
 def _route_key(path, method):
     norm = re.sub(r"\{[^}]*\}", "{}", path.rstrip("/") or "/").lower()
     return norm, method.upper()
 
 
+def _doc_ops(doc):
+    """[(path, method, operation)] of a document, in document order."""
+    out = []
+    for path, item in ((doc or {}).get("paths") or {}).items():
+        if not isinstance(item, dict):
+            continue
+        for method in CONTRACT_HTTP_METHODS:
+            op = item.get(method)
+            if isinstance(op, dict):
+                out.append((path, method, op))
+    return out
+
+
+def _load_doc(path):
+    try:
+        with open(path, encoding="utf-8") as fh:
+            doc = json.load(fh)
+    except Exception:
+        return None
+    return doc if isinstance(doc, dict) and isinstance(doc.get("paths"), dict) else None
+
+
+class _Planned(object):
+    """The planned operations, keyed by id and by route: feature drafts, then open changes."""
+
+    def __init__(self):
+        self.paths, self.by_id, self.routes, self.clashes = {}, {}, {}, []
+        self.removed, self.retired, self.changes = [], [], []
+
+    def put(self, path, method, op):
+        self.paths.setdefault(path, {})[method] = op
+        oid = str(op.get("operationId") or "")
+        if oid:
+            self.by_id[oid] = (path, method)
+        self.routes[_route_key(path, method)] = oid
+
+    def drop(self, path, method):
+        op = self.paths.get(path, {}).pop(method, None)
+        if path in self.paths and not self.paths[path]:
+            del self.paths[path]
+        self.routes.pop(_route_key(path, method), None)
+        if op and op.get("operationId"):
+            self.by_id.pop(str(op["operationId"]), None)
+
+    def get(self, oid):
+        loc = self.by_id.get(oid)
+        return self.paths[loc[0]][loc[1]] if loc else None
+
+    def retire(self, path, method):
+        """Takes an operation an open change removes out of the paths, so the operation that
+        replaces it can have its route; it is listed in `retired`."""
+        op = self.paths[path][method]
+        oid, cr = str(op.get("operationId") or ""), op["x-aw-removed-by"]
+        if "%s (%s)" % (oid, cr) in self.removed:
+            self.removed.remove("%s (%s)" % (oid, cr))
+        self.retired.append({"id": oid, "method": method, "path": path, "cr": cr})
+        self.drop(path, method)
+
+    def add_draft(self, doc, source):
+        import copy
+        for path, method, op in _doc_ops(doc):
+            oid = str(op.get("operationId") or "")
+            if oid and oid in self.by_id:
+                self.clashes.append("%s drafted twice (%s)" % (oid, source))
+                continue
+            if _route_key(path, method) in self.routes:
+                self.clashes.append("%s %s drafted twice (%s)" % (method.upper(), path, source))
+                continue
+            new = copy.deepcopy(op)
+            new["x-aw-draft"], new["x-aw-draft-source"] = True, source
+            self.put(path, method, new)
+
+    def apply_change(self, doc, source, cr):
+        import copy
+        touched = False
+        for r in doc.get("x-aw-removed") or []:
+            op = self.get(str(r.get("id") or ""))
+            if op is not None:
+                op["deprecated"], op["x-aw-removed-by"] = True, cr
+                self.removed.append("%s (%s)" % (r["id"], cr))
+                touched = True
+        for path, method, op in _doc_ops(doc):
+            oid = str(op.get("operationId") or "")
+            prev = self.get(oid) if oid else None
+            if prev is not None:
+                if prev.get("x-aw-change-by") and prev["x-aw-change-by"] != cr:
+                    self.clashes.append("%s is changed by both %s and %s — %s, the later, is "
+                                        "applied" % (oid, prev["x-aw-change-by"], cr, cr))
+                self.drop(*self.by_id[oid])
+            key = _route_key(path, method)
+            held = self.get(self.routes.get(key) or "")
+            if held is not None and held.get("x-aw-removed-by"):
+                self.retire(*self.by_id[self.routes[key]])
+            if key in self.routes:
+                self.clashes.append("%s %s is %s in a draft and %s in change %s" % (
+                    method.upper(), path, self.routes[key] or "unnamed", oid or "unnamed", cr))
+                continue
+            new = copy.deepcopy(op)
+            new["x-aw-draft"], new["x-aw-draft-source"], new["x-aw-change-by"] = True, source, cr
+            self.put(path, method, new)
+            touched = True
+        if touched:
+            self.changes.append(cr)
+
+
+def planned_operations(repo, rel, changes=True):
+    """Every planned operation in the repository: _Planned, plus the files read."""
+    plan, drafts, change_files = _Planned(), [], []
+    for f in _draft_files(repo):
+        doc = _load_doc(f)
+        if doc is not None:
+            drafts.append(rel(f))
+            plan.add_draft(doc, rel(f))
+    for f in (_change_draft_files(repo) if changes else []):
+        doc = _load_doc(f)
+        if doc is not None:
+            change_files.append(rel(f))
+            cr = str((doc.get("x-aw-draft") or {}).get("cr") or
+                     os.path.basename(os.path.dirname(f)))
+            plan.apply_change(doc, rel(f), cr)
+    return plan, drafts, change_files
+
+
 def cmd_contract_combine(args):
     import copy
     repo = args.repo
@@ -2691,96 +3158,99 @@ def cmd_contract_combine(args):
         with open(export_abs, "rb") as fh:
             export = _api_document(fh.read())
     out_abs = os.path.join(repo, COMBINED_DOC)
+    plan, drafts, change_files = planned_operations(repo, rel)
+    planned_n = sum(len(v) for v in plan.paths.values())
     result = {"ok": False, "doc": "", "export": export_rel,
               "export_exists": export is not None, "export_operations": 0,
-              "drafts": [], "draft_files": 0, "draft_operations": 0,
-              "added": 0, "added_ids": [], "added_csv": "", "served_csv": "",
+              "drafts": drafts, "draft_files": len(drafts),
+              "change_drafts": change_files, "changes_applied": plan.changes,
+              "changes_csv": ", ".join(plan.changes),
+              "planned": planned_n, "planned_ids": sorted(plan.by_id),
+              "removed_csv": ", ".join(plan.removed + ["%s (%s)" % (r["id"], r["cr"])
+                                                       for r in plan.retired]),
+              "unplanned": [], "unplanned_csv": "", "unserved": [], "unserved_csv": "",
               "clashes": [], "clashes_csv": "", "status": "", "reason": "",
               # The placeholder a `client` command names the document by, spelled out for
               # a prompt that asks for one (see contract-export).
               "placeholder": "{{contract}}"}
 
-    combined = copy.deepcopy(export) if export else {
+    combined = {
         "openapi": "3.0.3",
-        "info": {"title": "API — drafts only", "version": "draft",
-                 "description": ("No exported document yet: every operation here is drafted "
-                                 "from a backend plan and none is served.")},
-        "paths": {},
+        "info": {"title": "API — planned", "version": "plan",
+                 "description": ("The contract the frontend binds to: every operation the "
+                                 "features' API plans draft, with each open change applied. "
+                                 "Written by contract-combine on every frontend implement; do "
+                                 "not edit.")},
+        "paths": plan.paths,
     }
-    combined.setdefault("paths", {})
-    export_ops = _operations(export) if export else []
-    export_ids = {o["id"] for o in export_ops if o["id"]}
-    routes = {_route_key(o["path"], o["method"]) for o in export_ops}
-    added_ids = set()
-    added, served, clashes = [], [], []
-    drafts = _draft_files(repo)
-    for f in drafts:
-        try:
-            with open(f, encoding="utf-8") as fh:
-                doc = json.load(fh)
-        except Exception:
-            continue
-        if not isinstance(doc, dict) or not isinstance(doc.get("paths"), dict):
-            continue
-        result["drafts"].append(rel(f))
-        for path, item in doc["paths"].items():
-            if not isinstance(item, dict):
+    if plan.retired:
+        combined["x-aw-removed"] = plan.retired
+    unplanned, unserved = [], []
+    if export is not None:
+        ops = _doc_ops(export)
+        result["export_operations"] = len(ops)
+        served_ids, served_routes = set(), set()
+        for path, method, op in ops:
+            oid = str(op.get("operationId") or "")
+            key = _route_key(path, method)
+            served_routes.add(key)
+            if oid and oid in plan.by_id:
+                served_ids.add(oid)
+                continue
+            if key in plan.routes:
+                if plan.routes[key] and oid:
+                    plan.clashes.append("the service answers %s %s as %s; the plan names it %s"
+                                        % (method.upper(), path, oid, plan.routes[key]))
                 continue
-            for method in CONTRACT_HTTP_METHODS:
-                op = item.get(method)
-                if not isinstance(op, dict):
+            new = copy.deepcopy(op)
+            new["x-aw-unplanned"] = True
+            plan.put(path, method, new)
+            unplanned.append(oid or "%s %s" % (method.upper(), path))
+        for path, item in plan.paths.items():
+            for method, op in item.items():
+                if op.get("x-aw-unplanned") or op.get("x-aw-removed-by"):
                     continue
-                result["draft_operations"] += 1
                 oid = str(op.get("operationId") or "")
-                if oid and oid in export_ids:
-                    served.append(oid)
-                    continue
-                if oid and oid in added_ids:
-                    clashes.append("%s drafted twice (%s)" % (oid, rel(f)))
+                if (oid and oid in served_ids) or _route_key(path, method) in served_routes:
                     continue
-                key = _route_key(path, method)
-                if key in routes:
-                    clashes.append("%s %s (%s) — the service already answers it under another id"
-                                   % (method.upper(), path, oid or "no id"))
-                    continue
-                new = copy.deepcopy(op)
-                new["x-aw-draft"] = True
-                new["x-aw-draft-source"] = rel(f)
-                combined["paths"].setdefault(path, {})[method] = new
-                routes.add(key)
-                if oid:
-                    added_ids.add(oid)
-                added.append(oid or "%s %s" % (method.upper(), path))
-    result.update(draft_files=len(result["drafts"]), export_operations=len(export_ops),
-                  added=len(added), added_ids=added, added_csv=", ".join(added),
-                  served_csv=", ".join(served), clashes=clashes, clashes_csv="; ".join(clashes))
-
-    if export is None and not added:
+                op["x-aw-unserved"] = True
+                unserved.append(oid or "%s %s" % (method.upper(), path))
+    result.update(unplanned=unplanned, unplanned_csv=", ".join(unplanned),
+                  unserved=unserved, unserved_csv=", ".join(unserved),
+                  clashes=plan.clashes, clashes_csv="; ".join(plan.clashes))
+
+    if not plan.paths:
         # Nothing to read: a combined document left from an earlier run would be stale.
         if os.path.isfile(out_abs):
             os.remove(out_abs)
-        result["reason"] = ("the service has not published %s and no backend plan has a draft "
-                            "(%s) — there is no API document to bind to"
-                            % (export_rel or "an API document (no service lane)", DRAFT_NAME))
+        result["reason"] = ("no plan drafts an endpoint (%s)%s — there is no API "
+                            "document to bind to" % (DRAFT_NAME, "" if export is not None else
+                            ", and the service lane has written no as-built document"))
         return emit(result)
 
     os.makedirs(os.path.dirname(out_abs), exist_ok=True)
     with open(out_abs, "w", encoding="utf-8") as fh:
         json.dump(combined, fh, indent=2)
         fh.write("\n")
-    if export is not None and added:
-        status = ("%s — the service's exported document (%s, %d operation(s)) plus %d "
-                  "operation(s) drafted from the backend plans that it does not serve yet, "
-                  "marked x-aw-draft: %s" % (COMBINED_DOC, export_rel, len(export_ops),
-                                             len(added), ", ".join(added)))
-    elif export is not None:
-        status = ("%s — the service's exported document (%s, %d operation(s)); no drafted "
-                  "operation is missing from it" % (COMBINED_DOC, export_rel, len(export_ops)))
+    parts = ["%s — %d planned operation(s) from %d feature draft(s)"
+             % (COMBINED_DOC, planned_n, len(drafts))]
+    if plan.changes:
+        parts.append("with the open change(s) %s applied" % ", ".join(plan.changes))
+    if plan.removed:
+        parts.append("marked deprecated because an open change removes them: %s"
+                     % ", ".join(plan.removed))
+    if plan.retired:
+        parts.append("replaced on their route by an open change's operation, and listed in "
+                     "x-aw-removed: %s" % ", ".join("%s (%s)" % (r["id"], r["cr"])
+                                                    for r in plan.retired))
+    if export is not None:
+        parts.append("compared with the service's as-built document %s (%d operation(s)): "
+                     "%s planned operation(s) it does not serve yet (x-aw-unserved), %d it "
+                     "serves that no plan describes (x-aw-unplanned)"
+                     % (export_rel, result["export_operations"], len(unserved), len(unplanned)))
     else:
-        status = ("%s — %d operation(s) drafted from the backend plans, marked x-aw-draft; the "
-                  "service has not published %s yet, so none of them is served: %s"
-                  % (COMBINED_DOC, len(added), export_rel or "an API document", ", ".join(added)))
-    result.update(ok=True, doc=COMBINED_DOC, status=status)
+        parts.append("no as-built document, so which of them the service serves is not known")
+    result.update(ok=True, doc=COMBINED_DOC, status="; ".join(parts))
     emit(result)
 
 
@@ -2788,11 +3258,12 @@ def cmd_contract_combine(args):
 # The request ledger between the lanes, read from both plans:
 #   frontend plan §5 "Contract deltas needed" — | Request | Operation id | Needed by |
 #     Sends | Receives | Serves |, one RQ-n per row, the operation id it proposes
-#   backend plan's API section "Requests from the frontend lane" — | Request | Outcome |
-#     Operation id | Why |, `published` with the id that serves it, or `declined` with why
+#   the API plan's "Requests from the frontend lane" — | Request | Outcome | Operation id |
+#     Why |, `published` with the id that serves it, or `declined` with why (the backend
+#     plan's API section, for a feature planned before the API plan existed)
 # A request is OPEN until the backend answers it — and still open when the answer names an
-# id the backend plan has no endpoint for. A PUBLISHED request whose id no frontend binding
-# row cites yet is to RE-BIND. A DECLINED one goes back to the frontend plan.
+# id the API plan has no endpoint for. A PUBLISHED request whose id no frontend binding row
+# cites yet is to RE-BIND. A DECLINED one goes back to the frontend plan.
 
 def _tables(text):
     """Every markdown table: (lowered header cells, [row cells])."""
@@ -2863,12 +3334,34 @@ def backend_answers(text):
     return answers
 
 
+def _fields_operation_id(fields):
+    """The operation id a block's bullets ({lowered name: value}) name; "" when none does."""
+    for key in _OP_ID_KEYS:
+        if key in fields:
+            ids = _op_ids(fields[key])
+            return ids[0] if ids else ""
+    return ""
+
+
 def backend_operation_ids(text):
-    ids = []
-    for value in re.findall(r"\*\*Operation id\*\*\s*:\s*(.+)", _strip_comments(text)):
-        for x in _op_ids(value)[:1]:
-            if x not in ids:
-                ids.append(x)
+    """The operation id of each endpoint block in `text`, in order, read as contract-draft
+    reads it: the block runs from its `VERB /route` heading to the next heading."""
+    ids, fields = [], None
+
+    def close():
+        x = _fields_operation_id(fields) if fields is not None else ""
+        if x and x not in ids:
+            ids.append(x)
+
+    for line in _strip_comments(text).splitlines():
+        if _ENDPOINT.match(line) or _HEADING.match(line):
+            close()
+            fields = {} if _ENDPOINT.match(line) else None
+            continue
+        m = _BULLET_FIELD.match(line) if fields is not None else None
+        if m:
+            fields[m.group(1).strip().rstrip(":").strip().lower()] = m.group(2).strip()
+    close()
     return ids
 
 
@@ -2876,7 +3369,9 @@ def cmd_contract_requests(args):
     repo = args.repo
     fd = args.feature_dir if os.path.isabs(args.feature_dir) else os.path.join(repo, args.feature_dir)
     fe_plan = _first_file(fd, FRONTEND_PLAN_NAMES) if args.feature_dir else ""
-    be_plan = _first_file(fd, BACKEND_PLAN_NAMES) if args.feature_dir else ""
+    # The backend answers in the API plan — in its backend plan, for a feature planned
+    # before the API plan existed.
+    be_plan = api_source(fd)[0] if args.feature_dir else ""
     fe_text, be_text = _read(fe_plan), _read(be_plan)
     reqs = frontend_requests(fe_text) if fe_plan else []
     answers = backend_answers(be_text) if be_plan else {}
@@ -2891,7 +3386,7 @@ def cmd_contract_requests(args):
                          ("needed_by", "sends", "receives", "serves") if r[k])
         ask = "%s — proposed `%s`%s" % (r["id"], r["proposed"] or "—", (" (%s)" % need) if need else "")
         if not be_plan or not a.get("outcome"):
-            r.update(status="open", answer="", why="" if be_plan else "no backend plan yet")
+            r.update(status="open", answer="", why="" if be_plan else "no API plan yet")
         elif a["outcome"] == "declined":
             r.update(status="declined", answer="", why=a["why"])
         else:
@@ -2900,7 +3395,7 @@ def cmd_contract_requests(args):
                 r.update(status="published", answer=served, why=a["why"])
             else:
                 r.update(status="open", answer="",
-                         why="answered as `%s`, but the backend plan has no endpoint with that id"
+                         why="answered as `%s`, but the API plan has no endpoint with that id"
                              % (served or "—"))
         r["rebind"] = r["status"] == "published" and r["answer"] not in bound
         if r["status"] == "open":
@@ -2908,7 +3403,7 @@ def cmd_contract_requests(args):
             be_lines.append(ask + ((" — " + r["why"]) if r["why"] else ""))
         elif r["status"] == "declined":
             declined.append(r["id"])
-            fe_lines.append("%s was DECLINED by the backend plan (%s) — plan the experience "
+            fe_lines.append("%s was DECLINED by the API plan (%s) — plan the experience "
                             "without it, or route the need to /appweaver specify"
                             % (r["id"], r["why"] or "no reason given"))
         else:
@@ -2925,6 +3420,9 @@ def cmd_contract_requests(args):
         "ok": True,
         "frontend_plan": os.path.relpath(fe_plan, repo).replace("\\", "/") if fe_plan else "",
         "backend_plan": os.path.relpath(be_plan, repo).replace("\\", "/") if be_plan else "",
+        # Which document `backend_plan` is: the API plan, or a backend plan that still
+        # carries its API section.
+        "answers_in_api_plan": os.path.basename(be_plan) == API_PLAN_NAME if be_plan else False,
         "requests": reqs,
         "count": len(reqs),
         "open": open_, "open_count": len(open_), "open_csv": ", ".join(open_),
@@ -2940,7 +3438,7 @@ def cmd_contract_requests(args):
 
 
 # ─────────────────────────── contract-check ────────────────────────────────
-# Do the operation ids a frontend plan cites exist in the exported document? Read by
+# Do the operation ids a frontend plan cites exist in the combined document? Read by
 # script, so the answer does not depend on a model reading two documents carefully.
 #
 # The ids are read from two table shapes, the two plan templates' own:
@@ -3010,8 +3508,9 @@ def plan_operation_ids(text):
 
 # ─────────────────────────── contract-impact ───────────────────────────────
 # Does a change's SERVICE delta change or remove an operation the frontend binds to, with no
-# matching change on the frontend side? The service delta's "Contract deltas for the
-# frontend lane" table names each operation it adds, changes or removes; the frontend master
+# matching change on the frontend side? The change's "Contract deltas for the frontend lane"
+# table — in its delta API plan, or in the delta backend plan of a change planned before
+# that existed — names each operation it adds, changes or removes; the frontend master
 # plan's binding rows name the ids it calls. A changed or removed id the master binds to is
 # AFFECTED, and it is ADDRESSED when the change's frontend delta plan names it anywhere. What
 # is left is reported as a warning, never a refusal: the frontend half may be planned later
@@ -3040,7 +3539,9 @@ def cmd_contract_impact(args):
     absolute = lambda p: (p if os.path.isabs(p) else os.path.join(repo, p)) if p else ""
     be_delta, fe_plan, fe_delta = (absolute(args.delta_backend), absolute(args.frontend_plan),
                                    absolute(args.delta_frontend))
-    changes = service_delta_changes(_read(be_delta)) if be_delta else []
+    api_delta = os.path.join(os.path.dirname(be_delta), DELTA_API_PLAN_NAME) if be_delta else ""
+    table_from = api_delta if api_delta and os.path.isfile(api_delta) else be_delta
+    changes = service_delta_changes(_read(table_from)) if table_from else []
     bound = plan_operation_ids(_read(fe_plan))[0] if fe_plan and os.path.isfile(fe_plan) else []
     fe_delta_exists = bool(fe_delta) and os.path.isfile(fe_delta)
     fe_delta_text = _strip_comments(_read(fe_delta)) if fe_delta_exists else ""
@@ -3065,12 +3566,13 @@ def cmd_contract_impact(args):
 def cmd_contract_check(args):
     repo = args.repo
     plan_abs = args.plan if os.path.isabs(args.plan) else os.path.join(repo, args.plan)
-    doc_rel = args.doc or contract_doc(repo)
+    doc_rel = args.doc or COMBINED_DOC
     doc_abs = (doc_rel if os.path.isabs(doc_rel) else os.path.join(repo, doc_rel)) if doc_rel else ""
     result = {"ok": False, "plan": args.plan, "doc": doc_rel,
               "doc_exists": bool(doc_abs) and os.path.isfile(doc_abs),
               "cited": 0, "ids": [], "missing": [], "uncited": 0,
-              "drafted": [], "drafted_csv": "",
+              "removed": [], "removed_csv": "", "unserved": [], "unserved_csv": "",
+              "unplanned": [], "unplanned_csv": "",
               "doc_operations": 0, "doc_unnamed": 0, "reason": ""}
     if not os.path.isfile(plan_abs):
         result["reason"] = "the frontend plan %s is not on disk" % args.plan
@@ -3079,34 +3581,42 @@ def cmd_contract_check(args):
         cited, uncited = plan_operation_ids(fh.read())
     result.update(cited=len(cited), ids=cited, uncited=uncited)
     if not result["doc_exists"]:
-        result["reason"] = "no exported API document at %s" % (doc_rel or "(no service lane)")
+        result["reason"] = "no API document at %s" % (doc_rel or "(no service lane)")
         return emit(result)
     with open(doc_abs, "rb") as fh:
         doc = _api_document(fh.read())
     if doc is None:
         result["reason"] = "%s is not an OpenAPI or Swagger JSON document" % doc_rel
         return emit(result)
-    ops = _operations(doc)
-    known = {o["id"] for o in ops if o["id"]}
-    lower = {k.lower(): k for k in known}
+    ops = _doc_ops(doc)
+    by_id = {str(op.get("operationId")): op for _p, _m, op in ops if op.get("operationId")}
+    lower = {k.lower(): k for k in by_id}
+    # An operation an open change removes and another operation replaces on its route is
+    # out of the paths, in the combined document's x-aw-removed list.
+    retired = {str(r["id"]): str(r.get("cr") or "") for r in doc.get("x-aw-removed") or []
+               if isinstance(r, dict) and r.get("id")}
     missing = []
     for x in cited:
-        if x not in known:
+        if x not in by_id and x not in retired:
             near = lower.get(x.lower())
             missing.append(x + (" (the document has %s)" % near if near else ""))
-    # A cited id the document has only as a draft operation binds, and fails at run time
-    # until the service serves it.
-    drafted = [x for x in cited if x in _draft_ids(doc)]
+    # What the combined document says about a cited operation that IS there: an open
+    # change removes it, the service does not serve it yet, or the service serves it and
+    # no plan describes it.
+    removed = ["%s (%s)" % (x, by_id[x]["x-aw-removed-by"]) for x in cited
+               if x in by_id and by_id[x].get("x-aw-removed-by")]
+    removed += ["%s (%s)" % (x, retired[x]) for x in cited if x not in by_id and x in retired]
+    unserved = [x for x in cited if x in by_id and by_id[x].get("x-aw-unserved")]
+    unplanned = [x for x in cited if x in by_id and by_id[x].get("x-aw-unplanned")]
     result.update(missing=missing, doc_operations=len(ops),
-                  doc_unnamed=sum(1 for o in ops if not o["id"]),
-                  drafted=drafted, drafted_csv=", ".join(drafted))
+                  doc_unnamed=sum(1 for _p, _m, op in ops if not op.get("operationId")),
+                  removed=removed, removed_csv=", ".join(removed),
+                  unserved=unserved, unserved_csv=", ".join(unserved),
+                  unplanned=unplanned, unplanned_csv=", ".join(unplanned))
     parts = []
     if missing:
         parts.append("%d cited operation id(s) are not in %s: %s"
                      % (len(missing), doc_rel, ", ".join(missing)))
-    if drafted:
-        parts.append("%d cited operation id(s) are drafts the service does not serve yet: %s"
-                     % (len(drafted), ", ".join(drafted)))
     if not cited:
         parts.append("the plan cites no operation id")
     if uncited:
@@ -3116,6 +3626,827 @@ def cmd_contract_check(args):
     emit(result)
 
 
+# ─────────────────────────── contract-verify ───────────────────────────────
+# Does the built service serve what its plan says? The as-built document (contract-export)
+# against the operations THIS feature's plan names — never the whole service's, since a
+# feature is gated on its own surface. A planned operation the service does not serve, or
+# serves under another route, verb or id, is a finding that fails the gate: the frontend is
+# bound to the plan and its calls would fail. A field or status code that differs is
+# reported and never fails — the plan writes conceptual types, and a nullable or a casing
+# convention is not always a defect. So is an operation the service serves that no plan in
+# the repository describes, which a brownfield service has many of.
+#
+# Two modes. MASTER (analyze-slice): the feature's draft, with every change applied that
+# is merged and still open — on the change path this gate runs after finalize-delta and
+# before close-delta, when the change is in spec.md and not yet in the re-derived plan.
+# CHANGE (analyze-slice-delta, --cr): that change's draft alone — what it adds or changes
+# must be served as drafted, and what it removes must no longer be served.
+# A removed operation is still served when the service serves its id, or answers its route
+# while the plan keeps no other operation on it — a route the plan keeps an operation on is
+# that operation's, and the planned check reads what the service answers there.
+# `--check` reads no as-built document: it reports whether the plan names anything to check
+# (`needed`), so the gates write that document only for a feature or change that does.
+
+def _crstate():
+    """aw-crstate.py, loaded by path like _testlog — the one definition of "merged"."""
+    try:
+        import importlib.util
+        path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "aw-crstate.py")
+        spec = importlib.util.spec_from_file_location("aw_crstate", path)
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        return mod
+    except Exception:
+        return None
+
+
+def _resolve(doc, sch, depth=0):
+    """A schema with local $ref and allOf followed — enough to read its field names."""
+    if not isinstance(sch, dict) or depth > 8:
+        return sch if isinstance(sch, dict) else {}
+    ref = sch.get("$ref")
+    if isinstance(ref, str) and ref.startswith("#/"):
+        node = doc
+        for part in ref[2:].split("/"):
+            node = node.get(part.replace("~1", "/").replace("~0", "~"), {}) \
+                if isinstance(node, dict) else {}
+        return _resolve(doc, node, depth + 1)
+    if sch.get("allOf"):
+        merged = {"type": "object", "properties": {}}
+        for part in sch["allOf"]:
+            merged["properties"].update(_resolve(doc, part, depth + 1).get("properties") or {})
+        return merged
+    return sch
+
+
+def _field_names(doc, sch):
+    """The top-level field names of a body, or None when its schema names none."""
+    r = _resolve(doc, sch or {})
+    if r.get("type") == "array" or "items" in r:
+        r = _resolve(doc, r.get("items") or {})
+    props = r.get("properties")
+    return set(props) if isinstance(props, dict) and props else None
+
+
+def _request_schema(op):
+    body = (((op.get("requestBody") or {}).get("content") or {})
+            .get("application/json") or {}).get("schema")
+    if body is None:
+        for prm in op.get("parameters") or []:          # Swagger 2 keeps the body here
+            if isinstance(prm, dict) and prm.get("in") == "body":
+                return prm.get("schema")
+    return body
+
+
+def _success(op):
+    """(status, schema) of an operation's first 2xx response, and every 2xx it declares."""
+    codes = sorted(str(c) for c in (op.get("responses") or {}) if str(c).startswith("2"))
+    for code in codes:
+        r = op["responses"].get(code) or op["responses"].get(int(code)) or {}
+        if isinstance(r, dict):
+            sch = (((r.get("content") or {}).get("application/json") or {}).get("schema")
+                   or r.get("schema"))
+            return code, sch, codes
+    return "", None, codes
+
+
+def _differences(plan_doc, planned, served_doc, served):
+    """What a served operation states differently from its planned one, in words."""
+    notes = []
+    pa = _field_names(plan_doc, _request_schema(planned))
+    pb = _field_names(served_doc, _request_schema(served))
+    if pa is not None and pb is not None and pa != pb:
+        notes.append("request fields — the plan has %s, the service %s"
+                     % (", ".join(sorted(pa)) or "none", ", ".join(sorted(pb)) or "none"))
+    code_a, sch_a, _codes_a = _success(planned)
+    code_b, sch_b, codes_b = _success(served)
+    if code_a and codes_b and code_a not in codes_b:
+        notes.append("success status — the plan says %s, the service answers %s"
+                     % (code_a, ", ".join(codes_b)))
+    pa, pb = _field_names(plan_doc, sch_a), _field_names(served_doc, sch_b)
+    if pa is not None and pb is not None and pa != pb:
+        notes.append("response fields — the plan has %s, the service %s"
+                     % (", ".join(sorted(pa)) or "none", ", ".join(sorted(pb)) or "none"))
+    return notes
+
+
+def _verify_plan(fd, cr, rel):
+    """(plan, planned, removed, note) — what contract-verify checks: with `cr` that change's
+    draft alone, else the feature's draft with every change applied that is merged and still
+    open. `planned` is [(path, method, op)] the service must serve, `removed` what it must no
+    longer serve; `note` says why there is nothing to check, and is "" when there is."""
+    plan = _Planned()
+    if cr:
+        f = os.path.join(fd, "changes", cr, DRAFT_NAME)
+        doc = _load_doc(f)
+        if doc is None:
+            return plan, [], [], "change %s drafts no API change — nothing to check" % cr
+        plan.apply_change(doc, rel(f), cr)
+        removed = [dict(r, cr=cr) for r in doc.get("x-aw-removed") or []]
+    else:
+        f = os.path.join(fd, DRAFT_NAME)
+        doc = _load_doc(f)
+        if doc is not None:
+            plan.add_draft(doc, rel(f))
+        crs, spec_text = _crstate(), _read(os.path.join(fd, "spec.md"))
+        removed = []
+        for c in sorted(glob.glob(os.path.join(fd, "changes", "*", DRAFT_NAME))):
+            cid = os.path.basename(os.path.dirname(c))
+            change = _load_doc(c)
+            if cid == "archive" or change is None or not crs or not crs.merged_row(spec_text, cid):
+                continue
+            plan.apply_change(change, rel(c), cid)
+            removed += [dict(r, cr=cid) for r in change.get("x-aw-removed") or []]
+    planned = [(p, m, op) for p, item in plan.paths.items() for m, op in item.items()
+               if not op.get("x-aw-removed-by")]
+    note = "" if planned or removed else \
+        "the plan names no endpoint for this feature — there is nothing to check"
+    return plan, planned, removed, note
+
+
+def cmd_contract_verify(args):
+    repo = args.repo
+    rel = lambda p: os.path.relpath(p, repo).replace("\\", "/") if p else ""
+    fd = args.feature_dir if os.path.isabs(args.feature_dir) else os.path.join(repo, args.feature_dir)
+    doc_rel = args.doc or contract_doc(repo)
+    doc_abs = (doc_rel if os.path.isabs(doc_rel) else os.path.join(repo, doc_rel)) if doc_rel else ""
+    cr = (args.cr or "").strip()
+    result = {"ok": True, "checked": False, "mode": "change" if cr else "master", "cr": cr,
+              "doc": doc_rel, "doc_exists": bool(doc_abs) and os.path.isfile(doc_abs),
+              "planned": 0, "served": 0, "changes_applied": [],
+              "missing": [], "moved": [], "renamed": [], "still_served": [],
+              "fields": [], "unplanned": [], "unplanned_count": 0,
+              "findings": [], "findings_count": 0, "issues_text": "none",
+              "warning": "", "note": "", "reason": ""}
+
+    def finish(**kw):
+        result.update(kw)
+        result["findings_count"] = len(result["findings"])
+        result["ok"] = not result["findings"]
+        result["issues_text"] = "; ".join(
+            "%s %s — %s" % (f["ref"], f["where"], f["gap"]) for f in result["findings"]) or "none"
+        emit(result)
+
+    if not args.feature_dir:
+        if args.check:
+            return emit({"ok": True, "check": True, "mode": result["mode"], "cr": cr,
+                         "planned": 0, "removed": 0, "changes_applied": [], "needed": False,
+                         "note": "no feature named — the API was not checked"})
+        return finish(note="no feature named — the API was not checked")
+    plan, planned, removed, note = _verify_plan(fd, cr, rel)
+    result["changes_applied"] = plan.changes
+    result["planned"] = len(planned)
+    if args.check:
+        # Read-only, and no as-built document is read: is there anything to check? Asked
+        # before the document is written, so a feature or change that plans no endpoint
+        # never runs the lane's export.
+        return emit({"ok": True, "check": True, "mode": result["mode"], "cr": cr,
+                     "planned": len(planned), "removed": len(removed),
+                     "changes_applied": plan.changes, "needed": not note, "note": note})
+    if note:
+        return finish(note=note)
+    if not result["doc_exists"]:
+        return finish(note="no as-built API document at %s — the API was not checked"
+                           % (doc_rel or "(no service lane)"))
+    with open(doc_abs, "rb") as fh:
+        served_doc = _api_document(fh.read())
+    if served_doc is None:
+        return finish(note="%s is not an OpenAPI or Swagger JSON document — the API was not "
+                           "checked" % doc_rel)
+    served_ops = _doc_ops(served_doc)
+    by_id = {str(op.get("operationId")): (p, m, op) for p, m, op in served_ops if op.get("operationId")}
+    by_route = {_route_key(p, m): (p, m, op) for p, m, op in served_ops}
+    result.update(checked=True, served=len(served_ops))
+    findings, fields = [], []
+    plan_doc = {"paths": plan.paths}
+
+    def finding(kind, oid, where, gap):
+        result[kind].append("%s (%s)" % (oid or where, where))
+        findings.append({"severity": "high", "check": "api", "lane": "backend",
+                         "ref": oid or where, "where": where, "gap": gap, "fix": "implement"})
+
+    for path, method, op in planned:
+        oid = str(op.get("operationId") or "")
+        where = "%s %s" % (method.upper(), path)
+        hit = by_id.get(oid) if oid else None
+        if hit is not None:
+            if _route_key(hit[0], hit[1]) != _route_key(path, method):
+                finding("moved", oid, where, "the service serves %s at %s %s — the plan says %s"
+                        % (oid, hit[1].upper(), hit[0], where))
+                continue
+        else:
+            hit = by_route.get(_route_key(path, method))
+            if hit is not None and oid and hit[2].get("operationId"):
+                finding("renamed", oid, where, "the service serves %s as %s — the plan names it "
+                        "%s, the id the frontend binds by" % (where, hit[2]["operationId"], oid))
+                continue
+            if hit is None:
+                finding("missing", oid, where, "the service does not serve it — a planned "
+                        "endpoint the frontend is bound to")
+                continue
+        for n in _differences(plan_doc, op, served_doc, hit[2]):
+            fields.append("%s (%s): %s" % (oid or where, where, n))
+    kept_routes = {_route_key(p, m) for p, m, _op in planned}
+    for r in removed:
+        oid = str(r.get("id") or "")
+        hit = by_id.get(oid)
+        if hit is None and r.get("method") and r.get("path"):
+            key = _route_key(r["path"], r["method"])
+            hit = by_route.get(key)
+            # A route the plan keeps an operation on is that operation's to serve; the
+            # planned check above reads what the service answers there.
+            if hit is not None and key in kept_routes:
+                hit = None
+        if hit is not None:
+            finding("still_served", oid, "%s %s" % (hit[1].upper(), hit[0]),
+                    "change %s removes it, and the service still serves it" % r["cr"])
+    unplanned = []
+    if not cr:
+        everywhere, _d, _c = planned_operations(repo, rel)
+        for p, m, op in served_ops:
+            oid = str(op.get("operationId") or "")
+            if (oid and oid in everywhere.by_id) or _route_key(p, m) in everywhere.routes:
+                continue
+            unplanned.append(oid or "%s %s" % (m.upper(), p))
+    warn = []
+    if fields:
+        # The document the draft states them from: the API plan (or a backend plan, for a
+        # feature planned before it), or with --cr the change's delta API plan.
+        src = (delta_api_source(os.path.join(fd, "changes", cr)) if cr else api_source(fd))[0]
+        warn.append("the service serves %d planned operation(s) of this feature with fields or "
+                    "a status code other than %s states: %s"
+                    % (len(set(x.split(" (")[0] for x in fields)), rel(src) or "the plan",
+                       "; ".join(fields[:12])))
+    if unplanned:
+        warn.append("%d operation(s) the service serves are described by no plan: %s%s"
+                    % (len(unplanned), ", ".join(unplanned[:10]),
+                       " …" if len(unplanned) > 10 else ""))
+    finish(findings=findings, fields=fields, unplanned=unplanned[:50],
+           unplanned_count=len(unplanned),
+           warning=("API — " + ". ".join(warn) + ". Reported, not blocking: correct the code or "
+                    "the plan (/appweaver plan, then analyze-plan) where it matters.") if warn else "")
+
+
+# ───────────────────────── contract-merge / api-split ──────────────────────
+# THE API PLAN IS A MASTER. finalize-delta merges a change's delta API plan into it the way
+# it merges a delta-spec into spec.md, so the endpoints the change adds or changes are in the
+# document every redraw reads from the moment the change is merged, and `plan main`, which
+# re-derives the backend plan, finds them there. The merge is by script and by whole
+# endpoint block, keyed by operation id (by verb and route for a block without one):
+#   changed   the API plan's block is replaced by the change's
+#   added     the change's block goes after the last endpoint block — over one with the same
+#             id, so a re-run changes nothing
+#   removed   the block is deleted
+#   a Contract deltas row with no block   a minimal block is written from the row, and
+#             reported: its shapes are only as precise as that table cell. A row on a route
+#             the change wrote a block for keeps that block, and is reported
+#   a block with no operation id   takes the id its row gives its route, else the id of the
+#             block it replaces — operation ids are stable
+# An operation id is read as contract-draft reads it, from the block's bullets, so the merge
+# matches every block the draft names.
+# The requests the change answers replace or join the rows of the "Requests from the
+# frontend lane" table, and a Change History row records the merge, its Version cell
+# `(pending)` until close-delta stamps the number. Nothing else in the API plan moves.
+# `--check` writes nothing: it reports whether the change carries an API delta the API plan
+# has no Change History row for (`needed`), which close-delta asks before it archives.
+#
+# A FEATURE PLANNED BEFORE THE API PLAN EXISTED keeps its endpoints in its backend plan.
+# `api-split` moves them — every endpoint block and the requests section, wherever the plan
+# keeps them — into a new API plan, and leaves a line in the backend plan saying where they
+# went. contract-merge splits first when the feature has no API plan. Both redraw DRAFT_NAME.
+
+_FENCE = re.compile(r"^\s*(```|~~~)")
+_REQUESTS_HEAD = re.compile(r"requests\s+from\s+the\s+frontend\s+lane", re.I)
+_HISTORY_HEAD = re.compile(r"change\s+history", re.I)
+_HISTORY_COLUMNS = ("Version", "Date", "Change", "User stories", "CR")
+
+
+def _md_heads(lines):
+    """[(index, level, text)] — every heading outside a code fence."""
+    out, fence = [], False
+    for n, line in enumerate(lines):
+        if _FENCE.match(line):
+            fence = not fence
+            continue
+        m = None if fence else re.match(r"^(#{1,6})\s+(.*)$", line)
+        if m:
+            out.append((n, len(m.group(1)), m.group(2)))
+    return out
+
+
+def _block_route(path):
+    path = re.sub(r":([A-Za-z_]\w*)", r"{\1}", path.split("?")[0].rstrip(".,;"))
+    return path.rstrip("/") if len(path) > 1 else path
+
+
+def _md_endpoints(lines):
+    """[{start, end, level, method, path, oid}] — each endpoint block, from its heading to the
+    next heading, the span the drafter reads it from."""
+    heads = _md_heads(lines)
+    out = []
+    for i, (n, level, _t) in enumerate(heads):
+        m = _ENDPOINT.match(lines[n])
+        if not m:
+            continue
+        end = heads[i + 1][0] if i + 1 < len(heads) else len(lines)
+        ids = backend_operation_ids("\n".join(lines[n:end]))
+        out.append({"start": n, "end": end, "level": level, "method": m.group(2).lower(),
+                    "path": _block_route(m.group(3)), "oid": ids[0] if ids else ""})
+    return out
+
+
+def _md_section(lines, pattern):
+    """(heading index, level, end) of the first heading matching `pattern`, ending at the next
+    heading of any level; None when there is none."""
+    heads = _md_heads(lines)
+    for i, (n, level, text) in enumerate(heads):
+        if pattern.search(text):
+            return n, level, heads[i + 1][0] if i + 1 < len(heads) else len(lines)
+    return None
+
+
+def _tidy(lines):
+    """No run of blank lines longer than one, and none at either end."""
+    out = []
+    for line in lines:
+        if not line.strip() and out and not out[-1].strip():
+            continue
+        out.append(line.rstrip())
+    while out and not out[0].strip():
+        out.pop(0)
+    while out and not out[-1].strip():
+        out.pop()
+    return out
+
+
+def _clean_block(lines, level):
+    """A block as it is merged: authoring comments out, its heading at `level`."""
+    body = _strip_comments("\n".join(lines)).splitlines()
+    body = _tidy(body)
+    if body:
+        body[0] = re.sub(r"^#{1,6}", "#" * level, body[0], count=1)
+    return body
+
+
+def _table_rows(lines, start, end, *required):
+    """(header index, header cells, [(row index, cells)]) of the first table in lines[start:end]
+    whose header has every column in `required`; None when there is none."""
+    n = start
+    while n + 1 < end:
+        header, rule = _cells(lines[n]), _cells(lines[n + 1])
+        if header is not None and rule is not None and _is_rule(rule):
+            low = [h.lower() for h in header]
+            rows, k = [], n + 2
+            while k < end and _cells(lines[k]) is not None:
+                rows.append((k, _cells(lines[k])))
+                k += 1
+            if all(_col(low, r) >= 0 for r in required):
+                return n, low, rows
+            n = k
+            continue
+        n += 1
+    return None
+
+
+def _row_line(header, values):
+    """A table row in `header`'s column order, from {column name: value} — a column takes the
+    value named exactly as it is, else one whose name it starts with."""
+    cells = []
+    for h in header:
+        h = h.replace("-", " ")
+        named = [k for k in values if k]
+        k = h if h in named else next((k for k in named if h.startswith(k)), "")
+        cells.append(values.get(k, "") if k else "")
+    return "| " + " | ".join(cells) + " |"
+
+
+def _version_of(path):
+    m = re.search(r"^\*\*Version\*\*:[ \t]*(\S+)", _read(path), re.M)
+    return m.group(1) if m else ""
+
+
+def _api_plan_skeleton(fd):
+    """A new API plan, in the sections of templates/api-plan-template.md, before any endpoint
+    is in it. Its Version moves in lockstep with the feature's other masters."""
+    be = _first_file(fd, BACKEND_PLAN_NAMES)
+    m = re.search(r"^\*\*Feature\*\*:[ \t]*(.+?)[ \t]*(?:<!--.*)?$", _read(be), re.M) if be else None
+    feature = m.group(1).strip().strip("`") if m else os.path.basename(os.path.normpath(fd))
+    version = (_version_of(be) if be else "") or _version_of(os.path.join(fd, "spec.md")) or "v1.0"
+    return [
+        "# API Plan: %s" % feature, "",
+        "**Feature**: `%s`" % feature,
+        "**Version**: %s" % version,
+        "**Status**: Draft", "",
+        "<!-- The endpoints this service publishes — the API contract the frontend lane binds "
+        "to — and its answers to the frontend lane's requests, in the form of "
+        ".appweaver/templates/api-plan-template.md. Drafted by script into api-draft.json; "
+        "finalize-delta merges each change's delta API plan into it. -->", "",
+        "## Endpoints", "",
+        "## Requests from the frontend lane", "",
+        "None", "",
+        "## Change History", "",
+        "| " + " | ".join(_HISTORY_COLUMNS) + " |",
+        "|" + "|".join("-" * (len(c) + 2) for c in _HISTORY_COLUMNS) + "|",
+    ]
+
+
+def _endpoint_insert_at(lines):
+    """Where a new endpoint block goes: after the last one, else at the end of the Endpoints
+    section — dropping the `None` an empty one reads — else before the requests section or
+    the Change History, else at the end."""
+    blocks = _md_endpoints(lines)
+    if blocks:
+        return blocks[-1]["end"], blocks[-1]["level"]
+    heads = _md_heads(lines)
+    for i, (n, level, text) in enumerate(heads):
+        if re.match(r"^\s*(\d+\.\s*)?endpoints\b", text, re.I):
+            nxt = next((k for k, lv, _t in heads[i + 1:] if lv <= level), len(lines))
+            for k in range(nxt - 1, n, -1):
+                if lines[k].strip().strip("_*").lower() == "none":
+                    del lines[k]
+                    nxt -= 1
+            return nxt, level + 1
+    for pattern in (_REQUESTS_HEAD, _HISTORY_HEAD):
+        s = _md_section(lines, pattern)
+        if s:
+            return s[0], 3
+    return len(lines), 3
+
+
+def _insert(lines, at, block):
+    """Put `block` at index `at` with a blank line on either side."""
+    lead = [""] if at > 0 and lines[at - 1].strip() else []
+    lines[at:at] = lead + block + [""]
+
+
+def _upsert_requests(lines, answered):
+    """Each answered request ({column: value}, keyed by RQ id) replaces the API plan's row for
+    it or joins the table; returns the RQ ids written."""
+    if not answered:
+        return []
+    sec = _md_section(lines, _REQUESTS_HEAD)
+    if sec is None:
+        hist = _md_section(lines, _HISTORY_HEAD)
+        at = hist[0] if hist else len(lines)
+        _insert(lines, at, ["## Requests from the frontend lane", "", "None"])
+        sec = _md_section(lines, _REQUESTS_HEAD)
+    head_n, _level, end = sec
+    table = _table_rows(lines, head_n + 1, end, "request", "outcome")
+    if table is None:
+        # "None" under the heading is the empty ledger; the first answer replaces it.
+        for n in range(end - 1, head_n, -1):
+            if lines[n].strip().strip("_*").lower() == "none":
+                del lines[n]
+                end -= 1
+        _insert(lines, end, ["| Request | Outcome | Operation id | Why |", "|---|---|---|---|"])
+        table = _table_rows(lines, head_n + 1, len(lines), "request", "outcome")
+    hn, header, rows = table
+    rc = _col(header, "request")
+
+    def rq_of(cells):
+        # The row's request is the first RQ id in its Request cell, as backend_answers reads it.
+        m = _RQ_ID.search(cells[rc]) if rc < len(cells) else None
+        return m.group(0) if m else ""
+
+    written = []
+    for rq, values in answered.items():
+        line = _row_line(header, values)
+        hit = next((k for k, cells in rows if rq_of(cells) == rq), None)
+        if hit is not None:
+            lines[hit] = line
+        else:
+            last = rows[-1][0] if rows else hn + 1
+            lines[last + 1:last + 1] = [line]
+            rows.append((last + 1, _cells(line)))
+        written.append(rq)
+    return written
+
+
+def _history_names(lines, cr):
+    """True when the Change History table in `lines` has a row naming `cr`."""
+    sec = _md_section(lines, _HISTORY_HEAD) if cr else None
+    table = _table_rows(lines, sec[0] + 1, sec[2], "version") if sec else None
+    return bool(table and any(cr in "|".join(cells) for _k, cells in table[2]))
+
+
+def _history_row(lines, cr, change, version="(pending)", today=""):
+    """A Change History row, unless a row already names `cr`; True when one was written."""
+    sec = _md_section(lines, _HISTORY_HEAD)
+    if sec is None:
+        _insert(lines, len(lines), ["## Change History", "",
+                                    "| " + " | ".join(_HISTORY_COLUMNS) + " |",
+                                    "|" + "|".join("-" * (len(c) + 2) for c in _HISTORY_COLUMNS) + "|"])
+        sec = _md_section(lines, _HISTORY_HEAD)
+    head_n, _level, end = sec
+    table = _table_rows(lines, head_n + 1, end, "version")
+    if table is None:
+        _insert(lines, end, ["| " + " | ".join(_HISTORY_COLUMNS) + " |",
+                             "|" + "|".join("-" * (len(c) + 2) for c in _HISTORY_COLUMNS) + "|"])
+        sec = _md_section(lines, _HISTORY_HEAD)
+        table = _table_rows(lines, sec[0] + 1, sec[2], "version")
+    hn, header, rows = table
+    if _history_names(lines, cr):
+        return False
+    line = _row_line(header, {"version": version, "date": today, "change": change,
+                              "user stories": "—", "cr": cr or "—"})
+    last = rows[-1][0] if rows else hn + 1
+    lines[last + 1:last + 1] = [line]
+    return True
+
+
+def _split_api(repo, fd, rel, today):
+    """Move a feature's endpoint blocks and requests section out of its backend plan into a
+    new API plan. Writes nothing when the feature already has one or its plan names none."""
+    api = os.path.join(fd, API_PLAN_NAME)
+    be = _first_file(fd, BACKEND_PLAN_NAMES)
+    out = {"ok": True, "split": False, "path": rel(api), "backend_plan": rel(be),
+           "endpoints": 0, "requests_moved": False, "reason": ""}
+    if os.path.isfile(api):
+        out["reason"] = "%s already has an API plan" % rel(fd)
+        return out
+    if not be:
+        out["reason"] = "no backend plan in %s — nothing to split" % rel(fd)
+        return out
+    lines = _read(be).splitlines()
+    blocks = _md_endpoints(lines)
+    req = _md_section(lines, _REQUESTS_HEAD)
+    if not blocks and req is None:
+        out["reason"] = "%s names no endpoint — nothing to split" % rel(be)
+        return out
+    plan = _api_plan_skeleton(fd)
+    at, _lv = _endpoint_insert_at(plan)
+    moved = []
+    for b in blocks:
+        moved += _clean_block(lines[b["start"]:b["end"]], 3) + [""]
+    if moved:
+        _insert(plan, at, _tidy(moved))
+    if req is not None:
+        body = _tidy(_strip_comments("\n".join(lines[req[0] + 1:req[2]])).splitlines())
+        if body and not (len(body) == 1 and body[0].strip().strip("_*").lower() == "none"):
+            sec = _md_section(plan, _REQUESTS_HEAD)
+            plan[sec[0] + 1:sec[2]] = [""] + body + [""]
+            out["requests_moved"] = True
+    version = _version_of(be) or "v1.0"
+    _history_row(plan, "", "Split out of %s by api-split: %d endpoint(s)%s"
+                 % (os.path.basename(be), len(blocks),
+                    " and the requests table" if out["requests_moved"] else ""), version, today)
+    # The backend plan keeps a line where the API was, so a reader of it knows where it went.
+    spans = sorted([(b["start"], b["end"]) for b in blocks] + ([(req[0], req[2])] if req else []))
+    first = spans[0][0]
+    for s, e in reversed(spans):
+        del lines[s:e]
+    _insert(lines, first, [
+        "The endpoints this service publishes — route, verb, operation id, request, success and "
+        "errors — and its answers to the frontend lane's requests are in "
+        "[%s](%s), the API contract the frontend lane binds to." % (API_PLAN_NAME, API_PLAN_NAME)])
+    _history_row(lines, "", "Endpoints and requests moved to %s (api-split)" % API_PLAN_NAME,
+                 version, today)
+    with open(api, "w", encoding="utf-8") as fh:
+        fh.write("\n".join(_tidy(plan)) + "\n")
+    with open(be, "w", encoding="utf-8") as fh:
+        fh.write("\n".join(_tidy(lines)) + "\n")
+    out.update(split=True, endpoints=len(blocks))
+    return out
+
+
+def _delta_requests(text):
+    """{RQ id: {column: value}} — the requests a change answers, from its requests table."""
+    out = {}
+    for header, rows in _tables(text):
+        rc, oc = _col(header, "request"), _col(header, "outcome")
+        if rc < 0 or oc < 0:
+            continue
+        for row in rows:
+            m = _RQ_ID.search(row[rc]) if rc < len(row) else None
+            if m and not _is_placeholder(row[oc] if oc < len(row) else ""):
+                out[m.group(0)] = {h.replace("-", " "): (row[n] if n < len(row) else "")
+                                   for n, h in enumerate(header)}
+    return out
+
+
+def _with_operation_id(block, oid):
+    """An endpoint block's lines with an Operation id bullet before its first bullet."""
+    at = next((n for n, line in enumerate(block) if n and _BULLET_FIELD.match(line)), len(block))
+    return block[:at] + ["- **Operation id**: `%s`" % oid] + block[at:]
+
+
+def _table_block(row, cr, level):
+    """The block a Contract deltas row stands for when the change wrote none for it."""
+    parts = re.split(r"→|->", row["shape"] or "", maxsplit=1)
+    lines = ["%s `%s %s` — drafted from change %s's Contract deltas table"
+             % ("#" * level, row["method"].upper(), row["path"], cr), "",
+             "- **Operation id**: `%s`" % row["id"]]
+    if len(parts) > 1:
+        lines.append("- **Request**: %s" % parts[0].strip())
+        lines.append("- **Success**: `200` → %s" % parts[1].strip())
+    elif parts[0].strip():
+        lines.append("- **Success**: `200` → %s" % parts[0].strip())
+    return lines
+
+
+def cmd_contract_merge(args):
+    import datetime
+    repo = args.repo
+    rel = lambda p: os.path.relpath(p, repo).replace("\\", "/") if p else ""
+    fd = args.feature_dir if os.path.isabs(args.feature_dir) else os.path.join(repo, args.feature_dir)
+    cr = (args.cr or "").strip()
+    api = os.path.join(fd, API_PLAN_NAME)
+    today = datetime.date.today().isoformat()
+    out = {"ok": True, "merged": False, "written": False, "split": False, "cr": cr,
+           "path": rel(api), "delta": "", "added": [], "changed": [], "removed": [],
+           "from_table": [], "block_kept": [], "id_added": [], "not_found": [], "requests": [],
+           "history_row": False,
+           "draft": "", "draft_operations": 0, "dropped_text": "none", "warning": "",
+           "reason": ""}
+    if not args.feature_dir or not cr:
+        if args.check:
+            fail("contract-merge --check: name the feature (--feature-dir) and the change (--cr)")
+        out["reason"] = "name the feature (--feature-dir) and the change (--cr)"
+        return emit(out)
+    cr_dir = os.path.join(fd, "changes", cr)
+    src, whole = delta_api_source(cr_dir)
+    out["delta"] = rel(src)
+    text = _strip_comments(_read(src)) if src else ""
+    region = text if whole else (api_section(text) or "")
+    rows = _delta_contract_rows(text)
+    kinds = {r["id"]: r for r in rows}
+    region_lines = region.splitlines()
+    delta_blocks = [dict(b, lines=region_lines[b["start"]:b["end"]])
+                    for b in _md_endpoints(region_lines)]
+    answered = _delta_requests(text)
+    if args.check:
+        # Read-only: does the change carry an API delta the API plan has not merged? Every
+        # merge writes a Change History row naming the change, so that row is the record.
+        has = bool(rows or delta_blocks or answered)
+        done = os.path.isfile(api) and _history_names(_read(api).splitlines(), cr)
+        reason = ("change %s changes no endpoint and answers no request — nothing to merge" % cr
+                  if not has else "%s records the merge of change %s" % (rel(api), cr) if done
+                  else "change %s's API delta (%s) is not merged: %s has no Change History row "
+                       "naming it" % (cr, rel(src), rel(api)))
+        return emit({"ok": True, "check": True, "cr": cr, "path": rel(api), "delta": rel(src),
+                     "has_delta": has, "merged": bool(done), "needed": has and not done,
+                     "reason": reason})
+    if not rows and not delta_blocks and not answered:
+        out["reason"] = ("change %s changes no endpoint and answers no request — nothing to merge"
+                         % cr)
+        return emit(out)
+
+    if not os.path.isfile(api):
+        split = _split_api(repo, fd, rel, today)
+        out["split"] = split["split"]
+        if not split["split"]:
+            with open(api, "w", encoding="utf-8") as fh:
+                fh.write("\n".join(_api_plan_skeleton(fd)) + "\n")
+    before = _read(api)
+    lines = before.splitlines()
+
+    def find(oid, method, path):
+        for b in _md_endpoints(lines):
+            if oid and b["oid"] == oid:
+                return b
+        key = _route_key(_block_route(path), method) if method and path else None
+        for b in _md_endpoints(lines):
+            if key and _route_key(b["path"], b["method"]) == key:
+                return b
+        return None
+
+    for r in rows:
+        if r["change"] != "removed":
+            continue
+        # One already gone is what the change asks for — a re-run, or a hand edit first.
+        b = find(r["id"], r["method"], r["path"])
+        if b is not None:
+            del lines[b["start"]:b["end"]]
+        out["removed"].append(r["id"])
+
+    def put(oid, method, path, block, kind):
+        b = find(oid, method, path)
+        if b is not None:
+            lines[b["start"]:b["end"]] = _clean_block(block, b["level"]) + [""]
+        else:
+            at, level = _endpoint_insert_at(lines)
+            _insert(lines, at, _clean_block(block, level))
+            if kind == "changed":
+                out["not_found"].append("%s (changed, not in the API plan — added)"
+                                        % (oid or "%s %s" % (method.upper(), path)))
+        out["changed" if kind == "changed" else "added"].append(
+            oid or "%s %s" % (method.upper(), path))
+
+    row_at = {_route_key(_block_route(r["path"]), r["method"]): r for r in rows
+              if r["change"] != "removed" and r["id"] and r["method"] and r["path"]}
+    written_ids, written_routes = set(), set()
+    for b in delta_blocks:
+        oid, block, key = b["oid"], b["lines"], _route_key(b["path"], b["method"])
+        if not oid:
+            # Operation ids are stable: a block that names none takes the id its row gives
+            # its route, else the id of the block it replaces.
+            held = find("", b["method"], b["path"])
+            oid = row_at[key]["id"] if key in row_at else held["oid"] if held else ""
+            if oid:
+                block = _with_operation_id(block, oid)
+                out["id_added"].append("%s (%s %s)" % (oid, b["method"].upper(), b["path"]))
+        row = kinds.get(oid)
+        if row and row["change"] == "removed":
+            continue
+        kind = row["change"] if row else ("changed" if find(oid, b["method"], b["path"])
+                                          else "added")
+        put(oid, b["method"], b["path"], block, kind)
+        written_ids.add(oid)
+        written_routes.add(key)
+    for r in rows:
+        if r["change"] == "removed" or r["id"] in written_ids or not r["method"] or not r["path"]:
+            continue
+        # A block this merge wrote on the row's route is the precise one; the row never
+        # overwrites it.
+        if _route_key(_block_route(r["path"]), r["method"]) in written_routes:
+            out["block_kept"].append("%s (%s %s)" % (r["id"], r["method"].upper(), r["path"]))
+            continue
+        put(r["id"], r["method"], r["path"], _table_block(r, cr, 3), r["change"])
+        out["from_table"].append(r["id"])
+    out["requests"] = _upsert_requests(lines, answered)
+
+    bits = ["%s: %s" % (k, ", ".join(out[k])) for k in ("added", "changed", "removed") if out[k]]
+    if out["requests"]:
+        bits.append("requests answered: %s" % ", ".join(out["requests"]))
+    out["history_row"] = _history_row(lines, cr, "API of %s merged by finalize-delta — %s"
+                                      % (cr, "; ".join(bits) or "no endpoint"), "(pending)", today)
+    after = "\n".join(_tidy(lines)) + "\n"
+    if after != before:
+        with open(api, "w", encoding="utf-8") as fh:
+            fh.write(after)
+        out["written"] = True
+    out["merged"] = True
+    # What the redraw dropped beyond what the change removed on purpose.
+    draft = _draft_master(repo, fd, rel)
+    dropped = [d for d in draft["dropped"] if d.split(" (")[0] not in out["removed"]]
+    out.update(draft=draft["path"], draft_operations=draft["operations"],
+               dropped_text=", ".join(dropped) or "none")
+    warn = []
+    if out["from_table"]:
+        warn.append("%d endpoint(s) had no block in %s and were written from their Contract "
+                    "deltas row, so their shapes are only as precise as that cell: %s"
+                    % (len(out["from_table"]), rel(src), ", ".join(out["from_table"])))
+    if out["block_kept"]:
+        warn.append("%d Contract deltas row(s) name a route %s also writes a block for, under "
+                    "another operation id, so the block was kept: %s"
+                    % (len(out["block_kept"]), rel(src), ", ".join(out["block_kept"])))
+    if out["not_found"]:
+        warn.append("%s did not have what the change changes: %s"
+                    % (rel(api), ", ".join(out["not_found"])))
+    if warn:
+        out["warning"] = ("API MERGE — %s. Complete them in %s with /appweaver plan main."
+                          % ("; ".join(warn), rel(api)))
+    emit(out)
+
+
+def _api_still_in_plan(fd, cr=""):
+    """{needed, endpoints, path, plan} — whether the backend plan (or, with `cr`, the change's
+    delta backend plan) still carries the API while no API plan beside it does. A document
+    scaffolded beside it from the empty template would be read in its place."""
+    if cr:
+        cr_dir = os.path.join(fd, "changes", cr)
+        target = os.path.join(cr_dir, DELTA_API_PLAN_NAME)
+        plan = _first_file(cr_dir, DELTA_PLAN_NAMES["backend"])
+        text = _strip_comments(_read(plan)) if plan else ""
+        endpoints = len(_md_endpoints((api_section(text) or "").splitlines()))
+        carries = bool(endpoints or _delta_contract_rows(text))
+    else:
+        target = os.path.join(fd, API_PLAN_NAME)
+        plan = _first_file(fd, BACKEND_PLAN_NAMES)
+        lines = _read(plan).splitlines() if plan else []
+        endpoints = len(_md_endpoints(lines))
+        carries = bool(endpoints or _md_section(lines, _REQUESTS_HEAD))
+    return {"needed": carries and not os.path.isfile(target), "endpoints": endpoints,
+            "path": target, "plan": plan}
+
+
+def cmd_api_split(args):
+    import datetime
+    repo = args.repo
+    rel = lambda p: os.path.relpath(p, repo).replace("\\", "/") if p else ""
+    fd = args.feature_dir if os.path.isabs(args.feature_dir) else os.path.join(repo, args.feature_dir)
+    if not args.feature_dir:
+        return emit({"ok": True, "split": False, "needed": False, "path": "", "backend_plan": "",
+                     "endpoints": 0, "requests_moved": False, "draft_operations": 0,
+                     "dropped_text": "none", "reason": "no feature named — nothing to split"})
+    if args.check or args.cr:
+        # Read-only: is there an API still to move? A change's API is never split — the
+        # change is planned again into its delta API plan — so --cr only ever checks.
+        s = _api_still_in_plan(fd, (args.cr or "").strip())
+        return emit({"ok": True, "split": False, "needed": s["needed"], "path": rel(s["path"]),
+                     "backend_plan": rel(s["plan"]), "endpoints": s["endpoints"],
+                     "requests_moved": False, "draft_operations": 0, "dropped_text": "none",
+                     "reason": ("%s still carries the API, and %s does not exist yet"
+                                % (rel(s["plan"]), rel(s["path"]))) if s["needed"] else ""})
+    out = _split_api(repo, fd, rel, datetime.date.today().isoformat())
+    out["needed"] = False
+    out.update(draft_operations=0, dropped_text="none")
+    if out["split"]:
+        draft = _draft_master(repo, fd, rel)
+        out.update(draft_operations=draft["operations"], dropped_text=draft["dropped_text"])
+    emit(out)
+
+
 # ──────────────────────────────── probe ────────────────────────────────────
 
 def profile_terms(prof):
@@ -3201,6 +4532,159 @@ def cmd_probe(args):
     })
 
 
+# ─────────────────────────────── rule coverage ─────────────────────────────
+# WHICH STACKS HAVE A TECHNICAL RULE SET, measured where it matters: against the active
+# project's tech-rule-bindings.md. A map names a stack's rules with a placeholder in the
+# folder segment of the path — guardrails/technology/{{backend_stack}}/… — so a stack has
+# a rule set exactly as far as the files the map names for it exist. A folder holding
+# some of them is partial, not complete; a map that names no stack folder for a lane
+# makes the stack choice irrelevant to that lane's rules, which reads `not-mapped`.
+#
+# A stack with no rule set is a supported setup (STACK-PROFILES.md §7): the lane runs on
+# ai-rules.md and the technical constitution. The report is for saying so where the
+# stack is chosen, rather than leaving every later phase's warning to reveal it.
+#
+# THE PLACEHOLDER TABLE IS resolve-tech's: {{stack}} is the service lane's, the other
+# lane's placeholders resolve from stacks.json, and a bullet that needs a lane nobody
+# declared is skipped, as resolve-tech skips it. The bullets read are the ones
+# resolve-tech reads: `- ` lines under a `## /<command>` heading.
+
+CORPUS_REL = "guardrails/technology/"
+RULE_HOLE = re.compile(r"\{\{\s*([a-z_]+)\s*\}\}")
+CORPUS_HOLES = {"backend": ("backend_stack", "stack"), "frontend": ("frontend_stack",)}
+LANE_WORDS = {"backend": "service", "frontend": "UI"}
+
+
+def active_project(repo):
+    try:
+        with open(os.path.join(repo, ".appweaver", "domain.json"), encoding="utf-8") as fh:
+            return (json.load(fh).get("domain") or "").strip()
+    except (ValueError, OSError, AttributeError):
+        return ""
+
+
+def map_bullets(path):
+    """Every `- ` bullet under a `## /<command>` heading of a rule map. A path written as
+    code (- `path`) is read without its backticks."""
+    out, grab = [], False
+    try:
+        with open(path, encoding="utf-8") as fh:
+            lines = fh.read().splitlines()
+    except OSError:
+        return out
+    for line in lines:
+        if line.startswith("## "):
+            grab = line.strip().startswith("## /")
+            continue
+        m = re.match(r"^\s*-\s+(.*?)\s*$", line) if grab else None
+        if m:
+            out.append(re.sub(r"^`([^`]+)`$", r"\1", m.group(1)))
+    return out
+
+
+def stack_rule_files(repo, bullets, kind, prof, lanes):
+    """The files the map names in `prof`'s rule folder, resolved as they would be with
+    `prof` declared for `kind` and the other lane as stacks.json has it."""
+    other = "frontend" if kind == "backend" else "backend"
+    ob = kind_block(repo, lanes, other)
+    subs = {kind + "_stack": prof.get("id", ""), kind + "_ecosystem": prof.get("ecosystem", ""),
+            other + "_stack": ob[other + "_profile"], other + "_ecosystem": ob[other + "_ecosystem"]}
+    subs["stack"] = subs["backend_stack"]
+    folder = re.compile(r"^%s\{\{\s*(?:%s)\s*\}\}/" % (re.escape(CORPUS_REL), "|".join(CORPUS_HOLES[kind])))
+    files = []
+    for b in bullets:
+        if not folder.match(b):
+            continue
+        if any(not subs.get(h) for h in RULE_HOLE.findall(b)):
+            continue
+        path = RULE_HOLE.sub(lambda m: subs[m.group(1)], b)
+        if path not in files:
+            files.append(path)
+    return files
+
+
+def rule_coverage(repo, kind, prof, bullets, lanes):
+    files = stack_rule_files(repo, bullets, kind, prof, lanes)
+    present = [f for f in files if os.path.isfile(os.path.join(repo, f))]
+    missing = [f for f in files if f not in present]
+    folder = CORPUS_REL + prof.get("id", "") + "/"
+    verdict = ("not-mapped" if not files else "complete" if not missing
+               else "partial" if present else "none")
+    return {"id": prof.get("id", ""), "title": prof.get("title", "") or prof.get("id", ""),
+            "verdict": verdict, "mapped": len(files), "present": len(present),
+            "missing_count": len(missing), "missing": missing, "folder": folder,
+            "folder_exists": os.path.isdir(os.path.join(repo, folder))}
+
+
+def coverage_note(kind, map_rel, rows):
+    """The one line select-stack puts in front of a lane's menu."""
+    if not rows or all(r["verdict"] == "not-mapped" for r in rows):
+        return ("%s names no stack rule folder for a %s lane, so the stack chosen here does "
+                "not change which technical rules load." % (map_rel, kind))
+    have = ["%s — complete" % r["title"] for r in rows if r["verdict"] == "complete"]
+    have += ["%s — %d of %d files" % (r["title"], r["present"], r["mapped"])
+             for r in rows if r["verdict"] == "partial"]
+    none = [r["title"] for r in rows if r["verdict"] == "none"]
+    text = "Technical rule sets in %s for a %s stack: %s." % (
+        map_rel, kind, "; ".join(have) if have else "none yet")
+    if none:
+        text += (" None for: %s. A stack without one can still be declared, built and tested; "
+                 "plan, implement, build and analyze-slice then load no stack rules for it "
+                 "beyond ai-rules.md and the technical constitution until %s<id>/ holds them. "
+                 "On an existing codebase, onboard writes code-derived rules instead."
+                 % (", ".join(none), CORPUS_REL))
+    return text
+
+
+def coverage_warning(kind, map_rel, row):
+    """The warning select-stack raises for a declared lane whose stack lacks rules."""
+    lane = LANE_WORDS[kind]
+    who = "the %s lane's stack, %s (%s)," % (lane, row["title"], row["id"])
+    if row["verdict"] == "none":
+        return ("WARNING — %s has no technical rule set: %s maps %d file(s) under %s and none "
+                "exists. That is a supported setup — plan, implement, build and analyze-slice "
+                "will load no stack rules for this lane beyond ai-rules.md and the technical "
+                "constitution, and each will say so. To give the lane stack rules, write %s "
+                "with the file names the map lists (any existing folder under %s shows the "
+                "shape), or point the map at your own files. On an existing codebase, onboard "
+                "writes code-derived rules into guardrails/brf-<project>/ instead."
+                % (who, map_rel, row["mapped"], row["folder"], row["folder"], CORPUS_REL))
+    if row["verdict"] == "partial":
+        names = ", ".join(os.path.relpath(f, row["folder"]).replace(os.sep, "/")
+                          for f in row["missing"])
+        return ("WARNING — %s has an incomplete technical rule set: %d of the %d file(s) %s "
+                "maps under %s exist. Missing: %s. Those rules do not load for this lane until "
+                "the files are written or the map stops naming them."
+                % (who, row["present"], row["mapped"], map_rel, row["folder"], names))
+    return ""
+
+
+def cmd_rules(args):
+    repo = args.repo
+    project = active_project(repo)
+    map_rel = "guardrails/%s/tech-rule-bindings.md" % project
+    map_exists = bool(project) and os.path.isfile(os.path.join(repo, map_rel))
+    lanes = (read_stacks(repo) or {}).get("lanes") or []
+    bullets = map_bullets(os.path.join(repo, map_rel)) if map_exists else []
+    rows = [rule_coverage(repo, args.kind, p, bullets, lanes)
+            for p in load_profiles(repo, args.kind)]
+    out = {"project": project, "map": map_rel, "map_exists": map_exists, "kind": args.kind,
+           "profiles": rows,
+           "note": coverage_note(args.kind, map_rel, rows) if map_exists else (
+               "The active project has no %s, so no stack loads mapped technical rules."
+               % map_rel)}
+    if args.declared:
+        lane = next((l for l in lanes if l.get("kind") == args.kind), {})
+        pid = lane.get("profile", "")
+        prof = profile_of(repo, lane) or {"id": pid, "title": lane.get("stack", "")}
+        row = rule_coverage(repo, args.kind, prof, bullets, lanes) if lane and map_exists else {}
+        warning = coverage_warning(args.kind, map_rel, row) if row else ""
+        out.update({"declared": bool(lane), "lane_profile": pid,
+                    "verdict": row.get("verdict", ""), "lane_coverage": row,
+                    "ok": not warning, "warning": warning})
+    emit(out)
+
+
 def main():
     ap = argparse.ArgumentParser(prog="aw-stack", description=__doc__)
     ap.add_argument("--repo", default=".", help="repository root (callers pass their own resolver's answer)")
@@ -3322,8 +4806,9 @@ def main():
                    help="true when a test suite actually ran for the lane")
     p.add_argument("--requirements-ok", dest="requirements_ok", default="false",
                    help="true when the lane's code met the delta-spec")
-    p.add_argument("--findings", default="",
-                   help="the lane check's findings, a JSON list")
+    p.add_argument("--findings", action="append", default=[],
+                   help="the lane check's findings, a JSON list; given more than once, the "
+                        "lists are joined")
     p.set_defaults(func=cmd_slice_gate_stamp)
 
     p = sub.add_parser("run-phase", help="run a phase's command for every declared lane")
@@ -3348,36 +4833,72 @@ def main():
     p.set_defaults(func=cmd_set)
 
     p = sub.add_parser("contract-export",
-                       help="start the service lane, save its API document, stop it")
+                       help="write the service lane's API document as built, the way the lane says")
     p.add_argument("--timeout", type=int, default=180,
-                   help="seconds to wait for the document after starting the service")
+                   help="seconds to wait for the document — for `contract_write` to finish, or "
+                        "for the started service to serve it")
     p.set_defaults(func=cmd_contract_export)
 
     p = sub.add_parser("contract-draft",
-                       help="draft a feature's API document from its backend plan's API section")
+                       help="draft a feature's API document from its API plan, or a change's "
+                            "from its delta API plan")
     p.add_argument("--feature-dir", dest="feature_dir", default="")
+    p.add_argument("--cr", default="",
+                   help="draft this change's API changes into its change folder instead")
     p.set_defaults(func=cmd_contract_draft)
 
     p = sub.add_parser("contract-combine",
-                       help="the exported document plus every drafted operation it does not serve")
+                       help="every planned operation, with the open changes applied, plus the "
+                            "served operations no plan describes")
     p.set_defaults(func=cmd_contract_combine)
 
+    p = sub.add_parser("contract-verify",
+                       help="the API the built service serves vs the operations the plan names")
+    p.add_argument("--feature-dir", dest="feature_dir", default="")
+    p.add_argument("--cr", default="",
+                   help="check this change's operations only (analyze-slice-delta)")
+    p.add_argument("--doc", default="", help="the as-built document (default: the lane's)")
+    p.add_argument("--check", action="store_true",
+                   help="read no as-built document; only report whether the plan names "
+                        "anything to check (`needed`)")
+    p.set_defaults(func=cmd_contract_verify)
+
+    p = sub.add_parser("contract-merge",
+                       help="merge a change's delta API plan into its feature's API plan")
+    p.add_argument("--feature-dir", dest="feature_dir", default="")
+    p.add_argument("--cr", default="")
+    p.add_argument("--check", action="store_true",
+                   help="write nothing; only report whether the change carries an API delta "
+                        "the API plan has not merged (`needed`)")
+    p.set_defaults(func=cmd_contract_merge)
+
+    p = sub.add_parser("api-split",
+                       help="move a feature's endpoints and requests table out of its backend "
+                            "plan into a new API plan")
+    p.add_argument("--feature-dir", dest="feature_dir", default="")
+    p.add_argument("--check", action="store_true",
+                   help="only report whether the backend plan still carries the API (`needed`)")
+    p.add_argument("--cr", default="",
+                   help="check this change's delta backend plan instead (implies --check)")
+    p.set_defaults(func=cmd_api_split)
+
     p = sub.add_parser("contract-requests",
-                       help="the frontend plan's contract requests and the backend plan's answers")
+                       help="the frontend plan's contract requests and the API plan's answers")
     p.add_argument("--feature-dir", dest="feature_dir", default="")
     p.set_defaults(func=cmd_contract_requests)
 
     p = sub.add_parser("contract-check",
-                       help="the operation ids a frontend plan cites vs the exported document")
+                       help="the operation ids a frontend plan cites vs the combined document")
     p.add_argument("--plan", required=True, help="the frontend plan (master or delta)")
-    p.add_argument("--doc", default="", help="the API document (default: the exported one)")
+    p.add_argument("--doc", default="", help="the API document (default: the combined one)")
     p.set_defaults(func=cmd_contract_check)
 
     p = sub.add_parser("contract-impact",
                        help="operations a change's service delta changes or removes that the "
                             "frontend binds to, and whether its frontend delta carries them")
     p.add_argument("--delta-backend", dest="delta_backend", default="",
-                   help="the change's delta-backend-plan.md")
+                   help="the change's delta-backend-plan.md; the delta-api-plan.md beside it "
+                        "carries the table when the change has one")
     p.add_argument("--frontend-plan", dest="frontend_plan", default="",
                    help="the feature's master frontend plan")
     p.add_argument("--delta-frontend", dest="delta_frontend", default="",
@@ -3389,6 +4910,14 @@ def main():
     p.add_argument("--hint", default="", help="free prose to scan for a stack name")
     p.set_defaults(func=cmd_probe)
 
+    p = sub.add_parser("rules", help="which stacks the active project's technical map has "
+                                     "rule files for")
+    p.add_argument("--kind", choices=["backend", "frontend"], required=True)
+    p.add_argument("--declared", action="store_true",
+                   help="also report this kind's declared lane, with the warning select-stack "
+                        "raises when its stack's rule set is missing or incomplete")
+    p.set_defaults(func=cmd_rules)
+
     args = ap.parse_args()
     if not getattr(args, "func", None):
         ap.print_help()