@multileaf/ai-workflow 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-10-30
+
+### Added
+
+- Typed blocking reasons with exact continuations (OPP-004): every workflow, gate, and approval blocking exit emits a stable reason code plus either an exact runnable `aiw` continuation or an explicit terminal statement. With `--json`, blocks return machine-readable `reason_code` and `next_command`/`next_action`/`terminal` fields. `docs/continuation-inventory.md` maps every code and is kept in parity with the registry by a CI test.
+- `aiw risk assess` (OPP-002): read-only, content-based risk classification for working-tree or `--base-ref` changes. Six high-risk categories (data/irreversible, security, consumed contracts, concurrency, delivery/environment, untested regression) classify by what changed, never by size: documentation-only diffs are `passive`; size never decides. Deterministic and offline by default; `--escalate-item 1-6 --escalate-reason` raises and never lowers a tier; `risk_due: yes` names an exact runnable next command (`aiw.risk-assessment/v1` JSON envelope).
+- Light lane (OPP-001): a human-chosen `aiw task start --lane=light --lane-reason=...` for small, understood work — the resume test decides (resumable from the request plus `git diff`). No durable spec/plan artifacts; validation evidence is recorded via `aiw task evidence` and completion requires at least one entry; the lane and rationale are written into the session and approval ledger for audit. Stage commands block with `lane_escalation_required`; `aiw task escalate --reason` moves the workflow to the full lane (one-way, evidence preserved). The full lane remains the default and unchanged.
+- Emission ≠ usability policy and command ratchet (OPP-006): messages naming an `aiw` command must have a test that executes it. A ratchet test executes every command named by the generated skills and READMEs and fails on unknown commands.
+- Friction benchmark (OPP-005): `scripts/friction-bench.mjs` drives packaged-CLI journeys and classifies every non-success exit as in-band / out-of-band / dead-end, executing printed continuations to verify they resolve. CI enforces a zero-dead-end budget; the release gate re-verifies budget and determinism. Baseline: in-band 5, out-of-band 5, dead-end 0.
+- Adversarial review skills (OPP-003): `review-judge-a`, `review-judge-b`, and `review-refuter` ship in the self-hosting package. Two blind judges review independently; severe findings require a reproducing command or self-proving `file:line` citations and otherwise degrade to advisory; only corroborated severe findings block. Refuter command execution is permission-gated (default: evidence reading with an explicit no-command-executed marker, isolated directory, no network). Human acceptance of the review outcome is unchanged.
+- Workflow proportionality documentation: [ADR-001](.context/adrs/ADR-001-odd-rdd-proportionality-scope.md) records the ODD/RDD analysis — six implemented opportunities plus advisory-only model-integration opportunities (OPP-007/008) deliberately deferred until field exposure.
+
+### Fixed
+
+- `aiw risk assess` no longer truncates paths of tracked-modified files (the porcelain fixed-width column was destroyed by line trimming) and no longer flags `.aiw/` managed state (for example `lock.yml`) as concurrency risk.
+- `aiw risk` without a subcommand now prints its own typed usage instead of the general command dump.
+
+## [0.9.1] - 2026-10-24
+
+### Fixed
+
+- Workflow capabilities are always recommended: the seven SDD capabilities (brainstorming, ticket-driven-development, requirements-specification, implementation-planning, technical-design, code-review, verification) are marked universal and are recommended for any project, including scans with no detected signals. Previously a project without languages, frameworks, package manager, tests, linter, or CI received zero recommendations; stack-dependent capabilities still require their evidence.
+
 ## [0.9.0] - 2026-10-21
 
 ## [0.8.0] - 2026-10-20

package/README.md

@@ -14,6 +14,7 @@ AI-assisted development often relies on implicit prompts, duplicated configurati
 - skills, rules, agents, hooks, and templates are versioned resources;
 - target-specific files are generated through adapters;
 - quality gates and checkpoints provide completion evidence;
