@multileaf/ai-workflow 0.1.5 → 0.2.1

package/docs/ai-init-workflow-spec.md

@@ -6,13 +6,13 @@ Make `/ai-init` a guided, evidence-backed onboarding flow. The initial `npx` ins
 
 ## User flow
 
-1. **Model and consent.** Before repository analysis, recommend switching to a lower-cost model. Do not change model settings. Ask whether the user switched or wants to continue with the current model. Explain that repository analysis is read-only until resource selection.
+1. **Model and consent.** Before repository analysis, recommend switching to a lower-cost model. Do not change model settings. Use the host's native blocking question widget, with no preselected value, to ask whether the user switched, wants to continue with the current model, or wants to stop. Do not scan or launch subagents until the widget has an explicit continue response. Silence, ambiguity, dismissal, or a default value is not consent.
 2. **Parallel project analysis.** Use the host's native subagent mechanism to start independent read-only scans in parallel. Assign separate work to (a) technologies and package/workspace topology, (b) architecture, modules, and code patterns, and (c) tests, quality tools, and CI. The initiating agent is the orchestrator: it consolidates findings, resolves conflicts using repository evidence, and records paths for every material conclusion. If the host cannot start subagents, do the same scans directly and say so.
 3. **Monorepo coverage.** Discover root and nested project manifests, workspace definitions, package boundaries, framework configs, tests, and module entry points. Analyze each workspace separately, then summarize shared tooling and cross-workspace relationships. Never infer that root dependencies apply to every workspace.
-4. **Scan record.** Run the deterministic AI Workflow scan and combine it with the parallel analysis. Present technologies, architecture, patterns, modules, tests, quality commands, workspace topology, confidence, and source evidence. Do not include secret values. Ask for confirmation where conflicting or uncertain findings would affect installed guidance.
+4. **Scan record.** Run the deterministic AI Workflow scan and combine it with the parallel analysis. Present technologies, architecture, patterns, modules, tests, quality commands, workspace topology, confidence, and source evidence. Do not include secret values. Use the native blocking question widget to confirm, correct, or leave unresolved any conflicting or uncertain finding that would affect installed guidance.
 5. **Recommendations.** Match catalog capabilities to the consolidated project profile. Show concise tables grouped by resource category (skills, rules, agents, hooks, templates, and MCPs), with one row per item and a short, project-specific reason plus supporting evidence. Include resource types, required permissions, and project-specific configuration steps where relevant. Recommend an MCP only when repository evidence supports its use; disclose its publisher/source, capabilities, access, transport, and credential needs. Never invent credentials or silently enable an MCP.
-6. **Selection.** After the recommendation tables, use the coding host's native selection widget when it supports one. First offer: install all recommendations, customize, or install none. For customization, show selectable blocks grouped by resource type, then the individual recommended items in each selected block; retain each item's concise reason and evidence in the selection details. Include MCPs as a separate block. Keep dependencies visible and select required dependencies together. If the host has no selection widget, use an equivalent numbered prompt and accept all/custom/none explicitly.
-7. **Install and personalize.** Install only the confirmed selection. For “all”, install every recommendation that does not require an unapproved external permission. A missing external permission must not block independent bundled resources; report the external item as pending and give the user the exact retry command. For custom selection, install only selected items and their declared dependencies. Personalize resources only when project evidence materially changes their instructions (for example, test commands, workspace/module layout, framework patterns, or architectural boundaries). Preserve existing files and secrets; report conflicts rather than overwriting. MCP setup must use the selected host's supported project-level configuration, preserve existing configuration, use environment-variable references for secrets, and request separate approval for permissions or external execution.
+6. **Selection.** After the recommendation tables, use the coding host's native selection widget when it supports one. First offer: install all recommendations, customize, or install none. No option may be preselected or inferred. Wait for an explicit submission; a dismissed widget, blank response, silence, or ambiguity must stop progress without selecting or installing anything. For customization, show selectable blocks grouped by resource type, then the individual recommended items in each selected block; retain each item's concise reason and evidence in the selection details. Include MCPs as a separate block. Keep dependencies visible and select required dependencies together. If the host has no selection widget, ask an equivalent numbered prompt, end the turn, and wait for an explicit all/custom/none reply.
+7. **Install and personalize.** After an explicit non-empty selection, show the exact resources and prerequisite capabilities that will be installed. Use the native blocking question widget with no default choice to approve the exact preview, request changes, or cancel. Do not sync while the widget is unanswered. For “all”, install every recommendation that does not require an unapproved external permission. A missing external permission must not block independent bundled resources; report the external item as pending and give the user the exact retry command. For custom selection, install only selected items and their declared dependencies. Personalize resources only when project evidence materially changes their instructions (for example, test commands, workspace/module layout, framework patterns, or architectural boundaries). Preserve existing files and secrets; report conflicts rather than overwriting. Use separate blocking question widgets to authorize MCP configuration, server execution, external access, and credentials; never combine these permissions.
 8. **Completion.** Report installed resources by block, project-specific changes, skipped recommendations, conflicts, MCP authentication/trust steps, and validation performed. Recommend restarting/reloading the coding-agent session so newly installed resources are discovered. Do not claim a restart is required when the host loads changes immediately; distinguish host behavior where known.
 
 ## Safety and compatibility
