catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/services/run-report.ts

@@ -0,0 +1,176 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { JudgeDecision, RuleChange } from "../domain/judge.ts";
+import { type Finding, issueLine, type RunEvent } from "../domain/run-events.ts";
+import { findingKey, type RunState } from "../domain/run-state.ts";
+import { writeTextAtomic } from "../infra/store.ts";
+import { readChecks } from "./milestone-check.ts";
+import { readRecords, type Run } from "./run-store.ts";
+
+const read = (file: string): string => {
+  try {
+    return readFileSync(file, "utf8").trim();
+  } catch {
+    return "";
+  }
+};
+
+/** What a judge decided, in one line: the verb's own payload. */
+function said(d: JudgeDecision): string {
+  switch (d.verb) {
+    case "route":
+      return d.routes.map((r) => `${r.finding} -> ${r.to}`).join(", ");
+    case "answer":
+      return d.answer;
+    case "ask_owner":
+    case "park":
+      return d.question;
+    case "rules":
+      return `${d.changes.length} change(s) proposed`;
+    default:
+      return d.why;
+  }
+}
+
+const quote = (text: string): string => `'${text.replace(/'/g, "'\\''")}'`;
+
+/**
+ * The `## Rules review` section (plan 34): what the finished run's judge proposed, each change followed by the
+ * command that applies it. The run applies none; null when the run had no review (cancelled, failed).
+ */
+function rulesSection(failed: boolean, proposals: RuleChange[] | undefined): string[] | null {
+  if (failed) return ["## Rules review", "", "No rules review: the judge gave no readable answer.", ""];
+  if (!proposals) return null;
+  if (proposals.length === 0)
+    return ["## Rules review", "", "The judge proposed no change to the standing rules.", ""];
+  return [
+    "## Rules review",
+    "",
+    "Standing rules to review: apply any of these with the command under it.",
+    ...proposals.flatMap((c, i) => [
+      `${i + 1}. ${c.op === "add" ? "ADD" : "REMOVE"} ${c.text}${c.why ? ` — ${c.why}` : ""}`,
+      `   \`catherd knowledge ${c.op === "add" ? "add" : "rm"} ${quote(c.text)}\``,
+    ]),
+    "",
+  ];
+}
+
+/** The "fixed" part of a milestone's `Rounds:` line shows at most this many findings. */
+export const FIXED_LINES = 15;
+
+/**
+ * The findings of each review round of milestone `m`: a `commit.made` opens a round, and every ok reviewer end
+ * (`reviewer`, `ui-reviewer`, the partial pass `reviewer-<M>-2`) adds to it. A round with no reviewer end is left out.
+ */
+export function reviewRounds(events: RunEvent[], m: string): Finding[][] {
+  const reviewers = new Set<string>();
+  const rounds: Finding[][] = [];
+  let open: Finding[] | null = null;
+  for (const e of events) {
+    if (e.type === "dispatch.started") {
+      if ((e.role === "reviewer" || e.role === "ui-reviewer") && e.unit === m) reviewers.add(e.dispatchId);
+    } else if (e.type === "commit.made" && e.milestone === m) open = null;
+    else if (
+      e.type === "dispatch.ended" &&
+      reviewers.has(e.dispatchId) &&
+      e.status === "ok" &&
+      e.replyStatus !== "blocked" &&
+      e.replyStatus !== "refused"
+    ) {
+      if (!open) rounds.push((open = []));
+      open.push(...e.findings);
+    }
+  }
+  return rounds;
+}
+
+/** `Rounds: 3 review round(s) · fixed: <the BLOCKER and BUG lines an earlier round named and the last did not repeat>`. */
+export function roundsLine(events: RunEvent[], m: string): string {
+  const rounds = reviewRounds(events, m);
+  const last = new Set((rounds.at(-1) ?? []).map((f) => findingKey(issueLine(f))));
+  const seen = new Set<string>();
+  const fixed: string[] = [];
+  for (const f of rounds.slice(0, -1).flat()) {
+    const key = findingKey(issueLine(f));
+    if (f.label === "NIT" || last.has(key) || seen.has(key)) continue;
+    seen.add(key);
+    fixed.push(issueLine(f));
+  }
+  const head = `Rounds: ${rounds.length} review round(s)`;
+  return fixed.length ? `${head} · fixed: ${fixed.slice(0, FIXED_LINES).join(" · ")}` : head;
+}
+
+/** Per command, the latest check record of this run and milestone that is no baseline; "Gate: not recorded" when none. */
+export function gateLines(run: Run, m: string): string[] {
+  const latest = new Map<string, ReturnType<typeof readChecks>[number]>();
+  try {
+    for (const r of readChecks(run.meta.repo))
+      if (r.run === run.id && r.milestone === m && !r.baseline) latest.set(r.command, r);
+  } catch {
+    // a check store that cannot be read records nothing
+  }
+  return latest.size
+    ? [...latest.values()].map(
+        (r) =>
+          `Gate: \`${r.command}\` exit ${r.exit} on ${r.head.slice(0, 12)} · ${Math.round(r.durationMs / 1000)} s · secret scan: ${r.secrets ?? "not run"}`,
+      )
+    : ["Gate: not recorded"];
+}
+
+const oneLine = (s: string): string => s.replace(/\s*\n\s*/g, " ").trim();
+
+/**
+ * `<run>/report.md`, the body of the merge request: the run's title, each landed milestone's digest, the known
+ * issues verbatim by milestone, and the audit: every judge decision, and what each milestone's check passed on
+ * only through the base or a rerun (`audits`). Returns its path.
+ */
+export function writeRunReport(
+  run: Run,
+  s: RunState,
+  events: RunEvent[],
+  audits: Record<string, string[]> = {},
+  proposals?: RuleChange[],
+): string {
+  const landed = events.filter((e) => e.type === "milestone.landed");
+  const decided = events.filter((e) => e.type === "judge.decided");
+  const lines = [`# ${s.title || run.meta.title}`, ""];
+  for (const e of landed) {
+    const title = s.milestones.find((m) => m.id === e.milestone)?.title;
+    const digest = read(e.digestPath.startsWith("/") ? e.digestPath : join(run.dir, e.digestPath));
+    lines.push(
+      `## ${e.milestone}${title && title !== e.milestone ? `: ${title}` : ""}`,
+      "",
+      digest || `Landed at ${e.commit.slice(0, 12)}.`,
+      "",
+      roundsLine(events, e.milestone),
+      ...gateLines(run, e.milestone),
+      "",
+    );
+  }
+  if (landed.length === 0) lines.push("No milestone landed.", "");
+  lines.push("## Known issues", "");
+  const issues = landed.flatMap((e) => e.knownIssues.map((k) => `- ${e.milestone}: ${k}`));
+  lines.push(...(issues.length ? issues : ["None."]), "");
+  // plan 34: the latest lint of each milestone's preflight
+  const lint = [
+    ...new Set(events.flatMap((e) => (e.type === "preflight.done" ? [e.milestone] : []))),
+  ].flatMap((m) => {
+    const latest = events.findLast((e) => e.type === "preflight.done" && e.milestone === m);
+    return latest?.type === "preflight.done" ? latest.lint.map((l) => `- ${m}: ${l}`) : [];
+  });
+  if (lint.length) lines.push("## Plan lint", "", ...lint, "");
+  lines.push("## Audit", "");
+  const audit = [
+    ...decided.map((e) => `- ${e.unit} (${e.kind}): ${e.decision.verb}: ${oneLine(said(e.decision))}`),
+    ...Object.entries(audits).flatMap(([m, lines]) => lines.map((l) => `- ${m} (check): ${oneLine(l)}`)),
+    // a worker's conflict with its plan task, in record order
+    ...readRecords(run).records.flatMap((r) =>
+      (r.design ?? []).map((d) => `- ${r.name} DESIGN: ${oneLine(d)}`),
+    ),
+  ];
+  lines.push(...(audit.length ? audit : ["No judge decision."]), "");
+  lines.push(...(rulesSection(s.rulesReview?.failed === true, proposals) ?? []));
+  const file = join(run.dir, "report.md");
+  writeTextAtomic(file, lines.join("\n"));
+  return file;
+}

