aw-spec-cli 0.1.32 → 0.1.34

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

@@ -2,7 +2,8 @@
 # aw-spec-plan (orchestrator) — the spec-anchored Plan phase, BOTH LANES
 #
 # Authors the feature's LANE PLANS — the tech-agnostic HLDs that MEDIATE between the
-# spec and the code:
+# spec and the code — and the API contract between them:
+#   • specs/<Context>/<Feature>/api-plan.md       when a BACKEND lane is declared — its endpoints
 #   • specs/<Context>/<Feature>/backend-plan.md   when a BACKEND lane is declared
 #   • specs/<Context>/<Feature>/frontend-plan.md  when a FRONTEND lane is declared
 # `implement` GENERATES each lane's code from ITS PLAN ALONE (model-driven, not a
@@ -33,16 +34,28 @@
 # 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:
+# THE API PLAN COMES FIRST. The backend lane authors api-plan.md — every endpoint the
+# service publishes, the API contract between the lanes — before backend-plan.md, which then
+# realises each endpoint as a use-case. A change does the same in its own directory:
+# delta-api-plan.md first, then delta-backend-plan.md. After the backend half,
+# contract-draft writes api-draft.json beside the plans from the API plan, by script, so a
+# frontend can generate its client against endpoints the service has planned and not built
+# yet. The frontend plan reads the API plan and nothing else of the service's.
+#
+# A FEATURE PLANNED BEFORE API PLANS EXISTED keeps its endpoints in its backend plan, and
+# every reader falls back to that while it has no api-plan.md. Every re-derivation (`main`)
+# offers to move them out while they are there, by script (api-split); finalize-delta moves
+# them when it first merges a change's API into the feature. A change planned before then
+# keeps its API in its delta backend plan, which is re-planned with the API in it.
+#
+# THE CONTRACT HAND-OFF BETWEEN THE TWO LANES. Each lane's developer writes only their own
+# plans, 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.
+# surface lacks — every binding, when there is no API plan yet — and api-plan.md 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 API plan
+# is told which requests are open, the frontend plan which were answered (to re-bind) or
+# declined (to plan around).
 #
 # 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,
@@ -85,9 +98,9 @@
 #     CONFIRMED first — the run stops on a decline, leaving them untouched.
 #     Next: /appweaver analyze-plan (spec↔plan gate) → implement.
 #   • CR-…  → author THAT change's delta plans ONLY (delta-plan module). The masters are
-#     left UNTOUCHED, and finalize-delta does not merge them either: it merges the
-#     change's spec and model halves, and a master plan is RE-DERIVED from those — which
-#     is what the main row above does. The change stays OPEN.
+#     left UNTOUCHED, and finalize-delta does not merge the lane plans either: it merges
+#     the change's spec, model and API halves, and a master plan is RE-DERIVED from those —
+#     which is what the main row above does. The change stays OPEN.
 #     Next: analyze-plan-delta → implement (which asks which change) → build →
 #     analyze-slice-delta → finalize-delta → analyze-slice → close-delta.
 #   • new  → open a plan-only change first, then plan it: a refactor or architectural
@@ -116,8 +129,8 @@
 # =============================================================================
 
 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.5.0
+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, with api-plan.md (the endpoints the service publishes, the API contract the frontend binds to) authored before it; frontend-plan.md when a frontend lane is; all of them 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.8.1
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -161,10 +174,34 @@ vars:
   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: ""
+  # THE SERVICE'S API AS READ CONTEXT for the frontend lane — the API plan, or the backend
+  # plan of a feature planned before API plans existed; and the same for the chosen change.
+  # Bound only when the backend lane is declared, so a plan left behind by a removed lane
+  # never reaches the payload.
+  api_read: ""
+  delta_api_read: ""
+  # THE API PLAN (api-plan.md) — the endpoints the backend lane publishes, authored before
+  # the backend plan on the main path. api_mode: skip | author (fill the template just
+  # scaffolded) | update (revise the API plan that is there, or was just split out).
+  api_plan: ""
+  api_plan_exists: "false"
+  api_go: "false"              # the main path, on a worked backend lane
+  api_mode: "skip"
+  api_created: "false"
+  api_blocked: "false"         # the backend plan still carries the API — the split is offered
+  api_split_answer: ""
+  api_split_done: "false"
+  api_split_endpoints: "0"
+  api_split_dropped: "none"
+  api_split_kept: "true"
+  api_split_ok: "true"         # false when a yes to the split did not move the endpoints
+  api_in_backend: "false"      # the backend plan keeps the API this run: the scaffold refused and no split moved it
+  # What the backend plan's authoring step is told about where the endpoints are — the API
+  # plan, or this document itself when no split moved them out of it.
+  be_api_rule: "THE ENDPOINTS ARE IN api-plan.md (in context), authored just before this document: the API contract the frontend lane binds to. Do NOT restate them here — the API section of this document is the one line pointing to api-plan.md, and where the template has an endpoint block or a requests table (a template generated before API plans existed), that line goes in their place. REALISE every endpoint instead: each names under **Maps to** the use-case that serves it, and that use-case is this document's, with request and response DTOs that match the endpoint's shapes. An endpoint with no use-case here is unrealised. The traceability spine cites an endpoint as `VERB /route`."
+  cr_delta_backend_plan: ""    # cr-paths, on the delta path
+  cr_delta_api_plan: ""
+  cr_delta_api_exists: "false"
   rederive_be_txt: ""
   rederive_fe_txt: ""
   active_change: ""
