aw-spec-cli 0.1.32 → 0.1.34

package/assets/.appweaver/stack-profiles/dotnet-webapi.json

@@ -17,8 +17,6 @@
   "build": "dotnet build",
   "test": "dotnet test",
   "run": "dotnet run --project {{host}}",
-  "contract_run": "dotnet run --project {{host}} -- --environment Development --urls http://localhost:5000",
-  "contract": "http://localhost:5000/swagger/v1/swagger.json",
   "host_patterns": [
     "**/*.AppHost.csproj",
     "**/*.Api.csproj",

package/assets/.appweaver/stack-profiles/java-spring.json

@@ -17,8 +17,6 @@
   "build": "./mvnw clean install",
   "test": "./mvnw test",
   "run": "./mvnw spring-boot:run",
-  "contract_run": "./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8080",
-  "contract": "http://localhost:8080/v3/api-docs",
   "detect": [
     "pom.xml",
     "build.gradle"

package/assets/.appweaver/templates/api-plan-template.md

@@ -0,0 +1,107 @@
+# API Plan: [FEATURE]
+
+**Feature**: `[Feature]`
+
+**Plan home**: `specs/[Context]/[Feature]/api-plan.md`
+
+**Source spec**: `specs/[Context]/[Feature]/spec.md`
+
+**Backend plan**: `specs/[Context]/[Feature]/backend-plan.md`   <!-- realises each endpoint below as a use-case -->
+
+**Version**: v1.0   <!-- moves in lockstep with spec.md and the lane plans; close-delta stamps every applied change -->
+
+**Status**: Draft
+
+<!--
+  WHAT THIS DOCUMENT IS
+  =====================
+  The API CONTRACT of ONE feature: every endpoint the service lane publishes for it, and
+  the service lane's answers to the frontend lane's requests. It is the one document the
+  two lanes meet on, and the only part of the service's planning the frontend lane reads.
+
+    spec.md ──▶ api-plan.md ──┬──▶ api-draft.json         drafted by script (contract-draft)
+                              ├──▶ frontend-plan.md §5    binds to the operation ids
+                              └──▶ backend-plan.md        realises each endpoint as a use-case
+
+  IT IS A MASTER, LIKE spec.md. A change plans its API in changes/<CR-id>/delta-api-plan.md,
+  and finalize-delta merges that document into this one, by script and by whole endpoint
+  block (contract-merge). The backend plan is derived and never merged; this document is
+  merged, so what a change adds or changes is here from the moment the change is merged,
+  and every redraw of api-draft.json reads it from here.
+
+  THE FORM IS FIXED, IN EVERY PROJECT. Each endpoint is one block under "## Endpoints": the
+  heading `### `VERB /route`` with the fields below it. The contract scripts read exactly
+  this form — contract-draft writes api-draft.json from the blocks, contract-requests reads
+  the operation ids and the requests table, contract-merge replaces, adds and deletes whole
+  blocks by operation id — so an endpoint written as a table row or in prose reaches none
+  of them.
+
+  PROTOCOL LEVEL, TECHNOLOGY-AGNOSTIC. Route, verb, auth, request and response shapes,
+  status codes and the error contract — never controller code, framework attributes,
+  serializer settings or language types. Every shape is `{ field: type }` in conceptual
+  types (string, int, decimal, bool, enum(A|B), list<T>, id<T>, money, date, datetime): a
+  shape in prose reaches the frontend's client untyped. The stack binds at `implement`.
+  REST over HTTP is assumed, per the constitution. A service whose constitution publishes
+  another protocol states its operations in the same block form, but contract-draft drafts
+  only `VERB /route` headings, so api-draft.json carries none of the others.
+
+  WHAT LIVES ELSEWHERE
+  - The use-case behind each endpoint — handler orchestration, validation, authorization
+    rule, the DTOs it carries — is the backend plan's; **Maps to** names it. A shape written
+    as a DTO name instead of `{ field: type }` is read from that backend plan use-case.
+  - Traceability: each block's heading cites the spec ids it serves, and the backend plan's
+    traceability spine cites the endpoint as `VERB /route`.
+
+  HOW TO AUTHOR
+  - Fill every [PLACEHOLDER] and repeat the endpoint block once per endpoint.
+  - The OPERATION ID is the endpoint's name in the published API document, unique across
+    the service and never reused: the frontend plan binds to it, implement gives the
+    endpoint exactly it, and analyze-slice checks the built service serves it. An endpoint
+    the code already serves keeps the id it publishes, spelled exactly as the code spells
+    it; where it publishes none, write `—` and say so in the block — never an invented id,
+    which the built service would not carry.
+  - Write `None` under "## Endpoints" when the feature publishes no endpoint.
+  - Delete these authoring comments as you fill each section.
+-->
+
+## Endpoints
+
+### `[VERB] [/route]` — [purpose] · Serves US-[n] · FR-[nnn]
+
+- **Operation id**: `[OperationId]`
+- **Auth**: [required role/scope]
+- **Request**: `[path/query params]` + body `{ [field]: [type], … }`
+- **Success**: `2xx` → `{ [response shape] }`
+- **Errors** *(the error contract)*:
+
+  | Status | When | Body shape |
+  |---|---|---|
+  | 400 | [validation failure] | `{ errors: [{ field, message }] }` |
+  | 403 | [unauthorized] | `{ error }` |
+  | 409 | [conflict / duplicate — maps to a BR] | `{ error }` |
+
+- **Maps to**: `[use-case]` (the backend plan's element that realises it)
+
+## Requests from the frontend lane
+
+<!-- THE ANSWERS to the frontend plan's §5 "Contract deltas needed" table, one row per RQ-n
+     it raises. PUBLISH: add the endpoint above — under the proposed operation id unless it
+     clashes with one this service already uses — and name the id here. DECLINE: say why in
+     one line; a request the spec does not support is declined as a spec gap for `specify`,
+     never published on a guess. The frontend plan re-binds to the id given here. Keep every
+     answered row; write `None` instead of the table when the frontend plan raises no
+     request. -->
+
+| Request | Outcome | Operation id | Why |
+|---|---|---|---|
+| RQ-[n] | published / declined | `[OperationId]` / — | [one line — required when declined] |
+
+## Change History
+
+<!-- A row is appended when this document is re-derived (`plan main`) and when
+     finalize-delta merges a change into it — that row's Version reads `(pending)` until
+     close-delta stamps the number. Newest last. -->
+
+| Version | Date | Change | User stories | CR |
+|---------|------|--------|--------------|-----|
+| v1.0 | [DATE] | Initial API | US-1 | — |

package/assets/.appweaver/templates/delta-api-plan-template.md

@@ -0,0 +1,87 @@
+# Delta API Plan — [CR-ID]: [TITLE]
+
+**Feature**: `[Feature]`
+
+**Wave**: [N]   <!-- script-stamped from the delta-spec; same wave = developable in parallel, higher wave = after -->
+
+**Base version**: [vX.Y]   <!-- the API plan's version when this delta opened; close-delta bumps the minor at the end of the chain -->
+
+**Delta spec**: `changes/[CR-ID]/delta-spec.md`
+
+**Delta backend plan**: `changes/[CR-ID]/delta-backend-plan.md`   <!-- realises each endpoint below -->
+
+<!--
+  ONE CHANGE'S API. What this change adds to, changes in and removes from the feature's API
+  plan at specs/[Context]/[Feature]/api-plan.md, and the frontend lane's requests it
+  answers. It is authored in the change's own directory, beside the delta-spec and the delta
+  backend plan, and it is the only part of the change's service planning the frontend lane
+  binds to.
+
+  finalize-delta MERGES IT into api-plan.md, by script (contract-merge), as it merges the
+  delta-spec into spec.md: a `changed` endpoint's block replaces the API plan's block with
+  the same operation id, an `added` one joins the endpoints, a `removed` one is deleted, and
+  each request answered here replaces or joins its row of the API plan's requests table. The
+  merge copies each block as it stands, so a changed endpoint is written WHOLE, never as the
+  difference. The delta backend plan is never merged.
+
+  While the change is open, plan and analyze-plan-delta draft this document, by script, into
+  changes/[CR-ID]/api-draft.json — the API the frontend lane binds to for this change, and
+  the one analyze-slice-delta checks the built service against.
+
+  OPERATION IDS ARE STABLE. A changed endpoint keeps the id the API plan gives it; a new one
+  takes an id unique across the service. A `changed` or `removed` row whose operation the
+  frontend plan binds to is reported by analyze-plan-delta until this change's frontend delta
+  plan — or a follow-up change — carries the matching change.
+
+  TECHNOLOGY-AGNOSTIC, in the API plan's own form: every shape `{ field: type }` in
+  conceptual types, no code.
+-->
+
+## Contract deltas for the frontend lane
+
+<!-- One row per endpoint this change adds, changes or removes. The Operation id, Contract
+     and Change columns are what the merge and contract-impact read. `None` when the change
+     leaves the API as it is — the answer a purely internal change gives. -->
+
+| Operation id | Contract | Change | Shape | Serves |
+|---|---|---|---|---|
+| `[OperationId]` | `[VERB] [/route]` | added / changed / removed | [request → response field shapes] | FR-[nnn] · IC-[nnn] |
+
+## Endpoints added or changed
+
+<!-- Every endpoint the table marks `added` or `changed`, IN FULL, as the API plan's endpoint
+     block. A removed endpoint has its row above and no block. `None` when the table is
+     `None`. -->
+
+### `[VERB] [/route]` — [purpose] · Serves FR-[nnn]
+
+- **Operation id**: `[OperationId]`
+- **Auth**: [required role/scope]
+- **Request**: `[path/query params]` + body `{ [field]: [type], … }`
+- **Success**: `2xx` → `{ [response shape] }`
+- **Errors** *(the error contract)*:
+
+  | Status | When | Body shape |
+  |---|---|---|
+  | 400 | [validation failure] | `{ errors: [{ field, message }] }` |
+
+- **Maps to**: `[use-case]` (the element that realises it)
+
+## Requests from the frontend lane
+
+<!-- The open requests of the frontend plan's "Contract deltas needed" table that THIS change
+     answers — published under an operation id, with its endpoint above, or declined with the
+     reason. The merge writes each row into the API plan's requests table. A request this
+     change gives no basis for stays open for the master; write `None` when the change
+     answers none. -->
+
+| Request | Outcome | Operation id | Why |
+|---|---|---|---|
+| RQ-[n] | published / declined | `[OperationId]` / — | [one line — required when declined] |
+
+## On merge
+
+`finalize-delta` merges this document into the feature's `api-plan.md`, by script, with the
+change's spec and model halves, and leaves the change OPEN. The API plan's Change History gets
+a row for the merge, whose version `close-delta` stamps when it archives this file with the
+change. None of it is this document's job — it records the change, it does not apply it.

package/assets/.appweaver/templates/delta-design-template.md

@@ -12,6 +12,8 @@
 
 **Model delta**: `specs/[Context]/domain-model.[CR-ID].delta.md`   <!-- "none" when this change is behaviour-only -->
 
+**API delta**: `changes/[CR-ID]/delta-api-plan.md`   <!-- the endpoints this change adds, changes or removes, which this plan realises -->
+
 <!--
   ONE CHANGE'S PLAN FOR THE SERVICE LANE. It applies to the feature's master plan at
   specs/[Context]/[Feature]/backend-plan.md — never a new plan document. It is authored in
@@ -21,9 +23,15 @@
 
   IT DOES NOT TOUCH backend-plan.md, AND NEITHER DOES finalize-delta. Many changes may be
   open at once, so a delta that edited the master would move the baseline every other open
-  delta is authored against. The master plan is DERIVED from spec.md and domain-model.md —
-  the two documents finalize-delta does merge — so it is re-derived from them rather than
-  patched from this file.
+  delta is authored against. The master plan is DERIVED from spec.md, domain-model.md and
+  api-plan.md — the documents finalize-delta does merge — so it is re-derived from them
+  rather than patched from this file.
+
+  THE CHANGE'S API IS NOT PLANNED HERE. The endpoints it adds, changes or removes, and the
+  frontend lane's requests it answers, are in delta-api-plan.md beside this file: the only
+  part of the change's service planning the frontend lane binds to, and the one
+  finalize-delta merges into api-plan.md. This document plans the use-cases, ports and
+  adapters behind those endpoints.
 
   WHAT IT PLANS AGAINST — the EFFECTIVE MODEL, not the bare master:
     • specs/[Context]/domain-model.md              — the master model, what the domain IS today
@@ -82,14 +90,14 @@ it realises. "Realisation only — no spec delta" for a plan-only change.]
 
 ## ADDED — new plan elements
 
-<!-- New use-cases/handlers, endpoints, ports, adapters, and the realisation of any new
-     spec constraint / classification / contract. Serves = a spec id (FR-/BR-/CN-/DC-/IC-/US-);
-     the plan reads the spec and the domain model, never the domain rule files. -->
+<!-- New use-cases/handlers, ports, adapters, and the realisation of any new spec
+     constraint / classification / contract. A use-case behind an endpoint the API delta
+     adds names its operation id. Serves = a spec id (FR-/BR-/CN-/DC-/IC-/US-); the plan
+     reads the spec and the domain model, never the domain rule files. -->
 
 | Section (§) | Element | Kind | Serves |
 |---|---|---|---|
-| Application (§2) | `[Command/Query]` + handler | use-case | US-[n] · FR-[nnn] |
-| API (§3) | `[OperationId]` · `[VERB] [/route]` | endpoint | US-[n] · FR-[nnn] |
+| Application (§2) | `[Command/Query]` + handler — serves `[OperationId]` | use-case | US-[n] · FR-[nnn] |
 | Domain (§1) | `[Event]` handling / `[VO]` mapping | model realisation | BR-[nnn] · CN-[nnn] |
 | Infrastructure (§4.2) | `I[External]` adapter | contract realisation | IC-[nnn] |
 | Cross-cutting (§5) | [audit / retention / exposure decision] | constraint realisation | CN-[nnn] · DC-[nnn] |
@@ -112,22 +120,15 @@ it realises. "Realisation only — no spec delta" for a plan-only change.]
 [Which sections of the master ripple; shared elements touched (e.g. the aggregate root's
 realisation); new migration needed? (yes/no); any contract change other systems couple to.]
 
-## Contract deltas for the frontend lane
+## API changes
 
 <!--
-  What this change adds to, alters in or removes from the service's PUBLISHED surface — the
-  only part of this document the frontend lane may bind against. One row per contract; the
-  frontend delta plan cites these rather than re-deriving them. "None" when the surface is
-  unchanged, which is what a purely internal refactor should say. The operation id is the
-  endpoint's name in the published API document, unique across the service; an endpoint
-  the master plan already names keeps that id. A `changed` or `removed` row whose operation
-  the frontend plan binds to is reported by analyze-plan-delta until the frontend delta plan
-  of this change — or a follow-up change — carries the matching change.
+  The endpoints this change adds, changes or removes — its Contract deltas table and their
+  blocks — and the frontend lane's requests it answers are in delta-api-plan.md, beside this
+  file, not here. Keep this section as the one line below.
 -->
 
-| Operation id | Contract | Change | Shape | Serves |
-|---|---|---|---|---|
-| `[OperationId]` | `[VERB] [/route]` | added / changed / removed | [request → response field shapes] | IC-[nnn] · FR-[nnn] |
+The endpoints this change adds, changes or removes, and the requests it answers, are in [delta-api-plan.md](delta-api-plan.md).
 
 ## Other open deltas
 
@@ -156,8 +157,9 @@ e.g. re-test CreateOrder when the Order root's realisation or its repository is
 ## On merge
 
 `finalize-delta` merges the change's SPEC half into `spec.md` and its MODEL half into the
-context's `domain-model.md`, in one transaction, and leaves the change OPEN. It does NOT
-merge this document: the master plan is derived from those two, so it is re-derived rather
-than patched. `close-delta` archives this file with the change, bumps the minor version and
+context's `domain-model.md`, in one transaction, merges its `delta-api-plan.md` into the
+feature's `api-plan.md` by script, and leaves the change OPEN. It does NOT merge this
+document: the master plan is derived from those three, so it is re-derived rather than
+patched. `close-delta` archives this file with the change, bumps the minor version and
 writes the Change History rows. None of it is this document's job — it records the change,
 it does not apply it.

package/assets/.appweaver/templates/delta-spec-template.md

@@ -87,6 +87,6 @@
 - **On merge**: the new US-[n] is tagged `Added: (this CR)` in the master; finalize-delta
   merges this delta into spec.md and its model delta into domain-model.md — the two
   documents that DEFINE the slice, in one transaction — and appends the spec's Change
-  History row. The lane plans are not merged: they are derived from those two and are
-  re-derived from them. close-delta (after analyze-slice) archives the change and bumps
-  the minor version.
+  History row, then merges the change's delta API plan into api-plan.md by script. The
+  lane plans are not merged: they are derived from those three and are re-derived from
+  them. close-delta (after analyze-slice) archives the change and bumps the minor version.

package/assets/.appweaver/templates/design-template.md

@@ -8,6 +8,8 @@
 
 **Source model**: `specs/[Context]/domain-model.md`   <!-- structure: what the domain IS -->
 
+**API plan**: `specs/[Context]/[Feature]/api-plan.md`   <!-- the endpoints this service publishes, which §2 realises -->
+
 **Version**: v1.0   <!-- moves in lockstep with the spec; every applied change request bumps this — see Change History -->
 
 **Status**: Draft
@@ -60,6 +62,11 @@
   - Physical persistence (PKs/FKs, columns, indexes, JSON shapes, migration SQL)
     belongs to a technical-data-model. This doc states WHAT is stored and WHICH
     port persists it, not the schema.
+  - The endpoints this feature publishes — route, verb, operation id, request and
+    response shapes, the error contract — and the answers to the frontend lane's
+    requests are in api-plan.md beside this plan, the API contract the frontend lane
+    binds to. Each endpoint there maps to a §2.2 use-case, which this doc realises;
+    §3 points there and restates none of it.
 
   TECHNOLOGY-AGNOSTIC (mandatory)
   - Express behaviour as SIGNATURES + pre/post/invariant/raises pseudocode and
@@ -243,53 +250,23 @@ text, and do not add a rule the model does not carry)*
     4. [persist via port]  (single transaction boundary)
     5. [publish domain events]
     6. return [Response]
