aw-spec-cli 0.1.3 → 0.1.5

package/README.md

@@ -0,0 +1,291 @@
+# aw-spec-cli
+
+**AppWeaver Spec-Driven Development CLI** — Scaffold projects with vertical slices, DDD, CQRS, and AI agent skills.
+
+[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+
+---
+
+## Overview
+
+`aw-spec-cli` initializes new projects with the **AppWeaver Spec-Driven Development** structure:
+
+- **Vertical Slice Architecture** — Feature-oriented, decoupled modules
+- **Domain-Driven Design (DDD)** — Rich domain models, bounded contexts
+- **CQRS** — Command/Query separation for scalable reads/writes
+- **AI Agent Skills** — Ready-to-use skills for Claude Code, Antigravity, and KiloCode
+
+The CLI copies a battle-tested project skeleton (from the [AppWeaver.Spec](https://dev.azure.com/bytestrone-labs/AppWeaver/_git/AppWeaver.Spec) reference implementation) into your target directory.
+
+---
+
+## Installation
+
+### Global Install (via Azure Artifacts / npm)
+```bash
+# From Azure Artifacts (after publishing)
+npm install -g aw-spec-cli
+
+# Or use via npx
+npx aw-spec-cli@latest init
+```
+
+### Local Development Install
+```bash
+# From the cloned repository
+git clone https://dev.azure.com/bytestrone-labs/AppWeaver/_git/appweaver
+cd platform/Appweaver.Spec.Cli
+npm install
+npm run build
+# Then run via node
+dist/index.js init
+```
+
+Requires **Node.js ≥ 18**.
+
+---
+
+## Quick Start
+
+```bash
+# Create a new project in the current directory
+aw-spec init
+
+# Or specify a target directory
+aw-spec init my-project
+
+# Non-interactive (uses Claude skills by default)
+aw-spec init -y
+
+# Choose agent explicitly
+aw-spec init --agent antigravity
+aw-spec init --agent kilocode
+
+# Preview what would be copied (no changes)
+aw-spec init --dry-run
+```
+
+After initialization:
+
+```bash
+# Verify the installation
+aw-spec doctor
+
+# Start spec-driven development
+aw-spec specify "Your feature description"
+```
+
+---
+
+## Commands
+
+### `aw-spec init [directory]`
+
+Initialize a new AppWeaver Spec project.
+
+| Option | Description |
+|--------|-------------|
+| `directory` | Target directory (default: current directory) |
+| `-a, --agent <agent>` | Agent skills to include: `claude`, `antigravity`, `kilocode` (default: prompt) |
+| `-y, --yes` | Skip prompts, use defaults (Claude) |
+| `--dry-run` | Show what would be copied without making changes |
+
+**Copied structure:**
+```
+target-dir/
+├── .aw-spec/              # Core spec configuration
+│   ├── extensions.yml     # Extension registry
+│   ├── feature.json       # Feature tracking
+│   ├── workflows/         # Workflow definitions
+│   ├── templates/         # Spec/plan/task templates
+│   └── scripts/           # Bash/PowerShell helpers
+├── docs/                  # Documentation scaffold
+│   ├── architecture/
+│   ├── domain/
+│   ├── governance/
+│   ├── security/
+│   ├── domainspecs/
+│   ├── glossary/
+│   ├── VerticalSlice/     # Vertical slice packaging
+│   └── ...
+└── .claude/skills/        # Or .agents/skills/, .kilocode/
+    ├── aw-spec-specify/
+    ├── aw-spec-plan/
+    ├── aw-spec-implement/
+    └── ... (13 skills total)
+```
+
+### `aw-spec doctor`
+
+Verify the project structure is complete and valid.
+
+| Option | Description |
+|--------|-------------|
+| `-v, --verbose` | Show detailed output (lists all skills, missing items) |
+
+**Checks performed:**
+- Required folders: `.aw-spec/`, `docs/`
+- Required config files: `extensions.yml`, `feature.json`, `init-options.json`, `integration.json`, `workflow-registry.json`
+- Agent skills folder (`.claude/skills` or `.agents/skills`) with all 13 skills
+- Documentation structure (`architecture/`, `domain/`, `governance/`, `security/`, `domainspecs/`, `glossary/`, `VerticalSlice/`)
+- Vertical Slice packaging scripts (`pack-foundation.sh`, `unpack-foundation.sh`, `PACKAGING.md`)
+- `.aw-spec` subdirectories (`extensions/`, `templates/`, `scripts/`, `workflows/`, `integrations/`, `memory/`)
+
+---
+
+## Agent Support
+
+| Agent | Folder | Skills |
+|-------|--------|--------|
+| **Claude Code** | `.claude/skills/` | 13 skills (specify, plan, implement, tasks, clarify, analyze, checklist, foundation, constitution, select-domain, agent-context-update, addcomponent, taskstoissues) |
+| **Antigravity** | `.agents/skills/` | Same 13 skills, Antigravity-compatible format |
+| **KiloCode** | `.kilocode/` | Workflow definitions (`.md` files) |
+
+Choose based on your AI assistant. Skills provide guided workflows for spec-driven development:
+- `aw-spec-specify` — Write feature specifications
+- `aw-spec-plan` — Create implementation plans
+- `aw-spec-implement` — Generate code from plans
+- `aw-spec-tasks` — Break down into executable tasks
+- ... and more
+
+---
+
+## Project Structure (After Init)
+
+```
+my-project/
+├── .aw-spec/
+│   ├── extensions.yml
+│   ├── feature.json
+│   ├── init-options.json
+│   ├── integration.json
+│   ├── workflows/
+│   │   └── workflow-registry.json
+│   ├── extensions/
+│   │   └── agent-context/
+│   │       ├── scripts/
+│   │       └── commands/
+│   ├── templates/
+│   │   ├── spec-template.md
+│   │   ├── plan-template.md
+│   │   └── tasks-template.md
+│   ├── scripts/
+│   │   └── bash/
+│   │       └── common.sh
+│   ├── integrations/
+│   └── memory/
+├── docs/
+│   ├── architecture/
+│   ├── domain/
+│   ├── governance/
+│   ├── security/
+│   ├── domainspecs/
+│   ├── glossary/
+│   ├── interop/
+│   ├── ModularMonolith/
+│   ├── VerticalSlice/
+│   │   ├── VerticalSlice.pack.txt
+│   │   ├── PACKAGING.md
+│   │   ├── pack-foundation.sh
+│   │   └── unpack-foundation.sh
+│   ├── command.txt
+│   ├── components/
+│   ├── pharma-constitution.my-ref.md
+│   ├── requirement-spec.txt
+│   ├── technology-constitution.md
+│   └── README.md
+└── .claude/skills/          # Or .agents/skills/, .kilocode/
+    ├── aw-spec-addcomponent/
+    ├── aw-spec-agent-context-update/
+    ├── aw-spec-analyze/
+    ├── aw-spec-checklist/
+    ├── aw-spec-clarify/
+    ├── aw-spec-constitution/
+    ├── aw-spec-foundation/
+    ├── aw-spec-implement/
+    ├── aw-spec-plan/
+    ├── aw-spec-select-domain/
+    ├── aw-spec-specify/
+    ├── aw-spec-tasks/
+    └── aw-spec-taskstoissues/
+```
+
+---
+
+## Development
+
+### Prerequisites
+- Node.js ≥ 18
+- The [AppWeaver.Spec](https://dev.azure.com/bytestrone-labs/AppWeaver/_git/AppWeaver.Spec) repository cloned as a sibling directory (for bundling assets)
+
+### Scripts
+| Command | Description |
+|---------|-------------|
+| `npm run build` | Compile TypeScript to `dist/` |
+| `npm run bundle:content` | Copy assets from `../AppWeaver.Spec` → `assets/` |
+| `npm run prepack` | Build + bundle (runs automatically on `npm publish`) |
+| `npm test` | Run unit tests (Vitest) |
+| `npm run test:watch` | Watch mode |
+| `npm run lint` | ESLint on `src/` |
+| `npm run doctor` | Run CLI doctor on current directory |
+
+### Setup (Local Development)
+```bash
+# Clone the main repository
+git clone https://dev.azure.com/bytestrone-labs/AppWeaver/_git/appweaver
+cd platform/Appweaver.Spec.Cli
+npm install
+
+# Ensure AppWeaver.Spec is available for bundling
+# Either clone it as a sibling directory:
+#   git clone https://dev.azure.com/bytestrone-labs/AppWeaver/_git/AppWeaver.Spec ../AppWeaver.Spec
+# Or the bundling script will fall back to published assets in dist/assets/
+```
+
+### Setup (After Publishing to Azure Artifacts)
+Once published to Azure Artifacts, consumers can install via:
+```bash
+# From Azure Artifacts / npm registry (after publishing)
+npm install -g aw-spec-cli
+
+# Or use directly via npx
+npx aw-spec-cli@latest init
+```
+
+---
+
+## How It Works
+
+1. **Asset Bundling** (`scripts/bundle-content.ts`) — On publish, copies the AppWeaver.Spec reference implementation into `assets/` (excludes build artifacts, secrets, VCS folders).
+
+2. **Asset Resolution** (`src/utils/paths.ts`) — At runtime, finds assets in priority order:
+   - `dist/assets/` (published package)
+   - `../AppWeaver.Spec` (local development)
+   - `packageRoot/assets` (fallback)
+
+3. **Project Initialization** (`src/commands/init.ts`) — Copies `.aw-spec/`, `docs/`, and the selected agent's skills to the target directory with overwrite protection.
+
+4. **Validation** (`src/commands/doctor.ts`) — Comprehensive structure verification with colored output.
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make changes with tests
+4. Run `npm run build && npm test && npm run lint`
+5. Submit a PR
+
+---
+
+## License
+
+MIT © [AppWeaver Team](https://dev.azure.com/bytestrone-labs/AppWeaver)
+
+---
+
+## Related
+
+- [AppWeaver.Spec](https://dev.azure.com/bytestrone-labs/AppWeaver/_git/AppWeaver.Spec) — Reference implementation & source of bundled assets
+- [Spec-Driven Development](https://dev.azure.com/bytestrone-labs/AppWeaver/_git/AppWeaver.Spec?path=/docs/spec-driven-development.md) — Methodology overview

package/assets/.agents/agent.json

@@ -0,0 +1,28 @@
+{
+  "name": "antigravity",
+  "sdk": {
+    "type": "google-antigravity",
+    "package": "google-antigravity",
+    "module": "google.antigravity",
+    "adapter": "../.aw-spec/orchestrator/adapters/google_antigravity.py"
+  },
+  "runtime": "Antigravity CLI (agy -p) — Antigravity is Gemini-based",
+  "note": "Antigravity (agy) has no --system-prompt flag, so 'system' is folded into the prompt (system: prepend).",
+  "bin": "agy",
+  "args": ["--dangerously-skip-permissions", "--add-dir", "."],
+  "model_flag": "--model",
+  "system": "prepend",
+  "user": { "mode": "arg", "flag": "-p" },
+  "tools_flag": null,
+  "approval": {
+    "acceptEdits": ["--mode", "accept-edits"],
+    "bypassPermissions": ["--dangerously-skip-permissions"],
+    "default": [],
+    "readonly": ["--mode", "plan"]
+  },
+  "isolation": {
+    "bare": [],
+    "fresh": []
+  },
+  "result_keys": ["response", "result"]
+}

package/assets/.agents/skills/aw-spec-orch/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: "aw-spec-orch"
+description: "Parametric launcher (Antigravity): run ANY converted aw-spec skill on the aw-orchestrator under one of the 4 strategies (agent [default], spawn, sdk, sdk-apply)."
+argument-hint: "<skill> [strategy] [input…] — e.g. 'select-domain', 'specify spawn Build an order API', 'analyze-slice'"
+compatibility: "Requires .aw-spec/orchestrator/ and the agy CLI on PATH"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Orchestrator Skill Launcher
+
+Runs one converted `aw-spec-*` workflow on the shared, agent-agnostic engine. All orchestration and **all context management live in the workflow YAML + engine** (`.aw-spec/orchestrator/orchestrator.py`): the interpreter assembles the COMPLETE payload (system + user) for every request; you never author generation context yourself. Execution follows the chosen strategy; the checkpoint channel carries every human-facing interaction regardless of strategy.
+
+- **Engine + workflows (common, shared by all agents):** `.aw-spec/orchestrator/orchestrator.py`, `.aw-spec/orchestrator/workflows/aw-spec-<skill>.orch.yaml`, shared modules in `.aw-spec/orchestrator/modules/`, shared scripts in `.aw-spec/scripts/`
+- **This agent's transport profile:** `.agents/agent.json`
+
+  > Antigravity spawns via the `agy` CLI (Gemini-based; no `--system-prompt`,
+  > so `system` is folded into the prompt — isolation is best-effort). Its
+  > `sdk` block declares the SDK the `sdk`/`sdk-apply` strategies import
+  > (`google-antigravity`) and the adapter
+  > (`.aw-spec/orchestrator/adapters/google_antigravity.py`, shared per-SDK)
+  > that owns its calling convention.
+
+## Execution Steps
+
+1. **Parse Arguments** (`<skill> [strategy] [input…]`):
+   - `skill` (required): the aw-spec skill name, e.g. `demo`, `select-domain`, `foundation`, `specify`, `design`, `implement`, `build`. Resolve the workflow file `.aw-spec/orchestrator/workflows/aw-spec-<skill>.orch.yaml`. If it does not exist, list the available `aw-spec-*.orch.yaml` files in that folder and stop.
+   - `strategy` (optional, one of `agent`, `spawn`, `sdk`, `sdk-apply`; default `agent` — YOU fulfill each generation through the checkpoint channel, no profile needed): who executes each generation. Always pass `--strategy <strategy>`.
+   - Everything after the strategy is the user input: pass it as `--input "<text>"` (omit when empty).
+   - `--agent-profile .agents/agent.json` is required for `spawn`, `sdk`, and `sdk-apply` (`agent` needs no profile). If the SDK package isn't installed, add `--sdk-install`.
+   - **Always** pass `--checkpoint .aw-spec/orchestrator/.state/<skill>.state.json` — for EVERY strategy. Converted skills contain interactive steps (questions, selections, hooks); the checkpoint is how they reach you and the user. Strategies only govern who generates.
+   - `spawn` may also add `--isolation bare|fresh` and `--model <name>`; `sdk`/`sdk-apply` accept `--model <name>`.
+
+2. **Run the Interpreter**:
+   ```bash
+   python3 .aw-spec/orchestrator/orchestrator.py \
+     .aw-spec/orchestrator/workflows/aw-spec-<skill>.orch.yaml \
+     --strategy <strategy> \
+     --checkpoint .aw-spec/orchestrator/.state/<skill>.state.json \
+     [--agent-profile .agents/agent.json]   # spawn, sdk, sdk-apply \
+     [--input "<user input>"] \
+     --json
+   ```
+
+3. **Handle the Suspend/Resume Loop** — whenever the command exits with code `2`, read the printed `pending` JSON and dispatch on `pending.kind`; fulfill it, write the response to `pending.response_path`, then re-run the SAME command. Repeat until exit `0` (done) or `1` (stopped by a gate).
+   - **`ask`** — ask the USER the `prompt` with the listed `options` (use your question tool). Write the chosen answer as PLAIN TEXT to `response_path` (comma-separated values when `multi` is true).
+   - **`select`** — ask the USER to pick ONE of `options`; write the chosen value as plain text to `response_path`.
+   - **`hook`** — run each MANDATORY hook in `hooks` (each is a slash command of THIS agent) in this conversation; optional hooks at your discretion. Then write `done` to `response_path`.
+   - **`author`** — read `system_path` + `user_path` and treat them as your ONLY standards and context. Author the COMPLETE content of the file named in `target` and write it — content ONLY, no commentary, no code fence — to `response_path`. Do NOT write the target file yourself; the interpreter does that.
+   - **`agent_generate`** — read `system_path` + `user_path`; perform the task YOURSELF with the listed `tools` within `permission_mode`; write your full final reply — ending with the required ```json fence — to `response_path`.
+   - **`agent_query` / `agent_review`** — same as above but READ-ONLY (do not modify files); the reply must end with the required ```json fence.
+   - **`apply`** — an isolated generation already decided the changes: read `artifact_path` and write its file contents EXACTLY to the paths it names, then write the confirmation ```json fence to `response_path`.
+   - If `pending.note` is present, your previous response was rejected — follow the note and rewrite `response_path`.
+
+4. **Report**:
+   Report the final JSON (`status`, `outputs`, and any `reason`) to the user. On `stopped`, relay the gate message verbatim — it tells the user what to fix or run first.

package/assets/.agents/skills/aw-spec-orch-demo/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: "aw-spec-orch-demo"
+description: "Prototype launcher (Antigravity): run the aw-orchestrator using the specified strategy (spawn, agent, sdk, sdk-apply)."
+argument-hint: "Optional strategy ('agent', 'spawn', 'sdk', 'sdk-apply') and/or k=value vars (e.g. 'agent out_dir=...')"
+compatibility: "Requires .aw-spec/orchestrator/ and the gemini CLI on PATH"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Orchestrator Launcher
+
+All orchestration lives in the workflow YAML and is executed by `.aw-spec/orchestrator/orchestrator.py` (the general, agent-agnostic engine). The interpreter assembles the COMPLETE payload (system + user) for every request; you never author generation context yourself.
+
+- **Engine + workflow (general):** `.aw-spec/orchestrator/orchestrator.py`, `*.orch.yaml`
+- **This agent's transport profile:** `.agents/agent.json`
+
+  > Antigravity spawns via the `agy` CLI (Gemini-based; no `--system-prompt`, so
+  > `system` is folded into the prompt). Its `sdk` block declares the SDK the
+  > `sdk`/`sdk-apply` strategies import (`google-antigravity`) and the adapter
+  > (`.aw-spec/orchestrator/adapters/google_antigravity.py`, shared per-SDK)
+  > that owns its calling convention.
+
+## Execution Steps
+
+1. **Parse Arguments**:
+   - Identify the requested strategy (one of: `agent`, `spawn`, `sdk`, `sdk-apply`). If the user specifies a strategy as the first argument, use it. Otherwise, default to `spawn`.
+   - Always pass the strategy explicitly: `--strategy <strategy>`.
+   - `--agent-profile .agents/agent.json` is required for `spawn`, `sdk`, and `sdk-apply`:
+     `spawn` reads the CLI to launch (`agy`) from it; `sdk`/`sdk-apply` read the SDK
+     package/module (and its `adapter` file) to import from its `sdk` block.
+     If the SDK package isn't installed, add `--sdk-install` so the engine
+     pip-installs the declared package first. (`agent` needs no profile.)
+   - `--checkpoint .aw-spec/orchestrator/.demo-out/demo.state.json` is required for
+     `sdk-apply` and `agent` (suspend/resume — follow the loop in step 3).
+   - `spawn` accepts `--model <name>` (e.g. `gemini-2.5-pro`); isolation is
+     best-effort for Antigravity (no `--bare` equivalent). `sdk`/`sdk-apply`
+     accept `--model <name>`; isolation is intrinsic (fresh SDK session).
+
+2. **Run the Interpreter**:
+   Run the command (include only the bracketed flags that apply to the chosen strategy):
+   ```bash
+   python3 .aw-spec/orchestrator/orchestrator.py \
+     .aw-spec/orchestrator/workflows/aw-spec-demo.orch.yaml \
+     --strategy <strategy> \
+     [--agent-profile .agents/agent.json]   # spawn, sdk, sdk-apply \
+     [--checkpoint .aw-spec/orchestrator/.demo-out/demo.state.json]  # sdk-apply, agent \
+     --json
+   ```
+
+3. **Handle Suspend/Resume Loop (for `agent` or `sdk-apply` strategies)**:
+   - If the command exits with code `2` (suspend):
+     - Read the prompt from the sidecar file `<checkpoint-path>.user.md` (and system instructions from `<checkpoint-path>.system.md`).
+     - Fulfill the request directly using your own tools (e.g., implementing the handler or reviewing files in the workspace).
+     - Write the final generation or review output to `<checkpoint-path>.response.md`.
+     - Re-run the exact same command.
+     - Repeat until the orchestrator exits with code `0`.
+
+4. **Report**:
+   Report the final JSON outputs (`status`, `outputs`, `review_pass`, generated file paths, etc.) to the user.

package/assets/.aw-spec/DESIGN-FORMAT.md

@@ -0,0 +1,151 @@
+# 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
+`.aw-spec/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
+`/aw-spec-orch onboard` reverse-engineers from the repo's own structure and installs at
+`.aw-spec/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.
+
+## 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.