aw-spec-cli 0.1.32 → 0.1.34

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

@@ -5,12 +5,13 @@
 #   specify → plan → analyze-plan → implement.
 #
 # FOUR CHECKS, one per way a plan can be wrong:
-#   1. spec.md → backend-plan.md   — every spec item has a service home
+#   1. spec.md → backend-plan.md + api-plan.md — every spec item has a service home, and
+#      every endpoint the API plan publishes is realised by a use-case of the backend plan
 #   2. spec.md → frontend-plan.md  — every experience item has a screen home
-#   3. backend-plan.md ↔ frontend-plan.md — CONTRACT BINDING: every call the frontend
-#      makes exists in the service's published surface, with the same field shapes. This
-#      is the check neither one-sided pass can make: a frontend call the backend never
-#      defines passes both coverage checks and fails at integration.
+#   3. api-plan.md ↔ frontend-plan.md — CONTRACT BINDING: every call the frontend makes
+#      exists in the service's published API, with the same field shapes. This is the
+#      check neither one-sided pass can make: a frontend call the backend never defines
+#      passes both coverage checks and fails at integration.
 #   4. the plans → domain-model.md — no invented aggregate, no unenforced invariant. The
 #      model is spec-tier and is READ here, never written.
 # Plus the OVERLAY BACKSTOP: the domain gate checklist, as a fifth pass over both plans.
@@ -30,19 +31,30 @@
 # refuses the backend's implement, and the reverse. With the default (every declared
 # lane) every plan is gated, as before — each in its own receipt.
 #
+# THE BACKEND LANE IS TWO DOCUMENTS. Its endpoints and its answers to the frontend's
+# requests are in api-plan.md, and backend-plan.md realises each endpoint as a use-case.
+# Both are in context when the backend plan is, both are hashed into the backend receipt,
+# and a repair rewrites the one the gap is in: api-plan.md first, for a gap in an endpoint
+# or a request's answer, then backend-plan.md, which realises what the API plan states. A
+# feature planned before API plans existed keeps its endpoints in its backend plan's API
+# section; that section is then the API every check reads, and an API repair rewrites the
+# backend plan. (`plan main` offers to move them out.)
+#
 # THE REQUEST LEDGER IS READ BY SCRIPT. What the frontend plan asks of the service sits in
-# its §5 "Contract deltas needed" table, one RQ-n per request, and the backend plan answers
-# each in its API section's "Requests from the frontend lane" table. contract-requests reads
-# both on every pass, so check 3 is TOLD which requests are open (a backend-lane gap: answer
-# it, by publishing or declining) and which wait on the frontend (answered and not re-bound,
-# or declined). A frontend developer's run therefore reports open requests for the backend
+# its §5 "Contract deltas needed" table, one RQ-n per request, and the API plan answers each
+# in its "Requests from the frontend lane" table. contract-requests reads both on every
+# pass, so check 3 is TOLD which requests are open (a backend-lane gap: answer it, by
+# publishing or declining) and which wait on the frontend (answered and not re-bound, or
+# declined). A frontend developer's run therefore reports open requests for the backend
 # developer instead of stopping on them, and a backend developer's repair answers them.
-# A master run that gates the backend plan also redraws api-draft.json from its API
-# section, so the draft the frontend generates against matches the plan as repaired.
+# A master run that gates the backend lane also redraws api-draft.json from the API plan, so
+# the draft the frontend generates against matches the plan as repaired, and warns when the
+# redraw lost an operation the previous draft had.
 #
-# THE FRONTEND RECEIPT HASHES THE BACKEND'S PUBLISHED SURFACE TOO (the API section of
-# backend-plan.md): when the backend developer changes it — an answered request, a renamed
-# operation — the frontend lane is stale at implement until its plan is gated again.
+# THE FRONTEND RECEIPT HASHES THE SERVICE'S PUBLISHED API TOO (api-plan.md, or the backend
+# plan's API section for a feature planned before it): when the backend developer changes
+# it — an answered request, a renamed operation — the frontend lane is stale at implement
+# until its plan is gated again.
 #
 # THIS STAGE VALIDATES; `plan` AUTHORS. A declared lane whose plan document is MISSING
 # STOPS the run naming /appweaver plan — it is not scaffolded and repaired here. Filling
