aw-spec-cli 0.1.28 → 0.1.30

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

@@ -2,7 +2,7 @@
 """
 aw-stack — the lane model's deterministic core.
 
-Backs ten aw-spec-actions subcommands, called identically by the bash and the
+Backs seventeen 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
@@ -13,10 +13,18 @@ powershell twin so the two stay in parity by construction rather than by review:
     resolve   read .appweaver/stacks.json — for every downstream reader; with
               --feature-dir, narrowed to the lanes that feature has a surface in
     verify    is the declaration USABLE for the phase about to run — the gate
+    lane-select  read or write .appweaver/lane.json — the developer's WORKING lane
+    cr-lanes  the lanes a change touches, read from or written to its delta-spec
+    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
     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
 
 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 —
@@ -41,6 +49,22 @@ declared before the keys existed answers them too:
 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 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
+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,
 and it is supported: the kit ships the file with an empty `lanes` array for exactly
 that, plus a `_lane_format` key holding one sample lane of each kind with every field
@@ -49,6 +73,17 @@ filled in. Nothing reads `_lane_format`; it is there to copy from. It is the one
 `declare` already did. `resolve` can never write, which is why these are two
 subcommands and not one with a mode flag.
 
+THE WORKING LANE. stacks.json says which lanes the PROJECT has; .appweaver/lane.json says
+which of them THIS DEVELOPER is working on — `backend`, `frontend` or `both`. It is not
+committed: a backend developer and a frontend developer on one repository each keep their
+own. `select-stack` writes the default (both when both lanes are declared, otherwise the
+one that is), `select-lane` changes it, and a clone without the file reads that same
+default. Every reader gets `<kind>_working` beside `<kind>_declared`: a phase WRITES only a
+working lane — plans it, gates it, generates, builds and tests it — and still READS a lane
+that is declared but not worked, which is how a frontend plan binds to a backend plan
+another developer owns. With the default, every declared lane is worked, which is the
+behaviour from before the file existed.
+
 A lane's `root` IS the lane root folder — the subtree the lane owns and the only place
 its implement phase may write. The two words name one field, and `--source-path`
 is accepted wherever `--root` is.
@@ -85,9 +120,23 @@ import sys
 STACKS_REL = ".appweaver/stacks.json"
 PROFILES_REL = ".appweaver/stack-profiles"
 
+# The developer's working lane, and the three answers it can hold. Not committed — see
+# the module docstring.
+LANE_REL = ".appweaver/lane.json"
+WORKING_LANES = ("backend", "frontend", "both")
+
 # Where the exported 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).
+DRAFT_NAME = "api-draft.json"
+COMBINED_DOC = ".appweaver/contracts/openapi.combined.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 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`.
@@ -715,7 +764,7 @@ def lane_host(repo, lane):
     return None
 
 
-def lane_command(lane, phase, repo=None):
+def lane_command(lane, phase, repo=None, contract=""):
     """The command for one phase, with `{{root}}` standing for the lane root folder and
     `{{host}}` for the lane's runnable project inside it (see lane_host).
 
@@ -739,16 +788,17 @@ def lane_command(lane, phase, repo=None):
     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 service lane's exported API document (contract_doc), named as
