aw-spec-cli 0.1.29 → 0.1.31

package/assets/.appweaver/orchestrator/workflows/aw-spec-plan.orch.yaml

@@ -16,6 +16,34 @@
 # With NO lane declared at all the phase stops and names select-stack — a plan written
 # against no declared stack invents its own.
 #
+# IT PLANS THE DEVELOPER'S WORKING LANE. .appweaver/lane.json (select-stack writes the
+# default, select-lane narrows it, not committed) says which declared lanes the developer
+# on this machine works on. Only a WORKING lane is scaffolded, authored, re-derived or
+# delta-planned here; a lane that is declared but somebody else's is READ, never written —
+# the frontend plan still binds to the backend plan's published surface when another
+# developer owns it. The menu and the re-derive question below look only at the working
+# lanes' masters, so a frontend developer planning a feature whose backend is already
+# planned gets a first-run bootstrap of the frontend plan, with no question and no rewrite
+# of the backend plan. With the default (every declared lane) nothing changes.
+#
+# A CHANGE IS PLANNED ONLY IN THE LANES IT NAMES. Each change's delta-spec carries a
+# **Lanes** line (specify asks for it). The menu lists only the changes that touch a
+# working lane — the others are named in the question instead — and a change's delta plans
+# are written for the lanes that are on its line, worked here and planned already. A
+# backend-only change gets no frontend delta plan, even from a developer on `both`. A
+# change with no such line touches every lane.
+#
+# THE CONTRACT HAND-OFF BETWEEN THE TWO PLANS. Each lane's developer writes only their own
+# plan, so what the frontend needs from the service travels as a REQUEST LEDGER:
+# frontend-plan.md §5 "Contract deltas needed" holds one RQ-n per operation it needs and the
+# surface lacks — every binding, when there is no backend plan yet — and backend-plan.md §3
+# answers each in "Requests from the frontend lane", published under an operation id or
+# declined with the reason. contract-requests reads both before each lane is authored: the
+# backend plan is told which requests are open, the frontend plan which were answered (to
+# re-bind) or declined (to plan around). After the backend half, contract-draft writes
+# api-draft.json beside the plan from its API section, by script, so a frontend can
+# generate its client against endpoints the service has planned and not built yet.
+#
 # ONE COMMAND, TWO LANES, TWO RULE SETS. The lanes take their rules from different
 # headings of tech-rule-bindings (`## /aw-spec-plan-backend` for the service,
 # `## /aw-spec-plan-frontend` for the frontend), and each set is loaded only when its lane
@@ -64,7 +92,8 @@
 #     analyze-slice-delta → finalize-delta → analyze-slice → close-delta.
 #   • new  → open a plan-only change first, then plan it: a refactor or architectural
 #     decision where the realisation of EXISTING spec ids moves with no spec delta. Its
-#     delta-spec stays an unfilled stub, and that stub is the signal downstream.
+#     delta-spec stays an unfilled stub, and that stub is the signal downstream. It asks
+#     which lanes the change touches, as specify does, and stamps the stub's **Lanes** line.
 # The argument doubles as the answer — `plan main`, `plan CR-…` and `plan new` all skip
 # the prompt — and only the WHOLE argument counts, so guidance prose never selects.
 #
@@ -88,7 +117,7 @@
 
 name: aw-spec-plan
 description: "Author the feature's lane plans from the spec and the bounded context's domain model — backend-plan.md when a backend lane is declared, frontend-plan.md when a frontend lane is, both when both are. Lanes come from .appweaver/stacks.json, so one command covers backend-only, frontend-only and full-stack projects; the former separate design-ui command is folded in. It ASKS what it is planning, the way implement asks what it is building: the master (`main`), one of the OPEN CHANGES, or a new plan-only change for a refactor with no spec delta — the argument doubles as the answer, and the menu appears only once a master exists, so a first run bootstraps with no prompt. `main` on a feature that already has masters RE-DERIVES them from the merged spec.md + domain-model.md — the operation finalize-delta's contract assumes when it merges a change's spec and model halves and no lane plan — and is confirmed before it rewrites anything. A change instead gets delta-backend-plan.md / delta-frontend-plan.md inside changes/<CR-id>/ while the masters stay untouched, written against the effective model (the master model, the change's own model delta, and the pending model deltas of LOWER waves, which are its predecessors) and against the feature's real source files from its OKF concept. Master authoring is template-driven: the kit's templates by default, or the code-derived as-built structure when onboard installed an override. Authoring only — a master gates at analyze-plan; a change ships through the CR chain."
-version: 5.1.0
+version: 5.5.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -125,6 +154,19 @@ vars:
   fe_excluded: "false"        # this feature records no surface in the declared frontend lane (feature-lanes)
   be_lane_id: ""
   fe_lane_id: ""
+  # THE WORKING LANES (.appweaver/lane.json) — the declared lanes this developer writes.
+  # A declared lane that is not working is READ (its plan reaches the other lane's
+  # context) and never scaffolded, authored, re-derived or delta-planned.
+  be_working: "false"
+  fe_working: "false"
+  any_working: "false"
+  working_lane: ""
+  # The backend plans AS READ CONTEXT for the frontend lane — bound only when the backend
+  # lane is declared, so a plan left behind by a removed lane never reaches the payload.
+  be_plan_read: ""
+  delta_backend_plan_read: ""
+  rederive_be_txt: ""
+  rederive_fe_txt: ""
   active_change: ""
   has_change: "false"
   version: ""
@@ -134,7 +176,7 @@ vars:
   fe_mode: "skip"              # skip | bootstrap_gf | bootstrap_bf | update
   be_brownfield: "false"       # plan-scaffold.override_active — onboard installed the code-derived template
   fe_brownfield: "false"
