@axis-bootstrap/cli 0.1.0

package/templates/INSTRUCTIONS.md

@@ -0,0 +1,49 @@
+# {{PROJECT_NAME}} — AI Instructions
+
+> Single source of truth for AI agents. All IDE-specific files (CLAUDE.md, AGENTS.md, etc.) symlink here.
+
+## Purpose
+
+{{PROJECT_PURPOSE}}
+
+## Stack
+
+- {{STACK}}
+
+## How to Run
+
+```bash
+# fill in
+```
+
+## Architecture
+
+| Component | Responsibility |
+| --------- | -------------- |
+| `src/`    | Application source |
+| `tests/`  | Tests |
+
+## Design Principles
+
+1. Single Source of Truth — content lives in `.ai/`, never duplicated
+2. Progressive Disclosure — load only what is needed
+3. Spec-Driven — REASONS Canvas precedes code generation
+4. Harness-first — `.claude/settings.json` and hooks define behavior, not the prompt
+
+## Available Skills
+
+| Skill | When to use |
+| ----- | ----------- |
+| (none yet — add skills under `.ai/skills/<name>/SKILL.md`) | |
+
+## Conventions
+
+- Update `STATE.md` at end of every session with relevant changes
+- Update spec before code when requirements change
+- See [CONVENTIONS.md](CONVENTIONS.md) for the maintenance protocol
+
+## Key Documents
+
+- [CONVENTIONS.md](CONVENTIONS.md) — how to maintain this structure
+- [docs/STATE.md](docs/STATE.md) — current playbook
+- [docs/canvases/](docs/canvases/) — REASONS Canvases (one per feature)

package/templates/STATE.md

@@ -0,0 +1,27 @@
+# STATE — {{PROJECT_NAME}} Playbook
+
+> Curated memory. Read at session start. Update at session end. Curate (do not just append).
+
+## Active Decisions
+
+- (none yet)
+
+## In Progress
+
+- (none yet)
+
+## Blockers
+
+- (none)
+
+## Deferred Ideas
+
+- (none)
+
+## Lessons Learned
+
+- (none yet — add non-obvious insights only)
+
+## TODOs
+
+- [ ] First feature: scaffold a Canvas via `axis spdd canvas <slug>`

package/templates/bootstrap-skill/PLANNER.md

