aw-spec-cli 0.1.8 → 0.1.9

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

@@ -0,0 +1,461 @@
+# Stack profiles and the lane model
+
+Authoritative on two files: `.appweaver/stacks.json` (the lane declaration a project
+makes) and `.appweaver/stack-profiles/*.json` (the candidates it chooses from).
+
+`DESIGN-FORMAT.md` is to `design.md` what this document is to `stacks.json`.
+
+---
+
+## 1. What a lane is
+
+A **lane** is a technology target that owns disjoint source paths, 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.
+
+> One spec, one prototype, two designs, two implements, one build, one version.
+
+A lane is not a project, not a module, and not a layer. Two lanes exist when two
+toolchains do, which is why `kind` has exactly two values today (`backend`, `frontend`)
+and why nothing in the format assumes there are only two lanes.
+
+**Lanes get command names, never a `--lane` flag.** Rule maps are keyed on
+`## /aw-spec-<command>`, so a lane's phases are reached as `ui-implement`, `ui-foundation`
+and so on. A flag would have no heading to key on.
+
+---
+
+## 2. `.appweaver/stacks.json`
+
+```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/",
+      "run_from": "root",
+      "build": "npm run build", "test": "npm test", "run": "npm run dev" }
+  ],
+  "prototype": { "root": "prototype/", "run": "npm run dev --prefix prototype" }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `id` | the lane's **role** in the project (`service`, `web`). Paths, rules and the constitution half hang off it. Defaults: `service` for backend, `web` for frontend |
+| `kind` | `backend` or `frontend` — selects which phases and which rule headings apply |
+| `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 |
+| `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) |
+| `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` writes only under a
+   backend lane's root, `ui-implement` only under a frontend lane's, `build`/`test`/`run`
+   act on it, and `onboard` reverse-engineers out of it.
+2. **The commands are project-supplied strings.** The engine stays stdlib-only and
+   stack-ignorant. This is how `build` already avoids knowing what a compiler is, and it
+   is the only thing that makes "any frontend stack" tractable.
+3. **`prototype` is not a lane.** It has a root and a run command so an operator can look
+   at it, and nothing else. It is never built by `build`, never tested by `analyze-slice`,
+   never deployed, and never gated.
+
+### 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.
+
+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.
+- **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
+
+`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.
+
+`lane-verify` is the check, and it runs where the path has to be real: before `implement`,
+`implement-delta`, `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
+nothing but code.
+
+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
+  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
+  writing into a directory it created by accident. The overlap check is a second reading of
+  a rule `lane-declare` already enforces, and it earns its place because a hand-edited file
+  never passes `lane-declare`.
+
+### The file ships empty, and may be filled in by hand
+
+The kit installs `.appweaver/stacks.json` holding `{"lanes": []}`, 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.
+
+**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
+the untouched seed, and `verify` raises the same "no lane is declared" issue it raises when
+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
+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
+surfaces as a wrong or empty stack later. Running `select-stack` once over a hand-written
+file re-checks all three.
+
+### Absence is not a valid state for a governed project
+
+`lane-resolve` still reports `declared: false` and exits 0 when the file is missing — reading
+is never fatal. What changed is that the phases which *act* on a lane no longer proceed
+without one. `constitution`, `onboard`, `implement`, `implement-delta`, `build` and `run` all
+call `lane-verify` and stop with the fix named, because each of them needs an answer this
+file is the only place to get: which lanes to govern, which subtree to scan, where to write.
+
+Declaring **`(none)`** for a lane is a real answer and the way a project says it has none.
+
+---
+
+## 3. The ownership rule
+
+**Lane roots own their subtree and must be disjoint.** Two generators must never be able
+to write the same file.
+
+`lane-declare` refuses a declaration whose root contains, or is contained by, another
+lane's — compared as `/`-terminated paths, so `src/` is clear of `src-gen/` but collides
+with `src/api/`. The refusal is a non-zero exit and **`stacks.json` is left untouched**.
+
+This is checked at declaration time on purpose. The alternative — discovering it when two
+implement phases fight over a file — is a much worse place to find out.
+
+---
+
+## 4. Stack profiles — `.appweaver/stack-profiles/*.json`
+
+One JSON file per selectable stack. `stack-list` enumerates them; this is the extension
+point, so **a project adds its own stack by dropping a file in here, never by editing a
+workflow.**
+
+```jsonc
+{
+  "id": "react-vite",                        // required — unique, and unique ACROSS kinds
+  "kind": "frontend",                        // required — backend | frontend
+  "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
+  "run_from": "root",                        // where the commands run — see §3.1
+  "build": "npm run build",
+  "test":  "npm test",
+  "run":   "npm run dev",
+  "migrate": "",                             // optional — schema migration, if the stack has one
+  "prototype_run": "npm run dev --prefix prototype",   // frontend only — fills the prototype block
+  "detect": ["web/package.json", "web/vite.config.*"]  // ANY-of markers — how stack-detect recognises this stack
+}
+```
+
+`id` and `kind` are required; a file missing either, or containing invalid JSON, is
+**skipped rather than fatal** — one bad profile must not make the menu unopenable.
+
+### 4.1 `ecosystem` — which stack-partitioned corpus this stack draws from
+
+`language` names what a person writes; `ecosystem` names the **toolchain family the kit
+partitions its corpora by**, and the two are not the same question. `dotnet-webapi` and
+`blazor-wasm` are C# and F#-adjacent respectively but share one ecosystem, `dotnet`; the five
+JavaScript frontends and `node-express` share `node`. It is the directory key for the two
+trees that are physically per-ecosystem:
+
+| Tree | Keyed by | Read through |
+|---|---|---|
+| `foundations/<ecosystem>/<Name>/` | `ecosystem` | `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 to the declared lanes' ecosystems, and reports `all_foundations` alongside so
+the gate can say *what exists and why none of it applies*. A repo that has declared nothing yet
+is not filtered — there is no answer to filter on.
+
+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`
+
+A profile command sometimes has to name the source path — `dotnet run --project src/`. 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:
+
+```jsonc
+"run":   "dotnet run --project {{root}}",   // Services/Api/ ⇒ dotnet run --project Services/Api
+"build": "python -m compileall {{root}}"    // repo-root lane ⇒ python -m compileall .
+```
+
+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*.
+
+`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
+coexist and no sniffer can pick between them, so a default here would be a guess dressed up as
+configuration. Declare it and `run-migrate` runs it in the lane's working directory like any
+other phase; leave it and `run-migrate` keeps its .NET `dotnet ef` path, reporting `ran:false`
+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
+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.
+
+**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
+files silently overrule an operator who named a stack on the command line. Leading the option
+list is the right strength for a proposal — it is what an interactive menu opens on and what
+`--non-interactive` takes, and both remain choices anyone can override.
+
+**Profile ids must be unique across kinds, not just within one.** The direct-argument fast
+path (`select-stack dotnet-webapi react-vite`) matches each id against its own kind's list,
+and that is what lets a single argument answer both selections unambiguously. An id
+appearing under two kinds breaks it.
+
+The menu label is `<id> — <title> (<language>)`, and the id is its leading token. That is
+the contract between `stack-list` and `lane-declare`: `--profile` accepts either a bare id
+or a full menu label.
+
+**The id is also what `lane-probe` looks for in free prose** — the whole id and its `-`/`_`
+parts of three characters or more, so `react-vite` is found by "react". `title` and `language`
+are deliberately *not* searched: "TypeScript", "Next" and "Web" all appear in ordinary prose
+about a backend, and the two errors are not symmetric. A false positive authors a governed file
+the project never asked for; a false negative only produces a warning that names the fix. Pick
+ids accordingly — a profile whose id is a common English word will be matched too eagerly.
+
+---
+
+## 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:
+
+```sh
+grep -rl "lane-declare" .appweaver/orchestrator/workflows/   # must print exactly one file
+#   aw-spec-select-stack.orch.yaml   — a person picks
+```
+
+`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
+never to overwrite a lane a person had confirmed. With the declaration now **required** at
+the top of `onboard` — it is what tells the scan which subtrees to read — that gate can
+never open, and the pass was re-deriving an answer the run already had. The detection moved
+to where a person can see it: `stack-list --suggest`, inside `select-stack`.
+
+The `origin` key stays in the schema and stays optional. Nothing writes
+`reverse-engineered` today; a future caller that proposes a lane without a person in the
+loop would, and readers that branch on it keep working.
+
+`lane-resolve` reads and can never write, which is why these are separate subcommands
+rather than one with a mode flag: a reader that could write, given the wrong argument,
+gives up the property. `lane-verify` cannot write either, and always exits 0 — the calling
+workflow's gate owns the stop, so the reason reaches it as text instead of as an exit code
+nobody sees.
+
+**A person with a text editor is not a violation of this** — it is the other supported way
+to fill the file in, and the kit ships it empty for that. "One writer" is a rule about the
+*kit*: no second workflow may reach in and set a lane behind the operator's back. What it
+costs is that a hand-edited file skips the writer's checks, which is why `lane-verify`
+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*.
+- **`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 —
+  reporting green for a frontend it never compiled.
+
+## 5a. What this file IS for
+
+**It records which lanes a project has.** That is its first job, and everything else
+follows from it:
+
+| Question | Answered by |
+|---|---|
+| Which constitution halves does this project ratify? | a declared service lane ⇒ `constitution.technical.md`; a declared UI lane ⇒ `constitution.ui.md`. `(none)` ⇒ no half, and no file |
+| 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 |
+
+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
+`## /aw-spec-ui-constitution` heading in the technical rule map, a frontend lane in this
+file, and a UI stack named in the request. A heuristic OR can only ever turn a lane **on**.
+It had no way to express *this project has no UI*, so a stale heading or the word "react" in
+a request authored a ratified governance file for a lane that does not exist.
+
+The declaration answers in both directions, and it is the same file `build`, `implement` and
+`onboard` are held to. So it decides — and the rule map goes back to doing the job it is
+good at: **supplying the rules a lane's half ratifies**, not asserting that the lane exists.
+A mapped `## /aw-spec-ui-constitution` with no declared lane is reported as an
+inconsistency, naming both fixes (declare the lane, or drop the mapping if it was retired).
+
+`stacks.json` also serves the steps a rule file cannot reach: `build`, `analyze-slice`, `run`
+and `deploy` shell out from `execute_script` steps, and a bash script cannot read a markdown
+rule. Supplying the commands here is what stops them guessing.
+
+Choosing `(none)` for either lane routes through the same writer, which is what makes a
+re-run correct: a lane declared in an earlier run is removed — along with the `prototype`
+block for a retired frontend — rather than left stranded.
+
+## 5b. The starting sequence
+
+`select-stack` is the **first command of both sequences**, and the setup order now has one
+constraint where it previously had none. That is a deliberate trade: what it buys is that
+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 → …
+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
+a person's confirmation, which is what detection on a legacy repo needs.
+
+## 6. Subcommands
+
+Deterministic work lives in `aw-spec-actions` — **a true bash + powershell pair.** Both
+shells delegate to `.appweaver/scripts/python/aw-stack.py`, so the JSON contract has one
+implementation and the twins cannot drift.
+
+| Subcommand | Does |
+|---|---|
+| `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-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` |
+
+Both `lane-declare` branches — declaring a lane and declaring `none` — emit the **same key
+set**, so a caller binds outputs without knowing which branch ran.
+
+### Which subcommands consume the lane model
+
+| Subcommand | With a declaration | With none |
+|---|---|---|
+| `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 declared lanes' `ecosystem` (§4.1) | unfiltered / `dotnet` |
+| `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
+only per-test selector any shipped profile has, and `analyze-slice`'s integrity fence depends
+on it together with the zero-match vacuous-pass guard. On every other stack the lane's whole
+declared suite runs and the result reports `scoped:false`, which over-includes — the safe
+direction, and the direction that command already documents. What it no longer does is report
+`fence_green:true` for a suite it never ran.
+
+---
+
+## 7. Adding a stack
+
+1. Write `.appweaver/stack-profiles/<id>.json` per §4 — including `ecosystem`.
+2. Re-run `/appweaver select-stack` — it appears in the menu.
+
+No workflow or script changes. If adding a stack ever requires touching a workflow, the lane
+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
+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
+  project tree and does not require that the kit created it.
+
+## 7a. Mapping rules to a stack without pinning the map to one
+
+`resolve-tech` reads the project's `tech-rule-bindings.md` and collects the `- ` bullets under
+`## /<command>`. A bullet may name its stack with a **placeholder**, resolved from the lanes in
+`stacks.json`:
+
+| Placeholder | Resolves to |
+|---|---|
+| `{{stack}}` | the **backend** lane's profile id — the unqualified form means the service lane |
+| `{{backend_stack}}` / `{{frontend_stack}}` | that lane's profile id |
+| `{{backend_ecosystem}}` / `{{frontend_ecosystem}}` | that lane's `ecosystem` |
+
+```md
+## /aw-spec-design
+- guardrails/technology/{{stack}}/persistence.md
+- guardrails/technology/{{frontend_stack}}/ui-constitution.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.
+
+**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
+`stack_mismatch: true` and `tech-select` asks before loading. These files become *sticky
+standards* — the generator follows them for the rest of the run — so a Spring project mapped to
+the .NET corpus is being told to write C# project layout for Java code. That is worth one
+question. It never fires on an unconfigured repo, a repo with no map, or a matching corpus.

package/assets/.appweaver/ai-rules.md

@@ -0,0 +1,180 @@
+# AI Operational Rules
+
+> **Kit-resident and universal.** These rules govern every aw-spec authoring step, on every flow —
+> greenfield, brownfield, migration — in every industry and on every technology stack. They are
+> loaded first, before any project rule file, and they hold for all of them.
+>
+> This file asserts **no principle, no architecture, no methodology, no technology and no domain
+> content**. Those reach a step through the project's own constitution and its mapped rule files,
+> which are loaded after this one and are more specific than it. Where a project rule is stricter,
+> the project rule governs; these rules are the floor, never the ceiling.
+
+## 1. Authority — what wins
+
+- The **loaded constitution is ground truth**. It overrides a pre-trained habit, a convention you
+  recognise, and any contradictory document found inside the repository.
+- Each phase names its **own upstream authority**, and that authority outranks your judgement:
+  forward, the spec governs the design and the design governs the code; in reverse, **the code is
+  the oracle** — where code and any document disagree, the code is right and the document is the
+  defect to be recorded.
+- **A rule you cannot point to in a loaded document is not a rule.** Recognition is not authority.
+  If you cannot name the file, id, or code path a statement comes from, it is your assumption and
+  must be labelled as one.
+
+## 2. Evidence
+
+- Author only what the loaded authority supports. Do **not** import a concept, identifier,
+  obligation, convention, or quality attribute that no loaded document carries — however standard
+  it is in your experience, and however plainly the project seems to need it.
+- **Ground each substantive assertion in its source**: the requirement id, the section heading, the
+  rule file, the code path. An assertion with no ground does not belong in the output.
+- State partial, stubbed, deferred, or absent behaviour **at the level the source actually
+  reaches**. Never assert the ideal a source does not meet; route the gap to whatever ledger the
+  phase provides for it.
+
+## 3. When the authority is silent
+
+- **Silence is a finding, not a licence.** Record it through the phase's own mechanism — an open
+  question, a deferral or assumption entry, an explicit `TODO(<field>): reason` — and continue.
+- Never resolve an ambiguity by inventing content, and never resolve one silently. A single
+  unrecorded guess in an early phase is ratified as fact by every phase after it.
+- If the missing input defeats the phase's purpose, **stop and say precisely what is missing**.
+  That is a better outcome than an artifact that looks complete.
+
+## 4. When the authority contradicts itself
+
+**Check first, before you act.** Every governance file your step needs is already in front of you —
+the rule set is assembled and loaded ahead of your first action. So this check costs nothing extra
+and belongs at the start: before beginning the work, confirm that the rules bearing on *what you
+are about to do* agree with one another. Scope it to the action, not to the corpus — the question
+is "do the loaded authorities give me one answer here, or two?", never "let me audit all governance
+first". A conflict found while planning costs a question; the same conflict found after the
+artifact exists costs the artifact, and every artifact downstream of it.
+
+- Two loaded documents can give incompatible instructions. **First apply the precedence in
+  *Authority*** — constitution over rule file, the phase's named upstream artifact over your
+  judgement, code over document in reverse. Most apparent conflicts are precedence and resolve
+  there; resolve them and proceed.
+- A **real conflict** is one precedence does not decide: two sources of equal standing, both
+  binding, that cannot both be satisfied. **Stop before acting.** Do not pick a winner, do not
+  split the difference, and do not proceed with whichever you find more reasonable — each of
+  those ratifies a governance decision no one made, in an artifact that will not show it was made.
+- State it so it can be settled without re-deriving it: each instruction, the file and heading it
+  comes from, and the specific action that cannot satisfy both. Then ask which governs, and propose
+  the correction you would make.
+- The instruction you were **given** is not exempt. If the request conflicts with loaded
+  governance, raise that before doing the work — being asked to do something is not authority to
+  do it.
+
+**Then one of four things happens, and none of them is you choosing.**
+
+- **Amended** — the reviewer accepts a correction to the governance. Apply it under *Feeding a
+  clarification back into governance*, then **stop the run and ask for it to be started again**.
+  Do not continue: your rule set was assembled from the governance as it stood, so continuing
+  would build under rules that no longer exist and credit the result to a rule that was never
+  applied. The re-run loads the amendment, and so does every later phase.
+- **Resolved without amendment** — the reviewer says the two do not in fact conflict, and names
+  which governs. That is an answer, not a refusal: proceed under it, and record the resolution and
+  who gave it in the phase's own ledger so the next reader does not re-derive the question.
+- **Declined** — the reviewer rejects your correction and the conflict stands. **Stop**, naming
+  both sources and the exact incompatibility, so it can be settled in the governance itself and the
+  workflow started again. A rejected wording does not make a conflict go away.
+- **Unanswered** — no reviewer, no reply, or an unattended run: **stop.** Never settle it yourself,
+  and never at random. A random choice cannot be reproduced, has no owner, and leaves no trace in
+  the artifact — which is exactly what makes a conflicted artifact unrecoverable months later. A
+  halted pipeline is a signal someone can act on. If the project must proceed anyway, that is a
+  human's decision to make and to own: they name which source governs **for this run only**, and
+  you record it in the phase's ledger as an unratified choice for the next phase to see. One named
+  override is recoverable; an unattributable guess is not.
+
+## 5. Shape versus content
+
+- **A template is shape.** Copy its headings, ordering, granularity and tone. Never copy its
+  examples, its bracketed tokens, or its illustrative lists as though they were this project's
+  values. An example carried into an authored file becomes ratified law in a project it does not
+  fit — this is the most expensive mistake available to you here.
+- **Fill every placeholder the template defines**, or replace it with an explicit, justified
+  deferral. A leftover token can exclude the whole file from downstream assembly.
+- Refer to a section of another document **by its heading**, never by its number. Numbering differs
+  between templates and between flows; headings do not.
+- Cite a principle by **the numeral the loaded constitution actually carries**. Principle numbering
+  is derived per project — a numeral remembered from another constitution is simply wrong.
+
+## 6. Scope
+
+- Write only the **declared output target**. No drive-by edits to unrelated files, no opportunistic
+  refactor, no reformatting of what you did not change.
+- Create files only where the phase says you may. A new location is an amendment to request, not a
+  convenience to take.
+- Do not add a dependency, an abstraction layer, or an indirection the authority does not call for.
+  A wrapper with one implementation is scope creep wearing the costume of craft.
+- Keep an authored change **self-contained**: the artifact, the tests the phase asks for, and the
+  bookkeeping it names — nothing else.
+
+## 7. Determinism
+
+- Where a deterministic script owns a value, **never write it by hand**: versions, generated
+  identifiers, pipeline-stamped dates, and any counter or index a script maintains.
+- **Never edit generated bookkeeping to make a check pass.** A failing check is information; a
+  check edited into passing is a defect with the evidence removed.
+
+## 8. Reporting
+
+- Report **what happened, not what should have happened**. If a step failed, say so and include its
+  output. If a step was skipped, say it was skipped.
+- Never report a gate as passed by inference. *Passed* means the gate ran and returned a pass.
+- Do not pad an artifact to look finished. **A short, honest document a later phase can extend is
+  correct; a full one containing invention is not.**
+
+## 9. Refuse and ask
+
+Refuse, and ask for clarification, when a request would:
+
+- violate a principle the loaded constitution marks **NON-NEGOTIABLE**;
+- embed a secret, credential, connection string, key, or production hostname in code, in
+  configuration, or in a document;
+- disable, weaken, or globally bypass an access, tenancy, audit, retention, or data-protection
+  control that is in place;
+- require inventing domain content, a regulatory claim, or a behavioural guarantee that no loaded
+  document supports;
+- take an **irreversible action against a shared or production environment** — including running,
+  rather than authoring, a data migration.
+
+## 10. Feeding a clarification back into governance
+
+A question worth asking once is worth answering permanently — left in a conversation, the same
+ambiguity reaches the next run and is re-decided, differently. So a resolved clarification **may**
+be written back into the governance that was unclear. This is the highest-privilege act available
+to you here: you are editing the rules that govern you. Every condition below holds together, and
+none of them substitutes for another.
+
+- **Propose; never apply.** You draft the wording and the evidence for it. A human ratifies it. You
+  are never both the proposer and the approver, and silence is never approval.
+- **Never to unblock yourself.** A rule that is blocking you *now* is not amendable by you *now*.
+  Complete or stop the current work under the rule as written, and raise the amendment separately,
+  afterwards. This single condition is why this section is written as tightly as it is.
+  A stated conflict is the one case where the amendment is raised mid-run, and it does not weaken
+  the rule: the run **stops** on applying it rather than continuing, so you still never act under
+  governance you have just changed. Stopping is what separates a correction from a convenience.
+- **Clarification, not extension.** A clarification records what the governance already meant, for
+  a case it did not spell out. Anything that changes what is **permitted, required or forbidden**
+  is an amendment, and an amendment goes through the project's own change process — never through
+  this route wearing the word *clarify*.
+- **Establish the blast radius, and show it.** Name every command that loads the file — the rule
+  maps record which — every document that cites it, and every workflow whose behaviour would
+  change. *"It conflicts with nothing"* is a claim to be evidenced, not an assurance to be offered.
+- **Amend the file that was ambiguous.** Not a more convenient one, and never a second copy that
+  will drift from the first.
+- **Record its provenance** wherever that file records change: the question that prompted it, the
+  resolution, who approved it, and when. A rule whose origin is unrecorded cannot later be told
+  apart from one an agent invented.
+- **These operating rules are never amendable from inside a run** — not by any agent, for any
+  reason, however well evidenced. This file belongs to the kit, not to a project. A project needing
+  different behaviour adds its own rules, which load after these and are more specific.
+
+---
+
+Everything specific to a **technology, a stack, an industry or a domain** — generation conventions,
+folder and naming rules, data-handling and terminology obligations, and any further refusal
+conditions — is the **project owner's to supply**, and reaches a step through the active domain
+pack and its rule maps. Those rules **add to** these; they never relax them.

package/assets/.appweaver/domain.json

@@ -0,0 +1 @@
+{"domain":""}