intentdna 1.5.16 → 1.5.18

package/dist/hooks/cli.js

@@ -14,13 +14,15 @@
  *
  * Fail-open: all errors → { continue: true, suppressOutput: true }
  */
-import { readFile, stat } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { readFile, realpath, stat } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { readStdin, writeOutput, silentOutput, allowOutput, blockOutput } from "./protocol.js";
 import { validateHookInput } from "./schema.js";
 import { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, extractBashWritePaths, checkReflectionLimit, checkContextReadiness, checkWorkflowBoundary, } from "./enforce.js";
-import { appendAudit, readWorkflowState, appendTrace, rotateTraces, readTraces, cleanStaleState, readSurgeonAttempts, writeSurgeonAttempts, appendSessionRead, readSessionReads } from "./state.js";
+import { appendAudit, readWorkflowState, appendTrace, rotateTraces, readTraces, cleanStaleState, readSurgeonAttempts, writeSurgeonAttempts, appendSessionRead, readSessionReads, appendVerifierResult } from "./state.js";
+import { writeAuditEvent } from "../audit/index.js";
 // ── Constants ──────────────────────────────────────────────
 const DEFAULT_IR_PATH = ".dna/compiled/ir.json";
 const VALID_EVENTS = new Set([
@@ -104,7 +106,7 @@ async function main() {
     const state = {};
     let wfStateRaw = null;
     // Load workflow state for events that need it (handoff context + PreCompact preservation)
-    if (event === "PreToolUse" || event === "PreCompact") {
+    if (event === "PreToolUse" || event === "PostToolUse" || event === "PreCompact") {
         wfStateRaw = await readWorkflowState(projectDir, sessionId);
         if (wfStateRaw && wfStateRaw.active) {
             state.workflowState = {
@@ -153,12 +155,21 @@ async function main() {
             started_at: wfState.started_at,
             completed_artifacts: wfState.completed_artifacts,
         } : null;
-        let stopResult = enforceStop(ir, {
-            cwd: typeof rawInput.cwd === "string" ? rawInput.cwd : undefined,
-            sessionId: sessionId,
-            stop_reason: typeof rawInput.stop_reason === "string" ? rawInput.stop_reason : undefined,
-        }, stopContext);
-        let stopOutput = stopResult?.output ?? silentOutput();
+        const verifierResults = stopContext?.active
+            ? await runStopVerifiersForTest(projectDir, ir, stopContext, sessionId)
+            : [];
+        const blockingVerifierFailures = verifierResults.filter((result) => result.status === "fail" && result.severity === "block");
+        let stopOutput = blockingVerifierFailures.length > 0
+            ? blockOutput(`[Intent DNA] Verifier failures at step '${stopContext.current_step}':\n` +
+                blockingVerifierFailures.map((result) => `  - ${result.message ?? result.verifier_id}`).join("\n"))
+            : (enforceStop(clearBlockingVerifierCheckpoints(ir, stopContext), {
+                cwd: typeof rawInput.cwd === "string" ? rawInput.cwd : undefined,
+                sessionId: sessionId,
+                stop_reason: typeof rawInput.stop_reason === "string" ? rawInput.stop_reason : undefined,
+            }, stopContext)?.output ?? silentOutput());
+        if (blockingVerifierFailures.length === 0) {
+            stopOutput = appendStopVerifierWarnings(stopOutput, verifierResults, stopContext?.current_step);
+        }
         // Session summary: aggregate block/warn stats from trace
         try {
             const traces = await readTraces(projectDir, 1, sessionId);
@@ -216,7 +227,7 @@ async function main() {
                 const readPath = typeof rawInput.tool_input?.file_path === "string"
                     ? rawInput.tool_input.file_path : undefined;
                 if (readPath) {
-                    await appendSessionRead(projectDir, readPath, sessionId);
+                    await appendSessionRead(projectDir, await toProjectRelativePath(projectDir, readPath), sessionId);
                 }
             }
         }
@@ -224,12 +235,22 @@ async function main() {
         try {
             const reflectionOutput = await handleSurgeonReflection(ir, rawInput, projectDir, sessionId);
             if (reflectionOutput) {
-                // Merge: keep original output but append reflection warning
-                if (output.suppressOutput) {
-                    output = reflectionOutput;
-                }
-                else if (output.reason) {
-                    output = { ...output, reason: output.reason + "\n" + (reflectionOutput.reason ?? "") };
+                output = appendOutputText(output, reflectionOutput.reason ?? reflectionOutput.hookSpecificOutput?.additionalContext, "PostToolUse");
+            }
+        }
+        catch { /* fail-open */ }
+        try {
+            if (wfStateRaw?.active) {
+                const verifierResults = await runVerifiersForTest(projectDir, ir, {
+                    workflow: wfStateRaw.workflow,
+                    current_step: wfStateRaw.current_step,
+                    current_role: wfStateRaw.current_role,
+                }, "post_tool_use", sessionId);
+                const failingResults = verifierResults.filter((result) => result.status === "fail");
+                if (failingResults.length > 0) {
+                    const verifierText = `[Intent DNA] PostToolUse verifier failures at step '${wfStateRaw.current_step}':\n` +
+                        failingResults.map((result) => `  - ${result.message ?? result.verifier_id}`).join("\n");
+                    output = appendOutputText(output, verifierText, "PostToolUse");
                 }
             }
         }
@@ -414,6 +435,569 @@ async function scanConsumedArtifactPaths(projectDir, ir, workflowName, currentSt
     }
     return paths;
 }
+function clearBlockingVerifierCheckpoints(ir, workflowState) {
+    if (!workflowState || !ir.verifier_specs || ir.verifier_specs.length === 0)
+        return ir;
+    const blockedIds = new Set(ir.verifier_specs
+        .filter((spec) => (spec.when === "stop" || spec.when === "post_step") &&
+        spec.kind === "checkpoint" &&
+        spec.severity === "block" &&
+        spec.workflow_name === workflowState.workflow &&
+        spec.step_id === workflowState.current_step)
+        .map((spec) => spec.checkpoint?.assert)
+        .filter((value) => typeof value === "string"));
+    if (blockedIds.size === 0)
+        return ir;
+    const filterCheckpointList = (checkpoints) => checkpoints?.map((entry) => ({
+        ...entry,
+        checkpoints: entry.checkpoints.filter((cp) => !blockedIds.has(cp.assert) || (cp.action ?? "block") !== "block"),
+    })).filter((entry) => entry.checkpoints.length > 0);
+    return {
+        ...ir,
+        step_checkpoints: filterCheckpointList(ir.step_checkpoints),
+        workflows_ir: ir.workflows_ir?.map((workflow) => workflow.workflow_name !== workflowState.workflow
+            ? workflow
+            : {
+                ...workflow,
+                step_checkpoints: filterCheckpointList(workflow.step_checkpoints) ?? [],
+            }),
+    };
+}
+const DEFAULT_VERIFIER_COMMAND_TIMEOUT_MS = 30_000;
+const MAX_VERIFIER_EVIDENCE_BYTES = 4096;
+function appendOutputText(output, text, hookEventName) {
+    if (!text)
+        return output;
+    if (output.continue === false) {
+        return {
+            ...output,
+            reason: output.reason ? `${output.reason}\n${text}` : text,
+        };
+    }
+    const existing = output.hookSpecificOutput?.additionalContext;
+    if (existing) {
+        return {
+            ...output,
+            suppressOutput: undefined,
+            hookSpecificOutput: {
+                ...output.hookSpecificOutput,
+                hookEventName: output.hookSpecificOutput?.hookEventName ?? hookEventName,
+                additionalContext: `${existing}\n${text}`,
+            },
+        };
+    }
+    return allowOutput(text, hookEventName);
+}
+export function appendStopVerifierWarnings(output, verifierResults, currentStep) {
+    const warningVerifierFailures = verifierResults.filter((result) => result.status === "fail" && result.severity === "warn");
+    if (warningVerifierFailures.length === 0)
+        return output;
+    const warningText = `[Intent DNA] Verifier warnings at step '${currentStep ?? "unknown"}':\n` +
+        warningVerifierFailures.map((result) => `  - ${result.message ?? result.verifier_id}`).join("\n");
+    return appendOutputText(output, warningText, "Stop");
+}
+function trimEvidence(raw) {
+    if (!raw)
+        return undefined;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.length > MAX_VERIFIER_EVIDENCE_BYTES
+        ? trimmed.slice(0, MAX_VERIFIER_EVIDENCE_BYTES)
+        : trimmed;
+}
+function hasUnsafeShellControl(command) {
+    let inSingle = false;
+    let inDouble = false;
+    let escaped = false;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        const next = command[i + 1] ?? "";
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (ch === "\\" && !inSingle) {
+            escaped = true;
+            continue;
+        }
+        if (ch === "'" && !inDouble) {
+            inSingle = !inSingle;
+            continue;
+        }
+        if (ch === '"' && !inSingle) {
+            inDouble = !inDouble;
+            continue;
+        }
+        if (!inSingle && !inDouble) {
+            if (ch === ";" || ch === "`" || ch === "\n" || ch === "\r")
+                return true;
+            if ((ch === "&" || ch === "|" || ch === "<" || ch === ">") && next === ch)
+                return true;
+            if (ch === "$" && next === "(")
+                return true;
+            if ((ch === "<" || ch === ">") && next === "(")
+                return true;
+            if (ch === "|" || ch === "&" || ch === "<" || ch === ">")
+                return true;
+        }
+        if (inDouble) {
+            if (ch === "`")
+                return true;
+            if (ch === "$" && next === "(")
+                return true;
+        }
+    }
+    return false;
+}
+function isVerifierCommandAllowed(ir, command) {
+    const normalized = command.trim();
+    const policy = ir.verifier_policy;
+    if (!policy)
+        return false;
+    if (policy.allow_commands?.includes(normalized))
+        return true;
+    if (hasUnsafeShellControl(normalized))
+        return false;
+    return policy.allow_command_prefixes?.some((prefix) => normalized.startsWith(prefix)) ?? false;
+}
+function verifierCommandPolicyMessage(command) {
+    return `Verifier command not allowed by verifier_policy: ${command}`;
+}
+function isBuiltinAssertAllowed(ir, assertName) {
+    const policy = ir.verifier_policy;
+    return policy?.allow_builtin_asserts?.includes(assertName) ?? false;
+}
+function verifierAssertPolicyMessage(assertName) {
+    return `Verifier assert not allowed by verifier_policy: ${assertName}`;
+}
+function summarizeCommandEvidence(stdout, stderr) {
+    const stdoutBytes = Buffer.byteLength(stdout, "utf8");
+    const stderrBytes = Buffer.byteLength(stderr, "utf8");
+    if (stdoutBytes === 0 && stderrBytes === 0)
+        return undefined;
+    return trimEvidence(`stdout_bytes=${stdoutBytes} stderr_bytes=${stderrBytes}`);
+}
+async function execVerifierCommand(projectDir, command, timeoutMs = DEFAULT_VERIFIER_COMMAND_TIMEOUT_MS) {
+    return new Promise((resolvePromise) => {
+        const child = spawn("bash", ["-lc", command], { cwd: projectDir, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeoutId);
+            resolvePromise(result);
+        };
+        const timeoutId = setTimeout(() => {
+            child.kill("SIGTERM");
+            setTimeout(() => child.kill("SIGKILL"), 1000).unref();
+            settle({ passed: false, timedOut: true, exitCode: 124, evidence: summarizeCommandEvidence(stdout, stderr) });
+        }, timeoutMs);
+        child.stdout.on("data", (chunk) => {
+            stdout += String(chunk);
+            if (stdout.length > MAX_VERIFIER_EVIDENCE_BYTES) {
+                stdout = stdout.slice(0, MAX_VERIFIER_EVIDENCE_BYTES);
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += String(chunk);
+            if (stderr.length > MAX_VERIFIER_EVIDENCE_BYTES) {
+                stderr = stderr.slice(0, MAX_VERIFIER_EVIDENCE_BYTES);
+            }
+        });
+        child.on("error", (_error) => settle({
+            passed: false,
+            timedOut: false,
+            exitCode: 1,
+            evidence: summarizeCommandEvidence(stdout, stderr),
+        }));
+        child.on("close", (code) => settle({
+            passed: code === 0,
+            timedOut: false,
+            exitCode: code ?? 1,
+            evidence: summarizeCommandEvidence(stdout, stderr),
+        }));
+    });
+}
+async function runCheckpointVerifier(projectDir, ir, checkpoint, commandTimeoutMs = DEFAULT_VERIFIER_COMMAND_TIMEOUT_MS) {
+    const assertCommands = {
+        clean_working_tree: "git status --porcelain",
+        lint_passing: "npm run lint --silent 2>/dev/null",
+        build_passing: "npm run build --silent 2>/dev/null",
+    };
+    if (checkpoint.command) {
+        if (!isVerifierCommandAllowed(ir, checkpoint.command)) {
+            return {
+                passed: false,
+                target: checkpoint.command,
+                evidence: "policy_denied",
+                exit_code: 126,
+                message: verifierCommandPolicyMessage(checkpoint.command),
+            };
+        }
+        const commandResult = await execVerifierCommand(projectDir, checkpoint.command, commandTimeoutMs);
+        return {
+            passed: commandResult.passed,
+            target: checkpoint.command,
+            evidence: commandResult.evidence,
+            exit_code: commandResult.exitCode,
+            message: commandResult.passed
+                ? checkpoint.message
+                : commandResult.timedOut
+                    ? `Verifier command timed out after ${commandTimeoutMs}ms: ${checkpoint.command}`
+                    : `Verifier command failed: ${checkpoint.command}`,
+        };
+    }
+    if (checkpoint.assert === "clean_working_tree") {
+        if (!isBuiltinAssertAllowed(ir, checkpoint.assert)) {
+            return {
+                passed: false,
+                target: checkpoint.assert,
+                evidence: "policy_denied",
+                exit_code: 126,
+                message: verifierAssertPolicyMessage(checkpoint.assert),
+            };
+        }
+        try {
+            const raw = await new Promise((resolvePromise, rejectPromise) => {
+                const child = spawn("git", ["status", "--porcelain"], { cwd: projectDir, stdio: ["ignore", "pipe", "ignore"] });
+                let stdout = "";
+                child.stdout.on("data", (chunk) => { stdout += String(chunk); });
+                child.on("error", rejectPromise);
+                child.on("close", (code) => code === 0 ? resolvePromise(stdout) : rejectPromise(new Error("git status failed")));
+            });
+            const changedEntries = raw.split("\n").filter(Boolean).length;
+            return {
+                passed: raw.trim() === "",
+                target: checkpoint.assert,
+                evidence: `changed_entries=${changedEntries}`,
+                exit_code: 0,
+                message: checkpoint.message,
+            };
+        }
+        catch {
+            return { passed: false, target: checkpoint.assert, exit_code: 1, message: checkpoint.message };
+        }
+    }
+    if (checkpoint.assert === "no_test_regression") {
+        if (!isBuiltinAssertAllowed(ir, checkpoint.assert)) {
+            return {
+                passed: false,
+                target: checkpoint.assert,
+                evidence: "policy_denied",
+                exit_code: 126,
+                message: verifierAssertPolicyMessage(checkpoint.assert),
+            };
+        }
+        try {
+            const baseline = parseInt(await readFile(resolve(projectDir, ".dna/test-baseline"), "utf-8").catch(() => "0"), 10);
+            const current = parseInt(await readFile(resolve(projectDir, ".dna/test-current"), "utf-8").catch(() => "0"), 10);
+            return {
+                passed: current <= baseline,
+                target: checkpoint.assert,
+                evidence: `baseline=${baseline} current=${current}`,
+                exit_code: 0,
+                message: checkpoint.message,
+            };
+        }
+        catch {
+            return { passed: false, target: checkpoint.assert, exit_code: 1, message: checkpoint.message };
+        }
+    }
+    if (assertCommands[checkpoint.assert]) {
+        if (!isBuiltinAssertAllowed(ir, checkpoint.assert)) {
+            return {
+                passed: false,
+                target: checkpoint.assert,
+                evidence: "policy_denied",
+                exit_code: 126,
+                message: verifierAssertPolicyMessage(checkpoint.assert),
+            };
+        }
+        const commandResult = await execVerifierCommand(projectDir, assertCommands[checkpoint.assert], commandTimeoutMs);
+        return {
+            passed: commandResult.passed,
+            target: checkpoint.assert,
+            evidence: commandResult.evidence,
+            exit_code: commandResult.exitCode,
+            message: commandResult.passed
+                ? checkpoint.message
+                : commandResult.timedOut
+                    ? `Verifier command timed out after ${commandTimeoutMs}ms: ${assertCommands[checkpoint.assert]}`
+                    : checkpoint.message,
+        };
+    }
+    return { passed: false, target: checkpoint.assert, exit_code: 1, message: checkpoint.message };
+}
+function isWithinProjectRoot(projectRoot, targetPath) {
+    const relPath = relative(projectRoot, targetPath);
+    return relPath === "" || (!relPath.startsWith("..") && !isAbsolute(relPath));
+}
+async function resolveVerifierTarget(projectDir, targetPath) {
+    const projectRoot = await realpath(projectDir).catch(() => resolve(projectDir));
+    const resolvedPath = resolve(projectDir, targetPath);
+    if (!isWithinProjectRoot(projectRoot, resolvedPath)) {
+        return null;
+    }
+    const canonicalParent = await realpath(dirname(resolvedPath)).catch(() => null);
+    if (canonicalParent && !isWithinProjectRoot(projectRoot, canonicalParent)) {
+        return null;
+    }
+    const canonicalTarget = await realpath(resolvedPath).catch(() => null);
+    if (canonicalTarget && !isWithinProjectRoot(projectRoot, canonicalTarget)) {
+        return null;
+    }
+    return canonicalTarget ?? resolvedPath;
+}
+async function toProjectRelativePath(projectDir, filePath) {
+    const projectRoot = await realpath(projectDir).catch(() => resolve(projectDir));
+    const resolvedPath = resolve(projectDir, filePath);
+    const canonicalPath = await realpath(resolvedPath).catch(() => resolvedPath);
+    const targetPath = isWithinProjectRoot(projectRoot, canonicalPath) ? canonicalPath : resolvedPath;
+    const relPath = relative(projectRoot, targetPath);
+    return relPath === "" ? "." : relPath;
+}
+function getCompletionCheckFields(completion) {
+    if (typeof completion !== "object" || completion === null || Array.isArray(completion))
+        return [];
+    const fields = [];
+    if (completion.file_exists !== undefined)
+        fields.push("file_exists");
+    if (completion.file_not_empty !== undefined)
+        fields.push("file_not_empty");
+    if (completion.file_contains !== undefined)
+        fields.push("file_contains");
+    if (completion.command_success !== undefined)
+        fields.push("command_success");
+    return fields;
+}
+function validateCompletionVerifier(completion) {
+    const fields = getCompletionCheckFields(completion);
+    if (fields.length !== 1) {
+        return {
+            message: "Completion verifier must define exactly one check",
+            evidence: `fields:${fields.join(",") || "none"}`,
+        };
+    }
+    const field = fields[0];
+    if (field === "file_exists" && (typeof completion.file_exists !== "string" || !completion.file_exists)) {
+        return { message: "Completion verifier file_exists must be a non-empty string", evidence: "invalid:file_exists" };
+    }
+    if (field === "file_not_empty" && (typeof completion.file_not_empty !== "string" || !completion.file_not_empty)) {
+        return { message: "Completion verifier file_not_empty must be a non-empty string", evidence: "invalid:file_not_empty" };
+    }
+    if (field === "command_success" && (typeof completion.command_success !== "string" || !completion.command_success)) {
+        return { message: "Completion verifier command_success must be a non-empty string", evidence: "invalid:command_success" };
+    }
+    if (field === "file_contains") {
+        const fileContains = completion.file_contains;
+        if (typeof fileContains !== "object" || fileContains === null) {
+            return { message: "Completion verifier file_contains must define path and pattern", evidence: "invalid:file_contains" };
+        }
+        if (typeof fileContains.path !== "string" || !fileContains.path) {
+            return { message: "Completion verifier file_contains.path must be a non-empty string", evidence: "invalid:file_contains.path" };
+        }
+        if (typeof fileContains.pattern !== "string" || !fileContains.pattern) {
+            return { message: "Completion verifier file_contains.pattern must be a non-empty string", evidence: "invalid:file_contains.pattern" };
+        }
+    }
+    return null;
+}
+function getAuditCheckType(spec) {
+    if (spec.completion?.file_exists !== undefined)
+        return "file_exists";
+    if (spec.completion?.file_not_empty !== undefined)
+        return "file_not_empty";
+    if (spec.completion?.file_contains !== undefined)
+        return "file_contains";
+    if (spec.completion?.command_success !== undefined)
+        return "command_success";
+    if (spec.checkpoint?.command)
+        return "command_success";
+    return "checkpoint_assert";
+}
+async function writeVerifierAuditEvent(projectDir, result, spec) {
+    await writeAuditEvent({
+        timestamp: result.timestamp,
+        event_type: "completion_check",
+        workflow: result.workflow,
+        step_id: result.step_id,
+        target: result.target ?? spec.checkpoint?.assert ?? spec.id,
+        result: result.status,
+        check_type: getAuditCheckType(spec),
+        verifier_id: result.verifier_id,
+        verifier_when: result.when,
+        verifier_severity: result.severity,
+        verifier_kind: result.kind,
+        evidence: result.evidence,
+        exit_code: result.exit_code,
+        artifact: result.artifact,
+        message: result.message,
+    }, {
+        enabled: true,
+        storage: join(projectDir, ".dna", "audit"),
+        track: ["completion_checks"],
+    });
+}
+async function runVerifierSpec(projectDir, ir, spec, workflowState, sessionId, options) {
+    let passed = true;
+    let target;
+    let evidence;
+    let exit_code;
+    let artifact;
+    let message = spec.checkpoint?.message;
+    if (spec.kind === "checkpoint" && spec.checkpoint) {
+        const checkpointResult = await runCheckpointVerifier(projectDir, ir, spec.checkpoint, options?.commandTimeoutMs);
+        passed = checkpointResult.passed;
+        target = checkpointResult.target;
+        evidence = checkpointResult.evidence;
+        exit_code = checkpointResult.exit_code;
+        artifact = checkpointResult.artifact;
+        message = checkpointResult.message;
+    }
+    else if (spec.kind === "completion") {
+        const completion = spec.completion;
+        if (!completion) {
+            passed = false;
+            evidence = "fields:none";
+            message = "Completion verifier must define exactly one check";
+        }
+        else {
+            const invalidCompletion = validateCompletionVerifier(completion);
+            if (invalidCompletion) {
+                passed = false;
+                evidence = invalidCompletion.evidence;
+                message = invalidCompletion.message;
+            }
+            else if (completion.file_exists) {
+                target = completion.file_exists;
+                const resolvedTarget = await resolveVerifierTarget(projectDir, completion.file_exists);
+                artifact = resolvedTarget ?? undefined;
+                evidence = resolvedTarget ? `exists:${resolvedTarget}` : "path_escape";
+                if (!resolvedTarget) {
+                    passed = false;
+                    message = `Verifier target escapes project root: ${completion.file_exists}`;
+                }
+                else {
+                    try {
+                        await stat(resolvedTarget);
+                    }
+                    catch {
+                        passed = false;
+                        message = `Required file missing: ${completion.file_exists}`;
+                    }
+                }
+            }
+            else if (completion.file_not_empty) {
+                target = completion.file_not_empty;
+                const resolvedTarget = await resolveVerifierTarget(projectDir, completion.file_not_empty);
+                artifact = resolvedTarget ?? undefined;
+                evidence = resolvedTarget ? `not_empty:${resolvedTarget}` : "path_escape";
+                if (!resolvedTarget) {
+                    passed = false;
+                    message = `Verifier target escapes project root: ${completion.file_not_empty}`;
+                }
+                else {
+                    try {
+                        const raw = await readFile(resolvedTarget, "utf-8");
+                        evidence = `bytes=${Buffer.byteLength(raw, "utf8")}`;
+                        if (raw.trim().length === 0) {
+                            passed = false;
+                            message = `Required file is empty: ${completion.file_not_empty}`;
+                        }
+                    }
+                    catch {
+                        passed = false;
+                        message = `Required file missing: ${completion.file_not_empty}`;
+                    }
+                }
+            }
+            else if (completion.file_contains) {
+                target = completion.file_contains.path;
+                const resolvedTarget = await resolveVerifierTarget(projectDir, completion.file_contains.path);
+                artifact = resolvedTarget ?? undefined;
+                evidence = `pattern:${completion.file_contains.pattern}`;
+                if (!resolvedTarget) {
+                    passed = false;
+                    message = `Verifier target escapes project root: ${completion.file_contains.path}`;
+                }
+                else {
+                    try {
+                        const raw = await readFile(resolvedTarget, "utf-8");
+                        const re = new RegExp(completion.file_contains.pattern);
+                        if (!re.test(raw)) {
+                            passed = false;
+                            message = `Required pattern missing in ${completion.file_contains.path}`;
+                        }
+                    }
+                    catch {
+                        passed = false;
+                        message = `Required file missing: ${completion.file_contains.path}`;
+                    }
+                }
+            }
+            else if (completion.command_success) {
+                target = completion.command_success;
+                if (!isVerifierCommandAllowed(ir, completion.command_success)) {
+                    passed = false;
+                    evidence = "policy_denied";
+                    exit_code = 126;
+                    message = verifierCommandPolicyMessage(completion.command_success);
+                }
+                else {
+                    const commandResult = await execVerifierCommand(projectDir, completion.command_success, options?.commandTimeoutMs);
+                    passed = commandResult.passed;
+                    evidence = commandResult.evidence;
+                    exit_code = commandResult.exitCode;
+                    if (!passed) {
+                        message = commandResult.timedOut
+                            ? `Verifier command timed out after ${options?.commandTimeoutMs ?? DEFAULT_VERIFIER_COMMAND_TIMEOUT_MS}ms: ${completion.command_success}`
+                            : `Verifier command failed: ${completion.command_success}`;
+                    }
+                }
+            }
+        }
+    }
+    const entry = {
+        verifier_id: spec.id,
+        when: spec.when,
+        severity: spec.severity,
+        kind: spec.kind,
+        workflow: workflowState.workflow,
+        step_id: workflowState.current_step,
+        source_genes: spec.source_genes,
+        status: passed ? "pass" : "fail",
+        target,
+        evidence,
+        exit_code,
+        artifact,
+        message,
+        timestamp: new Date().toISOString(),
+    };
+    await appendVerifierResult(projectDir, entry, sessionId);
+    await writeVerifierAuditEvent(projectDir, entry, spec).catch(() => { });
+    return entry;
+}
+export async function runVerifiersForTest(projectDir, ir, workflowState, when, sessionId, options) {
+    const specs = (ir.verifier_specs ?? []).filter((spec) => spec.when === when &&
+        spec.workflow_name === workflowState.workflow &&
+        spec.step_id === workflowState.current_step);
+    const results = [];
+    for (const spec of specs) {
+        results.push(await runVerifierSpec(projectDir, ir, spec, workflowState, sessionId, options));
+    }
+    return results;
+}
+export async function runStopVerifiersForTest(projectDir, ir, workflowState, sessionId, options) {
+    const results = [];
+    results.push(...await runVerifiersForTest(projectDir, ir, workflowState, "post_step", sessionId, options));
+    results.push(...await runVerifiersForTest(projectDir, ir, workflowState, "pre_handoff", sessionId, options));
+    results.push(...await runVerifiersForTest(projectDir, ir, workflowState, "stop", sessionId, options));
+    return results;
+}
 // ── Surgeon Reflection Gate ──────────────────────────────
 /** Regex to parse test green count from vitest/flutter test output */
 const TEST_PASSED_RE = /(\d+)\s+(?:tests?\s+)?passed/i;
@@ -560,15 +1144,31 @@ export async function handlePreToolGates(ir, rawInput, wfState, projectDir, sess
         }
         // Gate 2: Context Gate — block write tools when required context files unread.
         const writeTools = new Set(["Edit", "Write", "Bash"]);
-        if (writeTools.has(toolName) && wfState?.active && ir.context_files) {
+        if (writeTools.has(toolName) && wfState?.active) {
             const required = [];
-            if (ir.context_files.mandatory)
-                required.push(...ir.context_files.mandatory);
-            if (ir.context_files.per_role?.[wfState.current_role]) {
-                required.push(...ir.context_files.per_role[wfState.current_role]);
+            if (ir.legibility_assets) {
+                for (const asset of ir.legibility_assets.mandatory ?? []) {
+                    if (asset.type === "required_read" && !required.includes(asset.path))
+                        required.push(asset.path);
+                }
+                for (const asset of ir.legibility_assets.per_role?.[wfState.current_role] ?? []) {
+                    if (asset.type === "required_read" && !required.includes(asset.path))
+                        required.push(asset.path);
+                }
+                for (const asset of ir.legibility_assets.per_workflow?.[wfState.workflow] ?? []) {
+                    if (asset.type === "required_read" && !required.includes(asset.path))
+                        required.push(asset.path);
+                }
             }
-            if (ir.context_files.per_workflow?.[wfState.workflow]) {
-                required.push(...ir.context_files.per_workflow[wfState.workflow]);
+            if (required.length === 0 && ir.context_files) {
+                if (ir.context_files.mandatory)
+                    required.push(...ir.context_files.mandatory);
+                if (ir.context_files.per_role?.[wfState.current_role]) {
+                    required.push(...ir.context_files.per_role[wfState.current_role]);
+                }
+                if (ir.context_files.per_workflow?.[wfState.workflow]) {
+                    required.push(...ir.context_files.per_workflow[wfState.workflow]);
+                }
             }
             if (required.length > 0) {
                 const sessionReadsState = await readSessionReads(projectDir, sessionId);