@gonrocca/nodd 0.1.0

package/extensions/nodd-prompt.test.ts

@@ -0,0 +1,87 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { BLOCK_A_BUDGET, BLOCK_B_BUDGET } from "../src/prompt.ts";
+import register from "./nodd-kernel.ts";
+
+type Handler = (event: unknown) => unknown;
+
+function host() {
+  const handlers = new Map<string, Handler>();
+  const pi = {
+    on: (event: string, handler: Handler) => handlers.set(event, handler),
+    registerTool: () => {},
+    appendEntry: () => {},
+  };
+  const kernel = register(pi as never, mkdtempSync(join(tmpdir(), "nodd-prompt-")));
+  return { handlers, kernel };
+}
+
+function fire(incoming: string | null | undefined): string {
+  const { handlers } = host();
+  const handler = handlers.get("before_agent_start");
+  assert.ok(handler, "the kernel must register a before_agent_start handler");
+  const result = handler!({ systemPrompt: incoming }) as { systemPrompt?: string } | undefined;
+  return result?.systemPrompt ?? "";
+}
+
+// ---------------------------------------------------------------------------
+// Chained, never replaced
+// ---------------------------------------------------------------------------
+test("the handler is registered on before_agent_start", () => {
+  assert.ok(host().handlers.has("before_agent_start"));
+});
+
+test("the result starts with the incoming prompt, byte for byte", () => {
+  const incoming = "ANOTHER EXTENSION'S CONTRIBUTION\nwith two lines.";
+  const result = fire(incoming);
+  assert.ok(result.startsWith(incoming), `other extensions' contributions must survive:\n${result.slice(0, 120)}`);
+  assert.ok(result.length > incoming.length, "NODD appends its own blocks");
+});
+
+test("both blocks are appended", () => {
+  const result = fire("base");
+  assert.match(result, /NODD/, "block A is present");
+  assert.match(result, /ODD · guía|gates disabled/, "block B or the disabled line is present");
+});
+
+test("an empty incoming prompt still yields NODD's blocks", () => {
+  const result = fire("");
+  assert.match(result, /NODD/);
+  assert.ok(result.length > 0);
+});
+
+test("a null or missing incoming prompt drops no content", () => {
+  for (const incoming of [null, undefined]) {
+    const result = fire(incoming);
+    assert.match(result, /NODD/, `incoming=${incoming} must still produce NODD's blocks`);
+    assert.ok(!result.includes("null") && !result.includes("undefined"), "no stringified nullish leaks in");
+  }
+});
+
+test("the appended content respects the budgets", () => {
+  const incoming = "base prompt";
+  const appended = fire(incoming).slice(incoming.length);
+  assert.ok(
+    appended.length <= BLOCK_A_BUDGET + BLOCK_B_BUDGET + 8,
+    `appended ${appended.length} exceeds the two budgets plus separators`,
+  );
+});
+
+test("firing twice does not accumulate: the prompt is rebuilt, not appended to itself", () => {
+  const { handlers } = host();
+  const handler = handlers.get("before_agent_start")!;
+  const first = (handler({ systemPrompt: "base" }) as { systemPrompt: string }).systemPrompt;
+  const second = (handler({ systemPrompt: "base" }) as { systemPrompt: string }).systemPrompt;
+  assert.equal(first, second, "a second turn with the same state renders the same prompt");
+});
+
+test("the handler never throws, whatever the event shape", () => {
+  const { handlers } = host();
+  const handler = handlers.get("before_agent_start")!;
+  for (const event of [undefined, null, {}, { systemPrompt: 42 }, "nonsense"]) {
+    assert.doesNotThrow(() => handler(event as never), `event ${JSON.stringify(event)} must not throw`);
+  }
+});

package/extensions/nodd-tools.test.ts