-  be_created: "false"          # plan-scaffold.created — true ⇒ the document was ABSENT ⇒ bootstrap
+  be_created: "false"          # plan-scaffold.created — reported only; NEW vs EXISTING is read from feature-paths before the scaffold
   fe_created: "false"
   be_migrated: "false"         # a legacy design.md was renamed into backend-plan.md this run
   fe_migrated: "false"
@@ -166,6 +208,21 @@ vars:
   main_label: ""               # cr-list --include-main's exact label, to test the selection against
   new_label: ""                # cr-list --include-new's
   open_new: "false"            # the NEW row was chosen ⇒ open a plan-only change before planning it
+  change_lane_options: []      # the NEW row's question: which lanes the plan-only change touches
+  change_lane_has: "false"
+  change_lanes_ask: "false"    # open_new AND the declared stacks offer an answer
+  change_lanes: ""             # the answer; empty ⇒ every declared lane is stamped
+  change_lanes_csv: ""         # what the new change's **Lanes** line records
+  # THE CHANGE'S LANES. The menu lists only the changes touching the working lane(s); a
+  # change's delta plans are written only for the lanes its **Lanes** line names.
+  plan_hidden_csv: ""          # open changes left out of the menu: they touch only the other lane
+  plan_hidden_note: ""         # …said in the menu's question when there are any
+  plan_preselect_hidden: ""    # the argument named one of those
+  preselect_visible: "true"
+  cr_lanes_csv: ""             # the lanes the chosen change touches
+  cr_touches_backend: "true"   # every lane until cr-paths answers
+  cr_touches_frontend: "true"
+  delta_any: "false"           # some lane is left to delta-plan after that narrowing
   has_changes: "false"
   rederive_needed: "false"     # main was chosen on a feature that already has masters
   rederive: "false"            # …and the rewrite was confirmed
@@ -178,6 +235,12 @@ vars:
   model_scope_plan: ""         # which part of those sections the domain layer realises
   source_files: []             # the feature's real source files, from its OKF concept
   source_count: "0"
+  # THE REQUEST LEDGER and the draft (contract-requests / contract-draft).
+  req_backend_text: "none"     # the frontend's requests still open — what the backend plan answers
+  req_frontend_text: "none"    # answered requests to re-bind and declined ones to plan around
+  req_summary: ""
+  draft_path: ""
+  draft_ops: "0"
 
 workflow:
 
@@ -199,6 +262,9 @@ workflow:
       - { name: fe_lane_id,      from: "$.frontend_lane_id" }
       - { name: fe_language,     from: "$.frontend_language" }
       - { name: fe_root,         from: "$.frontend_source_path" }
+      - { name: working_lane,    from: "$.working_lane" }
+      - { name: be_working,      from: "$.backend_working" }   # re-read per feature below
+      - { name: fe_working,      from: "$.frontend_working" }
 
   - id: require_lane
     action: verify_context
@@ -222,7 +288,7 @@ workflow:
   #    tech_select_ui_master before the master frontend sections, and the delta-plan
   #    module's own swap before the frontend delta plan.
   - id: tech_select
-    condition: "{{be_declared}} == true"
+    condition: "{{be_working}} == true"
     action: include
     module: .appweaver/orchestrator/modules/tech-select.orch.yaml
     with: { command: aw-spec-plan-backend }
@@ -238,6 +304,14 @@ workflow:
       - { name: feature_dir, from: "$.feature_dir" }
       - { name: spec_file,   from: "$.spec_file" }
       - { name: spec_exists, from: "$.spec_exists" }
+      # Both plans' paths and whether each is on disk (either spelling — the legacy design.md
+      # / design.ui.md resolve here too). NEW vs EXISTING per lane is decided from these,
+      # BEFORE anything is scaffolded, so a run that stops at the re-derive question leaves
+      # no template behind for the next run to mistake for an authored plan.
+      - { name: backend_plan,         from: "$.backend_plan" }
+      - { name: backend_plan_exists,  from: "$.backend_plan_exists" }
+      - { name: frontend_plan,        from: "$.frontend_plan" }
+      - { name: frontend_plan_exists, from: "$.frontend_plan_exists" }
 
   # THIS FEATURE'S LANES. lane_resolve above read the REPO's declaration; one feature may
   # own no part of a lane's surface — adopt records `lanes: [backend]` in
@@ -255,6 +329,27 @@ workflow:
       - { name: be_declared, from: "$.backend_declared" }
       - { name: fe_declared, from: "$.frontend_declared" }
       - { name: fe_excluded, from: "$.frontend_feature_excluded" }
+      - { name: be_working,  from: "$.backend_working" }
+      - { name: fe_working,  from: "$.frontend_working" }
+
+  # A WORKING LANE THIS FEATURE HAS. The working lanes are the developer's; the feature may
+  # record no surface in one of them (feature-lanes), and then there is nothing here for
+  # this developer to plan. Stopping says so — skipping silently would report a plan run
+  # that wrote nothing.
+  - id: any_working_be
+    condition: "{{be_working}} == true"
+    action: set
+    vars: { any_working: "true" }
+  - id: any_working_fe
+    condition: "{{fe_working}} == true"
+    action: set
+    vars: { any_working: "true" }
+
+  # The backend plan as READ context for the frontend lane, on a declared backend only.
+  - id: be_plan_read_set
+    condition: "{{be_declared}} == true"
+    action: set
+    vars: { be_plan_read: "{{backend_plan}}" }
 
   # The BOUNDED CONTEXT's domain model — where the aggregate root, its entities and its
   # invariants (BR-n) live. The spec cites them by id; this phase records where each is
@@ -313,6 +408,12 @@ workflow:
     on_false: stop
     on_false_message: "No spec.md for the current feature. Run /appweaver specify first."
 