@@ -108,8 +120,8 @@
 # =============================================================================
 
 name: aw-spec-analyze-plan
-description: The spec↔plan conformance gate for every declared lane — confirm backend-plan.md and frontend-plan.md follow spec.md, that they bind to each other's contract, and that neither contradicts the bounded context's domain model (domain overlays are a backstop); with approval, repair the drifting plan. Lanes come from .appweaver/stacks.json, so one command gates backend-only, frontend-only and full-stack projects. Each gated lane runs in one of two modes, decided from the changes/ directory rather than the ledger and defaulting to the read-only one — MASTER (no open change names that lane on its **Lanes** line) checks, repairs on approval and stops on unreconciled gaps; REPORT (an open change names it) runs the same checks read-only, because a master plan may not be rewritten while a delta to that lane is in flight. With no lane in master mode the run writes plan-analyze-report.md without asking, repairing or stopping. It never opens, merges or closes a change.
-version: 3.6.0
+description: The spec↔plan conformance gate for every declared lane — confirm backend-plan.md with its api-plan.md and frontend-plan.md follow spec.md, that the frontend binds to the API the service publishes, and that neither contradicts the bounded context's domain model (domain overlays are a backstop); with approval, repair the drifting plan. Lanes come from .appweaver/stacks.json, so one command gates backend-only, frontend-only and full-stack projects. Each gated lane runs in one of two modes, decided from the changes/ directory rather than the ledger and defaulting to the read-only one — MASTER (no open change names that lane on its **Lanes** line) checks, repairs on approval and stops on unreconciled gaps; REPORT (an open change names it) runs the same checks read-only, because a master plan may not be rewritten while a delta to that lane is in flight. With no lane in master mode the run writes plan-analyze-report.md without asking, repairing or stopping. It never opens, merges or closes a change.
+version: 3.9.1
 agent_agnostic: true
 dialect: aw-spec.orchestrator/v1
 
@@ -190,6 +202,25 @@ vars:
   req_frontend_text: "none"
   req_summary: "no contract request"
   draft_path: ""
+  draft_plan: ""           # the document it was drawn from: api-plan.md, or the backend plan
+  draft_unread: "0"
+  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 API PLAN — the backend lane's second document. In context with the backend plan;
+  # absent for a feature planned before API plans existed, whose API section is then the
+  # API every check reads and every API repair rewrites.
+  api_plan: ""
+  api_plan_exists: "false"
+  api_ctx_go: "false"
+  api_plan_ctx: ""
+  api_repair: "false"      # the analyze pass found a gap in an endpoint or a request's answer
+  api_repair_go: "false"   # …and this pass rewrites api-plan.md for it
+  api_in_backend: "false"  # …or, with no API plan, rewrites the backend plan's API section
+  # What the backend plan's repair is told about the API.
+  be_repair_api_rule: "THE ENDPOINTS ARE IN api-plan.md (in context), repaired before this document whenever a gap was in an endpoint or a request's answer. Do NOT publish or restate endpoints here: REALISE each endpoint of the API plan as the use-case its **Maps to** names, with request and response DTOs matching its shapes. A gap in an endpoint itself — its route, shapes, operation id or a request's answer — is the API plan's, not this document's."
   # PER-LANE PRESENCE. A lane is PRESENT when it is declared and its plan document is on
   # disk — its plan is then in context — and MISSING when it is WORKED and the document is
   # not. The engine has no
@@ -262,6 +293,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
@@ -538,18 +571,54 @@ workflow:
     condition: "{{fe_present}} == true"
     action: set
     vars: { fe_plan_ctx: "{{frontend_plan}}" }
