@deftai/directive-core 0.99.0 → 0.100.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/ceremony-dial.d.ts

@@ -1,5 +1,5 @@
 /**
- * Ceremony dial (#3214): ritual depth = f(task size × model tier × project shape).
+ * Ceremony dial (#3214 / #3263): ritual depth = f(task size × model tier × project shape).
  *
  * Selection policy over existing pieces — not a new subsystem.
  * Composes:
@@ -7,11 +7,15 @@
  *   - #3014 minimal consumer AGENTS profile (research pointer; not yet a shipped deposit)
  *   - effort estimate (#1581), model routing (#1976/#818), host capability (#1461)
  *
- * Two-stage dial (#3214 design note / #1581 ordering):
- *   cold-start / incomplete inputs → **rapid** (start light; no plan-item deadlock)
- *   escalate when evidence arrives (provisional M/L, mid/low tier, full matrix)
+ * Two-stage dial (#3214 design note / #1581 ordering) with tier-conditional cold-start (#3263):
+ *   cold-start / incomplete size → **tier-conditional**:
+ *     frontier (or unknown tier) → rapid; mid/low → standard (not rapid)
+ *   escalate when evidence arrives (provisional M/L size, full matrix)
  * Full matrix: S × frontier → rapid; non-project → minimal; else scales up.
  * Override always available via plan.policy.ceremonyDial.override; audited on write.
+ *
+ * Audit path (#3263): session:start records depth + provisional reasons on
+ * `.deft/ritual-state.json` under `ceremony_dial` — use `readCeremonyDialAudit`.
  */
 /** Canonical dotted policy field name. */
 export declare const FIELD_CEREMONY_DIAL = "plan.policy.ceremonyDial";
@@ -60,6 +64,11 @@ export interface CeremonyDialProfile {
     readonly skipFatPath: boolean;
     /** How much lifecycle / history write budget this depth intends. */
     readonly lifecycleWrites: "minimal" | "light" | "full";
+    /**
+     * Literal acceptance-command verification is always required (#3267 / #3156).
+     * Ceremony dial never skips capture+verbatim run — including rapid/minimal.
+     */
+    readonly literalAcceptanceRequired: true;
     readonly label: string;
 }
 export type CeremonyDialSource = "override" | "matrix" | "default" | "disabled" | "typed" | "default-on-error";
