@multileaf/ai-workflow 0.1.4 → 0.2.0

package/dist/workflow.js

@@ -1,4 +1,5 @@
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { randomUUID } from "node:crypto";
 import { BASE_DIRECTORIES, WORKFLOW_DIRECTORY } from "./constants.js";
 import { detectTarget, isTarget, renderAiInit, renderAiInitPath, renderResourcePath, } from "./adapter.js";
 import { loadBundledResources } from "./bundled-resources.js";
@@ -31,6 +32,7 @@ import { composeContext, CONTEXT_LAYERS, readContextStore, writeContextLayer, }
 import { loadContextDelta, retrieveTaskContext } from "./context-retrieval.js";
 import { createSummaryCache, isSummaryFresh, parseSummaryCache, serializeSummaryCache, } from "./context-cache.js";
 import { parseTokenUsage, recordTokenUsage, serializeTokenUsage } from "./token-usage.js";
+import { APPROVAL_STAGES, approveStage, beginStageApproval, createApprovalLedger, getUnresolvedPrerequisites, invalidateStageAndDescendants, parseApprovalLedger, parseWorkflowSession, rejectStage, serializeApprovalLedger, serializeWorkflowSession, skipOptionalStage, stageDefinition, stageFingerprint, } from "./human-approval.js";
 import { measureContextQuality, serializeContextQuality } from "./context-quality.js";
 import { serializeAdapterCapabilities } from "./adapter-contract.js";
 import { buildTraceabilityGraph, serializeTraceabilityGraph } from "./traceability.js";