@@ -0,0 +1,221 @@
+# Bootstrap Planner — Phase Orchestration
+
+This document describes the **execution state** of the bootstrap. The agent consults it as a state machine: each phase has an input, an output, and a gate before advancing.
+
+---
+
+## Orchestration Principles
+
+1. **Sequential and blocking** — do not start Phase N+1 without confirming Phase N's gate with the user
+2. **Each phase is atomic** — if something in Phase 2 indicates Phase 1 was wrong, **go back** to Phase 1, do not fix inline
+3. **Stateful** — keep a record of what was decided in each phase (write to `.ai/docs/STATE.md` in the target project once Phase 4 creates the file; until then, keep in session memory)
+4. **Never silence the user** — present summaries before each gate; wait for explicit approval
+
+---
+
+## Initial State
+
+When the skill is invoked, the agent checks:
+
+- Does `.ai/INSTRUCTIONS.md` exist in the target project? → **Mode:** audit (skip to Phase 5)
+- Does a readable `CLAUDE.md` or `AGENTS.md` exist? → **Mode:** migration (reduced Phase 1 — extract context from existing file)
+- Empty folder or just code? → **Mode:** full bootstrap (all 5 phases)
+
+Ask the user which mode applies if detection is ambiguous.
+
+---
+
+## Phase 1 — Discovery
+
+**Loads:** [references/PHASE-1-DISCOVERY.md](references/PHASE-1-DISCOVERY.md)
+
+**Input:** target project + user intent
+
+**Expected output:**
+
+- Project type identified (software / content / research / business / legal / educational / other)
+- Main stack or tools (if applicable)
+- 3-7 candidate domains to become skills
+- Critical constraints (compliance, deadline, team, preferred IDE)
+- Output quality criteria (proof-of-concept vs production)
+
+**Exit gate:**
+
+> Present structured summary in ~10 bullets. Ask literal confirmation: *"Is this correct and complete? Anything to add before proceeding?"*
+
+**Do not advance until receiving "yes" or applied corrections.**
+
+---
+
+## Phase 1.5 — SPDD Pipeline *(optional, recommended for complex projects)*
+
+**When to apply:** project with non-trivial business logic, multiple domain entities, or existing codebase to understand before speccing.
+
+**Trigger:** user says "analyze before speccing", project has >2 interacting entities, or complexity is evaluated as Large/Complex by Pattern #4.
+
+**Pipeline (each step has its own exit gate):**
+
+| # | Skill | Produces (REASONS Canvas section) | Why this order |
+| - | ----- | --------------------------------- | -------------- |
+| 1 | [`story-decompose`](../../story-decompose/SKILL.md) | **R** — INVEST stories with G/W/T ACs + DoD | Cannot align on what is undefined |
+| 2 | [`alignment`](../../alignment/SKILL.md) | **O** scope lock + **N** Norms + **S₂** Safeguards | Cannot design without governance bounds |
+| 3 | [`abstraction-first`](../../abstraction-first/SKILL.md) | **E** Entities + **A** Approach + **S₁** System structure | Cannot generate code without object design |
+
+The artifact produced is the **REASONS Canvas** ([references/CANVAS-REASONS.md](references/CANVAS-REASONS.md)) — single page per feature. If it doesn't fit, return to step 1 and split smaller.
+
+**Exit gate:**
+
+> Present the filled Canvas (all 7 dimensions: R/E/A/S₁/O/N/S₂). Ask: *"Does this capture the feature? Any AC, entity, norm, or invariant I missed?"* Advance to Phase 2 only after confirmation.
+
+**Note on `iterative-review`:** runs **after** code is generated (post-Phase 5). See Phase 6.
+
+---
+
+## Phase 2 — Spec Layer
+
+**Loads:** [references/PHASE-2-SPEC.md](references/PHASE-2-SPEC.md) + [references/TEMPLATES.md](references/TEMPLATES.md)
+
+**Input:** Phase 1 output
+
+**Generation in this order:**
+
+1. `mkdir -p .ai/{skills,rules,docs}` in target project
+2. `INSTRUCTIONS.md` (100-180 lines) using template adapted to type
+3. Skill skeletons (one SKILL.md per identified domain, without references/ yet)
+4. 3-7 initial rules with appropriate `applyTo` (omit if non-technical — use protocols)
+5. Doc stubs: `architecture.md`, `database-schema.md` (if software), `glossary.md` (if specialized domain)
+
+**Exit gate:**
+
+> List all files created with 1-line purpose each. Show line counts. Ask confirmation: *"This is the minimal Spec Layer. Any critical domain I missed? Any file that doesn't make sense for this project?"*
+
+---
+
+## Phase 3 — Harness Layer
+
+**Loads:** [references/PHASE-3-HARNESS.md](references/PHASE-3-HARNESS.md) + [references/TEMPLATES.md](references/TEMPLATES.md)
+
+**Input:** Phase 2 confirmed + project type
+
+**Critical decisions:**
+
+- **Lint/format hooks:** only if software with available formatter
+- **Destructive blocking hook:** **always** (universal, low cost, high value)
+- **Stop hook for tests:** only if software with test runner
+- **Sub-agents:** always enable `Explore`; others per scope
+- **Symlinks by IDE:** only for IDEs the user declared using
+
+**Generation:**
+
+1. `.claude/settings.json` (or equivalent) versioned, with appropriate permission profile
+2. `scripts/` with hooks (`format-file.sh`, `validate-bash.sh`, `run-tests-if-changed.sh` — only applicable ones)
+3. Symlinks via `setup-ide-links.sh` adapted to declared IDEs
+4. (Optional) `.gitignore` adjusted
+
+**Exit gate:**
+
+> Show `settings.json`, list of installed hooks, and symlink tree. Smoke test: *"I'll run `ls -la` to confirm the symlinks. May I?"* After confirmation, execute and show output.
+
+---
+
+## Phase 4 — Memory Layer
+
+**Loads:** [references/PHASE-4-MEMORY.md](references/PHASE-4-MEMORY.md)
+
+**Input:** Phases 2 and 3 confirmed
+
+**Generation:**
+
+1. `.ai/docs/STATE.md` with sections: Active Decisions, In Progress, Blockers, Deferred Ideas, Lessons Learned, TODOs
+2. `.ai/CONVENTIONS.md` with symlink map and maintenance rules
+
+**Exit gate:**
+
+> Show generated content. Ask: *"Are there decisions already made, current blockers, or important context to record now before the first real session?"* Update `STATE.md` with what the user provides.
+
+---
+
+## Phase 5 — Validation
+
+**Loads:** [references/PHASE-5-VALIDATION.md](references/PHASE-5-VALIDATION.md)
+
+**Input:** Phases 1-4 complete
+
+**Execution:**
+
+1. Run quality gates checklist (12-15 items)
+2. Calculate metrics (lines in INSTRUCTIONS, average SKILL.md size, rules count)
+3. Automated smoke tests (symlinks resolve, hooks execute)
+4. Generate handoff: list of files created + suggested next steps
+
+**Final gate:**
+
+> Present completed bootstrap report. List 3-5 actions suggested for the user to do next (e.g., "Create the first detailed skill for domain X", "Configure CI to validate symlinks").
+
+---
+
+## Phase 6 — Iterative Review *(post-bootstrap, per feature)*
+
+**When to apply:** triggered after code is generated from a REASONS Canvas, OR when a code review reveals drift between code and Canvas.
+
+**Loads:** [`iterative-review`](../../iterative-review/SKILL.md)
+
+**Two tracks:**
+
+- **Track A — Logic correction** (behavior wrong): update Canvas first → regenerate affected Operations → verify
+- **Track B — Refactoring** (no behavior change): refactor code → sync Canvas back → verify tests
+
+**Exit gate:**
+
+> Diff confined to Canvas Structure section? All ACs verified with concrete values? STATE.md updated with new patterns/decisions?
+
+**This phase is recurring** — every feature post-bootstrap re-enters Phase 1.5 → 6 cycle. Bootstrap (Phases 1-5) runs once; SPDD pipeline runs per feature.
+
+---
+
+## Recovery
+
+If a phase fails (user rejects output, contradictory information arises):
+
+- **In Phase 1-2:** review questions, adjust summary, regenerate
+- **In Phase 3:** if stack changed, regenerate `settings.json` and hooks; symlinks are reversible (`rm` + recreate)
+- **In Phase 4-5:** rarely requires going back; usually a targeted correction in `STATE.md` or `CONVENTIONS.md`
+
+**Never destroy the user's work.** Before overwriting an existing file, make a backup (`.bak`) or ask for confirmation.
+
+---
+
+## Frequent Decision Map
+
+| Phase question                           | Default answer                                                              |
+| ---------------------------------------- | --------------------------------------------------------------------------- |
+| Unknown type in Phase 1                  | Treat as "other" and use UNIVERSAL-MAP to infer                             |
+| Stack not in TEMPLATES.md                | Use Node.js template as base and adapt — log as follow-up                   |
+| User doesn't know which skills to create | Suggest 3 based on described domain + 1 universal quality skill (lint/test) |
+| User doesn't use any specific IDE        | Create only root symlinks (CLAUDE.md, AGENTS.md) and `.agents/`             |
+| Non-technical project                    | Partially skip Phase 3 (hooks); keep destructive blocking + permissions     |
+
+---
+
+## Expected Final State
+
+At the end, the target project has:
+
+```text
+target-project/
+├── .ai/
+│   ├── INSTRUCTIONS.md
+│   ├── CONVENTIONS.md
+│   ├── skills/                 (3-7 skills with minimal SKILL.md)
+│   ├── rules/                  (3-7 rules — if applicable)
+│   └── docs/
+│       ├── architecture.md     (if software)
+        └── STATE.md
+├── .claude/                    (symlinks)
+├── .cursor/, .agents/, .github/ (per declared IDEs)
+├── CLAUDE.md, AGENTS.md        (symlinks)
+├── .claude/settings.json       (versioned)
+└── scripts/                    (hooks — if software)
+```
+
+Expected complete structure in [PROMPT-TEMPLATE.md](PROMPT-TEMPLATE.md).