+- ceremony scales with the consequence of the change — risk-based lanes instead of uniform ceremony;
 - context is filtered and loaded only when needed to reduce token usage;
 - package-declared sensitive capabilities are evaluated by policy boundaries.
 
@@ -114,7 +115,7 @@ flowchart TD
 
 ## The SDD workflow
 
-AI Workflow supports an end-to-end specification-driven development cycle:
+AI Workflow supports an end-to-end specification-driven development cycle. Ceremony is proportional: `aiw risk assess` classifies each change by content, and small, understood work may run in a human-chosen light lane (evidence entries instead of durable artifacts) while substantial work runs the staged sequence below. The current end-to-end flow, both lanes, and the CI enforcement layer are diagrammed in [Architecture — Current flow](docs/architecture.md#current-flow).
 
 ```mermaid
 flowchart TD
@@ -205,6 +206,16 @@ npx @multileaf/ai-workflow recommend --select=typescript-quality,verification
 # Track a feature from its first artifact through final human approval.
 npx @multileaf/ai-workflow workflow start
 
+# Small, understood change? The light lane skips durable spec/plan artifacts
+# (human-chosen via the resume test) and records validation evidence instead.
+npx @multileaf/ai-workflow task start --ticket=TEAM-7 --lane=light --lane-reason="small fix, resumable from request"
+npx @multileaf/ai-workflow task evidence --validation="npm test: passed"
+npx @multileaf/ai-workflow workflow complete
+# If scope grows: aiw task escalate --reason=...
+
+# Classify the risk of current changes (read-only; content, not size).
+npx @multileaf/ai-workflow risk assess [--base-ref=<ref>] [--escalate-item=1-6 --escalate-reason=text] [--json]
+
 # Or start directly from a ticket / already-clear requirement (no brainstorm needed).
 npx @multileaf/ai-workflow task start --ticket=PROJ-142 --title="Add export endpoint"
 npx @multileaf/ai-workflow task status

package/dist/blocking-reasons.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Typed reason codes and exact continuations for every blocking CLI exit.
+ *
+ * Contract (OPP-004, REQ-OPP-004): a blocking output must carry 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. See ADR-001 and
+ * docs/opportunities/OPP-004-exact-continuation-commands.md.
+ */
+export declare const BLOCKING_REASON_CODES: readonly ["gate_evidence_missing", "gate_incomplete", "stage_prerequisite_pending", "stage_prerequisite_unresolved", "stage_awaiting_approval", "stage_already_approved", "approval_evidence_missing", "approval_stale", "approval_gate_missing", "lane_escalation_required", "light_evidence_missing"];
+export type BlockingReasonCode = (typeof BLOCKING_REASON_CODES)[number];
+/** How the user or agent gets past a block. Exactly one of three kinds. */
+export type BlockingContinuation = 
+/** An exact runnable `aiw` command with every argument resolved. */
+{
+    kind: "command";
+    command: string;
+}
+/** A concrete non-command step (for example, authoring an artifact). */
+ | {
+    kind: "action";
+    description: string;
+}
+/** No in-line continuation exists; a human decision is required. */
+ | {
+    kind: "terminal";
+    humanDecision: string;
+};
+/** Resolved context used by continuation producers. */
+export type BlockingContext = {
+    stage?: string;
+    pendingStages?: string[];
+    unresolvedStages?: string[];
+    artifactPath?: string;
+    gateIssues?: string[];
+    /** Context-specific human message preferred over the generic definition text. */
+    detail?: string;
+};
+export type BlockingReasonDefinition = {
+    code: BlockingReasonCode;
+    description: string;
+    continuation: (context: BlockingContext) => BlockingContinuation;
+};
+export declare const BLOCKING_REASON_INVENTORY: Readonly<Record<BlockingReasonCode, BlockingReasonDefinition>>;
+export declare function getBlockingReasonDefinition(code: string): BlockingReasonDefinition;
+export type BlockingResult = {
+    code: BlockingReasonCode;
+    /** Explanation of the block without continuation instructions. */
+    message: string;
+    continuation: BlockingContinuation;
+};
+export declare function describeBlockingReason(code: BlockingReasonCode, context: BlockingContext): BlockingResult;
+/** Error thrown by blocking CLI paths; carries the typed result for `--json` output. */
+export declare class BlockingError extends Error {
+    readonly result: BlockingResult;
+    constructor(result: BlockingResult);
+}
+export declare function formatBlockingOutput(result: BlockingResult): string;
+export type BlockingJson = {
+    reason_code: BlockingReasonCode;
+    next_command?: string;
+    next_action?: string;
+    terminal?: boolean;
+};
+export declare function blockingResultToJson(result: BlockingResult): BlockingJson;
+/** Markdown continuation inventory for docs generation and CI parity checks. */
+export declare function exportContinuationInventoryMarkdown(): string;

package/dist/blocking-reasons.js

@@ -0,0 +1,181 @@
+/**
+ * Typed reason codes and exact continuations for every blocking CLI exit.
+ *
+ * Contract (OPP-004, REQ-OPP-004): a blocking output must carry 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. See ADR-001 and
+ * docs/opportunities/OPP-004-exact-continuation-commands.md.
+ */
+export const BLOCKING_REASON_CODES = [
+    "gate_evidence_missing",
+    "gate_incomplete",
+    "stage_prerequisite_pending",
+    "stage_prerequisite_unresolved",
+    "stage_awaiting_approval",
+    "stage_already_approved",
+    "approval_evidence_missing",
+    "approval_stale",
+    "approval_gate_missing",
+    "lane_escalation_required",
+    "light_evidence_missing",
+];
+function command(commandText) {
+    return { kind: "command", command: commandText };
+}
+function action(description) {
+    return { kind: "action", description };
+}
+function terminal(humanDecision) {
+    return { kind: "terminal", humanDecision };
+}
+function firstStage(stages) {
+    return stages && stages.length > 0 ? stages[0] : undefined;
+}
+export const BLOCKING_REASON_INVENTORY = {
+    gate_evidence_missing: {
+        code: "gate_evidence_missing",
+        description: "The quality gate is blocked because the required evidence artifact is missing.",
+        continuation: (context) => context.stage && context.artifactPath
+            ? action(`Create the required artifact at ${context.artifactPath}, then run \`aiw gate ${context.stage}\`.`)
+            : terminal("Decide which stage artifact to author before gating."),
+    },
+    gate_incomplete: {
+        code: "gate_incomplete",
+        description: "The quality gate found completeness issues in the stage artifact.",
+        continuation: (context) => context.stage
+            ? action(`Fix the gate findings in the stage artifact${context.artifactPath ? ` (${context.artifactPath})` : ""}, then run \`aiw gate ${context.stage}\` again.`)
+            : terminal("Fix the gate findings, then rerun the stage gate."),
+    },
+    stage_prerequisite_pending: {
+        code: "stage_prerequisite_pending",
+        description: "A previous stage is awaiting human approval before this stage can start.",
+        continuation: (context) => {
+            const pending = firstStage(context.pendingStages);
+            return pending
+                ? command(`aiw approve ${pending}`)
+                : terminal("Review the pending previous stage with a human.");
+        },
+    },
+    stage_prerequisite_unresolved: {
+        code: "stage_prerequisite_unresolved",
+        description: "Previous stages need human approval or an accepted optional skip before this stage can start.",
+        continuation: (context) => {
+            const unresolved = firstStage(context.unresolvedStages);
+            return unresolved
+                ? command(`aiw approve ${unresolved}`)
+                : terminal("Resolve the previous stages with a human before continuing.");
+        },
+    },
+    stage_awaiting_approval: {
+        code: "stage_awaiting_approval",
+        description: "This stage is awaiting human approval; approve or reject it before continuing.",
+        continuation: (context) => context.stage
+            ? command(`aiw approve ${context.stage}`)
+            : terminal("A human must approve or reject the pending stage."),
+    },
+    stage_already_approved: {
+        code: "stage_already_approved",
+        description: "This stage is already approved; changed evidence requires rerunning its quality gate.",
+        continuation: (context) => context.stage
+            ? command(`aiw gate ${context.stage}`)
+            : terminal("A human must decide whether to rerun the gate for the changed evidence."),
+    },
+    approval_evidence_missing: {
+        code: "approval_evidence_missing",
+        description: "Approval cannot be recorded because the stage evidence artifact is missing.",
+        continuation: (context) => context.stage && context.artifactPath
+            ? action(`Create the required artifact at ${context.artifactPath}, then run \`aiw approve ${context.stage}\`.`)
+            : terminal("Decide which stage artifact to author before approving."),
+    },
+    approval_stale: {
+        code: "approval_stale",
+        description: "The artifact changed after review; its approval is stale and the gate must run again.",
+        continuation: (context) => context.stage
+            ? command(`aiw gate ${context.stage}`)
+            : terminal("A human must decide whether to rerun the gate for the changed artifact."),
+    },
+    approval_gate_missing: {
+        code: "approval_gate_missing",
+        description: "No passing quality gate is recorded for this stage; gate it before approving.",
+        continuation: (context) => context.stage
+            ? command(`aiw gate ${context.stage}`)
+            : terminal("A human must decide whether to gate the stage before approving."),
+    },
+    lane_escalation_required: {
+        code: "lane_escalation_required",
+        description: "Light-lane workflows do not author stage artifacts; escalate to the full lane to continue.",
+        continuation: () => action("Run `aiw task escalate --reason=<why scope grew>` to move this workflow to the full lane; recorded light-lane evidence is preserved."),
+    },
+    light_evidence_missing: {
+        code: "light_evidence_missing",
+        description: "A light-lane workflow cannot complete without at least one recorded validation entry.",
+        continuation: () => action("Run `aiw task evidence --validation=<command and result>` at least once, then `aiw workflow complete`."),
+    },
+};
+export function getBlockingReasonDefinition(code) {
+    const definition = BLOCKING_REASON_INVENTORY[code];
+    if (!definition)
+        throw new Error(`Unknown blocking reason code: ${code}`);
+    return definition;
+}
+export function describeBlockingReason(code, context) {
+    const definition = getBlockingReasonDefinition(code);
+    return {
+        code,
+        message: context.detail ?? definition.description,
+        continuation: definition.continuation(context),
+    };
+}
+/** Error thrown by blocking CLI paths; carries the typed result for `--json` output. */
+export class BlockingError extends Error {
+    result;
+    constructor(result) {
+        super(formatBlockingOutput(result));
+        this.name = "BlockingError";
+        this.result = result;
+    }
+}
+export function formatBlockingOutput(result) {
+    const prefix = `${result.message} [reason: ${result.code}]`;
+    switch (result.continuation.kind) {
+        case "command":
+            return `${prefix} Next: run \`${result.continuation.command}\`.`;
+        case "action":
+            return `${prefix} Next: ${result.continuation.description}`;
+        case "terminal":
+            return `${prefix} Terminal: no automatic continuation. ${result.continuation.humanDecision}`;
+    }
+}
+export function blockingResultToJson(result) {
+    switch (result.continuation.kind) {
+        case "command":
+            return { reason_code: result.code, next_command: result.continuation.command };
+        case "action":
+            return { reason_code: result.code, next_action: result.continuation.description };
+        case "terminal":
+            return { reason_code: result.code, terminal: true };
+    }
+}
+const CONTINUATION_KIND_LABEL = {
+    command: "runnable command",
+    action: "explicit action",
+    terminal: "terminal (human decision)",
+};
+/** Markdown continuation inventory for docs generation and CI parity checks. */
+export function exportContinuationInventoryMarkdown() {
+    const rows = BLOCKING_REASON_CODES.map((code) => {
+        const definition = getBlockingReasonDefinition(code);
+        return `| \`${code}\` | ${definition.description} | ${CONTINUATION_KIND_LABEL[commandKind(code)]} |`;
+    });
+    return ["| Reason code | Description | Continuation |", "| --- | --- | --- |", ...rows].join("\n");
+}
+function commandKind(code) {
+    const sample = describeBlockingReason(code, {
+        stage: "specification",
+        pendingStages: ["brainstorming"],
+        unresolvedStages: ["brainstorming"],
+        artifactPath: ".aiw/generated/specs/specification.md",
+    });
+    return sample.continuation.kind;
+}