package/src/services/run-service.ts

@@ -1,38 +1,118 @@
 import { existsSync, readFileSync } from "node:fs";
-import { relative } from "node:path";
+import { relative, sep } from "node:path";
 import { CatherdError } from "../domain/errors.ts";
 import { assertId, parseRung } from "../domain/ids.ts";
+import { assertLaneValues } from "../domain/lane.ts";
 import type { RunRecord } from "../domain/record.ts";
-import type { Role } from "../domain/roles.ts";
+import { ROLES, type Role } from "../domain/roles.ts";
+import { rulesFor, tagNames } from "../domain/rules.ts";
 import { awaitsCollect, dispatchPaths, endCollect, tryCollect } from "../infra/dispatch-dir.ts";
-import { gitToplevel } from "../infra/git.ts";
-import { writeTextAtomic } from "../infra/store.ts";
+import { withFileLock } from "../infra/filelock.ts";
+import { git, gitToplevel } from "../infra/git.ts";
+import { writeJsonAtomic, writeTextAtomic } from "../infra/store.ts";
 import {
   dispatchState,
   type DispatchState,
   latestDispatch,
   listDispatches,
+  liveDispatches,
   recordHints,
 } from "./dispatches.ts";
 import type { Deps } from "./ports.ts";
 import { assertNativeHost } from "./backends.ts";
