@gonrocca/nodd 0.1.0

package/src/odd-prose.ts

@@ -0,0 +1,198 @@
+// ODD's genuinely unmechanizable clauses — kept as guidance, labelled as guidance.
+//
+// One entry per `(P)` row of `REQ: odd-parity-matrix`, tagged with the canonical
+// step it belongs to and carrying the reason it could not become a gate. That
+// reason is load-bearing: the matrix forbids "we did not get to it", because a
+// clause with no stated obstacle is a mechanism someone skipped, and a test here
+// rejects that wording.
+//
+// **Why tag by step.** `src/prompt.ts` forwards only the current step's entries.
+// Injecting all eighteen at every turn is how gentle's guidance wall reached
+// 105,993 bytes: every clause was individually defensible. Scoping by step keeps
+// the block inside its budget without anyone having to delete anything.
+//
+// This module is data, not behaviour. It reads no file, imports no gate, and is
+// frozen so no caller can append to it at runtime.
+
+import type { CanonicalStep } from "./manifest.ts";
+
+export type ProseEntry = {
+  /** Row number in `REQ: odd-parity-matrix`. */
+  row: number;
+  /** The `routing.go` line, as the matrix cites it. */
+  line: string;
+  step: CanonicalStep;
+  /** The clause as forwarded to the model. */
+  clause: string;
+  /** Why it is not mechanizable. */
+  reason: string;
+};
+
+export const ODD_PROSE: readonly ProseEntry[] = Object.freeze([
+  {
+    row: 4,
+    line: ":45",
+    step: "authorize",
+    clause:
+      "If change intent is ambiguous, ask one clarifying question and stay read-only until it is answered.",
+    reason:
+      "Whether a request is ambiguous is a judgement about natural language. NODD mechanizes the consequence — undeclared intent blocks the first write — but the asking itself cannot be derived from tool events.",
+  },
+  {
+    row: 5,
+    line: ":46",
+    step: "explore",
+    clause:
+      "Explore the existing code and requirements first, proportionate to the request.",
+    reason:
+      "Proportionality is a judgement. The delegation counters mechanize the excess, never the sufficiency: NODD can see that too many files were read, never that enough were.",
+  },
+  {
+    row: 6,
+    line: ":47",
+    step: "resolve-uncertainty",
+    clause:
+      "Research is optional and scoped to one named uncertainty: ask at most one focused question and make at most one assumption challenge.",
+    reason:
+      "Whether a premise is high-consequence and unproven is not observable from tool events; only the model reading the problem can tell.",
+  },
+  {
+    row: 7,
+    line: ":48",
+    step: "classify",
+    clause:
+      "Substantial work means two or more meaningful steps, or progress worth recovering after an interruption. Small work stays small.",
+    reason:
+      "This is ODD's own admitted hole: the judgement is not mechanizable. NODD mechanizes only the declaration, so a skipped classification is observable instead of silent.",
+  },
+  {
+    row: 11,
+    line: ":50",
+    step: "implement",
+    clause:
+      "Close every task with a work-unit commit using a Conventional Commit message, branching first when you are on the default branch.",
+    reason:
+      "NODD observes the commit and records its SHA, but the wording of a Conventional Commit message is prose, and branch/PR composition belongs to the delivery tools.",
+  },
+  {
+    row: 19,
+    line: ":63",
+    step: "explore",
+    clause:
+      "Reading that prepares a write, and broad research, are delegated too — not only reading that stands on its own.",
+    reason:
+      "Intent-to-write is not visible in a read event. NODD cannot tell a read that prepares an edit from a read that answers a question, so the trigger stays advice.",
+  },
+  {
+    row: 28,
+    line: ":81",
+    step: "explore",
+    clause:
+      "Preparation trigger: when reading is preparing a change rather than answering a question, delegate before the reading accumulates.",
+    reason:
+      "Same obstacle as row 19, and the reason NODD ships no `prepare` gate: a mechanism here would have to guess intent, and a gate that guesses is worse than prose that admits it.",
+  },
+  {
+    row: 29,
+    line: ":82",
+    step: "implement",
+    clause:
+      "Two or more non-mechanical edits without delegating is a backstop trigger, alongside the tool-call and read counters.",
+    reason:
+      "Tool calls and distinct reads are counted exactly; whether an edit is non-mechanical is a judgement, so that third leg of the backstop is forwarded rather than counted.",
+  },
+  {
+    row: 32,
+    line: ":89",
+    step: "resolve-uncertainty",
+    clause:
+      "If research is declined, continue only where it is safe to do so, and disclose the uncertainty that stayed unresolved.",
+    reason:
+      "Safety under missing evidence is a judgement about consequences, not an observable property of a session.",
+  },
+  {
+    row: 33,
+    line: ":90",
+    step: "explore",
+    clause:
+      "Establish the problem, the outcome, the constraints and the evidence, adapting depth to consequence. The parent owns product decisions; workers return gaps instead of deciding.",
+    reason:
+      "The feature doc enforces the structure; how deep each section should go for a given consequence is prose.",
+  },
+  {
+    row: 34,
+    line: ":91",
+    step: "resolve-uncertainty",
+    clause:
+      "Prefer primary sources, attribute every claim to a URL or a code location, and distinguish verified facts from assumptions.",
+    reason:
+      "Citation quality is not observable from tool events: NODD can see that a file was read, never whether the claim it supports is faithful to it.",
+  },
+  {
+    row: 35,
+    line: ":92",
+    step: "resolve-uncertainty",
+    clause:
+      "Return findings, a recommendation, the tradeoffs and the open questions; forward research instructions to a fresh worker.",
+    reason:
+      "The report format is prose. The authority half is mechanized: an observed subagent result never sets intent — only an explicit declaration does.",
+  },
+  {
+    row: 36,
+    line: ":93",
+    step: "resolve-uncertainty",
+    clause:
+      "Make at most one scoped assumption challenge, naming the premise, the evidence and the consequence. Do not open a debate loop.",
+    reason:
+      "Neither the scope of a challenge nor the onset of a debate loop is observable from tool events.",
+  },
+  {
+    row: 38,
+    line: ":95",
+    step: "implement",
+    clause:
+      "About 400 authored changed lines per task is a planning heuristic only. It is not an acceptance criterion, not a hard cap, not a counter-trigger, not an automatic stop, not a forced split and not a review trigger. If the correct solution naturally exceeds it, say so briefly and continue.",
+    reason:
+      "A line count measures typing, not correctness. Mechanizing it would make the number an objective to optimize against, which is precisely what the clause forbids.",
+  },
+  {
+    row: 39,
+    line: ":95",
+    step: "implement",
+    clause:
+      "Never delete blank lines or comments for cosmetic savings, never minify, never omit tests, never add gratuitous abstractions, and never split work artificially to fit the number. Forward this same advisory to every subagent.",
+    reason:
+      "This is the anti-gaming half of the heuristic, and it only works as prose: any mechanism enforcing it would itself become the thing to game.",
+  },
+  {
+    row: 41,
+    line: ":97",
+    step: "track",
+    clause:
+      "Business scope changes still require the user's authorization, even when a finding makes the change look obviously correct.",
+    reason:
+      "Whether a change is a business scope change is a product judgement. The preservation, reason-required and checkbox halves of this clause are mechanized; this half is not.",
+  },
+  {
+    row: 44,
+    line: ":100",
+    step: "track",
+    clause:
+      "Read the feature document and its observation, then pass the locator to every worker. Small work without a doc still receives its authorized scope and its checks.",
+    reason:
+      "Handoff discipline lives in the prompt the parent writes for the worker, which NODD does not author.",
+  },
+  {
+    row: 49,
+    line: ":103",
+    step: "close",
+    clause:
+      "Ask once for the delivery strategy when the work is risky, rather than choosing chaining and slice boundaries silently.",
+    reason:
+      "The asking is the un-mechanized part: NODD records the strategy and measures the forecast, but deciding that a given change warrants asking is a judgement.",
+  },
+]);
+
+export function proseForStep(step: CanonicalStep): readonly ProseEntry[] {
+  return ODD_PROSE.filter((entry) => entry.step === step);
+}

