aw-spec-cli 0.1.33 → 0.1.35

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

@@ -13,12 +13,14 @@
 # is ACTIVATED so the stages after this one act on the same delta.
 #
 # THE FIVE CHECKS:
-#   1. delta-spec.md → delta-backend-plan.md   — every ADDED/MODIFIED spec item realised
+#   1. delta-spec.md → delta-backend-plan.md + delta-api-plan.md — every ADDED/MODIFIED
+#      spec item realised, and every endpoint the change's API adds or changes realised by
+#      an element of its delta backend plan
 #   2. delta-spec.md → delta-frontend-plan.md  — every experience item realised
-#   3. delta plan ↔ delta plan — CONTRACT BINDING across the change: what the frontend
-#      delta binds to must appear in the service delta's "Contract deltas for the frontend
-#      lane" table or in the master's published surface. A call neither publishes passes
-#      both one-sided checks and fails at integration.
+#   3. the change's API ↔ delta-frontend-plan.md — CONTRACT BINDING across the change: what
+#      the frontend delta binds to must appear in the change's API (its delta-api-plan.md)
+#      or in the feature's (api-plan.md). A call neither publishes passes both one-sided
+#      checks and fails at integration.
 #   4. THE EFFECTIVE MODEL — domain-model.md + this change's model delta + the model
 #      deltas of every LOWER-WAVE change (its predecessors). Every structural item the
 #      model delta adds has a realisation row; nothing structural is invented in a plan.
@@ -41,8 +43,16 @@
 # repaired or stopped on. Its delta plan not existing yet is a note, not a refusal — check 3
 # waits until both halves are on disk.
 #
+# THE SERVICE HALF IS TWO DOCUMENTS. The endpoints a change adds, changes and removes, and
+# the requests it answers, are in its delta-api-plan.md — the one finalize-delta merges into
+# api-plan.md, block by block — and its delta-backend-plan.md realises them. Both are in
+# context with the feature's API plan, and a repair rewrites the one the gap is in, the
+# delta API plan first. A change planned before delta API plans existed keeps its API in
+# its delta backend plan's contract table and API section, which every check then reads and
+# an API repair rewrites.
+#
 # A SERVICE CHANGE THAT BREAKS A FRONTEND BINDING IS A WARNING (contract-impact). An
-# operation the service delta changes or removes that the master frontend plan binds to,
+# operation the change's API changes or removes that the master frontend plan binds to,
 # and that the change's frontend delta plan does not name, is reported by script before the
 # check — whatever lanes the change names. The frontend half may follow from its own
 # developer or in a follow-up change, so it never stops the gate.
@@ -72,8 +82,8 @@
 # =============================================================================
 
 name: aw-spec-analyze-plan-delta
-description: The delta-spec↔delta-plan conformance gate for ONE open change — confirm its delta-backend-plan.md and delta-frontend-plan.md realise delta-spec.md, bind to each other's contract deltas, realise this change's domain model delta, and only MODIFY elements the masters really define. Checked against the EFFECTIVE model (domain-model.md plus this change's model delta plus every lower-wave predecessor's, whose delta-specs are in context too) and told, deterministically, which other open changes touch the same aggregates. Gates only the lanes the change names that you work on — the other developer's delta plan is read for the contract check, its gaps are reported for them, and its absence is a note. Warns, by script, when the service delta changes or removes an operation the frontend binds to and the frontend half does not follow. Asks which open change it is gating when more than one names your lane; a CR id as the argument selects without a prompt. Does not modify the masters or close the change.
-version: 2.2.0
+description: The delta-spec↔delta-plan conformance gate for ONE open change — confirm its delta-api-plan.md, delta-backend-plan.md and delta-frontend-plan.md realise delta-spec.md, that the frontend delta binds to the API the change and the feature publish, realise this change's domain model delta, and only MODIFY elements the masters really define. Checked against the EFFECTIVE model (domain-model.md plus this change's model delta plus every lower-wave predecessor's, whose delta-specs are in context too) and told, deterministically, which other open changes touch the same aggregates. Gates only the lanes the change names that you work on — the other developer's delta plan is read for the contract check, its gaps are reported for them, and its absence is a note. Warns, by script, when the service delta changes or removes an operation the frontend binds to and the frontend half does not follow. Asks which open change it is gating when more than one names your lane; a CR id as the argument selects without a prompt. Does not modify the masters or close the change.
+version: 2.5.0
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -158,6 +168,28 @@ vars:
   backend_repair: "false"
   frontend_repair: "false"
   delta_backend_plan: ""