@@ -0,0 +1,211 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import register, { createKernel, featureDocPath } from "./nodd-kernel.ts";
+import { parseFeatureDoc } from "../src/feature-doc.ts";
+
+function fakePi() {
+  const tools = new Map<string, any>();
+  return {
+    tools,
+    on() {},
+    appendEntry() {},
+    registerTool(name: string, options: any) { tools.set(name, options); },
+  };
+}
+
+function tmp(): string {
+  return mkdtempSync(join(tmpdir(), "nodd-tools-"));
+}
+
+test("both tools are registered with pi", () => {
+  const pi = fakePi();
+  register(pi as never);
+  assert.ok(pi.tools.has("nodd_declare"), "nodd_declare must be registered");
+  assert.ok(pi.tools.has("nodd_task"), "nodd_task must be registered");
+});
+
+test("route: tracked creates the feature doc and reports it in one line", () => {
+  const cwd = tmp();
+  const kernel = createKernel(undefined, cwd);
+  const result = kernel.declare({
+    intent: "change", route: "tracked", slug: "demo",
+    summary: "Make the thing work", title: "Demo feature",
+  });
+
+  const path = featureDocPath(cwd, "demo");
+  assert.ok(existsSync(path), `${path} must exist`);
+  const parsed = parseFeatureDoc(readFileSync(path, "utf8"));
+  assert.deepEqual(parsed.defects, []);
+  assert.equal(parsed.doc.objective, "Make the thing work");
+  assert.deepEqual(parsed.doc.tasks, [], "a fresh doc has an empty Tasks section");
+  assert.equal(result.text, ".nodd/demo/feature.md created with 0 tasks");
+});
+
+// A runner is pinned once. `tdd: strict` was not: re-declaring while omitting
+// `tdd` rewrote the document to `- tdd: off`, with no refusal and no trace, and
+// a GREEN with no RED then checked the task off. Dropping a discipline is as
+// much a change to how the work is judged as swapping the runner is.
+test("strict TDD cannot be dropped by re-declaring without it", () => {
+  const cwd = tmp();
+  const kernel = createKernel(undefined, cwd);
+  kernel.declare({
+    intent: "change", route: "tracked", slug: "demo", summary: "obj", title: "Demo",
+    runner: "npm test", tdd: "strict",
+  } as never);
+
+  const second = kernel.declare({
+    intent: "change", route: "tracked", slug: "demo", summary: "obj", title: "Demo",
+    runner: "npm test",
+  } as never);
+
+  assert.equal(second.ok, false, "omitting tdd must not silently downgrade strict to off");
+  const parsed = parseFeatureDoc(readFileSync(featureDocPath(cwd, "demo"), "utf8"));
+  assert.equal(parsed.doc.verification.tdd, "strict", "the pinned discipline must survive the refused re-declaration");
+});
+
+test("route: inline creates no durable artifact", () => {
+  const cwd = tmp();
+  const kernel = createKernel(undefined, cwd);
+  kernel.declare({ intent: "change", route: "inline", slug: "small", summary: "one-liner", title: "Small" });
+  assert.equal(existsSync(featureDocPath(cwd, "small")), false, "small understood work stays small");
+});
+
+test("invalid enum values are rejected before any file write", () => {
+  const cwd = tmp();
+  const pi = fakePi();
+  const kernel = register(pi as never, cwd);
+  const declare = pi.tools.get("nodd_declare")!;
+
+  assert.deepEqual(declare.parameters.properties.route.enum, ["inline", "tracked", "forge"]);
+  assert.deepEqual(declare.parameters.properties.intent.enum, ["read-only", "change"]);
+
+  const result = kernel.declare({ intent: "change", route: "sideways" as never, slug: "x", summary: "s", title: "T" });
+  assert.equal(result.ok, false);
+  assert.match(result.text, /route/);
+  assert.equal(existsSync(featureDocPath(cwd, "x")), false, "a rejected declaration writes nothing");
+});
+
+test("nodd_task add appends a task and the count is reported from the doc", () => {
+  const cwd = tmp();
+  const kernel = createKernel(undefined, cwd);
+  kernel.declare({ intent: "change", route: "tracked", slug: "demo", summary: "obj", title: "Demo" });
+
+  const added = kernel.task({ action: "add", id: "T1", title: "First task", slug: "demo" });
+  assert.equal(added.ok, true);
+  const parsed = parseFeatureDoc(readFileSync(featureDocPath(cwd, "demo"), "utf8"));
+  assert.deepEqual(parsed.doc.tasks, [{ id: "T1", title: "First task", checked: false }]);
+
+  const second = kernel.declare({ intent: "change", route: "tracked", slug: "demo", summary: "obj", title: "Demo" });
+  assert.match(second.text, /with 1 tasks?$/);
+});
+
+test("the model never writes the doc: the extension does", () => {
+  const cwd = tmp();
+  const kernel = createKernel(undefined, cwd);
+  kernel.declare({ intent: "change", route: "tracked", slug: "demo", summary: "obj", title: "Demo" });
+  const before = readFileSync(featureDocPath(cwd, "demo"), "utf8");
+  // There is no API that accepts doc text from the caller.
+  assert.ok(!("writeDoc" in kernel), "the kernel exposes no raw doc writer");
+  assert.equal(readFileSync(featureDocPath(cwd, "demo"), "utf8"), before);
+});
+
+/** Observe a successful bash run, so the evidence gate has something to see. */
+function observeGreen(kernel: ReturnType<typeof createKernel>, command: string, id = "v1"): void {
+  kernel.onToolResult({ toolCallId: id, toolName: "bash", input: { command }, isError: false, content: "ok" });
+}
+
+test("a checkoff with no observed run is refused by the evidence gate", () => {
+  const cwd = tmp();
+  const kernel = createKernel(undefined, cwd);
+  kernel.declare({ intent: "change", route: "tracked", slug: "demo", summary: "obj", title: "Demo" });
+  kernel.task({ action: "add", id: "T1", title: "First", slug: "demo" });
+
+  const checked = kernel.task({ action: "check", id: "T1", slug: "demo" });
+  assert.equal(checked.ok, false, "nothing was observed, so nothing may be claimed");
+  assert.match(checked.text, /nodd\/evidence/);
+  assert.equal(
+    parseFeatureDoc(readFileSync(featureDocPath(cwd, "demo"), "utf8")).doc.tasks[0].checked,
+    false,
+    "a refused checkoff changes nothing on disk",
+  );
+});
+
+test("a checkoff records the observed command, never an invented one", () => {
+  const cwd = tmp();
+  const kernel = createKernel(undefined, cwd);
+  // The runner is pinned here because that is the ordinary tracked declaration:
+  // an unpinned one records `success (runner not pinned)` instead, which is a
+  // different claim and has its own tests.
+  kernel.declare({ intent: "change", route: "tracked", slug: "demo", summary: "obj", title: "Demo", runner: "node --test" });
+  kernel.task({ action: "add", id: "T1", title: "First", slug: "demo" });
+  observeGreen(kernel, "node --test");
+
+  assert.equal(kernel.task({ action: "check", id: "T1", slug: "demo" }).ok, true);
+  const task = parseFeatureDoc(readFileSync(featureDocPath(cwd, "demo"), "utf8")).doc.tasks[0];
+  assert.equal(task.checked && task.evidence.command, "node --test");
+  assert.equal(task.checked && task.evidence.outcome, "success");
+});
+
+test("a checkoff with no observed commit records pending-commit", () => {
+  const cwd = tmp();
+  const kernel = createKernel(undefined, cwd);
+  kernel.declare({ intent: "change", route: "tracked", slug: "demo", summary: "obj", title: "Demo" });
+  kernel.task({ action: "add", id: "T1", title: "First", slug: "demo" });
+  observeGreen(kernel, "node --test");
+  kernel.task({ action: "check", id: "T1", slug: "demo" });
+
+  const task = parseFeatureDoc(readFileSync(featureDocPath(cwd, "demo"), "utf8")).doc.tasks[0];
+  assert.equal(task.checked && task.candidate, "pending-commit");
+});
+
+test("nodd_task reopen without a reason is refused; with one it records under Progress", () => {
+  const cwd = tmp();
+  const kernel = createKernel(undefined, cwd);
+  kernel.declare({ intent: "change", route: "tracked", slug: "demo", summary: "obj", title: "Demo" });
+  kernel.task({ action: "add", id: "T1", title: "First", slug: "demo" });
+  observeGreen(kernel, "node --test");
+  kernel.task({ action: "check", id: "T1", slug: "demo" });
+
+  const bare = kernel.task({ action: "reopen", id: "T1", slug: "demo" });
+  assert.equal(bare.ok, false);
+  assert.match(bare.text, /reason/i);
+  assert.equal(
+    parseFeatureDoc(readFileSync(featureDocPath(cwd, "demo"), "utf8")).doc.tasks[0].checked,
+    true,
+    "a refused reopen changes nothing on disk",
+  );
+
+  const withReason = kernel.task({ action: "reopen", id: "T1", slug: "demo", reason: "the check ran against stale code" });
+  assert.equal(withReason.ok, true);
+  const doc = parseFeatureDoc(readFileSync(featureDocPath(cwd, "demo"), "utf8")).doc;
+  assert.equal(doc.tasks[0].checked, false);
+  assert.match(doc.progress, /T1 reopened: the check ran against stale code/);
+});
+
+test("the reopen action is in the tool schema so the model can name it", () => {
+  const pi = fakePi();
+  register(pi as never, tmp());
+  assert.deepEqual(pi.tools.get("nodd_task")!.parameters.properties.action.enum, ["add", "check", "reopen"]);
+});
+
+test("a checkoff after an observed commit records that SHA as the candidate", () => {
+  const cwd = tmp();
+  const kernel = createKernel(undefined, cwd);
+  kernel.declare({ intent: "change", route: "tracked", slug: "demo", summary: "obj", title: "Demo" });
+  kernel.task({ action: "add", id: "T1", title: "First", slug: "demo" });
+
+  kernel.onToolResult({
+    toolCallId: "g1",
+    toolName: "bash",
+    input: { command: "git commit -m 'feat: first'" },
+    isError: false,
+    content: "[main 7c0ffee] feat: first\n 1 file changed",
+  });
+  kernel.task({ action: "check", id: "T1", slug: "demo" });
+
+  const task = parseFeatureDoc(readFileSync(featureDocPath(cwd, "demo"), "utf8")).doc.tasks[0];
+  assert.equal(task.checked && task.candidate, "7c0ffee");
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@gonrocca/nodd",
+  "version": "0.1.0",
+  "description": "Non-negotiable Organic Driven Development \u2014 the ODD protocol as runtime mechanism for pi: blocking gates, observed evidence, and promotion to /forge.",
+  "type": "module",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "nodd",
+    "odd",
+    "ai-coding-agent"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/nodd-kernel.ts",
+      "./extensions/nodd-gates.ts",
+      "./extensions/nodd-allow.ts",
+      "./extensions/nodd-models.ts",
+      "./extensions/nodd-agents.ts",
+      "./extensions/nodd-promote.ts"
+    ]
+  },
+  "files": [
+    "src",
+    "extensions",
+    "test",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test --experimental-strip-types"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.84.0"
+  },
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "license": "MIT"
+}

