@gonrocca/nodd 0.1.0

package/src/delivery.ts

@@ -0,0 +1,151 @@
+// Delivery strategy: recorded and measured, never enforced.
+//
+// `routing.go:103` gives ODD's delivery vocabulary. NODD splits it honestly
+// instead of pretending one mechanism covers it:
+//
+//   - **record** (here): a `## Delivery` section holding strategy, chain,
+//     forecast, running count and the slice boundaries with their commits. Both
+//     choices are cached so they are asked once.
+//   - **measure** (here): the running count is additions plus deletions parsed
+//     from observed `git` diffstat output, with a documented generated-file
+//     exclusion list. Unparseable output leaves it `unknown` — same fail-closed
+//     rule as the command outcomes (T019). A guessed number would be worse than
+//     no number, because it would look like a measurement.
+//   - **ask** (prose): asking is conversation.
+//   - **execute** (out of scope): `/zero-branch` and `/zero-pr` already do it,
+//     and ODD itself says push, PR and merge stay the user's (`routing.go:50`).
+//
+// The ~400-line crossing **emits no block**. `routing.go:95` calls the figure a
+// planning heuristic and explicitly not a hard cap, not an automatic stop and
+// not a forced split. Turning it into a gate would violate the very clause it
+// comes from, so `crossedForecast` returns a fact for the prompt to mention and
+// nothing in `src/gates/` may import this module at all.
+
+export type Strategy = "ask-on-risk" | "auto-chain" | "single-pr" | "exception-ok";
+export type Chain = "stacked-to-main" | "feature-branch-chain";
+
+const STRATEGIES: readonly string[] = ["ask-on-risk", "auto-chain", "single-pr", "exception-ok"];
+const CHAINS: readonly string[] = ["stacked-to-main", "feature-branch-chain"];
+
+export function isStrategy(value: string): value is Strategy {
+  return STRATEGIES.includes(value);
+}
+
+export function isChain(value: string): value is Chain {
+  return CHAINS.includes(value);
+}
+
+/** A slice's (base, head) pair. Chained by `src/review-candidate.ts`. */
+export type DeliveryBoundary = { base: string; head: string };
+
+export type Delivery = {
+  strategy: Strategy;
+  chain: Chain;
+  /** Authored changed lines forecast at feature-doc creation. */
+  forecast: number;
+  /** Measured so far, or `unknown` when no diffstat has been parsed. */
+  running: number | "unknown";
+  boundaries: DeliveryBoundary[];
+};
+
+export function defaultDelivery(): Delivery {
+  return {
+    // `ask-on-risk` is the default because the asking is the part NODD does not
+    // mechanize: defaulting to `auto-chain` would decide it silently.
+    strategy: "ask-on-risk",
+    chain: "stacked-to-main",
+    forecast: 0,
+    running: "unknown",
+    boundaries: [],
+  };
+}
+
+/**
+ * Paths whose churn is not authored work. Documented rather than inferred: a
+ * heuristic nobody can read is a heuristic nobody can correct.
+ */
+export const GENERATED_PATHS: RegExp[] = [
+  /(^|\/)package-lock\.json$/,
+  /(^|\/)pnpm-lock\.yaml$/,
+  /(^|\/)yarn\.lock$/,
+  /(^|\/)Cargo\.lock$/,
+  /(^|\/)poetry\.lock$/,
+  /(^|\/)(dist|build|out|coverage|node_modules|vendor)\//,
+  /\.min\.(js|css)$/,
+  /\.(snap|lock)$/,
+];
+
+function isGenerated(path: string): boolean {
+  return GENERATED_PATHS.some((pattern) => pattern.test(path));
+}
+
+/**
+ * Additions plus deletions of authored lines, from observed `git diff --stat`
+ * output. Per-file rows are the source: the summary line cannot be attributed to
+ * a path, so it cannot honour the exclusion list.
+ *
+ * Returns `unknown` when no per-file row parses. A diffstat whose every row is
+ * generated returns `0` — that is a measurement, not an absence.
+ */
+export function countAuthoredLines(gitOutput: string): number | "unknown" {
+  const rows = /^\s*(\S.*?)\s+\|\s+(\d+)\s*([+-]*)\s*$/gm;
+  let total = 0;
+  let parsedAny = false;
+
+  for (const match of (gitOutput ?? "").matchAll(rows)) {
+    const [, path, , marks] = match;
+    parsedAny = true;
+    if (isGenerated(path)) continue;
+    // The bar graph is scaled for wide diffs, so `+`/`-` counts are only
+    // trustworthy when they add up to the row's own total.
+    const changed = Number(match[2]);
+    const plus = (marks.match(/\+/g) ?? []).length;
+    const minus = (marks.match(/-/g) ?? []).length;
+    total += plus + minus === changed ? plus + minus : changed;
+  }
+
+  return parsedAny ? total : "unknown";
+}
+
+/**
+ * Whether the measured count passed the forecast. A fact for the dynamic prompt
+ * to mention. `unknown` never claims a crossing — fail-closed both ways.
+ */
+export function crossedForecast(delivery: Delivery): boolean {
+  return delivery.running !== "unknown" && delivery.forecast > 0 && delivery.running > delivery.forecast;
+}
+
+export function renderDelivery(delivery: Delivery): string[] {
+  return [
+    `- strategy: ${delivery.strategy}`,
+    `- chain: ${delivery.chain}`,
+    `- forecast: ${delivery.forecast}`,
+    `- running: ${delivery.running}`,
+    ...delivery.boundaries.map((b) => `- boundary: ${b.base}..${b.head}`),
+  ];
+}
+
+export function parseDelivery(block: string): Delivery {
+  const field = (name: string): string | null => {
+    const match = new RegExp(`^- ${name}: (.+)$`, "m").exec(block);
+    return match ? match[1].trim() : null;
+  };
+
+  const strategy = field("strategy");
+  const chain = field("chain");
+  const running = field("running");
+  const forecast = Number(field("forecast"));
+
+  const boundaries: DeliveryBoundary[] = [];
+  for (const match of block.matchAll(/^- boundary: (\S+)\.\.(\S+)$/gm)) {
+    boundaries.push({ base: match[1], head: match[2] });
+  }
+
+  return {
+    strategy: strategy && isStrategy(strategy) ? strategy : "ask-on-risk",
+    chain: chain && isChain(chain) ? chain : "stacked-to-main",
+    forecast: Number.isFinite(forecast) ? forecast : 0,
+    running: running !== null && /^\d+$/.test(running) ? Number(running) : "unknown",
+    boundaries,
+  };
+}

