aw-spec-cli 0.1.32 → 0.1.34

package/assets/.appweaver/orchestrator/modules/delta-plan.orch.yaml

@@ -3,14 +3,22 @@
 #
 # Included by /appweaver plan on its DELTA branch (a master plan already exists).
 # It authors, inside the change's own directory beside its delta-spec:
+#   • changes/<cr-id>/delta-api-plan.md       when a backend lane is declared — FIRST
 #   • changes/<cr-id>/delta-backend-plan.md   when a backend lane is declared
 #   • changes/<cr-id>/delta-frontend-plan.md  when a frontend lane is declared
-# and touches NEITHER master. The change stays OPEN; `implement` generates the code from
-# these documents (it asks which change, and takes the delta plans of the answer),
-# finalize-delta merges the change's SPEC and MODEL halves (never a lane plan — a master
-# plan is derived from those two and is re-derived from them), and close-delta archives
-# these plans with the change at the end. No version bump here, no code (that is
-# /appweaver implement).
+# and touches NO master. The change stays OPEN; `implement` generates the code from these
+# documents (it asks which change, and takes the delta plans of the answer), finalize-delta
+# merges the change's SPEC and MODEL halves and, by script, its delta API plan into
+# api-plan.md (never a lane plan — a master plan is derived from those and is re-derived
+# from them), and close-delta archives these plans with the change at the end. No version
+# bump here, no code (that is /appweaver implement).
+#
+# THE CHANGE'S API COMES FIRST. Its delta API plan — the endpoints it adds, changes and
+# removes, and the frontend lane's requests it answers — is authored before its delta
+# backend plan, which then realises each endpoint; the frontend delta plan binds to it. A
+# change planned before delta API plans existed keeps its API in its delta backend plan:
+# the scaffold refuses to put an empty delta API plan beside it, and the delta backend plan
+# is re-planned with the API in it, as before.
 #
 # IT DOES NOT CHOOSE THE CHANGE — the caller already did. `plan` asks one question at the
 # top of its run (which is why a re-plan of the MASTER and a delta are the same command),
@@ -46,17 +54,18 @@
 # from the caller already narrowed to the developer's working lanes (.appweaver/lane.json)
 # and to the lanes on the change's **Lanes** line, so a lane that is somebody else's, or
 # that the change does not touch, gets no delta plan here. The other half of the change is
-# READ: the frontend delta plan binds to delta_backend_plan_read, the change's service delta
-# plan as the backend developer left it — absent for a frontend-only change, whose bindings
-# are to the master's published surface.
+# READ: the frontend delta plan binds to delta_api_read, the change's API as the backend
+# developer left it (its delta API plan, or the delta backend plan of an older change) —
+# absent for a frontend-only change, whose bindings are to the feature's API (api_read).
 #
 # EXPECTS caller vars: feature_dir, spec_file, backend_plan, frontend_plan, domain_model,
 #   be_existing, fe_existing, fe_lane_id, source_files, source_count, USER_INPUT,
-#   delta_backend_plan_read,
+#   api_read, delta_api_read, req_backend_text,
 #   and — resolved by the caller from the change it chose and activated — cr_id, cr_dir,
 #   delta_spec, delta_model, wave, predecessor_files, predecessor_count, predecessor_ids,
 #   sibling_count, sibling_ids, related_docs.
-# PRODUCES: delta_backend_plan, delta_frontend_plan, downstream_count, impact_report.
+# PRODUCES: delta_api_plan, delta_backend_plan, delta_frontend_plan, downstream_count,
+#   impact_report.
 # =============================================================================
 
 name: delta-plan
@@ -91,13 +100,57 @@ vars:
   related_docs: []
   delta_backend_plan: ""
   delta_frontend_plan: ""
-  delta_backend_plan_read: ""
+  api_read: ""
+  delta_api_read: ""
+  req_backend_text: "none"
+  # The change's delta API plan. delta_api_go is false for a lane not worked here and for a
+  # change whose delta backend plan still carries its API (the scaffold is then `blocked`).
+  delta_api_plan: ""
+  delta_api_blocked: "false"
+  delta_api_go: "false"
+  be_delta_api_rule: ""     # what the delta backend plan is told about where the change's API is — set below
 
 workflow:
 
   # 1. Scaffold this change's plan document for each lane whose MASTER already exists.
   #    A lane whose master was scaffolded in this same run has just been authored from
   #    the whole spec — there is nothing for a delta to add to it — so it gets none.