+  # THE API — the change's delta-api-plan.md and the feature's api-plan.md, each in context
+  # with the backend lane's documents when it exists. A change planned before delta API
+  # plans has none: its delta backend plan carries its API, and an API repair goes there.
+  delta_api_plan: ""
+  delta_api_plan_exists: "false"
+  api_plan: ""
+  api_plan_exists: "false"
+  impact_go: "false"        # a delta backend or delta API plan is on disk ⇒ contract-impact runs
+  api_delta_go: "false"
+  api_master_go: "false"
+  be_api_delta_ctx: ""
+  api_master_ctx: ""
+  api_repair: "false"       # the analyze pass found a gap in an endpoint of the change's API
+  api_repair_go: "false"    # …and this pass rewrites delta-api-plan.md for it
+  api_in_backend: "false"   # …or, with no delta API plan, rewrites the delta backend plan
+  # What the delta backend plan's repair is told about the change's API — set below.
+  be_delta_api_rule: ""
+  change_draft_path: ""
+  change_draft_plan: ""     # the document the change's draft was drawn from
+  change_draft_unread: "0"
+  change_draft_unread_text: "none"
+  change_draft_clean: "true"
   delta_frontend_plan: ""
   # The plan paths AS CONTEXT — bound only for a lane this run actually gates. feature-paths
   # and cr-paths resolve every path whatever the declaration says, so putting them straight
