aw-spec-cli 0.1.26 → 0.1.28

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

@@ -9,7 +9,7 @@ makes) and `.appweaver/stack-profiles/*.json` (the candidates it chooses from).
 
 ## 1. What a lane is
 
-A **lane** is a technology target that owns disjoint source paths, compiles and tests
+A **lane** is a technology target that owns its own lane root folder, compiles and tests
 independently, and carries its own technical rules and constitution half — while
 *sharing* the feature, the spec, the domain, the version, and the knowledge bundle with
 every other lane.
@@ -22,7 +22,7 @@ and why nothing in the format assumes there are only two lanes.
 
 **Lanes get map headings, never a `--lane` flag.** Rule maps are keyed on
 `## /aw-spec-<name>`, so a lane's rule set is reached under its own heading —
-`## /aw-spec-implement-ui` for the frontend lane of `implement`, and so on. A flag would have
+`## /aw-spec-implement-frontend` for the frontend lane of `implement`, and so on. A flag would have
 no heading to key on. Where the two lanes are folded into one command, as `plan` and
 `implement` are, the heading names the lane and the command dispatches on the declaration.
 
@@ -33,9 +33,10 @@ no heading to key on. Where the two lanes are folded into one command, as `plan`
 ```jsonc
 {
   "lanes": [
-    { "id": "service", "kind": "backend",  "profile": "dotnet-webapi", "root": "src/",
-      "build": "dotnet build", "test": "dotnet test", "run": "dotnet run --project src/" },
-    { "id": "web",     "kind": "frontend", "profile": "react-vite",    "root": "web/",
+    { "id": "service", "kind": "backend",  "profile": "dotnet-webapi", "root": "backend/",
+      "run_from": "root",
+      "build": "dotnet build", "test": "dotnet test", "run": "dotnet run --project {{host}}" },
+    { "id": "web",     "kind": "frontend", "profile": "react-vite",    "root": "frontend/",
       "run_from": "root",
       "build": "npm run build", "test": "npm test", "run": "npm run dev" }
   ],
@@ -50,16 +51,19 @@ no heading to key on. Where the two lanes are folded into one command, as `plan`
 | `profile` | the stack profile the lane was declared from. Records the technology, so re-stacking a lane never renames the lane. `detected` where the kit ships no profile for what the code is |
 | `stack` | *(optional)* what the code was found to be, when `profile` is `detected` — e.g. `asp.net-webforms`. The honest record for a legacy lane |
 | `origin` | *(optional)* `reverse-engineered` on a lane `onboard` derived from an existing codebase. Absent means a person declared it, which is the greenfield shape and the historical one |
-| `root` | the lane's **source path** — the subtree it owns (see §3). `--source-path` and `--root` are two spellings of this one field |
+| `root` | the **lane root folder** — the subtree the lane owns (see §3). `--source-path` and `--root` are two spellings of this one field |
 | `test_root` | *(optional)* the lane's **test path**, written by hand only when the profile's answer does not fit this layout. Absent, `lane-resolve` / `lane-verify` work it out from the profile at read time (§4.3), so no lane has to be re-declared for it |
-| `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's own source path. 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` (§4.2) |
+| `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) |
 
 ### Three properties matter more than the schema
 
-1. **`root` is ownership, and it is the source path.** `implement`'s service lane writes its
-   code only under a backend lane's root and its frontend lane only under a frontend lane's,
+1. **`root` is ownership, and it is the lane root folder.** `implement`'s service lane writes its
+   code only under the backend lane root folder and its frontend lane only under the frontend one,
    `build`/`test`/`run` act on it, and `onboard` reverse-engineers out of it. The lane's
    **test path** (§4.3) is owned the same way, and is where `implement` writes the lane's tests.
 2. **The commands are project-supplied strings.** The engine stays stdlib-only and
@@ -71,33 +75,39 @@ no heading to key on. Where the two lanes are folded into one command, as `plan`
 
 ### 3.1 `root` is where the code is; `run_from` is where the commands run
 
-These are two questions and for most stacks they have two answers. `dotnet build` needs the
-solution file at the top while the lane owns `src/`; `go build ./...` needs the go.mod there
-while the lane owns `internal/`. Those profiles leave `run_from` at its default and run at
-the repository root.
-
-A stack whose **manifest lives inside the subtree** needs the other answer, and cannot work
-without it: a Maven wrapper at `backend/orderservice/mvnw` is unreachable from the repository
-root, so `java-spring` declares `run_from: "root"`. The five npm frontends and `blazor-wasm`
-declare it too, which is what let their commands stop hardcoding `--prefix web` — the lane
-already declares that directory, and a lane rooted at `client/` was previously building `web/`
-regardless.
+These are two questions, and an existing repository can give them two answers: a classic
+.NET repository keeps its solution file at the top while the lane owns `src/`, and a classic
+Go repository keeps `go.mod` there while the lane owns `internal/`. Their commands have to run
+at the repository root.
+
+**A new project is one self-contained folder per lane.** Every backend profile defaults to
+`backend/` and every frontend profile to `frontend/`, with `run_from: "root"`: the lane's
+build files, source and tests all live inside its lane root folder, and its commands run there.
+`foundation` builds exactly that — a pack unpacks into the lane root folder as packed, a spec build
+creates the whole project inside it — and reports a lane that does not run its commands in its
+own folder or keeps its tests outside it, rather than scaffolding a project its own build
+cannot find.
+
+**`select-stack` answers `run_from` from the disk.** Each backend profile lists the files its
+commands need (`build_files`: `*.sln`, `pom.xml`, `go.mod`, `package.json`, …). When a lane is
+declared, `lane-declare` looks for them: directly inside the lane root folder ⇒ `root`; only at the
+repository root ⇒ `repo`; nowhere yet — a greenfield lane — ⇒ the profile's own answer, which is
+inside the lane. So a classic repository keeps the shape it has, a Maven module whose `mvnw`
+sits in the lane root folder runs there, and a new project gets the self-contained layout, from
+one profile. `--run-from` overrides it, and so does editing `stacks.json`.
 
 Two consequences worth knowing:
 
-- **Declare a `run_from: "root"` lane at the directory holding its manifest**, not at its
-  source directory. `java-spring`'s profile default root is `src/main/java/`, which is where
-  the *code* goes; detection proposes the directory `pom.xml` actually sits in, which is the
-  one to accept. A lane rooted at `src/main/java/` will fail loudly with `./mvnw: not found`
-  rather than silently.
+- **Declare a lane at the directory holding its build file** when the code already exists and
+  should run there — a Maven lane at the folder with `pom.xml`, not at `src/main/java/`.
 - **A single-module project declares `.`** — stored as `./`, the repository root. It owns
   everything, so it overlaps every other lane by definition and cannot be combined with one.
 
-### Where the source path is checked against the disk
+### Where the lane root folder is checked against the disk
 
 `lane-declare` records a path; it does **not** require the path to exist. In a greenfield
-project it does not exist yet — the whole point of declaring `src/` on day one is that
-`implement` will create it.
+project it does not exist yet — the whole point of declaring `backend/` on day one is that
+`foundation` and `implement` will create it.
 
 `lane-verify` is the check, and it runs where the path has to be real: before `implement`,
 `build`, `run`, and before `onboard` reverse-engineers a codebase out of it. That split is what lets one file serve a project with no code yet and a project that is
@@ -108,7 +118,7 @@ Two failure classes, deliberately distinguished:
 - **MISSING** — the phase needs a lane of this kind and none is declared. Reported only for
   the kinds a caller names with `--require`, because "no frontend lane" is a correct and
   common state that must never fail a backend build.
-- **BROKEN** — a lane *is* declared and its source path is empty, is not a directory, or
+- **BROKEN** — a lane *is* declared and its lane root folder is empty, is not a directory, or
   overlaps another lane's. Checked for **every** declared lane whether or not the caller
   asked about it. A stack named against a path that is not there is a mistake in every
   phase, and letting it through means discovering it as an empty build or a generator
@@ -118,11 +128,25 @@ Two failure classes, deliberately distinguished:
 
 ### The file ships empty, and may be filled in by hand
 
-The kit installs `.appweaver/stacks.json` holding `{"lanes": []}`, alongside `domain.json` and
+The kit installs `.appweaver/stacks.json` with an empty `lanes` array, alongside `domain.json` and
 `feature.json`. It is there so a project can open it and fill it in directly — the block at
 the top of this section is the whole schema, and `select-stack` writes nothing a person
 could not have typed.
 
+**The shipped file carries a sample under `_lane_format`**: one backend and one frontend lane
+with every field above filled in (.NET and Next.js), plus a `prototype` block. No command
+reads that key, and `select-stack` leaves it in place, so it is safe to keep. To fill the file
+by hand, copy the lanes you need into `lanes` and edit them. The samples' optional fields hold
+values that change nothing when copied (`stack` is the profile's own title, `origin: "declared"`
+is the default, `test_root` is the profile's own answer), except `migrate`, which is a real
+command: keep it only if the lane has migrations to run. The frontend sample's `migrate` is
+empty because a Next.js lane has none.
+
+**Never leave an empty or half-filled entry in `lanes`.** Every entry there is a declared lane,
+whatever its values: `select-stack` replaces a lane only when its `id` matches, so it adds its
+lane beside a blank one instead of replacing it, and `lane-verify` then stops every phase on the
+blank lane's missing lane root folder.
+
 **An empty file and an absent one are the same state.** Shipping the file means its presence
 no longer says anything about whether a lane was declared, so `declared` reports on the
 `lanes` array and never on the file: `resolve` reports `exists: true, declared: false` for
@@ -131,7 +155,7 @@ the file is missing, naming which of the two it found.
 
 Hand-editing and `select-stack` are the same file and the same schema, so they interleave
 freely: fill in the service lane by hand and run `select-stack` later to add the UI one, or
-run it first and correct a source path in the editor. What hand-editing gives up is the
+run it first and correct a lane root folder in the editor. What hand-editing gives up is the
 checking `select-stack` does on the way in — an unknown `profile`, a missing `root`, and two
 lanes whose roots overlap are all refused there and merely written here. `lane-verify` still
 catches the last two before any phase acts on them; a profile id that matches nothing
@@ -152,7 +176,7 @@ Declaring **`(none)`** for a lane is a real answer and the way a project says it
 
 ## 3. The ownership rule
 
-**Lane roots own their subtree and must be disjoint.** Two generators must never be able
+**Lane root folders own their subtree and must be disjoint.** Two generators must never be able
 to write the same file. A lane owns its test path too, so the rule covers both: no source or
 test path of one lane may overlap a source or test path of another.
 
@@ -182,13 +206,25 @@ workflow.**
   "title": "React + Vite",                   // shown in the menu
   "language": "TypeScript",                  // shown in the menu, parenthesised
   "ecosystem": "node",                       // which stack-partitioned corpus this stack draws from
-  "root": "web/",                            // the lane root this profile defaults to
+  "root": "frontend/",                       // the folder a NEW lane of this stack gets — see §3.1
   "test_root": "",                           // optional — where tests go when not inside root — see §4.3
-  "run_from": "root",                        // where the commands run — see §3.1
+  "run_from": "root",                        // where the commands run for a new lane — see §3.1
+  "conventional_root": "web/",               // optional — where this stack's code usually sits in an
+                                             // EXISTING repository; `detect` is written against it
+  "conventional_test_root": "",              // optional — the test path that pairs with it — see §4.3
+  "build_files": [],                         // optional — the files its commands need (`*.sln`,
+                                             // `go.mod`); decides `run_from` at declare time — §3.1
   "build": "npm run build",
   "test":  "npm test",
   "run":   "npm run dev",
+  "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
+  "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
   "reserved_names": ["Event", "Request", "Response"],  // optional — names this stack's AMBIENT
                                              // scope already defines; see §4.4
@@ -209,49 +245,96 @@ trees that are physically per-ecosystem:
 
 | Tree | Keyed by | Read through |
 |---|---|---|
-| `foundations/<ecosystem>/<Name>/` | `ecosystem` | `foundation-list`, `foundation-locate` |
+| `foundations/<ecosystem>/<Name>/` | `ecosystem`, then each pack/spec's `# kind:` / `# profiles:` header | `foundation-list`, `foundation-locate` |
 | `foundations/<ecosystem>/components/<C>/` | `ecosystem` | `list-components`, `add-component` |
 
 **Why those two are filtered and the rule corpora are not.** A foundation bundle is a whole
 compiling project and a component runbook edits a host project's build files — both are
 executable artifacts in one toolchain, so offering a `dotnet` bundle to a Spring repo does not
 produce a scaffold, it produces a second foreign project beside the real one. `foundation-list`
