@multileaf/ai-workflow 0.1.5 → 0.2.0

package/dist/types.d.ts

@@ -1,5 +1,7 @@
 export declare const TARGETS: readonly ["codex", "claude", "cursor", "gemini", "copilot", "universal"];
 export type Target = (typeof TARGETS)[number];
+export declare const HUMAN_APPROVAL_STAGES: readonly ["brainstorming", "specification", "technical-design", "plan", "implementation", "verification", "review", "traceability"];
+export type HumanApprovalStage = (typeof HUMAN_APPROVAL_STAGES)[number];
 export type CommandResult = {
     exitCode: number;
     output?: string;

package/dist/types.js

@@ -1 +1,11 @@
 export const TARGETS = ["codex", "claude", "cursor", "gemini", "copilot", "universal"];
+export const HUMAN_APPROVAL_STAGES = [
+    "brainstorming",
+    "specification",
+    "technical-design",
+    "plan",
+    "implementation",
+    "verification",
+    "review",
+    "traceability",
+];

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." };
@@ -750,32 +885,48 @@ export async function runCommand(args, root, fs, services = {}) {
             const selectedArg = args.find((arg) => arg.startsWith("--select="))?.split("=", 2)[1];
             const selected = selectedArg?.split(",") ?? (command === "sync" ? readSelectedRecommendations(fs, aiw) : []);
             if (command === "sync") {
-                const result = syncSelectedResources(fs, root, aiw, profile, selected);
+                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")) {
-                    const approvedPermissions = parseApprovedPermissions(args);
-                    if (!approvedPermissions.includes("network:external")) {
-                        messages.push("Remote skill pending: network:external was not approved. Bundled resources were installed; rerun sync with --allow=network:external only if you approve external access.");
+                    let pendingReason = "network:external was not approved";
+                    try {
+                        enforceConfiguredOrganizationPolicy(fs, aiw, {
+                            provider: "vercel-skills",
+                            source: "vercel-labs/agent-skills",
+                            permissions: ["network:external"],
+                        });
                     }
-                    else {
-                        try {
-                            enforceConfiguredOrganizationPolicy(fs, aiw, {
-                                provider: "vercel-skills",
-                                source: "vercel-labs/agent-skills",
-                                permissions: ["network:external"],
-                            });
-                            const target = parseManifest(fs.read(join(aiw, "manifest.yml"))).target.active;
-                            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");
-                            messages.push("Remote React best-practices skill installed.");
-                        }
-                        catch (error) {
-                            const reason = error instanceof Error ? error.message : String(error);
-                            messages.push(`Remote skill pending: ${reason}`);
-                        }
+                    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(" ") };
             }
@@ -818,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) };
@@ -946,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`);
@@ -954,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`);
@@ -962,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`);
@@ -971,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`);
@@ -979,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 = [];
@@ -1011,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))
@@ -1042,25 +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 = {
-                brainstorming: "generated/specs/brainstorm.md",
-                specification: "generated/specs/specification.md",
-                plan: "generated/plans/implementation-plan.md",
-                verification: "generated/reports/verification-report.md",
-            };
-            if (!stage || !Object.hasOwn(requirements, stage))
+            if (!stage || !APPROVAL_STAGES.includes(stage))
                 return {
                     exitCode: 1,
-                    error: "Usage: aiw gate <brainstorming|specification|plan|verification>",
+                    error: `Usage: aiw gate <${APPROVAL_STAGES.join("|")}>`,
                 };
-            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}.` };
+            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 (command === "validate") {
             if (!fs.exists(join(aiw, "manifest.yml")))
@@ -1411,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("=")) ||
@@ -1561,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);
@@ -1612,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("/");
@@ -1620,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 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, 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
@@ -38,7 +38,10 @@ 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 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/package.json

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