@@ -23,6 +23,7 @@ Make `/ai-init` a guided, evidence-backed onboarding flow. The initial `npx` ins
 - Selection and external permissions are separate decisions. Selecting an MCP is not permission to execute it or to expose credentials.
 - Resource writes use target adapters, ownership tracking, safe paths, atomic updates, and conflict reporting.
 - Host-specific capabilities (subagents, selection widgets, MCP configuration, restart semantics) are detected or described accurately; provide a safe manual fallback where unavailable.
+- Every human decision uses the host's native blocking question widget when available, with no default choice; a prose prompt is permitted only as a documented fallback when the host has no blocking widget.
 
 ## Acceptance criteria
 
@@ -38,7 +39,11 @@ Make `/ai-init` a guided, evidence-backed onboarding flow. The initial `npx` ins
 - **AIINIT-009:** Completion lists changes and recommends a session restart/reload to discover installed resources.
 - **AIINIT-010:** CLI tests cover mixed-stack monorepos, all/custom/none selection, permission gating, MCP config merging, personalization, conflicts, and completion output.
 - **AIINIT-011:** Custom selections can choose individual resource references by block, while `--select=all` selects every recommended capability and `--select=` selects none.
-- **AIINIT-013:** A selected remote resource without approved network access does not block independent bundled resource sync; sync reports the remote item as pending and preserves unrelated project files.
+- **AIINIT-013:** Sync previews exact additions, updates, preserved files, conflicts, and external permissions without writing; apply is bound to the approved plan fingerprint and is transactional. External skills and MCP actions require separate approvals, so network denial cannot partially apply local resources.
+- **AIINIT-014:** The bootstrap uses a blocking question widget for model choice, uncertain scan facts, recommendation selection, and final install confirmation; no scan or install proceeds from silence, ambiguity, cancellation, or a default/preselected choice.
+- **AIINIT-015:** Every applicable SDD stage has a mandatory human approval checkpoint before the next stage; the agent uses the native blocking question widget with explicit approve/request-changes/reject choices, and automated quality gates remain distinct from human approval.
+- **AIINIT-016:** A versioned per-workflow approval ledger binds each human decision to the exact evidence fingerprint, blocks out-of-order commands, invalidates downstream approvals when evidence changes, and explains the next action in workflow status.
+- **AIINIT-017:** Every human checkpoint uses the host's native blocking question widget when available, leaves choices unselected, and acts only after an explicit submission. If unavailable, the agent uses a numbered chat prompt and waits for a later explicit reply. The CLI must describe that it cannot independently prove which UI produced an approval.
 
 ## Delivery slices
 

package/docs/architecture.md

@@ -43,6 +43,14 @@ Target files such as `.cursor/rules`, `.claude/skills`, or Codex skill directori
 
 Project analysis is hybrid: deterministic detectors establish observable facts, while a scoped AI interpreter explains conventions and produces recommendations. AI output is never confirmed project state without user approval.
 