-therefore narrows by ecosystem, and reports `all_foundations` alongside so the gate can say
-*what exists and why none of it applies*. `--ecosystem` narrows to the ONE lane being
+therefore narrows by ecosystem, and reports `all_foundations` alongside so the pick list can say
+*what exists and how much of it applies*. `--ecosystem` narrows to the ONE lane being
 scaffolded, which is what `foundation` passes: a repo declaring a .NET service and a Node UI
 must not be offered its .NET bundle while the UI lane is the target. Without that argument the
 filter falls back to every declared lane's ecosystem, and a repo that has declared nothing yet
 is not filtered — there is no answer to filter on.
 
-**A scaffold lands in a lane.** `foundation` unpacks a bundle into the SOURCE PATH of the lane
-it is scaffolding — never the repository root, and there is no output-directory argument. One
-bundle fills one lane, so a fullstack repo runs `foundation` once per lane. This is what makes
-every phase's "write only into your lane" rule true of the scaffold as well as of generated
-code: `implement`, `build`, `test` and `run` all resolve the same path the bundle unpacked into.
-A pack carrying its own test tree has it lifted onto the lane's **test path** (§4.3) afterwards,
-because for most backend stacks that path is a sibling of the source path rather than a
-directory inside it. Lanes must therefore be declared before `foundation` runs, which is why
-`select-stack` is the first command of both sequences.
+**Ecosystem alone is not narrow enough for a lane**, because it is shared across kinds: the
+five JavaScript frontends and `node-express` are all `node`, and `blazor-wasm` shares `dotnet`
+with the service stacks. So each pack and spec may open with header lines that `foundation-list`
+filters on as well — `# kind: backend|frontend` (absent = backend, the kind every pack shipped
+before the key existed scaffolds) and `# profiles: <id>, …` (absent = any profile of that kind).
+
+**Packs and specs.** A directory under `foundations/<ecosystem>/` may hold a pack
+(`<Name>.pack.txt` — a verified project unpacked byte-for-byte), any number of specs
+(`*.spec.txt` — a description an agent builds the project from), or both; each is its own
+entry in the lane's pick list, after which come `[manual spec]` (a spec given at the prompt)
+and `[skip]`. `foundations/foundation.spec.template.txt` is the shape of a spec. A spec build
+loads the technical rules the active project maps under `## /aw-spec-foundation-backend` or
+`## /aw-spec-foundation-frontend` (§7), and the spec it used is kept at
+`.appweaver/foundation/<lane>.spec.md`.
+
+**A scaffold lands in a lane.** `foundation` scaffolds into the FOLDER of each lane — its
+lane root folder, never a directory named on the command line — and the lane is self-contained
+(§3.1): a pack unpacks there exactly as packed, build files, source and tests together, and a
+spec build creates the whole project there and may write nowhere else — checked, not trusted:
+the repo is recorded before the build and compared after it, and a build that created, changed
+or deleted anything outside the lane root folder is "NOT accepted", with what it created there
+removed again and what it changed or deleted listed for the operator. One run covers every
+declared lane, backend then frontend, and each lane gets its own pick. A lane that does not run
+its commands in its lane root folder, or keeps its tests outside it, is reported and passed over. A
+lane that already holds files — any file in its source or test path — is asked "Overwrite?"
+before its pick list; "no" skips the lane, and "yes" replaces same-path files and deletes
+nothing. A pack's reference sample goes on top of the base project the same way. The one
+exception is a pack's **rule file** (`<pack name>.rules.json` beside the pack): the files and
+folders it names with `merge` are combined with the file already there, by an agent following
+the rule's own instruction, instead of being replaced — the .NET reference samples use it to
+merge their DbContext into the base project's. The format is in
+[PACKAGING.md](../guardrails/technology/dotnet-webapi/PACKAGING.md#the-rule-file-pack-namerulesjson).
+This is what makes every phase's "write only into your lane" rule true of the scaffold
+as well as of generated code: `implement`, `build`, `test` and `run` all resolve the same
+paths. Lanes must therefore be declared before `foundation` runs, which is why `select-stack`
+is the first command of both sequences.
 
 The technical RULE corpora at `guardrails/technology/<stack>/` are keyed by **profile id**, not
 ecosystem, because Spring and Quarkus are both `java` and do not share a persistence rule. They
 are selected through the project's `tech-rule-bindings.md` rather than filtered here — see §7.
 
-### 4.2 `run_from`, `{{root}}` and `migrate`
+### 4.2 `run_from`, `{{root}}`, `{{host}}` and `migrate`
 
-A profile command sometimes has to name the source path — `dotnet run --project src/`. Written
+A profile command sometimes has to name the lane root folder — `python -m compileall app`. Written
 literally that is the profile's *default* root frozen into the command, and it stays frozen when
 a lane declares a different one. Write **`{{root}}`** instead and it resolves to the lane's own
-root, expanded at run time so a hand-edited `root` in `stacks.json` stays consistent with it:
+root as seen from where the command runs, expanded at run time so a hand-edited `root` in
+`stacks.json` stays consistent with it:
 
 ```jsonc
-"run":   "dotnet run --project {{root}}",   // Services/Api/ ⇒ dotnet run --project Services/Api
-"build": "python -m compileall {{root}}"    // repo-root lane ⇒ python -m compileall .
+"build": "python -m compileall {{root}}"    // app/, run at the repo root ⇒ python -m compileall app
+                                            // a run_from: root lane ⇒ python -m compileall .
+```
+
+Some commands need a *project* inside the lane root folder rather than the folder itself.
+`dotnet run --project <folder>` needs exactly one project in that folder, and a solution has
+several — a pack's runnable one is `src/<App>.AppHost`, the .NET Aspire host. Write
+**`{{host}}`** and it resolves to that project's folder, from the profile's `host_patterns`:
+paths relative to the lane root folder, best first, `**/` for any depth, case ignored. The
+first pattern that matches exactly one file names the project; build output, dependency and
+test folders are never searched. It is looked up when the command is read, so a project
+scaffolded after the lane was declared is found, and with no single match `{{host}}` falls
+back to `{{root}}`:
+
+```jsonc
+"run": "dotnet run --project {{host}}",
+"host_patterns": ["**/*.AppHost.csproj", "**/*.Api.csproj", "**/*.Service.csproj"]
+// backend/ holding src/Acme.AppHost/ and src/Acme.Service/ ⇒ dotnet run --project src/Acme.AppHost
+// backend/ holding src/Acme.Api/ and src/Acme.Domain/    ⇒ dotnet run --project src/Acme.Api
 ```
 
 A command with no placeholder is used verbatim, so every literal command already on disk is
-unaffected. `{{root}}` is the answer when the command needs the *path*; `run_from: "root"` (§3.1)
-is the answer when it needs the *working directory*.
+unaffected. A lane keeps the command it was declared with: one declared before `{{host}}` was
+in its profile picks it up when select-stack declares it again. `{{root}}` and `{{host}}` are
+the answer when the command needs a *path*; `run_from: "root"` (§3.1) is the answer when it
+needs the *working directory*.
 
 `migrate` is an optional fourth phase command, alongside `build`/`test`/`run`. **No shipped
 profile declares one**, deliberately: Flyway, Liquibase, Alembic, Prisma and golang-migrate all
@@ -263,17 +346,21 @@ elsewhere rather than implying a migration succeeded.
 `detect` is an **ANY-of** list, not an all-of: `java-spring` names both `pom.xml` and
 `build.gradle` because a project has one or the other, and requiring both would make it
 undetectable. `stack-detect` scores a profile by how many of its patterns hit. Patterns are
-matched first as written (repo-root-relative, with `**` spanning separators), then relocated
-under any directory prefix — so a profile shipping `web/package.json` still recognises the
-same stack in `client/` or `apps/portal/`, which a brownfield repo that never saw our
+written against the layout an EXISTING repository of the stack usually has — the profile's
+`conventional_root` (`web/package.json`, `src/**/*.csproj`) — and matched first as written
+(repo-root-relative, with `**` spanning separators), then relocated under any directory prefix,
+with that root segment substituted — so a profile shipping `web/package.json` still recognises
+the same stack in `client/` or `apps/portal/`, which a brownfield repo that never saw our
 profiles will need. An anchored hit outranks a relocated one.
 
 `detect` and `root` are independent, and deliberately so: `go-chi` detects on `go.mod` at the
-repo root and declares a root of `internal/`. Detection reports the shallowest directory its
-evidence actually sits in, and that directory is what `select-stack` offers first when it asks
-for the lane's source path — ahead of the profile's own default, because a repo that already
-exists did not choose its layout from our profiles. The operator picks from the list or types
-a path the kit has never seen.
+repo root, keeps its code under `internal/` in an existing repository, and gives a new lane
+`backend/`. Detection reports the shallowest directory its evidence actually sits in; evidence
+only at the repository root (`App.sln`, `go.mod`) defers to the `conventional_root` when that
+directory is there, then to `root`. That directory is what `select-stack` offers first when it
+asks for the lane root folder — ahead of the profile's own default, because a repo that
+already exists did not choose its layout from our profiles. The operator picks from the list or
+types a path the kit has never seen.
 
 **Detection leads the menu; it never fills `preselect`.** The engine treats `preselect_from`
 as the answer, ahead of a headless `--select`, so filling it from a scan would let a repo's
@@ -323,47 +410,98 @@ Absent, nothing is reported and generation is unchanged.
 
 ### 4.3 `test_root` — where a lane's tests go
 
-Most backend stacks keep their tests **beside** the source, not inside it: .NET's `tests/` next
-to `src/`, Maven's `src/test/java/` next to `src/main/java/`, pytest's `tests/` next to `app/`.
-A lane that owned only its source path could not hold its own tests, so each lane also owns a
-**test path**, and `implement` writes the lane's paired tests there.
+In an existing repository most backend stacks keep their tests **beside** the source, not
+inside it: .NET's `tests/` next to `src/`, Maven's `src/test/java/` next to `src/main/java/`,
+pytest's `tests/` next to `app/`. A new, self-contained lane keeps them inside its lane root folder
+(`backend/tests/`). Either way each lane owns a **test path**, and `implement` writes the lane's
+paired tests there.
 
-A profile's `test_root` is the test path that pairs with its default `root`. `lane-resolve` and
+A profile's `test_root` is the test path that pairs with its default `root`, and its
+`conventional_test_root` the one that pairs with its `conventional_root`. `lane-resolve` and
 `lane-verify` report it per kind as `backend_test_path` / `frontend_test_path`, worked out at
 read time:
 
 | The lane | Its test path |
 |---|---|
 | declares `test_root` itself | that value |
-| sits at the profile's default root (`src/`) | the profile's `test_root` (`tests/`) |
-| sits at a path ending in the default root (`backend/src/`) | the profile's `test_root` under the same prefix (`backend/tests/`) |
-| anything else, or the profile declares no `test_root` | the source path itself |
-
-The last row is right for every shipped frontend (tests under `web/tests/`), for Go's
-colocated `_test.go` files, and for a Maven lane rooted at the directory holding its
-`pom.xml`, where `src/test/java/` is already inside the lane. A layout the table gets wrong is
-fixed by writing `test_root` on the lane in `stacks.json`.
-
-| Profile | `root` | `test_root` |
+| sits at the profile's default root (`backend/`) | the profile's `test_root` (`backend/tests/`) |
+| sits at a path ending in the default root (`apps/backend/`) | the profile's `test_root` under the same prefix (`apps/backend/tests/`) |
+| sits at — or at a path ending in — the conventional root (`src/`, `svc/src/main/java/`) | the `conventional_test_root`, the same way (`tests/`, `svc/src/test/java/`) |
+| anything else, or the profile declares neither | the lane root folder itself |
+
+The last row is right for every shipped frontend (tests under `frontend/tests/`), for Go's
+colocated `_test.go` files, and for a lane at any other folder name, whose tests are inside it.
+A layout the table gets wrong is fixed by writing `test_root` on the lane in `stacks.json`.
+
+| Profile | `root` | `test_root` | `conventional_root` | `conventional_test_root` |
+|---|---|---|---|---|
+| `dotnet-webapi` | `backend/` | `backend/tests/` | `src/` | `tests/` |
+| `java-spring` | `backend/` | `backend/src/test/java/` | `src/main/java/` | `src/test/java/` |
+| `python-fastapi` | `backend/` | `backend/tests/` | `app/` | `tests/` |
+| `node-express` | `backend/` | `backend/tests/` | `src/` | `tests/` |
+| `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. `implement` therefore runs
+three steps between the two lanes, each of which warns rather than stops:
+
+1. **Export** (`contract-export`) — 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.
+2. **Client** (`contract-client`) — run the frontend lane's `client` command, with
+   `{{contract}}` standing for that document as seen from where the command runs.
+3. **Check** (`contract-check`) — every operation id the frontend plan cites must be an
+   `operationId` in the document.
+
+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:
+
+| Key | Profile default | Set on the lane by |
 |---|---|---|
-| `dotnet-webapi` | `src/` | `tests/` |
-| `java-spring` | `src/main/java/` | `src/test/java/` |
-| `python-fastapi` | `app/` | `tests/` |
-| `node-express` | `src/` | `tests/` |
-| `go-chi` and every frontend | — | *(none — inside the source path)* |
+| `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 |
+
+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`.
+
+`--environment Development` matters for the .NET packs: outside Development they redirect
+to HTTPS, and the 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
+them:
+
+```json
+{"format": "aw-spec-pack-lane/v1",
+ "contract_run": "dotnet run --project src/AppWeaver.VerticalSlice.Service -- --environment Development --urls http://localhost:5000 --ConnectionStrings:SqliteConnection \"Data Source=App_Data/app.db\"",
+ "contract": "http://localhost:5000/swagger/v1/swagger.json"}
+```
 
 ---
 
 ## 5. Who may write this file
 
-**`lane-declare` writes it. Nothing else does, and it has exactly ONE caller** — so the
-rule is a grep, not a convention:
+**`lane-declare` writes whole lanes, and it has exactly ONE caller** — so the rule is a
+grep, not a convention:
 
 ```sh
 grep -rl "lane-declare" .appweaver/orchestrator/workflows/   # must print exactly one file
 #   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
+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
 brownfield sequence a repo could reach `onboard` undeclared, so `onboard` ran its own
 detection pass, recorded what it found marked `origin: reverse-engineered`, and was gated
@@ -390,11 +528,12 @@ re-runs the roots-disjoint one on every read (see §2).
 
 Consequences worth stating, because they are the reason for the design:
 
-- **`foundation` / `ui-foundation` scaffold *against* a declared lane** and verify what
-  they produced against it — stopping `STACK-MISMATCH:` rather than rewriting the
-  declaration to fit the scaffold. A wrong declaration surfaces at the scaffold instead of
-  being absorbed by it, and the lane a project *chose* stays the authority over the lane a
-  generator *happened to produce*.
+- **`foundation` scaffolds *into* a declared lane** and never rewrites the declaration to
+  fit what it produced. Each lane is scaffolded into its own source and test paths, and a
+  spec build must leave a project of the lane's own stack inside the lane — otherwise that
+  lane is reported "NOT usable" and the run moves on to the next one. A wrong declaration
+  surfaces at the scaffold instead of being absorbed by it, and the lane a project *chose*
+  stays the authority over the lane a generator *happened to produce*.
 - **`build` runs every declared lane's own build command**, in declaration order, and
   fails if any lane fails. Without a declaration it falls back to the historic
   first-match-wins sniffer, which is right for one lane and silently skips the second —
@@ -411,7 +550,7 @@ follows from it:
 | Which rule sets does `onboard` generate? | the same, per lane — `service/` and `frontend/` under the project folder |
 | Which subtree does `implement` write into? | that lane's `root` |
 | What does `build` compile, and `run` migrate? | every declared lane's own command, against its own root |
-| What does `onboard` scan? | the declared source paths — backend signals from outside the UI subtree, frontend signals from inside it |
+| What does `onboard` scan? | the declared lane root folders — backend signals from outside the UI subtree, frontend signals from inside it |
 
 This is a change of authority, and worth being explicit about. The question "does this
 project have a UI lane" used to be answered by OR-ing three heuristics: a
@@ -441,13 +580,15 @@ constraint where it previously had none. That is a deliberate trade: what it buy
 every later phase can ask this file a question and get an answer, instead of inferring one.
 
 ```
-GREENFIELD   select-stack → select-domain → constitution → select-feature → specify → …
+GREENFIELD   select-stack → constitution → [select-feature] → specify → …
 BROWNFIELD   select-stack → onboard → select-feature → adopt → …
 ```
 
-`select-domain` is greenfield-only: `onboard` derives the project from the code and
-activates it. On an existing codebase `select-stack` is mostly confirmation — it detects the
-stack and the source path from the repo's own files and leads the menu with them — but it is
+Neither sequence selects a project. Greenfield uses `guardrails/project-specific/`, which
+`.appweaver/domain.json` names as shipped; `onboard` creates `guardrails/brf-<domain>/` from
+the code and points `domain.json` at it. The optional `select-domain` switches `domain.json` to
+another project folder under `guardrails/` that already exists. On an existing codebase `select-stack` is mostly confirmation — it detects the
+stack and the lane root folder from the repo's own files and leads the menu with them — but it is
 a person's confirmation, which is what detection on a legacy repo needs.
 
 ## 6. Subcommands
@@ -460,7 +601,11 @@ 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 |
-| `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 lane — **the sole writer**. `detected` declares a stack the kit ships no profile for (needs `--stack` and a source path), which is how a legacy WebForms, JSP or ERB lane gets recorded at all |
+| `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-client` | `run-phase --phase client` for the frontend lane — its `client` command, `{{contract}}` expanded |
+| `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) against the document's `operationId`s — by script, no model |
 | `lane-resolve [--kind k] [--id lane]` | 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 |
 | `lane-verify [--require backend\|frontend]… [--allow-missing-root] [--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 |
 | `lane-probe [--kind k] [--hint text]` | read; the **file** signals for "does this lane exist" — a declared lane, and a stack named in free prose. Retained for callers that want a soft hint; the authoritative answer is the declaration, read through `lane-resolve` or `lane-verify` |
@@ -474,10 +619,11 @@ set**, so a caller binds outputs without knowing which branch ran.
 |---|---|---|
 | `build-compile` | every declared lane's own `build`, via `run-phase` | the historic first-match-wins ladder |
 | `test-run` | every declared lane's own `test`, via `run-phase` — **except** `--scope slice` on a repo where a .NET toolchain is present, which keeps the VSTest `--filter` path | the historic ladder |
-| `run-migrate` | a lane's declared `migrate` (§4.2) when there is one; otherwise `dotnet ef` searched under the **service lane's root** rather than an assumed `src/` | `dotnet ef` under `src/` |
-| `find-host-project` | searches the service lane's root, and reports the lane's `ecosystem` | searches `src/` |
-| `foundation-list`, `list-components` | narrowed to the `ecosystem` of the lane being scaffolded, else of every declared lane (§4.1) | unfiltered / `dotnet` |
-| `foundation-unpack` | unpacks into the lane's **source path**, and lifts a packed test tree onto its **test path** (§4.1, §4.3) | cannot run — `foundation` stops until a lane is declared |
+| `run-migrate` | a lane's declared `migrate` (§4.2) when there is one; otherwise `dotnet ef` searched under the **service lane root folder** rather than an assumed `src/` | `dotnet ef` under `src/` |
+| `find-host-project` | searches the service lane root folder, and reports the lane's `ecosystem` | searches `src/` |
+| `foundation-list`, `list-components` | narrowed to the `ecosystem` of the lane being scaffolded, else of every declared lane; `foundation-list` also by each entry's `# kind:` / `# profiles:` (§4.1) | unfiltered / `dotnet` |
+| `foundation-unpack` | unpacks into the **lane root folder**, and lifts a packed test tree onto its **test path** (§4.1, §4.3) | cannot run — `foundation` stops until a lane is declared |
+| `build-compile --kind` | that one lane's own `build` — what `foundation` runs after a spec build | the ladder; `--kind` is ignored |
 | `resolve-tech` | expands stack placeholders and flags a corpus mismatch (§7a) | no placeholders resolve; nothing is flagged |
 
 **Why `--scope slice` is the one exception.** VSTest's `--filter FullyQualifiedName~` is the
