freeharness 0.4.1

package/canonical/hooks/freeharness-converge.mjs

@@ -0,0 +1,227 @@
+// FreeHarness converge loop (Claude Code Stop hook, sdd capability). Shape taken from the
+// anthropics/claude-code ralph-loop plugin (Apache-2.0), fitted to an OpenSpec tasks.md as
+// the completion criterion instead of a free-text promise.
+// Opt-in per project: the hook does nothing unless <project>/.freeharness/converge.json
+// exists with {"change": "<id>", "max_rounds": 5, "promise": "<text>"}. On every Stop it
+// reads openspec/changes/<change>/tasks.md; while unchecked tasks remain and the round count
+// is below max_rounds it answers {"decision":"block","reason":"<next task + its Verify
+// line>"} (the Claude Code Stop contract: `block` keeps the agent working, `reason` is what
+// it reads next). When every task is checked, the limit is reached, or the loop is disabled,
+// the session ends normally. Each round is appended to .freeharness/converge.log. A tasks.md
+// that cannot be read as a task list (missing, empty, or no checkbox lines) disables the loop
+// for good: converge.json is rewritten with "disabled": true and the reason, so a broken
+// plan never traps a session. The promise text is echoed in the block reason so the agent
+// knows the exit condition. Re-entrant Stops (stop_hook_active) are bounded by the same
+// round budget, so the loop can never run away. Exit 0 on every path.
+// Disable: FREEHARNESS_HOOK_CONVERGE=off, or delete .freeharness/converge.json.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Defaults applied to a converge.json that omits them. */
+export const DEFAULTS = Object.freeze({ maxRounds: 5, promise: "every task in tasks.md is checked and its Verify line passed" });
+
+const TASK_LINE = /^\s*[-*]\s*\[([\sxX])\]\s*(.*)/;
+// The trailing `\s*` of the annotation patterns absorbs the `\r` of a CRLF file, which `.`
+// never matches; without it every annotation line of such a file reads as prose.
+const VERIFY_LINE = /^\s*Verify:\s*(.*?)\s*$/;
+const DISPOSITION_LINE = /^\s*Disposition:\s*(superseded|moved|external)\b\s*(.*?)\s*$/;
+/** The annotation lines a task may carry; any other line ends its block. */
+const ANNOTATION_LINE = /^\s*(?:Verify|Interfaces|Boundary|Depends|Disposition):\s*(.*)\s*$/;
+
+/**
+ * Resolves the project root of a Stop payload.
+ * @param {Record<string, any>} payload Hook payload.
+ * @returns {string} Absolute project dir.
+ */
+export function projectDir(payload) {
+  return process.env.CLAUDE_PROJECT_DIR || (typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd());
+}
+
+/**
+ * Reads and validates converge.json. Missing file = loop off; a malformed file is reported
+ * and treated as off (never a block on a config nobody can read).
+ * @param {string} project Project dir.
+ * @returns {{file:string, config:null|{change:string,maxRounds:number,promise:string,rounds:number,disabled:boolean,reason?:string}, error?:string}} Result.
+ */
+export function readConfig(project) {
+  const file = path.join(project, ".freeharness", "converge.json");
+  if (!fs.existsSync(file)) return { file, config: null };
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (e) {
+    return { file, config: null, error: `converge.json is not valid JSON (${e instanceof Error ? e.message : String(e)}); loop off` };
+  }
+  if (!parsed || typeof parsed !== "object" || typeof parsed.change !== "string" || !/^[A-Za-z0-9._-]+$/.test(parsed.change)) {
+    return { file, config: null, error: "converge.json needs a \"change\" id (letters, digits, . _ -); loop off" };
+  }
+  const maxRounds = Number.isInteger(parsed.max_rounds) && parsed.max_rounds > 0 ? parsed.max_rounds : DEFAULTS.maxRounds;
+  const rounds = Number.isInteger(parsed.rounds) && parsed.rounds >= 0 ? parsed.rounds : 0;
+  const promise = typeof parsed.promise === "string" && parsed.promise.trim() ? parsed.promise.trim() : DEFAULTS.promise;
+  return {
+    file,
+    config: { change: parsed.change, maxRounds, promise, rounds, disabled: parsed.disabled === true, reason: typeof parsed.reason === "string" ? parsed.reason : undefined },
+  };
+}
+
+/**
+ * Parses tasks.md into tasks with their Verify line and, when present, their Disposition.
+ * A Disposition line is read from the task's own annotation block (Verify, Boundary, Depends
+ * and the like may sit between them); any line that is neither a task nor one of the documented
+ * annotation lines ends that block, matching the engine's disposition-aware task count.
+ * @param {string} content File text.
+ * @returns {{done:boolean, text:string, verify:string|null, disposition:{kind:string,target:string}|null}[]} Tasks in order.
+ */
+export function parseTasks(content) {
+  const tasks = [];
+  let current = null;
+  for (const line of content.split("\n")) {
+    const t = line.match(TASK_LINE);
+    if (t) {
+      current = { done: t[1].toLowerCase() === "x", text: t[2].trim(), verify: null, disposition: null };
+      tasks.push(current);
+      continue;
+    }
+    if (!current) continue;
+    const v = line.match(VERIFY_LINE);
+    if (v) {
+      current.verify = v[1].trim();
+      continue;
+    }
+    const d = line.match(DISPOSITION_LINE);
+    if (d) {
+      current.disposition = { kind: d[1], target: d[2].trim() };
+      continue;
+    }
+    // Another annotation line (Boundary:, Depends:, Interfaces:): keep the task current so a
+    // later Disposition line in the same block is still attributed to it. Anything else, a
+    // blank line, a heading, prose or the continuation of a wrapped annotation, ends the block,
+    // so a Disposition line further down belongs to no task and never resolves this one.
+    if (!ANNOTATION_LINE.test(line)) current = null;
+  }
+  // Inline "Verify: ..." inside the task description (the 1.8 template shape) counts too.
+  for (const task of tasks) {
+    if (task.verify === null) {
+      const inline = task.text.match(/\bVerify:\s*(.+)$/);
+      if (inline) task.verify = inline[1].trim();
+    }
+  }
+  return tasks;
+}
+
+/**
+ * Appends one line to the round log.
+ * @param {string} project Project dir.
+ * @param {string} line Text.
+ */
+function log(project, line) {
+  const file = path.join(project, ".freeharness", "converge.log");
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, `${new Date().toISOString()} ${line}\n`, "utf8");
+}
+
+/**
+ * Rewrites converge.json with the updated round count or the disabled marker.
+ * @param {string} file Config path.
+ * @param {Record<string, unknown>} patch Fields to merge over the current file.
+ */
+function writeConfig(file, patch) {
+  let current = {};
+  try {
+    current = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    // unreadable: the patch alone is written (the reader already validated the shape)
+  }
+  fs.writeFileSync(file, `${JSON.stringify({ ...current, ...patch }, null, 2)}\n`, "utf8");
+}
+
+/**
+ * Decides the Stop response for one payload.
+ * @param {Record<string, any>} payload Parsed hook payload.
+ * @returns {Record<string, unknown> | null} JSON to print, or null to let the session end.
+ */
+export function respond(payload) {
+  const project = projectDir(payload);
+  const { file, config, error } = readConfig(project);
+  if (error) {
+    process.stderr.write(`freeharness-converge: ${error}\n`);
+    return null;
+  }
+  if (!config || config.disabled) return null;
+
+  const tasksFile = path.join(project, "openspec", "changes", config.change, "tasks.md");
+  let tasks;
+  try {
+    tasks = parseTasks(fs.readFileSync(tasksFile, "utf8"));
+  } catch (e) {
+    const reason = `tasks.md unreadable at ${tasksFile}: ${e instanceof Error ? e.message : String(e)}`;
+    writeConfig(file, { disabled: true, reason });
+    log(project, `disabled change=${config.change} reason="${reason}"`);
+    return { systemMessage: `freeharness-converge: disabled (${reason}). Fix the change id or the file and remove "disabled" from .freeharness/converge.json to re-arm.` };
+  }
+  if (tasks.length === 0) {
+    const reason = `tasks.md has no checkbox task lines (${tasksFile})`;
+    writeConfig(file, { disabled: true, reason });
+    log(project, `disabled change=${config.change} reason="${reason}"`);
+    return { systemMessage: `freeharness-converge: disabled (${reason}). Write the tasks as "- [ ] N.M ..." lines and remove "disabled" from .freeharness/converge.json to re-arm.` };
+  }
+
+  const open = tasks.filter((t) => !t.done && !t.disposition);
+  const dispositioned = tasks.filter((t) => !t.done && t.disposition);
+  if (open.length === 0) {
+    log(project, `complete change=${config.change} rounds=${config.rounds} tasks=${tasks.length}`);
+    // A dispositioned task is unchecked by construction, so the split is reported whenever one
+    // is present; the operator is never told a task is checked when it is only resolved elsewhere.
+    const settled =
+      dispositioned.length > 0
+        ? `every task of ${config.change} is checked or dispositioned (${tasks.length - dispositioned.length} checked, ${dispositioned.length} dispositioned)`
+        : `every task of ${config.change} is checked (${tasks.length})`;
+    return { systemMessage: `freeharness-converge: ${settled}; loop complete after ${config.rounds} round(s).` };
+  }
+  if (config.rounds >= config.maxRounds) {
+    const remaining = open.map((t) => t.text).join(" | ");
+    log(project, `limit change=${config.change} rounds=${config.rounds}/${config.maxRounds} remaining=${open.length} tasks="${remaining}"`);
+    if (dispositioned.length > 0) {
+      const skipped = dispositioned.map((t) => `${t.text} (${t.disposition.kind})`).join(" | ");
+      log(project, `dispositioned change=${config.change} tasks="${skipped}"`);
+    }
+    return { systemMessage: `freeharness-converge: round limit ${config.maxRounds} reached for ${config.change} with ${open.length} task(s) open: ${remaining}. Raise max_rounds or reset rounds in .freeharness/converge.json to continue.` };
+  }
+
+  const next = open[0];
+  const round = config.rounds + 1;
+  writeConfig(file, { rounds: round });
+  log(project, `round=${round}/${config.maxRounds} change=${config.change} open=${open.length} next="${next.text}"`);
+  const reason = [
+    `freeharness-converge round ${round}/${config.maxRounds} for change ${config.change}: ${open.length} task(s) still unchecked.`,
+    `Next task: ${next.text}`,
+    `Verify: ${next.verify ?? "(no Verify line; verify against the task text and the change's specs)"}`,
+    `Mark the task [x] in ${path.relative(project, tasksFile)} only after the verification passed. Stop when ${config.promise}.`,
+  ].join("\n");
+  return { decision: "block", reason };
+}
+
+/** Entry point: read stdin, respond or stay silent, exit 0. */
+function main() {
+  if ((process.env.FREEHARNESS_HOOK_CONVERGE || "").toLowerCase() === "off") return;
+  let payload = {};
+  try {
+    const raw = fs.readFileSync(0, "utf8");
+    if (raw.trim()) payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (!payload || typeof payload !== "object") return;
+  try {
+    const out = respond(payload);
+    if (out) process.stdout.write(JSON.stringify(out));
+  } catch (e) {
+    process.stderr.write(`freeharness-converge: ${e instanceof Error ? e.message : String(e)}\n`);
+  }
+}
+
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+  main();
+  process.exit(0);
+}