@deftai/directive-core 0.99.0 → 0.101.0

package/dist/literal-acceptance/safety.js

@@ -0,0 +1,251 @@
+/**
+ * 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 { EXECUTABLE_LITERAL_SOURCES } from "./types.js";
+/** Characters that imply shell composition / expansion (refuse closed). */
+const SHELL_META_CHARS = new Set([
+    ";",
+    "|",
+    "&",
+    "`",
+    "\n",
+    "\r",
+    "<",
+    ">",
+    "(",
+    ")",
+    "{",
+    "}",
+    "$",
+    "\0",
+]);
+/**
+ * First-token allowlist for **execution** (#3267 Greptile P1 ambient-authority).
+ * Network/SCM tools (curl/gh/git/docker) are intentionally excluded — they retain
+ * ambient credentials. Capture may still record broader CLI shape; only these
+ * tokens may spawn, and wrappers/PMs require subcommand allowlists below.
+ */
+const ALLOWED_FIRST_TOKENS = new Set([
+    "task",
+    "deft",
+    "directive",
+    "pnpm",
+    "npm",
+    "npx",
+    "yarn",
+    "bun",
+    "vitest",
+    "true",
+    "false",
+]);
+/**
+ * Exact wrapper subcommands that are verification-shaped (no scope/policy/scm/swarm
+ * mutations). Additional args after these tokens are allowed (e.g. `task check --json`).
+ */
+const ALLOWED_WRAPPER_SUBCOMMANDS = new Set([
+    "check",
+    "doctor",
+    "help",
+    "--help",
+    "-h",
+    "--version",
+    "-v",
+    "test",
+]);
+/**
+ * Prefixes for wrapper verbs that stay on the verify/read surface.
+ * `verify:` / `verify-` cover task verify:* family; bare `verify ` is the space form.
+ */
+const ALLOWED_WRAPPER_PREFIXES = ["verify:", "verify-", "verify "];
+/** Whether this provenance is allowed to spawn a shell (#3267). */
+export function isExecutableLiteralSource(source) {
+    return EXECUTABLE_LITERAL_SOURCES.includes(source);
+}
+/**
+ * Linear-time scan: refuse shell metacharacters and non-allowlisted first tokens.
+ * Intentionally does not parse full shell grammar — fail closed on ambiguity.
+ */
+export function evaluateCommandSafety(command) {
+    if (typeof command !== "string" || command.trim().length === 0) {
+        return { ok: false, reason: "empty command" };
+    }
+    const trimmed = command.trim();
+    if (trimmed.length > 500) {
+        return { ok: false, reason: "command exceeds 500 characters" };
+    }
+    for (let i = 0; i < trimmed.length; i += 1) {
+        const ch = trimmed[i];
+        if (SHELL_META_CHARS.has(ch)) {
+            return {
+                ok: false,
+                reason: `shell metacharacter ${JSON.stringify(ch)} is not allowed in literal AC commands`,
+            };
+        }
+    }
+    let end = 0;
+    while (end < trimmed.length && trimmed[end] !== " " && trimmed[end] !== "\t") {
+        end += 1;
+    }
+    const first = trimmed.slice(0, end).toLowerCase();
+    if (first.includes("/") || first.includes("\\") || first.includes(":")) {
+        return { ok: false, reason: "path-like first token is not allowlisted" };
+    }
+    if (!ALLOWED_FIRST_TOKENS.has(first)) {
+        return {
+            ok: false,
+            reason: `first token ${JSON.stringify(first)} is not in the literal-AC allowlist`,
+        };
+    }
+    const rest = trimmed.slice(end).trim();
+    // Framework wrappers: only verification / help / version subcommands (no scope/policy/merge).
+    if (first === "task" || first === "deft" || first === "directive") {
+        return evaluateWrapperSubcommand(rest);
+    }
+    // Package managers: only test/exec vitest/run test|check|--version (no install/publish/net).
+    // npx is stricter (no run/exec registry forms) — see evaluatePackageManagerArgs.
+    if (first === "pnpm" ||
+        first === "npm" ||
+        first === "npx" ||
+        first === "yarn" ||
+        first === "bun") {
+        return evaluatePackageManagerArgs(rest, first);
+    }
+    // vitest first-token: allow run / related test args only (no watch/ui).
+    if (first === "vitest") {
+        return evaluateVitestArgs(rest);
+    }
+    return { ok: true, reason: null };
+}
+/**
+ * Restrict task/deft/directive to verification-shaped subcommands.
+ * Fail closed on scope/policy/swarm/pr/scm/lifecycle mutations.
+ */
+function evaluateWrapperSubcommand(rest) {
+    if (rest.length === 0) {
+        return {
+            ok: false,
+            reason: "wrapper verb (task/deft/directive) requires a restricted verification subcommand",
+        };
+    }
+    const low = rest.toLowerCase();
+    // First subcommand token (before flags/args).
+    let subEnd = 0;
+    while (subEnd < low.length && low[subEnd] !== " " && low[subEnd] !== "\t") {
+        subEnd += 1;
+    }
+    const sub = low.slice(0, subEnd);
+    if (ALLOWED_WRAPPER_SUBCOMMANDS.has(sub)) {
+        return { ok: true, reason: null };
+    }
+    for (const prefix of ALLOWED_WRAPPER_PREFIXES) {
+        if (low.startsWith(prefix)) {
+            return { ok: true, reason: null };
+        }
+    }
+    return {
+        ok: false,
+        reason: "wrapper subcommand must be check|doctor|verify:*|help|--version " +
+            "(scope/policy/swarm/scm/merge and other ambient-authority verbs denied)",
+    };
+}
+/**
+ * Package-manager subcommand allowlist (no install/publish/exec of arbitrary bins).
+ * `npx` is stricter than npm/pnpm/yarn/bun: it must not accept `run`/`exec` forms that
+ * resolve arbitrary registry packages with inherited env (Greptile conf residual).
+ */
+function evaluatePackageManagerArgs(rest, firstToken) {
+    if (rest.length === 0) {
+        return { ok: false, reason: "package manager requires a restricted subcommand" };
+    }
+    const low = rest.toLowerCase();
+    // npx: only vitest (direct) or version/help — no `npx run` / `npx exec <pkg>` registry path.
+    if (firstToken === "npx") {
+        if (low === "--version" || low === "-v" || low === "--help" || low === "-h") {
+            return { ok: true, reason: null };
+        }
+        if (low === "vitest" || low.startsWith("vitest ")) {
+            const after = low === "vitest" ? "" : low.slice("vitest".length).trim();
+            return evaluateVitestArgs(after);
+        }
+        return {
+            ok: false,
+            reason: "npx is limited to vitest|--version|--help " +
+                "(npx run/exec/registry packages denied for ambient-authority)",
+        };
+    }
+    // exec: only vitest (not deft/task — those re-open wrapper ambient authority).
+    if (low.startsWith("exec ")) {
+        const afterExec = low.slice("exec ".length).trim();
+        if (afterExec === "vitest" || afterExec.startsWith("vitest ")) {
+            const after = afterExec === "vitest" ? "" : afterExec.slice("vitest".length).trim();
+            return evaluateVitestArgs(after);
+        }
+        return {
+            ok: false,
+            reason: "package-manager exec is limited to vitest " +
+                "(exec of deft/task/other bins denied for ambient-authority)",
+        };
+    }
+    if (low.startsWith("run vitest")) {
+        const after = low.slice("run vitest".length).trim();
+        return evaluateVitestArgs(after.length > 0 ? `run ${after}` : "run");
+    }
+    const allowedPm = low === "test" ||
+        low === "--version" ||
+        low === "-v" ||
+        low.startsWith("test ") ||
+        low.startsWith("run test") ||
+        low.startsWith("run check");
+    if (!allowedPm) {
+        return {
+            ok: false,
+            reason: "package-manager args must be test|exec vitest|run test|run check|--version " +
+                "(arbitrary scripts/network install denied for ambient-authority)",
+        };
+    }
+    return { ok: true, reason: null };
+}
+/**
+ * Vitest args: only non-interactive run paths. Deny watch/ui/browser hang modes.
+ */
+function evaluateVitestArgs(rest) {
+    const low = rest.trim().toLowerCase();
+    if (low.length === 0) {
+        // bare `vitest` defaults to watch in many setups — refuse closed.
+        return {
+            ok: false,
+            reason: "vitest requires explicit run (bare vitest defaults to watch; denied)",
+        };
+    }
+    for (const bad of ["watch", "ui", "browser", "--watch", "--ui", "--browser", "dev"]) {
+        if (low === bad ||
+            low.startsWith(`${bad} `) ||
+            low.endsWith(` ${bad}`) ||
+            low.includes(` ${bad} `)) {
+            return {
+                ok: false,
+                reason: `vitest ${bad} is denied (hang/interactive mode; use run)`,
+            };
+        }
+    }
+    if (low === "run" ||
+        low.startsWith("run ") ||
+        low === "--version" ||
+        low === "-v" ||
+        low.startsWith("--run")) {
+        return { ok: true, reason: null };
+    }
+    return {
+        ok: false,
+        reason: "vitest args must be run|--version (watch/ui/network denied for ambient-authority)",
+    };
+}
+//# sourceMappingURL=safety.js.map

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