@@ -236,11 +273,25 @@ vars:
   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_backend_text: "none"     # the frontend's requests still open — what the API plan answers (the backend plan, for a feature with none yet)
   req_frontend_text: "none"    # answered requests to re-bind and declined ones to plan around
   req_summary: ""
   draft_path: ""
+  draft_plan: ""               # the document it was drawn from: api-plan.md, or the backend plan
   draft_ops: "0"
+  draft_unread: "0"            # endpoint shapes the drafting script could not type
+  draft_unread_text: "none"
+  draft_clean: "true"
+  draft_dropped: "0"           # operations the previous draft had and this one does not
+  draft_dropped_text: "none"
+  draft_kept: "true"
+  # The change's own API draft (delta path).
+  draft_change_go: "false"
+  change_draft_path: ""
+  change_draft_plan: ""
+  change_draft_unread: "0"
+  change_draft_unread_text: "none"
+  change_draft_clean: "true"
 
 workflow:
 
@@ -312,6 +363,8 @@ workflow:
       - { name: backend_plan_exists,  from: "$.backend_plan_exists" }
       - { name: frontend_plan,        from: "$.frontend_plan" }
       - { name: frontend_plan_exists, from: "$.frontend_plan_exists" }
+      - { name: api_plan,             from: "$.api_plan" }
+      - { name: api_plan_exists,      from: "$.api_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
@@ -345,12 +398,6 @@ workflow:
     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
   # ENFORCED, so the model has to be in context or the instruction to "follow it exactly"
@@ -615,6 +662,28 @@ workflow:
   #     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.
+  #
+  #     THE API PLAN FIRST, on the main path of a worked backend lane. The scaffold refuses
+  #     (`blocked`) while a backend plan still carries the API, since an empty API plan
+  #     beside it would be read in its place — and a backend plan scaffolded from a template
+  #     generated before API plans existed carries an empty requests table, so on a first
+  #     run the backend plan must not be there yet. The delta path plans the change's API in
+  #     the delta-plan module instead and leaves the master API plan alone.
+  - id: api_go_arm
+    condition: "{{plan_target}} == main"
+    action: set
+    vars: { api_go: "{{be_working}}" }
+  - id: api_scaffold
+    condition: "{{api_go}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: plan-scaffold
+    args: ["--feature-dir", "{{feature_dir}}", "--lane", "api"]
+    outputs:
+      - { name: api_plan,    from: "$.plan_doc" }
+      - { name: api_created, from: "$.created" }
+      - { name: api_blocked, from: "$.blocked" }
+
   - id: be_scaffold
     condition: "{{be_working}} == true"
     action: execute_script
@@ -639,11 +708,100 @@ workflow:
       - { 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"
+  # A FEATURE PLANNED BEFORE API PLANS EXISTED keeps its endpoints in its backend plan, and
+  # the API scaffold above refused to put an empty API plan beside them. Offered on every
+  # re-derivation while they are there: api-split moves every endpoint block and the
+  # requests table into a new api-plan.md by script, leaves a line in the backend plan where
+  # they were, and redraws api-draft.json. A no keeps the old layout for this run — every
+  # reader falls back to the backend plan — and finalize-delta moves them when it first
+  # merges a change's API. Yes is first, so an unattended run moves them: the move only
+  # relocates blocks, and what it drew is checked against the draft before it below. A yes
+  # the split does not complete keeps the old layout too, and is reported.
+  - id: ask_api_split
+    condition: "{{api_blocked}} == true"
+    action: ask
+    prompt: "This feature's endpoints are still in {{backend_plan}}. Move them into their own api-plan.md now? A script does it (api-split): every endpoint block and the requests table go over as they are, the backend plan keeps one line saying where they went, and api-draft.json is redrawn from the new file. The frontend lane's next analyze-plan re-gates once, because the surface it binds to is now a different file. Answer no to keep them where they are for this run."
+    options: ["yes", "no"]
+    answer_var: api_split_answer
+  - id: api_split
+    condition: "{{api_split_answer}} == yes"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: api-split
+    args: ["--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: api_split_done,      from: "$.split" }
+      - { name: api_split_endpoints, from: "$.endpoints" }
+      - { name: api_split_dropped,   from: "$.dropped_text" }
+  - id: api_split_lost
+    condition: "{{api_split_dropped}} != none"
+    action: set
+    vars: { api_split_kept: "false" }
+  - id: warn_api_split_lost
+    condition: "{{api_split_done}} == true"
+    action: verify_context
+    require_true: api_split_kept
+    on_false: continue
+    on_false_message: "API SPLIT — the {{api_split_endpoints}} endpoint(s) moved into {{api_plan}} draw fewer operations than api-draft.json had before: {{api_split_dropped}}. Compare {{api_plan}} with the backend plan's history, restore what is missing, then re-run plan or analyze-plan."
+
+  # A YES THE SPLIT DID NOT COMPLETE — the script failed, or answered without moving the
+  # endpoints. They are still in the backend plan and no api-plan.md was written, so the run
+  # goes on as a declined split does (the backend plan keeps the API, below) and says so.
+  # The engine binds no reason for a script that fails without answering, so the message
+  # names the command that shows it.
+  - id: api_split_ok_flag
+    condition: "{{api_split_answer}} == yes"
     action: set
-    vars: { be_plan_read: "{{backend_plan}}" }
+    vars: { api_split_ok: "{{api_split_done}}" }
+  - id: warn_api_split_failed
+    action: verify_context
+    require_true: api_split_ok
+    on_false: continue
+    on_false_message: "API SPLIT DID NOT COMPLETE — you answered yes, but api-split did not move this feature's endpoints out of {{backend_plan}}, and no api-plan.md was written. This run went on as if the move had been declined: the endpoints stay in the backend plan, and its re-derivation keeps them there. To see why and move them, run `.appweaver/scripts/bash/aw-spec-actions.sh api-split --feature-dir {{feature_dir}}` (PowerShell: `.appweaver/scripts/powershell/aw-spec-actions.ps1 api-split --feature-dir {{feature_dir}}`); once it reports split=true, re-run /appweaver plan main to revise the new api-plan.md."
+
+  # THE API PLAN'S AUTHORING MODE, as ordered assignments: `update` revises an API plan that
+  # was already there; `author` fills a template the scaffold just copied in; a refused
+  # scaffold leaves `skip` and the API in the backend plan (`api_in_backend`) for this run;
+  # a split that happened makes it `update` again, over the blocks it moved, and the API is
+  # no longer in the backend plan.
+  - id: api_mode_existing
+    condition: "{{api_go}} == true"
+    action: set
+    vars: { api_mode: "update" }
+  - id: api_mode_author
+    condition: "{{api_created}} == true"
+    action: set
+    vars: { api_mode: "author" }
+  - id: api_mode_blocked
+    condition: "{{api_blocked}} == true"
+    action: set
+    vars: { api_mode: "skip", api_in_backend: "true" }
+  - id: api_mode_split
+    condition: "{{api_split_done}} == true"
+    action: set
+    vars: { api_mode: "update", api_in_backend: "false" }
+
+  # WHAT THE FRONTEND LANE READS OF THE SERVICE: the API plan when there is one — on disk
+  # already, or authored in this run — and otherwise the backend plan (the scaffold may
+  # have renamed a legacy design.md, so its path is the one taken after the scaffold).
+  # Nothing on an undeclared backend lane.
+  - id: api_read_be
+    condition: "{{be_declared}} == true"
+    action: set
+    vars: { api_read: "{{backend_plan}}" }
+  - id: api_read_on_disk
+    condition: "{{api_plan_exists}} == true"
+    action: set
+    vars: { api_read: "{{api_plan}}" }
+  - id: api_read_authored
+    condition: "{{api_mode}} != skip"
+    action: set
+    vars: { api_read: "{{api_plan}}" }
+  - id: api_read_undeclared
+    condition: "{{be_declared}} == false"
+    action: set
+    vars: { api_read: "" }
 
   # 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
@@ -710,6 +868,16 @@ workflow:
       - { name: req_backend_text, from: "$.backend_text" }
       - { name: req_summary,      from: "$.summary" }
 
+  # THE API STAYS IN THE BACKEND PLAN whenever no split moved it — declined, or a yes the
+  # split did not complete — so its re-derivation is told to keep the endpoint blocks and
+  # answer the requests itself, as it did before API plans existed. Told the endpoints were
+  # in api-plan.md, it would replace them with a pointer to a document that does not exist.
+  - id: be_api_rule_in_plan
+    condition: "{{api_in_backend}} == true"
+    action: set
+    vars:
+      be_api_rule: "THE ENDPOINTS STAY IN THIS DOCUMENT for this run — they have not been moved into api-plan.md. Keep the endpoint blocks of its API section in their form: the `VERB /route` heading, then **Operation id**, Request, Success and the Errors table, every shape `{ field: type }`. OPERATION IDS ARE STABLE: every endpoint keeps the operation id it already has, and a new one gets an id unique across the service. 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 |): 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."
+
   # 6. Pre-execution hooks.
   - id: resolve_pre_hooks
     action: execute_script
@@ -722,6 +890,129 @@ workflow:
     action: dispatch_hooks
     hooks_from_variable: before_hooks
 
+  # ═══════════ THE API PLAN — the endpoints, before the backend plan ══════════
+  # The contract first: the endpoints a client needs, their shapes and their errors, and
+  # the answers to the frontend lane's requests. The backend plan is authored next and
+  # realises each endpoint as a use-case. One template in every project, greenfield or
+  # brownfield — the endpoint block form is what the contract scripts read — so there is
+  # no template split here, only author (a template just scaffolded) or update.
+  - id: ctx_api
+    condition: "{{api_mode}} == author"
+    action: build_context
+    context:
+      - { path: "{{api_plan}}" }                       # the copied template = the fixed endpoint block form
+      - { path: "{{spec_file}}" }                      # BEHAVIOUR: what a client must be able to do
+      - { path: "{{domain_model}}", optional: true }   # the ubiquitous language; the BR-nnn an error answers to
+      - { path: .appweaver/DESIGN-FORMAT.md }          # the HLD contract, and The API plan in it
+      - { path: .appweaver/memory/constitution.technical.md, optional: true } # technology base ONLY — the protocol it publishes
+  - id: gen_api
+    condition: "{{api_mode}} == author"
+    action: agent_author
+    tools: Read   # the feature's EXISTING source arrives as {{source_files}} paths, not inlined
+    output_target: { type: file, path: "{{api_plan}}" }
+    task: |
+      Author the API PLAN (the target api-plan.md in context) for this feature by filling
+      out the template: every endpoint the service lane publishes for it, and its answers
+      to the frontend lane's requests. It is the API contract between the lanes — the
+      frontend plan binds to it, implement serves it, a script drafts it into
+      api-draft.json — and it is written BEFORE the backend plan, which then realises each
+      endpoint as a use-case. Guidance: {{USER_INPUT}}
+      Rules:
+      - THE SPEC IS THE BEHAVIOUR AUTHORITY. Publish the endpoints a client needs to do
+        what the spec's requirements and user stories say, and no more. Each block's
+        heading cites the spec ids it serves; an endpoint no spec id calls for is
+        over-reach.
+      - KEEP THE TEMPLATE'S FORM EXACTLY: one block per endpoint under "## Endpoints" — the
+        heading `### `VERB /route` — purpose · Serves …`, then **Operation id**, **Auth**,
+        **Request**, **Success**, the **Errors** table and **Maps to**. Scripts read exactly
+        this form; an endpoint written as a table row or in prose reaches neither
+        api-draft.json nor the frontend.
+      - EVERY SHAPE IS `{ field: type }` in conceptual types — path and query parameters,
+        request body, success body, each error body. A shape in prose reaches the frontend's
+        client untyped. **Maps to** names the use-case that serves the endpoint; the backend
+        plan, authored next, realises it under that name.
+      - NAME EVERY ENDPOINT. Its **Operation id** is its name in the 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.
+      - THE ERROR CONTRACT: every failure the spec's requirements and the model's BR-nnn
+        imply gets a row — its status, when it is returned, its body shape.
+      - DATA CLASSIFICATION (DC-): a response shape carries no field the spec's DC- items
+        keep from the client; cite the DC- id in the block whose shape it governs.
+      - THE CODE THAT EXISTS IS THE WHAT-IS AUTHORITY. {{source_count}} source file(s)
+        already realise this feature: {{source_files}}. Where the code already serves an
+        endpoint, record its route, verb and operation id exactly as the code has them; one
+        it serves under no id keeps `—` and says so in its block — never an invented id,
+        which the built service would not carry and analyze-slice would report. With no
+        source files there is nothing to conform to.
+      - 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 (| Request | Outcome | Operation id | Why |): PUBLISH
+        it as an 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.
+      - TECHNOLOGY-AGNOSTIC: protocol level only — no controller code, framework
+        attributes, serializer settings or language types. The stack binds at implement.
+      - Write `None` under "## Endpoints" when the feature publishes no endpoint.
+      - Set **Version** to the feature's version as the spec's header gives it, and write
+        the first Change History row.
+
+  # The API plan RE-DERIVED: revised against the spec as it stands now, before the backend
+  # plan is. The document in context is the current API plan — what is being revised, and
+  # its form — and the backend plan as it stands is read for the use-cases its endpoints
+  # map to.
+  - id: ctx_api_update
+    condition: "{{api_mode}} == update"
+    action: build_context
+    context:
+      - { path: "{{api_plan}}" }                       # the CURRENT API plan = what is being revised
+      - { path: "{{spec_file}}" }                      # BEHAVIOUR, carrying every change finalize-delta has merged
+      - { path: "{{domain_model}}", optional: true }   # the ubiquitous language; the BR-nnn an error answers to
+      - { path: "{{backend_plan}}", optional: true }   # READ ONLY — the use-cases the endpoints map to today
+      - { path: .appweaver/DESIGN-FORMAT.md }
+      - { path: .appweaver/memory/constitution.technical.md, optional: true } # technology base ONLY
+  - id: gen_api_update
+    condition: "{{api_mode}} == update"
+    action: agent_author
+    tools: Read   # the feature's EXISTING source arrives as {{source_files}} paths, not inlined
+    output_target: { type: file, path: "{{api_plan}}" }
+    task: |
+      RE-DERIVE the API PLAN in context from the current spec. The document you are given
+      is the feature's API as it stands today; produce the API this feature's spec calls
+      for NOW. It is revised before the backend plan, which then realises each endpoint.
+      Do not edit the backend plan. Guidance: {{USER_INPUT}}
+      Rules:
+      - THIS IS A REVISION, NOT A RE-AUTHORING. Keep every endpoint block the spec still
+        supports, byte-for-byte where nothing requires a change: the frontend plan binds to
+        it, and the built service is checked against it.
+      - OPERATION IDS ARE STABLE. Every endpoint keeps the operation id it already has. A
+        new endpoint gets one unique across the service; an endpoint without one gets one
+        now, unless the code serves it under none, which keeps `—`.
+      - WHAT THE SPEC SAYS NOW WINS. An endpoint no spec id still calls for is deleted with
+        its block; a requirement or user story a client needs and no endpoint serves is a
+        gap — add the endpoint. The draft drawn after this run reports every operation the
+        previous api-draft.json had and this document no longer has.
+      - KEEP THE FORM: one block per endpoint under "## Endpoints" — the `### `VERB /route``
+        heading, then **Operation id**, **Auth**, **Request**, **Success**, the **Errors**
+        table and **Maps to** — every shape `{ field: type }`. A block left in another form
+        by an earlier hand reaches neither api-draft.json nor the frontend: bring it into
+        this form.
+      - 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 (| Request | Outcome | Operation id | Why |): 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.
+        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}}. Where the plan and the code disagree about
+        a route, a verb or an operation id the code serves, the code is what is there —
+        record it as served and let the spec decide whether it changes.
+      - TECHNOLOGY-AGNOSTIC: protocol level only, conceptual types, no code.
+      - ADD ONE Change History row for this re-derivation, describing what moved and why
+        (the spec ids that drove it). Do NOT invent a version number — the version spine
+        belongs to close-delta.
+
   # ═══════════ BACKEND LANE — bootstrap, greenfield four-layer template ═══════
   # Author the whole HLD in one pass: all four layers as sections, tech-agnostic, traced
   # to the spec. build_context REPLACES the per-request envelope; sticky standards stay
@@ -733,6 +1024,7 @@ workflow:
       - { path: "{{backend_plan}}" }            # the copied template = section structure
       - { path: "{{spec_file}}" }               # BEHAVIOUR: FR/CN/DC/IC/US/SC + cited BR ids
       - { path: "{{domain_model}}", optional: true }   # the CONTEXT's canonical model — entities, invariants, boundary
+      - { path: "{{api_plan}}", optional: true }       # the API plan authored just before — the endpoints §2 realises
       - { path: .appweaver/DESIGN-FORMAT.md }      # the HLD contract
       - { path: .appweaver/memory/constitution.technical.md, optional: true } # technology base ONLY — no domain (domain enters via the spec + model)
   - id: gen_backend
@@ -764,32 +1056,18 @@ workflow:
         seams. The spec stays the only authority on BEHAVIOUR; the code is the authority
         on what the structure currently IS. With no source files this is a greenfield
         feature and there is nothing to conform to.
-      - Cover the four layers as sections: Domain (§1), Application (§2), API (§3),
-        Infrastructure (§4). Keep the template's section order and headings.
+      - Cover the four layers as sections: Domain (§1), Application (§2), API (§3 — the
+        one line pointing to api-plan.md), Infrastructure (§4). Keep the template's section
+        order and headings.
+      - {{be_api_rule}}
       - REALISE THE LIFTED CONSTRAINTS (each cites its spec id):
         • Constraints & NFRs (CN-) → structural ones (immutability, append-only audit,
           no-hard-delete) as §1 invariant enforcement/events; retention/performance/audit
           as §5 Cross-Cutting rows or §4 persistence.
-        • Data Classification (DC-) → §5 data-protection + the §2/§3 projection surface
-          (what MUST NOT be exposed in API/logs/traces).
+        • Data Classification (DC-) → §5 data-protection + the §2 projections (what MUST
+          NOT be exposed in responses, logs or traces).
         • Integration Contracts (IC-) → §4.2 External integrations (one port/adapter row
           per IC-), realising the obligation the spec named.
-      - PUBLISH THE SURFACE THE FRONTEND LANE BINDS TO. §3 states each endpoint's contract
-        as field shapes. That section is the ONLY part of this document the frontend plan
-        may read; keep it complete and self-contained, because a contract the UI needs and
-        this document never states becomes a client-side workaround.
-      - NAME EVERY ENDPOINT. Each §3 endpoint carries an **Operation id** — its name in the
-        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
@@ -825,6 +1103,7 @@ workflow:
       - { path: "{{backend_plan}}" }            # the scaffolded BROWNFIELD template = code-derived section structure
       - { path: "{{spec_file}}" }               # BEHAVIOUR: FR/CN/DC/IC/US/SC + cited BR ids
       - { path: "{{domain_model}}", optional: true }   # the CONTEXT's canonical model — entities, invariants, boundary
+      - { path: "{{api_plan}}", optional: true }       # the API plan authored just before — the endpoints §2 realises
       - { path: .appweaver/DESIGN-FORMAT.md }      # the HLD contract (see its Brownfield variant note)
       - { path: knowledge/architecture/overview.md, optional: true }  # the project's AS-BUILT architecture (onboard) — align to it
       - { path: knowledge/architecture/platform.md, optional: true }  # the as-built technology base / cross-cutting reality
@@ -873,22 +1152,9 @@ workflow:
         (immutability, append-only audit, no-hard-delete) as §1.2 invariant enforcement /
         events; retention/performance/audit as §2 persistence or §3 Cross-Cutting rows.
         DC- → §3 data-protection + the projection surface (what MUST NOT be exposed in
-        API/logs/traces).
-      - PUBLISH THE SURFACE THE FRONTEND LANE BINDS TO: the section carrying this feature's
-        endpoints states each contract as field shapes, completely, because it is the only
-        part of this document the frontend plan may read.
-      - NAME EVERY ENDPOINT with its route, verb and operation id — its name in the
-        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.
+        responses, logs or traces).
+      - {{be_api_rule}} The §2 axis this project publishes its endpoints from ends with
+        that line.
       - 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