package/src/feature-doc.test.ts

@@ -0,0 +1,120 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { emptyDoc, parseFeatureDoc, renderFeatureDoc, renderOutcome, type FeatureDoc } from "./feature-doc.ts";
+
+function docWithTasks(n: number): FeatureDoc {
+  const doc = emptyDoc({ slug: "demo", title: "Demo feature" });
+  doc.objective = "Make the thing work.";
+  doc.problem = "The thing does not work.";
+  doc.scope = "- src/thing.ts";
+  doc.constraints = "- no new dependencies";
+  doc.route = { intent: "change", route: "tracked" };
+  doc.verification = { runner: "npm test", tdd: "off", source: "nodd_declare", files: ["src/thing.ts"] };
+  doc.progress = "- started";
+  for (let i = 1; i <= n; i++) {
+    doc.tasks.push(
+      i === 2
+        ? {
+            id: `T${i}`,
+            title: `Task ${i}`,
+            checked: true,
+            evidence: { command: "npm test", outcome: "success" },
+            candidate: "1a2b3c4",
+          }
+        : { id: `T${i}`, title: `Task ${i}`, checked: false },
+    );
+  }
+  return doc;
+}
+
+for (const n of [0, 1, 3]) {
+  test(`parse(render(doc)) round-trips with ${n} tasks`, () => {
+    const doc = docWithTasks(n);
+    const parsed = parseFeatureDoc(renderFeatureDoc(doc));
+    assert.deepEqual(parsed.defects, []);
+    assert.deepEqual(parsed.doc, doc);
+  });
+}
+
+test("rendering is deterministic to the byte", () => {
+  const doc = docWithTasks(3);
+  assert.equal(renderFeatureDoc(doc), renderFeatureDoc(doc));
+});
+
+test("a checked task renders its observed evidence inline", () => {
+  const rendered = renderFeatureDoc(docWithTasks(3));
+  assert.match(rendered, /- \[x\] T2\. Task 2\n {2}- observed: `npm test` → success/);
+  assert.match(rendered, /- \[ \] T1\. Task 1/);
+});
+
+test("a checked task renders its review candidate, never its checkbox", () => {
+  const rendered = renderFeatureDoc(docWithTasks(3));
+  assert.match(rendered, /- \[x\] T2\. Task 2\n {2}- observed: `npm test` → success\n {2}- candidate: 1a2b3c4/);
+});
+
+test("a checked task without a candidate parses as a defect, not as checked", () => {
+  const text = renderFeatureDoc(docWithTasks(3)).replace("  - candidate: 1a2b3c4\n", "");
+  const parsed = parseFeatureDoc(text);
+  assert.ok(
+    parsed.defects.some((d) => d.includes("T2") && d.includes("candidate")),
+    `defects should name the missing candidate: ${JSON.stringify(parsed.defects)}`,
+  );
+  assert.equal(parsed.doc.tasks[1].checked, false, "a checkoff NODD cannot attribute is not a checkoff");
+});
+
+test("a missing section returns a typed defect list, never a throw", () => {
+  const broken = "# Feature: Demo\n\n## Objective\n\nx\n";
+  const parsed = parseFeatureDoc(broken);
+  assert.ok(parsed.defects.length > 0);
+  for (const missing of ["## Problem", "## Scope", "## Constraints", "## Route", "## Tasks"]) {
+    assert.ok(
+      parsed.defects.some((d) => d.includes(missing)),
+      `defects should name ${missing}: ${JSON.stringify(parsed.defects)}`,
+    );
+  }
+  assert.equal(parsed.doc.objective, "x");
+});
+
+test("the slug survives the round trip", () => {
+  const parsed = parseFeatureDoc(renderFeatureDoc(docWithTasks(1)));
+  assert.equal(parsed.doc.slug, "demo");
+});
+
+// ---------------------------------------------------------------------------
+// The declared verification contract (`## Verification`)
+// ---------------------------------------------------------------------------
+test("the declared runner and TDD mode survive the round trip", () => {
+  const parsed = parseFeatureDoc(renderFeatureDoc(docWithTasks(1)));
+  assert.equal(parsed.doc.verification.runner, "npm test");
+  assert.equal(parsed.doc.verification.source, "nodd_declare");
+  assert.deepEqual(parsed.doc.verification.files, ["src/thing.ts"]);
+});
+
+test("an undeclared runner round-trips as null, never as an invented command", () => {
+  const doc = emptyDoc({ slug: "bare", title: "Bare" });
+  const parsed = parseFeatureDoc(renderFeatureDoc(doc));
+  assert.equal(parsed.doc.verification.runner, null);
+  assert.equal(parsed.doc.verification.tdd, "off");
+  assert.deepEqual(parsed.doc.verification.files, []);
+});
+
+// ---------------------------------------------------------------------------
+// Matrix row 13: a pending check cannot be dropped from the close report
+// ---------------------------------------------------------------------------
+test("the Outcome section is derived from the tasks, so a pending check cannot be omitted", () => {
+  const rendered = renderFeatureDoc(docWithTasks(3));
+  const outcome = rendered.split("## Outcome")[1].split("## Progress")[0];
+
+  assert.match(outcome, /verified: 1 of 3/, "the count is reported, not asserted");
+  assert.match(outcome, /\[x\] T2: `npm test` → success/, "a verified task carries its observed evidence");
+  for (const pending of ["T1", "T3"]) {
+    assert.match(outcome, new RegExp(`\\[ \\] ${pending}: no observed verification yet`), `${pending} must appear as pending`);
+  }
+});
+
+test("no caller can author the Outcome section: it is a function of the task list", () => {
+  const doc = docWithTasks(3);
+  assert.ok(!("outcome" in doc), "there is no free-text outcome field to forge");
+  assert.deepEqual(renderOutcome(doc), renderOutcome({ ...doc }));
+  assert.deepEqual(renderOutcome(emptyDoc({ slug: "s", title: "T" })), ["No tasks declared yet."]);
+});

