aw-spec-cli 0.1.8 → 0.1.9

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

@@ -0,0 +1,200 @@
+# aw-spec design-doc format — the single high-level design (HLD)
+
+The format the spec-anchored pipeline uses for the **Design** phase. Sibling of
+`ORCH-DIALECT.md` (the orchestrator dialect) and `RULE-PARTITION.md` (which rules each
+command loads): this one governs the *artifact* those workflows read and write — the
+design document — not the engine. The authoring template is
+`.appweaver/templates/design-template.md`.
+
+## The contract
+
+A feature's design is **one document**, living beside its spec:
+
+```
+specs/<Aggregate>/
+  spec.md      # behaviour (tech-agnostic) — WHAT / WHY — the source of truth
+  design.md    # structure & decisions (tech-agnostic HLD) — the MEDIATOR
+  changes/     # open + archived change records (delta-spec + delta-design)
+```
+
+`design.md` is the **mediator** between the spec and the generated code:
+
+```
+spec.md  ──▶  design.md  ──▶  code (+ tests)
+behaviour     structure &       generated by `implement`
+FR/BR/US/SC   decisions (HLD)    (stack bound at generation time)
+```
+
+- **One design per aggregate.** The four clean-architecture layers (Domain,
+  Application, API, Infrastructure) are **sections** of this one document, each at
+  design level. Feature = aggregate; commands are user stories inside it. *(This is
+  the **greenfield** layout, authored from `design-template.md`. See the Brownfield
+  variant below for reverse-engineered / existing-codebase designs.)*
+- **High-level, not code.** It carries entities/value-objects/events, behaviour as
+  **signatures + pre/post/invariant/raises**, use-cases, endpoint contracts, ports,
+  and the significant technical decisions with rationale — but **no complete method
+  bodies**. See `design-template.md` for the section structure (§0–§9). The domain
+  layer (§1) follows spec.md exactly — its entities/value-objects are the spec's Key
+  Entities and its invariants are the spec's Business Rules.
+- **Technology-agnostic.** Behaviour and contracts use conceptual types, never a
+  language. The SAME design.md must be generatable on a different stack. The target
+  language/framework/persistence is bound only at `implement` time from the
+  constitution's technology base + the active stack profile.
+- **Physical schema is out of scope.** PKs/FKs, columns, indexes, JSON shapes, and
+  migration SQL belong to a separate technical-data-model — design.md states WHAT is
+  stored and WHICH port persists it, not the schema.
+- **Two deferral ledgers are first-class:** §7 Assumptions (`DA-n`, clarify later)
+  and §8 Workarounds (`WA-n`, clear later). They keep the HLD honest about what it
+  defers; `implement` tags generated code that leans on them.
+- **Solution-wide rules live elsewhere, not per feature:** the layering/dependency
+  rule is the constitution's; the code-generation mechanics (folder mapping,
+  file-per-element, test pairing, stack binding) are a technology-specific rule
+  applied in the `implement` phase. `design.md` stays feature-specific and
+  technology-agnostic.
+
+## Brownfield variant (existing codebases)
+
+A design reverse-engineered from — or added forward to — an **existing** codebase is
+authored from the repo's **code-derived `design-template` override**, which
+`/appweaver onboard` reverse-engineers from the repo's own structure and installs at
+`.appweaver/templates/overrides/design-template.md`. Both `adopt` (reverse design) and the
+forward `design` phase scaffold from it via the default template name. It is the **same
+contract** as above — one living HLD per aggregate, tech-agnostic, spec-anchored, with the
+same traceability spine and the two deferral ledgers — with **one difference that matters**:
+
+- **Structure follows the code, not a fixed layering.** The **code is the source of
+  truth**, so the design describes the system **as-built**. Its structural sections
+  are **derived from the code's own organisation** (its folders / projects / modules)
+  rather than the fixed Domain/Application/API/Infrastructure four. A component the
+  code has that fits no textbook layer (a UI tier, a worker, a host project) gets its
+  own section; a layer the code lacks does not appear. Two neutral anchors are kept
+  because every system has them and the tooling keys on them: **§1 is the domain/data
+  model** (the cross-reference tool reads it for `<Other>Id` reference edges) and one
+  **§2 subsection is the External Integrations table** (matched by heading keyword, so
+  `aw-xref` extracts contract edges from either layout). The `debt` ledger records
+  only debt the **code itself** evidences (stubs, dead code, torn seams) — being
+  organised unlike a reference architecture is **not** debt, it is the as-built shape;
+  migrating toward a target is a separate modernization decision.
+
+This keeps a brownfield design free of greenfield architectural bias while remaining a
+normal feature the CR delta loop and forward pipeline consume unchanged.
+
+Both overrides are derived against a **neutral skeleton** —
+`.appweaver/orchestrator/rev-templates/{design,delta-design}-template.skeleton.md` — which
+carries the bones above and names no layering, architecture style or technology. The
+greenfield templates are never placed in `onboard`'s context: a template whose headings
+*are* the four layers cannot be shown to an author whose job is to discover the layout
+from the code.
+
+## Frontend lane variant (`design-ui`)
+
+A project with a frontend lane designs it in its **own** document,
+`specs/<Feature>/design.ui.md`, authored by `design-ui` — not a section inside `design.md`.
+The lanes are governed by different constitution halves, take their rules from different
+map headings, and are implemented by different commands. A UI section inside the service
+design would put the lane's structure under the service lane's rules and hand `design-ui`
+the whole service design to read.
+
+It is the **same contract** — one living document per feature, technology-agnostic,
+spec-anchored, the same traceability spine and the same two ledgers. Its sections are
+navigation & screen structure · client state · component structure · interaction & flow ·
+contract binding · cross-cutting · traceability · `DA-n` · `WA-n`. Technology-agnostic here
+means no framework, router, state library or component library appears: a component is
+described by its responsibility, its inputs as field shapes, the events it raises and the
+states it can be in, and the framework binds at `implement-ui` from `constitution.ui.md`
+plus that command's rule set. The authoring template is
+`.appweaver/templates/ui-design-template.md`.
+
+**§5 Contract Binding is the lane boundary.** The UI design reads the whole spec — the
+experience is stated there — but only the service's **published surface**: the spec's `IC-`
+ids and the API contracts `design.md` states. No table, handler or persistence choice
+crosses that line, and an operation the experience needs that the surface does not offer is
+a contract delta raised back to the service lane, never a client workaround. ⌛ `design`
+will emit that surface as a `design-contract.md` projection; the rule does not change when
+it does, only what §5 reads.
+
+**`UX-` lives here and only here.** The service design excludes the spec's Experience
+Standards by contract — it realises no experience standard, and a traceability row for one
+would be a fabrication. So a `UX-` that reaches neither design is a dropped requirement,
+and design.ui.md's §7 is the only place that is visible.
+
+**Interaction & flow and cross-cutting are never omitted**, however thin the feature.
+They are the two sections a backend-shaped process silently drops, and loading, empty,
+error and permission-denied states are where most UI defects live. A lane whose code
+handles none of them records that as-built.
+
+In a brownfield repo `onboard` reverse-engineers this pair from the UI source and installs
+it at `.appweaver/templates/overrides/{ui-design,ui-delta-design}-template.md`, on the same
+terms as the service pair and from its own neutral skeletons. The files exist **only where
+the code has a lane** — a backend-only repo gets neither.
+
+## Generate forward, reconcile only the high-level back
+
+The design document and the code are **not** a byte-for-byte copy of each other.
+
+| Direction | Phase | What happens |
+|---|---|---|
+| **Generate** (forward) | Implement | The model reads spec + design.md and **generates** the code and tests — a reasoning step the design guides and constrains, not a transcription. |
+| **Reconcile** (high-level back) | Build / Run fixes | Compile/typecheck/runtime fixes happen on the **code**. Only when a fix is a **high-level technical variation** — a changed pattern, a new component, an altered contract/dependency — is that decision written back into design.md. Low-level churn stays in the code. |
+
+> **Invariant:** design.md remains a faithful **high-level** account of the built
+> system — every significant technical decision is recorded — but it is a durable
+> design reference, **not** a line-by-line mirror of the code. (This retires the old
+> `docs == files` extract/reconcile invariant.)
+
+## The traceability spine
+
+```
+FR/BR/US/SC ↔ design section (element / decision) ↔ code (+ tests) ↔ commit
+```
+
+Every design element traces **up** to a spec id, and the whole spec traces **down**
+into a design section (§6 Traceability). This is what makes the analyze gate and the
+review able to check coverage, and what keeps CR impact analysis exact.
+
+## Feature granularity (why a command is a delta, not a new feature)
+
+A **feature is the largest slice whose code no other feature owns.** Because
+`implement` regenerates the whole feature's code coherently, a shared file
+(`src/Domain/Order.cs`) must have exactly **one** owning design. So for an aggregate
+with a shared entity, **feature = the aggregate** (`Order`), and individual commands
+(`CreateOrder`, `UpdateOrder`, …) are **user stories / deltas** on the same design.md:
+
+- `CreateOrder` = US-1; `UpdateOrder` = US-2.
+- Adding `UpdateOrder` is an additive CR: a Delta Spec (`+US-2`) and a Delta Design
+  (`ADDED` new use-case/endpoint sections, `MODIFIED` the shared Order/root and
+  repository sections — see `delta-design-template.md`). The design phase amends
+  design.md doc-first, bumps the feature version (`v1.0 → v1.1`), and archives the CR;
+  `implement` regenerates the touched slice; regression re-tests the shared-file
+  dependents.
+
+Two command-level features would both claim `src/Domain/Order.cs` and collide —
+which is exactly why the aggregate is the boundary.
+
+## Migration status
+
+**Complete.** Every phase now runs this HLD model, including the executable chain.
+
+The legacy path-tagged helpers (`design-extract` / `design-reconcile` / `design-paths`)
+are **retired and deleted** from both shells. They belonged to the four-document,
+full-code model in which `design.{domain,application,api,infra}.md` carried the source
+inside ` ```lang path=… ` fences. That convention is gone — no template emits `path=`,
+and `design-scaffold` writes a single `design.md` — so all three had been finding
+nothing and no-op'ing at exit 0. (Their glob, `design.*.md`, could not have matched a
+single `design.md` even if the fences had survived: the second dot required a middle
+segment. The one legitimate remaining user of that glob, `list-features`'s informational
+`design_docs` count, is fixed to `design*.md`.)
+
+The question those helpers answered — *which files is this slice made of* — is now an
+**OKF query**, because the knowledge bundle is where that answer is actually maintained:
+
+| Need | Now |
+| --- | --- |
+| read the slice's files | `aw-xref concept-paths --feature-dir <dir>` → the concept's `source_files` |
+| record files a fix loop touched | `aw-xref concept-upsert --source-files … --merge` |
+
+`build`, `run`, and `analyze-slice` all read through `concept-paths` (feeding their fix
+loops and, in `analyze-slice`, the conformance pass) and write back through
+`concept-upsert --merge`. Both directions are advisory: `concept-paths` is strictly
+read-only and returns an empty list rather than an error when no concept exists yet, so
+a greenfield slice before its first `implement` behaves exactly as it did before.

package/assets/.appweaver/ORCH-DIALECT.md

@@ -0,0 +1,156 @@
+# aw-spec.orchestrator/v1 — orchestrator workflow dialect
+
+The workflow dialect executed by `.appweaver/orchestrator/orchestrator.py`, and the
+**only** workflow dialect that ships. It grew out of the earlier declarative
+`skill.yaml` dialect (`aw-spec.declarative/v1`, the `aw-spec-decl-*` skills), which
+was **retired 2026-08-03** along with its reference doc: same YAML subset, same
+step/`outputs:`/`condition:` conventions, but built for
+the **orchestrator model**: the interpreter assembles 100% of every model
+payload (system = standards/rules, user = artifacts + task) and a **fresh
+agent** executes it under one of the 4 strategies. Everything here is common
+across agent roots — `.claude`, `.agents`, `.kilocode` differ only in their
+transport profile (`agent.json`) and their thin `/appweaver` launcher.
+
+## Layout (the common folder)
+
+```
+.appweaver/orchestrator/
+  orchestrator.py            the engine (stdlib-only; reuses run-skill's YAML loader)
+  ORCH-DIALECT.md            → this doc lives at .appweaver/ORCH-DIALECT.md
+  README.md                  strategies, transports, checkpoint machinery
+  AGENT-PROFILE.md           profile (agent.json) reference
+  adapters/                  shared per-SDK adapters (claude_agent_sdk, google_antigravity)
+  modules/                   shared includable modules (*.orch.yaml): delta-design,
+                             delta-spec, domain-select, lane-gate, tech-select
+  rev-templates/             neutral (shape-only) skeletons the brownfield govern-backward
+                             authors follow — see aw-spec-onboard.orch.yaml
+  workflows/                 one aw-spec-<skill>.orch.yaml per converted skill (+ _smoke)
+.appweaver/scripts/            53 deterministic subcommands — 36 in aw-spec-actions (a true
+                             bash+powershell pair) + 17 across aw-xref, aw-inventory,
+                             aw-parity, aw-rev-constitution (thin sh/ps1 wrappers over one
+                             python core each) — reused as-is
+```
+
+## Execution model (strictly held)
+
+1. **Context management is the orchestrator's** — as in `workflows/aw-spec-demo.orch.yaml`.
+   `build_context` REPLACES the per-request envelope; `load_standards`
+   maintains the sticky system prefix. No agent ever assembles its own context.
+2. **Execution follows any of the 4 strategies** (`--strategy`, per-step
+   `strategy:` override): `sdk`, `sdk-apply`, `spawn`, `agent` — they only
+   govern WHO fulfills a generation, never what goes into it.
+3. **The checkpoint channel is strategy-independent** (D1): `ask`,
+   `user_select` and `dispatch_hooks` suspend via `--checkpoint` under EVERY
+   strategy, so the launching agent can relay to the human. Converted-skill
+   launchers therefore always pass `--checkpoint`.
+
+## Workflow file anatomy
+
+```yaml
+name: aw-spec-<skill>
+dialect: aw-spec.orchestrator/v1     # checked by --validate
+
+inputs:                              # F10 — bound from --input
+  user_input: { description: …, required: false, bind: USER_INPUT }
+
+scripts:                             # F1 — ref map for execute_script
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+standards:                           # F4 — optional seed of the sticky set
+  - { path: guardrails/technology/<stack>/clean-architecture.md, optional: true }
+
+vars: { k: v }                       # seed variables (--var k=v overrides)
+workflow: [ …steps… ]
+outputs: { k: "{{v}}" }              # resolved and printed at the end
+```
+
+Every step: `id:` (required, unique), `action:`, optional `condition:`
+(`==`/`!=`/truthy), optional `strategy:`/`model:` (generating actions),
+optional `outputs: [{name, from: "$.field"}]` (JSONPath into the step's
+structured result). `{{var}}` substitutes with dotted/index access
+(`{{q.text}}`, `{{items.0}}`); a value that is EXACTLY one `{{ref}}` yields
+the raw object, not its JSON string.
+
+## Actions
+
+| action | who runs | what it does |
+|---|---|---|
+| `set` | engine | assign vars (`vars:` or decl-style `parameters:`); raw-object aware |
+| `build_context` | engine | REPLACE the per-request envelope: `system:`/`context:` file lists (+ `context_from: <var>` holding paths a prior generation reported, + `vars:`) |
+| `load_standards` | engine | F4 — append to the **sticky standards set** prepended to every system block (dedup, `optional:`, `files:`/`files_from_variable`). This is the byte-stable, prompt-cacheable prefix |
+| `execute_script` | engine | F1 — run a `scripts:` ref (`subcommand:` + `args:`; sh/ps1 via `--os`); stdout's last line = JSON, bound via `outputs[]`; `on_error: continue` tolerated; cached across resumes; runs for real even in mock transport |
+| `verify_context` | engine | F2 — gates: `required_files` (+`allow_missing`), `require_non_empty` (+`on_empty[_message]`), `require_true` (+`on_false[_message]`), `require_value`+`equals` (+`on_mismatch[_message]`). `stop` raises a terminal stop |
+| `agent_generate` | fresh agent | demo contract (code work): agent DECIDES file paths per the loaded standards, writes with its tools, reports `files[]` in the trailing ```json fence. `sdk-apply` = read-only generation + invoking agent applies |
+| `agent_review` | fresh agent | read-only review of `review_of_var`/`review_of` files → `{pass, issues}` |
+| `agent_author` | fresh agent | F5 — **authored artifact** (decl `llm_generate`): the INTERPRETER owns `output_target: {type: file, path}`. Generation is READ-ONLY under every strategy; the ENGINE writes the returned content (sdk-apply degrades to sdk). Optional `context:` (per-request extras), `include_standards: false` (narrow payload) |
+| `agent_query` | fresh agent | F6 — generic read-only structured JSON (decl `llm_query`): `schema:` shapes the required fence, `outputs[]` binds it, `mock:` supplies the mock-transport result; one malformed-JSON retry on fresh strategies |
+| `ask` | human (via launcher) | F7 — question: `prompt`, `options`/`options_from`/`options_from_variable`, `multi`, `answer_key`, `answer_var` (default `answer`). Sources in order: cache → `--answer k=v` → `--non-interactive` (first option; all when multi) → checkpoint suspend `ask` → stdin |
+| `user_select` | human (via launcher) | F7 — pick ONE from `options_from_variable`; `preselect_from` (direct-argument fast path), `single_option_confirm`; `--select stepid=v`; binds `selection` + `outputs[]` |
+| `dispatch_hooks` | invoking agent | F8 — suspend kind `hook` with the `hooks_from_variable` list (slash commands of the LAUNCHING agent); logged-only without a checkpoint; never re-fires across resumes |
+| `include` | engine | F9 — run a module `.orch.yaml` inline: shares vars/envelope/standards/scripts/replay-cache; a module's own `scripts:` EXTEND the caller's map by `setdefault`, so the caller's ref wins on a clash and every module can declare what it invokes and still validate standalone; `with:` seeds inputs; cache keys namespaced `inc:<id>/…`; module `Stop` stops the caller |
+| `loop` | engine | `while: <cond>` + `max_iterations` (default 5), or F3 foreach `over: "{{list}}"` + `as: item` (binds `item`, `item_index`, `iteration`); `break` (+`condition:`) exits the innermost loop |
+
+Decl steps may keep their `parameters:` wrapper — every ported action reads
+`parameters:` or flat step keys interchangeably, so conversion is mechanical.
+
+## The suspend-kind protocol (checkpoint transport)
+
+At each handoff the engine writes sidecars next to the state file, prints the
+`pending` request (exit 2), and the launcher fulfills it, writes
+`response_path`, and re-runs the same command. Kinds:
+
+| kind | sidecars | launcher writes to response_path | resume ingests as |
+|---|---|---|---|
+| `agent_generate` | system/user | full reply ending in ```json fence | parsed fence → replay cache |
+| `agent_review`, `agent_query` | system/user | read-only reply ending in ```json fence | parsed fence |
+| `apply` | artifact | confirmation ```json fence after writing the named files | parsed fence |
+| `author` | system/user (+`target`) | the COMPLETE file content — no fence, no commentary (the ENGINE writes `target`) | raw content |
+| `ask` | none (`prompt`/`options`/`multi` inline) | the answer as plain text (comma-separated when multi) | string / list |
+| `select` | none (`prompt`/`options` inline) | the chosen option's value | string |
+| `hook` | none (`hooks` inline) | `done` after running the mandatory slash commands | `true` |
+
+A rejected response re-suspends with a `note` explaining what to fix. The
+state file persists vars, strategy, model, profile path, `--input`, answers,
+selects, `--os` and the replay cache — a bare
+`… <workflow> --checkpoint <state>` resumes with everything restored.
+Completed steps (generations, scripts, answers, hooks) replay from the cache
+and never re-fire; loop iterations get their own keys (`loopid#i`).
+
+## CLI
+
+```
+orchestrator.py <workflow.orch.yaml>
+  --strategy sdk|sdk-apply|spawn|agent   (per-step `strategy:` overrides)
+  --agent-profile <agent.json>           spawn/sdk/sdk-apply
+  --checkpoint <statefile>               the interaction channel (always, for converted skills)
+  --input "<text>"                       bound via inputs: (F10)
+  --answer k=v … / --select stepid=v …   HITL prefills
+  --non-interactive                      CI: first option everywhere
+  --os posix|windows                     script variant (F1 / D7)
+  --model <name> / --budget / --isolation bare|fresh / --sdk-install
+  --var k=v … / --show-full / --json / --dry-run
+  --validate                             F11 — static lint, never executes
+```
+
+## decl → orch conversion map
+
+| declarative (run-skill) | orchestrator |
+|---|---|
+| `load_context` (standards, domain rules, constitution) | `load_standards` (sticky system set — D3) |
+| `load_context` (feature artifacts, templates) | `build_context` `context:` before the consuming step |
+| `llm_generate` + `output_target` | `agent_author` (same `output_target`) |
+| `llm_query` | `agent_query` (+ `schema:`, `mock:`) |
+| `include_loaded_context: false` | narrow `build_context` + `include_standards: false` |
+| `execute_script` / `verify_context` / `ask` / `user_select` / `dispatch_hooks` / `set` / `loop` / `break` / `include` | same action, `parameters:` wrapper optional |
+| implement-style code tasks | `agent_generate` (+ `agent_review`), `context_from` chaining between iterations |
+
+## Validation & smoke
+
+- `--validate` every workflow/module (unknown actions/strategies, duplicate
+  ids, script refs + files on disk, `output_target.path`, module paths,
+  unproduced `{{vars}}`, dialect header).
+- `workflows/_smoke.orch.yaml` exercises every construct with no model and no
+  writes outside `.smoke-out`: run it `--non-interactive` (CI) and with
+  `--checkpoint` (protocol walk-through).

package/assets/.appweaver/RULE-PARTITION.md

@@ -0,0 +1,175 @@
+# Rule Partition — which command reads which rules
+
+*AppWeaver · aw-spec · companion to [Spec-Anchored-Pipeline.md](Spec-Anchored-Pipeline.md) and
+[DESIGN-FORMAT.md](DESIGN-FORMAT.md)*
+
+The authority on how rule files are partitioned across the pipeline, so each phase gets a
+focused, non-overlapping context. Domain-agnostic and technology-agnostic: it describes the
+**contract**, never a particular project's files. The concrete file lists are configuration —
+they live in the two rule maps, not here.
+
+---
+
+## The principle — the spec is the pivot
+
+Domain knowledge enters the pipeline **once**, at `specify`, and is written into the spec as
+identified requirements (`BR-` / `CN-` / `DC-` / `IC-` / `FR-`). From that point on the **spec is
+the only domain input**. Later phases mediate against the spec, not against the domain files.
+
+This is what makes a spec re-platformable: swap the technical rule set and the same spec still
+governs. It also stops domain detail leaking straight into code authoring without ever being
+pinned in a reviewable requirement.
+
+> **Lift, then gate.** If a domain constraint is needed downstream, it must first be *lifted*
+> into the spec as an id. A gate that finds a constraint in neither the spec nor the design
+> reports `LIFT-FAILURE:` and routes back to `specify` — it must never invent the rule into a
+> design or into code.
+
+---
+
+## The three classes of rule input
+
+| Class | What it is | Carried by |
+|---|---|---|
+| **Domain rule files** | Business/domain rules of the active domain | `domain-rule-bindings.md`, read by `resolve-domain` |
+| **Technical rule files** | Architecture, conventions, code-generation rules | `tech-rule-bindings.md`, read by `resolve-tech` |
+| **Constitution halves** | Ratified standing principles | Referred to **directly, as-is** — never mapped |
+
+Both maps are **configuration**: to change what a phase loads, edit the map, not the workflow.
+A command with **no heading** in a map loads nothing mapped for that class and
+**soft-continues** — an absent heading is a valid state, never a failure.
+
+### The constitution halves are not mapped
+
+- `.appweaver/memory/constitution.technical.md` — the technology base. Standing input to
+  **design + implement**. Domain-agnostic.
+- `.appweaver/memory/constitution.ui.md` — the **frontend lane's** base, a UX-* principle series.
+  Standing input to ⌛ **ui-design + ui-implement**. Domain-agnostic for the same reason the
+  technical base is, and it exists only where a frontend lane does — a backend-only project has
+  no such file.
+- `.appweaver/memory/constitution.domain.md` — the active domain's addenda. Standing input to
+  **specify** (and the gate checklist). Deliberately **not** loaded by design or implement.
+- `.appweaver/memory/constitution.md` — the composed human/compatibility view. The pipeline loads
+  the halves, not this file.
+
+One lane's constitution never governs the other lane's code: `design`/`implement` load the
+technical base and `ui-design`/`ui-implement` load the UI base. What they share is the spec.
+
+---
+
+## The map
+
+### `specify` — *domain modelling*
+- **Domain rule files: yes** — the domain authority. Authored INTO the spec as ids.
+- **Technical rule files: no**, with one exception: a **modelling methodology** (e.g. DDD
+  tactical patterns) may seed it. That is a domain-agnostic way of *modelling*, not a
+  technology choice. Like every other class, that exception is **configuration** — it is
+  wired under `## /aw-spec-specify` in `tech-rule-bindings.md`, not hardcoded in the
+  workflow. Nothing else may go under that heading: an architecture, persistence, or
+  code-generation file there would break specify's domain purity. Greenfield wires
+  the stack corpus's `domain-driven-design.md`; a code-derived (brownfield) project wires
+  `service/domain-modelling.md`, which `onboard` reverse-engineers from the code — the
+  as-built answer to *how does this codebase express a domain model*. Either way it is
+  **HOW to model**; **WHAT** the model is stays in the domain tier.
+- Constitution: the **domain** half.
+
+### `design` — *architecture; domain input = the spec only*
+- **Domain rule files: NEVER.** Domain reaches design solely as spec ids.
+- **Technical rule files: yes** — architecture and cross-cutting rules the design mediates the
+  spec against.
+- Constitution: the **technical** half.
+
+### `implement` / `implement-delta` — *code generation*
+- **Domain rule files: NEVER.** The design is the only input describing what to build.
+- **Technical rule files: yes** — the code-generation and convention set.
+- Constitution: the **technical** half.
+
+### `build` — *compile + repair*
+- **Technical rule files: yes** — the layering and convention rules the compile-fixer respects.
+- No domain files: build repairs against design intent, which the domain never reaches.
+
+### `run` — *runtime*
+- **Technical rule files:** only if the project evidences a runtime/hosting concern.
+
+### Gates — `analyze-design`, `analyze-delta-design`, `analyze-slice`, and the `/aw-spec-gate` overlay set
+- Load the domain **gate overlays** as a **conformance checklist**.
+- **Validation input ONLY — never authoring.** A gate may fail a document or a slice; it may
+  never write a rule into one.
+
+### `constitution`
+- Loads both classes to author each half from its own source.
+- The **UI half** is authored only where a frontend lane exists, and the technical map is the
+  authoritative test: `## /aw-spec-ui-constitution` resolving non-empty both proves the lane and
+  supplies its rules. A declared frontend lane in `.appweaver/stacks.json` or a UI stack named in
+  the request will also trigger it — neither is required, so nothing here constrains setup order.
+  With no signal at all the half is **skipped with a warning**, never an error.
+- The UI half is authored **before `domain-select`**, which is what keeps it domain-free — the
+  same ordering that protects the technical half.
+
+### `onboard` (brownfield)
+- Authors all three halves itself, and generates the rule set each one ratifies. The rule maps do
+  not exist yet when it starts, so its authority is the **code**: every principle and every
+  generated rule file is evidenced from source, and a greenfield rule file is never an input.
+- The **UI half** is authored where the **scan** finds a UI — `frontend_signals` reaching lane
+  strength — not where a map heading exists, because at onboard there is no map to read. The
+  order is therefore inverted: the half is authored from the code, then the `frontend/` rule set is
+  generated as its detail layer, then `## /aw-spec-ui-constitution` is appended to the technical
+  map. That heading is what makes every LATER `constitution` run behave like the greenfield case
+  above.
+- A frontend lane declared in `.appweaver/stacks.json` corroborates rather than decides: with no
+  UI source there is nothing to reverse-engineer, so nothing is authored.
+- `onboard` also **records** the lanes it reverse-engineered in `.appweaver/stacks.json`, through
+  `lane-declare` — still the sole writer, now with two callers. A derived lane carries
+  `origin: reverse-engineered` and an existing declaration is never overwritten, so a lane a
+  person confirmed always outranks one a scan proposed. Confirming or correcting a lane stays
+  `select-stack`'s job.
+- The **document templates** it derives obey the same partition as the halves that govern them:
+  the service design + delta-design pair is authored against `constitution.technical.md`, the
+  lane's pair against `constitution.ui.md` and the generated `frontend/` rules, and neither
+  reads a domain file. This is invariant 7 applied one level up — a lane's template describes
+  that lane's code and no other's.
+- **No greenfield artifact is ever in context.** Where a step needs a shape reference it reads a
+  neutral skeleton from `.appweaver/orchestrator/rev-templates/`, which carries the format and no
+  principle, rule, layering or technology. The rule maps do not exist yet when `onboard` starts,
+  so an instruction not to copy an exemplar would be the only control — absence is the stronger
+  one.
+- Ordering is preserved for the same reason as above: technical half → UI half → domain half.
+
+### `adopt` (brownfield)
+- Same partition, reversed: the reversed **spec** is authored with domain rules in context; the
+  reversed **design** is authored with the technical set only, so design stays domain-free.
+- Technical files here are **reference, not authority — the CODE wins.**
+
+---
+
+## Invariants
+
+1. **No domain rule file is ever loaded by `design`, `implement`, `implement-delta` or `build`.**
+2. **Domain reaches design and code only as spec ids.**
+3. **Gate overlays validate; they never author.**
+4. **A constraint not in the spec cannot be honoured downstream** — lift it first
+   (`LIFT-FAILURE:` → back to `specify`).
+5. **An absent map heading loads nothing and soft-continues** — it is never a blocking error.
+6. **The constitution halves are referred to directly** and never listed in either map.
+7. **A lane's constitution half governs that lane only** — `constitution.ui.md` never reaches
+   `design` or `implement`, and `constitution.technical.md` never reaches `ui-design` or
+   `ui-implement`.
+
+---
+
+## Where the concrete lists live
+
+| Map | Reader | Class |
+|---|---|---|
+| `guardrails/projects/<project>/domain-rule-bindings.md` | `resolve-domain` | domain rule files |
+| `guardrails/projects/<project>/tech-rule-bindings.md` | `resolve-tech` | technical rule files |
+
+Each map keys on `## /aw-spec-<command>` headings whose `- ` bullets are workspace-relative
+file paths — pointing into the shared corpora at `guardrails/technology/<stack>/` and
+`guardrails/domain/<industry>/`, or at the project's own three requirements files. A map is
+what binds a project to a corpus; the corpus itself belongs to no project. Shape references
+for authoring a new project live in
+`.appweaver/orchestrator/rev-templates/`.
+
+Rule files may carry a `Commands:` header naming their consumers. That header is **derived from
+these maps** — the maps are authoritative; a header that disagrees is a bug in the header.