aw-spec-cli 0.1.33 → 0.1.35

package/README.md

@@ -37,7 +37,6 @@ git clone https://dev.azure.com/bytestrone-labs/AppWeaver/_git/appweaver
 cd platform/Appweaver.Spec.Cli
 npm install
 npm run build
-# Then run via node
 dist/index.js init
 ```
 
@@ -53,18 +52,12 @@ aw-spec init
 
 # Or specify a target directory
 aw-spec init my-project
-
-# Non-interactive (uses Claude skills by default)
-aw-spec init -y
-
-# Choose agent explicitly
-aw-spec init --agent antigravity
-aw-spec init --agent kilocode
-
-# Preview what would be copied (no changes)
-aw-spec init --dry-run
 ```
 
+The interactive wizard prompts you to choose:
+- **Project Scaffolding**: Unpacks clean enterprise starter code (Java Spring Boot Hexagonal, .NET WebApi Vertical Slice, or Modular Monolith) without agent folders.
+- **Spec Workflow Setup**: Installs `.aw-spec/` pipelines and AI agent skills (Claude Code, Antigravity, Cursor, KiloCode).
+
 After initialization:
 
 ```bash
@@ -81,39 +74,20 @@ aw-spec specify "Your feature description"
 
 ### `aw-spec init [directory]`
 
-Initialize a new AppWeaver Spec project.
+Initialize an AppWeaver project: Project Scaffolding or Spec Workflow Setup.
 
 | Option | Description |
 |--------|-------------|
-| `directory` | Target directory (default: current directory) |
-| `-a, --agent <agent>` | Agent skills to include: `claude`, `antigravity`, `kilocode` (default: prompt) |
-| `-y, --yes` | Skip prompts, use defaults (Claude) |
-| `--dry-run` | Show what would be copied without making changes |
-
-**Copied structure:**
-```
-target-dir/
-├── .aw-spec/              # Core spec configuration
-│   ├── extensions.yml     # Extension registry
-│   ├── feature.json       # Feature tracking
-│   ├── workflows/         # Workflow definitions
-│   ├── templates/         # Spec/plan/task templates
-│   └── scripts/           # Bash/PowerShell helpers
-├── docs/                  # Documentation scaffold
-│   ├── architecture/
-│   ├── domain/
-│   ├── governance/
-│   ├── security/
-│   ├── domainspecs/
-│   ├── glossary/
-│   ├── VerticalSlice/     # Vertical slice packaging
-│   └── ...
-└── .claude/skills/        # Or .agents/skills/, .kilocode/
-    ├── aw-spec-specify/
-    ├── aw-spec-plan/
-    ├── aw-spec-implement/
-    └── ... (13 skills total)
-```
+| `[directory]` | Target directory (default: current directory `.`) |
+| `-i, --intent <intent>` | Action intent: `scaffolding` (Project Scaffolding) or `spec` (Spec Workflow Setup) |
+| `-b, --backend <stack>` | Backend stack: `java-spring`, `dotnet-webapi`, or `none` |
+| `-f, --frontend <stack>` | Frontend stack: `nextjs`, `react-vite`, or `none` |
+| `--foundation <type>` | Foundation type: `hexagonal`, `vertical-slice`, `modular-monolith` |
+| `--app-name <name>` | Application name for scaffolding |
+| `--package <package>` | Root package or namespace |
+| `-a, --agent <agent>` | Agent skills (for spec workflow): `claude`, `antigravity`, `kilocode`, `cursor`, etc. |
+| `-y, --yes` | Skip prompts and use defaults |
+| `--dry-run` | Show what would be created without making changes |
 
 ### `aw-spec doctor`
 
@@ -152,62 +126,83 @@ Choose based on your AI assistant. Skills provide guided workflows for spec-driv
 
 ## Project Structure (After Init)
 
+The resulting structure depends on the chosen intent:
+
+### Option A: Project Scaffolding (Clean Application Code)
+
+When choosing **Project Scaffolding**, the foundation unpacks directly into your project root. No `.aw-spec/` or AI agent folders are added, keeping the codebase completely clean and standard.
+
+**Example: Java Spring Boot — Hexagonal Architecture (`hexagonal`):**
 ```
 my-project/
-├── .aw-spec/
-│   ├── extensions.yml
-│   ├── feature.json
-│   ├── init-options.json
-│   ├── integration.json
+├── src/
+│   ├── main/
+│   │   ├── java/com/mycompany/order/
+│   │   │   ├── domain/               # Enterprise domain models & business rules
+│   │   │   ├── application/          # Use cases, inbound/outbound ports
+│   │   │   └── infrastructure/       # Adapters: Web REST controllers, DB repositories
+│   │   └── resources/
+│   │       └── application.yml
+│   └── test/
+├── pom.xml
+├── mvnw / mvnw.cmd
+└── README.md
+```
+
+**Example: .NET WebApi — Vertical Slice Architecture (`vertical-slice`):**
+```
+my-project/
+├── src/
+│   └── OrderService/
+│       ├── Features/                 # Self-contained vertical slices (Commands, Queries, Endpoints)
+│       │   └── Orders/
+│       │       ├── CreateOrder/
+│       │       └── GetOrderById/
+│       ├── Common/                   # Cross-cutting concerns & behaviors
+│       ├── Program.cs
+│       └── OrderService.csproj
+├── OrderService.sln
+└── README.md
+```
+
+---
+
+### Option B: Spec Workflow Setup (AI Agent Skills & Orchestration)
+
+When choosing **Spec Workflow Setup**, the CLI installs the spec-driven development orchestration files and selected AI agent skills:
+
+```
+my-project/
+├── .aw-spec/                         # Core spec configuration
+│   ├── extensions.yml                # Extension registry
+│   ├── feature.json                  # Feature tracking
+│   ├── init-options.json             # Stored setup configuration
+│   ├── integration.json              # Integration settings
 │   ├── workflows/