-    seen from where THIS lane's command runs — what a frontend lane's `client` command
-    generates from. With no service lane it is left as written.
+    `{{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.
     """
     if phase in CONTRACT_KEYS:
         cmd = lane_value(repo, lane, phase)
     else:
         cmd = (lane.get(phase) or "").strip()
     if "{{contract}}" in cmd and repo:
-        doc = contract_doc(repo)
+        doc = contract or contract_doc(repo)
         if doc:
             rel = os.path.relpath(os.path.join(repo, doc), lane_workdir(repo, lane))
             cmd = cmd.replace("{{contract}}", rel.replace("\\", "/"))
@@ -1226,6 +1276,385 @@ def apply_feature_lanes(payload, kinds):
         payload[kind + "_feature_excluded"] = excluded
         if excluded:
             payload[kind + "_declared"] = False
+            payload[kind + "_working"] = False
+
+
+# ───────────────────────────── working lane ────────────────────────────────
+
+def declared_kinds(lanes):
+    """The lane kinds stacks.json declares, backend first."""
+    return [k for k in ("backend", "frontend") if any(l.get("kind") == k for l in lanes)]
+
+
+def default_working(lanes):
+    """The working lane a developer has before choosing one: every declared lane."""
+    kinds = declared_kinds(lanes)
+    return "both" if len(kinds) == 2 else (kinds[0] if kinds else "")
+
+
+def read_lane_file(repo):
+    """lane.json's record: None when there is no file, {} when it cannot be read."""
+    path = os.path.join(repo, LANE_REL)
+    if not os.path.isfile(path):
+        return None
+    try:
+        with open(path, encoding="utf-8") as fh:
+            rec = json.load(fh)
+    except (OSError, ValueError):
+        return {}
+    return rec if isinstance(rec, dict) else {}
+
+
+def working_lane(repo, lanes):
+    """Which declared lanes this developer works on, and where that answer came from.
+
+    lane.json is honoured only while it names a lane that is still declared. A file that
+    is missing, unreadable, or names a lane select-stack has since removed falls back to
+    the default, and `note` says why — a stale choice must never switch a lane off.
+    """
+    kinds = declared_kinds(lanes)
+    default = default_working(lanes)
+    rec = read_lane_file(repo)
+    chosen = str((rec or {}).get("lane", "")).strip().lower()
+    lane, source, note = default, "default", ""
+    if rec is None:
+        note = "no %s — every declared lane is worked" % LANE_REL
+    elif chosen not in WORKING_LANES:
+        note = ("%s names no working lane ('%s'); every declared lane is worked. Run "
+                "/appweaver select-lane to choose one." % (LANE_REL, chosen))
+    elif chosen != "both" and chosen not in kinds:
+        note = ("%s selects the %s lane, which .appweaver/stacks.json does not declare; "
+                "every declared lane is worked. Run /appweaver select-lane to choose again."
+                % (LANE_REL, chosen))
+    else:
+        source = LANE_REL
+        lane = chosen if chosen != "both" else default
+    worked = kinds if lane == "both" else ([lane] if lane else [])
+    return {"lane": lane, "kinds": worked, "source": source, "note": note,
+            "default": default}
+
+
+def apply_working(payload, repo, lanes):
+    """Add the working-lane fields to a resolve/verify payload, after both kind blocks.
+
+    `working_kind` is the ONE kind being worked, or "" when every declared lane is — what a
+    caller passes as `--kind` so that both lanes behave exactly as an unnarrowed call did.
+    `working_root` / `working_test_path` follow the same rule, for a caller that narrows a
+    file list with `--under`.
+    """
+    w = working_lane(repo, lanes)
+    single = w["kinds"][0] if len(w["kinds"]) == 1 and len(declared_kinds(lanes)) == 2 else ""
+    payload.update({
+        "working_lane": w["lane"],
+        "working_kind": single,
+        "working_kinds": w["kinds"],
+        "working_source": w["source"],
+        "working_note": w["note"],
+        "working_default": w["default"],
+        "working_root": payload.get(single + "_source_path", "") if single else "",
+        "working_test_path": payload.get(single + "_test_path", "") if single else "",
+        "lane_file": LANE_REL,
+        "lane_file_exists": os.path.isfile(os.path.join(repo, LANE_REL)),
+    })
+    for kind in ("backend", "frontend"):
+        payload[kind + "_working"] = bool(payload.get(kind + "_declared")) and kind in w["kinds"]
+
+
+def lane_select_options(repo, lanes):
+    """One selectable line per working-lane answer: each declared lane, then `both` when
+    there are two. The value is the first token; the rest says what it means."""
+    out = []
+    for kind in declared_kinds(lanes):
+        lane = next(l for l in lanes if l.get("kind") == kind)
+        prof = profile_of(repo, lane)
+        title = (prof.get("title", "") or lane.get("stack", "")
+                 or lane.get("profile", "") or "no stack declared")
+        root = norm_root(lane.get("root"))
+        where = "the repo root" if root == REPO_ROOT else (root or "no lane root folder")
+        out.append(ROOT_LABEL_SEP.join(
+            [kind, "work on the %s lane `%s` only (%s at %s)"
+                   % (kind, lane.get("id", ""), title, where)]))
+    if len(out) == 2:
+        out.append(ROOT_LABEL_SEP.join(["both", "work on both lanes, as a full-stack developer"]))
+    return out
+
+
+def cmd_lane_select(args):
+    """Read the working lane, or write it.
+
+    No argument reports the current answer and the menu `select-lane` shows. `--lane`
+    writes one of the offered answers (a whole option line is accepted, as `user_select`
+    hands it back). `--default` writes the default for the declared stacks — select-stack's
+    call, so a re-stacked project starts again from every declared lane.
+    """
+    import datetime
+
+    repo = args.repo
+    lanes = (read_stacks(repo) or {}).get("lanes") or []
+    options = lane_select_options(repo, lanes)
+    keys = [strip_root_label(o) for o in options]
+    default = default_working(lanes)
+
+    wanted = ""
+    if args.default:
+        wanted = default
+        if not wanted:
+            fail("lane-select: no lane is declared in %s, so there is no working lane to "
+                 "set. Run /appweaver select-stack first." % STACKS_REL)
+    elif args.lane:
+        wanted = strip_root_label(args.lane).strip().lower()
+        if wanted not in keys:
+            fail("lane-select: '%s' is not a working lane for this project; the declared "
+                 "stacks offer %s" % (wanted, ", ".join(keys) or "none — run /appweaver select-stack"))
+
+    written = False
+    if wanted:
+        os.makedirs(os.path.join(repo, ".appweaver"), exist_ok=True)
+        with open(os.path.join(repo, LANE_REL), "w", encoding="utf-8") as fh:
+            json.dump({
+                "_note": ("This developer's working lane: backend, frontend or both. Not "
+                          "committed. select-stack writes the default; /appweaver "
+                          "select-lane changes it."),
+                "lane": wanted,
+                "set_by": "select-stack" if args.default else "select-lane",
+                "updated": datetime.datetime.now(datetime.timezone.utc)
+                           .strftime("%Y-%m-%dT%H:%M:%SZ"),
+            }, fh, indent=2)
+            fh.write("\n")
+        written = True
+
+    # The argument doubles as the answer, but only as a WHOLE word: `select-lane frontend`
+    # selects, prose that merely mentions a lane does not.
+    text = (args.preselect or "").strip().lower()
+    preselect = next((o for o, k in zip(options, keys) if k == text), "")
+
+    w = working_lane(repo, lanes)
+    emit({
+        "ok": True,
+        "declared": bool(lanes),
+        "declared_kinds": declared_kinds(lanes),
+        "lane": w["lane"],
+        "kinds": w["kinds"],
+        "source": w["source"],
+        "note": w["note"],
+        "default": default,
+        "select_options": options,
+        "option_keys": keys,
+        "option_count": len(options),
+        "preselect": preselect,
+        "written": written,
+        "path": LANE_REL,
+    })
+
+
+# THE LANES A CHANGE TOUCHES. A change's delta-spec names them on its `**Lanes**:` header
+# line: `backend`, `frontend`, or `backend, frontend`. specify asks when it opens a change
+# and plan asks when it opens a plan-only one, with both lanes as the answer listed first;
+# the spec half is written whole whatever the answer. A delta-spec with no such line, or
+# with the template's unfilled `[…]` placeholder, touches every declared lane — which is
+# what every change opened before the line existed did.
+_LANES_LINE = re.compile(r"^\*\*Lanes\*\*:[ \t]*(.*?)[ \t]*(?:<!--.*)?$", re.M)
+_WAVE_LINE = re.compile(r"^\*\*Wave\*\*:.*$", re.M)
+
+
+def change_lane_options(lanes):
+    """One selectable line per answer to "which lanes does this change touch?": both
+    first, then each lane alone. One declared lane is the only answer; none, no answer."""
+    kinds = declared_kinds(lanes)
+    if len(kinds) == 2:
+        return [ROOT_LABEL_SEP.join(["both", "the change touches the backend and the "
+                                     "frontend — each lane plans and builds its half"]),
+                ROOT_LABEL_SEP.join(["backend", "the change touches only the backend"]),
+                ROOT_LABEL_SEP.join(["frontend", "the change touches only the frontend"])]
+    return [ROOT_LABEL_SEP.join([k, "the change touches the %s, the only declared lane" % k])
+            for k in kinds]
+
+
+def read_change_lanes(path):
+    """The kinds a delta-spec's `**Lanes**:` line names, or None when it has no line, still
+    carries the template placeholder or cannot be opened.
+
+    The one Python reader of the line: the bash cr-list and cr-paths load it from this file,
+    and powershell's Get-ChangeLanes is its twin. A byte that is not UTF-8 elsewhere in the
+    document is read as a replacement character, as powershell reads it, so it never hides
+    the line."""
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            text = fh.read()
+    except OSError:
+        return None
+    m = _LANES_LINE.search(text)
+    value = m.group(1).strip().lower() if m else ""
+    if not value or value.startswith("["):
+        return None
+    if re.search(r"\bboth\b", value):
+        return ["backend", "frontend"]
+    kinds = [k for k in ("backend", "frontend") if re.search(r"\b%s\b" % k, value)]
+    return kinds or None
+
+
+def stamp_change_lanes(path, kinds):
+    """Write the `**Lanes**:` line: replaced in place when there is one, otherwise inserted
+    after the `**Wave**:` line — or after the title when there is no wave either — so the
+    header block stays together."""
+    with open(path, encoding="utf-8") as fh:
+        text = fh.read()
+    line = "**Lanes**: " + ", ".join(kinds)
+    if _LANES_LINE.search(text):
+        text = _LANES_LINE.sub(lambda _m: line, text, count=1)
+    else:
+        lines = text.split("\n")
+        at = next((i + 1 for i, l in enumerate(lines) if _WAVE_LINE.match(l)), None)
+        if at is None:
+            at = next((i + 1 for i, l in enumerate(lines) if l.startswith("# ")), 0)
+        lines[at:at] = ["", line]
+        text = "\n".join(lines)
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(text)
+
+
+def cmd_cr_lanes(args):
+    """The answers to "which lanes does this change touch?", and — with --delta-spec — the
+    lanes that change records.
+
+    `--set` writes an answer onto the delta-spec's `**Lanes**:` line (a whole option line
+    is accepted, as `user_select` hands it back); `--stamp` with no `--set` writes every
+    declared lane. `lanes` is what the change touches among the lanes declared now: the
+    recorded ones that are still declared, or every declared lane when nothing is recorded.
+    """
+    repo = args.repo
+    lanes = (read_stacks(repo) or {}).get("lanes") or []
+    kinds = declared_kinds(lanes)
+    options = change_lane_options(lanes)
+    keys = [strip_root_label(o) for o in options]
+    path = args.delta_spec
+    exists = bool(path) and os.path.isfile(path)
+
+    stamped = False
+    if args.stamp or args.set:
+        if not exists:
+            fail("cr-lanes: no delta-spec at %s — open the change first" % (path or "(none given)"))
+        answer = strip_root_label(args.set).strip().lower()
+        if answer:
+            offered = keys or ["both", "backend", "frontend"]
+            if answer not in offered:
+                fail("cr-lanes: '%s' is not an answer for this project; the declared stacks "
+                     "offer %s" % (answer, ", ".join(offered)))
+            chosen = ["backend", "frontend"] if answer == "both" else [answer]
+        else:
+            chosen = kinds or ["backend", "frontend"]
+        stamp_change_lanes(path, chosen)
+        stamped = True
+
+    recorded = read_change_lanes(path) if exists else None
+    if kinds:
+        touched = [k for k in (recorded or kinds) if k in kinds]
+    else:
+        touched = list(recorded or [])
+    emit({
+        "ok": True,
+        "declared_kinds": kinds,
+        "select_options": options,
+        "option_keys": keys,
+        "option_count": len(options),
+        "has_options": bool(options),
+        "default": keys[0] if keys else "",
+        "delta_spec": path,
+        "exists": exists,
+        "recorded": recorded is not None,
+        "recorded_kinds": recorded or [],
+        "lanes": touched,
+        "lanes_csv": ",".join(touched),
+        "backend": "backend" in touched,
+        "frontend": "frontend" in touched,
+        "source": "delta-spec" if recorded is not None else "declared",
+        "stamped": stamped,
+    })
+
+
+# THE RESULT OF analyze-slice-delta, ONE FILE PER LANE. A change's two lanes may be built and
+# gated by two developers, each on their own machine, so each lane's result is its own file
+# in the change's directory — `.aw-slice-gate.<lane>.json` — committed with the change and
+# archived with it. Each developer writes only their own lane's file, so the two results
+# never collide in a merge. `pass` needs the lane's tests green AND its requirements met;
+# anything else is `fail`. Green means no test failed: a lane that declares no test command
+# is green with nothing run, and `tests_ran` false says so, so a reader that needs an
+# executed suite checks that field rather than the verdict. The record also hashes the
+# delta-spec and the lane's delta plan the code was gated against, so a reader can tell
+# when either has moved since.
+SLICE_GATE = ".aw-slice-gate.%s.json"
+DELTA_PLAN_NAMES = {
+    "backend": ("delta-backend-plan.md", "delta-design.md"),
+    "frontend": ("delta-frontend-plan.md", "delta-design.ui.md"),
+}
+SLICE_GATE_NOTE = ("Written by analyze-slice-delta for one lane of this change: pass means no "
+                   "test of the lane failed and its code met the delta-spec. tests_ran says "
+                   "whether a test suite actually ran: false when the lane declares no test "
+                   "command. Each lane's developer writes only their own lane's file.")
+
+
+def _file_sha(path):
+    import hashlib
+    try:
+        with open(path, "rb") as fh:
+            return hashlib.sha256(fh.read()).hexdigest()
+    except OSError:
+        return ""
+
+
+def cmd_slice_gate_stamp(args):
+    import datetime
+    repo = args.repo
+    cr_dir = args.cr_dir if os.path.isabs(args.cr_dir) else os.path.join(repo, args.cr_dir)
+    if not os.path.isdir(cr_dir):
+        fail("slice-gate-stamp: no open change at %s" % args.cr_dir)
+    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
+    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)
+    plan = next((os.path.join(cr_dir, n) for n in DELTA_PLAN_NAMES[lane]
+                 if os.path.isfile(os.path.join(cr_dir, n))), "")
+    rec = {
+        "lane": lane,
+        "cr_id": args.cr_id or os.path.basename(os.path.normpath(cr_dir)),
+        "gated": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "verdict": "pass" if tests_green and requirements_ok else "fail",
+        "tests_green": tests_green,
+        "tests_ran": truthy(args.tests_ran),
+        "requirements_ok": requirements_ok,
+        "findings": len(findings) if findings is not None else None,
+        "high_findings": high,
+        "delta_spec_sha": _file_sha(os.path.join(cr_dir, "delta-spec.md")),
+        "delta_plan": os.path.basename(plan),
+        "delta_plan_sha": _file_sha(plan) if plan else "",
+        "note": SLICE_GATE_NOTE,
+    }
+    path = os.path.join(cr_dir, SLICE_GATE % lane)
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(json.dumps(rec, indent=2) + "\n")
+    emit({
+        "ok": True,
+        "file": os.path.relpath(path, repo).replace("\\", "/"),
+        "lane": lane,
+        "cr_id": rec["cr_id"],
+        "verdict": rec["verdict"],
+        "tests_green": tests_green,
+        "tests_ran": rec["tests_ran"],
+        "requirements_ok": requirements_ok,
+        "findings": rec["findings"],
+        "high_findings": high,
+        "gated": rec["gated"],
+    })
 
 
 def cmd_resolve(args):
@@ -1248,6 +1677,7 @@ def cmd_resolve(args):
         }
         payload.update(kind_block(args.repo, [], "backend"))
         payload.update(kind_block(args.repo, [], "frontend"))
+        apply_working(payload, args.repo, [])
         apply_feature_lanes(payload, fl)
         emit(payload)
         return
@@ -1293,6 +1723,7 @@ def cmd_resolve(args):
     }
     payload.update(kind_block(args.repo, lanes, "backend"))
     payload.update(kind_block(args.repo, lanes, "frontend"))
+    apply_working(payload, args.repo, lanes)
     apply_feature_lanes(payload, fl)
     emit(payload)
 
@@ -1317,6 +1748,12 @@ def cmd_resolve(args):
 # select-stack declares `src/` before any code exists, and the path becomes real
 # when implement writes into it. Every phase that READS the subtree — implement,
 # build, run, onboard — leaves the check on.
+#
+# --working-only narrows the on-disk half to the lanes this developer works on (and any
+# kind the caller requires). A backend developer's build must not stop because the
+# frontend lane — declared, and somebody else's — has not been scaffolded yet. A lane with
+# no root at all, and two lanes overlapping, are still checked for every lane: those are
+# declaration errors, not a lane that is merely somebody else's work in progress.
 
 # Named in the "no <kind> lane is declared, and %s needs one" message, for a caller that
 # passed --require but no --command of its own. `implement` covers both lanes in one
@@ -1333,6 +1770,7 @@ def cmd_verify(args):
     data = read_stacks(repo)
     lanes = (data or {}).get("lanes") or []
     required = [k for k in (args.require or []) if k in ("backend", "frontend")]
+    worked = working_lane(repo, lanes)["kinds"]
     issues = []
 
     # An empty file and an absent one are the SAME state. The kit ships
@@ -1364,7 +1802,8 @@ def cmd_verify(args):
                     "subtree; without one nothing can be built, run or written into it. "
                     "Re-run `/appweaver select-stack` and give it a lane root folder."
                     % (lane_id, kind, lane.get("profile", "?")))
-            elif not args.allow_missing_root and not root_on_disk(repo, root):
+            elif (not args.allow_missing_root and not root_on_disk(repo, root)
+                  and (not args.working_only or kind in worked or kind in required)):
                 issues.append(
                     "lane '%s' (%s, stack %s) declares lane root folder '%s', which is not a "
                     "directory in this repository. Re-run `/appweaver select-stack` and "
@@ -1398,6 +1837,7 @@ def cmd_verify(args):
         "lane_count": len(lanes),
         "kinds": sorted({l.get("kind", "") for l in lanes if l.get("kind")}),
         "root_check": not args.allow_missing_root,
+        "root_check_working_only": bool(args.working_only),
         "issues": issues,
         "issue_count": len(issues),
         # No lanes always carries an issue now, so a clean run always has lanes to name.
@@ -1412,6 +1852,7 @@ def cmd_verify(args):
     }
     payload.update(kind_block(repo, lanes, "backend"))
     payload.update(kind_block(repo, lanes, "frontend"))
+    apply_working(payload, repo, lanes)
     emit(payload)
     # Exit 0 even when the check fails: the workflow gate owns the stop, so the
     # message and every flattened field still reach it. A non-zero exit here would
@@ -1486,7 +1927,7 @@ def cmd_run_phase(args):
     testlog = _testlog()
     ok, ran = True, False
     for lane in lanes:
-        cmd = lane_command(lane, args.phase, repo)
+        cmd = lane_command(lane, args.phase, repo, getattr(args, "contract", "") or "")
         lane_id, root = lane.get("id", "?"), lane.get("root", "")
         if not cmd:
             results.append({"lane": lane_id, "root": root, "cmd": "",
@@ -1779,6 +2220,716 @@ def cmd_contract_export(args):
          unnamed=sum(1 for o in ops if not o["id"]), reason=note, log_tail="")
 
 
+# ─────────────────────────── 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.
+#
+# What it reads, in the plan template's own shapes:
+#   ### `VERB /route` — purpose · Serves …     one endpoint per heading
+#   - **Operation id**: `Name`
+#   - **Request**: `params` + body `{ field: type, … }`
+#   - **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
+# 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.
+
+_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+(.*)$")
+_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")
+
+_BASE_TYPES = {
+    "string": {"type": "string"}, "str": {"type": "string"}, "text": {"type": "string"},
+    "int": {"type": "integer"}, "integer": {"type": "integer"}, "long": {"type": "integer"},
+    "int32": {"type": "integer", "format": "int32"}, "int64": {"type": "integer", "format": "int64"},
+    "short": {"type": "integer"},
+    "decimal": {"type": "number"}, "number": {"type": "number"}, "float": {"type": "number"},
+    "double": {"type": "number"}, "money": {"type": "number", "description": "money"},
+    "amount": {"type": "number"},
+    "bool": {"type": "boolean"}, "boolean": {"type": "boolean"},
+    "date": {"type": "string", "format": "date"},
+    "datetime": {"type": "string", "format": "date-time"},
+    "date-time": {"type": "string", "format": "date-time"},
+    "timestamp": {"type": "string", "format": "date-time"},
+    "instant": {"type": "string", "format": "date-time"},
+    "datetimeoffset": {"type": "string", "format": "date-time"},
+    "time": {"type": "string", "description": "time of day"},
+    "guid": {"type": "string", "format": "uuid"}, "uuid": {"type": "string", "format": "uuid"},
+    "id": {"type": "string"}, "email": {"type": "string", "format": "email"},
+    "url": {"type": "string", "format": "uri"}, "uri": {"type": "string", "format": "uri"},
+    "object": {"type": "object"}, "json": {}, "any": {},
+}
+_NO_SHAPE = {"", "none", "—", "-", "–", "n/a", "no content", "nothing", "empty", "no body"}
+
+
+def _strip_comments(text):
+    return re.sub(r"<!--.*?-->", "", text or "", flags=re.S)
+
+
+def api_section(text):
+    """The text of a backend plan's API section — from the `## ` heading that names the API
+    to the next `## ` heading — or None when the plan has none (the brownfield layout groups
+    its endpoints under its own axes)."""
+    lines = (text or "").splitlines()
+    start = None
+    for n, line in enumerate(lines):
+        m = re.match(r"^##\s+(.*)$", line)
+        if not m:
+            continue
+        if start is not None:
+            return "\n".join(lines[start:n])
+        if re.search(r"\bAPI\b", m.group(1)):
+            start = n
+    return "\n".join(lines[start:]) if start is not None else None
+
+
+def _split_top(s, seps=","):
+    """Split at the separators that are not inside <>, {}, () or []."""
+    out, cur, depth = [], [], 0
+    for ch in s:
+        if ch in "<{([":
+            depth += 1
+        elif ch in ">})]":
+            depth = max(0, depth - 1)
+        if ch in seps and depth == 0:
+            out.append("".join(cur))
+            cur = []
+        else:
+            cur.append(ch)
+    out.append("".join(cur))
+    return [x.strip() for x in out if x.strip()]
+
+
+def _balanced(s, start):
+    """The `{ … }` that opens at s[start], or "" when it never closes."""
+    depth = 0
+    for n in range(start, len(s)):
+        if s[n] == "{":
+            depth += 1
+        elif s[n] == "}":
+            depth -= 1
+            if depth == 0:
+                return s[start:n + 1]
+    return ""
+
+
+def _is_placeholder(s):
+    s = (s or "").strip().strip("`").strip()
+    return s.startswith("[") or s in ("…", "...")
+
+
+class _Drafter(object):
+    """One backend plan's endpoints, as OpenAPI operations."""
+
+    def __init__(self, text):
+        self.text = _strip_comments(text)
+        self.unread = []
+        self.dtos = self._dto_index()
+
+    def _dto_index(self):
+        """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():
+            h = _HEADING.match(line)
+            if h:
+                ticks = re.findall(r"`([^`]+)`", h.group(1))
+                current = ticks[0].strip() if ticks else ""
+                continue
+            m = re.search(r"\*\*(Request|Response)\s*\(DTO\)\*\*\s*:\s*(.+)$", line)
+            if not m or not current:
+                continue
+            value = m.group(2)
+            brace = value.find("{")
+            if brace < 0:
+                continue
+            obj = _balanced(value, brace)
+            if not obj:
+                continue
+            dtos["%s:%s" % (current, m.group(1).lower())] = obj
+            named = re.search(r"([A-Za-z_][A-Za-z0-9_]*)\s*$", value[:brace].replace("`", ""))
+            if named:
+                dtos[named.group(1)] = obj
+        return dtos
+
+    def schema(self, text):
+        raw = (text or "").strip().strip("`").strip().rstrip(".,;").strip()
+        s = raw[:-1].strip() if raw.endswith("?") else raw
+        if not s or s in ("…", "..."):
+            return {}
+        if s.startswith("{") and s.endswith("}"):
+            return self.object_schema(s[1:-1])
+        m = re.match(r"^(list|set|array|collection|seq|sequence|ienumerable|ilist|ireadonlylist)"
+                     r"\s*[<(\[]\s*(.+?)\s*[>)\]]$", s, re.I)
+        if m:
+            return {"type": "array", "items": self.schema(m.group(2))}
+        if s.endswith("[]"):
+            return {"type": "array", "items": self.schema(s[:-2])}
+        m = re.match(r"^(map|dict|dictionary|record)\s*<\s*(.+)\s*>$", s, re.I)
+        if m:
+            parts = _split_top(m.group(2))
+            return {"type": "object",
+                    "additionalProperties": self.schema(parts[-1]) if parts else {}}
+        m = re.match(r"^id\s*[<(]\s*(.+?)\s*[>)]$", s, re.I)
+        if m:
+            return {"type": "string", "description": "id of %s" % m.group(1)}
+        m = re.match(r"^enum\s*[<({\[]\s*(.+?)\s*[>)}\]]$", s, re.I)
+        if m:
+            vals = [v.strip().strip("'\"`") for v in re.split(r"[|,]", m.group(1)) if v.strip()]
+            return {"type": "string", "enum": vals}
+        if "|" in s:
+            vals = [v.strip().strip("'\"") for v in s.split("|") if v.strip()]
+            typed = [v for v in vals if v.lower() not in ("null", "none")]
+            if typed and all(v.lower() in _BASE_TYPES for v in typed):
+                return dict(_BASE_TYPES[typed[0].lower()])
+            if len(vals) > 1 and all(re.match(r"^[A-Za-z][\w-]*$", v) for v in vals):
+                return {"type": "string", "enum": vals}
+        base = _BASE_TYPES.get(s.lower())
+        if base is not None:
+            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)
+        return {"description": raw}
+
+    def object_schema(self, body):
+        props, required = {}, []
+        for item in _split_top(body, ",;"):
+            if _is_placeholder(item):
+                continue
+            m = _FIELD.match(item)
+            if not m:
+                self.unread.append(item)
+                continue
+            name, q, typ = m.groups()
+            optional = bool(q) or typ.rstrip().endswith("?") or "(optional)" in typ.lower()
+            typ = re.sub(r"\(optional\)", "", typ, flags=re.I).strip()
+            props[name] = self.schema(typ)
+            if not optional:
+                required.append(name)
+        out = {"type": "object", "properties": props}
+        if required:
+            out["required"] = required
+        return out
+
+    def shape(self, text, fallback=""):
+        """The schema a Request body or a Success response states: the first `{ … }`, else
+        the first `code` span (a type, a list<…>, or a DTO named elsewhere). None when the
+        text says there is no body; the use case's DTO (`fallback`) when it says nothing."""
+        t = (text or "").strip()
+        if not t:
+            return self.object_schema(fallback[1:-1]) if fallback else None
+        spans = [x.strip() for x in re.findall(r"`([^`]+)`", t) if not _is_placeholder(x)]
+        first = spans[0] if spans else ""
+        # `list<{ … }>` written in one span keeps its wrapper.
+        if re.match(r"^(list|set|array|collection|seq|sequence|map|dict|dictionary|record)\s*<",
+                    first, re.I):
+            return self.schema(first)
+        brace = t.find("{")
+        if brace >= 0:
+            obj = _balanced(t, brace)
+            if obj:
+                return self.object_schema(obj[1:-1])
+        word = (first or t).strip().strip(".")
+        if word.lower() in _NO_SHAPE or re.fullmatch(r"[1-5]\d\d", word):
+            return None
+        if fallback and re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", word) and word not in self.dtos \
+                and word.lower() not in _BASE_TYPES:
+            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)
+        lines = (section if section is not None else self.text).splitlines()
+        blocks, cur = [], None
+        for line in lines:
+            m = _ENDPOINT.match(line)
+            if m:
+                cur = {"method": m.group(2).lower(), "path": m.group(3), "title": m.group(4),
+                       "lines": []}
+                blocks.append(cur)
+                continue
+            if _HEADING.match(line):
+                cur = None
+                continue
+            if cur is not None:
+                cur["lines"].append(line)
+        return [self.operation(b, plan_rel) for b in blocks]
+
+    def operation(self, b, plan_rel):
+        path = re.sub(r":([A-Za-z_]\w*)", r"{\1}", b["path"].split("?")[0].rstrip(".,;"))
+        if len(path) > 1:
+            path = path.rstrip("/")
+        method = b["method"]
+        title = re.sub(r"^[\s—–:-]+", "", b["title"]).strip()
+        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)
+            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
+        maps = ""
+        if "maps to" in fields:
+            ticks = re.findall(r"`([^`]+)`", fields["maps to"])
+            maps = ticks[0].strip() if ticks else fields["maps to"].split()[0] if fields["maps to"] else ""
+        req_dto = self.dtos.get("%s:request" % maps, "")
+        res_dto = self.dtos.get("%s:response" % maps, "")
+
+        op = {}
+        if oid:
+            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["x-aw-draft"] = True
+
+        path_names = re.findall(r"\{([^}]+)\}", path)
+        typed, body = {}, None
+        request = fields.get("request", "")
+        if request:
+            m = re.search(r"\bbody\b", request, re.I)
+            head = request[:m.start()] if m else request
+            if m:
+                body = self.shape(request[m.end():], req_dto)
+            elif method in ("post", "put", "patch") and "{" in request:
+                body = self.shape(request, req_dto)
+            for span in re.findall(r"`([^`]+)`", head):
+                if _is_placeholder(span) or "{" in span:
+                    continue
+                for item in _split_top(span.strip().lstrip("?"), ",;&"):
+                    f = _FIELD.match(item)
+                    if f:
+                        typed[f.group(1)] = (self.schema(f.group(3)), bool(f.group(2)))
+                    elif re.fullmatch(r"[A-Za-z_]\w*", item) and item.lower() not in _NO_SHAPE:
+                        typed.setdefault(item, ({"type": "string"}, True))
+        elif method in ("post", "put", "patch") and req_dto:
+            body = self.object_schema(req_dto[1:-1])
+        params = []
+        for name in path_names:
+            sch = typed.get(name, ({"type": "string"}, False))[0]
+            params.append({"name": name, "in": "path", "required": True, "schema": sch})
+        for name, (sch, _opt) in typed.items():
+            if name not in path_names:
+                params.append({"name": name, "in": "query", "required": False, "schema": sch})
+        if params:
+            op["parameters"] = params
+        if body is not None:
+            op["requestBody"] = {"required": True,
+                                 "content": {"application/json": {"schema": body}}}
+
+        success = fields.get("success", "")
+        status = re.search(r"\b([1-5]\d\d)\b", success)
+        code = status.group(1) if status else "200"
+        after = re.split(r"→|->", success, maxsplit=1)
+        result = self.shape(after[1] if len(after) > 1 else "", res_dto) if success \
+            else (self.object_schema(res_dto[1:-1]) if res_dto else None)
+        responses = {code: {"description": "Success"}}
+        if result is not None and code != "204":
+            responses[code]["content"] = {"application/json": {"schema": result}}
+        for err, when in errors:
+            if err not in responses:
+                responses[err] = {"description": re.sub(r"\s+", " ", when).strip() or "Error"}
+        op["responses"] = responses
+        return path, method, op
+
+
+def _sha_text(text):
+    import hashlib
+    return hashlib.sha256((text or "").encode("utf-8")).hexdigest()
+
+
+def _first_file(folder, names):
+    for name in names:
+        p = os.path.join(folder, name)
+        if os.path.isfile(p):
+            return p
+    return ""
+
+
+def _read(path):
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            return fh.read()
+    except OSError:
+        return ""
+
+
+def _is_draft_file(path):
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return "x-aw-draft" in (json.load(fh) or {})
+    except Exception:
+        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"]))
+    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": ""}
+    if not plan:
+        out["reason"] = "no backend plan in %s — nothing to draft" % rel(fd)
+        return emit(out)
+    text = _read(plan)
+    drafter = _Drafter(text)
+    paths, ids, dupes, seen = {}, [], [], set()
+    for path, method, op in drafter.operations(rel(plan)):
+        if (path, method) in seen:
+            dupes.append("%s %s" % (method.upper(), path))
+            continue
+        seen.add((path, method))
+        paths.setdefault(path, {})[method] = op
+        if op.get("operationId"):
+            ids.append(op["operationId"])
+    count = sum(len(v) for v in paths.values())
+    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)
+    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)
+    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)),
+        },
+        "x-aw-draft": {"source": rel(plan),
+                       "source_sha": _sha_text(section if section is not None else text)},
+        "paths": paths,
+    }
+    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)
+
+
+# ─────────────────────────── 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.
+
+def _draft_files(repo):
+    base = os.path.join(repo, "specs")
+    found = glob.glob(os.path.join(base, "*", DRAFT_NAME)) + \
+        glob.glob(os.path.join(base, "*", "*", DRAFT_NAME))
+    return sorted(set(found))
+
+
+def _route_key(path, method):
+    norm = re.sub(r"\{[^}]*\}", "{}", path.rstrip("/") or "/").lower()
+    return norm, method.upper()
+
+
+def cmd_contract_combine(args):
+    import copy
+    repo = args.repo
+    rel = lambda p: os.path.relpath(p, repo).replace("\\", "/")
+    export_rel = contract_doc(repo)
+    export_abs = os.path.join(repo, export_rel) if export_rel else ""
+    export = None
+    if export_abs and os.path.isfile(export_abs):
+        with open(export_abs, "rb") as fh:
+            export = _api_document(fh.read())
+    out_abs = os.path.join(repo, COMBINED_DOC)
+    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": "",
+              "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 {
+        "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": {},
+    }
+    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):
+                continue
+            for method in CONTRACT_HTTP_METHODS:
+                op = item.get(method)
+                if not isinstance(op, dict):
+                    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)))
+                    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:
+        # 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))
+        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)))
+    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)
+    emit(result)
+
+
+# ─────────────────────────── contract-requests ─────────────────────────────
+# 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
+# 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.
+
+def _tables(text):
+    """Every markdown table: (lowered header cells, [row cells])."""
+    lines = _strip_comments(text).splitlines()
+    out, i = [], 0
+    while i < len(lines):
+        header = _cells(lines[i])
+        rule = _cells(lines[i + 1]) if i + 1 < len(lines) else None
+        if header is None or rule is None or not _is_rule(rule):
+            i += 1
+            continue
+        rows = []
+        i += 2
+        while i < len(lines) and _cells(lines[i]) is not None:
+            rows.append(_cells(lines[i]))
+            i += 1
+        out.append(([h.lower() for h in header], rows))
+    return out
+
+
+def _col(header, *prefixes):
+    for n, h in enumerate(header):
+        if any(h.replace("-", " ").startswith(p) for p in prefixes):
+            return n
+    return -1
+
+
+def frontend_requests(text):
+    reqs, seen = [], set()
+    for header, rows in _tables(text):
+        rc = _col(header, "request")
+        if rc < 0 or _col(header, "outcome") >= 0:
+            continue
+        oc = _col(header, "operation id")
+        cols = {k: _col(header, k) for k in ("needed by", "sends", "receives", "serves")}
+        for row in rows:
+            m = _RQ_ID.search(row[rc]) if rc < len(row) else None
+            if not m or m.group(0) in seen:
+                continue
+            seen.add(m.group(0))
+            ids = _op_ids(row[oc]) if 0 <= oc < len(row) else []
+            cell = lambda k: row[cols[k]].strip() if 0 <= cols[k] < len(row) else ""
+            reqs.append({"id": m.group(0), "proposed": ids[0] if ids else "",
+                         "needed_by": cell("needed by"), "sends": cell("sends"),
+                         "receives": cell("receives"), "serves": cell("serves")})
+    return reqs
+
+
+def backend_answers(text):
+    answers = {}
+    for header, rows in _tables(text):
+        rc, oc = _col(header, "request"), _col(header, "outcome")
+        if rc < 0 or oc < 0:
+            continue
+        ic, wc = _col(header, "operation id"), _col(header, "why")
+        for row in rows:
+            m = _RQ_ID.search(row[rc]) if rc < len(row) else None
+            if not m:
+                continue
+            outcome = row[oc] if oc < len(row) else ""
+            ids = _op_ids(row[ic]) if 0 <= ic < len(row) else []
+            answers[m.group(0)] = {
+                "outcome": ("declined" if re.search(r"declin", outcome, re.I)
+                            else "published" if re.search(r"publish", outcome, re.I) else ""),
+                "id": ids[0] if ids else "",
+                "why": row[wc].strip() if 0 <= wc < len(row) else "",
+            }
+    return answers
+
+
+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)
+    return ids
+
+
+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 ""
+    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 {}
+    be_ids = set(backend_operation_ids(be_text)) if be_plan else set()
+    bound = set(plan_operation_ids(fe_text)[0]) if fe_plan else set()
+
+    open_, declined, published, rebind = [], [], [], []
+    be_lines, fe_lines = [], []
+    for r in reqs:
+        a = answers.get(r["id"]) or {}
+        need = "; ".join("%s %s" % (k.replace("_", " "), r[k]) for k in
+                         ("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")
+        elif a["outcome"] == "declined":
+            r.update(status="declined", answer="", why=a["why"])
+        else:
+            served = a["id"] or r["proposed"]
+            if served and served in be_ids:
+                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"
+                             % (served or "—"))
+        r["rebind"] = r["status"] == "published" and r["answer"] not in bound
+        if r["status"] == "open":
+            open_.append(r["id"])
+            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 "
+                            "without it, or route the need to /appweaver specify"
+                            % (r["id"], r["why"] or "no reason given"))
+        else:
+            published.append(r["id"])
+            if r["rebind"]:
+                rebind.append(r["id"])
+                fe_lines.append("%s was ANSWERED as `%s` — re-bind every binding row that needs "
+                                "it to that operation id" % (r["id"], r["answer"]))
+    orphans = sorted(k for k in answers if k not in {r["id"] for r in reqs})
+    summary = ("%d request(s): %d open, %d answered (%d still to re-bind), %d declined"
+               % (len(reqs), len(open_), len(published), len(rebind), len(declined))) \
+        if reqs else "no contract request"
+    emit({
+        "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 "",
+        "requests": reqs,
+        "count": len(reqs),
+        "open": open_, "open_count": len(open_), "open_csv": ", ".join(open_),
+        "published_count": len(published),
+        "declined": declined, "declined_count": len(declined), "declined_csv": ", ".join(declined),
+        "rebind": rebind, "rebind_count": len(rebind), "rebind_csv": ", ".join(rebind),
+        "orphans": orphans,
+        # What each lane's developer has to do, one line per request, for a prompt to quote.
+        "backend_text": "; ".join(be_lines) or "none",
+        "frontend_text": "; ".join(fe_lines) or "none",
+        "summary": summary,
+    })
+
+
 # ─────────────────────────── contract-check ────────────────────────────────
 # Do the operation ids a frontend plan cites exist in the exported document? Read by
 # script, so the answer does not depend on a model reading two documents carefully.
