@workit-dev/core 0.0.1 → 1.0.0

package/src/fanout-brief.ts

@@ -0,0 +1,486 @@
+// `workit fanout brief <slice>`: the complete worker brief, rendered from the
+// plan, the standing orders in force for the fanout (`workit ledger standing`)
+// and the slice's scratch dir, so the lead passes it to the worker verbatim.
+//
+// MODE is `resume` when the branch already exists with work on it (a retry
+// continues it), else `new`, also for a branch `fanout worktree create` made
+// that still sits at its base SHA (#432); `--attempt <n>` renders one
+// attempt of a race on its own branch `<branch>-try<n>` (refused when
+// another slice has that branch), worktree `<worktree>+try<n>` and session
+// `<lead>-w-<slice>+try<n>`: slice ids cannot contain `+`, so no attempt
+// collides with another slice's path or session.
+// The worker's host (`--host`, else the lead's: WORKIT_HOST or its own
+// session variable) picks the model lines, the Co-Authored-By trailer and the
+// identity rules: Claude Code workers use the WORKIT_SESSION_ID in their env (the
+// lead's: SubagentStart issues ids only to judges); OpenCode, Pi and Codex
+// workers export nothing (the host derives the id);
+// Cursor, CI and plain terminals export `<lead>-w-<slice>`. Once
+// `workit fanout worktree create` made the slice's worktree, WORKTREE and the
+// RULES name it: every git and check command runs as `workit <verb> --cwd <worktree> …`.
+// The lead must have a WORKIT_SESSION_ID: worker ids derive from it. A
+// worker id longer than the ledger's 128 characters hashes its slice part. The fan-in line follows the plan's `fanIn`:
+// one PR per slice forbids every merge; integration mode has the worker merge
+// the integration tip before reporting, and nothing else. It only reads, apart
+// from hiding `.workit-scratch/` in the repository's info/exclude.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { gateCheckNames, loadCheckConfig } from "./check-config";
+import { neededChecks } from "./core/policy/check-evidence";
+import { claudeSpawnArgs, resolveRoleModel, type RoleSelector } from "./core/role-models";
+import { activeStanding, readLedger, type LedgerActor } from "./ledger";
+import { branchRef, fanoutFail, planLeads, type FanoutFile, type FanoutResult } from "./fanout";
+import {
+  SCRATCH_DIR,
+  excludeScratch,
+  findSlice,
+  listWorktrees,
+  samePath,
+  slicePath,
+} from "./fanout-worktree";
+
+export type BriefMode = "new" | "resume";
+
+export type BriefOutcome = {
+  fanout: string;
+  slice: string;
+  mode: BriefMode;
+  attempt: number | null;
+  branch: string;
+  base: string;
+  tier: string;
+  /** Issues the slice's PR links (the brief's ISSUE line). */
+  issues: string[];
+  /** The model `models.roles` (or `fanout.tierModels`) names for the tier on the lead's host, else null. */
+  model: string | null;
+  /** Its effort, when one is configured. */
+  effort: string | null;
+  /** The model and effort the lead spawns this slice's non-author verifier with, else null. */
+  verifier: { model: string; effort: string | null } | null;
+  /** Absolute when the slice's worktree exists, else relative to the worker's worktree root. */
+  scratch: string;
+  /** The host the brief was rendered for (`--host`, else the lead's), or null. */
+  host: string | null;
+  /** RULE 3's Co-Authored-By trailer for that host, or null when it has none. */
+  coAuthor: string | null;
+  /** The id a worker exports, or null when its host issues or derives it. */
+  session: string | null;
+  standing: Array<{ id: string; what: string }>;
+  text: string;
+};
+
+export const DEFAULT_TIMEBOX = "30 minutes";
+
+/** The TIMEBOX line's tool-call budget when the slice names none (hooks/budget-signal.ts). */
+export const DEFAULT_TOOL_CALLS = 120;
+
+/** A hard slice's default budget: three hard slices hit 120 before their gates (retro W2.18). */
+export const HARD_TOOL_CALLS = 180;
+
+/** The share of the budget by which a worker has run its full gates, leaving the rest to fix what they find. */
+const GATES_BY = 0.6;
+
+/**
+ * The slice's TIMEBOX text plus a tool-call budget unless it already names
+ * one (hard slices get more), and the call by which the full gates have run.
+ */
+const timeboxText = (timebox: string | null, tier: string): string => {
+  const text = timebox ?? DEFAULT_TIMEBOX;
+  const named = /\b(\d+)\s+tool calls\b/u.exec(text);
+  const budget = named ? Number(named[1]) : tier === "hard" ? HARD_TOOL_CALLS : DEFAULT_TOOL_CALLS;
+  const withBudget = named ? text : `${text}, ${budget} tool calls`;
+  return `${withBudget} (run your full VERIFY gates by call ${Math.round(budget * GATES_BY)})`;
+};
+
+const REPORT = [
+  "REPORT: branch, head SHA, files changed, each VERIFY command with its exit code,",
+  "  each ACCEPTANCE line met / not met, rulings you made (`workit ledger ruling`),",
+  "  anything out of scope as a follow-up, not a diff. Report heads when pushed; CI is waited on once, at the end.",
+  "  A PR body goes through `--body-file -` (stdin), never a shared scratch path.",
+];
+
+/**
+ * How a worker's identity is settled on the lead's host (host-session.ts,
+ * docs/agents/hosts.md):
+ *   - `issued`: Claude Code. SubagentStart issues ids only to verifiers and
+ *     reviewers, so an implementer keeps the lead's WORKIT_SESSION_ID from its
+ *     env and never mints an id;
+ *   - `derived`: OpenCode, Pi, Codex. The worker's shell carries the host's own
+ *     session id, which exporting WORKIT_SESSION_ID cannot replace;
+ *   - `declared`: Cursor, CI, a plain terminal. Nothing vouches for an id, so
+ *     the brief declares `<lead>-w-<slice>`.
+ */
+export type BriefIdentity = "issued" | "derived" | "declared";
+
+/** The hosts a brief renders for, as `--host` spells them. */
+export const BRIEF_HOSTS = ["claude_code", "codex", "opencode", "cursor", "pi"] as const;
+
+const familyOf = (host: string | null): string => host?.replace(/_(?:cli|desktop)$/, "") ?? "";
+
+/**
+ * A known worker host for `host` (`codex` names Codex's CLI; `claude-code`
+ * and `_cli`/`_desktop` spellings are accepted), else null: unset, `cli` (a
+ * plain terminal) or a typo.
+ */
+export const briefHost = (host: string | null): string | null => {
+  const spelled = host?.trim().toLowerCase().replaceAll("-", "_") ?? "";
+  if (spelled === "codex") return "codex_cli";
+  return (BRIEF_HOSTS as readonly string[]).includes(familyOf(spelled)) ? spelled : null;
+};
+
+/**
+ * The Co-Authored-By trailer a host's agents sign commits with, or null for
+ * a host with no convention (Pi) or no host. Claude Code names the model
+ * family when the brief's model is a Claude alias (`opus` -> Claude Opus).
+ */
+export const coAuthorTrailer = (host: string | null, model: string | null): string | null => {
+  const family = familyOf(host);
+  if (family === "claude_code") {
+    const named = /\b(opus|sonnet|haiku|fable)\b/iu.exec(model ?? "")?.[1].toLowerCase();
+    const who = named ? `Claude ${named[0].toUpperCase()}${named.slice(1)}` : "Claude";
+    return `Co-Authored-By: ${who} <noreply@anthropic.com>`;
+  }
+  if (family === "cursor") return "Co-Authored-By: Cursor Agent <cursoragent@cursor.com>";
+  return null;
+};
+
+const identityOf = (host: string | null): BriefIdentity => {
+  const family = familyOf(host);
+  if (family === "claude_code") return "issued";
+  if (family === "opencode" || family === "pi" || family === "codex") return "derived";
+  return "declared";
+};
+
+const identityLines = (identity: BriefIdentity, session: string): string[] => {
+  if (identity === "issued")
+    return [
+      "  Session: your env already has WORKIT_SESSION_ID (the lead's id; SubagentStart issues ids only to verifiers and reviewers). Use it as is: workit commands read it and `workit git commit` adds the Workit-Session trailer; never export or hand-mint one.",
+    ];
+  if (identity === "derived")
+    return [
+      "  Session: your host already sets WORKIT_SESSION_ID in your shell; export nothing and never hand-mint one.",
+    ];
+  return [`  export WORKIT_SESSION_ID=${session}`];
+};
+
+/**
+ * RULES. With the slice's worktree made (`worktree`), every git and check
+ * command names it (`workit <verb> --cwd <worktree> …`, verb first so host
+ * allow rules match, one verb per call) and it is already on the branch;
+ * Workit's hooks keep an implementer inside it (#310).
+ */
+const rules = (
+  mode: BriefMode,
+  branch: string,
+  base: string,
+  worktree: string | null,
+  trailer: string | null,
+  host: string | null,
+): string[] => {
+  const workit = (verb: string) =>
+    worktree ? `workit ${verb} --cwd ${worktree}` : `workit ${verb}`;
+  let first = `  1. First command: \`workit git branch ${branch} --base ${base}\` (your worktree may start on another name).`;
+  if (worktree)
+    first = `  1. Work only in WORKTREE, already on ${branch}${mode === "resume" ? " at its head" : ""}: edit files under it and run each git and check command against it, one verb per call (\`${workit("git")} commit …\`, \`${workit("check")} <name>\`), never \`cd … &&\` chains or a shell variable in a path (paste the absolute path above). An implementer's change outside it is denied.`;
+  else if (mode === "resume")
+    first = `  1. First command: \`git switch ${branch}\`, then continue from its head.`;
+  return [
+    "RULES:",
+    first,
+    '  2. Decide ambiguities yourself: `workit ledger ruling "<what>" --why "<why>" --cost-if-wrong "<cost>"`; stop only for an irreversible, security-sensitive or out-of-worktree action.',
+    `  3. Commit with \`${workit("git")} commit -m <msg>${trailer ? ` --trailer "${trailer}"` : ""} -- <paths in SCOPE>\`${trailer ? " (Co-Authored-By rides in the same commit, never an amend)" : ""}; push only if this brief says so.${familyOf(host) === "claude_code" ? " Only a Claude Code host-isolated worktree (`.claude/worktrees/agent-<id>`) takes plain git instead, as its SubagentStart text says: that isolation refuses a git wrapper." : ""}`,
+    "  4. Never record a verdict on your own work.",
+    "  5. Run tests, lint, typecheck and builds only through `workit check`: a named check (`workit check <name>`), or an ad-hoc light command (a formatter, one linter, one test file) as `workit check --name <n> -- <cmd>`, which takes no lease. `--heavy` is only for full suites, packaging, builds and knip: one machine-wide lease queues every agent, so never a hand-made flock; `workit lock status` shows who holds it.",
+    "  6. A failed review gets one fix round and one recheck. Still failing: stop and report the open finding, never a third round (the lead spawns a decider). A product choice is the user's: report it, do not decide it.",
+    "  7. Before your final report, wait for or stop every background command you started; never report with one still running.",
+  ];
+};
+
+/** This repository's skill gates, named only where all of them exist (retro W2.36). */
+const WORKIT_SKILL_TESTS = [
+  "test/workit-core/skill-set.test.ts",
+  "test/workit-core/methods.test.ts",
+  "test/behavior/context-budget.test.ts",
+  "test/workit-core/generated-copies.test.ts",
+];
+
+/**
+ * Does a SCOPE entry reach skills or agent definitions (`**\/skills/**`,
+ * `**\/agents/**`)? Not under a `docs` dir: `docs/agents/*.md` is prose
+ * about agents, not a definition (retro W2.41).
+ */
+const touchesSkills = (scope: readonly string[]): boolean =>
+  scope.some((entry) => {
+    const segments = entry.split(/[\\/]/u);
+    const hit = segments.findIndex((segment) => segment === "skills" || segment === "agents");
+    return hit >= 0 && !segments.slice(0, hit).includes("docs");
+  });
+
+/**
+ * The extra VERIFY line for a slice whose SCOPE touches skills or agents:
+ * targeted tests miss the skill cap, pinned phrases and context budget, which
+ * fail only in CI. A `skills` check or group in the checks config is the
+ * portable form; else this repository's test files, else a generic rule.
+ * `root` is the slice's worktree once made: the worker runs the checks its
+ * branch defines, not those of the lead's checkout, which may be behind
+ * (retro W2.41: a stale main had no `skills` check).
+ */
+function skillsVerify(root: string, scope: readonly string[], verify: readonly string[]) {
+  if (!touchesSkills(scope)) return [];
+  const config = loadCheckConfig(root);
+  const named =
+    !config.error &&
+    (config.checks.some((check) => check.name === "skills") || "skills" in config.groups);
+  let command = "run the repo's skill and context-budget checks";
+  if (named) command = "workit check skills";
+  else if (WORKIT_SKILL_TESTS.every((file) => fs.existsSync(path.join(config.root, file))))
+    command = `workit check --name unit -- bun test ${WORKIT_SKILL_TESTS.join(" ")}`;
+  if (verify.some((line) => line.includes(command))) return [];
+  return [
+    `  skills: ${command}  (SCOPE touches skills or agents; targeted tests miss these gates)`,
+  ];
+}
+
+/**
+ * The VERIFY line naming each check a verdict on this slice needs (the
+ * repo's verification gate) that its VERIFY lines do not already run by
+ * name: a check run ad hoc leaves it missing on the verdict (retro 2026-11-07
+ * R5).
+ */
+function configuredVerify(root: string, lines: readonly string[]): string[] {
+  const config = loadCheckConfig(root);
+  if (config.error) return [];
+  const named = new Set(
+    lines.flatMap((line) =>
+      [...line.matchAll(/\bworkit check (?:--cwd \S+ )?([\w.-]+)/gu)].map((match) => match[1]),
+    ),
+  );
+  const missing = neededChecks("full", gateCheckNames(config, "verification")).filter(
+    (name) => !named.has(name),
+  );
+  return missing.length
+    ? [
+        `  checks: ${missing.map((name) => `workit check ${name}`).join("; ")}  (the configured checks a verdict records: run each by name, never ad hoc)`,
+      ]
+    : [];
+}
+
+/**
+ * The SPAWN lines a Claude Code lead copies into its Agent calls: the exact
+ * args its spawn hook passes as written (retro 2026-11-07 R1: a spawn the hook
+ * rewrote is refused in auto mode, and a re-issue dropped run_in_background).
+ */
+function spawnLines(
+  cwd: string,
+  host: string | null,
+  slice: string,
+  tier: RoleSelector["tier"],
+): string[] {
+  if (familyOf(host) !== "claude_code") return [];
+  const line = (label: string, type: string, selector: RoleSelector, prompt: string) => {
+    const args = claudeSpawnArgs(cwd, selector);
+    const fields = [
+      `subagent_type: "${type}"`,
+      ...(args ? [`model: "${args.model}"`] : []),
+      ...(args?.effort ? [`effort: "${args.effort}"`] : []),
+      "run_in_background: true",
+      `description: "${slice}"`,
+    ];
+    return `${label}: Agent ${fields.join(", ")}, prompt: ${prompt}`;
+  };
+  return [
+    line(
+      "SPAWN",
+      "workit:implementer",
+      { role: "implementer", tier },
+      `this brief, or its WORKER, TIER, TIMEBOX and WORKTREE lines plus "Run \`workit fanout brief ${slice}\` and follow it exactly."`,
+    ),
+    line(
+      "  verifier SPAWN",
+      "workit:verifier",
+      { role: "verifier" },
+      "the candidate branch with this slice's ACCEPTANCE and VERIFY",
+    ),
+  ];
+}
+
+/** VERIFY's extra lines: the skill gates, then the configured checks neither names. */
+function verifyLines(root: string, scope: readonly string[], verify: readonly string[]): string[] {
+  const skills = skillsVerify(root, scope, verify);
+  return [...skills, ...configuredVerify(root, [...verify, ...skills])];
+}
+
+/** A session id fragment that the ledger accepts ([A-Za-z0-9_.:@/+-]). */
+const sessionSafe = (text: string): string => text.replace(/[^A-Za-z0-9_.:@/+-]/gu, "-");
+
+/** The ledger's session id limit. */
+const SESSION_MAX = 128;
+
+/** `<lead>-w-<slice>[+try<n>]`, with the slice part hashed when the whole would be too long. */
+function workerSession(lead: string, slice: string, attempt: number | null): string {
+  const tail = attempt === null ? "" : `+try${attempt}`;
+  const full = `${lead}-w-${slice}${tail}`;
+  if (full.length <= SESSION_MAX) return full;
+  const digest = createHash("sha256").update(slice).digest("hex").slice(0, 12);
+  return `${lead.slice(0, SESSION_MAX - 3 - digest.length - tail.length)}-w-${digest}${tail}`;
+}
+
+export function renderBrief(
+  cwd: string,
+  plan: FanoutFile,
+  input: {
+    slice: string;
+    mode: BriefMode | null;
+    attempt: number | null;
+    actor: LedgerActor;
+    /** The worker's host (`--host`, normalized by briefHost), else the lead's. */
+    host?: string | null;
+  },
+): FanoutResult<BriefOutcome> {
+  const found = findSlice(plan, input.slice);
+  if (!found.ok) return found;
+  const slice = found.data;
+  const ledger = readLedger(cwd);
+  if (!ledger.ok) return fanoutFail(ledger.code, ledger.error, ledger.unblock);
+  if (!input.actor.session)
+    return fanoutFail(
+      "blocked",
+      "WORKIT_SESSION_ID is not set: worker session ids derive from the lead's",
+      "export WORKIT_SESSION_ID=<your session id>, then render the brief again",
+    );
+  const branch = input.attempt === null ? slice.branch : `${slice.branch}-try${input.attempt}`;
+  const taken = plan.slices.find((other) => other.id !== slice.id && other.branch === branch);
+  if (taken)
+    return fanoutFail(
+      "invalid_input",
+      `attempt branch ${branch} is slice ${taken.id}'s branch`,
+      "pick another --attempt number, or rename one of the branches in the plan",
+    );
+  const head = branchRef(cwd, branch);
+  const planned = `${slicePath(cwd, slice)}${input.attempt === null ? "" : `+try${input.attempt}`}`;
+  const made = ledger.value.rows.findLast(
+    (row) =>
+      row.type === "fanout.worktree.created" &&
+      row.fanout === plan.name &&
+      row.slice === slice.id &&
+      typeof row.path === "string" &&
+      samePath(row.path, planned),
+  );
+  const fresh = Boolean(head) && made?.baseSha === head;
+  // A dependent slice made after its dependencies landed starts on the trunk (#506).
+  const sliceBase = typeof made?.startBase === "string" ? made.startBase : slice.base;
+  const mode: BriefMode = input.mode ?? (head && !fresh ? "resume" : "new");
+  if (mode === "resume" && !head)
+    return fanoutFail(
+      "not_found",
+      `MODE resume needs the branch ${branch}, which does not exist here`,
+      `workit fanout brief ${slice.id} --mode new`,
+    );
+
+  const exists = listWorktrees(cwd).some((entry) => samePath(entry.path, planned));
+  excludeScratch(cwd);
+  const scratch = exists ? `${planned}/${SCRATCH_DIR}` : SCRATCH_DIR;
+  const scratchLine = exists
+    ? `SCRATCH: ${scratch}  (yours alone; temp files go here, never a shared path)`
+    : `SCRATCH: ${SCRATCH_DIR}/ at your worktree root (mkdir -p it; git ignores it; never a shared path)`;
+
+  const standing = activeStanding(ledger.value.rows, plan.name, planLeads(plan)).map((row) => ({
+    id: row.id,
+    what: String(row.what),
+  }));
+  const host = input.host ?? input.actor.host;
+  const identity = identityOf(host);
+  const model = resolveRoleModel(cwd, { role: "implementer", tier: slice.tier }, host);
+  const verifier = resolveRoleModel(cwd, { role: "verifier" }, host);
+  const coAuthor = coAuthorTrailer(host, model?.model ?? null);
+  const minted = workerSession(sessionSafe(input.actor.session), slice.id, input.attempt);
+  const session = identity === "declared" ? minted : null;
+  const fanIn =
+    plan.fanIn === "integration"
+      ? [
+          `FAN-IN: integration branch ${plan.trunk}. Before you report, merge its tip into your branch`,
+          `  (\`git merge --no-edit ${plan.trunk}\`), resolve conflicts inside SCOPE and re-run VERIFY, so the`,
+          "  lead's merge is a fast-forward. No other merge, and no rebase, retarget or force-push.",
+        ]
+      : [
+          "FAN-IN: one PR per slice. Never rebase, retarget, merge or force-push: the lead owns topology.",
+        ];
+
+  const lines = [
+    `MODE: ${mode}${input.attempt === null ? "" : `  (race attempt ${input.attempt}: the lead keeps the attempt with the best verdict)`}`,
+    `WORKER: ${slice.id}${input.attempt === null ? "" : `+try${input.attempt}`}`,
+    `GOAL: ${slice.goal}`,
+    `SCOPE: ${slice.scope.join(", ")}`,
+    ...(slice.owns.length ? [`  owns: ${slice.owns.join(", ")}`] : []),
+    `  branch: ${branch}   base: ${sliceBase}`,
+    `CONTEXT: ${slice.context ?? "none given: read the files in SCOPE and the neighbours they import"}`,
+    ...(slice.issues.length
+      ? [
+          `ISSUE: ${slice.issues.join(", ")}  (\`workit pr create\` on ${branch} links ${slice.issues.length === 1 ? "it" : "them"} by itself; no --issue needed)`,
+        ]
+      : []),
+    ...(mode === "resume" && head
+      ? [
+          `  resume: continue ${branch} from ${head.slice(0, 12)}; read \`git log ${sliceBase}..${branch}\` and \`workit ledger list --branch ${branch}\` (the last report, verdicts, rulings)`,
+        ]
+      : []),
+    "ACCEPTANCE:",
+    ...slice.acceptance.map((line) => `  - ${line}`),
+    `VERIFY: ${slice.verify.join("; ")}`,
+    ...verifyLines(exists ? planned : cwd, slice.scope, slice.verify),
+    ...(slice.reason ? [`REASON: ${slice.reason}`] : []),
+    `TIER: ${slice.tier}`,
+    ...(model
+      ? [
+          `  model: ${model.model}${model.effort ? `  effort: ${model.effort}` : ""}  (${model.source})`,
+        ]
+      : []),
+    ...(verifier
+      ? [
+          `  verifier: model ${verifier.model}${verifier.effort ? `  effort ${verifier.effort}` : ""}  (${verifier.source})`,
+        ]
+      : []),
+    ...spawnLines(cwd, host, slice.id, slice.tier),
+    `TIMEBOX: ${timeboxText(slice.timebox, slice.tier)}; past it without a new commit you will be replaced`,
+    scratchLine,
+    `FORBIDDEN: ${slice.forbidden.join("; ")}`,
+    ...fanIn,
+    ...REPORT,
+    "STANDING:",
+    ...(standing.length
+      ? standing.map((order) => `  - ${order.what}`)
+      : ["  - none recorded beyond this brief"]),
+    exists
+      ? `WORKTREE: ${planned}  (made by \`workit fanout worktree create ${slice.id}\`; yours alone)`
+      : `WORKTREE: ${planned}  (not made yet: the lead runs \`workit fanout worktree create ${slice.id}\` before spawning, then renders this brief again)`,
+    ...(exists &&
+    typeof made?.install === "string" &&
+    !fs.existsSync(path.join(planned, "node_modules"))
+      ? [`INSTALL: \`${made.install}\` first: the main checkout's node_modules was not linked here`]
+      : []),
+    ...identityLines(identity, minted),
+    ...rules(mode, branch, sliceBase, exists ? planned : null, coAuthor, host),
+  ];
+  return {
+    ok: true,
+    data: {
+      fanout: plan.name,
+      slice: slice.id,
+      mode,
+      attempt: input.attempt,
+      branch,
+      base: sliceBase,
+      tier: slice.tier,
+      issues: slice.issues,
+      model: model?.model ?? null,
+      effort: model?.effort ?? null,
+      verifier: verifier ? { model: verifier.model, effort: verifier.effort } : null,
+      scratch,
+      host,
+      coAuthor,
+      session,
+      standing,
+      text: `${lines.join("\n")}\n`,
+    },
+  };
+}