package/dist/command-evidence.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Emission ≠ usability enforcement (OPP-006, REQ-OPP-006).
+ *
+ * A test that verifies a message was emitted does not verify it is usable.
+ * Any user-facing artifact (docs, generated skills, blocking output) that
+ * names an `aiw` command must be covered by a test that proves the command
+ * is real — the source lesson: a shipped message named a command nobody had
+ * ever run, for months, with green coverage.
+ *
+ * This helper extracts `aiw ...` and `npx @multileaf/ai-workflow ...`
+ * invocations from artifact text so tests can execute them.
+ */
+export type CommandMention = {
+    /** Normalized invocation: command and subcommand words only, no flags. */
+    command: string;
+    /** Source label for diagnostics. */
+    source: string;
+};
+/** Extract normalized command mentions (command + optional subcommand, no flags). */
+export declare function extractAiwCommands(text: string, source?: string): CommandMention[];
+/**
+ * Informational mentions excluded from execution evidence. Every entry needs
+ * a justification; entries are exact normalized commands.
+ */
+export declare const INFORMATIONAL_ALLOWLIST: readonly {
+    command: string;
+    justification: string;
+}[];
+/** First token (the command word) used for recognition checks. */
+export declare function commandWord(mention: CommandMention): string;
+/** Signature of the general usage dump printed for unknown commands. */
+export declare const UNKNOWN_COMMAND_SIGNATURE = "aiw install [--target target] | workflow";

