@multileaf/ai-workflow 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-13
+
+### Added
+
+- Persisted human approval gates for every SDD stage, with explicit optional-stage skips and invalidation when reviewed evidence changes.
+- Reviewable, fingerprint-bound installation previews with conflict detection and rollback on failed syncs.
+- Reusable implementation evidence and code review templates, plus completeness checks for every workflow stage.
+
+### Changed
+
+- Require an active workflow, ordered stage evidence, a passing quality gate, and explicit human approval before advancing SDD work.
+- Align generated bootstrap and stage skills with the enforced approval and installation flows.
+
+## [0.1.5] - 2026-09-12
+
+### Fixed
+
+- Connect SDD capability recommendations through explicit prerequisites so custom selections include required earlier workflow stages.
+- Recommend verification for supported project profiles and test runners, including test commands discovered in monorepo workspaces.
+- Align brainstorming, specification, planning, and verification gates with their matching artifacts; remove references to a nonexistent review gate command.
+- Clarify skill handoffs across brainstorming, requirements, design, planning, implementation, verification, and code review.
+- Correct the project profile path referenced by the project initialization skill.
+
 ## [0.1.4] - 2026-09-12
 
 ### Added
@@ -66,7 +89,8 @@ All notable changes to this project are documented in this file. The format foll
 
 - Path confinement, symlink protection, explicit permission gates, secret redaction, strict parsers, atomic migrations, and immutable execution checkpoints.
 
-[Unreleased]: https://github.com/MultiLeaf/aiw/compare/v0.1.4...HEAD
+[Unreleased]: https://github.com/MultiLeaf/aiw/compare/v0.1.5...HEAD
+[0.1.5]: https://github.com/MultiLeaf/aiw/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/MultiLeaf/aiw/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/MultiLeaf/aiw/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/MultiLeaf/aiw/compare/v0.1.1...v0.1.2

package/README.md

@@ -122,49 +122,67 @@ flowchart TD
     D --> E[(.aiw/recommendations.yml)]
     E --> F{User confirms scope}
     F -->|Revise| B
-    F -->|Proceed| G[Brainstorm]
-
-    G --> H[(generated/specs/brainstorm.md)]
-    H --> I{Brainstorm gate}
-    I -->|Incomplete| G
-    I -->|Complete| J[Write specification]
-
-    J --> K[(generated/specs/specification.md)]
-    K --> L{Specification gate}
-    L -->|Incomplete| J
-    L -->|Complete| M{Architecture decision needed?}
-
-    M -->|Yes| N[Create ADR]
-    N --> O[(.context/adrs/ADR-NNN-title.md)]
-    O --> P[Update ADR index]
-    P --> Q[(.context/adrs/INDEX.md)]
-    M -->|No| R[Create implementation plan]
-    Q --> R
-
-    R --> S[(generated/plans/implementation-plan.md)]
-    S --> T{Plan gate}
-    T -->|Incomplete| R
-    T -->|Ready| U[Implement tasks with TDD]
-
-    U --> V[Write code and tests]
-    V --> W[Run task validation commands]
-    W --> X{Validation passes?}
-    X -->|No| U
-    X -->|Yes| Y[Record completion evidence]
-
-    Y --> Z[(generated/artifacts and checkpoint evidence)]
-    Z --> AA[Verify declared evidence]
-    AA --> AB{Verification gate}
-    AB -->|Missing evidence| U
-    AB -->|Complete| AC[Build traceability graph]
-
-    AC --> AD[Requirement → ADR → Task → Code → Test → Evidence]
-    AD --> AE[(generated artifacts and trace output)]
-    AE --> AF[Run repository self-validation]
-    AF --> AG[(.aiw/checkpoints/self-validation-TICKET.yml)]
-    AG --> AH{Review outcome}
-    AH -->|Changes required| U
-    AH -->|Accepted| AI[Commit and independent integration validation]
+    F -->|Proceed| G{Clarification needed?}
+
+    G -->|Yes| H[Brainstorm]
+    H --> I[(generated/specs/brainstorm.md)]
+    I --> J{Brainstorm quality gate}
+    J -->|Incomplete| H
+    J -->|Complete| JH{Human approves brainstorm?}
+    JH -->|Revise| H
+    JH -->|Approve| K[Write specification]
+    G -->|No| K
+
+    K --> L[(generated/specs/specification.md)]
+    L --> M{Specification quality gate}
+    M -->|Incomplete| K
+    M -->|Complete| MH{Human approves requirements?}
+    MH -->|Revise| K
+    MH -->|Approve| N{Architecture decision needed?}
+
+    N -->|Yes| O[Create ADR]
+    O --> P[(.context/adrs/ADR-NNN-title.md)]
+    P --> Q[Update ADR index]
+    Q --> R[(.context/adrs/INDEX.md)]
+    R --> RH{Human approves design?}
+    RH -->|Revise| O
+    RH -->|Approve| S[Create implementation plan]
+    N -->|No| S
+
+    S --> T[(generated/plans/implementation-plan.md)]
+    T --> U{Plan quality gate}
+    U -->|Incomplete| S
+    U -->|Ready| UH{Human approves plan?}
+    UH -->|Revise| S
+    UH -->|Approve| V[Implement tasks with TDD]
+
+    V --> W[Write code and tests]
+    W --> X[Run task validation commands]
+    X --> Y{Validation passes?}
+    Y -->|No| V
+    Y -->|Yes| Z[Record completion evidence]
+
+    Z --> AA[(generated/artifacts and checkpoint evidence)]
+    AA --> AAH{Human accepts implementation?}
+    AAH -->|Revise| V
+    AAH -->|Approve| AB[Write verification report]
+    AB --> AC{Verification quality gate}
+    AC -->|Missing evidence| V
+    AC -->|Complete| ACH{Human approves verification?}
+    ACH -->|Revise| V
+    ACH -->|Approve| AG[Run code-review skill when installed]
+    AG --> AH{Review findings?}
+    AH -->|Changes required| V
+    AH -->|Clear| AHR{Human accepts review outcome?}
+    AHR -->|Address findings| V
+    AHR -->|Approve| AD[Build final traceability graph]
+    AD --> AE[Requirement → ADR → Task → Code → Test → Evidence]
+    AE --> AF[(generated artifacts and trace output)]
+    AF --> AFH{Human approves traceability?}
+    AFH -->|Revise| AD
+    AFH -->|Approve| AI[Run repository self-validation]
+    AI --> AJ[(.aiw/checkpoints/self-validation-TICKET.yml)]
+    AJ --> AK[Commit and independent integration validation]
 
     B -. command history and evidence .-> LOGS[(.aiw/checkpoints/)]
     D -. command history and evidence .-> LOGS
