@gonrocca/nodd 0.1.0

package/src/gates/evidence.ts

@@ -0,0 +1,209 @@
+// gate-evidence — the one that makes the rest worth having.
+//
+// ODD says "evidence is what you observed, not what you expect" and then lets
+// the model write `Evidence: tests pass` with nothing behind it. Here a checkoff
+// is refused unless a `success` outcome was observed, from a real command, after
+// the task's last write.
+//
+// Four independent facts must line up, and each is checked against observation
+// rather than assertion:
+//
+//   1. a command ran           — a `tool_result`, not an assistant sentence
+//   2. it succeeded            — `isError === false`, i.e. exit 0 by pi's
+//                                construction; `exit`/`aborted`/`timeout`/
+//                                `unknown` never qualify (T019)
+//   3. it ran after the edit   — a green run predating the change proves
+//                                nothing about the change
+//   4. it was *the declared check* — the runner recorded at declaration time,
+//                                not whatever string the model picked
+//
+// Fact 4 is what makes the other three worth having. pi's bash tool exits 0 for
+// `echo 'I have verified that all tests pass'` just as it does for `npm test`,
+// so a gate that accepts any exit-0 accepts the model's own sentence wearing a
+// command's clothes — `Evidence: tests pass` again, now in NODD's format. The
+// model does not choose the runner: it is declared once, lands in the feature
+// doc's `## Verification` section, and the gate compares against it.
+//
+// Honest limit: when no runner was declared, fact 4 cannot be checked and is
+// skipped rather than faked. The artifact says so in the evidence line itself —
+// `success (runner not pinned)` — because a reader auditing a checkoff has to
+// be able to tell a run certified by the declared runner from one certified by
+// whatever exit-0 string was handy. Saying it only in `## Verification` leaves
+// the line that is actually read indistinguishable from a pinned one.
+//
+// Plus a fourth, per the ledger integrity rule: the record must be one this
+// kernel observed. A record on disk is a claim about the past; only the
+// committed observation set makes it evidence.
+//
+// With the gate off the checkoff proceeds but the artifact says
+// `observed: none (gate disabled)`. A disabled gate may stop enforcing; it may
+// not make the document assert something that was never verified.
+
+import type { Committed } from "../state.ts";
+import { classifyRecords, describeDegraded, type LedgerRecord } from "../ledger.ts";
+import { describeOutcome, isSuccess, parseOutcome } from "../outcome.ts";
+import { refuse, resolveFlag, type Policy, type Remedy } from "./policy.ts";
+
+export type TddContext = { mode: "strict" | "off"; source: string; runner: string };
+
+export type CheckRequest = {
+  task: string;
+  /** When the task's last observed write happened. Evidence must postdate it. */
+  lastWriteAt: string;
+  /**
+   * That write's position in observation order. Two tool results can share a
+   * millisecond, so the ordering is decided here and `lastWriteAt` is what the
+   * refusal quotes. `0` means nothing has been written yet.
+   */
+  lastWriteSeq?: number;
+  /** The declared verification command. `null` when the declaration pinned none. */
+  runner: string | null;
+  tdd?: TddContext;
+};
+
+export type ObservedEvidence = {
+  command: string;
+  outcome: string;
+  at?: string;
+  /** The call this evidence came from, so the caller can record exactly it. */
+  toolCallId?: string;
+  tdd?: TddContext;
+};
+
+export type EvidenceDecision =
+  | { allow: true; observed: ObservedEvidence }
+  | { allow: false; gate: "evidence"; reason: string; remedy: Remedy };
+
+const REMEDY = "run the verification command, then check the task off once it is observed to succeed";
+
+/**
+ * Whether an observed command *is* the declared runner. Prefix match on whole
+ * tokens, so `npm test -- src/login.test.ts` counts and `echo npm test` does
+ * not: a runner narrowed to one file is the ordinary way a task verifies
+ * itself, while the runner quoted inside another command is not a run of it.
+ *
+ * Exported because `gate-promotion`'s failure streak counts runs of the same
+ * declared runner, and the two gates must agree on what "a run of it" means.
+ */
+export function isDeclaredRunner(command: string, runner: string): boolean {
+  const actual = command.trim().split(/\s+/);
+  const declared = runner.trim().split(/\s+/);
+  if (declared.length === 0 || actual.length < declared.length) return false;
+  return declared.every((token, i) => actual[i] === token);
+}
+
+function deny(reason: string, remedy: string = REMEDY): EvidenceDecision {
+  const refusal = refuse("evidence", reason, remedy);
+  return { allow: false, gate: "evidence", reason: refusal.reason, remedy: refusal.remedy };
+}
+
+export function evidenceGate(
+  committed: Committed,
+  ledger: LedgerRecord[],
+  request: CheckRequest,
+  policy: Policy,
+): EvidenceDecision {
+  if (!resolveFlag("evidence", policy).enabled) {
+    return { allow: true, observed: { command: "none", outcome: "none (gate disabled)" } };
+  }
+
+  const runs = committed.commandResults.map((result) => ({
+    ...result,
+    outcome: parseOutcome(result.isError, result.resultText),
+  }));
+
+  // A ledger record this kernel did not observe is unverified, not evidence; one
+  // it *did* observe and that says something else is a mismatch, which is a
+  // different and more serious failure. Passing the observed calls is what makes
+  // the second branch reachable at all.
+  const observedIds = new Set(runs.map((run) => run.toolCallId));
+  const observedCalls = new Map(runs.map((run) => [
+    run.toolCallId,
+    { command: run.command, outcome: describeOutcome(run.outcome) },
+  ]));
+  const { degraded } = classifyRecords(ledger, observedIds, observedCalls);
+
+  const contradicted = degraded.filter((entry) => entry.reason === "mismatch");
+  if (contradicted.length > 0) {
+    // Fail closed and say which way: the ledger on disk disagrees with what this
+    // process watched happen, so neither can be trusted to back a checkoff.
+    return deny(
+      `the ledger contradicts this session's observations: ${describeDegraded(contradicted).join(" ")}`,
+      "re-run the verification command so a fresh, observed result replaces the contradicted record",
+    );
+  }
+
+  if (runs.length === 0 && degraded.length > 0) {
+    // Resuming in a new process lands here every time, by design: evidence
+    // means "observed by this kernel", and a fresh process has observed
+    // nothing yet. Correct, but a bare "insufficient evidence" would read as a
+    // bug and get the gate switched off, so the refusal says what happened and
+    // what to do about it.
+    return deny(
+      `the ledger holds ${degraded.length} record(s) from a previous session, which this kernel did not observe, so they are unverified and cannot support a checkoff`,
+      "re-run the verification command in this session so the result is observed, then check the task off",
+    );
+  }
+
+  if (runs.length === 0) {
+    return deny(`no command has been observed running for ${request.task}, so there is nothing to record as evidence`);
+  }
+
+  // The declared check, before success is even considered: a green `echo` is
+  // not a failing test run, it is not a test run at all.
+  const relevant = request.runner === null
+    ? runs
+    : runs.filter((run) => isDeclaredRunner(run.command, request.runner!));
+  if (relevant.length === 0) {
+    const observed = runs.map((run) => `\`${run.command}\``).join(", ");
+    return deny(
+      `this feature declared \`${request.runner}\` as its verification runner, and no observed command was a run of it (observed: ${observed})`,
+      `run \`${request.runner}\`, then check ${request.task} off once it is observed to succeed`,
+    );
+  }
+
+  const green = relevant.filter((run) => isSuccess(run.outcome));
+  if (green.length === 0) {
+    const last = relevant[relevant.length - 1];
+    return deny(`the last observed run of \`${last.command}\` ended ${describeOutcome(last.outcome)}, which is not success`);
+  }
+
+  const afterWrite = green.filter((run) => run.seq > (request.lastWriteSeq ?? 0) && run.at >= request.lastWriteAt);
+  if (afterWrite.length === 0) {
+    const last = green[green.length - 1];
+    return deny(
+      `the only observed success (\`${last.command}\`) ran before the last write to ${request.task}, so it says nothing about the current code`,
+    );
+  }
+
+  if (request.tdd?.mode === "strict") {
+    const chosen = afterWrite[afterWrite.length - 1];
+    const red = relevant.find((run) => !isSuccess(run.outcome) && run.at <= chosen.at);
+    if (!red) {
+      return deny(
+        `TDD mode is strict (${request.tdd.source}) but no failing (RED) run was observed before this success, so the test was never seen to fail first`,
+      );
+    }
+  }
+
+  const chosen = afterWrite[afterWrite.length - 1];
+  return {
+    allow: true,
+    observed: {
+      command: chosen.command,
+      outcome: request.runner === null
+        ? `${describeOutcome(chosen.outcome)} (runner not pinned)`
+        : describeOutcome(chosen.outcome),
+      at: chosen.at,
+      toolCallId: chosen.toolCallId,
+      ...(request.tdd?.mode === "strict" ? { tdd: request.tdd } : {}),
+    },
+  };
+}
+
+/** The feature doc's evidence line. Never rendered from anything but a decision. */
+export function renderObserved(observed: ObservedEvidence | null): string {
+  if (!observed) return "observed: none";
+  if (observed.outcome === "none (gate disabled)") return "observed: none (gate disabled)";
+  return `observed: \`${observed.command}\` → ${observed.outcome}`;
+}