@@ -205,6 +237,8 @@ workflow:
       - { name: frontend_plan,        from: "$.frontend_plan" }
       - { name: backend_plan_exists,  from: "$.backend_plan_exists" }
       - { 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
@@ -329,6 +363,8 @@ workflow:
       - { name: delta_frontend_plan,       from: "$.delta_frontend_plan" }
       - { name: delta_backend_plan_exists, from: "$.delta_backend_plan_exists" }
       - { name: delta_frontend_plan_exists, from: "$.delta_frontend_plan_exists" }
+      - { name: delta_api_plan,            from: "$.delta_api_plan" }
+      - { name: delta_api_plan_exists,     from: "$.delta_api_plan_exists" }
       - { name: wave,                      from: "$.wave" }
       - { name: predecessor_docs,          from: "$.predecessor_docs" }
       - { name: predecessor_count,         from: "$.predecessor_count" }
@@ -464,9 +500,20 @@ workflow:
     on_false: continue
     on_false_message: "NOTE — change {{cr_id}} also names the {{awaited_txt}} lane, whose developer has not written its delta plan yet. This run gates your half only; the contract between the two halves (check 3) is checked once both delta plans are on disk."
 
-  # D4b. What the service delta changes or removes that the frontend binds to, by script.
-  - id: contract_impact
+  # D4b. What the change's API changes or removes that the frontend binds to, by script.
+  #      contract-impact reads the delta API plan beside --delta-backend, and the delta
+  #      backend plan's own contract table for a change planned before delta API plans;
+  #      it runs when either document is on disk.
+  - id: impact_go_be
     condition: "{{delta_backend_plan_exists}} == true"
+    action: set
+    vars: { impact_go: "true" }
+  - id: impact_go_api
+    condition: "{{delta_api_plan_exists}} == true"
+    action: set
+    vars: { impact_go: "true" }
+  - id: contract_impact
+    condition: "{{impact_go}} == true"
     action: execute_script
     on_error: continue
     script: { ref: actions }
@@ -542,18 +589,74 @@ workflow:
     condition: "{{fe_seen}} == true"
     action: set
     vars: { fe_master_ctx: "{{frontend_plan}}" }
+  # The API documents ride with the backend lane's: the change's delta API plan with its
+  # delta backend plan, the feature's API plan with the master backend plan — each only when
+  # it exists.
+  - id: api_delta_arm
+    condition: "{{be_seen}} == true"
+    action: set
+    vars: { api_delta_go: "{{delta_api_plan_exists}}" }
+  - id: api_delta_ctx_path
+    condition: "{{api_delta_go}} == true"
+    action: set
+    vars: { be_api_delta_ctx: "{{delta_api_plan}}" }
+  - id: api_master_arm
+    condition: "{{be_master_ctx}} != "
+    action: set
+    vars: { api_master_go: "{{api_plan_exists}}" }
+  - id: api_master_ctx_path
+    condition: "{{api_master_go}} == true"
+    action: set
+    vars: { api_master_ctx: "{{api_plan}}" }
+
+  # What the delta backend plan's repair is told about the change's API: the delta API
+  # plan, or — for a change planned before those — its own contract table and API section.
+  - id: be_delta_api_rule_api
+    action: set
+    vars:
+      be_delta_api_rule: "THE CHANGE'S API IS IN delta-api-plan.md (in context), repaired before this document whenever a gap was in one of its endpoints. Do NOT publish or restate endpoints here: REALISE each endpoint it adds or changes as the use-case its **Maps to** names, ADDED or MODIFIED here, with request and response DTOs matching its shapes. A gap in an endpoint itself — its row, its block, its operation id, a request's answer — is the delta API plan's, not this document's."
+  - id: be_delta_api_rule_in_plan
+    condition: "{{delta_api_plan_exists}} == false"
+    action: set
+    vars:
+      be_delta_api_rule: "THIS CHANGE'S API IS IN THIS DOCUMENT — it was planned before delta API plans existed. CONTRACT gaps whose lane is `backend`: publish the missing surface in '## Contract deltas for the frontend lane' — one row per endpoint added, changed or removed, with its operation id — and write each added or changed endpoint in full under '## API — added and changed endpoints', every shape `{ field: type }`. Those are the only parts of this document the experience delta may bind to."
 
   # 4b. Load the domain GATE overlays (the domain-rule-bindings `/aw-spec-gate` checklist)
   #     as the conformance checklist — VALIDATION input only, NEVER authoring. analyze sees
   #     them (include_standards: true); the repair steps do NOT (the delta conforms to the
-  #     delta SPEC, not to the overlays). Empty/no-op for a non-domain project.
+  #     delta SPEC, not to the overlays). Empty/no-op for a non-domain project — a map whose
+  #     heading holds a `_None_` line. A map with no such heading, or one naming a file that
+  #     is not on disk, warns and carries on.
   - id: resolve_gate_overlays
     action: execute_script
     script: { ref: actions }
     subcommand: resolve-domain
     args: ["--command", "aw-spec-gate"]
     outputs:
-      - { name: gate_overlays, from: "$.candidates" }
+      - { name: gate_overlays,      from: "$.candidates" }
+      - { name: gate_domain,        from: "$.domain" }
+      - { name: gate_map_exists,    from: "$.rulemap_exists" }
+      - { name: gate_heading_found, from: "$.heading_found" }
+      - { name: gate_missing,       from: "$.missing" }
+  - id: gate_flags
+    action: set
+    vars: { gate_all_on_disk: "true" }
+  - id: gate_flag_missing
+    condition: "{{gate_missing}} != []"
+    action: set
+    vars: { gate_all_on_disk: "false" }
+  - id: warn_gate_heading
+    condition: "{{gate_map_exists}} == true"
+    action: verify_context
+    require_true: gate_heading_found
+    on_false: continue
+    on_false_message: "WARNING — guardrails/{{gate_domain}}/domain-rule-bindings.md has no `## /aw-spec-gate` heading, so the change's plans are checked against no domain checklist. If that is not intended, add the heading and its overlay files — it must read exactly `## /aw-spec-gate`; a project with no checklist keeps the heading with a `_None_` line."
+  - id: warn_gate_missing
+    condition: "{{gate_map_exists}} == true"
+    action: verify_context
+    require_true: gate_all_on_disk
+    on_false: continue
+    on_false_message: "WARNING — guardrails/{{gate_domain}}/domain-rule-bindings.md maps these checklist files under `## /aw-spec-gate`, but they are not on disk, so the change's plans were not checked against them: {{gate_missing}}. Correct the paths, or add the files."
   - id: load_gate_overlays
     action: load_standards
     files_from_variable: gate_overlays
@@ -583,9 +686,11 @@ workflow:
     context:
       - { path: "{{delta_spec}}" }                        # THE ANCHOR for this change
       - { path: "{{delta_model}}", optional: true }       # its model half — unfilled on a plan-only change
+      - { path: "{{be_api_delta_ctx}}", optional: true }  # the change's API — merged into api-plan.md at finalize-delta
       - { path: "{{be_delta_ctx}}", optional: true }
       - { path: "{{fe_delta_ctx}}", optional: true }
       - { path: "{{spec_file}}" }                         # the master spec (READ ONLY)
+      - { path: "{{api_master_ctx}}", optional: true }    # the feature's API (READ ONLY) — what a changed or removed endpoint must name
       - { path: "{{be_master_ctx}}", optional: true }     # the master plans (READ ONLY) — the base
       - { path: "{{fe_master_ctx}}", optional: true }     #   every MODIFIED element must name
       - { path: "{{domain_model}}", optional: true }      # the canonical model (READ ONLY)
@@ -613,8 +718,8 @@ workflow:
       - id: analyze
         action: agent_query
         include_standards: true            # the gate overlays (checklist) are in the standards
-        schema: { ok: true, backend_repair: false, frontend_repair: false, gaps: [ { severity: "high", check: "<spec-backend|spec-frontend|contract|model|master|wave|overlay>", lane: "<backend|frontend>", spec_ref: "<delta FR/BR/CN/DC/IC/UX/US or overlay or —>", where: "<delta-plan section>", gap: "<how it drifts>" } ] }
-        mock: { ok: true, backend_repair: false, frontend_repair: false, gaps: [] }
+        schema: { ok: true, backend_repair: false, api_repair: false, frontend_repair: false, gaps: [ { severity: "high", check: "<spec-backend|spec-frontend|contract|model|master|wave|overlay>", lane: "<backend|frontend>", spec_ref: "<delta FR/BR/CN/DC/IC/UX/US or overlay or —>", where: "<delta-plan section>", gap: "<how it drifts>" } ] }
+        mock: { ok: true, backend_repair: false, api_repair: false, frontend_repair: false, gaps: [] }
         task: |
           delta-spec.md is the ANCHOR for change {{cr_id}} (wave {{wave}}). Gate this
           change's DELTA PLANS against it, against the masters they change, and against the
@@ -628,7 +733,16 @@ workflow:
           nothing else. Every gap still carries the `lane` whose document must change to
           close it, even when that lane is not gated here.
 
-          CHECK 1 — delta-spec.md → delta-backend-plan.md (when it is in context):
+          THE CHANGE'S API is its delta-api-plan.md when it is in context — the endpoints
+          the change adds, changes and removes (its Contract deltas table and the whole
+          blocks under it) and the requests it answers; finalize-delta merges it into the
+          feature's api-plan.md by script, block by block. With no delta-api-plan.md in
+          context the change was planned before those existed, and its delta backend plan's
+          contract table and API section are its API. THE FEATURE'S API is api-plan.md when
+          it is in context, else the master backend plan's API section.
+
+          CHECK 1 — delta-spec.md → delta-backend-plan.md and the change's API (when the
+          delta backend plan is in context):
           (a) every ADDED / MODIFIED delta-spec item — FR / BR / CN- / DC- / IC- / user
           story — has a home in the delta plan (an ADDED or MODIFIED element that serves
           it). A delta-spec item with no delta-plan element is a HIGH gap. EXCEPT the
