@multileaf/ai-workflow 0.9.0 → 0.10.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";
@@ -110,8 +113,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 +134,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 +171,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 +276,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)`}.`);
@@ -199,6 +324,25 @@ export async function runCommand(args, root, fs, services = {}) {
             }
             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 +366,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 +390,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 +420,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 +1907,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 +1925,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 +2688,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) };
     }
 }
@@ -2561,20 +2733,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.
+
+## 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,21 @@
+# 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  |

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

package/docs/opportunities/OPP-001-proportional-ceremony-light-lane.md

@@ -0,0 +1,62 @@
+# OPP-001: Proportional ceremony — light lane for small, understood work
+
+- Status: Implemented (2026-10-30, plan Wave 4)
+- Priority: P2
+- Added: 2026-10-30
+- Decision: [ADR-001](../../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md), Decision A
+
+## Problem
+
+Every AI Workflow task, regardless of size or risk, traverses the same staged pipeline (brainstorm → specification → ADR → plan → implementation → verification → review → traceability), each stage producing durable artifacts under `.aiw/generated/`. For small, well-understood changes this generates artifacts nobody reads, and users bypass the workflow manually — which then produces no evidence at all. Gentle-AI retired SDD for exactly this reason; the market signal is that uniform ceremony causes abandonment in daily use.
+
+## Source concept (ODD)
+
+ODD classifies task size with the **resume test**: work is _small_ when it is understood, risk is contained, and the work could be resumed from the original request plus `git diff`. Small work creates **no durable task artifacts**; substantial work creates exactly one feature document before the first source write. ODD also holds that findings never silently expand authorization, and scope growth is an explicit event.
+
+References:
+
+- Gentle-AI `docs/usage.md`, section "Organic Driven Development (ODD)" — protocol steps 4 (Classify) and 5 (Track before the first write)
+- Gentle-AI `docs/intended-usage.md` — "Small, understood changes need no persistent task artifact"
+
+## Proposal
+
+Add a **light lane** alongside the existing full SDD lane:
+
+1. New flag `aiw task start --lane=light` (full lane remains the default).
+2. Entry criteria, evaluated and recorded at start — all must hold:
+   - the change is understood well enough to resume from the request plus `git diff` (the ODD resume test, stated verbatim in the command output so the human makes the call);
+   - expected blast radius is contained (no new requirement IDs, no architecture decision needed);
+   - TDD applies or an exception is recorded with reason.
+3. Light-lane behavior:
+   - No durable spec/plan/report artifacts are scaffolded.
+   - Evidence is still required: task validation commands run and completion evidence is recorded in `.aiw/checkpoints/` (compact form, linked to the ticket if present).
+   - The lane decision and its entry criteria are persisted, so audits can see why the light lane was used.
+4. Escalation: if scope grows beyond the entry criteria (new requirement, ADR needed, risk found), the task must escalate to the full lane; the escalation is an explicit recorded event, never a silent expansion. Escalation preserves already-recorded evidence.
+
+## Affected areas
+
+- `src/workflow.ts`, `src/types.ts` (lane state, escalation event)
+- CLI: task/workflow commands (`src/cli.ts`)
+- Stage skills and templates rendered through adapters (resources that describe the SDD sequence)
+- `docs/README.md` (main README workflow section), `docs/architecture.md` (approval contract description)
+- Checkpoint/evidence recording (`src/evidence.ts`, `src/human-approval.ts` interactions)
+
+## Acceptance criteria
+
+- Given a task started with `--lane=light`, when no scope growth occurs, then completion requires no `specification.md`/`implementation-plan.md` artifacts and records validation evidence plus the lane rationale in checkpoints.
+- Given a light-lane task, when scope growth is detected (or declared), then escalation to the full lane is required before further stage commands run, and prior evidence is preserved and linked.
+- Given the full lane (default), when a task starts, then behavior is unchanged from today.
+- Given a light-lane completion, when `.aiw/approvals.yml` is inspected, then the ledger shows the light-lane rationale, not a missing approval.
+- Non-interactive runs without an explicit lane default to the full lane.
+
+## Non-goals
+
+- No global "workflow off" switch (see ADR-001 Decision B).
+- No change to full-lane stage order, gates, or approval semantics.
+- No automatic lane detection that overrides the human's classification; automation may only suggest.
+
+## Open questions
+
+- Should the light lane allow skipping the brainstorm/spec stages only, or also merge implementation + verification evidence into a single checkpoint artifact?
+- Should escalation be self-declared by the agent, human-confirmed, or both (recommend both: agent proposes, human confirms)?
+- Does the lane need representation in `traceability` output (e.g., a light-lane marker on the ticket)?