package/src/feature-doc.ts

@@ -0,0 +1,292 @@
+// `.nodd/<slug>/feature.md` — extension-owned, never authored freehand by the
+// model. The schema follows gentle's `odd/tasks/<feature>.md`
+// (`odd/tasks/odd-mandatory-delegation.md`): title, Objective, Problem, Scope,
+// Constraints, Route, Tasks, Outcome, Progress.
+//
+// Two properties make this file evidence rather than prose: a checked task
+// carries its evidence reference *by type*, so rendering a `[x]` without one
+// does not compile; and a missing section returns a defect list instead of
+// throwing, because a half-written doc must be reported, not crash a session.
+
+import { defaultDelivery, parseDelivery, renderDelivery, type Delivery } from "./delivery.ts";
+
+export type Intent = "read-only" | "change";
+export type Route = "inline" | "tracked" | "forge";
+
+/**
+ * How this feature is verified, fixed at declaration time. `gate-evidence` will
+ * only accept a run of `runner`, so a checkoff cannot be satisfied by whatever
+ * exit-0 string the model happens to produce. `source` records who decided, per
+ * `routing.go:101`: the presence of a framework is not a choice.
+ */
+export type Verification = {
+  runner: string | null;
+  tdd: "strict" | "off";
+  source: string;
+  /** The distinct files the declaration promised to touch. */
+  files: string[];
+};
+
+export type TaskEvidence = {
+  command: string;
+  /** Rendered verbatim. `src/outcome.ts` owns the vocabulary. */
+  outcome: string;
+};
+
+/**
+ * A checked task carries both its observed evidence and its review candidate,
+ * by type. The candidate is a commit SHA or the literal `pending-commit`
+ * (`src/review-candidate.ts`) — never the checkbox, per `routing.go:51`,`:102`.
+ */
+export type Task =
+  | { id: string; title: string; checked: false }
+  | { id: string; title: string; checked: true; evidence: TaskEvidence; candidate: string };
+
+export type FeatureDoc = {
+  slug: string;
+  title: string;
+  objective: string;
+  problem: string;
+  scope: string;
+  constraints: string;
+  route: { intent: Intent; route: Route };
+  verification: Verification;
+  /** Recorded and measured, never enforced (`src/delivery.ts`). */
+  delivery: Delivery;
+  tasks: Task[];
+  progress: string;
+};
+
+export type ParsedFeatureDoc = { doc: FeatureDoc; defects: string[] };
+
+export function emptyDoc(fields: { slug: string; title: string }): FeatureDoc {
+  return {
+    slug: fields.slug,
+    title: fields.title,
+    objective: "",
+    problem: "",
+    scope: "",
+    constraints: "",
+    route: { intent: "change", route: "inline" },
+    verification: { runner: null, tdd: "off", source: "undeclared", files: [] },
+    delivery: defaultDelivery(),
+    tasks: [],
+    progress: "",
+  };
+}
+
+/**
+ * `## Outcome`, rendered from the task list rather than stored.
+ *
+ * Matrix row 13 (`routing.go:51`) requires that a close report cannot drop a
+ * failed or pending check. A free-text field can: in round 1 this was a string
+ * nothing ever wrote, so the section was permanently empty while the matrix
+ * claimed it was "rendered from the ledger". Deriving it makes the claim true —
+ * a pending task is in this section because it is in the list, and no caller
+ * can omit it.
+ */
+export function renderOutcome(doc: FeatureDoc): string[] {
+  if (doc.tasks.length === 0) return ["No tasks declared yet."];
+
+  const done = doc.tasks.filter((task) => task.checked);
+  const pending = doc.tasks.filter((task) => !task.checked);
+  const lines = [`- verified: ${done.length} of ${doc.tasks.length} task(s)`];
+
+  for (const task of done) {
+    if (task.checked) lines.push(`- [x] ${task.id}: \`${task.evidence.command}\` → ${task.evidence.outcome}`);
+  }
+  for (const task of pending) {
+    lines.push(`- [ ] ${task.id}: no observed verification yet`);
+  }
+  return lines;
+}
+
+const SECTIONS = [
+  "Objective",
+  "Problem",
+  "Scope",
+  "Constraints",
+  "Route",
+  "Verification",
+  "Delivery",
+  "Tasks",
+  "Outcome",
+  "Progress",
+] as const;
+
+function renderVerification(v: Verification): string[] {
+  return [
+    `- runner: ${v.runner ?? "none declared"}`,
+    `- tdd: ${v.tdd}`,
+    `- source: ${v.source}`,
+    `- files: ${v.files.length > 0 ? v.files.join(", ") : "none declared"}`,
+  ];
+}
+
+function parseVerification(block: string): Verification {
+  const field = (name: string): string | null => {
+    const match = new RegExp(`^- ${name}: (.+)$`, "m").exec(block);
+    const value = match ? match[1].trim() : null;
+    return value === null || value === "none declared" ? null : value;
+  };
+  const files = field("files");
+  return {
+    runner: field("runner"),
+    tdd: field("tdd") === "strict" ? "strict" : "off",
+    source: field("source") ?? "undeclared",
+    files: files === null ? [] : files.split(",").map((part) => part.trim()).filter((part) => part !== ""),
+  };
+}
+
+function renderTask(task: Task): string {
+  const box = task.checked ? "x" : " ";
+  const head = `- [${box}] ${task.id}. ${task.title}`;
+  if (!task.checked) return head;
+  return [
+    head,
+    `  - observed: \`${task.evidence.command}\` → ${task.evidence.outcome}`,
+    `  - candidate: ${task.candidate}`,
+  ].join("\n");
+}
+
+export function renderFeatureDoc(doc: FeatureDoc): string {
+  const body = [
+    `# Feature: ${doc.title}`,
+    "",
+    `<!-- nodd:slug ${doc.slug} -->`,
+    "",
+    "## Objective",
+    "",
+    doc.objective,
+    "",
+    "## Problem",
+    "",
+    doc.problem,
+    "",
+    "## Scope",
+    "",
+    doc.scope,
+    "",
+    "## Constraints",
+    "",
+    doc.constraints,
+    "",
+    "## Route",
+    "",
+    `- intent: ${doc.route.intent}`,
+    `- route: ${doc.route.route}`,
+    "",
+    "## Verification",
+    "",
+    ...renderVerification(doc.verification),
+    "",
+    "## Delivery",
+    "",
+    ...renderDelivery(doc.delivery),
+    "",
+    "## Tasks",
+    "",
+    doc.tasks.map(renderTask).join("\n"),
+    "",
+    "## Outcome",
+    "",
+    ...renderOutcome(doc),
+    "",
+    "## Progress",
+    "",
+    doc.progress,
+    "",
+  ];
+  return body.join("\n");
+}
+
+/** Split the body into `## <name>` sections, preserving each block's text. */
+function splitSections(text: string): Map<string, string> {
+  const out = new Map<string, string>();
+  let current: string | null = null;
+  let buffer: string[] = [];
+  for (const line of text.split("\n")) {
+    const heading = /^## (.+)$/.exec(line);
+    if (heading) {
+      if (current) out.set(current, buffer.join("\n").trim());
+      current = heading[1].trim();
+      buffer = [];
+    } else if (current) {
+      buffer.push(line);
+    }
+  }
+  if (current) out.set(current, buffer.join("\n").trim());
+  return out;
+}
+
+function parseTasks(block: string, defects: string[]): Task[] {
+  const tasks: Task[] = [];
+  const lines = block.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const item = /^- \[( |x)\] (\S+)\. (.*)$/.exec(lines[i]);
+    if (!item) continue;
+    const [, box, id, title] = item;
+    if (box !== "x") {
+      tasks.push({ id, title, checked: false });
+      continue;
+    }
+    const evidence = /^ {2}- observed: `(.*)` → (.+)$/.exec(lines[i + 1] ?? "");
+    if (!evidence) {
+      defects.push(`task ${id} is checked but carries no observed evidence line`);
+      tasks.push({ id, title, checked: false });
+      continue;
+    }
+    const candidate = /^ {2}- candidate: (.+)$/.exec(lines[i + 2] ?? "");
+    if (!candidate) {
+      defects.push(`task ${id} is checked but carries no review candidate line`);
+      tasks.push({ id, title, checked: false });
+      continue;
+    }
+    i += 2;
+    tasks.push({
+      id,
+      title,
+      checked: true,
+      evidence: { command: evidence[1], outcome: evidence[2] },
+      candidate: candidate[1].trim(),
+    });
+  }
+  return tasks;
+}
+
+export function parseFeatureDoc(text: string): ParsedFeatureDoc {
+  const defects: string[] = [];
+  const title = /^# Feature: (.+)$/m.exec(text)?.[1]?.trim() ?? "";
+  if (!title) defects.push("missing the `# Feature: <title>` heading");
+  const slug = /<!-- nodd:slug (\S+) -->/.exec(text)?.[1] ?? "";
+  if (!slug) defects.push("missing the `nodd:slug` marker");
+
+  const sections = splitSections(text);
+  for (const name of SECTIONS) {
+    if (!sections.has(name)) defects.push(`missing section \`## ${name}\``);
+  }
+
+  const routeBlock = sections.get("Route") ?? "";
+  const intent = /- intent: (\S+)/.exec(routeBlock)?.[1];
+  const route = /- route: (\S+)/.exec(routeBlock)?.[1];
+
+  return {
+    doc: {
+      slug,
+      title,
+      objective: sections.get("Objective") ?? "",
+      problem: sections.get("Problem") ?? "",
+      scope: sections.get("Scope") ?? "",
+      constraints: sections.get("Constraints") ?? "",
+      route: {
+        intent: intent === "read-only" || intent === "change" ? intent : "change",
+        route: route === "tracked" || route === "forge" ? route : "inline",
+      },
+      verification: parseVerification(sections.get("Verification") ?? ""),
+      delivery: parseDelivery(sections.get("Delivery") ?? ""),
+      tasks: parseTasks(sections.get("Tasks") ?? "", defects),
+      progress: sections.get("Progress") ?? "",
+    },
+    defects,
+  };
+}

