@deftai/directive-core 0.99.0 → 0.100.0

package/dist/literal-acceptance/evaluate.js

@@ -0,0 +1,193 @@
+/**
+ * Evaluate literal acceptance-command gate from an xBRIEF plan or path (#3267).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { captureLiteralAcceptanceCommandsDetailed, formatRejectedLedger, readStoredLiteralAcceptanceDetailed, } from "./capture.js";
+import { runLiteralAcceptanceCommands } from "./run.js";
+function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+function planOf(data) {
+    return asRecord(data.plan);
+}
+/**
+ * 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 function resolveLiteralAcceptanceDetailed(plan, options = {}) {
+    const stored = readStoredLiteralAcceptanceDetailed(plan);
+    if (options.captureFromNarratives === false) {
+        return stored;
+    }
+    const narratives = asRecord(plan.narratives);
+    if (narratives === null) {
+        return stored;
+    }
+    const parts = [];
+    for (const key of [
+        "Overview",
+        "Description",
+        "Acceptance",
+        "UserStory",
+        "ImplementationPlan",
+        "AcceptanceJustification",
+    ]) {
+        if (typeof narratives[key] === "string") {
+            parts.push(narratives[key]);
+        }
+    }
+    if (parts.length === 0)
+        return stored;
+    const captured = captureLiteralAcceptanceCommandsDetailed(parts.join("\n\n"));
+    // Merge commands: keep stored (richer context) first; add narrative captures by
+    // composite key (command+cwd+exit) so new stated lines are not suppressed.
+    const cmdKey = (c) => {
+        const cwd = c.cwd !== null && c.cwd !== undefined && c.cwd.trim().length > 0 ? c.cwd.trim() : "";
+        const exit = typeof c.expectedExitCode === "number" ? c.expectedExitCode : 0;
+        return `${c.command}\0${cwd}\0${exit}`;
+    };
+    const seen = new Set(stored.commands.map(cmdKey));
+    const commands = [...stored.commands];
+    for (const c of captured.commands) {
+        const k = cmdKey(c);
+        if (seen.has(k))
+            continue;
+        // Also skip pure command-string dupes already stored (any cwd) so narrative
+        // re-capture does not invent a second null-cwd twin of an explicit row.
+        if (commands.some((s) => s.command === c.command))
+            continue;
+        seen.add(k);
+        commands.push(c);
+    }
+    const rejectedSeen = new Set(stored.rejected.map((r) => `${r.command}\0${r.reason}`));
+    const rejected = [...stored.rejected];
+    for (const r of captured.rejected) {
+        const k = `${r.command}\0${r.reason}`;
+        if (rejectedSeen.has(k))
+            continue;
+        rejectedSeen.add(k);
+        rejected.push(r);
+    }
+    return { commands, rejected };
+}
+/**
+ * Resolve commands: stored first; optional narrative re-capture when empty.
+ */
+export function resolveLiteralAcceptanceCommands(plan, options = {}) {
+    return [...resolveLiteralAcceptanceDetailed(plan, options).commands];
+}
+function appendRejectedNote(message, rejected) {
+    const ledger = formatRejectedLedger(rejected);
+    if (ledger.length === 0)
+        return message;
+    if (message.length === 0)
+        return ledger;
+    return `${message}\n${ledger}`;
+}
+/**
+ * Evaluate from an in-memory plan object.
+ */
+export function evaluateLiteralAcceptanceFromPlan(plan, options = {}) {
+    const projectRoot = resolve(options.projectRoot ?? process.cwd());
+    const resolved = resolveLiteralAcceptanceDetailed(plan, {
+        captureFromNarratives: options.captureFromNarratives,
+    });
+    const result = runLiteralAcceptanceCommands(resolved.commands, {
+        projectRoot,
+        runner: options.runner,
+    });
+    // Rejected stated commands are fail-closed for completion (#3267 Greptile conf residual).
+    // A safety-rejected shell-shaped acceptance line is not "optional diagnostic" — operators
+    // must promote a safe alternative or remove the stated command from the task statement.
+    let ok = result.ok;
+    let code = result.code;
+    let message = appendRejectedNote(result.message, resolved.rejected);
+    if (resolved.rejected.length > 0) {
+        ok = false;
+        if (code === 0)
+            code = 1;
+        const ledger = formatRejectedLedger(resolved.rejected);
+        message =
+            `Literal acceptance-command gate FAILED (#3267): ${resolved.rejected.length} ` +
+                `safety-rejected stated command(s) block completion until resolved ` +
+                `(promote a safe alternative or remove from the task statement).\n` +
+                ledger +
+                (result.message.length > 0 ? `\n${result.message}` : "");
+    }
+    const withRejected = {
+        ...result,
+        ok,
+        code,
+        rejected: resolved.rejected,
+        message,
+    };
+    if (options.quiet === true && withRejected.ok) {
+        return { ...withRejected, message: "" };
+    }
+    return withRejected;
+}
+/**
+ * Evaluate from an xBRIEF JSON file path.
+ */
+export function evaluateLiteralAcceptanceFromPath(xbriefPath, options = {}) {
+    const abs = resolve(xbriefPath);
+    if (!existsSync(abs)) {
+        return {
+            ok: false,
+            code: 2,
+            message: `Literal acceptance-command gate: xBRIEF not found: ${abs}`,
+            commands: [],
+            runs: [],
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(abs, "utf8"));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            code: 2,
+            message: `Literal acceptance-command gate: unreadable xBRIEF (${msg}): ${abs}`,
+            commands: [],
+            runs: [],
+        };
+    }
+    const data = asRecord(parsed);
+    if (data === null) {
+        return {
+            ok: false,
+            code: 2,
+            message: `Literal acceptance-command gate: xBRIEF top-level is not an object: ${abs}`,
+            commands: [],
+            runs: [],
+        };
+    }
+    const plan = planOf(data);
+    if (plan === null) {
+        return {
+            ok: false,
+            code: 2,
+            message: `Literal acceptance-command gate: xBRIEF missing plan object: ${abs}`,
+            commands: [],
+            runs: [],
+        };
+    }
+    return evaluateLiteralAcceptanceFromPlan(plan, options);
+}
+/**
+ * Pure ceremony-dial contract helper: literal AC run is required at every depth
+ * including rapid/minimal (#3267 / #3214 / #3156).
+ */
+export function isLiteralAcceptanceRequiredAtCeremonyDepth(_depth) {
+    // Verification depth is constant — dial never skips this check.
+    return true;
+}
+//# sourceMappingURL=evaluate.js.map

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