+  # The API plan rides with the backend plan: in context whenever that one is, when it
+  # exists. A feature planned before API plans has none, and its backend plan's API section
+  # is read in its place — which is also where an API repair then goes.
+  - id: api_ctx_arm
+    condition: "{{be_present}} == true"
+    action: set
+    vars: { api_ctx_go: "{{api_plan_exists}}" }
+  - id: api_ctx_path
+    condition: "{{api_ctx_go}} == true"
+    action: set
+    vars: { api_plan_ctx: "{{api_plan}}" }
 
   # 2b. Load the domain GATE overlays (the domain-rule-bindings `/aw-spec-gate` checklist) as
   #     the conformance checklist — VALIDATION input only, NEVER authoring. The analyze
   #     step sees them (include_standards: true); the repair steps do NOT (a plan conforms
-  #     to the SPEC, not to the overlays). Empty/no-op for a non-domain project.
+  #     to the 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 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 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
@@ -576,6 +645,7 @@ workflow:
     context:
       - { path: "{{spec_file}}" }                       # THE ANCHOR
       - { path: "{{domain_model}}", optional: true }    # spec-tier, READ here and never written
+      - { path: "{{api_plan_ctx}}", optional: true }    # the service's published API, with the backend plan
       - { path: "{{be_plan_ctx}}", optional: true }
       - { path: "{{fe_plan_ctx}}", optional: true }
 
@@ -613,11 +683,19 @@ workflow:
           - { name: req_frontend_text, from: "$.frontend_text" }
           - { name: req_summary,       from: "$.summary" }
 
+      # With no API plan the backend plan's API section is the API, so its repair carries
+      # the rules the API repair does — the requests as this pass reads them included.
+      - id: be_repair_api_rule_in_plan
+        condition: "{{api_plan_exists}} == false"
+        action: set
+        vars:
+          be_repair_api_rule: "THE ENDPOINTS ARE IN THIS DOCUMENT'S API SECTION — this feature was planned before API plans existed. CONTRACT gaps whose lane is `backend`: PUBLISH the missing surface there as endpoint blocks (the `VERB /route` heading, **Operation id**, Request, Success, the Errors table, every shape `{ field: type }`), so the frontend plan has something real to bind to. ANSWER EVERY OPEN CONTRACT REQUEST: {{req_backend_text}}. Record each in the API section's 'Requests from the frontend lane' table (| Request | Outcome | Operation id | Why |; add the table if there is 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 — a request the spec gives no basis for is declined as a spec gap for /appweaver specify, never published on a guess. Keep every row the table already has."
+
       - 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|overlay>", lane: "<backend|frontend>", route: "<plan|specify>", spec_ref: "<FR/BR/CN/DC/IC/UX/US/SC or overlay or —>", where: "<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|overlay>", lane: "<backend|frontend>", route: "<plan|specify>", spec_ref: "<FR/BR/CN/DC/IC/UX/US/SC or overlay or —>", where: "<plan section>", gap: "<how it drifts>" } ] }
+        mock: { ok: true, backend_repair: false, api_repair: false, frontend_repair: false, gaps: [] }
         task: |
           spec.md is the ANCHOR. Gate this feature's LANE PLANS against it and against the
           bounded context's domain model, and list EVERY drift as a gap. Run the checks
@@ -631,16 +709,32 @@ workflow:
           gap still carries the `lane` whose document must change to close it, even when
           that lane is not gated here — it is reported for that lane's developer.
 
-          CHECK 1 — spec.md → backend-plan.md (when the backend plan is in context):
+          THE SERVICE'S API is api-plan.md when it is in context — the endpoints the
+          service publishes and its answers to the frontend's requests, a document of the
+          backend lane beside backend-plan.md, which realises each endpoint as a use-case.
+          With no api-plan.md in context the feature was planned before API plans existed,
+          and the backend plan's API section is the API. Below, "the API" means whichever
+          of the two this feature has.
+
+          CHECK 1 — spec.md → backend-plan.md and the API (when the backend plan is in
+          context):
           (a) every spec item — FR / Business Rule / Constraint (CN-) / Data
           Classification (DC-) / Integration Contract (IC-) / user story / success
           criterion — has a service home, and the Traceability section is complete. A
           lifted CN-/DC-/IC- with no plan row is a HIGH gap. EXCEPT the Experience
           Standards (UX-), which the service plan excludes by contract;
