devspec 0.1.2__tar.gz → 0.1.3__tar.gz

{devspec-0.1.2 → devspec-0.1.3}/.agents/rules/devspec-workflow.md

@@ -18,7 +18,7 @@ Follow these rules:
 - Use `devspec/foundation/codebase-structure.md` for repository access requirements.
 - Keep product context in `devspec/foundation/project-context.md`, durable principles in `devspec/constitution.md`, and operational governance, compliance rules, enforcement details, and delivery gates in `devspec/foundation/rules.md`.
 - Use `devspec/adapters/validation-flows.md` for enterprise acceptance checks.
-- For `/devspec.diagram`, keep Mermaid as the default output and treat `format=svg` or `format=mermaid+svg` as canonical command input, not a separate workflow.
+- For `/devspec.diagram`, keep SVG as the default output and treat any non-duplicated `format=` combination of `svg`, `html`, and `mermaid` as canonical command input. Example: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`.
 - Keep provider credentials, tokens, user settings, and secrets outside prompt, rule, skill, and artifact files.
 - Record unsupported Antigravity behavior as a limitation instead of changing workflow semantics.
 

devspec-0.1.3/.agents/skills/devspec-diagram.md

@@ -0,0 +1,17 @@
+---
+name: devspec-diagram
+description: Run /devspec.diagram using the canonical devspec command registry and Copilot reference contract.
+---
+
+Execute canonical command `/devspec.diagram`.
+
+- Read `devspec/adapters/command-registry.md` for the command contract.
+- Read `.github/prompts/devspec.diagram.prompt.md` and `.github/agents/devspec.diagram.agent.md` as the source of intent.
+- Preserve SVG as the default output. Pass through any non-duplicated `format=` combination of `svg`, `html`, and `mermaid`; examples include `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, and `format=html+mermaid`.
+- For SVG output, select the matching template from `.github/prompts/PATTERNS.md#svg-output-pattern`, including architecture, process-flow, sequence, state/lifecycle, domain-model, journey-map, timeline-plan, quadrant-analysis, and mindmap templates. Durable targets stay under `devspec/architecture/images/`, and validation follows `.github/prompts/PATTERNS.md#svg-output-pattern`.
+- Keep every generated SVG and HTML diagram on the shared dark architecture-style visual contract from `.github/prompts/PATTERNS.md#svg-output-pattern`, including custom smaller SVGs. Do not produce white/default/simple diagram styling unless the user explicitly requests a light or custom theme.
+- Preserve required inputs, output artifacts, status values, gates, handoff order, and recovery behavior.
+- Use Git-tracked `devspec/` artifacts for recovery before relying on chat history or Antigravity artifacts.
+- Treat unsupported Antigravity behavior as an adapter limitation, not a workflow change.
+
+Command input comes from the user's current message.

{devspec-0.1.2 → devspec-0.1.3}/.agents/skills/devspec-extract.md

@@ -8,7 +8,7 @@ Execute canonical command `/devspec.extract`.
 - Read `devspec/adapters/command-registry.md` for the command contract.
 - Read `.github/prompts/devspec.extract.prompt.md` and `.github/agents/devspec.extract.agent.md` as the source of intent.
 - Treat constitution changes as confirmation-gated candidates; route operational governance, compliance procedures, enforcement details, and delivery gates to `devspec/foundation/rules.md`.
-- Preserve `format=svg` and `format=mermaid+svg` as diagram generation preferences in queue notes; extraction remains queue-first and may generate at most one approved diagram artifact set only after the canonical approval gate.
+- Preserve any non-duplicated diagram `format=` combination of `svg`, `html`, and `mermaid` in queue notes; extraction remains queue-first and may generate at most one approved diagram artifact set only after the canonical approval gate.
 - Preserve required inputs, output artifacts, status values, gates, handoff order, and recovery behavior.
 - Use Git-tracked `devspec/` artifacts for recovery before relying on chat history or Antigravity artifacts.
 - Treat unsupported Antigravity behavior as an adapter limitation, not a workflow change.

{devspec-0.1.2 → devspec-0.1.3}/.claude/skills/devspec-diagram/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: devspec-diagram
-description: Run /devspec.diagram using the canonical devspec command registry. Generates evidence-backed diagrams, defaulting to Mermaid with opt-in SVG output, for architecture, workflows, journeys, sequences, states, timelines, and planning views. Supports mono-repo and multi-repo workspaces. Works across GitHub Copilot, Claude Code, OpenAI Codex, Cursor, and other AI agents.
+description: Run /devspec.diagram using the canonical devspec command registry. Generates evidence-backed diagrams, defaulting to SVG with optional Mermaid and HTML output, for architecture, workflows, journeys, sequences, states, timelines, and planning views. Supports mono-repo and multi-repo workspaces. Works across GitHub Copilot, Claude Code, OpenAI Codex, Cursor, and other AI agents.
 ---
 
 Execute canonical command `/devspec.diagram`.
@@ -9,7 +9,7 @@ Execute canonical command `/devspec.diagram`.
 2. Read `devspec/adapters/command-registry.md` for this command's required input, outputs, mutation level, and next handoff.
 3. Read `.github/prompts/devspec.diagram.prompt.md` and `.github/agents/devspec.diagram.agent.md` as the authoritative source of command intent and behavior.
 4. Apply `.github/prompts/PATTERNS.md` for shared behavior: interactive questions, prerequisite validation, session recovery, discovery exclusions, and output closure, including `PATTERNS.md#diagram-extraction-consistency-pattern`, `PATTERNS.md#svg-output-pattern`, `PATTERNS.md#mermaid-internal-naming-and-readability-pattern`, `PATTERNS.md#mermaid-visual-quality-pattern`, `PATTERNS.md#process-flow-extraction-pattern`, and `PATTERNS.md#excluded-diagram-families`.
-5. Treat Mermaid as the default output. Pass through `format=svg` for SVG-only output and `format=mermaid+svg` for both Mermaid and SVG; unsupported `format=` values require clarification.
+5. Treat SVG as the default output. Pass through any non-duplicated `format=` combination of `svg`, `html`, and `mermaid`; examples include `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, and `format=html+mermaid`. Unsupported or duplicated `format=` values require clarification.
 6. For every generated Mermaid `flowchart` or `stateDiagram-v2`: open with the dark theme init block, declare the semantic `classDef` palette for roles present, use role-appropriate node shapes, wrap boundaries of 3+ nodes in named `subgraph` blocks, draw cross-subgraph arrows after all `end` keywords, assign `classDef` classes in a batch block at the end, and verify node count stays within complexity guardrails. Never use an excluded family such as `architecture-beta`; substitute the documented portable alternative.
 7. For SVG output, use `devspec/architecture/_template/process-flow-diagram.svg` for process-flow rows or explicit process-flow SVG requests, otherwise use `devspec/architecture/_template/architecture-diagram.svg`. Write durable images under `devspec/architecture/images/`, and validate generated SVG as standalone XML with no scripts, iframes, foreignObject, external assets, secrets, or unresolved placeholders.
 8. Honor multi-repo boundaries: when `devspec/foundation/codebase-structure.md` records multiple repositories, scope diagram evidence to the correct repository boundary.

{devspec-0.1.2 → devspec-0.1.3}/.claude/skills/devspec-extract/SKILL.md

@@ -9,7 +9,7 @@ Execute canonical command `/devspec.extract`.
 2. Read `devspec/adapters/command-registry.md` for this command's required input, outputs, mutation level, and next handoff.
 3. Read `.github/prompts/devspec.extract.prompt.md` and `.github/agents/devspec.extract.agent.md` as the authoritative source of command intent and behavior.
 4. Apply `.github/prompts/PATTERNS.md` for shared behavior: interactive questions, prerequisite validation, session recovery, output closure, and specifically `PATTERNS.md#discovery-exclusion-pattern`, `PATTERNS.md#diagram-extraction-consistency-pattern`, `PATTERNS.md#svg-output-pattern`, and `PATTERNS.md#process-flow-extraction-pattern`. Do not queue diagram families listed in `PATTERNS.md#excluded-diagram-families` (such as `architecture-beta`) when seeding `devspec/architecture/artifact-queue.md`; use the documented portable alternative instead.