-    On failure: [which error → which API status in §3]
+    On failure: [which error → which status of the endpoint's error contract in api-plan.md]
   ```
 - **Emits**: `[DomainEvent]` (from §1.2)
 
 ## 3. API Layer
 
 <!--
-  The contract other systems couple to. Describe it at PROTOCOL level (REST assumed
-  per the constitution — adapt for gRPC/GraphQL/CLI if the stack differs), NOT as
-  controller code. Pin route, verb, auth, request/response shape, status codes, and
-  the error contract. Delegates to an Application use-case; no business logic here.
-  The OPERATION ID is the endpoint's name in the published API document, unique across
-  the service: the frontend plan cites it, and implement gives the endpoint exactly it.
+  The contract other systems couple to is NOT written here. Every endpoint this feature
+  publishes — route, verb, operation id, auth, request and response shapes, status codes,
+  the error contract — and the answers to the frontend lane's requests are in api-plan.md
+  beside this plan: the API contract the frontend lane binds to, merged by finalize-delta
+  when a change lands, and drafted by script into api-draft.json. Each endpoint there
+  names the §2.2 use-case it maps to, and that use-case is where this document realises
+  it. Keep this section as the one line below.
 -->
 
-### `[VERB] [/route]` — [purpose] · Serves US-Y · FR-00X
-
-- **Operation id**: `[OperationId]`
-- **Auth**: [required role/scope]
-- **Request**: `[path/query params]` + body `{ [field]: [type], … }`
-- **Success**: `2xx` → `{ [response shape] }`
-- **Errors** *(the error contract)*:
-
-  | Status | When | Body shape |
-  |---|---|---|
-  | 400 | [validation failure] | `{ errors: [{ field, message }] }` |
-  | 403 | [unauthorized] | `{ error }` |
-  | 409 | [conflict / duplicate — maps to a BR] | `{ error }` |
-
-- **Maps to**: `[Command/Query]` (§2.2)
-
-### Requests from the frontend lane
-
-<!-- THE ANSWERS to the frontend plan's §5 "Contract deltas needed" table, one row
-     per RQ-n it raises. PUBLISH: add the endpoint above — under the proposed
-     operation id unless it clashes with one this service already uses — and name
-     the id here. DECLINE: say why in one line; a request the spec does not
-     support is declined as a spec gap for `specify`, never published on a guess.
-     The frontend plan re-binds to the id given here. Keep every answered row;
-     write `None` instead of the table when the frontend plan raises no request.
-     plan and analyze-plan draft the endpoints above, by script, into
-     api-draft.json beside this plan, so a frontend can bind to an endpoint before
-     the service is built. -->
-
-| Request | Outcome | Operation id | Why |
-|---|---|---|---|
-| RQ-[n] | published / declined | `[OperationId]` / — | [one line — required when declined] |
+The endpoints this service publishes — route, verb, operation id, request, success and errors — and its answers to the frontend lane's requests are in [api-plan.md](api-plan.md), the API contract the frontend lane binds to.
 
 ## 4. Infrastructure Layer
 
@@ -365,7 +342,7 @@ text, and do not add a rule the model does not carry)*
 
 | Id | Source | Type | Design element(s) | Layer |
 |---|---|---|---|---|
-| FR-001 | spec | requirement | `[Root].[Behaviour]`, `[Command]`, `[VERB /route]` | Domain·App·API |
+| FR-001 | spec | requirement | `[Root].[Behaviour]`, `[Command]`, `[VERB /route]` (api-plan.md) | Domain·App·API |
 | BR-001 | model | invariant | `[Root]` invariant / `[VO]` validation | Domain |
 | CN-001 | spec | constraint | [where realised — §1 invariant / §4 persistence / §5 cross-cutting] | [layer] |
 | DC-001 | spec | classification | [exposure enforcement — §2 projection / §5 data-protection] | App·Infra |
@@ -409,8 +386,9 @@ text, and do not add a rule the model does not carry)*
 
 <!--
   The living-truth ledger. A row is appended when this plan is RE-DERIVED to carry a
-  change — this document is derived from spec.md and the context's domain-model.md, and
-  finalize-delta merges a change into those two, never into this one. close-delta archives
+  change — this document is derived from spec.md, the context's domain-model.md and
+  api-plan.md, and finalize-delta merges a change into those three, never into this one.
+  close-delta archives
   the CR, bumps the minor version in active_version.json and stamps that number into this
   document's **Version** header, so a header ahead of the newest row below means exactly
   what it says: the plan has not been re-derived since that version. A change to this

package/assets/.appweaver/templates/domain-model-template.md

@@ -22,6 +22,9 @@
 
   WRITERS, in order:
     • specify (first run in this context) — creates it and models the first aggregate(s).
+    • specify (a later feature's first run) and adopt — rewrite it to add that feature's
+      aggregate(s). A script checks each rewrite against the file as it was and puts it back
+      if an aggregate section, a BR-/XBR- rule or a ledger entry was lost.
     • specify (later runs) — writes specs/[Context]/domain-model.<CR-id>.delta.md instead;
       the master is untouched while a change is open.
     • finalize-delta — merges a delta into this file, ONE `## Aggregate:` SECTION AT A TIME.

package/assets/.appweaver/templates/ui-delta-design-template.md

@@ -10,7 +10,7 @@
 
 **Delta spec**: `changes/[CR-ID]/delta-spec.md`
 
-**Service delta**: `changes/[CR-ID]/delta-backend-plan.md`   <!-- "none — experience-only change" when this change has no service half -->
+**API delta**: `changes/[CR-ID]/delta-api-plan.md`   <!-- "none — the change leaves the API unchanged" when it has no API half -->
 
 <!--
   ONE CHANGE'S PLAN FOR THE FRONTEND LANE. It applies to the feature's master plan at
@@ -33,7 +33,9 @@
   EXPERIENCE does with it.
 
   THE LANE BOUNDARY IS THE PUBLISHED SURFACE. Bind against the delta-spec's IC- ids and
-  the service delta's "Contract deltas for the frontend lane" table — CITE those
+  the change's API delta (delta-api-plan.md) — its Contract deltas table and the endpoint
+  blocks under it — and, for an endpoint the change leaves alone, the feature's
+  api-plan.md. CITE those
   contracts, never re-derive or contradict them, and introduce no server-side behaviour,
   persistence assumption or handler detail. Anything the experience needs that the surface
   does not offer is a CONTRACT DELTA raised back to the service lane, never a workaround
@@ -108,15 +110,15 @@ CN-/DC-/IC-) it realises. "Realisation only — no spec delta" for a plan-only c
 ## Contract impact
 
 <!--