package/src/outcome.test.ts

@@ -0,0 +1,75 @@
+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 { parseOutcome, isSuccess, type Outcome } from "./outcome.ts";
+
+test("isError false is success by construction — pi's bash throws on any non-zero code", () => {
+  assert.deepEqual(parseOutcome(false, "anything at all"), { kind: "success" });
+  assert.deepEqual(parseOutcome(false, ""), { kind: "success" });
+});
+
+const TABLE: Array<[string, Outcome]> = [
+  ["Command exited with code 1", { kind: "exit", code: 1 }],
+  ["Command exited with code 137", { kind: "exit", code: 137 }],
+  ["Command exited with code 0", { kind: "exit", code: 0 }],
+  ["Command aborted", { kind: "aborted" }],
+  ["Command timed out after 120 seconds", { kind: "timeout", seconds: 120 }],
+  ["Command timed out after 5 seconds", { kind: "timeout", seconds: 5 }],
+];
+
+test("the five outcomes parse from the last line appended by bash.js:321", () => {
+  for (const [line, expected] of TABLE) {
+    assert.deepEqual(parseOutcome(true, line), expected, `"${line}"`);
+  }
+});
+
+test("a non-matching error text is unknown, never success", () => {
+  for (const text of ["", "ENOENT: no such file", "killed", "Command exited with code abc"]) {
+    const outcome = parseOutcome(true, text);
+    assert.equal(outcome.kind, "unknown", `"${text}" must be unknown`);
+    assert.equal(isSuccess(outcome), false, "unknown must never count as success");
+  }
+});
+
+// The marker is the *last* line pi appends. Text that merely mentions it is
+// stdout, and stdout is the model's playground: a test runner printing
+// "Command exited with code 1" in its own output must not be able to change
+// how its own run is recorded.
+test("the marker is only read from the last non-empty line", () => {
+  const stdout = "running suite\nCommand exited with code 1\nall good\n";
+  assert.deepEqual(parseOutcome(false, stdout), { kind: "success" },
+    "a successful run whose stdout quotes the marker is still success");
+
+  assert.deepEqual(parseOutcome(true, `${stdout}Command exited with code 2`), { kind: "exit", code: 2 },
+    "the real last line wins over an earlier quoted one");
+
+  assert.deepEqual(parseOutcome(true, "Command aborted\n\n  \n"), { kind: "aborted" },
+    "trailing blank lines are skipped");
+});
+
+test("isSuccess is true for success alone", () => {
+  assert.equal(isSuccess({ kind: "success" }), true);
+  for (const outcome of [
+    { kind: "exit", code: 0 }, { kind: "exit", code: 1 },
+    { kind: "aborted" }, { kind: "timeout", seconds: 1 }, { kind: "unknown" },
+  ] as Outcome[]) {
+    assert.equal(isSuccess(outcome), false, `${outcome.kind} is not success`);
+  }
+});
+
+// Three distinct failure modes collapsed into one boolean is how "the tests
+// pass" gets written after a timeout. The union has no room for that field.
+test("no boolean verdict field exists on any outcome", () => {
+  const src = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "outcome.ts"), "utf8");
+  const type = src.slice(src.indexOf("export type Outcome"), src.indexOf(";", src.indexOf("export type Outcome")));
+  for (const field of ["ok", "passed", "success:", "failed"]) {
+    assert.ok(!type.includes(field), `the Outcome union must not carry "${field}"`);
+  }
+  for (const outcome of TABLE.map(([, o]) => o)) {
+    for (const field of ["ok", "passed", "success", "failed"]) {
+      assert.ok(!(field in outcome), `${outcome.kind} must not carry "${field}"`);
+    }
+  }
+});