package/templates/bootstrap-skill/PROMPT-TEMPLATE.md

@@ -0,0 +1,128 @@
+# Prompt Template — Output Contract
+
+This is the **contract** of what a successful bootstrap delivers. Use as reference when generating and as the basis for validation in Phase 5.
+
+---
+
+## Expected Final Structure
+
+```text
+target-project/
+├── .ai/                                           ← SINGLE SOURCE
+│   ├── INSTRUCTIONS.md                            (100-180 lines)
+│   ├── CONVENTIONS.md                             (map + rules)
+│   ├── skills/
+│   │   ├── <skill-1>/SKILL.md                     (40-60 lines)
+│   │   ├── <skill-2>/SKILL.md
+│   │   └── ...                                    (3-7 skills)
+│   ├── rules/                                     (3-7 rules — if applicable)
+│   │   ├── code-style.md
+│   │   ├── architecture-patterns.md
+│   │   └── ...
+│   └── docs/
+│       ├── architecture.md                        (if software)
+│       ├── database-schema.md                     (if software)
+│       ├── glossary.md                            (if specialized domain)
+│       └── STATE.md                               (memory layer — curated playbook)
+│
+├── CLAUDE.md           → .ai/INSTRUCTIONS.md
+├── AGENTS.md           → .ai/INSTRUCTIONS.md
+│
+├── .claude/                                       (if Claude Code declared)
+│   ├── CLAUDE.md       → ../.ai/INSTRUCTIONS.md
+│   ├── rules           → ../.ai/rules
+│   ├── skills          → ../.ai/skills
+│   └── settings.json                              (versioned)
+│
+├── .cursor/, .agents/, .github/                   (per declared IDEs)
+│
+├── scripts/                                       (if software)
+│   ├── format-file.sh
+│   ├── validate-bash.sh
+│   └── run-tests-if-changed.sh
+│
+└── setup-ide-links.sh                             (idempotent)
+```
+
+---
+
+## Minimum Content per File
+
+### `.ai/INSTRUCTIONS.md`
+
+Order (consultation frequency, not logical importance):
+
+1. What the project does (1-2 sentences)
+2. Stack or tools (with versions)
+3. How to run / how to start
+4. Architecture in table (components + responsibility)
+5. Design principles (3-7 bullets with rationale)
+6. Code conventions (summary — details in rules)
+7. Available skills (table with when to use)
+8. Links to docs and references
+
+**Size:** 100-180 lines. Below 100 is superficial; above 200 loses focus.
+
+### `.ai/skills/<skill>/SKILL.md`
+
+```markdown
+---
+name: <skill-name>
+description: <2-4 lines mentioning domain terms that act as triggers>
+---
+
+# Skill Title
+
+<Purpose in 1-2 sentences.>
+
+## When to Use
+- <Scenario 1>
+- <Scenario 2>
+- <Scenario 3>
+
+## Quick Summary
+<Dense table or bullets>
+
+## References
+- [GUIDE.md](references/GUIDE.md) — <purpose>
+- [REFERENCE.md](references/REFERENCE.md) — <purpose>
+```
+
+**Size:** 40-60 lines. Description: 2-4 lines, written in third person, with trigger terms.
+
+### `.ai/CONVENTIONS.md`
+
+- Symlink map
+- Rules for the agent (where to create files, what never to do)
+- Knowledge Verification Chain
+- How to add new IDE (3-4 lines of `ln -s`)
+- Templates pointer (link to TEMPLATES.md or local copy)
+
+---
+
+## Handoff to User
+
+```markdown
+## Bootstrap Complete
+
+### What was created
+- N files in .ai/
+- N skills initialized: <list>
+- N rules: <list>
+- N stubs in docs/
+- Memory layer with STATE, CONVENTIONS
+- N symlinks distributing to <IDEs>
+- N hooks in settings.json
+
+### Metrics
+- INSTRUCTIONS.md: N lines (target 100-180) ✓
+- SKILL.md average: N lines (target 40-60) ✓
+- Symlinks: all resolve ✓
+- Smoke tests: pass ✓
+
+### Suggested next steps (3-5)
+1. Detail the first priority skill — populate references/GUIDE.md in <skill>
+2. Validate settings.json with the team
+3. Configure CI to verify symlink resolution
+4. Test invocation by another IDE (multi-tool smoke test)
+```

