aw-spec-cli 0.1.26 → 0.1.28

package/assets/foundations/node/NextAppRouter/NextAppRouter.spec.txt

@@ -0,0 +1,68 @@
+# kind: frontend
+# profiles: nextjs
+# title: Next.js App Router base (TypeScript, ESLint, Vitest) built from this spec
+
+# Next.js App Router foundation — frontend lane
+
+## Purpose
+A clean, building Next.js frontend for the lane: App Router, TypeScript in strict mode,
+ESLint, a token-based design-system layer and a working test setup. No business screens —
+/appweaver implement adds those per feature later, from frontend-plan.md.
+
+## Create
+Run at the repository root, naming the lane root folder, so the app lands directly in that
+folder (not in a folder inside or beside it):
+- `npx create-next-app@latest <lane root folder without trailing slash> --typescript --eslint --app --no-src-dir --import-alias "@/*" --use-npm --no-tailwind --yes`
+Set `"name"` in package.json to the project name in lower-kebab form
+(e.g. AppWeaver.Health -> appweaver-health).
+
+## Packages
+Development dependencies:
+- vitest, @vitejs/plugin-react, jsdom
+- @testing-library/react, @testing-library/jest-dom, @testing-library/user-event
+- vitest-axe (accessibility assertions)
+
+## Layout
+Under the lane root folder (create empty folders with a .gitkeep):
+```
+app/                  App Router — layout.tsx, page.tsx, loading.tsx, error.tsx, not-found.tsx
+components/           design-system compositions, presentational only
+features/             one folder per spec feature (empty at start)
+lib/api/              the generated contract client (empty at start — never hand-written)
+lib/                  cross-feature client utilities
+locales/              locale catalogues — en.json to start
+styles/tokens.css     the semantic design tokens
+tests/                component, integration and accessibility tests
+```
+
+## Starter files
+- `styles/tokens.css` — semantic CSS custom properties only (`--color-surface`,
+  `--color-text`, `--color-muted`, `--color-danger`, `--space-1..6`, `--radius-1..3`,
+  `--font-body`), with a `prefers-color-scheme: dark` block. Imported once by
+  `app/layout.tsx`; no literal colour anywhere else.
+- `app/layout.tsx` — html `lang` from the default locale, the tokens import, a skip-to-content
+  link, `<main id="main">`.
+- `app/page.tsx` — a server component rendering the app name and one line of text.
+- `app/loading.tsx`, `app/error.tsx` (client component with a retry button), `app/not-found.tsx`.
+- `components/Button.tsx` — one presentational component styled only with tokens, as the
+  pattern later components follow.
+- `lib/env.ts` — reads `NEXT_PUBLIC_API_BASE_URL` once and exports it typed; nothing else
+  reads `process.env`.
+- `locales/en.json` — the strings the starter pages use.
+- `.env.example` — `NEXT_PUBLIC_API_BASE_URL=http://localhost:5000`.
+Remove the create-next-app demo content (the default page body, its CSS module and images).
+
+## Configuration
+- `tsconfig.json`: `"strict": true`, keep the `@/*` alias.
+- `vitest.config.ts`: jsdom environment, the React plugin, `tests/setup.ts` as setup file
+  (registers jest-dom and vitest-axe matchers), the `@/*` alias.
+- package.json scripts: `dev`, `build`, `start`, `lint` (from create-next-app), plus
+  `"test": "vitest run"` and `"typecheck": "tsc --noEmit"`.
+
+## Tests
+- `tests/page.test.tsx` — renders the home page and asserts the app name is shown.
+- `tests/button.a11y.test.tsx` — renders `Button` and asserts no axe violations.
+
+## Done when
+`npm install`, `npm run build`, `npm test` and `npm run lint` all pass in the lane root
+folder, and `npm run dev` serves the home page at http://localhost:3000.

package/assets/guardrails/README.md

@@ -13,27 +13,39 @@ guardrails/
 ├── domain/<industry>/        domain rules — vary by industry, never by stack
 │   ├── healthcare/
 │   └── pharma/