-  What this change consumes from the service lane, taken from the service delta's
-  contract table: bindings added, changed, or no longer used. Anything the experience
+  What this change consumes from the service lane, taken from the API delta's
+  Contract deltas table: bindings added, changed, or no longer used. Anything the experience
   requires that the surface does not offer goes under "Contract deltas needed" and is
   raised back to the service lane. `None` when the binding surface is unchanged.
 -->
 
 | Contract | Consumed as | From |
 |---|---|---|
-| `[VERB] [/route]` | [what the screen does with it] | service delta / IC-[nnn] |
+| `[VERB] [/route]` | [what the screen does with it] | API delta / IC-[nnn] |
 
 **Contract deltas needed**: [what the service must add for this experience to work] — or `None`
 
@@ -153,7 +155,8 @@ container or a navigation edge changed.]
 ## On merge
 
 `finalize-delta` merges the change's SPEC half into `spec.md` and its MODEL half into the
-context's `domain-model.md`, in one transaction, and leaves the change OPEN. It does NOT
-merge this document: the master plan is derived from those two, so it is re-derived rather
-than patched. `close-delta` archives this file with the change and bumps the ONE version both
+context's `domain-model.md`, in one transaction, merges its `delta-api-plan.md` into the
+feature's `api-plan.md` by script, and leaves the change OPEN. It does NOT merge this
+document: the master plan is derived from those three, so it is re-derived rather than
+patched. `close-delta` archives this file with the change and bumps the ONE version both
 lanes share. None of it is this document's job — it records the change, it does not apply it.