+import { writeRunIndex } from "./catalog-service.ts";
 import {
   type AgentRun,
   appendAgentRun,
   appendKnowledge,
   createRun,
   findRun,
-  knowledgeFile,
+  knowledgeFor,
   readRecords,
+  removeKnowledgeLine,
   runFile,
+  type Run,
+  runPaths,
+  supersededBy,
+  supersededFile,
 } from "./run-store.ts";
-import { protocolView } from "./protocol.ts";
+import { protocolNext, protocolView } from "./protocol.ts";
+import { writePin } from "./run-pin.ts";
 import { claimRun, currentSession } from "./sessions.ts";
-import { refreshState } from "./state.ts";
+import { readNotes, refreshState } from "./state.ts";
+
+/** The run `id` was superseded by, or undefined: an open run, or one that cannot be found. */
+function nextInChain(id: string): string | undefined {
+  try {
+    return supersededBy(findRun(id))?.by;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * `runs supersede <run> --by <run>`: closes `run` with a pointer to the run that took it over (a planning
+ * run handed to the execution run in a worktree). Status hides it; dispatch refuses it. A run with live
+ * roles is refused: cancel them, or let them finish, first.
+ */
+export async function supersedeRun(
+  deps: Deps,
+  i: { run: string; by: string },
+): Promise<{ run: string; by: string; at: string; hints?: string[] }> {
+  const run = findRun(i.run);
+  const by = findRun(i.by);
+  if (run.id === by.id)
+    throw new CatherdError("E_INPUT_INVALID", `run ${run.id} cannot supersede itself`, {
+      fix: "pass the run that took over as --by",
+    });
+  // walk the chain the new pointer would join: any run it reaches back to `run` closes a cycle
+  const seen = new Set<string>([by.id]);
+  for (let hop = supersededBy(by)?.by; hop !== undefined && !seen.has(hop);) {
+    if (hop === run.id)
+      throw new CatherdError("E_INPUT_INVALID", `run ${by.id} is itself superseded by ${run.id}`, {
+        fix: "supersede the older run by the newer one",
+      });
+    seen.add(hop);
+    hop = nextInChain(hop);
+  }
+  // under the run's admission lock: a dispatch admitted meanwhile is either live here, or sees the pointer
+  const at = await withFileLock(runPaths(run.dir).admission, () => {
+    assertNoLiveRoles(
+      deps,
+      run,
+      `cancel them (cancel(run, name)) or let them finish, then supersede ${run.id}`,
+    );
+    return writeSuperseded(deps, run, by.id);
+  });
+  return { run: run.id, by: by.id, at, ...(await supersededHints(run, by.id)) };
+}
+
+/** Held under `run`'s admission lock: no role of it may be live when it closes. */
+function assertNoLiveRoles(deps: Deps, run: Run, fix: string): void {
+  const live = liveDispatches(run, deps.now());
+  if (live.length)
+    throw new CatherdError(
+      "E_INPUT_INVALID",
+      `run ${run.id} still has live roles: ${live.map((d) => d.admit.name).join(", ")}`,
+      { fix },
+    );
+}
+
+/** Held under `run`'s admission lock: the pointer to the run that took it over; its time. */
+function writeSuperseded(deps: Deps, run: Run, by: string): string {
+  const when = new Date(deps.now()).toISOString();
+  writeJsonAtomic(supersededFile(run), { schema: 1, by, at: when });
+  return when;
+}
+
+async function supersededHints(run: Run, by: string): Promise<{ hints?: string[] }> {
+  const { hints } = await refreshState(run, { next: `superseded by ${by}: continue there` });
+  return hints.length ? { hints } : {};
+}
 
 export async function startRun(
   deps: Deps,
-  i: { repo: string; title: string; aLines: string[] },
+  i: { repo: string; title: string; aLines: string[]; from?: string; base?: string },
 ): Promise<{
   run: string;
   dir: string;
@@ -44,17 +124,53 @@ export async function startRun(
     throw new CatherdError("E_IO_PATH", `${i.repo} is not inside a git repository`, {
       fix: "pass the path of the repository to work in",
     });
-  const run = createRun({
-    repo: top,
-    title: i.title,
-    aLines: i.aLines,
-    version: deps.version,
-    now: new Date(deps.now()),
-    startedBy: currentSession(deps),
-  });
-  await claimRun(deps, run);
+  // a run starts only when every enabled role has an indexed rung; the index it checked is the one it pins
+  const start = await deps.routing.checkStart(deps.profiles.forRepo(top), top);
+  if (start.unusable.length > 0) {
+    const roles = start.unusable.join(", ");
+    throw new CatherdError(
+      "E_CONFIG_INVALID",
+      `the ${roles} role${start.unusable.length === 1 ? " has" : "s have"} no usable rung on the Slopalytics index`,
+      {
+        fix: `catherd profile validate, then pick indexed pairs: catherd catalog list --role ${start.unusable[0]}`,
+      },
+    );
+  }
+  // where the first milestone's commit range starts; a repo with no commit yet has none
+  const head = await git(top, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]);
+  const open = async (): Promise<Run> => {
+    const run = createRun({
+      repo: top,
+      title: i.title,
+      aLines: i.aLines,
+      version: deps.version,
+      startHead: head.kind === "ok" ? head.out.trim() || null : null,
+      ...(i.base ? { base: i.base } : {}),
+      now: new Date(deps.now()),
+      startedBy: currentSession(deps),
+    });
+    // spec 1.5 "Pinned per run": what the run starts on stays what it dispatches on
+    writePin(deps, run);
+    writeRunIndex(run.dir, start.index);
+    await claimRun(deps, run);
+    return run;
+  };
+  // the run this one takes over must be free to close before anything is created, and stay so until its pointer
+  // is written: its admission lock is held from the check to the pointer, so no dispatch gets in between and
+  // leaves the new run open beside it (PR #50). It is the only lock taken first: the new run's are uncontended.
+  const from = i.from === undefined ? null : findRun(i.from);
+  const run = from
+    ? await withFileLock(runPaths(from.dir).admission, async () => {
+        assertNoLiveRoles(deps, from, `cancel them or let them finish, then run_start with from: ${from.id}`);
+        const opened = await open();
+        writeSuperseded(deps, from, opened.id);
+        return opened;
+      })
+    : await open();
+  const superseded = from ? await supersededHints(from, run.id) : {};
   // a failed state.md refresh never fails the start: the run exists and is usable, so a retry would orphan it
   const { hints } = await refreshState(run);
+  hints.push(...(superseded.hints ?? []));
   // spec 1.1 §10: the milestone loop, so the orchestrator starts on the protocol
   return { run: run.id, dir: run.dir, protocol: protocolView(run, []), ...(hints.length ? { hints } : {}) };
 }
@@ -63,7 +179,22 @@ export function writeRunFile(i: { run: string; path: string; content: string }):
   path: string;
   bytes: number;
 } {
-  const file = runFile(findRun(i.run), i.path, "write");
+  const run = findRun(i.run);
+  const file = runFile(run, i.path, "write");
+  const rel = relative(run.dir, file).split(sep).join("/");
+  // macOS disks ignore case, so Plan-Input/ is the same folder
+  const low = rel.toLowerCase();
+  if (low === "plan-approved.md" || low === "plan-input" || low.startsWith("plan-input/"))
+    throw new CatherdError(
+      "E_INPUT_INVALID",
+      `${rel} holds the owner's approved plan; roles never write it`,
+      {
+        fix: "write plan.md or a lane file",
+      },
+    );
+  // spec 1.5 "Lane editing": a lane's header values are checked when it is written, not first at preflight
+  const lane = /^lanes\/([^/]+)\.md$/.exec(rel);
+  if (lane) assertLaneValues(i.content, `lanes/${lane[1]}.md`);
   writeTextAtomic(file, i.content);
   return { path: file, bytes: Buffer.byteLength(i.content) };
 }
@@ -99,6 +230,28 @@ function capReply(reply: string, path: string): string {
   return `${head.slice(0, CAP_CHARS)}\n[capped: the full reply is ${path}]`;
 }
 
+/** Whether `text` names `token` (a role name or lane id) as a whole word, a full stop after it allowed. */
+export function names(text: string, token: string): boolean {
+  const t = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?<![\\w.-])${t}(?![\\w-]|\\.\\w)`).test(text);
+}
+
+/**
+ * Plan 22: state.md's Next never outlives the step it names. When it names a role whose record `result` returns
+ * (by its name or its lane), it moves on to the protocol's next step. A refresh that fails comes back as hints.
+ */
+async function advanceNext(run: Run, record: RunRecord): Promise<string[]> {
+  const stale = (next: string) =>
+    names(next, record.name) || (record.lane !== null && names(next, record.lane));
+  if (!stale(readNotes(run).next)) return [];
+  const { hints } = await refreshState(run, (n) =>
+    stale(n.next)
+      ? { next: `after ${record.name} (${record.status}): ${protocolNext(run, n.parked ?? [])}` }
+      : {},
+  );
+  return hints;
+}
+
 /**
  * A role's latest dispatch: its record once finished, its capped reply and its hints. Spec §3.7: reading a
  * finished record marks it read, with the collect lease (each record is marked read once, whoever reads it);
@@ -134,6 +287,7 @@ export async function result(
     if (x.admit.dispatchId !== d.admit.dispatchId) hints.push(...recordHints(run, x, r));
   }
   if (record) for (const h of recordHints(run, d, record)) if (!hints.includes(h)) hints.push(h);
+  if (record) for (const h of await advanceNext(run, record)) if (!hints.includes(h)) hints.push(h);
   const reply = dispatchPaths(d.dir).reply;
   const text = existsSync(reply) ? readFileSync(reply, "utf8") : "";
   return {
@@ -159,6 +313,10 @@ export function recordAgentRun(
     durationMs?: number;
     status?: AgentRun["status"];
     lane?: string;
+    /** plan 23: a native verifier's first reply line, so a VERDICT: BLOCKED: environment is told from a FAIL */
+    verdict?: string;
+    /** plan 23: the STATUS word of the subagent's reply */
+    replyStatus?: NonNullable<AgentRun["replyStatus"]>;
   },
 ): AgentRun {
   const run = findRun(i.run);
@@ -180,6 +338,8 @@ export function recordAgentRun(
     secs: i.durationMs === undefined ? null : Math.round(i.durationMs / 1000),
     status: i.status ?? "ok",
     lane: i.lane ?? null,
+    ...(i.verdict ? { verdict: i.verdict.trim().split("\n")[0] } : {}),
+    ...(i.replyStatus ? { replyStatus: i.replyStatus } : {}),
   };
   appendAgentRun(run, row);
   return row;
@@ -197,7 +357,7 @@ async function repoTop(repo: string): Promise<string> {
 
 /** What past runs of the repo learned; `repo` may be any path inside it. */
 export async function readKnowledge(repo: string): Promise<string> {
-  const file = knowledgeFile(await repoTop(repo));
+  const file = await knowledgeFor(await repoTop(repo));
   const text = existsSync(file) ? readFileSync(file, "utf8") : "";
   return text.trim() ? text : "catherd: no knowledge recorded yet for this repo";
 }
@@ -205,7 +365,7 @@ export async function readKnowledge(repo: string): Promise<string> {
 /** Where the repo's knowledge.md is (it may not exist yet); `repo` may be any path inside it. */
 export async function knowledgePath(repo: string): Promise<{ repo: string; path: string }> {
   const top = await repoTop(repo);
-  return { repo: top, path: knowledgeFile(top) };
+  return { repo: top, path: await knowledgeFor(top) };
 }
 
 /** The repo's knowledge.md as its lines, none when it is missing or blank; `repo` may be any path inside it. */
@@ -218,12 +378,33 @@ export async function knowledgeLines(repo: string): Promise<{ repo: string; path
 /** The source a line added by hand carries, where a landing puts its run's title and milestone. */
 const BY_HAND = "by hand";
 
-/** Appends one line of the user's own to the repo's knowledge.md, as `land`'s `learned` does; returns it. */
-export async function addKnowledge(repo: string, text: string, now: Date = new Date()): Promise<string> {
+/** The repo's standing rules for `role`: its knowledge.md as `rulesFor` gives it, "" when missing or blank. */
+export async function standingRules(repo: string, role: Role): Promise<string> {
+  const { lines } = await knowledgeLines(repo);
+  return rulesFor(lines.join("\n"), role);
+}
+
+/** Appends one line to the repo's knowledge.md (a hand-written one by default), as `land`'s `learned` does; returns it. */
+export async function addKnowledge(
+  repo: string,
+  text: string,
+  now: Date = new Date(),
+  source = BY_HAND,
+): Promise<string> {
   const top = await repoTop(repo);
   if (!text.trim())
     throw new CatherdError("E_INPUT_INVALID", "the knowledge line is empty", {
       fix: 'pass one line of text, e.g. catherd knowledge add "the targeted test is bun test <file>"',
     });
-  return appendKnowledge(top, now, BY_HAND, text);
+  const bad = (tagNames(text) ?? []).find((n) => !(ROLES as readonly string[]).includes(n));
+  if (bad !== undefined)
+    throw new CatherdError("E_INPUT_INVALID", `"${bad}" is not a role: tag a rule with ${ROLES.join(", ")}`, {
+      fix: 'catherd knowledge add "[worker, reviewer] <rule>"',
+    });
+  return appendKnowledge(top, now, source, text);
+}
+
+/** Removes the one line of the repo's knowledge.md that contains `match`; returns it. */
+export async function removeKnowledge(repo: string, match: string): Promise<string> {
+  return removeKnowledgeLine(await repoTop(repo), match);
 }