+  - id: require_working_lane
+    action: verify_context
+    require_true: any_working
+    on_false: stop
+    on_false_message: "Nothing to plan for your working lane `{{working_lane}}` (.appweaver/lane.json): this feature records no surface in it (backend declared for this feature={{be_declared}}, frontend={{fe_declared}}). Run /appweaver select-lane to work on another lane, or /appweaver select-feature to plan a feature that has this lane."
+
   # 3. Read the open change state (set by specify). The delta path uses it to decide
   #    whether there is anything to plan at all.
   - id: read_change
@@ -340,59 +441,33 @@ workflow:
       - { name: source_files, from: "$.paths" }
       - { name: source_count, from: "$.count" }
 
-  # 5. Scaffold each DECLARED lane's plan (idempotent — returns the existing path when it
-  #    already exists, and RENAMES a legacy design.md / design.ui.md into the plan name).
-  - id: be_scaffold
-    condition: "{{be_declared}} == true"
-    action: execute_script
-    script: { ref: actions }
-    subcommand: plan-scaffold
-    args: ["--feature-dir", "{{feature_dir}}", "--lane", "backend"]
-    outputs:
-      - { name: backend_plan,  from: "$.plan_doc" }
-      - { name: be_brownfield, from: "$.override_active" }   # true ⇒ onboard installed the code-derived template
-      - { name: be_created,    from: "$.created" }           # true ⇒ the document was ABSENT ⇒ bootstrap
-      - { name: be_migrated,   from: "$.migrated" }          # true ⇒ a legacy design.md was renamed into place
-
-  - id: fe_scaffold
-    condition: "{{fe_declared}} == true"
-    action: execute_script
-    script: { ref: actions }
-    subcommand: plan-scaffold
-    args: ["--feature-dir", "{{feature_dir}}", "--lane", "frontend"]
-    outputs:
-      - { name: frontend_plan, from: "$.plan_doc" }
-      - { name: fe_brownfield, from: "$.override_active" }
-      - { name: fe_created,    from: "$.created" }
-      - { name: fe_migrated,   from: "$.migrated" }
-
-  # 5a. Self-detect NEW-vs-EXISTING per lane, from each plan document's OWN existence
-  #     (symmetric with specify's spec.md trigger). A scaffold reports created=true only
-  #     when it had to CREATE the document, so created=false on a DECLARED lane means the
-  #     plan pre-existed and that lane's change is a delta.
-  #     A MIGRATED document counts as pre-existing: it is the same plan under its new
-  #     name, and its content was authored before this run.
-  #     Taking the lane's own `declared` value under the created/not-created condition is
-  #     how the AND is expressed — an undeclared lane's flags stay false either way.
+  # 5. Self-detect NEW-vs-EXISTING per WORKING lane, from each plan document's OWN
+  #    existence (symmetric with specify's spec.md trigger), read off feature-paths BEFORE
+  #    anything is written. A legacy design.md / design.ui.md counts as existing: it is the
+  #    same plan under its old name, authored before this run, and the scaffold at 5f
+  #    renames it into place.
+  #    Taking the lane's own `working` value under the exists/not-exists condition is how
+  #    the AND is expressed — a lane that is not worked keeps both flags false, so it is
+  #    never offered, re-derived, bootstrapped or delta-planned here.
   - id: be_flag_new
-    condition: "{{be_created}} == true"
+    condition: "{{backend_plan_exists}} == false"
     action: set
-    vars: { be_new: "{{be_declared}}" }
+    vars: { be_new: "{{be_working}}" }
   - id: be_flag_existing
-    condition: "{{be_created}} == false"
+    condition: "{{backend_plan_exists}} == true"
     action: set
-    vars: { be_existing: "{{be_declared}}" }
+    vars: { be_existing: "{{be_working}}" }
   - id: fe_flag_new
-    condition: "{{fe_created}} == true"
+    condition: "{{frontend_plan_exists}} == false"
     action: set
-    vars: { fe_new: "{{fe_declared}}" }
+    vars: { fe_new: "{{fe_working}}" }
   - id: fe_flag_existing
-    condition: "{{fe_created}} == false"
+    condition: "{{frontend_plan_exists}} == true"
     action: set
-    vars: { fe_existing: "{{fe_declared}}" }
+    vars: { fe_existing: "{{fe_working}}" }
 
-  # Either declared lane having a pre-existing master means this feature HAS BEEN PLANNED
-  # ONCE. That is the precondition for both of the things the menu below offers — a delta
+  # Either WORKING lane having a pre-existing master means this feature HAS BEEN PLANNED
+  # ONCE, for this developer. That is the precondition for both of the things the menu below offers — a delta
   # has to have a master to be a delta OF, and a re-derivation has to have a document to
   # re-derive. The two raises are independent so neither can cancel the other.
   - id: master_exists_backend
@@ -420,12 +495,18 @@ workflow:
   # needs one to be a delta of, and so does a plan-only change. So a first run authors the
   # masters with no prompt at all, exactly as before — and if a change is already open on
   # such a feature, it waits for the next run, when the menu will offer it.
+  #
+  # ONLY THE CHANGES THAT TOUCH YOUR WORKING LANE. `--lane` keeps the changes whose
+  # **Lanes** line names the working lane (every change, for `both`); a change for the other
+  # lane only has no delta plan for this developer to write, and is named in the question
+  # instead of offered. It goes last in the args, where an empty value cannot be mistaken
+  # for the next flag.
   - id: cr_list
     condition: "{{master_exists}} == true"
     action: execute_script
     script: { ref: actions }
     subcommand: cr-list