@@ -180,21 +198,39 @@ npx @multileaf/ai-workflow scan
 npx @multileaf/ai-workflow recommend
 
 # In CI, provide comma-separated recommendation IDs detected for that project.
-npx @multileaf/ai-workflow recommend --select=typescript-quality,vitest-testing
+npx @multileaf/ai-workflow recommend --select=typescript-quality,verification
 
-# Create structured product artifacts.
+# Track a feature from its first artifact through final human approval.
+npx @multileaf/ai-workflow workflow start
 npx @multileaf/ai-workflow brainstorm --title="Feature name"
+npx @multileaf/ai-workflow gate brainstorming
+# Present evidence and wait for a human reply before each approve command.
+npx @multileaf/ai-workflow approve brainstorming
 npx @multileaf/ai-workflow spec --title="Feature requirements"
+npx @multileaf/ai-workflow gate specification
+npx @multileaf/ai-workflow approve specification
 npx @multileaf/ai-workflow adr --id=001 --title="Technical decision"
+npx @multileaf/ai-workflow gate technical-design
+npx @multileaf/ai-workflow approve technical-design
 npx @multileaf/ai-workflow plan --title="Implementation plan"
-
-# Fill the generated scaffold sections before running their quality gates.
-npx @multileaf/ai-workflow gate specification
+npx @multileaf/ai-workflow gate plan
+npx @multileaf/ai-workflow approve plan
+# After implementation, write implementation-report.md and pass its gate.
+npx @multileaf/ai-workflow gate implementation
+npx @multileaf/ai-workflow approve implementation
+# Write verification-report.md and code-review.md before their gates.
+npx @multileaf/ai-workflow gate verification
+npx @multileaf/ai-workflow approve verification
+npx @multileaf/ai-workflow gate review
+npx @multileaf/ai-workflow approve review
 npx @multileaf/ai-workflow verify
 npx @multileaf/ai-workflow trace