+  #
+  #    THE CHANGE'S API FIRST, before the delta backend plan, for the reason the master's
+  #    is: the scaffold refuses (`blocked`) while the change's delta backend plan still
+  #    carries its API, and a delta backend plan scaffolded first from a template
+  #    generated before delta API plans existed could carry the old contract table.
+  - id: api_delta_scaffold
+    condition: "{{be_existing}} == true"
+    action: execute_script
+    script: { ref: actions }
+    subcommand: delta-plan-scaffold
+    args: ["--cr-id", "{{cr_id}}", "--lane", "api", "--feature-dir", "{{feature_dir}}"]
+    outputs:
+      - { name: delta_api_plan,    from: "$.delta_plan" }
+      - { name: delta_api_blocked, from: "$.blocked" }
+
+  # Where the change's API is authored, as ordered assignments: the delta API plan on a
+  # worked backend lane; its delta backend plan, as before, for a change whose delta
+  # backend plan already carries it.
+  - id: api_delta_arm
+    condition: "{{be_existing}} == true"
+    action: set
+    vars:
+      delta_api_go: "true"
+      be_delta_api_rule: "THE CHANGE'S API IS IN delta-api-plan.md (in context), authored just before this document: the endpoints it adds, changes and removes, and the requests it answers. Do NOT restate them here — the API section of this document is the one line pointing to delta-api-plan.md, and where the template has a contract table or an endpoint section (a template generated before delta API plans existed), that line goes in their place. REALISE every endpoint instead: each names under **Maps to** the use-case that serves it, which this document ADDS or MODIFIES, with request and response DTOs that match the endpoint's shapes; a removed endpoint's use-case is REMOVED unless something else still uses it."
+  - id: api_delta_in_backend_plan
+    condition: "{{delta_api_blocked}} == true"
+    action: set
+    vars:
+      delta_api_go: "false"
+      be_delta_api_rule: "THIS CHANGE WAS PLANNED BEFORE DELTA API PLANS EXISTED, so its API stays in this document. PUBLISH WHAT THE FRONTEND LANE NEEDS: fill '## Contract deltas for the frontend lane' with every addition, change or removal to this feature's published surface, one row per endpoint carrying its operation id — a changed endpoint keeps the one the API gives it, a new endpoint gets one unique across the service — and 'None' when the surface is unchanged. THEN WRITE EACH ENDPOINT IT ADDS OR CHANGES IN FULL under '## API — added and changed endpoints', as the API's own endpoint block: the `VERB /route` heading, then **Operation id**, **Request**, **Success** and the **Errors** table, every shape `{ field: type }`. A removed endpoint gets a `removed` row and no block."
+  # The frontend delta plan binds to the delta API plan once this run has one.
+  - id: delta_api_read_own
+    condition: "{{delta_api_go}} == true"
+    action: set
+    vars: { delta_api_read: "{{delta_api_plan}}" }
+
   - id: be_delta_scaffold
     condition: "{{be_existing}} == true"
     action: execute_script
@@ -116,6 +169,89 @@ workflow:
     outputs:
       - { name: delta_frontend_plan, from: "$.delta_plan" }
 
