@gonrocca/nodd 0.1.0

package/src/gates/track.test.ts

@@ -0,0 +1,80 @@
+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 { trackGate } from "./track.ts";
+
+function routed(route: "inline" | "tracked" | "forge", slug = "demo"): Committed {
+  return fold(emptyCommitted(), observation({
+    toolCallId: "d1", toolName: "nodd_declare",
+    input: { intent: "change", route, slug },
+    isError: false, resultText: "", at: "t",
+  }));
+}
+
+const write = { toolName: "write", input: { path: "src/a.ts" } };
+const absent = () => false;
+const present = () => true;
+
+test("a missing feature doc blocks the first write, naming the exact path", () => {
+  const decision = trackGate(routed("tracked"), write, emptyPolicy(), absent);
+  assert.equal(decision.allow, false);
+  assert.ok(decision.allow === false && decision.reason.includes(".nodd/demo/feature.md"));
+  assert.ok(decision.allow === false && decision.remedy.action.includes("nodd_declare"));
+  assert.ok(decision.allow === false && decision.remedy.escapeHatch === "/nodd-allow track");
+});
+
+test("a present feature doc allows the write", () => {
+  assert.equal(trackGate(routed("tracked"), write, emptyPolicy(), present).allow, true);
+});
+
+test("route forge is tracked too", () => {
+  assert.equal(trackGate(routed("forge"), write, emptyPolicy(), absent).allow, false);
+});
+
+// routing.go:94 — small, understood work creates no durable task artifacts.
+test("route inline never blocks", () => {
+  assert.equal(trackGate(routed("inline"), write, emptyPolicy(), absent).allow, true);
+  assert.equal(trackGate(routed("inline"), { toolName: "bash", input: { command: "echo x > f" } }, emptyPolicy(), absent).allow, true);
+});
+
+test("mutating bash blocks while a test command does not", () => {
+  const state = routed("tracked");
+  assert.equal(trackGate(state, { toolName: "bash", input: { command: "echo x > f" } }, emptyPolicy(), absent).allow, false);
+  assert.equal(trackGate(state, { toolName: "bash", input: { command: "npm test" } }, emptyPolicy(), absent).allow, true);
+});
+
+// A doc the model can rewrite is a doc the model can forge, and then evidence
+// is prose again. This holds even when the doc exists and the route is inline.
+test("a direct write to .nodd/** is always blocked, pointing at nodd_task", () => {
+  for (const state of [routed("tracked"), routed("inline"), emptyCommitted()]) {
+    for (const path of [".nodd/x/feature.md", ".nodd/demo/state.json", "/repo/.nodd/demo/feature.md"]) {
+      const decision = trackGate(state, { toolName: "write", input: { path } }, emptyPolicy(), present);
+      assert.equal(decision.allow, false, `${path} must be blocked`);
+      assert.ok(decision.allow === false && decision.remedy.action.includes("nodd_task"));
+    }
+  }
+  const edit = trackGate(routed("tracked"), { toolName: "edit", input: { path: ".nodd/demo/feature.md" } }, emptyPolicy(), present);
+  assert.equal(edit.allow, false);
+});
+
+// design.md says `.nodd/**` writes are "always blocked", but REQ: gate-framework
+// says flag semantics obey the kill switch "without exception", and
+// REQ: gate-kill-switch-semantics 3 says obey immediately without working
+// around it. The explicit "without exception" wins: a gate the user turned off
+// is off, including its doc-integrity half. Turning `track` off is the
+// documented way to hand-edit a feature doc.
+test("the flag off disables the whole gate, doc protection included", () => {
+  const policy = { ...emptyPolicy(), config: { track: { enabled: false } } };
+  assert.equal(trackGate(routed("tracked"), write, policy, absent).allow, true);
+  assert.equal(
+    trackGate(routed("tracked"), { toolName: "write", input: { path: ".nodd/demo/feature.md" } }, policy, present).allow,
+    true,
+    "a disabled gate does not keep enforcing half of itself",
+  );
+});
+
+test("an undeclared session does not block here — that is gate-classify's job", () => {
+  assert.equal(trackGate(emptyCommitted(), write, emptyPolicy(), absent).allow, true);
+});

package/src/gates/track.ts