@@ -927,6 +1193,7 @@ workflow:
       - { path: "{{backend_plan}}" }                   # the CURRENT master = what is being revised, and its section structure
       - { path: "{{spec_file}}" }                      # BEHAVIOUR, carrying every change finalize-delta has merged
       - { path: "{{domain_model}}", optional: true }   # the CONTEXT's canonical model — entities, invariants, boundary
+      - { path: "{{api_plan}}", optional: true }       # the API plan revised just before — absent when no split moved the endpoints
       - { path: .appweaver/DESIGN-FORMAT.md }          # the HLD contract
       - { path: .appweaver/memory/constitution.technical.md, optional: true } # technology base ONLY
   - id: gen_backend_update
@@ -958,17 +1225,7 @@ workflow:
         workarounds are DECISIONS THIS TEAM MADE, not derivations from the spec — keep
         every one, with its id and its basis, unless the thing it decided about is gone.
         Never renumber a surviving entry: its id is cited elsewhere.
-      - 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.
+      - {{be_api_rule}}
       - 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
@@ -981,11 +1238,15 @@ 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.
+  # ══════════════ THE DRAFT — the API plan as a document ═══════════════════════
+  # api-draft.json beside the plans, drawn by script from the API plan as it now stands (the
+  # backend plan's API section, for a feature planned before API plans existed): the API
+  # contract between the lanes. The frontend lane generates its client from it, and
+  # analyze-slice checks that the built service serves it. Rewritten only when it differs;
+  # removed when the plan names no endpoint. Advisory — a plan the script cannot read
+  # leaves the run going. Two things are reported: a shape it cannot type, because the
+  # frontend's client gets that data untyped; and an operation the previous draft had and
+  # this one does not, because the frontend may still bind to it.
   - id: contract_draft
     condition: "{{be_working}} == true"
     action: execute_script