-    args: ["--feature-dir", "{{feature_dir}}", "--preselect", "{{USER_INPUT}}", "--include-main", "--include-new"]
+    args: ["--feature-dir", "{{feature_dir}}", "--preselect", "{{USER_INPUT}}", "--include-main", "--include-new", "--lane", "{{working_lane}}"]
     outputs:
       - { name: change_options, from: "$.select_options" }
       - { name: matched_label,  from: "$.matched_label" }
@@ -433,6 +514,25 @@ workflow:
       - { name: new_label,      from: "$.new_label" }
       - { name: has_changes,    from: "$.has_changes" }
       - { name: change_count,   from: "$.count" }
+      - { name: plan_hidden_csv,       from: "$.hidden_ids_csv" }
+      - { name: plan_preselect_hidden, from: "$.preselect_hidden" }
+
+  # `plan CR-…` naming a change for the other lane only stops here, rather than showing a
+  # menu that leaves the named change out without saying why.
+  - id: preselect_hidden_flag
+    condition: "{{plan_preselect_hidden}} != "
+    action: set
+    vars: { preselect_visible: "false" }
+  - id: require_visible_change
+    action: verify_context
+    require_true: preselect_visible
+    on_false: stop
+    on_false_message: "Change {{plan_preselect_hidden}} does not touch your working lane `{{working_lane}}` (.appweaver/lane.json): its **Lanes** line names only the other lane, so there is no delta plan for you to write. Run /appweaver select-lane to work on that lane — or, if the change does need your lane, widen it first with `.appweaver/scripts/bash/aw-spec-actions.sh cr-lanes --cr-id {{plan_preselect_hidden}} --set both`."
+
+  - id: hidden_note_set
+    condition: "{{plan_hidden_csv}} != "
+    action: set
+    vars: { plan_hidden_note: " Not listed, because they touch only the other lane: {{plan_hidden_csv}}." }
 
   # The argument doubles as the answer: `plan main` and `plan CR-…` both resolve to a
   # label in matched_label and skip the prompt. Only the WHOLE argument counts as one of
@@ -440,7 +540,7 @@ workflow:
   - id: pick_target
     condition: "{{master_exists}} == true"
     action: user_select
-    prompt: "What is being planned? `main` re-plans the feature's master from its spec and domain model. A CR row authors that change's delta plans only, leaving the masters untouched — deltas sharing a wave are independent, and a higher wave is planned on top of the lower ones. `new` opens a plan-only change, for a refactor or architectural decision with no spec delta."
+    prompt: "What is being planned? `main` re-plans the feature's master from its spec and domain model. A CR row authors that change's delta plans only, leaving the masters untouched — deltas sharing a wave are independent, and a higher wave is planned on top of the lower ones. `new` opens a plan-only change, for a refactor or architectural decision with no spec delta.{{plan_hidden_note}}"
     options_from_variable: change_options
     preselect_from: matched_label
     single_option_confirm: true
@@ -482,10 +582,20 @@ workflow:
     action: set
     vars: { rederive_needed: "{{master_exists}}" }
 
+  # Which masters a yes rewrites — only the working lanes' — named in the question.
+  - id: rederive_be_named
+    condition: "{{be_existing}} == true"
+    action: set
+    vars: { rederive_be_txt: "backend-plan.md " }
+  - id: rederive_fe_named
+    condition: "{{fe_existing}} == true"
+    action: set
+    vars: { rederive_fe_txt: "frontend-plan.md " }
+
   - id: confirm_rederive
     condition: "{{rederive_needed}} == true"
     action: ask
-    prompt: "This feature already has master plan(s). Re-derive them from the current spec.md and domain-model.md? Recorded architectural decisions (DA-n) and workarounds (WA-n) are carried forward, but any section the spec and model no longer support IS REWRITTEN — including hand edits. Answer no to stop without touching them."
+    prompt: "This feature already has the master plan(s) {{rederive_be_txt}}{{rederive_fe_txt}}for your working lane `{{working_lane}}`. Re-derive them from the current spec.md and domain-model.md? Recorded architectural decisions (DA-n) and workarounds (WA-n) are carried forward, but any section the spec and model no longer support IS REWRITTEN — including hand edits. A lane you do not work on is not touched. Answer no to stop without touching them."
     options: ["no", "yes"]
     answer_var: rederive_answer
 
@@ -501,6 +611,40 @@ workflow:
     on_false: stop
     on_false_message: "Stopped — the master plans were left untouched. Re-run and answer yes to re-derive them, or pick a change instead (/appweaver plan CR-…) to author that change's delta plans without touching a master."
 
+  # 5f. Scaffold each WORKING lane's plan now that the run is going ahead (idempotent — it
+  #     returns the existing path when the plan is there, and RENAMES a legacy design.md /
+  #     design.ui.md into the plan name). It sits after the question on purpose: a template
+  #     copied in before a `no` stays on disk, and the next run reads it as a master.
+  - id: be_scaffold
+    condition: "{{be_working}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: plan-scaffold
+    args: ["--feature-dir", "{{feature_dir}}", "--lane", "backend"]
+    outputs:
+      - { name: backend_plan,  from: "$.plan_doc" }
+      - { name: be_brownfield, from: "$.override_active" }   # true ⇒ onboard installed the code-derived template
+      - { name: be_created,    from: "$.created" }
+      - { name: be_migrated,   from: "$.migrated" }          # true ⇒ a legacy design.md was renamed into place
+
+  - id: fe_scaffold
+    condition: "{{fe_working}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: plan-scaffold
+    args: ["--feature-dir", "{{feature_dir}}", "--lane", "frontend"]
+    outputs:
+      - { name: frontend_plan, from: "$.plan_doc" }
+      - { name: fe_brownfield, from: "$.override_active" }
+      - { name: fe_created,    from: "$.created" }
+      - { name: fe_migrated,   from: "$.migrated" }
+
+  # The scaffold may have renamed a legacy design.md, so the READ path is taken again.
+  - id: be_plan_read_scaffolded
+    condition: "{{be_working}} == true"
+    action: set
+    vars: { be_plan_read: "{{backend_plan}}" }
+
   # 5e. Resolve each lane's authoring MODE. Four ordered assignments per lane: the
   #     greenfield default for a new lane, the code-derived override replacing it, a
   #     `skip` for any lane that is not new — which silences both bootstrap branches on