package/templates/bootstrap-skill/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: axis-bootstrap
+description: Bootstrap any project — software or non-technical — with a complete Spec + Harness + Memory structure for AI-augmented work. Harness-first: permissions, hooks, and symlinks are configured before prompt optimization. Use when starting a new project from scratch, when adopting AI-augmented workflows in an existing project, when migrating from a monolithic CLAUDE.md to a structured framework, or when auditing a project for missing AI infrastructure. Also handles quick-start path (5 minutes). Trigger terms: bootstrap, initialize project, AI setup, .ai structure, CLAUDE.md, AGENTS.md, multi-IDE, skills, harness, spec-driven, progressive disclosure, axis, axis-bootstrap, failure attribution, ACE, memory playbook.
+---
+
+# AXIS Bootstrap
+
+Executable spec for bootstrapping projects with complete AI infrastructure. Orchestrates the creation of three layers (Spec, Harness, Memory) in sequential phases with explicit gates. **Harness is the priority — not the prompt.**
+
+## When to Use
+
+- New project — wants solid AI-collaboration foundation
+- Existing project without structured `.ai/`, or migration from monolithic `CLAUDE.md`
+- Auditing gaps in Spec/Harness/Memory; standardizing multiple projects
+- Quick start: 5-minute path (see `references/QUICKSTART.md`)
+
+## Summary Flow
+
+| Phase | Focus | Exit Gate |
+| ----- | ----- | --------- |
+| **1 — Discovery** | Interview to understand the project | Summary confirmed by user |
+| **1.5 — SPDD Pipeline** *(optional)* | `story-decompose` → `alignment` → `abstraction-first` produce REASONS Canvas | All 7 dimensions (R/E/A/S₁/O/N/S₂) filled and confirmed |
+| **2 — Spec Layer** | Generate INSTRUCTIONS, skills, rules, docs | `.ai/` structure populated and validated |
+| **3 — Harness Layer** | Configure settings, hooks, failure attribution, symlinks | Permissions and automation in effect |
+| **4 — Memory Layer** | Create STATE (playbook), CONVENTIONS | Curated memory ready for first session |
+| **5 — Validation** | Quality gates, k-trial smoke test, handoff | Bootstrap delivered |
+| **6 — Iterative Review** *(per feature, post-bootstrap)* | `iterative-review` keeps Canvas ⇄ code in sync | Diff scoped, ACs green, STATE updated |
+
+Detailed orchestration in [PLANNER.md](PLANNER.md). Final output contract in [PROMPT-TEMPLATE.md](PROMPT-TEMPLATE.md).
+
+## Execution Principles
+
+1. **Harness before prompts** — settings.json and hooks take precedence
+2. **Do not skip phases** — each depends on validation of the previous one
+3. **Do not fabricate** — if information is missing, ask (Knowledge Verification Chain)
+4. **Confirm before generating** — show the phase plan, wait for approval
+5. **Use templates** — do not invent formats; they live in `references/TEMPLATES.md`
+
+## References
+
+- [PLANNER.md](PLANNER.md) — phase orchestration and gate rules
+- [PROMPT-TEMPLATE.md](PROMPT-TEMPLATE.md) — expected final structure of the bootstrapped project
+- [references/QUICKSTART.md](references/QUICKSTART.md) — 5-minute path
+- [references/PHASE-1-DISCOVERY.md](references/PHASE-1-DISCOVERY.md) — interview and decision tree
+- [references/PHASE-2-SPEC.md](references/PHASE-2-SPEC.md) — Spec Layer generation
+- [references/PHASE-3-HARNESS.md](references/PHASE-3-HARNESS.md) — Harness Layer configuration + failure attribution
+- [references/PHASE-4-MEMORY.md](references/PHASE-4-MEMORY.md) — Memory Layer initialization + ACE principles
+- [references/PHASE-5-VALIDATION.md](references/PHASE-5-VALIDATION.md) — quality gates and handoff
+- [references/TEMPLATES.md](references/TEMPLATES.md) — all copy-paste templates
+- [references/PATTERNS.md](references/PATTERNS.md) — technical patterns (PD, KVC, ACE, k-trial)
+- [references/CANVAS-REASONS.md](references/CANVAS-REASONS.md) — REASONS Canvas template (SPDD artifact)
+- [references/UNIVERSAL-MAP.md](references/UNIVERSAL-MAP.md) — technical ↔ non-technical mapping
+
+## Final Validation (summary)
+
+`.ai/` populated · INSTRUCTIONS 100-180 lines · SKILL.md ≤ 60 · `settings.json` versioned · symlinks resolve · `STATE.md` curated · handoff delivered. Full checklist in [references/PHASE-5-VALIDATION.md](references/PHASE-5-VALIDATION.md).