@@ -0,0 +1,58 @@
+// gate-track — track before the first write.
+//
+// `routing.go:49`: for substantial authorized implementation, create the
+// feature document *before the first source write*, without asking permission.
+// NODD makes that literal: on a `tracked` or `forge` route, while
+// `.nodd/<slug>/feature.md` is absent, the first mutation does not happen.
+//
+// Route `inline` never blocks. Small, understood work stays small
+// (`routing.go:94`) — a gate that demanded a document for a one-line fix would
+// be the bureaucracy ODD explicitly refuses.
+//
+// The second half of this gate protects the document itself: `write`/`edit`
+// aimed at `.nodd/**` is refused and pointed at `nodd_task`. The feature doc is
+// extension-owned because a doc the model can rewrite is a doc the model can
+// forge, and then "Evidence: tests pass" is back, in a file, looking official.
+
+import type { Committed } from "../state.ts";
+import { allow, refuse, resolveFlag, type GateDecision, type Policy } from "./policy.ts";
+import { isFileWrite, isMutation, targetPath, type GateRequest } from "./request.ts";
+
+export function featureDocRelPath(slug: string): string {
+  return `.nodd/${slug}/feature.md`;
+}
+
+function targetsNoddDir(request: GateRequest): boolean {
+  const path = targetPath(request);
+  return isFileWrite(request) && path !== null && /(^|\/)\.nodd\//.test(path);
+}
+
+export function trackGate(
+  committed: Committed,
+  request: GateRequest,
+  policy: Policy,
+  docExists: (slug: string) => boolean,
+): GateDecision {
+  if (!resolveFlag("track", policy).enabled) return allow();
+
+  if (targetsNoddDir(request)) {
+    return refuse(
+      "track",
+      `${request.toolName} targets \`${targetPath(request)}\`, and NODD's own artifacts are written by NODD, not by the model`,
+      "use `nodd_task` to add or check off tasks, and `nodd_declare` to set the objective and route",
+    );
+  }
+
+  const declaration = committed.declaration;
+  if (!declaration) return allow();
+  if (declaration.route === "inline") return allow();
+  if (!isMutation(request)) return allow();
+  if (docExists(declaration.slug)) return allow();
+
+  const path = featureDocRelPath(declaration.slug);
+  return refuse(
+    "track",
+    `route \`${declaration.route}\` was declared but \`${path}\` does not exist, and ${request.toolName} would be the first write`,
+    `call \`nodd_declare\` with slug \`${declaration.slug}\` to create ${path}`,
+  );
+}

package/src/io.test.ts

