@multileaf/ai-workflow 0.1.5 → 0.2.1

package/dist/quality-gates.js

@@ -1,3 +1,4 @@
+import { parseDocument } from "yaml";
 function section(content, heading) {
     const match = content.match(new RegExp(`^## ${heading}\\s*$([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, "im"));
     return match?.[1].trim();
@@ -29,6 +30,15 @@ export function evaluateQualityGate(stage, content) {
             issues.push("Requirement acceptance criteria must use Given, When, and Then.");
         return issues;
     }
+    if (stage === "technical-design")
+        return requireSections(content, "Technical Design", [
+            "Context",
+            "Proposed Design",
+            "Alternatives",
+            "Interfaces",
+            "Risks",
+            "Validation",
+        ]);
     if (stage === "plan") {
         const fields = ["Requirement", "Code", "Tests", "Validation", "Evidence"];
         const issues = !/TASK-\d+/.test(content)
@@ -39,11 +49,53 @@ export function evaluateQualityGate(stage, content) {
                 issues.push(`Implementation plan task must define ${field}.`);
         return issues;
     }
-    return requireSections(content, "Verification Report", [
-        "Requirements Checked",
-        "Checks Passed",
-        "Missing Evidence",
-        "Residual Risks",
-        "Decision",
-    ]);
+    if (stage === "implementation")
+        return requireSections(content, "Implementation Evidence", [
+            "Changed Files",
+            "Tests",
+            "Validation",
+            "Deviations",
+        ]);
+    if (stage === "verification")
+        return requireSections(content, "Verification Report", [
+            "Requirements Checked",
+            "Checks Passed",
+            "Missing Evidence",
+            "Residual Risks",
+            "Decision",
+        ]);
+    if (stage === "review")
+        return requireSections(content, "Code Review", [
+            "Scope",
+            "Findings",
+            "Checks",
+            "Residual Risks",
+            "Decision",
+        ]);
+    const document = parseDocument(content, { uniqueKeys: true, strict: true });
+    if (document.errors.length)
+        return ["Traceability evidence must be valid YAML."];
+    const value = document.toJS();
+    if (!isRecord(value) || value.schema !== 1 || !Array.isArray(value.links))
+        return ["Traceability evidence must define schema: 1 and a links list."];
+    if (value.links.length === 0)
+        return ["Traceability evidence must link at least one requirement."];
+    const fields = ["requirement", "tasks", "code", "tests", "evidence"];
+    return value.links.flatMap((link, index) => {
+        if (!isRecord(link))
+            return [`Traceability link ${index + 1} must be a mapping.`];
+        return fields.flatMap((field) => {
+            const fieldValue = link[field];
+            return field === "requirement"
+                ? typeof fieldValue === "string" && /^REQ-\d+$/.test(fieldValue)
+                    ? []
+                    : [`Traceability link ${index + 1} requires a valid requirement ID.`]
+                : Array.isArray(fieldValue) && fieldValue.length > 0
+                    ? []
+                    : [`Traceability link ${index + 1} requires non-empty ${field} evidence.`];
+        });
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
 }

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) {