@multileaf/ai-workflow 0.8.0 → 0.10.0

package/dist/hook-installer.d.ts

@@ -0,0 +1,30 @@
+import type { FileSystem } from "./types.js";
+/**
+ * Claude Code hook installer: wires harness events to `aiw heartbeat`
+ * without a scheduler. Project-scoped: writes `.claude/settings.json` in
+ * the repository, never the user's global settings.
+ *
+ * Merge policy: existing hooks the project already declares are preserved
+ * untouched; AIW only appends its own entries, identified by the
+ * `aiw heartbeat` command, and skips them when already present
+ * (idempotent). Any JSON that is not a settings object is a hard conflict.
+ */
+export declare const CLAUDE_HOOK_COMMAND = "npx --yes --package=@multileaf/ai-workflow -- aiw heartbeat";
+export type ClaudeHookEntry = {
+    hooks: {
+        type: string;
+        command: string;
+        timeout?: number;
+    }[];
+};
+export type ClaudeSettings = {
+    hooks?: Record<string, ClaudeHookEntry[]>;
+} & Record<string, unknown>;
+export declare const AIW_HEARTBEAT_EVENTS: readonly ["Stop", "UserPromptSubmit"];
+export declare function parseClaudeSettings(content: string): ClaudeSettings;
+export declare function installHeartbeatHooks(settings: ClaudeSettings): {
+    settings: ClaudeSettings;
+    added: string[];
+    alreadyPresent: string[];
+};
+export declare function writeClaudeSettings(fs: FileSystem, path: string, settings: ClaudeSettings): void;

package/dist/hook-installer.js