package/src/gates/policy.test.ts

@@ -0,0 +1,77 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { GATE_IDS } from "./registry.ts";
+import {
+  allow,
+  consumeHatch,
+  firstRefusal,
+  grantHatch,
+  refuse,
+  resolveFlag,
+  type Policy,
+} from "./policy.ts";
+
+function policy(over: Partial<Policy> = {}): Policy {
+  return { config: {}, flags: {}, hatches: {}, ...over };
+}
+
+test("every gate id has a default flag entry and defaults to on", () => {
+  for (const id of GATE_IDS) {
+    const resolved = resolveFlag(id, policy());
+    assert.equal(resolved.enabled, true, `${id} must default to enabled`);
+    assert.equal(resolved.source, "default", `${id} with nothing chosen must report source default`);
+  }
+});
+
+test("precedence is flag > config > default, and the source is retained", () => {
+  assert.deepEqual(resolveFlag("track", policy()), { enabled: true, source: "default" });
+  assert.deepEqual(
+    resolveFlag("track", policy({ config: { track: { enabled: false } } })),
+    { enabled: false, source: "config" },
+  );
+  assert.deepEqual(
+    resolveFlag("track", policy({ config: { track: { enabled: true } }, flags: { track: false } })),
+    { enabled: false, source: "flag" },
+  );
+  assert.deepEqual(
+    resolveFlag("track", policy({ flags: { all: false } })),
+    { enabled: false, source: "flag" },
+  );
+});
+
+test("a refusal carries a remedy with a concrete action and the escape hatch", () => {
+  const decision = refuse("track", "no feature doc at .nodd/x/feature.md", "call nodd_declare");
+  assert.equal(decision.allow, false);
+  assert.equal(decision.gate, "track");
+  assert.equal(decision.remedy.action, "call nodd_declare");
+  assert.equal(decision.remedy.escapeHatch, "/nodd-allow track");
+});
+
+test("every gate's refusal renders gate id, observation and both remedies", () => {
+  for (const id of GATE_IDS) {
+    const decision = refuse(id, `observed something for ${id}`, `do the ${id} thing`);
+    assert.equal(decision.allow, false);
+    assert.ok(decision.reason.includes(id), `${id}: reason names the gate`);
+    assert.ok(decision.reason.includes("observed something"), `${id}: reason names the observation`);
+    assert.ok(decision.reason.includes(`do the ${id} thing`), `${id}: reason names the action`);
+    assert.ok(decision.reason.includes(`/nodd-allow ${id}`), `${id}: reason names the escape hatch`);
+  }
+});
+
+test("the first refusal wins, so a call never gets two messages", () => {
+  const decisions = [allow(), refuse("classify", "a", "b"), refuse("track", "c", "d")];
+  const winner = firstRefusal(decisions);
+  assert.equal(winner?.gate, "classify");
+  assert.equal(firstRefusal([allow(), allow()]), null);
+});
+
+test("an escape hatch is one-shot and never crosses gates", () => {
+  let p = grantHatch(policy(), "track", "I know what I am doing");
+  assert.equal(consumeHatch(p, "classify"), null, "an override for track must not clear classify");
+
+  const consumed = consumeHatch(p, "track");
+  assert.ok(consumed);
+  assert.equal(consumed.reason, "I know what I am doing");
+  p = consumed.policy;
+  assert.equal(consumeHatch(p, "track"), null, "the override is consumed, so the next refusal blocks");
+});