@@ -640,7 +754,14 @@ workflow:
           (d) PLAN-ONLY CHANGE — if the delta-spec is an unfilled stub, the spec is
           deliberately unchanged and this change moves only HOW existing ids are realised.
           Then every changed element must still trace to an EXISTING spec id in the master
-          spec (in context). An element tracing to nothing at all is still a HIGH gap.
+          spec (in context). An element tracing to nothing at all is still a HIGH gap;
+          (e) with a delta-api-plan.md: every endpoint it adds or changes names under
+          **Maps to** a use-case the delta backend plan ADDS or MODIFIES, or one the master
+          backend plan defines — an endpoint nothing realises is a HIGH gap on lane
+          `backend` — and the delta backend plan restates none of it. Every `added` or
+          `changed` row has its block, written WHOLE (the merge puts it in place of the
+          API plan's block as it stands, so a block that carries only the difference loses
+          the rest), every shape as `{ field: type }`; a `removed` row has no block.
 
           CHECK 2 — delta-spec.md → delta-frontend-plan.md (when it is in context):
           (a) every UX- item in the delta-spec has a home HERE — the service lane excludes
@@ -656,8 +777,7 @@ workflow:
           CHECK 3 — CONTRACT BINDING across the change (ONLY when {{both_lanes}} is true;
           skip entirely otherwise):
           (a) EVERY call, endpoint or payload the experience delta binds to is EITHER in