@@ -0,0 +1,82 @@
+/**
+ * Literal acceptance-command verification (#3267).
+ *
+ * Capture exact stated shell commands from the task statement at intake;
+ * run them verbatim before done. Self-chosen verification is supplementary.
+ * Extends #973 machine-verifiable-spec. Survives ceremony dial rapid/minimal
+ * (#3214) — verification depth is constant (#3156).
+ */
+/** Where a literal command was recovered from. */
+export type LiteralAcceptanceSource = "task_statement" | "verify_commands" | "plan_item" | "explicit" | "metadata";
+/**
+ * Sources trusted for automatic shell execution (#3267 Greptile P1).
+ * `task_statement` (raw issue/task text) is capture-only until an agent promotes
+ * the exact command into swarm.verify_commands / plan item / explicit metadata.
+ */
+export declare const EXECUTABLE_LITERAL_SOURCES: readonly LiteralAcceptanceSource[];
+/**
+ * One executable acceptance command exactly as stated (no paraphrase).
+ * `command` is the shell string to run with the same flags/cwd as written.
+ */
+export interface LiteralAcceptanceCommand {
+    /** Exact command string from the task statement (not reworded). */
+    readonly command: string;
+    /**
+     * Working directory relative to project root when stated; null/omit = project root.
+     * Absolute paths are allowed when the statement uses them.
+     */
+    readonly cwd?: string | null;
+    /** Expected stdout substring when the statement names expected output. */
+    readonly expectedStdout?: string | null;
+    /** Expected process exit code (default 0). */
+    readonly expectedExitCode?: number;
+    readonly source: LiteralAcceptanceSource;
+    /** Short provenance (heading, field path, or line context). */
+    readonly sourceSpan?: string | null;
+}
+/** Result of running one stored command. */
+export interface LiteralAcceptanceRunResult {
+    readonly command: string;
+    readonly cwd: string;
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly ok: boolean;
+    readonly detail: string;
+}
+/**
+ * Shell-shaped command that was refused by the safety allowlist (#3267 residual).
+ * Operators must see these — silent drop hides ambient-authority / shape mistakes.
+ */
+export interface RejectedLiteralCommand {
+    readonly command: string;
+    readonly reason: string;
+    readonly sourceSpan?: string | null;
+}
+/** Aggregate evaluate / done-gate result. */
+export interface LiteralAcceptanceGateResult {
+    readonly ok: boolean;
+    /** 0 = pass or no commands; 1 = command failed; 2 = config / input error. */
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly commands: readonly LiteralAcceptanceCommand[];
+    readonly runs: readonly LiteralAcceptanceRunResult[];
+    /** Safety-rejected shell-shaped lines (fail-loud ledger; may be empty). */
+    readonly rejected?: readonly RejectedLiteralCommand[];
+}
+/** Metadata key for operator-visible rejected command ledger (#3267). */
+export declare const LITERAL_ACCEPTANCE_REJECTED_METADATA_KEY: "literal_acceptance_rejected";
+/** Injectable shell runner for tests (default: spawnSync shell). */
+export type LiteralAcceptanceRunner = (input: {
+    readonly command: string;
+    readonly cwd: string;
+}) => {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+};
+/** Metadata key on plan.metadata for captured literal commands (#3267). */
+export declare const LITERAL_ACCEPTANCE_METADATA_KEY: "literal_acceptance_commands";
+/** Alternate camelCase key accepted on read. */
+export declare const LITERAL_ACCEPTANCE_METADATA_KEY_CAMEL: "literalAcceptanceCommands";
+//# sourceMappingURL=types.d.ts.map