package/dist/command-evidence.js

@@ -0,0 +1,61 @@
+/**
+ * Emission ≠ usability enforcement (OPP-006, REQ-OPP-006).
+ *
+ * A test that verifies a message was emitted does not verify it is usable.
+ * Any user-facing artifact (docs, generated skills, blocking output) that
+ * names an `aiw` command must be covered by a test that proves the command
+ * is real — the source lesson: a shipped message named a command nobody had
+ * ever run, for months, with green coverage.
+ *
+ * This helper extracts `aiw ...` and `npx @multileaf/ai-workflow ...`
+ * invocations from artifact text so tests can execute them.
+ */
+const INVOCATION_PATTERN = /(^|`|\n)(?:aiw|npx @multileaf\/ai-workflow) ([a-z][a-z-]*)(?: ([a-z][a-z-]*))?/g;
+/** English words that must never be captured as a subcommand. */
+const STOP_WORDS = new Set([
+    "and",
+    "or",
+    "the",
+    "a",
+    "to",
+    "then",
+    "is",
+    "in",
+    "with",
+    "before",
+    "after",
+    "you",
+    "see",
+    "for",
+    "that",
+    "helps",
+    "tool",
+]);
+/** Extract normalized command mentions (command + optional subcommand, no flags). */
+export function extractAiwCommands(text, source = "text") {
+    const mentions = [];
+    for (const match of text.matchAll(INVOCATION_PATTERN)) {
+        const subcommand = match[3] && !STOP_WORDS.has(match[3]) ? match[3] : undefined;
+        const command = subcommand ? `${match[2]} ${subcommand}` : match[2];
+        if (!mentions.some((mention) => mention.command === command && mention.source === source)) {
+            mentions.push({ command, source });
+        }
+    }
+    return mentions;
+}
+/**
+ * Informational mentions excluded from execution evidence. Every entry needs
+ * a justification; entries are exact normalized commands.
+ */
+export const INFORMATIONAL_ALLOWLIST = [
+    {
+        command: "aiw install",
+        justification: "Executed by the install e2e suite; README form includes --target variants.",
+    },
+];
+/** First token (the command word) used for recognition checks. */
+export function commandWord(mention) {
+    return mention.command.split(" ")[0];
+}
+/** Signature of the general usage dump printed for unknown commands. */
+export const UNKNOWN_COMMAND_SIGNATURE = "aiw install [--target target] | workflow";

package/dist/human-approval.d.ts

@@ -13,6 +13,9 @@ export type ApprovalLedger = {
     schema: 1;
     workflowId: string;
     stages: Partial<Record<HumanApprovalStage, StageApprovalRecord>>;
+    /** Light-lane provenance so audits see the rationale instead of missing approvals. */
+    lane?: "light";
+    laneReason?: string;
 };
 export type WorkflowSession = {
     schema: 1;
@@ -22,13 +25,25 @@ export type WorkflowSession = {
     updatedAt: string;
     ticket?: string;
     title?: string;
+    /** Light lane marker; absent means the full lane (REQ-OPP-001). */
+    lane?: "light";
+    /** Recorded rationale for using the light lane (the resume-test call). */
+    laneReason?: string;
+    /** Presence means the workflow escalated to the full lane (effective lane: full). */
+    laneEscalatedAt?: string;
+    laneEscalationReason?: string;
 };
+/** The lane that currently governs stage commands: escalation moves light → full. */
+export declare function effectiveLane(session: WorkflowSession): "full" | "light";
 export declare function validateTaskTicket(ticket: string): void;
 export type ApprovalStageDefinition = {
     optional: boolean;
     requiresQualityGate: boolean;
 };
-export declare function createApprovalLedger(workflowId: string): ApprovalLedger;
+export declare function createApprovalLedger(workflowId: string, options?: {
+    lane?: "light";
+    laneReason?: string;
+}): ApprovalLedger;
 export declare function serializeWorkflowSession(session: WorkflowSession): string;
 export declare function parseWorkflowSession(content: string): WorkflowSession;
 export declare function stageDefinition(stage: HumanApprovalStage): ApprovalStageDefinition;

package/dist/human-approval.js

@@ -2,6 +2,10 @@ import { createHash } from "node:crypto";
 import { parseDocument, stringify } from "yaml";
 import { HUMAN_APPROVAL_STAGES } from "./types.js";
 export const APPROVAL_STAGES = HUMAN_APPROVAL_STAGES;
+/** The lane that currently governs stage commands: escalation moves light → full. */
+export function effectiveLane(session) {
+    return session.lane === "light" && !session.laneEscalatedAt ? "light" : "full";
+}
 export function validateTaskTicket(ticket) {
     if (!/^[A-Z][A-Z0-9_]*-\d+$/.test(ticket))
         throw new Error("Task ticket must match TEAM-123, for example PROJ-142.");
@@ -25,7 +29,7 @@ const APPROVAL_RECORD_KEYS = new Set([
     "reason",
     "updatedAt",
 ]);
-const LEDGER_KEYS = new Set(["schema", "workflowId", "stages"]);
+const LEDGER_KEYS = new Set(["schema", "workflowId", "stages", "lane", "laneReason"]);
 const SESSION_KEYS = new Set([
     "schema",
     "workflowId",
@@ -34,10 +38,23 @@ const SESSION_KEYS = new Set([
     "updatedAt",
     "ticket",
     "title",
+    "lane",
+    "laneReason",
+    "laneEscalatedAt",
+    "laneEscalationReason",
 ]);
-export function createApprovalLedger(workflowId) {
+export function createApprovalLedger(workflowId, options = {}) {
     assertWorkflowId(workflowId);
-    return { schema: 1, workflowId, stages: {} };
+    if (options.lane === "light" && !options.laneReason)
+        throw new Error("Light-lane ledgers require a recorded lane reason.");
+    return {
+        schema: 1,
+        workflowId,
+        stages: {},
+        ...(options.lane === "light" && options.laneReason
+            ? { lane: "light", laneReason: options.laneReason }
+            : {}),
+    };
 }
 export function serializeWorkflowSession(session) {
     validateWorkflowSession(session);
@@ -65,6 +82,20 @@ export function parseWorkflowSession(content) {
         throw new Error("Workflow session title must be a string.");
     if (typeof value.ticket === "string")
         validateTaskTicket(value.ticket);
+    const lane = value.lane === undefined ? undefined : value.lane;
+    if (lane !== undefined && lane !== "light")
+        throw new Error("Workflow session lane must be light when present.");
+    const laneReason = value.laneReason;
+    if (laneReason !== undefined && typeof laneReason !== "string")
+        throw new Error("Workflow session lane reason must be a string.");
+    if (lane === "light" && !laneReason)
+        throw new Error("Light-lane sessions require a lane reason.");
+    const laneEscalatedAt = value.laneEscalatedAt;
+    if (laneEscalatedAt !== undefined && typeof laneEscalatedAt !== "string")
+        throw new Error("Workflow session lane escalation timestamp must be a string.");
+    const laneEscalationReason = value.laneEscalationReason;
+    if (laneEscalationReason !== undefined && typeof laneEscalationReason !== "string")
+        throw new Error("Workflow session lane escalation reason must be a string.");
     const session = {
         schema: 1,
         workflowId: value.workflowId,
@@ -73,6 +104,10 @@ export function parseWorkflowSession(content) {
         updatedAt: value.updatedAt,
         ...(value.ticket === undefined ? {} : { ticket: value.ticket }),
         ...(value.title === undefined ? {} : { title: value.title }),
+        ...(lane === undefined ? {} : { lane }),
+        ...(laneReason === undefined ? {} : { laneReason }),
+        ...(laneEscalatedAt === undefined ? {} : { laneEscalatedAt }),
+        ...(laneEscalationReason === undefined ? {} : { laneEscalationReason }),
     };
     validateWorkflowSession(session);
     return session;
@@ -168,7 +203,14 @@ export function invalidateStageAndDescendants(ledger, stage, updatedAt) {
 export function serializeApprovalLedger(ledger) {
     validateLedger(ledger);
     const stages = Object.fromEntries(APPROVAL_STAGES.flatMap((stage) => ledger.stages[stage] ? [[stage, ledger.stages[stage]]] : []));
-    return stringify({ schema: 1, workflowId: ledger.workflowId, stages }, { lineWidth: 0 });
+    return stringify({
+        schema: 1,
+        workflowId: ledger.workflowId,
+        stages,
+        ...(ledger.lane === "light" && ledger.laneReason
+            ? { lane: ledger.lane, laneReason: ledger.laneReason }
+            : {}),
+    }, { lineWidth: 0 });
 }
 export function parseApprovalLedger(content) {
     const document = parseDocument(content, { uniqueKeys: true, strict: true });
@@ -191,7 +233,14 @@ export function parseApprovalLedger(content) {
             throw new Error(`Approval ledger has unknown workflow stage: ${stageName}.`);
         stages[stageName] = parseStageRecord(stageName, record);
     }
-    const ledger = { schema: 1, workflowId: value.workflowId, stages };
+    const ledger = {
+        schema: 1,
+        workflowId: value.workflowId,
+        stages,
+        ...(value.lane === "light" && typeof value.laneReason === "string"
+            ? { lane: "light", laneReason: value.laneReason }
+            : {}),
+    };
     validateLedger(ledger);
     return ledger;
 }
@@ -221,6 +270,17 @@ function validateWorkflowSession(session) {
         throw new Error("Workflow session status must be active or complete.");
     assertTimestamp(session.startedAt);
     assertTimestamp(session.updatedAt);
+    if (session.lane !== undefined && session.lane !== "light")
+        throw new Error("Workflow session lane must be light when present.");
+    if (session.lane === "light" && !session.laneReason)
+        throw new Error("Light-lane sessions require a lane reason.");
+    if (session.laneEscalatedAt !== undefined) {
+        assertTimestamp(session.laneEscalatedAt);
+        if (session.lane !== "light")
+            throw new Error("Lane escalation is only meaningful on light-lane sessions.");
+        if (!session.laneEscalationReason)
+            throw new Error("Lane escalation requires a reason.");
+    }
 }
 function withStage(ledger, stage, record) {
     return {
@@ -287,6 +347,10 @@ function validateLedger(ledger) {
     if (ledger.schema !== 1 || !isRecord(ledger.stages))
         throw new Error("Approval ledger schema must be version 1 with a stages mapping.");
     assertWorkflowId(ledger.workflowId);
+    if (ledger.lane !== undefined && ledger.lane !== "light")
+        throw new Error("Approval ledger lane must be light when present.");
+    if (ledger.lane === "light" && !ledger.laneReason)
+        throw new Error("Light-lane ledgers require a lane reason.");
     for (const [stage, record] of Object.entries(ledger.stages)) {
         if (!isApprovalStage(stage))
             throw new Error(`Approval ledger has unknown workflow stage: ${stage}.`);

package/dist/recommendations.js

@@ -3,6 +3,7 @@ const CATALOG = [
     {
         id: "brainstorming",
         provider: "multileaf",
+        universal: true,
         rationale: "A project-specific brainstorming flow helps clarify goals and constraints before implementation.",
         permissions: [],
         resources: local([
@@ -17,6 +18,7 @@ const CATALOG = [
     {
         id: "ticket-driven-development",
         provider: "multileaf",
+        universal: true,
         rationale: "Work often arrives as a ticket or an already-clear requirement; this entry point starts the SDD flow from the ticket without a brainstorming phase.",
         permissions: [],
         resources: local([
@@ -30,6 +32,7 @@ const CATALOG = [
     {
         id: "requirements-specification",
         provider: "multileaf",
+        universal: true,
         rationale: "The project can use explicit requirements and acceptance criteria before changes are planned.",
         permissions: [],
         resources: local([
@@ -44,6 +47,7 @@ const CATALOG = [
     {
         id: "implementation-planning",
         provider: "multileaf",
+        universal: true,
         rationale: "A traceable implementation plan can connect project requirements, tests, risks, and validation.",
         permissions: [],
         resources: local([
@@ -59,6 +63,7 @@ const CATALOG = [
     {
         id: "technical-design",
         provider: "multileaf",
+        universal: true,
         rationale: "Architecture changes benefit from explicit alternatives, trade-offs, and decision records.",
         permissions: [],
         resources: local([
@@ -74,6 +79,7 @@ const CATALOG = [
     {
         id: "code-review",
         provider: "multileaf",
+        universal: true,
         rationale: "A consistent review checklist helps validate changes against this repository's conventions.",
         permissions: [],
         resources: local([
@@ -164,6 +170,7 @@ const CATALOG = [
     {
         id: "verification",
         provider: "multileaf",
+        universal: true,
         rationale: "Verification guidance can use the project's detected test runner and quality commands.",
         permissions: [],
         resources: local([
@@ -241,7 +248,15 @@ const CATALOG = [
 ];
 export function recommendCapabilities(profile) {
     return CATALOG.flatMap((capability) => {
-        const match = capability.matches(profile);
+        const match = capability.matches(profile) ??
+            (capability.universal
+                ? {
+                    evidence: [
+                        "Workflow capability: applies to any project, with or without detected signals.",
+                    ],
+                    confidence: 0.9,
+                }
+                : undefined);
         return match
             ? [
                 {