productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/riskClassify.js

@@ -0,0 +1,149 @@
+// B3 risky-work classifier. productfoo treats spec-first as a boundary only for work
+// that is irreversible, agentic/delegated, or outbound-facing; everything else
+// is advisory. This makes that judgment concrete, inspectable, and overridable
+// with a recorded reason — never a silent verdict.
+import { withGlyph } from "./statusGlyphs.js";
+const SIGNAL_TERMS = {
+    irreversible: [
+        "delete", "drop", "destroy", "wipe", "purge", "truncate", "overwrite",
+        "migrate", "migration", "schema", "production", "prod", "deploy", "release",
+        "payment", "charge", "refund", "billing", "money", "irreversible", "destructive",
+    ],
+    agentic: [
+        "agent", "agentic", "autonomous", "autonomy", "unattended", "delegate",
+        "delegated", "loop", "background", "automatic", "auto-run", "self-serve",
+        "on behalf", "without approval", "cron", "scheduled", "nightly", "automatically",
+    ],
+    outbound: [
+        "email", "send", "publish", "post", "notify", "notification", "customer",
+        "external", "outbound", "broadcast", "slack", "tweet", "sms", "webhook",
+        "public", "message users",
+    ],
+};
+/**
+ * Terms whose risk a governing frame cannot talk away.
+ *
+ * These name a *behaviour being created* — something that will act on its own — and
+ * "I'm only adding a monitor for it" does not make that safe. Everything else in the
+ * lexicon is a noun that risky work and work *about* risky work mention equally often.
+ *
+ * This is the line that keeps the dampener below from becoming a hole: "add a
+ * background loop that watches deploys and auto-rolls-back" still blocks, because
+ * `loop` and `automatically` live here, even though `watches` reads like governance.
+ */
+const BEHAVIOUR_TERMS = [
+    "autonomous", "autonomy", "unattended", "auto-run", "automatically", "loop",
+    "cron", "scheduled", "nightly", "on behalf", "without approval", "delegate", "delegated",
+];
+/** Verbs a *build* statement opens with. "delete the prod table" opens with none of them. */
+const BUILD_VERBS = [
+    "add", "create", "write", "wire", "fix", "update", "refactor", "rename",
+    "introduce", "implement", "build", "make", "extend", "tighten", "calibrate", "harden",
+];
+/** What the work is doing TO the risky thing: constraining it, or watching it. */
+const GOVERNANCE_TERMS = [
+    "hook", "gate", "guard", "block", "blocks", "deny", "denies", "refuse", "refuses",
+    "prevent", "prevents", "test", "tests", "lint", "check", "checks", "validate",
+    "verify", "audit", "document", "warn", "warns", "log", "logs", "monitor", "monitors",
+    "detect", "detects", "review", "classify", "surface", "report", "dry-run", "spec",
+];
+function matchTerms(work, terms) {
+    const haystack = work.toLowerCase();
+    const matched = [];
+    for (const term of terms) {
+        // Tolerate the inflections, because a gate that misses is worse than one that asks.
+        // `\bdeploy\b` does not match "deploys"; `\bdelete\b` does not match "deleting". The
+        // exact-word matcher waved both through — a false negative in a safety gate, and the
+        // more dangerous direction to be wrong in.
+        const pattern = /^[a-z]+$/.test(term)
+            ? new RegExp(`\\b${term}(s|d|es|ed|ing)?\\b`)
+            : new RegExp(term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+        if (pattern.test(haystack))
+            matched.push(term);
+    }
+    return matched;
+}
+/**
+ * Is the work *governing* the risky thing rather than *doing* it?
+ *
+ * "Add a hook that denies raw research agents" mentions agents; it does not act
+ * agentically — it is the thing that stops agents. "Add a test for the delete path"
+ * mentions delete; it deletes nothing. A bag of words cannot tell those from "delete
+ * the production table", and this classifier used to call all three risky.
+ *
+ * The tell is grammatical, and it is cheap to read: the statement OPENS with a build
+ * verb (so the risky term is an object, not the action) and names a governing
+ * construct (a hook, a gate, a test, an audit). Real risky work does not open with
+ * "add a guard that…".
+ *
+ * This is a heuristic and it will be wrong sometimes. That is why it lowers confidence
+ * and prints its reasoning instead of silently flipping the verdict.
+ */
+export function isGovernedFrame(work) {
+    const words = work.toLowerCase().split(/[^a-z-]+/).filter(Boolean);
+    // The head is either a build verb ("add a hook that blocks deploys") or the governing
+    // act itself ("document the refund flow", "audit the payment path"). Risky work opens
+    // with neither — "delete the production table" leads with the destruction.
+    const head = words.slice(0, 5);
+    const opensGoverning = head.some((w) => BUILD_VERBS.includes(w) || GOVERNANCE_TERMS.includes(w));
+    return opensGoverning && matchTerms(work, GOVERNANCE_TERMS).length > 0;
+}
+export function classifyWork(work, override, options = {}) {
+    const dimensions = {
+        irreversible: matchTerms(work, SIGNAL_TERMS.irreversible),
+        agentic: matchTerms(work, SIGNAL_TERMS.agentic),
+        outbound: matchTerms(work, SIGNAL_TERMS.outbound),
+    };
+    const hits = Object.keys(dimensions).filter((dim) => dimensions[dim].length > 0);
+    const matched = hits.flatMap((dim) => dimensions[dim]);
+    const behaviour = matched.filter((term) => BEHAVIOUR_TERMS.includes(term));
+    const strict = options.strict === true;
+    // A governing frame only earns the downgrade when nothing in the work names a
+    // behaviour that acts on its own. "A loop that monitors deploys" is still a loop.
+    const governed_frame = hits.length > 0 && behaviour.length === 0 && isGovernedFrame(work);
+    const confidence = hits.length === 0 ? "high" : behaviour.length > 0 ? "high" : governed_frame ? "low" : "medium";
+    const risky = hits.length > 0 && (strict || !governed_frame);
+    const evidence = hits.map((dim) => `${dim} (${dimensions[dim].join(", ")})`).join("; ");
+    let rationale;
+    if (hits.length === 0) {
+        rationale = "No irreversible, agentic, or outbound-facing signals matched; treat spec-first as advisory.";
+    }
+    else if (governed_frame && !strict) {
+        // Never silently downgrade. Show the evidence, the reasoning, and the dissent —
+        // the reader has to be able to disagree with this and re-run it.
+        rationale =
+            `Matched ${evidence} — but this work reads as governing or testing those things, not doing them ` +
+                `(it opens with a build verb and names a guard, gate, test, or check). Keyword matches are evidence, ` +
+                `not proof, and a classifier that blocks on the mere mention of "agent" or "delete" is one people learn ` +
+                `to override on sight. Spec-first is advisory here. If this work really does act — delegates autonomy, ` +
+                `touches production, or reaches a user — it is risky and \`foo spec\` is the reflex. Force the block with --strict.`;
+    }
+    else if (behaviour.length > 0) {
+        rationale = `Matched ${evidence}. ${behaviour.join(", ")} names a behaviour that acts on its own, so a governing frame cannot excuse it.`;
+    }
+    else {
+        rationale = `Matched ${evidence}.`;
+    }
+    // An override is a recorded human decision to waive the boundary, not a silent skip.
+    const spec_first_required = risky && !override;
+    return { work, risky, dimensions, confidence, governed_frame, rationale, override, spec_first_required };
+}
+export function renderClassification(classification, asJson, glyphsOn = false) {
+    if (asJson)
+        return `${JSON.stringify({ schema_version: "0.1", ...classification }, null, 2)}\n`;
+    const lines = [
+        `Risk classification for: ${classification.work}`,
+        "",
+        withGlyph("classification", `Verdict: ${classification.risky ? "risky" : "routine"} (confidence: ${classification.confidence})`, glyphsOn),
+        `Rationale: ${classification.rationale}`,
+    ];
+    if (classification.override) {
+        lines.push(`Override recorded: ${classification.override}`);
+    }
+    lines.push("", classification.spec_first_required
+        ? withGlyph("needs_input", "Boundary (B3): spec-first is required before build. Run `foo spec` or `foo spec start`.", glyphsOn)
+        : classification.override
+            ? "Boundary (B3) waived by recorded override; proceed with the override on record."
+            : "Signal: spec-first is advisory for this work. `foo spec` is still the faster reflex.", "");
+    return lines.join("\n");
+}

package/dist-public/src/routines.d.ts

@@ -0,0 +1,42 @@
+import { type RuntimeId, type TriggerKind } from "./agentAdapters.js";
+import type { SeverityClass } from "./severityClass.js";
+export interface RoutineTrigger {
+    kind: TriggerKind;
+    cron: string | null;
+    tz: string | null;
+    event: string | null;
+}
+export interface Routine {
+    id: string;
+    title: string;
+    goal: string;
+    mode: string;
+    trigger: RoutineTrigger;
+    /** Runtimes this routine is bound to (from the adapters block). */
+    runtimes: RuntimeId[];
+    /** schedule/event triggers run with no human present at fire time. */
+    unattended: boolean;
+    verifyCheck: string | null;
+    terminalStates: string[];
+    approvalBoundaries: string[];
+    observeSources: string[];
+    allowedActions: string[];
+}
+export interface RoutineFinding {
+    kind: "autonomy_incomplete" | "unknown_runtime" | "runtime_not_headless" | "unsupported_runtime" | "trigger_malformed";
+    severity: "high" | "medium" | "low";
+    class: SeverityClass;
+    /** B4 when this is the autonomy boundary; absent for advisory-only findings. */
+    boundary: "B4" | null;
+    subject: string;
+    summary: string;
+    suggested_actions: string[];
+    requires_human: boolean;
+}
+export declare function parseRoutines(packetDir: string): {
+    specId: string;
+    routines: Routine[];
+};
+export declare function validateRoutine(routine: Routine): RoutineFinding[];
+export declare function passPrompt(routine: Routine, packetRel: string): string;
+export declare function emitBinding(routine: Routine, runtime: RuntimeId, packetRel: string): string;

package/dist-public/src/routines.js

@@ -0,0 +1,269 @@
+// Portable routines (portable-routines-v0): a routine is a loop contract whose
+// trigger is a schedule or event (not just manual), bound to one or more coding
+// agents. Fiona Fung's "routines" — async agent management — made runtime-neutral.
+//
+// The split that makes it agnostic:
+//   - The CONTRACT (goal, observe, act, verify, stop, ask_user_when, budget) is
+//     the existing loop contract — canonical, validated by loopContracts.ts, the
+//     same for every runtime.
+//   - The TRIGGER (when it fires) is canonical too: a standard cron / event name.
+//   - Only the BINDING (how a given agent arms the trigger and runs one pass
+//     headless) is per-runtime, and that lives in agentAdapters.ts.
+//
+// This module reads routines out of loops.yaml, enforces the autonomy boundary
+// (B4) for anything that runs unattended, resolves the bound adapters, and emits
+// the per-runtime binding artifact. productfoo never schedules anything itself.
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "./vendorYaml.js";
+import { loadLoopContracts } from "./loopContracts.js";
+import { NotFoundError } from "./errorTaxonomy.js";
+import { AGENT_ADAPTERS, getAdapter } from "./agentAdapters.js";
+function asObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function str(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+function strArray(value) {
+    return Array.isArray(value) ? value.map(str).filter((x) => x !== null) : [];
+}
+function parseTrigger(raw) {
+    const t = asObject(raw);
+    const kind = (str(t.kind) ?? "manual");
+    return { kind, cron: str(t.cron), tz: str(t.tz), event: str(t.event) };
+}
+// Terminal states come from lifecycle.terminal_states when present, else the
+// keys of the stop: block (each key is a terminal state name).
+function parseTerminalStates(loop) {
+    const lifecycle = asObject(loop.lifecycle);
+    const fromLifecycle = strArray(lifecycle.terminal_states);
+    if (fromLifecycle.length > 0)
+        return fromLifecycle;
+    return Object.keys(asObject(loop.stop));
+}
+// A loop entry is a routine when it declares an adapters block or a non-manual
+// trigger; a plain manual loop stays a loop.
+function isRoutineEntry(loop) {
+    if ("adapters" in loop)
+        return true;
+    const kind = str(asObject(loop.trigger).kind);
+    return kind === "schedule" || kind === "event";
+}
+export function parseRoutines(packetDir) {
+    const loopsPath = path.join(packetDir, "loops.yaml");
+    if (!existsSync(loopsPath)) {
+        // Absent is not a defect (#702): NotFoundError classifies as `not_found`, which never pages.
+        throw new NotFoundError("loops.yaml missing; run foo loop design <packet-dir> > <packet-dir>/loops.yaml, then add trigger + adapters", "E_PACKET_NOT_FOUND");
+    }
+    // Reuse the base loop-contract validation so a routine can never skip it.
+    const { specId } = loadLoopContracts(packetDir);
+    const doc = asObject(parseYaml(readFileSync(loopsPath, "utf8")));
+    const loops = Array.isArray(doc.loops) ? doc.loops : [];
+    const routines = [];
+    for (const raw of loops) {
+        const loop = asObject(raw);
+        if (!isRoutineEntry(loop))
+            continue;
+        const trigger = parseTrigger(loop.trigger);
+        const adapters = asObject(loop.adapters);
+        const runtimes = strArray(adapters.runtimes);
+        const verify = asObject(loop.verify);
+        routines.push({
+            id: str(loop.id) ?? "L-?",
+            title: str(loop.title) ?? "",
+            goal: str(loop.goal) ?? "",
+            mode: str(loop.mode) ?? "human-in-loop",
+            trigger,
+            runtimes,
+            unattended: trigger.kind === "schedule" || trigger.kind === "event",
+            verifyCheck: str(verify.check),
+            terminalStates: parseTerminalStates(loop),
+            approvalBoundaries: strArray(loop.ask_user_when),
+            observeSources: strArray(asObject(loop.observe).sources),
+            allowedActions: strArray(asObject(loop.act).allowed),
+        });
+    }
+    return { specId, routines };
+}
+// Validate a routine. The autonomy boundary (B4) findings carry boundary: "B4"
+// and are the only ones a caller should escalate to a blocking exit under
+// --strict; everything else is an advisory signal (signals-over-gates).
+export function validateRoutine(routine) {
+    const findings = [];
+    // B4: an unattended routine MUST carry a verification check, at least one
+    // terminal state, and an approval boundary — otherwise unbounded action.
+    if (routine.unattended) {
+        const missing = [];
+        if (!routine.verifyCheck)
+            missing.push("verify.check");
+        if (routine.terminalStates.length === 0)
+            missing.push("a terminal state");
+        if (routine.approvalBoundaries.length === 0)
+            missing.push("ask_user_when (approval boundary)");
+        if (missing.length > 0) {
+            findings.push({
+                kind: "autonomy_incomplete",
+                severity: "high",
+                class: "bad",
+                boundary: "B4",
+                subject: `routine:${routine.id}`,
+                summary: `Unattended routine ${routine.id} is missing ${missing.join(", ")}. An unattended loop without these is unbounded risk (B4).`,
+                suggested_actions: [
+                    "add a verify.check the routine runs every pass",
+                    "declare terminal states so the loop can stop",
+                    "list ask_user_when boundaries for actions that need a human",
+                ],
+                requires_human: true,
+            });
+        }
+        if (routine.trigger.kind === "schedule" && !routine.trigger.cron) {
+            findings.push({
+                kind: "trigger_malformed",
+                severity: "high",
+                class: "bad",
+                boundary: "B4",
+                subject: `routine:${routine.id}`,
+                summary: `Routine ${routine.id} has a schedule trigger with no cron expression.`,
+                suggested_actions: ["set trigger.cron to a standard 5-field cron expression"],
+                requires_human: true,
+            });
+        }
+    }
+    if (routine.runtimes.length === 0) {
+        findings.push({
+            kind: "unknown_runtime",
+            severity: "medium",
+            class: "sad",
+            boundary: null,
+            subject: `routine:${routine.id}`,
+            summary: `Routine ${routine.id} is bound to no runtime; it has a contract but nothing to run it.`,
+            suggested_actions: [`add adapters.runtimes (e.g. [claude, codex])`],
+            requires_human: false,
+        });
+    }
+    for (const runtime of routine.runtimes) {
+        const adapter = getAdapter(runtime);
+        if (!adapter) {
+            findings.push({
+                kind: "unknown_runtime",
+                severity: "medium",
+                class: "bad",
+                boundary: null,
+                subject: `routine:${routine.id}`,
+                summary: `Routine ${routine.id} names unknown runtime "${runtime}".`,
+                suggested_actions: [`use a known runtime: ${Object.keys(AGENT_ADAPTERS).join(", ")}`],
+                requires_human: false,
+            });
+            continue;
+        }
+        if (routine.unattended && !adapter.can_run_headless) {
+            findings.push({
+                kind: "runtime_not_headless",
+                severity: "high",
+                class: "bad",
+                boundary: "B4",
+                subject: `routine:${routine.id}`,
+                summary: `Runtime ${adapter.label} cannot run headless, so it cannot safely back an unattended routine.`,
+                suggested_actions: [
+                    `arm this routine through github-actions running a headless runtime instead`,
+                    `or bind ${routine.id} to a headless runtime (${AGENT_ADAPTERS.claude.label}, ${AGENT_ADAPTERS.codex.label})`,
+                ],
+                requires_human: true,
+            });
+        }
+        else if (adapter.support === "planned") {
+            findings.push({
+                kind: "unsupported_runtime",
+                severity: "low",
+                class: "sad",
+                boundary: null,
+                subject: `routine:${routine.id}`,
+                summary: `Runtime ${adapter.label} is mapped but not yet supported: ${adapter.notes}`,
+                suggested_actions: [`prefer a supported runtime for now: ${supportedLabels()}`],
+                requires_human: false,
+            });
+        }
+    }
+    return findings;
+}
+function supportedLabels() {
+    return (Object.values(AGENT_ADAPTERS))
+        .filter((a) => a.support === "supported")
+        .map((a) => a.label)
+        .join(", ");
+}
+// The pass instruction handed to whichever runtime fires — identical across
+// runtimes, which is what makes the routine portable. Built from the contract.
+export function passPrompt(routine, packetRel) {
+    return [
+        `Run one pass of foo routine ${routine.id} on packet ${packetRel}.`,
+        `Goal: ${routine.goal}`,
+        `Observe only: ${routine.observeSources.join(", ") || "the packet artifacts"}.`,
+        `Allowed actions: ${routine.allowedActions.join("; ") || "propose findings only"}.`,
+        `Pause and ask a human when: ${routine.approvalBoundaries.join("; ") || "any irreversible or outbound action"}.`,
+        `Verify with: ${routine.verifyCheck ?? "foo asp verify " + packetRel}.`,
+        `Record the iteration to the packet ledger, then stop at a terminal state (${routine.terminalStates.join(", ") || "succeeded, blocked, exhausted"}).`,
+    ].join("\n");
+}
+// Emit the per-runtime binding artifact: how THIS runtime arms the trigger and
+// runs one pass. Read-only — prints to stdout for review before it is committed
+// or armed; foo schedules nothing itself.
+export function emitBinding(routine, runtime, packetRel) {
+    const adapter = getAdapter(runtime);
+    if (!adapter)
+        throw new Error(`unknown runtime "${runtime}" — known: ${Object.keys(AGENT_ADAPTERS).join(", ")}`);
+    const prompt = passPrompt(routine, packetRel);
+    const oneLinePrompt = prompt.replace(/\n/g, " ");
+    const invoke = adapter.invoke_template
+        ? adapter.invoke_template.replace("{prompt}", oneLinePrompt).replace("{packet}", packetRel)
+        : null;
+    const cron = routine.trigger.cron ?? "<set trigger.cron>";
+    const header = [
+        `# foo routine binding — ${routine.id} → ${adapter.label} (${adapter.support})`,
+        `# Canonical contract lives in the packet; this is only the ${adapter.label} binding.`,
+        `# Review before arming. productfoo does not schedule this for you.`,
+    ];
+    if (runtime === "github-actions") {
+        // CI is a meta-adapter: it has no invoke of its own (invoke_template is null)
+        // but hosts another runtime's headless invocation on a cron, so it is handled
+        // before the headless guard below.
+        return [
+            ...header,
+            `# Hosts a headless runtime on a cron. Fill in the runtime step below.`,
+            `name: foo-routine-${routine.id}`,
+            `on:`,
+            `  schedule:`,
+            `    - cron: "${cron}"`,
+            `jobs:`,
+            `  ${routine.id.toLowerCase()}:`,
+            `    runs-on: ubuntu-latest`,
+            `    steps:`,
+            `      - uses: actions/checkout@v4`,
+            `      - name: run routine pass`,
+            `        run: |`,
+            `          # e.g. ${AGENT_ADAPTERS.codex.invoke_template?.replace("{prompt}", '"$PROMPT"')}`,
+            `        env:`,
+            `          PROMPT: ${JSON.stringify(oneLinePrompt)}`,
+            "",
+        ].join("\n");
+    }
+    if (!adapter.can_run_headless || !invoke) {
+        return [
+            ...header,
+            `#`,
+            `# ${adapter.label} cannot be driven headless today.`,
+            `# Gap: ${adapter.notes}`,
+            `# Fix: arm this routine via github-actions running a headless runtime, or bind to ${supportedLabels()}.`,
+            "",
+        ].join("\n");
+    }
+    // Schedule bindings render as a reviewable crontab line; manual/event note how
+    // they fire instead.
+    const trigger = routine.trigger.kind === "schedule"
+        ? [`# Arm with cron (${routine.trigger.tz ?? "local"} time):`, `${cron}  ${invoke}`]
+        : routine.trigger.kind === "event"
+            ? [`# Fires on event: ${routine.trigger.event ?? "<set trigger.event>"}`, `# Invoke per pass:`, invoke]
+            : [`# Manual — run per pass:`, invoke];
+    return [...header, ...trigger, ""].join("\n");
+}

package/dist-public/src/routingPolicy.d.ts

@@ -0,0 +1,172 @@
+import type { ModelRoster } from "./activeModel.js";
+import type { Depth } from "./conductor/types.js";
+import { type PricingTable } from "./loopBudget.js";
+import type { RiskClassification, RiskConfidence } from "./riskClassify.js";
+export type TierDefinition = {
+    name: string;
+    purpose: string;
+    /** Task types this tier serves, from the data file. */
+    taskTypes: readonly string[];
+};
+export type DifficultyPolicy = {
+    /** How the numbers below were arrived at, in the data file's own words. */
+    basis: string | null;
+    /** Signal name -> weight. */
+    signals: Record<string, number>;
+    /** Score at or above which a task moves up the ladder; null when the data file omits it. */
+    escalateAt: number | null;
+    /** Score at or below which a task moves down the ladder; null when omitted. */
+    downgradeAt: number | null;
+    maxTierMoves: number | null;
+    /** Difficulty band -> thinking budget in tokens (R-003: adaptive, never fixed). */
+    thinkingBudgetTokens: Record<string, number>;
+};
+export type EscalationPolicy = {
+    basis: string | null;
+    quality: {
+        retriesSameModel: number | null;
+        then: string | null;
+        maxTierMoves: number | null;
+    };
+    resilience: {
+        trigger: string | null;
+        direction: string | null;
+        maxTierMoves: number | null;
+    };
+};
+export type ReviewPolicy = {
+    requireDifferentFamily: boolean;
+    onSameFamily: string | null;
+};
+export type PanelPolicy = {
+    default: string | null;
+    requireComparableCandidates: boolean;
+    comparabilityMaxRankGap: number | null;
+    onIncomparable: string | null;
+    adjudication: string | null;
+};
+export type WorkflowLane = "direct" | "shape-fast" | "review-targeted" | "deep-explicit";
+export type WorkflowRollout = "observe_only" | "enabled";
+export type WorkflowPolicy = {
+    /** False when workflow policy data cannot safely drive execution. */
+    valid: boolean;
+    basis: string | null;
+    rollout: WorkflowRollout | null;
+    defaultLane: WorkflowLane | null;
+    conservativeLane: WorkflowLane | null;
+    laneOrder: readonly WorkflowLane[];
+    executableLanes: readonly WorkflowLane[];
+    targetedMinDomains: number | null;
+    depthLanes: Partial<Record<Depth, WorkflowLane>>;
+    ambiguityTerms: readonly string[];
+    domainSignals: Record<string, readonly string[]>;
+    limitations: Partial<Record<WorkflowLane, string>>;
+};
+export type RoutingPolicy = {
+    /** Basename of the data file, e.g. "routing-policy.yaml". */
+    source: string;
+    /** False when the data file is missing or unreadable — resolution degrades, never throws. */
+    available: boolean;
+    date: string | null;
+    staleAfterDays: number | null;
+    /** Where the tier definitions and task-type map come from. */
+    evidence: string | null;
+    /** Tier names weakest -> strongest. Difficulty moves along this list and nowhere else. */
+    ladder: readonly string[];
+    /** Where anything unresolvable lands. Null when the data file is unavailable. */
+    conservativeTier: string | null;
+    tiers: Record<string, TierDefinition>;
+    /** Task type -> tier name. */
+    taskTypes: Record<string, string>;
+    difficulty: DifficultyPolicy;
+    escalation: EscalationPolicy;
+    review: ReviewPolicy;
+    panel: PanelPolicy;
+    /** Request -> orchestration amount. Deliberately separate from model tiers. */
+    workflow: WorkflowPolicy;
+    /** Data keys that may never become routing inputs (R-011). */
+    forbiddenInputs: readonly string[];
+    /** Worded findings carried into every decision made against this policy. */
+    findings: readonly string[];
+};
+/** One tier decision, with the reason it landed there and any honesty findings. */
+export type TierDecision = {
+    /** Resolved tier name, or null when there is no policy to resolve against. */
+    tier: string | null;
+    /** Plain-text reason, safe to show a reader who did not watch the run. */
+    reason: string;
+    /** True when the decision fell back to the conservative tier rather than being mapped. */
+    degraded: boolean;
+    findings: readonly string[];
+};
+export type WorkflowLaneDecision = {
+    /** The lane the caller may execute now under the rollout policy. */
+    lane: WorkflowLane;
+    /** The smallest adequate lane selected before rollout gating. */
+    recommended_lane: WorkflowLane;
+    reason: string;
+    signals: readonly string[];
+    confidence: RiskConfidence;
+    conservative_escalation: boolean;
+    explicit: boolean;
+    executable: boolean;
+    rollout: WorkflowRollout;
+    /** Routing is deterministic and never spends a model call. */
+    routing_model_calls: 0;
+    boundary?: "B5";
+    required_capability?: "research";
+    limitation?: string;
+};
+export type WorkflowLaneInput = {
+    work: string;
+    explicitLane?: WorkflowLane;
+    explicitDepth?: Depth;
+    risk: RiskClassification;
+    researchRequested?: boolean;
+};
+export type RoutingContext = {
+    policy: RoutingPolicy;
+    roster: ModelRoster;
+    /** The price table backing the policy — a stale one degrades routing (R-013). */
+    pricing: PricingTable;
+    now?: Date;
+};
+/**
+ * Every path in `value` whose key is a forbidden routing input (R-011). Exported
+ * so any surface that accepts routing data — the policy file, the roster, a
+ * future refresh proposal — can ask the same question of it. The node that
+ * *declares* the forbidden list is skipped; naming a thing is not using it.
+ */
+export declare function findForbiddenInputs(value: unknown, forbidden: readonly string[]): string[];
+export declare function loadRoutingPolicy(root?: string): RoutingPolicy;
+/** Days between the policy date and `now`; Infinity when the date is unusable. */
+export declare function routingPolicyAgeDays(policy: RoutingPolicy, now?: Date): number;
+/** True when the policy is older than its own declared refresh window (RISK-002). */
+export declare function routingPolicyIsStale(policy: RoutingPolicy, now?: Date): boolean;
+/**
+ * The tier a task type maps to, before difficulty adjusts it (R-002 step 1). An
+ * unmapped task type lands conservatively and says so — never on the cheap end
+ * by default.
+ */
+export declare function tierForTaskType(ctx: RoutingContext, taskType: string): TierDecision;
+/**
+ * The tier a specific model sits in. Tier membership is roster data: a model the
+ * roster does not place, or does not know at all, resolves conservatively with a
+ * worded finding rather than being guessed into a tier (R-013).
+ */
+export declare function tierForModel(ctx: RoutingContext, modelId: string): TierDecision;
+/** Roster models placed in `tier`, in roster order. Empty is a real answer, not an error. */
+export declare function modelsForTier(ctx: RoutingContext, tier: string): string[];
+/**
+ * Move `tier` `steps` rungs along the ladder (R-003 allows at most one, and the
+ * policy data says how many). A tier that is off the ladder — a different axis
+ * rather than a stronger rung — does not move, and says why. Movement stops at
+ * the ends rather than wrapping.
+ */
+export declare function adjustTier(policy: RoutingPolicy, tier: string, steps: number): TierDecision;
+/**
+ * Choose how much orchestration a request earns. This is a pure, deterministic
+ * decision over committed policy data plus the existing B3 classifier: it never
+ * calls a model merely to decide that no extra model call is needed.
+ */
+export declare function resolveWorkflowLane(policy: RoutingPolicy, input: WorkflowLaneInput): WorkflowLaneDecision;