+npx @multileaf/ai-workflow gate traceability
+npx @multileaf/ai-workflow approve traceability
+npx @multileaf/ai-workflow workflow complete
 ```
 
-Scaffold commands write deterministic files at fixed paths and a repeated invocation replaces that scaffold. Complete and review each artifact before advancing. Requirements use stable identifiers and Given/When/Then acceptance criteria. Plans link tasks to requirements, tests, risks, dependencies, and expected evidence. `gate` performs textual completeness checks, `verify` validates the expected verification fields rather than running a test command, and `trace` records declared links between requirements, decisions, tasks, code, tests, and evidence.
+Scaffold commands write deterministic files at fixed paths and a repeated invocation replaces that scaffold. Each applicable workflow stage requires two separate checks: its automated quality gate (when available), then explicit human approval. After presenting the artifact or evidence, the agent must stop and wait for the human before invoking the next skill, command, scaffold, or implementation action. A passing `aiw gate` validates artifact completeness only; it never records or implies human approval. Requirements use stable identifiers and Given/When/Then acceptance criteria. Plans link tasks to requirements, tests, risks, dependencies, and expected evidence. `verify` checks that the specification has acceptance criteria and the plan links requirements to validation; it does not execute project test commands. `trace` records declared links between requirements, decisions, tasks, code, tests, and evidence. Code review is performed with the `code-review` skill when installed; there is no separate review gate command, but the human must accept the review outcome before completion.
 
 ## Project intelligence
 

package/dist/adapter.js

@@ -40,24 +40,32 @@ This skill is the bootstrap for AI Workflow. The installer intentionally install
 
 ## First-run setup
 
-1. Before scanning, recommend that the user switch to a cheaper model for this onboarding. Ask whether they switched or prefer to continue with the current model; never change model settings yourself. Explain that analysis is read-only and optional resources will not be installed without their selection.
+### Mandatory interaction checkpoints
+
+This setup is gated by explicit user replies. A question is a blocking checkpoint, not narration: ask it, end your current response/turn immediately, and do no further analysis, tool calls, commands, or file changes until the user replies in a later turn. Never answer your own question, infer an answer from silence, or continue because a widget has a preselected value. If the host cannot pause for an answer, stop and ask the user to continue the setup after replying.
+
+1. Before scanning, recommend that the user switch to a cheaper model. Ask whether they switched or explicitly want to continue with the current model; never change model settings yourself. Explain that analysis is read-only and optional resources will not be installed without their selection. Then stop the turn and wait. Do not launch analysis agents or run \`aiw scan\` until the user replies. If the reply is unclear, ask again and stop; proceed only after an explicit answer to continue (including an explicit choice to keep the current model).
 2. Use the host's native subagent mechanism to launch these read-only analyses in parallel: (a) technologies, root and nested manifests, workspaces, and monorepo boundaries; (b) architecture, modules, entry points, and recurring code patterns; (c) tests, quality commands, CI, and developer tools. Keep the main agent as orchestrator. Wait for all results, verify important claims against cited project files, reconcile disagreements, and consolidate one evidence-backed project profile. Do not inspect secrets, ignored files, dependency directories such as \`node_modules\`, or generated output; inspect declared dependencies in project manifests. If subagents are unavailable, perform the same analyses directly and disclose the fallback.
 3. Run \`npx --yes --package=@multileaf/ai-workflow -- aiw scan\` and read \`.aiw/profile.yml\`. Treat this deterministic scan as another evidence source, not as a replacement for workspace-level analysis. Summarize each workspace separately; do not assume root dependencies or commands apply to every module. Ask the user to confirm uncertain or conflicting facts before using them as project policy. Add confirmed architecture and recurring patterns to the matching entries in the \`project_modules\` JSON array in \`.aiw/profile.yml\`, including file-path evidence; create a root-level entry when only the root project exists. Preserve existing detected fields and never store secrets or source-code excerpts there.
 4. Run \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend\` and read \`.aiw/recommendations.yml\`. Combine catalog results with the consolidated project profile. Recommend matching skills, rules, agents, hooks, templates, and MCP servers. For every MCP, disclose its publisher/source, purpose, capabilities, permissions, transport, and credential needs; verify them against current official host and server documentation. Recommend only integrations supported by project evidence and never invent credentials.
-5. Use the host's native selection widget. First offer three choices: install all recommendations, customize, or install none. If the user chooses customization, show the install plan in separate selectable blocks for skills, rules, agents, hooks, templates, and MCPs, with each item, its rationale, project-specific changes, and dependencies visible. If the host lacks a multi-select widget, use a numbered all/custom/none prompt and grouped checklists. MCP selection does not grant permission to execute the server or use external access; ask separately for those permissions.
-6. Record all recommendations with \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=all\`; for customized item-level choices, pass the selected resource references such as \`skills/verification,rules/tdd-policy,agents/test-engineer\`. Use \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=\` when none are chosen. If any AI Workflow resources are selected, run \`npx --yes --package=@multileaf/ai-workflow -- aiw sync\`, adding \`--allow=network:external\` only after separate approval. Install only selected resources and declared dependencies. Tailor instructions only where project evidence changes their usefulness (such as test commands, workspace boundaries, framework patterns, or module architecture). Preserve existing files, configuration, and secrets; report conflicts rather than overwriting them.
+5. Present recommendations as concise tables grouped by category: skills, rules, agents, hooks, templates, and MCPs. Include one row per recommended item and columns for the item, a short project-specific reason for the recommendation, and relevant evidence. For MCP rows, also summarize purpose, source, permissions, transport, and credential needs (use a separate table if needed). Do not show a flat list without category headings or generic reasons such as “useful for this project.” After the tables, use the host's native selection widget to offer three explicit choices: install all recommendations, customize, or install none. The widget must start with no choice selected; never accept a default or preselected value as the user's answer. If the user customizes, show selectable category blocks and individual items, keeping each item's short reason and declared prerequisites visible. Read \`requires\` from \`.aiw/recommendations.yml\`; explain that choosing a stage auto-selects its prerequisite capabilities and their resources. If the host lacks a multi-select widget, ask a numbered all/custom/none question and stop the turn to wait for the reply. Do not run a selection command or install anything until a reply/explicit widget submission arrives in a later turn. A dismissed widget, empty answer, silence, or ambiguous answer means no consent; ask again or stop without installing. MCP selection does not grant permission to execute the server or use external access; ask separately for those permissions.
+6. Only after receiving the user's explicit all/custom/none choice, record it: use \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=all\` for an explicit all choice; for customized item-level choices, pass only the selected resource references such as \`skills/verification,rules/tdd-policy,agents/test-engineer\`; use \`npx --yes --package=@multileaf/ai-workflow -- aiw recommend --select=\` for an explicit none choice. Before syncing a non-empty selection, show the exact selected resources and their prerequisites. Run \`npx --yes --package=@multileaf/ai-workflow -- aiw sync --preview\` and show the complete plan, including additions, updates, preserved files, conflicts, and any external permissions. Ask the user to approve this exact plan and stop the turn. Run sync only after that confirmation arrives in a later turn. Only after a later explicit approval, rerun preview if selection or project files changed, then run \`npx --yes --package=@multileaf/ai-workflow -- aiw sync --approve-plan=<fingerprint>\` using the fingerprint from the approved preview. A changed plan or conflict must stop without writes. Remote skills are not installed by sync: ask separately for network access and installation approval, then use \`npx --yes --package=@multileaf/ai-workflow -- aiw skills install --source=vercel-labs/agent-skills --skill=vercel-react-best-practices --allow=network:external\`. MCP configuration, server execution, and credentials each require separate consent. Install only confirmed selected resources and declared dependencies. Tailor instructions only where project evidence changes their usefulness (such as test commands, workspace boundaries, framework patterns, or module architecture). Preserve existing files, configuration, and secrets; report conflicts rather than overwriting them.
 7. For selected MCPs, add only the selected servers to the host's supported project configuration. Check current official host and server documentation for the configuration format, merge existing settings without replacing unrelated entries, and use environment-variable references instead of literal credentials. Do not run server install/start/authentication commands without separate approval. If the target requires user-level changes or safe configuration cannot be validated, give the user exact manual steps and report the MCP as pending rather than installed.
-8. Report installed resources by block, project-specific changes, skipped recommendations, MCP trust/authentication steps, and conflicts. Recommend restarting or reloading the coding-agent session so it discovers newly installed resources; follow known host behavior if it reloads changes automatically. Introduce only the gates supported by installed resources: brainstorming → specification → architecture decision when needed → implementation plan → implementation with tests → verification → traceability → review.
+8. Report installed resources by block, project-specific changes, skipped recommendations, MCP trust/authentication steps, and conflicts. Recommend restarting or reloading the coding-agent session so it discovers newly installed resources; follow known host behavior if it reloads changes automatically. Introduce only the gates supported by installed resources: brainstorming → specification → architecture decision when needed → implementation plan → implementation with tests → verification → code review → traceability.
 
 If the user declines all recommendations, leave the project with only the bootstrap skill and scan state. Do not treat scanning or recommendation as consent to install.
 
 ## For each feature request after setup
 
-- Start with the brainstorming skill when scope, users, constraints, or assumptions are unclear.
-- Create and complete a specification with stable requirement IDs and Given/When/Then acceptance criteria; pass \`npx --yes --package=@multileaf/ai-workflow -- aiw gate specification\` before planning.
-- Record consequential architecture choices as ADRs. Create an implementation plan that links tasks to requirements, tests, risks, and validation commands; pass \`npx --yes --package=@multileaf/ai-workflow -- aiw gate plan\` before coding.
-- Follow the TDD policy and project quality rules. Use specialist agents for requirements, architecture, implementation, tests, security, documentation, and review when useful.
-- Run the declared checks, then \`npx --yes --package=@multileaf/ai-workflow -- aiw verify\`, \`npx --yes --package=@multileaf/ai-workflow -- aiw trace\`, and the review gate. Do not claim completion without evidence.
+### Mandatory human gates between stages
+
+For every CLI command below, use \`npx --yes --package=@multileaf/ai-workflow -- aiw <command>\`; do not assume a global \`aiw\` binary exists. Start each feature request with \`npx --yes --package=@multileaf/ai-workflow -- aiw workflow start\` and check progress with \`npx --yes --package=@multileaf/ai-workflow -- aiw workflow status\`. Complete it with \`npx --yes --package=@multileaf/ai-workflow -- aiw workflow complete\` only after all stages resolve. The \`aiw gate <stage>\` command checks evidence and records a pending review; a passing result is not human approval. At every stage boundary—brainstorming, specification, technical design, plan, implementation, verification, code review, and traceability—present the exact artifact/evidence, ask whether the user approves proceeding, end the turn, and wait for an explicit reply in a later turn. On approval, record it with \`npx --yes --package=@multileaf/ai-workflow -- aiw approve <stage>\`; if the user asks for changes, record the rejection first with \`npx --yes --package=@multileaf/ai-workflow -- aiw reject <stage> --reason=<feedback>\`, then revise and rerun the gate. Do not invoke the next skill, create its scaffold, run its commands, or edit its artifacts before approval is recorded or the pending stage is rejected. Silence, an ambiguous reply, an automated gate pass, or earlier approval never counts. Brainstorming and technical design may be skipped only after explaining why and receiving explicit human acceptance; record each skip with \`npx --yes --package=@multileaf/ai-workflow -- aiw skip <stage> --reason=<accepted reason>\`.
+
+- Use the brainstorming skill when scope, users, constraints, or assumptions are unclear; create its artifact with \`npx --yes --package=@multileaf/ai-workflow -- aiw brainstorm\`, validate it with \`npx --yes --package=@multileaf/ai-workflow -- aiw gate brainstorming\`, present it, wait, then record the reply with \`npx --yes --package=@multileaf/ai-workflow -- aiw approve brainstorming\` before specification. If unnecessary, ask to skip and record explicit acceptance with \`npx --yes --package=@multileaf/ai-workflow -- aiw skip brainstorming --reason=...\`.
+- Create a specification with stable requirement IDs and Given/When/Then acceptance criteria; pass \`npx --yes --package=@multileaf/ai-workflow -- aiw gate specification\`, present it, wait, and record approval before design or planning.
+- For changes with architecture impact, write \`.aiw/generated/reports/technical-design.md\` using the technical-design template, record consequential choices as ADRs, pass \`npx --yes --package=@multileaf/ai-workflow -- aiw gate technical-design\`, and obtain/record approval before planning. If design is unnecessary, obtain explicit acceptance and record a reasoned skip. Then create an implementation plan with \`npx --yes --package=@multileaf/ai-workflow -- aiw plan\`, pass \`npx --yes --package=@multileaf/ai-workflow -- aiw gate plan\`, present it, wait, and record approval before coding.
+- When TDD resources are installed and the project has a test workflow, follow the TDD policy; otherwise use the project's existing validation methods. Follow installed project quality rules and use specialist agents only when useful. After implementation, write \`.aiw/generated/reports/implementation-report.md\` with changed files, tests, validation, and deviations; pass \`npx --yes --package=@multileaf/ai-workflow -- aiw gate implementation\`, present the diff/evidence, wait, and record approval before verification.
+- Run declared checks, write \`.aiw/generated/reports/verification-report.md\`, pass \`npx --yes --package=@multileaf/ai-workflow -- aiw gate verification\`, run \`npx --yes --package=@multileaf/ai-workflow -- aiw verify\`, present results, wait, and record approval before review. Write \`.aiw/generated/reports/code-review.md\` with findings/checks/risks/decision, pass \`npx --yes --package=@multileaf/ai-workflow -- aiw gate review\`, present findings, wait, and record approval before \`npx --yes --package=@multileaf/ai-workflow -- aiw trace\`. Pass \`npx --yes --package=@multileaf/ai-workflow -- aiw gate traceability\`, present the final graph, wait, record approval, then complete the workflow. Do not claim completion without evidence.
 
 ## Language policy
 

package/dist/generator.js

@@ -2,18 +2,28 @@ import { resolveGeneratedPath } from "./drift.js";
 export function generateProjectResources(profile, selected, write) {
     const linterCommand = safeInlineValue(profile.quality.linter?.command);
     const formatterCommand = safeInlineValue(profile.quality.formatter?.command);
-    const testCommand = safeInlineValue(profile.testing?.command);
+    const testCommands = [
+        ...(profile.testing?.command ? [{ scope: "project", command: profile.testing.command }] : []),
+        ...(profile.modules ?? []).flatMap((module) => module.testing?.command
+            ? [{ scope: `workspace ${module.path}`, command: module.testing.command }]
+            : []),
+    ].map(({ scope, command }) => ({ scope, command: safeInlineValue(command) }));
+    const uniqueTestCommands = [
+        ...new Map(testCommands
+            .filter(({ command }) => command)
+            .map(({ scope, command }) => [`${scope}:${command}`, { scope, command }])).values(),
+    ];
     if (selected.includes("typescript-quality") || selected.includes("rules/project-quality"))
         write(resolveGeneratedPath("rules/project-quality.md"), `# Project Quality Rules\n\n- Use ${profile.runtime.languages.map((language) => (language === "typescript" ? "TypeScript" : language)).join(", ")} with strict typing.\n${linterCommand ? `- Run \`${linterCommand}\` before completion.\n` : ""}${formatterCommand ? `- Run \`${formatterCommand}\` before review.\n` : ""}- Keep all generated AI Workflow artifacts in English.\n`);
     if (selected.includes("tdd-development") || selected.includes("rules/tdd-project-policy"))