package/src/gates/policy.ts

@@ -0,0 +1,90 @@
+// The shape every NODD gate shares: a decision, a flag and an escape hatch.
+//
+// `remedy` is non-optional on a refusal. A gate that blocks without telling the
+// agent how to proceed is the worst kind of gate — it turns enforcement into a
+// dead end — so the type makes that unwritable rather than merely discouraged.
+//
+// Flag resolution keeps its source instead of collapsing it to a boolean,
+// because `/nodd-gates status` has to answer "who decided this?" and `default`
+// has to mean "nobody chose" (`routing.go:114`).
+
+import type { GateId } from "./registry.ts";
+
+export type Remedy = {
+  action: string;
+  escapeHatch: `/nodd-allow ${GateId}`;
+};
+
+export type GateDecision =
+  | { allow: true }
+  | { allow: false; gate: GateId; reason: string; remedy: Remedy };
+
+export type FlagSource = "flag" | "config" | "default";
+export type ResolvedFlag = { enabled: boolean; source: FlagSource };
+
+export type Policy = {
+  /** From `~/.pi/nodd.json`. */
+  config: Record<string, { enabled: boolean }>;
+  /** From the `--nodd-off` CLI flag. `all` disables every gate. */
+  flags: Record<string, boolean>;
+  /** Granted one-shot overrides, by gate id. */
+  hatches: Record<string, { reason: string; at?: string }>;
+};
+
+export function emptyPolicy(): Policy {
+  return { config: {}, flags: {}, hatches: {} };
+}
+
+export function resolveFlag(gate: GateId, policy: Policy): ResolvedFlag {
+  if (policy.flags.all === false) return { enabled: false, source: "flag" };
+  const flag = policy.flags[gate];
+  if (typeof flag === "boolean") return { enabled: flag, source: "flag" };
+  const configured = policy.config[gate]?.enabled;
+  if (typeof configured === "boolean") return { enabled: configured, source: "config" };
+  // NODD's gates default on: enforcement is the product. Everything else about
+  // the kill switch is ODD's, unchanged.
+  return { enabled: true, source: "default" };
+}
+
+export function allow(): GateDecision {
+  return { allow: true };
+}
+
+/**
+ * Build a refusal. The rendered reason always carries three things: what was
+ * observed, the concrete action, and the escape hatch.
+ */
+export function refuse(gate: GateId, observed: string, action: string): GateDecision {
+  const escapeHatch = `/nodd-allow ${gate}` as const;
+  return {
+    allow: false,
+    gate,
+    reason: `nodd/${gate}: ${observed}. To proceed: ${action}. To override this once: ${escapeHatch}`,
+    remedy: { action, escapeHatch },
+  };
+}
+
+/** First refusal wins: a single call never collects two overlapping messages. */
+export function firstRefusal(decisions: GateDecision[]): Extract<GateDecision, { allow: false }> | null {
+  for (const decision of decisions) {
+    if (decision.allow === false) return decision;
+  }
+  return null;
+}
+
+export function grantHatch(policy: Policy, gate: GateId, reason: string, at?: string): Policy {
+  return { ...policy, hatches: { ...policy.hatches, [gate]: { reason, ...(at ? { at } : {}) } } };
+}
+
+/**
+ * Consume a one-shot override for exactly this gate. Returns the reason and the
+ * policy with the override spent, or null when there is none — never implicit,
+ * never permanent, never cross-gate.
+ */
+export function consumeHatch(policy: Policy, gate: GateId): { reason: string; policy: Policy } | null {
+  const hatch = policy.hatches[gate];
+  if (!hatch) return null;
+  const hatches = { ...policy.hatches };
+  delete hatches[gate];
+  return { reason: hatch.reason, policy: { ...policy, hatches } };
+}