-└── projects/<project>/       what a project SELECTS
-    └── dotnet-default-project/
-        ├── tech-rule-bindings.md      → technology/dotnet-webapi/ + technology/nextjs/
-        ├── domain-rule-bindings.md    → domain/healthcare/
-        ├── service/technical-requirements.md    PROJECT-SUPPLIED
-        ├── frontend/ui-requirements.md          PROJECT-SUPPLIED
-        └── domain/domain-requirements.md        PROJECT-SUPPLIED
+├── project-specific/         the project's own rules — what it SELECTS from the corpora
+│   ├── tech-rule-bindings.md      → technology/{{backend_stack}}/ + technology/{{frontend_stack}}/
+│   ├── domain-rule-bindings.md    → domain/healthcare/
+│   ├── service/technical-requirements.md    PROJECT-SUPPLIED
+│   ├── frontend/ui-requirements.md          PROJECT-SUPPLIED
+│   └── domain/domain-requirements.md        PROJECT-SUPPLIED
+└── brf-<name>/               a project `onboard` reverse-engineers from existing code
 ```
 
-`/appweaver select-domain` selects a **project** folder and stores it in `.appweaver/domain.json`;
-`resolve-tech` and `resolve-domain` read that project's two maps. **To change what a command loads,
-edit the map — never a workflow.** The folder names `technology/` and `domain/` are the only
+**The active project is the folder `.appweaver/domain.json` names** — `project-specific` as shipped,
+and `brf-<name>` once `onboard` has run, because onboard creates that folder and writes its name
+there. No sequence selects a project. To use another one, copy `project-specific/` to a new folder
+here, change the `guardrails/project-specific/` paths inside its two maps to the new folder, and run
+the optional `/appweaver select-domain <name>` — it lists the folders here that hold a map and
+writes the one picked into `domain.json` (editing `"domain"` by hand does the same). It never
+creates a folder. Re-run `/appweaver constitution` after switching so the constitution follows.
+`resolve-tech` and `resolve-domain` read the active project's two maps. **To change what a command
+loads, edit the map — never a workflow.** The folder names `technology/` and `domain/` are the only
 vocabulary here: a project's maps may point anywhere, in any combination.
 
-**A directory under `projects/` is a project only if it carries a rule map.** Both shells'
-`list-domains` enforces that, exactly as `foundations/` requires a `*.pack.txt`. Either map
+**A directory under `guardrails/` is a project only if it carries a rule map.** Both shells'
+`list-domains` enforces that, exactly as `foundations/` requires a `*.pack.txt` or `*.spec.txt` — the
+corpora `technology/` and `domain/` carry no map, so they are never taken for a project. Either map
 qualifies, because `onboard` writes the domain map several steps before the technical one.
 
-**A brownfield project owns its rules outright.** `dotnet-default-project` above holds only three
+**The technical map names no stack.** Every path in `project-specific/tech-rule-bindings.md` writes
+its stack directory as `{{backend_stack}}` or `{{frontend_stack}}`, resolved from the lanes in
+`.appweaver/stacks.json`, so the same map serves a .NET repo and a Spring one. A corpus that lacks a
+mapped file reports it as missing and loads nothing in its place.
+
+**A brownfield project owns its rules outright.** `project-specific/` above holds only three
 files because it maps the rest from the shared corpora. A project `onboard` reverse-engineers —
-`projects/brf-<name>/` — holds everything: the domain set in `domain/`, the technical set in
+`brf-<name>/` — holds everything: the domain set in `domain/`, the technical set in
 `service/`, the lane set in `frontend/`, and its own charter at `domain/domain-constitution.md`,
 named the way an industry corpus names its charter. Both maps still sit at the project root, and
 nothing a project owns is written outside its own folder — which is what lets two onboarded
@@ -91,7 +103,7 @@ is what lists it. Infer the tier from the folder and the fold breaks.
   `stacks.json` and a rule folder are the same word.
 - **An industry** — create `domain/<industry>/`, author the overlays, point a project's
   `domain-rule-bindings.md` at it. The technical map needs no edit.
-- **A project** — copy `projects/dotnet-default-project/`, repoint the bullets, replace the three
+- **A project** — fill in `project-specific/`: repoint the bullets and replace the three
   project-supplied files. Nothing outside that folder changes.
 
 ## Files — technical (`technology/dotnet-webapi/`)
@@ -214,8 +226,10 @@ Everything this tree once held that governance does not load left it on 2026-08-
 `foundations/<stack>/`:
 
 - **Scaffold corpora** — `foundations/dotnet/ModularMonolith/` and `foundations/dotnet/VerticalSlice/`:
-  a `<Name>.pack.txt` payload and the scripts that pack and unpack it, read by
-  `/appweaver foundation`.
+  a `<Name>.pack.txt` payload and the scripts that pack and unpack it; and specs —
+  `foundations/node/NextAppRouter/NextAppRouter.spec.txt` — that describe a project an agent
+  builds into the lane. Both read by `/appweaver foundation`; the shape of a spec is
+  `foundations/foundation.spec.template.txt`.
 - **Framework component runbooks** — `foundations/dotnet/components/`: the integration contracts
   `/appweaver add-component` follows when wiring an opt-in component into a scaffolded project.
 

package/assets/guardrails/{projects/dotnet-default-project → project-specific}/domain-rule-bindings.md

@@ -1,4 +1,4 @@
-# dotnet-default-project — Command → Domain-Rule-File Map
+# project-specific — Command → Domain-Rule-File Map
 
 Per-command list of the **domain** rule files this project loads (via `resolve-domain`
 + the `domain-select` module, into the sticky standards set) for the spec-anchored
@@ -19,8 +19,8 @@ through the spec/design (as CN-/DC-/IC- ids).
 - To govern a different industry, repoint these bullets at another
   `guardrails/domain/<industry>/` corpus — `guardrails/domain/pharma/` also ships. Nothing
   else changes: the technical map, the workflows and the engine are untouched.
-- This file is the **canonical domain mapping** for this project; `/appweaver
-  select-domain` selects this project folder as active.
+- This file is the **canonical domain mapping** for this project; it is used whenever
+  `.appweaver/domain.json` names `project-specific`, which it does by default.
 
 ---
 
@@ -49,12 +49,12 @@ through the spec/design (as CN-/DC-/IC- ids).
 - guardrails/domain/healthcare/zero-trust.domain.md
 - guardrails/domain/healthcare/ai-rules.domain.md
 - guardrails/domain/healthcare/folder-structure.domain.md
-- guardrails/projects/dotnet-default-project/domain/domain-requirements.md
+- guardrails/project-specific/domain/domain-requirements.md
 
 ## /aw-spec-specify
 <!-- The FULL domain set. Specify models the domain COMPLETELY and LIFTS the constraint
      overlays into the spec's CN-/DC-/IC- sections (design/implement never see these files). -->
-- guardrails/projects/dotnet-default-project/domain/domain-requirements.md
+- guardrails/project-specific/domain/domain-requirements.md
 - guardrails/domain/healthcare/domain-driven-design.domain.md
 - guardrails/domain/healthcare/clinical-terms.md
 - guardrails/domain/healthcare/terminology.md
@@ -74,12 +74,22 @@ through the spec/design (as CN-/DC-/IC- ids).
 - guardrails/domain/healthcare/api-versioning.domain.md
 - guardrails/domain/healthcare/vertical-slices.domain.md
 
-## /aw-spec-plan
-_None — design loads no domain file. Domain reaches design only through the spec (BR-/CN-/DC-/IC-)._
+## /aw-spec-plan-backend
+_None — the service lane of plan loads no domain file. Domain reaches it only through the spec
+(BR-/CN-/DC-/IC-) and the context's domain-model.md._
 
-## /aw-spec-implement
-_None — implement loads no domain file. Domain reaches implement only through design.md. Framework
-components are added separately via `/appweaver add-component`._
+## /aw-spec-plan-frontend
+_None — the frontend lane of plan loads no domain file. Domain reaches it only through the spec
+and the context's domain-model.md._
+
+## /aw-spec-implement-backend
+_None — the service lane of implement loads no domain file. Domain reaches it only through
+backend-plan.md and the context's domain-model.md. Framework components are added separately via
+`/appweaver add-component`._
+
+## /aw-spec-implement-frontend
+_None — the frontend lane of implement loads no domain file. Domain reaches it only through
+frontend-plan.md and the context's domain-model.md._
 
 ## /aw-spec-gate
 <!-- Conformance checklist for the gates (analyze-plan · analyze-slice): the domain-derived
@@ -106,10 +116,12 @@ components are added separately via `/appweaver add-component`._
 
 | Command | Domain rule files | Role |
 |---|---|---|
-| /aw-spec-constitution | 14 | domain principles (XVI+) — the industry constitution + standard industry rules + the project's own requirements |
+| /aw-spec-constitution | 16 | domain principles (XVI+) — the industry constitution + standard industry rules + the project's own requirements |
 | /aw-spec-specify | 19 | author into spec (lift → CN-/DC-/IC-) |
-| /aw-spec-plan | 0 | none — spec is the only domain input |
-| /aw-spec-implement | 0 | none — design is the only domain input |
+| /aw-spec-plan-backend | 0 | none — the spec and the domain model carry the domain |
+| /aw-spec-plan-frontend | 0 | none — the spec and the domain model carry the domain |
+| /aw-spec-implement-backend | 0 | none — backend-plan.md and the domain model carry the domain |
+| /aw-spec-implement-frontend | 0 | none — frontend-plan.md and the domain model carry the domain |
 | /aw-spec-gate | 14 | conformance checklist (validate, don't author) |
 
 > Retired in the orchestrator pipeline: the prose `/aw-spec-plan` phase, `/aw-spec-tasks`,

package/assets/guardrails/project-specific/tech-rule-bindings.md

@@ -0,0 +1,296 @@
+# project-specific — Command → Technical-Rule-File Map
+
+Per-command list of the **technical** rule files this project loads (via `resolve-tech` +
+the `tech-select` module, into the sticky standards set) for the spec-anchored
+orchestrator pipeline. This is the technical counterpart of `domain-rule-bindings.md`
+(which maps the DOMAIN rule files).
+
+**The model:** the technical rule files are CONFIGURATION — tune this map, not the
+workflows. They live in the **shared technology corpora**, one folder per stack, and this
+map is what binds a project to them. The ratified output (`constitution.technical.md`) is
+NOT listed here — every consumer refers to it directly, as-is.
+
+- All paths are workspace-relative. This project maps two stack corpora:
+  `guardrails/technology/{{backend_stack}}/` (the service) and
+  `guardrails/technology/{{frontend_stack}}/` (the frontend lane). Both are **standard rules
+  shared by every project that maps them**, and neither is domain-specific. The frontend corpus is
+  read by four headings — `## /aw-spec-ui-constitution` ratifies the lane's base,
+  `## /aw-spec-plan-frontend` / `## /aw-spec-implement-frontend` carry the detail rules under
+  it, and `## /aw-spec-foundation-frontend` is what a spec-built scaffold of the lane follows.
+- `plan`, `implement` and `foundation` are keyed per lane KIND, not per command: each runs
+  both lanes in one run and loads one set or the other for each — `## /aw-spec-<command>-backend`
+  for the service lane, `## /aw-spec-<command>-frontend` for the frontend lane. `foundation`
+  loads its set only when the lane is built from a spec — a pack is unpacked as-is.
+- The two files this project authors — `service/technical-requirements.md` and
+  `frontend/ui-requirements.md` — live beside this map. They are the only mapped technical
+  files expected to differ between two projects on the same stacks.
+- A corpus's `examples/` folder holds the worked `<SampleProjectName>` sample for the
+  rule file beside it, split out so a phase can load the rules without the sample code. The
+  code-generating phases map both; `## /aw-spec-constitution` maps the rules alone, because a
+  thin authority document has no use for sample code.
+- `resolve-tech --command <name>` collects the `- ` bullets under `## /<name>`.
+- **Every stack directory below is a placeholder**, resolved from the lanes in
+  `.appweaver/stacks.json`: `{{backend_stack}}` is the service lane's stack and
+  `{{frontend_stack}}` the frontend lane's (`{{stack}}`, `{{backend_ecosystem}}` and
+  `{{frontend_ecosystem}}` are also available). `guardrails/technology/{{backend_stack}}/persistence.md`
+  reads as `dotnet-webapi/` in a .NET repo and `java-spring/` in a Spring one, so this one map
+  serves whatever stacks the project declares. A placeholder for an undeclared lane skips
+  that bullet, so a backend-only repo loads no frontend rules. A resolved path with no file
+  on disk is reported as missing and loads nothing in its place. The bullets were written
+  against the `dotnet-webapi` and `nextjs` corpora; another stack's corpus may hold only
+  part of them. See STACK-PROFILES.md §7a.
+- Adding a stack is adding a corpus under `guardrails/technology/<stack>/` with the same file
+  names — the placeholders then reach it with no change to this map, and no workflow, script
+  or engine change is involved.
+- This file is the **canonical technical mapping** for this project; it is used whenever
+  `.appweaver/domain.json` names `project-specific`, which it does by default.
+- A command with no heading here loads no mapped technical file (only the workflow's
+  universal `ai-rules.md` seed + `constitution.technical.md`, referred to directly).
+- `## /aw-spec-specify` is the one **modelling-methodology** slot (see the rule partition):
+  a domain-agnostic way of *modelling*, never a technology choice. Everything below it is a
+  HOW-phase technical set.
+
+---
+
+## /aw-spec-specify
+<!-- MODELLING METHODOLOGY ONLY, in two halves. Specify is the domain phase: the single kind
+     of technical input it may take is a domain-agnostic way of MODELLING, never a technology
+     choice. Do NOT add an architecture / persistence / codegen file here — that would break
+     specify's domain purity (design/implement own those). The domain's own DDD overlay
+     (domain-driven-design.domain.md) arrives separately via domain-rule-bindings.
+
+     1. THE DOMAIN MODEL — DDD tactical patterns, plus the same methodology worked through
+        in code as the example beside it.
+     2. THE EXPERIENCE MODEL — the ux/ rules that govern how specify states the experience:
+        Experience Scope, and the project-wide Experience Standards it lifts as UX- ids for
+        prototype / design-ui / implement-ui to author and verify against. These are
+        methodology, not visual design; each file's own "What must NOT appear" section is
+        what keeps screens out of the spec.
+
+     ⚠ The ux/ files sit in a DOMAIN corpus folder but are TECHNICAL-tier inputs: a file's
+     tier is the map that lists it, not the folder it lives in. guardrails/domain/healthcare/
+     ihe-conformance.md under ## /aw-spec-plan-backend is the same pattern. Unmapping them does not
+     make the spec's Experience Standards section disappear — the section is unconditional and
+     resolves to "None" — it removes the methodology specify fills it from. -->
+- guardrails/technology/{{backend_stack}}/domain-driven-design.md
+- guardrails/technology/{{backend_stack}}/examples/domain-driven-design.md
+- guardrails/domain/healthcare/ux/journey-mapping.md
+- guardrails/domain/healthcare/ux/interaction-states.md
+- guardrails/domain/healthcare/ux/accessibility-standards.md
+- guardrails/domain/healthcare/ux/content-design.md
+
+## /aw-spec-plan-backend
+<!-- The technical/architecture rule files the design author works from (alongside the
+     spec and constitution.technical.md), each followed by its worked example. NO domain file
+     here — domain reaches design only as spec ids (BR-/CN-/DC-/IC-). -->
+- guardrails/technology/{{backend_stack}}/clean-architecture.md
+- guardrails/technology/{{backend_stack}}/cqrs.md
+- guardrails/technology/{{backend_stack}}/eventing.md
+- guardrails/technology/{{backend_stack}}/modular-monolith.md
+- guardrails/technology/{{backend_stack}}/vertical-slices.md
+- guardrails/technology/{{backend_stack}}/persistence.md
+- guardrails/technology/{{backend_stack}}/folder-structure.md
+- guardrails/technology/{{backend_stack}}/testing.md
+- guardrails/technology/{{backend_stack}}/api-versioning.md
+- guardrails/technology/{{backend_stack}}/zero-trust.md
+- guardrails/technology/{{backend_stack}}/authorization.md
+- guardrails/technology/{{backend_stack}}/authorization-matrix.md
+- guardrails/technology/{{backend_stack}}/auditing.md
+- guardrails/technology/{{backend_stack}}/data-classification.md
+- guardrails/domain/healthcare/ihe-conformance.md
+- guardrails/technology/{{backend_stack}}/examples/clean-architecture.md
+- guardrails/technology/{{backend_stack}}/examples/cqrs.md
+- guardrails/technology/{{backend_stack}}/examples/eventing.md
+- guardrails/technology/{{backend_stack}}/examples/vertical-slices.md
+- guardrails/technology/{{backend_stack}}/examples/persistence.md
+- guardrails/technology/{{backend_stack}}/examples/api-versioning.md
+- guardrails/technology/{{backend_stack}}/examples/zero-trust.md
+- guardrails/technology/{{backend_stack}}/examples/authorization.md
+- guardrails/technology/{{backend_stack}}/examples/auditing.md
+
+## /aw-spec-plan-frontend
+<!-- The FRONTEND LANE's design phase. Its own heading, not a branch of ## /aw-spec-plan-backend:
+     the two lanes are governed by different constitution halves and own disjoint source
+     paths, so keying the map on a heading of its own gives the lane its own rule set for zero
+     mechanism change. NO domain file here — the domain reaches design.ui.md as spec ids,
+     exactly as it reaches design.md. The lane's ratified base (constitution.ui.md) is
+     referred to directly and is NOT mapped.
+
+     THE SERVICE LANE ENTERS THROUGH ONE FILE. api-integration.{{backend_stack}}.md is the
+     CROSS-LANE pairing rule set — what the service guarantees (paging shape, concurrency
+     token, error codes, redaction, caching, CORS) and what the client therefore must do.
+     It is named for the service stack and mapped through the placeholder, so ONE bullet
+     serves every backend: it resolves to api-integration.dotnet-webapi.md in a .NET repo and to
+     api-integration.java-spring.md in a Spring repo — both authored — and to a REPORTED
+     missing file for a backend whose pairing nobody has written yet, rather than silently
+     loading one stack's assumptions into another. A repo with no backend lane skips the
+     bullet entirely. No other service-lane file is mapped here: design.ui.md consumes the
+     published surface, never the service's internals. -->
+- guardrails/technology/{{frontend_stack}}/component-architecture.md
+- guardrails/technology/{{frontend_stack}}/routing-navigation.md
+- guardrails/technology/{{frontend_stack}}/state-management.md
+- guardrails/technology/{{frontend_stack}}/error-handling.md
+- guardrails/technology/{{frontend_stack}}/forms-and-validation.md
+- guardrails/technology/{{frontend_stack}}/auth-session.md
+- guardrails/technology/{{frontend_stack}}/design-system.md
+- guardrails/technology/{{frontend_stack}}/accessibility-implementation.md
+- guardrails/technology/{{frontend_stack}}/i18n.md
+- guardrails/technology/{{frontend_stack}}/performance-budgets.md
+- guardrails/technology/{{frontend_stack}}/api-integration.{{backend_stack}}.md
+
+## /aw-spec-implement-backend
+<!-- The FRAMEWORK / code-generation rule files the SERVICE lane's generator builds against
+     (alongside backend-plan.md and constitution.technical.md). It is loaded on BOTH paths,
+     master and delta: a change's code follows the same rules as the master it changes.
+     NO domain file — domain reaches implement only through the plan (on the delta path, the
+     master backend-plan.md + the change's delta plan). clean-architecture/cqrs are planning
+     concerns; component wiring is a separate /appweaver add-component step. -->
+- guardrails/technology/{{backend_stack}}/coding-standards.md
+- guardrails/technology/{{backend_stack}}/dependency-policy.md
+- guardrails/technology/{{backend_stack}}/folder-structure.md
+- guardrails/technology/{{backend_stack}}/framework-api-map.md
+- guardrails/technology/{{backend_stack}}/testing.md
+- guardrails/technology/{{backend_stack}}/PACKAGING.md
+
+## /aw-spec-implement-frontend
+<!-- The FRONTEND LANE's code-generation set — the HOW that lane of `implement` builds
+     against, alongside frontend-plan.md and constitution.ui.md. It is loaded on BOTH paths,
+     master and delta, as the service lane's set is. NO domain file
+     (domain reached the lane through spec -> frontend-plan.md), and NO service-lane file
+     beyond the pairing rules below — this lane never writes outside its declared lane root folder.
+
+     EIGHT FILES ARE MAPPED FOR BOTH LANE PHASES on purpose. error-handling,
+     forms-and-validation, auth-session, design-system, accessibility-implementation, i18n,
+     performance-budgets and the api-integration pairing each carry a DESIGN half and an
+     IMPLEMENT half of one rule: the design decides the states, the affordances and the
+     targets; this phase realises them. A rule read by only one of the two loses the
+     pairing, and the half that goes unread is always the one that then goes unbuilt. -->
+- guardrails/technology/{{frontend_stack}}/component-conventions.md
+- guardrails/technology/{{frontend_stack}}/api-client.md
+- guardrails/technology/{{frontend_stack}}/api-integration.{{backend_stack}}.md
+- guardrails/technology/{{frontend_stack}}/auth-session.md
+- guardrails/technology/{{frontend_stack}}/client-security.md
+- guardrails/technology/{{frontend_stack}}/error-handling.md
+- guardrails/technology/{{frontend_stack}}/forms-and-validation.md
+- guardrails/technology/{{frontend_stack}}/design-system.md
+- guardrails/technology/{{frontend_stack}}/accessibility-implementation.md
+- guardrails/technology/{{frontend_stack}}/i18n.md
+- guardrails/technology/{{frontend_stack}}/performance-budgets.md
+- guardrails/technology/{{frontend_stack}}/observability.md
+- guardrails/technology/{{frontend_stack}}/frontend-testing.md
+
+## /aw-spec-build
+<!-- The compile/fix reference set: the layering + coding rules the fixer respects when
+     repairing compile errors against the design intent, plus the layering example it repairs
+     towards. NO domain file (build loads domain rules separately via domain-select) and no
+     constitution.technical here. -->
+- guardrails/technology/{{backend_stack}}/clean-architecture.md
+- guardrails/technology/{{backend_stack}}/coding-standards.md
+- guardrails/technology/{{backend_stack}}/examples/clean-architecture.md
+
+## /aw-spec-analyze-slice
+<!-- The design↔code conformance gate's TECHNICAL checklist: the code + tests are
+     validated against these (alongside the DOMAIN gate overlays, loaded separately via
+     resolve-domain `## /aw-spec-gate`). Validation input only — never authoring. -->
+- guardrails/technology/{{backend_stack}}/testing.md
+- guardrails/technology/{{backend_stack}}/coding-standards.md
+- guardrails/technology/{{backend_stack}}/framework-api-map.md
+
+## /aw-spec-constitution
+<!-- What the TECHNICAL half of the split constitution ratifies into
+     constitution.technical.md: the technology base, then the STANDARD technical rules for
+     this industry — the same corpus design and implement build against, so a ratified
+     principle can cite the rule it governs — and last the PROJECT-SUPPLIED file the project
+     team authors. Loaded BEFORE the technical half and before domain-select, so the
+     technical author stays domain-free (the seam). NO domain file here: the domain half's
+     sources are the domain map's ## /aw-spec-constitution. NO examples/ file either — the
+     ratified half is one declarative line and a `→` pointer per principle, so sample code is
+     weight without a reader. -->
+- guardrails/technology/{{backend_stack}}/technology-constitution.md
+- guardrails/technology/{{backend_stack}}/clean-architecture.md
+- guardrails/technology/{{backend_stack}}/modular-monolith.md
+- guardrails/technology/{{backend_stack}}/vertical-slices.md
+- guardrails/technology/{{backend_stack}}/domain-driven-design.md
+- guardrails/technology/{{backend_stack}}/cqrs.md
+- guardrails/technology/{{backend_stack}}/persistence.md
+- guardrails/technology/{{backend_stack}}/eventing.md
+- guardrails/technology/{{backend_stack}}/folder-structure.md
+- guardrails/technology/{{backend_stack}}/testing.md
+- guardrails/technology/{{backend_stack}}/zero-trust.md
+- guardrails/technology/{{backend_stack}}/authorization.md
+- guardrails/technology/{{backend_stack}}/auditing.md
+- guardrails/technology/{{backend_stack}}/data-classification.md
+- guardrails/technology/{{backend_stack}}/api-versioning.md
+- guardrails/technology/{{backend_stack}}/coding-standards.md
+- guardrails/technology/{{backend_stack}}/dependency-policy.md
+- guardrails/project-specific/service/technical-requirements.md
+
+## /aw-spec-ui-constitution
+<!-- What the UI half ratifies into constitution.ui.md as a UX-* principle series: the
+     standard frontend rules for this industry, then the PROJECT-SUPPLIED file. This heading
+     is also the AUTHORITATIVE signal that the project HAS a frontend lane — with no heading
+     here the constitution command skips the UI half and creates no file at all. Domain-free,
+     and loaded before domain-select for the same reason as the set above. -->
+- guardrails/technology/{{frontend_stack}}/ui-constitution.md
+- guardrails/project-specific/frontend/ui-requirements.md
+
+## /aw-spec-run
+<!-- Execution / data migration: the persistence rules the migration step generates against,
+     plus their worked example. NO domain file; run does not reference constitution.technical.md. -->
+- guardrails/technology/{{backend_stack}}/persistence.md
+- guardrails/technology/{{backend_stack}}/examples/persistence.md
+
+## /aw-spec-foundation-backend
+<!-- What `foundation` builds the SERVICE lane's base project against when the operator picks
+     a spec ([spec] or [manual spec]) instead of a pack. A pack is verified against these rules
+     when it is made; a spec build is not, so the agent gets them as standards and follows them
+     wherever the spec is silent. The set is the SHAPE of a base project — stack base, folder
+     structure, packages, coding and test conventions, the framework's own types, and the
+     project team's technical requirements — not the architecture/persistence detail set plan
+     and implement load for features. NO domain file: a scaffold has no domain yet. -->
+- guardrails/technology/{{backend_stack}}/technology-constitution.md
+- guardrails/technology/{{backend_stack}}/folder-structure.md
+- guardrails/technology/{{backend_stack}}/dependency-policy.md
+- guardrails/technology/{{backend_stack}}/coding-standards.md
+- guardrails/technology/{{backend_stack}}/framework-api-map.md
+- guardrails/technology/{{backend_stack}}/testing.md
+- guardrails/project-specific/service/technical-requirements.md
+
+## /aw-spec-foundation-frontend
+<!-- The same for the FRONTEND lane: the lane base (ui-constitution, which carries the
+     mandatory frontend folder structure), how components are split and named, routing, the
+     design system, the generated API client the lane talks to the service through, the test
+     setup, and the project team's ui-requirements. Loaded INSTEAD of the backend set, never
+     on top of it — foundation swaps the standards between the two lanes. -->
+- guardrails/technology/{{frontend_stack}}/ui-constitution.md
+- guardrails/technology/{{frontend_stack}}/component-architecture.md
+- guardrails/technology/{{frontend_stack}}/component-conventions.md
+- guardrails/technology/{{frontend_stack}}/routing-navigation.md
+- guardrails/technology/{{frontend_stack}}/design-system.md
+- guardrails/technology/{{frontend_stack}}/api-client.md
+- guardrails/technology/{{frontend_stack}}/frontend-testing.md
+- guardrails/project-specific/frontend/ui-requirements.md
+
+---
+
+## Quick reference (command → technical file count)
+
+| Command | Technical rule files | Role |
+|---|---|---|
+| /aw-spec-specify | 6 | the modelling methodology the spec is expressed in: DDD for the domain model (+ its example), and the four ux/ rules for the experience model it lifts as UX- ids — no technology |
+| /aw-spec-plan-backend | 24 | architecture/security/interop the design author mediates the spec against, each with its example |
+| /aw-spec-plan-frontend | 11 | the frontend lane's design set — composition, routing, client state, interaction states, forms, auth surface, design system, accessibility, i18n, performance, and the cross-lane API pairing the UI design author works from (from spec.md) |
+| /aw-spec-implement-backend | 6 | governance/architecture the SERVICE lane builds against (from backend-plan.md), both paths |
+| /aw-spec-implement-frontend | 13 | the FRONTEND lane's code-generation set (from frontend-plan.md), both paths — conventions, the generated client + its service pairing, auth, client security, states, forms, design system, accessibility, i18n, performance, observability and testing |
+| /aw-spec-build | 3 | layering + coding rules the compile-fixer respects, + the layering example |
+| /aw-spec-analyze-slice | 3 | testing + coding rules and the framework API map the design↔code gate validates against |
+| /aw-spec-constitution | 18 | what the technical half ratifies — the technology base, the standard technical rules, and the project team's technical-requirements.md |
+| /aw-spec-ui-constitution | 2 | what the frontend lane's half ratifies — the UI base + the project team's ui-requirements.md — and the signal that the lane exists |
+| /aw-spec-run | 2 | persistence rules the execution / data-migration step generates against, + its example |
+| /aw-spec-foundation-backend | 7 | what `foundation` builds the service lane's base project against when it is built from a spec rather than unpacked from a pack |
+| /aw-spec-foundation-frontend | 8 | the same for the frontend lane — loaded instead of the backend set, never on top of it |
+
+> All migrated workflows are on this map. The conformance-gate workflows **analyze-plan**
+> and **analyze-plan-delta** are intentionally NOT here — they validate the plans / the delta
+> against the spec + DOMAIN gate overlays only (domain-rule-bindings `## /aw-spec-gate`), with no
+> technical gate checklist.

package/assets/guardrails/technology/dotnet-webapi/PACKAGING.md

@@ -162,12 +162,63 @@ AAABAAE...
 
 ---
 
+## The rule file (`<pack name>.rules.json`)
+
+Every file in a pack is unpacked as packed, and a file that is already there is replaced. A
+pack that needs some files treated otherwise ships a rule file beside it, named after the
+pack: `VerticalSlice.rules.json` for `VerticalSlice.pack.txt`,
+`VerticalSlice.Reference.rules.json` for `VerticalSlice.Reference.pack.txt`. Without one, the
+pack unpacks exactly as described above.
+
+```json
+{
+  "format": "aw-spec-pack-rules/v1",
+  "rules": [
+    {
+      "path": "src/AppWeaver.VerticalSlice.Service/Infrastructure/ApplicationDbContext.cs",
+      "action": "merge",
+      "note": "why this file is merged — for the reader only",
+      "instruction": [
+        "Produce one ApplicationDbContext based on the EXISTING file:",
+        "- insert every INCOMING `public DbSet<...>` property right after the class's opening brace;",
+        "- keep everything else in the EXISTING file unchanged."
+      ]
+    },
+    { "path": "src/AppWeaver.VerticalSlice.Service/Features/", "action": "replace" }
+  ]
+}
+```
+
+- **`path`** is written as the pack holds it, sentinel included, and is renamed the way the
+  pack's files are — one rule file serves every app name. A path ending in `/` covers every
+  pack file under that folder; a rule for a file wins over its folder's rule.
+- **`action`** is `merge` or `replace`. `replace` writes the pack's file over the existing one,
+  which is also what happens to every file no rule names. `merge` applies only when the file is
+  already there (from the base project, or from the lane before a re-unpack); otherwise the
+  pack's file is simply written.
+- **`instruction`** (required for `merge`; a string or a list of lines) tells the merging
+  agent how to combine the two versions. It sees the **EXISTING** file — the one in the lane
+  before this pack was unpacked — and the **INCOMING** file — the pack's own, with the sentinel
+  already renamed — and returns the merged file; the engine writes it.
+- **`note`** is optional and ignored by the kit.
+
+A rule file that does not parse, or a rule with an unknown action or a merge with no
+instruction, stops that pack before anything is written: the base pack reports the lane "not
+scaffolded", and a broken reference rule file leaves the sample out with the reason. A rule
+whose path the pack does not hold is reported in the lane's line — a sign the pack changed
+and the rule file was not updated with it.
+
+---
+
 ## How scaffolding consumes the bundle
 
-`/appweaver foundation VerticalSlice <AppName> [OutputDir]` runs `unpack-foundation.ps1`,
-which reads the sentinel from the pack header, derives the four target case forms, and
-writes the renamed files to the output directory (**repo root by default**). The phase is
-defined in `.appweaver/orchestrator/workflows/aw-spec-foundation.orch.yaml`.
+`/appweaver foundation` unpacks the pack a lane picks into that lane's **lane root folder**
+(`backend/` by default) with `unpack-foundation.ps1` (or `.sh`), which reads the sentinel from
+the pack header, derives the four target case forms, and writes the renamed files. Before it
+runs, the pack's rule file is read and every file to be merged is put aside; after it, each
+merge runs as its rule says. A reference sample, when the pack ships one and the operator
+wants it, goes on top the same way with its own rule file. The steps are in
+`.appweaver/orchestrator/modules/foundation-pack.orch.yaml`.
 
 ```powershell
 ./unpack-foundation.ps1 -PackFile ./VerticalSlice.pack.txt -TargetAppName AppWeaver.Health -OutDir ../../../ 
@@ -182,3 +233,6 @@ defined in `.appweaver/orchestrator/workflows/aw-spec-foundation.orch.yaml`.
 - [ ] No `bin/obj/.vs` or local `.db` files committed into the pack.
 - [ ] `pack-foundation.ps1` reported a non-zero sentinel hit count.
 - [ ] `VerticalSlice.pack.txt` regenerated and committed after any change.
+- [ ] Each pack's rule file names every file that must be merged rather than replaced (for a
+      reference sample: every file it shares with the base pack that is not a straight
+      replacement), and no rule names a path the pack no longer holds.

package/assets/guardrails/technology/dotnet-webapi/api-versioning.md

@@ -1,6 +1,6 @@
 # API Versioning Policy
 
-> Pure technology (domain-agnostic) — domain (e.g. FHIR) versioning in [[api-versioning.domain]]. Commands: `/aw-spec-plan`.
+> Pure technology (domain-agnostic) — domain (e.g. FHIR) versioning in [[api-versioning.domain]]. Commands: `/aw-spec-plan-backend`.
 
 ## REST versioning
 

package/assets/guardrails/technology/dotnet-webapi/auditing.md

@@ -1,6 +1,6 @@
 # Auditing & Observability Standards
 
-> Pure technology (domain-agnostic) — domain audit additions in [[auditing.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-plan`.
+> Pure technology (domain-agnostic) — domain audit additions in [[auditing.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-plan-backend`.
 
 ## Observability baseline
 

package/assets/guardrails/technology/dotnet-webapi/authorization.md

@@ -1,6 +1,6 @@
 # Authorization Standards
 
-> Pure technology (domain-agnostic) — domain roles & matrix in [[authorization.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-plan`.
+> Pure technology (domain-agnostic) — domain roles & matrix in [[authorization.domain]]. NON-NEGOTIABLE. Commands: `/aw-spec-plan-backend`.
 
 ## Authorization model
 

package/assets/guardrails/technology/dotnet-webapi/clean-architecture.md

@@ -1,6 +1,6 @@
 # Clean Architecture Standards
 
-> Pure technology (domain-agnostic). NON-NEGOTIABLE. Commands: `/aw-spec-plan`, `/aw-spec-build`.
+> Pure technology (domain-agnostic). NON-NEGOTIABLE. Commands: `/aw-spec-plan-backend`, `/aw-spec-build`.
 
 ## Dependency direction