@@ -994,8 +1255,33 @@ workflow:
     subcommand: contract-draft
     args: ["--feature-dir", "{{feature_dir}}"]
     outputs:
-      - { name: draft_path, from: "$.path" }
-      - { name: draft_ops,  from: "$.operations" }
+      - { name: draft_path,         from: "$.path" }
+      - { name: draft_plan,         from: "$.plan" }
+      - { name: draft_ops,          from: "$.operations" }
+      - { name: draft_unread,       from: "$.unread_count" }
+      - { name: draft_unread_text,  from: "$.unread_text" }
+      - { name: draft_dropped,      from: "$.dropped_count" }
+      - { name: draft_dropped_text, from: "$.dropped_text" }
+  - id: draft_unread_flag
+    condition: "{{draft_unread}} != 0"
+    action: set
+    vars: { draft_clean: "false" }
+  - id: warn_draft_unread
+    condition: "{{be_working}} == true"
+    action: verify_context
+    require_true: draft_clean
+    on_false: continue
+    on_false_message: "API DRAFT — {{draft_unread}} endpoint shape(s) in {{draft_plan}} are not written as `{ field: type }`, so the frontend's client gets that data untyped: {{draft_unread_text}}. Write each request and response the way the template's endpoint block does, then re-run plan or analyze-plan."
+  - id: draft_dropped_flag
+    condition: "{{draft_dropped}} != 0"
+    action: set
+    vars: { draft_kept: "false" }
+  - id: warn_draft_dropped
+    condition: "{{be_working}} == true"
+    action: verify_context
+    require_true: draft_kept
+    on_false: continue
+    on_false_message: "API DRAFT — {{draft_dropped}} operation(s) the previous api-draft.json had are no longer in {{draft_plan}}: {{draft_dropped_text}}. The frontend lane may still bind to them. If this run removed them on purpose, the frontend plan has to stop binding to them; if not, restore their blocks in {{draft_plan}} and re-run plan or analyze-plan."
 
   # THE LEDGER AGAIN, for the frontend half: the backend plan may have just answered.
   - id: contract_requests_frontend