package/src/gates/promotion.test.ts

@@ -0,0 +1,133 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { emptyPolicy } from "./policy.ts";
+import { promotionGate, type PromotionSignals } from "./promotion.ts";
+
+const noSignals: PromotionSignals = {
+  slug: "cache-warmup",
+  consecutiveFailures: 0,
+  failedTaskId: null,
+  declaredFiles: 0,
+  observedFiles: 0,
+};
+
+const request = { toolName: "write", input: { file_path: "/repo/src/cache.ts" } };
+
+function decide(signals: Partial<PromotionSignals>) {
+  return promotionGate({ ...noSignals, ...signals }, request, emptyPolicy());
+}
+
+// ---------------------------------------------------------------------------
+// Trigger 1 — two consecutive non-success outcomes on one task
+// ---------------------------------------------------------------------------
+test("two consecutive failures on one task block, naming the task and both attempts", () => {
+  const decision = decide({ consecutiveFailures: 2, failedTaskId: "T007" });
+  assert.equal(decision.allow, false);
+  if (decision.allow) return;
+  assert.ok(decision.reason.includes("T007"), "the blocked task is named");
+  assert.match(decision.reason, /2|dos/, "both attempts are counted");
+});
+
+test("one failure does not block: a first failure is normal work", () => {
+  assert.equal(decide({ consecutiveFailures: 1, failedTaskId: "T007" }).allow, true);
+});
+
+test("failure then success does not block: the streak is consecutive, not cumulative", () => {
+  // The caller resets the counter on success; the gate must not carry history
+  // of its own that could keep a resolved task blocked forever.
+  assert.equal(decide({ consecutiveFailures: 0, failedTaskId: "T007" }).allow, true);
+});
+
+// ---------------------------------------------------------------------------
+// Trigger 2 — mismatch between declared and observed files
+// ---------------------------------------------------------------------------
+test("3 files observed against 2 declared blocks with both counts", () => {
+  const decision = decide({ declaredFiles: 2, observedFiles: 3 });
+  assert.equal(decision.allow, false);
+  if (decision.allow) return;
+  assert.ok(decision.reason.includes("3") && decision.reason.includes("2"), decision.reason);
+});
+
+test("40 observed against 40 declared does not block: mismatch, not magnitude", () => {
+  assert.equal(decide({ declaredFiles: 40, observedFiles: 40 }).allow, true);
+});
+
+test("fewer files than declared does not block: doing less than planned is not divergence upward", () => {
+  assert.equal(decide({ declaredFiles: 9, observedFiles: 2 }).allow, true);
+});
+
+test("zero declared is not a mismatch: nothing was promised to diverge from", () => {
+  assert.equal(decide({ declaredFiles: 0, observedFiles: 12 }).allow, true);
+});
+
+// ---------------------------------------------------------------------------
+// The trigger that was specified and then removed
+// ---------------------------------------------------------------------------
+test("there is no user-request trigger: it was not derivable and is gone, not faked", () => {
+  // `/nodd-promote` lives in another extension with no path to kernel state and
+  // performs the promotion itself, so no gate could ever observe the asking.
+  // Round 1 shipped it as a hardcoded `false`, which is the exact failure this
+  // gate exists to refuse. It is absent from the type and from the source.
+  assert.ok(!("userRequested" in noSignals), "the signal is gone from the type");
+  const source = readFileSync(new URL("./promotion.ts", import.meta.url), "utf8")
+    .split("\n")
+    .filter((line) => !/^\s*(\/\/|\*|\/\*)/.test(line))
+    .join("\n");
+  assert.ok(!source.includes("userRequested"), "and gone from the executable code");
+});
+
+// ---------------------------------------------------------------------------
+// The two ways forward
+// ---------------------------------------------------------------------------
+test("a block offers exactly the promote command and the escape hatch", () => {
+  const decision = decide({ declaredFiles: 2, observedFiles: 3 });
+  assert.equal(decision.allow, false);
+  if (decision.allow) return;
+  assert.ok(decision.remedy.action.includes("/nodd-promote cache-warmup"), decision.remedy.action);
+  assert.equal(decision.remedy.escapeHatch, "/nodd-allow promotion");
+});
+
+test("no trigger at all allows", () => {
+  assert.equal(decide({}).allow, true);
+});
+
+// ---------------------------------------------------------------------------
+// Kill switch
+// ---------------------------------------------------------------------------
+test("disabling the gate turns it off entirely, even with every trigger firing", () => {
+  const policy = { ...emptyPolicy(), config: { promotion: { enabled: false } } };
+  const decision = promotionGate(
+    { slug: "x", consecutiveFailures: 5, failedTaskId: "npm test", declaredFiles: 1, observedFiles: 99 },
+    request,
+    policy,
+  );
+  assert.equal(decision.allow, true, "a user-owned kill switch is not advisory");
+});
+
+// ---------------------------------------------------------------------------
+// The part of routing.go:68 NODD keeps
+// ---------------------------------------------------------------------------
+test("no promotion path reads a line count, a byte size or a risk score", () => {
+  const source = readFileSync(new URL("./promotion.ts", import.meta.url), "utf8")
+    .split("\n")
+    .filter((line) => !/^\s*(\/\/|\*|\/\*)/.test(line))
+    .join("\n");
+
+  for (const forbidden of ["lineCount", "linesChanged", "byteSize", "risk", "complexity", "estimate", "forecast"]) {
+    assert.ok(!source.includes(forbidden), `promotion must not read ${forbidden}`);
+  }
+  assert.ok(!source.includes("countAuthoredLines"), "the delivery counter is off limits to gates");
+  assert.ok(!/from "\.\.\/delivery\.ts"/.test(source), "promotion must not import delivery");
+});
+
+test("the signals type exposes no size field at all", () => {
+  const signals: PromotionSignals = { ...noSignals };
+  assert.deepEqual(Object.keys(signals).sort(), [
+    "consecutiveFailures",
+    "declaredFiles",
+    "failedTaskId",
+    "observedFiles",
+    "slug",
+  ]);
+});