-          the service delta's "Contract deltas for the frontend lane" table OR already in
-          the MASTER backend plan's published surface. One that is in neither is a HIGH
+          the change's API OR already in the feature's API. One that is in neither is a HIGH
           `contract` gap — lane `backend` when the delta-spec requires the capability, lane
           `frontend` when the experience invented it;
           (b) FIELD SHAPES agree in both directions — a field the experience reads that the
@@ -666,14 +786,15 @@ workflow:
           (c) anything the experience delta raised under "Contract deltas needed" is
           UNRESOLVED by definition: report it so it is closed here rather than at
           integration;
-          (d) a contract the service delta REMOVES or narrows that the master frontend plan
+          (d) a contract the change's API REMOVES or narrows that the master frontend plan
           still uses is a HIGH gap — the experience delta has to carry the matching change;
           (e) OPERATION IDS MATCH. Every binding row the experience delta adds or changes
-          leads with an operation id, and that id is the one the service delta's table or
-          the master backend plan gives the endpoint, spelled exactly. A binding with no id,
-          or with an id neither names, is a HIGH `contract` gap on lane `frontend`; a
-          service-delta row with no operation id is one on lane `backend`. Implement finds
-          each endpoint by this id in the service's exported API document.
+          leads with an operation id, and that id is the one the change's API or the
+          feature's API gives the endpoint, spelled exactly. A binding with no id, or with
+          an id neither names, is a HIGH `contract` gap on lane `frontend`; a Contract
+          deltas row with no operation id is one on lane `backend`. Implement finds each
+          endpoint by this id in the API document drafted from the API plans, this change's
+          included.
 
           CHECK 4 — THE EFFECTIVE MODEL. It is domain-model.md PLUS this change's model
           delta PLUS the model deltas of every LOWER-WAVE change in context (its
@@ -701,9 +822,14 @@ workflow:
           cannot MODIFY what the master does not define (that would be an ADD). A dangling
           MODIFIED reference is a HIGH `master` gap;
           (b) every MODIFIED / REMOVED spec id names one the master spec really defines;
-          (c) nothing in a delta plan edits the master: the delta plans are the whole plan
-          for this change, and no stage merges them back — a master plan is re-derived from
-          the spec and the model that finalize-delta merges.
+          (c) nothing in a delta plan edits the master: the delta lane plans are the whole
+          plan for this change, and no stage merges them back — a master plan is
+          re-derived from the spec, the model and the API that finalize-delta merges;
+          (d) every `changed` or `removed` endpoint of the change's API names an endpoint
+          the feature's API really has, by its operation id — the merge finds it by that id
+          — and an `added` one takes an id the feature's API does not already use. A
+          `changed` endpoint the feature does not have is a HIGH `master` gap on lane
+          `backend`: it is an `added` one.
 
           CHECK 6 — WAVE DISCIPLINE. This change is wave {{wave}}. Other open changes
           touching the same aggregates, computed from the pending model deltas:
@@ -730,14 +856,18 @@ workflow:
           a delta plan).
 
           Tag every gap with its `check` and the `lane` whose document must change to close
-          it. Set backend_repair true if any gap needs the service delta rewritten, and
-          frontend_repair likewise. (If a delta plan is still the empty template, treat the
-          WHOLE delta spec as gaps against it.) Set ok=true ONLY when every applicable
-          check passes and no touched checklist constraint is unaccounted for.
+          it. Set api_repair true if any gap is in an endpoint of the change's API — a
+          Contract deltas row, a block, an operation id, a request's answer — and
+          backend_repair true if any needs the delta backend plan itself rewritten; both
+          when both are. Set frontend_repair likewise. (If a delta plan is still the empty
+          template, treat the WHOLE delta spec as gaps against it.) Set ok=true ONLY when
+          every applicable check passes and no touched checklist constraint is unaccounted
+          for.
         outputs:
           - { name: analyze_ok,      from: "$.ok" }
           - { name: analyze_gaps,    from: "$.gaps" }
           - { name: backend_repair,  from: "$.backend_repair" }
+          - { name: api_repair,      from: "$.api_repair" }
           - { name: frontend_repair, from: "$.frontend_repair" }
       - id: conform_break
         action: break
@@ -821,6 +951,27 @@ workflow:
         condition: "{{backend_repair}} == true"
         action: set
         vars: { be_repair: "{{be_present}}" }