package/assets/.appweaver/templates/ui-design-template.md

@@ -192,11 +192,11 @@ a lost connection mid-flight.]
 
 <!-- THE LANE BOUNDARY. One row per service operation this feature's UI depends
      on. Bind against the service's PUBLISHED SURFACE — the spec's IC- ids and
-     the API contracts backend-plan.md states — and never against the service's
+     the endpoints api-plan.md states — and never against the service's
      internals: no table, no handler, no persistence assumption crosses this
      line. An interface the experience needs and the service does not offer is a
      CONTRACT DELTA raised back to the service lane, never a workaround in the
-     client. The OPERATION ID is the one backend-plan.md §3 gives the endpoint —
+     client. The OPERATION ID is the one api-plan.md gives the endpoint —
      the name implement finds it by in the API document, and checks before
      generating. A row that needs an operation the service does not publish yet
      cites the operation id its request below proposes, and names the RQ-n in
@@ -212,10 +212,10 @@ it invalidates, and how an optimistic update rolls back.]
 **Contract deltas needed**
 
 <!-- THE REQUEST LEDGER. One row per operation the experience needs that the
-     service's published surface does not offer — and, when there is no backend
+     service's published surface does not offer — and, when there is no API
      plan yet, one per binding. Each request keeps its RQ-n for life: never
      renumber or reuse one. Propose the operation id and the field shapes; the