@@ -0,0 +1,81 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { nodeFs, writeVerified, type Fs } from "./io.ts";
+
+function tmp(): string {
+  return mkdtempSync(join(tmpdir(), "nodd-io-"));
+}
+
+test("a verified write lands on disk and reports success", () => {
+  const dir = tmp();
+  const target = join(dir, "feature.md");
+  const result = writeVerified(target, "hello\n", { fs: nodeFs });
+  assert.equal(result.ok, true);
+  assert.equal(readFileSync(target, "utf8"), "hello\n");
+  assert.deepEqual(readdirSync(dir), ["feature.md"], "the temp file must not survive");
+});
+
+test("a failing writer leaves the previous file intact and reports the limitation", () => {
+  const dir = tmp();
+  const target = join(dir, "feature.md");
+  writeFileSync(target, "original\n", "utf8");
+  const failing: Fs = { ...nodeFs, writeFileSync: () => { throw new Error("ENOSPC: disk full"); } };
+
+  const result = writeVerified(target, "replacement\n", { fs: failing });
+  assert.equal(result.ok, false);
+  assert.match(result.limitation, /ENOSPC/);
+  assert.equal(readFileSync(target, "utf8"), "original\n", "the previous file must survive");
+});
+
+test("a read-back mismatch is reported as a failure, not as success", () => {
+  const dir = tmp();
+  const target = join(dir, "feature.md");
+  writeFileSync(target, "original\n", "utf8");
+  // A writer that silently truncates: the write "succeeds" and the content is wrong.
+  const lying: Fs = { ...nodeFs, readFileSync: () => "trunca" };
+
+  const result = writeVerified(target, "replacement\n", { fs: lying });
+  assert.equal(result.ok, false);
+  assert.match(result.limitation, /read-back/);
+});
+
+test("an interrupted write leaves no partial file behind", () => {
+  const dir = tmp();
+  const target = join(dir, "feature.md");
+  const interrupted: Fs = { ...nodeFs, renameSync: () => { throw new Error("interrupted"); } };
+
+  const result = writeVerified(target, "half", { fs: interrupted });
+  assert.equal(result.ok, false);
+  assert.deepEqual(readdirSync(dir), [], "no partial and no temp file may remain");
+});
+
+test("divergent on-disk content is preserved alongside, losing neither version", () => {
+  const dir = tmp();
+  const target = join(dir, "feature.md");
+  writeFileSync(target, "edited by hand\n", "utf8");
+
+  const result = writeVerified(target, "nodd version\n", {
+    fs: nodeFs,
+    expectedPrevious: "what nodd last wrote\n",
+    now: () => "20260919T100000",
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(result.conflictPath, join(dir, "feature.conflict-20260919T100000.md"));
+  assert.equal(readFileSync(target, "utf8"), "nodd version\n");
+  assert.equal(readFileSync(result.conflictPath!, "utf8"), "edited by hand\n");
+});
+
+test("matching previous content produces no conflict file", () => {
+  const dir = tmp();
+  const target = join(dir, "feature.md");
+  writeFileSync(target, "same\n", "utf8");
+
+  const result = writeVerified(target, "next\n", { fs: nodeFs, expectedPrevious: "same\n" });
+  assert.equal(result.ok, true);
+  assert.equal(result.conflictPath, undefined);
+  assert.deepEqual(readdirSync(dir), ["feature.md"]);
+});

package/src/io.ts

@@ -0,0 +1,94 @@
+// Every NODD artifact write goes through here.
+//
+// `routing.go:98` — "read back both writes; they are not atomic". NODD carries
+// the disk half of that clause literally: write to a temp file, rename, read
+// back, and compare against what we meant to write. A mismatch preserves the
+// previous file and returns a limitation instead of claiming success, because a
+// write NODD did not verify is exactly the kind of unearned "done" this product
+// exists to refuse.
+//
+// If the on-disk content diverged from what NODD last wrote, both versions
+// survive: the new content lands, the divergent one is kept beside it as
+// `<name>.conflict-<ts>.md`. Neither is lost, and only the real conflict is
+// worth asking the user about.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
+
+/** The file operations this module needs, injectable so tests can force failure. */
+export type Fs = {
+  existsSync(path: string): boolean;
+  mkdirSync(path: string, options: { recursive: true }): void;
+  readFileSync(path: string, encoding: "utf8"): string;
+  writeFileSync(path: string, data: string, encoding: "utf8"): void;
+  renameSync(from: string, to: string): void;
+  unlinkSync(path: string): void;
+};
+
+export const nodeFs: Fs = { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync };
+
+export type WriteResult =
+  | { ok: true; conflictPath?: string }
+  | { ok: false; limitation: string };
+
+export type WriteOptions = {
+  fs?: Fs;
+  /**
+   * What NODD believes it last wrote. When the file on disk says something
+   * else, the divergent version is preserved rather than overwritten.
+   */
+  expectedPrevious?: string;
+  now?: () => string;
+};
+
+function timestamp(): string {
+  return new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "");
+}
+
+function conflictPathFor(target: string, stamp: string): string {
+  const ext = extname(target);
+  const base = target.slice(0, target.length - ext.length);
+  return `${base}.conflict-${stamp}${ext}`;
+}
+
+export function writeVerified(target: string, content: string, options: WriteOptions = {}): WriteResult {
+  const fs = options.fs ?? nodeFs;
+  const stamp = (options.now ?? timestamp)();
+  const temp = join(dirname(target), `.${stamp}.nodd-tmp`);
+
+  let conflictPath: string | undefined;
+  try {
+    fs.mkdirSync(dirname(target), { recursive: true });
+
+    if (options.expectedPrevious !== undefined && fs.existsSync(target)) {
+      const onDisk = fs.readFileSync(target, "utf8");
+      if (onDisk !== options.expectedPrevious) {
+        conflictPath = conflictPathFor(target, stamp);
+        fs.writeFileSync(conflictPath, onDisk, "utf8");
+      }
+    }
+
+    fs.writeFileSync(temp, content, "utf8");
+    fs.renameSync(temp, target);
+  } catch (err) {
+    try {
+      if (fs.existsSync(temp)) fs.unlinkSync(temp);
+    } catch {
+      // Best effort: the temp file is already reported through the limitation.
+    }
+    return { ok: false, limitation: err instanceof Error ? err.message : String(err) };
+  }
+
+  // The success path is reachable only through a matching read-back.
+  let readBack: string;
+  try {
+    readBack = fs.readFileSync(target, "utf8");
+  } catch (err) {
+    return { ok: false, limitation: `read-back failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (readBack !== content) {
+    return { ok: false, limitation: `read-back mismatch on ${target}: the file on disk is not what NODD wrote` };
+  }
+
+  return conflictPath ? { ok: true, conflictPath } : { ok: true };
+}

package/src/ledger.test.ts

@@ -0,0 +1,122 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { appendRecord, readLedger, classifyRecords, type LedgerRecord } from "./ledger.ts";
+import type { Fs } from "./io.ts";
+
+function memoryFs(seed: Record<string, string> = {}): Fs & { files: Map<string, string> } {
+  const files = new Map(Object.entries(seed));
+  return {
+    files,
+    readFileSync: (p: string) => {
+      const found = files.get(p);
+      if (found === undefined) { const e: any = new Error("ENOENT"); e.code = "ENOENT"; throw e; }
+      return found;
+    },
+    writeFileSync: (p: string, data: string) => { files.set(p, data); },
+    renameSync: (from: string, to: string) => {
+      files.set(to, files.get(from)!);
+      files.delete(from);
+    },
+    existsSync: (p: string) => files.has(p),
+    mkdirSync: () => {},
+    unlinkSync: (p: string) => { files.delete(p); },
+  };
+}
+
+const PATH = ".nodd/demo/state.json";
+
+function rec(id: string, command = "npm test"): LedgerRecord {
+  return { toolCallId: id, tool: "bash", command, outcome: { kind: "success" }, at: "2026-09-19T10:00:00.000Z" };
+}
+
+test("two appends re-read in order", () => {
+  const fs = memoryFs();
+  appendRecord(PATH, rec("c1", "npm test"), fs);
+  appendRecord(PATH, rec("c2", "npm run build"), fs);
+
+  const { records, defects } = readLedger(PATH, fs);
+  assert.deepEqual(defects, []);
+  assert.deepEqual(records.map((r) => r.toolCallId), ["c1", "c2"]);
+  assert.equal(records[1].command, "npm run build");
+});
+
+test("a missing ledger is empty and is not a defect", () => {
+  const { records, defects } = readLedger(PATH, memoryFs());
+  assert.deepEqual(records, []);
+  assert.deepEqual(defects, []);
+});
+
+test("a truncated file yields a defect and an empty ledger without throwing", () => {
+  const { records, defects } = readLedger(PATH, memoryFs({ [PATH]: '{"records":[{"toolCallId":"c1"' }));
+  assert.deepEqual(records, [], "corrupt content is never evidence");
+  assert.equal(defects.length, 1);
+  assert.match(defects[0], /state\.json/);
+});
+
+test("a record without a toolCallId is rejected by the append API", () => {
+  const fs = memoryFs();
+  assert.throws(() => appendRecord(PATH, { tool: "bash", command: "x", outcome: { kind: "success" }, at: "t" } as any, fs),
+    /toolCallId/);
+  assert.equal(fs.files.has(PATH), false, "nothing was written");
+});
+
+test("an interrupted write leaves no partial file visible at the real path", () => {
+  const fs = memoryFs();
+  appendRecord(PATH, rec("c1"), fs);
+  const good = fs.files.get(PATH)!;
+
+  const failing: Fs = { ...fs, renameSync: () => { throw new Error("boom"); } };
+  assert.throws(() => appendRecord(PATH, rec("c2"), failing));
+  assert.equal(fs.files.get(PATH), good, "the previous good content is intact");
+  assert.deepEqual(readLedger(PATH, fs).records.map((r) => r.toolCallId), ["c1"]);
+});
+
+// --- integrity: a record is evidence only if THIS kernel observed it ---
+
+test("records whose toolCallId this session observed are trusted", () => {
+  const { trusted, degraded } = classifyRecords([rec("c1"), rec("c2")], new Set(["c1", "c2"]));
+  assert.deepEqual(trusted.map((r) => r.toolCallId), ["c1", "c2"]);
+  assert.deepEqual(degraded, []);
+});
+
+// The T010 probe child rewrote a whole .nodd file because it had `write` and no
+// append tool. A forged record is well-formed JSON; what it cannot be is a
+// toolCallId this process saw.
+test("a record the kernel never observed is degraded, not trusted", () => {
+  const forged = { ...rec("forged-1", "npm test"), outcome: { kind: "success" } as const };
+  const { trusted, degraded } = classifyRecords([rec("c1"), forged], new Set(["c1"]));
+
+  assert.deepEqual(trusted.map((r) => r.toolCallId), ["c1"]);
+  assert.equal(degraded.length, 1);
+  assert.equal(degraded[0].record.toolCallId, "forged-1");
+  assert.equal(degraded[0].reason, "unobserved");
+  assert.match(degraded[0].detail, /not observed/i);
+});
+
+test("a record whose command or outcome disagrees with what was observed is degraded", () => {
+  const observed = new Map([["c1", { command: "npm test", outcome: "exit 1" }]]);
+
+  const rewritten = { ...rec("c1", "npm test"), outcome: { kind: "success" } as const };
+  const byOutcome = classifyRecords([rewritten], new Set(["c1"]), observed);
+  assert.deepEqual(byOutcome.trusted, [], "a flipped outcome is not evidence");
+  assert.equal(byOutcome.degraded[0].reason, "mismatch");
+  assert.match(byOutcome.degraded[0].detail, /exit 1/);
+
+  const byCommand = classifyRecords([rec("c1", "echo pretend")], new Set(["c1"]), observed);
+  assert.deepEqual(byCommand.trusted, []);
+  assert.equal(byCommand.degraded[0].reason, "mismatch");
+});
+
+// Honest limit: a fresh process saw nothing, so everything is unverified. That
+// is reported as unverified, never as proven-forged and never as success.
+test("with an empty observed set every record is degraded as unverified", () => {
+  const { trusted, degraded } = classifyRecords([rec("c1"), rec("c2")], new Set());
+  assert.deepEqual(trusted, []);
+  assert.equal(degraded.length, 2);
+  for (const d of degraded) assert.equal(d.reason, "unobserved");
+});
+
+test("degradation never throws away the record, it reports it", () => {
+  const { degraded } = classifyRecords([rec("x")], new Set());
+  assert.equal(degraded[0].record.toolCallId, "x", "the record survives for the report");
+});

package/src/ledger.ts

@@ -0,0 +1,133 @@
+// `.nodd/<slug>/state.json` — what the extension observed.
+//
+// Append-only, written atomically through `writeVerified`. Every record carries
+// the `toolCallId` of the call it came from: the append API refuses a record
+// without one, so model-authored text cannot enter the ledger by construction.
+//
+// A corrupt file is a reported defect treated as empty. It is never evidence.
+//
+// ## Observed, not merely written
+//
+// The feature doc belongs to the user — hand-editing it with `track` off is
+// legitimate. The ledger does not: it is the record of what the kernel saw.
+// Well-formed JSON on disk proves nothing about whether anything ran, and there
+// are two ordinary ways wrong records get there: a human editing the file, and
+// a delegated child rewriting it whole (the T010 probe child did exactly that,
+// having `write` and no append tool).
+//
+// So a record counts as evidence only when its `toolCallId` is one this kernel
+// committed this session, with the command and outcome it actually observed.
+// Everything else is degraded to unverified and reported — never assumed valid,
+// never silently dropped. Otherwise "observed" decays into "was written in a
+// file", and that is the single thing NODD exists to prevent.
+//
+// Deliberately not cryptographic. An in-memory id set answers the only question
+// worth asking here — did *this* process see it happen — and a signing scheme
+// would add key management without changing that answer.
+
+import { writeVerified, nodeFs, type Fs } from "./io.ts";
+import { describeOutcome, type Outcome } from "./outcome.ts";
+
+export type LedgerRecord = {
+  toolCallId: string;
+  tool: string;
+  command: string;
+  outcome: Outcome;
+  at: string;
+};
+
+export type ReadResult = { records: LedgerRecord[]; defects: string[] };
+
+export function readLedger(path: string, fs: Fs = nodeFs): ReadResult {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(path, "utf8");
+  } catch {
+    return { records: [], defects: [] };
+  }
+
+  try {
+    const parsed = JSON.parse(raw) as { records?: unknown };
+    const records = Array.isArray(parsed.records) ? parsed.records : [];
+    const usable = records.filter(
+      (r): r is LedgerRecord => typeof (r as LedgerRecord)?.toolCallId === "string",
+    );
+    const defects = usable.length === records.length
+      ? []
+      : [`${path}: ${records.length - usable.length} record(s) without a toolCallId were ignored`];
+    return { records: usable, defects };
+  } catch {
+    return { records: [], defects: [`${path}: not valid JSON, treated as empty (it is not evidence)`] };
+  }
+}
+
+export function appendRecord(path: string, record: LedgerRecord, fs: Fs = nodeFs): void {
+  if (typeof record?.toolCallId !== "string" || record.toolCallId === "") {
+    throw new Error("nodd ledger: a record without a toolCallId is not an observation and cannot be appended");
+  }
+
+  const { records } = readLedger(path, fs);
+  const next = JSON.stringify({ records: [...records, record] }, null, 2);
+
+  const result = writeVerified(path, next, { fs });
+  if (!result.ok) throw new Error(`nodd ledger: ${result.limitation}`);
+}
+
+export type Degraded = {
+  record: LedgerRecord;
+  reason: "unobserved" | "mismatch";
+  detail: string;
+};
+
+/** What the kernel observed for a given call, for cross-checking the file. */
+export type ObservedCall = { command: string; outcome: string };
+
+/**
+ * Split the ledger into what this kernel can vouch for and what it cannot.
+ *
+ * Honest limit: a fresh process has an empty observed set, so a pre-existing
+ * ledger comes back entirely `unobserved`. That is "unverified", not "proven
+ * forged" — the two read differently in a report, and neither counts as
+ * success.
+ */
+export function classifyRecords(
+  records: LedgerRecord[],
+  observedIds: Set<string>,
+  observedCalls: Map<string, ObservedCall> = new Map(),
+): { trusted: LedgerRecord[]; degraded: Degraded[] } {
+  const trusted: LedgerRecord[] = [];
+  const degraded: Degraded[] = [];
+
+  for (const record of records) {
+    if (!observedIds.has(record.toolCallId)) {
+      degraded.push({
+        record,
+        reason: "unobserved",
+        detail: `${record.toolCallId} was not observed by this session, so it is unverified and does not count as evidence`,
+      });
+      continue;
+    }
+
+    const observed = observedCalls.get(record.toolCallId);
+    if (observed) {
+      const outcome = describeOutcome(record.outcome);
+      if (observed.command !== record.command || observed.outcome !== outcome) {
+        degraded.push({
+          record,
+          reason: "mismatch",
+          detail: `${record.toolCallId} on disk says \`${record.command}\` → ${outcome}, but this session observed \`${observed.command}\` → ${observed.outcome}`,
+        });
+        continue;
+      }
+    }
+
+    trusted.push(record);
+  }
+
+  return { trusted, degraded };
+}
+
+/** One line per degraded record, for a refusal message or a status report. */
+export function describeDegraded(degraded: Degraded[]): string[] {
+  return degraded.map((d) => `- ${d.detail}`);
+}