package/src/bash-classifier.test.ts

@@ -0,0 +1,114 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { classifyBash, COVERED_PATTERNS, NOT_COVERED } from "./bash-classifier.ts";
+
+const CASES: Array<[string, "mutating" | "non-mutating"]> = [
+  // --- mutating ---
+  ["echo hi > f.txt", "mutating"],
+  ["cat a >> b", "mutating"],
+  ["ls | tee out.txt", "mutating"],
+  ["sed -i 's/a/b/' f.ts", "mutating"],
+  ["perl -i -pe 's/x/y/' f.ts", "mutating"],
+  ["mv a b", "mutating"],
+  ["cp a b", "mutating"],
+  ["rm -rf build", "mutating"],
+  ["rmdir empty", "mutating"],
+  ["ln -s a b", "mutating"],
+  ["install -m 755 a /usr/local/bin/a", "mutating"],
+  ["dd if=/dev/zero of=f bs=1M count=1", "mutating"],
+  ["truncate -s 0 log", "mutating"],
+  ["touch newfile", "mutating"],
+  ["mkdir -p src/new", "mutating"],
+  ["chmod +x run.sh", "mutating"],
+  ["chown gon:gon f", "mutating"],
+  ["patch -p1 < fix.diff", "mutating"],
+  ["git apply fix.patch", "mutating"],
+  ["git checkout -- src/a.ts", "mutating"],
+  ["git restore src/a.ts", "mutating"],
+  ["git reset --hard HEAD", "mutating"],
+  ["git commit -m 'x'", "mutating"],
+  ["git stash", "mutating"],
+  ["git clean -fd", "mutating"],
+  ["npm install lodash", "mutating"],
+  ["pnpm add -D vitest", "mutating"],
+  ["yarn add react", "mutating"],
+  ["pip install requests", "mutating"],
+  ["cargo add serde", "mutating"],
+  ["node -e \"require('fs').writeFileSync('f','x')\"", "mutating"],
+  ["python -c \"open('f','w').write('x')\"", "mutating"],
+  ["ls && echo x > f", "mutating"],
+
+  // --- non-mutating: the ones a wrong gate would break ---
+  ["ls -la", "non-mutating"],
+  ["grep -rn 'a>b' src", "non-mutating"],
+  ["cmd 2>&1", "non-mutating"],
+  ["npm test 2>&1 | tail -5", "non-mutating"],
+  ["git status", "non-mutating"],
+  ["git log --oneline -5", "non-mutating"],
+  ["git diff", "non-mutating"],
+  ["git show HEAD", "non-mutating"],
+  ["npm test", "non-mutating"],
+  ["node --test", "non-mutating"],
+  ["cat package.json", "non-mutating"],
+  ["find . -name '*.ts'", "non-mutating"],
+  ["echo hello", "non-mutating"],
+  ["pwd", "non-mutating"],
+  ["wc -l src/*.ts", "non-mutating"],
+  ["rg 'pattern' --files-with-matches", "non-mutating"],
+];
+
+test(`the classifier labels ${CASES.length} commands correctly`, () => {
+  for (const [command, expected] of CASES) {
+    assert.equal(classifyBash(command), expected, `"${command}" should be ${expected}`);
+  }
+});
+
+test("the covered pattern list is non-empty and every pattern matches something", () => {
+  assert.ok(COVERED_PATTERNS.length > 0);
+  for (const entry of COVERED_PATTERNS) {
+    assert.ok(entry.label.length > 0, "every covered row carries a label");
+    assert.ok(entry.example.length > 0, "every covered row carries an example");
+    assert.equal(classifyBash(entry.example), "mutating", `the example "${entry.example}" must classify as mutating`);
+  }
+});
+
+test("the not-covered list is non-empty and names scripts and indirect writers", () => {
+  assert.ok(NOT_COVERED.length > 0);
+  const all = NOT_COVERED.join(" ").toLowerCase();
+  for (const word of ["script", "make", "compiler", "eval", "background", "outside pi"]) {
+    assert.ok(all.includes(word), `the not-covered list must name "${word}"`);
+  }
+});
+
+const README = readFileSync(join(dirname(dirname(fileURLToPath(import.meta.url))), "README.md"), "utf8");
+
+function bashSection(): string {
+  const start = README.indexOf("## The bash gate");
+  assert.ok(start >= 0, "README must carry a `## The bash gate` section");
+  const rest = README.slice(start + 1);
+  const end = rest.indexOf("\n## ");
+  return end < 0 ? rest : rest.slice(0, end);
+}
+
+test("every covered row in the README matches the classifier's own pattern list", () => {
+  const section = bashSection();
+  for (const entry of COVERED_PATTERNS) {
+    assert.ok(section.includes(entry.label), `README's covered table is missing "${entry.label}"`);
+  }
+  for (const item of NOT_COVERED) {
+    assert.ok(section.includes(item), `README's not-covered list is missing "${item}"`);
+  }
+});
+
+// ODD's original sin was claiming compliance while shipping delivery. A
+// denylist is a partial mechanism, and the documentation says so in the same
+// place it lists what is covered.
+test("the bash-gate section claims no guarantee it cannot keep", () => {
+  const section = bashSection().toLowerCase();
+  for (const word of ["guarantees", "garantiza", "exhaustive", "all writes"]) {
+    assert.ok(!section.includes(word), `the bash-gate section must not contain "${word}"`);
+  }
+});