package/src/gates/promotion.ts

@@ -0,0 +1,81 @@
+// gate-promotion — escalate on divergence, never on size.
+//
+// `REQ: escalation-divergence`. ODD escalates a route by predicted magnitude
+// (`routing.go:68`); NODD keeps only the half of that decision it can observe.
+// The two triggers are:
+//
+//   1. two consecutive non-`success` outcomes of the declared runner — the plan
+//      is not working, which is a fact about observed results;
+//   2. a task writing more distinct files than it declared — the work is not
+//      the shape it was declared to be;
+//
+// ## The trigger that was removed
+//
+// A third trigger, "the user asked", was specified and then deleted, because it
+// was not derivable. `/nodd-promote` lives in another extension with no path to
+// kernel state, and it *performs* the promotion rather than requesting one —
+// there is no moment at which a gate could observe the asking and still have
+// something left to do about it. Round 1 shipped it as a hardcoded `false`,
+// which is the failure this whole gate exists to refuse: a fabricated signal is
+// worse than an absent one, so the condition is gone from the type, the gate,
+// the requirement and the README rather than left there looking operational.
+//
+// **No size, line count, byte count or risk score is read.** A big task that
+// succeeds is not divergent, and a three-line task that fails twice is. The
+// counts this gate does use are *declared vs observed*, which is a mismatch, not
+// a magnitude: 40 files against 40 declared allows, 3 against 2 blocks. A test
+// scans this file for every size-flavoured identifier, including any import of
+// `delivery.ts`, whose line counter exists to inform a human and must never
+// reach a gate.
+//
+// A block offers exactly two ways forward, because a gate that stops the work
+// without naming the exit is a dead end.
+
+import { allow, refuse, resolveFlag, type GateDecision, type Policy } from "./policy.ts";
+import type { GateRequest } from "./request.ts";
+import { isFileWrite } from "./request.ts";
+
+export type PromotionSignals = {
+  slug: string;
+  /** Trailing non-`success` outcomes of the declared runner, derived by the caller. */
+  consecutiveFailures: number;
+  /** The command whose runs failed, quoted in the refusal. */
+  failedTaskId: string | null;
+  /** Distinct files the current task said it would touch. */
+  declaredFiles: number;
+  /** Distinct files it has actually written. */
+  observedFiles: number;
+};
+
+const CONSECUTIVE_FAILURE_LIMIT = 2;
+
+export function promotionGate(signals: PromotionSignals, request: GateRequest, policy: Policy): GateDecision {
+  if (!resolveFlag("promotion", policy).enabled) return allow();
+  if (!isFileWrite(request)) return allow();
+
+  const action =
+    `promote the run with \`/nodd-promote ${signals.slug}\` so forge plans the rest, ` +
+    "or keep going here if you judge the divergence is not real";
+
+  if (signals.consecutiveFailures >= CONSECUTIVE_FAILURE_LIMIT) {
+    return refuse(
+      "promotion",
+      `task ${signals.failedTaskId ?? "(unnamed)"} has failed ${signals.consecutiveFailures} times in a row: ` +
+        "the plan is not working, which is what escalation is for",
+      action,
+    );
+  }
+
+  // Zero declared means nothing was promised, so there is nothing to diverge
+  // from — that is an undeclared task, which is `gate-track`'s business.
+  if (signals.declaredFiles > 0 && signals.observedFiles > signals.declaredFiles) {
+    return refuse(
+      "promotion",
+      `this task declared ${signals.declaredFiles} file(s) and has written ${signals.observedFiles}: ` +
+        "the work is not the shape it was declared to be",
+      action,
+    );
+  }
+
+  return allow();
+}