@@ -0,0 +1,12 @@
+/**
+ * Literal acceptance-command verification (#3267).
+ *
+ * Capture exact stated shell commands at intake; run them verbatim before done.
+ * Extends #973; survives ceremony dial rapid/minimal (#3214).
+ */
+export { attachLiteralAcceptanceCommands, type CaptureLiteralAcceptanceResult, captureAndAttachLiteralAcceptance, captureLiteralAcceptanceCommands, captureLiteralAcceptanceCommandsDetailed, formatRejectedLedger, readStoredLiteralAcceptanceCommands, readStoredLiteralAcceptanceDetailed, } from "./capture.js";
+export { type EvaluateLiteralAcceptanceOptions, evaluateLiteralAcceptanceFromPath, evaluateLiteralAcceptanceFromPlan, isLiteralAcceptanceRequiredAtCeremonyDepth, resolveLiteralAcceptanceCommands, resolveLiteralAcceptanceDetailed, } from "./evaluate.js";
+export { defaultLiteralAcceptanceRunner, runLiteralAcceptanceCommand, runLiteralAcceptanceCommands, } from "./run.js";
+export { type CommandSafetyResult, evaluateCommandSafety, isExecutableLiteralSource, } from "./safety.js";
+export { EXECUTABLE_LITERAL_SOURCES, LITERAL_ACCEPTANCE_METADATA_KEY, LITERAL_ACCEPTANCE_METADATA_KEY_CAMEL, LITERAL_ACCEPTANCE_REJECTED_METADATA_KEY, type LiteralAcceptanceCommand, type LiteralAcceptanceGateResult, type LiteralAcceptanceRunner, type LiteralAcceptanceRunResult, type LiteralAcceptanceSource, type RejectedLiteralCommand, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/literal-acceptance/index.js

@@ -0,0 +1,12 @@
+/**
+ * Literal acceptance-command verification (#3267).
+ *
+ * Capture exact stated shell commands at intake; run them verbatim before done.
+ * Extends #973; survives ceremony dial rapid/minimal (#3214).
+ */
+export { attachLiteralAcceptanceCommands, captureAndAttachLiteralAcceptance, captureLiteralAcceptanceCommands, captureLiteralAcceptanceCommandsDetailed, formatRejectedLedger, readStoredLiteralAcceptanceCommands, readStoredLiteralAcceptanceDetailed, } from "./capture.js";
+export { evaluateLiteralAcceptanceFromPath, evaluateLiteralAcceptanceFromPlan, isLiteralAcceptanceRequiredAtCeremonyDepth, resolveLiteralAcceptanceCommands, resolveLiteralAcceptanceDetailed, } from "./evaluate.js";
+export { defaultLiteralAcceptanceRunner, runLiteralAcceptanceCommand, runLiteralAcceptanceCommands, } from "./run.js";
+export { evaluateCommandSafety, isExecutableLiteralSource, } from "./safety.js";
+export { EXECUTABLE_LITERAL_SOURCES, LITERAL_ACCEPTANCE_METADATA_KEY, LITERAL_ACCEPTANCE_METADATA_KEY_CAMEL, LITERAL_ACCEPTANCE_REJECTED_METADATA_KEY, } from "./types.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,38 @@
+/**
+ * Run stored literal acceptance commands verbatim (#3267).
+ *
+ * Same flags, same cwd (project root unless the command record states otherwise).
+ * Fail closed on non-zero exit or missing expected stdout.
+ * Self-chosen verification is supplementary — this gate only runs stored literals.
+ */
+import type { LiteralAcceptanceCommand, LiteralAcceptanceGateResult, LiteralAcceptanceRunner, LiteralAcceptanceRunResult } from "./types.js";
+/** Default shell runner: exact command string via platform shell. */
+export declare function defaultLiteralAcceptanceRunner(input: {
+    readonly command: string;
+    readonly cwd: string;
+}): {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+/**
+ * Run one command record verbatim. Does not re-tokenize or rewrite the command string.
+ */
+export declare function runLiteralAcceptanceCommand(cmd: LiteralAcceptanceCommand, options: {
+    readonly projectRoot: string;
+    readonly runner?: LiteralAcceptanceRunner;
+}): LiteralAcceptanceRunResult;
+/**
+ * Run all stored commands in order. Fail closed if any fail.
+ * Empty command list → ok (nothing stated to verify).
+ */
+export declare function runLiteralAcceptanceCommands(commands: readonly LiteralAcceptanceCommand[], options: {
+    readonly projectRoot: string;
+    readonly runner?: LiteralAcceptanceRunner;
+    /**
+     * When true, allow source=task_statement (raw issue text) to spawn.
+     * Default false — issue text is capture-only until promoted (#3267 Greptile P1).
+     */
+    readonly allowTaskStatement?: boolean;
+}): LiteralAcceptanceGateResult;
+//# sourceMappingURL=run.d.ts.map

package/dist/literal-acceptance/run.js

@@ -0,0 +1,216 @@
+/**
+ * Run stored literal acceptance commands verbatim (#3267).
+ *
+ * Same flags, same cwd (project root unless the command record states otherwise).
+ * Fail closed on non-zero exit or missing expected stdout.
+ * Self-chosen verification is supplementary — this gate only runs stored literals.
+ */
+import { spawnSync } from "node:child_process";
+import { isAbsolute, resolve } from "node:path";
+import { evaluateCommandSafety, isExecutableLiteralSource } from "./safety.js";
+/** Default shell runner: exact command string via platform shell. */
+export function defaultLiteralAcceptanceRunner(input) {
+    // Windows: cmd.exe /c; POSIX: shell true uses sh -c. Exact string preserved.
+    const result = spawnSync(input.command, {
+        cwd: input.cwd,
+        encoding: "utf8",
+        shell: true,
+        env: process.env,
+        maxBuffer: 16 * 1024 * 1024,
+    });
+    const exitCode = typeof result.status === "number" ? result.status : result.error !== undefined ? 1 : 1;
+    return {
+        exitCode,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr: typeof result.stderr === "string"
+            ? result.stderr
+            : result.error instanceof Error
+                ? result.error.message
+                : "",
+    };
+}
+function resolveCwd(projectRoot, cmd) {
+    if (cmd.cwd === null || cmd.cwd === undefined || cmd.cwd.trim().length === 0) {
+        return resolve(projectRoot);
+    }
+    const raw = cmd.cwd.trim();
+    if (isAbsolute(raw))
+        return raw;
+    return resolve(projectRoot, raw);
+}
+/**
+ * Run one command record verbatim. Does not re-tokenize or rewrite the command string.
+ */
+export function runLiteralAcceptanceCommand(cmd, options) {
+    const cwd = resolveCwd(options.projectRoot, cmd);
+    const safety = evaluateCommandSafety(cmd.command);
+    if (!safety.ok) {
+        return {
+            command: cmd.command,
+            cwd,
+            exitCode: 2,
+            stdout: "",
+            stderr: safety.reason ?? "unsafe command",
+            ok: false,
+            detail: `refused: ${safety.reason ?? "unsafe command"}`,
+        };
+    }
+    const runner = options.runner ?? defaultLiteralAcceptanceRunner;
+    const result = runner({ command: cmd.command, cwd });
+    const expectedExit = cmd.expectedExitCode ?? 0;
+    let ok = result.exitCode === expectedExit;
+    let detail = ok
+        ? `exit ${result.exitCode} (expected ${expectedExit})`
+        : `exit ${result.exitCode} (expected ${expectedExit})`;
+    if (ok &&
+        cmd.expectedStdout !== null &&
+        cmd.expectedStdout !== undefined &&
+        cmd.expectedStdout.length > 0) {
+        if (!result.stdout.includes(cmd.expectedStdout)) {
+            ok = false;
+            detail = `stdout missing expected substring ${JSON.stringify(cmd.expectedStdout)}`;
+        }
+    }
+    return {
+        command: cmd.command,
+        cwd,
+        exitCode: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        ok,
+        detail,
+    };
+}
+/**
+ * Run all stored commands in order. Fail closed if any fail.
+ * Empty command list → ok (nothing stated to verify).
+ */
+export function runLiteralAcceptanceCommands(commands, options) {
+    if (commands.length === 0) {
+        return {
+            ok: true,
+            code: 0,
+            message: "Literal acceptance-command gate: no stated commands (nothing to run) (#3267)",
+            commands: [],
+            runs: [],
+        };
+    }
+    const untrusted = commands.filter((c) => c.source === "task_statement" && options.allowTaskStatement !== true);
+    const executable = commands.filter((c) => isExecutableLiteralSource(c.source) ||
+        (c.source === "task_statement" && options.allowTaskStatement === true));
+    // Fail closed: every capture-only stated command must have a matching agent-promoted
+    // peer with the same execution constraints (command + cwd + expectedStdout + exit).
+    // Command-text-only promotion must not drop cwd/expected-result (Greptile conf residual).
+    const promotionKey = (c) => {
+        const cwd = c.cwd !== null && c.cwd !== undefined && String(c.cwd).trim().length > 0
+            ? String(c.cwd).trim()
+            : "";
+        const stdout = c.expectedStdout !== null &&
+            c.expectedStdout !== undefined &&
+            String(c.expectedStdout).length > 0
+            ? String(c.expectedStdout)
+            : "";
+        const exit = typeof c.expectedExitCode === "number" ? c.expectedExitCode : 0;
+        return `${c.command}\0${cwd}\0${stdout}\0${exit}`;
+    };
+    const executableKeySet = new Set(executable.map(promotionKey));
+    // Also accept command-text match when both sides have default context (null cwd / exit 0),
+    // but never when the stated row carries a non-default constraint the peer lacks.
+    const unpromoted = untrusted.filter((c) => {
+        if (executableKeySet.has(promotionKey(c)))
+            return false;
+        // Strict: if stated has non-default context, require exact peer key only.
+        const hasContext = (c.cwd !== null && c.cwd !== undefined && String(c.cwd).trim().length > 0) ||
+            (c.expectedStdout !== null &&
+                c.expectedStdout !== undefined &&
+                String(c.expectedStdout).length > 0) ||
+            (typeof c.expectedExitCode === "number" && c.expectedExitCode !== 0);
+        if (hasContext)
+            return true;
+        // Default-context stated: require at least same command text among executables.
+        return !executable.some((e) => e.command === c.command);
+    });
+    if (unpromoted.length > 0) {
+        const listed = unpromoted
+            .map((c) => {
+            const bits = [`command=${JSON.stringify(c.command)}`];
+            if (c.cwd)
+                bits.push(`cwd=${JSON.stringify(c.cwd)}`);
+            if (c.expectedStdout)
+                bits.push(`expectedStdout=${JSON.stringify(c.expectedStdout)}`);
+            if (typeof c.expectedExitCode === "number" && c.expectedExitCode !== 0) {
+                bits.push(`expectedExitCode=${c.expectedExitCode}`);
+            }
+            return `  - ${bits.join(" ")} (source=${c.source})`;
+        })
+            .join("\n");
+        return {
+            ok: false,
+            code: 1,
+            message: `Literal acceptance-command gate FAILED (#3267): ${unpromoted.length} stated command(s) ` +
+                `are capture-only (source=task_statement) and have no matching agent-promoted peer.\n` +
+                `Promote the exact command strings (and cwd/expectedStdout/expectedExitCode when stated) ` +
+                `into plan.metadata.swarm.verify_commands (or plan item / explicit metadata), then re-run.\n` +
+                `Note: an unrelated executable peer or a same-text peer with different context does not waive.\n` +
+                listed,
+            commands,
+            runs: [],
+        };
+    }
+    if (executable.length === 0) {
+        return {
+            ok: true,
+            code: 0,
+            message: "Literal acceptance-command gate: no executable (agent-authored) commands (#3267)",
+            commands,
+            runs: [],
+        };
+    }
+    const runs = [];
+    for (const cmd of executable) {
+        if (typeof cmd.command !== "string" || cmd.command.trim().length === 0) {
+            return {
+                ok: false,
+                code: 2,
+                message: "Literal acceptance-command gate config error: empty command entry (#3267)",
+                commands,
+                runs,
+            };
+        }
+        runs.push(runLiteralAcceptanceCommand(cmd, options));
+    }
+    const failed = runs.filter((r) => !r.ok);
+    if (failed.length === 0) {
+        const lines = runs.map((r) => `  ✓ ${r.command} — ${r.detail}`);
+        // Untrusted that matched an executable peer were promoted for run; no skip note needed.
+        return {
+            ok: true,
+            code: 0,
+            message: `Literal acceptance-command gate passed (#3267): ${runs.length} command(s) run verbatim\n` +
+                lines.join("\n"),
+            commands,
+            runs,
+        };
+    }
+    const lines = runs.map((r) => {
+        const mark = r.ok ? "✓" : "✗";
+        const err = r.ok
+            ? r.detail
+            : `${r.detail}${r.stderr.trim().length > 0 ? `; stderr=${truncate(r.stderr, 200)}` : ""}`;
+        return `  ${mark} ${r.command} — ${err}`;
+    });
+    return {
+        ok: false,
+        code: 1,
+        message: `Literal acceptance-command gate FAILED (#3267): ${failed.length}/${runs.length} command(s) did not pass.\n` +
+            `Commands must run verbatim (same flags/cwd) — self-chosen verification is not a substitute.\n` +
+            lines.join("\n"),
+        commands,
+        runs,
+    };
+}
+function truncate(s, max) {
+    const t = s.replace(/\s+/g, " ").trim();
+    return t.length <= max ? t : `${t.slice(0, max)}…`;
+}
+//# sourceMappingURL=run.js.map

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

@@ -0,0 +1,24 @@
+/**
+ * Safety filters for literal acceptance commands (#3267 Greptile P1).
+ *
+ * Stored commands may originate from issue text. Before shell execution they
+ * MUST pass an allowlist of argv-shaped CLI invocations without shell metacharacters.
+ * source=task_statement is capture-only until agent promotes to verify_commands.
+ *
+ * Wrapper verbs (task/deft/directive) and package managers are further restricted
+ * to read-only / verification subcommands so ambient credentials and lifecycle
+ * mutations cannot ride an acceptance command (#3267 residual).
+ */
+import type { LiteralAcceptanceSource } from "./types.js";
+export interface CommandSafetyResult {
+    readonly ok: boolean;
+    readonly reason: string | null;
+}
+/** Whether this provenance is allowed to spawn a shell (#3267). */
+export declare function isExecutableLiteralSource(source: LiteralAcceptanceSource | string): boolean;
+/**
+ * Linear-time scan: refuse shell metacharacters and non-allowlisted first tokens.
+ * Intentionally does not parse full shell grammar — fail closed on ambiguity.
+ */
+export declare function evaluateCommandSafety(command: string): CommandSafetyResult;
+//# sourceMappingURL=safety.d.ts.map