+  # ═════════════════════ THE CHANGE'S API — the delta API plan ═════════════════
+  # The endpoints the change adds, changes and removes, and the requests it answers, in
+  # the API plan's own block form — which finalize-delta merges into api-plan.md block by
+  # block, so a changed endpoint is written whole. Authored before the delta backend plan,
+  # which realises each endpoint.
+  - id: ctx_api_delta
+    condition: "{{delta_api_go}} == true"
+    action: build_context
+    context_from: related_docs               # the predecessors' delta-specs and every open
+                                             # change's model delta — the same two kinds,
+                                             # and the same opposite licence, as the
+                                             # service lane below.
+    context:
+      - "{{delta_api_plan}}"                 # the delta API plan template to fill
+      - "{{delta_spec}}"                     # the spec-side change (from specify)
+      - { path: "{{delta_model}}", optional: true }
+      - "{{spec_file}}"                      # the current master spec (READ ONLY)
+      - { path: "{{api_read}}", optional: true }
+                                             # THE FEATURE'S API AS IT STANDS (READ ONLY) —
+                                             # api-plan.md, or the backend plan of a feature
+                                             # planned before it. Planned against block by
+                                             # block, never edited here.
+      - { path: "{{domain_model}}", optional: true }
+      - { path: .appweaver/memory/constitution.technical.md, optional: true }
+      - { path: "{{cr_dir}}/delta-slice-analyze-report.md", optional: true }
+      - { path: "{{cr_dir}}/delta-slice-analyze-report.backend.md", optional: true }
+                                             # WHAT THE LAST GATE FOUND — a missing or moved
+                                             # endpoint tagged `fix: plan` is closed here.
+      - { path: .appweaver/DESIGN-FORMAT.md }
+  - id: author_api_delta
+    condition: "{{delta_api_go}} == true"
+    action: agent_author                     # plan's technical standards stay ON (default) — correct here
+    tools: Read   # the feature's EXISTING source arrives as {{source_files}} paths, not inlined
+    output_target: { type: file, path: "{{delta_api_plan}}" }
+    task: |
+      Fill the DELTA API PLAN for change {{cr_id}} (wave {{wave}}) — the target document in
+      context: the endpoints this change adds to, changes in and removes from the feature's
+      API, and the frontend lane's requests it answers. It is authored before the change's
+      delta backend plan, which then realises each endpoint, and finalize-delta merges it
+      into api-plan.md by script, every block as it stands. THE DELTA ONLY — do NOT edit the
+      feature's api-plan.md or backend-plan.md.
+      - THE FEATURE'S API AS IT STANDS is in context: api-plan.md, or the API section of a
+        backend plan written before API plans existed. Plan against it, block by block.
+      - FILL "## Contract deltas for the frontend lane" with one row per endpoint the change
+        adds, changes or removes: Operation id, Contract (`VERB /route`), Change (added /
+        changed / removed), Shape, Serves. A changed endpoint keeps the operation id the API
+        gives it; a new one takes an id unique across the service. `None` when the change
+        leaves the API as it is — what a purely internal change says.
+      - THEN WRITE EACH ENDPOINT IT ADDS OR CHANGES IN FULL under "## Endpoints added or
+        changed", in the API's own block form: the `### `VERB /route`` heading, then
+        **Operation id**, **Auth**, **Request**, **Success**, the **Errors** table and
+        **Maps to**, every shape as `{ field: type }`. The merge puts this block in place of
+        the API's block, so a changed endpoint is written WHOLE — its unchanged fields too —
+        never as the difference. A removed endpoint has its row and no block. A shape in
+        prose reaches the frontend untyped.
+      - ANSWER THE REQUESTS THIS CHANGE SERVES. Still open in the frontend plan's "Contract
+        deltas needed": {{req_backend_text}}. Answer under "## Requests from the frontend
+        lane" only those this change's delta-spec gives a basis for — published under an
+        operation id, with its endpoint above, or declined with the reason. The others stay
+        open for the master. `None` when the change answers none.
+      - READ THE CODE FIRST. {{source_count}} source file(s) currently realise this
+        feature: {{source_files}}. Where the code already serves an endpoint this change
+        touches, its route, verb and operation id are as the code has them.
+      - THE LAST GATE'S REPORT, when one is in context (delta-slice-analyze-report.md from
+        a run that gated every lane, delta-slice-analyze-report.backend.md from one that
+        gated the backend alone; when both are, the one with the later date is the last
+        gate). A finding tagged `fix: plan` about an endpoint says THIS document was what was
+        wrong — re-derive the rows and blocks it names. EVIDENCE, never a requirement
+        source: the delta-spec stays the only authority on what the change must do.
+      - THE EFFECTIVE MODEL IS master + this change's delta + the PREDECESSOR deltas in
+        context. {{predecessor_count}} predecessor(s) — open changes in a LOWER wave:
+        {{predecessor_ids}}. You MAY build on one. {{sibling_count}} SIBLING change(s) at
+        the same or a higher wave: {{sibling_ids}} — never assume any of them lands; plan
+        against the API as it stands.
+      - TWO CASES — decide from the delta-spec in context: SPEC-DRIVEN, where every endpoint
+        row serves one of the delta-spec's ids; PLAN-ONLY (an unfilled stub), where an
+        endpoint row still traces to an EXISTING spec id — the realisation moves, never the
+        requirement.
+      - TECHNOLOGY-AGNOSTIC: protocol level only, conceptual types, no code.
+      - Do NOT edit the Wave / Base version / Delta spec / Delta backend plan headers —
+        scripts stamp those.
+      Guidance: {{USER_INPUT}}
+
   # ═════════════════════ BACKEND LANE — the service delta plan ═════════════════
   - id: ctx_backend_delta
     condition: "{{be_existing}} == true"