-│   │   └── workflow-registry.json
+│   │   └── workflow-registry.json    # Workflow pipeline definitions
 │   ├── extensions/
 │   │   └── agent-context/
-│   │       ├── scripts/
-│   │       └── commands/
-│   ├── templates/
+│   ├── templates/                    # Spec, plan, and task templates
 │   │   ├── spec-template.md
 │   │   ├── plan-template.md
 │   │   └── tasks-template.md
-│   ├── scripts/
-│   │   └── bash/
-│   │       └── common.sh
-│   ├── integrations/
+│   ├── scripts/                      # Automation & validation scripts
 │   └── memory/
-├── docs/
+├── docs/                             # Architecture & governance reference docs
 │   ├── architecture/
 │   ├── domain/
 │   ├── governance/
 │   ├── security/
-│   ├── domainspecs/
-│   ├── glossary/
-│   ├── interop/
-│   ├── ModularMonolith/
-│   ├── VerticalSlice/
-│   │   ├── VerticalSlice.pack.txt
-│   │   ├── PACKAGING.md
-│   │   ├── pack-foundation.sh
-│   │   └── unpack-foundation.sh
-│   ├── command.txt
-│   ├── components/
-│   ├── pharma-constitution.my-ref.md
-│   ├── requirement-spec.txt
-│   ├── technology-constitution.md
-│   └── README.md
-└── .claude/skills/          # Or .agents/skills/, .kilocode/
-    ├── aw-spec-addcomponent/
-    ├── aw-spec-agent-context-update/
-    ├── aw-spec-analyze/
+│   └── ...
+└── .agents/skills/                   # Or .claude/skills/, .kilocode/
+    ├── aw-spec-specify/
+    ├── aw-spec-plan/
+    ├── aw-spec-implement/
+    ├── aw-spec-tasks/
     ├── aw-spec-checklist/
     ├── aw-spec-clarify/
-    ├── aw-spec-constitution/
     ├── aw-spec-foundation/
-    ├── aw-spec-implement/
-    ├── aw-spec-plan/
-    ├── aw-spec-select-domain/
-    ├── aw-spec-specify/
-    ├── aw-spec-tasks/
-    └── aw-spec-taskstoissues/
+    └── ... (13 skills total)
 ```
 
 ---

package/assets/.appweaver/DESIGN-FORMAT.md

@@ -16,6 +16,7 @@ specs/<Context>/
   domain-model.md        # STRUCTURE — aggregates, entities, invariants (BR-nnn) — shared
   <Aggregate>/
     spec.md              # BEHAVIOUR (tech-agnostic) — WHAT / WHY
+    api-plan.md          # the API CONTRACT — the endpoints the service publishes
     backend-plan.md      # structure & decisions (tech-agnostic HLD) — the MEDIATOR
     changes/             # open + archived change records (delta-spec + delta plans)
 ```
@@ -38,8 +39,10 @@ FR/US/SC/CN/DC/IC
 
 - **One design per feature.** The four clean-architecture layers (Domain,
   Application, API, Infrastructure) are **sections** of this one document, each at
-  design level. A feature is a capability scope the developer chooses — it may act on
-  several aggregates, and several features may act on one; its operations are user
+  design level — except the endpoints themselves, which are in `api-plan.md` (see
+  *The API plan* below); §3 points there. A feature is a capability scope the
+  developer chooses — it may act on several aggregates, and several features may act
+  on one; its operations are user
   stories inside it. *(This is
   the **greenfield** layout, authored from `design-template.md`. See the Brownfield
   variant below for reverse-engineered / existing-codebase designs.)*
@@ -67,6 +70,37 @@ FR/US/SC/CN/DC/IC
   applied in the `implement` phase. `backend-plan.md` stays feature-specific and
   technology-agnostic.
 
+## The API plan (`api-plan.md`)
+
+The endpoints a feature's service publishes — route, verb, operation id, request and
+response shapes, the error contract — and its answers to the frontend lane's requests are
+**one document of their own**, `api-plan.md`, beside the backend plan. It is the API
+contract between the lanes: the frontend plan binds to its operation ids, `implement`
+serves it, and `contract-draft` writes `api-draft.json` from it by script. The backend plan
+realises each endpoint as a use-case and names it under the endpoint's **Maps to**.
+
+- **A master, like `spec.md`.** A change plans its API in
+  `changes/<CR-id>/delta-api-plan.md` — a Contract deltas table (one row per endpoint
+  `added`, `changed` or `removed`), each added or changed endpoint written whole, and the
+  requests the change answers — and `finalize-delta` merges it into `api-plan.md` by script
+  (`contract-merge`), by whole endpoint block keyed by operation id. The backend plan is
+  derived and never merged; the API plan is merged, so what a change adds or changes is in
+  the document every redraw reads from the moment the change is merged.
+- **One form in every project.** Each endpoint is a block under `## Endpoints`: the heading
+  `### `VERB /route`` and its fields, every shape `{ field: type }`. The contract scripts
+  read exactly that form, so it is the kit's template (`api-plan-template.md`,
+  `delta-api-plan-template.md`) in greenfield and brownfield repos alike; an override
+  generated by `onboard` shapes the backend plan, never the API plan.
+- **Operation ids are stable.** An endpoint keeps its id for life; a new one takes an id
+  unique across the service. An endpoint the code already serves keeps the id the code
+  publishes, and one it serves under no id writes `—`, never an invented id.
+- **Authored first.** `plan` writes the API plan before the backend plan on both paths —
+  the master, and a change's delta — so the contract is fixed before what realises it.
+- **Features planned before it** keep their endpoints in the backend plan's API section,
+  which every reader falls back to while no `api-plan.md` exists. A re-derivation
+  (`plan main`) offers to move them once, by script (`api-split`), and `finalize-delta`
+  moves them when it first merges a change's API into the feature.
+
 ## Brownfield variant (existing codebases)
 
 A design reverse-engineered from — or added forward to — an **existing** codebase is
