@pedrocivita/tocket 2.5.0 → 2.6.4

package/dist/utils/appmaps.d.ts

@@ -0,0 +1,65 @@
+/** AppMap Memory Bank convention — file-first index and last-run history. */
+export declare const LAST_RUN_SCHEMA = "tocket.appmaps.last-run/v0";
+export declare const APPMAPS_DIR = ".context/appmaps";
+export declare const LAST_RUN_JSON = "last-run.json";
+export declare const LAST_RUN_MD = "last-run.md";
+export declare const APPMAPS_README = "README.md";
+export declare const APPMAPS_GOALS = "goals.md";
+export declare const APPMAP_SUFFIX = ".appmap.json";
+export interface LastRunResult {
+    id: string;
+    name: string;
+    ok: boolean;
+    ms: number;
+    jev_choice?: string | null;
+    jev_confidence?: number | null;
+    /** Real last-run snapshots use objects; older fixtures may use a string. */
+    evidence?: unknown;
+    error?: string | null;
+}
+export interface LastRun {
+    schema: typeof LAST_RUN_SCHEMA;
+    app: string;
+    map: string;
+    runner: string;
+    model: string;
+    mode: string;
+    finished_at: string;
+    all_ok: boolean;
+    passed: number;
+    total: number;
+    results: LastRunResult[];
+}
+export declare class LastRunValidationError extends Error {
+    constructor(message: string);
+}
+/** Validate and normalize a parsed last-run document. */
+export declare function validateLastRun(value: unknown): LastRun;
+/** Parse a last-run.json string and validate it against v0. */
+export declare function parseLastRun(raw: string): LastRun;
+/** Empty but schema-valid last-run document used by `tocket suite init`. */
+export declare function emptyLastRun(): LastRun;
+/** Human table for `.context/appmaps/last-run.md`. */
+export declare function writeLastRunMd(run: LastRun): string;
+/** Slug used for bank filenames (\`<app>.appmap.json\`, triage). */
+export declare function appSlug(app: string): string;
+/** Bank filename for a copied mapper AppMap. */
+export declare function appmapBankFile(app: string): string;
+/** Repo-relative path for the bank map copy. */
+export declare function appmapBankRel(app: string): string;
+export declare class AppmapDiscoveryError extends Error {
+    constructor(message: string);
+}
+/** Parse mapper (or hand) AppMap JSON. Object only; no full schema vendoring. */
+export declare function parseAppmapJson(raw: string): unknown;
+/**
+ * Find `*.appmap.json` in a mapper `--out` directory.
+ * Prefers `<app>.appmap.json` when several files exist.
+ */
+export declare function discoverAppmapJson(dir: string, app?: string): string;
+/** Point last-run.map at the bank copy; fill empty app from --app. */
+export declare function normalizeLastRunRaw(raw: unknown, mapRel: string, app?: string): unknown;
+/** Minimal README stub written when `.context/appmaps/` is created. */
+export declare function appmapsReadmeStub(): string;
+export declare function appmapsGoalsStub(): string;
+export declare function prettyLastRunJson(value: unknown): string;

package/dist/utils/appmaps.js