@@ -136,6 +272,11 @@ workflow:
                                              # unfilled one, and that is a valid state.
       - "{{spec_file}}"                      # the current master spec (READ ONLY)
       - "{{backend_plan}}"                   # the current master plan (READ ONLY — never amended here)
+      - { path: "{{delta_api_plan}}", optional: true }
+                                             # THE CHANGE'S API, authored just above — the
+                                             # endpoints this plan realises. Absent for a change
+                                             # planned before delta API plans existed, whose API
+                                             # is in this plan.
       - { path: "{{domain_model}}", optional: true }
                                              # the context's CANONICAL model — the aggregate root,
                                              # its entities and its invariants live here, not in the
@@ -205,13 +346,7 @@ workflow:
         that either order of merging works. If consuming one is genuinely unavoidable,
         that is a dependency, not an overlap: record it under "## Depends on" and say the
         wave must be raised. Until merged, every one of them is a proposal.
-      - PUBLISH WHAT THE FRONTEND LANE NEEDS. Fill "## Contract deltas for the frontend
-        lane" with every addition or change to this feature's published surface, as field
-        shapes. That table is the only part of this document the frontend delta plan may
-        bind against; a contract the UI needs and this document never states becomes a
-        client-side workaround. "None" when the surface is unchanged. Each row carries the
-        endpoint's operation id: a changed endpoint keeps the one the master plan gives
-        it, and a new endpoint gets one unique across the service.
+      - {{be_delta_api_rule}}
       - Stay technology-agnostic (no code) and keep the master's form: behaviour as
         signatures + pre/post/invariant/raises, contracts as field shapes.
       - TWO CASES — decide from the delta-spec in context:
@@ -260,13 +395,17 @@ workflow:
       - { path: "{{delta_model}}", optional: true }
       - "{{spec_file}}"                      # the current master spec (READ ONLY)
       - "{{frontend_plan}}"                  # the current master plan (READ ONLY — never amended here)
-      - { path: "{{delta_backend_plan_read}}", optional: true }
-                                             # THE SERVICE HALF of this same change — its contract
-                                             # table is what this lane binds to. READ here, and
+      - { path: "{{delta_api_read}}", optional: true }
+                                             # THIS CHANGE'S API — its delta API plan, or the
+                                             # delta backend plan of a change planned before
+                                             # those — is what this lane binds to. READ here, and
                                              # authored above only when the backend is a working
                                              # lane: another developer may own it. Optional: an
-                                             # experience-only change has no service delta, and a
+                                             # experience-only change has no API delta, and a
                                              # frontend-only project has no service lane at all.
+      - { path: "{{api_read}}", optional: true }
+                                             # THE FEATURE'S API as it stands — for the endpoints
+                                             # this change leaves alone.
       - { path: "{{domain_model}}", optional: true }
       - { path: .appweaver/memory/constitution.ui.md, optional: true }
       - { path: "{{cr_dir}}/delta-slice-analyze-report.md", optional: true }
@@ -315,15 +454,17 @@ workflow:
         delta-spec does not describe is a SPEC gap: log it as a DA-n that routes back to
         `specify`, never invent the requirement here.
       - THE LANE BOUNDARY IS THE PUBLISHED SURFACE. Bind against the delta-spec's IC- ids
-        and, where the service delta is in context, its "Contract deltas for the frontend
-        lane" table. CITE those contracts; do not restate, re-derive or contradict them,
-        and introduce no server-side behaviour or persistence assumption. What the
-        experience needs and the surface does not offer goes under "Contract deltas
-        needed", raised back to the service lane — never worked around in the client.
+        and, where this change's API is in context, its "Contract deltas for the frontend
+        lane" table and the endpoint blocks it writes; for an endpoint the change leaves
+        alone, the feature's API in context. CITE those contracts; do not restate,
+        re-derive or contradict them, and introduce no server-side behaviour or persistence
+        assumption. What the experience needs and the surface does not offer goes under
+        "Contract deltas needed", raised back to the service lane — never worked around in
+        the client.
       - A BINDING ROW'S ELEMENT LEADS WITH ITS OPERATION ID — `OperationId` · `VERB