-5. Preserve `format=svg` and `format=mermaid+svg` as diagram generation preferences in queue notes. Extraction remains queue-first and may generate at most one approved diagram artifact set only after the canonical approval gate.
+5. Preserve any non-duplicated diagram `format=` combination of `svg`, `html`, and `mermaid` in queue notes. Extraction remains queue-first and may generate at most one approved diagram artifact set only after the canonical approval gate.
 6. For multi-repo extraction: process each repository source in sequence, apply discovery exclusions from `devspec/foundation/discovery-exclusions.md`, record per-repo evidence and status in `devspec/foundation/extraction-state.md`, and seed diagram candidates per-repo in `devspec/architecture/artifact-queue.md`.
 
 Command input comes from the user's current message.

{devspec-0.1.2 → devspec-0.1.3}/.cursor/rules/devspec-workflow.mdc

@@ -18,7 +18,7 @@ Follow these rules:
 - Use `devspec/glossary.md` for status values.
 - Use `devspec/foundation/codebase-structure.md` for repository access requirements.
 - Use `devspec/adapters/validation-flows.md` for enterprise acceptance checks.
-- For `/devspec.diagram`, keep Mermaid as the default output and treat `format=svg` or `format=mermaid+svg` as canonical command input, not a separate workflow.
+- For `/devspec.diagram`, keep SVG as the default output and treat any non-duplicated `format=` combination of `svg`, `html`, and `mermaid` as canonical command input. Example: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`.
 - Record unsupported platform behavior as a limitation instead of changing workflow semantics.
 
 Do not recommend unregistered commands such as `/devspec.plan`, `/devspec.architecture`, `/devspec.provider-integrations`, `/devspec.queue`, or `/devspec.decisions`.

{devspec-0.1.2 → devspec-0.1.3}/.gemini/commands/devspec/diagram.toml

@@ -8,7 +8,7 @@ Before acting:
 3. Follow `.github/prompts/PATTERNS.md` for shared workflow, recovery, output, discovery, and recommendation behavior.
 4. Recover from existing Git-tracked `devspec/` artifacts before relying on Gemini session memory.
 5. Preserve required inputs, output artifacts, status values, gates, handoff order, and recovery behavior.
-6. Preserve Mermaid as the default output, pass through `format=svg` for SVG-only output, and pass through `format=mermaid+svg` for both Mermaid and SVG.
+6. Preserve SVG as the default output. Pass through any non-duplicated `format=` combination of `svg`, `html`, and `mermaid`; examples include `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, and `format=html+mermaid`.
 7. For SVG output, use `devspec/architecture/_template/process-flow-diagram.svg` for process-flow rows or explicit process-flow SVG requests, otherwise use `devspec/architecture/_template/architecture-diagram.svg`. Durable targets stay under `devspec/architecture/images/`, and validation follows `.github/prompts/PATTERNS.md#svg-output-pattern`.
 8. Treat Gemini-specific command syntax as platform mechanics, not a workflow change.
 

{devspec-0.1.2 → devspec-0.1.3}/.gemini/commands/devspec/extract.toml

@@ -8,7 +8,7 @@ Before acting:
 3. Follow `.github/prompts/PATTERNS.md` for shared workflow, recovery, output, discovery, and recommendation behavior.
 4. Recover from existing Git-tracked `devspec/` artifacts before relying on Gemini session memory.
 5. Preserve required inputs, output artifacts, status values, gates, handoff order, and recovery behavior.
-6. Preserve `format=svg` and `format=mermaid+svg` as diagram generation preferences in queue notes; extraction remains queue-first and may generate at most one approved diagram artifact set only after the canonical approval gate.
+6. Preserve any non-duplicated diagram `format=` combination of `svg`, `html`, and `mermaid` in queue notes; extraction remains queue-first and may generate at most one approved diagram artifact set only after the canonical approval gate.
 7. Treat Gemini-specific command syntax as platform mechanics, not a workflow change.
 
 The user's raw command input, if any, is appended below these instructions by Gemini CLI.

{devspec-0.1.2 → devspec-0.1.3}/.github/agents/devspec.clarify.agent.md

@@ -16,11 +16,12 @@ handoffs:
 You create or update `devspec/work-items/<work-item-folder>/clarify.md`.
 
 ## Constraints
-- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
+- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Work-Item Change Request Pattern](../prompts/PATTERNS.md#work-item-change-request-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
 - `story.md` must exist.
 - Update `Workflow State` in `meta.md` and `Resume State` in `clarify.md` before asking or resolving a blocking question.
 - Handle one independent blocker at a time.
 - Resolve the active blocker recorded in `story.md`, `finalize.md`, user input, or existing `clarify.md`; do not run the full Readiness Gap Scan in this command.
+- Do not use clarification to introduce post-baseline scope. If user input for a work item in `finalized`, `tasks-planned`, `implementing`, `implemented`, `reviewing`, or `reviewed` status changes scope instead of resolving the active blocker, record the routing reason in `clarify.md`, leave baseline intake unchanged, and hand off to `/devspec.story`.
 - Preserve and apply the Question Basis Pattern for the active blocker.
 - For structured clarification questions, provide 2-5 meaningful and mutually exclusive options when possible, exactly one recommended option with a short reason, and `Custom Answer`.
 - Keep active and resolved blocker records only in `Clarification Log`; at most one row may be `open`.
@@ -32,7 +33,7 @@ You create or update `devspec/work-items/<work-item-folder>/clarify.md`.
 1. Locate the target work item.
 2. Read `meta.md` when present, `story.md`, `finalize.md` when present, and existing `clarify.md`.
 3. Reconcile `Resume State`; keep any pending user question active and preserve the source artifact for the active blocker.
-4. Ask or resolve the active structured `clarification` question, then update `clarify.md` with `Resume State` and `Clarification Log`.
+4. Classify user input against the active blocker; if it introduces post-baseline scope, route to `/devspec.story`, otherwise ask or resolve the active structured `clarification` question and update `clarify.md` with `Resume State` and `Clarification Log`.
 5. When a blocker is answered, update its `Clarification Log` row to `resolved`, `superseded`, or `withdrawn`, record the answer and impacted artifacts, and update any impacted upstream artifact by reference instead of duplicating full intake or finalization content.
 6. When no blocker remains open, update next action toward `/devspec.finalize` unless the recorded source artifact requires returning to `/devspec.story`.
 7. Report per Output Format.

{devspec-0.1.2 → devspec-0.1.3}/.github/agents/devspec.diagram.agent.md

@@ -1,6 +1,6 @@
 ---
 name: "devspec.diagram"
-description: "Use to generate or update one evidence-backed diagram, defaulting to Mermaid with opt-in SVG output, for architecture, workflows, journeys, sequences, states, timelines, planning views, or stable domain structures."
+description: "Use to generate or update one evidence-backed diagram, defaulting to SVG with optional Mermaid and HTML output, for architecture, workflows, journeys, sequences, states, timelines, planning views, or stable domain structures."
 tools: [read, edit, search, vscode/askQuestions]
 model: ["GPT-5.4 (copilot)", "GPT-5.3-Codex (copilot)", "Claude Sonnet 4.6 (copilot)", "Claude Haiku 4.5 (copilot)"]
 user-invocable: true
@@ -16,14 +16,18 @@ handoffs:
 You generate or update one diagram for a requested architecture, module, feature workflow, user journey, sequence, state, timeline, planning view, or stable domain subject.
 
 ## Constraints
-- Follow the [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Multi-Repo Validation Pattern](../prompts/PATTERNS.md#multi-repo-validation-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Discovery Exclusion Pattern](../prompts/PATTERNS.md#discovery-exclusion-pattern), [Diagram Extraction Consistency Pattern](../prompts/PATTERNS.md#diagram-extraction-consistency-pattern), [SVG Output Pattern](../prompts/PATTERNS.md#svg-output-pattern), [Mermaid Internal Naming and Readability Pattern](../prompts/PATTERNS.md#mermaid-internal-naming-and-readability-pattern), [Mermaid Visual Quality Pattern](../prompts/PATTERNS.md#mermaid-visual-quality-pattern), [Process Flow Extraction Pattern](../prompts/PATTERNS.md#process-flow-extraction-pattern), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
+- Follow the [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Multi-Repo Validation Pattern](../prompts/PATTERNS.md#multi-repo-validation-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Discovery Exclusion Pattern](../prompts/PATTERNS.md#discovery-exclusion-pattern), [Diagram Extraction Consistency Pattern](../prompts/PATTERNS.md#diagram-extraction-consistency-pattern), [Architecture Diagram Intake Pattern](../prompts/PATTERNS.md#architecture-diagram-intake-pattern), [Diagram Family Intake Pattern](../prompts/PATTERNS.md#diagram-family-intake-pattern), [SVG Output Pattern](../prompts/PATTERNS.md#svg-output-pattern), [Mermaid Internal Naming and Readability Pattern](../prompts/PATTERNS.md#mermaid-internal-naming-and-readability-pattern), [Mermaid Visual Quality Pattern](../prompts/PATTERNS.md#mermaid-visual-quality-pattern), [Process Flow Extraction Pattern](../prompts/PATTERNS.md#process-flow-extraction-pattern), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
 - Required user input is mandatory.
 - Apply the Work-Item Target Pattern only when the request is explicitly work-item-specific or clearly temporary for one work item, bug, or security issue.
-- Generate exactly one diagram artifact set per run unless the user continues through the queue or explicitly requests process-flow batch generation. A `format=mermaid+svg` request is one artifact set with two output files.
+- Generate exactly one diagram artifact set per run unless the user continues through the queue or explicitly requests process-flow batch generation.
 - Treat a clear `/devspec.diagram` request as approval to generate one diagram; ask only when target location, diagram type, scope, evidence, overwrite behavior, or queue continuation is ambiguous, using the matching `selection`, `clarification`, `approval`, or `continuation` intent.
 - Treat `/devspec.diagram Generate all process-flow diagrams` or equivalent wording as explicit batch-generation approval for eligible process-flow rows in `devspec/architecture/artifact-queue.md`.
-- Parse optional output format tokens before generation. Supported tokens are `format=mermaid`, `format=svg`, and `format=mermaid+svg`; default to `mermaid` when absent. Ask one structured `clarification` question for any other `format=` value.
+- Parse optional output format tokens before generation. Supported `format=` values contain one or more unique output types from `svg`, `html`, and `mermaid`, joined with `+`. Example: `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, `format=html+mermaid`. Default to `format=svg` when absent. Ask one structured `clarification` question for unknown or duplicated output types.
+- Parse structured architecture-diagram input using `PATTERNS.md#architecture-diagram-intake-pattern`; fields such as `Application/System`, `Architecture style`, `Primary goal of diagram`, `Audience`, actors, components, stores, flows, boundaries, design rules, and output format are approved diagram input for one artifact set.
+- Parse structured non-architecture diagram input using `PATTERNS.md#diagram-family-intake-pattern`; fields for sequence, state/lifecycle, domain model, journey, timeline/gantt, quadrant, and mindmap diagrams are approved diagram input for one artifact set when they match the selected diagram family.
+- Treat editable SVG, SVG-only output, real SVG text, "Generate as SVG", "Generate this as SVG", or "not as a raster image" as the default `format=svg` unless the user explicitly requests an output combination containing `html` or `mermaid`.
 - Do not invent architecture, user behavior, service interactions, states, or dependencies; separate observed facts from assumptions.
+- When structured input says not to add components not listed, treat listed actors, components, systems, and data stores as the complete visible node set unless a confirmed durable artifact conflict requires clarification.
 - Use the naming and layout guidance in `PATTERNS.md#diagram-extraction-consistency-pattern`, including the language-neutral default catalog when the request matches a catalog subject.
 - Use `PATTERNS.md#mermaid-internal-naming-and-readability-pattern` for Mermaid node ID, node label, edge label, class, method, layout, and anti-bloat rules.
 - Apply `PATTERNS.md#mermaid-visual-quality-pattern` fully (theme init, `classDef` palette, node shapes, subgraph boundaries, and guardrails) to every generated `flowchart` and `stateDiagram-v2`; apply complexity guardrails from that pattern to all other supported families.
@@ -33,44 +37,46 @@ You generate or update one diagram for a requested architecture, module, feature
 - Keep runtime communication and compile-time project dependencies in separate diagrams; default to runtime or logical data flow unless the user explicitly requests a project dependency graph.
 - For logical architecture diagrams, exclude SDLC actors, CI/CD, build artifacts, and source-code project files; enforce sensible C4-style system boundaries and keep owned application databases inside the system boundary.
 - Avoid API, Swagger, tech stack, version, library, hosting, and framework boilerplate details in flowchart nodes unless the requested diagram specifically needs startup, request-pipeline, infrastructure-layer, or physical deployment detail.
-- If the user asks for "only Mermaid", apply that restriction to the Mermaid content inside `Mermaid Diagram`; still preserve required devspec artifact metadata, source evidence, assumptions, and maintenance notes in the generated artifact.
-- If the user requests `format=svg`, create or update the Markdown diagram artifact for metadata, evidence, assumptions, maintenance notes, queue linkage, and SVG target reference, but omit the Mermaid block content. Create the SVG under `devspec/architecture/images/dia-NNN-<diagram-name>.svg` for durable diagrams or `devspec/work-items/<work-item-folder>/images/<diagram-name>.svg` for temporary work-item diagrams.
-- If the user requests `format=mermaid+svg`, create or update both the Markdown Mermaid diagram artifact and the SVG image file.
-- For SVG output, use `../../devspec/architecture/_template/process-flow-diagram.svg` when the request is explicitly a process-flow SVG or the matched queue row has `process-flow`, `business-process`, `user-journey`, `lifecycle-flow`, or `hybrid-user-to-data-operational-flow` tags. Use `../../devspec/architecture/_template/architecture-diagram.svg` for all other architecture, component, topology, dependency, domain, state, sequence companion, and general workflow SVGs.
+- If the user asks for "only Mermaid", treat it as `format=mermaid` and apply that restriction to the Mermaid content inside the optional Markdown artifact.
+- If the selected output set includes `svg`, create the SVG under `devspec/architecture/images/dia-NNN-<diagram-name>.svg` for durable diagrams or `devspec/work-items/<work-item-folder>/images/<diagram-name>.svg` for temporary work-item diagrams.
+- If the selected output set includes `mermaid`, create or update the optional Mermaid Markdown diagram artifact for metadata, evidence, assumptions, maintenance notes, queue linkage, and Mermaid content.
+- If the selected output set includes `html`, create or update the optional standalone HTML file under `devspec/architecture/html/dia-NNN-<diagram-name>.html` for durable diagrams or `devspec/work-items/<work-item-folder>/html/<diagram-name>.html` for temporary work-item diagrams.
+- All generated SVG and HTML diagram visuals must follow the shared dark architecture-style visual contract from `PATTERNS.md#svg-output-pattern`: dark slate page, framed surface, subtle grid or dividers, monospace typography, semantic neon role colors, real text labels, arrows behind nodes, compact legends, and no white/default/simple styling unless the user explicitly requests a light or custom theme.
+- For SVG output, select the template from `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`, using the most specific matching queue tags, explicit request, or diagram family.
 - Keep queue `Diagram type` as the logical diagram family. Choose the full Mermaid declaration for generated Mermaid content from queue notes, catalog guidance, or evidence, such as `flowchart LR`, `flowchart TD`, `flowchart BT`, `sequenceDiagram`, `stateDiagram-v2`, `erDiagram`, `gantt`, `quadrantChart`, `mindmap`, or `timeline`.
 - Prefer `flowchart LR` for relationship maps, dependency graphs, event flows, and pipelines; `flowchart TD` for context, topology, hierarchy, data movement, and risk grouping; `sequenceDiagram` for interactions over time; `journey` for user-facing flows; `stateDiagram-v2` for lifecycle behavior; `classDiagram` for stable domain or structural relationships; `erDiagram` for entity relationship models; `gantt` for sprint plans and release schedules; `timeline` for historical milestones and event sequences; `quadrantChart` for 2D priority or risk scoring; and `mindmap` for exploratory domain brainstorming when formal structure is not yet available.
 - Reuse matching queue metadata for subject, scope, diagram type, target location, evidence, and confidence instead of reclassifying from scratch unless the queued row is stale, contradicted, or incomplete.
-- Store stable system, module, feature workflow, user journey, sequence, state, class/domain, process-flow, and cross-feature diagrams under `devspec/architecture/diagrams/dia-NNN-<diagram-name>.md` by default.
+- Store stable system, module, feature workflow, user journey, sequence, state, class/domain, process-flow, and cross-feature diagrams under `devspec/architecture/images/dia-NNN-<diagram-name>.svg` by default. Store optional Mermaid Markdown companions under `devspec/architecture/diagrams/dia-NNN-<diagram-name>.md` and optional HTML companions under `devspec/architecture/html/dia-NNN-<diagram-name>.html`.
 - Store work-item diagrams only for explicit requests or clearly temporary bug reproduction, migration path, security incident or threat flow, implementation plan, or experiment flows that should not become durable architecture.
 - Keep `devspec/architecture/overview.md` limited to architecture context, diagram references, decision references, and architecture gaps or blockers.
 - Use `devspec/architecture/artifact-queue.md` as the resumable diagram queue.
 - For durable diagram files, write status only to `devspec/architecture/artifact-queue.md`; do not mirror queue status in the generated diagram file.
-- For work-item `diagrams.md`, do not maintain a separate diagram index or status; write temporary work-item-specific diagram content under `Diagram Content` and keep diagram status from `devspec/glossary.md#artifact-status-values` in `devspec/architecture/artifact-queue.md`.
+- For work-item diagrams, do not maintain a separate diagram index or status; write temporary SVG output under `images/`, optional Mermaid Markdown content under `Diagram Content`, optional HTML under `html/`, and keep diagram status from `devspec/glossary.md#artifact-status-values` in `devspec/architecture/artifact-queue.md`.
 - Update `Resume State` in the target diagram artifact, and `Workflow State` in `meta.md` only for work-item diagrams.
 - Update queue rows before asking for `confirmation`, `approval`, or `continuation`, after generation, or when evidence is missing.
-- For process-flow batch generation, select only rows where `Tags` includes `process-flow`, status is `proposed` or `confirmed`, confidence is `observed` or `high-confidence`, target location matches `devspec/architecture/diagrams/dia-NNN-<diagram-name>.md`, any recorded output format is valid, and `Next action or notes` records that duplicate check passed.
+- For process-flow batch generation, select only rows where `Tags` includes `process-flow`, status is `proposed` or `confirmed`, confidence is `observed` or `high-confidence`, target location matches `devspec/architecture/images/dia-NNN-<diagram-name>.svg` unless a non-SVG output set is explicitly requested, any recorded output format is valid, and `Next action or notes` records that duplicate check passed.
 - Generate process-flow batch rows in `DIA-*` order, never renumber existing rows, mark generated rows `generated`, and leave low-confidence, blocked, ambiguous, or duplicate rows queued with notes.
 - Ensure generated process-flow diagrams are end-to-end business or operational flows, not module call graphs. The hybrid user-to-data operational flow must include user entry points, application boundaries, services, data stores, validations, operational states, and outcomes without becoming a pure infrastructure or database diagram.
 - For process-flow SVGs, keep the happy path visually obvious, use distinct roles for start/end, manual, automated, integration, decision, exception, and artifact steps, draw exception paths as labeled dashed rose arrows, label loop-backs or rework paths, and avoid dangling branches.
-- Before writing, check `devspec/architecture/diagrams/*.md`, `devspec/architecture/images/*.svg`, `devspec/architecture/overview.md`, `devspec/architecture/artifact-queue.md`, and relevant work-item `diagrams.md` and `images/*.svg` files for equivalent diagrams.
-- Use `../../devspec/architecture/_template/diagram.md` for detailed architecture diagrams and `../../devspec/work-items/_template/diagrams.md` only for explicit or temporary work-item diagrams.
-- Use the selected SVG template from `../../devspec/architecture/_template/architecture-diagram.svg` or `../../devspec/architecture/_template/process-flow-diagram.svg` as the starting point unless a documented constraint requires a smaller custom SVG.
+- Before writing, check `devspec/architecture/images/*.svg`, `devspec/architecture/diagrams/*.md`, `devspec/architecture/html/*.html`, `devspec/architecture/overview.md`, `devspec/architecture/artifact-queue.md`, and relevant work-item `images/*.svg`, `diagrams.md`, and `html/*.html` files for equivalent diagrams.
+- Use `../../devspec/architecture/_template/diagram.md` only when the selected output set includes `mermaid` for detailed architecture diagrams, `../../devspec/architecture/_template/diagram.html` only when the selected output set includes `html`, and `../../devspec/work-items/_template/diagrams.md` only when the selected output set includes `mermaid` for explicit or temporary work-item diagrams.
+- Use the selected SVG template from `../../devspec/architecture/_template/` as the starting point unless a documented constraint requires a smaller custom SVG. A custom SVG must still preserve the shared dark visual contract.
 - Prefer existing devspec artifacts, queue rows, manifests, and targeted reads before broad search or Explore runs.
 - Never use an excluded diagram family from `PATTERNS.md#excluded-diagram-families`. If the user requests `architecture-beta`, `block`, `kanban`, `radar`, `sankey`, `venn`, `packet`, `zenuml`, `gitGraph`, `pie`, or `xychart-beta`, explain why it is excluded and offer the portable alternative in one sentence before proceeding with the alternative.
 
 ## Approach
-1. Parse the requested subject, scope, audience, and diagram type.
+1. Parse the requested subject, scope, audience, diagram type, and any structured architecture or diagram-family intake fields.
 2. Read relevant architecture, foundation, queue, and work-item artifacts only when referenced.
 3. Reconcile `Resume State`, existing queue rows, discovery exclusions, and optional exploration state.
 4. Match the request to an existing queue row when possible, then reuse its scope, diagram type, subject, target location, evidence, and confidence.
 5. Classify scope as `architecture`, `module`, `feature`, `workflow`, `user-journey`, or `work-item` only when no usable queue row exists.
-6. Select the output format, diagram type, and Mermaid declaration when Mermaid output is selected, or ask one structured `selection` question when the format, diagram type, declaration, or target location is ambiguous.
+6. Select the output format, diagram type, and Mermaid declaration when the selected output set includes `mermaid`, defaulting to `format=svg`, or ask one structured `selection` question when the format, diagram type, declaration, or target location is ambiguous.
 7. Gather evidence with targeted reads, search, or Explore.
 8. Check for an equivalent existing diagram before adding a queue row or writing output.
 9. Add or update queue rows with scope, diagram type, subject, target location, evidence, confidence, status, tags, and next action or notes that include the duplicate-check result.
 10. If the user requested process-flow batch generation, filter eligible process-flow rows and generate them in `DIA-*` order.
 11. Otherwise, ask one structured `clarification`, `approval`, or `continuation` question for clarification, overwrite approval, or queue continuation when needed.
-12. Generate selected output: for Mermaid, follow the Mermaid internal naming and visual quality rules; for SVG, follow the SVG Output Pattern, use the SVG template, avoid external assets and forbidden elements, and validate the file as XML before reporting success. Then write `Diagram Metadata`, selected diagram sections, `Source Evidence and Assumptions`, and any `Maintenance Notes` to the Markdown target, write the SVG target when selected, add or update the `overview.md` `Diagram Reference Index` row when the diagram is durable, mark generated queue rows `generated`, `skipped`, or `blocked`, and report per Output Format.
+12. Generate selected output: for SVG, follow the SVG Output Pattern, use the SVG template, avoid external assets and forbidden elements, and validate the file as XML before reporting success; for Mermaid output, create the optional Markdown artifact and follow Mermaid internal naming and visual quality rules; for HTML output, use the HTML template and keep it standalone and static. Then write selected output targets, add or update the `overview.md` `Diagram Reference Index` row when the diagram is durable, mark generated queue rows `generated`, `skipped`, or `blocked`, and report per Output Format.
 
 ## Output Format
 - Diagram target location

{devspec-0.1.2 → devspec-0.1.3}/.github/agents/devspec.extract.agent.md

@@ -41,17 +41,17 @@ You create or refresh devspec extraction artifacts from supported repository sou
 - Use `devspec/foundation/extraction-state.md` only for the extraction queue, resume state, blockers, and confirmations. Keep extracted facts in target artifacts, reusable discovery methods in `devspec/foundation/exploration-state.md`, and diagram queue state in `devspec/architecture/artifact-queue.md`.
 - Write or update `devspec/architecture/overview.md` and relevant live `devspec/foundation/` files.
 - Use `devspec/architecture/_template/*.md` and `devspec/foundation/_template/*.md` as section contracts; initialize missing live files from templates, but do not overwrite existing live files from templates.
-- During the `process-flows` extraction row, seed business-centric end-to-end process-flow candidates in `devspec/architecture/artifact-queue.md` when they meet the process-flow rubric and pass the equivalent-diagram check. Preserve requested output format notes when input includes `format=svg` or `format=mermaid+svg`; default remains `format=mermaid`.
+- During the `process-flows` extraction row, seed business-centric end-to-end process-flow candidates in `devspec/architecture/artifact-queue.md` when they meet the process-flow rubric and pass the equivalent-diagram check. Preserve requested output format notes when input includes supported diagram format tokens; default remains `format=svg`.
 - Include process-flow rows for business workflows, user journeys, lifecycle flows, cross-service process sequences, and the default `Hybrid User-to-Data Operational Flow` when evidence supports user entry points through application boundaries, services, integrations, data stores, validations, operational states, and outcomes.
 - During the `diagram-candidates` extraction row, seed non-process-flow architecture, module, feature workflow, sequence, state, class/domain, and user-journey candidates in `devspec/architecture/artifact-queue.md` only when they meet the diagram extraction rubric and pass the equivalent-diagram check.
 - Use the language-neutral default catalog in `PATTERNS.md#default-diagram-candidate-catalog` when selecting diagram candidates. Do not create language-, framework-, vendor-, or platform-specific default subjects.
 - Treat `/devspec.extract` as queue-first discovery seeding for diagram candidates; recommend `/devspec.diagram` as the normal follow-up for generation.
 - Add queued candidates in queue order with ID, scope, diagram type, subject, target location, evidence, confidence, status, tags, and next action or notes that include the duplicate-check result.
-- Use sequence-preserving naming for durable diagram candidates: `DIA-001` maps to subject `dia-001-<diagram-name>`, Markdown target `devspec/architecture/diagrams/dia-001-<diagram-name>.md`, and optional SVG target `devspec/architecture/images/dia-001-<diagram-name>.svg`. Never renumber existing `DIA-*` rows or generated `dia-NNN-*` files.
+- Use sequence-preserving naming for durable diagram candidates: `DIA-001` maps to subject `dia-001-<diagram-name>`, default SVG target `devspec/architecture/images/dia-001-<diagram-name>.svg`, optional Mermaid Markdown target `devspec/architecture/diagrams/dia-001-<diagram-name>.md`, and optional HTML target `devspec/architecture/html/dia-001-<diagram-name>.html`. Never renumber existing `DIA-*` rows or generated `dia-NNN-*` files.
 - Tag process-flow rows with `process-flow`, plus narrower tags such as `business-process`, `user-journey`, `lifecycle-flow`, or `hybrid-user-to-data-operational-flow` when they apply.
-- Keep queue `Diagram type` limited to the logical diagram family. Record suggested Mermaid declarations such as `flowchart LR`, `flowchart TD`, or `sequenceDiagram`, plus output format tokens such as `format=svg` or `format=mermaid+svg`, in `Next action or notes` when they will help `/devspec.diagram`.
-- When queueing process-flow or diagram candidates, record in queue notes that future Mermaid generation must follow `PATTERNS.md#mermaid-internal-naming-and-readability-pattern` and `PATTERNS.md#mermaid-visual-quality-pattern`, and future SVG generation must follow `PATTERNS.md#svg-output-pattern`. For process-flow SVG candidates, note that `/devspec.diagram` must use `devspec/architecture/_template/process-flow-diagram.svg`; for other SVG candidates, use `devspec/architecture/_template/architecture-diagram.svg`. Do not queue diagram families listed in `PATTERNS.md#excluded-diagram-families` such as `architecture-beta`, `block`, or `xychart-beta`; use the documented portable alternative instead.
-- Ask one structured `approval` question before generating diagrams during extraction. Generate at most one confirmed diagram artifact set only if the user explicitly continues within the extraction run, update its queue status, then stop or ask one structured `continuation` question only when no higher-priority confirmation is pending. Honor `format=svg` and `format=mermaid+svg` only after this approval.
+- Keep queue `Diagram type` limited to the logical diagram family. Record suggested Mermaid declarations such as `flowchart LR`, `flowchart TD`, or `sequenceDiagram` when the output set includes `mermaid`, plus requested output format tokens such as `format=svg`, `format=html`, `format=mermaid`, `format=svg+html`, `format=svg+mermaid`, `format=svg+html+mermaid`, or `format=html+mermaid`, in `Next action or notes` when they will help `/devspec.diagram`.
+- When queueing process-flow or diagram candidates, record in queue notes that future Mermaid generation must follow `PATTERNS.md#mermaid-internal-naming-and-readability-pattern` and `PATTERNS.md#mermaid-visual-quality-pattern`, and future SVG generation must select the SVG template from `PATTERNS.md#svg-output-pattern`. Do not queue diagram families listed in `PATTERNS.md#excluded-diagram-families` such as `architecture-beta`, `block`, or `xychart-beta`; use the documented portable alternative instead.
+- Ask one structured `approval` question before generating diagrams during extraction. Generate at most one confirmed diagram artifact set only if the user explicitly continues within the extraction run, update its queue status, then stop or ask one structured `continuation` question only when no higher-priority confirmation is pending. Honor requested diagram output formats only after this approval.
 - On rerun, resume `devspec/architecture/artifact-queue.md` before proposing duplicate candidates; when several queue items are pending, ask only about the next unresolved row.
 - Do not create ADR files unless the user explicitly asks and the decision has clear supporting evidence. When an ADR is needed, initialize it from `devspec/architecture/_template/decision.md` and create `devspec/architecture/decisions/` on demand.
 - For multi-repo inputs, produce an architecture overview, keep per-repository provenance visible, and use supplied labels as repository names and role candidates in `codebase-structure.md`.
@@ -74,8 +74,8 @@ You create or refresh devspec extraction artifacts from supported repository sou
 6. Use `Explore` only when targeted reads and search are insufficient for the active row.
 7. Update the active target artifact with compact evidence-backed records, preserving manual content.
 8. Record blockers, confirmations, or completion in `extraction-state.md` before asking, pausing, blocking, or moving to the next row.
-9. For `process-flows`, update only `devspec/architecture/artifact-queue.md`; queue eligible process-flow rows with `process-flow` tags, `dia-NNN-*` subjects, and notes covering actor or trigger, business outcome, decisions or state changes, data touchpoints, integrations, duplicate-check result, output format when specified, Mermaid declaration guidance, Mermaid internal naming guidance, and process-flow SVG template guidance when requested.
-10. For `diagram-candidates`, update only `devspec/architecture/artifact-queue.md`; include output format, Mermaid internal naming guidance, and SVG output guidance when requested in queue notes, and generate diagrams only through confirmed continuation or `/devspec.diagram`.
+9. For `process-flows`, update only `devspec/architecture/artifact-queue.md`; queue eligible process-flow rows with `process-flow` tags, `dia-NNN-*` subjects, and notes covering actor or trigger, business outcome, decisions or state changes, data touchpoints, integrations, duplicate-check result, output format when specified, Mermaid declaration and internal naming guidance when the output set includes `mermaid`, and process-flow SVG template guidance when the output set includes `svg`.
+10. For `diagram-candidates`, update only `devspec/architecture/artifact-queue.md`; include output format, Mermaid internal naming guidance when the output set includes `mermaid`, SVG output guidance when the output set includes `svg`, and HTML output guidance when the output set includes `html` in queue notes, and generate diagrams only through confirmed continuation or `/devspec.diagram`.
 11. For `constitution-candidates`, ask before writing principle-level changes; after confirmation, perform the constitution amendment impact check before updating the artifact.
 12. Continue one row at a time until blocked, waiting for user input, stopped, or complete.
 13. Report per Output Format.

{devspec-0.1.2 → devspec-0.1.3}/.github/agents/devspec.finalize.agent.md

@@ -16,9 +16,10 @@ handoffs:
 You create or update `devspec/work-items/<work-item-folder>/finalize.md`.
 
 ## Constraints
-- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Readiness Gap Scan Pattern](../prompts/PATTERNS.md#readiness-gap-scan-pattern), [Explore and Memory Pattern](../prompts/PATTERNS.md#explore-and-memory-pattern), [Multi-Repo Validation Pattern](../prompts/PATTERNS.md#multi-repo-validation-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Discovery Exclusion Pattern](../prompts/PATTERNS.md#discovery-exclusion-pattern), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
-- Required upstream artifacts must exist before finalization; use `story.md#summary`, `story.md#description`, `story.md#acceptance-criteria`, `story.md#functional-requirements`, `story.md#nonfunctional-requirements`, `story.md#edge-cases`, and `story.md#planning-signals` as the source for intake narrative, requirements, acceptance criteria, dependencies, type-specific notes, risks, and blockers.
+- Follow the [Work-Item Target Pattern](../prompts/PATTERNS.md#work-item-target-pattern), [Work-Item Change Request Pattern](../prompts/PATTERNS.md#work-item-change-request-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Readiness Gap Scan Pattern](../prompts/PATTERNS.md#readiness-gap-scan-pattern), [Explore and Memory Pattern](../prompts/PATTERNS.md#explore-and-memory-pattern), [Multi-Repo Validation Pattern](../prompts/PATTERNS.md#multi-repo-validation-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Discovery Exclusion Pattern](../prompts/PATTERNS.md#discovery-exclusion-pattern), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
+- Required upstream artifacts must exist before finalization; use `story.md#summary`, `story.md#change-requests`, `story.md#description`, `story.md#acceptance-criteria`, `story.md#functional-requirements`, `story.md#nonfunctional-requirements`, `story.md#edge-cases`, and `story.md#planning-signals` as the source for intake narrative, change requests, requirements, acceptance criteria, dependencies, type-specific notes, risks, and blockers.
 - Read `decisions.md` when present; use accepted work-item decisions as scope, planning, validation, rollout, or handoff inputs by referencing their `DEC-*` IDs.
+- When finalizing an accepted change request, set `Resume State` `Current item` to the active `CR-###` and append CR-scoped readiness, implementation brief, validation plan, and blocker rows. Preserve prior baseline and prior CR rows.
 - Run the Readiness Gap Scan before setting `finalize.md` to `ready`.
 - Set `Readiness Assessment` status to `ready` only when every required readiness gate is `ready` or `not applicable`; otherwise set it to `not ready`.
 - Mark the brief `not ready` while blockers remain or required repository access, foundation alignment, architecture alignment, compliance handling, or validation expectations are missing, ambiguous, conflicting, or unconfirmed.
@@ -29,6 +30,7 @@ You create or update `devspec/work-items/<work-item-folder>/finalize.md`.
 - Ensure every acceptance criterion, type-specific requirement, delivery gate, and material risk has validation coverage in `Validation Plan` or a blocking reason before marking `ready`.
 - For multi-repo work, record only repository readiness summary in `Implementation Brief`, including required repositories and whether access is confirmed, missing, or blocked; keep local paths and access requirement values in `../../devspec/foundation/codebase-structure.md`.
 - Do not invent missing requirements or silently change scope.
+- Do not rewrite baseline readiness, implementation brief, validation plan, or blocker rows to fit later change-request scope.
 - Use `Explore` when implementation context, analogous behavior, or impact areas need quick discovery.
 - Use session memory only for transient notes; `finalize.md` remains canonical.
 - Update `Workflow State` in `meta.md` and `Resume State` in `finalize.md` before marking `not ready`, asking for clarification, or handing off.
@@ -47,7 +49,7 @@ You create or update `devspec/work-items/<work-item-folder>/finalize.md`.
 2. Read `meta.md` when present, `decisions.md` when present, required upstream artifacts, and applicable foundation and architecture alignment sources.
 3. Reconcile `Resume State`, discovery exclusions, and optional exploration state.
 4. Use `Explore` when needed; persist meaningful discovery notes and unresolved assumptions before asking or writing.
-5. Run the Readiness Gap Scan, including foundation and architecture alignment, and map material gaps into readiness gates, `Implementation Brief`, `Validation Plan`, or blockers.
+5. Run the Readiness Gap Scan for the current item (`baseline` or active `CR-###`), including foundation and architecture alignment, and map material gaps into readiness gates, `Implementation Brief`, `Validation Plan`, or blockers.
 6. Resolve target selection or blockers through structured `selection` or `clarification` questions following the Interactive Question Pattern; use `/devspec.clarify` for the top blocking ambiguity when a separate clarification handoff is needed.
 7. Apply type-specific readiness gates and write `finalize.md` with `../../devspec/work-items/_template/finalize.md`.
 8. Report per Output Format.

{devspec-0.1.2 → devspec-0.1.3}/.github/agents/devspec.implement-task.agent.md

@@ -16,9 +16,10 @@ handoffs:
 You implement the current work item and update `devspec/work-items/<work-item-folder>/implement.md`.
 
 ## Constraints
-- Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Multi-Repo Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure.
+- Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Work-Item Change Request Pattern, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Multi-Repo Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure.
 - `finalize.md` must be `ready` and `tasks.md` must exist.
 - Implement pending rows from `tasks.md#implementation-tasks` sequentially unless the user stops or skips.
+- For change-request implementation, implement only pending rows whose `Scope` matches the active `CR-###` unless the user explicitly directs otherwise; preserve baseline and prior CR evidence.
 - Validate target repository path and access before changing code or running validation for multi-repo tasks.
 - Stop before implementation when target repository access is missing, ambiguous, or unconfirmed; direct the user to `/devspec.codebase-structure`.
 - Do not edit repositories marked `reference-only`, `validation-only`, `release-coordination`, or `unavailable` without structured confirmation.
@@ -27,7 +28,7 @@ You implement the current work item and update `devspec/work-items/<work-item-fo
 - Keep the work item as the orchestration boundary and execute one repository-aware task checkpoint at a time.
 - For monorepos, distinguish tasks by target area, module, layer, or validation surface; for multi-repo work, every task must name target repository and access requirement.
 - Apply the Minimum Necessary Implementation Pattern before each task attempt, including confirming whether the task requires a code change.
-- Apply the Task Quality Gate Pattern before each task attempt, respecting `Depends on` and `Source refs` from `tasks.md`; record any task-quality blocker in `implement.md` and stop for the required structured question.
+- Apply the Task Quality Gate Pattern before each task attempt, respecting `Scope`, `Depends on`, and `Source refs` from `tasks.md`; record any task-quality blocker in `implement.md` and stop for the required structured question.
 - Use targeted reads and searches from `tasks.md` target areas before broad discovery.
 - Resume a `paused` current task when prerequisites still hold; ask one structured `resume` question for `stopped` or ambiguous state.
 - Update `implement.md` using `../../devspec/work-items/_template/implement.md`.
@@ -39,6 +40,7 @@ You implement the current work item and update `devspec/work-items/<work-item-fo
 - If code changes are not applicable in the configured target repository, record that clearly.
 - Keep `Implementation Task Ledger`, `Implementation Execution Log`, and `Resume State` current after each task, validation run, blocker, pause, stop, or retry escalation.
 - Keep `tasks.md#implementation-tasks` `Status`, `Attempt count`, and `Last checkpoint` aligned with `implement.md` after each task attempt, validation result, blocker, skip, or completion.
+- Append implementation evidence and execution-log rows. Do not remove or rewrite prior baseline or prior CR evidence except to add explicit correction notes.
 - Keep `implement.md` recovery-focused; omit empty evidence and record only access checks, changes, validation, type-specific notes, risks, retries, blockers, telemetry, and handoff details.
 - Do not narrate rejected implementation options unless they explain a risk, blocker, retry, or review concern.
 - Record implementation progress in compact tables.
@@ -52,7 +54,7 @@ You implement the current work item and update `devspec/work-items/<work-item-fo
 5. Resolve target selection, blocker clarification, or multi-repo access before implementation.
 6. Record pre-run token telemetry or mark it unavailable.
 7. Apply type-specific work-item handling rules for bugs and security vulnerabilities.
-8. Select the next paused or pending task; if none remain, update `implement.md`, mark completion, and notify the user.
+8. Select the next paused or pending task for the active scope; if none remain, update `implement.md`, mark completion, and notify the user.
 9. Apply the Minimum Necessary Implementation Pattern and Task Quality Gate Pattern, implement the task when applicable, and run appropriate validation.
 10. Record reusable search, helper-command, repair, or validation methods.
 11. Update `implement.md` with access status, implementation task ledger, checkpoints, implementation execution log, changed files, validation, blockers, type-specific notes, counts, and confirmation outcome; update the matching task row in `tasks.md` when its status, attempt count, or checkpoint changed.

{devspec-0.1.2 → devspec-0.1.3}/.github/agents/devspec.review.agent.md

@@ -16,12 +16,14 @@ handoffs:
 You review the current work item and update `devspec/work-items/<work-item-folder>/review.md`.
 
 ## Constraints
-- Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure.
+- Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Work-Item Change Request Pattern, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure.
 - `finalize.md`, `tasks.md`, and `implement.md` must exist.
 - Review against the finalized brief, `tasks.md`, `implement.md`, and implemented changes, not a new plan.
+- For change-request review, review the active `CR-###` against its finalized rows, task rows, implementation evidence, and changed work while preserving prior baseline and prior CR review records.
 - Record findings with severity and required action when applicable.
 - Record task-quality, validation, scope, security, regression, and follow-up issues as `Review Findings`; use `Review Outcome` only for status, summary, scope alignment, validation coverage, task completion alignment, and type-specific summary notes.
 - Treat correctness, finalized scope, security, and validation coverage as primary review responsibilities; use the Minimum Necessary Implementation Pattern only to flag unnecessary dependencies, speculative abstractions, duplicated helper layers, oversized task outputs, or implementation not required by the finalized brief.
+- Flag overwritten baseline task content, missing CR source refs, CR implementation without appended task rows, source-ref drift between CR rows and tasks, and rewritten prior implementation or review evidence when they affect close readiness.
 - Apply review expectations from `../../devspec/foundation/rules.md#work-item-handling-rules` and any stricter delivery gates from `../../devspec/foundation/rules.md#delivery-gate-catalog`.
 - Update `Workflow State` in `meta.md` and `Resume State` in `review.md` before recording findings, asking for clarification, or handing off.
 
@@ -30,7 +32,7 @@ You review the current work item and update `devspec/work-items/<work-item-folde
 2. Read `meta.md` when present, `finalize.md`, `tasks.md`, `implement.md`, existing `review.md`, and relevant code context.
 3. Reconcile `Resume State`, discovery exclusions, and optional exploration state.
 4. Resolve target selection or blockers through structured `selection` or `clarification` questions following the Interactive Question Pattern.
-5. Check task completion alignment, source refs, scope adherence, bugs, regressions, security risks, validation gaps, missing tests, and unnecessary implementation complexity.
+5. Check task completion alignment, source refs, scope adherence, append-only preservation, bugs, regressions, security risks, validation gaps, missing tests, and unnecessary implementation complexity.
 6. Record reusable review discovery methods and write `review.md` with `../../devspec/work-items/_template/review.md`.
 7. Report per Output Format.
 

{devspec-0.1.2 → devspec-0.1.3}/.github/agents/devspec.story.agent.md

@@ -16,7 +16,7 @@ handoffs:
 You create or update work-item intake artifacts under `devspec/work-items/<work-item-folder>/`.
 
 ## Constraints
-- Follow the [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), [Work-Item Folder Naming Pattern](../prompts/PATTERNS.md#work-item-folder-naming-pattern), [Multi-Repo Validation Pattern](../prompts/PATTERNS.md#multi-repo-validation-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Discovery Exclusion Pattern](../prompts/PATTERNS.md#discovery-exclusion-pattern), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
+- Follow the [Prerequisite Validation Pattern](../prompts/PATTERNS.md#prerequisite-validation-pattern), [Session Recovery Pattern](../prompts/PATTERNS.md#session-recovery-pattern), [Interactive Question Pattern](../prompts/PATTERNS.md#interactive-question-pattern), [Question Basis Pattern](../prompts/PATTERNS.md#question-basis-pattern), [Work-Item Change Request Pattern](../prompts/PATTERNS.md#work-item-change-request-pattern), [Work-Item Folder Naming Pattern](../prompts/PATTERNS.md#work-item-folder-naming-pattern), [Multi-Repo Validation Pattern](../prompts/PATTERNS.md#multi-repo-validation-pattern), [Token Stewardship Pattern](../prompts/PATTERNS.md#token-stewardship-pattern), [Discovery Exclusion Pattern](../prompts/PATTERNS.md#discovery-exclusion-pattern), [Exploration Recovery Pattern](../prompts/PATTERNS.md#exploration-recovery-pattern), and [Output Closure Pattern](../prompts/PATTERNS.md#output-closure-pattern).
 - Required user input is mandatory.
 - Validate provider URLs or identifiers before treating input as resolved.
 - Use `devspec/foundation/provider-integrations.md` for provider resolution policy, supported inputs, outcome handling, confirmation requirements, manual fallback, integration access expectations, and source-resolution recording; initialize it from `devspec/foundation/_template/provider-integrations.md` when missing.
@@ -29,6 +29,10 @@ You create or update work-item intake artifacts under `devspec/work-items/<work-
 - Write or update `meta.md` and `story.md` using `../../devspec/work-items/_template/` as the section contract.
 - Keep `meta.md` as the work-item control record: `Work-Item Record`, `Triage Index`, and `Workflow State`.
 - Keep source confirmation and manual intake details in `story.md#source-record`; keep the concise requested outcome in `story.md#summary`; keep background, problem, impact, affected scope, and type-specific context in `story.md#description`; keep completion checks in `story.md#acceptance-criteria`; keep behavior in `story.md#functional-requirements`; keep quality attributes in `story.md#nonfunctional-requirements`; keep boundary and failure behavior in `story.md#edge-cases`; keep assumptions, dependencies, risks, blockers, terms, and scope exclusions in `story.md#planning-signals`; keep work-item decision records in `decisions.md`; do not duplicate those details in `meta.md`.
+- For existing work items whose `meta.md#workflow-state` `Work item status` is `finalized`, `tasks-planned`, `implementing`, `implemented`, `reviewing`, or `reviewed`, classify new user scope with the Work-Item Change Request Pattern before editing baseline intake.
+- Related post-baseline scope must append the next `CR-###` row in `story.md#change-requests` and CR-scoped criteria or requirement rows such as `CR-001-AC-001`, `CR-001-FR-001`, and `CR-001-NFR-001`; do not rewrite original `Summary`, `Description`, or baseline `AC-*`, `FR-*`, `NFR-*`, `EDGE-*`, or `Planning Signals` rows.
+- If post-baseline input appears independent or unrelated to the current story, ask one structured `selection` question before writing, with options to append to this work item, create a new linked work item, or provide `Custom Answer`. If the user chooses a linked work item, do not add a `CR-###` row to the original item.
+- When the user chooses a new linked work item, create it only through the standard folder naming pattern and record the original item in `meta.md#work-item-record` `Parent work item`; do not encode `CR-###` in the folder name.
 - Update `Workflow State` in `meta.md` and `Resume State` in `story.md` before asking provider, manual-intake, repo-dependency, or folder-naming questions when the folder exists; otherwise carry the pending state into the artifacts once created.
 - Record source resolution, confirmation, type, external reference, and type-appropriate urgency in `meta.md`; for features, record priority instead of severity.
 - Record impact and affected scope details in `story.md#description`, with only a compact routing summary in `meta.md#triage-index`.
@@ -47,11 +51,11 @@ You create or update work-item intake artifacts under `devspec/work-items/<work-
 1. Validate the incoming reference against supported provider formats.
 2. Check discovery exclusions and optional exploration state for known provider resolution methods in the same scope.
 3. Resolve or normalize the reference, or stop with correction guidance.
-4. For existing work items, read `meta.md` and `story.md` and reconcile `Resume State`.
+4. For existing work items, read `meta.md` and `story.md`, reconcile `Resume State`, and classify incoming scope as baseline intake, a related append-only change request, or a potential independent linked item.
 5. Ask one structured `clarification`, `confirmation`, or `selection` question when required.
 6. Collect manual intake fields if manual intake is chosen.
 7. Confirm the input is one story or work item; if not, ask the user to select one item or record a split blocker.
-8. Determine type, priority or severity, impacted scope, acceptance criteria, functional requirements, nonfunctional requirements, edge cases, planning signals, and multi-repo dependencies.
+8. Determine type, priority or severity, impacted scope, acceptance criteria, functional requirements, nonfunctional requirements, edge cases, planning signals, and multi-repo dependencies; for accepted change requests, append CR-scoped rows without rewriting baseline rows.
 9. Validate multi-repo configuration when dependencies exist.
 10. Derive and validate the folder name before creating or updating artifacts.
 11. Write the intake artifacts and report per Output Format.

{devspec-0.1.2 → devspec-0.1.3}/.github/agents/devspec.tasks.agent.md

@@ -13,9 +13,11 @@ handoffs:
 You create or update `devspec/work-items/<work-item-folder>/tasks.md`.
 
 ## Constraints
-- Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Explore and Memory, Multi-Repo Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure.
+- Follow [PATTERNS.md](../prompts/PATTERNS.md), especially: Work-Item Target, Work-Item Change Request Pattern, Session Recovery, Interactive Question, Question Basis, Prerequisite Validation, Explore and Memory, Multi-Repo Validation, Token Stewardship, Minimum Necessary Implementation, Task Quality Gate, Discovery Exclusion, Exploration Recovery, and Output Closure.
 - `finalize.md` must exist and be marked `ready`.
 - Do not change or expand the finalized scope.
+- For change-request planning, plan only the active `CR-###` recorded in `Resume State` or finalized source refs. Append new task rows after the highest existing `T-###`; do not regenerate, renumber, remove, or rewrite existing task rows.
+- Every task row must record `Scope` as `baseline` or the active `CR-###`.
 - Assign multi-repo tasks only to configured repositories whose access requirements support the planned work.
 - For monorepos, keep the work item as the orchestration boundary and distinguish executable tasks by target area, module, layer, or validation surface.
 - Use `reference-only` repositories for context only; surface a blocker when required repository access is missing, ambiguous, unconfirmed, or insufficient for needed edits or validation.
@@ -27,7 +29,7 @@ You create or update `devspec/work-items/<work-item-folder>/tasks.md`.
 - Default to 3-5 executable tasks for ordinary work items; use fewer for narrow changes and more only when repository boundaries, dependencies, validation surfaces, or finalized scope require it.
 - Merge planned tasks that target the same area and share the same validation unless separate checkpoints materially improve recovery or review.
 - Do not create standalone refactor, dependency, abstraction, cleanup, or future-proofing tasks unless `finalize.md` requires them.
-- Every task row must name source refs, a concrete target area or files, a specific validation method, an observable done condition, and dependency order.
+- Every task row must name scope, source refs, a concrete target area or files, a specific validation method, an observable done condition, and dependency order.
 - Use `finalize.md#implementation-brief` as the source for implementation scope, acceptance criteria, planning inputs, multi-repo readiness, type-specific requirements, risks, and follow-ups; use `finalize.md#validation-plan` for validation methods.
 - Do not copy finalized dependencies, repository lists, or validation methods into `Planning Basis`; record source references there and put executable details on the task rows that use them.
 - Use `Implementation Tasks` as the single table for ordered tasks, likely impacted areas, validation, and done criteria.
@@ -39,7 +41,7 @@ You create or update `devspec/work-items/<work-item-folder>/tasks.md`.
 4. Use `Explore` when needed; persist meaningful discovery notes, dependency mapping, and unresolved questions before asking or writing.
 5. Resolve target selection or blockers through structured `selection` or `clarification` questions following the Interactive Question Pattern.
 6. Apply the Task Quality Gate Pattern; block or ask one structured question for material planning gaps.
-7. Apply type-specific planning rules and write repository-aware tasks with `../../devspec/work-items/_template/tasks.md`.
+7. Apply type-specific planning rules and write repository-aware tasks with `../../devspec/work-items/_template/tasks.md`, appending change-request task rows when the current item is `CR-###`.
 8. Report per Output Format.
 
 ## Output Format