@deftai/directive-core 0.99.0 → 0.101.0

package/dist/literal-acceptance/capture.js

@@ -0,0 +1,658 @@
+/**
+ * Capture exact stated acceptance commands from a task statement (#3267).
+ *
+ * Only extracts commands that appear literally in the text — never invents
+ * or paraphrases. Prefer fenced blocks and labeled lines (verify:/command:/run:).
+ *
+ * Safety-rejected shell-shaped lines are recorded on a rejected ledger so they
+ * do not vanish silently (#3267 residual). Dedup keys include cwd/expectedExitCode
+ * so distinct execution contexts are not collapsed.
+ */
+import { evaluateCommandSafety } from "./safety.js";
+import { EXECUTABLE_LITERAL_SOURCES, LITERAL_ACCEPTANCE_REJECTED_METADATA_KEY } from "./types.js";
+/** Labeled keywords (single-token, linear match). */
+const LABELED_KEYWORDS = new Set(["verify", "command", "run", "check", "exec", "shell"]);
+/** Words that look like a CLI invocation start (not prose). */
+const CLI_START_RE = /^(?:task|deft|directive|pnpm|npm|npx|yarn|bun|node|python|py|pytest|vitest|cargo|go|dotnet|make|curl|gh|git|uv|pip|poetry|rg|echo|true|false)\b/i;
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * Normalize a captured command string.
+ * Trailing period is stripped only when it is sentence punctuation — not when the
+ * last token is `.` / `..` (cwd / parent path, e.g. `docker build .`).
+ */
+function normalizeCommand(raw) {
+    let s = raw.trim();
+    // Strip surrounding backticks once.
+    if (s.startsWith("`") && s.endsWith("`") && s.length >= 2) {
+        s = s.slice(1, -1).trim();
+    }
+    // Strip trailing period that is clearly sentence punctuation (not a path token).
+    // Preserve: `file.ts`, `..`, and commands ending in whitespace+`.` (cwd path).
+    if (s.endsWith(".") && !s.endsWith("..") && !/\.\w+$/.test(s) && !/\s\.$/.test(s) && s !== ".") {
+        s = s.slice(0, -1).trim();
+    }
+    if (s.length === 0)
+        return null;
+    // Reject pure prose / multi-sentence blobs without CLI shape.
+    if (s.length > 500)
+        return null;
+    if (s.includes("\n")) {
+        // Multi-line only accepted from fenced blocks (caller splits).
+        return null;
+    }
+    return s;
+}
+function looksLikeShellCommand(command) {
+    if (CLI_START_RE.test(command))
+        return true;
+    // Flags or paths suggest a real invocation.
+    if (/\s--?[a-zA-Z]/.test(command))
+        return true;
+    // Subcommand shape: word word
+    if (/^\S+\s+\S+/.test(command) && !/^[A-Z][a-z]+\s/.test(command))
+        return true;
+    return false;
+}
+/** Dedupe key includes execution context so distinct cwd/exit targets stay distinct. */
+function commandDedupeKey(cmd) {
+    const cwd = cmd.cwd !== null && cmd.cwd !== undefined && cmd.cwd.trim().length > 0 ? cmd.cwd.trim() : "";
+    const exit = typeof cmd.expectedExitCode === "number" && Number.isFinite(cmd.expectedExitCode)
+        ? cmd.expectedExitCode
+        : 0;
+    return `${cmd.command}\0${cwd}\0${exit}`;
+}
+function recordRejected(buckets, command, reason, sourceSpan) {
+    const key = `${command}\0${reason}`;
+    if (buckets.rejectedSeen.has(key))
+        return;
+    buckets.rejectedSeen.add(key);
+    buckets.rejected.push({
+        command,
+        reason,
+        sourceSpan,
+    });
+}
+/**
+ * Push a full command record (preserves cwd / expectedStdout / expectedExitCode).
+ * Safety failures go to the rejected ledger instead of silent drop.
+ */
+function pushCommand(buckets, cmd) {
+    const safety = evaluateCommandSafety(cmd.command);
+    if (!safety.ok) {
+        recordRejected(buckets, cmd.command, safety.reason ?? "unsafe command", cmd.sourceSpan ?? null);
+        return;
+    }
+    const key = commandDedupeKey(cmd);
+    if (buckets.seen.has(key))
+        return;
+    buckets.seen.add(key);
+    buckets.out.push({
+        command: cmd.command,
+        cwd: cmd.cwd ?? null,
+        expectedStdout: cmd.expectedStdout ?? null,
+        expectedExitCode: cmd.expectedExitCode ?? 0,
+        source: cmd.source,
+        sourceSpan: cmd.sourceSpan ?? null,
+    });
+}
+/** Capture-path helper: command string only (defaults for context fields). */
+function pushUnique(buckets, command, source, sourceSpan) {
+    pushCommand(buckets, {
+        command,
+        cwd: null,
+        expectedStdout: null,
+        expectedExitCode: 0,
+        source,
+        sourceSpan,
+    });
+}
+/** Linear: does heading text mention acceptance/verify regions? */
+function isRegionHeading(text) {
+    const low = text.toLowerCase();
+    if (low.includes("acceptance"))
+        return true;
+    if (low.includes("verify") || low.includes("verification"))
+        return true;
+    if (low.includes("done-gate") || low.includes("done gate"))
+        return true;
+    if (low.includes("run verbatim"))
+        return true;
+    if (low === "check" || low.startsWith("check ") || low.endsWith(" check"))
+        return true;
+    return false;
+}
+/** Skip leading spaces/tabs only (bounded, linear). */
+function skipWs(line, start) {
+    let i = start;
+    while (i < line.length && (line[i] === " " || line[i] === "\t"))
+        i += 1;
+    return i;
+}
+/** Parse `verify: cmd` / bullet-prefixed labeled lines without polynomial regex. */
+function matchLabeledCommand(line) {
+    let i = skipWs(line, 0);
+    // Optional bullet or number prefix.
+    if (i < line.length && "-*+".includes(line[i])) {
+        i = skipWs(line, i + 1);
+    }
+    else if (i < line.length) {
+        const ch = line[i];
+        if (ch >= "0" && ch <= "9") {
+            while (i < line.length) {
+                const d = line[i];
+                if (d < "0" || d > "9")
+                    break;
+                i += 1;
+            }
+            if (i < line.length && (line[i] === "." || line[i] === ")"))
+                i += 1;
+            i = skipWs(line, i);
+        }
+    }
+    const keywordStart = i;
+    while (i < line.length && /[a-zA-Z]/.test(line[i]))
+        i += 1;
+    if (i === keywordStart)
+        return null;
+    const keyword = line.slice(keywordStart, i).toLowerCase();
+    if (!LABELED_KEYWORDS.has(keyword))
+        return null;
+    i = skipWs(line, i);
+    if (i >= line.length || line[i] !== ":")
+        return null;
+    i = skipWs(line, i + 1);
+    if (i >= line.length)
+        return null;
+    return line.slice(i).trimEnd();
+}
+/** Mid-line `verify: cmd` (e.g. "Also run: verify: task check"). */
+function matchMidlineLabeled(line) {
+    const low = line.toLowerCase();
+    for (const kw of LABELED_KEYWORDS) {
+        if (kw === "run" || kw === "check")
+            continue; // too ambiguous mid-line
+        const needle = `${kw}:`;
+        const idx = low.indexOf(needle);
+        if (idx < 0)
+            continue;
+        const rest = line.slice(idx + needle.length).trim();
+        if (rest.length > 0)
+            return rest;
+    }
+    return null;
+}
+/** `$ cmd` or `> cmd` prompt lines. */
+function matchPromptCommand(line) {
+    let i = skipWs(line, 0);
+    if (i >= line.length)
+        return null;
+    if (line[i] !== "$" && line[i] !== ">")
+        return null;
+    i = skipWs(line, i + 1);
+    if (i >= line.length)
+        return null;
+    return line.slice(i).trimEnd();
+}
+/**
+ * Walk fenced ``` / ~~~ blocks; keep fence body lines that look like shell.
+ * When `requireRegion` is true, only fences under an acceptance/verify heading.
+ */
+function extractFromFences(text, requireRegion, buckets) {
+    const lines = text.split(/\r?\n/);
+    let inFence = false;
+    let fenceLang = "";
+    let regionActive = !requireRegion;
+    let fenceStartLine = 0;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? "";
+        const heading = matchMarkdownHeading(line);
+        if (heading !== null && !inFence) {
+            regionActive = requireRegion ? isRegionHeading(heading.text) : true;
+            continue;
+        }
+        const fenceOpen = matchFenceOpen(line);
+        if (fenceOpen !== null && !inFence) {
+            inFence = true;
+            fenceLang = fenceOpen.lang;
+            fenceStartLine = i + 1;
+            continue;
+        }
+        if (inFence && matchFenceClose(line)) {
+            inFence = false;
+            fenceLang = "";
+            continue;
+        }
+        if (!inFence)
+            continue;
+        if (requireRegion && !regionActive)
+            continue;
+        // Skip comment-only fence lines.
+        const trimmed = line.trim();
+        if (trimmed.length === 0 || trimmed.startsWith("#") || trimmed.startsWith("//")) {
+            continue;
+        }
+        // Shell-ish langs always accepted; unknown langs need CLI shape.
+        const langOk = isShellFenceLang(fenceLang);
+        if (!langOk && fenceLang !== "")
+            continue;
+        // Strip leading prompt markers inside fences.
+        let body = trimmed;
+        if (body.startsWith("$ ") || body.startsWith("> ")) {
+            body = body.slice(2).trim();
+        }
+        const normalized = normalizeCommand(body);
+        if (normalized === null)
+            continue;
+        if (!looksLikeShellCommand(normalized) && (fenceLang === "" || !langOk))
+            continue;
+        pushUnique(buckets, normalized, "task_statement", `fence@L${fenceStartLine}${fenceLang ? `:${fenceLang}` : ""}`);
+    }
+}
+function isShellFenceLang(lang) {
+    return (lang === "" ||
+        lang === "bash" ||
+        lang === "sh" ||
+        lang === "shell" ||
+        lang === "zsh" ||
+        lang === "console" ||
+        lang === "powershell" ||
+        lang === "pwsh" ||
+        lang === "cmd" ||
+        lang === "text");
+}
+/** Linear fence open: ```lang or ~~~lang */
+function matchFenceOpen(line) {
+    const t = line.trimEnd();
+    if (t.startsWith("```")) {
+        const rest = t.slice(3).trim().toLowerCase();
+        if (rest.includes(" ") || rest.includes("\t"))
+            return null;
+        return { lang: rest };
+    }
+    if (t.startsWith("~~~")) {
+        const rest = t.slice(3).trim().toLowerCase();
+        if (rest.includes(" ") || rest.includes("\t"))
+            return null;
+        return { lang: rest };
+    }
+    return null;
+}
+function matchFenceClose(line) {
+    const t = line.trim();
+    return t === "```" || t === "~~~";
+}
+function matchMarkdownHeading(line) {
+    if (!line.startsWith("#"))
+        return null;
+    let level = 0;
+    while (level < line.length && line[level] === "#")
+        level += 1;
+    if (level < 1 || level > 6)
+        return null;
+    if (level >= line.length || line[level] !== " ")
+        return null;
+    return { level, text: line.slice(level + 1).trim() };
+}
+/** Extract from labeled lines and `$` prompts anywhere in the statement. */
+function extractFromLabeledLines(text, buckets) {
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? "";
+        let capturedLabeled = false;
+        let labeledBody = matchLabeledCommand(line);
+        if (labeledBody === null && matchPromptCommand(line) === null) {
+            // Avoid treating `$ task verify:branch` as labeled "branch".
+            labeledBody = matchMidlineLabeled(line);
+        }
+        if (labeledBody !== null) {
+            const normalized = normalizeCommand(labeledBody);
+            if (normalized !== null && looksLikeShellCommand(normalized)) {
+                pushUnique(buckets, normalized, "task_statement", `labeled@L${i + 1}`);
+                capturedLabeled = true;
+            }
+        }
+        if (capturedLabeled)
+            continue;
+        const promptBody = matchPromptCommand(line);
+        if (promptBody !== null) {
+            const normalized = normalizeCommand(promptBody);
+            if (normalized !== null && looksLikeShellCommand(normalized)) {
+                pushUnique(buckets, normalized, "task_statement", `prompt@L${i + 1}`);
+            }
+        }
+    }
+}
+/**
+ * Extract inline `` `command` `` spans that follow verify/run language on the same line.
+ * Example: `run \`task check\` before done`
+ */
+function extractInlineVerifySpans(text, buckets) {
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? "";
+        if (!/\b(verify|run|execute|acceptance)\b/i.test(line))
+            continue;
+        let pos = 0;
+        while (pos < line.length) {
+            const open = line.indexOf("`", pos);
+            if (open < 0)
+                break;
+            const close = line.indexOf("`", open + 1);
+            if (close < 0)
+                break;
+            const inner = line.slice(open + 1, close);
+            pos = close + 1;
+            if (inner.includes("\n"))
+                continue;
+            const normalized = normalizeCommand(inner);
+            if (normalized === null || !looksLikeShellCommand(normalized))
+                continue;
+            pushUnique(buckets, normalized, "task_statement", `inline@L${i + 1}`);
+        }
+    }
+}
+function emptyBuckets() {
+    return {
+        out: [],
+        seen: new Set(),
+        rejected: [],
+        rejectedSeen: new Set(),
+    };
+}
+/**
+ * Capture literal acceptance commands from free-form task statement text.
+ * Returns commands + rejected ledger — never invents commands.
+ */
+export function captureLiteralAcceptanceCommandsDetailed(taskStatement) {
+    if (!isNonEmptyString(taskStatement)) {
+        return { commands: [], rejected: [] };
+    }
+    const buckets = emptyBuckets();
+    // Prefer fences under acceptance/verify headings first.
+    extractFromFences(taskStatement, true, buckets);
+    // Then any shell fences in the whole statement (still literal, not invented).
+    extractFromFences(taskStatement, false, buckets);
+    extractFromLabeledLines(taskStatement, buckets);
+    extractInlineVerifySpans(taskStatement, buckets);
+    return { commands: buckets.out, rejected: buckets.rejected };
+}
+/**
+ * Capture literal acceptance commands from free-form task statement text.
+ * Returns [] when none are stated — never invents commands.
+ */
+export function captureLiteralAcceptanceCommands(taskStatement) {
+    return [...captureLiteralAcceptanceCommandsDetailed(taskStatement).commands];
+}
+/**
+ * Read already-stored commands from plan.metadata / swarm.verify_commands / item.command.
+ * Preserves exact strings and execution context (cwd / expectedStdout / expectedExitCode).
+ */
+export function readStoredLiteralAcceptanceCommands(plan) {
+    return readStoredLiteralAcceptanceDetailed(plan).commands;
+}
+/** Read stored commands plus any persisted rejected ledger. */
+export function readStoredLiteralAcceptanceDetailed(plan) {
+    if (plan === null || plan === undefined || typeof plan !== "object") {
+        return { commands: [], rejected: [] };
+    }
+    const buckets = emptyBuckets();
+    const metadata = asRecord(plan.metadata);
+    if (metadata !== null) {
+        const explicit = metadata.literal_acceptance_commands ?? metadata.literalAcceptanceCommands ?? null;
+        for (const cmd of coerceCommandList(explicit, "explicit", "metadata.literal_acceptance")) {
+            pushCommand(buckets, cmd);
+        }
+        // Persisted rejected ledger (operator visibility across reloads).
+        const persistedRejected = metadata[LITERAL_ACCEPTANCE_REJECTED_METADATA_KEY] ??
+            metadata.literalAcceptanceRejected ??
+            null;
+        if (Array.isArray(persistedRejected)) {
+            for (const entry of persistedRejected) {
+                const rec = asRecord(entry);
+                if (rec === null)
+                    continue;
+                if (!isNonEmptyString(rec.command) || !isNonEmptyString(rec.reason))
+                    continue;
+                recordRejected(buckets, rec.command.trim(), rec.reason.trim(), isNonEmptyString(rec.sourceSpan) ? rec.sourceSpan : null);
+            }
+        }
+        const swarm = asRecord(metadata.swarm);
+        if (swarm !== null) {
+            // swarm.verify_commands is a string list (legacy). Prefer richer
+            // literal_acceptance_commands rows already loaded — do not invent a
+            // null-cwd duplicate for the same command text.
+            const alreadyHasCommand = (command) => buckets.out.some((c) => c.command === command);
+            for (const cmd of coerceCommandList(swarm.verify_commands, "verify_commands", "swarm.verify_commands")) {
+                if (alreadyHasCommand(cmd.command))
+                    continue;
+                pushCommand(buckets, cmd);
+            }
+            for (const cmd of coerceCommandList(swarm.literal_acceptance_commands ?? swarm.literalAcceptanceCommands, "metadata", "swarm.literal_acceptance")) {
+                pushCommand(buckets, cmd);
+            }
+        }
+    }
+    walkPlanItems(plan.items, "items", buckets);
+    return { commands: buckets.out, rejected: buckets.rejected };
+}
+function walkPlanItems(items, pathPrefix, buckets) {
+    if (!Array.isArray(items))
+        return;
+    items.forEach((item, index) => {
+        const rec = asRecord(item);
+        if (rec === null)
+            return;
+        const path = `${pathPrefix}[${index}]`;
+        const commandField = rec.command ?? rec.verify ?? rec.verify_command;
+        if (isNonEmptyString(commandField)) {
+            const normalized = normalizeCommand(commandField);
+            if (normalized !== null) {
+                pushUnique(buckets, normalized, "plan_item", `${path}.command`);
+            }
+        }
+        walkPlanItems(rec.subItems, `${path}.subItems`, buckets);
+        walkPlanItems(rec.items, `${path}.items`, buckets);
+    });
+}
+function coerceCommandList(raw, source, span) {
+    if (raw === null || raw === undefined)
+        return [];
+    if (typeof raw === "string") {
+        const normalized = normalizeCommand(raw);
+        if (normalized === null)
+            return [];
+        return [
+            {
+                command: normalized,
+                cwd: null,
+                expectedStdout: null,
+                expectedExitCode: 0,
+                source,
+                sourceSpan: span,
+            },
+        ];
+    }
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        if (typeof entry === "string") {
+            const normalized = normalizeCommand(entry);
+            if (normalized !== null) {
+                out.push({
+                    command: normalized,
+                    cwd: null,
+                    expectedStdout: null,
+                    expectedExitCode: 0,
+                    source,
+                    sourceSpan: span,
+                });
+            }
+            continue;
+        }
+        const rec = asRecord(entry);
+        if (rec === null)
+            continue;
+        const command = rec.command ?? rec.cmd ?? rec.shell;
+        if (!isNonEmptyString(command))
+            continue;
+        const normalized = normalizeCommand(command);
+        if (normalized === null)
+            continue;
+        // Preserve persisted source when present so task_statement stays capture-only (#3267).
+        const persistedSource = typeof rec.source === "string" && rec.source.trim().length > 0
+            ? rec.source.trim()
+            : source;
+        out.push({
+            command: normalized,
+            cwd: isNonEmptyString(rec.cwd) ? rec.cwd.trim() : null,
+            expectedStdout: isNonEmptyString(rec.expectedStdout)
+                ? rec.expectedStdout
+                : isNonEmptyString(rec.expected_stdout)
+                    ? rec.expected_stdout
+                    : null,
+            expectedExitCode: typeof rec.expectedExitCode === "number"
+                ? rec.expectedExitCode
+                : typeof rec.expected_exit_code === "number"
+                    ? rec.expected_exit_code
+                    : 0,
+            source: persistedSource,
+            sourceSpan: isNonEmptyString(rec.sourceSpan)
+                ? rec.sourceSpan
+                : isNonEmptyString(rec.source_span)
+                    ? rec.source_span
+                    : span,
+        });
+    }
+    return out;
+}
+function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+function isExecutableSource(source) {
+    return EXECUTABLE_LITERAL_SOURCES.includes(source);
+}
+/**
+ * Attach captured commands onto plan.metadata without paraphrasing.
+ * Merges with existing literal_acceptance_commands.
+ * Only agent-executable sources (not task_statement) are mirrored into
+ * swarm.verify_commands — issue text must be promoted explicitly (#3267).
+ * Returns a shallow-cloned plan with updated metadata.
+ */
+export function attachLiteralAcceptanceCommands(plan, commands, rejected = []) {
+    if (commands.length === 0 && rejected.length === 0) {
+        return plan;
+    }
+    const metadata = {
+        ...(asRecord(plan.metadata) ?? {}),
+    };
+    const existing = readStoredLiteralAcceptanceDetailed(plan);
+    const merged = mergeCommands(existing.commands, commands);
+    metadata.literal_acceptance_commands = merged.map(toSerializable);
+    // Rejected ledger: merge and persist for operator visibility.
+    const rejectedMerged = mergeRejected(existing.rejected, rejected);
+    if (rejectedMerged.length > 0) {
+        metadata[LITERAL_ACCEPTANCE_REJECTED_METADATA_KEY] = rejectedMerged.map((r) => {
+            const row = { command: r.command, reason: r.reason };
+            if (r.sourceSpan !== null && r.sourceSpan !== undefined && r.sourceSpan.length > 0) {
+                row.sourceSpan = r.sourceSpan;
+            }
+            return row;
+        });
+    }
+    // Keep swarm.verify_commands in sync only for executable (agent-authored) sources.
+    // task_statement stays capture-only until an agent promotes exact strings (#3267).
+    const swarm = { ...(asRecord(metadata.swarm) ?? {}) };
+    const executableCmds = merged.filter((c) => isExecutableSource(c.source)).map((c) => c.command);
+    const prevVerify = Array.isArray(swarm.verify_commands)
+        ? swarm.verify_commands.filter((x) => typeof x === "string")
+        : [];
+    const verifyMerged = [...prevVerify];
+    for (const cmd of executableCmds) {
+        if (!verifyMerged.includes(cmd))
+            verifyMerged.push(cmd);
+    }
+    if (verifyMerged.length > 0) {
+        swarm.verify_commands = verifyMerged;
+    }
+    metadata.swarm = swarm;
+    return {
+        ...plan,
+        metadata,
+    };
+}
+/**
+ * Capture from task statement text and attach onto a plan (intake helper).
+ */
+export function captureAndAttachLiteralAcceptance(plan, taskStatement) {
+    const captured = captureLiteralAcceptanceCommandsDetailed(taskStatement);
+    if (captured.commands.length === 0 && captured.rejected.length === 0) {
+        const stored = readStoredLiteralAcceptanceDetailed(plan);
+        return { plan, commands: stored.commands, rejected: stored.rejected };
+    }
+    const next = attachLiteralAcceptanceCommands(plan, captured.commands, captured.rejected);
+    const stored = readStoredLiteralAcceptanceDetailed(next);
+    return { plan: next, commands: stored.commands, rejected: stored.rejected };
+}
+function mergeCommands(a, b) {
+    const seen = new Set();
+    const out = [];
+    for (const cmd of [...a, ...b]) {
+        const key = commandDedupeKey(cmd);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(cmd);
+    }
+    return out;
+}
+function mergeRejected(a, b) {
+    const seen = new Set();
+    const out = [];
+    for (const r of [...a, ...b]) {
+        const key = `${r.command}\0${r.reason}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(r);
+    }
+    return out;
+}
+function toSerializable(cmd) {
+    const row = {
+        command: cmd.command,
+        source: cmd.source,
+    };
+    if (cmd.cwd !== null && cmd.cwd !== undefined && cmd.cwd.length > 0) {
+        row.cwd = cmd.cwd;
+    }
+    if (cmd.expectedStdout !== null &&
+        cmd.expectedStdout !== undefined &&
+        cmd.expectedStdout.length > 0) {
+        row.expectedStdout = cmd.expectedStdout;
+    }
+    if (cmd.expectedExitCode !== undefined && cmd.expectedExitCode !== 0) {
+        row.expectedExitCode = cmd.expectedExitCode;
+    }
+    if (cmd.sourceSpan !== null && cmd.sourceSpan !== undefined && cmd.sourceSpan.length > 0) {
+        row.sourceSpan = cmd.sourceSpan;
+    }
+    return row;
+}
+/** Format rejected ledger for CLI / complete-gate messages. */
+export function formatRejectedLedger(rejected) {
+    if (rejected.length === 0)
+        return "";
+    const lines = rejected.map((r) => {
+        const span = r.sourceSpan !== null && r.sourceSpan !== undefined ? ` @${r.sourceSpan}` : "";
+        return `  ✗ rejected: ${r.command}${span} — ${r.reason}`;
+    });
+    return (`Literal acceptance rejected ${rejected.length} shell-shaped command(s) (#3267 safety ledger):\n` +
+        lines.join("\n"));
+}
+//# sourceMappingURL=capture.js.map

package/dist/literal-acceptance/evaluate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Evaluate literal acceptance-command gate from an xBRIEF plan or path (#3267).
+ */
+import type { LiteralAcceptanceCommand, LiteralAcceptanceGateResult, LiteralAcceptanceRunner, RejectedLiteralCommand } from "./types.js";
+export interface EvaluateLiteralAcceptanceOptions {
+    readonly projectRoot?: string;
+    readonly runner?: LiteralAcceptanceRunner;
+    /**
+     * When true and the plan has no stored commands, re-scan Overview/Description
+     * narratives for stated commands (intake recovery). Default true.
+     */
+    readonly captureFromNarratives?: boolean;
+    /** Quiet success (empty message on pass). */
+    readonly quiet?: boolean;
+}
+/**
+ * Resolve commands + rejected ledger.
+ * Stored first; when captureFromNarratives is true (default), also re-scan narratives
+ * and merge any newly stated commands so stored entries cannot hide AC updates
+ * (Greptile conf residual).
+ */
+export declare function resolveLiteralAcceptanceDetailed(plan: Record<string, unknown>, options?: {
+    readonly captureFromNarratives?: boolean;
+}): {
+    readonly commands: readonly LiteralAcceptanceCommand[];
+    readonly rejected: readonly RejectedLiteralCommand[];
+};
+/**
+ * Resolve commands: stored first; optional narrative re-capture when empty.
+ */
+export declare function resolveLiteralAcceptanceCommands(plan: Record<string, unknown>, options?: {
+    readonly captureFromNarratives?: boolean;
+}): LiteralAcceptanceCommand[];
+/**
+ * Evaluate from an in-memory plan object.
+ */
+export declare function evaluateLiteralAcceptanceFromPlan(plan: Record<string, unknown>, options?: EvaluateLiteralAcceptanceOptions): LiteralAcceptanceGateResult;
+/**
+ * Evaluate from an xBRIEF JSON file path.
+ */
+export declare function evaluateLiteralAcceptanceFromPath(xbriefPath: string, options?: EvaluateLiteralAcceptanceOptions): LiteralAcceptanceGateResult;
+/**
+ * Pure ceremony-dial contract helper: literal AC run is required at every depth
+ * including rapid/minimal (#3267 / #3214 / #3156).
+ */
+export declare function isLiteralAcceptanceRequiredAtCeremonyDepth(_depth: string | null | undefined): boolean;
+//# sourceMappingURL=evaluate.d.ts.map