-          (b) NO plan element exceeds or contradicts the spec — anything without a spec
-          basis is a drift unless already logged as a DA-n assumption;
+          (b) NO plan element — and no endpoint of the API — exceeds or contradicts the
+          spec: anything without a spec basis is a drift unless already logged as a DA-n
+          assumption;
           (c) the layers are coherent (Application→Domain, API→Application, Infra
-          implements the declared ports) and it stays high-level + technology-agnostic.
+          implements the declared ports) and it stays high-level + technology-agnostic;
+          (d) with an api-plan.md: every endpoint it publishes names under **Maps to** a
+          use-case the backend plan defines, with DTOs matching its shapes — an endpoint
+          nothing realises is a HIGH gap on lane `backend` — and the backend plan restates
+          no endpoint (its API section is the one line pointing to api-plan.md). Every
+          endpoint is a `VERB /route` block with its shapes as `{ field: type }`: one
+          written as a table row or in prose reaches neither api-draft.json nor the
+          frontend, a HIGH gap.
 
           CHECK 2 — spec.md → frontend-plan.md (when the frontend plan is in context):
           (a) every Experience Standard (UX-) has a home here — the service plan excludes
@@ -654,21 +748,21 @@ workflow:
           (d) it stays technology-agnostic — no framework, router, state library, component
           library or styling approach.
 