@@ -1787,6 +2938,8 @@ def cmd_contract_export(args):
 #   - the master plan's §5, a table with an `Operation id` column;
 #   - a delta plan's ADDED/MODIFIED tables, where a row whose section is `Contract
 #     Binding` names the operation id as its element's first `code` span.
+# A table with a `Request` column is the request ledger, not a binding: its operation ids
+# are proposals, and the binding row that needs one cites it on its own.
 
 _OP_ID = re.compile(r"^[A-Za-z_][A-Za-z0-9_.-]*$")
 _NOT_AN_ID = {"none", "tbd", "todo", "na"}
@@ -1825,6 +2978,8 @@ def plan_operation_ids(text):
         lowered = [h.lower() for h in header]
         id_col = next((n for n, h in enumerate(lowered) if h.replace("-", " ") == "operation id"), -1)
         section_col = next((n for n, h in enumerate(lowered) if h.startswith("section")), -1)
+        if "request" in lowered:
+            id_col = section_col = -1
         i += 2
         while i < len(lines) and _cells(lines[i]) is not None:
             row = _cells(lines[i])
@@ -1844,6 +2999,60 @@ def plan_operation_ids(text):
     return cited, uncited
 
 
+# ─────────────────────────── 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
+# 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
+# by its own developer, or in a follow-up change.
+
+def service_delta_changes(text):
+    """[(operation id, 'changed' | 'removed')] from the contract table of a service delta."""
+    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
+        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 "")
+            if ids and kind and ids[0] not in seen:
+                seen.add(ids[0])
+                out.append((ids[0], kind))
+    return out
+
+
+def cmd_contract_impact(args):
+    repo = args.repo
+    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 []
+    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 ""
+    affected = [(x, k) for x, k in changes if x in bound]
+    addressed = [x for x, _ in affected if re.search(r"(?<![\w.-])%s(?![\w.-])" % re.escape(x), fe_delta_text)]
+    unaddressed = [(x, k) for x, k in affected if x not in addressed]
+    emit({
+        "ok": True,
+        "changes": [{"id": x, "change": k} for x, k in changes],
+        "changed_csv": ", ".join("%s (%s)" % (x, k) for x, k in changes),
+        "frontend_bound": len(bound),
+        "affected": [x for x, _ in affected],
+        "addressed": addressed,
+        "frontend_delta_exists": fe_delta_exists,
+        "unaddressed": [{"id": x, "change": k} for x, k in unaddressed],
+        "unaddressed_count": len(unaddressed),
+        "unaddressed_csv": ", ".join("%s (%s)" % (x, k) for x, k in unaddressed),
+        "warn": bool(unaddressed),
+    })
+
+
 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)