-        /route` — copied exactly from the service delta's table or, for an endpoint the
-        change does not touch, the master backend plan. Implement looks the endpoint up by
-        it in the service's exported API document.
+        /route` — copied exactly from this change's API or, for an endpoint the change does
+        not touch, the feature's. Implement looks the endpoint up by it in the API document
+        drafted from the API plans, this change's included.
       - UX- IS THIS DOCUMENT'S TO REALISE. The service plan excludes the spec's Experience
         Standards by contract, so a UX- item in the delta-spec that reaches neither plan
         is a dropped requirement.
@@ -341,7 +482,7 @@ workflow:
       - TECHNOLOGY-AGNOSTIC: no framework, router, state library, component library or
         styling approach — responsibilities, field shapes, events and states only. The
         header's Lane field is `{{fe_lane_id}}`.
-      - Do NOT edit the Wave / Base version / Delta spec / Service delta headers — scripts
+      - Do NOT edit the Wave / Base version / Delta spec / API delta headers — scripts
         stamp those.
       Guidance: {{USER_INPUT}}
 

package/assets/.appweaver/orchestrator/modules/domain-select.orch.yaml

@@ -5,7 +5,10 @@
 # `action: include`) by every domain-aware converted skill. Same flow:
 #   1. resolve the active domain + candidate rule files for {{command}}
 #   2. Domain gate: no domain / no domain-rule-bindings → ask Continue (technical only)
-#      or EXIT (stops the whole skill, no side effects)
+#      or EXIT (stops the whole skill, no side effects). Where the map exists but loads
+#      less than it says — no `## /{{command}}` heading (absent or misspelled; a heading
+#      present and deliberately empty does not warn), or a mapped file not on disk — WARN
+#      and carry on; the engine returns each warning in the run result.
 #   3. Selection box: all / subset / none
 #   4. load the selected rule files — into the STICKY STANDARDS SET (D3: domain
 #      rules are SYSTEM standards; every later generation sees them without the
@@ -43,7 +46,32 @@ workflow:
     outputs:
       - { name: domain,            from: "$.domain" }
       - { name: dg_rulemap_exists, from: "$.rulemap_exists" }
+      - { name: dg_heading_found,  from: "$.heading_found" }
       - { name: dg_candidates,     from: "$.candidates" }
+      - { name: dg_missing,        from: "$.missing" }
+
+  # 1b. What the map says and does not load — warnings, never stops, and only where the
+  #     map exists (its absence is the gate below). The engine has no "list is not empty"
+  #     test, so the missing list sets a flag false when it has entries.
+  - id: dg_flags
+    action: set
+    vars: { dg_all_on_disk: "true" }
+  - id: dg_flag_missing
+    condition: "{{dg_missing}} != []"
+    action: set
+    vars: { dg_all_on_disk: "false" }
+  - id: warn_no_heading
+    condition: "{{dg_rulemap_exists}} == true"
+    action: verify_context
+    require_true: dg_heading_found
+    on_false: continue
+    on_false_message: "WARNING — guardrails/{{domain}}/domain-rule-bindings.md has no `## /{{command}}` heading, so this step loads no domain rules from the map. If that is not intended, add the heading and its rule files — it must read exactly `## /{{command}}`."
+  - id: warn_missing
+    condition: "{{dg_rulemap_exists}} == true"
+    action: verify_context
+    require_true: dg_all_on_disk
+    on_false: continue
+    on_false_message: "WARNING — guardrails/{{domain}}/domain-rule-bindings.md maps these files under `## /{{command}}`, but they are not on disk, so they were not loaded: {{dg_missing}}. Correct the paths, or add the files."
 
   # 2. Domain gate — only when the project or its domain-rule-bindings.md is missing.
   - id: gate

package/assets/.appweaver/orchestrator/modules/foundation-pack.orch.yaml

@@ -68,6 +68,7 @@ workflow:
       fp_residue_note: "not checked"
       fp_lane_found: "false"
       fp_lane_file: ""
+      fp_lane_contract_write: ""
       fp_lane_contract_run: ""
       fp_lane_contract: ""
       fp_lane_client: ""
