@multileaf/ai-workflow 0.9.0 → 0.11.0

package/dist/workflow.js

@@ -50,7 +50,8 @@ 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, summarizeUsageByModel, } from "./token-usage.js";
-import { APPROVAL_STAGES, assertWorkflowId, validateTaskTicket, approveStage, beginStageApproval, createApprovalLedger, getUnresolvedPrerequisites, invalidateStageAndDescendants, parseApprovalLedger, parseWorkflowSession, rejectStage, serializeApprovalLedger, serializeWorkflowSession, skipOptionalStage, stageDefinition, stageFingerprint, } from "./human-approval.js";
+import { APPROVAL_STAGES, assertWorkflowId, validateTaskTicket, approveStage, beginStageApproval, createApprovalLedger, getUnresolvedPrerequisites, invalidateStageAndDescendants, parseApprovalLedger, parseWorkflowSession, rejectStage, serializeApprovalLedger, serializeWorkflowSession, skipOptionalStage, stageDefinition, stageFingerprint, effectiveLane, } from "./human-approval.js";
+import { parse as parseYaml, stringify } from "yaml";
 import { measureContextQuality, serializeContextQuality } from "./context-quality.js";
 import { collectContextBench, compareContextBench, parseContextBench, serializeContextBench, } from "./context-benchmark.js";
 import { materializeParityTask, parseParityTask, runParitySuite, serializeParitySuite, TASK_ASSEMBLER, } from "./task-parity.js";
@@ -64,6 +65,8 @@ import { parseTraceabilityGraph } from "./traceability.js";
 import { serializeAdapterCapabilities } from "./adapter-contract.js";
 import { buildTraceabilityGraph, serializeTraceabilityGraph } from "./traceability.js";
 import { evaluateQualityGate } from "./quality-gates.js";
+import { BlockingError, blockingResultToJson, describeBlockingReason } from "./blocking-reasons.js";
+import { runRiskAssess } from "./risk-assess.js";
 import { parseMigrationCheckpoint, planNeutralResourceMigration, readResourceBytes, serializeMigrationPreview, serializeMigrationCheckpoint, validateNeutralResourceDocument, writeResourceBytes, } from "./migration.js";
 import { parsePrivateRegistries, parseTeamPreset, serializePrivateRegistries, serializeTeamPreset, fetchPrivateRegistryClient, } from "./team-configuration.js";
 import { enforcePolicyGate, gitPolicyTracking } from "./policy-gate.js";