-          CHECK 3 — CONTRACT BINDING, backend-plan.md ↔ frontend-plan.md (ONLY when
+          CHECK 3 — CONTRACT BINDING, the API ↔ frontend-plan.md (ONLY when
           {{both_lanes}} is true; skip entirely otherwise). This is the check neither
           one-sided pass can make, and it runs whichever of the two plans is gated:
           (a) EVERY call, endpoint or payload the frontend plan binds to EXISTS in the
-          service plan's published API surface. One that does not is a HIGH gap on the
-          `contract` check — lane `backend` when the spec requires the capability (the
-          service must publish it), lane `frontend` when the experience invented it;
+          API. One that does not is a HIGH gap on the `contract` check — lane `backend`
+          when the spec requires the capability (the service must publish it), lane
+          `frontend` when the experience invented it;
           (b) the FIELD SHAPES agree in both directions — a field the frontend reads that
           the service never returns, and a required field the service demands that the
           frontend never sends, are both HIGH gaps;
           (c) THE REQUEST LEDGER, read by script from both plans ({{req_summary}}). OPEN —
           raised in the frontend plan's "Contract deltas needed" and not answered in the
-          backend plan's "Requests from the frontend lane": {{req_backend_text}}. Report
-          EACH as a HIGH `contract` gap on lane `backend`, route `plan`, naming the RQ-n:
-          the backend plan must publish it or decline it. WAITING ON THE FRONTEND PLAN —
+          API's "Requests from the frontend lane": {{req_backend_text}}. Report EACH as a
+          HIGH `contract` gap on lane `backend`, route `plan`, naming the RQ-n: the API
+          must publish it or decline it. WAITING ON THE FRONTEND PLAN —
           answered and not yet re-bound, or declined: {{req_frontend_text}}. Report EACH as
           a HIGH `contract` gap on lane `frontend`, route `plan`. `none` means nothing in
           that group. A binding row that cites an open request's proposed id is that
@@ -676,12 +770,13 @@ workflow:
           (d) the frontend plan cites the service's published surface and does NOT restate,
           re-derive or contradict it, and states no server-side behaviour or persistence
           assumption;
-          (e) OPERATION IDS MATCH. Every §5 row's Operation id is the one the backend plan's
-          §3 gives that endpoint, spelled exactly, and every §3 endpoint has one, unique
-          across the plan. A §5 row with no id (`—` without a DA-n) or with an id §3 does not
-          name is a HIGH `contract` gap on lane `frontend`; a §3 endpoint with no id, or two
-          endpoints sharing one, is one on lane `backend`. Implement finds each endpoint by
-          this id in the service's exported API document.
+          (e) OPERATION IDS MATCH. Every §5 row's Operation id is the one the API gives
+          that endpoint, spelled exactly, and every endpoint of the API has one, unique
+          across the service. A §5 row with no id (`—` without a DA-n) or with an id the API
+          does not name is a HIGH `contract` gap on lane `frontend`; an endpoint with no id,
+          or two endpoints sharing one, is one on lane `backend`. Implement finds each
+          endpoint by this id in the API document drafted from the API, and analyze-slice
+          checks the service serves it under it.
 
           CHECK 4 — the plans → domain-model.md (when the model is in context; skip if it
           is not):
@@ -716,14 +811,18 @@ workflow:
           - route `plan` for everything a rewrite of a lane plan closes: a missing plan
             home, a name that differs from the model's, an invariant restated instead of
             cited, a contract binding, an element with no spec basis.
-          Set backend_repair true if any `plan`-route gap needs the backend plan rewritten,
-          and frontend_repair likewise. (If a plan is still the empty template, treat the
+          Set api_repair true if any `plan`-route gap is in an endpoint of the API or in a
+          request's answer — its route, shapes, operation id, a missing endpoint, an open
+          request — and backend_repair true if any needs the backend plan itself rewritten
+          (a use-case, the domain, a port, the ledgers); both when both are. Set
+          frontend_repair likewise. (If a plan is still the empty template, treat the
           WHOLE spec as gaps against it.) Set ok=true ONLY when every applicable check
           passes and no 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" }
 
       # WHO CAN CLOSE EACH GAP, decided by script from the tags above: a LIFT-FAILURE is
@@ -777,9 +876,9 @@ workflow:
           - "## How to read this" — state BOTH readings and that only the operator knows
             which applies, because it depends on whether finalize-delta has already run:
             (a) AFTER finalize-delta merged a change, these gaps are EXPECTED. The lane
-            plans are DERIVED from spec.md + domain-model.md and finalize-delta merges the
-            change into those two documents only, so the plans stand at their last authored
-            content and the spec has moved ahead of them. The remedy is
+            plans are DERIVED from spec.md + domain-model.md + api-plan.md and finalize-delta
+            merges the change into those documents only, so the lane plans stand at their
+            last authored content and the spec and the API have moved ahead of them. The remedy is
             /appweaver plan main (which re-derives them, carrying DA-n / WA-n forward),
             after /appweaver close-delta, not a repair of either plan.
             (b) BEFORE finalize-delta, the masters have not moved, so these gaps are real
@@ -869,6 +968,31 @@ workflow:
         condition: "{{backend_repair}} == true"
         action: set
         vars: { be_repair: "{{be_may_repair}}" }
+      # THE API'S OWN REPAIR, by the same ordered assignments. With no api-plan.md the API is
+      # the backend plan's API section, so an API gap raises the backend 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_may_repair}}" }
+      - id: api_repair_in_backend
+        condition: "{{api_plan_exists}} == false"
+        action: set
+        vars: { api_in_backend: "{{api_repair_go}}" }
+      - id: api_repair_no_plan
+        condition: "{{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: api_repair_last_pass
+        condition: "{{repairs_left}} == false"
+        action: set
+        vars: { api_repair_go: "false" }
       - id: be_repair_last_pass
         condition: "{{repairs_left}} == false"
         action: set
@@ -885,6 +1009,40 @@ workflow:
         action: set
         vars: { fe_repair: "false" }
 
+      # The API first, so the backend repair below reads the API as repaired: files in the
+      # envelope are read when each request is assembled.
+      - id: repair_api
+        condition: "{{api_repair_go}} == true"
+        action: agent_author
+        include_standards: false           # rewrite-in-place: spec anchors — NOT the overlays
+        output_target: { type: file, path: "{{api_plan}}" }
+        task: |
+          spec.md is the ANCHOR — update api-plan.md (in context), the endpoints this
+          service publishes, to CONFORM to it, closing the gaps whose lane is `backend` that
+          are in an endpoint or a request's answer (the spec WINS every time):
+          {{analyze_gaps}}
+          - CONTRACT gaps: PUBLISH the missing endpoint as a block under "## Endpoints" —
+            the `### `VERB /route`` heading, then **Operation id**, **Auth**, **Request**,
+            **Success**, the **Errors** table and **Maps to** — every shape as
+            `{ field: type }`, so the frontend plan has something real to bind to. Correct a
+            shape or an error contract the spec contradicts.
+          - OPERATION IDS ARE STABLE: an endpoint keeps the id it has; one without an id gets
+            one unique across the service; two endpoints sharing one are split.
+          - ANSWER EVERY OPEN CONTRACT REQUEST: {{req_backend_text}}. Record each in
+            "Requests from the frontend lane" (| 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 — a request the
+            spec gives no basis for is declined as a spec gap for /appweaver specify, never
+            published on a guess. Keep every row the table already has.
+          - REMOVE an endpoint no spec id calls for. The draft drawn after this run reports
+            every operation the previous api-draft.json had and this document no longer has.
+          - **Maps to** names the use-case the backend plan realises the endpoint with; a
+            new endpoint names the use-case the backend plan's repair will add.
+          - Preserve every already-conformant block VERBATIM. Do NOT change the spec, the
+            domain model, the backend plan or the frontend plan. Add one Change History row
+            for the repair; do not invent a version number.
+          Return the COMPLETE updated api-plan.md content only.
+
       - id: repair_backend
         condition: "{{be_repair}} == true"
         action: agent_author
@@ -906,15 +1064,7 @@ workflow:
             what one says. DO NOT EDIT domain-model.md — it is spec-tier and read-only
             here. If a gap can only be closed by ADDING to the model, you cannot close it:
             leave it open and add a DA-n saying it routes to /appweaver specify.
-          - CONTRACT gaps whose lane is `backend`: PUBLISH the missing surface in the API
-            section as field shapes, so the frontend plan has something real to bind to.
-          - ANSWER EVERY OPEN CONTRACT REQUEST: {{req_backend_text}}. Record each in the API
-            section's "Requests from the frontend lane" table (| Request | Outcome |
-            Operation id | Why |; add the table if there is 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 — a request the spec gives no basis for is
-            declined as a spec gap for /appweaver specify, never published on a guess.
-            Keep every row the table already has.
+          - {{be_repair_api_rule}}
           - REMOVE, or move to a DA-n assumption, any plan element with no spec basis —
             never keep a plan that exceeds or contradicts the spec. EXCEPTION: do NOT
             remove a cross-cutting element that is (or may be) mandated by the technical
@@ -928,9 +1078,9 @@ workflow:
             note "lift-failure: <constraint> — re-run /appweaver specify to lift it into
             CN-/DC-/IC-". (The gate will stop and direct the user to specify.)
           - Keep the Traceability section in sync. Preserve every already-conformant
-            section VERBATIM. Do NOT change the spec, the domain model or the frontend plan.
-            Close only the gaps whose lane is `backend`; a frontend gap is not this
-            document's.
+            section VERBATIM. Do NOT change the spec, the domain model, the frontend plan or
+            api-plan.md. Close only the gaps whose lane is `backend`; a frontend gap is not
+            this document's.
           Return the COMPLETE updated backend-plan.md content only.
 
       - id: repair_frontend
@@ -951,10 +1101,10 @@ workflow:
           - Realise each CN-/DC-/IC-/SC- with an experience obligation, citing its spec id
             — the authorization surface and access conditions, what may not reach the
             client or its logs, storage and URLs, the binding rows, the performance row.
-          - CONTRACT gaps whose lane is `frontend`: bind ONLY to the service plan's
-            published surface (in context). CITE it; do not restate, re-derive or
-            contradict it, and introduce NO server-side behaviour or persistence
-            assumption. A capability the experience needs that the surface does not offer
+          - CONTRACT gaps whose lane is `frontend`: bind ONLY to the service's published
+            API in context — api-plan.md, or the API section of a backend plan written
+            before API plans existed. CITE it; do not restate, re-derive or contradict it,
+            and introduce NO server-side behaviour or persistence assumption. A capability the experience needs that the surface does not offer
             is a CONTRACT REQUEST in §5's "Contract deltas needed" table — a new RQ-n, the
             operation id it proposes, what it sends and receives, the spec ids it serves —
             and the binding row that needs it cites that id; it is the service lane's to
@@ -964,7 +1114,7 @@ workflow:
             declined one, or log a DA-n routing the need to /appweaver specify.
           - Use the domain model's UBIQUITOUS LANGUAGE exactly in labels, states and
             messages, and cite BR-nnn rather than restating a rule. DO NOT EDIT
-            domain-model.md or backend-plan.md.
+            domain-model.md, api-plan.md or backend-plan.md.
           - A state the UI can reach that the spec does not describe is a SPEC gap: log it
             as a DA-n that routes to /appweaver specify; never invent the requirement here.
           - Stay TECHNOLOGY-AGNOSTIC: no framework, router, state library, component
@@ -999,9 +1149,13 @@ workflow:
     action: set
     vars: { stamp_fe: "{{fe_may_repair}}" }
 
-  # THE DRAFT, redrawn from the backend plan as this run leaves it — a repair may have
-  # published an endpoint or answered a request. Master mode only, like the receipt, and
-  # only for a gated backend plan. Advisory: it never fails the gate.
+  # THE DRAFT, redrawn from the API plan as this run leaves it (the backend plan's API
+  # section, for a feature planned before API plans existed) — a repair may have published
+  # an endpoint or answered a request. It is the API contract the frontend lane binds to
+  # and analyze-slice checks the code against. Master mode only, like the receipt, and only
+  # for a gated backend lane. Advisory: it never fails the gate. A shape it cannot type is
+  # reported, because the frontend's client gets that data untyped, and so is an operation
+  # the previous draft had and this one does not, because the frontend may still bind to it.
   - id: contract_draft
     condition: "{{stamp_be}} == true"
     action: execute_script
@@ -1010,7 +1164,32 @@ workflow:
     subcommand: contract-draft
     args: ["--feature-dir", "{{feature_dir}}"]
     outputs:
-      - { name: draft_path, from: "$.path" }
+      - { name: draft_path,         from: "$.path" }
+      - { name: draft_plan,         from: "$.plan" }
+      - { 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: "{{stamp_be}} == 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 analyze-plan."
+  - id: draft_dropped_flag
+    condition: "{{draft_dropped}} != 0"
+    action: set
+    vars: { draft_kept: "false" }
+  - id: warn_draft_dropped
+    condition: "{{stamp_be}} == 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 a repair removed them on purpose, the frontend plan has to stop binding to them; if not, restore their blocks in {{draft_plan}} and re-run analyze-plan."
 
   - id: plan_gate_stamp_backend
     condition: "{{stamp_be}} == true"
@@ -1072,6 +1251,7 @@ outputs:
   feature_dir: "{{feature_dir}}"
   bounded_context: "{{context}}"
   backend_plan: "{{backend_plan}}"      # empty when no backend lane is declared
+  api_plan: "{{api_plan_ctx}}"          # api-plan.md, gated with the backend plan; empty for a feature planned before API plans, whose backend plan carries its API
   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)
   domain_model: "{{domain_model}}"
@@ -1092,7 +1272,7 @@ outputs:
   frontend_receipt: "{{fe_receipt}}"  # .aw-plan-gate.frontend.json, with the frontend's own verdict ({{fe_verdict}})
   gate_receipt_at: "{{receipt_gated}}"
   other_lane_gaps: "{{other_csv}}"   # findings in a plan this run does not repair — another developer's lane, or one an open change names
-  contract_requests: "{{req_summary}}" # the frontend plan's RQ-n requests and the backend plan's answers, as this run left them
-  api_draft: "{{draft_path}}"          # api-draft.json, redrawn from the gated backend plan's API section — commit it with the plan
-  note: "Ran for your working lane `{{working_lane}}` — backend plan: {{be_lane_mode}}; frontend plan: {{fe_lane_mode}} ({{open_count}} change(s) open: {{open_ids}}). A lane is in master mode unless an open change names it on its **Lanes** line. Gated: spec→backend-plan ({{be_gated}}), spec→frontend-plan ({{fe_gated}}), the plan↔plan contract binding ({{both_lanes}} — it needs both plans, and reads the one you do not work on without repairing it) and each gated plan against domain-model.md. {{other_gaps}} finding(s) are in a plan this run does not repair — a lane you do not work on, for its developer, or a lane an open change names — and are reported, not repaired: {{other_csv}}. The domain model was READ, never written: a gap that needs a new entity, event or invariant is fixed by /appweaver specify. A plan in REPORT mode was not rewritten either — a master plan may not move while a delta that names its lane is in flight."
-  next: "MASTER mode (no open change names the lane, verdict={{gate_verdict}}): /appweaver implement — no gap a plan rewrite closes is left; version unchanged, this gate closes nothing. If the verdict is routed-gaps, implement generates and warns: {{routed_csv}} — each is a spec or model gap, lifted by opening a change with /appweaver specify. REPORT mode (an open change names the lane — backend: {{be_open_ids}}; frontend: {{fe_open_ids}}): that lane's plan was checked read-only, and a run with no lane in master mode wrote plan-analyze-report.md only. If finalize-delta has already merged, the gaps ARE that merge — the lane plans are derived from spec.md + domain-model.md and finalize-delta moves only those two, so re-derive with /appweaver plan main after /appweaver close-delta, then re-run /appweaver analyze-plan in master mode. If the change has NOT merged yet, gate it where it lives: /appweaver analyze-plan-delta."
+  contract_requests: "{{req_summary}}" # the frontend plan's RQ-n requests and the API plan's answers, as this run left them
+  api_draft: "{{draft_path}}"          # api-draft.json, redrawn from {{draft_plan}} — commit it with the plans
+  note: "Ran for your working lane `{{working_lane}}` — backend plan: {{be_lane_mode}}; frontend plan: {{fe_lane_mode}} ({{open_count}} change(s) open: {{open_ids}}). A lane is in master mode unless an open change names it on its **Lanes** line. Gated: spec→backend-plan ({{be_gated}}), spec→frontend-plan ({{fe_gated}}), the frontend plan's contract binding against the API ({{both_lanes}} — it needs both lanes' plans, and reads the one you do not work on without repairing it) and each gated plan against domain-model.md. {{other_gaps}} finding(s) are in a plan this run does not repair — a lane you do not work on, for its developer, or a lane an open change names — and are reported, not repaired: {{other_csv}}. The domain model was READ, never written: a gap that needs a new entity, event or invariant is fixed by /appweaver specify. A plan in REPORT mode was not rewritten either — a master plan may not move while a delta that names its lane is in flight."
+  next: "MASTER mode (no open change names the lane, verdict={{gate_verdict}}): /appweaver implement — no gap a plan rewrite closes is left; version unchanged, this gate closes nothing. If the verdict is routed-gaps, implement generates and warns: {{routed_csv}} — each is a spec or model gap, lifted by opening a change with /appweaver specify. REPORT mode (an open change names the lane — backend: {{be_open_ids}}; frontend: {{fe_open_ids}}): that lane's plan was checked read-only, and a run with no lane in master mode wrote plan-analyze-report.md only. If finalize-delta has already merged, the gaps ARE that merge — the lane plans are derived from spec.md + domain-model.md + api-plan.md and finalize-delta moves only those, so re-derive with /appweaver plan main after /appweaver close-delta, then re-run /appweaver analyze-plan in master mode. If the change has NOT merged yet, gate it where it lives: /appweaver analyze-plan-delta."