-        write(resolveGeneratedPath("rules/tdd-project-policy.md"), `# TDD Project Policy\n\n${testCommand ? `- Run \`${testCommand}\` for verification.\n` : ""}- Write a failing behavioral test before implementation.\n- Refactor only after the test is green.\n`);
+        write(resolveGeneratedPath("rules/tdd-project-policy.md"), `# TDD Project Policy\n\n${uniqueTestCommands.map(({ scope, command }) => `- Run the ${scope} test command \`${command}\` for verification.`).join("\n")}${uniqueTestCommands.length ? "\n" : ""}- Write a failing behavioral test before implementation.\n- Refactor only after the test is green.\n`);
     if (selected.includes("nextjs-development") ||
         selected.includes("react-best-practices") ||
         selected.includes("rules/architecture-policy"))
         write(resolveGeneratedPath("agents/project-context.md"), `# Project Context\n\nThis project uses ${profile.frameworks.map((framework) => (framework === "nextjs" ? "Next.js" : framework)).join(", ")}. Follow the detected project structure and existing framework conventions.\n`);
     if (selected.length > 0) {
         write(resolveGeneratedPath("context/project-profile.md"), `# Confirmed Project Profile\n\n- Languages: ${profile.runtime.languages.join(", ") || "none detected"}\n- Frameworks: ${profile.frameworks.join(", ") || "none detected"}\n- Package manager: ${profile.packageManager}\n- All generated content is in English.\n`);
-        write(resolveGeneratedPath("hooks/quality-check.md"), `# Quality Check Hook\n\nRun the available project quality commands before completion.${linterCommand ? `\n\n- Linter: \`${linterCommand}\`` : ""}${formatterCommand ? `\n- Formatter: \`${formatterCommand}\`` : ""}${testCommand ? `\n- Tests: \`${testCommand}\`` : ""}\n`);
+        write(resolveGeneratedPath("hooks/quality-check.md"), `# Quality Check Hook\n\nRun the available project quality commands before completion.${linterCommand ? `\n\n- Linter: \`${linterCommand}\`` : ""}${formatterCommand ? `\n- Formatter: \`${formatterCommand}\`` : ""}${uniqueTestCommands.map(({ scope, command }) => `\n- ${scope} tests: \`${command}\``).join("")}\n`);
     }
 }
 function safeInlineValue(value) {

package/dist/human-approval.d.ts

@@ -0,0 +1,51 @@
+import { type HumanApprovalStage } from "./types.js";
+export declare const APPROVAL_STAGES: readonly ["brainstorming", "specification", "technical-design", "plan", "implementation", "verification", "review", "traceability"];
+export type ApprovalStatus = "draft" | "pending-human" | "approved" | "rejected" | "skipped" | "stale";
+export type QualityGateResult = "not-run" | "passed" | "failed" | "not-applicable";
+export type StageApprovalRecord = {
+    status: ApprovalStatus;
+    qualityGate: QualityGateResult;
+    artifactHash?: string;
+    reason?: string;
+    updatedAt: string;
+};
+export type ApprovalLedger = {
+    schema: 1;
+    workflowId: string;
+    stages: Partial<Record<HumanApprovalStage, StageApprovalRecord>>;
+};
+export type WorkflowSession = {
+    schema: 1;
+    workflowId: string;
+    status: "active" | "complete";
+    startedAt: string;
+    updatedAt: string;
+};
+export type ApprovalStageDefinition = {
+    optional: boolean;
+    requiresQualityGate: boolean;
+};
+export declare function createApprovalLedger(workflowId: string): ApprovalLedger;
+export declare function serializeWorkflowSession(session: WorkflowSession): string;
+export declare function parseWorkflowSession(content: string): WorkflowSession;
+export declare function stageDefinition(stage: HumanApprovalStage): ApprovalStageDefinition;
+export declare function stageFingerprint(content: string | Uint8Array): string;
+export declare function getUnresolvedPrerequisites(ledger: ApprovalLedger, stage: HumanApprovalStage): HumanApprovalStage[];
+export declare function beginStageApproval(ledger: ApprovalLedger, stage: HumanApprovalStage, input: {
+    artifactHash: string;
+    qualityGate: QualityGateResult;
+    updatedAt: string;
+}): ApprovalLedger;
+export declare function approveStage(ledger: ApprovalLedger, stage: HumanApprovalStage, input: {
+    artifactHash: string;
+    updatedAt: string;
+}): ApprovalLedger;
+export declare function rejectStage(ledger: ApprovalLedger, stage: HumanApprovalStage, reason: string, updatedAt: string): ApprovalLedger;
+export declare function skipOptionalStage(ledger: ApprovalLedger, stage: HumanApprovalStage, input: {
+    reason: string;
+    humanAccepted: boolean;
+    updatedAt: string;
+}): ApprovalLedger;
+export declare function invalidateStageAndDescendants(ledger: ApprovalLedger, stage: HumanApprovalStage, updatedAt: string): ApprovalLedger;
+export declare function serializeApprovalLedger(ledger: ApprovalLedger): string;
+export declare function parseApprovalLedger(content: string): ApprovalLedger;

package/dist/human-approval.js

@@ -0,0 +1,286 @@
+import { createHash } from "node:crypto";
+import { parseDocument, stringify } from "yaml";
+import { HUMAN_APPROVAL_STAGES } from "./types.js";
+export const APPROVAL_STAGES = HUMAN_APPROVAL_STAGES;
+const STAGE_DEFINITIONS = {
+    brainstorming: { optional: true, requiresQualityGate: true },
+    specification: { optional: false, requiresQualityGate: true },
+    "technical-design": { optional: true, requiresQualityGate: true },
+    plan: { optional: false, requiresQualityGate: true },
+    implementation: { optional: false, requiresQualityGate: true },
+    verification: { optional: false, requiresQualityGate: true },
+    review: { optional: false, requiresQualityGate: true },
+    traceability: { optional: false, requiresQualityGate: true },
+};
+const APPROVAL_STATUSES = ["draft", "pending-human", "approved", "rejected", "skipped", "stale"];
+const QUALITY_GATE_RESULTS = ["not-run", "passed", "failed", "not-applicable"];
+const APPROVAL_RECORD_KEYS = new Set([
+    "status",
+    "qualityGate",
+    "artifactHash",
+    "reason",
+    "updatedAt",
+]);
+const LEDGER_KEYS = new Set(["schema", "workflowId", "stages"]);
+const SESSION_KEYS = new Set(["schema", "workflowId", "status", "startedAt", "updatedAt"]);
+export function createApprovalLedger(workflowId) {
+    assertWorkflowId(workflowId);
+    return { schema: 1, workflowId, stages: {} };
+}
+export function serializeWorkflowSession(session) {
+    validateWorkflowSession(session);
+    return stringify(session, { lineWidth: 0 });
+}
+export function parseWorkflowSession(content) {
+    const document = parseDocument(content, { uniqueKeys: true, strict: true });
+    if (document.errors.length)
+        throw new Error("Workflow session contains invalid YAML.");
+    const value = document.toJS();
+    if (!isRecord(value) || value.schema !== 1)
+        throw new Error("Workflow session schema must be version 1.");
+    for (const key of Object.keys(value))
+        if (!SESSION_KEYS.has(key))
+            throw new Error(`Workflow session has unknown field: ${key}.`);
+    if (typeof value.workflowId !== "string")
+        throw new Error("Workflow session requires a workflowId.");
+    if (value.status !== "active" && value.status !== "complete")
+        throw new Error("Workflow session status must be active or complete.");
+    if (typeof value.startedAt !== "string" || typeof value.updatedAt !== "string")
+        throw new Error("Workflow session requires start and update timestamps.");
+    const session = {
+        schema: 1,
+        workflowId: value.workflowId,
+        status: value.status,
+        startedAt: value.startedAt,
+        updatedAt: value.updatedAt,
+    };
+    validateWorkflowSession(session);
+    return session;
+}
+export function stageDefinition(stage) {
+    return STAGE_DEFINITIONS[stage];
+}
+export function stageFingerprint(content) {
+    return `sha256-${createHash("sha256").update(content).digest("hex")}`;
+}
+export function getUnresolvedPrerequisites(ledger, stage) {
+    const stageIndex = APPROVAL_STAGES.indexOf(stage);
+    return APPROVAL_STAGES.slice(0, stageIndex).filter((prerequisite) => {
+        const status = ledger.stages[prerequisite]?.status;
+        return status !== "approved" && status !== "skipped";
+    });
+}
+export function beginStageApproval(ledger, stage, input) {
+    assertHash(input.artifactHash);
+    assertTimestamp(input.updatedAt);
+    assertPrerequisitesResolved(ledger, stage);
+    const definition = stageDefinition(stage);
+    if (definition.requiresQualityGate && input.qualityGate !== "passed")
+        throw new Error(`The ${stage} quality gate must pass before human review.`);
+    if (!definition.requiresQualityGate && input.qualityGate !== "not-applicable")
+        throw new Error(`The ${stage} stage has no automated quality gate; use not-applicable.`);
+    const existing = ledger.stages[stage];
+    if (existing?.status === "approved" && existing.artifactHash === input.artifactHash)
+        return ledger;
+    const reset = existing && (existing.artifactHash !== input.artifactHash || existing.status === "skipped")
+        ? invalidateStageAndDescendants(ledger, stage, input.updatedAt)
+        : ledger;
+    return withStage(reset, stage, {
+        status: "pending-human",
+        qualityGate: input.qualityGate,
+        artifactHash: input.artifactHash,
+        updatedAt: input.updatedAt,
+    });
+}
+export function approveStage(ledger, stage, input) {
+    assertHash(input.artifactHash);
+    assertTimestamp(input.updatedAt);
+    assertPrerequisitesResolved(ledger, stage);
+    const current = ledger.stages[stage];
+    if (!current || current.status !== "pending-human")
+        throw new Error(`The ${stage} stage is not pending human approval.`);
+    if (current.artifactHash !== input.artifactHash)
+        throw new Error(`The ${stage} artifact changed after review; request approval again.`);
+    return withStage(ledger, stage, { ...current, status: "approved", updatedAt: input.updatedAt });
+}
+export function rejectStage(ledger, stage, reason, updatedAt) {
+    assertTimestamp(updatedAt);
+    if (!ledger.stages[stage] || ledger.stages[stage].status !== "pending-human")
+        throw new Error(`The ${stage} stage is not pending human approval.`);
+    if (!reason.trim())
+        throw new Error("A reason is required when rejecting a stage.");
+    const invalidated = invalidateStageAndDescendants(ledger, stage, updatedAt);
+    return withStage(invalidated, stage, {
+        ...ledger.stages[stage],
+        status: "rejected",
+        reason: reason.trim(),
+        updatedAt,
+    });
+}
+export function skipOptionalStage(ledger, stage, input) {
+    assertTimestamp(input.updatedAt);
+    if (!stageDefinition(stage).optional)
+        throw new Error(`The ${stage} stage is required and cannot be skipped.`);
+    if (!input.humanAccepted)
+        throw new Error(`Explicit human acceptance is required to skip ${stage}.`);
+    if (!input.reason.trim())
+        throw new Error(`A reason is required to skip ${stage}.`);
+    assertPrerequisitesResolved(ledger, stage);
+    const invalidated = invalidateStageAndDescendants(ledger, stage, input.updatedAt);
+    return withStage(invalidated, stage, {
+        status: "skipped",
+        qualityGate: "not-applicable",
+        reason: input.reason.trim(),
+        updatedAt: input.updatedAt,
+    });
+}
+export function invalidateStageAndDescendants(ledger, stage, updatedAt) {
+    assertTimestamp(updatedAt);
+    const stageIndex = APPROVAL_STAGES.indexOf(stage);
+    const stages = { ...ledger.stages };
+    for (const affected of APPROVAL_STAGES.slice(stageIndex)) {
+        const record = stages[affected];
+        if (record && record.status !== "draft")
+            stages[affected] = { ...record, status: "stale", updatedAt };
+    }
+    return { schema: 1, workflowId: ledger.workflowId, stages };
+}
+export function serializeApprovalLedger(ledger) {
+    validateLedger(ledger);
+    const stages = Object.fromEntries(APPROVAL_STAGES.flatMap((stage) => ledger.stages[stage] ? [[stage, ledger.stages[stage]]] : []));
+    return stringify({ schema: 1, workflowId: ledger.workflowId, stages }, { lineWidth: 0 });
+}
+export function parseApprovalLedger(content) {
+    const document = parseDocument(content, { uniqueKeys: true, strict: true });
+    if (document.errors.length)
+        throw new Error("Approval ledger contains invalid YAML.");
+    const value = document.toJS();
+    if (!isRecord(value) || value.schema !== 1)
+        throw new Error("Approval ledger schema must be version 1.");
+    for (const key of Object.keys(value))
+        if (!LEDGER_KEYS.has(key))
+            throw new Error(`Approval ledger has unknown field: ${key}.`);
+    if (typeof value.workflowId !== "string")
+        throw new Error("Approval ledger requires a workflowId.");
+    assertWorkflowId(value.workflowId);
+    if (!isRecord(value.stages))
+        throw new Error("Approval ledger stages must be a mapping.");
+    const stages = {};
+    for (const [stageName, record] of Object.entries(value.stages)) {
+        if (!isApprovalStage(stageName))
+            throw new Error(`Approval ledger has unknown workflow stage: ${stageName}.`);
+        stages[stageName] = parseStageRecord(stageName, record);
+    }
+    const ledger = { schema: 1, workflowId: value.workflowId, stages };
+    validateLedger(ledger);
+    return ledger;
+}
+function assertPrerequisitesResolved(ledger, stage) {
+    const unresolved = getUnresolvedPrerequisites(ledger, stage);
+    if (unresolved.length)
+        throw new Error(`The ${stage} stage is blocked until these stages are approved or explicitly skipped: ${unresolved.join(", ")}.`);
+}
+function assertHash(value) {
+    if (!/^sha256-[a-f0-9]{64}$/.test(value))
+        throw new Error("Stage artifact fingerprint must be a SHA-256 hash.");
+}
+function assertTimestamp(value) {
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/.test(value) ||
+        !Number.isFinite(Date.parse(value)))
+        throw new Error("Approval timestamp must be a valid date-time.");
+}
+function assertWorkflowId(value) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(value))
+        throw new Error("Workflow ID must be 1–64 characters using letters, numbers, dot, underscore, or hyphen.");
+}
+function validateWorkflowSession(session) {
+    if (session.schema !== 1)
+        throw new Error("Workflow session schema must be version 1.");
+    assertWorkflowId(session.workflowId);
+    if (session.status !== "active" && session.status !== "complete")
+        throw new Error("Workflow session status must be active or complete.");
+    assertTimestamp(session.startedAt);
+    assertTimestamp(session.updatedAt);
+}
+function withStage(ledger, stage, record) {
+    return {
+        schema: 1,
+        workflowId: ledger.workflowId,
+        stages: { ...ledger.stages, [stage]: record },
+    };
+}
+function isApprovalStage(value) {
+    return APPROVAL_STAGES.includes(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseStageRecord(stage, value) {
+    if (!isRecord(value))
+        throw new Error(`Approval record for ${stage} must be a mapping.`);
+    for (const key of Object.keys(value))
+        if (!APPROVAL_RECORD_KEYS.has(key))
+            throw new Error(`Approval record for ${stage} has unknown field: ${key}.`);
+    const { status, qualityGate, artifactHash, reason, updatedAt } = value;
+    if (typeof status !== "string" || !APPROVAL_STATUSES.includes(status))
+        throw new Error(`Approval record for ${stage} has an invalid status.`);
+    if (typeof qualityGate !== "string" || !QUALITY_GATE_RESULTS.includes(qualityGate))
+        throw new Error(`Approval record for ${stage} has an invalid quality gate result.`);
+    if (typeof updatedAt !== "string")
+        throw new Error(`Approval record for ${stage} requires an updatedAt timestamp.`);
+    assertTimestamp(updatedAt);
+    if (artifactHash !== undefined) {
+        if (typeof artifactHash !== "string")
+            throw new Error(`Approval record for ${stage} has an invalid artifact fingerprint.`);
+        assertHash(artifactHash);
+    }
+    if (reason !== undefined && typeof reason !== "string")
+        throw new Error(`Approval record for ${stage} has an invalid reason.`);
+    const record = {
+        status: status,
+        qualityGate: qualityGate,
+        updatedAt,
+        ...(artifactHash === undefined ? {} : { artifactHash }),
+        ...(reason === undefined ? {} : { reason }),
+    };
+    if (record.status === "pending-human" && !record.artifactHash)
+        throw new Error(`Pending approval for ${stage} requires an artifact fingerprint.`);
+    if (record.status === "approved" && !record.artifactHash)
+        throw new Error(`Approved stage ${stage} requires an artifact fingerprint.`);
+    if ((record.status === "pending-human" || record.status === "approved") &&
+        stageDefinition(stage).requiresQualityGate &&
+        record.qualityGate !== "passed")
+        throw new Error(`Human-reviewed stage ${stage} must have a passing quality gate.`);
+    if (!stageDefinition(stage).requiresQualityGate && record.qualityGate !== "not-applicable")
+        throw new Error(`Stage ${stage} has no automated quality gate and must use not-applicable.`);
+    if (record.status === "skipped") {
+        if (!stageDefinition(stage).optional)
+            throw new Error(`Required stage ${stage} cannot be skipped.`);
+        if (!record.reason?.trim())
+            throw new Error(`Skipped stage ${stage} requires a reason.`);
+    }
+    if (record.status === "rejected" && !record.reason?.trim())
+        throw new Error(`Rejected stage ${stage} requires a reason.`);
+    return record;
+}
+function validateLedger(ledger) {
+    if (ledger.schema !== 1 || !isRecord(ledger.stages))
+        throw new Error("Approval ledger schema must be version 1 with a stages mapping.");
+    assertWorkflowId(ledger.workflowId);
+    for (const [stage, record] of Object.entries(ledger.stages)) {
+        if (!isApprovalStage(stage))
+            throw new Error(`Approval ledger has unknown workflow stage: ${stage}.`);
+        parseStageRecord(stage, record);
+    }
+    for (const stage of APPROVAL_STAGES) {
+        const status = ledger.stages[stage]?.status;
+        if (status === "pending-human" ||
+            status === "approved" ||
+            status === "rejected" ||
+            status === "skipped") {
+            const unresolved = getUnresolvedPrerequisites(ledger, stage);
+            if (unresolved.length)
+                throw new Error(`Approval ledger has out-of-order decision for ${stage}; unresolved stages: ${unresolved.join(", ")}.`);
+        }
+    }
+}