@@ -76,10 +79,9 @@ function beginWorkflowSession(fs, aiw, options) {
     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.`,
-            };
+            throw new BlockingError(describeBlockingReason("workflow_still_active", {
+                detail: `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`);
@@ -110,8 +112,15 @@ function beginWorkflowSession(fs, aiw, options) {
         updatedAt: now,
         ...(options.ticket ? { ticket: options.ticket } : {}),
         ...(options.title ? { title: options.title } : {}),
+        ...(options.lane === "light" && options.laneReason
+            ? { lane: "light", laneReason: options.laneReason }
+            : {}),
     };
-    const ledger = createApprovalLedger(workflowId);
+    const ledger = createApprovalLedger(workflowId, {
+        ...(options.lane === "light" && options.laneReason
+            ? { lane: "light", laneReason: options.laneReason }
+            : {}),
+    });
     fs.write(ledgerPath, serializeApprovalLedger(ledger));
     fs.write(sessionPath, serializeWorkflowSession(session));
     return { exitCode: 0, output: `Workflow started: ${workflowId}.` };
@@ -124,14 +133,35 @@ export async function runCommand(args, root, fs, services = {}) {
         if (command === "task") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
-            const usage = "Usage: aiw task start --ticket=TEAM-123 [--title=text] [--id=workflow-id] | aiw task status";
+            const usage = "Usage: aiw task start --ticket=TEAM-123 [--title=text] [--id=workflow-id] [--lane=light --lane-reason=text] | aiw task status | aiw task escalate --reason=text | aiw task evidence --validation=text";
             const action = args[1];
             const sessionPath = join(aiw, "workflow.yml");
             if (action === "start") {
-                const options = parseNamedOptions(args.slice(2), ["ticket", "title", "id"]);
+                const options = parseNamedOptions(args.slice(2), [
+                    "ticket",
+                    "title",
+                    "id",
+                    "lane",
+                    "lane-reason",
+                ]);
                 if (!options?.ticket)
                     return { exitCode: 1, error: usage };
                 validateTaskTicket(options.ticket);
+                if (options.lane !== undefined && options.lane !== "light")
+                    return { exitCode: 1, error: "Only --lane=light exists; omit it for the full lane." };
+                const laneReason = options["lane-reason"];
+                if (options.lane === "light") {
+                    if (!laneReason)
+                        return {
+                            exitCode: 1,
+                            error: "--lane=light requires --lane-reason: the resume-test call, recorded for audit.",
+                        };
+                    if (laneReason.length > 500 || /[\r\n]/.test(laneReason))
+                        return {
+                            exitCode: 1,
+                            error: "--lane-reason must be a single line of at most 500 bytes.",
+                        };
+                }
                 if (options.id !== undefined) {
                     try {
                         assertWorkflowId(options.id);
@@ -140,20 +170,104 @@ export async function runCommand(args, root, fs, services = {}) {
                         return { exitCode: 1, error: "Workflow ID must be a UUID." };
                     }
                 }
+                const lane = options.lane === "light" ? "light" : undefined;
                 const result = beginWorkflowSession(fs, aiw, {
                     ...(options.id ? { id: options.id } : {}),
                     ticket: options.ticket,
                     ...(options.title ? { title: options.title } : {}),
+                    ...(lane ? { lane, laneReason: laneReason } : {}),
                 });
                 if (result.exitCode !== 0)
                     return result;
                 const title = options.title ? ` titled "${options.title}"` : "";
+                if (lane)
+                    return {
+                        exitCode: 0,
+                        output: `Task started for ticket ${options.ticket}${title} (light lane): ${result.output}\n` +
+                            "Resume test: this work is small when it is understood, risk is contained, and the work could be resumed from your request plus `git diff`.\n" +
+                            `Rationale recorded: ${laneReason}\n` +
+                            'No durable spec/plan artifacts are required. Record validation with `aiw task evidence --validation="<command and result>"`, then complete with `aiw workflow complete`. If scope grows, escalate with `aiw task escalate --reason=...`.',
+                    };
                 return {
                     exitCode: 0,
                     output: `Task started for ticket ${options.ticket}${title}: ${result.output}\n` +
                         `Next steps: ask the user whether the requirement is clear enough to skip brainstorming (record an accepted skip with \`aiw skip brainstorming --reason="Requirement provided by ticket ${options.ticket}"\`), then create the specification with \`aiw spec --ticket=${options.ticket} --title=...\`.`,
                 };
             }