package/src/gates/registry.ts

@@ -0,0 +1,21 @@
+// The gate list, in evaluation order. First refusal wins.
+//
+// The order is not cosmetic. `authorize` and `classify` are deliberately
+// disjoint — `authorize` speaks only when an intent *was* declared read-only,
+// `classify` only when nothing was declared — so the same call never collects
+// two messages saying different things about the same missing declaration.
+
+export const GATE_IDS = Object.freeze([
+  "authorize",
+  "classify",
+  "track",
+  "delegate",
+  "evidence",
+  "promotion",
+] as const);
+
+export type GateId = (typeof GATE_IDS)[number];
+
+export function isGateId(value: string): value is GateId {
+  return (GATE_IDS as readonly string[]).includes(value);
+}

package/src/gates/request.ts

@@ -0,0 +1,41 @@
+// The shape a gate sees: one tool call, before it runs.
+//
+// This is the extension's translation of pi's `ToolCallEvent`
+// (`types.d.ts:649-691`) into something pure. Gates never touch pi types.
+
+import { classifyBash } from "../bash-classifier.ts";
+
+export type GateRequest = {
+  toolName: string;
+  input: Record<string, unknown>;
+};
+
+export function targetPath(request: GateRequest): string | null {
+  const path = request.input?.path;
+  return typeof path === "string" && path !== "" ? path : null;
+}
+
+/** A direct, typed file write: `write` or `edit`. Exactly gateable. */
+export function isFileWrite(request: GateRequest): boolean {
+  return request.toolName === "write" || request.toolName === "edit";
+}
+
+/** A bash call whose command matches the documented mutation denylist. */
+export function isMutatingBash(request: GateRequest): boolean {
+  if (request.toolName !== "bash") return false;
+  const command = request.input?.command;
+  return typeof command === "string" && classifyBash(command) === "mutating";
+}
+
+/**
+ * Any observable attempt to change the workspace: a typed write, or a bash
+ * command the classifier recognises as mutating.
+ */
+export function isMutation(request: GateRequest): boolean {
+  return isFileWrite(request) || isMutatingBash(request);
+}
+
+/** Delegating to a writer is a mutation by proxy (`routing.go:44`). */
+export function isDelegation(request: GateRequest): boolean {
+  return request.toolName === "subagent";
+}