@@ -1852,6 +3061,7 @@ def cmd_contract_check(args):
     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": "",
               "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
@@ -1875,12 +3085,19 @@ def cmd_contract_check(args):
         if x not in known:
             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)]
     result.update(missing=missing, doc_operations=len(ops),
-                  doc_unnamed=sum(1 for o in ops if not o["id"]))
+                  doc_unnamed=sum(1 for o in ops if not o["id"]),
+                  drafted=drafted, drafted_csv=", ".join(drafted))
     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:
@@ -2056,14 +3273,58 @@ def main():
                         "will create")
     p.add_argument("--command", default="",
                    help="the phase being gated, quoted back in the failure message")
+    p.add_argument("--working-only", dest="working_only", action="store_true",
+                   help="check on disk only the lane root folders of the working lane(s) "
+                        "(.appweaver/lane.json) and the --require'd kinds")
     p.set_defaults(func=cmd_verify)
 
+    p = sub.add_parser("lane-select", help="read or write the developer's working lane")
+    p.add_argument("--lane", default="",
+                   help="write this working lane: backend, frontend or both (an option "
+                        "line from select_options is accepted)")
+    p.add_argument("--default", action="store_true",
+                   help="write the default for the declared stacks: both when both lanes "
+                        "are declared, otherwise the one that is")
+    p.add_argument("--preselect", default="",
+                   help="direct-argument text; a whole-word match selects that option")
+    p.set_defaults(func=cmd_lane_select)
+
+    p = sub.add_parser("cr-lanes", help="the lanes a change touches: the answers, and the "
+                                        "delta-spec's **Lanes** line")
+    p.add_argument("--delta-spec", dest="delta_spec", default="",
+                   help="the change's delta-spec.md; its **Lanes** line is read, or written "
+                        "with --set / --stamp")
+    p.add_argument("--set", default="",
+                   help="write this answer: both, backend or frontend (an option line from "
+                        "select_options is accepted)")
+    p.add_argument("--stamp", action="store_true",
+                   help="write the line; with no --set, every declared lane")
+    p.set_defaults(func=cmd_cr_lanes)
+
+    p = sub.add_parser("slice-gate-stamp",
+                       help="write one lane's analyze-slice-delta result into the change")
+    p.add_argument("--cr-dir", dest="cr_dir", required=True, help="the change's directory")
+    p.add_argument("--cr-id", dest="cr_id", default="")
+    p.add_argument("--lane", required=True, choices=["backend", "frontend"])
+    p.add_argument("--tests-green", dest="tests_green", default="false",
+                   help="true when no test of the lane failed (green with nothing run when "
+                        "the lane declares no test command)")
+    p.add_argument("--tests-ran", dest="tests_ran", default="false",
+                   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.set_defaults(func=cmd_slice_gate_stamp)
+
     p = sub.add_parser("run-phase", help="run a phase's command for every declared lane")
     p.add_argument("--phase", required=True, choices=["build", "test", "run", "migrate", "client"],
                    help="which project-supplied command to run; `client` is a frontend lane's "
                         "client generator, with {{contract}} expanded")
     p.add_argument("--kind", choices=["backend", "frontend"],
                    help="restrict to one lane kind (default: every declared lane)")
+    p.add_argument("--contract", default="",
+                   help="the API document {{contract}} names (default: the exported one)")
     p.set_defaults(func=cmd_run_phase)
 
     p = sub.add_parser("set", help="change API-contract keys on a declared lane")
@@ -2083,12 +3344,37 @@ def main():
                    help="seconds to wait for the document after starting the service")
     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")
+    p.add_argument("--feature-dir", dest="feature_dir", default="")
+    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")
+    p.set_defaults(func=cmd_contract_combine)
+
+    p = sub.add_parser("contract-requests",
+                       help="the frontend plan's contract requests and the backend 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")
     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.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")
+    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="",
+                   help="the change's delta-frontend-plan.md (may not exist yet)")
+    p.set_defaults(func=cmd_contract_impact)
+
     p = sub.add_parser("probe", help="evidence of a lane of this kind (file signals only)")
     p.add_argument("--kind", choices=["backend", "frontend"], default="frontend")
     p.add_argument("--hint", default="", help="free prose to scan for a stack name")