package/templates/bootstrap-skill/references/CANVAS-REASONS.md

@@ -0,0 +1,111 @@
+# REASONS Canvas — SPDD Artifact Template
+
+> Single-page spec produced collaboratively (PO + dev + AI) before code generation. Aligned with [Martin Fowler — Structured Prompt-Driven Development](https://martinfowler.com/articles/structured-prompt-driven). Filled by the AXIS SPDD pipeline (`story-decompose` → `alignment` → `abstraction-first` → generate → `iterative-review`).
+
+## Why a Canvas (not a long doc)
+
+Long specs create the illusion of work (Spec Kit issue #75). The Canvas enforces a single page per feature — if it doesn't fit, the feature is too big and must be re-decomposed via `story-decompose`.
+
+## The seven dimensions (R-E-A-S-O-N-S)
+
+| Letter  | Dimension          | Layer      | Filled by                | Purpose                                                  |
+| ------- | ------------------ | ---------- | ------------------------ | -------------------------------------------------------- |
+| **R**   | Requirements       | Abstract   | `story-decompose`        | INVEST story + Given/When/Then ACs + DoD                 |
+| **E**   | Entities           | Abstract   | `abstraction-first`      | Domain nouns, relationships, single responsibility       |
+| **A**   | Approach (Strategy)| Abstract   | `abstraction-first`      | High-level strategy to satisfy R                         |
+| **S₁**  | System structure   | Abstract   | `abstraction-first`      | Components, layer boundaries, file tree                  |
+| **O**   | Operations         | Specific   | `alignment` + dev        | Concrete, testable steps / endpoints / methods           |
+| **N**   | Norms              | Governance | `alignment`              | Engineering standards (naming, logging, defensive coding) |
+| **S₂**  | Safeguards         | Governance | `alignment`              | Non-negotiable invariants (correctness, perf, security)  |
+
+> **Layered reading:**
+> - **Abstract (R, E, A, S₁)** = intent + design. *What* and *with what shape*.
+> - **Specific (O)** = execution. *How*, step-by-step.
+> - **Governance (N, S₂)** = boundaries. *What must always hold*.
+
+## Canvas template
+
+````markdown
+# Canvas — <feature name>
+
+## R — Requirements
+**Story:** As a <role>, I want <capability>, so that <value>.
+**ACs (Given/When/Then):**
+- Given <context>, When <action>, Then <expected with concrete numbers>
+- Given …, When …, Then …
+**Definition of Done:**
+- [ ] All ACs verified with automated tests
+- [ ] <other DoD criteria>
+
+## E — Entities
+- **<EntityA>** — single responsibility: <…>; relates to <EntityB> via <…>
+- **<EntityB>** — …
+
+## A — Approach (strategy)
+<1-3 sentences on the strategy. e.g. "Compute pricing via Strategy pattern keyed on plan type, dispatched from PricingService. Use existing repository for persistence — no schema change.">
+
+## S₁ — System structure
+**Layers touched:** Controller → Service → Repository → Domain
+**Components:**
+- `PricingService` (new) — orchestrates strategy lookup and computation
+- `PricingStrategy` (interface) — Standard / Premium implementations
+**File tree (closed scope):**
+```
+src/
+├── domain/<Entity>.ts            (new)
+├── application/<Service>.ts      (modified)
+└── infrastructure/<Repo>.ts      (new)
+tests/
+└── application/<Service>.spec.ts (new)
+```
+
+## O — Operations
+- [ ] `PricingService.calculate(input)`: input → output, references AC #1, #3
+- [ ] `StandardStrategy.apply(usage)`: …
+- [ ] HTTP endpoint `POST /pricing/quote`: returns 200 with body schema X
+
+## N — Norms
+- Naming: `<Entity>Service`, `<Entity>Repository` — no abbreviations
+- Logging: structured JSON with `correlationId` on every Service entry/exit
+- Errors: throw `DomainError` for business rule violations, never return null
+- Tests: AAA, no shared mutable fixtures
+
+## S₂ — Safeguards (invariants)
+- Bill total is always non-negative
+- No PII in logs
+- Latency p95 < 200ms for `/pricing/quote`
+- DROP/TRUNCATE never executed without explicit confirmation
+````
+
+## Canvas lifecycle
+
+```text
+1. story-decompose    → fills R (one Canvas per INVEST story)
+2. alignment          → fills O (scope lock) + N + S₂
+3. abstraction-first  → fills E + A + S₁
+4. (code generation)  → uses O as direct prompt; checks N + S₂ on every step
+5. iterative-review   → updates Canvas (Track A) or syncs Canvas to code (Track B)
+```
+
+## Validation gates
+
+- [ ] All seven dimensions present (no `TBD`)
+- [ ] R has ≥2 ACs with concrete numeric values
+- [ ] E entities each have a single, stated responsibility
+- [ ] A names a concrete strategy (not "we'll figure it out")
+- [ ] S₁ file tree is **closed** — no wildcards
+- [ ] O references AC numbers from R (traceability)
+- [ ] N has ≥3 standards (naming + observability + at least one more)
+- [ ] S₂ has ≥1 invariant (otherwise no test target)
+
+## Storage
+
+- One Canvas per feature, lives in `.ai/docs/canvases/<feature-slug>.md`
+- When complete + merged, move under `.ai/docs/canvases/done/` (kept for traceability)
+- The active Canvas is referenced from `STATE.md` → In Progress
+
+## Relation to STATE.md
+
+- Canvas captures **one feature** (closed scope, eventually archived)
+- STATE captures **project-level continuity** (active decisions, blockers)
+- Deferrals from Canvas → flow into STATE → seed next Canvas