@@ -46,6 +48,139 @@ export async function runCommand(args, root, fs, services = {}) {
     try {
         fs = withSafeProjectWrites(fs, root);
         const command = args[0] ?? "help";
+        if (command === "workflow") {
+            if (!fs.exists(join(aiw, "manifest.yml")))
+                return { exitCode: 1, error: "Run `aiw install` first." };
+            const action = args[1];
+            const sessionPath = join(aiw, "workflow.yml");
+            const ledgerPath = join(aiw, "approvals.yml");
+            if (action === "start") {
+                const options = parseNamedOptions(args.slice(2), ["id"]);
+                if (!options)
+                    return { exitCode: 1, error: "Usage: aiw workflow start [--id=workflow-id]" };
+                if (fs.exists(sessionPath)) {
+                    const previous = parseWorkflowSession(fs.read(sessionPath));
+                    if (previous.status === "active")
+                        return {
+                            exitCode: 1,
+                            error: `Workflow ${previous.workflowId} is still active. Complete it before starting another.`,
+                        };
+                    if (!fs.exists(ledgerPath))
+                        return { exitCode: 1, error: "Completed workflow is missing its approval ledger." };
+                    const archive = join(aiw, `checkpoints/workflow-${previous.workflowId}-approvals.yml`);
+                    if (fs.exists(archive))
+                        return { exitCode: 1, error: `Workflow approval archive already exists: ${archive}` };
+                    fs.mkdir(join(aiw, "checkpoints"));
+                    fs.write(archive, fs.read(ledgerPath));
+                }
+                else if (fs.exists(ledgerPath)) {
+                    return {
+                        exitCode: 1,
+                        error: "Approval ledger exists without a workflow session; run doctor.",
+                    };
+                }
+                const workflowId = options.id ?? randomUUID();
+                const priorRun = join(aiw, `checkpoints/workflow-${workflowId}-approvals.yml`);
+                if (fs.exists(priorRun))
+                    return {
+                        exitCode: 1,
+                        error: `Workflow ID has already been used: ${workflowId}. Choose a new ID.`,
+                    };
+                const now = new Date().toISOString();
+                const session = {
+                    schema: 1,
+                    workflowId,
+                    status: "active",
+                    startedAt: now,
+                    updatedAt: now,
+                };
+                const ledger = createApprovalLedger(workflowId);
+                fs.write(ledgerPath, serializeApprovalLedger(ledger));
+                fs.write(sessionPath, serializeWorkflowSession(session));
+                return { exitCode: 0, output: `Workflow started: ${workflowId}.` };
+            }
+            if (action === "status") {
+                if (!fs.exists(sessionPath))
+                    return { exitCode: 0, output: "No SDD workflow is active." };
+                const { session, ledger } = readWorkflowState(aiw, fs, false);
+                const stages = APPROVAL_STAGES.map((stage) => `- ${stage}: ${ledger.stages[stage]?.status ?? "not-started"}`);
+                return {
+                    exitCode: 0,
+                    output: `Workflow ${session.workflowId} (${session.status})\n${stages.join("\n")}\n${workflowNextAction(ledger)}`,
+                };
+            }
+            if (action === "complete") {
+                const { session, ledger } = readActiveWorkflow(aiw, fs);
+                const unresolved = APPROVAL_STAGES.filter((stage) => ledger.stages[stage]?.status !== "approved" &&
+                    ledger.stages[stage]?.status !== "skipped");
+                if (unresolved.length)
+                    return {
+                        exitCode: 1,
+                        error: `Workflow cannot complete before every stage is approved or explicitly skipped: ${unresolved.join(", ")}.`,
+                    };
+                fs.write(sessionPath, serializeWorkflowSession({
+                    ...session,
+                    status: "complete",
+                    updatedAt: new Date().toISOString(),
+                }));
+                return { exitCode: 0, output: `Workflow completed: ${session.workflowId}.` };
+            }
+            return {
+                exitCode: 1,
+                error: "Usage: aiw workflow <start|status|complete> [options]",
+            };
+        }
+        if (command === "approve" || command === "reject" || command === "skip") {
+            const stage = args[1];
+            if (!stage || !APPROVAL_STAGES.includes(stage))
+                return { exitCode: 1, error: `Usage: aiw ${command} <workflow-stage> [options]` };
+            const { ledger } = readActiveWorkflow(aiw, fs);
+            const workflowStage = stage;
+            if (command === "skip") {
+                const options = parseNamedOptions(args.slice(2), ["reason"]);
+                if (!options?.reason)
+                    return {
+                        exitCode: 1,
+                        error: "Usage: aiw skip <optional-stage> --reason=human-approved-reason",
+                    };
+                const updated = skipOptionalStage(ledger, workflowStage, {
+                    reason: options.reason,
+                    humanAccepted: true,
+                    updatedAt: new Date().toISOString(),
+                });
+                fs.write(join(aiw, "approvals.yml"), serializeApprovalLedger(updated));
+                return { exitCode: 0, output: `Human-approved skip recorded for ${workflowStage}.` };
+            }
+            const artifact = approvalArtifactPath(aiw, workflowStage);
+            if (!artifact || !fs.exists(artifact))
+                return { exitCode: 1, error: `Approval evidence is missing for ${workflowStage}.` };
+            const artifactHash = stageFingerprint(fs.read(artifact));
+            if (command === "approve") {
+                if (ledger.stages[workflowStage]?.artifactHash !== artifactHash) {
+                    const invalidated = invalidateStageAndDescendants(ledger, workflowStage, new Date().toISOString());
+                    fs.write(join(aiw, "approvals.yml"), serializeApprovalLedger(invalidated));
+                    return {
+                        exitCode: 1,
+                        error: `The ${workflowStage} artifact changed after review; its approval is stale. Rerun the quality gate and request approval again.`,
+                    };
+                }
+                const updated = approveStage(ledger, workflowStage, {
+                    artifactHash,
+                    updatedAt: new Date().toISOString(),
+                });
+                fs.write(join(aiw, "approvals.yml"), serializeApprovalLedger(updated));
+                return { exitCode: 0, output: `Human approval recorded for ${workflowStage}.` };
+            }
+            const options = parseNamedOptions(args.slice(2), ["reason"]);
+            if (!options?.reason)
+                return { exitCode: 1, error: "Usage: aiw reject <stage> --reason=human-feedback" };
+            const updated = rejectStage(ledger, workflowStage, options.reason, new Date().toISOString());
+            fs.write(join(aiw, "approvals.yml"), serializeApprovalLedger(updated));
+            return {
+                exitCode: 0,
+                output: `Human rejection recorded for ${workflowStage}. Revise this stage.`,
+            };
+        }
         if (command === "ui") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
@@ -749,6 +884,52 @@ export async function runCommand(args, root, fs, services = {}) {
                 : await profileProject(root);
             const selectedArg = args.find((arg) => arg.startsWith("--select="))?.split("=", 2)[1];
             const selected = selectedArg?.split(",") ?? (command === "sync" ? readSelectedRecommendations(fs, aiw) : []);
+            if (command === "sync") {
+                const previewOnly = args.includes("--preview");
+                const planApprovals = args.filter((arg) => arg.startsWith("--approve-plan="));
+                if (planApprovals.length > 1 || (previewOnly && planApprovals.length > 0))
+                    return {
+                        exitCode: 1,
+                        error: "Usage: aiw sync [--preview | --approve-plan=sha256-fingerprint]",
+                    };
+                const approval = planApprovals[0]?.slice("--approve-plan=".length);
+                const result = syncSelectedResources(fs, root, aiw, profile, selected, !previewOnly, approval);
+                if (result.error)
+                    return { exitCode: 1, error: result.error };
+                if (previewOnly)
+                    return { exitCode: 0, output: result.preview };
+                if (!approval)
+                    return {
+                        exitCode: 1,
+                        error: `Sync is read-only until the exact preview is approved. Review the plan, then rerun with --approve-plan=${result.fingerprint}.`,
+                    };
+                if (approval !== result.fingerprint)
+                    return {
+                        exitCode: 1,
+                        error: `The sync plan changed after review. Run aiw sync --preview again and approve the new fingerprint (${result.fingerprint}).`,
+                    };
+                if (result.conflicts?.length)
+                    return {
+                        exitCode: 1,
+                        error: `Sync plan has conflicts and made no changes: ${result.conflicts.join(", ")}`,
+                    };
+                const messages = [result.output ?? "Selected bundled resources synchronized."];
+                if (selected.includes("react-best-practices")) {
+                    let pendingReason = "network:external was not approved";
+                    try {
+                        enforceConfiguredOrganizationPolicy(fs, aiw, {
+                            provider: "vercel-skills",
+                            source: "vercel-labs/agent-skills",
+                            permissions: ["network:external"],
+                        });
+                    }
+                    catch (error) {
+                        pendingReason = error instanceof Error ? error.message : String(error);
+                    }
+                    messages.push(`Remote skill pending: ${pendingReason}. Install it separately with aiw skills install.`);
+                }
+                return { exitCode: 0, output: messages.join(" ") };
+            }
             if (selected.includes("react-best-practices")) {
                 const approvedPermissions = parseApprovedPermissions(args);
                 if (!approvedPermissions.includes("network:external"))
@@ -765,12 +946,6 @@ export async function runCommand(args, root, fs, services = {}) {
                 await installVercelSkill(services.externalSkills ?? nodeCommandExecutor, "vercel-labs/agent-skills", "vercel-react-best-practices", target);
                 writeVercelSkillLock(fs, root, aiw, "vercel-labs/agent-skills", "vercel-react-best-practices");
             }
-            if (command === "sync") {
-                const result = syncSelectedResources(fs, root, aiw, profile, selected);
-                return result.error
-                    ? { exitCode: 1, error: result.error }
-                    : { exitCode: 0, output: result.output };
-            }
             const conflicts = [];
             generateProjectResources(profile, selected, (path, content) => {
                 const destination = join(aiw, path);
@@ -794,7 +969,14 @@ export async function runCommand(args, root, fs, services = {}) {
             try {
                 const manifest = fs.read(join(aiw, "manifest.yml"));
                 parseManifest(manifest);
-                return { exitCode: 0, output: manifest };
+                const workflowPath = join(aiw, "workflow.yml");
+                if (!fs.exists(workflowPath))
+                    return { exitCode: 0, output: manifest };
+                const { session, ledger } = readWorkflowState(aiw, fs, false);
+                return {
+                    exitCode: 0,
+                    output: `${manifest}\nSDD workflow ${session.workflowId} (${session.status})\n${workflowNextAction(ledger)}`,
+                };
             }
             catch (error) {
                 return { exitCode: 1, error: error instanceof Error ? error.message : String(error) };
@@ -922,6 +1104,7 @@ export async function runCommand(args, root, fs, services = {}) {
         if (command === "brainstorm") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
+            assertStageReady(aiw, fs, "brainstorming");
             const title = args.find((arg) => arg.startsWith("--title="))?.slice(8) || "Untitled Brainstorm";
             const path = join(aiw, "generated/specs/brainstorm.md");
             fs.write(path, `# ${title}\n\n## Goal\n\n## Users\n\n## Facts\n\n## Assumptions\n\n## Hypotheses\n\n## Constraints\n\n## Risks\n\n## Non-goals\n\n## Open Questions\n\n`);
@@ -930,6 +1113,7 @@ export async function runCommand(args, root, fs, services = {}) {
         if (command === "spec") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
+            assertStageReady(aiw, fs, "specification");
             const title = args.find((arg) => arg.startsWith("--title="))?.slice(8) || "Untitled Specification";
             const path = join(aiw, "generated/specs/specification.md");
             fs.write(path, `# ${title}\n\n## Context\n\n## Requirements\n\n### REQ-001: Requirement title\n\n- **Description:**\n- **Acceptance criteria:**\n  - Given\n  - When\n  - Then\n\n## Non-functional Requirements\n\n## Constraints\n\n## Open Questions\n\n`);
@@ -938,6 +1122,7 @@ export async function runCommand(args, root, fs, services = {}) {
         if (command === "adr") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
+            assertStageReady(aiw, fs, "technical-design");
             const id = args.find((arg) => arg.startsWith("--id="))?.slice(5) || "001";
             const title = args.find((arg) => arg.startsWith("--title="))?.slice(8) || "Untitled Decision";
             const path = join(root, ".context/adrs", `ADR-${id}-${title.toLowerCase().replaceAll(" ", "-")}.md`);
@@ -947,6 +1132,7 @@ export async function runCommand(args, root, fs, services = {}) {
         if (command === "plan") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
+            assertStageReady(aiw, fs, "plan");
             const title = args.find((arg) => arg.startsWith("--title="))?.slice(8) || "Untitled Implementation Plan";
             const path = join(aiw, "generated/plans/implementation-plan.md");
             fs.write(path, `# ${title}\n\n## Linked Requirements\n\n- REQ-001: Link to the specification requirement.\n\n## Tasks\n\n- [ ] TASK-001: Implement the first increment.\n  - Requirement: REQ-001\n  - Code: src/\n  - Tests: src/**/*.test.ts\n  - Validation: npm test\n  - Evidence: Record the passing command output and changed files.\n\n## Validation Commands\n\n- npm run check\n\n## Risks and Dependencies\n\n- Dependencies: List prerequisite tasks, packages, or decisions.\n- Risks: Record delivery, compatibility, and validation risks with mitigations.\n\n## Completion Evidence\n\n- TASK-001: Link code changes, test results, and validation output.\n\n`);
@@ -955,6 +1141,7 @@ export async function runCommand(args, root, fs, services = {}) {
         if (command === "verify") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
+            assertStageReady(aiw, fs, "verification");
             const specPath = join(aiw, "generated/specs/specification.md");
             const planPath = join(aiw, "generated/plans/implementation-plan.md");
             const issues = [];
@@ -987,6 +1174,7 @@ export async function runCommand(args, root, fs, services = {}) {
         if (command === "trace") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
+            assertStageReady(aiw, fs, "traceability");
             const specPath = join(aiw, "generated/specs/specification.md");
             const planPath = join(aiw, "generated/plans/implementation-plan.md");
             if (!fs.exists(specPath) || !fs.exists(planPath))
@@ -1018,21 +1206,36 @@ export async function runCommand(args, root, fs, services = {}) {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
             const stage = args[1];
-            const requirements = {
-                specification: "generated/specs/brainstorm.md",
-                plan: "generated/specs/specification.md",
-                verification: "generated/plans/implementation-plan.md",
+            if (!stage || !APPROVAL_STAGES.includes(stage))
+                return {
+                    exitCode: 1,
+                    error: `Usage: aiw gate <${APPROVAL_STAGES.join("|")}>`,
+                };
+            const workflowStage = stage;
+            assertStageReady(aiw, fs, workflowStage);
+            const artifactPath = approvalArtifactPath(aiw, workflowStage);
+            if (!artifactPath || !fs.exists(artifactPath))
+                return {
+                    exitCode: 1,
+                    error: `Quality gate blocked: required evidence is missing for ${stage}.`,
+                };
+            const hasQualityGate = stageDefinition(workflowStage).requiresQualityGate;
+            if (hasQualityGate) {
+                const issues = evaluateQualityGate(stage, fs.read(artifactPath));
+                if (issues.length)
+                    return { exitCode: 1, error: `Quality gate blocked: ${issues.join(" ")}` };
+            }
+            const { ledger } = readActiveWorkflow(aiw, fs);
+            const updated = beginStageApproval(ledger, workflowStage, {
+                artifactHash: stageFingerprint(fs.read(artifactPath)),
+                qualityGate: hasQualityGate ? "passed" : "not-applicable",
+                updatedAt: new Date().toISOString(),
+            });
+            fs.write(join(aiw, "approvals.yml"), serializeApprovalLedger(updated));
+            return {
+                exitCode: 0,
+                output: `${hasQualityGate ? `Quality gate passed for ${stage}.` : `Evidence recorded for ${stage}; no automated quality gate applies.`} Human approval is still required: run aiw approve ${stage}.`,
             };
-            if (!stage || !(stage in requirements))
-                return { exitCode: 1, error: "Usage: aiw gate <specification|plan|verification>" };
-            const gateStage = stage;
-            const artifact = requirements[gateStage];
-            if (!fs.exists(join(aiw, artifact)))
-                return { exitCode: 1, error: `Quality gate blocked: missing ${artifact}` };
-            const issues = evaluateQualityGate(gateStage, fs.read(join(aiw, artifact)));
-            return issues.length
-                ? { exitCode: 1, error: `Quality gate blocked: ${issues.join(" ")}` }
-                : { exitCode: 0, output: `Quality gate passed for ${stage}.` };
         }
         if (command === "validate") {
             if (!fs.exists(join(aiw, "manifest.yml")))
@@ -1383,13 +1586,81 @@ export async function runCommand(args, root, fs, services = {}) {
         }
         return {
             exitCode: 0,
-            output: "aiw install [--target target] | ui [--port=number] | orchestrate --plan=path [--execute] [--max-parallel=number] | telemetry <status|enable|disable> [privacy options] | plugin <create|validate> [options] | scan | self-validate --ticket=TYPE-000 | organization-policy --file=path [--replace] | policy-check --package=path [--package=path] | preset --file=path [--replace] | context | context-summary | context-quality | capabilities [--target=target] | token-usage [--stage=name --budget=number --used=number] | registry [--search=query] [--private=name] | registry configure --file=path [--replace] | skills <search|inspect|install|check|update> [options] | audit-package --package=path | verify-package --package=path --checksum=sha256 | brainstorm [--title=title] | spec [--title=title] | adr [--id=id --title=title] | plan [--title=title] | verify | trace | gate <stage> | recommend [--select=id,id] | status | doctor | repair | uninstall [--dry-run] | target <target> | rollback | confirm | resolve --package=path | update --package=path --target=target | validate [--package=path]",
+            output: "aiw install [--target target] | workflow <start|status|complete> [--id=id] | approve <stage> | reject <stage> --reason=text | skip <optional-stage> --reason=text | ui [--port=number] | orchestrate --plan=path [--execute] [--max-parallel=number] | telemetry <status|enable|disable> [privacy options] | plugin <create|validate> [options] | scan | self-validate --ticket=TYPE-000 | organization-policy --file=path [--replace] | policy-check --package=path [--package=path] | preset --file=path [--replace] | context | context-summary | context-quality | capabilities [--target=target] | token-usage [--stage=name --budget=number --used=number] | registry [--search=query] [--private=name] | registry configure --file=path [--replace] | skills <search|inspect|install|check|update> [options] | audit-package --package=path | verify-package --package=path --checksum=sha256 | brainstorm [--title=title] | spec [--title=title] | adr [--id=id --title=title] | plan [--title=title] | verify | trace | gate <stage> | recommend [--select=id,id] | status | doctor | repair | uninstall [--dry-run] | target <target> | rollback | confirm | resolve --package=path | update --package=path --target=target | validate [--package=path]",
         };
     }
     catch (error) {
         return { exitCode: 1, error: error instanceof Error ? error.message : String(error) };
     }
 }
+function readWorkflowState(aiw, fs, requireActive = true) {
+    const sessionPath = join(aiw, "workflow.yml");
+    const ledgerPath = join(aiw, "approvals.yml");
+    if (!fs.exists(sessionPath) || !fs.exists(ledgerPath))
+        throw new Error("No SDD workflow is active. Start one with `aiw workflow start`.");
+    const session = parseWorkflowSession(fs.read(sessionPath));
+    let ledger = parseApprovalLedger(fs.read(ledgerPath));
+    if (session.workflowId !== ledger.workflowId)
+        throw new Error("Workflow session and approval ledger IDs do not match; run doctor.");
+    if (requireActive && session.status !== "active")
+        throw new Error(`Workflow ${session.workflowId} is complete; start a new workflow first.`);
+    const changed = APPROVAL_STAGES.find((stage) => {
+        const record = ledger.stages[stage];
+        if (!record?.artifactHash || !["pending-human", "approved"].includes(record.status))
+            return false;
+        const artifact = approvalArtifactPath(aiw, stage);
+        return (!artifact ||
+            !fs.exists(artifact) ||
+            stageFingerprint(fs.read(artifact)) !== record.artifactHash);
+    });
+    if (changed) {
+        ledger = invalidateStageAndDescendants(ledger, changed, new Date().toISOString());
+        fs.write(ledgerPath, serializeApprovalLedger(ledger));
+    }
+    return { session, ledger };
+}
+function readActiveWorkflow(aiw, fs) {
+    return readWorkflowState(aiw, fs, true);
+}
+function workflowNextAction(ledger) {
+    const next = APPROVAL_STAGES.find((stage) => ledger.stages[stage]?.status !== "approved" && ledger.stages[stage]?.status !== "skipped");
+    if (!next)
+        return "Next action: all stages are resolved; run aiw workflow complete.";
+    if (ledger.stages[next]?.status === "pending-human")
+        return `Next action: present ${next} evidence and wait for the human; then run aiw approve ${next} (or reject it).`;
+    if (ledger.stages[next]?.status === "stale" || ledger.stages[next]?.status === "rejected")
+        return `Next action: revise ${next}, rerun its gate, and request human approval.`;
+    return `Next action: prepare ${next} evidence.`;
+}
+function assertStageReady(aiw, fs, stage) {
+    const { ledger } = readActiveWorkflow(aiw, fs);
+    const unresolved = getUnresolvedPrerequisites(ledger, stage);
+    if (unresolved.length) {
+        const pending = unresolved.filter((prerequisite) => ledger.stages[prerequisite]?.status === "pending-human");
+        if (pending.length)
+            throw new Error(`Cannot enter ${stage}; previous stage(s) are awaiting human approval: ${pending.join(", ")}.`);
+        throw new Error(`Cannot enter ${stage}; previous stages require human approval or an accepted optional skip: ${unresolved.join(", ")}.`);
+    }
+    const current = ledger.stages[stage];
+    if (current?.status === "pending-human")
+        throw new Error(`${stage} is awaiting human approval. Approve or reject it before continuing.`);
+    if (current?.status === "approved")
+        throw new Error(`${stage} is already approved. Evidence changes require rerunning its gate.`);
+}
+function approvalArtifactPath(aiw, stage) {
+    if (stage === "technical-design")
+        return join(aiw, "generated/reports/technical-design.md");
+    const paths = {
+        brainstorming: "generated/specs/brainstorm.md",
+        specification: "generated/specs/specification.md",
+        plan: "generated/plans/implementation-plan.md",
+        implementation: "generated/reports/implementation-report.md",
+        verification: "generated/reports/verification-report.md",
+        review: "generated/reports/code-review.md",
+        traceability: "generated/artifacts/traceability.yml",
+    };
+    return resolve(aiw, paths[stage]);
+}
 function parseNamedOptions(args, allowed) {
     const entries = args.map((arg) => arg.match(/^--([a-z-]+)=(.+)$/)?.slice(1));
     if (args.some((arg) => arg.indexOf("=") !== arg.lastIndexOf("=")) ||
@@ -1533,7 +1804,7 @@ function containsCredential(value, credential, visited = new Set()) {
     visited.add(value);
     return Object.values(value).some((entry) => containsCredential(entry, credential, visited));
 }
-function syncSelectedResources(fs, root, aiw, profile, selected) {
+function syncSelectedResources(fs, root, aiw, profile, selected, apply = false, approvedFingerprint) {
     const target = parseManifest(fs.read(join(aiw, "manifest.yml"))).target.active;
     const resourceSelections = resourcesForCapabilities(selected);
     const bundled = loadBundledResources(target);
@@ -1584,7 +1855,16 @@ function syncSelectedResources(fs, root, aiw, profile, selected) {
     const inventory = parseOwnership(fs.read(ownershipPath));
     const nextInventory = new Map(inventory.map((entry) => [entry.path, entry]));
     const changes = [];
+    const changeActions = new Map();
+    const preserved = new Map();
     const conflicts = [];
+    const preserve = (path, type, content) => {
+        preserved.set(path, {
+            path,
+            state: type ?? "unknown",
+            ...(content === undefined ? {} : { contentFingerprint: stageFingerprint(content) }),
+        });
+    };
     for (const [path, { content, metadata }] of desired) {
         assertSafeProjectPath(fs, root, path);
         const relativePath = relative(root, path).split(sep).join("/");
@@ -1592,41 +1872,89 @@ function syncSelectedResources(fs, root, aiw, profile, selected) {
         const owned = nextInventory.get(relativePath);
         if (type === "missing") {
             changes.push({ path, content: Buffer.from(content, "utf8") });
+            changeActions.set(relativePath, "add");
             nextInventory.set(relativePath, createOwnedFile(relativePath, content, metadata));
             continue;
         }
         if (type !== "file" || !owned) {
             conflicts.push(relativePath);
+            preserve(relativePath, type);
             continue;
         }
         const actual = fs.read(path);
         if (createOwnedFile(relativePath, actual).checksum !== owned.checksum) {
             conflicts.push(relativePath);
+            preserve(relativePath, type, actual);
             continue;
         }
-        if (actual !== content)
+        if (actual !== content) {
             changes.push({ path, content: Buffer.from(content, "utf8") });
+            changeActions.set(relativePath, "update");
+        }
+        else
+            preserve(relativePath, type, actual);
         nextInventory.set(relativePath, createOwnedFile(relativePath, content, metadata));
     }
     for (const [path, content] of generatedFiles) {
         assertSafeProjectPath(fs, root, path);
         const type = fs.pathType?.(path);
-        if (type === "missing")
+        const relativePath = relative(root, path).split(sep).join("/");
+        if (type === "missing") {
             changes.push({ path, content: Buffer.from(content, "utf8") });
-        else if (type !== "file" || fs.read(path) !== content)
+            changeActions.set(relativePath, "add");
+        }
+        else if (type !== "file" || fs.read(path) !== content) {
             conflicts.push(relative(root, path).split(sep).join("/"));
+            preserve(relativePath, type, type === "file" ? fs.read(path) : undefined);
+        }
+        else
+            preserve(relativePath, type, fs.read(path));
     }
-    if (conflicts.length)
-        return {
-            error: `Sync preserved existing or modified project resources: ${[...new Set(conflicts)].sort().join(", ")}`,
-        };
     const nextOwnership = serializeOwnership([...nextInventory.values()]);
-    if (fs.read(ownershipPath) !== nextOwnership)
+    if (fs.read(ownershipPath) !== nextOwnership) {
         changes.push({ path: ownershipPath, content: Buffer.from(nextOwnership, "utf8") });
+        changeActions.set(relative(root, ownershipPath).split(sep).join("/"), "update");
+    }
+    const plan = {
+        target,
+        selected: [...new Set(selected)].sort(),
+        changes: changes
+            .map(({ path, content }) => ({
+            path: relative(root, path).split(sep).join("/"),
+            action: changeActions.get(relative(root, path).split(sep).join("/")) ?? "update",
+            contentFingerprint: stageFingerprint(content ?? new Uint8Array()),
+        }))
+            .sort((a, b) => a.path.localeCompare(b.path)),
+        preserved: [...preserved.values()].sort((a, b) => a.path.localeCompare(b.path)),
+        conflicts: [...new Set(conflicts)].sort(),
+        externalPending: selected.includes("react-best-practices")
+            ? [
+                {
+                    id: "vercel-react-best-practices",
+                    source: "vercel-labs/agent-skills",
+                    permissions: ["network:external"],
+                    approval: "separate human decision required",
+                },
+            ]
+            : [],
+    };
+    const fingerprint = stageFingerprint(JSON.stringify(plan));
+    const preview = `${JSON.stringify({ plan, fingerprint }, null, 2)}\n`;
+    if (!apply)
+        return { preview, fingerprint, conflicts: plan.conflicts };
+    if (!approvedFingerprint)
+        return { preview, fingerprint, conflicts: plan.conflicts };
+    if (approvedFingerprint !== fingerprint)
+        return { error: `The sync plan changed after review; current fingerprint is ${fingerprint}.` };
+    if (plan.conflicts.length)
+        return { error: `Sync plan has conflicts and made no changes: ${plan.conflicts.join(", ")}` };
     if (changes.length)
         applyProjectFileChanges(fs, root, changes);
     return {
         output: `Synchronized ${resourceSelections.length} selected bundled resources for ${target} and generated ${generatedFiles.size} project-specific files.`,
+        preview,
+        fingerprint,
+        conflicts: plan.conflicts,
     };
 }
 function personalizeBundledResource(type, id, content, profile) {

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. Ask whether the user switched or explicitly wants to continue with the current model. End the agent turn after asking and wait for a reply before scanning, launching subagents, or calling tools. Silence, ambiguity, or a preselected widget 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.
-5. **Recommendations.** Match catalog capabilities to the consolidated project profile. Show each recommendation with its purpose, evidence, resource types (skills, rules, agents, hooks, templates), required permissions, MCP server/source, and project-specific configuration steps. 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.** 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. 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. 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.
+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. 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, ask for confirmation, end the turn, and wait. Install only after that confirmation arrives in a later turn. 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.
 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
@@ -31,12 +31,17 @@ Make `/ai-init` a guided, evidence-backed onboarding flow. The initial `npx` ins
 - **AIINIT-003:** On supported hosts, three independent read-only analysis agents start in parallel and the orchestrator consolidates their evidence; unsupported hosts use a disclosed sequential fallback.
 - **AIINIT-004:** Scans include separate summaries for every detected monorepo workspace and do not attribute root dependencies to all packages.
 - **AIINIT-005:** Recommendations identify matching evidence, resource blocks, dependencies, MCP sources, and permissions.
+- **AIINIT-012:** Recommendations are displayed in concise tables grouped by category, and each item has a project-specific reason and supporting evidence before selection.
 - **AIINIT-006:** The selection UI offers install-all, custom, and none; custom selections can choose individual items by skills, rules, agents, hooks, templates, and MCPs.
 - **AIINIT-007:** Installation activates only selected resources and required dependencies, personalizes only context-sensitive content, and preserves unowned or edited files.
 - **AIINIT-008:** MCP setup is target-aware, merges safely with existing configuration, never stores literal secrets, and requires separate permission approval.
 - **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:** 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 pauses the agent turn at the model choice, 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; automated quality gates are explicitly distinct from human approval, and the agent must stop the turn until an explicit decision arrives.
+- **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.
 
 ## 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. Approval records provide an audit trail but cannot prove the identity of a person who responded in a host conversation.
+
+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/docs/backlog.md

@@ -43,6 +43,7 @@ Priority levels: **P0** blocks the product or makes it unsafe; **P1** is require
 - [x] **SDD-005** Implement verification skill. _Acceptance:_ missing evidence and untested requirements are reported.
 - [x] **SDD-006** Implement requirement-to-evidence traceability graph. _Acceptance:_ requirement → decision → task → code → test → evidence is queryable.
 - [x] **SDD-007** Add quality gates between workflow stages. _Acceptance:_ incomplete artifacts block progression with actionable feedback.
+- [x] **SDD-008** Connect workflow recommendations and quality gates to the SDD sequence. _Acceptance:_ selected later stages include declared prerequisites; verification is recommended for supported project profiles and test runners; each gate checks the matching artifact; review instructions do not refer to a nonexistent CLI gate.
 
 ## Adapters and migration — P1/P2
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multileaf/ai-workflow",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "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

@@ -7,3 +7,4 @@ description: Turn an early product idea into structured goals, assumptions, cons
 
 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.
 
+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.