aw-spec-cli 0.1.26 → 0.1.27

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.
@@ -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,16 @@ 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) |
 
 ### 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 +72,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 +115,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 +125,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 +152,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 +173,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,12 +203,19 @@ 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
   "prototype_run": "npm run dev --prefix prototype",   // frontend only — fills the prototype block
   "reserved_names": ["Event", "Request", "Response"],  // optional — names this stack's AMBIENT
@@ -209,49 +237,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 +338,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,34 +402,37 @@ 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` |
-|---|---|---|
-| `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)* |
+| 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/` | — |
 
 ---
 
@@ -390,11 +472,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 +494,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 +524,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 +545,7 @@ 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 lane — **the sole writer**. `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-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 +559,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 +584,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

package/assets/.appweaver/domain.json

@@ -1 +1 @@
-{"domain":""}
+{"domain":"project-specific"}

package/assets/.appweaver/orchestrator/AGENT-PROFILE.md

@@ -9,11 +9,27 @@ for that agent; the engine that consumes it is the *general* file in `.appweaver
 ```
 .appweaver/orchestrator/orchestrator.py    ← general engine (reads a profile)
 .appweaver/orchestrator/adapters/*.py      ← shared SDK adapters (one per SDK, not per agent)
-.claude/agent.json                       ← Claude Code profile  (claude -p / claude-agent-sdk)
-.agents/agent.json                       ← Antigravity profile  (agy -p / google-antigravity)
-.kilocode/agent.json                     ← Kilo Code profile    (delegates to claude)
+.claude/agent.json                       ← Claude Code profile    (claude -p / claude-agent-sdk)
+.agents/agent.json                       ← Antigravity profile    (agy -p / google-antigravity)
+.kilo/agent.json                         ← Kilo Code profile      (kilo run / claude-agent-sdk)
+.cursor/agent.json                       ← Cursor profile         (cursor-agent -p)
+.copilot/agent.json                      ← GitHub Copilot profile (copilot -p)
+.devin/agent.json                        ← Devin profile          (devin -p)
+.cline/agent.json                        ← Cline profile          (cline)
+.roo/agent.json                          ← Roo Code profile       (roo --print)
+.opencode/agent.json                     ← opencode profile       (opencode run)
+.factory/agent.json                      ← Factory Droid profile  (droid exec)
+.augment/agent.json                      ← Augment profile        (auggie --print)
+.continue/agent.json                     ← Continue profile       (cn -p)
+.kiro/agent.json                         ← Kiro profile           (kiro-cli chat)
+.codex/agent.json                        ← OpenAI Codex profile   (codex exec)
+.gemini/agent.json                       ← Gemini CLI profile     (gemini -p)
+.amp/agent.json                          ← Amp profile            (amp -x)
 ```
 
+Only the first three have an `sdk` block; the rest support the `agent` and
+`spawn` strategies.
+
 The launcher passes its profile with `--agent-profile <path>` (which implies
 `--transport real`).
 
@@ -60,7 +76,7 @@ options). Adapters are keyed by SDK, not by agent:
 `adapters/google_antigravity.py` maps the neutral permission modes onto
 Antigravity policies and drives `Agent` / `LocalAgentConfig` (used by
 `.agents`), while `adapters/claude_agent_sdk.py` drives `query` /
-`ClaudeAgentOptions` (shared by `.claude` and `.kilocode`, whose SDK is the
+`ClaudeAgentOptions` (shared by `.claude` and `.kilo`, whose SDK is the
 same) — none of which the engine knows about; it only follows the profile's
 `sdk.adapter` pointer.
 
@@ -87,11 +103,23 @@ When `system` is `"prepend"`, the system block is folded into the prompt
 ## Adding a new agent
 
 1. Drop an `agent.json` at that agent's root (`.<agent>/agent.json`) describing its CLI.
-2. Add a launcher in that agent's native format that calls
-   `orchestrator.py … --agent-profile .<agent>/agent.json`.
-3. For the `sdk`/`sdk-apply` strategies, add an `sdk` block and point
+2. Add the agent's row to the profile table in `.appweaver/orchestrator/LAUNCHER.md`.
+   The launchers in folders several agents read (`.claude/skills/`, `.agents/skills/`)
+   name no agent; an agent loading one of them finds its profile in that table.
+3. Add a launcher in that agent's native format that points at `LAUNCHER.md` and
+   names `.<agent>/agent.json` as the agent's profile — `.cursor/commands/appweaver.md`
+   is the shortest example.
+4. For the `sdk`/`sdk-apply` strategies, add an `sdk` block and point
    `sdk.adapter` at the matching adapter in `.appweaver/orchestrator/adapters/`
    — or drop a new adapter there first if that SDK has none yet.
-
-No engine change required. Verify with `--dry-run` (prints the exact command
-without executing).
+5. Add the agent's folder (and its launcher folder, if different) to `KIT_AGENT_DIRS`
+   in `.appweaver/scripts/python/aw-inventory.py`, so a brownfield inventory does not
+   read the kit's files as the project's own. When the launcher sits in a folder the
+   project also uses (as `.github/` holds its CI), add the launcher's exact path to
+   `KIT_AGENT_FILES` instead.
+
+No engine change required. Verify with `--dry-run` on `_smoke.orch.yaml`
+(`--non-interactive --strategy spawn --agent-profile .<agent>/agent.json --dry-run`):
+it prints the exact command the profile builds for every model step — the
+read-only `agent_query`, `agent_author` and `agent_review`, and the `agent_generate`
+edit step — without executing any of them.