@@ -498,16 +644,17 @@ No workflow or script changes. If adding a stack ever requires touching a workfl
 model is wrong and that is the bug to fix.
 
 That gives the new stack every phase that is driven by a **command** — build, test, run,
-migrate — plus the correct source path everywhere, immediately. Two things are opt-in because
+migrate — plus the correct lane root folder everywhere, immediately. Two things are opt-in because
 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.
-- **A foundation bundle** — `foundations/<ecosystem>/<Name>/`, only if you want `/appweaver
-  foundation` to scaffold this stack. Scaffolding with the stack's own tooling and then
-  declaring the result with `select-stack` is fully supported: `implement` generates INTO a
+- **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
+  scaffolding with the stack's own tooling is fully supported: `implement` generates INTO a
   project tree and does not require that the kit created it.
 
 ## 7a. Mapping rules to a stack without pinning the map to one
@@ -523,15 +670,20 @@ they are content the kit cannot invent:
 | `{{backend_ecosystem}}` / `{{frontend_ecosystem}}` | that lane's `ecosystem` |
 
 ```md
-## /aw-spec-plan
+## /aw-spec-plan-backend
 - guardrails/technology/{{stack}}/persistence.md
-- guardrails/technology/{{frontend_stack}}/ui-constitution.md
+
+## /aw-spec-plan-frontend
+- guardrails/technology/{{frontend_stack}}/component-architecture.md
+- guardrails/technology/{{frontend_stack}}/api-integration.{{backend_stack}}.md
 ```
 
 One map, read from a Spring repo, loads `java-spring/persistence.md`; read from a .NET repo it
-loads `dotnet-webapi/persistence.md`. A placeholder for a lane that is not declared **skips**
-that bullet — a frontend rule in a backend-only repo is not an error — and a resolved path with
-no file on disk is reported under `missing` rather than silently dropped.
+loads `dotnet-webapi/persistence.md`. Each heading holds one lane's rules, and a workflow loads
+a lane's heading only when that lane runs. A placeholder for a lane that is not declared
+**skips** that bullet — in a frontend-only repo the `api-integration.{{backend_stack}}.md`
+pairing bullet is skipped, not an error — and a resolved path with no file on disk is reported
+under `missing` rather than silently dropped.
 
 **A bullet that spells the stack out is still used**, because a shared corpus may be referenced
 on purpose. But when that directory is not one the repo declares, `resolve-tech` returns