From a6ffbbc80ed05a79ef6f1b0b1ec588f0733d8a01 Mon Sep 17 00:00:00 2001
From: Vikram Reddy <gvreddy04@gmail.com>
Date: Sat, 5 Sep 2026 12:02:56 +0530
Subject: [PATCH 1/7] Refactor Devspec Protocols and Lifecycle Documentation

- Updated install-manifest.txt to remove obsolete architecture files.
- Revised lifecycle.md to clarify state vocabulary and work item stages, including new routing options.
- Enhanced repo-access.xml to include more detailed access requirements and examples.
- Modified run.xml to streamline preflight checks for repository access.
- Added last field to quickfix template for improved state tracking.
- Updated finalize.md and review.md templates to enhance traceability and findings documentation.
- Adjusted tasks.md template to ensure proper task status representation.
- Improved how-to.md to clarify installation steps and repository scope confirmation.
- Revised workflows.md to better outline new repository setup and command execution.
- Enhanced definitions.py to establish a clear lifecycle command order.
- Updated framework.py to include new lifecycle commands and improve validation checks.
- Added tests for contract consistency and protocol validation to ensure alignment with documentation.
- Introduced new protocols for revision and security to enhance project governance.
- Created state.xml protocol to standardize state vocabulary across commands.
- Implemented comprehensive tests to validate contract consistency and artifact shapes.
---
 .agents/skills/devspec-codebase-structure.md  |   2 +-
 .agents/skills/devspec-coding-standards.md    |   2 +-
 .agents/skills/devspec-extract.md             |   2 +-
 .agents/skills/devspec-grooming.md            |   2 +-
 .../devspec-codebase-structure/SKILL.md       |   2 +-
 .../skills/devspec-coding-standards/SKILL.md  |   2 +-
 .claude/skills/devspec-extract/SKILL.md       |   2 +-
 .cursor/rules/devspec-workflow.mdc            |   2 +-
 .../commands/devspec/codebase-structure.toml  |   2 +-
 .../commands/devspec/coding-standards.toml    |   2 +-
 .gemini/commands/devspec/extract.toml         |   2 +-
 .../devspec.codebase-structure.agent.md       |   2 +-
 .../agents/devspec.coding-standards.agent.md  |   2 +-
 .github/agents/devspec.extract.agent.md       |   2 +-
 .../architecture/_template/artifact-queue.md  |   4 +-
 devspec/architecture/_template/diagram.md     |  16 +-
 devspec/architecture/artifact-queue.md        |  11 +-
 devspec/architecture/overview.md              |   7 +-
 devspec/command-registry.md                   |  34 +--
 devspec/contracts/devspec.changerequest.md    |   6 +-
 devspec/contracts/devspec.clarify.md          |   9 +-
 .../contracts/devspec.codebase-structure.md   |   6 +-
 devspec/contracts/devspec.coding-standards.md |   8 +-
 devspec/contracts/devspec.diagram.md          |   7 +-
 devspec/contracts/devspec.extract.md          |  11 +-
 devspec/contracts/devspec.finalize.md         |  11 +-
 devspec/contracts/devspec.grooming.md         |   6 +-
 devspec/contracts/devspec.implement.md        |  10 +-
 devspec/contracts/devspec.projectcontext.md   |   7 +-
 devspec/contracts/devspec.quickfix.md         |   8 +-
 devspec/contracts/devspec.review.md           |  13 +-
 devspec/contracts/devspec.rules.md            |   9 +-
 devspec/contracts/devspec.story.md            |   8 +-
 devspec/contracts/devspec.tasks.md            |   7 +-
 devspec/contracts/devspec.techstack.md        |   6 +-
 .../_template/codebase-structure.md           |   4 +-
 .../foundation/_template/project-context.md   |  14 +-
 devspec/foundation/_template/rules.md         |   4 +-
 devspec/foundation/_template/tech-stack.md    |   4 +-
 devspec/glossary.md                           |  14 +-
 devspec/install-manifest.txt                  |   2 -
 devspec/lifecycle.md                          |  21 +-
 devspec/protocols/repo-access.xml             |   2 +-
 devspec/protocols/revision.xml                |   6 +
 devspec/protocols/run.xml                     |   2 +-
 devspec/protocols/security.xml                |   8 +
 devspec/protocols/state.xml                   |  10 +
 devspec/quickfixes/_template.md               |   2 +
 devspec/work-items/_template/finalize.md      |   2 +-
 devspec/work-items/_template/review.md        |   6 +-
 devspec/work-items/_template/tasks.md         |   2 +-
 docs/how-to.md                                |   6 +-
 docs/workflows.md                             |   2 +-
 src/devspec_lite/definitions.py               |  29 +++
 src/devspec_lite/framework.py                 |  39 +++-
 tests/test_contract_consistency.py            | 194 ++++++++++++++++++
 tests/test_framework.py                       |  13 +-
 57 files changed, 448 insertions(+), 170 deletions(-)
 create mode 100644 devspec/protocols/revision.xml
 create mode 100644 devspec/protocols/security.xml
 create mode 100644 devspec/protocols/state.xml
 create mode 100644 tests/test_contract_consistency.py

diff --git a/.agents/skills/devspec-codebase-structure.md b/.agents/skills/devspec-codebase-structure.md
index 785fd7b..19ab054 100644
--- a/.agents/skills/devspec-codebase-structure.md
+++ b/.agents/skills/devspec-codebase-structure.md
@@ -1,5 +1,5 @@
 ---
 name: devspec-codebase-structure
-description: Capture owned source roots, module boundaries, integrations, and repository access.
+description: Capture or customize owned source roots, repository layouts, module boundaries, integrations, and repository access.
 ---
 Read and execute `devspec/contracts/devspec.codebase-structure.md`.
diff --git a/.agents/skills/devspec-coding-standards.md b/.agents/skills/devspec-coding-standards.md
index c23ee48..50c5269 100644
--- a/.agents/skills/devspec-coding-standards.md
+++ b/.agents/skills/devspec-coding-standards.md
@@ -1,5 +1,5 @@
 ---
 name: devspec-coding-standards
-description: Capture reusable observed or developer-defined coding standards with numbered examples.
+description: Capture concise, reusable coding conventions, followable examples, and anti-patterns from source evidence or developer-defined standards.
 ---
 Read and execute `devspec/contracts/devspec.coding-standards.md`.
diff --git a/.agents/skills/devspec-extract.md b/.agents/skills/devspec-extract.md
index 6552a6a..e2c7fe6 100644
--- a/.agents/skills/devspec-extract.md
+++ b/.agents/skills/devspec-extract.md
@@ -1,5 +1,5 @@
 ---
 name: devspec-extract
-description: Backfill concise foundation evidence from an existing repository.
+description: Inspect the approved existing system end-to-end, produce its technical, business, workflow, and rule baseline, and prepare an evidence-backed diagram candidate list for explicit generation approval.
 ---
 Read and execute `devspec/contracts/devspec.extract.md`.
diff --git a/.agents/skills/devspec-grooming.md b/.agents/skills/devspec-grooming.md
index 01194b9..d729cad 100644
--- a/.agents/skills/devspec-grooming.md
+++ b/.agents/skills/devspec-grooming.md
@@ -1,5 +1,5 @@
 ---
 name: devspec-grooming
-description: Make one draft story buildable through scoped review and targeted questions.
+description: Make one draft story buildable through scoped review and material questions.
 ---
 Read and execute `devspec/contracts/devspec.grooming.md`.
diff --git a/.claude/skills/devspec-codebase-structure/SKILL.md b/.claude/skills/devspec-codebase-structure/SKILL.md
index 785fd7b..19ab054 100644
--- a/.claude/skills/devspec-codebase-structure/SKILL.md
+++ b/.claude/skills/devspec-codebase-structure/SKILL.md
@@ -1,5 +1,5 @@
 ---
 name: devspec-codebase-structure
-description: Capture owned source roots, module boundaries, integrations, and repository access.
+description: Capture or customize owned source roots, repository layouts, module boundaries, integrations, and repository access.
 ---
 Read and execute `devspec/contracts/devspec.codebase-structure.md`.
diff --git a/.claude/skills/devspec-coding-standards/SKILL.md b/.claude/skills/devspec-coding-standards/SKILL.md
index b66bbe2..50c5269 100644
--- a/.claude/skills/devspec-coding-standards/SKILL.md
+++ b/.claude/skills/devspec-coding-standards/SKILL.md
@@ -1,5 +1,5 @@
 ---
 name: devspec-coding-standards
-description: Capture short, evidence-backed conventions and anti-patterns.
+description: Capture concise, reusable coding conventions, followable examples, and anti-patterns from source evidence or developer-defined standards.
 ---
 Read and execute `devspec/contracts/devspec.coding-standards.md`.
diff --git a/.claude/skills/devspec-extract/SKILL.md b/.claude/skills/devspec-extract/SKILL.md
index ea65694..e2c7fe6 100644
--- a/.claude/skills/devspec-extract/SKILL.md
+++ b/.claude/skills/devspec-extract/SKILL.md
@@ -1,5 +1,5 @@
 ---
 name: devspec-extract
-description: Inspect the approved existing system end-to-end and produce its technical, business, workflow, rule, and diagram baseline without requiring separate foundation or diagram commands.
+description: Inspect the approved existing system end-to-end, produce its technical, business, workflow, and rule baseline, and prepare an evidence-backed diagram candidate list for explicit generation approval.
 ---
 Read and execute `devspec/contracts/devspec.extract.md`.
diff --git a/.cursor/rules/devspec-workflow.mdc b/.cursor/rules/devspec-workflow.mdc
index 68236b8..f0fa80b 100644
--- a/.cursor/rules/devspec-workflow.mdc
+++ b/.cursor/rules/devspec-workflow.mdc
@@ -2,4 +2,4 @@
 description: Devspec Lite workflow
 alwaysApply: false
 ---
-For `devspec.changerequest`, `devspec.clarify`, `devspec.codebase-structure`, `devspec.coding-standards`, `devspec.diagram`, `devspec.extract`, `devspec.finalize`, `devspec.grooming`, `devspec.implement`, `devspec.projectcontext`, `devspec.quickfix`, `devspec.review`, `devspec.rules`, `devspec.story`, `devspec.tasks`, `devspec.techstack`, read the matching `devspec/contracts/` file and listed protocols. For a clear continuation, resolve per-worktree current context and run only the saved next action; ask before switching stories.
+For `devspec.extract`, `devspec.projectcontext`, `devspec.techstack`, `devspec.codebase-structure`, `devspec.coding-standards`, `devspec.rules`, `devspec.story`, `devspec.grooming`, `devspec.clarify`, `devspec.changerequest`, `devspec.finalize`, `devspec.tasks`, `devspec.implement`, `devspec.review`, `devspec.diagram`, `devspec.quickfix`, read the matching `devspec/contracts/` file and listed protocols. For a clear continuation, resolve per-worktree current context and run only the saved next action; ask before switching stories.
diff --git a/.gemini/commands/devspec/codebase-structure.toml b/.gemini/commands/devspec/codebase-structure.toml
index 6d67d8d..51c6168 100644
--- a/.gemini/commands/devspec/codebase-structure.toml
+++ b/.gemini/commands/devspec/codebase-structure.toml
@@ -1,2 +1,2 @@
-description = "Capture owned source roots, module boundaries, integrations, and repository access."
+description = "Capture or customize owned source roots, repository layouts, module boundaries, integrations, and repository access."
 prompt = "Read and execute devspec/contracts/devspec.codebase-structure.md"
diff --git a/.gemini/commands/devspec/coding-standards.toml b/.gemini/commands/devspec/coding-standards.toml
index eb62300..ff86ac3 100644
--- a/.gemini/commands/devspec/coding-standards.toml
+++ b/.gemini/commands/devspec/coding-standards.toml
@@ -1,2 +1,2 @@
-description = "Capture short, evidence-backed conventions and anti-patterns."
+description = "Capture concise, reusable coding conventions, followable examples, and anti-patterns from source evidence or developer-defined standards."
 prompt = "Read and execute devspec/contracts/devspec.coding-standards.md"
diff --git a/.gemini/commands/devspec/extract.toml b/.gemini/commands/devspec/extract.toml
index c49329e..b121a71 100644
--- a/.gemini/commands/devspec/extract.toml
+++ b/.gemini/commands/devspec/extract.toml
@@ -1,2 +1,2 @@
-description = "Inspect the approved existing system end-to-end and produce its technical, business, workflow, rule, and diagram baseline without requiring separate foundation or diagram commands."
+description = "Inspect the approved existing system end-to-end, produce its technical, business, workflow, and rule baseline, and prepare an evidence-backed diagram candidate list for explicit generation approval."
 prompt = "Read and execute devspec/contracts/devspec.extract.md"
diff --git a/.github/agents/devspec.codebase-structure.agent.md b/.github/agents/devspec.codebase-structure.agent.md
index 043cc53..838c9f0 100644
--- a/.github/agents/devspec.codebase-structure.agent.md
+++ b/.github/agents/devspec.codebase-structure.agent.md
@@ -1,6 +1,6 @@
 ---
 name: devspec.codebase-structure
-description: Capture owned source roots, module boundaries, integrations, and repository access.
+description: Capture or customize owned source roots, repository layouts, module boundaries, integrations, and repository access.
 user-invocable: true
 ---
 Execute `devspec/contracts/devspec.codebase-structure.md`.
diff --git a/.github/agents/devspec.coding-standards.agent.md b/.github/agents/devspec.coding-standards.agent.md
index ee8257b..861a28f 100644
--- a/.github/agents/devspec.coding-standards.agent.md
+++ b/.github/agents/devspec.coding-standards.agent.md
@@ -1,6 +1,6 @@
 ---
 name: devspec.coding-standards
-description: Capture short, evidence-backed conventions and anti-patterns.
+description: Capture concise, reusable coding conventions, followable examples, and anti-patterns from source evidence or developer-defined standards.
 user-invocable: true
 ---
 Execute `devspec/contracts/devspec.coding-standards.md`.
diff --git a/.github/agents/devspec.extract.agent.md b/.github/agents/devspec.extract.agent.md
index d9417d8..6f089c1 100644
--- a/.github/agents/devspec.extract.agent.md
+++ b/.github/agents/devspec.extract.agent.md
@@ -1,6 +1,6 @@
 ---
 name: devspec.extract
-description: Backfill concise foundation evidence from an existing repository.
+description: Inspect the approved existing system end-to-end, produce its technical, business, workflow, and rule baseline, and prepare an evidence-backed diagram candidate list for explicit generation approval.
 user-invocable: true
 ---
 Execute `devspec/contracts/devspec.extract.md`.
diff --git a/devspec/architecture/_template/artifact-queue.md b/devspec/architecture/_template/artifact-queue.md
index 2aee793..f51949f 100644
--- a/devspec/architecture/_template/artifact-queue.md
+++ b/devspec/architecture/_template/artifact-queue.md
@@ -1,4 +1,4 @@
 # Architecture Artifact Queue
 
-| ID | Scope | Type | Subject | Output | Evidence | Status | Next |
-|---|---|---|---|---|---|---|---|
+| ID | Scope | Type | Subject | Output | Evidence | Duplicate check | Status | Next |
+|---|---|---|---|---|---|---|---|---|
diff --git a/devspec/architecture/_template/diagram.md b/devspec/architecture/_template/diagram.md
index b927565..19d30d8 100644
--- a/devspec/architecture/_template/diagram.md
+++ b/devspec/architecture/_template/diagram.md
@@ -1,6 +1,6 @@
 # Architecture Diagram
 
-Use this optional Markdown artifact for one durable Mermaid architecture, module, feature, workflow, process-flow, user journey, sequence, state, or domain diagram when the selected output set includes `mermaid`. SVG is the default diagram output and lives under `devspec/architecture/images/`; HTML is optional and lives under `devspec/architecture/html/`. Keep diagram status in `devspec/architecture/artifact-queue.md`; keep generated content references, supporting evidence, assumptions, and maintenance notes here when this Markdown artifact is created.
+Use this optional Markdown artifact for one durable Mermaid architecture, module, feature, workflow, process-flow, user journey, sequence, state, or domain diagram when the selected output set includes `mermaid`. SVG is the default diagram output and lives under `devspec/architecture/diagrams/`; HTML is optional and lives under `devspec/architecture/diagrams/`. Keep diagram status in `devspec/architecture/artifact-queue.md`; keep generated content references, supporting evidence, assumptions, and maintenance notes here when this Markdown artifact is created.
 
 ## Resume State
 
@@ -9,7 +9,7 @@ Use this optional Markdown artifact for one durable Mermaid architecture, module
 | Current stage | diagram |
 | Current command | `/devspec.diagram` |
 | Current agent | devspec.diagram |
-| Run status | See `devspec/glossary.md#run-status-values` |
+| Run status | See `devspec/protocols/state.xml` |
 | Current item | |
 | Last completed step | |
 | Next required action | |
@@ -35,12 +35,12 @@ Use this optional Markdown artifact for one durable Mermaid architecture, module
 | Architecture style | monolith, microservices, event-driven, serverless, agentic workflow, multi-repo, cloud-native, or user-provided style |
 | Output format | mermaid, svg+mermaid, html+mermaid, or svg+html+mermaid |
 | Mermaid declaration | flowchart TD, flowchart LR, flowchart BT, sequenceDiagram, journey, stateDiagram-v2, classDiagram, erDiagram, gantt, quadrantChart, mindmap, timeline |
-| SVG target | `devspec/architecture/images/dia-NNN-<diagram-name>.svg` when output format includes svg |
-| HTML target | `devspec/architecture/html/dia-NNN-<diagram-name>.html` when output format includes html |
+| SVG target | `devspec/architecture/diagrams/dia-NNN-<diagram-name>.svg` when output format includes svg |
+| HTML target | `devspec/architecture/diagrams/dia-NNN-<diagram-name>.html` when output format includes html |
 | Subject | `dia-NNN-<diagram-name>` |
 | Confidence | observed, high-confidence, low-confidence |
 | Tags | |
-| Queue row | `devspec/architecture/artifact-queue.md#diagram-queue-register` |
+| Queue row | `devspec/architecture/artifact-queue.md` |
 
 When a request uses the structured architecture-diagram prompt format and the selected output set includes `mermaid`, reflect the provided system name, architecture style, purpose, audience, actors, components, stores, flows, boundaries, design rules, and output format in this metadata, the queue row notes, source evidence and assumptions, and generated diagram content. If the request uses structured non-architecture diagram input, reflect the matching sequence, state/lifecycle, domain model, journey, timeline/gantt, quadrant, or mindmap fields in this metadata, the queue row notes, source evidence and assumptions, generated Mermaid content, and any SVG or HTML companion output. If the request omits output format, use SVG-only output and do not create this Markdown artifact.
 
@@ -101,9 +101,9 @@ flowchart TD
 ## Companion Outputs
 
 - Use this section when `Output format` includes `svg` or `html`.
-- Store the durable SVG at `devspec/architecture/images/dia-NNN-<diagram-name>.svg`.
-- Store optional standalone HTML at `devspec/architecture/html/dia-NNN-<diagram-name>.html`.
-- Select SVG templates from `.github/prompts/PATTERNS.md#svg-output-pattern`: `architecture-diagram.svg`, `process-flow-diagram.svg`, `sequence-diagram.svg`, `state-lifecycle-diagram.svg`, `domain-model-diagram.svg`, `journey-map-diagram.svg`, `timeline-plan-diagram.svg`, `quadrant-analysis-diagram.svg`, or `mindmap-diagram.svg`. Every template must preserve the shared dark architecture-style visual contract unless a documented constraint requires a smaller custom SVG.
+- Store the durable SVG at `devspec/architecture/diagrams/dia-NNN-<diagram-name>.svg`.
+- Store optional standalone HTML at `devspec/architecture/diagrams/dia-NNN-<diagram-name>.html`.
+- Select SVG templates from `devspec/architecture/_template/`: `architecture-diagram.svg`, `process-flow-diagram.svg`, `sequence-diagram.svg`, `state-lifecycle-diagram.svg`, `domain-model-diagram.svg`, `journey-map-diagram.svg`, `timeline-plan-diagram.svg`, `quadrant-analysis-diagram.svg`, or `mindmap-diagram.svg`. Every template must preserve the shared dark architecture-style visual contract unless a documented constraint requires a smaller custom SVG.
 - Generated SVG must be standalone XML with inline styles and no external assets, `<script>`, `<iframe>`, `<foreignObject>`, remote fonts, remote images, secrets, credentials, internal-only URLs, or unresolved placeholders.
 - Generated HTML must be standalone static HTML with inline styles and no external assets, `<script>`, `<iframe>`, remote fonts, remote images, secrets, credentials, internal-only URLs, or unresolved placeholders.
 - Validate the SVG as XML before reporting generation complete.
diff --git a/devspec/architecture/artifact-queue.md b/devspec/architecture/artifact-queue.md
index 76b0da9..bba7bf5 100644
--- a/devspec/architecture/artifact-queue.md
+++ b/devspec/architecture/artifact-queue.md
@@ -1,7 +1,8 @@
 # Architecture Artifact Queue
 
-| ID | Scope | Type | Subject | Output | Evidence | Status | Next |
-|---|---|---|---|---|---|---|---|
-| DOC-001 | workflow | flowchart | foundation-route | `docs/assets/foundation-routes.svg` | command registry, repository state | complete | none |
-| DOC-002 | workflow | flowchart | delivery-route | `docs/assets/delivery-routes.svg` | command contracts, protocols | complete | none |
-| DOC-003 | workflow | flowchart | install-lifecycle | `docs/assets/maintenance-flow.svg` | CLI, Doctor, setup guides | complete | none |
+| ID | Scope | Type | Subject | Output | Evidence | Duplicate check | Status | Next |
+|---|---|---|---|---|---|---|---|---|
+| DIA-001 | workflow | Process flow | foundation-route | `docs/assets/foundation-routes.svg` | command registry, repository state | none | complete | none |
+| DIA-002 | workflow | Process flow | delivery-route | `docs/assets/delivery-routes.svg` | command contracts, protocols | none | complete | none |
+| DIA-003 | workflow | Process flow | install-lifecycle | `docs/assets/maintenance-flow.svg` | CLI, doctor, setup guides | none | complete | none |
+| DIA-004 | workflow | Process flow | manual-copy-route | `docs/assets/manual-copy-flow.svg` | manual copy guide, install manifest | none | complete | none |
diff --git a/devspec/architecture/overview.md b/devspec/architecture/overview.md
index 32d32b5..19204ec 100644
--- a/devspec/architecture/overview.md
+++ b/devspec/architecture/overview.md
@@ -9,6 +9,7 @@
 
 | ID | Diagram | Scope | Evidence | Link |
 |---|---|---|---|---|
-| DOC-001 | Foundation route | workflow | command registry, repository state | `docs/assets/foundation-routes.svg` |
-| DOC-002 | Delivery route | workflow | command contracts, protocols | `docs/assets/delivery-routes.svg` |
-| DOC-003 | Install lifecycle | workflow | CLI, Doctor, setup guides | `docs/assets/maintenance-flow.svg` |
+| DIA-001 | Foundation route | workflow | command registry, repository state | `docs/assets/foundation-routes.svg` |
+| DIA-002 | Delivery route | workflow | command contracts, protocols | `docs/assets/delivery-routes.svg` |
+| DIA-003 | Install lifecycle | workflow | CLI, doctor, setup guides | `docs/assets/maintenance-flow.svg` |
+| DIA-004 | Manual copy route | workflow | manual copy guide, install manifest | `docs/assets/manual-copy-flow.svg` |
diff --git a/devspec/command-registry.md b/devspec/command-registry.md
index 24175a1..7dcfa5e 100644
--- a/devspec/command-registry.md
+++ b/devspec/command-registry.md
@@ -1,22 +1,24 @@
 # Command Registry
 
+Purpose and next route are the contract's own `<purpose>` and `<transition next>` values. Change the contract, not this table.
+
 | Command | Purpose | Next route |
 |---|---|---|
-| `devspec.extract` | Build the complete evidence-backed baseline for an existing scoped system, prepare the applicable diagram list, then obtain explicit all-or-selected generation approval. | `devspec.story` or `devspec.clarify` |
-| `devspec.projectcontext` | Capture product purpose, users, outcomes, and scope boundaries. | `techstack` |
-| `devspec.techstack` | Capture evidence-backed runtime, frameworks, data, tooling, and delivery constraints. | `codebase-structure` |
-| `devspec.codebase-structure` | Capture or customize owned roots, representative repository layout trees, boundaries, integrations, and access. | `coding-standards` |
-| `devspec.coding-standards` | Capture or update reusable observed or developer-defined standards with linked numbered code examples and anti-patterns. | `rules` |
-| `devspec.rules` | Capture non-negotiable engineering, security, compliance, delivery, and accessibility rules. | `story` |
-| `devspec.story` | Create one concise work-item intake from a request or provider reference. | `devspec.grooming` or `devspec.finalize` |
-| `devspec.grooming` | Make one draft story buildable through scoped review and material questions. | `devspec.clarify` or `devspec.finalize` |
-| `devspec.clarify` | Resolve one active blocker and resume its originating command. | `resume-origin` |
-| `devspec.changerequest` | Append one related post-finalization requirement without rewriting history. | `finalize` |
-| `devspec.finalize` | Produce a concise readiness brief and validation plan. | `devspec.clarify` or `devspec.tasks` |
-| `devspec.tasks` | Create ordered, independently verifiable implementation tasks. | `implement` |
-| `devspec.implement` | Implement pending ready tasks with focused checkpoints and validation. | `review` |
-| `devspec.review` | Review changed work, record an outcome, and set one next action. | `devspec.implement`, `devspec.clarify`, or terminal |
-| `devspec.diagram` | Create one targeted evidence-backed diagram with duplicate checks and durable queue state. | return to caller |
-| `devspec.quickfix` | Implement and validate one localized, low-risk enhancement or bug fix. | terminal, `devspec.clarify`, or `devspec.story` |
+| `devspec.extract` | Inspect the approved existing system end-to-end, produce its technical, business, workflow, and rule baseline, and prepare an evidence-backed diagram candidate list for explicit generation approval. | `devspec.story`, `devspec.clarify` |
+| `devspec.projectcontext` | Capture product purpose, users, outcomes, and scope boundaries. | `devspec.techstack`, `return-to-caller`, `devspec.clarify` |
+| `devspec.techstack` | Capture evidence-backed runtime, frameworks, data, tooling, and delivery constraints. | `devspec.codebase-structure`, `return-to-caller`, `devspec.clarify` |
+| `devspec.codebase-structure` | Capture or customize owned source roots, repository layouts, module boundaries, integrations, and repository access. | `devspec.coding-standards`, `return-to-caller`, `devspec.clarify` |
+| `devspec.coding-standards` | Capture concise, reusable coding conventions, followable examples, and anti-patterns from source evidence or developer-defined standards. | `devspec.rules`, `return-to-caller`, `devspec.clarify` |
+| `devspec.rules` | Capture non-negotiable engineering, security, compliance, delivery, and accessibility rules. | `devspec.story`, `return-to-caller`, `devspec.clarify` |
+| `devspec.story` | Create one concise work-item intake from a request or provider reference. | `devspec.grooming`, `devspec.finalize`, `devspec.clarify` |
+| `devspec.grooming` | Make one draft story buildable through scoped review and material questions. | `devspec.finalize`, `devspec.clarify` |
+| `devspec.clarify` | Resolve one active blocker and resume its originating stage. | `resume-origin` |
+| `devspec.changerequest` | Append one related post-finalization requirement without rewriting history. | `devspec.finalize`, `devspec.clarify` |
+| `devspec.finalize` | Produce a concise readiness brief and validation plan. | `devspec.tasks`, `devspec.clarify` |
+| `devspec.tasks` | Create ordered, independently verifiable implementation tasks. | `devspec.implement`, `devspec.clarify` |
+| `devspec.implement` | Implement pending ready tasks with focused checkpoints and validation. | `devspec.review`, `devspec.clarify` |
+| `devspec.review` | Review changed work against readiness, tasks, and validation evidence. | `none`, `devspec.implement`, `devspec.clarify` |
+| `devspec.diagram` | Create one evidence-backed diagram with duplicate checks and durable queue state. | `return-to-caller`, `devspec.clarify` |
+| `devspec.quickfix` | Implement and validate one localized, low-risk enhancement or bug fix. | `none`, `devspec.clarify`, `devspec.story` |
 
 Work-item IDs are optional for `grooming`, `finalize`, `tasks`, `implement`, `review`, `clarify`, and `changerequest`. Without an ID, resolve the private per-worktree current context and run only the work item's recorded `next` action. Use an explicit ID to switch stories; when several eligible stories exist, ask the user to choose.
diff --git a/devspec/contracts/devspec.changerequest.md b/devspec/contracts/devspec.changerequest.md
index d45c969..986b1d1 100644
--- a/devspec/contracts/devspec.changerequest.md
+++ b/devspec/contracts/devspec.changerequest.md
@@ -9,9 +9,12 @@ Invocation: `/devspec.changerequest [work-item-id] Add JSON export`
   <protocols>
     <protocol ref="ask" />
     <protocol ref="run" />
+    <protocol ref="state" />
     <protocol ref="current-work-item" />
+    <protocol ref="revision" />
     <protocol ref="work" />
   </protocols>
+  <scope>Use only for a requirement related to a work item that is already finalized. Use devspec.story for independent scope, and edit the story directly while it is still before finalization.</scope>
   <input>An optional work-item ID and one related missing requirement.</input>
   <rules>
     <rule>Append the next CR-### entry and CR-scoped criteria; never rewrite baseline evidence.</rule>
@@ -27,7 +30,4 @@ Invocation: `/devspec.changerequest [work-item-id] Add JSON export`
     <transition outcome="classification-blocked" stage="finalization" run="blocked" next="devspec.clarify" />
   </transitions>
   <closure>Append the CR, increment scope_revision, mark downstream records superseded, and preserve their historical evidence.</closure>
-  <actions>Classify scope as related or independent; append the next CR identifier when related.</actions>
-  <artifact>devspec/work-items/&lt;id&gt;/story.md</artifact>
-  <handoff>finalize</handoff>
 </workflow>
diff --git a/devspec/contracts/devspec.clarify.md b/devspec/contracts/devspec.clarify.md
index 93197b7..7f82bc0 100644
--- a/devspec/contracts/devspec.clarify.md
+++ b/devspec/contracts/devspec.clarify.md
@@ -8,9 +8,13 @@ Invocation: `/devspec.clarify [work-item-id]`
   <purpose>Resolve one active blocker and resume its originating stage.</purpose>
   <protocols>
     <protocol ref="ask" />
-    <protocol ref="current-work-item" />
     <protocol ref="run" />
+    <protocol ref="state" />
+    <protocol ref="current-work-item" />
+    <protocol ref="revision" />
+    <protocol ref="work" />
   </protocols>
+  <scope>Use only to resolve one recorded material blocker and resume the command that recorded it. This command never advances a stage, changes scope, or answers a question its originating command has not recorded.</scope>
   <input>An optional work-item ID, or one foundation or quickfix record, with one active material blocker question.</input>
   <rules>
     <rule>Resolve the one highest-priority material decision in its active queue and append its answer to decisions.md. For a work item, append the origin command, question, resolution, evidence, and exact resume command to clarify.md.</rule>
@@ -28,7 +32,4 @@ Invocation: `/devspec.clarify [work-item-id]`
     <transition outcome="decision-resolved" stage="origin" run="active" next="resume-origin" />
   </transitions>
   <closure>Append the resolution, restore the exact saved stage and next command, and do not change scope while resolving a blocker.</closure>
-  <actions>Ask the recorded high-priority material question, append the resolution, and return to the saved next action.</actions>
-  <artifact>devspec/work-items/&lt;id&gt;/decisions.md</artifact>
-  <handoff>resume-origin</handoff>
 </workflow>
diff --git a/devspec/contracts/devspec.codebase-structure.md b/devspec/contracts/devspec.codebase-structure.md
index 849d8ee..4f3b0a6 100644
--- a/devspec/contracts/devspec.codebase-structure.md
+++ b/devspec/contracts/devspec.codebase-structure.md
@@ -9,6 +9,7 @@ Invocation: `/devspec.codebase-structure`
   <protocols>
     <protocol ref="ask" />
     <protocol ref="run" />
+    <protocol ref="state" />
     <protocol ref="work" />
     <protocol ref="repo-access" />
   </protocols>
@@ -23,13 +24,12 @@ Invocation: `/devspec.codebase-structure`
   <entry>Completed technology stack in the new foundation chain, or an explicit targeted update; reject an existing-system baseline request.</entry>
   <outputs>
     <artifact path="devspec/foundation/codebase-structure.md" />
+    <artifact path="devspec/foundation/decisions.md" />
   </outputs>
   <transitions>
     <transition outcome="foundation-updated" stage="foundation" run="active" next="devspec.coding-standards" />
     <transition outcome="targeted-update-complete" stage="foundation" run="active" next="return-to-caller" />
+    <transition outcome="evidence-blocked" stage="foundation" run="blocked" next="devspec.clarify" />
   </transitions>
   <closure>Record repository access boundaries, representative layout trees, and one registered next command; blocked evidence routes to devspec.clarify.</closure>
-  <actions>Map or customize owned areas, then record repository paths, roles, named access requirements, and layout origins before relying on them.</actions>
-  <artifact>devspec/foundation/codebase-structure.md</artifact>
-  <handoff>coding-standards</handoff>
 </workflow>
diff --git a/devspec/contracts/devspec.coding-standards.md b/devspec/contracts/devspec.coding-standards.md
index c3041b5..be1a613 100644
--- a/devspec/contracts/devspec.coding-standards.md
+++ b/devspec/contracts/devspec.coding-standards.md
@@ -1,6 +1,6 @@
 # devspec.coding-standards
 
-Capture concise, reusable coding conventions, examples, and anti-patterns.
+Capture concise, reusable coding conventions, followable examples, and anti-patterns from source evidence or developer-defined standards.
 
 Invocation: `/devspec.coding-standards`
 
@@ -9,6 +9,7 @@ Invocation: `/devspec.coding-standards`
   <protocols>
     <protocol ref="ask" />
     <protocol ref="run" />
+    <protocol ref="state" />
     <protocol ref="work" />
   </protocols>
   <scope>Use for new-repository foundation authoring or an explicitly requested targeted update. Use devspec.extract, not this command, to establish an existing-system baseline.</scope>
@@ -22,13 +23,12 @@ Invocation: `/devspec.coding-standards`
   <entry>Completed codebase structure in the new foundation chain, or an explicit targeted update; reject an existing-system baseline request.</entry>
   <outputs>
     <artifact path="devspec/foundation/coding-standards.md" />
+    <artifact path="devspec/foundation/decisions.md" />
   </outputs>
   <transitions>
     <transition outcome="foundation-updated" stage="foundation" run="active" next="devspec.rules" />
     <transition outcome="targeted-update-complete" stage="foundation" run="active" next="return-to-caller" />
+    <transition outcome="evidence-blocked" stage="foundation" run="blocked" next="devspec.clarify" />
   </transitions>
   <closure>Record each retained standard with its stable ID, origin, linked numbered examples, and an anti-pattern when applicable, then register one next command; blocked evidence routes to devspec.clarify.</closure>
-  <actions>Record only standards that change a developer action, preserving developer-defined numbered examples as reusable implementation guidance.</actions>
-  <artifact>devspec/foundation/coding-standards.md</artifact>
-  <handoff>rules</handoff>
 </workflow>
diff --git a/devspec/contracts/devspec.diagram.md b/devspec/contracts/devspec.diagram.md
index 797f956..c8f3dd1 100644
--- a/devspec/contracts/devspec.diagram.md
+++ b/devspec/contracts/devspec.diagram.md
@@ -9,18 +9,20 @@ Invocation: `/devspec.diagram runtime architecture format=svg motion=none|explai
   <protocols>
     <protocol ref="ask" />
     <protocol ref="run" />
+    <protocol ref="state" />
     <protocol ref="work" />
     <protocol ref="repo-access" />
   </protocols>
   <scope>Use for one targeted diagram in the current approved context. An explicit process-flow batch request may generate every queued, non-duplicate process-flow candidate; devspec.extract otherwise owns existing-system diagram discovery, candidate listing, and all-or-selected generation approval.</scope>
   <input>Diagram queue ID, subject, work item, explicit process-flow batch request, format request, or optional `motion=none|explain` in the current repository or an explicitly scoped multi-repository system.</input>
   <rules>
+    <rule>Read only the evidence the requested subject needs, the one diagram-type pattern selected, and its matching family template. Do not load unrelated templates or explore beyond the subject's confirmed boundary.</rule>
     <rule>Select the diagram type from devspec/architecture/_template/diagram-types.md; load only the needed pattern.</rule>
     <rule>Start each SVG from the matching family-specific template: `architecture-diagram.svg` for system architecture, application landscape, and infrastructure topology; `process-flow-diagram.svg` for process flows; `sequence-diagram.svg` for interactions; `state-lifecycle-diagram.svg` for state behavior; `domain-model-diagram.svg` for domain models; `journey-map-diagram.svg` for journeys; `timeline-plan-diagram.svg` for timelines; `quadrant-analysis-diagram.svg` for quadrants; and `mindmap-diagram.svg` for mind maps.</rule>
     <rule>Create only evidence-backed, non-duplicate diagrams and persist queue or overview state for recovery.</rule>
     <rule>For a multi-repository diagram, use repo-access before reading or validating another repository.</rule>
     <rule>Accept a stable queued `DIA-###` ID or diagram subject, record subject, type, evidence, format, status, and next in the queue, and index completed output in the overview. On an explicit process-flow batch request, generate every queued non-duplicate process-flow candidate, validate each output, update each queue row independently, and leave the caller lifecycle state unchanged.</rule>
-    <rule>Default to SVG with title and description and validate its XML; write Mermaid or HTML only when explicitly requested.</rule>
+    <rule>Default to SVG with title and description and validate its XML. Write Mermaid or HTML only when explicitly requested, and when you do, record it from `devspec/architecture/_template/diagram.md` or `diagram.html` so its evidence, assumptions, and maintenance notes stay with the output.</rule>
     <rule>Default to `motion=none`. Treat an explicit request for an animated diagram without a motion value as `motion=explain`; reject unsupported motion values.</rule>
     <rule>For `motion=explain`, animate only an evidence-backed sequence, flow, or state transition and follow the opt-in motion guidance in diagram-types.md. Keep the complete meaning visible in the static final frame, provide a reduced-motion result with no information loss, and do not add decorative motion or imply unsupported behavior.</rule>
     <rule>Record animated SVG output in the queue's existing Output field as `svg; motion=explain`. When HTML is also requested, inline the same SVG so its motion and reduced-motion behavior remain intact.</rule>
@@ -38,7 +40,4 @@ Invocation: `/devspec.diagram runtime architecture format=svg motion=none|explai
     <transition outcome="evidence-blocked" stage="caller" run="blocked" next="devspec.clarify" />
   </transitions>
   <closure>Validate the queued output, including finite animation and final-frame and reduced-motion completeness when motion is requested; index only completed diagrams, and leave the caller's saved stage unchanged.</closure>
-  <actions>Use static SVG by default; add explanatory motion, Mermaid, or HTML only when requested.</actions>
-  <artifact>devspec/architecture/artifact-queue.md</artifact>
-  <handoff>return-to-caller</handoff>
 </workflow>
diff --git a/devspec/contracts/devspec.extract.md b/devspec/contracts/devspec.extract.md
index e4288fc..67a250e 100644
--- a/devspec/contracts/devspec.extract.md
+++ b/devspec/contracts/devspec.extract.md
@@ -1,6 +1,6 @@
 # devspec.extract
 
-Build a complete evidence-backed baseline for one existing repository or an explicitly scoped multi-repository system.
+Inspect the approved existing system end-to-end, produce its technical, business, workflow, and rule baseline, and prepare an evidence-backed diagram candidate list for explicit generation approval.
 
 Invocation: `/devspec.extract`
 
@@ -9,9 +9,12 @@ Invocation: `/devspec.extract`
   <protocols>
     <protocol ref="ask" />
     <protocol ref="run" />
+    <protocol ref="state" />
     <protocol ref="work" />
     <protocol ref="repo-access" />
+    <protocol ref="security" />
   </protocols>
+  <scope>Use for the existing-system baseline of an approved source scope. This command completes the whole foundation chain in one run; do not also run the individual foundation commands for the same repository. It prepares diagram candidates and offers generation once; devspec.diagram owns every later diagram.</scope>
   <input>Explicitly confirmed source repository scope, or current canonical evidence that names each repository's role, local path, and allowed access.</input>
   <rules>
     <rule>Treat the agent's current workspace or scaffolding directory as a proposed source target, never proof. Before inspecting source, obtain either an explicit user confirmation that names every source repository, role, path, and read, edit, and validation permission, or current canonical evidence that records those facts. If neither exists, first collect one repository path at a time, then ask one access question after each confirmed path; record the accepted source scope in `devspec/foundation/codebase-structure.md` before reading source. Later commands may use that current record as scope evidence.</rule>
@@ -28,6 +31,7 @@ Invocation: `/devspec.extract`
     <rule>After all foundation extraction outputs are complete, show the user or developer the complete candidate list. When one or more candidates exist, ask exactly one interactive confirmation: "Do you want me generate all the possible diagrams?" Offer: `Yes — generate all listed diagrams`, `No — prepare the list only`, `Choose diagrams — enter the IDs or subjects to generate`, and `Custom Answer`. Recommend `No — prepare the list only` when no generation preference is already confirmed. Each choice must include a concise example.</rule>
     <rule>If the user or developer chooses `Yes`, generate every listed non-duplicate candidate, validate each SVG XML file, update its queue status, and index completed durable output in the overview. If they choose `No`, leave the evidence-backed candidate list prepared in the queue without generating diagrams. If they choose `Choose diagrams`, generate only the entered non-duplicate IDs or subjects and leave the remainder listed in the queue.</rule>
     <rule>Whenever the candidate list is shown, tell the user or developer that any listed diagram can be generated later with `/devspec.diagram &lt;DIA-ID-or-subject&gt;`; include one concrete example such as `/devspec.diagram DIA-002`.</rule>
+    <rule>Record every path deliberately left out of inspection in `devspec/foundation/discovery-exclusions.md` with its reason, so a later run does not re-explore it or mistake the gap for missing evidence.</rule>
     <rule>Keep one extraction coverage item active and write discovered facts to their destination artifact, not queue state. Reuse recorded discovery methods and do not repeat a failed method unless its condition changed.</rule>
   </rules>
   <entry>Existing system with confirmed source scope and no active incompatible extraction run; reject new-repository foundation authoring or an assumed workspace target.</entry>
@@ -50,10 +54,9 @@ Invocation: `/devspec.extract`
     <artifact path="devspec/foundation/extraction-state.md" />
     <artifact path="devspec/foundation/exploration-state.md" />
     <artifact path="devspec/foundation/extraction-coverage.md" />
+    <artifact path="devspec/foundation/discovery-exclusions.md" />
     <artifact path="devspec/architecture/artifact-queue.md" />
     <artifact path="devspec/architecture/overview.md" />
+    <artifact path="devspec/foundation/decisions.md" />
   </outputs>
-  <actions>Confirm and record source scope before inspection, then complete the existing-system baseline, prepare and present the applicable diagram list, obtain the one diagram-generation confirmation, and record remaining gaps or blocked evidence.</actions>
-  <artifact>devspec/foundation/extraction-coverage.md</artifact>
-  <handoff>devspec.story-or-devspec.clarify</handoff>
 </workflow>
diff --git a/devspec/contracts/devspec.finalize.md b/devspec/contracts/devspec.finalize.md
index 216c36f..5425e09 100644
--- a/devspec/contracts/devspec.finalize.md
+++ b/devspec/contracts/devspec.finalize.md
@@ -9,16 +9,20 @@ Invocation: `/devspec.finalize [work-item-id]`
   <protocols>
     <protocol ref="ask" />
     <protocol ref="run" />
+    <protocol ref="state" />
     <protocol ref="current-work-item" />
+    <protocol ref="revision" />
     <protocol ref="work" />
+    <protocol ref="security" />
   </protocols>
+  <scope>Use to decide whether the current scope revision is buildable and to record its brief and validation plan. This command plans readiness only; devspec.tasks sequences the work and devspec.implement changes code.</scope>
   <input>An optional work-item ID or a groomed current draft.</input>
   <rules>
+    <rule>Read only the current-revision story and decisions, the finalization traces' direct sources in coding standards, codebase structure, rules, workflow rules, constitution, and the architecture queue or overview. Do not scan unrelated work items, unrelated code areas, or historical revisions beyond the superseded sections of this work item.</rule>
     <rule>Check only material readiness gaps: scope, criteria, behavior, data, integration, security, compliance, validation, and delivery constraints.</rule>
     <rule>Mark ready only when remaining gaps cannot materially change implementation or validation; otherwise create one material blocker question.</rule>
     <rule>Classify every accepted material decision as work-item-local or reusable. Promote a reusable business or validation decision to devspec/foundation/workflow-rules.md with a stable rule ID and source decision link; promote a reusable engineering constraint to devspec/foundation/rules.md. Record the resulting canonical rule link in decisions.md.</rule>
-    <rule>Record one compact foundation trace for the relevant coding conventions, owned areas and boundaries, canonical rules, applicable active `CP-###` principles, and OWASP categories. Record a separate architecture and diagram trace for relevant overview entries, completed diagrams, or queued candidates, including implementation and validation impact; no diagram is required. For every relevant OWASP category, state applicability, required control, and planned project-native evidence.</rule>
-    <rule>Do not mark ready while a relevant OWASP category, required control, or security-validation plan is unresolved.</rule>
+    <rule>Record one compact foundation trace for the relevant coding conventions, owned areas and boundaries, canonical rules, applicable active `CP-###` principles, and the OWASP categories the change touches. Record a separate architecture and diagram trace for relevant overview entries, completed diagrams, or queued candidates, including implementation and validation impact; no diagram is required.</rule>
     <rule>Write a concise implementation brief and validation plan, not implementation code.</rule>
   </rules>
   <entry>Active work item at finalization with a complete current-revision story; reject stale finalization, blocked work, or incomplete draft scope.</entry>
@@ -31,7 +35,4 @@ Invocation: `/devspec.finalize [work-item-id]`
     <transition outcome="material-blocker" stage="finalization" run="blocked" next="devspec.clarify" />
   </transitions>
   <closure>Stamp the readiness brief with the current scope revision. Preserve earlier revision sections as superseded history.</closure>
-  <actions>Scan only material readiness gaps; do not invent implementation detail.</actions>
-  <artifact>devspec/work-items/&lt;id&gt;/finalize.md</artifact>
-  <handoff>devspec.clarify-or-devspec.tasks</handoff>
 </workflow>
diff --git a/devspec/contracts/devspec.grooming.md b/devspec/contracts/devspec.grooming.md
index 8519162..1e8025e 100644
--- a/devspec/contracts/devspec.grooming.md
+++ b/devspec/contracts/devspec.grooming.md
@@ -9,9 +9,12 @@ Invocation: `/devspec.grooming [work-item-id]`
   <protocols>
     <protocol ref="ask" />
     <protocol ref="run" />
+    <protocol ref="state" />
     <protocol ref="current-work-item" />
+    <protocol ref="revision" />
     <protocol ref="work" />
   </protocols>
+  <scope>Use only when a draft story needs scoped analysis before it can be built. Skip it and run devspec.finalize directly when behavior, acceptance criteria, and the affected code area are already clear.</scope>
   <input>An optional work-item ID or clear current draft.</input>
   <rules>
     <rule>Read only the draft, relevant coding standards, codebase structure, foundation rules and workflow rules, selected code area, and direct dependencies; do not scan unrelated historical work-item decisions.</rule>
@@ -28,7 +31,4 @@ Invocation: `/devspec.grooming [work-item-id]`
     <transition outcome="material-blocker" stage="grooming" run="blocked" next="devspec.clarify" />
   </transitions>
   <closure>Do not advance while a material question remains unanswered; record the one blocker and resume reference.</closure>
-  <actions>Improve draft story and decisions in place; suggest only material questions.</actions>
-  <artifact>devspec/work-items/&lt;id&gt;/story.md</artifact>
-  <handoff>devspec.clarify-or-devspec.finalize</handoff>
 </workflow>
diff --git a/devspec/contracts/devspec.implement.md b/devspec/contracts/devspec.implement.md
index e3f7aec..8231548 100644
--- a/devspec/contracts/devspec.implement.md
+++ b/devspec/contracts/devspec.implement.md
@@ -9,19 +9,22 @@ Invocation: `/devspec.implement [work-item-id]`
   <protocols>
     <protocol ref="ask" />
     <protocol ref="run" />
+    <protocol ref="state" />
     <protocol ref="current-work-item" />
+    <protocol ref="revision" />
     <protocol ref="work" />
     <protocol ref="repo-access" />
+    <protocol ref="security" />
   </protocols>
+  <scope>Use to execute the ordered pending tasks of the current scope revision. This command does not re-plan, widen scope, or review its own output.</scope>
   <input>An optional work-item ID with ready finalization and pending task records.</input>
   <rules>
+    <rule>Read only the tasks being implemented, the finalization traces they cite, and the code area and direct dependencies each task names. Do not scan unrelated work items, unrelated code areas, or historical decision records.</rule>
     <rule>Confirm every task is in finalized scope, unblocked, and ordered before editing code.</rule>
     <rule>Checkpoint before edits and focused validation; stop for a material ambiguity instead of expanding scope.</rule>
     <rule>Before editing, apply the relevant finalization foundation trace: coding standards and their follow examples, owned code areas and boundaries, canonical rules, and applicable OWASP controls.</rule>
     <rule>Record changed areas, applied decision or canonical rule IDs, and validation evidence after each meaningful task.</rule>
     <rule>Express a business or validation decision through named code and tests. Add a developer comment only when its rationale is not evident from the code or test; reference the canonical rule ID, never an old work-item decision as the sole authority.</rule>
-    <rule>Record project-native security evidence for every applicable OWASP control. A suspected false positive or not-applicable finding requires the agent to ask one material confirmation question of the implementing developer, then record the explicit confirmation, rationale, enforceable supporting evidence, and material-change revalidation trigger; it remains proposed until review.</rule>
-    <rule>Do not classify a known unresolved vulnerability as not applicable merely because access is limited, authenticated, or internal-only.</rule>
   </rules>
   <entry>Active work item at implementation with current-revision ready finalization and ordered pending tasks; reject stale plans, blocked tasks, or changed scope.</entry>
   <outputs>
@@ -33,7 +36,4 @@ Invocation: `/devspec.implement [work-item-id]`
     <transition outcome="material-blocker" stage="implementation" run="blocked" next="devspec.clarify" />
   </transitions>
   <closure>Record the changed-work baseline and mark a task complete only after its recorded validation passes; preserve superseded revisions.</closure>
-  <actions>Stay within finalized scope; checkpoint before edits and validation.</actions>
-  <artifact>devspec/work-items/&lt;id&gt;/implement.md</artifact>
-  <handoff>review</handoff>
 </workflow>
diff --git a/devspec/contracts/devspec.projectcontext.md b/devspec/contracts/devspec.projectcontext.md
index e0d272e..14555db 100644
--- a/devspec/contracts/devspec.projectcontext.md
+++ b/devspec/contracts/devspec.projectcontext.md
@@ -9,25 +9,24 @@ Invocation: `/devspec.projectcontext`
   <protocols>
     <protocol ref="ask" />
     <protocol ref="run" />
+    <protocol ref="state" />
     <protocol ref="work" />
   </protocols>
   <scope>Use for new-repository foundation authoring or an explicitly requested targeted update. Use devspec.extract, not this command, to establish an existing-system baseline.</scope>
   <input>Product context, a confirmed source, or an explicit durable-principle promotion or retirement.</input>
   <rules>
     <rule>Capture purpose, users, outcomes, boundaries, and delivery context only. When the developer explicitly promotes or retires a rare cross-work-item principle, update `devspec/constitution.md` with its stable `CP-###` ID, evidence, state, and append-only history; do not infer a promotion.</rule>
-    <rule>Mark each material statement confirmed, observed, inferred, or blocked.</rule>
   </rules>
   <entry>New foundation chain with project context absent, or an explicit targeted update; reject an existing-system baseline request.</entry>
   <outputs>
     <artifact path="devspec/foundation/project-context.md" />
     <artifact path="devspec/constitution.md" />
+    <artifact path="devspec/foundation/decisions.md" />
   </outputs>
   <transitions>
     <transition outcome="foundation-updated" stage="foundation" run="active" next="devspec.techstack" />
     <transition outcome="targeted-update-complete" stage="foundation" run="active" next="return-to-caller" />
+    <transition outcome="evidence-blocked" stage="foundation" run="blocked" next="devspec.clarify" />
   </transitions>
   <closure>Record the foundation state and one registered next command; blocked evidence routes to devspec.clarify.</closure>
-  <actions>Update product context with clearly labeled confirmed, observed, inferred, or blocked statements.</actions>
-  <artifact>devspec/foundation/project-context.md</artifact>
-  <handoff>techstack</handoff>
 </workflow>
diff --git a/devspec/contracts/devspec.quickfix.md b/devspec/contracts/devspec.quickfix.md
index 7b9b526..e406818 100644
--- a/devspec/contracts/devspec.quickfix.md
+++ b/devspec/contracts/devspec.quickfix.md
@@ -9,8 +9,11 @@ Invocation: `/devspec.quickfix Fix Orders empty-state text`
   <protocols>
     <protocol ref="ask" />
     <protocol ref="run" />
+    <protocol ref="state" />
     <protocol ref="work" />
+    <protocol ref="repo-access" />
   </protocols>
+  <scope>Use only for one localized, low-risk change that needs no work item. Route public contracts, schema or migration work, security work, breaking changes, and unresolved risk to devspec.story instead.</scope>
   <input>One localized bug fix or small enhancement.</input>
   <rules>
     <rule>Select one primary scope: UI, internal API, function/job, library, configuration, tests, or a user-defined bounded scope.</rule>
@@ -25,10 +28,7 @@ Invocation: `/devspec.quickfix Fix Orders empty-state text`
   <transitions>
     <transition outcome="complete" stage="complete" run="complete" next="none" />
     <transition outcome="material-blocker" stage="triage" run="blocked" next="devspec.clarify" />
-    <transition outcome="routed" stage="routed" run="complete" next="devspec.story" />
+    <transition outcome="routed" stage="routed" run="active" next="devspec.story" />
   </transitions>
   <closure>Record the selected route, validation evidence, and terminal next action. Direct implementation is allowed only for the declared low-risk scope.</closure>
-  <actions>Select one primary scope, route risky work, then implement and validate directly.</actions>
-  <artifact>devspec/quickfixes/QF-###-slug.md</artifact>
-  <handoff>none-or-devspec.clarify-or-devspec.story</handoff>
 </workflow>
diff --git a/devspec/contracts/devspec.review.md b/devspec/contracts/devspec.review.md
index b09d726..92d8c64 100644
--- a/devspec/contracts/devspec.review.md
+++ b/devspec/contracts/devspec.review.md
@@ -9,19 +9,23 @@ Invocation: `/devspec.review [work-item-id]`
   <protocols>
     <protocol ref="ask" />
     <protocol ref="run" />
+    <protocol ref="state" />
     <protocol ref="current-work-item" />
+    <protocol ref="revision" />
     <protocol ref="work" />
+    <protocol ref="repo-access" />
+    <protocol ref="security" />
   </protocols>
+  <scope>Use to judge completed implementation against the current scope revision's approved scope and recorded evidence. This command records findings; devspec.implement applies them.</scope>
   <input>An optional work-item ID with finalization, tasks, implementation record, and changed work.</input>
   <rules>
+    <rule>Read only the changed-work baseline's changed paths and their direct callers, the current-revision finalization, tasks, and implementation records, and the canonical rules those records cite. Do not re-review unchanged code or unrelated work items.</rule>
     <rule>Compare changed work to approved scope, task source coverage, finalization foundation and architecture traces, validation evidence, and every applicable accepted material decision or canonical rule.</rule>
+    <rule>Verify the work against every protocol this work item loaded, and report a violation as a finding: evidence labels and changed-work baseline from state, revision currency from revision, scope and change discipline from work, access boundaries from repo-access, and the security gate from security.</rule>
     <rule>Check changed source against the shared work protocol for duplicated capabilities, unjustified dependencies, speculative abstractions, and unused configuration. Evaluate the choices against approved requirements, project conventions, and any recorded justification.</rule>
     <rule>Record actionable complexity findings in the existing Findings table with the location, supporting evidence, and a suitable simpler alternative or removal that preserves required behavior and safeguards.</rule>
     <rule>Require rework for demonstrated violations of approved scope or the shared implementation rule. Do not block acceptance solely because a different stylistic implementation is shorter.</rule>
     <rule>Record each decision or rule verification as implemented-as-decided, intentionally-superseded with a recorded replacement, or not-verified. Treat an unrecorded contradiction as rework-required.</rule>
-    <rule>Verify every applicable OWASP control and its project-native evidence. Confirm a proposed false positive or not-applicable finding only when the implementing developer confirmed it, enforceable evidence supports the rationale, and the reviewer records confirmation.</rule>
-    <rule>Do not record accepted while an applicable OWASP control lacks evidence or an exception lacks either confirmation. Treat unsupported internal-only, authenticated-only, or limited-access reasoning as an applicable risk with reduced exposure. A known unresolved vulnerability cannot be closed as an exception.</rule>
-    <rule>Record a material-change revalidation trigger for every confirmed exception covering related code, access control, deployment, integration, or exposure.</rule>
     <rule>Write findings only; do not silently edit implementation code.</rule>
     <rule>Record exactly one outcome: accepted, rework-required, or blocked; record exactly one next action.</rule>
   </rules>
@@ -36,7 +40,4 @@ Invocation: `/devspec.review [work-item-id]`
     <transition outcome="blocked" stage="review" run="blocked" next="devspec.clarify" />
   </transitions>
   <closure>Verify the recorded changed-work baseline. Accepted is terminal and clears current-work-item context; rework returns only affected tasks to implementation and blocked work preserves context.</closure>
-  <actions>Record the review outcome, one next action, and any actionable findings; do not silently change implementation code.</actions>
-  <artifact>devspec/work-items/&lt;id&gt;/review.md</artifact>
-  <handoff>devspec.implement-or-devspec.clarify-or-none</handoff>
 </workflow>
diff --git a/devspec/contracts/devspec.rules.md b/devspec/contracts/devspec.rules.md
index 9cd26d3..bc158ef 100644
--- a/devspec/contracts/devspec.rules.md
+++ b/devspec/contracts/devspec.rules.md
@@ -9,26 +9,25 @@ Invocation: `/devspec.rules`
   <protocols>
     <protocol ref="ask" />
     <protocol ref="run" />
+    <protocol ref="state" />
     <protocol ref="work" />
+    <protocol ref="security" />
   </protocols>
   <scope>Use for new-repository foundation authoring or an explicitly requested targeted update. Use devspec.extract, not this command, to establish an existing-system baseline.</scope>
   <input>Hard engineering, compliance, security, delivery, or accessibility constraints.</input>
   <rules>
     <rule>Keep non-negotiable rules separate from ordinary coding conventions and link applicable active `CP-###` constitution principles rather than duplicating them.</rule>
     <rule>State enforcement or validation for each rule when known.</rule>
-    <rule>Maintain one OWASP Top 10:2025 baseline in rules.md. For every category, record whether it is applicable, limited, out-of-scope, or unknown, plus the required project control and enforcement evidence.</rule>
-    <rule>Record limited or internal-only exposure only when enforceable access, deployment, or network evidence supports it; otherwise treat the category as applicable with reduced exposure.</rule>
   </rules>
   <entry>Completed coding standards in the new foundation chain, or an explicit targeted update; reject an existing-system baseline request.</entry>
   <outputs>
     <artifact path="devspec/foundation/rules.md" />
+    <artifact path="devspec/foundation/decisions.md" />
   </outputs>
   <transitions>
     <transition outcome="foundation-ready" stage="foundation" run="active" next="devspec.story" />
     <transition outcome="targeted-update-complete" stage="foundation" run="active" next="return-to-caller" />
+    <transition outcome="evidence-blocked" stage="foundation" run="blocked" next="devspec.clarify" />
   </transitions>
   <closure>Record enforceable rules and one registered next command; blocked evidence routes to devspec.clarify.</closure>
-  <actions>Keep hard constraints distinct from ordinary coding conventions and establish the project OWASP baseline.</actions>
-  <artifact>devspec/foundation/rules.md</artifact>
-  <handoff>story</handoff>
 </workflow>
diff --git a/devspec/contracts/devspec.story.md b/devspec/contracts/devspec.story.md
index 2b513b9..2e488f5 100644
--- a/devspec/contracts/devspec.story.md
+++ b/devspec/contracts/devspec.story.md
@@ -9,9 +9,12 @@ Invocation: `/devspec.story Add customer export`
   <protocols>
     <protocol ref="ask" />
     <protocol ref="run" />
+    <protocol ref="state" />
     <protocol ref="current-work-item" />
+    <protocol ref="revision" />
     <protocol ref="work" />
   </protocols>
+  <scope>Use to open one new work item from a manual request or a provider reference. Use devspec.changerequest for related scope on an already-finalized work item, and devspec.quickfix for a localized low-risk change that needs no work item.</scope>
   <input>One manual feature, bug, security issue, or task, or one provider work-item URL or identifier resolvable through an available authenticated MCP tool.</input>
   <rules>
     <rule>Handle exactly one work item; ask a material selection question when input contains independent items.</rule>
@@ -22,6 +25,7 @@ Invocation: `/devspec.story Add customer export`
     <rule>Allow manual intake as an explicit fallback only when provider resolution is unavailable or the developer intentionally selects it. Record the confirmation result and concise redacted source summary in story.md; keep credentials, tokens, and unnecessary personal data out of all artifacts.</rule>
     <rule>If a provider reference is ambiguous, inaccessible, unavailable through MCP, or insufficient to create one work item, ask one material clarification or offer the structured manual fallback. Do not silently fall back to browser search, create an unverified work item, or fabricate provider content.</rule>
     <rule>Read only the coding standards, codebase structure, foundation rules, and workflow rules relevant to the requested behavior and code area; do not scan unrelated historical work-item decisions.</rule>
+    <rule>Resolve a provider reference against `devspec/foundation/provider-integrations.md`: use its accepted inputs, validation guardrails, and confirmation requirements, and record the resolution outcome there when a new provider, input form, or guardrail is confirmed.</rule>
     <rule>Create folders as optional-provider-prefix plus numeric ID plus kebab-case title; do not rename legacy folders automatically.</rule>
     <rule>Before finalization, update the baseline; after finalization, route related scope to changerequest and unrelated scope to a linked item.</rule>
     <rule>Treat an explicit story request as new-work intent unless it is clearly related finalized scope, which routes to changerequest.</rule>
@@ -32,6 +36,7 @@ Invocation: `/devspec.story Add customer export`
   <outputs>
     <artifact path="devspec/work-items/&lt;id&gt;/story.md" />
     <artifact path="devspec/work-items/&lt;id&gt;/meta.md" />
+    <artifact path="devspec/foundation/provider-integrations.md" />
   </outputs>
   <transitions>
     <transition outcome="grooming-required" stage="grooming" run="active" next="devspec.grooming" />
@@ -39,7 +44,4 @@ Invocation: `/devspec.story Add customer export`
     <transition outcome="provider-reference-blocked" stage="intake" run="blocked" next="devspec.clarify" />
   </transitions>
   <closure>Record the selected route and normalized provider source when used. Use grooming when code-area evidence, compatibility, risk, or acceptance criteria needs scoped analysis.</closure>
-  <actions>Resolve one provider reference read-only when available, require structured confirmation before creating the work item, or record an explicitly chosen manual request; preserve finalized baselines.</actions>
-  <artifact>devspec/work-items/&lt;id&gt;/story.md</artifact>
-  <handoff>devspec.grooming-or-devspec.finalize</handoff>
 </workflow>
diff --git a/devspec/contracts/devspec.tasks.md b/devspec/contracts/devspec.tasks.md
index f1d19e5..c34b7be 100644
--- a/devspec/contracts/devspec.tasks.md
+++ b/devspec/contracts/devspec.tasks.md
@@ -9,12 +9,16 @@ Invocation: `/devspec.tasks [work-item-id]`
   <protocols>
     <protocol ref="ask" />
     <protocol ref="run" />
+    <protocol ref="state" />
     <protocol ref="current-work-item" />
+    <protocol ref="revision" />
     <protocol ref="work" />
     <protocol ref="repo-access" />
   </protocols>
+  <scope>Use to turn a ready finalization into an ordered, independently verifiable plan. This command plans only; devspec.implement makes the changes.</scope>
   <input>An optional work-item ID with a ready current finalization brief.</input>
   <rules>
+    <rule>Read only the current finalization brief, the story's current-revision criteria, and the foundation or architecture entries that brief already cites. Do not re-derive the traces from source or re-read unrelated foundation artifacts.</rule>
     <rule>Each task names scope, dependency, source justification, applicable decision or canonical rule IDs, validation, and done condition. Cite the finalization foundation and architecture traces for coding standards, codebase boundaries, diagrams, and OWASP controls instead of duplicating them per task.</rule>
     <rule>Order dependencies before dependents and split only work too broad to validate safely.</rule>
   </rules>
@@ -28,7 +32,4 @@ Invocation: `/devspec.tasks [work-item-id]`
     <transition outcome="material-blocker" stage="tasks" run="blocked" next="devspec.clarify" />
   </transitions>
   <closure>Plan only the active revision. Each task has source justification, validation, done condition, and a controlled initial status.</closure>
-  <actions>Trace tasks to readiness items and validation evidence; sequence dependencies first.</actions>
-  <artifact>devspec/work-items/&lt;id&gt;/tasks.md</artifact>
-  <handoff>implement</handoff>
 </workflow>
diff --git a/devspec/contracts/devspec.techstack.md b/devspec/contracts/devspec.techstack.md
index 29babc0..74725b9 100644
--- a/devspec/contracts/devspec.techstack.md
+++ b/devspec/contracts/devspec.techstack.md
@@ -9,6 +9,7 @@ Invocation: `/devspec.techstack`
   <protocols>
     <protocol ref="ask" />
     <protocol ref="run" />
+    <protocol ref="state" />
     <protocol ref="work" />
   </protocols>
   <scope>Use for new-repository foundation authoring or an explicitly requested targeted update. Use devspec.extract, not this command, to establish an existing-system baseline.</scope>
@@ -20,13 +21,12 @@ Invocation: `/devspec.techstack`
   <entry>Completed project context in the new foundation chain, or an explicit targeted update; reject an existing-system baseline request.</entry>
   <outputs>
     <artifact path="devspec/foundation/tech-stack.md" />
+    <artifact path="devspec/foundation/decisions.md" />
   </outputs>
   <transitions>
     <transition outcome="foundation-updated" stage="foundation" run="active" next="devspec.codebase-structure" />
     <transition outcome="targeted-update-complete" stage="foundation" run="active" next="return-to-caller" />
+    <transition outcome="evidence-blocked" stage="foundation" run="blocked" next="devspec.clarify" />
   </transitions>
   <closure>Record inspected evidence and one registered next command; blocked evidence routes to devspec.clarify.</closure>
-  <actions>Inspect manifests and configuration before asking for missing material facts.</actions>
-  <artifact>devspec/foundation/tech-stack.md</artifact>
-  <handoff>codebase-structure</handoff>
 </workflow>
diff --git a/devspec/foundation/_template/codebase-structure.md b/devspec/foundation/_template/codebase-structure.md
index ccdb4b1..38f9ba5 100644
--- a/devspec/foundation/_template/codebase-structure.md
+++ b/devspec/foundation/_template/codebase-structure.md
@@ -1,7 +1,7 @@
 # Codebase Structure
 
-| Area | Ownership | Boundary | Evidence |
-|---|---|---|---|
+| Area | Ownership | Boundary | Integration points | Validation location | Evidence |
+|---|---|---|---|---|---|
 
 ## Repositories
 
diff --git a/devspec/foundation/_template/project-context.md b/devspec/foundation/_template/project-context.md
index dfa89a1..7fbae89 100644
--- a/devspec/foundation/_template/project-context.md
+++ b/devspec/foundation/_template/project-context.md
@@ -1,7 +1,11 @@
 # Project Context
 
-- Purpose:
-- Users:
-- Outcomes:
-- Scope boundaries:
-- Delivery context:
+Label every statement `confirmed`, `observed`, `inferred`, or `blocked`.
+
+| Area | Statement | Evidence label | Evidence |
+|---|---|---|---|
+| Purpose |  |  |  |
+| Users |  |  |  |
+| Outcomes |  |  |  |
+| Scope boundaries |  |  |  |
+| Delivery context |  |  |  |
diff --git a/devspec/foundation/_template/rules.md b/devspec/foundation/_template/rules.md
index ca53ddf..b062016 100644
--- a/devspec/foundation/_template/rules.md
+++ b/devspec/foundation/_template/rules.md
@@ -2,8 +2,8 @@
 
 ## Project Rules
 
-| Rule ID | Rule | Why | Enforcement | Source decision |
-|---|---|---|---|---|
+| Rule ID | Rule | Why | Enforcement | Constitution principles | Source decision |
+|---|---|---|---|---|---|
 
 ## OWASP Top 10:2025 Baseline
 
diff --git a/devspec/foundation/_template/tech-stack.md b/devspec/foundation/_template/tech-stack.md
index cdc4140..8bcd60b 100644
--- a/devspec/foundation/_template/tech-stack.md
+++ b/devspec/foundation/_template/tech-stack.md
@@ -1,4 +1,4 @@
 # Technology Stack
 
-| Area | Confirmed stack | Evidence | Constraint |
-|---|---|---|---|
+| Area | Confirmed stack | Supported versions | Evidence | Constraint |
+|---|---|---|---|---|
diff --git a/devspec/glossary.md b/devspec/glossary.md
index 7956616..0989ba5 100644
--- a/devspec/glossary.md
+++ b/devspec/glossary.md
@@ -1,13 +1,11 @@
 # Glossary
 
-- Work-item stages: intake, grooming, finalization, tasks, implementation, review, complete.
-- Quickfix stages: triage, implementation, validation, complete, routed.
-- Run states: active (eligible to continue), paused (user-paused), blocked (one active material decision), stopped (requires new direction), complete (terminal with `next: none`).
-- Task statuses: pending, in-progress, blocked, complete, superseded.
-- Scope revision: a monotonic work-item number. Finalization, tasks, implementation, and review operate only on the current revision; older records are retained as superseded history.
+Run states, work-item and quickfix stages, task statuses, evidence labels, the changed-work baseline, and resume semantics are defined once in `devspec/protocols/state.xml`. `devspec/lifecycle.md` owns the route graph. This file covers the remaining terms.
+
+- Scope revision: a monotonic work-item number. Finalization, tasks, implementation, and review operate only on the current revision; older records are retained as superseded history. `devspec/protocols/revision.xml` owns its rules.
 - Current work-item context: a private, per-worktree Git-metadata selection used to resolve an omitted work-item ID. It is never a Git-tracked artifact and never replaces `meta.md` as canonical state.
-- Evidence: confirmed, observed, inferred, blocked.
-- OWASP exception: a reviewer-confirmed false-positive or not-applicable finding supported by enforceable evidence; it is distinct from an unresolved vulnerability.
+- Material question: a question whose answer can change implementation, validation, or scope. Only material questions enter the ask queue.
+- OWASP exception: a reviewer-confirmed false-positive or not-applicable finding supported by enforceable evidence; it is distinct from an unresolved vulnerability. `devspec/protocols/security.xml` owns its confirmation rules.
 
 ## Repository access requirements
 
@@ -20,4 +18,4 @@
 | `release-coordination` | Coordinate release information only; do not inspect, edit, or validate repository contents. |
 | `unavailable` | The repository cannot currently be accessed; record the impact as a blocker. |
 
-Use these values in `foundation/codebase-structure.md`. Select the least privilege that satisfies the current command; the repository location alone never grants access.
\ No newline at end of file
+Record these values in `foundation/codebase-structure.md`. Select the least privilege that satisfies the current command; the repository location alone never grants access. `devspec/protocols/repo-access.xml` owns how they are collected and enforced.
diff --git a/devspec/install-manifest.txt b/devspec/install-manifest.txt
index 211b2cf..4161965 100644
--- a/devspec/install-manifest.txt
+++ b/devspec/install-manifest.txt
@@ -13,5 +13,3 @@ work-items/_template/*.md
 quickfixes/README.md
 quickfixes/_template.md
 architecture/_template/*
-architecture/overview.md
-architecture/artifact-queue.md
diff --git a/devspec/lifecycle.md b/devspec/lifecycle.md
index 5abdac1..b9abb2a 100644
--- a/devspec/lifecycle.md
+++ b/devspec/lifecycle.md
@@ -1,35 +1,32 @@
 # Devspec Lifecycle
 
-Canonical contracts in `devspec/contracts/` own command behavior. This document defines the shared state vocabulary and the legal route graph those contracts use.
+Canonical contracts in `devspec/contracts/` own command behavior. This document owns the state-record locations and the legal route graph those contracts use. The shared state vocabulary — run states, stages, task statuses, evidence labels, the changed-work baseline, and resume semantics — lives in `devspec/protocols/state.xml`.
 
 ## State records
 
 - A foundation command records its command, stage, run state, last action, resume reference, next action, and update date in `devspec/foundation/decisions.md`.
-- A work item records the same state in `meta.md`. Its `scope_revision` starts at `1` and increases only when `devspec.changerequest` accepts a related requirement.
-- The selected current work item is private convenience state, not workflow evidence. Store it only at the per-worktree path returned by `git rev-parse --git-path devspec/current-work-item.json`; it identifies the work item, branch, selection source, and timestamp. Never commit a current-story file.
+- A work item records the same state in `meta.md`, together with its scope revision.
 - A quickfix records its state in front matter. A diagram records queue status and returns to its invoking workflow without changing that workflow's state.
-- `active` means the registered next command may run. `blocked` means exactly one active material decision is recorded and the next command is `devspec.clarify`. `paused` is an explicit user pause. `stopped` requires a new user direction before resuming. `complete` is terminal and must use `next: none`.
+- The selected current work item is private convenience state, not workflow evidence. Store it only at the per-worktree path returned by `git rev-parse --git-path devspec/current-work-item.json`. Never commit a current-story file. `devspec/protocols/current-work-item.xml` owns its selection, validation, and recovery rules.
 
-## Work-item states and revisions
+## Work-item stages
 
 | Stage | Required next command or terminal outcome |
 |---|---|
-| `intake` | `devspec.story` |
+| `intake` | `devspec.story` or `devspec.clarify` |
 | `grooming` | `devspec.grooming` or `devspec.clarify` |
 | `finalization` | `devspec.finalize` or `devspec.clarify` |
-| `tasks` | `devspec.tasks` |
+| `tasks` | `devspec.tasks` or `devspec.clarify` |
 | `implementation` | `devspec.implement` or `devspec.clarify` |
 | `review` | `devspec.review` or `devspec.clarify` |
 | `complete` | terminal (`next: none`) |
 
-Task status is one of `pending`, `in-progress`, `blocked`, `complete`, or `superseded`. A task becomes `complete` only after its recorded validation passes. Finalization, task, implementation, and review records carry the active scope revision. A change request increments that revision, preserves earlier revision sections as `superseded`, and requires fresh finalization before planning or implementation continues.
-
-Before an ID-free work-item command, resolve current context in this order: a validated supplied ID, a valid branch-matched local selection, then exactly one eligible non-terminal work item on the current branch. Clear a selection that has a changed branch, a missing work-item folder or `meta.md`, terminal work, or a stage/next-action mismatch. If several items remain, ask the user to choose. A clear continuation request dispatches only the selected `next` action; blocked work goes through `devspec.clarify`, and terminal work does not resume.
+Every non-terminal stage may route to `devspec.clarify`, and only to `devspec.clarify`, when it records a material blocker. `devspec/protocols/revision.xml` owns which revision each stage may read and write.
 
 ## Route graph
 
-- Existing repository: `devspec.extract → devspec.story`; an evidence gap that can materially affect later work is `blocked → devspec.clarify`.
+- Existing repository: `devspec.extract → devspec.story`.
 - New repository: `devspec.projectcontext → devspec.techstack → devspec.codebase-structure → devspec.coding-standards → devspec.rules → devspec.story`. A targeted foundation update returns to its caller after completing its declared artifact.
 - Work item: `devspec.story → devspec.grooming|devspec.finalize → devspec.tasks → devspec.implement → devspec.review`. Review results are `accepted → complete`, `rework-required → devspec.implement`, or `blocked → devspec.clarify`.
 - Work-item IDs are optional selectors for switching or resolving ambiguity. After a story is selected, normal commands and `continue` use its per-worktree context and never skip the recorded `next` command.
-- `devspec.clarify` resolves one decision and resumes its saved originating command. `devspec.changerequest` is allowed only after finalization and always returns to `devspec.finalize` with a new revision. `devspec.quickfix` is `complete`, `blocked`, or `routed -> devspec.story`. `devspec.diagram` returns to its caller.
+- `devspec.clarify` resolves one decision and resumes its saved originating command. `devspec.changerequest` is allowed only after finalization and always returns to `devspec.finalize` with a new revision. `devspec.quickfix` is `complete`, `blocked`, or `routed → devspec.story`. `devspec.diagram` returns to its caller.
diff --git a/devspec/protocols/repo-access.xml b/devspec/protocols/repo-access.xml
index ba2ee12..fd02ce1 100644
--- a/devspec/protocols/repo-access.xml
+++ b/devspec/protocols/repo-access.xml
@@ -1,6 +1,6 @@
 <protocol id="repo-access">
   <when>Load before accessing a repository outside the scaffolding root, whenever source scope is not already confirmed, and whenever a task depends on more than one repository.</when>
   <collect>When a repository path is not already evidenced, first ask for one repository name or local path in a free-form text input. Show at least two examples such as `D:\Code\orders-api` and `D:\Code\orders-web`; allow the developer to type another path. Confirm the path before asking about access, and repeat for each additional repository.</collect>
-  <validate>After each path is confirmed, ask one interactive question: “What access requirement applies to &lt;repository&gt;?” Always offer these five exclusive choices plus Custom Answer: Reference-only (example: inspect source, configuration, and tests as evidence; do not edit or run validations), Edit (example: update approved repository files; do not run validations), Edit-and-test (Recommended; example: make approved changes and run focused validations, including tests), Validation-only (example: run approved validations without editing), and Unavailable (example: record a blocker because the repository cannot be accessed). Include Custom Answer (example: a different boundary such as edit only one approved folder). Recommend Edit-and-test with the justification that it permits normal delivery work and focused evidence; it grants capability, not authorization to change source outside the active command scope. Record each repository's role, local path, workspace availability, named access requirement, and evidence. Treat the current workspace as a proposed target until an explicit user confirmation or current canonical evidence names that repository and boundary.</validate>
+  <validate>After each path is confirmed, ask one interactive question: “What access requirement applies to &lt;repository&gt;?” Offer the named access requirements from devspec/glossary.md as exclusive choices with an example each, plus Custom Answer: Reference-only (example: inspect source, configuration, and tests as evidence; do not edit or run validations), Edit (example: update approved repository files; do not run validations), Edit-and-test (Recommended; example: make approved changes and run focused validations, including tests), Validation-only (example: run approved validations without editing), Release-coordination (example: coordinate release information without inspecting or changing repository contents), and Unavailable (example: record a blocker because the repository cannot be accessed). Include Custom Answer (example: a different boundary such as edit only one approved folder). Mark exactly one choice recommended, and recommend the least-privilege option that satisfies the current command. Recommend Edit-and-test with the justification that it permits normal delivery work and focused evidence; it grants capability, not authorization to change source outside the active command scope. Record each repository's role, local path, workspace availability, named access requirement, and evidence. Treat the current workspace as a proposed target until an explicit user confirmation or current canonical evidence names that repository and boundary.</validate>
   <respect>Never edit a reference-only, validation-only, release-coordination, or unavailable repository. Never validate a reference-only, release-coordination, or unavailable repository. Validate a validation-only repository only when its recorded validation permission allows it.</respect>
 </protocol>
\ No newline at end of file
diff --git a/devspec/protocols/revision.xml b/devspec/protocols/revision.xml
new file mode 100644
index 0000000..2539980
--- /dev/null
+++ b/devspec/protocols/revision.xml
@@ -0,0 +1,6 @@
+<protocol id="revision">
+  <when>Load for every work-item command. The scope revision decides which records are current and which are history.</when>
+  <current>meta.md `scope_revision` starts at 1 and increases only when devspec.changerequest accepts a related requirement. Finalization, task, implementation, and review records each carry the revision they belong to. Read and write only the current revision. Each command stamps its own key in meta.md as it completes: devspec.finalize sets `finalized_revision`, devspec.tasks `planned_revision`, devspec.implement `implemented_revision`, and devspec.review `reviewed_revision`. A key behind `scope_revision` means that stage must run again.</current>
+  <supersede>An accepted change request increments the revision, marks the earlier finalization, task, implementation, and review sections superseded, and preserves their evidence unchanged. Fresh finalization is required before planning or implementation continues.</supersede>
+  <reject>Reject stale or superseded readiness, task, or implementation evidence instead of updating it in place, and record the mismatch as the reason.</reject>
+</protocol>
diff --git a/devspec/protocols/run.xml b/devspec/protocols/run.xml
index 631c540..13fd084 100644
--- a/devspec/protocols/run.xml
+++ b/devspec/protocols/run.xml
@@ -1,5 +1,5 @@
 <protocol id="run">
-  <preflight>Before every command, confirm single-repository or multi-repository scope from either explicit developer confirmation or current canonical evidence. Treat the current workspace as proposed, never proof. When repository evidence is absent, collect one repository name or local path at a time through a free-form text input with two path examples and a custom typed value; do not present access choices until that path is confirmed. After each path is confirmed, ask exactly one interactive named access-requirement question with two to five exclusive choices, an example for each, Custom Answer, and exactly one recommended least-privilege choice with justification. Record that repository's role and named access requirement; repeat path collection then access confirmation for each additional repository. A new repository may explicitly confirm that no source exists yet. Do not inspect or change source until this sequence is complete. Then validate required input, target artifact, stage, and access before output.</preflight>
+  <preflight>Before every command, confirm single-repository or multi-repository scope from either explicit developer confirmation or current canonical evidence. Treat the current workspace as proposed, never proof. When repository evidence is absent, complete the repo-access protocol before reading, editing, or validating source; a new repository may explicitly confirm that no source exists yet. Do not inspect or change source until that sequence is complete. Then validate required input, target artifact, stage, and access before output.</preflight>
   <checkpoint>Before material questions, edits, validation, retries, or handoff, save stage, run state, last action, resume reference, and exactly one next action in the command's state record.</checkpoint>
   <state-records>
     <work-item>devspec/work-items/&lt;id&gt;/meta.md</work-item>
diff --git a/devspec/protocols/security.xml b/devspec/protocols/security.xml
new file mode 100644
index 0000000..dec8d1a
--- /dev/null
+++ b/devspec/protocols/security.xml
@@ -0,0 +1,8 @@
+<protocol id="security">
+  <when>Load whenever a command establishes, applies, or verifies the project security baseline.</when>
+  <baseline>Maintain exactly one OWASP Top 10:2025 baseline, in devspec/foundation/rules.md. For every category record its applicability (applicable, limited, out-of-scope, or unknown), the required project control, and the enforcement or evidence that backs it. Record gaps and unknowns rather than omitting a category.</baseline>
+  <exposure>Record limited or internal-only exposure only when enforceable access, deployment, or network evidence supports it; otherwise treat the category as applicable with reduced exposure. A known unresolved vulnerability is never closed as not applicable because access is limited, authenticated, or internal-only.</exposure>
+  <evidence>Record project-native evidence for every applicable control, expressed through the project's own code, tests, configuration, or pipeline rather than a claim in an artifact.</evidence>
+  <exception>A suspected false positive or not-applicable finding requires one material confirmation question to the implementing developer, then a record of the explicit confirmation, its rationale, the enforceable supporting evidence, and a material-change revalidation trigger covering related code, access control, deployment, integration, and exposure. It remains proposed until a reviewer confirms it.</exception>
+  <gate>Do not mark a work item ready, and do not record an accepted review, while an applicable category, required control, security-validation plan, or exception confirmation is unresolved.</gate>
+</protocol>
diff --git a/devspec/protocols/state.xml b/devspec/protocols/state.xml
new file mode 100644
index 0000000..add8983
--- /dev/null
+++ b/devspec/protocols/state.xml
@@ -0,0 +1,10 @@
+<protocol id="state">
+  <when>Load with every command. This is the shared vocabulary that every state record, transition, and closing report uses. devspec/lifecycle.md holds the legal route graph and devspec/glossary.md the full term list.</when>
+  <repository-route>Read devspec/foundation/repository-state.md before the first foundation command. State `existing` starts at devspec.extract; state `new` starts at devspec.projectcontext. Do not infer the state from the presence of source.</repository-route>
+  <run-states>`active` means the registered next command may run. `paused` is an explicit user pause. `blocked` means exactly one active material decision is recorded and the next command is devspec.clarify. `stopped` requires a new user direction before resuming. `complete` is terminal and must record `next: none`.</run-states>
+  <stages>Work-item stages are intake, grooming, finalization, tasks, implementation, review, and complete. Quickfix stages are triage, implementation, validation, complete, and routed. Foundation and extraction work uses the foundation stage. A command that returns to its caller reports the caller's stage.</stages>
+  <task-statuses>A task is pending, in-progress, blocked, complete, or superseded. A task becomes complete only after its recorded validation passes.</task-statuses>
+  <evidence-labels>Label every durable fact confirmed, observed, inferred, or blocked. Never record an inferred fact as confirmed.</evidence-labels>
+  <changed-work-baseline>The changed-work baseline is what an implementation is measured from: the base revision, the comparison revision or an explicit working-tree marker, and the list of changed paths. devspec.implement records it; devspec.review verifies the recorded baseline before judging the work.</changed-work-baseline>
+  <resume>`return-to-caller` and `resume-origin` both mean: continue the command named in this record's saved resume reference, at its saved stage and next action. Never infer a caller. When no resume reference is saved, report the outcome and stop instead of guessing a next command.</resume>
+</protocol>
diff --git a/devspec/quickfixes/_template.md b/devspec/quickfixes/_template.md
index 7e7173d..f0fda6e 100644
--- a/devspec/quickfixes/_template.md
+++ b/devspec/quickfixes/_template.md
@@ -3,6 +3,7 @@ id: QF-###-slug
 type: bug
 stage: triage
 run: active
+last: none
 scope: []
 resume: none
 next: select scope
@@ -18,6 +19,7 @@ updated: <yyyy-mm-dd>
 - Outcome:
 
 - Route: complete | devspec.clarify | devspec.story
+
 ## Decisions
 
 | ID | Material question | Evidence | Impact | Choices | Recommended | Recommendation justification | Applicability | Canonical rule link | Answer or skip reason | Status |
diff --git a/devspec/work-items/_template/finalize.md b/devspec/work-items/_template/finalize.md
index 46a01ba..87e23bc 100644
--- a/devspec/work-items/_template/finalize.md
+++ b/devspec/work-items/_template/finalize.md
@@ -7,7 +7,7 @@
 
 ## Foundation Traceability
 
-| Foundation artifact | Relevant convention, area, boundary, or rule | Applicability or boundary | Evidence |
+| Foundation artifact or `CP-###` principle | Relevant convention, area, boundary, or rule | Applicability or boundary | Evidence |
 |---|---|---|---|
 
 ## Architecture and Diagram Trace
diff --git a/devspec/work-items/_template/review.md b/devspec/work-items/_template/review.md
index 28adaaa..27408f7 100644
--- a/devspec/work-items/_template/review.md
+++ b/devspec/work-items/_template/review.md
@@ -15,6 +15,8 @@
 | Architecture or diagram reference | Expected implementation or validation impact | Evidence | Status | Finding or action |
 |---|---|---|---|---|
 
+Use `implemented-as-decided`, `intentionally-superseded` with a recorded replacement, or `not-verified`. Treat an unrecorded contradiction as rework-required.
+
 ## Security Verification
 
 | Finding ID | OWASP category | Disposition | Developer confirmation | Rationale and enforceable evidence | Reviewer confirmation | Revalidate when | Status or action |
@@ -24,5 +26,5 @@ Use `remediated`, `confirmed-not-applicable`, `confirmed-false-positive`, or `un
 
 ## Findings
 
-| Finding | Severity | Evidence | Required action |
-|---|---|---|---|
\ No newline at end of file
+| Finding | Location | Severity | Evidence | Required action |
+|---|---|---|---|---|
\ No newline at end of file
diff --git a/devspec/work-items/_template/tasks.md b/devspec/work-items/_template/tasks.md
index 1b608ee..5562e88 100644
--- a/devspec/work-items/_template/tasks.md
+++ b/devspec/work-items/_template/tasks.md
@@ -4,4 +4,4 @@
 - Status: active | superseded
 
 | ID | Task | Scope | Depends on | Source justification and foundation or architecture trace | Decision or rule IDs | Validation | Done condition | Status |
-|---|---|---|---|---|---|---|
\ No newline at end of file
+|---|---|---|---|---|---|---|---|---|
\ No newline at end of file
diff --git a/docs/how-to.md b/docs/how-to.md
index 2655834..beb4601 100644
--- a/docs/how-to.md
+++ b/docs/how-to.md
@@ -1,6 +1,6 @@
 # How to use Devspec Lite
 
-This guide uses real developer situations to show which agent command to run, when to run it, and what happens next. Run `devspec-lite init` and `devspec-lite doctor` first; then invoke the listed `devspec.*` command from your configured agent host.
+This guide uses real developer situations to show which agent command to run, when to run it, and what happens next. Install the framework by either setup route, then invoke the listed `devspec.*` command from your configured agent host. The CLI is one route, not a prerequisite.
 
 Git-tracked `devspec/` artifacts are the project record. Do not skip a command because the answer is present in chat: record the evidence or decision in the matching artifact.
 
@@ -8,7 +8,7 @@ Git-tracked `devspec/` artifacts are the project record. Do not skip a command b
 
 ## Choose the scaffold and confirm source scope
 
-The `devspec/` scaffold may live in the code repository or in a separate Git repository that records a multi-repository change. The directory open in the agent host is the scaffold location, not automatic permission to inspect source. Before every `devspec.*` command, confirm single-repository or multi-repository scope in two steps when current evidence is absent: first ask for one repository name or local path in a free-form text input with examples; after that path is confirmed, ask one interactive named access-requirement question with examples, Custom Answer, and one least-privilege recommendation. Repeat the two questions for each repository, recording its role and access requirement. A new repository may explicitly confirm that no source exists yet. Current canonical evidence may replace a repeated confirmation only when it records the same facts.
+The `devspec/` scaffold may live in the code repository or in a separate Git repository that records a multi-repository change. The directory open in the agent host is the scaffold location, not automatic permission to inspect source. Before every `devspec.*` command, confirm single-repository or multi-repository scope when current evidence is absent. The agent collects each repository path, then asks one access-requirement question per repository, as `devspec/protocols/repo-access.xml` defines. A new repository may explicitly confirm that no source exists yet. Current canonical evidence may replace a repeated confirmation only when it records the same facts.
 
 Use the [beginner command examples](command-examples.md) to choose a scaffold layout, confirm one or more repository boundaries, and copy a safe first prompt for every command.
 
@@ -21,7 +21,7 @@ For provider-backed story intake, pass one GitHub, Azure DevOps, Jira, GitLab, o
 | Existing codebase with no trusted Devspec baseline | `devspec.extract` | Start a story after the baseline is ready. |
 | Brand-new repository | `devspec.projectcontext` | Continue the new-foundation route. |
 | New feature, API contract, migration, security change, or multiple concerns | `devspec.story` | Groom when needed, then finalize, plan, implement, and review. |
-| One local, low-risk correction | `devspec.quickfix` | Complete directly or route to a story. |
+| One local, low-risk correction | `devspec.quickfix` | Complete directly, clarify a blocker, or route to a story. |
 | A recorded material decision blocks current work | `devspec.clarify` | Resume the exact saved command. |
 | A related requirement arrives after finalization | `devspec.changerequest` | Re-finalize the new scope revision. |
 | One evidence-backed architecture or workflow visual is needed | `devspec.diagram` | Return to the caller's workflow. |
diff --git a/docs/workflows.md b/docs/workflows.md
index a13e83f..c8f2ade 100644
--- a/docs/workflows.md
+++ b/docs/workflows.md
@@ -9,7 +9,7 @@ Use the smallest route that preserves a durable, reviewable record. Git-tracked
 - New repository: start with `devspec.projectcontext`.
 - Before every command, confirm the single-repository or multi-repository scope, including the scaffold location and each source repository's role, path, and permissions, unless current canonical evidence records it. The current workspace alone is not proof of scope.
 - Existing repository: run `devspec.extract` once with confirmed scope. It completes the evidence-backed technical, workflow, and rule baseline, prepares the applicable diagram list, and asks whether to generate all, selected, or no diagrams. A prepared item can later be generated with `/devspec.diagram DIA-###`; do not rerun individual foundation commands afterward.
-- New repository: use `projectcontext`, `techstack`, `codebase-structure`, `coding-standards`, `rules`, and `diagram` as input-driven authoring commands.
+- New repository: run `projectcontext`, `techstack`, `codebase-structure`, `coding-standards`, and `rules` in order as input-driven authoring commands. `diagram` is not part of the chain; call it separately and it returns to its caller.
 
 ## 2. Deliver a change
 
diff --git a/src/devspec_lite/definitions.py b/src/devspec_lite/definitions.py
index dce0ce7..02cf877 100644
--- a/src/devspec_lite/definitions.py
+++ b/src/devspec_lite/definitions.py
@@ -52,3 +52,32 @@ def install_files() -> tuple[Path, ...]:
 
 COMMANDS = load_commands()
 PROTOCOLS = tuple(path.stem for path in sorted((canonical_root() / "protocols").glob("*.xml")))
+
+# Reading order for human-facing command lists. COMMANDS is sorted by filename, which would
+# open every listing with changerequest and hide the route the commands actually follow.
+LIFECYCLE_ORDER = (
+    "extract",
+    "projectcontext",
+    "techstack",
+    "codebase-structure",
+    "coding-standards",
+    "rules",
+    "story",
+    "grooming",
+    "clarify",
+    "changerequest",
+    "finalize",
+    "tasks",
+    "implement",
+    "review",
+    "diagram",
+    "quickfix",
+)
+
+
+def lifecycle_commands() -> tuple[Command, ...]:
+    remaining = {command.name: command for command in COMMANDS}
+    ordered = [remaining.pop(name) for name in LIFECYCLE_ORDER if name in remaining]
+    # A new contract that is not yet placed in the route still has to reach every listing.
+    ordered.extend(remaining[name] for name in sorted(remaining))
+    return tuple(ordered)
diff --git a/src/devspec_lite/framework.py b/src/devspec_lite/framework.py
index cd50d94..178a7e0 100644
--- a/src/devspec_lite/framework.py
+++ b/src/devspec_lite/framework.py
@@ -10,7 +10,7 @@
 from xml.etree import ElementTree
 
 from . import __version__
-from .definitions import COMMANDS, PROTOCOLS, canonical_root, install_files
+from .definitions import COMMANDS, PROTOCOLS, canonical_root, install_files, lifecycle_commands
 
 PROFILES = ("all", "copilot", "codex", "claude", "cursor", "gemini", "antigravity")
 ADAPTERS = PROFILES[1:]
@@ -69,7 +69,7 @@ def doctor(root: Path, profile: str) -> list[str]:
     if (root / "devspec/work-items/current.md").exists():
         issues.append("tracked current-story artifact is not allowed: devspec/work-items/current.md")
     valid_stages = {"foundation", "intake", "grooming", "finalization", "tasks", "implementation", "review", "complete", "triage", "routed", "caller", "origin"}
-    valid_runs = {"active", "blocked", "complete"}
+    valid_runs = {"active", "paused", "blocked", "stopped", "complete"}
     valid_next = {f"devspec.{command.name}" for command in COMMANDS} | {"none", "return-to-caller", "resume-origin"}
     lifecycle_templates = {
         "devspec/work-items/_template/meta.md": ("scope_revision:", "finalized_revision:", "planned_revision:", "implemented_revision:", "reviewed_revision:"),
@@ -77,7 +77,11 @@ def doctor(root: Path, profile: str) -> list[str]:
     }
     current_context_commands = {"story", "grooming", "finalize", "tasks", "implement", "review", "clarify", "changerequest"}
     protocol_text_requirements = {
-        "run": {"preflight": ("Before every command", "single-repository or multi-repository scope", "current workspace as proposed", "free-form text input", "After each path is confirmed", "interactive named access-requirement question", "Do not inspect or change source")},
+        "run": {"preflight": ("Before every command", "single-repository or multi-repository scope", "current workspace as proposed", "repo-access protocol", "Do not inspect or change source")},
+        "repo-access": {
+            "collect": ("free-form text input", "Confirm the path before asking about access"),
+            "validate": ("After each path is confirmed", "Custom Answer", "least-privilege"),
+        },
         "current-work-item": {
             "location": ("git rev-parse --git-path devspec/current-work-item.json", "Never create or commit"),
             "record": ("work-item ID", "current branch", "selection source", "timestamp", "never committed or pushed"),
@@ -101,7 +105,8 @@ def doctor(root: Path, profile: str) -> list[str]:
                     "work": ("scope", "evidence", "change", "artifacts"),
                     "repo-access": ("when", "validate", "respect"),
                     "current-work-item": ("when", "location", "record", "selection", "validation", "recovery", "continuation", "update", "clear"),
-                }[name]
+                    "state": ("when", "run-states", "stages", "task-statuses", "evidence-labels", "resume"),
+                }.get(name, ())
                 present = {child.tag for child in ElementTree.fromstring(path.read_text(encoding="utf-8"))}
                 missing = sorted(set(required) - present)
                 if missing:
@@ -111,7 +116,7 @@ def doctor(root: Path, profile: str) -> list[str]:
                     value = protocol.findtext(tag, default="")
                     for phrase in phrases:
                         if phrase not in value:
-                            issues.append(f"missing current-story resolver requirement: {path}: {tag}: {phrase}")
+                            issues.append(f"missing protocol requirement: {path}: {tag}: {phrase}")
     for command in COMMANDS:
         path = root / f"devspec/contracts/devspec.{command.name}.md"
         if path.is_file():
@@ -120,7 +125,7 @@ def doctor(root: Path, profile: str) -> list[str]:
                 workflow = ElementTree.fromstring(xml_block(text))
                 if workflow.tag != "workflow" or workflow.attrib.get("command") != f"devspec.{command.name}":
                     issues.append(f"invalid contract identity: {path}")
-                required = {"purpose", "protocols", "input", "rules", "entry", "outputs", "transitions", "closure", "actions", "artifact", "handoff"}
+                required = {"purpose", "protocols", "scope", "input", "rules", "entry", "outputs", "transitions", "closure"}
                 present = {child.tag for child in workflow}
                 missing = sorted(required - present)
                 if missing:
@@ -153,6 +158,8 @@ def doctor(root: Path, profile: str) -> list[str]:
                         issues.append(f"blocked transition must clarify: {path}")
                     if next_command == "none" and run != "complete":
                         issues.append(f"terminal transition must be complete: {path}")
+                    if run == "complete" and next_command != "none":
+                        issues.append(f"complete transition must be terminal: {path}")
     registry = root / "devspec/command-registry.md"
     registry_text = registry.read_text(encoding="utf-8") if registry.is_file() else ""
     for command in COMMANDS:
@@ -200,7 +207,8 @@ def doctor(root: Path, profile: str) -> list[str]:
 # Upgrade lifecycle. These definitions intentionally follow the compact installer
 # above so existing callers retain their public import locations.
 def _sha256(path: Path) -> str:
-    return hashlib.sha256(path.read_bytes()).hexdigest()
+    # Hash normalized text so a CRLF checkout does not read as local drift.
+    return hashlib.sha256(path.read_text(encoding="utf-8").encode("utf-8")).hexdigest()
 
 
 def _state_from_target(root: Path) -> str:
@@ -212,11 +220,16 @@ def _state_from_target(root: Path) -> str:
     return "existing"
 
 
+# Live project state seeded once from a template, then never overwritten by sync.
+SEEDED_FROM_TEMPLATE = (
+    (Path("devspec/architecture/overview.md"), "architecture/_template/overview.md"),
+    (Path("devspec/architecture/artifact-queue.md"), "architecture/_template/artifact-queue.md"),
+)
+
+
 def _ownership(relative: Path) -> str:
     if relative == Path("constitution.md"):
         return PROJECT_OWNED
-    if relative in {Path("architecture/overview.md"), Path("architecture/artifact-queue.md")}:
-        return PROJECT_OWNED
     if relative == Path("foundation/repository-state.md"):
         return PROJECT_OWNED
     return FRAMEWORK_OWNED
@@ -230,13 +243,17 @@ def managed_payload(profile: str, repo_state: str) -> tuple[ManagedFile, ...]:
         files.append(ManagedFile(Path("devspec") / relative, source.read_text(encoding="utf-8"), _ownership(relative)))
     route = "devspec.extract" if repo_state == "existing" else "devspec.projectcontext"
     files.append(ManagedFile(Path("devspec/foundation/repository-state.md"), f"# Repository State\n\n- State: {repo_state}\n- Start with: `{route}`\n", PROJECT_OWNED))
+    # Seed the live architecture records from their templates. Installing the canonical copies
+    # would hand every target repository devspec-lite's own diagram rows.
+    for target, template in SEEDED_FROM_TEMPLATE:
+        files.append(ManagedFile(target, (source_root / template).read_text(encoding="utf-8"), PROJECT_OWNED))
     adapters = ADAPTERS if profile == "all" else (profile,)
     for adapter in adapters:
         if adapter == "codex":
-            command_lines = "\n".join(f"- `devspec.{c.name}`: read `devspec/contracts/devspec.{c.name}.md`." for c in COMMANDS)
+            command_lines = "\n".join(f"- `devspec.{c.name}`: read `devspec/contracts/devspec.{c.name}.md`." for c in lifecycle_commands())
             files.append(ManagedFile(Path("AGENTS.md"), "# Devspec Lite\n\nUse Git-tracked `devspec/` artifacts as canonical state. For a clear work-item continuation, resolve the per-worktree current context and run only its saved next action; ask before switching among multiple stories.\n\n" + command_lines + "\n", FRAMEWORK_OWNED))
         elif adapter == "cursor":
-            commands = ", ".join(f"`devspec.{c.name}`" for c in COMMANDS)
+            commands = ", ".join(f"`devspec.{c.name}`" for c in lifecycle_commands())
             files.append(ManagedFile(Path(".cursor/rules/devspec-workflow.mdc"), f"---\ndescription: Devspec Lite workflow\nalwaysApply: false\n---\nFor {commands}, read the matching `devspec/contracts/` file and listed protocols. For a clear continuation, resolve per-worktree current context and run only the saved next action; ask before switching stories.\n", FRAMEWORK_OWNED))
         elif adapter == "copilot":
             for command in COMMANDS:
diff --git a/tests/test_contract_consistency.py b/tests/test_contract_consistency.py
new file mode 100644
index 0000000..c132e5d
--- /dev/null
+++ b/tests/test_contract_consistency.py
@@ -0,0 +1,194 @@
+"""Cross-check the contracts against every surface that restates them.
+
+The other suites install into a temporary directory and validate that, so drift between
+this repository's own checked-in wrappers and its contracts stayed invisible. These tests
+validate the repository itself.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import unittest
+from pathlib import Path
+from xml.etree import ElementTree
+
+REPO = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(REPO / "src"))
+
+from devspec_lite.definitions import COMMANDS, LIFECYCLE_ORDER, PROTOCOLS, lifecycle_commands  # noqa: E402
+from devspec_lite.framework import FRAMEWORK_OWNED, doctor, managed_payload  # noqa: E402
+
+CONTRACTS = REPO / "devspec/contracts"
+# Live project state and this project's own work products are deliberately not installed.
+UNINSTALLED = ("foundation/repository-state.md", "architecture/overview.md", "architecture/artifact-queue.md")
+
+
+def contract_text(name: str) -> str:
+    return (CONTRACTS / f"devspec.{name}.md").read_text(encoding="utf-8")
+
+
+def workflow(name: str) -> ElementTree.Element:
+    text = contract_text(name)
+    return ElementTree.fromstring(text[text.index("<workflow"):text.index("</workflow>") + len("</workflow>")])
+
+
+def table_rows(text: str, header_starts: str) -> list[list[str]]:
+    rows = []
+    seen_header = False
+    for line in text.splitlines():
+        line = line.strip()
+        if not line.startswith("|"):
+            seen_header = False
+            continue
+        cells = [c.strip() for c in line.strip("|").split("|")]
+        if cells[0].startswith(header_starts):
+            seen_header = True
+            continue
+        if seen_header and not set("".join(cells)) <= set("-: "):
+            rows.append(cells)
+    return rows
+
+
+class RepositoryIsCurrentTests(unittest.TestCase):
+    def test_checked_in_wrappers_match_the_contracts(self) -> None:
+        drift = []
+        for item in managed_payload("all", "existing"):
+            if item.ownership != FRAMEWORK_OWNED:
+                continue
+            target = REPO / item.path
+            if target.is_file() and target.read_text(encoding="utf-8") != item.content:
+                drift.append(item.path.as_posix())
+        self.assertEqual([], drift, "run the installer to regenerate these from devspec/contracts")
+
+    def test_doctor_passes_against_this_repository(self) -> None:
+        self.assertEqual([], doctor(REPO, "all"))
+
+    def test_install_manifest_covers_every_canonical_file(self) -> None:
+        from devspec_lite.definitions import canonical_root, install_files
+
+        root = canonical_root()
+        installed = {p.relative_to(root).as_posix() for p in install_files()}
+        for path in sorted(root.rglob("*")):
+            if not path.is_file():
+                continue
+            relative = path.relative_to(root).as_posix()
+            if relative in UNINSTALLED or relative.startswith("quickfixes/QF-") or relative.startswith("work-items/") and "_template" not in relative:
+                continue
+            self.assertIn(relative, installed, f"{relative} is not covered by install-manifest.txt")
+
+
+class ContractSchemaTests(unittest.TestCase):
+    def test_every_command_has_a_lifecycle_position(self) -> None:
+        self.assertEqual(sorted(LIFECYCLE_ORDER), sorted(c.name for c in COMMANDS))
+
+    def test_heading_summary_matches_purpose(self) -> None:
+        for command in COMMANDS:
+            with self.subTest(command.name):
+                summary = contract_text(command.name).split("\n")[2].strip()
+                self.assertEqual(command.purpose, summary)
+
+    def test_derivable_elements_are_not_restated(self) -> None:
+        # <artifact> restated <outputs>, <handoff> restated <transitions>, <actions> restated <rules>.
+        for command in COMMANDS:
+            with self.subTest(command.name):
+                present = {child.tag for child in workflow(command.name)}
+                self.assertEqual(set(), present & {"artifact", "handoff", "actions"})
+
+    def test_every_contract_scopes_itself(self) -> None:
+        for command in COMMANDS:
+            with self.subTest(command.name):
+                scope = workflow(command.name).findtext("scope", default="").strip()
+                self.assertTrue(scope, "contract must state when to use it and what to use instead")
+
+    def test_protocol_refs_resolve(self) -> None:
+        for command in COMMANDS:
+            for ref in workflow(command.name).find("protocols"):
+                with self.subTest(command=command.name, ref=ref.attrib.get("ref")):
+                    self.assertIn(ref.attrib.get("ref"), PROTOCOLS)
+
+    def test_every_protocol_is_loaded_by_a_contract(self) -> None:
+        used = {ref.attrib.get("ref") for c in COMMANDS for ref in workflow(c.name).find("protocols")}
+        self.assertEqual(set(PROTOCOLS), used, "an unreferenced protocol never reaches the agent")
+
+    def test_shared_vocabulary_reaches_every_command(self) -> None:
+        for command in COMMANDS:
+            with self.subTest(command.name):
+                refs = {ref.attrib.get("ref") for ref in workflow(command.name).find("protocols")}
+                self.assertIn("state", refs)
+                self.assertIn("run", refs)
+
+
+class RouteGraphTests(unittest.TestCase):
+    def transitions(self, name: str) -> list[dict]:
+        return [t.attrib for t in workflow(name).find("transitions")]
+
+    def test_blocked_and_terminal_transitions_agree_with_lifecycle(self) -> None:
+        for command in COMMANDS:
+            for attrib in self.transitions(command.name):
+                with self.subTest(command=command.name, outcome=attrib.get("outcome")):
+                    if attrib["run"] == "blocked":
+                        self.assertEqual("devspec.clarify", attrib["next"])
+                    if attrib["run"] == "complete":
+                        self.assertEqual("none", attrib["next"])
+                    if attrib["next"] == "none":
+                        self.assertEqual("complete", attrib["run"])
+
+    def test_work_item_stages_match_the_lifecycle_table(self) -> None:
+        text = (REPO / "devspec/lifecycle.md").read_text(encoding="utf-8")
+        documented = {row[0].strip("`"): row[1] for row in table_rows(text, "Stage")}
+        stages = {"intake", "grooming", "finalization", "tasks", "implementation", "review", "complete"}
+        self.assertEqual(stages, set(documented))
+        for command in COMMANDS:
+            for attrib in self.transitions(command.name):
+                stage, nxt = attrib["stage"], attrib["next"]
+                if stage in documented and nxt.startswith("devspec."):
+                    with self.subTest(command=command.name, stage=stage):
+                        self.assertIn(nxt, documented[stage], f"lifecycle.md does not allow {stage} -> {nxt}")
+
+    def test_registry_restates_the_contracts_exactly(self) -> None:
+        text = (REPO / "devspec/command-registry.md").read_text(encoding="utf-8")
+        rows = table_rows(text, "Command")
+        self.assertEqual([f"`devspec.{c.name}`" for c in lifecycle_commands()], [r[0] for r in rows])
+        for command, row in zip(lifecycle_commands(), rows):
+            with self.subTest(command.name):
+                self.assertEqual(command.purpose, row[1])
+                expected = []
+                for attrib in self.transitions(command.name):
+                    if attrib["next"] not in expected:
+                        expected.append(attrib["next"])
+                self.assertEqual(", ".join(f"`{v}`" for v in expected), row[2])
+
+
+class ArtifactShapeTests(unittest.TestCase):
+    def test_markdown_tables_are_well_formed(self) -> None:
+        separator = re.compile(r"\|(\s*:?-+:?\s*\|)+$")
+        broken = []
+        for path in sorted((REPO / "devspec").rglob("*.md")):
+            lines = path.read_text(encoding="utf-8").split("\n")
+            for index, line in enumerate(lines[:-1]):
+                nxt = lines[index + 1].strip()
+                if line.strip().startswith("|") and separator.fullmatch(nxt):
+                    header = line.strip().strip("|").split("|")
+                    if len(header) != len(nxt.strip("|").split("|")):
+                        broken.append(f"{path.relative_to(REPO).as_posix()}:{index + 1}")
+        self.assertEqual([], broken)
+
+    def test_contract_outputs_have_a_template(self) -> None:
+        template_map = (REPO / "devspec/foundation/template-map.md").read_text(encoding="utf-8")
+        work_item_templates = {p.name for p in (REPO / "devspec/work-items/_template").glob("*.md")}
+        for command in COMMANDS:
+            for artifact in workflow(command.name).find("outputs"):
+                path = artifact.attrib["path"]
+                with self.subTest(command=command.name, path=path):
+                    name = path.rsplit("/", 1)[-1]
+                    if path.startswith("devspec/work-items/"):
+                        self.assertIn(name, work_item_templates)
+                    elif path.startswith("devspec/foundation/"):
+                        self.assertIn(f"`{name}`", template_map)
+                    else:
+                        self.assertTrue((REPO / path).is_file() or "###" in name, f"no home for {path}")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_framework.py b/tests/test_framework.py
index b2e425c..4ad09fb 100644
--- a/tests/test_framework.py
+++ b/tests/test_framework.py
@@ -112,6 +112,7 @@ def test_security_foundation_and_confirmed_exception_path_are_installed(self) ->
             finalize_contract = (target / "devspec/contracts/devspec.finalize.md").read_text(encoding="utf-8")
             implement_contract = (target / "devspec/contracts/devspec.implement.md").read_text(encoding="utf-8")
             review_contract = (target / "devspec/contracts/devspec.review.md").read_text(encoding="utf-8")
+            security_protocol = (target / "devspec/protocols/security.xml").read_text(encoding="utf-8")
             self.assertEqual(1, rules.count("OWASP Top 10:2025 Baseline"))
             self.assertIn("A01:2025 Broken Access Control", rules)
             self.assertIn("A10:2025 Mishandling of Exceptional Conditions", rules)
@@ -121,18 +122,20 @@ def test_security_foundation_and_confirmed_exception_path_are_installed(self) ->
             self.assertIn("Developer confirmation", implementation_template)
             self.assertIn("Security Verification", review_template)
             self.assertIn("Reviewer confirmation", review_template)
-            self.assertIn("OWASP Top 10:2025", rules_contract)
+            # The security protocol owns the baseline, exception, and gate; the contracts load it.
+            self.assertIn("OWASP Top 10:2025", security_protocol)
+            self.assertIn("one material confirmation question", security_protocol)
+            self.assertIn("known unresolved vulnerability", security_protocol)
+            for contract in (rules_contract, extract_contract, finalize_contract, implement_contract, review_contract):
+                self.assertIn('<protocol ref="security" />', contract)
             self.assertIn("do not infer an internal-only", extract_contract)
             self.assertIn("foundation trace", finalize_contract)
-            self.assertIn("ask one material confirmation question", implement_contract)
-            self.assertIn("reviewer records confirmation", review_contract)
-            self.assertIn("known unresolved vulnerability", review_contract)
     def test_contract_xml_and_quickfix_routing_are_present(self) -> None:
         with tempfile.TemporaryDirectory() as raw:
             target = Path(raw)
             main(["init", "--target", str(target), "--profile", "copilot", "--repo-state", "existing"])
             quickfix = (target / "devspec/contracts/devspec.quickfix.md").read_text(encoding="utf-8")
-            self.assertIn("route risky work", quickfix)
+            self.assertIn("Route public API contracts", quickfix)
             self.assertIn("database schema or migration", quickfix)
             self.assertIn("<rules>", quickfix)
             self.assertIn('<protocol ref="ask" />', quickfix)

From d321852329bf1172728cf64ac3e38b02d7cf71f2 Mon Sep 17 00:00:00 2001
From: Vikram Reddy <gvreddy04@gmail.com>
Date: Sat, 5 Sep 2026 16:13:46 +0530
Subject: [PATCH 2/7] feat: Add documentation tests to ensure all commands are
 covered in guides and validate template fields in contracts

---
 devspec/README.md                  |  2 ++
 docs/quickstart.md                 |  2 ++
 tests/test_contract_consistency.py | 33 ++++++++++++++++++++++++++++++
 3 files changed, 37 insertions(+)

diff --git a/devspec/README.md b/devspec/README.md
index 17684a7..af929fd 100644
--- a/devspec/README.md
+++ b/devspec/README.md
@@ -7,4 +7,6 @@ After `story` selects a work item, use the normal work-item commands without rep
 
 Use `clarify` only for an active blocker and `quickfix` only for localized, low-risk changes. See `lifecycle.md` for all command transitions.
 
+Each contract in `contracts/` states its own intent, scope, rules, and transitions, and loads the shared behavior it needs from `protocols/`: `state` for the run-state and evidence vocabulary, `run` for preflight and checkpoints, `work` for scope and change discipline, `ask` for material questions, `current-work-item` for ID-free continuation, `revision` for scope revisions, `repo-access` for repository boundaries, and `security` for the OWASP baseline. A rule belongs in a protocol when more than one command needs it.
+
 `diagram` creates static SVG by default. Use `motion=explain` only for an evidence-backed sequence, flow, or state transition; animated output must retain complete static and reduced-motion meaning.
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 9f3dd0a..ff8a698 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -25,6 +25,8 @@ Use a narrower profile such as `copilot`, `codex`, `claude`, `cursor`, `gemini`,
 
 Work route: `devspec.story → devspec.grooming` when needed `→ devspec.finalize → devspec.tasks → devspec.implement → devspec.review`.
 
+When a command reports a blocker, run `devspec.clarify`: it resolves the one recorded decision and resumes the exact saved command. When a related requirement arrives after finalization, run `devspec.changerequest` to append it and re-finalize the new scope revision.
+
 Use `devspec.quickfix` only for one localized, low-risk change. It routes API contracts, migrations, authentication/security, and breaking changes to the full route.
 
 ## Workflow routes
diff --git a/tests/test_contract_consistency.py b/tests/test_contract_consistency.py
index c132e5d..d7ecd50 100644
--- a/tests/test_contract_consistency.py
+++ b/tests/test_contract_consistency.py
@@ -160,6 +160,18 @@ def test_registry_restates_the_contracts_exactly(self) -> None:
                 self.assertEqual(", ".join(f"`{v}`" for v in expected), row[2])
 
 
+class DocumentationTests(unittest.TestCase):
+    # A command a guide never names is a command a reader never finds.
+    COVERING_DOCS = ("how-to.md", "command-examples.md", "quickstart.md", "workflows.md", "upstream-command-parity.md")
+
+    def test_every_command_appears_in_the_command_guides(self) -> None:
+        for doc in self.COVERING_DOCS:
+            text = (REPO / "docs" / doc).read_text(encoding="utf-8")
+            for command in COMMANDS:
+                with self.subTest(doc=doc, command=command.name):
+                    self.assertIn(command.name, text)
+
+
 class ArtifactShapeTests(unittest.TestCase):
     def test_markdown_tables_are_well_formed(self) -> None:
         separator = re.compile(r"\|(\s*:?-+:?\s*\|)+$")
@@ -174,6 +186,27 @@ def test_markdown_tables_are_well_formed(self) -> None:
                         broken.append(f"{path.relative_to(REPO).as_posix()}:{index + 1}")
         self.assertEqual([], broken)
 
+    # Each entry is a field some contract or protocol names, and the template that must offer it.
+    REQUIRED_FIELDS = {
+        "devspec/foundation/_template/rules.md": ("Constitution principles",),
+        "devspec/foundation/_template/tech-stack.md": ("Supported versions",),
+        "devspec/foundation/_template/project-context.md": ("Evidence label",),
+        "devspec/foundation/_template/codebase-structure.md": ("Integration points", "Validation location"),
+        "devspec/architecture/_template/artifact-queue.md": ("Duplicate check",),
+        "devspec/work-items/_template/finalize.md": ("CP-###", "Scope revision:"),
+        "devspec/work-items/_template/tasks.md": ("Done condition", "Scope revision:"),
+        "devspec/work-items/_template/implement.md": ("Changed-work baseline:",),
+        "devspec/work-items/_template/review.md": ("Location", "implemented-as-decided", "Changed-work baseline:"),
+        "devspec/quickfixes/_template.md": ("last:", "resume:", "next:"),
+    }
+
+    def test_templates_carry_the_fields_contracts_require(self) -> None:
+        for template, fields in self.REQUIRED_FIELDS.items():
+            text = (REPO / template).read_text(encoding="utf-8")
+            for field in fields:
+                with self.subTest(template=template, field=field):
+                    self.assertIn(field, text)
+
     def test_contract_outputs_have_a_template(self) -> None:
         template_map = (REPO / "devspec/foundation/template-map.md").read_text(encoding="utf-8")
         work_item_templates = {p.name for p in (REPO / "devspec/work-items/_template").glob("*.md")}

From b94be268f2bf445e8be0fde03b42d637cd8cb014 Mon Sep 17 00:00:00 2001
From: Vikram Reddy <gvreddy04@gmail.com>
Date: Sat, 5 Sep 2026 16:44:54 +0530
Subject: [PATCH 3/7] Enhance protocols and documentation for clarity and
 consistency

- Updated the `run` protocol to clarify the checkpoint process and state record handling.
- Revised the `security` protocol to improve language around exposure and exception handling.
- Enhanced the `state` protocol to specify the reporting of next actions and clarify stage definitions.
- Improved the `work` protocol to ensure evidence labels are applied consistently.
- Modified quickfix and work-item templates to clarify decision recording and routing.
- Updated command examples and how-to documentation for improved clarity on repository access and command usage.
- Refined the framework to ensure proper validation and error handling in the doctor function.
- Added tests to ensure contract consistency and validate protocol references.
---
 README.md                                     |  2 +-
 .../architecture/_template/artifact-queue.md  |  2 +
 .../architecture/_template/diagram-sample.md  |  6 +--
 devspec/architecture/_template/diagram.md     | 34 +++---------
 devspec/command-registry.md                   |  2 +-
 devspec/contracts/devspec.changerequest.md    |  3 +-
 devspec/contracts/devspec.clarify.md          |  1 +
 .../contracts/devspec.codebase-structure.md   |  4 +-
 devspec/contracts/devspec.coding-standards.md |  5 +-
 devspec/contracts/devspec.diagram.md          |  8 +--
 devspec/contracts/devspec.extract.md          | 25 +++++----
 devspec/contracts/devspec.finalize.md         |  1 +
 devspec/contracts/devspec.grooming.md         |  2 +
 devspec/contracts/devspec.implement.md        |  4 +-
 devspec/contracts/devspec.projectcontext.md   |  2 +-
 devspec/contracts/devspec.quickfix.md         |  4 +-
 devspec/contracts/devspec.review.md           |  1 +
 devspec/contracts/devspec.rules.md            |  2 +-
 devspec/contracts/devspec.story.md            |  5 +-
 devspec/contracts/devspec.tasks.md            |  4 +-
 devspec/contracts/devspec.techstack.md        |  3 +-
 .../_template/codebase-structure.md           |  2 +-
 devspec/foundation/_template/decisions.md     |  4 +-
 .../_template/extraction-coverage.md          |  2 +-
 .../_template/provider-integrations.md        |  2 +-
 devspec/foundation/_template/roles.md         |  2 +-
 devspec/foundation/_template/rules.md         |  2 +-
 .../_template/technical-baseline.md           |  2 +-
 .../foundation/_template/workflow-rules.md    |  2 +-
 devspec/foundation/_template/workflows.md     |  2 +-
 devspec/foundation/template-map.md            |  2 +-
 devspec/glossary.md                           | 10 ++--
 devspec/lifecycle.md                          |  6 +--
 devspec/protocols/ask.xml                     |  3 +-
 devspec/protocols/current-work-item.xml       |  4 +-
 devspec/protocols/repo-access.xml             | 12 +++--
 devspec/protocols/run.xml                     |  5 +-
 devspec/protocols/security.xml                |  6 +--
 devspec/protocols/state.xml                   |  4 +-
 devspec/protocols/work.xml                    |  3 +-
 devspec/quickfixes/_template.md               |  8 +--
 devspec/work-items/_template/decisions.md     |  4 +-
 devspec/work-items/_template/implement.md     |  2 +-
 devspec/work-items/_template/review.md        |  2 +-
 devspec/work-items/_template/story.md         |  2 +-
 devspec/work-items/_template/tasks.md         |  2 +-
 docs/command-examples.md                      |  2 +-
 docs/how-to.md                                |  5 +-
 docs/manual-copy.md                           | 11 +++-
 docs/upstream-command-parity.md               |  7 +--
 docs/workflows.md                             | 16 +++---
 src/devspec_lite/framework.py                 | 43 +++++++--------
 tests/test_contract_consistency.py            | 52 +++++++++++++++----
 tests/test_framework.py                       | 19 ++++---
 54 files changed, 213 insertions(+), 157 deletions(-)

diff --git a/README.md b/README.md
index 8b216d1..dce5475 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@ Devspec Lite is a compact, resumable spec-driven workflow for AI coding agents.
 | macOS/Linux package-manager installation | [Homebrew](docs/setup-homebrew.md) |
 | Already installed the CLI; need init, upgrade, or profile changes | [CLI lifecycle](docs/setup-lifecycle.md) |
 
-Manual copying and CLI installation produce the same canonical `devspec/` content and agent wrappers. In either route, set the target repository's `repository-state.md` to `new` or `existing`. Choose one setup route; the CLI is optional.
+Manual copying and CLI installation produce the same canonical `devspec/` content and agent wrappers, once the manual route resets the project records listed in its guide. In either route, set the target repository's `repository-state.md` to `new` or `existing`. Choose one setup route; the CLI is optional.
 
 ## CLI quick start
 
diff --git a/devspec/architecture/_template/artifact-queue.md b/devspec/architecture/_template/artifact-queue.md
index f51949f..b35a7ac 100644
--- a/devspec/architecture/_template/artifact-queue.md
+++ b/devspec/architecture/_template/artifact-queue.md
@@ -1,4 +1,6 @@
 # Architecture Artifact Queue
 
+One row per diagram candidate. `Duplicate check` records what was compared and the result, so a later run does not regenerate an existing diagram. `Next` is the one action left for that row, or `none` when it is complete.
+
 | ID | Scope | Type | Subject | Output | Evidence | Duplicate check | Status | Next |
 |---|---|---|---|---|---|---|---|---|
diff --git a/devspec/architecture/_template/diagram-sample.md b/devspec/architecture/_template/diagram-sample.md
index 690a0a7..06b4651 100644
--- a/devspec/architecture/_template/diagram-sample.md
+++ b/devspec/architecture/_template/diagram-sample.md
@@ -19,9 +19,9 @@ A process flow makes the one routing decision, its two outcomes, and the durable
 
 ## Queue row
 
-| ID | Scope | Type | Subject | Output | Evidence | Status | Next |
-|---|---|---|---|---|---|---|---|
-| DIA-001 | workflow | process flow | customer-request-routing | images/dia-001-customer-request-routing.svg | contracts above | complete | index in overview |
+| ID | Scope | Type | Subject | Output | Evidence | Duplicate check | Status | Next |
+|---|---|---|---|---|---|---|---|---|
+| DIA-001 | workflow | Process flow | customer-request-routing | `devspec/architecture/diagrams/dia-001-customer-request-routing.svg` | contracts above | no existing diagram covers this subject | complete | index in overview |
 
 ## Completion
 
diff --git a/devspec/architecture/_template/diagram.md b/devspec/architecture/_template/diagram.md
index 19d30d8..79e0892 100644
--- a/devspec/architecture/_template/diagram.md
+++ b/devspec/architecture/_template/diagram.md
@@ -2,32 +2,14 @@
 
 Use this optional Markdown artifact for one durable Mermaid architecture, module, feature, workflow, process-flow, user journey, sequence, state, or domain diagram when the selected output set includes `mermaid`. SVG is the default diagram output and lives under `devspec/architecture/diagrams/`; HTML is optional and lives under `devspec/architecture/diagrams/`. Keep diagram status in `devspec/architecture/artifact-queue.md`; keep generated content references, supporting evidence, assumptions, and maintenance notes here when this Markdown artifact is created.
 
-## Resume State
-
-| Field | Value |
-| --- | --- |
-| Current stage | diagram |
-| Current command | `/devspec.diagram` |
-| Current agent | devspec.diagram |
-| Run status | See `devspec/protocols/state.xml` |
-| Current item | |
-| Last completed step | |
-| Next required action | |
-| Pending user question | |
-| Question options and examples | |
-| Custom Answer entry or response | |
-| Recommended option and justification | |
-| Continuation condition | |
-| Resume command | `/devspec.diagram` |
-| Resume notes | |
-| Updated | |
+This record holds evidence and maintenance notes only. Queue status lives in `devspec/architecture/artifact-queue.md`, and any material question belongs in the caller's decision record; a diagram never holds workflow run state.
 
 ## Diagram Metadata
 
 | Field | Value |
 | --- | --- |
 | ID | |
-| Display title | `DIA-NNN - <Title Case Diagram Name>` |
+| Display title | `DIA-### - <Title Case Diagram Name>` |
 | Scope | architecture, module, feature, workflow, user-journey |
 | Diagram type | flowchart, sequenceDiagram, journey, stateDiagram, classDiagram, erDiagram, gantt, quadrantChart, mindmap, timeline |
 | Audience | developers, architects, security reviewers, operators, stakeholders, or user-provided audience |
@@ -35,9 +17,9 @@ Use this optional Markdown artifact for one durable Mermaid architecture, module
 | Architecture style | monolith, microservices, event-driven, serverless, agentic workflow, multi-repo, cloud-native, or user-provided style |
 | Output format | mermaid, svg+mermaid, html+mermaid, or svg+html+mermaid |
 | Mermaid declaration | flowchart TD, flowchart LR, flowchart BT, sequenceDiagram, journey, stateDiagram-v2, classDiagram, erDiagram, gantt, quadrantChart, mindmap, timeline |
-| SVG target | `devspec/architecture/diagrams/dia-NNN-<diagram-name>.svg` when output format includes svg |
-| HTML target | `devspec/architecture/diagrams/dia-NNN-<diagram-name>.html` when output format includes html |
-| Subject | `dia-NNN-<diagram-name>` |
+| SVG target | `devspec/architecture/diagrams/dia-###-<diagram-name>.svg` when output format includes svg |
+| HTML target | `devspec/architecture/diagrams/dia-###-<diagram-name>.html` when output format includes html |
+| Subject | `dia-###-<diagram-name>` |
 | Confidence | observed, high-confidence, low-confidence |
 | Tags | |
 | Queue row | `devspec/architecture/artifact-queue.md` |
@@ -47,7 +29,7 @@ When a request uses the structured architecture-diagram prompt format and the se
 ## Mermaid Diagram
 
 - Include this section only when the selected output set includes `mermaid`. SVG-only and HTML-only output should not create this Markdown artifact.
-- Keep durable `DIA-*` IDs and `dia-NNN-*` subjects in metadata and filenames only; Mermaid content uses simple internal naming.
+- Keep durable `DIA-*` IDs and `dia-###-*` subjects in metadata and filenames only; Mermaid content uses simple internal naming.
 - Use short alphanumeric node IDs, double-quoted node labels of 1-4 words, and 2-3 word edge labels. Do not use `\n` or `<br>` inside node labels or edge labels.
 - Keep architectural flowcharts focused on one primary domain at macro level, structurally unidirectional, and adjacent by layer. Do not include overloaded graphs, cross-layer arrows, decision diamonds, UI micro-interactions, or return/error paths unless the diagram is explicitly an algorithm or activity flowchart.
 - Use `sequenceDiagram` for exact step-by-step request and response behavior. Sequence diagrams should show happy-path messages between distinct participants, collapse pass-through API client helpers, and use method names for message labels.
@@ -101,8 +83,8 @@ flowchart TD
 ## Companion Outputs
 
 - Use this section when `Output format` includes `svg` or `html`.
-- Store the durable SVG at `devspec/architecture/diagrams/dia-NNN-<diagram-name>.svg`.
-- Store optional standalone HTML at `devspec/architecture/diagrams/dia-NNN-<diagram-name>.html`.
+- Store the durable SVG at `devspec/architecture/diagrams/dia-###-<diagram-name>.svg`.
+- Store optional standalone HTML at `devspec/architecture/diagrams/dia-###-<diagram-name>.html`.
 - Select SVG templates from `devspec/architecture/_template/`: `architecture-diagram.svg`, `process-flow-diagram.svg`, `sequence-diagram.svg`, `state-lifecycle-diagram.svg`, `domain-model-diagram.svg`, `journey-map-diagram.svg`, `timeline-plan-diagram.svg`, `quadrant-analysis-diagram.svg`, or `mindmap-diagram.svg`. Every template must preserve the shared dark architecture-style visual contract unless a documented constraint requires a smaller custom SVG.
 - Generated SVG must be standalone XML with inline styles and no external assets, `<script>`, `<iframe>`, `<foreignObject>`, remote fonts, remote images, secrets, credentials, internal-only URLs, or unresolved placeholders.
 - Generated HTML must be standalone static HTML with inline styles and no external assets, `<script>`, `<iframe>`, remote fonts, remote images, secrets, credentials, internal-only URLs, or unresolved placeholders.
diff --git a/devspec/command-registry.md b/devspec/command-registry.md
index 7dcfa5e..e3df55d 100644
--- a/devspec/command-registry.md
+++ b/devspec/command-registry.md
@@ -21,4 +21,4 @@ Purpose and next route are the contract's own `<purpose>` and `<transition next>
 | `devspec.diagram` | Create one evidence-backed diagram with duplicate checks and durable queue state. | `return-to-caller`, `devspec.clarify` |
 | `devspec.quickfix` | Implement and validate one localized, low-risk enhancement or bug fix. | `none`, `devspec.clarify`, `devspec.story` |
 
-Work-item IDs are optional for `grooming`, `finalize`, `tasks`, `implement`, `review`, `clarify`, and `changerequest`. Without an ID, resolve the private per-worktree current context and run only the work item's recorded `next` action. Use an explicit ID to switch stories; when several eligible stories exist, ask the user to choose.
+Work-item IDs are optional for `grooming`, `finalize`, `tasks`, `implement`, `review`, `clarify`, and `changerequest`. Without an ID, resolve the private per-worktree current context and run only the work item's recorded `next` action. Use an explicit ID to switch stories; when several eligible work items exist, ask the developer to choose.
diff --git a/devspec/contracts/devspec.changerequest.md b/devspec/contracts/devspec.changerequest.md
index 986b1d1..4eaf549 100644
--- a/devspec/contracts/devspec.changerequest.md
+++ b/devspec/contracts/devspec.changerequest.md
@@ -24,10 +24,11 @@ Invocation: `/devspec.changerequest [work-item-id] Add JSON export`
   <outputs>
     <artifact path="devspec/work-items/&lt;id&gt;/story.md" />
     <artifact path="devspec/work-items/&lt;id&gt;/meta.md" />
+    <artifact path="devspec/work-items/&lt;id&gt;/decisions.md" />
   </outputs>
   <transitions>
     <transition outcome="related-change-accepted" stage="finalization" run="active" next="devspec.finalize" />
     <transition outcome="classification-blocked" stage="finalization" run="blocked" next="devspec.clarify" />
   </transitions>
-  <closure>Append the CR, increment scope_revision, mark downstream records superseded, and preserve their historical evidence.</closure>
+  <closure>Append the CR and record the classification that justified it.</closure>
 </workflow>
diff --git a/devspec/contracts/devspec.clarify.md b/devspec/contracts/devspec.clarify.md
index 7f82bc0..108489a 100644
--- a/devspec/contracts/devspec.clarify.md
+++ b/devspec/contracts/devspec.clarify.md
@@ -27,6 +27,7 @@ Invocation: `/devspec.clarify [work-item-id]`
     <artifact path="devspec/work-items/&lt;id&gt;/decisions.md" />
     <artifact path="devspec/work-items/&lt;id&gt;/clarify.md" />
     <artifact path="devspec/quickfixes/QF-###-slug.md" />
+    <artifact path="devspec/work-items/&lt;id&gt;/meta.md" />
   </outputs>
   <transitions>
     <transition outcome="decision-resolved" stage="origin" run="active" next="resume-origin" />
diff --git a/devspec/contracts/devspec.codebase-structure.md b/devspec/contracts/devspec.codebase-structure.md
index 4f3b0a6..8aeb301 100644
--- a/devspec/contracts/devspec.codebase-structure.md
+++ b/devspec/contracts/devspec.codebase-structure.md
@@ -19,7 +19,7 @@ Invocation: `/devspec.codebase-structure`
     <rule>Map owned source roots, boundaries, integration points, and validation locations.</rule>
     <rule>For each repository, maintain a readable `text` layout tree rooted at its recorded local path. Include solution or manifest files, owned roots, meaningful modules, configuration, and integration or migration locations; keep it representative rather than exhaustive and exclude dependencies, caches, generated output, and secrets.</rule>
     <rule>For an explicit targeted update, accept a developer-provided layout tree or structure change without rerunning extraction. Mark developer-defined additions or changes as such, retain observed evidence where it remains accurate, and reconcile the repository table, layout tree, and area map.</rule>
-    <rule>Use repo-access whenever scope or access evidence is missing and when work crosses repositories. Record one named least-privilege access requirement per repository; never infer access from its path.</rule>
+    <rule>Reconcile the repository table with the access requirements repo-access recorded; never infer access from a repository path.</rule>
   </rules>
   <entry>Completed technology stack in the new foundation chain, or an explicit targeted update; reject an existing-system baseline request.</entry>
   <outputs>
@@ -31,5 +31,5 @@ Invocation: `/devspec.codebase-structure`
     <transition outcome="targeted-update-complete" stage="foundation" run="active" next="return-to-caller" />
     <transition outcome="evidence-blocked" stage="foundation" run="blocked" next="devspec.clarify" />
   </transitions>
-  <closure>Record repository access boundaries, representative layout trees, and one registered next command; blocked evidence routes to devspec.clarify.</closure>
+  <closure>Record repository access boundaries, representative layout trees, and one registered next command.</closure>
 </workflow>
diff --git a/devspec/contracts/devspec.coding-standards.md b/devspec/contracts/devspec.coding-standards.md
index be1a613..10f08f9 100644
--- a/devspec/contracts/devspec.coding-standards.md
+++ b/devspec/contracts/devspec.coding-standards.md
@@ -11,13 +11,14 @@ Invocation: `/devspec.coding-standards`
     <protocol ref="run" />
     <protocol ref="state" />
     <protocol ref="work" />
+    <protocol ref="repo-access" />
   </protocols>
   <scope>Use for new-repository foundation authoring or an explicitly requested targeted update. Use devspec.extract, not this command, to establish an existing-system baseline.</scope>
   <input>Observed conventions, approved standards, or developer-defined custom standards with followable numbered examples or example updates.</input>
   <rules>
     <rule>Keep only conventions that change implementation or review behavior.</rule>
     <rule>For an observed convention, assign a stable `CS-###` ID, cite its local source evidence, and record concise fenced code or test snippets as linked `EX-###` entries under `## Standards Examples`. Record an anti-pattern when repository evidence supports one.</rule>
-    <rule>Accept a custom standard explicitly supplied or approved by a developer even when no local source example exists. Mark it developer-defined rather than observed, record its approval or request as evidence, assign or retain a stable `CS-###` ID, and include a concise illustrative `EX-###` entry for future implementations. For a developer-defined example, identify its source as the user or developer directive and date.</rule>
+    <rule>Accept a custom standard explicitly supplied or approved by a developer even when no local source example exists. Mark it developer-defined rather than observed, record its approval or request as evidence, assign or retain a stable `CS-###` ID, and include a concise illustrative `EX-###` entry for future implementations. For a developer-defined example, identify its source as the developer directive and date.</rule>
     <rule>For an explicit targeted update, accept added, replaced, or retired standards examples without rerunning extraction. Preserve existing `CS-###` and `EX-###` IDs, create new IDs without renumbering historical entries, and reconcile each standard's linked example IDs and origin.</rule>
   </rules>
   <entry>Completed codebase structure in the new foundation chain, or an explicit targeted update; reject an existing-system baseline request.</entry>
@@ -30,5 +31,5 @@ Invocation: `/devspec.coding-standards`
     <transition outcome="targeted-update-complete" stage="foundation" run="active" next="return-to-caller" />
     <transition outcome="evidence-blocked" stage="foundation" run="blocked" next="devspec.clarify" />
   </transitions>
-  <closure>Record each retained standard with its stable ID, origin, linked numbered examples, and an anti-pattern when applicable, then register one next command; blocked evidence routes to devspec.clarify.</closure>
+  <closure>Record each retained standard with its stable ID, origin, linked numbered examples, and an anti-pattern when applicable and register one next command.</closure>
 </workflow>
diff --git a/devspec/contracts/devspec.diagram.md b/devspec/contracts/devspec.diagram.md
index c8f3dd1..da26cd2 100644
--- a/devspec/contracts/devspec.diagram.md
+++ b/devspec/contracts/devspec.diagram.md
@@ -17,11 +17,11 @@ Invocation: `/devspec.diagram runtime architecture format=svg motion=none|explai
   <input>Diagram queue ID, subject, work item, explicit process-flow batch request, format request, or optional `motion=none|explain` in the current repository or an explicitly scoped multi-repository system.</input>
   <rules>
     <rule>Read only the evidence the requested subject needs, the one diagram-type pattern selected, and its matching family template. Do not load unrelated templates or explore beyond the subject's confirmed boundary.</rule>
-    <rule>Select the diagram type from devspec/architecture/_template/diagram-types.md; load only the needed pattern.</rule>
+    <rule>Select the diagram type from devspec/architecture/_template/diagram-types.md.</rule>
     <rule>Start each SVG from the matching family-specific template: `architecture-diagram.svg` for system architecture, application landscape, and infrastructure topology; `process-flow-diagram.svg` for process flows; `sequence-diagram.svg` for interactions; `state-lifecycle-diagram.svg` for state behavior; `domain-model-diagram.svg` for domain models; `journey-map-diagram.svg` for journeys; `timeline-plan-diagram.svg` for timelines; `quadrant-analysis-diagram.svg` for quadrants; and `mindmap-diagram.svg` for mind maps.</rule>
     <rule>Create only evidence-backed, non-duplicate diagrams and persist queue or overview state for recovery.</rule>
-    <rule>For a multi-repository diagram, use repo-access before reading or validating another repository.</rule>
-    <rule>Accept a stable queued `DIA-###` ID or diagram subject, record subject, type, evidence, format, status, and next in the queue, and index completed output in the overview. On an explicit process-flow batch request, generate every queued non-duplicate process-flow candidate, validate each output, update each queue row independently, and leave the caller lifecycle state unchanged.</rule>
+    <rule>Record an evidence blocker in the caller's decision record, never in the queue, and leave the caller's saved stage and next action unchanged.</rule>
+    <rule>Accept a stable queued `DIA-###` ID or diagram subject, record subject, type, evidence, output format, duplicate-check result, status, and next action in the queue, and index completed output in the overview. On an explicit process-flow batch request, generate every queued non-duplicate process-flow candidate, validate each output, update each queue row independently, and leave the caller lifecycle state unchanged.</rule>
     <rule>Default to SVG with title and description and validate its XML. Write Mermaid or HTML only when explicitly requested, and when you do, record it from `devspec/architecture/_template/diagram.md` or `diagram.html` so its evidence, assumptions, and maintenance notes stay with the output.</rule>
     <rule>Default to `motion=none`. Treat an explicit request for an animated diagram without a motion value as `motion=explain`; reject unsupported motion values.</rule>
     <rule>For `motion=explain`, animate only an evidence-backed sequence, flow, or state transition and follow the opt-in motion guidance in diagram-types.md. Keep the complete meaning visible in the static final frame, provide a reduced-motion result with no information loss, and do not add decorative motion or imply unsupported behavior.</rule>
@@ -34,6 +34,8 @@ Invocation: `/devspec.diagram runtime architecture format=svg motion=none|explai
   <outputs>
     <artifact path="devspec/architecture/artifact-queue.md" />
     <artifact path="devspec/architecture/overview.md" />
+    <artifact path="devspec/foundation/decisions.md" />
+    <artifact path="devspec/work-items/&lt;id&gt;/decisions.md" />
   </outputs>
   <transitions>
     <transition outcome="diagram-complete" stage="caller" run="active" next="return-to-caller" />
diff --git a/devspec/contracts/devspec.extract.md b/devspec/contracts/devspec.extract.md
index 67a250e..6dbfc4c 100644
--- a/devspec/contracts/devspec.extract.md
+++ b/devspec/contracts/devspec.extract.md
@@ -17,29 +17,23 @@ Invocation: `/devspec.extract`
   <scope>Use for the existing-system baseline of an approved source scope. This command completes the whole foundation chain in one run; do not also run the individual foundation commands for the same repository. It prepares diagram candidates and offers generation once; devspec.diagram owns every later diagram.</scope>
   <input>Explicitly confirmed source repository scope, or current canonical evidence that names each repository's role, local path, and allowed access.</input>
   <rules>
-    <rule>Treat the agent's current workspace or scaffolding directory as a proposed source target, never proof. Before inspecting source, obtain either an explicit user confirmation that names every source repository, role, path, and read, edit, and validation permission, or current canonical evidence that records those facts. If neither exists, first collect one repository path at a time, then ask one access question after each confirmed path; record the accepted source scope in `devspec/foundation/codebase-structure.md` before reading source. Later commands may use that current record as scope evidence.</rule>
+    <rule>Complete repo-access before inspecting source, then record the accepted source scope in `devspec/foundation/codebase-structure.md`. Later commands may use that record as scope evidence.</rule>
     <rule>Inspect owned source, tests, manifests, configuration, infrastructure, scripts, and docs; exclude dependencies, caches, generated output, and repositories outside approved scope.</rule>
-    <rule>For multi-repository work, record every repository role, path, access boundary, and evidence before reading, editing, or validating it.</rule>
     <rule>For every approved repository, record an observed repository layout in `devspec/foundation/codebase-structure.md`: a readable `text` tree rooted at its confirmed local path that includes solution or manifest files, owned source and test roots, meaningful modules, configuration, and integration or migration locations. Keep the tree representative rather than exhaustive; exclude dependencies, caches, generated output, and secrets.</rule>
-    <rule>Ask one clarification for every unresolved material question. Label all durable findings confirmed, observed, inferred, or blocked; do not invent roles, workflows, business rules, validation rules, integrations, or diagrams.</rule>
+    <rule>Do not invent roles, workflows, business rules, validation rules, integrations, or diagrams; record an absent fact as blocked instead.</rule>
     <rule>Initialize and complete every listed foundation artifact from its template when missing: project context, technology stack, codebase structure, coding standards with followable local examples, rules, technical baseline, roles, workflows, workflow rules, extraction state, exploration state, and coverage. Record rare cross-work-item principle candidates in `devspec/constitution.md` with stable `CP-###` IDs, evidence, and candidate state; do not promote inferred candidates.</rule>
     <rule>For each observed coding convention that changes implementation or review behavior, assign a stable `CS-###` ID and capture one or more concise, concrete local code or test snippets as `EX-###` entries under `## Standards Examples`. Each entry names the applicable standard IDs, source location, and fenced language-appropriate code; one example may apply to multiple standards. Record a relevant anti-pattern when repository evidence supports one.</rule>
-    <rule>Populate the single OWASP Top 10:2025 baseline in rules.md from observed code, dependencies, configuration, deployment, and access evidence. Record controls, gaps, and unknowns; do not infer an internal-only or limited-access boundary without enforceable evidence.</rule>
+    <rule>Populate the OWASP baseline in rules.md from observed code, dependency, configuration, deployment, and access evidence.</rule>
     <rule>For every confirmed business workflow, record its business area, participating roles, trigger, outcome, business rules, validation rules, evidence, and applicable exceptions.</rule>
     <rule>Identify applicable evidence-backed diagram candidates: system architecture, application landscape, infrastructure topology, integration sequence or context, and a journey or process-flow diagram for every confirmed workflow. Add domain-model or state-lifecycle candidates only when evidence supports them.</rule>
-    <rule>Record every candidate in the diagram queue with its stable ID, type, subject, evidence, output format, duplicate-check result, status, and next action. Keep the overview limited to completed diagram links; do not generate an SVG or add an overview entry during extraction before the user answers the post-extraction diagram question.</rule>
-    <rule>After all foundation extraction outputs are complete, show the user or developer the complete candidate list. When one or more candidates exist, ask exactly one interactive confirmation: "Do you want me generate all the possible diagrams?" Offer: `Yes — generate all listed diagrams`, `No — prepare the list only`, `Choose diagrams — enter the IDs or subjects to generate`, and `Custom Answer`. Recommend `No — prepare the list only` when no generation preference is already confirmed. Each choice must include a concise example.</rule>
-    <rule>If the user or developer chooses `Yes`, generate every listed non-duplicate candidate, validate each SVG XML file, update its queue status, and index completed durable output in the overview. If they choose `No`, leave the evidence-backed candidate list prepared in the queue without generating diagrams. If they choose `Choose diagrams`, generate only the entered non-duplicate IDs or subjects and leave the remainder listed in the queue.</rule>
-    <rule>Whenever the candidate list is shown, tell the user or developer that any listed diagram can be generated later with `/devspec.diagram &lt;DIA-ID-or-subject&gt;`; include one concrete example such as `/devspec.diagram DIA-002`.</rule>
+    <rule>Record every candidate in the diagram queue with its stable ID, type, subject, evidence, output format, duplicate-check result, status, and next action. Keep the overview limited to completed diagram links; do not generate an SVG or add an overview entry during extraction before the developer answers the post-extraction diagram question.</rule>
+    <rule>After all foundation extraction outputs are complete, show the developer the complete candidate list. When one or more candidates exist, ask exactly one interactive confirmation: "Do you want me to generate all the possible diagrams?" Offer: `Yes — generate all listed diagrams`, `No — prepare the list only`, `Choose diagrams — enter the IDs or subjects to generate`, and `Custom Answer`. Recommend `No — prepare the list only` when no generation preference is already confirmed. Each choice must include a concise example.</rule>
+    <rule>If the developer chooses `Yes`, generate every listed non-duplicate candidate, validate each SVG XML file, update its queue status, and index completed durable output in the overview. If they choose `No`, leave the evidence-backed candidate list prepared in the queue without generating diagrams. If they choose `Choose diagrams`, generate only the entered non-duplicate IDs or subjects and leave the remainder listed in the queue.</rule>
+    <rule>Whenever the candidate list is shown, tell the developer that any listed diagram can be generated later with `/devspec.diagram &lt;DIA-ID-or-subject&gt;`; include one concrete example such as `/devspec.diagram DIA-002`.</rule>
     <rule>Record every path deliberately left out of inspection in `devspec/foundation/discovery-exclusions.md` with its reason, so a later run does not re-explore it or mistake the gap for missing evidence.</rule>
     <rule>Keep one extraction coverage item active and write discovered facts to their destination artifact, not queue state. Reuse recorded discovery methods and do not repeat a failed method unless its condition changed.</rule>
   </rules>
   <entry>Existing system with confirmed source scope and no active incompatible extraction run; reject new-repository foundation authoring or an assumed workspace target.</entry>
-  <transitions>
-    <transition outcome="foundation-ready" stage="foundation" run="active" next="devspec.story" />
-    <transition outcome="evidence-blocked" stage="foundation" run="blocked" next="devspec.clarify" />
-  </transitions>
-  <closure>Complete the listed baseline outputs and present the diagram candidate list before routing to story. Record every material evidence gap as blocked with a continuation condition, and preserve ungenerated candidates for `/devspec.diagram`.</closure>
   <outputs>
     <artifact path="devspec/constitution.md" />
     <artifact path="devspec/foundation/project-context.md" />
@@ -59,4 +53,9 @@ Invocation: `/devspec.extract`
     <artifact path="devspec/architecture/overview.md" />
     <artifact path="devspec/foundation/decisions.md" />
   </outputs>
+  <transitions>
+    <transition outcome="foundation-ready" stage="foundation" run="active" next="devspec.story" />
+    <transition outcome="evidence-blocked" stage="foundation" run="blocked" next="devspec.clarify" />
+  </transitions>
+  <closure>Complete the listed baseline outputs and present the diagram candidate list before routing to story. Record every material evidence gap as blocked with a continuation condition, and preserve ungenerated candidates for `/devspec.diagram`.</closure>
 </workflow>
diff --git a/devspec/contracts/devspec.finalize.md b/devspec/contracts/devspec.finalize.md
index 5425e09..6e2c5ef 100644
--- a/devspec/contracts/devspec.finalize.md
+++ b/devspec/contracts/devspec.finalize.md
@@ -29,6 +29,7 @@ Invocation: `/devspec.finalize [work-item-id]`
   <outputs>
     <artifact path="devspec/work-items/&lt;id&gt;/finalize.md" />
     <artifact path="devspec/work-items/&lt;id&gt;/meta.md" />
+    <artifact path="devspec/work-items/&lt;id&gt;/decisions.md" />
   </outputs>
   <transitions>
     <transition outcome="ready" stage="tasks" run="active" next="devspec.tasks" />
diff --git a/devspec/contracts/devspec.grooming.md b/devspec/contracts/devspec.grooming.md
index 1e8025e..091c52b 100644
--- a/devspec/contracts/devspec.grooming.md
+++ b/devspec/contracts/devspec.grooming.md
@@ -13,6 +13,7 @@ Invocation: `/devspec.grooming [work-item-id]`
     <protocol ref="current-work-item" />
     <protocol ref="revision" />
     <protocol ref="work" />
+    <protocol ref="repo-access" />
   </protocols>
   <scope>Use only when a draft story needs scoped analysis before it can be built. Skip it and run devspec.finalize directly when behavior, acceptance criteria, and the affected code area are already clear.</scope>
   <input>An optional work-item ID or clear current draft.</input>
@@ -25,6 +26,7 @@ Invocation: `/devspec.grooming [work-item-id]`
   <outputs>
     <artifact path="devspec/work-items/&lt;id&gt;/story.md" />
     <artifact path="devspec/work-items/&lt;id&gt;/decisions.md" />
+    <artifact path="devspec/work-items/&lt;id&gt;/meta.md" />
   </outputs>
   <transitions>
     <transition outcome="ready-for-finalization" stage="finalization" run="active" next="devspec.finalize" />
diff --git a/devspec/contracts/devspec.implement.md b/devspec/contracts/devspec.implement.md
index 8231548..ded72ef 100644
--- a/devspec/contracts/devspec.implement.md
+++ b/devspec/contracts/devspec.implement.md
@@ -30,10 +30,12 @@ Invocation: `/devspec.implement [work-item-id]`
   <outputs>
     <artifact path="devspec/work-items/&lt;id&gt;/implement.md" />
     <artifact path="devspec/work-items/&lt;id&gt;/tasks.md" />
+    <artifact path="devspec/work-items/&lt;id&gt;/meta.md" />
+    <artifact path="devspec/work-items/&lt;id&gt;/decisions.md" />
   </outputs>
   <transitions>
     <transition outcome="implementation-complete" stage="review" run="active" next="devspec.review" />
     <transition outcome="material-blocker" stage="implementation" run="blocked" next="devspec.clarify" />
   </transitions>
-  <closure>Record the changed-work baseline and mark a task complete only after its recorded validation passes; preserve superseded revisions.</closure>
+  <closure>Record the changed-work baseline and mark a task complete only after its recorded validation passes.</closure>
 </workflow>
diff --git a/devspec/contracts/devspec.projectcontext.md b/devspec/contracts/devspec.projectcontext.md
index 14555db..8b0860e 100644
--- a/devspec/contracts/devspec.projectcontext.md
+++ b/devspec/contracts/devspec.projectcontext.md
@@ -28,5 +28,5 @@ Invocation: `/devspec.projectcontext`
     <transition outcome="targeted-update-complete" stage="foundation" run="active" next="return-to-caller" />
     <transition outcome="evidence-blocked" stage="foundation" run="blocked" next="devspec.clarify" />
   </transitions>
-  <closure>Record the foundation state and one registered next command; blocked evidence routes to devspec.clarify.</closure>
+  <closure>Record the foundation state and one registered next command.</closure>
 </workflow>
diff --git a/devspec/contracts/devspec.quickfix.md b/devspec/contracts/devspec.quickfix.md
index e406818..085a8b8 100644
--- a/devspec/contracts/devspec.quickfix.md
+++ b/devspec/contracts/devspec.quickfix.md
@@ -13,7 +13,7 @@ Invocation: `/devspec.quickfix Fix Orders empty-state text`
     <protocol ref="work" />
     <protocol ref="repo-access" />
   </protocols>
-  <scope>Use only for one localized, low-risk change that needs no work item. Route public contracts, schema or migration work, security work, breaking changes, and unresolved risk to devspec.story instead.</scope>
+  <scope>Use only for one localized, low-risk change that needs no work item. Route anything outside that boundary to devspec.story before editing code.</scope>
   <input>One localized bug fix or small enhancement.</input>
   <rules>
     <rule>Select one primary scope: UI, internal API, function/job, library, configuration, tests, or a user-defined bounded scope.</rule>
@@ -21,7 +21,7 @@ Invocation: `/devspec.quickfix Fix Orders empty-state text`
     <rule>Create a QF record, implement, and run focused validation in the same command.</rule>
     <rule>Route public API contracts, database schema or migration, authentication or security work, breaking changes, unrelated concerns, and unresolved risk to story and suggested grooming without editing code.</rule>
   </rules>
-  <entry>One documented localized low-risk request at triage with one primary scope; reject contracts, migrations, security work, breaking changes, unrelated concerns, and unresolved risk.</entry>
+  <entry>One documented localized low-risk request at triage with one primary scope; reject any request this command must route.</entry>
   <outputs>
     <artifact path="devspec/quickfixes/QF-###-slug.md" />
   </outputs>
diff --git a/devspec/contracts/devspec.review.md b/devspec/contracts/devspec.review.md
index 92d8c64..6307bc7 100644
--- a/devspec/contracts/devspec.review.md
+++ b/devspec/contracts/devspec.review.md
@@ -33,6 +33,7 @@ Invocation: `/devspec.review [work-item-id]`
   <outputs>
     <artifact path="devspec/work-items/&lt;id&gt;/review.md" />
     <artifact path="devspec/work-items/&lt;id&gt;/meta.md" />
+    <artifact path="devspec/work-items/&lt;id&gt;/decisions.md" />
   </outputs>
   <transitions>
     <transition outcome="accepted" stage="complete" run="complete" next="none" />
diff --git a/devspec/contracts/devspec.rules.md b/devspec/contracts/devspec.rules.md
index bc158ef..62389c6 100644
--- a/devspec/contracts/devspec.rules.md
+++ b/devspec/contracts/devspec.rules.md
@@ -29,5 +29,5 @@ Invocation: `/devspec.rules`
     <transition outcome="targeted-update-complete" stage="foundation" run="active" next="return-to-caller" />
     <transition outcome="evidence-blocked" stage="foundation" run="blocked" next="devspec.clarify" />
   </transitions>
-  <closure>Record enforceable rules and one registered next command; blocked evidence routes to devspec.clarify.</closure>
+  <closure>Record enforceable rules and one registered next command.</closure>
 </workflow>
diff --git a/devspec/contracts/devspec.story.md b/devspec/contracts/devspec.story.md
index 2e488f5..7e6d12d 100644
--- a/devspec/contracts/devspec.story.md
+++ b/devspec/contracts/devspec.story.md
@@ -13,6 +13,7 @@ Invocation: `/devspec.story Add customer export`
     <protocol ref="current-work-item" />
     <protocol ref="revision" />
     <protocol ref="work" />
+    <protocol ref="repo-access" />
   </protocols>
   <scope>Use to open one new work item from a manual request or a provider reference. Use devspec.changerequest for related scope on an already-finalized work item, and devspec.quickfix for a localized low-risk change that needs no work item.</scope>
   <input>One manual feature, bug, security issue, or task, or one provider work-item URL or identifier resolvable through an available authenticated MCP tool.</input>
@@ -27,8 +28,7 @@ Invocation: `/devspec.story Add customer export`
     <rule>Read only the coding standards, codebase structure, foundation rules, and workflow rules relevant to the requested behavior and code area; do not scan unrelated historical work-item decisions.</rule>
     <rule>Resolve a provider reference against `devspec/foundation/provider-integrations.md`: use its accepted inputs, validation guardrails, and confirmation requirements, and record the resolution outcome there when a new provider, input form, or guardrail is confirmed.</rule>
     <rule>Create folders as optional-provider-prefix plus numeric ID plus kebab-case title; do not rename legacy folders automatically.</rule>
-    <rule>Before finalization, update the baseline; after finalization, route related scope to changerequest and unrelated scope to a linked item.</rule>
-    <rule>Treat an explicit story request as new-work intent unless it is clearly related finalized scope, which routes to changerequest.</rule>
+    <rule>Treat an explicit story request as new-work intent. Before finalization, update the baseline in place; after finalization, route related scope to changerequest and unrelated scope to a linked item.</rule>
     <rule>When creating a story or accepting a validated explicit ID, set current-work-item context for the current branch; preserve meta.md as the canonical state record.</rule>
     <rule>For an ordinary request with current context, resume clearly related pre-finalization work; ask one classification question before switching stories or accepting independent scope.</rule>
   </rules>
@@ -37,6 +37,7 @@ Invocation: `/devspec.story Add customer export`
     <artifact path="devspec/work-items/&lt;id&gt;/story.md" />
     <artifact path="devspec/work-items/&lt;id&gt;/meta.md" />
     <artifact path="devspec/foundation/provider-integrations.md" />
+    <artifact path="devspec/work-items/&lt;id&gt;/decisions.md" />
   </outputs>
   <transitions>
     <transition outcome="grooming-required" stage="grooming" run="active" next="devspec.grooming" />
diff --git a/devspec/contracts/devspec.tasks.md b/devspec/contracts/devspec.tasks.md
index c34b7be..19269ed 100644
--- a/devspec/contracts/devspec.tasks.md
+++ b/devspec/contracts/devspec.tasks.md
@@ -14,6 +14,7 @@ Invocation: `/devspec.tasks [work-item-id]`
     <protocol ref="revision" />
     <protocol ref="work" />
     <protocol ref="repo-access" />
+    <protocol ref="security" />
   </protocols>
   <scope>Use to turn a ready finalization into an ordered, independently verifiable plan. This command plans only; devspec.implement makes the changes.</scope>
   <input>An optional work-item ID with a ready current finalization brief.</input>
@@ -22,10 +23,11 @@ Invocation: `/devspec.tasks [work-item-id]`
     <rule>Each task names scope, dependency, source justification, applicable decision or canonical rule IDs, validation, and done condition. Cite the finalization foundation and architecture traces for coding standards, codebase boundaries, diagrams, and OWASP controls instead of duplicating them per task.</rule>
     <rule>Order dependencies before dependents and split only work too broad to validate safely.</rule>
   </rules>
-  <entry>Active work item at tasks with a ready finalization matching the current scope revision; reject blocked, stale, or superseded readiness evidence.</entry>
+  <entry>Active work item at tasks with a ready finalization matching the current scope revision; reject blocked readiness evidence.</entry>
   <outputs>
     <artifact path="devspec/work-items/&lt;id&gt;/tasks.md" />
     <artifact path="devspec/work-items/&lt;id&gt;/meta.md" />
+    <artifact path="devspec/work-items/&lt;id&gt;/decisions.md" />
   </outputs>
   <transitions>
     <transition outcome="tasks-planned" stage="implementation" run="active" next="devspec.implement" />
diff --git a/devspec/contracts/devspec.techstack.md b/devspec/contracts/devspec.techstack.md
index 74725b9..e21cd65 100644
--- a/devspec/contracts/devspec.techstack.md
+++ b/devspec/contracts/devspec.techstack.md
@@ -11,6 +11,7 @@ Invocation: `/devspec.techstack`
     <protocol ref="run" />
     <protocol ref="state" />
     <protocol ref="work" />
+    <protocol ref="repo-access" />
   </protocols>
   <scope>Use for new-repository foundation authoring or an explicitly requested targeted update. Use devspec.extract, not this command, to establish an existing-system baseline.</scope>
   <input>Stack evidence, target stack, or delivery constraint.</input>
@@ -28,5 +29,5 @@ Invocation: `/devspec.techstack`
     <transition outcome="targeted-update-complete" stage="foundation" run="active" next="return-to-caller" />
     <transition outcome="evidence-blocked" stage="foundation" run="blocked" next="devspec.clarify" />
   </transitions>
-  <closure>Record inspected evidence and one registered next command; blocked evidence routes to devspec.clarify.</closure>
+  <closure>Record inspected evidence and one registered next command.</closure>
 </workflow>
diff --git a/devspec/foundation/_template/codebase-structure.md b/devspec/foundation/_template/codebase-structure.md
index 38f9ba5..4f8b89a 100644
--- a/devspec/foundation/_template/codebase-structure.md
+++ b/devspec/foundation/_template/codebase-structure.md
@@ -27,4 +27,4 @@ For every repository above, record a representative tree rooted at its confirmed
 |   `-- &lt;meaningful-module&gt;/
 |-- &lt;test-root&gt;/
 `-- &lt;configuration-or-migration-location&gt;/
-```
\ No newline at end of file
+```
diff --git a/devspec/foundation/_template/decisions.md b/devspec/foundation/_template/decisions.md
index ae810e6..8908d95 100644
--- a/devspec/foundation/_template/decisions.md
+++ b/devspec/foundation/_template/decisions.md
@@ -7,5 +7,7 @@
 
 ## Decisions
 
+One row per material question, in the shape `devspec/protocols/ask.xml` requires. Record the row before waiting for an answer.
+
 | ID | Material question | Evidence | Impact | Choices | Recommended | Recommendation justification | Applicability | Canonical rule link | Answer or skip reason | Status |
-|---|---|---|---|---|---|---|---|---|---|---|
\ No newline at end of file
+|---|---|---|---|---|---|---|---|---|---|---|
diff --git a/devspec/foundation/_template/extraction-coverage.md b/devspec/foundation/_template/extraction-coverage.md
index 68f674c..3996d03 100644
--- a/devspec/foundation/_template/extraction-coverage.md
+++ b/devspec/foundation/_template/extraction-coverage.md
@@ -1,4 +1,4 @@
 # Extraction Coverage
 
 | Area | Scope | Destination artifact | Evidence | Status | Gap or next action |
-|---|---|---|---|---|---|
\ No newline at end of file
+|---|---|---|---|---|---|
diff --git a/devspec/foundation/_template/provider-integrations.md b/devspec/foundation/_template/provider-integrations.md
index 786b88d..1a00cab 100644
--- a/devspec/foundation/_template/provider-integrations.md
+++ b/devspec/foundation/_template/provider-integrations.md
@@ -47,4 +47,4 @@ Show provider, identifier, title, type when available, current external status w
 | Failure detail | Distinguish not found, unauthorized, malformed input, and transient provider failures. |
 | Authentication configuration | Keep provider authentication outside prompt artifacts. |
 | Privilege model | Use least-privilege tokens or service identities. |
-| Access mode | Prefer read-only access for intake and review unless write-back is separately required. |
\ No newline at end of file
+| Access mode | Prefer read-only access for intake and review unless write-back is separately required. |
diff --git a/devspec/foundation/_template/roles.md b/devspec/foundation/_template/roles.md
index 553e39f..c658559 100644
--- a/devspec/foundation/_template/roles.md
+++ b/devspec/foundation/_template/roles.md
@@ -1,4 +1,4 @@
 # Roles
 
 | Role | Responsibilities | Permission boundary | Workflows | Evidence |
-|---|---|---|---|---|
\ No newline at end of file
+|---|---|---|---|---|
diff --git a/devspec/foundation/_template/rules.md b/devspec/foundation/_template/rules.md
index b062016..f115272 100644
--- a/devspec/foundation/_template/rules.md
+++ b/devspec/foundation/_template/rules.md
@@ -22,4 +22,4 @@ Record the project applicability, required control, and enforcement evidence for
 | A07:2025 Authentication Failures |  |  |  |  |
 | A08:2025 Software or Data Integrity Failures |  |  |  |  |
 | A09:2025 Security Logging and Alerting Failures |  |  |  |  |
-| A10:2025 Mishandling of Exceptional Conditions |  |  |  |  |
\ No newline at end of file
+| A10:2025 Mishandling of Exceptional Conditions |  |  |  |  |
diff --git a/devspec/foundation/_template/technical-baseline.md b/devspec/foundation/_template/technical-baseline.md
index f62eb47..2f3f500 100644
--- a/devspec/foundation/_template/technical-baseline.md
+++ b/devspec/foundation/_template/technical-baseline.md
@@ -13,4 +13,4 @@
 ## Integrations
 
 | Integration | Direction | Contract or protocol | Failure or security concern | Evidence |
-|---|---|---|---|---|
\ No newline at end of file
+|---|---|---|---|---|
diff --git a/devspec/foundation/_template/workflow-rules.md b/devspec/foundation/_template/workflow-rules.md
index ea38b76..5fbd477 100644
--- a/devspec/foundation/_template/workflow-rules.md
+++ b/devspec/foundation/_template/workflow-rules.md
@@ -1,4 +1,4 @@
 # Workflow Rules
 
 | Rule ID | Workflow ID | Applicability | Rule | Validation or enforcement | Exception | Source decision | Evidence |
-|---|---|---|---|---|---|---|---|
\ No newline at end of file
+|---|---|---|---|---|---|---|---|
diff --git a/devspec/foundation/_template/workflows.md b/devspec/foundation/_template/workflows.md
index a293692..d4caedc 100644
--- a/devspec/foundation/_template/workflows.md
+++ b/devspec/foundation/_template/workflows.md
@@ -8,4 +8,4 @@
 ## Role Workflow Matrix
 
 | Role | Workflow ID | Responsibility | Entry or exit | Evidence |
-|---|---|---|---|---|
\ No newline at end of file
+|---|---|---|---|---|
diff --git a/devspec/foundation/template-map.md b/devspec/foundation/template-map.md
index 042e303..492a2b7 100644
--- a/devspec/foundation/template-map.md
+++ b/devspec/foundation/template-map.md
@@ -18,4 +18,4 @@ Create a missing canonical artifact from its matching template before editing it
 | `_template/exploration-state.md` | `exploration-state.md` | `devspec.extract` |
 | `_template/extraction-coverage.md` | `extraction-coverage.md` | `devspec.extract` |
 | `_template/discovery-exclusions.md` | `discovery-exclusions.md` | `devspec.extract` |
-| `_template/provider-integrations.md` | `provider-integrations.md` | provider-backed work |
\ No newline at end of file
+| `_template/provider-integrations.md` | `provider-integrations.md` | provider-backed work |
diff --git a/devspec/glossary.md b/devspec/glossary.md
index 0989ba5..6af9ba2 100644
--- a/devspec/glossary.md
+++ b/devspec/glossary.md
@@ -2,9 +2,13 @@
 
 Run states, work-item and quickfix stages, task statuses, evidence labels, the changed-work baseline, and resume semantics are defined once in `devspec/protocols/state.xml`. `devspec/lifecycle.md` owns the route graph. This file covers the remaining terms.
 
-- Scope revision: a monotonic work-item number. Finalization, tasks, implementation, and review operate only on the current revision; older records are retained as superseded history. `devspec/protocols/revision.xml` owns its rules.
+- Scope revision: a monotonic work-item number identifying which generation of approved scope a record belongs to. `devspec/protocols/revision.xml` owns its rules.
 - Current work-item context: a private, per-worktree Git-metadata selection used to resolve an omitted work-item ID. It is never a Git-tracked artifact and never replaces `meta.md` as canonical state.
-- Material question: a question whose answer can change implementation, validation, or scope. Only material questions enter the ask queue.
+- Material question: a question whose answer can change implementation, validation, or scope. Only material questions enter the ask queue; anything else is decided without asking.
+- Material decision: the recorded answer to a material question, held in the command's decision record.
+- Material blocker: a material question that must be answered before the command can continue. It sets run state `blocked` and makes `devspec.clarify` the next command. Exactly one may be active at a time.
+- Developer: the person the agent asks. Every interactive question in this framework is addressed to the developer; the agent never answers its own material question.
+- Registered next action: the single next command recorded in the state record. A command reports exactly one, and `none` is a valid registered next action for terminal work.
 - OWASP exception: a reviewer-confirmed false-positive or not-applicable finding supported by enforceable evidence; it is distinct from an unresolved vulnerability. `devspec/protocols/security.xml` owns its confirmation rules.
 
 ## Repository access requirements
@@ -18,4 +22,4 @@ Run states, work-item and quickfix stages, task statuses, evidence labels, the c
 | `release-coordination` | Coordinate release information only; do not inspect, edit, or validate repository contents. |
 | `unavailable` | The repository cannot currently be accessed; record the impact as a blocker. |
 
-Record these values in `foundation/codebase-structure.md`. Select the least privilege that satisfies the current command; the repository location alone never grants access. `devspec/protocols/repo-access.xml` owns how they are collected and enforced.
+These lowercase values are the recorded form. `devspec/protocols/repo-access.xml` owns how they are collected, recommended, recorded, and enforced.
diff --git a/devspec/lifecycle.md b/devspec/lifecycle.md
index b9abb2a..9eef2c4 100644
--- a/devspec/lifecycle.md
+++ b/devspec/lifecycle.md
@@ -7,7 +7,7 @@ Canonical contracts in `devspec/contracts/` own command behavior. This document
 - A foundation command records its command, stage, run state, last action, resume reference, next action, and update date in `devspec/foundation/decisions.md`.
 - A work item records the same state in `meta.md`, together with its scope revision.
 - A quickfix records its state in front matter. A diagram records queue status and returns to its invoking workflow without changing that workflow's state.
-- The selected current work item is private convenience state, not workflow evidence. Store it only at the per-worktree path returned by `git rev-parse --git-path devspec/current-work-item.json`. Never commit a current-story file. `devspec/protocols/current-work-item.xml` owns its selection, validation, and recovery rules.
+- The selected current work item is private convenience state, never workflow evidence and never committed. `devspec/protocols/current-work-item.xml` owns where it is stored and how it is selected, validated, and cleared.
 
 ## Work-item stages
 
@@ -28,5 +28,5 @@ Every non-terminal stage may route to `devspec.clarify`, and only to `devspec.cl
 - Existing repository: `devspec.extract → devspec.story`.
 - New repository: `devspec.projectcontext → devspec.techstack → devspec.codebase-structure → devspec.coding-standards → devspec.rules → devspec.story`. A targeted foundation update returns to its caller after completing its declared artifact.
 - Work item: `devspec.story → devspec.grooming|devspec.finalize → devspec.tasks → devspec.implement → devspec.review`. Review results are `accepted → complete`, `rework-required → devspec.implement`, or `blocked → devspec.clarify`.
-- Work-item IDs are optional selectors for switching or resolving ambiguity. After a story is selected, normal commands and `continue` use its per-worktree context and never skip the recorded `next` command.
-- `devspec.clarify` resolves one decision and resumes its saved originating command. `devspec.changerequest` is allowed only after finalization and always returns to `devspec.finalize` with a new revision. `devspec.quickfix` is `complete`, `blocked`, or `routed → devspec.story`. `devspec.diagram` returns to its caller.
+- Work-item IDs are optional selectors for switching or resolving ambiguity. Without one, the current-work-item protocol resolves which work item a command acts on.
+- `devspec.clarify` resolves one decision and resumes its saved originating command. `devspec.changerequest` is allowed only after finalization and always returns to `devspec.finalize` with a new revision. `devspec.quickfix` ends complete, blocks to `devspec.clarify`, or routes to `devspec.story`. `devspec.diagram` returns to its caller.
diff --git a/devspec/protocols/ask.xml b/devspec/protocols/ask.xml
index e3d5b9b..c9d4e88 100644
--- a/devspec/protocols/ask.xml
+++ b/devspec/protocols/ask.xml
@@ -1,11 +1,12 @@
 <protocol id="ask">
+  <when>Load with every command. It governs how any material question is asked and recorded.</when>
   <scope>Maintain one active material-question queue for the invoking command. A command may deliberately scope its queue to one recorded material blocker.</scope>
   <trigger>Ask one clarification for every unresolved material question in the active command queue.</trigger>
   <sequence>Ask exactly one unanswered material question at a time. Record and resolve it before asking the next material question.</sequence>
   <completion>Maintain the active material-question queue until every material question is answered or skipped. After each answer, re-evaluate every remaining material question against current decisions; skip an invalid or inapplicable material question with its reason, then ask the next valid unanswered material question. Resume the workflow only when no applicable unanswered material questions remain.</completion>
   <checkpoint>Persist material-question ID, evidence, impact, choices, recommendation, recommendation justification, applicability, canonical rule link when promoted, resume action, and answer-or-skip status in the command's decision record before waiting.</checkpoint>
   <interaction count="one" mode="interactive">
-    <choices>Offer two to five meaningful exclusive choices, each with a short example.</choices>
+    <choices>Offer two to five meaningful exclusive choices, each with a short example. A protocol that defines a fixed named value set offers that whole set instead. Custom Answer is always additional and never counts toward the limit.</choices>
     <recommendation required="true" justification-required="true" />
     <custom-answer required="true" />
     <fallback>Render identical text choices only when the host lacks interactive controls.</fallback>
diff --git a/devspec/protocols/current-work-item.xml b/devspec/protocols/current-work-item.xml
index 40984f1..d4d875e 100644
--- a/devspec/protocols/current-work-item.xml
+++ b/devspec/protocols/current-work-item.xml
@@ -2,9 +2,9 @@
   <when>Use before a work-item command with an omitted ID and for a clear continuation request such as continue or where were we.</when>
   <location>Use `git rev-parse --git-path devspec/current-work-item.json` for per-worktree local context. Never create or commit a tracked current-work-item artifact.</location>
   <record>Store work-item ID, current branch, selection source, and timestamp only in that local JSON record; it is never committed or pushed.</record>
-  <selection>Prefer a validated explicit ID, then a valid local selection for the current branch, then exactly one eligible non-terminal work item. Ask the user to choose whenever multiple items remain.</selection>
+  <selection>Prefer a validated explicit ID, then a valid local selection for the current branch, then exactly one non-terminal work item on the current branch. Ask the developer to choose whenever multiple items remain.</selection>
   <validation>Clear a selection when its branch changed, its folder or meta record is missing, it is complete, or its saved stage and next action do not permit the requested command.</validation>
-  <recovery>When no valid selection exists, recover only one eligible work item; otherwise ask the user to select or start a story.</recovery>
+  <recovery>When no valid selection exists, recover only one eligible work item; otherwise ask the developer to select one or start a work item.</recovery>
   <continuation>For a clear continuation request, dispatch only the selected saved meta.md next action. A blocked item uses devspec.clarify; a terminal item is not resumed.</continuation>
   <update>Set local context after story creation, validated explicit selection, or unique recovery. Preserve it while clarify restores the saved command.</update>
   <clear>Clear local context after accepted review. Context is convenience state; meta.md remains canonical workflow truth.</clear>
diff --git a/devspec/protocols/repo-access.xml b/devspec/protocols/repo-access.xml
index fd02ce1..59df176 100644
--- a/devspec/protocols/repo-access.xml
+++ b/devspec/protocols/repo-access.xml
@@ -1,6 +1,8 @@
 <protocol id="repo-access">
-  <when>Load before accessing a repository outside the scaffolding root, whenever source scope is not already confirmed, and whenever a task depends on more than one repository.</when>
-  <collect>When a repository path is not already evidenced, first ask for one repository name or local path in a free-form text input. Show at least two examples such as `D:\Code\orders-api` and `D:\Code\orders-web`; allow the developer to type another path. Confirm the path before asking about access, and repeat for each additional repository.</collect>
-  <validate>After each path is confirmed, ask one interactive question: “What access requirement applies to &lt;repository&gt;?” Offer the named access requirements from devspec/glossary.md as exclusive choices with an example each, plus Custom Answer: Reference-only (example: inspect source, configuration, and tests as evidence; do not edit or run validations), Edit (example: update approved repository files; do not run validations), Edit-and-test (Recommended; example: make approved changes and run focused validations, including tests), Validation-only (example: run approved validations without editing), Release-coordination (example: coordinate release information without inspecting or changing repository contents), and Unavailable (example: record a blocker because the repository cannot be accessed). Include Custom Answer (example: a different boundary such as edit only one approved folder). Mark exactly one choice recommended, and recommend the least-privilege option that satisfies the current command. Recommend Edit-and-test with the justification that it permits normal delivery work and focused evidence; it grants capability, not authorization to change source outside the active command scope. Record each repository's role, local path, workspace availability, named access requirement, and evidence. Treat the current workspace as a proposed target until an explicit user confirmation or current canonical evidence names that repository and boundary.</validate>
-  <respect>Never edit a reference-only, validation-only, release-coordination, or unavailable repository. Never validate a reference-only, release-coordination, or unavailable repository. Validate a validation-only repository only when its recorded validation permission allows it.</respect>
-</protocol>
\ No newline at end of file
+  <when>Load before reading, editing, or validating any repository other than the one holding the devspec scaffold, whenever source scope is not already confirmed by current canonical evidence, and whenever the work depends on more than one repository.</when>
+  <collect>When a repository path is not already evidenced, ask for one repository name or local path at a time in a free-form text input. Show at least two examples such as `D:\Code\orders-api` and `D:\Code\orders-web`, and allow the developer to type another path. Confirm the path before asking about access, then repeat for each additional repository.</collect>
+  <question>After each path is confirmed, ask one interactive question: “What access requirement applies to &lt;repository&gt;?” Offer every named access requirement from devspec/glossary.md as an exclusive choice with a short example — reference-only (inspect source, configuration, and tests as evidence), edit (update approved files without running validations), edit-and-test (make approved changes and run focused validations), validation-only (run approved validations without editing), release-coordination (coordinate release information without inspecting the repository), and unavailable (the repository cannot be reached) — plus Custom Answer for a narrower boundary such as editing one approved folder.</question>
+  <recommend>Mark exactly one choice recommended and justify it. Recommend the least-privilege requirement that satisfies the current command; where normal delivery work applies that is edit-and-test, because it permits focused change and evidence. A granted requirement is capability, not authorization to change source outside the active command scope.</recommend>
+  <record>Record each repository's role, local path, workspace availability, named access requirement in the lowercase form devspec/glossary.md uses, and the evidence for it, in devspec/foundation/codebase-structure.md.</record>
+  <respect>Honor exactly the recorded requirement and nothing wider. Never inspect a release-coordination or unavailable repository. Never edit a reference-only, validation-only, release-coordination, or unavailable repository. Never validate a reference-only, edit, release-coordination, or unavailable repository.</respect>
+</protocol>
diff --git a/devspec/protocols/run.xml b/devspec/protocols/run.xml
index 13fd084..a7cae43 100644
--- a/devspec/protocols/run.xml
+++ b/devspec/protocols/run.xml
@@ -1,6 +1,7 @@
 <protocol id="run">
+  <when>Load with every command. It governs preflight, checkpoints, resumption, and closing report.</when>
   <preflight>Before every command, confirm single-repository or multi-repository scope from either explicit developer confirmation or current canonical evidence. Treat the current workspace as proposed, never proof. When repository evidence is absent, complete the repo-access protocol before reading, editing, or validating source; a new repository may explicitly confirm that no source exists yet. Do not inspect or change source until that sequence is complete. Then validate required input, target artifact, stage, and access before output.</preflight>
-  <checkpoint>Before material questions, edits, validation, retries, or handoff, save stage, run state, last action, resume reference, and exactly one next action in the command's state record.</checkpoint>
+  <checkpoint>Before material questions, edits, validation, retries, or handoff, save stage, run state, last action, resume reference, and exactly one next action in the command's state record. For foundation work the state record and the decision record are the same file, holding both a Run State row and a Decisions row.</checkpoint>
   <state-records>
     <work-item>devspec/work-items/&lt;id&gt;/meta.md</work-item>
     <foundation>devspec/foundation/decisions.md</foundation>
@@ -8,6 +9,6 @@
   </state-records>
   <context>For a work-item continuation, use current-work-item before validating stage. Dispatch only the saved next action; do not skip a stage.</context>
   <resume>Resume paused work when prerequisites hold. Clear or recover stale local context, and ask one interactive selection question when multiple work items or a stopped state make continuation ambiguous.</resume>
-  <blocked>Record the material blocker and continuation condition; retry only when that condition changes or the user directs it.</blocked>
+  <blocked>Record the material blocker and continuation condition; retry only when that condition changes or the developer directs it.</blocked>
   <closure>Report artifact, outcome, blocker if any, and exactly one registered next action.</closure>
 </protocol>
\ No newline at end of file
diff --git a/devspec/protocols/security.xml b/devspec/protocols/security.xml
index dec8d1a..fc2becc 100644
--- a/devspec/protocols/security.xml
+++ b/devspec/protocols/security.xml
@@ -1,8 +1,8 @@
 <protocol id="security">
   <when>Load whenever a command establishes, applies, or verifies the project security baseline.</when>
   <baseline>Maintain exactly one OWASP Top 10:2025 baseline, in devspec/foundation/rules.md. For every category record its applicability (applicable, limited, out-of-scope, or unknown), the required project control, and the enforcement or evidence that backs it. Record gaps and unknowns rather than omitting a category.</baseline>
-  <exposure>Record limited or internal-only exposure only when enforceable access, deployment, or network evidence supports it; otherwise treat the category as applicable with reduced exposure. A known unresolved vulnerability is never closed as not applicable because access is limited, authenticated, or internal-only.</exposure>
+  <exposure>Record limited or internal-only exposure only when enforceable access, deployment, or network evidence supports it; otherwise record the category as applicable and note the reduced exposure in its evidence. A known unresolved vulnerability is never closed as not applicable because access is limited, authenticated, or internal-only.</exposure>
   <evidence>Record project-native evidence for every applicable control, expressed through the project's own code, tests, configuration, or pipeline rather than a claim in an artifact.</evidence>
-  <exception>A suspected false positive or not-applicable finding requires one material confirmation question to the implementing developer, then a record of the explicit confirmation, its rationale, the enforceable supporting evidence, and a material-change revalidation trigger covering related code, access control, deployment, integration, and exposure. It remains proposed until a reviewer confirms it.</exception>
-  <gate>Do not mark a work item ready, and do not record an accepted review, while an applicable category, required control, security-validation plan, or exception confirmation is unresolved.</gate>
+  <exception>A suspected false positive or not-applicable finding requires ask the developer one material confirmation question, then a record of the explicit confirmation, its rationale, the enforceable supporting evidence, and a material-change revalidation trigger covering related code, access control, deployment, integration, and exposure. It remains proposed until a reviewer confirms it.</exception>
+  <gate>Do not mark a work item ready, and do not record an accepted review, while an applicable category, its required control, its planned validation, or an exception confirmation is unresolved.</gate>
 </protocol>
diff --git a/devspec/protocols/state.xml b/devspec/protocols/state.xml
index add8983..5fdb941 100644
--- a/devspec/protocols/state.xml
+++ b/devspec/protocols/state.xml
@@ -1,8 +1,8 @@
 <protocol id="state">
   <when>Load with every command. This is the shared vocabulary that every state record, transition, and closing report uses. devspec/lifecycle.md holds the legal route graph and devspec/glossary.md the full term list.</when>
   <repository-route>Read devspec/foundation/repository-state.md before the first foundation command. State `existing` starts at devspec.extract; state `new` starts at devspec.projectcontext. Do not infer the state from the presence of source.</repository-route>
-  <run-states>`active` means the registered next command may run. `paused` is an explicit user pause. `blocked` means exactly one active material decision is recorded and the next command is devspec.clarify. `stopped` requires a new user direction before resuming. `complete` is terminal and must record `next: none`.</run-states>
-  <stages>Work-item stages are intake, grooming, finalization, tasks, implementation, review, and complete. Quickfix stages are triage, implementation, validation, complete, and routed. Foundation and extraction work uses the foundation stage. A command that returns to its caller reports the caller's stage.</stages>
+  <run-states>`active` means the registered next command may run. `paused` is an explicit user pause. `blocked` means exactly one active material decision is recorded and the next command is devspec.clarify. `stopped` requires a new user direction before resuming. `complete` is terminal and must record `next: none`, which is itself the one reported next action.</run-states>
+  <stages>Work-item stages are intake, grooming, finalization, tasks, implementation, review, and complete. A quickfix advances through triage, implementation, and validation inside its single run, then ends at complete or routed; only complete, triage, and routed appear as transition stages. Foundation and extraction work uses the foundation stage. A command that returns to its caller reports the caller's stage.</stages>
   <task-statuses>A task is pending, in-progress, blocked, complete, or superseded. A task becomes complete only after its recorded validation passes.</task-statuses>
   <evidence-labels>Label every durable fact confirmed, observed, inferred, or blocked. Never record an inferred fact as confirmed.</evidence-labels>
   <changed-work-baseline>The changed-work baseline is what an implementation is measured from: the base revision, the comparison revision or an explicit working-tree marker, and the list of changed paths. devspec.implement records it; devspec.review verifies the recorded baseline before judging the work.</changed-work-baseline>
diff --git a/devspec/protocols/work.xml b/devspec/protocols/work.xml
index 46b9c9d..f27001f 100644
--- a/devspec/protocols/work.xml
+++ b/devspec/protocols/work.xml
@@ -1,7 +1,8 @@
 <protocol id="work">
+  <when>Load with every command. It governs what may be touched and how a change is made.</when>
   <scope>Select the smallest affected area and direct dependencies; exclude generated application outputs, dependency directories, caches, and unrelated source. Canonical `devspec/` artifacts remain in scope when the command owns them.</scope>
   <initialize>When a target artifact, required state record, or its parent folder is missing, create it from the matching _template artifact before editing. Resolve foundation artifacts through devspec/foundation/template-map.md. For a new work item, initialize every file from devspec/work-items/_template, including meta.md and decisions.md. For a new quickfix, initialize devspec/quickfixes/QF-###-slug.md from devspec/quickfixes/_template.md. Never overwrite an existing artifact.</initialize>
-  <evidence>Label durable facts as confirmed, observed, inferred, or blocked.</evidence>
+  <evidence>Apply the evidence labels defined in the state protocol to every durable fact this command records.</evidence>
   <change>
     For source changes only, inspect the affected behavior and relevant callers before editing; for defects, identify the underlying cause within approved scope. These checks do not require source exploration for unrelated artifact work.
     Choose the smallest safe change that satisfies approved requirements and project conventions. Prefer suitable existing project code, standard-library or platform capabilities, and installed dependencies before introducing custom code. New dependencies or abstractions require a concrete present need; do not add speculative ones.
diff --git a/devspec/quickfixes/_template.md b/devspec/quickfixes/_template.md
index f0fda6e..de1b7ef 100644
--- a/devspec/quickfixes/_template.md
+++ b/devspec/quickfixes/_template.md
@@ -3,8 +3,8 @@ id: QF-###-slug
 type: bug
 stage: triage
 run: active
-last: none
 scope: []
+last: none
 resume: none
 next: select scope
 updated: <yyyy-mm-dd>
@@ -18,9 +18,11 @@ updated: <yyyy-mm-dd>
 - Validation:
 - Outcome:
 
-- Route: complete | devspec.clarify | devspec.story
+- Route: complete | blocked (`devspec.clarify`) | routed (`devspec.story`)
 
 ## Decisions
 
+One row per material question, in the shape `devspec/protocols/ask.xml` requires.
+
 | ID | Material question | Evidence | Impact | Choices | Recommended | Recommendation justification | Applicability | Canonical rule link | Answer or skip reason | Status |
-|---|---|---|---|---|---|---|---|---|---|---|
\ No newline at end of file
+|---|---|---|---|---|---|---|---|---|---|---|
diff --git a/devspec/work-items/_template/decisions.md b/devspec/work-items/_template/decisions.md
index c1911d4..96dfd36 100644
--- a/devspec/work-items/_template/decisions.md
+++ b/devspec/work-items/_template/decisions.md
@@ -1,4 +1,6 @@
 # Decisions
 
+One row per material question, in the shape `devspec/protocols/ask.xml` requires. Record the row before waiting for an answer.
+
 | ID | Material question | Evidence | Impact | Choices | Recommended | Recommendation justification | Applicability | Canonical rule link | Answer or skip reason | Status |
-|---|---|---|---|---|---|---|---|---|---|---|
\ No newline at end of file
+|---|---|---|---|---|---|---|---|---|---|---|
diff --git a/devspec/work-items/_template/implement.md b/devspec/work-items/_template/implement.md
index a2911cd..d83665c 100644
--- a/devspec/work-items/_template/implement.md
+++ b/devspec/work-items/_template/implement.md
@@ -12,4 +12,4 @@
 | Finding ID | OWASP category | Disposition | Developer confirmation | Rationale and enforceable evidence | Validation evidence | Revalidate when |
 |---|---|---|---|---|---|---|
 
-Use `proposed-not-applicable` or `proposed-false-positive` only for a suspected finding. A real unresolved vulnerability remains `unresolved`; do not relabel it as an exception.
\ No newline at end of file
+Use `proposed-not-applicable` or `proposed-false-positive` only for a suspected finding. A real unresolved vulnerability remains `unresolved`; do not relabel it as an exception.
diff --git a/devspec/work-items/_template/review.md b/devspec/work-items/_template/review.md
index 27408f7..2b084a0 100644
--- a/devspec/work-items/_template/review.md
+++ b/devspec/work-items/_template/review.md
@@ -27,4 +27,4 @@ Use `remediated`, `confirmed-not-applicable`, `confirmed-false-positive`, or `un
 ## Findings
 
 | Finding | Location | Severity | Evidence | Required action |
-|---|---|---|---|---|
\ No newline at end of file
+|---|---|---|---|---|
diff --git a/devspec/work-items/_template/story.md b/devspec/work-items/_template/story.md
index 0390d86..fba7218 100644
--- a/devspec/work-items/_template/story.md
+++ b/devspec/work-items/_template/story.md
@@ -32,4 +32,4 @@ Record a concise, redacted summary of the provider title, description, acceptanc
 ## Change Requests
 
 | ID | Request | Status |
-|---|---|---|
\ No newline at end of file
+|---|---|---|
diff --git a/devspec/work-items/_template/tasks.md b/devspec/work-items/_template/tasks.md
index 5562e88..ff89c4a 100644
--- a/devspec/work-items/_template/tasks.md
+++ b/devspec/work-items/_template/tasks.md
@@ -4,4 +4,4 @@
 - Status: active | superseded
 
 | ID | Task | Scope | Depends on | Source justification and foundation or architecture trace | Decision or rule IDs | Validation | Done condition | Status |
-|---|---|---|---|---|---|---|---|---|
\ No newline at end of file
+|---|---|---|---|---|---|---|---|---|
diff --git a/docs/command-examples.md b/docs/command-examples.md
index e85522b..8f2bc5a 100644
--- a/docs/command-examples.md
+++ b/docs/command-examples.md
@@ -9,7 +9,7 @@ No `devspec.*` command treats the agent's current workspace as proof of its repo
 When evidence is absent, collect scope in this order for every command:
 
 1. Ask one free-form repository path question. The text input should say, “Which repository is in scope? Enter its local path or name.” Show examples such as `D:\Code\orders-api` and `D:\Code\orders-web`, and let the developer type another value. Do not ask about access yet.
-2. After the path is confirmed, ask: **What access requirement applies to `D:\Code\orders-api`?** Always show these choices: **Reference-only** — inspect source, configuration, and tests as evidence; do not edit or run validations. **Edit** — update approved repository files; do not run validations. **Edit-and-test (Recommended)** — make approved changes and run focused validations, including tests. **Validation-only** — run approved validations without editing. **Unavailable** — record a blocker because the repository cannot be accessed. **Custom Answer** — describe another boundary, for example edit only one approved folder. `Edit-and-test` grants normal delivery capability; the active command still controls whether source is changed.
+2. After the path is confirmed, ask: **What access requirement applies to `D:\Code\orders-api`?** Always show these choices: **Reference-only** — inspect source, configuration, and tests as evidence; do not edit or run validations. **Edit** — update approved repository files; do not run validations. **Edit-and-test (Recommended)** — make approved changes and run focused validations, including tests. **Validation-only** — run approved validations without editing. **Release-coordination** — coordinate release information without inspecting the repository. **Unavailable** — record a blocker because the repository cannot be accessed. **Custom Answer** — describe another boundary, for example edit only one approved folder. `Edit-and-test` grants normal delivery capability; the active command still controls whether source is changed.
 3. Repeat the path question and then the access question for each additional repository. Record the scaffold path, repository role, and the separate read, edit, and validation permissions before continuing.
 
 For a new project, the path answer may say `D:\Code\inventory — no source exists yet`; access is still confirmed after the path.
diff --git a/docs/how-to.md b/docs/how-to.md
index beb4601..fd00fda 100644
--- a/docs/how-to.md
+++ b/docs/how-to.md
@@ -31,8 +31,6 @@ For provider-backed story intake, pass one GitHub, Azure DevOps, Jira, GitLab, o
 
 Say `continue` or run the next work-item command without an ID. Devspec resolves private per-worktree context, reads the selected `meta.md` next action, and resumes only that action. If context is missing or multiple active stories exist, it asks you to select one; use an ID only to switch stories explicitly.
 
-
-
 ## 1. Map an existing service before changing it
 
 **Scenario.** You inherit an orders API and need to add an export, but its integrations, conventions, and security controls are not documented.
@@ -47,7 +45,7 @@ uvx devspec-lite doctor --target . --profile all
 2. Confirm source scope in order: first enter the repository path or name in the free-form prompt, then choose a named access requirement after the path is confirmed. Show all standard access choices and recommend `edit-and-test`; that grants normal delivery capability, while the active command still prevents unnecessary source changes. If a team needs a narrow exception—such as “edit but run only lint”—use **Custom Answer**. The current workspace is only a proposed target; current canonical evidence may replace these questions only when it records the same path, role, and permissions.
 3. In your agent host, run a scoped request such as `/devspec.extract Source scope confirmed: orders API at D:\Code\orders-api (primary, read/edit/validate).`
 4. It inspects only the confirmed source, tests, configuration, and documentation, then creates the evidence-backed foundation and prepares a list of applicable diagrams.
-5. At extraction closure, it shows the list and asks: **“Do you want me generate all the possible diagrams?”** Choose **Yes** to generate every listed diagram, **No** to leave the list prepared, or enter selected IDs or subjects. For example, enter `DIA-001, DIA-004` to generate only those two.
+5. At extraction closure, it shows the list and asks: **“Do you want me to generate all the possible diagrams?”** Choose **Yes** to generate every listed diagram, **No** to leave the list prepared, or enter selected IDs or subjects. For example, enter `DIA-001, DIA-004` to generate only those two.
 6. Any prepared diagram can be generated later with `/devspec.diagram <DIA-ID-or-subject>`, for example `/devspec.diagram DIA-002`. Static SVG is the default. Use `/devspec.diagram DIA-002 motion=explain` only when the confirmed sequence, flow, or state transition benefits from explanatory motion.
 7. If material evidence or source scope is unavailable, answer the recorded question through `/devspec.clarify`. Otherwise, begin the requested change with `/devspec.story Add customer export`.
 
@@ -150,7 +148,6 @@ uvx devspec-lite doctor --target . --profile all
 
 **Scenario.** Finalization is blocked because the required data-retention period is unknown.
 
-
 1. Run `/devspec.clarify` and answer the one recorded decision.
 
 **What to expect.** Clarification resumes the exact saved stage and next command. It does not add new scope or bypass a required review.
diff --git a/docs/manual-copy.md b/docs/manual-copy.md
index f192780..e5ebe56 100644
--- a/docs/manual-copy.md
+++ b/docs/manual-copy.md
@@ -27,6 +27,15 @@ Copy `devspec/` and the folder or file for the agent host into the target reposi
 
 Do not pre-copy individual foundation or work-item templates. When an agent needs a missing target artifact, the shared `work` protocol creates it from the matching `_template`; creating a work item initializes every file in `devspec/work-items/_template`, including `meta.md`.
 
+The `main` checkout also carries Devspec Lite's own project records, which the CLI never installs. After copying, reset these in the target so it starts empty:
+
+| Path | Action in the target repository |
+|---|---|
+| `devspec/architecture/artifact-queue.md` | Replace with `devspec/architecture/_template/artifact-queue.md` |
+| `devspec/architecture/overview.md` | Replace with `devspec/architecture/_template/overview.md` |
+| `devspec/quickfixes/QF-*.md` | Delete; keep `README.md` and `_template.md` |
+| `devspec/foundation/repository-state.md` | Replace as described in step 3 |
+
 ## 3. Set the target repository state
 
 After copying `devspec/`, replace `devspec/foundation/repository-state.md` with the state that matches the target repository. Do not retain the state from the `main` checkout.
@@ -51,7 +60,7 @@ Use this exact Markdown structure:
 
 ## 4. Verify and commit
 
-Verify that every path listed in `devspec/install-manifest.txt` exists, that the selected agent wrapper is present, and that `devspec/foundation/repository-state.md` has the target's intended state and start command. Compare any same-named target wrapper before replacing it, then commit the copied files with the target repository.
+Verify that every path listed in `devspec/install-manifest.txt` exists, that the selected agent wrapper is present, that `devspec/foundation/repository-state.md` has the target's intended state and start command, and that every row in step 2's reset table has been applied. Compare any same-named target wrapper before replacing it, then commit the copied files with the target repository.
 
 ## 5. Update manually
 
diff --git a/docs/upstream-command-parity.md b/docs/upstream-command-parity.md
index cfe036b..52371c4 100644
--- a/docs/upstream-command-parity.md
+++ b/docs/upstream-command-parity.md
@@ -2,10 +2,11 @@
 
 Comparison baseline: [`speclabs/devspec` commit `b93275bb4cef4645bbeef72cb8357aa7a6f8adb7`](https://github.com/speclabs/devspec/blob/b93275bb4cef4645bbeef72cb8357aa7a6f8adb7/devspec/adapters/command-registry.md).
 
-| Upstream command | Devspec Lite | Status |
+| Upstream command | Devspec Lite command | Status |
 |---|---|---|
-| extract, projectcontext, techstack, codebase-structure, coding-standards, rules | Same name | Supported |
-| story, clarify, changerequest, finalize, tasks, implement, review, diagram | Same name | Supported |
+| extract, projectcontext, techstack, codebase-structure, coding-standards, rules | `devspec.extract`, `devspec.projectcontext`, `devspec.techstack`, `devspec.codebase-structure`, `devspec.coding-standards`, `devspec.rules` | Same name, supported |
+| story, clarify, changerequest, finalize, tasks, implement, review, diagram | `devspec.story`, `devspec.clarify`, `devspec.changerequest`, `devspec.finalize`, `devspec.tasks`, `devspec.implement`, `devspec.review`, `devspec.diagram` | Same name, supported |
+| none | `devspec.grooming`, `devspec.quickfix` | Lite only |
 
 Lite additionally provides `devspec.grooming` and `devspec.quickfix`. Existing-system extraction remains deliberately comprehensive and routes directly to `devspec.story`; it does not repeat the upstream's five foundation commands.
 
diff --git a/docs/workflows.md b/docs/workflows.md
index c8f2ade..e6fdbec 100644
--- a/docs/workflows.md
+++ b/docs/workflows.md
@@ -9,7 +9,7 @@ Use the smallest route that preserves a durable, reviewable record. Git-tracked
 - New repository: start with `devspec.projectcontext`.
 - Before every command, confirm the single-repository or multi-repository scope, including the scaffold location and each source repository's role, path, and permissions, unless current canonical evidence records it. The current workspace alone is not proof of scope.
 - Existing repository: run `devspec.extract` once with confirmed scope. It completes the evidence-backed technical, workflow, and rule baseline, prepares the applicable diagram list, and asks whether to generate all, selected, or no diagrams. A prepared item can later be generated with `/devspec.diagram DIA-###`; do not rerun individual foundation commands afterward.
-- New repository: run `projectcontext`, `techstack`, `codebase-structure`, `coding-standards`, and `rules` in order as input-driven authoring commands. `diagram` is not part of the chain; call it separately and it returns to its caller.
+- New repository: run `devspec.projectcontext`, `devspec.techstack`, `devspec.codebase-structure`, `devspec.coding-standards`, and `devspec.rules` in order as input-driven authoring commands. `devspec.diagram` is not part of the chain; call it separately and it returns to its caller.
 
 ## 2. Deliver a change
 
@@ -19,7 +19,6 @@ Use `devspec.quickfix` only when the request is one localized enhancement or bug
 
 Use the work-item route for public contracts, data migrations, authentication/security work, breaking changes, unresolved risk, or multiple concerns. Grooming is optional; use it when the story has material ambiguity, risk, or incomplete acceptance criteria. `clarify` asks one interactive material blocker question, records the decision, and resumes the originating stage.
 
-
 Every command validates its declared entry state and records one explicit transition in the canonical artifact. Work items use a monotonic `scope_revision`; a related change request increments it, retains older finalization, task, implementation, and review evidence as superseded history, and requires a new finalization. Review accepts only a matching revision and changed-work baseline; accepted work is terminal, rework returns affected tasks to implementation, and blocked work routes through `clarify`.
 After `devspec.story` selects a work item, continue with `devspec.grooming`, `devspec.finalize`, `devspec.tasks`, `devspec.implement`, `devspec.review`, `devspec.clarify`, or `devspec.changerequest` without an ID. The private per-worktree selection resolves the current story only when it matches the branch and `meta.md`; `continue` dispatches only its recorded `next` action. Provide an ID to switch stories. If several active stories are eligible, Devspec asks you to choose rather than inferring.
 A material decision is work-item-local unless it applies beyond that story. At finalization, promote a reusable business or validation decision to `foundation/workflow-rules.md` with a stable rule ID; promote a reusable engineering constraint to `foundation/rules.md`. New stories read only relevant foundation rules and the affected code area, not every historic decision file. Code and tests are the primary enforcement; add a developer comment only for non-obvious rationale and cite the canonical rule ID.
@@ -38,16 +37,15 @@ Assign a stable `DIA-###` ID, keep status in the queue, and add only completed d
 
 Diagram output defaults to static SVG with `motion=none`. Use `/devspec.diagram DIA-### motion=explain` when a confirmed sequence, flow, or state transition benefits from motion. The queue records `svg; motion=explain`; the animation must be finite, preserve a complete static final frame, and expose the same information when reduced motion is enabled. Request HTML separately when its presentation shell is needed.
 
-
 `init` is idempotent for unchanged managed files. It will not overwrite a changed contract or wrapper. For CLI-managed repositories, use `diff`, then `sync --dry-run`, followed by `sync` and `doctor` after an upgrade or profile addition. Manual-copy updates follow the [manual-copy guide](manual-copy.md). `sync` never deletes retained obsolete files.
 
 ## Examples
 
 | Situation | Route |
 |---|---|
-| New service repository | `projectcontext → techstack → codebase-structure → coding-standards → rules` |
-| Existing service with unknown conventions | `extract` — complete baseline extraction |
-| Correct a known empty-state label | `quickfix` with `UI` scope |
-| Add a customer-export API and authorization | `story → grooming → finalize → tasks → implement → review` |
-| A requirement is blocked by a data-retention decision | `clarify`, then resume the saved stage |
-| Add a related requirement after finalization | `changerequest → finalize → tasks → implement → review` |
+| New service repository | `devspec.projectcontext → devspec.techstack → devspec.codebase-structure → devspec.coding-standards → devspec.rules` |
+| Existing service with unknown conventions | `devspec.extract` — complete baseline extraction |
+| Correct a known empty-state label | `devspec.quickfix` with `UI` scope |
+| Add a customer-export API and authorization | `devspec.story → devspec.grooming → devspec.finalize → devspec.tasks → devspec.implement → devspec.review` |
+| A requirement is blocked by a data-retention decision | `devspec.clarify`, then resume the saved stage |
+| Add a related requirement after finalization | `devspec.changerequest → devspec.finalize → devspec.tasks → devspec.implement → devspec.review` |
diff --git a/src/devspec_lite/framework.py b/src/devspec_lite/framework.py
index 178a7e0..7d8fe0b 100644
--- a/src/devspec_lite/framework.py
+++ b/src/devspec_lite/framework.py
@@ -10,7 +10,7 @@
 from xml.etree import ElementTree
 
 from . import __version__
-from .definitions import COMMANDS, PROTOCOLS, canonical_root, install_files, lifecycle_commands
+from .definitions import COMMANDS, PROTOCOLS, canonical_root, install_files, lifecycle_commands, workflow_block
 
 PROFILES = ("all", "copilot", "codex", "claude", "cursor", "gemini", "antigravity")
 ADAPTERS = PROFILES[1:]
@@ -53,10 +53,8 @@ def wrapper_text(adapter: str, command) -> tuple[str, str]:
     raise ValueError(adapter)
 
 
-def xml_block(text: str) -> str:
-    start = text.index("<workflow")
-    end = text.index("</workflow>") + len("</workflow>")
-    return text[start:end]
+# Re-exported so existing callers keep importing it from here.
+xml_block = workflow_block
 
 
 def expected_paths(profile: str) -> list[Path]:
@@ -65,10 +63,15 @@ def expected_paths(profile: str) -> list[Path]:
 
 
 def doctor(root: Path, profile: str) -> list[str]:
-    issues = [f"missing: {path}" for path in expected_paths(profile) if not (root / path).is_file()]
-    if (root / "devspec/work-items/current.md").exists():
-        issues.append("tracked current-story artifact is not allowed: devspec/work-items/current.md")
-    valid_stages = {"foundation", "intake", "grooming", "finalization", "tasks", "implementation", "review", "complete", "triage", "routed", "caller", "origin"}
+    try:
+        expected = expected_paths(profile)
+    except OSError as exc:
+        return [f"cannot read the canonical framework: {exc}"]
+    issues = [f"missing: {path}" for path in expected if not (root / path).is_file()]
+    for forbidden in ("devspec/work-items/current.md", "devspec/current-work-item.json"):
+        if (root / forbidden).exists():
+            issues.append(f"tracked current-work-item artifact is not allowed: {forbidden}")
+    valid_stages = {"foundation", "intake", "grooming", "finalization", "tasks", "implementation", "review", "complete", "triage", "validation", "routed", "caller", "origin"}
     valid_runs = {"active", "paused", "blocked", "stopped", "complete"}
     valid_next = {f"devspec.{command.name}" for command in COMMANDS} | {"none", "return-to-caller", "resume-origin"}
     lifecycle_templates = {
@@ -80,12 +83,13 @@ def doctor(root: Path, profile: str) -> list[str]:
         "run": {"preflight": ("Before every command", "single-repository or multi-repository scope", "current workspace as proposed", "repo-access protocol", "Do not inspect or change source")},
         "repo-access": {
             "collect": ("free-form text input", "Confirm the path before asking about access"),
-            "validate": ("After each path is confirmed", "Custom Answer", "least-privilege"),
+            "question": ("After each path is confirmed", "Custom Answer"),
+            "recommend": ("exactly one choice recommended", "least-privilege"),
         },
         "current-work-item": {
             "location": ("git rev-parse --git-path devspec/current-work-item.json", "Never create or commit"),
             "record": ("work-item ID", "current branch", "selection source", "timestamp", "never committed or pushed"),
-            "selection": ("validated explicit ID", "exactly one eligible non-terminal"),
+            "selection": ("validated explicit ID", "exactly one non-terminal work item on the current branch"),
             "validation": ("branch changed", "stage and next action"),
             "continuation": ("saved meta.md next action", "devspec.clarify", "terminal item is not resumed"),
             "clear": ("accepted review",),
@@ -95,23 +99,22 @@ def doctor(root: Path, profile: str) -> list[str]:
         path = root / f"devspec/protocols/{name}.xml"
         if path.is_file():
             try:
-                ElementTree.fromstring(path.read_text(encoding="utf-8"))
-            except ElementTree.ParseError as exc:
+                protocol = ElementTree.fromstring(path.read_text(encoding="utf-8"))
+            except (ElementTree.ParseError, OSError, UnicodeDecodeError) as exc:
                 issues.append(f"invalid XML: {path}: {exc}")
             else:
                 required = {
                     "ask": ("trigger", "checkpoint", "interaction", "resolution"),
                     "run": ("preflight", "checkpoint", "context", "resume", "blocked", "closure"),
                     "work": ("scope", "evidence", "change", "artifacts"),
-                    "repo-access": ("when", "validate", "respect"),
+                    "repo-access": ("when", "collect", "question", "recommend", "record", "respect"),
                     "current-work-item": ("when", "location", "record", "selection", "validation", "recovery", "continuation", "update", "clear"),
                     "state": ("when", "run-states", "stages", "task-statuses", "evidence-labels", "resume"),
                 }.get(name, ())
-                present = {child.tag for child in ElementTree.fromstring(path.read_text(encoding="utf-8"))}
+                present = {child.tag for child in protocol}
                 missing = sorted(set(required) - present)
                 if missing:
                     issues.append(f"missing protocol tags: {path}: {', '.join(missing)}")
-                protocol = ElementTree.fromstring(path.read_text(encoding="utf-8"))
                 for tag, phrases in protocol_text_requirements.get(name, {}).items():
                     value = protocol.findtext(tag, default="")
                     for phrase in phrases:
@@ -120,8 +123,8 @@ def doctor(root: Path, profile: str) -> list[str]:
     for command in COMMANDS:
         path = root / f"devspec/contracts/devspec.{command.name}.md"
         if path.is_file():
-            text = path.read_text(encoding="utf-8")
             try:
+                text = path.read_text(encoding="utf-8")
                 workflow = ElementTree.fromstring(xml_block(text))
                 if workflow.tag != "workflow" or workflow.attrib.get("command") != f"devspec.{command.name}":
                     issues.append(f"invalid contract identity: {path}")
@@ -136,9 +139,7 @@ def doctor(root: Path, profile: str) -> list[str]:
                     issues.append(f"missing current-story protocol: {path}")
                 if command.name != "story" and command.name in current_context_commands and "[work-item-id]" not in text:
                     issues.append(f"work-item ID is not optional: {path}")
-                if command.name == "story" and "current-work-item" not in protocol_refs:
-                    issues.append(f"missing current-story classification protocol: {path}")
-            except (ValueError, ElementTree.ParseError) as exc:
+            except (ValueError, ElementTree.ParseError, OSError, UnicodeDecodeError) as exc:
                 issues.append(f"invalid contract XML: {path}: {exc}")
                 continue
             outputs = workflow.find("outputs")
@@ -147,7 +148,7 @@ def doctor(root: Path, profile: str) -> list[str]:
             transitions = workflow.find("transitions")
             if transitions is None or not list(transitions):
                 issues.append(f"missing contract transitions: {path}")
-            elif transitions is not None:
+            else:
                 for transition in transitions:
                     stage = transition.attrib.get("stage")
                     run = transition.attrib.get("run")
diff --git a/tests/test_contract_consistency.py b/tests/test_contract_consistency.py
index d7ecd50..ba5c553 100644
--- a/tests/test_contract_consistency.py
+++ b/tests/test_contract_consistency.py
@@ -52,14 +52,19 @@ def table_rows(text: str, header_starts: str) -> list[list[str]]:
 
 class RepositoryIsCurrentTests(unittest.TestCase):
     def test_checked_in_wrappers_match_the_contracts(self) -> None:
-        drift = []
+        drift, checked = [], 0
         for item in managed_payload("all", "existing"):
             if item.ownership != FRAMEWORK_OWNED:
                 continue
             target = REPO / item.path
-            if target.is_file() and target.read_text(encoding="utf-8") != item.content:
+            if not target.is_file():
+                drift.append(f"{item.path.as_posix()} (missing)")
+            elif target.read_text(encoding="utf-8") != item.content:
                 drift.append(item.path.as_posix())
+            else:
+                checked += 1
         self.assertEqual([], drift, "run the installer to regenerate these from devspec/contracts")
+        self.assertGreater(checked, len(COMMANDS), "expected at least one wrapper per command")
 
     def test_doctor_passes_against_this_repository(self) -> None:
         self.assertEqual([], doctor(REPO, "all"))
@@ -85,11 +90,13 @@ def test_every_command_has_a_lifecycle_position(self) -> None:
     def test_heading_summary_matches_purpose(self) -> None:
         for command in COMMANDS:
             with self.subTest(command.name):
-                summary = contract_text(command.name).split("\n")[2].strip()
+                body = contract_text(command.name)
+                summary = body[body.index("\n\n") + 2:body.index("\n\nInvocation:")].strip()
                 self.assertEqual(command.purpose, summary)
 
     def test_derivable_elements_are_not_restated(self) -> None:
-        # <artifact> restated <outputs>, <handoff> restated <transitions>, <actions> restated <rules>.
+        # A workflow-level <artifact> restated <outputs>, <handoff> restated <transitions>, and
+        # <actions> restated <rules>. The <artifact> child inside <outputs> is unaffected.
         for command in COMMANDS:
             with self.subTest(command.name):
                 present = {child.tag for child in workflow(command.name)}
@@ -103,7 +110,9 @@ def test_every_contract_scopes_itself(self) -> None:
 
     def test_protocol_refs_resolve(self) -> None:
         for command in COMMANDS:
-            for ref in workflow(command.name).find("protocols"):
+            refs = list(workflow(command.name).find("protocols"))
+            self.assertTrue(refs, f"{command.name} loads no protocol")
+            for ref in refs:
                 with self.subTest(command=command.name, ref=ref.attrib.get("ref")):
                     self.assertIn(ref.attrib.get("ref"), PROTOCOLS)
 
@@ -146,6 +155,25 @@ def test_work_item_stages_match_the_lifecycle_table(self) -> None:
                     with self.subTest(command=command.name, stage=stage):
                         self.assertIn(nxt, documented[stage], f"lifecycle.md does not allow {stage} -> {nxt}")
 
+    def test_a_command_declares_the_records_it_writes(self) -> None:
+        # ask.xml routes a blocker to a decision record; run.xml checkpoints the state record.
+        for command in COMMANDS:
+            outputs = [a.attrib["path"] for a in workflow(command.name).find("outputs")]
+            stages = {t["stage"] for t in self.transitions(command.name)}
+            runs = {t["run"] for t in self.transitions(command.name)}
+            work_item = any(p.startswith("devspec/work-items/") for p in outputs)
+            with self.subTest(command.name):
+                if "blocked" in runs:
+                    self.assertTrue(
+                        any("decisions.md" in p for p in outputs) or any("QF-###" in p for p in outputs),
+                        f"{command.name} can block but declares no decision record",
+                    )
+                if work_item and stages - {"caller", "origin"}:
+                    self.assertTrue(
+                        any(p.endswith("meta.md") for p in outputs),
+                        f"{command.name} moves a work item but declares no meta.md",
+                    )
+
     def test_registry_restates_the_contracts_exactly(self) -> None:
         text = (REPO / "devspec/command-registry.md").read_text(encoding="utf-8")
         rows = table_rows(text, "Command")
@@ -169,22 +197,26 @@ def test_every_command_appears_in_the_command_guides(self) -> None:
             text = (REPO / "docs" / doc).read_text(encoding="utf-8")
             for command in COMMANDS:
                 with self.subTest(doc=doc, command=command.name):
-                    self.assertIn(command.name, text)
+                    self.assertIn(f"devspec.{command.name}", text)
 
 
 class ArtifactShapeTests(unittest.TestCase):
     def test_markdown_tables_are_well_formed(self) -> None:
         separator = re.compile(r"\|(\s*:?-+:?\s*\|)+$")
-        broken = []
-        for path in sorted((REPO / "devspec").rglob("*.md")):
+        broken, seen = [], 0
+        roots = sorted((REPO / "devspec").rglob("*.md")) + sorted((REPO / "docs").rglob("*.md"))
+        roots += [REPO / "README.md", REPO / "AGENTS.md"]
+        for path in roots:
             lines = path.read_text(encoding="utf-8").split("\n")
             for index, line in enumerate(lines[:-1]):
                 nxt = lines[index + 1].strip()
                 if line.strip().startswith("|") and separator.fullmatch(nxt):
+                    seen += 1
                     header = line.strip().strip("|").split("|")
                     if len(header) != len(nxt.strip("|").split("|")):
                         broken.append(f"{path.relative_to(REPO).as_posix()}:{index + 1}")
         self.assertEqual([], broken)
+        self.assertGreater(seen, 30, "table scan found almost nothing; the walk is probably wrong")
 
     # Each entry is a field some contract or protocol names, and the template that must offer it.
     REQUIRED_FIELDS = {
@@ -211,7 +243,9 @@ def test_contract_outputs_have_a_template(self) -> None:
         template_map = (REPO / "devspec/foundation/template-map.md").read_text(encoding="utf-8")
         work_item_templates = {p.name for p in (REPO / "devspec/work-items/_template").glob("*.md")}
         for command in COMMANDS:
-            for artifact in workflow(command.name).find("outputs"):
+            artifacts = list(workflow(command.name).find("outputs"))
+            self.assertTrue(artifacts, f"{command.name} declares no output")
+            for artifact in artifacts:
                 path = artifact.attrib["path"]
                 with self.subTest(command=command.name, path=path):
                     name = path.rsplit("/", 1)[-1]
diff --git a/tests/test_framework.py b/tests/test_framework.py
index 4ad09fb..c939378 100644
--- a/tests/test_framework.py
+++ b/tests/test_framework.py
@@ -67,7 +67,7 @@ def test_ask_protocol_requires_interactive_choices(self) -> None:
             run = ElementTree.fromstring((target / "devspec/protocols/run.xml").read_text(encoding="utf-8"))
             self.assertEqual("devspec/foundation/decisions.md", run.findtext("state-records/foundation"))
             repo_access = ElementTree.fromstring((target / "devspec/protocols/repo-access.xml").read_text(encoding="utf-8"))
-            self.assertIn("Validate a validation-only repository only", repo_access.findtext("respect"))
+            self.assertIn("Never validate a reference-only, edit, release-coordination, or unavailable repository", repo_access.findtext("respect"))
             self.assertTrue((target / "devspec/foundation/template-map.md").is_file())
             self.assertTrue((target / "devspec/foundation/_template/decisions.md").is_file())
             self.assertTrue((target / "AGENTS.md").is_file())
@@ -128,7 +128,7 @@ def test_security_foundation_and_confirmed_exception_path_are_installed(self) ->
             self.assertIn("known unresolved vulnerability", security_protocol)
             for contract in (rules_contract, extract_contract, finalize_contract, implement_contract, review_contract):
                 self.assertIn('<protocol ref="security" />', contract)
-            self.assertIn("do not infer an internal-only", extract_contract)
+            self.assertIn("internal-only", security_protocol)
             self.assertIn("foundation trace", finalize_contract)
     def test_contract_xml_and_quickfix_routing_are_present(self) -> None:
         with tempfile.TemporaryDirectory() as raw:
@@ -172,7 +172,7 @@ def test_extract_prepares_diagrams_and_requests_generation_confirmation(self) ->
             extract = (target / "devspec/contracts/devspec.extract.md").read_text(encoding="utf-8")
             diagram = (target / "devspec/contracts/devspec.diagram.md").read_text(encoding="utf-8")
             how_to = (Path(__file__).resolve().parents[1] / "docs/how-to.md").read_text(encoding="utf-8")
-            self.assertIn("Do you want me generate all the possible diagrams?", extract)
+            self.assertIn("Do you want me to generate all the possible diagrams?", extract)
             self.assertIn("Yes — generate all listed diagrams", extract)
             self.assertIn("No — prepare the list only", extract)
             self.assertIn("Choose diagrams — enter the IDs or subjects to generate", extract)
@@ -396,11 +396,14 @@ def test_current_work_item_protocol_and_optional_ids_are_installed(self) -> None
             self.assertIn("Continue current work without an ID", how_to)
             self.assertIn("selected `meta.md` next action", how_to)
             self.assertIn("post-finalization route", how_to)
-            tracked_context = target / "devspec/work-items/current.md"
-            tracked_context.parent.mkdir(parents=True, exist_ok=True)
-            tracked_context.write_text("current: STORY-001\n", encoding="utf-8")
-            issues = doctor(target, "all")
-            self.assertTrue(any("tracked current-story artifact" in issue for issue in issues))
+            # Both the legacy path and the path a real violation takes today.
+            for forbidden in ("devspec/work-items/current.md", "devspec/current-work-item.json"):
+                tracked_context = target / forbidden
+                tracked_context.parent.mkdir(parents=True, exist_ok=True)
+                tracked_context.write_text("current: STORY-001\n", encoding="utf-8")
+                issues = doctor(target, "all")
+                self.assertTrue(any(f"tracked current-work-item artifact is not allowed: {forbidden}" in issue for issue in issues))
+                tracked_context.unlink()
 
 if __name__ == "__main__":
     unittest.main()

From 2ad5778a928493b842c28ea2d7666825d06f20e6 Mon Sep 17 00:00:00 2001
From: Vikram Reddy <gvreddy04@gmail.com>
Date: Sat, 5 Sep 2026 16:47:30 +0530
Subject: [PATCH 4/7] feat: Add tests for installed contracts to verify
 constitution and command parity

---
 docs/upstream-command-parity.md                     | 13 -------------
 ...ity_contracts.py => test_installed_contracts.py} |  0
 2 files changed, 13 deletions(-)
 delete mode 100644 docs/upstream-command-parity.md
 rename tests/{test_parity_contracts.py => test_installed_contracts.py} (100%)

diff --git a/docs/upstream-command-parity.md b/docs/upstream-command-parity.md
deleted file mode 100644
index 52371c4..0000000
--- a/docs/upstream-command-parity.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# Upstream Command Parity
-
-Comparison baseline: [`speclabs/devspec` commit `b93275bb4cef4645bbeef72cb8357aa7a6f8adb7`](https://github.com/speclabs/devspec/blob/b93275bb4cef4645bbeef72cb8357aa7a6f8adb7/devspec/adapters/command-registry.md).
-
-| Upstream command | Devspec Lite command | Status |
-|---|---|---|
-| extract, projectcontext, techstack, codebase-structure, coding-standards, rules | `devspec.extract`, `devspec.projectcontext`, `devspec.techstack`, `devspec.codebase-structure`, `devspec.coding-standards`, `devspec.rules` | Same name, supported |
-| story, clarify, changerequest, finalize, tasks, implement, review, diagram | `devspec.story`, `devspec.clarify`, `devspec.changerequest`, `devspec.finalize`, `devspec.tasks`, `devspec.implement`, `devspec.review`, `devspec.diagram` | Same name, supported |
-| none | `devspec.grooming`, `devspec.quickfix` | Lite only |
-
-Lite additionally provides `devspec.grooming` and `devspec.quickfix`. Existing-system extraction remains deliberately comprehensive and routes directly to `devspec.story`; it does not repeat the upstream's five foundation commands.
-
-This release adds constitution candidates and explicit promotion, work-item clarification ledgers, finalization architecture traces, explicit process-flow batch diagrams, and the `diff`/`sync` installer lifecycle. `sync` never deletes retained obsolete files.
diff --git a/tests/test_parity_contracts.py b/tests/test_installed_contracts.py
similarity index 100%
rename from tests/test_parity_contracts.py
rename to tests/test_installed_contracts.py

From 2b51e9d50ff48c2575540ad20a96bfb49d3bffd9 Mon Sep 17 00:00:00 2001
From: Vikram Reddy <gvreddy04@gmail.com>
Date: Sat, 5 Sep 2026 16:47:46 +0530
Subject: [PATCH 5/7] refactor: Rename ParityContractTests to
 InstalledContractTests for clarity

---
 tests/test_contract_consistency.py | 2 +-
 tests/test_installed_contracts.py  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/test_contract_consistency.py b/tests/test_contract_consistency.py
index ba5c553..6181b28 100644
--- a/tests/test_contract_consistency.py
+++ b/tests/test_contract_consistency.py
@@ -190,7 +190,7 @@ def test_registry_restates_the_contracts_exactly(self) -> None:
 
 class DocumentationTests(unittest.TestCase):
     # A command a guide never names is a command a reader never finds.
-    COVERING_DOCS = ("how-to.md", "command-examples.md", "quickstart.md", "workflows.md", "upstream-command-parity.md")
+    COVERING_DOCS = ("how-to.md", "command-examples.md", "quickstart.md", "workflows.md")
 
     def test_every_command_appears_in_the_command_guides(self) -> None:
         for doc in self.COVERING_DOCS:
diff --git a/tests/test_installed_contracts.py b/tests/test_installed_contracts.py
index 5eb09f7..8659598 100644
--- a/tests/test_installed_contracts.py
+++ b/tests/test_installed_contracts.py
@@ -7,7 +7,7 @@
 from devspec_lite.framework import doctor, install_framework
 
 
-class ParityContractTests(unittest.TestCase):
+class InstalledContractTests(unittest.TestCase):
     def test_constitution_clarification_architecture_and_batch_contracts_are_installed(self) -> None:
         with tempfile.TemporaryDirectory() as raw:
             target = Path(raw)

From 8bba135ca6f91a33d21e2041c088d4dcc7f94060 Mon Sep 17 00:00:00 2001
From: Vikram Reddy <gvreddy04@gmail.com>
Date: Sat, 5 Sep 2026 17:07:35 +0530
Subject: [PATCH 6/7] Enhance documentation and workflow clarity

- Updated architecture overview to clarify diagram generation and constraints.
- Revised install manifest to specify glob patterns for artifacts.
- Clarified lifecycle routing for work-item stages and material blockers.
- Improved SVG diagrams for foundation routes and manual copy flow.
- Enhanced command examples to specify access requirements and permissions.
- Updated how-to guide to reflect changes in repository state handling.
- Revised manual copy instructions to specify paths and avoid copying unnecessary files.
- Clarified quickstart instructions regarding repository scope confirmation.
- Improved setup documentation for Homebrew, Python, and WinGet.
- Enhanced workflows documentation to emphasize repository scope confirmation.
- Updated framework logic to prevent overwriting project-owned files during initialization.
- Added tests to ensure project work is preserved when adding profiles.
---
 README.md                                     |  4 ++-
 devspec/README.md                             |  2 +-
 .../architecture/_template/diagram-sample.md  |  4 ++-
 devspec/architecture/overview.md              |  1 +
 devspec/install-manifest.txt                  |  5 +++-
 devspec/lifecycle.md                          |  4 +--
 docs/assets/foundation-routes.svg             |  2 +-
 docs/assets/manual-copy-flow.svg              | 19 +++++++-------
 docs/command-examples.md                      |  4 +--
 docs/how-to.md                                | 20 +++++++--------
 docs/manual-copy.md                           |  6 ++---
 docs/quickstart.md                            |  4 ++-
 docs/setup-homebrew.md                        |  4 +--
 docs/setup-lifecycle.md                       |  2 +-
 docs/setup-python.md                          |  4 ++-
 docs/setup-winget.md                          |  2 +-
 docs/workflows.md                             |  2 +-
 src/devspec_lite/framework.py                 |  8 +++---
 tests/test_upgrade.py                         | 25 ++++++++++++++++++-
 19 files changed, 79 insertions(+), 43 deletions(-)

diff --git a/README.md b/README.md
index dce5475..d979fbd 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,8 @@ Manual copying and CLI installation produce the same canonical `devspec/` conten
 
 ## CLI quick start
 
+The [CLI quick start](docs/quickstart.md) walks through initializing, validating, and choosing the first command.
+
 After choosing a CLI route, initialize and validate the repository:
 
 ```powershell
@@ -28,7 +30,7 @@ uvx devspec-lite init --target . --profile all --repo-state new
 uvx devspec-lite doctor --target . --profile all
 ```
 
-`init` copies canonical Markdown + XML contracts, concise templates, and the wrappers for the selected agent profile. Use the `devspec.*` commands exposed by your agent host. Use `devspec-lite diff --target .` to inspect installed-framework drift and `devspec-lite sync --target . --profile all --dry-run` before applying a framework upgrade.
+`init` copies canonical Markdown + XML contracts, concise templates, and the wrappers for the selected agent profile. It generates `devspec/foundation/repository-state.md` from `--repo-state` and seeds empty `devspec/architecture/overview.md` and `artifact-queue.md` from their templates. Those two, plus `devspec/constitution.md`, are project-owned: `init` and `sync` never overwrite them, even with `--force`. Use the `devspec.*` commands exposed by your agent host. Use `devspec-lite diff --target .` to inspect installed-framework drift and `devspec-lite sync --target . --profile all --dry-run` before applying a framework upgrade.
 
 ## Choose a workflow route
 
diff --git a/devspec/README.md b/devspec/README.md
index af929fd..164485f 100644
--- a/devspec/README.md
+++ b/devspec/README.md
@@ -1,6 +1,6 @@
 # Devspec Lite
 
-New repository foundation: `projectcontext → techstack → codebase-structure → coding-standards → rules`. Existing repository baseline: `extract` completes the foundation, prepares the applicable diagram list, and asks whether to generate all or selected diagrams. Rare durable cross-work-item principles live in `constitution.md`; `projectcontext` promotes or retires them only on explicit input.
+New repository foundation: `projectcontext → techstack → codebase-structure → coding-standards → rules`. Existing repository baseline: `extract` completes the foundation, prepares the applicable diagram list, and asks whether to generate all or selected diagrams. Rare durable cross-work-item principles live in `constitution.md` with stable `CP-###` IDs. `extract` records candidates from evidence; `projectcontext` promotes or retires them only on explicit input.
 
 Work item: `story → grooming` when needed `→ finalize → tasks → implement → review`. Story intake accepts one manual request or, when an authenticated MCP connector is available, one read-only provider work-item reference.
 After `story` selects a work item, use the normal work-item commands without repeating its ID. Per-worktree private context resolves the selected story and its recorded `next` action; use an ID only to switch or disambiguate stories.
diff --git a/devspec/architecture/_template/diagram-sample.md b/devspec/architecture/_template/diagram-sample.md
index 06b4651..0b4803b 100644
--- a/devspec/architecture/_template/diagram-sample.md
+++ b/devspec/architecture/_template/diagram-sample.md
@@ -1,6 +1,8 @@
 # Diagram Sample
 
-Use this compact worked example as a pattern. Replace every value with repository evidence; queue state belongs only in artifact-queue.md.
+Use this compact worked example as a pattern for the record. Replace every value with repository evidence; queue state belongs only in artifact-queue.md.
+
+The accompanying `diagram-sample.svg` is deliberately small so the pattern stays readable. A real diagram starts from the matching family template in this directory and keeps its 1600 by 900 canvas, as `diagram-types.md` requires.
 
 ## Brief
 
diff --git a/devspec/architecture/overview.md b/devspec/architecture/overview.md
index 19204ec..3b867a0 100644
--- a/devspec/architecture/overview.md
+++ b/devspec/architecture/overview.md
@@ -4,6 +4,7 @@
 - Scope: developer workflow and setup guidance, not product runtime architecture.
 - Sources: command contracts, protocols, CLI behavior, and setup documentation.
 - Constraint: diagrams show confirmed routes only; they do not infer application dependencies.
+- Deviation: these four are wide documentation banners sized to the guides that embed them, not the 1600 by 900 canvas `_template/diagram-types.md` requires for a family template. They keep the dark grammar, titles, descriptions, and evidence rules. A diagram generated by `devspec.diagram` uses the family template and its canvas.
 
 ## Diagram index
 
diff --git a/devspec/install-manifest.txt b/devspec/install-manifest.txt
index 4161965..1e3c40b 100644
--- a/devspec/install-manifest.txt
+++ b/devspec/install-manifest.txt
@@ -1,4 +1,7 @@
-# Canonical Devspec Lite artifacts installed by automated and manual setup.
+# Glob patterns for the canonical artifacts copied by automated and manual setup.
+# Not the full install list: repository-state.md is generated from the chosen repository
+# state, and architecture/overview.md and architecture/artifact-queue.md are seeded from
+# architecture/_template/ so a target repository starts with empty records.
 README.md
 constitution.md
 command-registry.md
diff --git a/devspec/lifecycle.md b/devspec/lifecycle.md
index 9eef2c4..e4ffdea 100644
--- a/devspec/lifecycle.md
+++ b/devspec/lifecycle.md
@@ -21,7 +21,7 @@ Canonical contracts in `devspec/contracts/` own command behavior. This document
 | `review` | `devspec.review` or `devspec.clarify` |
 | `complete` | terminal (`next: none`) |
 
-Every non-terminal stage may route to `devspec.clarify`, and only to `devspec.clarify`, when it records a material blocker. `devspec/protocols/revision.xml` owns which revision each stage may read and write.
+A work-item stage that records a material blocker routes to `devspec.clarify` and nowhere else. The foundation, caller, and quickfix triage stages do the same; the quickfix `routed` stage is non-terminal and routes only to `devspec.story`. `devspec/protocols/revision.xml` owns which revision each stage may read and write.
 
 ## Route graph
 
@@ -29,4 +29,4 @@ Every non-terminal stage may route to `devspec.clarify`, and only to `devspec.cl
 - New repository: `devspec.projectcontext → devspec.techstack → devspec.codebase-structure → devspec.coding-standards → devspec.rules → devspec.story`. A targeted foundation update returns to its caller after completing its declared artifact.
 - Work item: `devspec.story → devspec.grooming|devspec.finalize → devspec.tasks → devspec.implement → devspec.review`. Review results are `accepted → complete`, `rework-required → devspec.implement`, or `blocked → devspec.clarify`.
 - Work-item IDs are optional selectors for switching or resolving ambiguity. Without one, the current-work-item protocol resolves which work item a command acts on.
-- `devspec.clarify` resolves one decision and resumes its saved originating command. `devspec.changerequest` is allowed only after finalization and always returns to `devspec.finalize` with a new revision. `devspec.quickfix` ends complete, blocks to `devspec.clarify`, or routes to `devspec.story`. `devspec.diagram` returns to its caller.
+- `devspec.clarify` resolves one decision and resumes its saved originating command. `devspec.changerequest` is allowed only after finalization and always returns to `devspec.finalize` with a new revision. `devspec.quickfix` ends complete, blocks to `devspec.clarify`, or routes to `devspec.story`. `devspec.diagram` returns to its caller, or blocks to `devspec.clarify`.
diff --git a/docs/assets/foundation-routes.svg b/docs/assets/foundation-routes.svg
index c7e4d4f..4db8b4d 100644
--- a/docs/assets/foundation-routes.svg
+++ b/docs/assets/foundation-routes.svg
@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1440 520" role="img" aria-labelledby="title desc"><title id="title">Foundation routes for new and existing repositories</title><desc id="desc">New repositories begin with project context. Existing repositories use Extract to create the complete evidence-backed baseline.</desc><style>.bg{fill:#070b18}.surface{fill:#101827;stroke:#24324b}.lane{fill:#0c1323;stroke:#263653;stroke-dasharray:6 7}.eyebrow{font:700 12px system-ui,sans-serif;letter-spacing:2px;fill:#69d8ff}.title{font:700 30px system-ui,sans-serif;fill:#f8fafc}.sub{font:15px system-ui,sans-serif;fill:#aab8cf}.laneLabel{font:700 11px system-ui,sans-serif;letter-spacing:1.5px;fill:#7f91b1}.card{fill:#16223a;stroke:#35517c;stroke-width:1.5}.start{fill:#123745;stroke:#39c9d9}.extract{fill:#252044;stroke:#9c8cff}.nodeTitle{font:700 15px system-ui,sans-serif;fill:#f8fafc}.nodeMeta{font:12px system-ui,sans-serif;fill:#aab8cf}.flow{fill:none;stroke:#69d8ff;stroke-width:2.5;marker-end:url(#arrow)}.flowMuted{fill:none;stroke:#9c8cff;stroke-width:2.5;marker-end:url(#arrowV)}.foot{font:600 11px system-ui,sans-serif;letter-spacing:1px;fill:#6f86a8}</style><defs><pattern id="grid" width="32" height="32" patternUnits="userSpaceOnUse"><path d="M32 0H0V32" fill="none" stroke="#14213a" stroke-width="1"/></pattern><marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#69d8ff"/></marker><marker id="arrowV" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#9c8cff"/></marker></defs><rect class="bg" width="1440" height="520"/><rect fill="url(#grid)" width="1440" height="520" opacity=".9"/><rect class="surface" x="28" y="28" width="1384" height="464" rx="20"/><text x="64" y="67" class="eyebrow">DEVSPEC LITE / FOUNDATION</text><text x="64" y="103" class="title">Choose the correct repository route</text><text x="64" y="131" class="sub">New projects are documented intentionally. Existing systems are documented end-to-end from observed evidence.</text><rect class="lane" x="64" y="154" width="1312" height="126" rx="14"/><text x="88" y="181" class="laneLabel">NEW REPOSITORY</text><rect class="lane" x="64" y="314" width="1312" height="126" rx="14"/><text x="88" y="341" class="laneLabel">EXISTING REPOSITORY</text><rect class="card start" x="110" y="196" width="180" height="58" rx="10"/><text x="130" y="220" class="nodeTitle">New repository</text><text x="130" y="240" class="nodeMeta">no source to inspect</text><rect class="card start" x="110" y="356" width="180" height="58" rx="10"/><text x="130" y="380" class="nodeTitle">Existing repository</text><text x="130" y="400" class="nodeMeta">source already present</text><rect class="card extract" x="335" y="356" width="150" height="58" rx="10"/><text x="355" y="380" class="nodeTitle">extract</text><text x="355" y="400" class="nodeMeta">complete baseline</text><rect class="card" x="545" y="245" width="170" height="58" rx="10"/><text x="565" y="269" class="nodeTitle">projectcontext</text><text x="565" y="289" class="nodeMeta">purpose + boundaries</text><rect class="card" x="755" y="245" width="150" height="58" rx="10"/><text x="775" y="269" class="nodeTitle">techstack</text><text x="775" y="289" class="nodeMeta">observed tooling</text><rect class="card" x="945" y="245" width="180" height="58" rx="10"/><text x="965" y="269" class="nodeTitle">codebase-structure</text><text x="965" y="289" class="nodeMeta">roots + boundaries</text><rect class="card" x="1185" y="245" width="150" height="58" rx="10"/><text x="1205" y="269" class="nodeTitle">standards + rules</text><text x="1205" y="289" class="nodeMeta">constraints</text><path class="flow" d="M290 225H505V274H545"/><path class="flowMuted" d="M290 385H335"/><path class="flow" d="M715 274H755M905 274H945M1125 274H1185"/><text x="64" y="468" class="foot">NEW: AUTHOR FOUNDATION COMMANDS • EXISTING: EXTRACT CREATES THE COMPLETE BASELINE</text></svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1440 520" role="img" aria-labelledby="title desc"><title id="title">Foundation routes for new and existing repositories</title><desc id="desc">New repositories begin with project context. Existing repositories use Extract to create the complete evidence-backed baseline.</desc><style>.bg{fill:#070b18}.surface{fill:#101827;stroke:#24324b}.lane{fill:#0c1323;stroke:#263653;stroke-dasharray:6 7}.eyebrow{font:700 12px system-ui,sans-serif;letter-spacing:2px;fill:#69d8ff}.title{font:700 30px system-ui,sans-serif;fill:#f8fafc}.sub{font:15px system-ui,sans-serif;fill:#aab8cf}.laneLabel{font:700 11px system-ui,sans-serif;letter-spacing:1.5px;fill:#7f91b1}.card{fill:#16223a;stroke:#35517c;stroke-width:1.5}.start{fill:#123745;stroke:#39c9d9}.extract{fill:#252044;stroke:#9c8cff}.nodeTitle{font:700 15px system-ui,sans-serif;fill:#f8fafc}.nodeMeta{font:12px system-ui,sans-serif;fill:#aab8cf}.flow{fill:none;stroke:#69d8ff;stroke-width:2.5;marker-end:url(#arrow)}.flowMuted{fill:none;stroke:#9c8cff;stroke-width:2.5;marker-end:url(#arrowV)}.foot{font:600 11px system-ui,sans-serif;letter-spacing:1px;fill:#6f86a8}</style><defs><pattern id="grid" width="32" height="32" patternUnits="userSpaceOnUse"><path d="M32 0H0V32" fill="none" stroke="#14213a" stroke-width="1"/></pattern><marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#69d8ff"/></marker><marker id="arrowV" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#9c8cff"/></marker></defs><rect class="bg" width="1440" height="520"/><rect fill="url(#grid)" width="1440" height="520" opacity=".9"/><rect class="surface" x="28" y="28" width="1384" height="464" rx="20"/><text x="64" y="67" class="eyebrow">DEVSPEC LITE / FOUNDATION</text><text x="64" y="103" class="title">Choose the correct repository route</text><text x="64" y="131" class="sub">New projects are documented intentionally. Existing systems are documented end-to-end from observed evidence.</text><rect class="lane" x="64" y="154" width="1312" height="126" rx="14"/><text x="88" y="181" class="laneLabel">NEW REPOSITORY</text><rect class="lane" x="64" y="314" width="1312" height="126" rx="14"/><text x="88" y="341" class="laneLabel">EXISTING REPOSITORY</text><rect class="card start" x="110" y="196" width="180" height="58" rx="10"/><text x="130" y="220" class="nodeTitle">New repository</text><text x="130" y="240" class="nodeMeta">no source to inspect</text><rect class="card start" x="110" y="356" width="180" height="58" rx="10"/><text x="130" y="380" class="nodeTitle">Existing repository</text><text x="130" y="400" class="nodeMeta">source already present</text><rect class="card extract" x="335" y="356" width="150" height="58" rx="10"/><text x="355" y="380" class="nodeTitle">extract</text><text x="355" y="400" class="nodeMeta">complete baseline</text><rect class="card" x="535" y="245" width="165" height="58" rx="10"/><text x="553" y="269" class="nodeTitle">projectcontext</text><text x="553" y="289" class="nodeMeta">purpose + boundaries</text><rect class="card" x="718" y="245" width="125" height="58" rx="10"/><text x="736" y="269" class="nodeTitle">techstack</text><text x="736" y="289" class="nodeMeta">observed tooling</text><rect class="card" x="861" y="245" width="185" height="58" rx="10"/><text x="879" y="269" class="nodeTitle">codebase-structure</text><text x="879" y="289" class="nodeMeta">roots + boundaries</text><rect class="card" x="1064" y="245" width="172" height="58" rx="10"/><text x="1082" y="269" class="nodeTitle">coding-standards</text><text x="1082" y="289" class="nodeMeta">conventions</text><rect class="card" x="1254" y="245" width="105" height="58" rx="10"/><text x="1272" y="269" class="nodeTitle">rules</text><text x="1272" y="289" class="nodeMeta">constraints</text><path class="flow" d="M290 225H505V274H535"/><path class="flowMuted" d="M290 385H335"/><path class="flow" d="M700 274H718M843 274H861M1046 274H1064M1236 274H1254"/><text x="64" y="468" class="foot">NEW: AUTHOR FOUNDATION COMMANDS • EXISTING: EXTRACT CREATES THE COMPLETE BASELINE</text></svg>
diff --git a/docs/assets/manual-copy-flow.svg b/docs/assets/manual-copy-flow.svg
index 359ff0d..f245271 100644
--- a/docs/assets/manual-copy-flow.svg
+++ b/docs/assets/manual-copy-flow.svg
@@ -1,14 +1,15 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1440 440" role="img" aria-labelledby="title desc">
   <title id="title">Manual copy flow for Devspec Lite</title>
-  <desc id="desc">A developer checks out the latest main branch, chooses one agent profile, copies the canonical artifacts into a target repository, verifies the files, and commits them. Updates repeat the comparison and copy steps without requiring the CLI.</desc>
-  <style>.bg{fill:#070b18}.surface{fill:#101827;stroke:#263653}.card{fill:#16223a;stroke:#35517c;stroke-width:1.5}.start{fill:#123745;stroke:#39c9d9}.safe{fill:#17372d;stroke:#64d49a}.eyebrow{font:700 12px system-ui,sans-serif;letter-spacing:2px;fill:#69d8ff}.title{font:700 30px system-ui,sans-serif;fill:#f8fafc}.sub{font:15px system-ui,sans-serif;fill:#aab8cf}.node{font:700 15px system-ui,sans-serif;fill:#f8fafc}.meta{font:12px system-ui,sans-serif;fill:#aab8cf}.flow{fill:none;stroke:#69d8ff;stroke-width:2.5;marker-end:url(#arrow)}.loop{fill:none;stroke:#9c8cff;stroke-width:2.2;stroke-dasharray:7 6;marker-end:url(#arrowV)}.note{font:13px system-ui,sans-serif;fill:#c1cae0}.foot{font:600 11px system-ui,sans-serif;letter-spacing:1px;fill:#6f86a8}</style>
+  <desc id="desc">A developer checks out the latest main branch, chooses one agent profile, copies the canonical artifacts into a target repository, resets the project records that the checkout carries, sets the target repository state, then verifies and commits. Updates repeat the comparison and copy steps without requiring the CLI.</desc>
+  <style>.bg{fill:#070b18}.surface{fill:#101827;stroke:#263653}.card{fill:#16223a;stroke:#35517c;stroke-width:1.5}.start{fill:#123745;stroke:#39c9d9}.reset{fill:#3a2b10;stroke:#ffc857}.safe{fill:#17372d;stroke:#64d49a}.eyebrow{font:700 12px system-ui,sans-serif;letter-spacing:2px;fill:#69d8ff}.title{font:700 30px system-ui,sans-serif;fill:#f8fafc}.sub{font:15px system-ui,sans-serif;fill:#aab8cf}.node{font:700 15px system-ui,sans-serif;fill:#f8fafc}.meta{font:12px system-ui,sans-serif;fill:#aab8cf}.flow{fill:none;stroke:#69d8ff;stroke-width:2.5;marker-end:url(#arrow)}.loop{fill:none;stroke:#9c8cff;stroke-width:2.2;stroke-dasharray:7 6;marker-end:url(#arrowV)}.note{font:13px system-ui,sans-serif;fill:#c1cae0}.foot{font:600 11px system-ui,sans-serif;letter-spacing:1px;fill:#6f86a8}</style>
   <defs><pattern id="grid" width="32" height="32" patternUnits="userSpaceOnUse"><path d="M32 0H0V32" fill="none" stroke="#14213a"/></pattern><marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#69d8ff"/></marker><marker id="arrowV" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#9c8cff"/></marker></defs>
   <rect class="bg" width="1440" height="440"/><rect fill="url(#grid)" width="1440" height="440" opacity=".9"/><rect class="surface" x="28" y="28" width="1384" height="384" rx="20"/>
   <text x="64" y="67" class="eyebrow">DEVSPEC LITE / MANUAL COPY</text><text x="64" y="103" class="title">Copy the latest main profile without an installer</text><text x="64" y="131" class="sub">Main-branch files are canonical. Python and the CLI are optional, not required.</text>
-  <rect class="card start" x="84" y="220" width="200" height="62" rx="10"/><text x="104" y="246" class="node">Check out main</text><text x="104" y="266" class="meta">latest canonical files</text>
-  <rect class="card" x="350" y="220" width="185" height="62" rx="10"/><text x="370" y="246" class="node">Choose profile</text><text x="370" y="266" class="meta">one agent host</text>
-  <rect class="card" x="600" y="220" width="210" height="62" rx="10"/><text x="620" y="246" class="node">Copy required files</text><text x="620" y="266" class="meta">devspec + wrapper</text>
-  <rect class="card" x="875" y="220" width="180" height="62" rx="10"/><text x="895" y="246" class="node">Verify paths</text><text x="895" y="266" class="meta">manifest + wrapper</text>
-  <rect class="card safe" x="1120" y="220" width="210" height="62" rx="10"/><text x="1140" y="246" class="node">Commit target files</text><text x="1140" y="266" class="meta">start the workflow</text>
-  <path class="flow" d="M284 251H350M535 251H600M810 251H875M1055 251H1120"/><path class="loop" d="M965 220V166H705V220"/><text x="714" y="153" class="note">latest main → compare, copy approved changes, commit</text><text x="64" y="366" class="foot">NO PYTHON • NO CLI • NO PACKAGE MANAGER • PRESERVE LOCAL CUSTOMIZATIONS</text>
-</svg>
\ No newline at end of file
+  <rect class="card start" x="56" y="220" width="205" height="62" rx="10"/><text x="72" y="246" class="node">Check out main</text><text x="72" y="266" class="meta">latest canonical files</text>
+  <rect class="card" x="279" y="220" width="205" height="62" rx="10"/><text x="295" y="246" class="node">Choose profile</text><text x="295" y="266" class="meta">one agent host</text>
+  <rect class="card" x="502" y="220" width="205" height="62" rx="10"/><text x="518" y="246" class="node">Copy required files</text><text x="518" y="266" class="meta">devspec + wrapper</text>
+  <rect class="card reset" x="725" y="220" width="205" height="62" rx="10"/><text x="741" y="246" class="node">Reset project data</text><text x="741" y="266" class="meta">queue, overview, QF</text>
+  <rect class="card" x="948" y="220" width="205" height="62" rx="10"/><text x="964" y="246" class="node">Set repository state</text><text x="964" y="266" class="meta">new or existing</text>
+  <rect class="card safe" x="1171" y="220" width="205" height="62" rx="10"/><text x="1187" y="246" class="node">Verify and commit</text><text x="1187" y="266" class="meta">manifest + reset table</text>
+  <path class="flow" d="M261 251H279M484 251H502M707 251H725M930 251H948M1153 251H1171"/><path class="loop" d="M1273 220V166H604V220"/><text x="620" y="153" class="note">latest main → compare, copy approved changes, reset project data, commit</text><text x="64" y="366" class="foot">NO PYTHON • NO CLI • NO PACKAGE MANAGER • PRESERVE LOCAL CUSTOMIZATIONS</text>
+</svg>
diff --git a/docs/command-examples.md b/docs/command-examples.md
index 8f2bc5a..6f15de3 100644
--- a/docs/command-examples.md
+++ b/docs/command-examples.md
@@ -9,7 +9,7 @@ No `devspec.*` command treats the agent's current workspace as proof of its repo
 When evidence is absent, collect scope in this order for every command:
 
 1. Ask one free-form repository path question. The text input should say, “Which repository is in scope? Enter its local path or name.” Show examples such as `D:\Code\orders-api` and `D:\Code\orders-web`, and let the developer type another value. Do not ask about access yet.
-2. After the path is confirmed, ask: **What access requirement applies to `D:\Code\orders-api`?** Always show these choices: **Reference-only** — inspect source, configuration, and tests as evidence; do not edit or run validations. **Edit** — update approved repository files; do not run validations. **Edit-and-test (Recommended)** — make approved changes and run focused validations, including tests. **Validation-only** — run approved validations without editing. **Release-coordination** — coordinate release information without inspecting the repository. **Unavailable** — record a blocker because the repository cannot be accessed. **Custom Answer** — describe another boundary, for example edit only one approved folder. `Edit-and-test` grants normal delivery capability; the active command still controls whether source is changed.
+2. After the path is confirmed, ask: **What access requirement applies to `D:\Code\orders-api`?** Always show these choices: **Reference-only** — inspect source, configuration, and tests as evidence; do not edit or run validations. **Edit** — update approved repository files; do not run validations. **Edit-and-test** — make approved changes and run focused validations, including tests. Recommended for ordinary delivery work; for a repository outside the change, recommend the least privilege that still satisfies the command. **Validation-only** — run approved validations without editing. **Release-coordination** — coordinate release information without inspecting the repository. **Unavailable** — record a blocker because the repository cannot be accessed. **Custom Answer** — describe another boundary, for example edit only one approved folder. `Edit-and-test` grants normal delivery capability; the active command still controls whether source is changed.
 3. Repeat the path question and then the access question for each additional repository. Record the scaffold path, repository role, and the separate read, edit, and validation permissions before continuing.
 
 For a new project, the path answer may say `D:\Code\inventory — no source exists yet`; access is still confirmed after the path.
@@ -27,7 +27,7 @@ The scaffold location is not a source-access grant. When it is outside the code
 
 ## Work with multiple repositories
 
-Name a primary repository that owns the change record, then list every dependent repository. For each one, state a local path plus one named access requirement (`reference-only`, `edit`, `edit-and-test`, `validation-only`, `release-coordination`, or `unavailable`). For example, a documentation repository might be `read/edit/validate`; a production-infrastructure repository may be `read` only. The agent must not infer missing permissions, edit a reference-only repository, or validate it.
+Name a primary repository that owns the change record, then list every dependent repository. For each one, state a local path plus one named access requirement (`reference-only`, `edit`, `edit-and-test`, `validation-only`, `release-coordination`, or `unavailable`). For example, a documentation repository might be `edit-and-test`; a production-infrastructure repository may be `reference-only`. The agent must not infer missing permissions. It honors exactly the recorded requirement, as `devspec/protocols/repo-access.xml` defines: an `edit` repository is never validated, and a `release-coordination` one is never even inspected.
 
 ## Intake from MCP providers
 
diff --git a/docs/how-to.md b/docs/how-to.md
index fd00fda..0272eab 100644
--- a/docs/how-to.md
+++ b/docs/how-to.md
@@ -18,14 +18,14 @@ For provider-backed story intake, pass one GitHub, Azure DevOps, Jira, GitLab, o
 
 | Developer situation | Run | Then |
 |---|---|---|
-| Existing codebase with no trusted Devspec baseline | `devspec.extract` | Start a story after the baseline is ready. |
-| Brand-new repository | `devspec.projectcontext` | Continue the new-foundation route. |
+| `devspec/foundation/repository-state.md` says `existing` | `devspec.extract` | Start a work item after the baseline is ready. |
+| `devspec/foundation/repository-state.md` says `new` | `devspec.projectcontext` | Continue the new-foundation route. |
 | New feature, API contract, migration, security change, or multiple concerns | `devspec.story` | Groom when needed, then finalize, plan, implement, and review. |
 | One local, low-risk correction | `devspec.quickfix` | Complete directly, clarify a blocker, or route to a story. |
 | A recorded material decision blocks current work | `devspec.clarify` | Resume the exact saved command. |
 | A related requirement arrives after finalization | `devspec.changerequest` | Re-finalize the new scope revision. |
-| One evidence-backed architecture or workflow visual is needed | `devspec.diagram` | Return to the caller's workflow. |
-| A known foundation artifact needs a narrow update | Its matching foundation command | Return to the caller after the update. |
+| One evidence-backed architecture or workflow visual is needed | `devspec.diagram` | Return to the caller's workflow, or clarify an evidence blocker. |
+| A known foundation artifact needs a narrow update | Its matching foundation command | Return to the caller, or clarify an evidence blocker. |
 
 ## Continue current work without an ID
 
@@ -42,8 +42,8 @@ uvx devspec-lite init --target . --profile all --repo-state existing
 uvx devspec-lite doctor --target . --profile all
 ```
 
-2. Confirm source scope in order: first enter the repository path or name in the free-form prompt, then choose a named access requirement after the path is confirmed. Show all standard access choices and recommend `edit-and-test`; that grants normal delivery capability, while the active command still prevents unnecessary source changes. If a team needs a narrow exception—such as “edit but run only lint”—use **Custom Answer**. The current workspace is only a proposed target; current canonical evidence may replace these questions only when it records the same path, role, and permissions.
-3. In your agent host, run a scoped request such as `/devspec.extract Source scope confirmed: orders API at D:\Code\orders-api (primary, read/edit/validate).`
+2. Confirm source scope in order: first enter the repository path or name in the free-form prompt, then choose a named access requirement after the path is confirmed. Show all six named access choices. Exactly one is recommended, with a justification, and it is the least privilege that satisfies the command: for ordinary delivery work that is `edit-and-test`, but a repository you only read as evidence should be recommended `reference-only`. If a team needs a narrow exception—such as “edit but run only lint”—use **Custom Answer**. The current workspace is only a proposed target; current canonical evidence may replace these questions only when it records the same path, role, and permissions.
+3. In your agent host, run a scoped request such as `/devspec.extract Source scope confirmed: orders API at D:\Code\orders-api (primary, `edit-and-test`).`
 4. It inspects only the confirmed source, tests, configuration, and documentation, then creates the evidence-backed foundation and prepares a list of applicable diagrams.
 5. At extraction closure, it shows the list and asks: **“Do you want me to generate all the possible diagrams?”** Choose **Yes** to generate every listed diagram, **No** to leave the list prepared, or enter selected IDs or subjects. For example, enter `DIA-001, DIA-004` to generate only those two.
 6. Any prepared diagram can be generated later with `/devspec.diagram <DIA-ID-or-subject>`, for example `/devspec.diagram DIA-002`. Static SVG is the default. Use `/devspec.diagram DIA-002 motion=explain` only when the confirmed sequence, flow, or state transition benefits from explanatory motion.
@@ -67,7 +67,7 @@ uvx devspec-lite doctor --target . --profile all
 **Scenario.** Your team has created an empty service repository and wants a durable engineering baseline before accepting feature work.
 
 1. Initialize it with `--repo-state new`.
-2. Confirm the repository scope before the first command, for example: `Scope confirmed: scaffold and planned source at D:\Code\inventory; no source exists yet; read/edit/validate.`
+2. Confirm the repository scope before the first command, for example: `Scope confirmed: scaffold and planned source at D:\Code\inventory; no source exists yet; `edit-and-test`.`
 3. Run these agent commands in order:
 
 ```text
@@ -81,7 +81,7 @@ uvx devspec-lite doctor --target . --profile all
 4. Use `/devspec.coding-standards` to add a team-defined standard at any time as a targeted update. Include a concise example that future implementations should follow; the artifact distinguishes it from an observed source convention.
 5. Use `/devspec.diagram <subject>` only when a specific evidence-backed visual is needed during this route. Add `motion=explain` only for a confirmed sequence, flow, or state transition; otherwise keep the static default.
 
-**What to expect.** Each command records its artifact and advances to the next command. After `rules`, the foundation is ready for `/devspec.story`.
+**What to expect.** Each command records its artifact and advances to the next command, or records an evidence blocker and routes to `/devspec.clarify`. After `devspec.rules`, the foundation is ready for `/devspec.story`.
 
 ## 3. Deliver a feature from request to accepted review
 
@@ -114,13 +114,13 @@ uvx devspec-lite doctor --target . --profile all
 3. Start the story from the primary repository and state the repository roles, local paths, and read, edit, and validation permissions in the request. For example:
 
 ```text
-/devspec.story Add checkout address validation. Primary: orders-api at D:\Code\orders-api (read/edit/validate). Dependent UI: orders-web at D:\Code\orders-web (read/edit/validate).
+/devspec.story Add checkout address validation. Primary: orders-api at D:\Code\orders-api (`edit-and-test`). Dependent UI: orders-web at D:\Code\orders-web (`edit-and-test`).
 ```
 
 4. When a command needs the second repository, it uses the `repo-access` protocol before reading, editing, or validating it. Record a repository as reference-only or validation-only when that is its real boundary.
 5. Run `/devspec.extract` instead of the individual foundation commands when you need an evidence-backed baseline for an explicitly scoped multi-repository existing system.
 
-**What to expect.** There is no separate multi-repository configuration command. The approved roles, paths, and access permissions are the configuration, recorded in canonical Devspec artifacts. Never infer edit access, and never validate a reference-only or unavailable repository.
+**What to expect.** There is no separate multi-repository configuration command. The approved roles, paths, and access permissions are the configuration, recorded in canonical Devspec artifacts. Never infer access from a path. Honor exactly the recorded requirement: never inspect a `release-coordination` or `unavailable` repository; never edit a `reference-only`, `validation-only`, `release-coordination`, or `unavailable` one; and never validate a `reference-only`, `edit`, `release-coordination`, or `unavailable` one. `devspec/protocols/repo-access.xml` is the authority.
 
 - Next command for a new change: `/devspec.story <one request with repository scope>`.
 
diff --git a/docs/manual-copy.md b/docs/manual-copy.md
index e5ebe56..d0fd34d 100644
--- a/docs/manual-copy.md
+++ b/docs/manual-copy.md
@@ -14,11 +14,11 @@ The `main` checkout supplies the canonical `devspec/` directory and prebuilt age
 
 ## 2. Copy one profile
 
-Copy `devspec/` and the folder or file for the agent host into the target repository.
+Copy `devspec/` and the folder or file for the agent host into the target repository. Copy only the listed paths. In particular do not copy `.github/workflows/` — those are Devspec Lite's own release pipelines, and one of them requests publishing credentials.
 
 | Profile | Copy from the `main` checkout | Copy into the target repository |
 |---|---|---|
-| Copilot | `devspec/`, `.github/` | `devspec/`, `.github/` |
+| Copilot | `devspec/`, `.github/prompts/`, `.github/agents/` | `devspec/`, `.github/prompts/`, `.github/agents/` |
 | Codex | `devspec/`, `AGENTS.md` | `devspec/`, `AGENTS.md` |
 | Claude | `devspec/`, `.claude/` | `devspec/`, `.claude/` |
 | Cursor | `devspec/`, `.cursor/` | `devspec/`, `.cursor/` |
@@ -60,7 +60,7 @@ Use this exact Markdown structure:
 
 ## 4. Verify and commit
 
-Verify that every path listed in `devspec/install-manifest.txt` exists, that the selected agent wrapper is present, that `devspec/foundation/repository-state.md` has the target's intended state and start command, and that every row in step 2's reset table has been applied. Compare any same-named target wrapper before replacing it, then commit the copied files with the target repository.
+Verify that every glob pattern in `devspec/install-manifest.txt` resolves to at least one copied file, that the selected agent wrapper is present, that `devspec/foundation/repository-state.md` has the target's intended state and start command, and that every row in step 2's reset table has been applied. Compare any same-named target wrapper before replacing it, then commit the copied files with the target repository.
 
 ## 5. Update manually
 
diff --git a/docs/quickstart.md b/docs/quickstart.md
index ff8a698..b92a3cd 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -20,8 +20,10 @@ Use a narrower profile such as `copilot`, `codex`, `claude`, `cursor`, `gemini`,
 
 ## 2. Start the right workflow
 
+Every `devspec.*` command begins by confirming repository scope: it asks for each repository path, then one named access requirement per repository. Answer those before the command inspects any source. The route itself comes from `devspec/foundation/repository-state.md`, which `init` writes from `--repo-state`.
+
 - New repository: author the foundation intentionally with `devspec.projectcontext → devspec.techstack → devspec.codebase-structure → devspec.coding-standards → devspec.rules`.
-- Existing repository: run `devspec.extract` once. It creates the evidence-backed technical, workflow, and rules baseline, prepares the possible-diagram list, and asks whether to generate all or selected diagrams. Select **No** to keep only the list; later generate a static SVG with `/devspec.diagram DIA-002`, or request an evidence-backed animated explanation with `/devspec.diagram DIA-002 motion=explain`.
+- Existing repository: run `devspec.extract` once. It creates the evidence-backed technical, business, workflow, and rule baseline, prepares the possible-diagram list, then asks one question with four answers: generate all, prepare the list only, choose specific diagrams, or a custom answer. Choosing to prepare the list only keeps the candidates without generating them; later generate a static SVG with `/devspec.diagram DIA-002`, or request an evidence-backed animated explanation with `/devspec.diagram DIA-002 motion=explain`.
 
 Work route: `devspec.story → devspec.grooming` when needed `→ devspec.finalize → devspec.tasks → devspec.implement → devspec.review`.
 
diff --git a/docs/setup-homebrew.md b/docs/setup-homebrew.md
index 630b30e..f9db12f 100644
--- a/docs/setup-homebrew.md
+++ b/docs/setup-homebrew.md
@@ -1,6 +1,6 @@
 # Homebrew setup
 
-Use this route on macOS or Linux only after the Devspec Lite formula is published to a Homebrew tap. If the tap or formula is unavailable, choose [Python and uvx](setup-python.md) or [manual copy from `main`](manual-copy.md).
+Use this route on macOS or Linux only after the Devspec Lite formula is published to a Homebrew tap. If the tap or formula is unavailable, use [manual copy from `main`](manual-copy.md); the [Python route](setup-python.md) needs the same release.
 
 ## Install
 
@@ -22,7 +22,7 @@ devspec-lite init --target . --profile all --repo-state new
 devspec-lite doctor --target . --profile all
 ```
 
-Use a single-agent profile when the repository does not need every adapter wrapper.
+Use a single-agent profile when the repository does not need every adapter wrapper: `copilot`, `codex`, `claude`, `cursor`, `gemini`, or `antigravity`.
 
 ## Next steps
 
diff --git a/docs/setup-lifecycle.md b/docs/setup-lifecycle.md
index ebe2dfa..0f23712 100644
--- a/docs/setup-lifecycle.md
+++ b/docs/setup-lifecycle.md
@@ -14,7 +14,7 @@ The terminal CLI is `devspec-lite`. After initialization, the installed agent wr
 |---|---|---|
 | Install the CLI | `uvx`, `pipx`, WinGet, or Homebrew | Choose one package-manager route below. |
 | Check version | `devspec-lite --version` | Confirms the installed CLI. |
-| Initialize | `devspec-lite init --target <path> --profile <profile> --repo-state <new|existing>` | Copies canonical artifacts and selected wrappers. |
+| Initialize | `devspec-lite init --target <path> --profile <profile> --repo-state <new\|existing>` | Copies canonical artifacts and selected wrappers. |
 | Validate | `devspec-lite doctor --target <path> --profile <profile>` | Read-only check of contracts, protocols, templates, and wrappers. |
 | Compare installed framework files | `devspec-lite diff --target <path>` | Read-only drift report. |
 | Synchronize canonical artifacts | `devspec-lite sync --target <path> --profile <profile> --dry-run` | Preview, then run without `--dry-run`; use `--force` only for reviewed framework-owned edits. |
diff --git a/docs/setup-python.md b/docs/setup-python.md
index adae95c..51f356e 100644
--- a/docs/setup-python.md
+++ b/docs/setup-python.md
@@ -1,6 +1,8 @@
 # Python and uvx setup
 
-Use this route on Windows, macOS, or Linux when Python 3.10 or newer is available. Choose `uvx` for one-off use, or `pipx` for a persistent CLI installation. To avoid installing Python or any CLI, use [manual copy from `main`](manual-copy.md).
+Use this route on Windows, macOS, or Linux when Python 3.10 or newer is available. Choose `uvx` for one-off use, or `pipx` for a persistent CLI installation.
+
+The commands below need a published package. Until the first `v*` release is tagged, no CLI route resolves; use [manual copy from `main`](manual-copy.md), which never requires Python or a package manager.
 
 ## One-off use with uvx
 
diff --git a/docs/setup-winget.md b/docs/setup-winget.md
index 8e1eb8a..b75342b 100644
--- a/docs/setup-winget.md
+++ b/docs/setup-winget.md
@@ -1,6 +1,6 @@
 # WinGet setup
 
-Use this route on Windows only after the Devspec Lite package is published to WinGet. If the package is unavailable, choose [Python and uvx](setup-python.md) or [manual copy from `main`](manual-copy.md).
+Use this route on Windows only after the Devspec Lite package is published to WinGet. If the package is unavailable, use [manual copy from `main`](manual-copy.md); the [Python route](setup-python.md) needs the same release.
 
 ## Install
 
diff --git a/docs/workflows.md b/docs/workflows.md
index e6fdbec..f748329 100644
--- a/docs/workflows.md
+++ b/docs/workflows.md
@@ -9,7 +9,7 @@ Use the smallest route that preserves a durable, reviewable record. Git-tracked
 - New repository: start with `devspec.projectcontext`.
 - Before every command, confirm the single-repository or multi-repository scope, including the scaffold location and each source repository's role, path, and permissions, unless current canonical evidence records it. The current workspace alone is not proof of scope.
 - Existing repository: run `devspec.extract` once with confirmed scope. It completes the evidence-backed technical, workflow, and rule baseline, prepares the applicable diagram list, and asks whether to generate all, selected, or no diagrams. A prepared item can later be generated with `/devspec.diagram DIA-###`; do not rerun individual foundation commands afterward.
-- New repository: run `devspec.projectcontext`, `devspec.techstack`, `devspec.codebase-structure`, `devspec.coding-standards`, and `devspec.rules` in order as input-driven authoring commands. `devspec.diagram` is not part of the chain; call it separately and it returns to its caller.
+- New repository: run `devspec.projectcontext`, `devspec.techstack`, `devspec.codebase-structure`, `devspec.coding-standards`, and `devspec.rules` in order. `devspec.techstack`, `devspec.codebase-structure`, and `devspec.coding-standards` inspect source for evidence, so they confirm repository access first; the other two are input-driven. `devspec.diagram` is not part of the chain; call it separately and it returns to its caller.
 
 ## 2. Deliver a change
 
diff --git a/src/devspec_lite/framework.py b/src/devspec_lite/framework.py
index 7d8fe0b..4b8b9bc 100644
--- a/src/devspec_lite/framework.py
+++ b/src/devspec_lite/framework.py
@@ -326,10 +326,10 @@ def _copy_plan(root: Path, files: tuple[ManagedFile, ...], previous: dict | None
             skipped.append(name)
             continue
         if item.ownership == PROJECT_OWNED:
-            if mode == "sync":
-                skipped.append(f"{name} (project-owned)")
-            else:
-                conflicts.append(f"{name} already exists and differs")
+            # A project-owned file that already exists is the developer's own work, and its
+            # presence is expected when re-running init to add a profile. Never overwrite it,
+            # and never fail on it: the only escape would be --force, which would destroy it.
+            skipped.append(f"{name} (project-owned)")
             continue
         if mode == "sync" and old.get(name, {}).get("sha256") == digest:
             writable.append(item)
diff --git a/tests/test_upgrade.py b/tests/test_upgrade.py
index a566ea4..a6aa9aa 100644
--- a/tests/test_upgrade.py
+++ b/tests/test_upgrade.py
@@ -11,6 +11,26 @@
 
 
 class UpgradeLifecycleTests(unittest.TestCase):
+    def test_adding_a_profile_preserves_project_work(self) -> None:
+        # Re-running init to add a profile must not fail on, or overwrite, the developer's own
+        # constitution, architecture queue, or overview. The only escape used to be --force,
+        # which would have destroyed exactly those files.
+        with tempfile.TemporaryDirectory() as raw:
+            target = Path(raw)
+            main(["init", "--target", str(target), "--profile", "codex", "--repo-state", "existing"])
+            owned = {
+                "devspec/constitution.md": "# Constitution\n\n| CP-001 | keep me |\n",
+                "devspec/architecture/artifact-queue.md": "# Architecture Artifact Queue\n\n| DIA-001 | keep me |\n",
+                "devspec/architecture/overview.md": "# Architecture Overview\n\nkeep me\n",
+            }
+            for path, content in owned.items():
+                (target / path).write_text(content, encoding="utf-8")
+            self.assertEqual(0, main(["init", "--target", str(target), "--profile", "claude", "--repo-state", "existing"]))
+            for path, content in owned.items():
+                self.assertEqual(content, (target / path).read_text(encoding="utf-8"), path)
+            self.assertTrue((target / ".claude/skills/devspec-story/SKILL.md").is_file())
+            self.assertTrue((target / "AGENTS.md").is_file())
+
     def run_cli(self, arguments: list[str]) -> tuple[int, str]:
         output = io.StringIO()
         with contextlib.redirect_stdout(output):
@@ -51,8 +71,11 @@ def test_diff_reports_missing_files_and_init_force_preserves_project_owned_files
             self.assertIn("AGENTS.md", diff_framework(target, "codex")["missing"])
             constitution = target / "devspec/constitution.md"
             constitution.write_text("# Constitution\n\nCP-001: protected\n", encoding="utf-8")
-            self.assertEqual(2, main(["init", "--target", str(target), "--profile", "codex", "--repo-state", "new", "--force"]))
+            # init now restores the missing wrapper instead of failing, and --force still
+            # cannot reach a project-owned file.
+            self.assertEqual(0, main(["init", "--target", str(target), "--profile", "codex", "--repo-state", "new", "--force"]))
             self.assertIn("CP-001: protected", constitution.read_text(encoding="utf-8"))
+            self.assertTrue((target / "AGENTS.md").is_file())
 
     def test_sync_preserves_project_owned_constitution(self) -> None:
         with tempfile.TemporaryDirectory() as raw:

From a66d5ac4ba173d196dce49ee3b68d1a5c49011fe Mon Sep 17 00:00:00 2001
From: Vikram Reddy <gvreddy04@gmail.com>
Date: Sat, 5 Sep 2026 17:57:18 +0530
Subject: [PATCH 7/7] Enhance diagram generation documentation and templates

- Updated workflows documentation to include a new section for generating diagrams, detailing the selection of diagram types and templates.
- Added new SVG templates for Application Landscape and Infrastructure Topology diagrams, providing a structured format for visualizing application and infrastructure architectures.
- Introduced a diagram route SVG to illustrate the diagram generation process within Devspec Lite.
- Expanded test coverage for diagram templates to ensure no dangling marker references and validate the presence of expected diagram types.
---
 .../application-landscape-diagram.svg         | 196 ++++++++++++++++++
 .../_template/architecture-diagram.svg        | 151 +++++++-------
 .../architecture/_template/diagram-sample.md  |   2 +-
 .../architecture/_template/diagram-sample.svg | 141 ++++++++++++-
 .../architecture/_template/diagram-types.md   |   8 +-
 devspec/architecture/_template/diagram.md     |   2 +-
 .../_template/domain-model-diagram.svg        |   6 +-
 .../infrastructure-topology-diagram.svg       | 193 +++++++++++++++++
 .../_template/journey-map-diagram.svg         |  15 +-
 .../_template/mindmap-diagram.svg             |  20 +-
 .../_template/process-flow-diagram.svg        |  10 +-
 .../_template/quadrant-analysis-diagram.svg   |   8 +-
 .../_template/state-lifecycle-diagram.svg     |  34 +--
 .../_template/timeline-plan-diagram.svg       |  97 +++++----
 devspec/architecture/artifact-queue.md        |   1 +
 devspec/architecture/overview.md              |   1 +
 devspec/contracts/devspec.diagram.md          |   3 +-
 docs/assets/delivery-routes.svg               |   2 +-
 docs/assets/diagram-route.svg                 |   1 +
 docs/workflows.md                             |  22 +-
 tests/test_framework.py                       |  30 +++
 21 files changed, 770 insertions(+), 173 deletions(-)
 create mode 100644 devspec/architecture/_template/application-landscape-diagram.svg
 create mode 100644 devspec/architecture/_template/infrastructure-topology-diagram.svg
 create mode 100644 docs/assets/diagram-route.svg

diff --git a/devspec/architecture/_template/application-landscape-diagram.svg b/devspec/architecture/_template/application-landscape-diagram.svg
new file mode 100644
index 0000000..07ee8e0
--- /dev/null
+++ b/devspec/architecture/_template/application-landscape-diagram.svg
@@ -0,0 +1,196 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 900" role="img" aria-labelledby="title desc">
+  <title id="title">[DIAGRAM_TITLE] - Application Landscape Diagram</title>
+  <desc id="desc">[DIAGRAM_DESCRIPTION]</desc>
+
+  <defs>
+    <style><![CDATA[
+      svg {
+        background: #020617;
+        font-family: "JetBrains Mono", "Cascadia Code", monospace;
+      }
+
+      .page-bg { fill: #020617; }
+      .grid-line { stroke: #1e293b; stroke-width: 0.7; opacity: 0.65; }
+      .surface { fill: #0f172a; stroke: #1e293b; stroke-width: 1.4; filter: url(#soft-shadow); }
+      .title { fill: #f8fafc; font-size: 38px; font-weight: 800; }
+      .subtitle { fill: #cbd5e1; font-size: 16px; font-weight: 500; }
+      .eyebrow { fill: #67e8f9; font-size: 13px; font-weight: 800; letter-spacing: 1.6px; }
+      .footer { fill: #64748b; font-size: 12px; }
+
+      .domain { fill: rgba(15, 23, 42, 0.22); stroke-width: 1.6; stroke-dasharray: 10 8; }
+      .domain-a { stroke: #22d3ee; }
+      .domain-b { stroke: #34d399; }
+      .domain-shared { stroke: #a78bfa; }
+      .domain-title { font-size: 13px; font-weight: 900; letter-spacing: 1px; }
+      .domain-title.a { fill: #67e8f9; }
+      .domain-title.b { fill: #6ee7b7; }
+      .domain-title.shared { fill: #c4b5fd; }
+
+      .app-mask { fill: #0f172a; }
+      .app { stroke-width: 1.8; filter: url(#node-glow); }
+      .app-owned { fill: rgba(30, 41, 59, 0.78); stroke: #94a3b8; }
+      .app-primary { fill: rgba(8, 51, 68, 0.46); stroke: #22d3ee; }
+      .app-service { fill: rgba(6, 78, 59, 0.46); stroke: #34d399; }
+      .app-shared { fill: rgba(76, 29, 149, 0.46); stroke: #a78bfa; }
+      .app-vendor { fill: rgba(120, 53, 15, 0.40); stroke: #fbbf24; }
+
+      .app-title { fill: #f8fafc; font-size: 16px; font-weight: 800; }
+      .app-role { fill: #cbd5e1; font-size: 12px; font-weight: 600; }
+      .app-owner { fill: #94a3b8; font-size: 11px; font-weight: 600; }
+
+      .interface { fill: none; stroke: #e2e8f0; stroke-width: 2.2; opacity: 0.92; }
+      .interface-async { stroke: #fb923c; stroke-dasharray: 9 5; }
+      .interface-label-bg { fill: #0f172a; stroke: #334155; stroke-width: 1; }
+      .interface-label { fill: #f8fafc; font-size: 12px; font-weight: 800; }
+
+      .legend-panel { fill: rgba(15, 23, 42, 0.86); stroke: #334155; stroke-width: 1.2; }
+      .legend-title { fill: #f8fafc; font-size: 14px; font-weight: 800; }
+      .legend-text { fill: #cbd5e1; font-size: 12px; font-weight: 600; }
+    ]]></style>
+
+    <pattern id="grid" width="48" height="48" patternUnits="userSpaceOnUse">
+      <path class="grid-line" d="M 48 0 L 0 0 0 48" fill="none"/>
+    </pattern>
+
+    <filter id="soft-shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="22" stdDeviation="22" flood-color="#000000" flood-opacity="0.34"/>
+    </filter>
+
+    <filter id="node-glow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="0" stdDeviation="5" flood-color="#38bdf8" flood-opacity="0.16"/>
+    </filter>
+
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#e2e8f0"/>
+    </marker>
+
+    <marker id="arrow-async" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#fb923c"/>
+    </marker>
+  </defs>
+
+  <rect class="page-bg" width="1600" height="900"/>
+  <rect width="1600" height="900" fill="url(#grid)" opacity="0.42"/>
+  <rect class="surface" x="48" y="42" width="1504" height="816" rx="20"/>
+
+  <text class="eyebrow" x="92" y="92">[PROJECT_NAME]</text>
+  <text class="title" x="92" y="138">[DIAGRAM_TITLE]</text>
+  <text class="subtitle" x="92" y="168">[DIAGRAM_DESCRIPTION]</text>
+
+  <!-- Draw interface links before application cards so connectors stay behind the labels.
+       Every link joins two application edges; labels name the interface, not a step order. -->
+  <path class="interface" d="M 380 346 L 500 346" marker-end="url(#arrow)"/>
+  <rect class="interface-label-bg" x="406" y="334" width="68" height="24" rx="7"/>
+  <text class="interface-label" x="440" y="351" text-anchor="middle">REST</text>
+
+  <path class="interface" d="M 260 402 L 260 442" marker-end="url(#arrow)"/>
+  <rect class="interface-label-bg" x="282" y="410" width="76" height="24" rx="7"/>
+  <text class="interface-label" x="320" y="427" text-anchor="middle">Batch</text>
+
+  <path class="interface" d="M 740 346 L 940 346" marker-end="url(#arrow)"/>
+  <rect class="interface-label-bg" x="800" y="334" width="80" height="24" rx="7"/>
+  <text class="interface-label" x="840" y="351" text-anchor="middle">Contract</text>
+
+  <path class="interface" d="M 1140 346 L 1260 346" marker-end="url(#arrow)"/>
+  <rect class="interface-label-bg" x="1166" y="334" width="68" height="24" rx="7"/>
+  <text class="interface-label" x="1200" y="351" text-anchor="middle">SaaS</text>
+
+  <path class="interface" d="M 1040 402 L 1040 442" marker-end="url(#arrow)"/>
+  <rect class="interface-label-bg" x="1062" y="410" width="76" height="24" rx="7"/>
+  <text class="interface-label" x="1100" y="427" text-anchor="middle">Sync</text>
+
+  <path class="interface interface-async" d="M 620 402 C 620 520, 660 570, 720 646" marker-end="url(#arrow-async)"/>
+  <rect class="interface-label-bg" x="642" y="530" width="94" height="24" rx="7"/>
+  <text class="interface-label" x="689" y="547" text-anchor="middle">Publish</text>
+
+  <path class="interface interface-async" d="M 880 646 C 940 610, 980 580, 1040 542" marker-end="url(#arrow-async)"/>
+  <rect class="interface-label-bg" x="898" y="566" width="94" height="24" rx="7"/>
+  <text class="interface-label" x="945" y="583" text-anchor="middle">Consume</text>
+
+  <g data-domain="a">
+    <rect class="domain domain-a" x="104" y="230" width="656" height="330" rx="20"/>
+    <text class="domain-title a" x="130" y="262">[CAPABILITY_DOMAIN_A]</text>
+  </g>
+
+  <g data-domain="b">
+    <rect class="domain domain-b" x="900" y="230" width="604" height="330" rx="20"/>
+    <text class="domain-title b" x="926" y="262">[CAPABILITY_DOMAIN_B]</text>
+  </g>
+
+  <g data-domain="shared">
+    <rect class="domain domain-shared" x="104" y="596" width="1400" height="130" rx="20"/>
+    <text class="domain-title shared" x="130" y="626">[SHARED_PLATFORM]</text>
+  </g>
+
+  <g class="application" data-application="a-primary">
+    <rect class="app-mask" x="140" y="290" width="240" height="112" rx="14"/>
+    <rect class="app app-primary" x="140" y="290" width="240" height="112" rx="14"/>
+    <text class="app-title" x="260" y="330" text-anchor="middle">[App A1]</text>
+    <text class="app-role" x="260" y="354" text-anchor="middle">customer entry</text>
+    <text class="app-owner" x="260" y="378" text-anchor="middle">Owner: [team]</text>
+  </g>
+
+  <g class="application" data-application="a-service">
+    <rect class="app-mask" x="500" y="290" width="240" height="112" rx="14"/>
+    <rect class="app app-service" x="500" y="290" width="240" height="112" rx="14"/>
+    <text class="app-title" x="620" y="330" text-anchor="middle">[App A2]</text>
+    <text class="app-role" x="620" y="354" text-anchor="middle">order handling</text>
+    <text class="app-owner" x="620" y="378" text-anchor="middle">Owner: [team]</text>
+  </g>
+
+  <g class="application" data-application="a-support">
+    <rect class="app-mask" x="140" y="442" width="240" height="100" rx="14"/>
+    <rect class="app app-owned" x="140" y="442" width="240" height="100" rx="14"/>
+    <text class="app-title" x="260" y="480" text-anchor="middle">[App A3]</text>
+    <text class="app-role" x="260" y="504" text-anchor="middle">reporting</text>
+    <text class="app-owner" x="260" y="526" text-anchor="middle">Owner: [team]</text>
+  </g>
+
+  <g class="application" data-application="b-service">
+    <rect class="app-mask" x="940" y="290" width="200" height="112" rx="14"/>
+    <rect class="app app-service" x="940" y="290" width="200" height="112" rx="14"/>
+    <text class="app-title" x="1040" y="330" text-anchor="middle">[App B1]</text>
+    <text class="app-role" x="1040" y="354" text-anchor="middle">fulfilment</text>
+    <text class="app-owner" x="1040" y="378" text-anchor="middle">Owner: [team]</text>
+  </g>
+
+  <g class="application" data-application="b-vendor">
+    <rect class="app-mask" x="1260" y="290" width="220" height="112" rx="14"/>
+    <rect class="app app-vendor" x="1260" y="290" width="220" height="112" rx="14"/>
+    <text class="app-title" x="1370" y="330" text-anchor="middle">[Vendor App]</text>
+    <text class="app-role" x="1370" y="354" text-anchor="middle">bought capability</text>
+    <text class="app-owner" x="1370" y="378" text-anchor="middle">Owner: [vendor]</text>
+  </g>
+
+  <g class="application" data-application="b-support">
+    <rect class="app-mask" x="940" y="442" width="200" height="100" rx="14"/>
+    <rect class="app app-owned" x="940" y="442" width="200" height="100" rx="14"/>
+    <text class="app-title" x="1040" y="480" text-anchor="middle">[App B2]</text>
+    <text class="app-role" x="1040" y="504" text-anchor="middle">settlement</text>
+    <text class="app-owner" x="1040" y="526" text-anchor="middle">Owner: [team]</text>
+  </g>
+
+  <g class="application" data-application="shared-service">
+    <rect class="app-mask" x="640" y="646" width="320" height="64" rx="14"/>
+    <rect class="app app-shared" x="640" y="646" width="320" height="64" rx="14"/>
+    <text class="app-title" x="800" y="674" text-anchor="middle">[Shared Service]</text>
+    <text class="app-role" x="800" y="696" text-anchor="middle">events / identity / integration</text>
+  </g>
+
+  <g class="legend" transform="translate(400 748)">
+    <rect class="legend-panel" x="0" y="0" width="1108" height="76" rx="14"/>
+    <text class="legend-title" x="24" y="48">Legend</text>
+    <rect class="app app-service" x="130" y="40" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="164" y="52">Owned application</text>
+    <rect class="app app-shared" x="330" y="40" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="364" y="52">Shared platform</text>
+    <rect class="app app-vendor" x="510" y="40" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="544" y="52">Vendor / SaaS</text>
+    <line class="interface" x1="690" y1="47" x2="732" y2="47" marker-end="url(#arrow)"/>
+    <text class="legend-text" x="748" y="52">Synchronous interface</text>
+    <line class="interface interface-async" x1="940" y1="47" x2="982" y2="47" marker-end="url(#arrow-async)"/>
+    <text class="legend-text" x="998" y="52">Event / async</text>
+  </g>
+
+  <text class="footer" x="92" y="812">Generated by devspec - [DATE_OR_VERSION]</text>
+</svg>
diff --git a/devspec/architecture/_template/architecture-diagram.svg b/devspec/architecture/_template/architecture-diagram.svg
index 5b5ae2a..4293945 100644
--- a/devspec/architecture/_template/architecture-diagram.svg
+++ b/devspec/architecture/_template/architecture-diagram.svg
@@ -1,5 +1,5 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 900" role="img" aria-labelledby="title desc">
-  <title id="title">[DIAGRAM_TITLE]</title>
+  <title id="title">[DIAGRAM_TITLE] - System Architecture Diagram</title>
   <desc id="desc">[DIAGRAM_DESCRIPTION]</desc>
 
   <defs>
@@ -84,7 +84,6 @@
       <path d="M 0 0 L 10 5 L 0 10 z" fill="#fb923c"/>
     </marker>
   </defs>
-
   <rect class="page-bg" width="1600" height="900"/>
   <rect width="1600" height="900" fill="url(#grid)" opacity="0.42"/>
   <rect class="surface" x="48" y="42" width="1504" height="816" rx="20"/>
@@ -93,127 +92,129 @@
   <text class="title" x="92" y="138">[DIAGRAM_TITLE]</text>
   <text class="subtitle" x="92" y="168">[DIAGRAM_DESCRIPTION]</text>
 
-  <!-- Draw arrows before boundaries and nodes so connectors stay behind component boxes. -->
-  <path class="flow flow-security" d="M 250 330 C 345 255, 455 255, 550 330" marker-end="url(#arrow-security)"/>
-  <g transform="translate(387 248)">
+  <!-- Draw connectors before boundaries and nodes so every line stays behind the component cards.
+       Every connector starts on one node edge and ends on another node edge; none end in open space. -->
+
+  <path class="flow flow-security" d="M 324 408 L 492 408" marker-end="url(#arrow-security)"/>
+  <g transform="translate(352 408)">
     <circle class="step-badge" cx="0" cy="0" r="16"/>
     <text class="step-text" x="0" y="5" text-anchor="middle">1</text>
   </g>
-  <rect class="flow-label-bg" x="410" y="236" width="78" height="24" rx="7"/>
-  <text class="flow-label" x="449" y="253" text-anchor="middle">Sign in</text>
+  <rect class="flow-label-bg" x="368" y="396" width="72" height="24" rx="7"/>
+  <text class="flow-label" x="404" y="413" text-anchor="middle">Sign in</text>
 
-  <path class="flow" d="M 250 420 C 340 420, 460 420, 550 420" marker-end="url(#arrow)"/>
-  <g transform="translate(385 420)">
+  <path class="flow" d="M 712 408 L 880 408" marker-end="url(#arrow)"/>
+  <g transform="translate(758 408)">
     <circle class="step-badge" cx="0" cy="0" r="16"/>
     <text class="step-text" x="0" y="5" text-anchor="middle">2</text>
   </g>
-  <rect class="flow-label-bg" x="410" y="408" width="78" height="24" rx="7"/>
-  <text class="flow-label" x="449" y="425" text-anchor="middle">Request</text>
+  <rect class="flow-label-bg" x="784" y="396" width="82" height="24" rx="7"/>
+  <text class="flow-label" x="825" y="413" text-anchor="middle">Request</text>
 
-  <path class="flow" d="M 750 420 C 835 420, 925 420, 1010 420" marker-end="url(#arrow)"/>
-  <g transform="translate(872 420)">
+  <path class="flow flow-secondary" d="M 880 430 C 820 470, 740 502, 700 576" marker-end="url(#arrow-secondary)"/>
+  <g transform="translate(800 498)">
     <circle class="step-badge" cx="0" cy="0" r="16"/>
     <text class="step-text" x="0" y="5" text-anchor="middle">3</text>
   </g>
-  <rect class="flow-label-bg" x="898" y="408" width="76" height="24" rx="7"/>
-  <text class="flow-label" x="936" y="425" text-anchor="middle">Calls</text>
+  <rect class="flow-label-bg" x="826" y="486" width="86" height="24" rx="7"/>
+  <text class="flow-label" x="869" y="503" text-anchor="middle">Stores</text>
 
-  <path class="flow flow-secondary" d="M 650 488 C 650 548, 650 575, 650 635" marker-end="url(#arrow-secondary)"/>
-  <g transform="translate(650 556)">
+  <path class="flow flow-event" d="M 995 452 L 995 576" marker-end="url(#arrow-event)"/>
+  <g transform="translate(995 500)">
     <circle class="step-badge" cx="0" cy="0" r="16"/>
     <text class="step-text" x="0" y="5" text-anchor="middle">4</text>
   </g>
-  <rect class="flow-label-bg" x="672" y="544" width="86" height="24" rx="7"/>
-  <text class="flow-label" x="715" y="561" text-anchor="middle">Stores</text>
+  <rect class="flow-label-bg" x="1017" y="488" width="94" height="24" rx="7"/>
+  <text class="flow-label" x="1064" y="505" text-anchor="middle">Enqueue</text>
 
-  <path class="flow flow-event" d="M 750 470 C 850 585, 990 585, 1090 470" marker-end="url(#arrow-event)"/>
-  <g transform="translate(916 586)">
+  <path class="flow flow-event" d="M 1110 620 C 1220 620, 1320 570, 1378 452" marker-end="url(#arrow-event)"/>
+  <g transform="translate(1263 580)">
     <circle class="step-badge" cx="0" cy="0" r="16"/>
     <text class="step-text" x="0" y="5" text-anchor="middle">5</text>
   </g>
-  <rect class="flow-label-bg" x="942" y="574" width="86" height="24" rx="7"/>
-  <text class="flow-label" x="985" y="591" text-anchor="middle">Events</text>
+  <rect class="flow-label-bg" x="1290" y="596" width="76" height="24" rx="7"/>
+  <text class="flow-label" x="1328" y="613" text-anchor="middle">Calls</text>
 
   <g class="boundary-group" data-boundary="client-boundary">
-    <rect class="boundary boundary-client" x="104" y="250" width="210" height="260" rx="18"/>
-    <text class="boundary-title client" x="130" y="282">[CLIENT_BOUNDARY]</text>
+    <rect class="boundary boundary-client" x="104" y="300" width="250" height="190" rx="18"/>
+    <text class="boundary-title client" x="128" y="332">[CLIENT_BOUNDARY]</text>
   </g>
 
   <g class="boundary-group" data-boundary="application-boundary">
-    <rect class="boundary boundary-app" x="500" y="245" width="640" height="500" rx="20"/>
-    <text class="boundary-title app" x="528" y="278">[APPLICATION_BOUNDARY]</text>
+    <rect class="boundary boundary-app" x="430" y="248" width="740" height="470" rx="20"/>
+    <text class="boundary-title app" x="456" y="280">[APPLICATION_BOUNDARY]</text>
   </g>
 
   <g class="boundary-group" data-boundary="external-boundary">
-    <rect class="boundary boundary-external" x="1200" y="250" width="265" height="260" rx="18"/>
-    <text class="boundary-title external" x="1228" y="282">[EXTERNAL_BOUNDARY]</text>
+    <rect class="boundary boundary-external" x="1246" y="300" width="264" height="190" rx="18"/>
+    <text class="boundary-title external" x="1270" y="332">[EXTERNAL_BOUNDARY]</text>
   </g>
 
   <g class="boundary-group" data-boundary="security-boundary">
-    <rect class="boundary boundary-security" x="520" y="304" width="250" height="206" rx="16"/>
-    <text class="boundary-title security" x="546" y="334">[SECURITY_BOUNDARY]</text>
+    <rect class="boundary boundary-security" x="462" y="318" width="270" height="156" rx="16"/>
+    <text class="boundary-title security" x="484" y="346">[SECURITY_BOUNDARY]</text>
   </g>
 
   <g class="component" data-component="user-client">
-    <rect class="node-mask" x="142" y="338" width="172" height="92" rx="12"/>
-    <rect class="node node-frontend" x="142" y="338" width="172" height="92" rx="12"/>
-    <text class="node-title" x="228" y="373" text-anchor="middle">User Client</text>
-    <text class="node-meta" x="228" y="398" text-anchor="middle">Actor Entry</text>
-    <text class="node-tag" x="228" y="420" text-anchor="middle">Replace me</text>
+    <rect class="node-mask" x="134" y="364" width="190" height="88" rx="12"/>
+    <rect class="node node-frontend" x="134" y="364" width="190" height="88" rx="12"/>
+    <text class="node-title" x="229" y="396" text-anchor="middle">User Client</text>
+    <text class="node-meta" x="229" y="419" text-anchor="middle">Actor Entry</text>
+    <text class="node-tag" x="229" y="440" text-anchor="middle">Replace me</text>
   </g>
 
   <g class="component" data-component="security-control">
-    <rect class="node-mask" x="550" y="350" width="200" height="86" rx="12"/>
-    <rect class="node node-security" x="550" y="350" width="200" height="86" rx="12"/>
-    <text class="node-title" x="650" y="383" text-anchor="middle">Security</text>
-    <text class="node-meta" x="650" y="406" text-anchor="middle">Policy Checks</text>
-    <text class="node-tag" x="650" y="427" text-anchor="middle">Replace me</text>
+    <rect class="node-mask" x="492" y="364" width="220" height="88" rx="12"/>
+    <rect class="node node-security" x="492" y="364" width="220" height="88" rx="12"/>
+    <text class="node-title" x="602" y="396" text-anchor="middle">Security</text>
+    <text class="node-meta" x="602" y="419" text-anchor="middle">Policy Checks</text>
+    <text class="node-tag" x="602" y="440" text-anchor="middle">Replace me</text>
   </g>
 
   <g class="component" data-component="orchestration-service">
-    <rect class="node-mask" x="800" y="350" width="210" height="86" rx="12"/>
-    <rect class="node node-backend" x="800" y="350" width="210" height="86" rx="12"/>
-    <text class="node-title" x="905" y="383" text-anchor="middle">Core Service</text>
-    <text class="node-meta" x="905" y="406" text-anchor="middle">Orchestration</text>
-    <text class="node-tag" x="905" y="427" text-anchor="middle">Replace me</text>
+    <rect class="node-mask" x="880" y="364" width="230" height="88" rx="12"/>
+    <rect class="node node-backend" x="880" y="364" width="230" height="88" rx="12"/>
+    <text class="node-title" x="995" y="396" text-anchor="middle">Core Service</text>
+    <text class="node-meta" x="995" y="419" text-anchor="middle">Orchestration</text>
+    <text class="node-tag" x="995" y="440" text-anchor="middle">Replace me</text>
   </g>
 
-  <g class="component" data-component="data-store">
-    <rect class="node-mask" x="550" y="635" width="200" height="86" rx="12"/>
-    <rect class="node node-data" x="550" y="635" width="200" height="86" rx="12"/>
-    <text class="node-title" x="650" y="668" text-anchor="middle">Data Store</text>
-    <text class="node-meta" x="650" y="691" text-anchor="middle">Owned Data</text>
-    <text class="node-tag" x="650" y="712" text-anchor="middle">Replace me</text>
+  <g class="component" data-component="external-system">
+    <rect class="node-mask" x="1276" y="364" width="204" height="88" rx="12"/>
+    <rect class="node node-external" x="1276" y="364" width="204" height="88" rx="12"/>
+    <text class="node-title" x="1378" y="396" text-anchor="middle">External API</text>
+    <text class="node-meta" x="1378" y="419" text-anchor="middle">Third Party</text>
+    <text class="node-tag" x="1378" y="440" text-anchor="middle">Replace me</text>
   </g>
 
-  <g class="component" data-component="worker">
-    <rect class="node-mask" x="850" y="635" width="200" height="86" rx="12"/>
-    <rect class="node node-event" x="850" y="635" width="200" height="86" rx="12"/>
-    <text class="node-title" x="950" y="668" text-anchor="middle">Worker</text>
-    <text class="node-meta" x="950" y="691" text-anchor="middle">Async Flow</text>
-    <text class="node-tag" x="950" y="712" text-anchor="middle">Replace me</text>
+  <g class="component" data-component="data-store">
+    <rect class="node-mask" x="492" y="576" width="220" height="88" rx="12"/>
+    <rect class="node node-data" x="492" y="576" width="220" height="88" rx="12"/>
+    <text class="node-title" x="602" y="608" text-anchor="middle">Data Store</text>
+    <text class="node-meta" x="602" y="631" text-anchor="middle">Owned Data</text>
+    <text class="node-tag" x="602" y="652" text-anchor="middle">Replace me</text>
   </g>
 
-  <g class="component" data-component="external-system">
-    <rect class="node-mask" x="1235" y="344" width="200" height="92" rx="12"/>
-    <rect class="node node-external" x="1235" y="344" width="200" height="92" rx="12"/>
-    <text class="node-title" x="1335" y="379" text-anchor="middle">External API</text>
-    <text class="node-meta" x="1335" y="404" text-anchor="middle">Third Party</text>
-    <text class="node-tag" x="1335" y="426" text-anchor="middle">Replace me</text>
+  <g class="component" data-component="worker">
+    <rect class="node-mask" x="880" y="576" width="230" height="88" rx="12"/>
+    <rect class="node node-event" x="880" y="576" width="230" height="88" rx="12"/>
+    <text class="node-title" x="995" y="608" text-anchor="middle">Worker</text>
+    <text class="node-meta" x="995" y="631" text-anchor="middle">Async Flow</text>
+    <text class="node-tag" x="995" y="652" text-anchor="middle">Replace me</text>
   </g>
 
-  <g class="legend" transform="translate(1040 690)">
-    <rect class="legend-panel" x="0" y="0" width="420" height="112" rx="14"/>
+  <g class="legend" transform="translate(104 560)">
+    <rect class="legend-panel" x="0" y="0" width="300" height="186" rx="14"/>
     <text class="legend-title" x="24" y="32">Legend</text>
-    <circle class="step-badge" cx="34" cy="62" r="12"/>
-    <text class="step-text" x="34" y="67" text-anchor="middle">1</text>
-    <text class="legend-text" x="58" y="67">Numbered data or control flow</text>
-    <rect class="node node-backend" x="250" y="52" width="22" height="14" rx="4"/>
-    <text class="legend-text" x="284" y="64">Owned service</text>
-    <line class="flow flow-secondary" x1="24" y1="88" x2="66" y2="88" marker-end="url(#arrow-secondary)"/>
-    <text class="legend-text" x="82" y="92">Optional or async flow</text>
-    <rect class="boundary boundary-security" x="250" y="80" width="22" height="14" rx="3"/>
-    <text class="legend-text" x="284" y="92">Boundary</text>
+    <circle class="step-badge" cx="34" cy="58" r="12"/>
+    <text class="step-text" x="34" y="63" text-anchor="middle">1</text>
+    <text class="legend-text" x="58" y="63">Numbered flow</text>
+    <rect class="node node-backend" x="24" y="85" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="58" y="97">Owned service</text>
+    <line class="flow flow-secondary" x1="24" y1="126" x2="66" y2="126" marker-end="url(#arrow-secondary)"/>
+    <text class="legend-text" x="82" y="130">Optional or async flow</text>
+    <rect class="boundary boundary-security" x="24" y="153" width="22" height="14" rx="3"/>
+    <text class="legend-text" x="58" y="165">Boundary</text>
   </g>
 
   <text class="footer" x="92" y="812">Generated by devspec - [DATE_OR_VERSION]</text>
diff --git a/devspec/architecture/_template/diagram-sample.md b/devspec/architecture/_template/diagram-sample.md
index 0b4803b..a955009 100644
--- a/devspec/architecture/_template/diagram-sample.md
+++ b/devspec/architecture/_template/diagram-sample.md
@@ -2,7 +2,7 @@
 
 Use this compact worked example as a pattern for the record. Replace every value with repository evidence; queue state belongs only in artifact-queue.md.
 
-The accompanying `diagram-sample.svg` is deliberately small so the pattern stays readable. A real diagram starts from the matching family template in this directory and keeps its 1600 by 900 canvas, as `diagram-types.md` requires.
+The accompanying `diagram-sample.svg` is a completed worked example on the shared 1600 by 900 canvas, so it shows the visual contract a real diagram must meet. A real diagram still starts from the matching family template in this directory rather than from this sample.
 
 ## Brief
 
diff --git a/devspec/architecture/_template/diagram-sample.svg b/devspec/architecture/_template/diagram-sample.svg
index 46cea2a..1d5cd3e 100644
--- a/devspec/architecture/_template/diagram-sample.svg
+++ b/devspec/architecture/_template/diagram-sample.svg
@@ -1 +1,140 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 400" role="img" aria-labelledby="title desc"><title id="title">Customer request routing sample</title><desc id="desc">A confirmed request is routed to a localized quickfix or to a traceable work item based on scope and risk.</desc><style>.bg{fill:#070b18}.surface{fill:#101827;stroke:#263653}.lane{fill:#0c1323;stroke:#263653;stroke-dasharray:6 7}.eyebrow{font:700 11px system-ui,sans-serif;letter-spacing:1.8px;fill:#69d8ff}.title{font:700 24px system-ui,sans-serif;fill:#f8fafc}.sub{font:13px system-ui,sans-serif;fill:#aab8cf}.card{fill:#16223a;stroke:#35517c;stroke-width:1.5}.quick{fill:#3a2b10;stroke:#ffc857}.start{fill:#123745;stroke:#39c9d9}.decision{fill:#1d3450;stroke:#69d8ff;stroke-width:2}.node{font:700 14px system-ui,sans-serif;fill:#f8fafc}.meta{font:11px system-ui,sans-serif;fill:#aab8cf}.flow{fill:none;stroke:#69d8ff;stroke-width:2.4;marker-end:url(#a)}.gold{fill:none;stroke:#ffc857;stroke-width:2.4;marker-end:url(#g)}.label{font:700 11px system-ui,sans-serif;fill:#ffd978}.foot{font:600 10px system-ui,sans-serif;letter-spacing:1px;fill:#6f86a8}</style><defs><pattern id="grid" width="28" height="28" patternUnits="userSpaceOnUse"><path d="M28 0H0V28" fill="none" stroke="#14213a"/></pattern><marker id="a" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto"><path d="M0,0 L0,6 L8,3z" fill="#69d8ff"/></marker><marker id="g" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto"><path d="M0,0 L0,6 L8,3z" fill="#ffc857"/></marker></defs><rect class="bg" width="960" height="400"/><rect fill="url(#grid)" width="960" height="400"/><rect class="surface" x="22" y="22" width="916" height="356" rx="18"/><text x="52" y="57" class="eyebrow">DEVSPEC LITE / PROCESS FLOW SAMPLE</text><text x="52" y="88" class="title">Customer request routing</text><text x="52" y="111" class="sub">Use confirmed scope and risk to select one durable route.</text><rect class="lane" x="52" y="138" width="856" height="168" rx="12"/><rect class="card start" x="86" y="205" width="142" height="54" rx="9"/><text x="106" y="228" class="node">Request</text><text x="106" y="247" class="meta">confirmed need</text><polygon class="decision" points="338,190 396,232 338,274 280,232"/><text x="338" y="228" text-anchor="middle" class="node">Local +</text><text x="338" y="246" text-anchor="middle" class="node">low risk?</text><rect class="card quick" x="500" y="164" width="166" height="54" rx="9"/><text x="520" y="187" class="node">quickfix</text><text x="520" y="206" class="meta">focused validation</text><rect class="card" x="500" y="250" width="166" height="54" rx="9"/><text x="520" y="273" class="node">work item</text><text x="520" y="292" class="meta">story to review</text><rect class="card" x="740" y="205" width="130" height="54" rx="9"/><text x="760" y="228" class="node">Record</text><text x="760" y="247" class="meta">evidence + next</text><path class="flow" d="M228 232H280"/><path class="gold" d="M396 211H450V191H500M666 191H705V232H740"/><path class="flow" d="M396 253H450V277H500M666 277H705V232H740"/><text x="420" y="199" class="label">YES</text><text x="416" y="270" class="label">NO / RISK</text><text x="52" y="345" class="foot">EVIDENCE: QUICKFIX + STORY CONTRACTS • TYPE: PROCESS FLOW • STATUS: COMPLETE</text></svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 900" role="img" aria-labelledby="title desc">
+  <title id="title">Customer request routing - Process Flow Sample</title>
+  <desc id="desc">A confirmed request is routed to a localized quickfix or to a traceable work item based on scope and risk, and either route ends in one durable record.</desc>
+
+  <defs>
+    <style><![CDATA[
+      svg {
+        background: #020617;
+        font-family: "JetBrains Mono", "Cascadia Code", monospace;
+      }
+
+      .page-bg { fill: #020617; }
+      .grid-line { stroke: #1e293b; stroke-width: 0.7; opacity: 0.65; }
+      .surface { fill: #0f172a; stroke: #1e293b; stroke-width: 1.4; filter: url(#soft-shadow); }
+      .title { fill: #f8fafc; font-size: 38px; font-weight: 800; }
+      .subtitle { fill: #cbd5e1; font-size: 16px; font-weight: 500; }
+      .eyebrow { fill: #67e8f9; font-size: 13px; font-weight: 800; letter-spacing: 1.6px; }
+      .footer { fill: #64748b; font-size: 12px; }
+
+      .lane { fill: rgba(15, 23, 42, 0.22); stroke: #334155; stroke-width: 1.2; stroke-dasharray: 8 8; }
+      .lane-title { fill: #6ee7b7; font-size: 13px; font-weight: 900; letter-spacing: 1.2px; }
+
+      .step-mask { fill: #0f172a; }
+      .step { stroke-width: 1.8; filter: url(#node-glow); }
+      .step-boundary { fill: rgba(8, 51, 68, 0.46); stroke: #22d3ee; }
+      .step-integration { fill: rgba(120, 53, 15, 0.40); stroke: #fbbf24; }
+      .step-automated { fill: rgba(76, 29, 149, 0.46); stroke: #a78bfa; }
+      .step-review { fill: rgba(6, 78, 59, 0.46); stroke: #34d399; }
+      .decision { fill: rgba(136, 19, 55, 0.46); stroke: #fb7185; stroke-width: 2; }
+
+      .step-title { fill: #f8fafc; font-size: 16px; font-weight: 800; }
+      .step-detail { fill: #cbd5e1; font-size: 12px; font-weight: 600; }
+      .decision-text { fill: #f8fafc; font-size: 15px; font-weight: 800; }
+
+      .flow { fill: none; stroke: #e2e8f0; stroke-width: 2.4; }
+      .flow-alt { stroke: #fbbf24; }
+      .flow-label-bg { fill: #0f172a; stroke: #334155; stroke-width: 1; }
+      .flow-label { fill: #f8fafc; font-size: 12px; font-weight: 800; }
+
+      .legend-panel { fill: rgba(15, 23, 42, 0.86); stroke: #334155; stroke-width: 1.2; }
+      .legend-title { fill: #f8fafc; font-size: 14px; font-weight: 800; }
+      .legend-text { fill: #cbd5e1; font-size: 12px; font-weight: 600; }
+    ]]></style>
+
+    <pattern id="grid" width="48" height="48" patternUnits="userSpaceOnUse">
+      <path class="grid-line" d="M 48 0 L 0 0 0 48" fill="none"/>
+    </pattern>
+
+    <filter id="soft-shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="22" stdDeviation="22" flood-color="#000000" flood-opacity="0.34"/>
+    </filter>
+
+    <filter id="node-glow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="0" stdDeviation="5" flood-color="#38bdf8" flood-opacity="0.16"/>
+    </filter>
+
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#e2e8f0"/>
+    </marker>
+
+    <marker id="arrow-alt" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#fbbf24"/>
+    </marker>
+  </defs>
+
+  <rect class="page-bg" width="1600" height="900"/>
+  <rect width="1600" height="900" fill="url(#grid)" opacity="0.42"/>
+  <rect class="surface" x="48" y="42" width="1504" height="816" rx="20"/>
+
+  <text class="eyebrow" x="92" y="92">DEVSPEC LITE / PROCESS FLOW SAMPLE</text>
+  <text class="title" x="92" y="138">Customer request routing</text>
+  <text class="subtitle" x="92" y="168">Use confirmed scope and risk to select one durable route.</text>
+
+  <rect class="lane" x="92" y="250" width="1416" height="380" rx="16"/>
+  <text class="lane-title" x="118" y="284">CONFIRMED ROUTE</text>
+
+  <!-- Connectors are drawn before the cards, so every arrowhead lands on a card edge and no label sits on a corner. -->
+  <path class="flow" d="M 370 422 H 475" marker-end="url(#arrow)"/>
+
+  <path class="flow flow-alt" d="M 645 422 H 706 V 354 H 790" marker-end="url(#arrow-alt)"/>
+  <rect class="flow-label-bg" x="716" y="342" width="56" height="24" rx="7"/>
+  <text class="flow-label" x="744" y="359" text-anchor="middle">YES</text>
+
+  <path class="flow" d="M 560 497 V 518 H 790" marker-end="url(#arrow)"/>
+  <rect class="flow-label-bg" x="612" y="506" width="104" height="24" rx="7"/>
+  <text class="flow-label" x="664" y="523" text-anchor="middle">NO / RISK</text>
+
+  <path class="flow flow-alt" d="M 1040 354 H 1130 V 422 H 1200" marker-end="url(#arrow-alt)"/>
+  <path class="flow" d="M 1040 518 H 1130 V 422 H 1200" marker-end="url(#arrow)"/>
+
+  <g data-step="request">
+    <rect class="step-mask" x="140" y="376" width="230" height="92" rx="14"/>
+    <rect class="step step-boundary" x="140" y="376" width="230" height="92" rx="14"/>
+    <text class="step-title" x="255" y="412" text-anchor="middle">Request</text>
+    <text class="step-detail" x="255" y="437" text-anchor="middle">confirmed need</text>
+  </g>
+
+  <g data-step="decision">
+    <polygon class="step-mask" points="560,347 645,422 560,497 475,422"/>
+    <polygon class="decision" points="560,347 645,422 560,497 475,422"/>
+    <text class="decision-text" x="560" y="416" text-anchor="middle">Local +</text>
+    <text class="decision-text" x="560" y="438" text-anchor="middle">low risk?</text>
+  </g>
+
+  <g data-step="quickfix">
+    <rect class="step-mask" x="790" y="306" width="250" height="96" rx="14"/>
+    <rect class="step step-integration" x="790" y="306" width="250" height="96" rx="14"/>
+    <text class="step-title" x="915" y="344" text-anchor="middle">quickfix</text>
+    <text class="step-detail" x="915" y="369" text-anchor="middle">focused validation</text>
+  </g>
+
+  <g data-step="work-item">
+    <rect class="step-mask" x="790" y="470" width="250" height="96" rx="14"/>
+    <rect class="step step-automated" x="790" y="470" width="250" height="96" rx="14"/>
+    <text class="step-title" x="915" y="508" text-anchor="middle">work item</text>
+    <text class="step-detail" x="915" y="533" text-anchor="middle">story to review</text>
+  </g>
+
+  <g data-step="record">
+    <rect class="step-mask" x="1200" y="376" width="250" height="92" rx="14"/>
+    <rect class="step step-review" x="1200" y="376" width="250" height="92" rx="14"/>
+    <text class="step-title" x="1325" y="412" text-anchor="middle">Record</text>
+    <text class="step-detail" x="1325" y="437" text-anchor="middle">evidence + next</text>
+  </g>
+
+  <g class="legend" transform="translate(92 676)">
+    <rect class="legend-panel" x="0" y="0" width="900" height="76" rx="14"/>
+    <text class="legend-title" x="24" y="48">Legend</text>
+    <rect class="step step-boundary" x="130" y="40" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="164" y="52">Entry</text>
+    <polygon class="decision" points="290,40 304,54 290,68 276,54"/>
+    <text class="legend-text" x="318" y="58">Decision</text>
+    <rect class="step step-integration" x="450" y="40" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="484" y="52">Quickfix route</text>
+    <rect class="step step-automated" x="640" y="40" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="674" y="52">Work-item route</text>
+  </g>
+
+  <text class="footer" x="92" y="812">EVIDENCE: QUICKFIX + STORY CONTRACTS - TYPE: PROCESS FLOW - STATUS: COMPLETE</text>
+</svg>
diff --git a/devspec/architecture/_template/diagram-types.md b/devspec/architecture/_template/diagram-types.md
index af033a8..9bd63b8 100644
--- a/devspec/architecture/_template/diagram-types.md
+++ b/devspec/architecture/_template/diagram-types.md
@@ -30,7 +30,9 @@ Use the smallest diagram that makes a confirmed relationship easier to understan
 
 | Diagram type | SVG template |
 |---|---|
-| System architecture, application landscape, infrastructure topology | `architecture-diagram.svg` |
+| System architecture | `architecture-diagram.svg` |
+| Application landscape | `application-landscape-diagram.svg` |
+| Infrastructure topology | `infrastructure-topology-diagram.svg` |
 | Process flow | `process-flow-diagram.svg` |
 | Sequence | `sequence-diagram.svg` |
 | State lifecycle | `state-lifecycle-diagram.svg` |
@@ -44,6 +46,10 @@ Use the smallest diagram that makes a confirmed relationship easier to understan
 
 Do not infer entities, callers, timelines, ownership, user sentiment, or priorities. Record uncertain information in the work item or decisions file, not as a factual diagram label. Keep a flowchart to one primary concern; split a diagram that cannot remain readable instead of shrinking text or crossing unrelated flows.
 
+The journey template ships a signal row. Keep it only when a measured or user-confirmed signal supports every point; delete the row and its legend entry otherwise, because an unmeasured curve is inferred sentiment.
+
+Every connector must start on one shape edge and end on another. A line that begins or ends in open space, or whose arrowhead is hidden behind the shape it points at, states a relationship the diagram does not actually show. Keep label backgrounds clear of boundary strokes and other labels, and keep every colour that appears on a shape present in the legend.
+
 ## Opt-in motion
 
 Use motion only for `motion=explain`, and only when an evidence-backed order or transition helps the reader understand the diagram. A plain request for an animated diagram selects this mode. Static SVG remains the default.
diff --git a/devspec/architecture/_template/diagram.md b/devspec/architecture/_template/diagram.md
index 79e0892..b8be2cc 100644
--- a/devspec/architecture/_template/diagram.md
+++ b/devspec/architecture/_template/diagram.md
@@ -85,7 +85,7 @@ flowchart TD
 - Use this section when `Output format` includes `svg` or `html`.
 - Store the durable SVG at `devspec/architecture/diagrams/dia-###-<diagram-name>.svg`.
 - Store optional standalone HTML at `devspec/architecture/diagrams/dia-###-<diagram-name>.html`.
-- Select SVG templates from `devspec/architecture/_template/`: `architecture-diagram.svg`, `process-flow-diagram.svg`, `sequence-diagram.svg`, `state-lifecycle-diagram.svg`, `domain-model-diagram.svg`, `journey-map-diagram.svg`, `timeline-plan-diagram.svg`, `quadrant-analysis-diagram.svg`, or `mindmap-diagram.svg`. Every template must preserve the shared dark architecture-style visual contract unless a documented constraint requires a smaller custom SVG.
+- Select SVG templates from `devspec/architecture/_template/`: `architecture-diagram.svg`, `application-landscape-diagram.svg`, `infrastructure-topology-diagram.svg`, `process-flow-diagram.svg`, `sequence-diagram.svg`, `state-lifecycle-diagram.svg`, `domain-model-diagram.svg`, `journey-map-diagram.svg`, `timeline-plan-diagram.svg`, `quadrant-analysis-diagram.svg`, or `mindmap-diagram.svg`. Every template must preserve the shared dark architecture-style visual contract unless a documented constraint requires a smaller custom SVG.
 - Generated SVG must be standalone XML with inline styles and no external assets, `<script>`, `<iframe>`, `<foreignObject>`, remote fonts, remote images, secrets, credentials, internal-only URLs, or unresolved placeholders.
 - Generated HTML must be standalone static HTML with inline styles and no external assets, `<script>`, `<iframe>`, remote fonts, remote images, secrets, credentials, internal-only URLs, or unresolved placeholders.
 - Validate the SVG as XML before reporting generation complete.
diff --git a/devspec/architecture/_template/domain-model-diagram.svg b/devspec/architecture/_template/domain-model-diagram.svg
index c7bfa13..86e37aa 100644
--- a/devspec/architecture/_template/domain-model-diagram.svg
+++ b/devspec/architecture/_template/domain-model-diagram.svg
@@ -85,10 +85,10 @@
   <path class="relation" d="M 955 400 C 1060 400, 1140 400, 1245 400" marker-end="url(#arrow)"/>
   <text class="cardinality" x="982" y="388">1</text>
   <text class="cardinality" x="1210" y="388">*</text>
-  <rect class="relation-label-bg" x="1080" y="388" width="84" height="24" rx="7"/>
-  <text class="relation-label" x="1122" y="405" text-anchor="middle">Uses</text>
+  <rect class="relation-label-bg" x="1010" y="388" width="84" height="24" rx="7"/>
+  <text class="relation-label" x="1052" y="405" text-anchor="middle">Uses</text>
 
-  <path class="relation relation-secondary" d="M 830 550 C 830 625, 830 655, 830 730" marker-end="url(#arrow-secondary)"/>
+  <path class="relation relation-secondary" d="M 830 470 C 830 560, 830 640, 830 730" marker-end="url(#arrow-secondary)"/>
   <rect class="relation-label-bg" x="852" y="632" width="94" height="24" rx="7"/>
   <text class="relation-label" x="899" y="649" text-anchor="middle">Stores</text>
 
diff --git a/devspec/architecture/_template/infrastructure-topology-diagram.svg b/devspec/architecture/_template/infrastructure-topology-diagram.svg
new file mode 100644
index 0000000..24d22c9
--- /dev/null
+++ b/devspec/architecture/_template/infrastructure-topology-diagram.svg
@@ -0,0 +1,193 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 900" role="img" aria-labelledby="title desc">
+  <title id="title">[DIAGRAM_TITLE] - Infrastructure Topology Diagram</title>
+  <desc id="desc">[DIAGRAM_DESCRIPTION]</desc>
+
+  <defs>
+    <style><![CDATA[
+      svg {
+        background: #020617;
+        font-family: "JetBrains Mono", "Cascadia Code", monospace;
+      }
+
+      .page-bg { fill: #020617; }
+      .grid-line { stroke: #1e293b; stroke-width: 0.7; opacity: 0.65; }
+      .surface { fill: #0f172a; stroke: #1e293b; stroke-width: 1.4; filter: url(#soft-shadow); }
+      .title { fill: #f8fafc; font-size: 38px; font-weight: 800; }
+      .subtitle { fill: #cbd5e1; font-size: 16px; font-weight: 500; }
+      .eyebrow { fill: #67e8f9; font-size: 13px; font-weight: 800; letter-spacing: 1.6px; }
+      .footer { fill: #64748b; font-size: 12px; }
+
+      .environment { fill: rgba(15, 23, 42, 0.24); stroke: #334155; stroke-width: 1.3; stroke-dasharray: 10 8; }
+      .environment-title { fill: #94a3b8; font-size: 13px; font-weight: 900; letter-spacing: 1.2px; }
+
+      .zone { fill: rgba(15, 23, 42, 0.20); stroke-width: 1.6; stroke-dasharray: 8 7; }
+      .zone-provider { stroke: #34d399; }
+      .zone-external { stroke: #fbbf24; }
+      .zone-title { font-size: 13px; font-weight: 800; letter-spacing: 0.7px; }
+      .zone-title.provider { fill: #6ee7b7; }
+      .zone-title.external { fill: #fcd34d; }
+
+      .node-mask { fill: #0f172a; }
+      .node { stroke-width: 1.8; filter: url(#node-glow); }
+      .node-edge { fill: rgba(8, 51, 68, 0.46); stroke: #22d3ee; }
+      .node-compute { fill: rgba(6, 78, 59, 0.46); stroke: #34d399; }
+      .node-data { fill: rgba(76, 29, 149, 0.46); stroke: #a78bfa; }
+      .node-external { fill: rgba(120, 53, 15, 0.40); stroke: #fbbf24; }
+
+      .node-title { fill: #f8fafc; font-size: 16px; font-weight: 800; }
+      .node-meta { fill: #cbd5e1; font-size: 12px; font-weight: 600; }
+      .node-tag { fill: #94a3b8; font-size: 11px; font-weight: 600; }
+
+      .link { fill: none; stroke: #e2e8f0; stroke-width: 2.2; opacity: 0.92; }
+      .link-secondary { stroke: #94a3b8; stroke-dasharray: 8 6; }
+      .link-label-bg { fill: #0f172a; stroke: #334155; stroke-width: 1; }
+      .link-label { fill: #f8fafc; font-size: 12px; font-weight: 800; }
+
+      .legend-panel { fill: rgba(15, 23, 42, 0.86); stroke: #334155; stroke-width: 1.2; }
+      .legend-title { fill: #f8fafc; font-size: 14px; font-weight: 800; }
+      .legend-text { fill: #cbd5e1; font-size: 12px; font-weight: 600; }
+    ]]></style>
+
+    <pattern id="grid" width="48" height="48" patternUnits="userSpaceOnUse">
+      <path class="grid-line" d="M 48 0 L 0 0 0 48" fill="none"/>
+    </pattern>
+
+    <filter id="soft-shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="22" stdDeviation="22" flood-color="#000000" flood-opacity="0.34"/>
+    </filter>
+
+    <filter id="node-glow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="0" stdDeviation="5" flood-color="#38bdf8" flood-opacity="0.16"/>
+    </filter>
+
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#e2e8f0"/>
+    </marker>
+
+    <marker id="arrow-secondary" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#94a3b8"/>
+    </marker>
+  </defs>
+
+  <rect class="page-bg" width="1600" height="900"/>
+  <rect width="1600" height="900" fill="url(#grid)" opacity="0.42"/>
+  <rect class="surface" x="48" y="42" width="1504" height="816" rx="20"/>
+
+  <text class="eyebrow" x="92" y="92">[PROJECT_NAME]</text>
+  <text class="title" x="92" y="138">[DIAGRAM_TITLE]</text>
+  <text class="subtitle" x="92" y="168">[DIAGRAM_DESCRIPTION]</text>
+
+  <g data-environment="primary">
+    <rect class="environment" x="104" y="214" width="1404" height="276" rx="20"/>
+    <text class="environment-title" x="130" y="242">[ENVIRONMENT_PRIMARY]</text>
+  </g>
+
+  <g data-environment="secondary">
+    <rect class="environment" x="104" y="546" width="1404" height="168" rx="20"/>
+    <text class="environment-title" x="130" y="574">[ENVIRONMENT_SECONDARY]</text>
+  </g>
+
+  <g data-zone="primary-provider">
+    <rect class="zone zone-provider" x="140" y="256" width="900" height="202" rx="16"/>
+    <text class="zone-title provider" x="164" y="282">[PROVIDER_OR_REGION]</text>
+  </g>
+
+  <g data-zone="primary-external">
+    <rect class="zone zone-external" x="1140" y="256" width="340" height="202" rx="16"/>
+    <text class="zone-title external" x="1164" y="282">[EXTERNAL_DEPENDENCY]</text>
+  </g>
+
+  <g data-zone="secondary-provider">
+    <rect class="zone zone-provider" x="140" y="582" width="900" height="118" rx="16"/>
+    <text class="zone-title provider" x="164" y="606">[PROVIDER_OR_REGION]</text>
+  </g>
+
+  <!-- Draw links before nodes so connectors stay behind the cards.
+       Every link starts and ends on a node edge; labels name the protocol or channel, not a step order. -->
+  <path class="link" d="M 376 336 L 496 336" marker-end="url(#arrow)"/>
+  <rect class="link-label-bg" x="404" y="324" width="66" height="24" rx="7"/>
+  <text class="link-label" x="437" y="341" text-anchor="middle">HTTPS</text>
+
+  <path class="link" d="M 696 336 L 816 336" marker-end="url(#arrow)"/>
+  <rect class="link-label-bg" x="726" y="324" width="60" height="24" rx="7"/>
+  <text class="link-label" x="756" y="341" text-anchor="middle">TLS</text>
+
+  <path class="link" d="M 596 384 C 596 428, 1310 428, 1310 384" marker-end="url(#arrow)"/>
+  <rect class="link-label-bg" x="906" y="405" width="88" height="24" rx="7"/>
+  <text class="link-label" x="950" y="422" text-anchor="middle">Egress</text>
+
+  <path class="link link-secondary" d="M 916 384 L 916 588" marker-end="url(#arrow-secondary)"/>
+  <rect class="link-label-bg" x="938" y="506" width="118" height="24" rx="7"/>
+  <text class="link-label" x="997" y="523" text-anchor="middle">Replication</text>
+
+  <path class="link" d="M 696 631 L 816 631" marker-end="url(#arrow)"/>
+  <rect class="link-label-bg" x="726" y="619" width="60" height="24" rx="7"/>
+  <text class="link-label" x="756" y="636" text-anchor="middle">TLS</text>
+
+  <g class="node-group" data-node="edge">
+    <rect class="node-mask" x="176" y="288" width="200" height="96" rx="12"/>
+    <rect class="node node-edge" x="176" y="288" width="200" height="96" rx="12"/>
+    <text class="node-title" x="276" y="322" text-anchor="middle">Edge</text>
+    <text class="node-meta" x="276" y="346" text-anchor="middle">Ingress / DNS</text>
+    <text class="node-tag" x="276" y="368" text-anchor="middle">Replace me</text>
+  </g>
+
+  <g class="node-group" data-node="runtime">
+    <rect class="node-mask" x="496" y="288" width="200" height="96" rx="12"/>
+    <rect class="node node-compute" x="496" y="288" width="200" height="96" rx="12"/>
+    <text class="node-title" x="596" y="322" text-anchor="middle">Runtime Host</text>
+    <text class="node-meta" x="596" y="346" text-anchor="middle">Compute</text>
+    <text class="node-tag" x="596" y="368" text-anchor="middle">Replace me</text>
+  </g>
+
+  <g class="node-group" data-node="managed-data">
+    <rect class="node-mask" x="816" y="288" width="200" height="96" rx="12"/>
+    <rect class="node node-data" x="816" y="288" width="200" height="96" rx="12"/>
+    <text class="node-title" x="916" y="322" text-anchor="middle">Managed Data</text>
+    <text class="node-meta" x="916" y="346" text-anchor="middle">Primary store</text>
+    <text class="node-tag" x="916" y="368" text-anchor="middle">Replace me</text>
+  </g>
+
+  <g class="node-group" data-node="external-service">
+    <rect class="node-mask" x="1180" y="288" width="260" height="96" rx="12"/>
+    <rect class="node node-external" x="1180" y="288" width="260" height="96" rx="12"/>
+    <text class="node-title" x="1310" y="322" text-anchor="middle">Third-Party API</text>
+    <text class="node-meta" x="1310" y="346" text-anchor="middle">Outside control</text>
+    <text class="node-tag" x="1310" y="368" text-anchor="middle">Replace me</text>
+  </g>
+
+  <g class="node-group" data-node="standby-runtime">
+    <rect class="node-mask" x="496" y="588" width="200" height="86" rx="12"/>
+    <rect class="node node-compute" x="496" y="588" width="200" height="86" rx="12"/>
+    <text class="node-title" x="596" y="620" text-anchor="middle">Standby Host</text>
+    <text class="node-meta" x="596" y="643" text-anchor="middle">Compute</text>
+    <text class="node-tag" x="596" y="664" text-anchor="middle">Replace me</text>
+  </g>
+
+  <g class="node-group" data-node="replica-data">
+    <rect class="node-mask" x="816" y="588" width="200" height="86" rx="12"/>
+    <rect class="node node-data" x="816" y="588" width="200" height="86" rx="12"/>
+    <text class="node-title" x="916" y="620" text-anchor="middle">Replica Data</text>
+    <text class="node-meta" x="916" y="643" text-anchor="middle">Read replica</text>
+    <text class="node-tag" x="916" y="664" text-anchor="middle">Replace me</text>
+  </g>
+
+  <g class="legend" transform="translate(400 730)">
+    <rect class="legend-panel" x="0" y="0" width="1108" height="76" rx="14"/>
+    <text class="legend-title" x="24" y="48">Legend</text>
+    <rect class="node node-edge" x="130" y="40" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="164" y="52">Edge</text>
+    <rect class="node node-compute" x="240" y="40" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="274" y="52">Compute</text>
+    <rect class="node node-data" x="400" y="40" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="434" y="52">Managed data</text>
+    <rect class="node node-external" x="610" y="40" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="644" y="52">External</text>
+    <line class="link" x1="760" y1="47" x2="802" y2="47" marker-end="url(#arrow)"/>
+    <text class="legend-text" x="818" y="52">Network path</text>
+    <line class="link link-secondary" x1="960" y1="47" x2="1002" y2="47" marker-end="url(#arrow-secondary)"/>
+    <text class="legend-text" x="1018" y="52">Replication</text>
+  </g>
+
+  <text class="footer" x="92" y="838">Generated by devspec - [DATE_OR_VERSION]</text>
+</svg>
diff --git a/devspec/architecture/_template/journey-map-diagram.svg b/devspec/architecture/_template/journey-map-diagram.svg
index cd4473e..e9a7fd6 100644
--- a/devspec/architecture/_template/journey-map-diagram.svg
+++ b/devspec/architecture/_template/journey-map-diagram.svg
@@ -76,6 +76,7 @@
   <text class="row-label" x="100" y="348">ACTOR</text>
   <text class="row-label" x="100" y="494">SYSTEM</text>
   <text class="row-label" x="100" y="648">OUTCOME</text>
+  <text class="row-label" x="100" y="736">SIGNAL</text>
 
   <g data-stage="discover">
     <rect class="stage-column" x="205" y="236" width="250" height="450" rx="18"/>
@@ -105,7 +106,7 @@
   <path class="flow" d="M 355 356 C 425 356, 455 356, 525 356" marker-end="url(#arrow)"/>
   <path class="flow" d="M 635 356 C 705 356, 735 482, 805 482" marker-end="url(#arrow)"/>
   <path class="flow" d="M 915 482 C 985 482, 1015 356, 1085 356" marker-end="url(#arrow)"/>
-  <path class="flow-secondary" d="M 355 514 C 425 514, 455 514, 525 514" marker-end="url(#arrow-secondary)"/>
+  <path class="flow-secondary" d="M 610 392 L 610 474" marker-end="url(#arrow-secondary)"/>
   <path class="flow-secondary" d="M 635 514 C 705 514, 735 514, 805 514" marker-end="url(#arrow-secondary)"/>
   <path class="flow-secondary" d="M 915 514 C 985 514, 1015 514, 1085 514" marker-end="url(#arrow-secondary)"/>
   <path class="emotion-line" d="M 270 744 C 430 700, 580 710, 730 736 C 880 770, 1035 730, 1190 704"/>
@@ -160,15 +161,15 @@
   <circle class="emotion-dot" cx="890" cy="760" r="8"/>
   <circle class="emotion-dot" cx="1170" cy="710" r="8"/>
 
-  <g class="legend" transform="translate(1040 704)">
-    <rect class="legend-panel" x="0" y="0" width="420" height="112" rx="14"/>
+  <g class="legend" transform="translate(1300 670)">
+    <rect class="legend-panel" x="0" y="0" width="230" height="146" rx="14"/>
     <text class="legend-title" x="24" y="32">Legend</text>
     <rect class="touchpoint touchpoint-manual" x="24" y="52" width="22" height="14" rx="4"/>
     <text class="legend-text" x="58" y="64">Actor action</text>
-    <rect class="touchpoint touchpoint-system" x="230" y="52" width="22" height="14" rx="4"/>
-    <text class="legend-text" x="264" y="64">System action</text>
-    <line class="emotion-line" x1="24" y1="88" x2="66" y2="88"/>
-    <text class="legend-text" x="82" y="92">Experience signal</text>
+    <rect class="touchpoint touchpoint-system" x="24" y="84" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="58" y="96">System action</text>
+    <line class="emotion-line" x1="24" y1="122" x2="66" y2="122"/>
+    <text class="legend-text" x="82" y="126">Experience signal</text>
   </g>
 
   <text class="footer" x="92" y="812">Generated by devspec - [DATE_OR_VERSION]</text>
diff --git a/devspec/architecture/_template/mindmap-diagram.svg b/devspec/architecture/_template/mindmap-diagram.svg
index 78c5f63..4a18c2c 100644
--- a/devspec/architecture/_template/mindmap-diagram.svg
+++ b/devspec/architecture/_template/mindmap-diagram.svg
@@ -75,21 +75,21 @@
   <text class="subtitle" x="92" y="168">[DIAGRAM_DESCRIPTION]</text>
 
   <!-- Draw branches before topic cards so connectors stay behind the labels. -->
-  <path class="branch" d="M 800 450 C 665 320, 515 290, 365 300" marker-end="url(#arrow)"/>
-  <path class="branch" d="M 800 450 C 650 430, 515 430, 380 430" marker-end="url(#arrow)"/>
-  <path class="branch branch-security" d="M 800 450 C 665 585, 515 620, 365 610" marker-end="url(#arrow-secondary)"/>
-  <path class="branch" d="M 800 450 C 935 320, 1085 290, 1235 300" marker-end="url(#arrow)"/>
-  <path class="branch branch-event" d="M 800 450 C 950 430, 1085 430, 1220 430" marker-end="url(#arrow)"/>
-  <path class="branch branch-secondary" d="M 800 450 C 935 585, 1085 620, 1235 610" marker-end="url(#arrow-secondary)"/>
+  <path class="branch" d="M 660 420 C 590 380, 520 310, 445 298" marker-end="url(#arrow)"/>
+  <path class="branch" d="M 660 450 C 600 450, 505 434, 445 430" marker-end="url(#arrow)"/>
+  <path class="branch branch-security" d="M 660 480 C 590 520, 520 600, 445 610" marker-end="url(#arrow-secondary)"/>
+  <path class="branch" d="M 940 420 C 1010 380, 1080 310, 1155 298" marker-end="url(#arrow)"/>
+  <path class="branch branch-event" d="M 940 450 C 1000 450, 1095 434, 1155 430" marker-end="url(#arrow)"/>
+  <path class="branch branch-secondary" d="M 940 480 C 1010 520, 1080 600, 1155 610" marker-end="url(#arrow-secondary)"/>
 
   <g data-cluster="left-capabilities">
-    <rect class="cluster cluster-left" x="128" y="238" width="420" height="430" rx="20"/>
-    <text class="cluster-title left" x="156" y="270">[CAPABILITY_GROUP_A]</text>
+    <rect class="cluster cluster-left" x="128" y="210" width="420" height="458" rx="20"/>
+    <text class="cluster-title left" x="156" y="242">[CAPABILITY_GROUP_A]</text>
   </g>
 
   <g data-cluster="right-capabilities">
-    <rect class="cluster cluster-right" x="1052" y="238" width="420" height="430" rx="20"/>
-    <text class="cluster-title right" x="1080" y="270">[CAPABILITY_GROUP_B]</text>
+    <rect class="cluster cluster-right" x="1052" y="210" width="420" height="458" rx="20"/>
+    <text class="cluster-title right" x="1080" y="242">[CAPABILITY_GROUP_B]</text>
   </g>
 
   <g data-topic="root">
diff --git a/devspec/architecture/_template/process-flow-diagram.svg b/devspec/architecture/_template/process-flow-diagram.svg
index f31c0e8..f071db7 100644
--- a/devspec/architecture/_template/process-flow-diagram.svg
+++ b/devspec/architecture/_template/process-flow-diagram.svg
@@ -198,28 +198,28 @@
     <text class="step-detail" x="621" y="414" text-anchor="middle">validate + process</text>
   </g>
 
-  <g data-step="3" data-type="decision">
+  <g data-step="decision" data-type="decision">
     <polygon class="step-mask" points="825,326 885,386 825,446 765,386"/>
     <polygon class="decision" points="825,326 885,386 825,446 765,386"/>
     <text class="decision-text" x="825" y="381" text-anchor="middle">Decision?</text>
     <text class="decision-subtext" x="825" y="401" text-anchor="middle">Yes / No</text>
   </g>
 
-  <g data-step="4" data-type="integration">
+  <g data-step="3" data-type="integration">
     <rect class="step-mask" x="966" y="337" width="190" height="98" rx="12"/>
     <rect class="step step-integration" x="966" y="337" width="190" height="98" rx="12"/>
     <circle class="num num-integration" cx="991" cy="362" r="14"/>
-    <text class="num-text" x="991" y="366" text-anchor="middle">4</text>
+    <text class="num-text" x="991" y="366" text-anchor="middle">3</text>
     <text class="actor integration" x="1022" y="366">API</text>
     <text class="step-title" x="1061" y="392" text-anchor="middle">Integration</text>
     <text class="step-detail" x="1061" y="414" text-anchor="middle">external handoff</text>
   </g>
 
-  <g data-step="5" data-type="automated">
+  <g data-step="4" data-type="automated">
     <rect class="step-mask" x="1235" y="337" width="190" height="98" rx="12"/>
     <rect class="step step-automated" x="1235" y="337" width="190" height="98" rx="12"/>
     <circle class="num num-automated" cx="1260" cy="362" r="14"/>
-    <text class="num-text" x="1260" y="366" text-anchor="middle">5</text>
+    <text class="num-text" x="1260" y="366" text-anchor="middle">4</text>
     <text class="actor automated" x="1291" y="366">SYSTEM</text>
     <text class="step-title" x="1330" y="392" text-anchor="middle">Finalize</text>
     <text class="step-detail" x="1330" y="414" text-anchor="middle">notify + record</text>
diff --git a/devspec/architecture/_template/quadrant-analysis-diagram.svg b/devspec/architecture/_template/quadrant-analysis-diagram.svg
index ffc812c..a91a277 100644
--- a/devspec/architecture/_template/quadrant-analysis-diagram.svg
+++ b/devspec/architecture/_template/quadrant-analysis-diagram.svg
@@ -112,14 +112,16 @@
   </g>
 
   <g class="legend" transform="translate(1200 650)">
-    <rect class="legend-panel" x="0" y="0" width="250" height="140" rx="14"/>
+    <rect class="legend-panel" x="0" y="0" width="250" height="172" rx="14"/>
     <text class="legend-title" x="24" y="32">Legend</text>
     <circle class="item item-high" cx="34" cy="62" r="10"/>
     <text class="legend-text" x="58" y="67">Priority item</text>
     <circle class="item item-risk" cx="34" cy="92" r="10"/>
     <text class="legend-text" x="58" y="97">Risk item</text>
-    <circle class="item item-info" cx="34" cy="122" r="10"/>
-    <text class="legend-text" x="58" y="127">Exploratory item</text>
+    <circle class="item item-medium" cx="34" cy="122" r="10"/>
+    <text class="legend-text" x="58" y="127">Deferred item</text>
+    <circle class="item item-info" cx="34" cy="152" r="10"/>
+    <text class="legend-text" x="58" y="157">Exploratory item</text>
   </g>
 
   <text class="footer" x="92" y="812">Generated by devspec - [DATE_OR_VERSION]</text>
diff --git a/devspec/architecture/_template/state-lifecycle-diagram.svg b/devspec/architecture/_template/state-lifecycle-diagram.svg
index 706e55c..ce5bb59 100644
--- a/devspec/architecture/_template/state-lifecycle-diagram.svg
+++ b/devspec/architecture/_template/state-lifecycle-diagram.svg
@@ -91,8 +91,8 @@
   </g>
 
   <g data-region="exception-lifecycle">
-    <rect class="region region-exception" x="735" y="610" width="280" height="130" rx="18"/>
-    <text class="region-title exception" x="762" y="640">[EXCEPTION_STATE]</text>
+    <rect class="region region-exception" x="520" y="610" width="300" height="130" rx="18"/>
+    <text class="region-title exception" x="546" y="640">[EXCEPTION_STATE]</text>
   </g>
 
   <!-- Draw transitions after regions and before state nodes so connectors stay readable but behind lifecycle boxes. -->
@@ -109,13 +109,13 @@
   <text class="transition-label" x="1080" y="425" text-anchor="middle">Approve</text>
 
   <path class="transition transition-secondary" d="M 1362 420 C 1410 420, 1430 420, 1478 420" marker-end="url(#arrow-secondary)"/>
-  <path class="transition transition-exception" d="M 874 470 C 874 545, 874 570, 874 645" marker-end="url(#arrow-security)"/>
-  <rect class="transition-label-bg" x="900" y="546" width="88" height="24" rx="7"/>
-  <text class="transition-label" x="944" y="563" text-anchor="middle">Reject</text>
+  <path class="transition transition-exception" d="M 824 474 C 824 545, 760 580, 720 652" marker-end="url(#arrow-security)"/>
+  <rect class="transition-label-bg" x="846" y="560" width="80" height="24" rx="7"/>
+  <text class="transition-label" x="886" y="577" text-anchor="middle">Reject</text>
 
-  <path class="transition transition-loop" d="M 774 688 C 635 745, 455 720, 486 488" marker-end="url(#arrow-loop)"/>
-  <rect class="transition-label-bg" x="565" y="708" width="96" height="24" rx="7"/>
-  <text class="transition-label" x="613" y="725" text-anchor="middle">Revise</text>
+  <path class="transition transition-loop" d="M 560 685 C 440 685, 486 590, 486 474" marker-end="url(#arrow-loop)"/>
+  <rect class="transition-label-bg" x="392" y="606" width="88" height="24" rx="7"/>
+  <text class="transition-label" x="436" y="623" text-anchor="middle">Revise</text>
 
   <g data-state="start">
     <circle class="terminal" cx="154" cy="420" r="40"/>
@@ -152,23 +152,23 @@
   </g>
 
   <g data-state="rework">
-    <rect class="state-mask" x="774" y="652" width="200" height="66" rx="14"/>
-    <rect class="state state-exception" x="774" y="652" width="200" height="66" rx="14"/>
-    <text class="state-title" x="874" y="681" text-anchor="middle">Rework</text>
-    <text class="state-meta" x="874" y="704" text-anchor="middle">Resolve issues</text>
+    <rect class="state-mask" x="560" y="652" width="220" height="66" rx="14"/>
+    <rect class="state state-exception" x="560" y="652" width="220" height="66" rx="14"/>
+    <text class="state-title" x="670" y="681" text-anchor="middle">Rework</text>
+    <text class="state-meta" x="670" y="704" text-anchor="middle">Resolve issues</text>
   </g>
 
   <g class="legend" transform="translate(1040 690)">
-    <rect class="legend-panel" x="0" y="0" width="420" height="112" rx="14"/>
+    <rect class="legend-panel" x="0" y="0" width="470" height="112" rx="14"/>
     <text class="legend-title" x="24" y="32">Legend</text>
     <rect class="state state-active" x="24" y="52" width="22" height="14" rx="4"/>
     <text class="legend-text" x="58" y="64">Normal state</text>
-    <rect class="state state-exception" x="230" y="52" width="22" height="14" rx="4"/>
-    <text class="legend-text" x="264" y="64">Exception</text>
+    <rect class="state state-exception" x="250" y="52" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="284" y="64">Exception</text>
     <line class="transition transition-secondary" x1="24" y1="88" x2="66" y2="88" marker-end="url(#arrow-secondary)"/>
     <text class="legend-text" x="82" y="92">Return or terminal flow</text>
-    <line class="transition transition-exception" x1="230" y1="88" x2="272" y2="88" marker-end="url(#arrow-security)"/>
-    <text class="legend-text" x="288" y="92">Rejected transition</text>
+    <line class="transition transition-exception" x1="250" y1="88" x2="292" y2="88" marker-end="url(#arrow-security)"/>
+    <text class="legend-text" x="308" y="92">Rejected transition</text>
   </g>
 
   <text class="footer" x="92" y="812">Generated by devspec - [DATE_OR_VERSION]</text>
diff --git a/devspec/architecture/_template/timeline-plan-diagram.svg b/devspec/architecture/_template/timeline-plan-diagram.svg
index 4923d1f..09caebe 100644
--- a/devspec/architecture/_template/timeline-plan-diagram.svg
+++ b/devspec/architecture/_template/timeline-plan-diagram.svg
@@ -63,7 +63,6 @@
       <path d="M 0 0 L 10 5 L 0 10 z" fill="#fb7185"/>
     </marker>
   </defs>
-
   <rect class="page-bg" width="1600" height="900"/>
   <rect width="1600" height="900" fill="url(#grid)" opacity="0.42"/>
   <rect class="surface" x="48" y="42" width="1504" height="816" rx="20"/>
@@ -73,84 +72,92 @@
   <text class="subtitle" x="92" y="168">[DIAGRAM_DESCRIPTION]</text>
 
   <g data-phase="planning">
-    <rect class="phase-band" x="140" y="250" width="320" height="430" rx="18"/>
-    <text class="phase-title" x="168" y="284">PLANNING</text>
+    <rect class="phase-band" x="140" y="230" width="320" height="390" rx="18"/>
+    <text class="phase-title" x="168" y="262">PLANNING</text>
   </g>
 
   <g data-phase="build">
-    <rect class="phase-band" x="490" y="250" width="320" height="430" rx="18"/>
-    <text class="phase-title" x="518" y="284">BUILD</text>
+    <rect class="phase-band" x="490" y="230" width="320" height="390" rx="18"/>
+    <text class="phase-title" x="518" y="262">BUILD</text>
   </g>
 
   <g data-phase="validate">
-    <rect class="phase-band" x="840" y="250" width="320" height="430" rx="18"/>
-    <text class="phase-title" x="868" y="284">VALIDATE</text>
+    <rect class="phase-band" x="840" y="230" width="320" height="390" rx="18"/>
+    <text class="phase-title" x="868" y="262">VALIDATE</text>
   </g>
 
   <g data-phase="release">
-    <rect class="phase-band" x="1190" y="250" width="260" height="430" rx="18"/>
-    <text class="phase-title" x="1218" y="284">RELEASE</text>
+    <rect class="phase-band" x="1190" y="230" width="260" height="390" rx="18"/>
+    <text class="phase-title" x="1218" y="262">RELEASE</text>
   </g>
 
-  <!-- Draw timeline axis and dependencies before milestone cards. -->
-  <line class="axis" x1="170" y1="470" x2="1410" y2="470"/>
-  <line class="tick" x1="250" y1="430" x2="250" y2="510"/>
+  <!-- Time runs along the axis; each tick carries the one date for the milestone above it. -->
+  <line class="axis" x1="140" y1="470" x2="1478" y2="470" marker-end="url(#arrow)"/>
+  <line class="tick" x1="250" y1="388" x2="250" y2="510"/>
   <text class="tick-label" x="250" y="535" text-anchor="middle">[T1]</text>
-  <line class="tick" x1="600" y1="430" x2="600" y2="510"/>
+  <line class="tick" x1="600" y1="388" x2="600" y2="510"/>
   <text class="tick-label" x="600" y="535" text-anchor="middle">[T2]</text>
-  <line class="tick" x1="950" y1="430" x2="950" y2="510"/>
+  <line class="tick" x1="950" y1="388" x2="950" y2="510"/>
   <text class="tick-label" x="950" y="535" text-anchor="middle">[T3]</text>
-  <line class="tick" x1="1300" y1="430" x2="1300" y2="510"/>
+  <line class="tick" x1="1300" y1="388" x2="1300" y2="510"/>
   <text class="tick-label" x="1300" y="535" text-anchor="middle">[T4]</text>
 
-  <path class="dependency" d="M 345 350 C 430 300, 515 300, 600 350" marker-end="url(#arrow)"/>
-  <rect class="dependency-label-bg" x="452" y="288" width="92" height="24" rx="7"/>
-  <text class="dependency-label" x="498" y="305" text-anchor="middle">Depends</text>
-  <path class="dependency dependency-risk" d="M 950 350 C 1038 300, 1212 300, 1300 350" marker-end="url(#arrow-security)"/>
-  <rect class="dependency-label-bg" x="1100" y="288" width="76" height="24" rx="7"/>
-  <text class="dependency-label" x="1138" y="305" text-anchor="middle">Risk</text>
+  <!-- Dependency and risk links join milestone points on the axis, so both ends always name a milestone. -->
+  <path class="dependency" d="M 262 481 C 340 575, 510 575, 588 481" marker-end="url(#arrow)"/>
+  <rect class="dependency-label-bg" x="379" y="533" width="92" height="24" rx="7"/>
+  <text class="dependency-label" x="425" y="550" text-anchor="middle">Depends</text>
+
+  <path class="dependency dependency-risk" d="M 962 481 C 1040 575, 1210 575, 1288 481" marker-end="url(#arrow-security)"/>
+  <rect class="dependency-label-bg" x="1085" y="533" width="76" height="24" rx="7"/>
+  <text class="dependency-label" x="1123" y="550" text-anchor="middle">Risk</text>
 
   <g data-milestone="plan">
     <circle class="milestone-dot" cx="250" cy="470" r="15"/>
-    <rect class="milestone-mask" x="155" y="330" width="190" height="82" rx="12"/>
-    <rect class="milestone milestone-plan" x="155" y="330" width="190" height="82" rx="12"/>
-    <text class="milestone-title" x="250" y="362" text-anchor="middle">Plan Ready</text>
-    <text class="milestone-date" x="250" y="386" text-anchor="middle">[date / sprint]</text>
+    <rect class="milestone-mask" x="155" y="300" width="190" height="88" rx="12"/>
+    <rect class="milestone milestone-plan" x="155" y="300" width="190" height="88" rx="12"/>
+    <text class="milestone-title" x="250" y="336" text-anchor="middle">Plan Ready</text>
+    <text class="milestone-date" x="250" y="360" text-anchor="middle">[owner / deliverable]</text>
   </g>
 
   <g data-milestone="build">
     <circle class="milestone-dot" cx="600" cy="470" r="15"/>
-    <rect class="milestone-mask" x="505" y="330" width="190" height="82" rx="12"/>
-    <rect class="milestone milestone-build" x="505" y="330" width="190" height="82" rx="12"/>
-    <text class="milestone-title" x="600" y="362" text-anchor="middle">Build Done</text>
-    <text class="milestone-date" x="600" y="386" text-anchor="middle">[date / sprint]</text>
+    <rect class="milestone-mask" x="505" y="300" width="190" height="88" rx="12"/>
+    <rect class="milestone milestone-build" x="505" y="300" width="190" height="88" rx="12"/>
+    <text class="milestone-title" x="600" y="336" text-anchor="middle">Build Done</text>
+    <text class="milestone-date" x="600" y="360" text-anchor="middle">[owner / deliverable]</text>
   </g>
 
   <g data-milestone="validate">
     <circle class="milestone-dot" cx="950" cy="470" r="15"/>
-    <rect class="milestone-mask" x="855" y="560" width="190" height="82" rx="12"/>
-    <rect class="milestone milestone-risk" x="855" y="560" width="190" height="82" rx="12"/>
-    <text class="milestone-title" x="950" y="592" text-anchor="middle">Validation Gate</text>
-    <text class="milestone-date" x="950" y="616" text-anchor="middle">[date / sprint]</text>
+    <rect class="milestone-mask" x="855" y="300" width="190" height="88" rx="12"/>
+    <rect class="milestone milestone-risk" x="855" y="300" width="190" height="88" rx="12"/>
+    <text class="milestone-title" x="950" y="336" text-anchor="middle">Validation Gate</text>
+    <text class="milestone-date" x="950" y="360" text-anchor="middle">[owner / deliverable]</text>
   </g>
 
   <g data-milestone="release">
     <circle class="milestone-dot" cx="1300" cy="470" r="15"/>
-    <rect class="milestone-mask" x="1205" y="330" width="190" height="82" rx="12"/>
-    <rect class="milestone milestone-release" x="1205" y="330" width="190" height="82" rx="12"/>
-    <text class="milestone-title" x="1300" y="362" text-anchor="middle">Release</text>
-    <text class="milestone-date" x="1300" y="386" text-anchor="middle">[date / sprint]</text>
+    <rect class="milestone-mask" x="1205" y="300" width="190" height="88" rx="12"/>
+    <rect class="milestone milestone-release" x="1205" y="300" width="190" height="88" rx="12"/>
+    <text class="milestone-title" x="1300" y="336" text-anchor="middle">Release</text>
+    <text class="milestone-date" x="1300" y="360" text-anchor="middle">[owner / deliverable]</text>
   </g>
 
-  <g class="legend" transform="translate(1040 704)">
-    <rect class="legend-panel" x="0" y="0" width="420" height="112" rx="14"/>
+  <g class="legend" transform="translate(140 668)">
+    <rect class="legend-panel" x="0" y="0" width="800" height="112" rx="14"/>
     <text class="legend-title" x="24" y="32">Legend</text>
-    <rect class="milestone milestone-build" x="24" y="52" width="22" height="14" rx="4"/>
-    <text class="legend-text" x="58" y="64">Milestone</text>
-    <rect class="milestone milestone-risk" x="230" y="52" width="22" height="14" rx="4"/>
-    <text class="legend-text" x="264" y="64">Gate / risk</text>
-    <line class="dependency" x1="24" y1="88" x2="66" y2="88" marker-end="url(#arrow)"/>
-    <text class="legend-text" x="82" y="92">Dependency</text>
+    <rect class="milestone milestone-plan" x="24" y="50" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="58" y="62">Planned</text>
+    <rect class="milestone milestone-build" x="24" y="82" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="58" y="94">Delivered</text>
+    <rect class="milestone milestone-risk" x="270" y="50" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="304" y="62">Gate / risk</text>
+    <rect class="milestone milestone-release" x="270" y="82" width="22" height="14" rx="4"/>
+    <text class="legend-text" x="304" y="94">Release</text>
+    <line class="dependency" x1="516" y1="58" x2="558" y2="58" marker-end="url(#arrow)"/>
+    <text class="legend-text" x="574" y="62">Dependency (source first)</text>
+    <line class="dependency dependency-risk" x1="516" y1="90" x2="558" y2="90" marker-end="url(#arrow-security)"/>
+    <text class="legend-text" x="574" y="94">Risk link</text>
   </g>
 
   <text class="footer" x="92" y="812">Generated by devspec - [DATE_OR_VERSION]</text>
diff --git a/devspec/architecture/artifact-queue.md b/devspec/architecture/artifact-queue.md
index bba7bf5..cf2cb3d 100644
--- a/devspec/architecture/artifact-queue.md
+++ b/devspec/architecture/artifact-queue.md
@@ -6,3 +6,4 @@
 | DIA-002 | workflow | Process flow | delivery-route | `docs/assets/delivery-routes.svg` | command contracts, protocols | none | complete | none |
 | DIA-003 | workflow | Process flow | install-lifecycle | `docs/assets/maintenance-flow.svg` | CLI, doctor, setup guides | none | complete | none |
 | DIA-004 | workflow | Process flow | manual-copy-route | `docs/assets/manual-copy-flow.svg` | manual copy guide, install manifest | none | complete | none |
+| DIA-005 | workflow | Process flow | diagram-route | `docs/assets/diagram-route.svg` | diagram contract, clarify transition | none | complete | none |
diff --git a/devspec/architecture/overview.md b/devspec/architecture/overview.md
index 3b867a0..3a59efa 100644
--- a/devspec/architecture/overview.md
+++ b/devspec/architecture/overview.md
@@ -14,3 +14,4 @@
 | DIA-002 | Delivery route | workflow | command contracts, protocols | `docs/assets/delivery-routes.svg` |
 | DIA-003 | Install lifecycle | workflow | CLI, doctor, setup guides | `docs/assets/maintenance-flow.svg` |
 | DIA-004 | Manual copy route | workflow | manual copy guide, install manifest | `docs/assets/manual-copy-flow.svg` |
+| DIA-005 | Diagram route | workflow | diagram contract, clarify transition | `docs/assets/diagram-route.svg` |
diff --git a/devspec/contracts/devspec.diagram.md b/devspec/contracts/devspec.diagram.md
index da26cd2..c18bc49 100644
--- a/devspec/contracts/devspec.diagram.md
+++ b/devspec/contracts/devspec.diagram.md
@@ -18,7 +18,7 @@ Invocation: `/devspec.diagram runtime architecture format=svg motion=none|explai
   <rules>
     <rule>Read only the evidence the requested subject needs, the one diagram-type pattern selected, and its matching family template. Do not load unrelated templates or explore beyond the subject's confirmed boundary.</rule>
     <rule>Select the diagram type from devspec/architecture/_template/diagram-types.md.</rule>
-    <rule>Start each SVG from the matching family-specific template: `architecture-diagram.svg` for system architecture, application landscape, and infrastructure topology; `process-flow-diagram.svg` for process flows; `sequence-diagram.svg` for interactions; `state-lifecycle-diagram.svg` for state behavior; `domain-model-diagram.svg` for domain models; `journey-map-diagram.svg` for journeys; `timeline-plan-diagram.svg` for timelines; `quadrant-analysis-diagram.svg` for quadrants; and `mindmap-diagram.svg` for mind maps.</rule>
+    <rule>Start each SVG from the matching family-specific template: `architecture-diagram.svg` for system architecture; `application-landscape-diagram.svg` for application landscapes; `infrastructure-topology-diagram.svg` for infrastructure topology; `process-flow-diagram.svg` for process flows; `sequence-diagram.svg` for interactions; `state-lifecycle-diagram.svg` for state behavior; `domain-model-diagram.svg` for domain models; `journey-map-diagram.svg` for journeys; `timeline-plan-diagram.svg` for timelines; `quadrant-analysis-diagram.svg` for quadrants; and `mindmap-diagram.svg` for mind maps.</rule>
     <rule>Create only evidence-backed, non-duplicate diagrams and persist queue or overview state for recovery.</rule>
     <rule>Record an evidence blocker in the caller's decision record, never in the queue, and leave the caller's saved stage and next action unchanged.</rule>
     <rule>Accept a stable queued `DIA-###` ID or diagram subject, record subject, type, evidence, output format, duplicate-check result, status, and next action in the queue, and index completed output in the overview. On an explicit process-flow batch request, generate every queued non-duplicate process-flow candidate, validate each output, update each queue row independently, and leave the caller lifecycle state unchanged.</rule>
@@ -27,6 +27,7 @@ Invocation: `/devspec.diagram runtime architecture format=svg motion=none|explai
     <rule>For `motion=explain`, animate only an evidence-backed sequence, flow, or state transition and follow the opt-in motion guidance in diagram-types.md. Keep the complete meaning visible in the static final frame, provide a reduced-motion result with no information loss, and do not add decorative motion or imply unsupported behavior.</rule>
     <rule>Record animated SVG output in the queue's existing Output field as `svg; motion=explain`. When HTML is also requested, inline the same SVG so its motion and reduced-motion behavior remain intact.</rule>
     <rule>Preserve the template's standalone dark visual contract: 1600 by 900 canvas, subtle grid, framed surface, monospace typography, semantic role colors, connectors behind cards, short labels, and a legend only when its notation needs explanation. Replace every placeholder before completion and do not use external assets, scripts, iframes, foreign objects, remote fonts, unresolved placeholders, or unsupported diagram families.</rule>
+    <rule>Anchor every connector to a shape edge at both ends, keep each arrowhead visible instead of hidden behind the shape it points at, and remove any shape the evidence leaves unconnected. Keep label backgrounds clear of boundary strokes, other labels, and neighboring shapes, and give every color that appears on a shape a matching legend entry.</rule>
     <rule>Keep labels short and place explanations in supporting Markdown rather than the graphic. Keep flowcharts to one primary concern and split an overloaded diagram at a confirmed responsibility boundary; use `sequence` for ordered interactions and the process-flow template for end-to-end operational behavior.</rule>
     <rule>For process flows, make the happy path visually obvious; distinguish start or end, manual, automated, integration, decision, exception, and artifact steps; label loop-backs; and draw exception paths as labeled dashed rose arrows that terminate or reconnect to a named step.</rule>
   </rules>
diff --git a/docs/assets/delivery-routes.svg b/docs/assets/delivery-routes.svg
index 76f656d..ecde7ea 100644
--- a/docs/assets/delivery-routes.svg
+++ b/docs/assets/delivery-routes.svg
@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1440 590" role="img" aria-labelledby="title desc"><title id="title">Delivery routes for quick fixes and work items</title><desc id="desc">A localized low-risk request uses Quickfix, focused validation, and a recorded outcome. Broader or higher-risk work follows Story, optional Grooming, Finalize, Tasks, Implement, and Review. Clarify resumes the blocked stage.</desc><style>.bg{fill:#070b18}.surface{fill:#101827;stroke:#24324b}.lane{fill:#0c1323;stroke:#263653;stroke-dasharray:6 7}.eyebrow{font:700 12px system-ui,sans-serif;letter-spacing:2px;fill:#69d8ff}.title{font:700 30px system-ui,sans-serif;fill:#f8fafc}.sub{font:15px system-ui,sans-serif;fill:#aab8cf}.laneLabel{font:700 11px system-ui,sans-serif;letter-spacing:1.5px;fill:#7f91b1}.card{fill:#16223a;stroke:#35517c;stroke-width:1.5}.quick{fill:#3a2b10;stroke:#ffc857}.start{fill:#123745;stroke:#39c9d9}.decision{fill:#1d3450;stroke:#69d8ff;stroke-width:2}.nodeTitle{font:700 14px system-ui,sans-serif;fill:#f8fafc}.nodeMeta{font:12px system-ui,sans-serif;fill:#aab8cf}.flow{fill:none;stroke:#69d8ff;stroke-width:2.5;marker-end:url(#arrow)}.flowQuick{fill:none;stroke:#ffc857;stroke-width:2.5;marker-end:url(#arrowGold)}.clarify{fill:none;stroke:#9c8cff;stroke-width:2;stroke-dasharray:6 6;marker-end:url(#arrowV)}.label{font:700 12px system-ui,sans-serif;fill:#ffd978}.note{font:13px system-ui,sans-serif;fill:#aab8cf}.foot{font:600 11px system-ui,sans-serif;letter-spacing:1px;fill:#6f86a8}</style><defs><pattern id="grid" width="32" height="32" patternUnits="userSpaceOnUse"><path d="M32 0H0V32" fill="none" stroke="#14213a" stroke-width="1"/></pattern><marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#69d8ff"/></marker><marker id="arrowGold" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#ffc857"/></marker><marker id="arrowV" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#9c8cff"/></marker></defs><rect class="bg" width="1440" height="590"/><rect fill="url(#grid)" width="1440" height="590" opacity=".9"/><rect class="surface" x="28" y="28" width="1384" height="534" rx="20"/><text x="64" y="67" class="eyebrow">DEVSPEC LITE / DELIVERY</text><text x="64" y="103" class="title">Take the smallest safe route</text><text x="64" y="131" class="sub">Quickfix handles one localized, low-risk concern. Scope, risk, or durable design needs a traceable work item.</text><rect class="lane" x="64" y="156" width="1312" height="142" rx="14"/><text x="88" y="183" class="laneLabel">LOCAL / LOW-RISK CHANGE</text><rect class="lane" x="64" y="366" width="1312" height="130" rx="14"/><text x="88" y="393" class="laneLabel">PLANNED WORK ITEM</text><rect class="card start" x="90" y="264" width="155" height="58" rx="10"/><text x="110" y="288" class="nodeTitle">Request</text><text x="110" y="308" class="nodeMeta">one stated need</text><polygon class="decision" points="332,248 398,292 332,336 266,292"/><text x="332" y="287" text-anchor="middle" class="nodeTitle">Local +</text><text x="332" y="306" text-anchor="middle" class="nodeTitle">low risk?</text><rect class="card quick" x="500" y="205" width="150" height="58" rx="10"/><text x="520" y="229" class="nodeTitle">quickfix</text><text x="520" y="249" class="nodeMeta">targeted discovery</text><rect class="card quick" x="700" y="205" width="160" height="58" rx="10"/><text x="720" y="229" class="nodeTitle">focused validation</text><text x="720" y="249" class="nodeMeta">direct evidence</text><rect class="card quick" x="910" y="205" width="190" height="58" rx="10"/><text x="930" y="229" class="nodeTitle">QF record + outcome</text><text x="930" y="249" class="nodeMeta">resume state included</text><rect class="card" x="500" y="420" width="115" height="58" rx="10"/><text x="520" y="455" class="nodeTitle">story</text><rect class="card" x="645" y="420" width="130" height="58" rx="10"/><text x="665" y="455" class="nodeTitle">grooming*</text><rect class="card" x="805" y="420" width="115" height="58" rx="10"/><text x="825" y="455" class="nodeTitle">finalize</text><rect class="card" x="950" y="420" width="100" height="58" rx="10"/><text x="970" y="455" class="nodeTitle">tasks</text><rect class="card" x="1080" y="420" width="125" height="58" rx="10"/><text x="1100" y="455" class="nodeTitle">implement</text><rect class="card" x="1235" y="420" width="110" height="58" rx="10"/><text x="1255" y="455" class="nodeTitle">review</text><path class="flow" d="M245 293H266"/><path class="flowQuick" d="M398 270H450V234H500M650 234H700M860 234H910"/><path class="flow" d="M398 315H450V449H500M615 449H645M775 449H805M920 449H950M1050 449H1080M1205 449H1235"/><text x="425" y="257" class="label">YES</text><text x="420" y="340" class="label">NO / RISK</text><path class="clarify" d="M862 420V374H710V420"/><text x="720" y="358" class="note">blocker: clarify, then resume the originating stage</text><text x="64" y="530" class="foot">* SUGGEST GROOMING ONLY WHEN AMBIGUITY, RISK, OR ACCEPTANCE CRITERIA ARE MATERIALLY INCOMPLETE</text></svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1440 590" role="img" aria-labelledby="title desc"><title id="title">Delivery routes for quick fixes and work items</title><desc id="desc">A localized low-risk request uses Quickfix, focused validation, and a recorded outcome. Broader or higher-risk work follows Story, optional Grooming, Finalize, Tasks, Implement, and Review. Clarify resumes the blocked stage.</desc><style>.bg{fill:#070b18}.surface{fill:#101827;stroke:#24324b}.lane{fill:#0c1323;stroke:#263653;stroke-dasharray:6 7}.eyebrow{font:700 12px system-ui,sans-serif;letter-spacing:2px;fill:#69d8ff}.title{font:700 30px system-ui,sans-serif;fill:#f8fafc}.sub{font:15px system-ui,sans-serif;fill:#aab8cf}.laneLabel{font:700 11px system-ui,sans-serif;letter-spacing:1.5px;fill:#7f91b1}.card{fill:#16223a;stroke:#35517c;stroke-width:1.5}.quick{fill:#3a2b10;stroke:#ffc857}.start{fill:#123745;stroke:#39c9d9}.decision{fill:#1d3450;stroke:#69d8ff;stroke-width:2}.nodeTitle{font:700 14px system-ui,sans-serif;fill:#f8fafc}.nodeMeta{font:12px system-ui,sans-serif;fill:#aab8cf}.flow{fill:none;stroke:#69d8ff;stroke-width:2.5;marker-end:url(#arrow)}.flowQuick{fill:none;stroke:#ffc857;stroke-width:2.5;marker-end:url(#arrowGold)}.clarify{fill:none;stroke:#9c8cff;stroke-width:2;stroke-dasharray:6 6;marker-end:url(#arrowV)}.label{font:700 12px system-ui,sans-serif;fill:#ffd978}.note{font:13px system-ui,sans-serif;fill:#aab8cf}.foot{font:600 11px system-ui,sans-serif;letter-spacing:1px;fill:#6f86a8}</style><defs><pattern id="grid" width="32" height="32" patternUnits="userSpaceOnUse"><path d="M32 0H0V32" fill="none" stroke="#14213a" stroke-width="1"/></pattern><marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#69d8ff"/></marker><marker id="arrowGold" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#ffc857"/></marker><marker id="arrowV" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#9c8cff"/></marker></defs><rect class="bg" width="1440" height="590"/><rect fill="url(#grid)" width="1440" height="590" opacity=".9"/><rect class="surface" x="28" y="28" width="1384" height="534" rx="20"/><text x="64" y="67" class="eyebrow">DEVSPEC LITE / DELIVERY</text><text x="64" y="103" class="title">Take the smallest safe route</text><text x="64" y="131" class="sub">Quickfix handles one localized, low-risk concern. Scope, risk, or durable design needs a traceable work item.</text><rect class="lane" x="64" y="156" width="1312" height="142" rx="14"/><text x="88" y="183" class="laneLabel">LOCAL / LOW-RISK CHANGE</text><rect class="lane" x="64" y="366" width="1312" height="130" rx="14"/><text x="88" y="393" class="laneLabel">PLANNED WORK ITEM</text><rect class="card start" x="90" y="264" width="155" height="58" rx="10"/><text x="110" y="288" class="nodeTitle">Request</text><text x="110" y="308" class="nodeMeta">one stated need</text><polygon class="decision" points="332,248 398,292 332,336 266,292"/><text x="332" y="287" text-anchor="middle" class="nodeTitle">Local +</text><text x="332" y="306" text-anchor="middle" class="nodeTitle">low risk?</text><rect class="card quick" x="500" y="205" width="150" height="58" rx="10"/><text x="520" y="229" class="nodeTitle">quickfix</text><text x="520" y="249" class="nodeMeta">targeted discovery</text><rect class="card quick" x="700" y="205" width="160" height="58" rx="10"/><text x="720" y="229" class="nodeTitle">focused validation</text><text x="720" y="249" class="nodeMeta">direct evidence</text><rect class="card quick" x="910" y="205" width="190" height="58" rx="10"/><text x="930" y="229" class="nodeTitle">QF record + outcome</text><text x="930" y="249" class="nodeMeta">resume state included</text><rect class="card" x="500" y="420" width="115" height="58" rx="10"/><text x="520" y="455" class="nodeTitle">story</text><rect class="card" x="645" y="420" width="130" height="58" rx="10"/><text x="665" y="455" class="nodeTitle">grooming*</text><rect class="card" x="805" y="420" width="115" height="58" rx="10"/><text x="825" y="455" class="nodeTitle">finalize</text><rect class="card" x="950" y="420" width="100" height="58" rx="10"/><text x="970" y="455" class="nodeTitle">tasks</text><rect class="card" x="1080" y="420" width="125" height="58" rx="10"/><text x="1100" y="455" class="nodeTitle">implement</text><rect class="card" x="1235" y="420" width="110" height="58" rx="10"/><text x="1255" y="455" class="nodeTitle">review</text><path class="flow" d="M245 293H266"/><path class="flowQuick" d="M398 270H450V234H500M650 234H700M860 234H910"/><path class="flow" d="M398 315H430V449H500M615 449H645M775 449H805M920 449H950M1050 449H1080M1205 449H1235"/><text x="425" y="257" class="label">YES</text><text x="440" y="340" class="label">NO / RISK</text><path class="clarify" d="M862 420V374H710V420"/><text x="720" y="358" class="note">blocker: clarify, then resume the originating stage</text><text x="64" y="530" class="foot">* SUGGEST GROOMING ONLY WHEN AMBIGUITY, RISK, OR ACCEPTANCE CRITERIA ARE MATERIALLY INCOMPLETE</text></svg>
diff --git a/docs/assets/diagram-route.svg b/docs/assets/diagram-route.svg
new file mode 100644
index 0000000..f1f53fb
--- /dev/null
+++ b/docs/assets/diagram-route.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1440 470" role="img" aria-labelledby="title desc"><title id="title">Diagram command route for Devspec Lite</title><desc id="desc">A queued candidate or subject is duplicate-checked, matched to a diagram type and family template, generated as SVG, validated, then indexed in the queue and overview before control returns to the caller. Missing evidence records a blocker and routes to devspec.clarify, which resumes the queued subject.</desc><style>.bg{fill:#070b18}.surface{fill:#101827;stroke:#24324b}.lane{fill:#0c1323;stroke:#263653;stroke-dasharray:6 7}.eyebrow{font:700 12px system-ui,sans-serif;letter-spacing:2px;fill:#69d8ff}.title{font:700 30px system-ui,sans-serif;fill:#f8fafc}.sub{font:15px system-ui,sans-serif;fill:#aab8cf}.laneTitle{font:700 11px system-ui,sans-serif;letter-spacing:1.6px;fill:#64d49a}.laneTitleAlt{font:700 11px system-ui,sans-serif;letter-spacing:1.6px;fill:#ff8fa8}.card{fill:#16223a;stroke:#35517c;stroke-width:1.5}.start{fill:#123745;stroke:#39c9d9}.safe{fill:#17372d;stroke:#64d49a}.warn{fill:#3a1622;stroke:#ff8fa8}.nodeTitle{font:700 15px system-ui,sans-serif;fill:#f8fafc}.nodeMeta{font:12px system-ui,sans-serif;fill:#aab8cf}.flow{fill:none;stroke:#69d8ff;stroke-width:2.5;marker-end:url(#arrow)}.exception{fill:none;stroke:#ff8fa8;stroke-width:2.2;stroke-dasharray:7 6;marker-end:url(#arrowX)}.loop{fill:none;stroke:#9c8cff;stroke-width:2.2;stroke-dasharray:7 6;marker-end:url(#arrowV)}.label{font:700 11px system-ui,sans-serif;fill:#ffb3c4}.note{font:13px system-ui,sans-serif;fill:#c1cae0}.foot{font:600 11px system-ui,sans-serif;letter-spacing:1px;fill:#6f86a8}</style><defs><pattern id="grid" width="32" height="32" patternUnits="userSpaceOnUse"><path d="M32 0H0V32" fill="none" stroke="#14213a" stroke-width="1"/></pattern><marker id="arrow" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto"><path d="M0,0 L0,6 L8,3z" fill="#69d8ff"/></marker><marker id="arrowX" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto"><path d="M0,0 L0,6 L8,3z" fill="#ff8fa8"/></marker><marker id="arrowV" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto"><path d="M0,0 L0,6 L8,3z" fill="#9c8cff"/></marker></defs><rect class="bg" width="1440" height="470"/><rect fill="url(#grid)" width="1440" height="470"/><rect class="surface" x="22" y="22" width="1396" height="426" rx="18"/><text x="52" y="57" class="eyebrow">DEVSPEC LITE / DIAGRAM</text><text x="52" y="88" class="title">Generate one diagram, once</text><text x="52" y="111" class="sub">A queued candidate becomes one validated, indexed diagram. Anything unproven becomes a clarify blocker instead.</text><rect class="lane" x="52" y="138" width="1336" height="124" rx="14"/><text x="76" y="162" class="laneTitle">GENERATE</text><rect class="lane" x="52" y="310" width="1336" height="96" rx="14"/><text x="76" y="334" class="laneTitleAlt">BLOCKED</text><path class="flow" d="M232 205H272M438 205H478M624 205H664M820 205H860M1006 205H1046M1206 205H1246"/><path class="exception" d="M551 234V348"/><text x="563" y="272" class="label">NO EVIDENCE</text><path class="flow" d="M658 372H760"/><path class="loop" d="M845 396V420H159V234"/><text x="200" y="411" class="note">clarify, then resume the queued subject</text><rect class="card start" x="86" y="176" width="146" height="58" rx="10"/><text x="159" y="200" class="nodeTitle" text-anchor="middle">Queue row</text><text x="159" y="220" class="nodeMeta" text-anchor="middle">DIA-### or subject</text><rect class="card" x="272" y="176" width="166" height="58" rx="10"/><text x="355" y="200" class="nodeTitle" text-anchor="middle">Duplicate check</text><text x="355" y="220" class="nodeMeta" text-anchor="middle">compare subjects</text><rect class="card" x="478" y="176" width="146" height="58" rx="10"/><text x="551" y="200" class="nodeTitle" text-anchor="middle">Select type</text><text x="551" y="220" class="nodeMeta" text-anchor="middle">family template</text><rect class="card" x="664" y="176" width="156" height="58" rx="10"/><text x="742" y="200" class="nodeTitle" text-anchor="middle">Generate SVG</text><text x="742" y="220" class="nodeMeta" text-anchor="middle">motion optional</text><rect class="card" x="860" y="176" width="146" height="58" rx="10"/><text x="933" y="200" class="nodeTitle" text-anchor="middle">Validate XML</text><text x="933" y="220" class="nodeMeta" text-anchor="middle">standalone check</text><rect class="card safe" x="1046" y="176" width="160" height="58" rx="10"/><text x="1126" y="200" class="nodeTitle" text-anchor="middle">Index output</text><text x="1126" y="220" class="nodeMeta" text-anchor="middle">queue + overview</text><rect class="card start" x="1246" y="180" width="110" height="50" rx="25"/><text x="1301" y="210" class="nodeTitle" text-anchor="middle">Caller</text><rect class="card warn" x="478" y="348" width="180" height="48" rx="10"/><text x="568" y="377" class="nodeTitle" text-anchor="middle">Evidence blocker</text><rect class="card" x="760" y="348" width="170" height="48" rx="10"/><text x="845" y="377" class="nodeTitle" text-anchor="middle">devspec.clarify</text><text x="52" y="436" class="foot">ONE DIAGRAM PER RUN - QUEUE STATE IS DURABLE - CALLER LIFECYCLE STAGE IS NEVER CHANGED</text></svg>
diff --git a/docs/workflows.md b/docs/workflows.md
index f748329..06b9af3 100644
--- a/docs/workflows.md
+++ b/docs/workflows.md
@@ -29,9 +29,27 @@ Every project maintains one OWASP Top 10:2025 baseline in `foundation/rules.md`.
 
 ![Install and maintenance flow](assets/maintenance-flow.svg)
 
-## Diagram sample
+## 4. Generate one diagram
 
-For an evidence-backed architecture or workflow visual, choose a pattern from the [diagram type guide](../devspec/architecture/_template/diagram-types.md), then use the compact [diagram record sample](../devspec/architecture/_template/diagram-sample.md), its standalone [SVG sample](../devspec/architecture/_template/diagram-sample.svg), the opt-in [motion sample](../devspec/architecture/_template/diagram-motion-sample.svg), or its optional [HTML presentation sample](../devspec/architecture/_template/diagram-sample.html).
+![Diagram route](assets/diagram-route.svg)
+
+For an evidence-backed architecture or workflow visual, choose a pattern from the [diagram type guide](../devspec/architecture/_template/diagram-types.md), then start the SVG from the family template that guide selects. Each diagram type has its own template in `devspec/architecture/_template/`:
+
+| Diagram type | SVG template |
+|---|---|
+| System architecture | [`architecture-diagram.svg`](../devspec/architecture/_template/architecture-diagram.svg) |
+| Application landscape | [`application-landscape-diagram.svg`](../devspec/architecture/_template/application-landscape-diagram.svg) |
+| Infrastructure topology | [`infrastructure-topology-diagram.svg`](../devspec/architecture/_template/infrastructure-topology-diagram.svg) |
+| Process flow | [`process-flow-diagram.svg`](../devspec/architecture/_template/process-flow-diagram.svg) |
+| Sequence | [`sequence-diagram.svg`](../devspec/architecture/_template/sequence-diagram.svg) |
+| State lifecycle | [`state-lifecycle-diagram.svg`](../devspec/architecture/_template/state-lifecycle-diagram.svg) |
+| Domain model | [`domain-model-diagram.svg`](../devspec/architecture/_template/domain-model-diagram.svg) |
+| Journey map | [`journey-map-diagram.svg`](../devspec/architecture/_template/journey-map-diagram.svg) |
+| Timeline | [`timeline-plan-diagram.svg`](../devspec/architecture/_template/timeline-plan-diagram.svg) |
+| Quadrant | [`quadrant-analysis-diagram.svg`](../devspec/architecture/_template/quadrant-analysis-diagram.svg) |
+| Mind map | [`mindmap-diagram.svg`](../devspec/architecture/_template/mindmap-diagram.svg) |
+
+For the record that accompanies a diagram, use the compact [diagram record sample](../devspec/architecture/_template/diagram-sample.md) and its worked [SVG sample](../devspec/architecture/_template/diagram-sample.svg). The opt-in [motion sample](../devspec/architecture/_template/diagram-motion-sample.svg) shows the animation pattern, and the [HTML presentation sample](../devspec/architecture/_template/diagram-sample.html) shows the optional presentation shell.
 
 Assign a stable `DIA-###` ID, keep status in the queue, and add only completed diagram links to the overview index.
 
diff --git a/tests/test_framework.py b/tests/test_framework.py
index c939378..5ad906c 100644
--- a/tests/test_framework.py
+++ b/tests/test_framework.py
@@ -302,6 +302,8 @@ def test_family_specific_diagram_templates_are_installed_and_well_formed(self) -
             template_root = target / "devspec/architecture/_template"
             expected = (
                 "architecture-diagram.svg",
+                "application-landscape-diagram.svg",
+                "infrastructure-topology-diagram.svg",
                 "process-flow-diagram.svg",
                 "sequence-diagram.svg",
                 "state-lifecycle-diagram.svg",
@@ -320,6 +322,34 @@ def test_family_specific_diagram_templates_are_installed_and_well_formed(self) -
             diagram = (target / "devspec/contracts/devspec.diagram.md").read_text(encoding="utf-8")
             self.assertIn("Start each SVG from the matching family-specific template", diagram)
             self.assertIn("connectors behind cards", diagram)
+            self.assertIn("Anchor every connector to a shape edge at both ends", diagram)
+            types = (target / "devspec/architecture/_template/diagram-types.md").read_text(encoding="utf-8")
+            for name in expected:
+                with self.subTest(mapped=name):
+                    self.assertIn(f"`{name}`", types)
+
+    def test_diagram_templates_have_no_dangling_marker_references(self) -> None:
+        """A marker-end pointing at a missing id renders a connector with no arrowhead."""
+        with tempfile.TemporaryDirectory() as raw:
+            target = Path(raw)
+            main(["init", "--target", str(target), "--profile", "all", "--repo-state", "existing"])
+            namespace = "{http://www.w3.org/2000/svg}"
+            for path in sorted((target / "devspec/architecture/_template").glob("*.svg")):
+                with self.subTest(template=path.name):
+                    root = ElementTree.parse(path).getroot()
+                    defined = {marker.attrib.get("id") for marker in root.iter(f"{namespace}marker")}
+                    referenced = set()
+                    for element in root.iter():
+                        for attribute in ("marker-end", "marker-start", "filter", "fill", "stroke"):
+                            value = element.attrib.get(attribute, "")
+                            if value.startswith("url(#"):
+                                referenced.add(value[5:-1])
+                    self.assertTrue(referenced <= defined | {node.attrib.get("id") for node in root.iter()},
+                                    f"{path.name} references an undefined id")
+                    serialized = ElementTree.tostring(root, encoding="unicode")
+                    self.assertNotIn("<script", serialized)
+                    self.assertNotIn("foreignObject", serialized)
+                    self.assertNotIn("<iframe", serialized)
 
     def test_init_refuses_changed_managed_file(self) -> None:
         with tempfile.TemporaryDirectory() as raw: