@multileaf/ai-workflow 0.8.0 → 0.10.0

package/dist/workflow.js

@@ -1,4 +1,5 @@
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { BASE_DIRECTORIES, WORKFLOW_DIRECTORY } from "./constants.js";
 import { detectTarget, isTarget, renderAiInit, describeResource, renderAiInitPath, renderResourcePath, } from "./adapter.js";
@@ -13,6 +14,20 @@ import { recommendCapabilities, rankRecommendations, resourcesForCapabilities, s
 import { selectRecommendations } from "./selection.js";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
+async function readStdin() {
+    const terminal = createInterface({ input: stdin });
+    try {
+        return await new Promise((resolve, reject) => {
+            let data = "";
+            stdin.on("data", (chunk) => (data += chunk));
+            stdin.on("end", () => resolve(data));
+            stdin.on("error", reject);
+        });
+    }
+    finally {
+        terminal.close();
+    }
+}
 import { generateProjectResources } from "./generator.js";
 import { detectDrift } from "./drift.js";
 import { parseManifest, serializeManifest } from "./manifest.js";
@@ -35,17 +50,23 @@ 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";
 import { appendUsageSidecarEntry, parseUsageSidecar, serializeUsageSidecar, serializeUsageSidecarSummary, summarizeUsageSidecar, USAGE_SIDECAR_PATH, USAGE_TIERS, } from "./usage-sidecar.js";
+import { mergeImportedEvents, parseClaudeCodeTranscript, parseCodexSession, parseGeminiTranscript, parsePiSession, summarizeImport, } from "./usage-import.js";
+import { describeHeartbeatOutcome, emptyHeartbeatState, HEARTBEAT_STATE_PATH, HEARTBEAT_TTL_SECONDS, HEARTBEAT_WARN_SECONDS, parseHeartbeatState, recordBeat, serializeHeartbeatCheckpoint, serializeHeartbeatState, validateHeartbeatThresholds, } from "./heartbeat.js";
+import { installHeartbeatHooks, parseClaudeSettings, writeClaudeSettings, } from "./hook-installer.js";
 import { computeCostAttribution, serializeCostAttribution, serializeTaskUsage, summarizeTaskUsage, } from "./cost-attribution.js";
 import { defaultRoutingTable, parseRoutingTable, resolveRoute, ROUTING_TABLE_PATH, serializeResolvedRoute, serializeRoutingTable, } from "./model-routing.js";
 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";
@@ -92,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}.` };
@@ -106,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);
@@ -122,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 {
@@ -143,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)`}.`);
@@ -181,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)
@@ -204,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,
@@ -223,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,
@@ -244,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());
@@ -1731,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." };
@@ -1744,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, {
@@ -2156,6 +2343,100 @@ export async function runCommand(args, root, fs, services = {}) {
                     "\nSources: .aiw/checkpoints/usage-sidecar.yml + .aiw/generated/artifacts/traceability.yml (verified = linked evidence present).",
             };
         }
+        if (command === "heartbeat") {
+            if (!fs.exists(join(aiw, "manifest.yml")))
+                return { exitCode: 1, error: "Run `aiw install` first." };
+            const parsed = parseNamedOptions(args.slice(1), ["session", "warn", "ttl"]);
+            if (!parsed)
+                return {
+                    exitCode: 1,
+                    error: "Usage: aiw heartbeat --session=id [--warn=seconds] [--ttl=seconds]",
+                };
+            const warnSeconds = parsed.warn === undefined ? HEARTBEAT_WARN_SECONDS : Number(parsed.warn);
+            const ttlSeconds = parsed.ttl === undefined ? HEARTBEAT_TTL_SECONDS : Number(parsed.ttl);
+            try {
+                validateHeartbeatThresholds(warnSeconds, ttlSeconds);
+            }
+            catch (error) {
+                return { exitCode: 1, error: error.message };
+            }
+            let session = parsed.session;
+            if (!session && !stdin.isTTY) {
+                // Claude Code hooks deliver a JSON payload with session_id on stdin.
+                try {
+                    const payload = JSON.parse(await readStdin());
+                    if (payload &&
+                        typeof payload === "object" &&
+                        typeof payload.session_id === "string")
+                        session = payload.session_id;
+                }
+                catch {
+                    // No parseable payload: fall through to the explicit error below.
+                }
+            }
+            if (!session)
+                return {
+                    exitCode: 1,
+                    error: "A session id is required: pass --session=id or pipe a harness hook JSON payload on stdin.",
+                };
+            const statePath = join(aiw, HEARTBEAT_STATE_PATH);
+            const state = fs.exists(statePath)
+                ? parseHeartbeatState(fs.read(statePath))
+                : emptyHeartbeatState();
+            const { state: nextState, outcome } = recordBeat(state, session, new Date(), warnSeconds, ttlSeconds);
+            fs.write(statePath, serializeHeartbeatState(nextState));
+            const lines = [describeHeartbeatOutcome(outcome)];
+            if (outcome.checkpoint) {
+                const checkpointPath = join(aiw, `checkpoints/heartbeat-${session}-${outcome.checkpoint.index}.yml`);
+                fs.write(checkpointPath, serializeHeartbeatCheckpoint(outcome.checkpoint, outcome.gapSeconds ?? 0, ttlSeconds));
+                lines.push(`checkpoint: ${relative(root, checkpointPath).split(sep).join("/")}`);
+            }
+            return { exitCode: 0, output: lines.join("\n") };
+        }
+        if (command === "hooks") {
+            if (!fs.exists(join(aiw, "manifest.yml")))
+                return { exitCode: 1, error: "Run `aiw install` first." };
+            const action = args[1];
+            if (action !== "install")
+                return {
+                    exitCode: 1,
+                    error: "Usage: aiw hooks install --target=claude-code (codex and gemini adapters follow the same command)",
+                };
+            const parsed = parseNamedOptions(args.slice(2), ["target"]);
+            if (!parsed?.target)
+                return { exitCode: 1, error: "Usage: aiw hooks install --target=claude-code" };
+            if (parsed.target !== "claude-code")
+                return {
+                    exitCode: 1,
+                    error: `Harness hook adapter not available yet for: ${parsed.target}. Claude Code is wired; codex and gemini follow the same pattern.`,
+                };
+            const settingsPath = join(root, ".claude/settings.json");
+            let settings;
+            try {
+                settings = parseClaudeSettings(fs.exists(settingsPath) ? fs.read(settingsPath) : "");
+            }
+            catch (error) {
+                return {
+                    exitCode: 1,
+                    error: `Existing .claude/settings.json is not a valid hooks file; fix or move it first: ${error.message}`,
+                };
+            }
+            const result = installHeartbeatHooks(settings);
+            if (fs.pathType?.(settingsPath) === "symlink")
+                return {
+                    exitCode: 1,
+                    error: ".claude/settings.json is a symbolic link; install hooks manually.",
+                };
+            writeClaudeSettings(fs, settingsPath, result.settings);
+            return {
+                exitCode: 0,
+                output: `Heartbeat hooks installed into .claude/settings.json (project-scoped):\n` +
+                    [...result.added, ...result.alreadyPresent]
+                        .map((event) => `- ${event}: ${result.added.includes(event) ? "added" : "already present"} → aiw heartbeat on every event`)
+                        .join("\n") +
+                    "\nSessions now record beats; idle gaps inside the warn window save a compact checkpoint while the cache is still warm.",
+            };
+        }
         if (command === "usage-sidecar") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
@@ -2172,6 +2453,109 @@ export async function runCommand(args, root, fs, services = {}) {
                             : ""),
                 };
             }
+            if (action === "import") {
+                const parsed = parseNamedOptions(args.slice(2), ["from", "path"]);
+                const source = parsed?.from;
+                if (!parsed || !source || !["claude-code", "codex", "gemini", "pi"].includes(source))
+                    return {
+                        exitCode: 1,
+                        error: "Usage: aiw usage-sidecar import --from=claude-code|codex|gemini|pi [--path=logs-directory]",
+                    };
+                if (!fs.list)
+                    return { exitCode: 1, error: "The filesystem cannot enumerate harness logs." };
+                const home = homedir();
+                const defaultRoot = source === "claude-code"
+                    ? join(home, ".claude/projects", root.split("/").join("-"))
+                    : source === "codex"
+                        ? join(home, ".codex/sessions")
+                        : source === "pi"
+                            ? join(home, ".pi/agent/sessions")
+                            : join(home, ".gemini/antigravity-cli/brain");
+                const scanRoot = parsed.path ? resolve(parsed.path) : defaultRoot;
+                if (fs.pathType?.(scanRoot) !== "directory")
+                    return {
+                        exitCode: 1,
+                        error: `Harness log directory not found: ${scanRoot}. Pass --path to point at the ${source} logs.`,
+                    };
+                const wanted = (name) => source === "claude-code"
+                    ? name.endsWith(".jsonl")
+                    : source === "codex"
+                        ? /^rollout-.*\.jsonl$/.test(name)
+                        : name === "transcript_full.jsonl";
+                const files = [];
+                const listDirectory = fs.list;
+                if (source === "pi") {
+                    // Pi groups sessions into directories named after the project path.
+                    const munged = root.split("/").join("-");
+                    for (const name of listDirectory(scanRoot) ?? []) {
+                        if (!name.includes(munged))
+                            continue;
+                        const directory = join(scanRoot, name);
+                        if (fs.pathType?.(directory) !== "directory")
+                            continue;
+                        for (const file of listDirectory(directory) ?? [])
+                            if (file.endsWith(".jsonl") && fs.pathType?.(join(directory, file)) === "file")
+                                files.push(join(directory, file));
+                    }
+                }
+                else {
+                    const walk = (directory, depth) => {
+                        if (depth > 6)
+                            return;
+                        for (const name of listDirectory(directory) ?? []) {
+                            const absolute = join(directory, name);
+                            const type = fs.pathType?.(absolute);
+                            if (type === "directory")
+                                walk(absolute, depth + 1);
+                            else if (type === "file" && wanted(name))
+                                files.push(absolute);
+                        }
+                    };
+                    walk(scanRoot, 0);
+                }
+                files.sort();
+                const events = [];
+                for (const file of files) {
+                    const content = fs.read(file);
+                    if (source === "claude-code")
+                        events.push(...parseClaudeCodeTranscript(content));
+                    else if (source === "codex") {
+                        const parsedEvents = parseCodexSession(content, root);
+                        if (parsedEvents)
+                            events.push(...parsedEvents);
+                    }
+                    else if (source === "pi")
+                        events.push(...parsePiSession(content));
+                    else
+                        events.push(...parseGeminiTranscript(content));
+                }
+                let ledger;
+                try {
+                    ledger = fs.exists(sidecarPath) ? parseUsageSidecar(fs.read(sidecarPath)) : [];
+                }
+                catch (error) {
+                    throw new Error(`Usage sidecar is unreadable: ${error.message}`, {
+                        cause: error,
+                    });
+                }
+                const merged = mergeImportedEvents(ledger, events);
+                fs.write(sidecarPath, serializeUsageSidecar(merged.ledger));
+                const result = {
+                    source,
+                    files: files.length,
+                    events: events.length,
+                    imported: merged.imported,
+                    skipped: merged.skipped,
+                };
+                return {
+                    exitCode: 0,
+                    output: summarizeImport(result) +
+                        (source === "gemini"
+                            ? "\nnote: Gemini transcripts do not record a working directory, so imports cannot be scoped to this project."
+                            : "") +
+                        `\nLedger: .aiw/${USAGE_SIDECAR_PATH} (rerun safely: already-imported events are skipped).`,
+                };
+            }
             if (action === "record") {
                 const recordArgs = args.slice(2).filter((arg) => arg !== "--estimated");
                 if (recordArgs.some((arg) => arg !== "--estimated" && !arg.startsWith("--")))
@@ -2304,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) };
     }
 }
@@ -2346,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.