package/src/outcome.ts

@@ -0,0 +1,63 @@
+// What actually happened when a command ran.
+//
+// Derived from the raw observation, never from a model claim. The source of
+// truth is pi's own bash tool: it throws for every non-zero exit code
+// (`bash.js:347`), so `isError === false` means exit 0 by construction — no
+// wrapper, no `; echo $?`, no tool override. When it does throw, `bash.js:321`
+// appends one marker line describing why.
+//
+// The union deliberately has no boolean. "Did it pass?" collapses `exit 1`,
+// `aborted` and `timeout` into one shape, and that collapse is precisely how a
+// timed-out suite gets written down as "tests pass". Callers must name the
+// failure mode they are willing to accept; `unknown` is never one of them.
+
+export type Outcome =
+  | { kind: "success" }
+  | { kind: "exit"; code: number }
+  | { kind: "aborted" }
+  | { kind: "timeout"; seconds: number }
+  | { kind: "unknown" };
+
+function lastNonEmptyLine(text: string): string {
+  const lines = (text ?? "").split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (line !== "") return line;
+  }
+  return "";
+}
+
+export function parseOutcome(isError: boolean, resultText: string): Outcome {
+  if (!isError) return { kind: "success" };
+
+  // Only the last line. Anything earlier is stdout, and stdout is attacker-
+  // controlled in the only sense that matters here: a runner can print the
+  // marker text itself, and must not thereby rewrite its own verdict.
+  const line = lastNonEmptyLine(resultText);
+
+  const exited = /^Command exited with code (\d+)$/.exec(line);
+  if (exited) return { kind: "exit", code: Number(exited[1]) };
+
+  if (line === "Command aborted") return { kind: "aborted" };
+
+  const timedOut = /^Command timed out after (\d+) seconds?$/.exec(line);
+  if (timedOut) return { kind: "timeout", seconds: Number(timedOut[1]) };
+
+  return { kind: "unknown" };
+}
+
+/** Only `success` satisfies evidence. Everything else, including `unknown`, does not. */
+export function isSuccess(outcome: Outcome): boolean {
+  return outcome.kind === "success";
+}
+
+/** A short human phrase for a feature doc or a refusal message. */
+export function describeOutcome(outcome: Outcome): string {
+  switch (outcome.kind) {
+    case "success": return "success";
+    case "exit": return `exit ${outcome.code}`;
+    case "aborted": return "aborted";
+    case "timeout": return `timed out after ${outcome.seconds}s`;
+    case "unknown": return "unknown";
+  }
+}