@@ -198,8 +199,9 @@ workflow:
     on_false_message: "NOT scaffolded — the {{fl_name}} unpacker failed and wrote {{fp_written}} file(s). Its output ends: {{fp_unpack_out}}"
 
   # 5b. The pack's LANE SETTINGS (<pack name>.lane.json beside it): what only the pack
-  #     knows about the project it scaffolds — chiefly how its service is started on its
-  #     own so implement can export the API document. Recorded on the lane with lane-set;
+  #     knows about the project it scaffolds — chiefly how its service's API document is
+  #     written, or how the service is started on its own to fetch it, so analyze-slice
+  #     can check the API it serves against the plan. Recorded on the lane with lane-set;
   #     a key the file leaves empty is not touched, and a pack with no such file leaves
   #     the lane on its stack profile's values.
   - id: fp_lane_settings
@@ -211,6 +213,7 @@ workflow:
     outputs:
       - { name: fp_lane_found,        from: "$.found" }
       - { name: fp_lane_file,         from: "$.file" }
+      - { name: fp_lane_contract_write, from: "$.contract_write" }
       - { name: fp_lane_contract_run, from: "$.contract_run" }
       - { name: fp_lane_contract,     from: "$.contract" }
       - { name: fp_lane_client,       from: "$.client" }
@@ -221,14 +224,14 @@ workflow:
     on_error: continue
     script: { ref: actions }
     subcommand: lane-set
-    args: ["--id", "{{fl_lane_id}}", "--set", "contract_run={{fp_lane_contract_run}}", "--set", "contract={{fp_lane_contract}}", "--set", "client={{fp_lane_client}}"]
+    args: ["--id", "{{fl_lane_id}}", "--set", "contract_write={{fp_lane_contract_write}}", "--set", "contract_run={{fp_lane_contract_run}}", "--set", "contract={{fp_lane_contract}}", "--set", "client={{fp_lane_client}}"]
     outputs:
       - { name: fp_lane_recorded, from: "$.ok" }
 
   - id: fp_lane_noted
     action: set
     condition: "{{fp_lane_recorded}} == true"
-    vars: { fp_lane_note: "; the pack's API-export settings ({{fp_lane_file}}) recorded on the {{fl_lane_id}} lane" }
+    vars: { fp_lane_note: "; the pack's API-document settings ({{fp_lane_file}}) recorded on the {{fl_lane_id}} lane" }
 
   # 6. The merges the rule file asks for: the file that was there (put aside) and the
   #    pack's version (now on disk) become one, as the rule's instruction says.

package/assets/.appweaver/orchestrator/modules/foundation-spec.orch.yaml

@@ -69,6 +69,7 @@ workflow:
       fs_build_ack: ""
       fs_build_ok: ""
       fs_build_note: "build not run — /appweaver build compiles it and repairs compile errors"
+      fs_hdr_contract_write: ""
       fs_hdr_contract_run: ""
       fs_hdr_contract: ""
       fs_hdr_client: ""
@@ -76,20 +77,17 @@ workflow:
       fs_placeholder: ""
       fs_is_backend: "false"
       fs_is_frontend: "false"
-      fs_need_run: "false"
-      fs_need_url: "false"
+      fs_need_write: "false"
       fs_need_client: "false"
-      fs_ans_contract_run: ""
-      fs_ans_contract: ""
+      fs_ans_contract_write: ""
       fs_ans_client: ""
+      fs_set_write: ""
       fs_set_run: ""
       fs_set_url: ""
       fs_set_client: ""
-      fs_cur_contract_run: ""
-      fs_cur_contract: ""
+      fs_cur_contract_write: ""
       fs_cur_client: ""
-      fs_cur_run_shown: "none — the export is skipped until one is set"
-      fs_cur_url_shown: "none — the export is skipped until one is set"
+      fs_cur_write_shown: "none — the API is not checked against the plan until one is set"
       fs_cur_client_shown: "none — implement asks for one before it generates the frontend"
       fs_lane_written: ""
       fs_lane_note: ""
@@ -152,6 +150,7 @@ workflow:
       - { name: fs_source,    from: "$.source" }
       - { name: fs_title,     from: "$.title" }
       - { name: fs_reason,    from: "$.reason" }
+      - { name: fs_hdr_contract_write, from: "$.contract_write" }
       - { name: fs_hdr_contract_run, from: "$.contract_run" }
       - { name: fs_hdr_contract,     from: "$.contract" }
       - { name: fs_hdr_client,       from: "$.client" }