@@ -552,6 +696,20 @@ workflow:
     action: set
     vars: { fe_mode: "update" }
 
+  # 5g. THE REQUEST LEDGER as it stands before either lane is authored — the requests the
+  #     frontend plan has raised that the backend plan has not answered yet. Read by script
+  #     from both plans; advisory, so a plan without the tables reads as no request.
+  - id: contract_requests_backend
+    condition: "{{be_working}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: contract-requests
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: req_backend_text, from: "$.backend_text" }
+      - { name: req_summary,      from: "$.summary" }
+
   # 6. Pre-execution hooks.
   - id: resolve_pre_hooks
     action: execute_script
@@ -624,6 +782,14 @@ workflow:
         service's published API document (e.g. `CreatePatient`), unique across the
         service and never reused. The frontend plan cites it, and implement gives the
         endpoint exactly this id, so the two lanes meet on it.
+      - ANSWER THE FRONTEND LANE'S CONTRACT REQUESTS. Still open in the frontend plan's §5
+        "Contract deltas needed": {{req_backend_text}}. Answer each one in §3's "Requests
+        from the frontend lane" table (| Request | Outcome | Operation id | Why |): PUBLISH
+        it as a §3 endpoint, under the operation id it proposes unless that clashes with
+        one this service already uses, or DECLINE it with the reason. Publish only what
+        the spec supports — a request the spec gives no basis for is declined as a spec gap
+        for /appweaver specify, never published on a guess. `none` means no request is
+        open: write `None` under that heading when the table would be empty.
       - CONSTITUTION-MANDATED CROSS-CUTTING (from the loaded technical constitution, NOT
         the spec): a NON-NEGOTIABLE technical principle you must apply that has NO
         per-feature spec id. APPLY it (it is non-negotiable), and because it is not
@@ -715,6 +881,14 @@ workflow:
         service's published API document, unique across the service. Where the code
         already gives the endpoint one, record THAT id exactly as the code spells it; the
         frontend plan cites it and implement finds the endpoint by it.
+      - ANSWER THE FRONTEND LANE'S CONTRACT REQUESTS. Still open in the frontend plan's
+        "Contract deltas needed" table: {{req_backend_text}}. Answer each one in a
+        "Requests from the frontend lane" table beside this feature's endpoints (| Request
+        | Outcome | Operation id | Why |): PUBLISH it as an endpoint, under the operation id
+        it proposes unless that clashes with one the service already uses, or DECLINE it
+        with the reason. Publish only what the spec supports — a request the spec gives no
+        basis for is declined as a spec gap for /appweaver specify. `none` means no request
+        is open: write `None` under that heading when the table would be empty.
       - CONSTITUTION-MANDATED CROSS-CUTTING (from the loaded technical constitution, NOT
         the spec): a NON-NEGOTIABLE technical principle with no per-feature spec id —
         APPLY it, and LOG it as a §5 DA-n whose basis cites the mandating principle
@@ -787,6 +961,14 @@ workflow:
       - OPERATION IDS ARE STABLE. Every endpoint keeps the operation id it already has —
         the frontend plan and the built code both use it. A new endpoint gets one, unique
         across the service; an endpoint without one gets one now.
+      - ANSWER THE FRONTEND LANE'S CONTRACT REQUESTS. Still open in the frontend plan's §5
+        "Contract deltas needed": {{req_backend_text}}. Answer each one in the "Requests
+        from the frontend lane" table of the API section (| Request | Outcome | Operation id
+        | Why |) — add the table if the document has none: PUBLISH it as an endpoint, under
+        the operation id it proposes unless that clashes with one already in use, or
+        DECLINE it with the reason. Publish only what the spec supports — a request the
+        spec gives no basis for is declined as a spec gap for /appweaver specify. Keep
+        every row the table already has. `none` means no request is open.
       - THE CODE THAT EXISTS IS THE WHAT-IS AUTHORITY. {{source_count}} source file(s)
         realise this feature: {{source_files}}. READ them, and where the plan and the code
         disagree about STRUCTURE, the code is what is actually there — conform to it and
@@ -799,6 +981,34 @@ workflow:
         (the spec ids and BR-nnn that drove it). Do NOT invent a version number — the
         version spine belongs to close-delta.
 
+  # ══════════════ THE DRAFT — the backend plan's API section as a document ══════
+  # api-draft.json beside the plan, drawn by script from the API section as it now stands,
+  # so the frontend lane can generate its client against what the service has planned
+  # before the service is built. Rewritten only when it differs; removed when the plan
+  # names no endpoint. Advisory — a plan the script cannot read leaves the run going.
+  - id: contract_draft
+    condition: "{{be_working}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: contract-draft
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: draft_path, from: "$.path" }
+      - { name: draft_ops,  from: "$.operations" }
+
+  # THE LEDGER AGAIN, for the frontend half: the backend plan may have just answered.
+  - id: contract_requests_frontend
+    condition: "{{fe_working}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: contract-requests
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: req_frontend_text, from: "$.frontend_text" }
+      - { name: req_summary,       from: "$.summary" }
+
   # ══════════════ THE LANE SWAP — the frontend's rules replace the backend's ═══
   # Both tech-select includes used to run up at step 4, before either lane authored
   # anything, and sticky standards only accumulate — so on a full-stack run the backend