-     backend plan answers in its "Requests from the frontend lane" table —
+     API plan answers in its "Requests from the frontend lane" table —
      published under an operation id, or declined with the reason. An answered
      request is re-bound in the table above to the id the backend gave it; a
      declined one is planned around, or routed to `specify` when the spec needs

package/assets/foundations/foundation.spec.template.txt

@@ -24,20 +24,26 @@
 #                Vue, SvelteKit and the Express backend alike)
 #   # title:     the label in the pick list
 #
-# Three more header lines carry the API CONTRACT between the lanes. /appweaver foundation
-# records them on the lane in .appweaver/stacks.json once the project is built, and
-# /appweaver implement uses them to export the service's OpenAPI document and generate the
-# frontend's client from it before it generates the frontend. A spec that leaves one out
-# is asked for it at the end of the build; leaving the answer empty keeps the stack
-# profile's default.
+# Four more header lines carry the API settings of the lanes. /appweaver foundation
+# records them on the lane in .appweaver/stacks.json once the project is built. The API
+# CONTRACT between the lanes is each feature's API plan (api-plan.md), which the frontend
+# binds to; a backend lane's settings say how its service's AS-BUILT document is had, so
+# /appweaver analyze-slice can check the API the code serves against the API plan. A spec
+# that gives neither backend way is asked for `contract-write` at the end of the build,
+# and one that gives no client is asked for it; an empty answer keeps the lane's value.
 #