@@ -170,6 +169,7 @@ workflow:
       - { name: fs_source,    from: "$.source" }
       - { name: fs_title,     from: "$.title" }
       - { name: fs_reason,    from: "$.reason" }
+      - { name: fs_hdr_contract_write, from: "$.contract_write" }
       - { name: fs_hdr_contract_run, from: "$.contract_run" }
       - { name: fs_hdr_contract,     from: "$.contract" }
       - { name: fs_hdr_client,       from: "$.client" }
@@ -421,14 +421,17 @@ workflow:
     condition: "{{fs_build_ok}} == false"
     vars: { fs_build_note: "build FAILED — run /appweaver build, which repairs compile errors: {{fs_build_tail}}" }
 
-  # 8. THE API CONTRACT SETTINGS — what implement uses between the lanes to export the
-  #    service's OpenAPI document and generate the frontend's client from it
-  #    (STACK-PROFILES.md §4.5). A backend lane needs its start command and document URL,
-  #    a frontend lane its client command. Each comes from the spec's header
-  #    (`# contract-run:`, `# contract:`, `# client:`, read at capture); one the header
-  #    does not give is asked for, and an empty answer keeps the lane's current value —
-  #    the stack profile's, unless something set it already. What there is, is recorded
-  #    on the lane with lane-set, as the pack route records a pack's .lane.json.
+  # 8. THE API CONTRACT SETTINGS — what the lanes use for the API between them
+  #    (STACK-PROFILES.md §4.5). A frontend lane needs its client command, which generates
+  #    its API client from the API documents drawn from the features' API plans. A backend lane may say how its
+  #    service's as-built API document is written — `contract_write`, a command that writes
+  #    it with no server started — which analyze-slice runs to check the API the code
+  #    serves against the plan; or how the service is started to fetch it (`contract_run`
+  #    + `contract`), which only the header gives. Each comes from the spec's header
+  #    (`# contract-write:`, `# contract-run:`, `# contract:`, `# client:`, read at capture);
+  #    the one the header does not give is asked for, and an empty answer keeps the lane's
+  #    current value. What there is, is recorded on the lane with lane-set, as the pack
+  #    route records a pack's .lane.json.
   - id: fs_kind_backend
     action: set
     condition: "{{fl_kind}} == backend"
@@ -437,14 +440,15 @@ workflow:
     action: set
     condition: "{{fl_kind}} == frontend"
     vars: { fs_is_frontend: "true" }
-  - id: fs_need_run_arm
+  # Asked only when the header names no way at all: a start command it gives is a way.
+  - id: fs_need_write_arm
     action: set
-    condition: "{{fs_hdr_contract_run}} == "
-    vars: { fs_need_run: "{{fs_is_backend}}" }
-  - id: fs_need_url_arm
+    condition: "{{fs_hdr_contract_write}} == "
+    vars: { fs_need_write: "{{fs_is_backend}}" }
+  - id: fs_need_write_run
     action: set
-    condition: "{{fs_hdr_contract}} == "
-    vars: { fs_need_url: "{{fs_is_backend}}" }
+    condition: "{{fs_hdr_contract_run}} != "
+    vars: { fs_need_write: "false" }
   - id: fs_need_client_arm
     action: set
     condition: "{{fs_hdr_client}} == "
@@ -458,47 +462,36 @@ workflow:
     subcommand: lane-resolve
     args: ["--id", "{{fl_lane_id}}"]
     outputs:
-      - { name: fs_cur_contract_run, from: "$.backend_contract_run" }
-      - { name: fs_cur_contract,     from: "$.backend_contract" }
-      - { name: fs_cur_client,       from: "$.frontend_client" }
-  - id: fs_cur_run_known
+      - { name: fs_cur_contract_write, from: "$.backend_contract_write" }
+      - { name: fs_cur_client,         from: "$.frontend_client" }
+  - id: fs_cur_write_known
     action: set