package/src/gates/authorize.test.ts

@@ -0,0 +1,62 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { emptyCommitted, fold, type Committed } from "../state.ts";
+import { observation } from "../observations.ts";
+import { emptyPolicy } from "./policy.ts";
+import { authorizeGate } from "./authorize.ts";
+
+function declared(intent: "read-only" | "change"): Committed {
+  return fold(emptyCommitted(), observation({
+    toolCallId: "d1", toolName: "nodd_declare",
+    input: { intent, route: "inline", slug: "demo" },
+    isError: false, resultText: "", at: "t",
+  }));
+}
+
+const write = { toolName: "write", input: { path: "src/a.ts" } };
+
+test("read-only blocks a write and the reason names the declaration", () => {
+  const decision = authorizeGate(declared("read-only"), write, emptyPolicy());
+  assert.equal(decision.allow, false);
+  assert.ok(decision.allow === false && decision.reason.includes("read-only"));
+  assert.ok(decision.allow === false && decision.remedy.escapeHatch === "/nodd-allow authorize");
+});
+
+test("read-only blocks edit, mutating bash and the subagent writer", () => {
+  const state = declared("read-only");
+  for (const request of [
+    { toolName: "edit", input: { path: "a.ts" } },
+    { toolName: "bash", input: { command: "echo x > f" } },
+    { toolName: "subagent", input: { agent: "nodd-implement", prompt: "write the thing" } },
+  ]) {
+    assert.equal(authorizeGate(state, request, emptyPolicy()).allow, false, `${request.toolName} must block`);
+  }
+});
+
+test("read-only allows reading, searching and non-mutating bash", () => {
+  const state = declared("read-only");
+  for (const request of [
+    { toolName: "read", input: { path: "a.ts" } },
+    { toolName: "grep", input: { pattern: "x" } },
+    { toolName: "ls", input: { path: "." } },
+    { toolName: "bash", input: { command: "npm test" } },
+    { toolName: "bash", input: { command: "git status" } },
+  ]) {
+    assert.equal(authorizeGate(state, request, emptyPolicy()).allow, true, `${JSON.stringify(request.input)} must pass`);
+  }
+});
+
+test("intent: change allows the write", () => {
+  assert.equal(authorizeGate(declared("change"), write, emptyPolicy()).allow, true);
+});
+
+// The two gates are disjoint on purpose: `classify` owns the undeclared case,
+// so a single call never collects two messages about the same missing thing.
+test("an undeclared state returns allow — that is gate-classify's job", () => {
+  assert.equal(authorizeGate(emptyCommitted(), write, emptyPolicy()).allow, true);
+});
+
+test("the flag off allows the read-only write", () => {
+  const policy = { ...emptyPolicy(), config: { authorize: { enabled: false } } };
+  assert.equal(authorizeGate(declared("read-only"), write, policy).allow, true);
+});