@@ -0,0 +1,52 @@
+/**
+ * Claude Code hook installer: wires harness events to `aiw heartbeat`
+ * without a scheduler. Project-scoped: writes `.claude/settings.json` in
+ * the repository, never the user's global settings.
+ *
+ * Merge policy: existing hooks the project already declares are preserved
+ * untouched; AIW only appends its own entries, identified by the
+ * `aiw heartbeat` command, and skips them when already present
+ * (idempotent). Any JSON that is not a settings object is a hard conflict.
+ */
+export const CLAUDE_HOOK_COMMAND = "npx --yes --package=@multileaf/ai-workflow -- aiw heartbeat";
+export const AIW_HEARTBEAT_EVENTS = ["Stop", "UserPromptSubmit"];
+export function parseClaudeSettings(content) {
+    if (!content.trim())
+        return {};
+    const parsed = JSON.parse(content);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error(".claude/settings.json must be a JSON object.");
+    const settings = parsed;
+    if (settings.hooks !== undefined) {
+        if (typeof settings.hooks !== "object" ||
+            settings.hooks === null ||
+            Array.isArray(settings.hooks))
+            throw new Error(".claude/settings.json hooks must be an object keyed by event name.");
+        for (const [event, entries] of Object.entries(settings.hooks))
+            if (!Array.isArray(entries))
+                throw new Error(`.claude/settings.json hooks.${event} must be a list.`);
+    }
+    return settings;
+}
+export function installHeartbeatHooks(settings) {
+    const hooks = { ...(settings.hooks ?? {}) };
+    const added = [];
+    const alreadyPresent = [];
+    for (const event of AIW_HEARTBEAT_EVENTS) {
+        const entries = hooks[event] ? [...hooks[event]] : [];
+        const exists = entries.some((entry) => entry.hooks?.some((hook) => hook.command === CLAUDE_HOOK_COMMAND));
+        if (exists)
+            alreadyPresent.push(event);
+        else {
+            entries.push({
+                hooks: [{ type: "command", command: CLAUDE_HOOK_COMMAND, timeout: 15 }],
+            });
+            added.push(event);
+        }
+        hooks[event] = entries;
+    }
+    return { settings: { ...settings, hooks }, added, alreadyPresent };
+}
+export function writeClaudeSettings(fs, path, settings) {
+    fs.write(path, `${JSON.stringify(settings, null, 2)}\n`);
+}

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
             ? [
                 {

package/dist/risk-assess.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Deterministic, content-based risk classification for changed paths (OPP-002,
+ * REQ-OPP-002). Risk is classified by WHAT changed, never by how much: a
+ * documentation-only diff is passive; two lines of authentication code are
+ * high. Rules are path-based approximations, deliberately biased toward
+ * `high` — a failed or uncertain assessment never implies low risk.
+ *
+ * The six high-risk items follow the escalation list of the source concept
+ * (RDD `review assess`): 1 data/irreversible effects, 2 security,
+ * 3 contracts others consume, 4 concurrency, 5 delivery/environment,
+ * 6 no test would catch a regression.
+ */
+import type { CommandResult, FileSystem } from "./types.js";
+export type RiskTier = "passive" | "medium" | "high";
+export type RiskCategoryCode = "data_irreversible" | "security" | "consumed_contract" | "concurrency" | "delivery_environment" | "untested_regression";
+export type RiskReason = {
+    code: RiskCategoryCode | "agent_escalation";
+    path?: string;
+    detail?: string;
+};
+export type ChangedFile = {
+    path: string;
+};
+export type RiskCategory = {
+    item: 1 | 2 | 3 | 4 | 5 | 6;
+    code: RiskCategoryCode;
+    description: string;
+};
+export declare const RISK_CATEGORIES: readonly RiskCategory[];
+export type AssessOptions = {
+    /**
+     * Predicate telling whether a changed source file has a covering test.
+     * When absent, the untested_regression category is not asserted
+     * (unknown is not low; the tier then rests on the other categories).
+     */
+    hasCoveringTest?: (path: string) => boolean;
+};
+export type RiskAssessment = {
+    tier: RiskTier;
+    reasons: RiskReason[];
+    changedPaths: string[];
+};
+export declare function assessRisk(changes: readonly ChangedFile[], options?: AssessOptions): RiskAssessment;
+export declare function runRiskAssess(args: string[], root: string, fs: FileSystem): Promise<CommandResult>;
+/**
+ * Agent escalation (RDD parity): an agent may raise — never lower — the tier
+ * citing one of the six high-risk items. Item must be 1..6; the reason is a
+ * non-empty single line of at most 500 bytes.
+ */
+export declare function applyEscalation(assessment: RiskAssessment, item: number, reason: string): RiskAssessment;

package/dist/risk-assess.js

@@ -0,0 +1,273 @@
+/**
+ * Deterministic, content-based risk classification for changed paths (OPP-002,
+ * REQ-OPP-002). Risk is classified by WHAT changed, never by how much: a
+ * documentation-only diff is passive; two lines of authentication code are
+ * high. Rules are path-based approximations, deliberately biased toward
+ * `high` — a failed or uncertain assessment never implies low risk.
+ *
+ * The six high-risk items follow the escalation list of the source concept
+ * (RDD `review assess`): 1 data/irreversible effects, 2 security,
+ * 3 contracts others consume, 4 concurrency, 5 delivery/environment,
+ * 6 no test would catch a regression.
+ */
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+export const RISK_CATEGORIES = [
+    {
+        item: 1,
+        code: "data_irreversible",
+        description: "Data or irreversible effects: migrations, schema, destructive data operations.",
+    },
+    {
+        item: 2,
+        code: "security",
+        description: "Security: authentication, authorization, credentials, secrets, cryptography, sessions, permissions.",
+    },
+    {
+        item: 3,
+        code: "consumed_contract",
+        description: "Contracts others consume: package manifests, public type declarations, API schemas.",
+    },
+    {
+        item: 4,
+        code: "concurrency",
+        description: "Concurrency: workers, pools, locks, queues, and other shared-state primitives.",
+    },
+    {
+        item: 5,
+        code: "delivery_environment",
+        description: "Delivery or environment: CI pipelines, containers, deployment, release and install scripts.",
+    },
+    {
+        item: 6,
+        code: "untested_regression",
+        description: "No test would catch a regression: changed source with no covering test detected.",
+    },
+];
+/**
+ * Path rules are intentionally broad: over-flagging costs one review, while
+ * under-flagging ships unreviewed risk. Test files are excluded before
+ * matching so test-only changes stay out of the high categories.
+ */
+const CATEGORY_RULES = [
+    {
+        code: "data_irreversible",
+        pattern: /(^|\/)(migrations?|db\/migrate)\//i,
+    },
+    { code: "data_irreversible", pattern: /migration|schema\.prisma$/i },
+    {
+        code: "security",
+        pattern: /(^|\/)(auth|login|credential|secret|token|password|session|permission|acl)\b|(^|\/)(crypto|ssl|tls|jwt)|\bsecurity\b|\.env/i,
+    },
+    {
+        code: "consumed_contract",
+        pattern: /(^|\/)(package|pyproject|cargo|go)\.(json|toml)$|\.d\.ts$|(^|\/)(api|openapi|swagger)(\/|$)|\.graphql$|\.proto$/i,
+    },
+    {
+        code: "concurrency",
+        pattern: /worker|pool|lock|queue|mutex|atomic|parallel|thread|scheduler/i,
+    },
+    {
+        code: "delivery_environment",
+        pattern: /(^|\/)\.github\/workflows\/|dockerfile|docker-compose|jenkinsfile|gitlab-ci|(^|\/)(ci|deploy|helm|k8s|terraform)(\/|\.|$)|(^|\/)scripts\/(release|install|deploy)|(^|\/)release-|\.npmrc$|^makefile$/i,
+    },
+];
+/** Documentation is passive by its own nature (path approximation). */
+const PASSIVE_PATTERN = /\.(md|rst|adoc|txt)|(^|\/)(docs?|documentation)(\/|$)|(^|\/)(license|licence|changelog|notice|authors|contributors)(\.|$)/i;
+const TEST_FILE_PATTERN = /\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs)$|(^|\/)(__tests__|tests?|e2e)(\/|$)/i;
+const SOURCE_FILE_PATTERN = /\.(ts|tsx|js|jsx|mjs|cjs|py|rb|go|rs|java|sql|sh)$/i;
+/**
+ * Workflow-managed state (`.aiw/`) is never authored source: excluding it
+ * keeps `aiw`'s own lockfiles, checkpoints, and generated artifacts out of
+ * the risk picture (a real-flow defect: `.aiw/lock.yml` matched "lock").
+ */
+const WORKFLOW_STATE_PATTERN = /(^|\/)\.aiw\//;
+export function assessRisk(changes, options = {}) {
+    const reasons = [];
+    let anyCode = false;
+    const isTestCovered = options.hasCoveringTest;
+    for (const change of changes) {
+        if (WORKFLOW_STATE_PATTERN.test(change.path))
+            continue;
+        const isPassive = PASSIVE_PATTERN.test(change.path);
+        const isTest = TEST_FILE_PATTERN.test(change.path);
+        if (!isPassive)
+            anyCode = true;
+        // Passive documentation never ships executable risk; test files are
+        // evidence, not surface. Neither triggers the high-risk categories.
+        if (isPassive || isTest)
+            continue;
+        for (const rule of CATEGORY_RULES) {
+            if (rule.pattern.test(change.path))
+                reasons.push({ code: rule.code, path: change.path });
+        }
+        if (isTestCovered && SOURCE_FILE_PATTERN.test(change.path) && !isTestCovered(change.path)) {
+            reasons.push({ code: "untested_regression", path: change.path });
+        }
+    }
+    const tier = reasons.length > 0 ? "high" : anyCode ? "medium" : "passive";
+    return { tier, reasons, changedPaths: changes.map((change) => change.path) };
+}
+const CATEGORY_BY_ITEM = new Map(RISK_CATEGORIES.map((category) => [category.item, category]));
+const RISK_ASSESS_SCHEMA = "aiw.risk-assessment/v1";
+const RISK_ASSESS_USAGE = "Usage: aiw risk assess [--base-ref=ref] [--ticket=ID] [--escalate-item=1-6 --escalate-reason=text] [--json]";
+/** Raw git output lines: no per-line trimming — porcelain columns are fixed-width. */
+function gitRawLines(root, args) {
+    try {
+        const output = execFileSync("git", args, {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return output
+            .split("\n")
+            .map((line) => line.replace(/\r$/, ""))
+            .filter((line) => line.length > 0);
+    }
+    catch {
+        return undefined;
+    }
+}
+function gitLines(root, args) {
+    return gitRawLines(root, args)?.map((line) => line.trim());
+}
+/** Working-tree changes from `git status --porcelain` (staged, unstaged, untracked). */
+function workingTreeChanges(root) {
+    const lines = gitRawLines(root, ["status", "--porcelain", "--untracked-files=all"]);
+    if (!lines)
+        return undefined;
+    return lines.map((line) => {
+        const path = line.slice(3).trim();
+        const renameArrow = path.indexOf(" -> ");
+        return renameArrow === -1 ? path : path.slice(renameArrow + 4);
+    });
+}
+function committedRangeChanges(root, baseRef) {
+    return gitLines(root, ["diff", "--name-only", `${baseRef}...HEAD`]);
+}
+/** Deterministic covering-test probe: sibling *.test.* / *.spec.* variants. */
+function hasCoveringTest(root, fs) {
+    return (path) => {
+        const directory = path.slice(0, path.lastIndexOf("/"));
+        const base = path.slice(path.lastIndexOf("/") + 1);
+        const dot = base.lastIndexOf(".");
+        const stem = dot === -1 ? base : base.slice(0, dot);
+        const extension = dot === -1 ? "" : base.slice(dot);
+        const candidates = [`${stem}.test${extension}`, `${stem}.spec${extension}`].map((name) => join(root, directory, name));
+        return candidates.some((candidate) => fs.exists(candidate));
+    };
+}
+function parseRiskAssessArgs(rest) {
+    const parsed = {};
+    for (const argument of rest) {
+        const match = argument.match(/^--([a-z-]+)=(.*)$/);
+        if (!match)
+            return undefined;
+        const [, name, value] = match;
+        if (name === "base-ref")
+            parsed.baseRef = value;
+        else if (name === "ticket")
+            parsed.ticket = value;
+        else if (name === "escalate-item") {
+            if (!/^\d+$/.test(value))
+                return undefined;
+            parsed.escalateItem = Number(value);
+        }
+        else if (name === "escalate-reason")
+            parsed.escalateReason = value;
+        else
+            return undefined;
+    }
+    if ((parsed.escalateItem === undefined) !== (parsed.escalateReason === undefined) ||
+        (parsed.ticket !== undefined && parsed.ticket.length === 0))
+        return undefined;
+    return parsed;
+}
+export async function runRiskAssess(args, root, fs) {
+    const jsonRequested = args.includes("--json");
+    const parsed = parseRiskAssessArgs(args.filter((argument) => argument !== "--json"));
+    if (!parsed)
+        return { exitCode: 1, error: RISK_ASSESS_USAGE };
+    const insideWorkTree = gitLines(root, ["rev-parse", "--is-inside-work-tree"]);
+    if (!insideWorkTree || insideWorkTree[0] !== "true")
+        return {
+            exitCode: 1,
+            error: "risk assess requires a git repository; run it inside one or pass --base-ref for a committed range.",
+        };
+    const changedPaths = parsed.baseRef
+        ? committedRangeChanges(root, parsed.baseRef)
+        : workingTreeChanges(root);
+    if (!changedPaths)
+        return {
+            exitCode: 1,
+            error: `git failed to enumerate changes${parsed.baseRef ? ` for --base-ref=${parsed.baseRef}` : ""}; verify the reference exists.`,
+        };
+    let assessment = assessRisk(changedPaths.map((path) => ({ path })), { hasCoveringTest: hasCoveringTest(root, fs) });
+    if (parsed.escalateItem !== undefined && parsed.escalateReason !== undefined) {
+        try {
+            assessment = applyEscalation(assessment, parsed.escalateItem, parsed.escalateReason);
+        }
+        catch (error) {
+            return { exitCode: 1, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    const riskDue = assessment.tier === "high";
+    const activeWorkflow = fs.exists(join(root, ".aiw", "workflow.yml"));
+    const nextCommand = riskDue && !activeWorkflow ? "aiw workflow start" : undefined;
+    const nextAction = riskDue && activeWorkflow
+        ? "Continue the active workflow: gate and approve the stages this change touches."
+        : undefined;
+    if (jsonRequested) {
+        const envelope = {
+            schema: RISK_ASSESS_SCHEMA,
+            risk: assessment.tier,
+            reasons: assessment.reasons,
+            changed_paths: assessment.changedPaths.length,
+            risk_due: riskDue,
+        };
+        if (parsed.ticket)
+            envelope.ticket = parsed.ticket;
+        if (nextCommand)
+            envelope.next_command = nextCommand;
+        if (nextAction)
+            envelope.next_action = nextAction;
+        return { exitCode: 0, output: JSON.stringify(envelope, null, 2) };
+    }
+    const lines = [`risk: ${assessment.tier}`];
+    for (const reason of assessment.reasons)
+        lines.push(`  - ${reason.code}${reason.path ? `: ${reason.path}` : reason.detail ? ` (${reason.detail})` : ""}`);
+    const next = nextCommand
+        ? `risk due: yes -> ${nextCommand}`
+        : nextAction
+            ? `risk due: yes -> ${nextAction}`
+            : "risk due: no";
+    lines.push(next);
+    return { exitCode: 0, output: lines.join("\n") };
+}
+/**
+ * Agent escalation (RDD parity): an agent may raise — never lower — the tier
+ * citing one of the six high-risk items. Item must be 1..6; the reason is a
+ * non-empty single line of at most 500 bytes.
+ */
+export function applyEscalation(assessment, item, reason) {
+    if (!Number.isInteger(item) || item < 1 || item > 6)
+        throw new Error("Escalation item must be an integer from 1 to 6.");
+    if (reason.length === 0)
+        throw new Error("Escalation reason must not be empty.");
+    if (reason.length > 500)
+        throw new Error("Escalation reason must be at most 500 bytes on one line.");
+    if (/[\r\n]/.test(reason))
+        throw new Error("Escalation reason must be a single line.");
+    const category = CATEGORY_BY_ITEM.get(item);
+    if (!category)
+        throw new Error("Escalation item must be an integer from 1 to 6.");
+    const escalation = {
+        code: "agent_escalation",
+        detail: `item ${item}: ${category.code} — ${reason}`,
+    };
+    return {
+        ...assessment,
+        tier: "high",
+        reasons: [...assessment.reasons, escalation],
+    };
+}