+## Human workflow approvals
+
+The SDD approval contract models the ordered stages brainstorming, specification, technical design, plan, implementation, verification, review, and traceability. Brainstorming and technical design are optional; skipping either requires a human-accepted reason. Every other stage must be approved. Automated quality-gate results are stored separately from human decisions and can only move an artifact to pending review, never directly to approved.
+
+Each approval is scoped to one workflow ID and bound to a SHA-256 fingerprint of the exact artifact reviewed, so a later feature cannot reuse earlier approvals. A content change or rejection makes that stage and its descendants stale. The CLI persists the versioned ledger in `.aiw/approvals.yml`, blocks stage commands when prerequisites are unresolved, and keeps passing quality gates distinct from human approval. The generated bootstrap and stage skills require the host's native blocking question widget for human decisions when available, with a waiting chat prompt as fallback. Approval records provide an audit trail but cannot prove the identity of a respondent or independently verify that the host widget was used.
+
+Every stage has a stable evidence path and an automated completeness gate. Design, implementation, review, and traceability use explicit report templates; a passing completeness check still leaves the stage pending until a human accepts the exact evidence.
+
 ## Modularity
 
 The CLI is an entry point, not the business layer. Filesystem, package providers, scanners, recommendation engines, generators, validators, and adapters must be replaceable through interfaces and dependency injection.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multileaf/ai-workflow",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "Portable spec-driven development workflow for AI coding agents",
   "license": "MIT",
   "repository": {

package/resources/package.yaml

@@ -69,6 +69,8 @@ resources:
     - { id: task, version: 0.1.0, path: templates/task.md }
     - { id: test-plan, version: 0.1.0, path: templates/test-plan.md }
     - { id: verification-report, version: 0.1.0, path: templates/verification-report.md }
+    - { id: implementation-evidence, version: 0.1.0, path: templates/implementation-evidence.md }
+    - { id: code-review, version: 0.1.0, path: templates/code-review.md }
     - { id: security-review, version: 0.1.0, path: templates/security-review.md }
     - { id: migration-report, version: 0.1.0, path: templates/migration-report.md }
 provides:

package/resources/skills/brainstorming.md

@@ -5,6 +5,8 @@ description: Turn an early product idea into structured goals, assumptions, cons
 
 # Brainstorming
 
+For every approval or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”; for a skip, offer “Accept skip” or “Do not skip”. Wait for an actual submission before running `aiw approve`, `aiw reject`, or `aiw skip` or proceeding. Collect revision/skip reasons in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Separate facts, hypotheses, decisions, and open questions. Identify users, desired outcomes, constraints, risks, and non-goals. Do not prematurely prescribe implementation. Produce a versioned brainstorm artifact in English.
 
-When the request is already clear, skip brainstorming. Once the goal and constraints are clear, hand off to `requirements-specification` and link the specification to this brainstorm when one exists.
+Start an AI Workflow session for each feature with `npx --yes --package=@multileaf/ai-workflow -- aiw workflow start` unless one is already active. When the request is already clear, explain why brainstorming can be skipped, ask the human to accept the skip, stop, and record only an explicit acceptance with `aiw skip brainstorming --reason=<accepted reason>`. Otherwise create `.aiw/generated/specs/brainstorm.md`, run `aiw gate brainstorming`, present the exact artifact and a concise summary, and ask whether to proceed to requirements. Stop the turn and wait. Only after an explicit approval, record it with `aiw approve brainstorming`; do not start or scaffold requirements before that command succeeds. If changes are requested, first record `aiw reject brainstorming --reason=<feedback>`, then revise the artifact, rerun its gate, and ask again. Use `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global CLI is available.

package/resources/skills/code-review.md

@@ -5,6 +5,8 @@ description: Review code for correctness, maintainability, design quality, and r
 
 # Code Review
 
+For every approval, rejection, or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”; for a skip, offer “Accept skip” or “Do not skip”. Wait for an actual submission before running `aiw approve`, `aiw reject`, or `aiw skip` or proceeding. Collect revision/skip reasons in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Review behavior, boundaries, cohesion, naming, types, error handling, duplication, complexity, tests, and documentation. Prioritize actionable findings with severity and evidence.
 
-If findings require changes, send them back to implementation and require verification again. If there are no blocking findings, record the review result and complete traceability. This skill is a review checklist, not a CLI quality gate.
+Write `.aiw/generated/reports/code-review.md` with the scope, findings (including an explicit `None` when clear), checks, residual risks, and decision. Run `aiw gate review`, present the exact report, and ask whether to address findings or accept the residual risk. Stop and wait for an explicit decision. Only after approval, record it with `aiw approve review`; do not start traceability before it succeeds. If changes are requested, first record `aiw reject review --reason=<feedback>`, return to implementation, and require verification and review again. Review completeness is an automated gate; it does not replace human approval. Invoke commands through `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global binary exists.

package/resources/skills/implementation-planning.md

@@ -5,6 +5,8 @@ description: Break an approved design into independently verifiable implementati
 
 # Implementation Planning
 
+For every approval, rejection, or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”; for a skip, offer “Accept skip” or “Do not skip”. Wait for an actual submission before running `aiw approve`, `aiw reject`, or `aiw skip` or proceeding. Collect revision/skip reasons in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Create small ordered tasks. Each task must reference requirements, affected modules, tests, commands, dependencies, and completion evidence.
 
-After the plan passes its gate, implement in task order. Use `tdd-development` when it is installed and the project has a test workflow; otherwise use the repository's existing validation methods. Hand completed work to `verification`.
+Write `.aiw/generated/plans/implementation-plan.md` with ordered tasks, requirement links, affected modules, tests, validation, dependencies, risks, and completion evidence. After `aiw gate plan` passes, present the exact plan to the human and ask for explicit approval. Stop and wait; a gate pass is not approval. Do not edit implementation files until approval arrives and `aiw approve plan` succeeds. If changes are requested, first record `aiw reject plan --reason=<feedback>`, then revise the plan, rerun its gate, and ask again. After approval, implement in task order. Use `tdd-development` when installed and the project has a test workflow; otherwise use existing validation. When implementation is complete, write `.aiw/generated/reports/implementation-report.md` with changed files, tests, validation results, and deviations; run `aiw gate implementation`, present the diff and evidence to the human, stop, and wait for explicit approval. Record approval with `aiw approve implementation` before verification. Invoke CLI commands through `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global binary exists.

package/resources/skills/project-init.md

@@ -5,4 +5,6 @@ description: Inspect a repository, build a project profile, and prepare AI Workf
 
 # Project Initialization
 
+Use the host's native blocking question widget for uncertain project facts and setup decisions when available. Leave choices unselected; offer to confirm the evidence, correct it, or leave it unresolved. Do not make an uncertain inference project policy until the widget is explicitly submitted. If the host has no blocking widget, ask one numbered question in chat and wait for an explicit response before proceeding.
+
 Inspect structure and configuration safely. Detect languages, frameworks, package managers, scripts, tests, quality tools, CI, and conventions. Record evidence and confidence in `.aiw/profile.yml`. Ask for confirmation before treating uncertain inferences as facts. Recommend capabilities with rationale, permissions, and conflicts.

package/resources/skills/requirements-specification.md

@@ -5,6 +5,8 @@ description: Convert a product idea into testable, traceable requirements.
 
 # Requirements Specification
 
+For every approval, rejection, or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”; for a skip, offer “Accept skip” or “Do not skip”. Wait for an actual submission before running `aiw approve`, `aiw reject`, or `aiw skip` or proceeding. Collect revision/skip reasons in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Give each requirement a stable identifier. Define observable behavior, acceptance criteria, constraints, and unresolved questions. Link requirements to their source brainstorm and distinguish confirmed facts from assumptions. Do not approve ambiguous critical requirements.
 
-After requirements are confirmed, use `technical-design` when the change affects architecture or has consequential design choices; otherwise hand off to `implementation-planning`.
+Create `.aiw/generated/specs/specification.md` and run `aiw gate specification`. Present the exact requirements and unresolved questions to the human and ask for explicit approval. Stop the turn and wait; a passing gate is not approval. Only after approval, run `aiw approve specification`; do not create design or plan artifacts before it succeeds. If changes are requested, first record `aiw reject specification --reason=<feedback>`, then revise the specification, rerun its gate, and ask again. After approval, use `technical-design` when the change affects architecture or has consequential design choices. Otherwise explain why design can be skipped, ask the human to accept, stop, and record an explicit acceptance with `aiw skip technical-design --reason=<accepted reason>` before planning. Invoke commands through `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` if `aiw` is not installed globally.

package/resources/skills/tdd-development.md

@@ -5,6 +5,8 @@ description: Implement repository changes through test-first development.
 
 # TDD Development
 
+For implementation approval or rejection, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”. Wait for an actual submission before running `aiw approve` or `aiw reject` or starting verification. Collect requested changes in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Follow Red, Green, Refactor, Verify. Write a failing behavioral test first, implement the smallest change, refactor for clarity and design quality, then run the relevant quality gate. Never weaken a test to make an implementation pass.
 
-After implementation tasks are green and refactored, hand off to `verification` with the changed requirements, test commands, and evidence.
+After implementation tasks are green and refactored, write `.aiw/generated/reports/implementation-report.md` with changed files, tests, validation results, and deviations. Run `aiw gate implementation`, present the diff, changed requirements, test commands, and exact evidence to the human. Ask for explicit approval to proceed to verification, end the turn, and wait. Do not invoke verification until the human approves and `aiw approve implementation` succeeds. If changes are requested, first record `aiw reject implementation --reason=<feedback>`, remain in implementation, repeat relevant tests, update the report, rerun its gate, and ask again. Invoke CLI commands through `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global binary exists.

package/resources/skills/technical-design.md

@@ -5,6 +5,8 @@ description: Design modular technical solutions from approved requirements.
 
 # Technical Design
 
+For every approval, rejection, or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”; for a skip, offer “Accept skip” or “Do not skip”. Wait for an actual submission before running `aiw approve`, `aiw reject`, or `aiw skip` or proceeding. Collect revision/skip reasons in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Map requirements to components, interfaces, data flows, and validation strategy. Compare meaningful alternatives and record decisions with rationale, risks, and consequences. Prefer small cohesive modules, explicit contracts, dependency inversion, and reversible changes.
 
-Link each design and ADR to the affected requirements. Once decisions are recorded, hand off to `implementation-planning`.
+Write the reviewable design to `.aiw/generated/reports/technical-design.md` using the technical-design template. Link each design and ADR to affected requirements. Run `aiw gate technical-design`, present the exact design and decisions to the human, and ask for explicit approval. Stop and wait; do not create an implementation plan until approval arrives. Only after approval, record it with `aiw approve technical-design`. If changes are requested, first record `aiw reject technical-design --reason=<feedback>`, then revise the design/ADRs, rerun the gate, and ask again. If no technical design is needed, obtain explicit human acceptance and record `aiw skip technical-design --reason=<accepted reason>`. Use `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global CLI is available.

package/resources/skills/verification.md

@@ -5,6 +5,8 @@ description: Verify implementation against requirements and produce traceable ev
 
 # Verification
 
+For every approval or rejection, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer “Approve and continue”, “Request changes”, and “Reject/stop”. Wait for an actual submission before running `aiw approve` or `aiw reject` or proceeding to the next stage. Collect requested changes in a follow-up free-text widget. If the host has no blocking widget, use a numbered chat prompt and end the turn until an explicit reply arrives. The CLI records the decision but cannot verify that a widget was used.
+
 Check every acceptance criterion, quality gate, security requirement, and affected adapter. Report passed checks, missing evidence, failures, and residual risks. A task is not complete when required evidence is missing.
 
-Create the verification report and validate it with `npx --yes --package=@multileaf/ai-workflow -- aiw gate verification`. Then hand off to `code-review` when installed; after review, update traceability and completion evidence.
+Write `.aiw/generated/reports/verification-report.md` using the verification-report template and validate it with `npx --yes --package=@multileaf/ai-workflow -- aiw gate verification`. Present the exact report, checks, missing evidence, and residual risks to the human. Ask for explicit approval to proceed, end the turn, and wait; an automated gate pass is not human acceptance. Only after approval, record it with `aiw approve verification`. Do not start code review or final traceability before that command succeeds. If verification fails or changes are requested, record `aiw reject verification --reason=<feedback>` before editing the report or returning to implementation, then repeat verification, update the report, rerun the gate, and ask again. Use npx package invocation for other `aiw` commands when no global binary exists.

package/resources/templates/code-review.md

@@ -0,0 +1,21 @@
+# Code Review
+
+## Scope
+
+Describe the diff and requirements reviewed.
+
+## Findings
+
+List findings with severity, file/line evidence, and actionable remediation. State `None` when there are no findings.
+
+## Checks
+
+List checks performed and their results.
+
+## Residual Risks
+
+State remaining risks or `None`.
+
+## Decision
+
+Recommend accept, revise, or reject, with rationale.

package/resources/templates/implementation-evidence.md

@@ -0,0 +1,17 @@
+# Implementation Evidence
+
+## Changed Files
+
+- `path/to/file` — reason for the change.
+
+## Tests
+
+- Command and result; list relevant tests.
+
+## Validation
+
+- Command and result for required project checks.
+
+## Deviations
+
+None, or explain approved plan deviations and their impact.