@@ -82,18 +116,14 @@ same traceability spine and the two deferral ledgers — with **one difference t
   are **derived from the code's own organisation** (its folders / projects / modules)
   rather than the fixed Domain/Application/API/Infrastructure four. A component the
   code has that fits no textbook layer (a UI tier, a worker, a host project) gets its
-  own section; a layer the code lacks does not appear. Three neutral anchors are kept
+  own section; a layer the code lacks does not appear. Two neutral anchors are kept
   because every system has them and the tooling keys on them: **§1 is the domain/data
-  model** (the cross-reference tool reads it for `<Other>Id` reference edges), one
+  model** (the cross-reference tool reads it for `<Other>Id` reference edges), and one
   **§2 subsection is the External Integrations table** (matched by heading keyword, so
-  `aw-xref` extracts contract edges from either layout), and **each published endpoint
-  is an endpoint block** — the greenfield §3 form, `#### `VERB /route`` with its
-  **Operation id**, followed by the "Requests from the frontend lane" table — inside
-  whichever §2 axis publishes it. The contract scripts read exactly that form: the API
-  draft is written from the headings, and the request ledger between the two lanes reads
-  the operation ids and the table. An endpoint the code already serves keeps the id it
-  publishes; where it publishes none the plan writes `—` and records a §5 assumption,
-  never an invented id. The `debt` ledger records
+  `aw-xref` extracts contract edges from either layout). The published endpoints are not
+  in the plan at all: they are in the feature's `api-plan.md`, whose form is the same in
+  every project (see *The API plan* above), and the §2 axis that publishes them ends with
+  a line pointing there. The `debt` ledger records
   only debt the **code itself** evidences (stubs, dead code, torn seams) — being
   organised unlike a reference architecture is **not** debt, it is the as-built shape;
   migrating toward a target is a separate modernization decision.
@@ -129,7 +159,7 @@ states it can be in, and the framework binds in the FRONTEND LANE of `implement`
 
 **§5 Contract Binding is the lane boundary.** The UI design reads the whole spec — the
 experience is stated there — but only the service's **published surface**: the spec's `IC-`
-ids and the API contracts `backend-plan.md` states. No table, handler or persistence choice
+ids and the endpoints `api-plan.md` states. No table, handler or persistence choice
 crosses that line, and an operation the experience needs that the surface does not offer is
 a contract delta raised back to the service lane, never a client workaround. ⌛ `design`
 will emit that surface as a `design-contract.md` projection; the rule does not change when
@@ -138,11 +168,11 @@ it does, only what §5 reads.
 **Contract deltas are a request ledger between the two plans.** frontend-plan.md §5 "Contract
 deltas needed" is a table, one `RQ-n` per operation the experience needs and the surface does
 not offer, with the operation id and field shapes it proposes; a request keeps its id for
-life. backend-plan.md §3 answers each in its "Requests from the frontend lane" table —
+life. api-plan.md answers each in its "Requests from the frontend lane" table —
 `published` under an operation id, or `declined` with the reason — so each lane's developer
-writes only their own plan. `contract-requests` reads both: an open request is a backend-lane
+writes only their own plans. `contract-requests` reads both: an open request is a backend-lane
 gap at `analyze-plan`, a declined one or an answered one not yet re-bound is a frontend-lane
-gap. With no backend plan at all, every binding is a request.
+gap. With no API plan at all, every binding is a request.
 
 **`UX-` lives here and only here.** The service design excludes the spec's Experience
 Standards by contract — it realises no experience standard, and a traceability row for one
@@ -198,16 +228,18 @@ backend-plan.md:
 
 - `CreateOrder` = US-1; `UpdateOrder` = US-2.
 - Adding `UpdateOrder` is an additive CR: a **delta-spec** (`+US-2`), the change's own
-  **model delta** where the domain moves, and **delta lane plans** (`ADDED` new
-  use-case/endpoint sections, `MODIFIED` the shared Order/root and repository sections —
-  see `delta-design-template.md`). All three live inside `changes/<CR-id>/`, and the
-  MASTERS are not touched while the change is open: `plan` writes
-  `delta-backend-plan.md` / `delta-frontend-plan.md` beside the delta-spec, never
-  `backend-plan.md`. `implement` generates only what the delta marks ADDED or MODIFIED;
-  regression re-tests the shared-file dependents.
+  **model delta** where the domain moves, a **delta API plan** (the `UpdateOrder` endpoint,
+  `added` — see `delta-api-plan-template.md`) and **delta lane plans** (`ADDED` the new
+  use-case, `MODIFIED` the shared Order/root and repository sections — see
+  `delta-design-template.md`). All of them live inside `changes/<CR-id>/`, and the
+  MASTERS are not touched while the change is open: `plan` writes `delta-api-plan.md`,
+  `delta-backend-plan.md` and `delta-frontend-plan.md` beside the delta-spec, never
+  `api-plan.md` or `backend-plan.md`. `implement` generates only what the delta marks
+  ADDED or MODIFIED; regression re-tests the shared-file dependents.
 - **Nothing in the plan phase bumps a version or archives a change.** `finalize-delta`