@@ -1040,7 +1326,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: "{{be_plan_read}}", optional: true }                    # §5 ONLY — the service's published surface, never its internals
+      - { path: "{{api_read}}", optional: true }                        # §5 ONLY — the service's API: api-plan.md, or the backend plan of a feature planned before it
   - id: gen_frontend
     condition: "{{fe_mode}} == bootstrap_gf"
     action: agent_author
@@ -1084,22 +1370,23 @@ workflow:
         gap: log it as a §8 DA-n and say it routes to `specify`; never invent the
         requirement here.
       - §5 IS 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 those contracts; do NOT restate, re-derive or contradict them,
-        and introduce NO server-side behaviour, persistence assumption or handler detail.
+        the spec's IC- ids, and where the service's API is in context (api-plan.md, or the
+        API section of a backend plan written before API plans existed), the endpoints it
+        states. CITE those contracts; do NOT restate, re-derive or contradict them, and
+        introduce NO server-side behaviour, persistence assumption or handler detail.
       - 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.
+        API in context, EVERY binding is a request. The backend developer answers each in
+        the API 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, or the id its request proposes —
+        **Operation id** in the API in context, 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
@@ -1142,7 +1429,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: "{{be_plan_read}}", optional: true }                    # §5 ONLY — the service's published surface, never its internals
+      - { path: "{{api_read}}", optional: true }                        # §5 ONLY — the service's API: api-plan.md, or the backend plan of a feature planned before it
   - id: gen_frontend_brownfield
     condition: "{{fe_mode}} == bootstrap_bf"
     action: agent_author