package/src/manifest.test.ts

@@ -0,0 +1,53 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  CANONICAL_STEPS,
+  CONFIGURABLE_SLOTS,
+  MECHANISM_STEPS,
+  THRESHOLDS,
+} from "./manifest.ts";
+
+// Values carried from gentle's capabilitymanifest/manifest.go:203-216 plus the
+// 20-tool-call backstop, which is prose in routing.go:82. A silent edit must
+// fail here.
+test("thresholds carry gentle's exact values", () => {
+  assert.equal(THRESHOLDS.minUnderstandingFiles, 1);
+  assert.equal(THRESHOLDS.maxUnderstandingFiles, 3);
+  assert.equal(THRESHOLDS.maxMechanicalWriteFiles, 1);
+  assert.equal(THRESHOLDS.mappingMinUnderstandingFiles, 4);
+  assert.equal(THRESHOLDS.writerMinNonTrivialFiles, 2);
+  assert.equal(THRESHOLDS.longSessionToolCalls, 20);
+});
+
+test("the canonical step list is the seven ODD steps in order", () => {
+  assert.deepEqual(CANONICAL_STEPS, [
+    "authorize",
+    "explore",
+    "resolve-uncertainty",
+    "classify",
+    "track",
+    "implement",
+    "close",
+  ]);
+  assert.ok(Object.isFrozen(CANONICAL_STEPS));
+});
+
+test("the four mechanism steps are absent from the configurable slot set", () => {
+  assert.deepEqual([...MECHANISM_STEPS], ["authorize", "classify", "track", "close"]);
+  for (const step of MECHANISM_STEPS) {
+    assert.ok(!CONFIGURABLE_SLOTS.includes(step as never), `${step} must not be configurable`);
+  }
+  assert.deepEqual(CONFIGURABLE_SLOTS, [
+    "default",
+    "orchestrator",
+    "explore",
+    "resolve-uncertainty",
+    "implement",
+  ]);
+});
+
+test("every mechanism step is still displayed", () => {
+  for (const step of MECHANISM_STEPS) {
+    assert.ok(CANONICAL_STEPS.includes(step), `${step} must stay visible in the protocol`);
+  }
+});