+            if (action === "escalate") {
+                const options = parseNamedOptions(args.slice(2), ["reason"]);
+                if (!options?.reason)
+                    return { exitCode: 1, error: "Usage: aiw task escalate --reason=why-scope-grew" };
+                if (!fs.exists(sessionPath))
+                    return { exitCode: 1, error: "No SDD workflow is active. Start one first." };
+                const { session } = readWorkflowState(aiw, fs);
+                if (session.lane !== "light")
+                    return {
+                        exitCode: 1,
+                        error: "Only light-lane workflows escalate; this one already runs the full lane.",
+                    };
+                if (session.laneEscalatedAt)
+                    return {
+                        exitCode: 1,
+                        error: `Workflow ${session.workflowId} already escalated to the full lane.`,
+                    };
+                const now = new Date().toISOString();
+                fs.write(sessionPath, serializeWorkflowSession({
+                    ...session,
+                    laneEscalatedAt: now,
+                    laneEscalationReason: options.reason,
+                    updatedAt: now,
+                }));
+                const evidencePath = join(aiw, `checkpoints/task-light-${session.workflowId}.yml`);
+                return {
+                    exitCode: 0,
+                    output: `Workflow ${session.workflowId} escalated to the full lane.\n` +
+                        (fs.exists(evidencePath)
+                            ? `Light-lane evidence preserved and linked: ${evidencePath}\n`
+                            : "No light-lane evidence had been recorded yet.\n") +
+                        "Stages now run the full approval sequence from brainstorming.",
+                };
+            }
+            if (action === "evidence") {
+                const options = parseNamedOptions(args.slice(2), ["validation"]);
+                if (!options?.validation)
+                    return {
+                        exitCode: 1,
+                        error: 'Usage: aiw task evidence --validation="<command and its observed result>"',
+                    };
+                if (!fs.exists(sessionPath))
+                    return { exitCode: 1, error: "No SDD workflow is active. Start one first." };
+                const { session } = readWorkflowState(aiw, fs);
+                if (effectiveLane(session) !== "light")
+                    return {
+                        exitCode: 1,
+                        error: "Evidence entries are a light-lane command; full-lane workflows record stage artifacts and gates.",
+                    };
+                const evidencePath = join(aiw, `checkpoints/task-light-${session.workflowId}.yml`);
+                const existing = fs.exists(evidencePath)
+                    ? parseLightEvidence(fs.read(evidencePath))
+                    : {
+                        schema: 1,
+                        workflowId: session.workflowId,
+                        ...(session.ticket ? { ticket: session.ticket } : {}),
+                        lane: "light",
+                        ...(session.laneReason ? { laneReason: session.laneReason } : {}),
+                        entries: [],
+                    };
+                const updated = {
+                    ...existing,
+                    entries: [
+                        ...existing.entries,
+                        { note: options.validation, recordedAt: new Date().toISOString() },
+                    ],
+                };
+                fs.mkdir(join(aiw, "checkpoints"));
+                fs.write(evidencePath, stringify({ ...updated }, { lineWidth: 0 }));
+                return {
+                    exitCode: 0,
+                    output: `Validation evidence recorded (${updated.entries.length} entr${updated.entries.length === 1 ? "y" : "ies"}): ${options.validation}`,
+                };
+            }
             if (action === "status") {
                 if (!fs.exists(sessionPath))
                     return {
@@ -161,14 +275,24 @@ export async function runCommand(args, root, fs, services = {}) {
                         output: "No SDD workflow is active. Start one with `aiw task start --ticket=TEAM-123`.",
                     };
                 const { session, ledger } = readWorkflowState(aiw, fs, false);
+                const lane = session.lane === "light"
+                    ? [
+                        `Lane: light — ${session.laneEscalatedAt ? `escalated to the full lane (${session.laneEscalationReason})` : session.laneReason}`,
+                    ]
+                    : [];
                 const lines = [
                     ...(session.ticket
                         ? [`Ticket: ${session.ticket}${session.title ? ` — ${session.title}` : ""}`]
                         : []),
+                    ...lane,
                     `Workflow: ${session.workflowId} (${session.status})`,
                     "Stages:",
                     ...APPROVAL_STAGES.map((stage) => `- ${stage}: ${ledger.stages[stage]?.status ?? "not-started"}`),
                 ];
+                if (session.status === "active" && effectiveLane(session) === "light") {
+                    lines.push('Next: record validation with `aiw task evidence --validation="<command and result>"`, then `aiw workflow complete`. If scope grows: `aiw task escalate --reason=...`.');
+                    return { exitCode: 0, output: lines.join("\n") };
+                }
                 const next = APPROVAL_STAGES.find((stage) => (ledger.stages[stage]?.status ?? "not-started") === "not-started");
                 if (session.status === "active" && next)
                     lines.push(`Next: ${next === "brainstorming" && session.ticket ? `decide brainstorm or record an accepted skip (ticket ${session.ticket} already provides the requirement)` : `advance ${next} (gate, approval)`}.`);
@@ -182,7 +306,7 @@ export async function runCommand(args, root, fs, services = {}) {
             const action = args[1];
             const sessionPath = join(aiw, "workflow.yml");
             if (action === "start") {
-                const options = parseNamedOptions(args.slice(2), ["id"]);
+                const options = parseNamedOptions(args.slice(2).filter((argument) => argument !== "--json"), ["id"]);
                 if (!options)
                     return { exitCode: 1, error: "Usage: aiw workflow start [--id=workflow-id]" };
                 return beginWorkflowSession(fs, aiw, { id: options.id });
@@ -197,8 +321,67 @@ export async function runCommand(args, root, fs, services = {}) {
                     output: `Workflow ${session.workflowId} (${session.status})\n${stages.join("\n")}\n${workflowNextAction(ledger)}`,
                 };
             }
+            if (action === "abandon") {
+                const options = parseNamedOptions(args.slice(2), ["reason"]);
+                if (!options?.reason)
+                    return { exitCode: 1, error: "Usage: aiw workflow abandon --reason=why-obsolete" };
+                if (options.reason.length > 500 || /[\r\n]/.test(options.reason))
+                    return {
+                        exitCode: 1,
+                        error: "--reason must be a single line of at most 500 bytes.",
+                    };
+                if (!fs.exists(sessionPath))
+                    return {
+                        exitCode: 1,
+                        error: "No SDD workflow is active; start one with `aiw workflow start` or `aiw task start --ticket=TEAM-123`. [reason: workflow_not_active] Terminal: no automatic continuation beyond starting a workflow.",
+                    };
+                const { session } = readActiveWorkflow(aiw, fs);
+                const ledgerPath = join(aiw, "approvals.yml");
+                const sessionArchive = join(aiw, "checkpoints", `workflow-${session.workflowId}-session.yml`);
+                const ledgerArchive = join(aiw, "checkpoints", `workflow-${session.workflowId}-approvals.yml`);
+                fs.mkdir(join(aiw, "checkpoints"));
+                const now = new Date().toISOString();
+                const archivedSession = {
+                    ...session,
+                    status: "abandoned",
+                    abandonedReason: options.reason,
+                    updatedAt: now,
+                };
+                fs.write(sessionArchive, serializeWorkflowSession(archivedSession));
+                if (fs.exists(ledgerPath))
+                    fs.write(ledgerArchive, fs.read(ledgerPath));
+                fs.remove?.(sessionPath);
+                if (fs.exists(ledgerPath))
+                    fs.remove?.(ledgerPath);
+                return {
+                    exitCode: 0,
+                    output: `Workflow ${session.workflowId} abandoned (${options.reason}).\n` +
+                        `Session archived: ${sessionArchive}\n` +
+                        (fs.exists(ledgerArchive) ? `Approval ledger archived: ${ledgerArchive}\n` : "") +
+                        "Start a new one when ready.",
+                };
+            }
             if (action === "complete") {
                 const { session, ledger } = readActiveWorkflow(aiw, fs);
+                if (effectiveLane(session) === "light") {
+                    const evidencePath = join(aiw, `checkpoints/task-light-${session.workflowId}.yml`);
+                    const hasEntries = fs.exists(evidencePath)
+                        ? parseLightEvidence(fs.read(evidencePath)).entries.length > 0
+                        : false;
+                    if (!hasEntries)
+                        throw new BlockingError(describeBlockingReason("light_evidence_missing", {
+                            detail: `Light-lane workflow ${session.workflowId} cannot complete without recorded validation evidence.`,
+                        }));
+                    fs.write(sessionPath, serializeWorkflowSession({
+                        ...session,
+                        status: "complete",
+                        updatedAt: new Date().toISOString(),
+                    }));
+                    return {
+                        exitCode: 0,
+                        output: `Workflow completed (light lane): ${session.workflowId}. Evidence: ${evidencePath}`,
+                    };
+                }
                 const unresolved = APPROVAL_STAGES.filter((stage) => ledger.stages[stage]?.status !== "approved" &&
                     ledger.stages[stage]?.status !== "skipped");
                 if (unresolved.length)
@@ -222,10 +405,15 @@ export async function runCommand(args, root, fs, services = {}) {
             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 rest = args.slice(2).filter((argument) => argument !== "--json");
+            const { session, ledger } = readActiveWorkflow(aiw, fs);
+            if (effectiveLane(session) === "light")
+                throw new BlockingError(describeBlockingReason("lane_escalation_required", {
+                    detail: `Light-lane workflow ${session.workflowId} does not approve stages; escalate to the full lane to continue.`,
+                }));
             const workflowStage = stage;
             if (command === "skip") {
-                const options = parseNamedOptions(args.slice(2), ["reason"]);
+                const options = parseNamedOptions(rest, ["reason"]);
                 if (!options?.reason)
                     return {
                         exitCode: 1,
@@ -241,19 +429,28 @@ export async function runCommand(args, root, fs, services = {}) {
             }
             const artifact = approvalArtifactPath(aiw, workflowStage);
             if (!artifact || !fs.exists(artifact))
-                return { exitCode: 1, error: `Approval evidence is missing for ${workflowStage}.` };
+                throw new BlockingError(describeBlockingReason("approval_evidence_missing", {
+                    stage: workflowStage,
+                    artifactPath: artifact ?? undefined,
+                    detail: `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));
                     const existing = ledger.stages[workflowStage];
-                    return {
-                        exitCode: 1,
-                        error: existing
-                            ? `The ${workflowStage} artifact changed after review; its approval is stale. Rerun the quality gate and request approval again.`
-                            : `No passing quality gate recorded for ${workflowStage}. Run aiw gate ${workflowStage} before approving.`,
-                    };
+                    if (existing)
+                        throw new BlockingError(describeBlockingReason("approval_stale", {
+                            stage: workflowStage,
+                            artifactPath: artifact,
+                            detail: `The ${workflowStage} artifact changed after review; its approval is stale. Rerun the quality gate and request approval again.`,
+                        }));
+                    throw new BlockingError(describeBlockingReason("approval_gate_missing", {
+                        stage: workflowStage,
+                        artifactPath: artifact,
+                        detail: `No passing quality gate recorded for ${workflowStage}. Run aiw gate ${workflowStage} before approving.`,
+                    }));
                 }
                 const updated = approveStage(ledger, workflowStage, {
                     artifactHash,
@@ -262,7 +459,7 @@ export async function runCommand(args, root, fs, services = {}) {
                 fs.write(join(aiw, "approvals.yml"), serializeApprovalLedger(updated));
                 return { exitCode: 0, output: `Human approval recorded for ${workflowStage}.` };
             }
-            const options = parseNamedOptions(args.slice(2), ["reason"]);
+            const options = parseNamedOptions(rest, ["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());
@@ -1749,6 +1946,11 @@ export async function runCommand(args, root, fs, services = {}) {
             fs.write(path, serialized);
             return { exitCode: 0, output: `Traceability graph created: ${path}` };
         }
+        if (command === "risk") {
+            if (args[1] !== "assess")
+                return { exitCode: 1, error: "Usage: aiw risk assess [--base-ref=ref] [--json]" };
+            return runRiskAssess(args.slice(2), root, fs);
+        }
         if (command === "gate") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
@@ -1762,15 +1964,21 @@ export async function runCommand(args, root, fs, services = {}) {
             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}.`,
-                };
+                throw new BlockingError(describeBlockingReason("gate_evidence_missing", {
+                    stage,
+                    artifactPath: artifactPath ?? undefined,
+                    detail: `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(" ")}` };
+                    throw new BlockingError(describeBlockingReason("gate_incomplete", {
+                        stage,
+                        artifactPath,
+                        gateIssues: issues,
+                        detail: `Quality gate blocked: ${issues.join(" ")}`,
+                    }));
             }
             const { ledger } = readActiveWorkflow(aiw, fs);
             const updated = beginStageApproval(ledger, workflowStage, {
@@ -2519,6 +2727,9 @@ export async function runCommand(args, root, fs, services = {}) {
         };
     }
     catch (error) {
+        if (error instanceof BlockingError && args.includes("--json")) {
+            return { exitCode: 1, output: JSON.stringify(blockingResultToJson(error.result)) };
+        }
         return { exitCode: 1, error: error instanceof Error ? error.message : String(error) };
     }
 }
@@ -2532,7 +2743,9 @@ function readWorkflowState(aiw, fs, requireActive = true) {
     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.`);
+        throw new BlockingError(describeBlockingReason("workflow_complete", {
+            detail: `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))
@@ -2561,20 +2774,57 @@ function workflowNextAction(ledger) {
         return `Next action: revise ${next}, rerun its gate, and request human approval.`;
     return `Next action: prepare ${next} evidence.`;
 }
+function parseLightEvidence(content) {
+    const value = parseYaml(content);
+    if (!value || typeof value !== "object" || value.schema !== 1)
+        throw new Error("Light-lane evidence checkpoint must be schema version 1.");
+    const record = value;
+    const entries = Array.isArray(record.entries) ? record.entries : [];
+    return {
+        schema: 1,
+        workflowId: String(record.workflowId ?? ""),
+        ...(record.ticket !== undefined ? { ticket: String(record.ticket) } : {}),
+        lane: "light",
+        ...(record.laneReason !== undefined ? { laneReason: String(record.laneReason) } : {}),
+        entries: entries.map((entry) => ({
+            note: String(entry.note ?? ""),
+            recordedAt: String(entry.recordedAt ?? ""),
+        })),
+    };
+}
 function assertStageReady(aiw, fs, stage) {
-    const { ledger } = readActiveWorkflow(aiw, fs);
+    const { session, ledger } = readActiveWorkflow(aiw, fs);
+    if (effectiveLane(session) === "light")
+        throw new BlockingError(describeBlockingReason("lane_escalation_required", {
+            stage,
+            detail: `Light-lane workflow ${session.workflowId} does not author stage artifacts; escalate to the full lane to continue.`,
+        }));
     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(", ")}.`);
+            throw new BlockingError(describeBlockingReason("stage_prerequisite_pending", {
+                stage,
+                pendingStages: pending,
+                detail: `Cannot enter ${stage}; previous stage(s) are awaiting human approval: ${pending.join(", ")}.`,
+            }));
+        throw new BlockingError(describeBlockingReason("stage_prerequisite_unresolved", {
+            stage,
+            unresolvedStages: unresolved,
+            detail: `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.`);
+        throw new BlockingError(describeBlockingReason("stage_awaiting_approval", {
+            stage,
+            detail: `${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.`);
+        throw new BlockingError(describeBlockingReason("stage_already_approved", {
+            stage,
+            detail: `${stage} is already approved. Evidence changes require rerunning its gate.`,
+        }));
 }
 function approvalArtifactPath(aiw, stage) {
     if (stage === "technical-design")

package/docs/README.md

@@ -22,6 +22,8 @@ AI Workflow is a portable, spec-driven development system for AI coding agents.
 - [Plugin authoring](plugin-authoring.md)
 - [Release process](release-process.md)
 - [Release backlog](release-backlog.md)
+- [Continuation inventory](continuation-inventory.md)
+- [Workflow proportionality opportunities](opportunities/README.md) (ODD/RDD analysis, ADR-001)
 - [Backlog](backlog.md)
 
 All generated AI Workflow artifacts are written in English unless the user explicitly requests another language.

package/docs/architecture.md

@@ -45,6 +45,56 @@ Project analysis is hybrid: deterministic detectors establish observable facts,
 
 ## Human workflow approvals
 
+Workflows run in one of two lanes. The **full lane** (default, and the only non-interactive default) is the staged approval sequence below. The **light lane** (`aiw task start --lane=light --lane-reason=...`, human-chosen via the resume test — work is small when it could be resumed from the request plus `git diff`) skips durable spec/plan artifacts: validation evidence is recorded per entry (`aiw task evidence`), completion requires at least one entry, and the lane plus rationale are written into the session and approval ledger for audit. Stage commands in the light lane block with a `lane_escalation_required` reason until `aiw task escalate --reason=...` moves the workflow to the full lane; recorded evidence is preserved and linked. Escalation is one-way; the full lane then runs the complete approval sequence. An obsolete active workflow is archived with `aiw workflow abandon --reason=...`: session and ledger move under `.aiw/checkpoints/` with `status: abandoned`, freeing the active slot.
+
+## Current flow
+
+```mermaid
+flowchart TD
+    REQ["Change request / ticket"] --> RA["aiw risk assess<br/>read-only · content-based · deterministic"]
+    RA -->|"passive — docs-only"| LANE
+    RA -->|"medium — plain code"| LANE
+    RA -->|"high — security · contracts · concurrency ·<br/>data · delivery · untested (risk due: yes)"| FS
+
+    LANE{"Human lane decision<br/>resume test: resumable from<br/>request + git diff?"}
+    LANE -->|"light — human chooses"| LS
+    LANE -->|"full — default"| FS
+
+    subgraph LIGHT["Light lane — no durable artifacts"]
+        LS["aiw task start --lane=light --lane-reason<br/>rationale into session + ledger"] --> LE["aiw task evidence --validation<br/>compact checkpoint"]
+        LE --> LC["aiw workflow complete<br/>requires at least one entry"]
+    end
+
+    subgraph FULL["Full lane — staged SDD, gate + human approve per stage"]
+        FS["workflow start"] --> BR["brainstorming"] --> SP["specification"] --> TD["technical-design<br/>optional, skip needs reason"] --> PL["plan"] --> IM["implementation<br/>TDD"] --> VE["verification"] --> RV["code review"] --> TR["traceability"] --> FC["workflow complete"]
+    end
+
+    LS -.->|"stage or approve attempted"| B1["Blocked<br/>reason: lane_escalation_required"]
+    B1 --> ESC["aiw task escalate --reason<br/>one-way · evidence preserved"]
+    ESC --> FS
+
+    RV -.->|"adversarial-review skills installed"| ADV["judge A + judge B — blind, independent<br/>refuter: corroborated severe blocks<br/>refuted / inconclusive → advisory<br/>unevidenced severe → advisory"]
+
+    LC --> AUD["Audit trail<br/>approvals ledger · checkpoints · light evidence"]
+    FC --> AUD
+
+    subgraph CI["CI enforcement layer"]
+        E1["OPP-004: every block prints a reason code<br/>plus an exact next_command — continuations<br/>are executed by tests before they ship"]
+        E2["OPP-006 ratchet: every aiw command named<br/>by skills and READMEs executes in tests"]
+        E3["OPP-005 friction benchmark:<br/>in-band / out-of-band / dead-end<br/>budget: zero dead ends"]
+    end
+
+    B1 -.-> E1
+    E1 -.-> E2 -.-> E3
+```
+
+Reading notes:
+
+- `aiw risk assess` is **advisory**: it informs the lane decision and flags risk due; it never forces a lane or bypasses approval.
+- The light lane is never agent-chosen: `resources/skills/ticket.md` routes it through the host's blocking question widget with the resume test stated verbatim.
+- Every blocking exit on the diagram prints `[reason: <code>]` and either `Next: run \`aiw ...\`` or an explicit terminal statement — the full mapping lives in [Continuation inventory](continuation-inventory.md).
+- A `high` risk assessment with an active workflow points at continuing the workflow (gate and approve); without one it names `aiw workflow start`.
+
 The SDD approval contract models the ordered stages brainstorming, specification, technical design, plan, implementation, verification, review, and traceability. Brainstorming and technical design are optional; skipping either requires a human-accepted reason. Every other stage must be approved. Automated quality-gate results are stored separately from human decisions and can only move an artifact to pending review, never directly to approved.
 
 Each approval is scoped to one workflow ID and bound to a SHA-256 fingerprint of the exact artifact reviewed, so a later feature cannot reuse earlier approvals. A content change or rejection makes that stage and its descendants stale. The CLI persists the versioned ledger in `.aiw/approvals.yml`, blocks stage commands when prerequisites are unresolved, and keeps passing quality gates distinct from human approval. The generated bootstrap and stage skills require the host's native blocking question widget for human decisions when available, with a waiting chat prompt as fallback. Approval records provide an audit trail but cannot prove the identity of a respondent or independently verify that the host widget was used.

package/docs/backlog.md

@@ -109,6 +109,19 @@ Priority levels: **P0** blocks the product or makes it unsafe; **P1** is require
 
 - [x] **ENG-001** Update GitHub Actions to Node 24-native versions. _Acceptance:_ `actions/checkout` and `actions/setup-node` upgraded past v4 so release workflows no longer emit Node.js 20 deprecation warnings; CI and Release workflows pass on `ubuntu-latest` before and after the October 19, 2026 Ubuntu 26 runner migration.
 
+## Workflow proportionality (ODD/RDD analysis) — P1–P3
+
+Derived from the Gentle-AI ODD/RDD analysis; scope and rejected alternatives recorded in [ADR-001](../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md). Each item links to a self-contained opportunity document under `docs/opportunities/` and can be implemented independently.
+
+- [x] **OPP-001** Add a light lane for small, understood work (proportional ceremony). _Acceptance:_ see [OPP-001](../opportunities/OPP-001-proportional-ceremony-light-lane.md); no durable spec/plan artifacts for light tasks, evidence and lane rationale still recorded, explicit escalation to the full lane on scope growth, full lane unchanged.
+- [x] **OPP-002** Add `aiw risk assess` — read-only, content-based risk classification with an exact runnable next command. _Acceptance:_ see [OPP-002](../opportunities/OPP-002-risk-assess-command.md); deterministic and offline by default, no `.aiw/` mutation, escalation raises and never lowers tier, `next_command` executes as printed.
+- [x] **OPP-003** Ship an optional `adversarial-review` package (blind judges + refuter with proof-carrying findings). _Acceptance:_ see [OPP-003](../opportunities/OPP-003-adversarial-review-package.md); severe findings without reproducible evidence degrade to advisory; refutation outcomes are corroborated/refuted/inconclusive with proof references; human acceptance still required.
+- [ ] **OPP-004** Emit typed reason codes and exact continuation commands on every blocking exit. _Acceptance:_ see [OPP-004](../opportunities/OPP-004-exact-continuation-commands.md); every block carries a reason code and either a tested runnable `next_command` or an explicit terminal statement; continuation inventory stays complete in CI.
+- [x] **OPP-005** Add a friction benchmark classifying blocks as in-band / out-of-band / dead-end over packaged-CLI journeys. _Acceptance:_ see [OPP-005](../opportunities/OPP-005-friction-benchmark.md); deterministic classification, continuations actually executed, CI fails on any dead end.
+- [x] **OPP-006** Adopt the emission ≠ usability test policy: messages naming a command must have a test executing it. _Acceptance:_ see [OPP-006](../opportunities/OPP-006-emission-usability-test-policy.md); extraction helper covers emitted and generated command mentions; generated `ai-init` skills' commands are executed in e2e tests.
+- [ ] **007-decision-findings-triage-scope-watch** Decision model — findings-evidence triage and lane scope-watch (advisory-only). _Acceptance:_ see [OPP-007](../opportunities/OPP-007-decision-findings-triage-scope-watch.md); unconfigured = byte-identical offline behavior; advisory flags never block, never lower tiers, never choose lanes.
+- [ ] **008-embedding-covering-tests-judge-context** Embedding retrieval — covering-test detection and judge context scoping. _Acceptance:_ see [OPP-008](../opportunities/OPP-008-embedding-covering-tests-judge-context.md); retrieval only prevents false `untested` flags (absence fails safe toward high); scoped judge prompts labeled as context aids within token ceilings.
+
 ## Backlog rules
 
 - [x] **FND-009** Add self-validation workflow. _Acceptance:_ changes affecting AIW behavior execute against this repository and record generated-output evidence.

package/docs/continuation-inventory.md

@@ -0,0 +1,24 @@
+# Continuation Inventory
+
+Every blocking `aiw` exit carries a stable reason code plus either an exact runnable continuation or an explicit terminal statement. A message may name a command only when running that command resolves the block it was printed for (OPP-004, [ADR-001](../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md)).
+
+- Codes are declared in `src/blocking-reasons.ts` (`BLOCKING_REASON_CODES`); adding a code requires a definition with a continuation producer and a test.
+- With `--json`, blocking exits return `{ "reason_code": ..., "next_command" | "next_action" | "terminal": ... }`.
+- The table below is generated from the registry; a test in `src/blocking-reasons.test.ts` fails CI when this page drifts from the code.
+
+| Reason code                     | Description                                                                                   | Continuation     |
+| ------------------------------- | --------------------------------------------------------------------------------------------- | ---------------- |
+| `gate_evidence_missing`         | The quality gate is blocked because the required evidence artifact is missing.                | explicit action  |
+| `gate_incomplete`               | The quality gate found completeness issues in the stage artifact.                             | explicit action  |
+| `stage_prerequisite_pending`    | A previous stage is awaiting human approval before this stage can start.                      | runnable command |
+| `stage_prerequisite_unresolved` | Previous stages need human approval or an accepted optional skip before this stage can start. | runnable command |
+| `stage_awaiting_approval`       | This stage is awaiting human approval; approve or reject it before continuing.                | runnable command |
+| `stage_already_approved`        | This stage is already approved; changed evidence requires rerunning its quality gate.         | runnable command |
+| `approval_evidence_missing`     | Approval cannot be recorded because the stage evidence artifact is missing.                   | explicit action  |
+| `approval_stale`                | The artifact changed after review; its approval is stale and the gate must run again.         | runnable command |
+| `approval_gate_missing`         | No passing quality gate is recorded for this stage; gate it before approving.                 | runnable command |
+| `lane_escalation_required`      | Light-lane workflows do not author stage artifacts; escalate to the full lane to continue.    | explicit action  |
+| `light_evidence_missing`        | A light-lane workflow cannot complete without at least one recorded validation entry.         | explicit action  |
+| `workflow_still_active`         | A workflow is already active; finish or archive it before starting another.                   | explicit action  |
+| `workflow_not_active`           | No SDD workflow is active for this command to operate on.                                     | runnable command |
+| `workflow_complete`             | This workflow is already complete; start a new workflow to continue working.                  | runnable command |

package/docs/decision-model-evaluation.md

@@ -40,3 +40,7 @@ Observed behavior on real plans: an evidence-free plan scored `gate: ready` with
 ## Hard boundary (unchanged)
 
 Decision-model output is `inferred` evidence with confidence, never `confirmed`. It can move an artifact to _pending review_, never to _approved_, and cannot replace the fingerprinted human approval ledger. This matches the existing approval contract and keeps the audit trail human-owned.
+
+## Planned integration (OPP-007)
+
+The next planned decision-model roles follow the same contracts: findings-evidence triage for severe review findings (does the cited proof support the claim — advisory flag, the refuter still decides) and a lane scope-watch that flags mismatch between a chosen light lane and deterministic risk signals. Both stay advisory-only with the deterministic floor unchanged; unconfigured behavior is byte-identical. See [OPP-007](opportunities/OPP-007-decision-findings-triage-scope-watch.md).