@@ -1182,19 +1469,20 @@ workflow:
         or its logs, storage and URLs, IC- as binding rows, SC- as the performance
         decision.
       - 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
+        spec's IC- ids and, where the service's API is in context (api-plan.md, or the API
+        section of a backend plan written before API plans existed), the endpoints it
         states. Cite them; do not restate, re-derive or contradict them, and introduce no
         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 RQ-n. With NO API 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
+      - EVERY BINDING ROW CITES ITS OPERATION ID, copied exactly from the API in context,
+        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
@@ -1225,7 +1513,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: "{{be_plan_read}}", optional: true }                    # §5 ONLY — the service's published surface, never its internals
+      - { path: "{{api_read}}", optional: true }                        # §5 ONLY — the service's API: api-plan.md, or the backend plan of a feature planned before it
   - id: gen_frontend_update
     condition: "{{fe_mode}} == update"
     action: agent_author
@@ -1251,20 +1539,21 @@ workflow:
         source file(s) realise this feature: {{source_files}}. Read them and conform to
         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.
+        — the spec's IC- ids and, where the service's API is in context (api-plan.md, or
+        the API section of a backend plan written before API plans existed), the
+        endpoints 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.
+        already in the table with its id — the API plan's answers refer to it. With NO
+        API 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
+      - EVERY BINDING ROW CITES ITS OPERATION ID, copied exactly from the API in context 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.
+        id the API 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.
@@ -1371,10 +1660,13 @@ 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.
+      # THIS CHANGE'S API, as READ context for its frontend delta plan — what the experience
+      # binds to, which the backend developer may have authored in a run of their own: the
+      # delta API plan, or the delta backend plan of a change planned before those.
+      # Bound below only on a declared backend lane.
       - { name: cr_delta_backend_plan, from: "$.delta_backend_plan" }