package/src/gates/authorize.ts

@@ -0,0 +1,32 @@
+// gate-authorize — read-only work stays read-only.
+//
+// `routing.go:43-44`: investigation, explanation, review, audit and planning
+// requests are read-only unless the user explicitly asked for a change; such
+// work "may inspect, explain, compare, and recommend, but must not write or
+// edit files, delegate a writer, invoke apply, or create implementation
+// artifacts". Delegating a writer counts, which is why `subagent` is blocked
+// here too — otherwise read-only would mean "do not write it yourself".
+//
+// This gate is silent when nothing was declared. That case belongs to
+// `gate-classify`, and the two never double-block the same call.
+
+import type { Committed } from "../state.ts";
+import { allow, refuse, resolveFlag, type GateDecision, type Policy } from "./policy.ts";
+import { isDelegation, isMutation } from "./request.ts";
+import type { GateRequest } from "./request.ts";
+
+export function authorizeGate(committed: Committed, request: GateRequest, policy: Policy): GateDecision {
+  if (!resolveFlag("authorize", policy).enabled) return allow();
+
+  const declaration = committed.declaration;
+  if (!declaration || declaration.intent !== "read-only") return allow();
+
+  if (!isMutation(request) && !isDelegation(request)) return allow();
+
+  const what = isDelegation(request) ? `delegating to a writer (${request.toolName})` : `${request.toolName}`;
+  return refuse(
+    "authorize",
+    `this request was declared \`intent: read-only\`, and ${what} would change the workspace`,
+    "if the user did authorize a change, call `nodd_declare` again with `intent: change`",
+  );
+}