@@ -0,0 +1,280 @@
+/** AppMap Memory Bank convention — file-first index and last-run history. */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+export const LAST_RUN_SCHEMA = "tocket.appmaps.last-run/v0";
+export const APPMAPS_DIR = ".context/appmaps";
+export const LAST_RUN_JSON = "last-run.json";
+export const LAST_RUN_MD = "last-run.md";
+export const APPMAPS_README = "README.md";
+export const APPMAPS_GOALS = "goals.md";
+export const APPMAP_SUFFIX = ".appmap.json";
+export class LastRunValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LastRunValidationError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function expectString(value, field) {
+    if (typeof value !== "string") {
+        throw new LastRunValidationError(`${field} must be a string`);
+    }
+    return value;
+}
+function expectBoolean(value, field) {
+    if (typeof value !== "boolean") {
+        throw new LastRunValidationError(`${field} must be a boolean`);
+    }
+    return value;
+}
+function expectNumber(value, field) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new LastRunValidationError(`${field} must be a finite number`);
+    }
+    return value;
+}
+function optionalString(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    if (typeof value !== "string") {
+        throw new LastRunValidationError(`${field} must be a string or null`);
+    }
+    return value;
+}
+function optionalNumber(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new LastRunValidationError(`${field} must be a finite number or null`);
+    }
+    return value;
+}
+function parseResult(value, index) {
+    if (!isRecord(value)) {
+        throw new LastRunValidationError(`results[${index}] must be an object`);
+    }
+    const result = {
+        id: expectString(value.id, `results[${index}].id`),
+        name: expectString(value.name, `results[${index}].name`),
+        ok: expectBoolean(value.ok, `results[${index}].ok`),
+        ms: expectNumber(value.ms, `results[${index}].ms`),
+    };
+    const jevChoice = optionalString(value.jev_choice, `results[${index}].jev_choice`);
+    if (jevChoice !== undefined)
+        result.jev_choice = jevChoice;
+    const jevConfidence = optionalNumber(value.jev_confidence, `results[${index}].jev_confidence`);
+    if (jevConfidence !== undefined)
+        result.jev_confidence = jevConfidence;
+    if (value.evidence !== undefined)
+        result.evidence = value.evidence;
+    const error = optionalString(value.error, `results[${index}].error`);
+    if (error !== undefined)
+        result.error = error;
+    return result;
+}
+/** Validate and normalize a parsed last-run document. */
+export function validateLastRun(value) {
+    if (!isRecord(value)) {
+        throw new LastRunValidationError("last-run.json must be a JSON object");
+    }
+    const schema = expectString(value.schema, "schema");
+    if (schema !== LAST_RUN_SCHEMA) {
+        throw new LastRunValidationError(`schema must be "${LAST_RUN_SCHEMA}"`);
+    }
+    if (!Array.isArray(value.results)) {
+        throw new LastRunValidationError("results must be an array");
+    }
+    return {
+        schema: LAST_RUN_SCHEMA,
+        app: expectString(value.app, "app"),
+        map: expectString(value.map, "map"),
+        runner: expectString(value.runner, "runner"),
+        model: expectString(value.model, "model"),
+        mode: expectString(value.mode, "mode"),
+        finished_at: expectString(value.finished_at, "finished_at"),
+        all_ok: expectBoolean(value.all_ok, "all_ok"),
+        passed: expectNumber(value.passed, "passed"),
+        total: expectNumber(value.total, "total"),
+        results: value.results.map((item, index) => parseResult(item, index)),
+    };
+}
+/** Parse a last-run.json string and validate it against v0. */
+export function parseLastRun(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new LastRunValidationError("last-run.json is not valid JSON");
+    }
+    return validateLastRun(parsed);
+}
+function mdCell(value) {
+    if (value === null || value === undefined || value === "")
+        return "";
+    const text = typeof value === "object" ? JSON.stringify(value) : String(value);
+    return text.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+function formatOk(ok) {
+    return ok ? "pass" : "fail";
+}
+/** Empty but schema-valid last-run document used by `tocket suite init`. */
+export function emptyLastRun() {
+    return {
+        schema: LAST_RUN_SCHEMA,
+        app: "",
+        map: "",
+        runner: "",
+        model: "",
+        mode: "",
+        finished_at: "",
+        all_ok: true,
+        passed: 0,
+        total: 0,
+        results: [],
+    };
+}
+/** Human table for `.context/appmaps/last-run.md`. */
+export function writeLastRunMd(run) {
+    const resultRows = run.results.length
+        ? run.results
+            .map((result) => `| ${mdCell(result.id)} | ${mdCell(result.name)} | ${formatOk(result.ok)} | ${mdCell(result.ms)} | ${mdCell(result.jev_choice)} | ${mdCell(result.jev_confidence)} | ${mdCell(result.evidence)} | ${mdCell(result.error)} |`)
+            .join("\n")
+        : "| _none_ | | | | | | | |";
+    return `# Last AppMap run
+
+| Field | Value |
+| --- | --- |
+| Schema | ${mdCell(run.schema)} |
+| App | ${mdCell(run.app)} |
+| Map | ${mdCell(run.map)} |
+| Runner | ${mdCell(run.runner)} |
+| Model | ${mdCell(run.model)} |
+| Mode | ${mdCell(run.mode)} |
+| Finished | ${mdCell(run.finished_at)} |
+| Result | ${run.passed}/${run.total} passed |
+| All OK | ${run.all_ok ? "yes" : "no"} |
+
+## Results
+
+| ID | Name | OK | ms | Jev | Confidence | Evidence | Error |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+${resultRows}
+`;
+}
+/** Slug used for bank filenames (\`<app>.appmap.json\`, triage). */
+export function appSlug(app) {
+    return app.trim() ? app.trim().replace(/[^a-zA-Z0-9._-]+/g, "-") : "suite";
+}
+/** Bank filename for a copied mapper AppMap. */
+export function appmapBankFile(app) {
+    return `${appSlug(app)}${APPMAP_SUFFIX}`;
+}
+/** Repo-relative path for the bank map copy. */
+export function appmapBankRel(app) {
+    return `${APPMAPS_DIR}/${appmapBankFile(app)}`;
+}
+export class AppmapDiscoveryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AppmapDiscoveryError";
+    }
+}
+/** Parse mapper (or hand) AppMap JSON. Object only; no full schema vendoring. */
+export function parseAppmapJson(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("AppMap is not valid JSON");
+    }
+    if (!isRecord(parsed)) {
+        throw new Error("AppMap must be a JSON object");
+    }
+    return parsed;
+}
+/**
+ * Find `*.appmap.json` in a mapper `--out` directory.
+ * Prefers `<app>.appmap.json` when several files exist.
+ */
+export function discoverAppmapJson(dir, app) {
+    if (!existsSync(dir)) {
+        throw new AppmapDiscoveryError(`mapper-out directory not found: ${dir}`);
+    }
+    if (!statSync(dir).isDirectory()) {
+        throw new AppmapDiscoveryError(`mapper-out is not a directory: ${dir}`);
+    }
+    const files = readdirSync(dir)
+        .filter((name) => name.endsWith(APPMAP_SUFFIX))
+        .sort();
+    if (files.length === 0) {
+        throw new AppmapDiscoveryError(`No *${APPMAP_SUFFIX} found in ${dir}`);
+    }
+    if (app) {
+        const preferred = appmapBankFile(app);
+        if (files.includes(preferred)) {
+            return join(dir, preferred);
+        }
+    }
+    if (files.length === 1) {
+        return join(dir, files[0]);
+    }
+    throw new AppmapDiscoveryError(`Multiple *${APPMAP_SUFFIX} in ${dir} (${files.join(", ")}). Pass --map <file>.`);
+}
+/** Point last-run.map at the bank copy; fill empty app from --app. */
+export function normalizeLastRunRaw(raw, mapRel, app) {
+    if (!isRecord(raw))
+        return raw;
+    const next = { ...raw, map: mapRel };
+    if (app && (typeof next.app !== "string" || next.app.trim() === "")) {
+        next.app = app;
+    }
+    return next;
+}
+/** Minimal README stub written when `.context/appmaps/` is created. */
+export function appmapsReadmeStub() {
+    return `# AppMaps
+
+Index, last-run history, and a Memory Bank copy of the mapper AppMap.
+
+\`tocket suite loop\` copies \`<app>.appmap.json\` here so status and triage
+can read what Oficina wrote. Runners stay outside this directory.
+\`.context/appmaps/\` is file-first: \`tocket suite\` does not execute maps.
+
+| File | Purpose |
+| --- | --- |
+| \`goals.md\` | Suite goals and coverage intent |
+| \`<app>.appmap.json\` | Mapper (or hand) map copy |
+| \`last-run.json\` | Last run (\`schema\`: \`${LAST_RUN_SCHEMA}\`) |
+| \`last-run.md\` | Human-readable last-run table |
+| \`<app>.triage.json\` | Optional Jev/heuristic triage (\`tocket.appmaps.triage/v0\`) |
+
+## Tempestivita loop (Oficina)
+
+1. Mapper (sibling, not vendored): \`npx tsx src/cli.ts all --url https://tempestivita.civita.dev --smoke\`
+2. \`tocket suite loop --app tempestivita --mapper-out <mapper>/out --last-run <last-run.json> [--dry-run]\`
+3. \`tocket suite status\`
+
+Generic decisions (any state) use \`tocket decide\` → \`.context/decisions/<research|write|review>/\`. Loop does not call decide.
+`;
+}
+export function appmapsGoalsStub() {
+    return `# AppMap goals
+
+Record suite goals and coverage intent here.
+
+\`tocket suite loop\` copies \`<app>.appmap.json\` into this directory for the Memory Bank.
+This file is the index, not a runner.
+`;
+}
+export function prettyLastRunJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+//# sourceMappingURL=appmaps.js.map