@@ -830,7 +1040,7 @@ workflow:
       - { path: "{{domain_model}}", optional: true }                    # the ubiquitous language this lane's labels and messages use
       - { path: .appweaver/DESIGN-FORMAT.md }                           # the design-doc contract + its frontend lane variant
       - { path: .appweaver/memory/constitution.ui.md, optional: true }  # the lane's ratified UX-* base — optional: a lane may be declared before it is ratified
-      - { path: "{{backend_plan}}", optional: true }                    # §5 ONLY — the service's published surface, never its internals
+      - { path: "{{be_plan_read}}", optional: true }                    # §5 ONLY — the service's published surface, never its internals
   - id: gen_frontend
     condition: "{{fe_mode}} == bootstrap_gf"
     action: agent_author
@@ -877,14 +1087,20 @@ workflow:
         the spec's IC- ids, and where the backend plan is in context, the API contracts
         it states. CITE those contracts; do NOT restate, re-derive or contradict them,
         and introduce NO server-side behaviour, persistence assumption or handler detail.
-        Anything the experience needs that the surface does not offer is a CONTRACT
-        DELTA raised back to the service lane under "Contract deltas needed" — never a
-        workaround in the client. Where no service plan is in context, bind from the
-        spec's IC- surface and record that as a §8 DA-n.
+      - WHAT THE SURFACE DOES NOT OFFER IS A CONTRACT REQUEST, never a workaround in the
+        client: one row in §5's "Contract deltas needed" table per operation, with a new
+        RQ-n (never renumber or reuse one), the operation id you propose, what it sends
+        and receives as field shapes, and the spec ids it serves. The binding row that
+        needs it cites that proposed id and names the RQ-n in its Serves cell. With NO
+        backend plan in context, EVERY binding is a request. The backend developer
+        answers each in the backend plan; this plan never edits that one.
+      - THE BACKEND'S ANSWERS SO FAR: {{req_frontend_text}}. Re-bind every binding row of
+        an answered request to the operation id the backend gave it, and plan around a
+        declined one — or log a §8 DA-n routing the need to /appweaver specify. `none`
+        means no answer is waiting on this plan.
       - EVERY §5 ROW CITES ITS OPERATION ID, copied exactly from the endpoint's
-        **Operation id** in the backend plan's §3 — implement looks the endpoint up by it
-        in the service's exported API document. Where no service plan names one, write
-        `—` and record it in the same §8 DA-n.
+        **Operation id** in the backend plan's §3, or the id its request proposes —
+        implement looks the endpoint up by it in the API document.
       - CONSTITUTION-MANDATED CROSS-CUTTING (from the loaded UI constitution, NOT the
         spec): a NON-NEGOTIABLE UX principle you must apply that has no per-feature spec
         id. APPLY it, and because it is not spec-derived, LOG it as a §8 DA-n whose
@@ -926,7 +1142,7 @@ workflow:
       - { path: .appweaver/DESIGN-FORMAT.md }                           # the design-doc contract + its frontend lane variant
       - { path: .appweaver/memory/constitution.ui.md, optional: true }  # the lane's UX-* base, reversed by onboard from this same UI
       - { path: knowledge/architecture/frontend.md, optional: true }    # the as-built UI architecture + the SHARED surface no slice owns
-      - { path: "{{backend_plan}}", optional: true }                    # §5 ONLY — the service's published surface, never its internals
+      - { path: "{{be_plan_read}}", optional: true }                    # §5 ONLY — the service's published surface, never its internals
   - id: gen_frontend_brownfield
     condition: "{{fe_mode}} == bootstrap_bf"
     action: agent_author
@@ -968,11 +1184,18 @@ workflow:
       - THE LANE BOUNDARY: bind against the service's PUBLISHED surface only — the
         spec's IC- ids and, where the backend plan is in context, the API contracts it
         states. Cite them; do not restate, re-derive or contradict them, and introduce no