package/src/promote.test.ts

@@ -0,0 +1,129 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { emptyDoc, type FeatureDoc } from "./feature-doc.ts";
+import { promotedRequirements } from "./promote.ts";
+
+function doc(overrides: Partial<FeatureDoc> = {}): FeatureDoc {
+  return {
+    ...emptyDoc({ slug: "cache-warmup", title: "Warm the cache on boot" }),
+    objective: "Serve the first request from a warm cache.",
+    problem: "Cold starts take 4s because the cache is empty until the first miss.",
+    scope: "The boot path only. Not the eviction policy.",
+    constraints: "No new dependencies. Boot must stay under 1s.",
+    tasks: [
+      {
+        id: "T001",
+        title: "Read the boot sequence",
+        checked: true,
+        evidence: { command: "node --test src/boot.test.ts", outcome: "success" },
+        candidate: "a1b2c3d",
+      },
+      {
+        id: "T002",
+        title: "Preload the ten hottest keys",
+        checked: true,
+        evidence: { command: "node --test src/cache.test.ts", outcome: "success" },
+        candidate: "pending-commit",
+      },
+      { id: "T003", title: "Measure the cold-start delta", checked: false },
+    ],
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The content that must survive the handoff
+// ---------------------------------------------------------------------------
+test("the objective, problem, scope and constraints all reach the requirements", () => {
+  const out = promotedRequirements(doc());
+  assert.ok(out.includes("Serve the first request from a warm cache."));
+  assert.ok(out.includes("Cold starts take 4s"));
+  assert.ok(out.includes("Not the eviction policy."));
+  assert.ok(out.includes("Boot must stay under 1s."));
+  assert.ok(out.includes("cache-warmup"), "the slug identifies the run");
+  assert.ok(out.includes("Warm the cache on boot"));
+});
+
+test("completed tasks arrive with their evidence under an already-resolved heading", () => {
+  const out = promotedRequirements(doc());
+  const heading = out.split("\n").find((line) => /^##+ /.test(line) && /resolved|done|already/i.test(line));
+  assert.ok(heading, `an already-resolved section must exist:\n${out}`);
+
+  const section = out.slice(out.indexOf(heading!));
+  for (const fragment of [
+    "Read the boot sequence",
+    "Preload the ten hottest keys",
+    "node --test src/boot.test.ts",
+    "node --test src/cache.test.ts",
+    "a1b2c3d",
+  ]) {
+    assert.ok(section.includes(fragment), `the resolved section must carry ${fragment}`);
+  }
+});
+
+test("the resolved section says in words that this work must not be redone", () => {
+  const out = promotedRequirements(doc());
+  assert.match(out, /not be redone|do not redo|already done/i);
+});
+
+test("unchecked tasks are carried as remaining work, not as resolved", () => {
+  const out = promotedRequirements(doc());
+  const resolvedAt = out.search(/^##+ .*(resolved|already)/im);
+  assert.ok(out.includes("Measure the cold-start delta"));
+  assert.ok(
+    out.indexOf("Measure the cold-start delta") < resolvedAt || !out.slice(resolvedAt).includes("Measure the cold-start delta"),
+    "an unchecked task must not appear as already-resolved",
+  );
+});
+
+// ---------------------------------------------------------------------------
+// The deliberate omission
+// ---------------------------------------------------------------------------
+test("the output is a requirements document and nothing else", () => {
+  const out = promotedRequirements(doc());
+  assert.equal(typeof out, "string");
+  assert.ok(out.startsWith("#"), "it opens as a markdown document");
+  assert.ok(out.endsWith("\n"));
+});
+
+test("nothing in this module emits a design or a tasks document", () => {
+  // Deliberate: forge's resume lands on `no-plan` and restarts at `plan` only
+  // when design.md and tasks.md are absent (orchestrator.md:102-105). A module
+  // that could write either would defeat the whole point of promoting.
+  const source = readFileSync(new URL("./promote.ts", import.meta.url), "utf8")
+    .split("\n")
+    .filter((line) => !/^\s*(\/\/|\*|\/\*)/.test(line))
+    .join("\n");
+  assert.ok(!source.includes("design.md"), "no design.md may be produced");
+  assert.ok(!source.includes("tasks.md"), "no tasks.md may be produced");
+});
+
+test("the module is pure: it opens no file and writes nothing", () => {
+  const source = readFileSync(new URL("./promote.ts", import.meta.url), "utf8")
+    .split("\n")
+    .filter((line) => !/^\s*(\/\/|\*|\/\*)/.test(line))
+    .join("\n");
+  assert.ok(!source.includes("node:fs"), "string in, string out");
+  assert.ok(!/writeFile|mkdir/.test(source));
+});
+
+// ---------------------------------------------------------------------------
+// Degenerate inputs
+// ---------------------------------------------------------------------------
+test("a doc with no completed tasks says so rather than emitting an empty section", () => {
+  const out = promotedRequirements(doc({ tasks: [{ id: "T001", title: "Only task", checked: false }] }));
+  assert.match(out, /Only task/);
+  assert.match(out, /ning|none|no completed|nothing/i);
+});
+
+test("an empty doc still produces a well-formed document", () => {
+  const out = promotedRequirements(emptyDoc({ slug: "empty", title: "Empty" }));
+  assert.ok(out.startsWith("# "));
+  assert.ok(out.includes("empty"));
+  assert.doesNotThrow(() => promotedRequirements(emptyDoc({ slug: "x", title: "" })));
+});
+
+test("promotion is deterministic: the same doc yields the same bytes", () => {
+  assert.equal(promotedRequirements(doc()), promotedRequirements(doc()));
+});

package/src/promote.ts

@@ -0,0 +1,64 @@
+// Feature doc → forge requirements, as a pure string transform.
+//
+// Promotion is a handoff, not a migration: NODD's `.nodd/<slug>/feature.md` stays
+// where it is, and forge receives a `requirements.md` it can plan from.
+//
+// **What this deliberately does not emit.** No `design.md` and no `tasks.md`.
+// Forge's resume algorithm lands on `no-plan` and restarts at `plan` precisely
+// when those two are absent (`orchestrator.md:102-105`); emitting a half-built
+// plan would push the resume into `analyzing` or `building` and hand forge a
+// plan nobody wrote. A source-scan test asserts neither filename appears here.
+//
+// Completed tasks travel with their observed evidence, under a heading that says
+// in words they must not be redone — a plan phase that re-plans finished work is
+// the expensive failure this section exists to prevent.
+
+import type { FeatureDoc, Task } from "./feature-doc.ts";
+
+function section(heading: string, body: string, fallback: string): string {
+  return `## ${heading}\n\n${body.trim() === "" ? fallback : body.trim()}\n`;
+}
+
+function resolvedRow(task: Task): string {
+  if (!task.checked) return "";
+  return [
+    `- **${task.id} — ${task.title}**`,
+    `  - verified by: \`${task.evidence.command}\``,
+    `  - observed: ${task.evidence.outcome}`,
+    `  - review candidate: ${task.candidate}`,
+  ].join("\n");
+}
+
+export function promotedRequirements(doc: FeatureDoc): string {
+  const done = doc.tasks.filter((task): task is Extract<Task, { checked: true }> => task.checked);
+  const remaining = doc.tasks.filter((task) => !task.checked);
+
+  const resolved =
+    done.length === 0
+      ? "None. No task in this run reached a verified completion, so nothing here is already done."
+      : [
+          "The work below is **already done and verified**. It must not be redone, re-planned or",
+          "re-implemented. Treat it as existing context; plan only what remains.",
+          "",
+          ...done.map(resolvedRow),
+        ].join("\n");
+
+  const remainingBody =
+    remaining.length === 0
+      ? "Everything recorded in the NODD run is complete; the remaining scope is whatever the objective still implies."
+      : remaining.map((task) => `- ${task.id} — ${task.title}`).join("\n");
+
+  return [
+    `# ${doc.title || doc.slug}`,
+    "",
+    `Promoted from the NODD run \`${doc.slug}\`. NODD kept the inline route until the work`,
+    "outgrew it; this document is the handoff, not a fresh start.",
+    "",
+    section("Objective", doc.objective, "_Not recorded in the NODD run._"),
+    section("Problem", doc.problem, "_Not recorded in the NODD run._"),
+    section("Scope", doc.scope, "_Not recorded in the NODD run._"),
+    section("Constraints", doc.constraints, "_Not recorded in the NODD run._"),
+    section("Remaining work", remainingBody, "_Nothing recorded._"),
+    section("Already resolved — do not redo", resolved, "None."),
+  ].join("\n");
+}