package/dist/literal-acceptance/types.js

@@ -0,0 +1,26 @@
+/**
+ * Literal acceptance-command verification (#3267).
+ *
+ * Capture exact stated shell commands from the task statement at intake;
+ * run them verbatim before done. Self-chosen verification is supplementary.
+ * Extends #973 machine-verifiable-spec. Survives ceremony dial rapid/minimal
+ * (#3214) — verification depth is constant (#3156).
+ */
+/**
+ * Sources trusted for automatic shell execution (#3267 Greptile P1).
+ * `task_statement` (raw issue/task text) is capture-only until an agent promotes
+ * the exact command into swarm.verify_commands / plan item / explicit metadata.
+ */
+export const EXECUTABLE_LITERAL_SOURCES = [
+    "verify_commands",
+    "plan_item",
+    "explicit",
+    "metadata",
+];
+/** Metadata key for operator-visible rejected command ledger (#3267). */
+export const LITERAL_ACCEPTANCE_REJECTED_METADATA_KEY = "literal_acceptance_rejected";
+/** Metadata key on plan.metadata for captured literal commands (#3267). */
+export const LITERAL_ACCEPTANCE_METADATA_KEY = "literal_acceptance_commands";
+/** Alternate camelCase key accepted on read. */
+export const LITERAL_ACCEPTANCE_METADATA_KEY_CAMEL = "literalAcceptanceCommands";
+//# sourceMappingURL=types.js.map