+      # The change's API by the same assignments. With no delta API plan the change's API
+      # is in its delta backend plan, so an API gap raises that repair instead.
+      - id: api_repair_clear
+        action: set
+        vars: { api_repair_go: "false", api_in_backend: "false" }
+      - id: api_repair_flag
+        condition: "{{api_repair}} == true"
+        action: set
+        vars: { api_repair_go: "{{be_present}}" }
+      - id: api_repair_in_backend
+        condition: "{{delta_api_plan_exists}} == false"
+        action: set
+        vars: { api_in_backend: "{{api_repair_go}}" }
+      - id: api_repair_no_plan
+        condition: "{{delta_api_plan_exists}} == false"
+        action: set
+        vars: { api_repair_go: "false" }
+      - id: be_repair_for_api
+        condition: "{{api_in_backend}} == true"
+        action: set
+        vars: { be_repair: "true" }
       - id: fe_repair_clear
         action: set
         vars: { fe_repair: "false" }
@@ -829,6 +980,36 @@ workflow:
         action: set
         vars: { fe_repair: "{{fe_present}}" }
 
+      # The change's API first, so the delta backend repair below reads it as repaired.
+      - id: repair_api
+        condition: "{{api_repair_go}} == true"
+        action: agent_author
+        include_standards: false           # rewrite-in-place: the delta spec anchors — NOT the overlays
+        output_target: { type: file, path: "{{delta_api_plan}}" }
+        task: |
+          delta-spec.md is the ANCHOR — update the DELTA API PLAN for {{cr_id}} (in context)
+          to REALISE it, closing the gaps whose lane is `backend` that are in one of its
+          endpoints (the delta spec WINS every time):
+          {{analyze_gaps}}
+          - "## Contract deltas for the frontend lane": one row per endpoint the change
+            adds, changes or removes, with its operation id. A changed or removed endpoint
+            names one the feature's API (in context) really has, by its id; one it does not
+            have is `added`. A new endpoint takes an id unique across the service.
+          - "## Endpoints added or changed": each `added` or `changed` endpoint as a WHOLE
+            block — the `### `VERB /route`` heading, then **Operation id**, **Auth**,
+            **Request**, **Success**, the **Errors** table and **Maps to**, every shape as
+            `{ field: type }`. finalize-delta puts this block in place of the API plan's, so
+            it carries the unchanged fields too. A removed endpoint has no block.
+          - "## Requests from the frontend lane": only the requests this change's delta spec
+            gives a basis for; `None` when it answers none.
+          - REMOVE any endpoint with no delta-spec basis (on a PLAN-ONLY change, no existing
+            spec id); **Maps to** names the use-case the delta backend plan realises it with.
+          - Preserve every already-conformant row and block VERBATIM. Do NOT change the
+            delta spec, the feature's API plan, either delta lane plan, the masters or the
+            domain model. Do NOT edit the Wave / Base version / Delta spec / Delta backend
+            plan headers — scripts stamp those.
+          Return the COMPLETE updated delta API plan content only.
+
       - id: repair_backend
         condition: "{{be_repair}} == true"
         action: agent_author
@@ -852,9 +1033,7 @@ workflow:
             EDIT domain-model.md or the model delta: they are spec-tier. A gap that can
             only be closed by ADDING to the model stays open with a DA-n saying it routes
             to /appweaver specify.
-          - CONTRACT gaps whose lane is `backend`: publish the missing surface in
-            "## Contract deltas for the frontend lane" as field shapes. That table is the
-            only part of this document the experience delta may bind to.
+          - {{be_delta_api_rule}}
           - WAVE gaps: name a lower-wave change you build on under "## Depends on", and
             name a same-wave overlap under "Other open deltas" — you may NOT assume a
             same-wave change's structure or contract, because nothing orders it against
@@ -867,8 +1046,9 @@ workflow:
             the delta spec".
           - Keep the technology-agnostic form (signatures + pre/post/invariant, field
             shapes — NO code). Preserve every already-conformant section VERBATIM. Do NOT
-            change the delta spec, the masters or the domain model. Do NOT edit the Wave /
-            Base version / Delta spec / Model delta headers — scripts stamp those.
+            change the delta spec, the delta API plan, the masters or the domain model. Do
+            NOT edit the Wave / Base version / Delta spec / Model delta / API delta headers
+            — scripts stamp those.
           Return the COMPLETE updated delta plan content only.
 
       - id: repair_frontend