-#   # contract-run:  (backend) the command that starts the API ON ITS OWN — no
+#   # contract-write: (backend) a command that WRITES the service's OpenAPI JSON to
+#                    {{contract}} with no server started — the stack's own generator, or
+#                    a script that loads the application and dumps its document. Run in
+#                    the lane root folder. Preferred: nothing of the service runs
+#   # contract-run:  (backend) or: the command that starts the API ON ITS OWN — no
 #                    orchestration host, nothing it needs that is not on this machine —
 #                    run in the lane root folder. <App> stands for the app name given
 #                    at /appweaver foundation
-#   # contract:      (backend) the URL that running API serves its OpenAPI document at
-#   # client:        (frontend) the command that generates the API client from that
-#                    document; {{contract}} in it stands for the document's path
+#   # contract:      (backend) with contract-run: the URL that running API serves its
+#                    OpenAPI document at
+#   # client:        (frontend) the command that generates the API client from an
+#                    OpenAPI document; {{contract}} in it stands for the document's path
 #
 # The header is the leading block of `#` lines; the first line that does not start with
 # `#` ends it. Everything after this header block is the spec itself, written for the
@@ -82,17 +88,18 @@ Settings files, environment variables, ports, connection strings (placeholders,
 secrets).
 
 ## API document
-Backend: the API serves its OpenAPI document at the `# contract:` URL, and the
-`# contract-run:` command starts it on its own on the port that URL names — over http, with
-every setting it needs to start present in its configuration (a local database file, not a
-container). Frontend: say which tool the `# client:` command runs, so it is installed as a
-development dependency.
+Backend: the `# contract-write:` command writes the API's OpenAPI document without starting
+a server — say which tool or script it runs, so it is part of the project. Or, with
+`# contract-run:` and `# contract:`, the API serves its document at that URL and the command
+starts it on its own on the port the URL names — over http, with every setting it needs to
+start present in its configuration (a local database file, not a container). Frontend: say
+which tool the `# client:` command runs, so it is installed as a development dependency.
 
 ## Tests
 The test project(s): framework, where they live (the lane's test path), and the one test that
 must pass on a fresh scaffold.
 
 ## Done when
-How to confirm the scaffold works — the lane's build passes, the test command passes, the app
-starts and answers a named URL (for a backend, the `# contract:` URL, started with the
-`# contract-run:` command).
+How to confirm the scaffold works — the lane's build passes, the test command passes, and for
+a backend its API document is written: by the `# contract-write:` command, or served at the
+`# contract:` URL once `# contract-run:` starts it.