package/dist/utils/appmaps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appmaps.js","sourceRoot":"","sources":["../../src/utils/appmaps.ts"],"names":[],"mappings":"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"}

package/dist/utils/context.d.ts

@@ -1,6 +1,8 @@
 /** Shared constants and helpers for .context/ file operations. */
 /** Number of days after which activeContext.md is considered stale. */
 export declare const STALENESS_THRESHOLD_DAYS = 7;
+/** Display paths with posix `/` on every OS (CLI "wrote …" / from= lines). */
+export declare function toRepoRelative(cwd: string, outPath: string): string;
 /**
  * Extract the first meaningful line from the "## Current Focus" section
  * of an activeContext.md file. Returns empty string if no focus is set.

package/dist/utils/context.js

@@ -1,6 +1,27 @@
 /** Shared constants and helpers for .context/ file operations. */
+import { isAbsolute, relative, sep } from "node:path";
 /** Number of days after which activeContext.md is considered stale. */
 export const STALENESS_THRESHOLD_DAYS = 7;
+/** Display paths with posix `/` on every OS (CLI "wrote …" / from= lines). */
+export function toRepoRelative(cwd, outPath) {
+    if (!outPath)
+        return outPath;
+    if (!isAbsolute(outPath)) {
+        return posixifyPath(outPath);
+    }
+    const rel = relative(cwd, outPath);
+    if (!rel ||
+        isAbsolute(rel) ||
+        rel === ".." ||
+        rel.startsWith(`..${sep}`) ||
+        rel.startsWith("../")) {
+        return posixifyPath(outPath);
+    }
+    return posixifyPath(rel);
+}
+function posixifyPath(p) {
+    return p.split(/[\\/]/g).join("/");
+}
 /**
  * Extract the first meaningful line from the "## Current Focus" section
  * of an activeContext.md file. Returns empty string if no focus is set.

package/dist/utils/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/utils/context.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,uEAAuE;AACvE,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAE1C;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAC1D,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC;QAAE,OAAO,EAAE,CAAC;IACxE,OAAO,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACjE,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/utils/context.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEtD,uEAAuE;AACvE,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAE1C,8EAA8E;AAC9E,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,OAAe;IACzD,IAAI,CAAC,OAAO;QAAE,OAAO,OAAO,CAAC;IAC7B,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACzB,OAAO,YAAY,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IACD,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACnC,IACE,CAAC,GAAG;QACJ,UAAU,CAAC,GAAG,CAAC;QACf,GAAG,KAAK,IAAI;QACZ,GAAG,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC;QAC1B,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,EACrB,CAAC;QACD,OAAO,YAAY,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC;AAED,SAAS,YAAY,CAAC,CAAS;IAC7B,OAAO,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAC1D,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC;QAAE,OAAO,EAAE,CAAC;IACxE,OAAO,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACjE,CAAC"}

package/dist/utils/decide.d.ts

@@ -0,0 +1,178 @@
+/** Generic Choice/Noul decisions. File-first; writes only under `.context/decisions/`. */
+import { type JevQuestion } from "./jev.js";
+export { toRepoRelative } from "./context.js";
+export declare const DECIDE_SCHEMA = "tocket.decide/v0";
+export declare const DECISIONS_DIR = ".context/decisions";
+export declare const DECISIONS_README = "README.md";
+export declare const STUB_MODEL = "stub-v0";
+/** Codila chief.py default: only route research/write at or above this confidence. */
+export declare const DEFAULT_CONFIDENCE_THRESHOLD = 0.85;
+export declare const QUEUE_DESTINATIONS: readonly ["research", "write", "review"];
+export declare const HIGH_CONFIDENCE_ROUTES: readonly ["research", "write"];
+export declare const BOUNDED_FORKS: readonly ["agent", "model", "tool", "action", "human"];
+export declare const DECIDE_LOOP = "state-questions-action-verify";
+export declare const RANK_WIDE_MIN = 5;
+/** Well-known Choice names for the file-first tool-risk gate (AutoMode pattern, not LangChain APIs). */
+export declare const TOOL_GATE_NAMES: readonly ["tool_gate", "action_gate"];
+export declare const TOOL_GATE_OPTIONS: readonly ["allow", "block", "ask"];
+export type QueueDestination = (typeof QUEUE_DESTINATIONS)[number];
+export type BoundedFork = (typeof BOUNDED_FORKS)[number];
+export type DecideMode = "active" | "shadow" | "dry-run";
+export type DecideSource = "jev" | "stub";
+export type DecideSemantics = "handoff" | "log-only";
+export type DecideHandoffStatus = "queued" | "logged";
+export type DecidePrimitive = "choice" | "noul" | "score";
+export type ToolGate = (typeof TOOL_GATE_OPTIONS)[number];
+export type ToolGateName = (typeof TOOL_GATE_NAMES)[number];
+export interface DecideChoiceSpec {
+    name: string;
+    options: string[];
+}
+export interface DecideNoulSpec {
+    name: string;
+}
+export interface DecideScoreSpec {
+    name: string;
+    min: number;
+    max: number;
+}
+export interface DecideChoiceAnswer {
+    type: "choice";
+    choice: string;
+    confidence: number;
+    rationale: string;
+    probabilities?: Record<string, number>;
+}
+export interface DecideNoulAnswer {
+    type: "noul";
+    noul: number;
+    confidence: number;
+    rationale: string;
+}
+export interface DecideScoreAnswer {
+    type: "score";
+    score: number;
+    confidence: number;
+    rationale: string;
+}
+export type DecideAnswer = DecideChoiceAnswer | DecideNoulAnswer | DecideScoreAnswer;
+export interface DecideRecord {
+    schema: typeof DECIDE_SCHEMA;
+    id: string;
+    generated_at: string;
+    mode: DecideMode;
+    source: DecideSource;
+    model: string;
+    /** Codila-style router: selected option (first Choice). */
+    choice: string | null;
+    confidence: number;
+    /** Queue hint: research | write | review. Low-confidence research/write becomes review. */
+    destination: QueueDestination;
+    gated: boolean;
+    /**
+     * Tool-risk gate from a `tool_gate` / `action_gate` Choice (`allow|block|ask`).
+     * Null when the handoff has no gate question. Independent of Codila `gated`.
+     */
+    tool_gate: ToolGate | null;
+    confidence_threshold: number;
+    /** handoff = workers may consume; log-only = shadow/dry-run (Tocket does not run workers). */
+    semantics: DecideSemantics;
+    status: DecideHandoffStatus;
+    /** Always false: Jev decides; LLMs create; agents act. This CLI only writes a file. */
+    executes: false;
+    loop: typeof DECIDE_LOOP;
+    fork: BoundedFork;
+    primitives: DecidePrimitive[];
+    batched: boolean;
+    rank_wide: boolean;
+    narrow: string | null;
+    state_summary: string;
+    state: unknown;
+    questions: Record<string, JevQuestion>;
+    answers: Record<string, DecideAnswer>;
+}
+export interface RunDecideOptions {
+    cwd: string;
+    state?: string;
+    fromPath?: string;
+    choices?: string[];
+    nouls?: string[];
+    scores?: string[];
+    fork?: string;
+    dryRun?: boolean;
+    shadow?: boolean;
+    id?: string;
+    confidenceThreshold?: number;
+    apiKey?: string | null;
+    now?: () => string;
+    fetchImpl?: typeof fetch;
+}
+export declare class DecideError extends Error {
+    constructor(message: string);
+}
+export declare function parseChoiceSpec(spec: string): DecideChoiceSpec;
+export declare function parseNoulSpec(spec: string): DecideNoulSpec;
+export declare function parseScoreSpec(spec: string): DecideScoreSpec;
+export declare function parseFork(raw?: string): BoundedFork;
+export declare function choiceCriterion(option: string): string;
+export declare function isQueueDestination(value: string): value is QueueDestination;
+export declare function isHighConfidenceRoute(value: string): boolean;
+export declare function isToolGateName(name: string): boolean;
+export declare function isToolGate(value: string | null | undefined): value is ToolGate;
+export declare function parseToolGate(value: unknown): ToolGate | null;
+/** Read a well-known `tool_gate` / `action_gate` Choice from answers. */
+export declare function extractToolGate(answers: Record<string, DecideAnswer>): ToolGate | null;
+export declare function resolveRecordToolGate(record: {
+    tool_gate?: ToolGate | null;
+    answers?: Record<string, DecideAnswer>;
+}): ToolGate | null;
+export declare function toolGateRefusesApply(gate: ToolGate | null): boolean;
+export declare function parseConfidenceThreshold(raw?: string | number): number;
+export declare function primaryChoice(answers: Record<string, DecideAnswer>): {
+    choice: string | null;
+    confidence: number;
+};
+/** Codila gate: research/write only when confidence >= threshold; otherwise review. */
+export declare function resolveDestination(choice: string | null, confidence: number, threshold?: number, fork?: BoundedFork): {
+    destination: QueueDestination;
+    gated: boolean;
+};
+export declare function resolveSemantics(mode: DecideMode): {
+    semantics: DecideSemantics;
+    status: DecideHandoffStatus;
+};
+export declare function slugId(value: string): string;
+export declare function fileTimestamp(iso: string): string;
+export declare function summarizeState(state: unknown): string;
+export declare function stateBlob(state: unknown): string;
+export declare function parseStateInput(raw: string): unknown;
+export declare function loadState(options: {
+    state?: string;
+    fromPath?: string;
+}): unknown;
+export declare function buildQuestions(choices: DecideChoiceSpec[], nouls: DecideNoulSpec[], scores?: DecideScoreSpec[]): Record<string, JevQuestion>;
+export declare function stubChoice(name: string, options: string[], state: unknown): DecideChoiceAnswer;
+export declare function stubNoul(_name: string, state: unknown): DecideNoulAnswer;
+export declare function stubScore(name: string, min: number, max: number, state: unknown): DecideScoreAnswer;
+export declare function stubAnswers(questions: Record<string, JevQuestion>, state: unknown): Record<string, DecideAnswer>;
+export declare function isInsideContext(cwd: string, targetPath: string): boolean;
+export declare function decisionOutputPath(cwd: string, generatedAt: string, id: string, destination?: QueueDestination): string;
+export declare function defaultDecisionId(choices: DecideChoiceSpec[], nouls: DecideNoulSpec[], scores?: DecideScoreSpec[]): string;
+export declare function listPrimitives(questions: Record<string, JevQuestion>): DecidePrimitive[];
+export declare function choiceOptionCount(questions: Record<string, JevQuestion>): number;
+export declare function resolveDecideMode(options: {
+    dryRun?: boolean;
+    shadow?: boolean;
+    apiKey?: string;
+}): {
+    useLive: boolean;
+    mode: DecideMode;
+};
+export declare function prettyDecideJson(value: unknown): string;
+export declare function decisionsReadmeStub(): string;
+export declare function parseDecideRecord(raw: string): DecideRecord;
+export declare function formatDecideSummary(record: DecideRecord, relPath: string): string;
+export declare function runDecide(options: RunDecideOptions): Promise<{
+    record: DecideRecord;
+    outPath: string;
+}>;