+      - { name: cr_delta_api_plan,     from: "$.delta_api_plan" }
+      - { name: cr_delta_api_exists,   from: "$.delta_api_plan_exists" }
       # 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
@@ -1386,10 +1678,18 @@ workflow:
       - { name: cr_touches_backend,  from: "$.touches_backend" }
       - { name: cr_touches_frontend, from: "$.touches_frontend" }
 
-  - id: delta_backend_plan_read_set
+  - id: delta_api_read_be
     condition: "{{be_declared}} == true"
     action: set
-    vars: { delta_backend_plan_read: "{{cr_delta_backend_plan}}" }
+    vars: { delta_api_read: "{{cr_delta_backend_plan}}" }
+  - id: delta_api_read_on_disk
+    condition: "{{cr_delta_api_exists}} == true"
+    action: set
+    vars: { delta_api_read: "{{cr_delta_api_plan}}" }
+  - id: delta_api_read_undeclared
+    condition: "{{be_declared}} == false"
+    action: set
+    vars: { delta_api_read: "" }
 
   # 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,
@@ -1428,6 +1728,39 @@ workflow:
     action: include
     module: .appweaver/orchestrator/modules/delta-plan.orch.yaml
 
+  # THE CHANGE'S API DRAFT — what its delta API plan adds, changes and removes in the
+  # service's API (its delta backend plan's, for a change planned before delta API plans
+  # existed), drawn by script into changes/<CR-id>/api-draft.json. While the change is
+  # open the frontend lane binds to it over the feature's draft, analyze-slice-delta checks
+  # the built service against it, and finalize-delta merges the change's API into the
+  # feature's api-plan.md, whose redrawn draft then carries it.
+  - id: draft_change_arm
+    condition: "{{plan_target}} == delta"
+    action: set
+    vars: { draft_change_go: "{{be_existing}}" }
+  - id: contract_draft_change
+    condition: "{{draft_change_go}} == true"
+    action: execute_script
+    on_error: continue
+    script: { ref: actions }
+    subcommand: contract-draft
+    args: ["--feature-dir", "{{feature_dir}}", "--cr", "{{cr_id}}"]
+    outputs:
+      - { name: change_draft_path,        from: "$.path" }
+      - { name: change_draft_plan,        from: "$.plan" }
+      - { name: change_draft_unread,      from: "$.unread_count" }
+      - { name: change_draft_unread_text, from: "$.unread_text" }
+  - id: change_draft_unread_flag
+    condition: "{{change_draft_unread}} != 0"
+    action: set
+    vars: { change_draft_clean: "false" }
+  - id: warn_change_draft_unread
+    condition: "{{draft_change_go}} == true"
+    action: verify_context
+    require_true: change_draft_clean
+    on_false: continue
+    on_false_message: "API DRAFT — {{change_draft_unread}} endpoint shape(s) in {{change_draft_plan}} are not written as `{ field: type }`, so the frontend's client gets that data untyped: {{change_draft_unread_text}}. Write each endpoint the change adds or changes as a whole block under its endpoints section, the way the API plan does, then re-run plan {{cr_id}} or analyze-plan-delta."
+
   # 6b. CROSS-SLICE EDGES, from the document that states them. `aw-xref record` reads the
   #     MASTER service plan — §1 References-by-id and the External integrations table — and
   #     writes a Cross-References row into every sibling aggregate this one uses. Its input