-    condition: "{{fs_cur_contract_run}} != "
-    vars: { fs_cur_run_shown: "{{fs_cur_contract_run}}" }
-  - id: fs_cur_url_known
-    action: set
-    condition: "{{fs_cur_contract}} != "
-    vars: { fs_cur_url_shown: "{{fs_cur_contract}}" }
+    condition: "{{fs_cur_contract_write}} != "
+    vars: { fs_cur_write_shown: "{{fs_cur_contract_write}}" }
   - id: fs_cur_client_known
     action: set
     condition: "{{fs_cur_client}} != "
     vars: { fs_cur_client_shown: "{{fs_cur_client}}" }
 
-  - id: fs_ask_contract_run
-    action: ask
-    condition: "{{fs_need_run}} == true"
-    prompt: |
-      How does the API in lane `{{fl_lane_id}}` start ON ITS OWN? /appweaver implement starts
-      it with this command to fetch its OpenAPI document before it generates the frontend.
-      The spec's header gives no `# contract-run:`.
-      Type the command — it runs in {{fl_workdir}} — with no orchestration host and nothing
-      the API cannot reach on this machine.
-      Leave it empty to keep the current one: {{fs_cur_run_shown}}
-    answer_var: fs_ans_contract_run
-  - id: fs_ask_contract
+  - id: fs_ask_contract_write
     action: ask
-    condition: "{{fs_need_url}} == true"
+    condition: "{{fs_need_write}} == true"
     prompt: |
-      At what URL does that running API serve its OpenAPI document? The spec's header gives
-      no `# contract:`.
-      Leave it empty to keep the current one: {{fs_cur_url_shown}}
-    answer_var: fs_ans_contract
+      How is the API document of lane `{{fl_lane_id}}` written, with no server started?
+      analyze-slice runs this command once the code is built and checks the API it
+      writes against backend-plan.md — the frontend lane is bound to the plan, never to
+      the running service. The spec's header gives no `# contract-write:`.
+      Type a command that writes the service's OpenAPI JSON to {{fs_placeholder}} — the
+      stack's own generator, or a script that loads the application and dumps its
+      document. It runs in {{fl_workdir}}.
+      Leave it empty to keep the current one: {{fs_cur_write_shown}}
+    answer_var: fs_ans_contract_write
   - id: fs_ask_client
     action: ask
     condition: "{{fs_need_client}} == true"
     prompt: |
-      Which command generates this frontend's API client from the service's OpenAPI
-      document? The spec's header gives no `# client:`.
+      Which command generates this frontend's API client from an OpenAPI document? The
+      spec's header gives no `# client:`.
       It runs in {{fl_workdir}}, and {{fs_placeholder}} in it stands for the document's path —
       for example: npx openapi-typescript {{fs_placeholder}} -o lib/api/schema.d.ts
       Leave it empty to keep the current one: {{fs_cur_client_shown}}
@@ -509,15 +502,11 @@ workflow:
   - id: fs_set_backend
     action: set
     condition: "{{fs_is_backend}} == true"
-    vars: { fs_set_run: "{{fs_hdr_contract_run}}", fs_set_url: "{{fs_hdr_contract}}" }
-  - id: fs_set_run_answer
-    action: set
-    condition: "{{fs_need_run}} == true"
-    vars: { fs_set_run: "{{fs_ans_contract_run}}" }
-  - id: fs_set_url_answer
+    vars: { fs_set_write: "{{fs_hdr_contract_write}}", fs_set_run: "{{fs_hdr_contract_run}}", fs_set_url: "{{fs_hdr_contract}}" }
+  - id: fs_set_write_answer
     action: set
-    condition: "{{fs_need_url}} == true"
-    vars: { fs_set_url: "{{fs_ans_contract}}" }
+    condition: "{{fs_need_write}} == true"
+    vars: { fs_set_write: "{{fs_ans_contract_write}}" }
   - id: fs_set_frontend
     action: set
     condition: "{{fs_is_frontend}} == true"
@@ -532,7 +521,7 @@ workflow:
     on_error: continue
     script: { ref: actions }
     subcommand: lane-set
-    args: ["--id", "{{fl_lane_id}}", "--set", "contract_run={{fs_set_run}}", "--set", "contract={{fs_set_url}}", "--set", "client={{fs_set_client}}"]
+    args: ["--id", "{{fl_lane_id}}", "--set", "contract_write={{fs_set_write}}", "--set", "contract_run={{fs_set_run}}", "--set", "contract={{fs_set_url}}", "--set", "client={{fs_set_client}}"]
     outputs:
       - { name: fs_lane_written, from: "$.written" }
   - id: fs_lane_noted