-  MERGES the delta into `spec.md` and the context's `domain-model.md` (not the lane
-  plans — they are derived from those two and are re-derived by `/appweaver plan main`),
+  MERGES the delta into `spec.md`, the context's `domain-model.md` and `api-plan.md` (not
+  the lane plans — they are derived from those three and are re-derived by
+  `/appweaver plan main`),
   and `close-delta` is the sole stage that archives `changes/<CR-id>/` and moves the
   version (`v1.0 → v1.1`). The two are deliberately separate so a red `analyze-slice`
   between them is still "fix and re-run" rather than a change that already shipped.

package/assets/.appweaver/STACK-PROFILES.md

@@ -56,9 +56,10 @@ no heading to key on. Where the two lanes are folded into one command, as `plan`
 | `run_from` | *(optional)* **where the commands run**: `repo` (the default, and the shape of every lane written before this key existed) at the repository root, or `root` inside the lane root folder. `select-stack` decides it from where the stack's build file sits — see §3.1 |
 | `build` / `test` / `run` | project-supplied command strings the engine shells out to. These are the matched **profile's** defaults and may not fit a legacy layout — reviewing them is what `select-stack` is for. `{{root}}` in a command resolves to this lane's `root`, as seen from where the command runs (§4.2) |
 | `migrate` | *(optional)* the lane's schema-migration command, recorded only when the profile declares one. Absent, `run-migrate` falls back to `dotnet ef` and otherwise reports that nothing ran (§4.2) |
-| `contract_run` | *(optional, backend)* the command that starts the service on its own so `implement` can export its API document (§4.5). Absent, the profile's is used. `foundation` sets it from a pack's `<pack>.lane.json` |
-| `contract` | *(optional, backend)* the URL the running service serves its API document at (§4.5). Absent, the profile's is used |
-| `client` | *(optional, frontend)* the command that generates the frontend's API client from that document; `{{contract}}` in it is the document's path. No shipped profile has one: `implement` asks the developer the first time and records the answer here (§4.5) |
+| `contract_write` | *(optional, backend)* a command that writes the service's as-built API document to `{{contract}}` with no server started, which `analyze-slice` runs to check the API the code serves against the plan (§4.5). `foundation` sets it from a pack's `<pack>.lane.json` or a spec's header, or asks for it on the spec route |
+| `contract_run` | *(optional, backend)* or: the command that starts the service on its own so its document can be fetched (§4.5). `foundation` sets it from a pack's `<pack>.lane.json` or a spec's header |
+| `contract` | *(optional, backend)* with `contract_run`: the URL the running service serves its API document at (§4.5) |
+| `client` | *(optional, frontend)* the command that generates the frontend's API client from the API document; `{{contract}}` in it is the document's path. No shipped profile has one: `implement` asks the developer the first time and records the answer here (§4.5) |
 
 ### Three properties matter more than the schema
 
@@ -218,11 +219,11 @@ behaviour from before the file existed.
 
 | Phase | With a working lane narrower than the declared lanes |
 |---|---|
-| `plan` | scaffolds, authors, re-derives and delta-plans only the working lane; the menu and the re-derive question look only at its master. The other lane's plan is read — the frontend plan binds to the backend plan's published surface. The backend half answers the frontend's open contract requests and writes `api-draft.json`; the frontend half re-binds answered requests and raises new ones (§4.5) |
-| `analyze-plan` | gates, repairs and receipts only the working lane's plan (`.aw-plan-gate.<lane>.json`, that lane's verdict); check 3 reads the other plan and the request ledger, and a finding only it can close is reported for its developer (`plan-gaps --lanes` → `other`). The frontend receipt also hashes the backend plan's §3, so a backend contract change re-gates the frontend |
-| `implement` | offers, receipt-checks and generates only the working lane; a refused receipt skips that lane with the reason. The backend half exports the API document; the frontend half reads it, combined with the drafts, and never starts the service (§4.5) |
-| `build` | compiles only the working lane (`build-compile --kind`); `lane-verify --working-only` does not require the other lane's root on disk. With the backend worked, a green compile re-exports the API document |
-| `analyze-slice` | tests only the working lane (`test-run --kind`); the fix loops' file list is narrowed with `concept-paths --under`; the composition pass runs when the backend is worked |
+| `plan` | scaffolds, authors, re-derives and delta-plans only the working lane; the menu and the re-derive question look only at its master. The frontend plan binds to the API plan (`api-plan.md`), the backend lane's published surface, and never reads the backend plan. The backend half writes the API plan first — answering the frontend's open contract requests there — and `api-draft.json` from it; the frontend half re-binds answered requests and raises new ones (§4.5) |
+| `analyze-plan` | gates, repairs and receipts only the working lane's documents (`.aw-plan-gate.<lane>.json`, that lane's verdict; the backend's covers `api-plan.md` too); check 3 reads the API plan, the frontend plan and the request ledger, and a finding only the other lane can close is reported for its developer (`plan-gaps --lanes` → `other`). The frontend receipt also hashes `api-plan.md`, so a contract change re-gates the frontend |
+| `implement` | offers, receipt-checks and generates only the working lane; a refused receipt skips that lane with the reason. The backend half serves every endpoint of `api-plan.md` as written; the frontend half binds to the features' drafts, combined, and never starts the service (§4.5) |
+| `build` | compiles only the working lane (`build-compile --kind`); `lane-verify --working-only` does not require the other lane's root on disk |
+| `analyze-slice` | tests only the working lane (`test-run --kind`); the fix loops' file list is narrowed with `concept-paths --under`; the composition pass and the API check — the built service against the API plan (§4.5) — run when the backend is worked |
 | `specify`, `finalize-delta`, `close-delta` | **ignore it** — the spec is written whole, and a change merges and closes with whatever its lanes delivered |
 
 **A change records the lanes it touches**, separately from anyone's working lane: the