package/src/bash-classifier.ts

@@ -0,0 +1,69 @@
+// Does this bash command mutate the filesystem?
+//
+// `tool_call` hands us `input.command` as a string (`types.d.ts:653-656`), not
+// a declaration of filesystem intent. `write` and `edit` are typed and gated
+// exactly; bash can only be gated by pattern. This is a denylist, and a
+// denylist is by construction incomplete.
+//
+// That incompleteness is shipped as documentation, not buried here:
+// `NOT_COVERED` below is rendered into README.md and asserted against by test,
+// so the product cannot quietly imply a coverage it does not have. An honest
+// partial gate beats a dishonest total one.
+
+export type BashClass = "mutating" | "non-mutating";
+
+export type CoveredPattern = {
+  label: string;
+  example: string;
+  test(command: string): boolean;
+};
+
+/** A command word at the start of the string or after a shell separator. */
+function commandWord(words: string[]): RegExp {
+  return new RegExp(String.raw`(^|[;&|]|&&|\|\|)\s*(sudo\s+)?(${words.join("|")})\b`);
+}
+
+/**
+ * Output redirection, excluding the fd-only forms. `2>&1` and `>&2` redirect a
+ * descriptor, they do not create a file; treating them as writes would block
+ * `npm test 2>&1`, which is the single most common harmless command there is.
+ */
+function redirectsToFile(command: string): boolean {
+  const withoutFdDuplication = command.replace(/\d*>&\d+/g, "").replace(/&>/g, ">");
+  // A `>` inside quotes is data, not redirection (`grep -rn 'a>b' src`).
+  const unquoted = withoutFdDuplication.replace(/'[^']*'/g, "''").replace(/"[^"]*"/g, '""');
+  return />>?\s*\S/.test(unquoted);
+}
+
+export const COVERED_PATTERNS: CoveredPattern[] = [
+  { label: "output redirection (`>`, `>>`), excluding fd-only forms like `2>&1`", example: "echo hi > f.txt", test: redirectsToFile },
+  { label: "`tee`", example: "ls | tee out.txt", test: (c) => commandWord(["tee"]).test(c) || /\|\s*(sudo\s+)?tee\b/.test(c) },
+  { label: "in-place editors (`sed -i`, `perl -i`)", example: "sed -i 's/a/b/' f.ts", test: (c) => /\b(sed|perl)\b[^;&|]*\s-i\b/.test(c) },
+  { label: "movers and removers (`mv`, `cp`, `rm`, `rmdir`, `ln`, `install`, `dd`, `truncate`, `touch`, `mkdir`)", example: "rm -rf build", test: (c) => commandWord(["mv", "cp", "rm", "rmdir", "ln", "install", "dd", "truncate", "touch", "mkdir"]).test(c) },
+  { label: "permission changes (`chmod`, `chown`)", example: "chmod +x run.sh", test: (c) => commandWord(["chmod", "chown"]).test(c) },
+  { label: "`patch`", example: "patch -p1 < fix.diff", test: (c) => commandWord(["patch"]).test(c) },
+  { label: "mutating `git` subcommands (`apply`, `checkout`, `restore`, `reset`, `commit`, `stash`, `clean`, `mv`, `rm`)", example: "git commit -m 'x'", test: (c) => /\bgit\s+(apply|checkout|restore|reset|commit|stash|clean|mv|rm)\b/.test(c) },
+  { label: "package installers (`npm`/`pnpm`/`yarn`/`pip`/`cargo` install or add)", example: "npm install lodash", test: (c) => /\b(npm|pnpm|yarn|pip|pip3|cargo)\s+(install|add|i)\b/.test(c) },
+  { label: "inline interpreters (`node -e`, `python -c`)", example: "node -e \"require('fs').writeFileSync('f','x')\"", test: (c) => /\b(node|deno|bun)\s+(-e|--eval)\b/.test(c) || /\bpython3?\s+-c\b/.test(c) },
+];
+
+/**
+ * The mutation vectors this classifier does **not** catch. Shipped in README.md
+ * beside the covered table, because a partial mechanism that presents itself as
+ * total is how ODD ended up promising compliance while shipping delivery.
+ */
+export const NOT_COVERED: string[] = [
+  "a script or build target that writes: `./build.sh`, `make`, `npm run build`",
+  "compilers, formatters and codegen writing as a side effect",
+  "redirection hidden behind a variable or `eval`",
+  "a pre-existing background process",
+  "writes performed by other extensions' or MCP tools",
+  "writes performed outside pi entirely",
+  "a delegated child launched with its own `extensions:` list, which pi-subagents starts with `--no-extensions`",
+];
+
+export function classifyBash(command: string): BashClass {
+  const text = (command ?? "").trim();
+  if (!text) return "non-mutating";
+  return COVERED_PATTERNS.some((pattern) => pattern.test(text)) ? "mutating" : "non-mutating";
+}