@@ -1468,10 +1801,11 @@ workflow:
   #     conformance gate) → implement. No change is opened either way.
   #   • DELTA → the chosen change stays OPEN with filled delta plans. Ship it via the CR
   #     chain: /appweaver analyze-plan-delta → implement → build → analyze-slice-delta
-  #     → finalize-delta (merges the delta into spec.md + domain-model.md — not the lane
-  #     plans, which are derived from those two; the change stays OPEN) → analyze-slice
-  #     → close-delta (archives the change, bumps the minor version). Re-deriving the
-  #     masters from the merged documents is `plan main` on a later run.
+  #     → finalize-delta (merges the delta into spec.md + domain-model.md, and its delta
+  #     API plan into api-plan.md — not the lane plans, which are derived from those; the
+  #     change stays OPEN) → analyze-slice → close-delta (archives the change, bumps the
+  #     minor version). Re-deriving the masters from the merged documents is `plan main`
+  #     on a later run.
 
   # 7. Post-execution hooks.
   - id: resolve_post_hooks
@@ -1488,6 +1822,8 @@ workflow:
 outputs:
   feature_dir: "{{feature_dir}}"
   bounded_context: "{{context}}"
+  api_plan: "{{api_plan}}"              # api-plan.md — the endpoints the service publishes, the API contract the frontend binds to
+  api_mode: "{{api_mode}}"              # author | update | skip (not the main path, not your lane, or no split moved the endpoints out of the backend plan)
   backend_plan: "{{backend_plan}}"      # empty when no backend lane is declared
   frontend_plan: "{{frontend_plan}}"    # empty when no frontend lane is declared
   frontend_excluded: "{{fe_excluded}}" # true = a frontend lane is declared and this feature records no surface in it (feature-lanes)
@@ -1500,7 +1836,8 @@ outputs:
   version: "{{version}}"
   change_id: "{{active_change}}"
   source_count: "{{source_count}}"
-  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."
+  api_draft: "{{draft_path}}"          # api-draft.json, drafted by script from {{draft_plan}} ({{draft_ops}} operation(s)) — the API contract the frontend binds to; commit it with the plans
+  change_api_draft: "{{change_draft_path}}"   # on the delta path: changes/<CR-id>/api-draft.json, the change's API changes — commit it with the change
+  contract_requests: "{{req_summary}}" # the frontend plan's RQ-n requests and the API 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 API plan answers them; commit the plans so the other lane's developer sees them. The API plan: api_mode {{api_mode}} — `author` or `update` means it was written before the backend plan, which realises its endpoints; `skip` means this run did not write it (not the main path, not your lane, or the endpoints are still in the backend plan). 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, and its delta API plan into api-plan.md — not the lane plans, which are derived from those — 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."