package/dist/policy/ac-pass-banking.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Typed plan.policy.acPassBanking (#3285).
+ *
+ * Surplus-threshold policy for post-AC-pass deepening: after the first
+ * stated-AC bank, agents may deepen only when remaining budget is at least
+ * this fraction of the hard max (default 0.2 = 20%).
+ *
+ * Composes #3266 bank-the-pass and product-first done-gate (#3284).
+ */
+/** Canonical dotted path for policy:show / PROJECT-DEFINITION. */
+export declare const FIELD_AC_PASS_BANKING = "plan.policy.acPassBanking";
+/** CLI alias for `task policy:show --field=acPassBanking`. */
+export declare const FIELD_AC_PASS_BANKING_CLI_ALIAS = "acPassBanking";
+/**
+ * Default surplus fraction of max turns/cost that must remain after bank
+ * before self-imposed deepening is allowed (#3285).
+ */
+export declare const DEFAULT_SURPLUS_THRESHOLD = 0.2;
+/** Floor / ceiling for surplusThreshold (inclusive). */
+export declare const SURPLUS_THRESHOLD_MIN = 0;
+export declare const SURPLUS_THRESHOLD_MAX = 1;
+/** Optional env override (fraction 0–1 or percent 0–100). */
+export declare const ENV_SURPLUS_THRESHOLD = "DEFT_AC_PASS_SURPLUS_THRESHOLD";
+export interface AcPassBankingConfig {
+    /**
+     * When false, surplus gate is inactive (unbounded / optional discipline only).
+     * Default true — the gate still only binds under a hard effort budget.
+     */
+    readonly enabled: boolean;
+    /**
+     * Minimum remaining fraction of max turns/cost required to deepen after bank.
+     * Default {@link DEFAULT_SURPLUS_THRESHOLD} (0.2).
+     */
+    readonly surplusThreshold: number;
+}
+export type AcPassBankingSource = "typed" | "env" | "default" | "default-on-error";
+export interface AcPassBankingResolved extends AcPassBankingConfig {
+    readonly source: AcPassBankingSource;
+    readonly error: string | null;
+}
+/** Parse a 0–1 fraction or a 0–100 percent string/number into a fraction. */
+export declare function parseSurplusThreshold(raw: unknown): number | null;
+/** Validate a `plan.policy.acPassBanking` payload. */
+export declare function validateAcPassBanking(value: unknown): string[];
+/**
+ * Resolve surplus policy from typed plan.policy.acPassBanking, then env,
+ * then defaults (#3285).
+ */
+export declare function resolveAcPassBanking(projectRoot?: string | null, environ?: Readonly<Record<string, string | undefined>>): AcPassBankingResolved;
+export interface AcPassBankingPolicyField {
+    readonly name: typeof FIELD_AC_PASS_BANKING;
+    readonly current: AcPassBankingConfig;
+    readonly default: AcPassBankingConfig;
+    readonly source: string;
+}
+/** Inspector row for `task policy:show --field=acPassBanking` (#3285). */
+export declare function inspectAcPassBanking(_data: Record<string, unknown> | null, projectRoot?: string): AcPassBankingPolicyField;
+//# sourceMappingURL=ac-pass-banking.d.ts.map

package/dist/policy/ac-pass-banking.js

@@ -0,0 +1,150 @@
+/**
+ * Typed plan.policy.acPassBanking (#3285).
+ *
+ * Surplus-threshold policy for post-AC-pass deepening: after the first
+ * stated-AC bank, agents may deepen only when remaining budget is at least
+ * this fraction of the hard max (default 0.2 = 20%).
+ *
+ * Composes #3266 bank-the-pass and product-first done-gate (#3284).
+ */
+import { readPlanPolicy } from "./plan-extensions.js";
+import { loadProjectDefinition } from "./resolve.js";
+/** Canonical dotted path for policy:show / PROJECT-DEFINITION. */
+export const FIELD_AC_PASS_BANKING = "plan.policy.acPassBanking";
+/** CLI alias for `task policy:show --field=acPassBanking`. */
+export const FIELD_AC_PASS_BANKING_CLI_ALIAS = "acPassBanking";
+/**
+ * Default surplus fraction of max turns/cost that must remain after bank
+ * before self-imposed deepening is allowed (#3285).
+ */
+export const DEFAULT_SURPLUS_THRESHOLD = 0.2;
+/** Floor / ceiling for surplusThreshold (inclusive). */
+export const SURPLUS_THRESHOLD_MIN = 0;
+export const SURPLUS_THRESHOLD_MAX = 1;
+/** Optional env override (fraction 0–1 or percent 0–100). */
+export const ENV_SURPLUS_THRESHOLD = "DEFT_AC_PASS_SURPLUS_THRESHOLD";
+function defaultResolved(source, error = null, override) {
+    return {
+        enabled: override?.enabled ?? true,
+        surplusThreshold: override?.surplusThreshold ?? DEFAULT_SURPLUS_THRESHOLD,
+        source,
+        error,
+    };
+}
+/** Parse a 0–1 fraction or a 0–100 percent string/number into a fraction. */
+export function parseSurplusThreshold(raw) {
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        if (raw >= 0 && raw <= 1)
+            return raw;
+        // Allow 20 meaning 20% when clearly a percent.
+        if (raw > 1 && raw <= 100)
+            return raw / 100;
+        return null;
+    }
+    if (typeof raw === "string") {
+        const text = raw.trim();
+        if (!text)
+            return null;
+        const percent = text.endsWith("%");
+        const n = Number(percent ? text.slice(0, -1).trim() : text);
+        if (!Number.isFinite(n))
+            return null;
+        if (percent) {
+            if (n < 0 || n > 100)
+                return null;
+            return n / 100;
+        }
+        if (n >= 0 && n <= 1)
+            return n;
+        if (n > 1 && n <= 100)
+            return n / 100;
+        return null;
+    }
+    return null;
+}
+/** Validate a `plan.policy.acPassBanking` payload. */
+export function validateAcPassBanking(value) {
+    if (value === null || value === undefined) {
+        return [];
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return [`${FIELD_AC_PASS_BANKING} must be an object; got ${typeof value}`];
+    }
+    const rec = value;
+    const errors = [];
+    if ("enabled" in rec && typeof rec.enabled !== "boolean") {
+        errors.push(`${FIELD_AC_PASS_BANKING}.enabled must be a boolean`);
+    }
+    if ("surplusThreshold" in rec) {
+        const parsed = parseSurplusThreshold(rec.surplusThreshold);
+        if (parsed === null) {
+            errors.push(`${FIELD_AC_PASS_BANKING}.surplusThreshold must be a fraction 0–1 ` +
+                `(or percent 0–100); got ${JSON.stringify(rec.surplusThreshold)}`);
+        }
+    }
+    return errors;
+}
+/**
+ * Resolve surplus policy from typed plan.policy.acPassBanking, then env,
+ * then defaults (#3285).
+ */
+export function resolveAcPassBanking(projectRoot, environ = process.env) {
+    if (projectRoot !== undefined && projectRoot !== null && projectRoot.length > 0) {
+        const [data, err] = loadProjectDefinition(projectRoot);
+        if (data !== null) {
+            const policyBlock = readPlanPolicy(data.plan);
+            if (typeof policyBlock === "object" &&
+                policyBlock !== null &&
+                !Array.isArray(policyBlock) &&
+                "acPassBanking" in policyBlock) {
+                const raw = policyBlock.acPassBanking;
+                const errors = validateAcPassBanking(raw);
+                if (errors.length > 0) {
+                    return defaultResolved("default-on-error", errors[0] ?? "invalid acPassBanking");
+                }
+                if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+                    const rec = raw;
+                    const enabled = typeof rec.enabled === "boolean" ? rec.enabled : true;
+                    const threshold = "surplusThreshold" in rec
+                        ? (parseSurplusThreshold(rec.surplusThreshold) ?? DEFAULT_SURPLUS_THRESHOLD)
+                        : DEFAULT_SURPLUS_THRESHOLD;
+                    return {
+                        enabled,
+                        surplusThreshold: threshold,
+                        source: "typed",
+                        error: null,
+                    };
+                }
+            }
+        }
+        else if (err !== null && err.length > 0) {
+            // Fall through to env/default; record nothing as fatal.
+        }
+    }
+    const envRaw = environ[ENV_SURPLUS_THRESHOLD];
+    if (envRaw !== undefined && envRaw.trim() !== "") {
+        const parsed = parseSurplusThreshold(envRaw);
+        if (parsed !== null) {
+            return defaultResolved("env", null, { surplusThreshold: parsed });
+        }
+        return defaultResolved("default-on-error", `${ENV_SURPLUS_THRESHOLD} is not a valid fraction/percent: ${envRaw}`);
+    }
+    return defaultResolved("default");
+}
+/** Inspector row for `task policy:show --field=acPassBanking` (#3285). */
+export function inspectAcPassBanking(_data, projectRoot) {
+    const resolved = resolveAcPassBanking(projectRoot);
+    return {
+        name: FIELD_AC_PASS_BANKING,
+        current: {
+            enabled: resolved.enabled,
+            surplusThreshold: resolved.surplusThreshold,
+        },
+        default: {
+            enabled: true,
+            surplusThreshold: DEFAULT_SURPLUS_THRESHOLD,
+        },
+        source: resolved.source,
+    };
+}
+//# sourceMappingURL=ac-pass-banking.js.map