-        server-side behaviour. What the experience needs and the surface lacks is a
-        contract delta raised back to the service lane, never a client workaround.
-      - EVERY BINDING ROW CITES ITS OPERATION ID, copied exactly from the backend plan —
-        implement looks the endpoint up by it in the service's exported API document.
-        Where no service plan names one, write `—` and record it as a DA-n.
+        server-side behaviour.
+      - WHAT THE SURFACE LACKS IS A CONTRACT REQUEST, never a client workaround: one row
+        in the "Contract deltas needed" table per operation, with a new RQ-n (never
+        renumbered or reused), the operation id you propose, what it sends and receives,
+        and the spec ids it serves; the binding row that needs it cites that id and names
+        the RQ-n. With NO backend plan in context, EVERY binding is a request.
+      - THE BACKEND'S ANSWERS SO FAR: {{req_frontend_text}}. Re-bind an answered
+        request's binding rows to the id the backend gave it; plan around a declined one,
+        or log a DA-n routing the need to /appweaver specify. `none` means nothing waits.
+      - EVERY BINDING ROW CITES ITS OPERATION ID, copied exactly from the backend plan, or
+        the id its request proposes — implement looks the endpoint up by it in the API
+        document.
       - CONSTITUTION-MANDATED CROSS-CUTTING with no per-feature spec id: apply it, and
         log it as a DA-n citing the mandating principle ("per constitution.ui.md
         UX-<n>"). Do not fabricate a spec id for it and do not leave it uncited.
@@ -1002,7 +1225,7 @@ workflow:
       - { path: "{{domain_model}}", optional: true }                    # the ubiquitous language this lane's labels and messages use
       - { path: .appweaver/DESIGN-FORMAT.md }                           # the design-doc contract + its frontend lane variant
       - { path: .appweaver/memory/constitution.ui.md, optional: true }  # the lane's ratified UX-* base
-      - { path: "{{backend_plan}}", optional: true }                    # §5 ONLY — the service's published surface, never its internals
+      - { path: "{{be_plan_read}}", optional: true }                    # §5 ONLY — the service's published surface, never its internals
   - id: gen_frontend_update
     condition: "{{fe_mode}} == update"
     action: agent_author
@@ -1029,11 +1252,19 @@ workflow:
         the component boundaries and naming actually there.
       - THE LANE BOUNDARY IS UNCHANGED: bind against the service's PUBLISHED surface only
         — the spec's IC- ids and, where the backend plan is in context, the API contracts
-        it states. What the experience needs and the surface lacks is a contract delta
-        raised back to the service lane, never a client workaround.
-      - EVERY BINDING ROW CITES ITS OPERATION ID, copied exactly from the backend plan; a
-        row that has none yet gets it now, and a row whose id the backend plan no longer
-        has is re-bound. Where no service plan names one, write `—` with a DA-n.
+        it states.
+      - WHAT THE SURFACE LACKS IS A CONTRACT REQUEST, never a client workaround: one row
+        in §5's "Contract deltas needed" table per operation, with a new RQ-n, the
+        operation id you propose, what it sends and receives, and the spec ids it serves;
+        the binding row that needs it cites that id and names the RQ-n. KEEP every request
+        already in the table with its id — the backend plan's answers refer to it. With NO
+        backend plan in context, EVERY binding is a request.
+      - THE BACKEND'S ANSWERS SO FAR: {{req_frontend_text}}. Re-bind an answered
+        request's binding rows to the id the backend gave it; plan around a declined one,
+        or log a §8 DA-n routing the need to /appweaver specify. `none` means nothing waits.
+      - EVERY BINDING ROW CITES ITS OPERATION ID, copied exactly from the backend plan or
+        the id its request proposes; a row that has none yet gets one now, and a row whose
+        id the backend plan no longer has is re-bound.
       - TECHNOLOGY-AGNOSTIC: no framework, router, state library, component library or
         styling approach — responsibilities, field shapes, events and states only.
       - ADD ONE Change History row for this re-derivation, describing what MOVED and why.
@@ -1048,6 +1279,33 @@ workflow:
   # unchanged and the realisation of EXISTING spec ids moves (a refactor, an architectural
   # decision). cr-setup scaffolds the delta-spec, which stays an unfilled stub on this
   # path — that stub IS the signal to every downstream gate that no requirement moved.
+  #
+  # It is asked first which lanes the change touches, as specify asks when it opens one:
+  # both — listed first, the default — or one lane alone, from the stacks declared, and
+  # with one declared lane there is no question. The answer is not narrowed to this
+  # developer's working lane: a refactor may need both lanes even when one developer
+  # opened it. It is stamped on the stub's **Lanes** line.
+  - id: change_lane_options
+    condition: "{{open_new}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: cr-lanes
+    outputs:
+      - { name: change_lane_options, from: "$.select_options" }
+      - { name: change_lane_has,     from: "$.has_options" }
+  - id: change_lanes_ask_arm
+    condition: "{{open_new}} == true"
+    action: set
+    vars: { change_lanes_ask: "{{change_lane_has}}" }
+  - id: ask_change_lanes
+    condition: "{{change_lanes_ask}} == true"
+    action: user_select
+    prompt: "Which lanes does this plan-only change touch? The answer is recorded on the change's **Lanes** line as the lanes that plan and build it."
+    options_from_variable: change_lane_options
+    single_option_confirm: true
+    outputs:
+      - { name: change_lanes, from: selection }
+
   - id: open_change
     condition: "{{open_new}} == true"
     action: execute_script
@@ -1057,6 +1315,19 @@ workflow:
     outputs:
       - { name: opened_cr, from: "$.cr_id" }
 
+  # --set goes last: an empty answer is dropped by PowerShell 5.1, and the script then
+  # stamps every declared lane. A failure leaves the template placeholder, which reads as
+  # every declared lane.
+  - id: stamp_change_lanes
+    condition: "{{open_new}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: cr-lanes
+    args: ["--cr-id", "{{opened_cr}}", "--feature-dir", "{{feature_dir}}", "--stamp", "--set", "{{change_lanes}}"]
+    outputs:
+      - { name: change_lanes_csv, from: "$.lanes_csv" }
+
   # Coalesce the two ways in. An existing change arrived as a LABEL ("CR-… · wave 2 ·
   # title") and the scripts take its first token; a just-opened one arrives as a bare id.
   - id: cr_choice_picked
@@ -1100,16 +1371,58 @@ workflow:
       - { name: predecessor_ids,   from: "$.predecessor_ids" }
       - { name: sibling_count,     from: "$.sibling_count" }
       - { name: sibling_ids,       from: "$.sibling_ids" }
+      # THIS CHANGE'S SERVICE HALF, as READ context for its frontend delta plan — the
+      # contract table the experience binds to, which the backend developer may have
+      # authored in a run of their own. Bound below only on a declared backend lane.
+      - { name: cr_delta_backend_plan, from: "$.delta_backend_plan" }
       # Predecessors AND siblings in one list: the delta plan is authored against both, and
       # a build_context takes a single `context_from:` variable. Which entries are which is
       # carried by predecessor_ids / sibling_ids, because the planner's licence over the two
       # is opposite — a predecessor may be built on, a sibling may only be designed around.
       - { name: related_docs,      from: "$.related_docs" }
+      # The lanes this change touches — its delta-spec's **Lanes** line, every lane when it
+      # records none.
+      - { name: cr_lanes_csv,        from: "$.lanes_csv" }
+      - { name: cr_touches_backend,  from: "$.touches_backend" }
+      - { name: cr_touches_frontend, from: "$.touches_frontend" }
+
+  - id: delta_backend_plan_read_set
+    condition: "{{be_declared}} == true"
+    action: set
+    vars: { delta_backend_plan_read: "{{cr_delta_backend_plan}}" }
+
+  # ONLY THE LANES THE CHANGE NAMES. be_existing / fe_existing already mean "a working lane
+  # with a master plan"; a lane the change's **Lanes** line leaves out is knocked down here,
+  # so a backend-only change gets no frontend delta plan even from a developer on `both`.
+  # This runs after every master-path use of the two flags — the delta-plan module below is
+  # the only reader left.
+  - id: be_not_in_change
+    condition: "{{cr_touches_backend}} == false"
+    action: set
+    vars: { be_existing: "false" }
+  - id: fe_not_in_change
+    condition: "{{cr_touches_frontend}} == false"
+    action: set
+    vars: { fe_existing: "false" }
+  - id: delta_any_be
+    condition: "{{be_existing}} == true"
+    action: set
+    vars: { delta_any: "true" }
+  - id: delta_any_fe
+    condition: "{{fe_existing}} == true"
+    action: set
+    vars: { delta_any: "true" }
+  - id: require_delta_lane
+    condition: "{{plan_target}} == delta"
+    action: verify_context
+    require_true: delta_any
+    on_false: stop
+    on_false_message: "Change {{cr_id}} touches {{cr_lanes_csv}}, but no lane on that list is both one you work on (`{{working_lane}}`) and planned already — a delta plan needs a master plan to be a delta of (backend master on disk = {{backend_plan_exists}}, frontend = {{frontend_plan_exists}}). Run /appweaver plan main to author the missing master first, or /appweaver select-lane to work on the lane this change needs."
 
-  # Author that change's delta plans — one per declared lane whose MASTER exists, inside
-  # changes/<CR-id>/ beside its delta-spec. The masters are left UNTOUCHED; the change
-  # stays OPEN and finalize-delta merges it later. Runs in this context (shares vars +
-  # the lane rule sets + source_files).
+  # Author that change's delta plans — one per lane the change names that you work on and
+  # whose MASTER exists, inside changes/<CR-id>/ beside its delta-spec. The masters are left
+  # UNTOUCHED; the change stays OPEN and finalize-delta merges it later. Runs in this
+  # context (shares vars + the lane rule sets + source_files).
   - id: delta_plan_module
     condition: "{{plan_target}} == delta"
     action: include
@@ -1181,10 +1494,13 @@ outputs:
   domain_model: "{{domain_model}}"
   plan_mode: "{{plan_mode}}"
   plan_target: "{{plan_target}}"
+  working_lane: "{{working_lane}}"     # the developer's working lane(s) — .appweaver/lane.json
   be_mode: "{{be_mode}}"
   fe_mode: "{{fe_mode}}"
   version: "{{version}}"
   change_id: "{{active_change}}"
   source_count: "{{source_count}}"
-  note: "This run was pointed at `{{plan_target}}` (plan_mode {{plan_mode}}); backend lane {{be_mode}}, frontend lane {{fe_mode}}. Lanes come from .appweaver/stacks.json: backend declared = {{be_declared}}, frontend declared = {{fe_declared}}. A declared lane gets a plan; an undeclared one gets nothing and that is not a failure. A lane whose mode is `update` had its MASTER re-derived from the current spec and model, with its DA-n and WA-n ledgers carried forward — that rewrite was confirmed before it ran. The domain model at {{domain_model}} was READ, never written — it is spec-tier, and this phase records where each invariant is ENFORCED rather than what it says."
+  api_draft: "{{draft_path}}"          # api-draft.json, drafted by script from the backend plan's API section ({{draft_ops}} operation(s)) — commit it with the plan
+  contract_requests: "{{req_summary}}" # the frontend plan's RQ-n requests and the backend plan's answers
+  note: "This run was pointed at `{{plan_target}}` (plan_mode {{plan_mode}}); backend lane {{be_mode}}, frontend lane {{fe_mode}}. Lanes come from .appweaver/stacks.json: backend declared = {{be_declared}}, frontend declared = {{fe_declared}}; your working lane is `{{working_lane}}` (.appweaver/lane.json — backend worked = {{be_working}}, frontend worked = {{fe_working}}). A working lane gets a plan; a declared lane you do not work on is read, never written, and an undeclared one gets nothing — neither is a failure. Contract requests: {{req_summary}} — the frontend plan raises them in §5 'Contract deltas needed' and the backend plan answers them in its API section; commit the plans so the other lane's developer sees them. A lane whose mode is `update` had its MASTER re-derived from the current spec and model, with its DA-n and WA-n ledgers carried forward — that rewrite was confirmed before it ran. The domain model at {{domain_model}} was READ, never written — it is spec-tier, and this phase records where each invariant is ENFORCED rather than what it says."
   next: "MAIN (masters authored or re-derived): /appweaver analyze-plan (spec↔plan gate) → implement. DELTA (change {{active_change}} open, delta plans authored): /appweaver analyze-plan-delta → implement → build → analyze-slice-delta → finalize-delta → analyze-slice → close-delta — implement is the same command on both paths and ASKS which open change it is building, so pass the id (/appweaver implement {{active_change}}) to skip the prompt (finalize-delta merges the delta into spec.md and domain-model.md — not the lane plans, which are derived from those two — but leaves the change open; analyze-slice verifies the slice against the merged masters; close-delta archives the change and bumps the minor version). Once a change has merged, /appweaver plan main re-derives the masters from the documents it merged into."