@@ -888,10 +1068,11 @@ workflow:
             from the master frontend plan (in context); if the master does not define it,
             make it an ADDED element instead. A shared component is MODIFIED in place,
             never copied into the change.
-          - CONTRACT gaps whose lane is `frontend`: bind ONLY to the service delta's
-            "## Contract deltas for the frontend lane" table and to the master plan's
-            published surface. CITE them; do not restate, re-derive or contradict them, and
-            introduce NO server-side behaviour or persistence assumption. A capability the
+          - CONTRACT gaps whose lane is `frontend`: bind ONLY to the change's API (its
+            delta API plan — or, for a change planned before those, its delta backend plan's
+            contract table) and to the feature's API. CITE them; do not restate, re-derive
+            or contradict them, and introduce NO server-side behaviour or persistence
+            assumption. A capability the
             experience needs that neither offers stays under "Contract deltas needed" — it
             is the service lane's to publish, never a client-side workaround.
           - WAVE gaps: name a lower-wave change you build on under "## Depends on", and a
@@ -905,10 +1086,38 @@ workflow:
             requirement here.
           - Stay TECHNOLOGY-AGNOSTIC: no framework, router, state library, component
             library or styling approach. Preserve every already-conformant section
-            VERBATIM. Do NOT edit the Wave / Base version / Delta spec / Service delta
-            headers — scripts stamp those.
+            VERBATIM. Do NOT edit the Wave / Base version / Delta spec / API delta headers
+            — scripts stamp those.
           Return the COMPLETE updated delta plan content only.
 
+  # THE CHANGE'S API DRAFT, redrawn from the change's API as this run leaves it — its delta
+  # API plan, or the delta backend plan of a change planned before those; a repair may have
+  # added, changed or removed an endpoint. The frontend lane binds to it while the change is
+  # open, and analyze-slice-delta checks the built service against it. Advisory: it never
+  # fails the gate.
+  - id: contract_draft_change
+    condition: "{{be_present}} == 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: "{{be_present}} == 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."
+
   # THE STOP. Two independent raises: nothing drifts, or what drifts is only the other
   # developer's to close — reported for them below.
   - id: gate_ok_conformant
@@ -948,6 +1157,7 @@ outputs:
   cr_id: "{{cr_id}}"
   cr_dir: "{{cr_dir}}"
   wave: "{{wave}}"
+  delta_api_plan: "{{be_api_delta_ctx}}"          # the change's API, gated with its delta backend plan; empty for a change planned before delta API plans
   delta_backend_plan: "{{delta_backend_plan}}"    # empty when that lane has no delta plan
   delta_frontend_plan: "{{delta_frontend_plan}}"
   conformant: "{{analyze_ok}}"                     # every check passed, the other developer's half included; false on a run that finishes means only other_lane_gaps are left
@@ -957,6 +1167,7 @@ outputs:
   gated_backend: "{{be_present}}"                  # checked and repaired by this run
   gated_frontend: "{{fe_present}}"
   other_lane_gaps: "{{other_csv}}"                 # gaps only the other developer's delta plan can close
-  contract_impact: "{{impact_csv}}"                # operations the service delta changes or removes that the frontend still binds to
+  contract_impact: "{{impact_csv}}"                # operations the change's API changes or removes that the frontend still binds to
+  change_api_draft: "{{change_draft_path}}"        # changes/<CR-id>/api-draft.json, redrawn from {{change_draft_plan}}
   note: "Gated change {{cr_id}} (wave {{wave}}) against its delta spec, the masters it changes, and the EFFECTIVE model — domain-model.md plus this change's model delta plus the {{predecessor_count}} predecessor change(s) from LOWER waves (each one's model delta and its delta-spec). Same-wave changes are visible but never assumed: {{sibling_count}} open at the same or a higher wave, overlapping this one on — {{overlap_report}}. The masters and the model were READ, never written."
   next: "/appweaver implement {{cr_id}} → build → analyze-slice-delta → finalize-delta → analyze-slice → close-delta   (implement is one command for both lanes and both paths — passing the id above skips its 'which change' prompt; the delta plans realise the delta spec; the change stays OPEN through finalize-delta's merge and analyze-slice's verification, and only close-delta archives it and bumps the version)"