@@ -97,25 +106,38 @@ export declare function normalizeCeremonyTaskSize(raw: unknown): CeremonyTaskSiz
 export declare function normalizeCeremonyModelTier(raw: unknown): CeremonyModelTier | null;
 export declare function normalizeCeremonyProjectShape(raw: unknown): CeremonyProjectShape | null;
 /**
- * Two-stage / partial-evidence selection when size or tier is missing (#3214 design note).
+ * Tier-conditional cold-start depth when task size is incomplete (#3263).
+ *
+ * Mid/low models benefit from structure on hard tasks and should not cold-start
+ * at rapid (start-light / escalate-too-late signature). Frontier recovers from a
+ * light start. Unknown tier stays rapid (optimistic cold default; pass
+ * `--model-tier` / `DEFT_CEREMONY_MODEL_TIER` to unlock the mid/low floor).
+ *
+ * Escalate-on-evidence still applies when size later arrives (full matrix).
+ */
+export declare function selectCeremonyColdStartDepth(modelTier: CeremonyModelTier | null | undefined): CeremonyDepth;
+/**
+ * Two-stage / partial-evidence selection when size or tier is missing
+ * (#3214 design note / #3263 tier-conditional cold-start).
  *
- * Start light (rapid) on cold incomplete inputs; escalate when partial evidence already
- * implies heavier ceremony (apps-bank safety: hard/substantial work must not stay rapid).
- * Does not invent plan-item effort (#1581 post-planning only).
+ * Cold incomplete size is tier-conditional (#3263): mid/low → standard, frontier
+ * or unknown → rapid. When size is known without tier, escalate on substantial
+ * size (apps-bank safety). Does not invent plan-item effort (#1581 post-planning only).
  */
 export declare function selectCeremonyDepthFromPartialEvidence(inputs: {
     readonly taskSize: CeremonyTaskSize | null;
     readonly modelTier: CeremonyModelTier | null;
 }): CeremonyDepth;
 /**
- * Pure default matrix (#3214 acceptance + two-stage design note):
+ * Pure default matrix (#3214 acceptance + #3263 tier-conditional cold-start):
  * - non-project → minimal (#3014 direction)
  * - S × frontier → rapid (strategies/rapid.md)
  * - S × mid → standard (mid-tier gains from structure)
  * - S × low → elevated
  * - M × low → elevated; M otherwise → standard
  * - L/XL → elevated (except L × frontier stays standard)
- * - Incomplete size/tier → two-stage partial evidence (default rapid; escalate on M/L or mid/low)
+ * - Incomplete size → tier-conditional cold-start (#3263): mid/low → standard; frontier/unknown → rapid
+ * - Size known, tier missing → escalate on M/L (partial evidence)
  */
 export declare function selectCeremonyDepthFromMatrix(inputs: CeremonyDialInputs): CeremonyDepth;
 export interface SelectCeremonyDepthOptions {
@@ -126,7 +148,7 @@ export interface SelectCeremonyDepthOptions {
  * Deterministic depth selection (pure; no IO).
  *
  * Precedence: disabled → standard; override → forced depth; else matrix on inputs;
- * empty inputs → **rapid** (two-stage cold default; escalate when evidence arrives).
+ * empty inputs → **rapid** (unknown-tier cold default; #3263 mid/low need modelTier set).
  */
 export declare function selectCeremonyDepth(options?: SelectCeremonyDepthOptions): CeremonyDialSelection;
 export interface ResolveCeremonyDialOptions {
@@ -230,4 +252,38 @@ export declare function resolveSessionCeremonyDialInputs(projectRoot: string, ex
     readonly inputs: CeremonyDialInputs;
     readonly provisional: ProvisionalCeremonyEstimate;
 };
+export interface CeremonyDialAuditProvisional {
+    readonly taskSize: CeremonyTaskSize | null;
+    readonly modelTier: CeremonyModelTier | null;
+    readonly projectShape: CeremonyProjectShape | null;
+    readonly reasons: readonly string[];
+}
+/**
+ * Snapshot of dial selection recorded on `.deft/ritual-state.json` at session:start.
+ * Operators audit failed-task depth / provisional reasons without re-running ritual.
+ */
+export interface CeremonyDialAuditSnapshot {
+    readonly path: string;
+    readonly depth: CeremonyDepth | null;
+    readonly source: string | null;
+    readonly inputs: {
+        readonly taskSize: CeremonyTaskSize | null;
+        readonly modelTier: CeremonyModelTier | null;
+        readonly projectShape: CeremonyProjectShape | null;
+    } | null;
+    readonly provisional: CeremonyDialAuditProvisional | null;
+    readonly raw: Record<string, unknown> | null;
+    readonly error: string | null;
+}
+/**
+ * Read ceremony dial depth + provisional reasons from ritual-state (#3263 audit path).
+ * session:start already writes `ceremony_dial` (incl. provisional) — this is the
+ * operator/read path so failed runs can confirm start-light vs escalate timing.
+ *
+ * Returns `error` when ritual-state is missing/unreadable or lacks `ceremony_dial`;
+ * does not throw.
+ */
+export declare function readCeremonyDialAudit(projectRoot: string): CeremonyDialAuditSnapshot;
+/** One-line operator summary for audit tooling / failed-task forensics (#3263). */
+export declare function formatCeremonyDialAuditLine(audit: CeremonyDialAuditSnapshot): string;
 //# sourceMappingURL=ceremony-dial.d.ts.map