@@ -292,9 +293,11 @@ workflow.**
   "host_patterns": [],                       // optional — where the runnable project sits, for
                                              // `{{host}}` in a command — see §4.2
   "migrate": "",                             // optional — schema migration, if the stack has one
-  "contract_run": "",                        // optional, backend — start the service to export
-                                             // its API document — see §4.5
-  "contract": "",                            // optional, backend — the URL it serves it at
+  "contract_write": "",                      // optional, backend — write the as-built API
+                                             // document to {{contract}} — see §4.5
+  "contract_run": "",                        // optional, backend — or start the service to
+                                             // fetch it …
+  "contract": "",                            // … from this URL
   "client": "",                              // optional, frontend — generate the API client
                                              // from `{{contract}}` — see §4.5
   "prototype_run": "npm run dev --prefix prototype",   // frontend only — fills the prototype block
@@ -514,53 +517,78 @@ A layout the table gets wrong is fixed by writing `test_root` on the lane in `st
 | `go-chi` | `backend/` | *(inside the lane root folder)* | `internal/` | — |
 | every frontend | `frontend/` | *(inside the lane root folder)* | `web/` | — |
 
-### 4.5 `contract_run`, `contract` and `client` — the API contract between the lanes
-
-The frontend lane binds to the service through the service's published API document, and
-the document that counts is the one the **built code** serves. **The backend lane publishes
-it and the frontend lane reads it**, so the two can be built by different developers at
-different times, and a frontend developer never needs the service's code built or its
-runtime installed. Every step warns rather than stops:
-
-1. **Export** (`contract-export`) — run by whoever works on the service lane: `implement`
-   after its backend half generates, and `build` after a green compile. Start the service
-   with the backend lane's `contract_run`, fetch its `contract` URL, write the document to
-   `<service lane root folder>/contracts/openapi.json`, and stop the service with
-   everything it started. A service already answering at the URL is used as it is, and
-   the run says it may be older than the code. The document is committed with the service.
-2. **Draft** (`contract-draft`) — run by the backend lane's `plan` and `analyze-plan`:
-   `backend-plan.md` §3 drafted by script into `specs/<ctx>/<feature>/api-draft.json`, an
-   OpenAPI document of what the plan says the service will serve. Committed with the plan.
-3. **Combine** (`contract-combine`) — run by the frontend half of `implement`: the exported
-   document plus every drafted operation it does not serve yet, each marked `x-aw-draft`,
-   written to `.appweaver/contracts/openapi.combined.json` (not committed). A drafted
-   operation whose id the service serves drops out; one whose route and verb the service
-   answers under another id is left out and reported.
-4. **Client** (`contract-client --doc`) — run the frontend lane's `client` command, with
+### 4.5 `contract_write`, `contract_run`, `contract` and `client` — the API between the lanes
+
+**The contract between the lanes is the API plan.** Each feature's `api-plan.md`, beside its
+backend plan, states the endpoints the service publishes — route, verb, operation id, field
+shapes, errors — in one form in every project, so the scripts read it the same way on every stack.
+The frontend lane binds to those endpoints, drafted from the API plan by script, and the built
+service is checked against that document rather than read from. So the frontend works the same on
+every stack and in a brownfield repo, can be built before the backend is, and never needs the
+service's code built, started or its runtime installed. The API plan is a master: a change plans
+its API in `changes/<CR-id>/delta-api-plan.md`, and `finalize-delta` merges it in by script. A
+feature planned before API plans existed keeps its endpoints in its backend plan's API section,
+which every step below reads instead until `api-split` moves them out. Every step warns rather
+than stops, except the backend gates' check and the merge:
+
+1. **Draft** (`contract-draft`) — run by the backend lane's `plan` and `analyze-plan`, and by
+   `adopt`: `api-plan.md` drafted by script into `specs/<ctx>/<feature>/api-draft.json`.
+   Committed with the plan. A shape not written as `{ field: type }` is reported, since the
+   frontend's client gets it untyped, and so is an operation the previous draft had and this one
+   does not.
+2. **Draft a change** (`contract-draft --cr`) — run by `plan` and `analyze-plan-delta` on a
+   change: the endpoints its `delta-api-plan.md` adds or changes, written as full blocks, and the
+   ones it removes, into `changes/<CR-id>/api-draft.json`.
+3. **Merge** (`contract-merge`) — run by `finalize-delta`: the change's delta API plan merged
+   into `api-plan.md` by whole endpoint block, keyed by operation id, with the requests it
+   answers; `api-draft.json` is redrawn from the result. A run that does not answer stops
+   `finalize-delta` with the command that finishes it, and `close-delta` will not archive a
+   change whose API delta `api-plan.md` has not recorded (`contract-merge --check`).
+4. **Combine** (`contract-combine`) — run by the frontend half of `implement`: every feature's
+   draft with each open change's applied over it, written to
+   `.appweaver/contracts/openapi.combined.json` (not committed). An operation an open change
+   removes stays, marked `deprecated` with the change that removes it, so a frontend still bound
+   to it is told rather than broken. Where an open change serves another operation on its
+   route, that one takes the route, and the removed one moves to the document's `x-aw-removed`
+   list with its route and change, so a binding to it is still reported as removed.
+5. **Client** (`contract-client --doc`) — run the frontend lane's `client` command, with
    `{{contract}}` standing for the combined document as seen from where the command runs.
-5. **Check** (`contract-check`) — every operation id the frontend plan cites must be an
-   `operationId` in the combined document; the ids that are only drafts are named apart.
+6. **Check** (`contract-check`) — every operation id the frontend plan cites must be an
+   `operationId` in the combined document; the ids an open change removes, and those the
+   service does not serve yet, are named apart.
+7. **Verify** (`contract-export` + `contract-verify`) — run by the backend gates: after its fix
+   loops `analyze-slice` writes the service's AS-BUILT document to
+   `<service lane root folder>/contracts/openapi.json` and compares it with the feature's draft
+   (plus a change merged and not yet closed); `analyze-slice-delta` does it for the change's own
+   draft. A planned endpoint not served, or served under another route, verb or operation id,
+   fails the gate; a field or status code that differs warns. A feature whose plan names no
+   endpoint, or a change that drafts no API change, is not checked and the lane's export is
+   not run (`contract-verify --check` asks first). Committed, the as-built document
+   also adds the operations no plan describes to the frontend's combined document, marked
+   `x-aw-unplanned` — the endpoints of a brownfield feature nobody has adopted yet.
 
 Between the plans, what the frontend needs and the backend does not publish travels as a
 **request ledger**: `frontend-plan.md` §5 "Contract deltas needed" holds one `RQ-n` per
-request, and `backend-plan.md` §3 "Requests from the frontend lane" answers each —
+request, and `api-plan.md` "Requests from the frontend lane" answers each —
 published under an operation id, or declined. `contract-requests` reads both (§6).
 
-Each key is read from the lane first and from its profile second, so a lane declared
-before the keys existed still answers them. Where the values come from:
+**How the as-built document is written is the lane's setting**, because only the project knows
+it, and a lane that sets none is simply not checked:
 
-| Key | Profile default | Set on the lane by |
+| Key | What it is | Set on the lane by |
 |---|---|---|
-| `contract_run` | `dotnet-webapi`: `dotnet run --project {{host}} -- --environment Development --urls http://localhost:5000`<br>`java-spring`: `./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8080` | `foundation`: on the pack route from the pack's `<pack>.lane.json` — the shipped .NET packs start their API project alone (the AppHost needs Docker), the Java `Hexagonal` pack its one Maven module; on the spec route from the spec's `# contract-run:` header line, or the operator's answer when it has none |
-| `contract` | `dotnet-webapi`: `http://localhost:5000/swagger/v1/swagger.json`<br>`java-spring`: `http://localhost:8080/v3/api-docs` (springdoc's default path) | `foundation`, the same way — the `# contract:` header line on the spec route |
-| `client` | none — no generator is assumed | `foundation` on the spec route, from the `# client:` header line or the operator's answer; else `implement`, which asks the first time and records the answer |
+| `contract_write` | 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 (a FastAPI app's `app.openapi()`, for instance). Preferred: nothing of the service runs. It writes to a scratch path, and only a document that reads as OpenAPI replaces the committed one | `foundation`: from the pack's `<pack>.lane.json`; on the spec route from the spec's `# contract-write:` header line, or the operator's answer when the header gives no way |
+| `contract_run` + `contract` | start the service on its own, fetch its document from the URL, stop it and everything it started. For a stack that can only serve its document; a service already answering at the URL is used, and said to maybe be older than the code. Starting a service runs its startup code — the shipped .NET packs migrate a local SQLite file | `foundation`: from the pack's `<pack>.lane.json` (the shipped packs set these), or the spec's `# contract-run:` / `# contract:` header lines |
+| `client` | the frontend's client generator | `foundation` on the spec route, from the `# client:` header line or the operator's answer; else `implement`, which asks the first time and records the answer |
 
-On the spec route an empty answer keeps the lane's current value, so a lane nobody set
-anything on stays on the profile's default. `foundations/foundation.spec.template.txt`
-shows the three header lines; `<App>` in them is the app name given at `foundation`.
+No stack profile sets a way to write the document: starting a service runs whatever its
+configuration points at, so the kit never does it unless the project says so. Each key is still
+read from the lane first and from its profile second, so a project's own profile may carry one.
+`foundations/foundation.spec.template.txt` shows the header lines; `<App>` in them is the app name
+given at `foundation`.
 
 `--environment Development` matters for the .NET packs: outside Development they redirect
-to HTTPS, and the export fetches over http. Their API projects also read
+to HTTPS, and `contract-export` fetches over http. Their API projects also read
 `ConnectionStrings:SqliteConnection` when started without the AppHost, and the packs'
 configuration carries none, so their commands pass one. A pack's `<pack>.lane.json` sits
 beside its `.pack.txt`, names the pack's sentinel the way its files do, and is renamed with
@@ -584,10 +612,10 @@ grep -rl "lane-declare" .appweaver/orchestrator/workflows/   # must print exactl
 #   aw-spec-select-stack.orch.yaml   — a person picks
 ```
 
-**`lane-set` changes three keys on a lane that is already there, and nothing else** —
-`contract_run`, `contract` and `client` (§4.5). Its callers are `foundation`, recording
-what a pack knows about starting its service, and `implement`, recording the client
-command a developer types. They cannot use `lane-declare`, which rebuilds the whole lane
+**`lane-set` changes four keys on a lane that is already there, and nothing else** —
+`contract_write`, `contract_run`, `contract` and `client` (§4.5). Its callers are
+`foundation`, recording what a pack or a spec knows about writing its service's API
+document, and `implement`, recording the client command a developer types. They cannot use `lane-declare`, which rebuilds the whole lane
 and would reset every command on it to the profile's default.
 
 `onboard` used to be a second caller. Before `select-stack` was the first command of the
@@ -689,15 +717,19 @@ implementation and the twins cannot drift.
 |---|---|
 | `stack-list [--kind k] [--preselect text] [--include-none] [--suggest]` | enumerate the installed profiles; returns `select_options[]`, and `preselect` when the text names one of *this kind's* ids. `--suggest` also runs detection, so the menu **leads with** the stack this repo's files point at and `root_options[]` leads with the directory the evidence sits in |
 | `stack-detect [--kind k] [--exclude-root p]…` | match the repo's OWN files against the installed profiles — the brownfield candidate list, since an existing repo already answered the question. Writes nothing. `--exclude-root` keeps a service profile from relocating onto a subtree another lane owns |
+| `stack-rules --kind k [--declared]` | for each profile of the kind, how many of the files the active project's `tech-rule-bindings.md` names under `guardrails/technology/{{<kind>_stack}}/` exist with that profile put in, resolved with `resolve-tech`'s placeholder table: `complete`, `partial`, `none`, or `not-mapped` when the map names no stack folder for the lane. `note` is the line `select-stack` puts in the menu; `--declared` adds the declared lane's verdict, `ok`, and the `warning` `select-stack` raises when it is partial or none. Read-only (§7) |
 | `lane-declare --profile <id\|label\|none\|detected> [--kind k] [--id lane] [--source-path\|--root p] [--stack label] [--origin declared\|reverse-engineered] [--build/--test/--run/--migrate c] [--run-from repo\|root] [--no-prototype] [--require-existing-root]` | upsert a WHOLE lane — its one caller is `select-stack` (§5). `detected` declares a stack the kit ships no profile for (needs `--stack` and a lane root folder), which is how a legacy WebForms, JSP or ERB lane gets recorded at all |
-| `lane-set (--id lane\|--kind k) [--set KEY=VALUE]… [--unset KEY]…` | change only `contract_run`, `contract` or `client` on a lane already declared, leaving the rest of it alone. An empty VALUE changes nothing; `--unset` puts the key back on the profile's value. Called by `foundation` (a pack's lane settings) and `implement` (the client command a developer supplies) — re-declaring would reset every other command |
-| `contract-export [--timeout s]` | start the service lane with `contract_run`, fetch `contract`, save it to `<service root>/contracts/openapi.json`, stop the service and everything it started. A service already answering at the URL is used as it is, and said so (§4.5) |
-| `contract-draft --feature-dir p` | draft `api-draft.json` beside the feature's plans from `backend-plan.md`'s API section, by script: each `### \`VERB /route\`` endpoint with its operation id, request and response field shapes (conceptual types → JSON schema, a use case's DTO standing in for a named shape) and error statuses. Rewritten only when it differs; removed when the plan names no endpoint (§4.5) |
-| `contract-combine` | write `.appweaver/contracts/openapi.combined.json`: the exported document plus every feature's drafted operations it does not serve, marked `x-aw-draft`. `ok:false` with a reason when there is neither (§4.5) |
-| `contract-requests --feature-dir p` | the request ledger: the frontend plan's `RQ-n` rows against the backend plan's answers — `open`, `published` (and whether the frontend still has to re-bind), `declined` — with one line per lane's to-do for a prompt to quote |
-| `contract-client [--doc d]` | `run-phase --phase client` for the frontend lane — its `client` command, `{{contract}}` expanded to `--doc` (`implement` passes the combined document), else to the exported one |
-| `contract-check --plan p [--doc d]` | the operation ids a frontend plan cites (its §5 `Operation id` column, or a delta plan's `Contract Binding` rows; never the request table) against the document's `operationId`s — by script, no model. `drafted[]` names the cited ids that are only draft operations |
-| `contract-impact --delta-backend p --frontend-plan p [--delta-frontend p]` | the operations a change's service delta marks `changed` or `removed` in its "Contract deltas for the frontend lane" table that the frontend master plan binds to, and which of them the change's frontend delta plan does not name (`unaddressed[]`) — `analyze-plan-delta`'s warning. By script, no model |
+| `lane-set (--id lane\|--kind k) [--set KEY=VALUE]… [--unset KEY]…` | change only `contract_write`, `contract_run`, `contract` or `client` on a lane already declared, leaving the rest of it alone. An empty VALUE changes nothing; `--unset` puts the key back on the profile's value. Called by `foundation` (a pack's lane settings) and `implement` (the client command a developer supplies) — re-declaring would reset every other command |
+| `contract-export [--timeout s]` | write the service lane's as-built API document to `<service root>/contracts/openapi.json`: run its `contract_write` command (to a scratch path, kept only when it reads as OpenAPI), or start the service with `contract_run`, fetch `contract` and stop it and everything it started. Returns the `way` used and, on a failure, its `cause`; a lane with neither writes nothing (`cause: no-way`) (§4.5) |
+| `contract-draft --feature-dir p [--cr id]` | draft `api-draft.json` beside the feature's plans from `api-plan.md` (for a feature planned before it, the backend plan's API section), by script: each `### \`VERB /route\`` endpoint with its operation id, request and response field shapes (conceptual types → JSON schema, a use case's DTO standing in for a named shape) and error statuses with their body shapes. `unread` lists the shapes it could not type, and `dropped` the operations the draft it replaced had. Rewritten only when it differs; removed when the plan names no endpoint. With `--cr`, the change's draft in its change folder, from its `delta-api-plan.md` (§4.5) |
+| `contract-merge --feature-dir p --cr id` | merge the change's `delta-api-plan.md` into the feature's `api-plan.md` — whole endpoint blocks keyed by operation id (verb and route for a block with none, which is written with the id its row or the block it replaces gives that route): changed ones replaced, added ones after the last, removed ones deleted, a Contract deltas row with no block written from the row and reported (never over a block the change wrote on the same route) — plus the requests it answers and a `(pending)` Change History row; redraws `api-draft.json` and reports what it dropped. A feature with no `api-plan.md` has its backend plan's API moved into one first. A second run changes nothing. `finalize-delta`'s call (§4.5). With `--check` it writes nothing and reports `needed` — the change carries an API delta `api-plan.md` has no Change History row for — which `close-delta` asks before it archives |
+| `api-split --feature-dir p [--check] [--cr id]` | move a feature's endpoint blocks and requests table out of its backend plan into a new `api-plan.md`, leaving one line where they were, and redraw `api-draft.json`. `--check` only reports whether the backend plan still carries the API (`needed`); `--cr` checks a change's delta backend plan the same way. `plan main` offers it |
+| `contract-combine` | write `.appweaver/contracts/openapi.combined.json`: every feature's draft with each open change's applied — added, replaced, or marked `deprecated` with `x-aw-removed-by`, or, where an open change serves another operation on its route, listed in the document's `x-aw-removed` — plus, from a committed as-built document, the operations no plan describes (`x-aw-unplanned`), and `x-aw-unserved` on planned ones it does not serve. `ok:false` with a reason when there is nothing (§4.5) |
+| `contract-requests --feature-dir p` | the request ledger: the frontend plan's `RQ-n` rows against the API plan's answers — `open`, `published` (and whether the frontend still has to re-bind), `declined` — with one line per lane's to-do for a prompt to quote |
+| `contract-client [--doc d]` | `run-phase --phase client` for the frontend lane — its `client` command, `{{contract}}` expanded to `--doc` (`implement` passes the combined document), else to the as-built one |
+| `contract-check --plan p [--doc d]` | the operation ids a frontend plan cites (its §5 `Operation id` column, or a delta plan's `Contract Binding` rows; never the request table) against the combined document's `operationId`s — by script, no model. Also names the cited ids an open change removes, the service does not serve yet, and the service serves with no plan describing them |
+| `contract-impact --delta-backend p --frontend-plan p [--delta-frontend p]` | the operations a change's API delta marks `changed` or `removed` in its "Contract deltas for the frontend lane" table — the `delta-api-plan.md` beside the delta backend plan when there is one — that the frontend master plan binds to, and which of them the change's frontend delta plan does not name (`unaddressed[]`) — `analyze-plan-delta`'s warning. By script, no model |
+| `contract-verify --feature-dir p [--cr id] [--doc d] [--check]` | the as-built document against the operations the feature's draft names, with any change merged into its spec and not yet closed applied — or, with `--cr`, against that change's draft alone. `missing`, `moved`, `renamed` and `still_served` are findings (`ok:false`) — a removed operation is still served when its id is, or its route is answered while the plan keeps no other operation on it; differing fields and status codes, and served operations no plan describes, are the `warning`. `checked:false` with a `note` when there is nothing to check against. `--check` reads no as-built document and reports `needed` — the plan names something to check — which the gates ask before they write the document. By script, no model |
 | `lane-resolve [--kind k] [--id lane] [--feature-dir p]` | read; exit 0 always. `exists` reports the file, `declared` reports the lanes — the shipped-but-unfilled seed is `exists:true, declared:false`. Returns the matched lane **and** both kinds flattened — `backend_source_path`, `frontend_root_exists`, `backend_build` … — so a workflow binds one variable instead of calling twice — and the working-lane fields of §2a |
 | `lane-verify [--require backend\|frontend]… [--allow-missing-root] [--working-only] [--command phase]` | **the gate**: is the declaration usable for the phase about to run. Never writes, and **always exits 0** — the calling workflow's `verify_context` owns the stop, so the reason arrives as text. `--working-only` checks on disk only the working lanes' root folders and the required kinds (§2a). Whatever the flags, `kinds_on_disk[]` lists the kinds whose lane root folder exists and `missing_roots` the issue each declared lane without one raises when `--allow-missing-root` is not passed |
 | `lane-select [--lane backend\|frontend\|both] [--default] [--preselect text]` | read or write `.appweaver/lane.json` (§2a). No argument reads it and returns the `select_options[]` the declared stacks offer; `--lane` writes one of them; `--default` writes the default — `select-stack`'s call |
@@ -745,7 +777,10 @@ they are content the kit cannot invent:
 - **Technical rules** — a corpus at `guardrails/technology/<id>/`, mapped from the project's
   `tech-rule-bindings.md` (§7a). Until one exists the stack runs with the universal
   `ai-rules.md` and the technical constitution, which is the greenfield-safe default, not an
-  error.
+  error. It is said, not left to be discovered: `select-stack`'s menu names the stacks the
+  active map has rule files for, a lane declared on a stack with none or only some of them
+  raises a warning (`stack-rules`), and each later phase reports the missing folder once
+  rather than file by file.
 - **A foundation pack or spec** — `foundations/<ecosystem>/<Name>/`, only if you want
   `/appweaver foundation` to offer one for this stack (give it `# kind:` / `# profiles:`
   header lines). Without one, `foundation` still offers `[manual spec]` for the lane, and

package/assets/.appweaver/orchestrator/LAUNCHER.md

@@ -81,7 +81,7 @@ If the user names a strategy your row does not support — or you have no row an
    - If `pending.note` is present, your previous response was rejected — follow the note and rewrite `response_path`.
 
 4. **Report**:
-   Report the final JSON (`status`, `outputs`, and any `reason`) to the user. On `stopped`, relay the gate message verbatim — it tells the user what to fix or run first.
+   Report the final JSON (`status`, `outputs`, and any `reason`) to the user. On `stopped`, relay the gate message verbatim — it tells the user what to fix or run first. Relay every entry of `warnings` too, verbatim and one per line, on `ok` and on `stopped` alike: each is a check that failed and let the run continue — a lane skipped, a rule file not loaded, a document not exported — and the run log that also shows it is not printed under `--json`.
 
 ## Adding an agent