faberun 0.7.0 → 0.9.0

package/src/plan/template.mjs

@@ -0,0 +1,278 @@
+/**
+ * Planning contract templates: the one-node `mode: "discovery"` contracts a
+ * plan pipeline runs outside the control session — draft, review, revise (a
+ * draft carrying the reviewer's findings), spec authoring, and spec review.
+ * Separate from freeze.mjs (which turns an already-built plan into a
+ * validated contract on disk) because this module never touches the
+ * filesystem or a model: it only assembles the JSON object `validateContract`
+ * accepts, from exactly the inputs each role may see. The reviewer's packet
+ * is the enforced case: it carries the spec, the repository facts and the
+ * artefact under review, never the author's packet, transcript or summary.
+ */
+import { assertObject, rejectUnknown, requireId, requireString, requireStringArray } from "../contract/assert.mjs";
+import { CONTRACT_VERSION, PROTOCOL_SCHEMA_VERSION } from "../contract/index.mjs";
+import { validateDefinitionOfDone } from "../contract/definition-of-done.mjs";
+import { validateVerificationCommands } from "../contract/verification.mjs";
+
+/** @typedef {import("../contract/index.mjs").JsonObject} JsonObject */
+/** @typedef {"draft"|"review"|"revise"|"spec-author"|"spec-review"} PlanningKind */
+/** @typedef {"low"|"standard"|"high"} RiskTier */
+/** @typedef {{campaignId: string, phase: string, n: number, goal?: string, cwd?: string, runtimes: Record<string, JsonObject>, runtimeDefaults: {worker?: string, judge?: string}, specPath?: string, repoFactsPath?: string, planPath?: string, findingsPath?: string, notesPath?: string}} PlanningContractInputs */
+/** @typedef {{id: string, objective: string, taskKind: string, riskTier: RiskTier, dependsOn: string[], readFiles: string[], writeFiles: string[], definitionOfDone: import("../contract/definition-of-done.mjs").DefinitionOfDoneItem[], verification: import("../contract/verification.mjs").VerificationCommand[]}} PlanOutputNode */
+/** @typedef {{nodes: PlanOutputNode[], justification?: string}} PlanOutput */
+/** @typedef {{id: string, severity: "critical"|"major"|"minor", nodeId: string, text: string}} PlanFindingOutput */
+
+/**
+ * The taskKind catalogue a draft or revise classifies against. Exported here,
+ * not read from a separate document, so `TASK_KIND_CATALOGUE_PATH` (this
+ * module's own repo-relative path) is a real, always-present file a
+ * closed-context worker can be told to read for the authoritative list.
+ */
+export const TASK_KINDS = Object.freeze(["docs", "implement", "test", "refactor", "infra", "judge"]);
+
+/** The risk tiers a draft or revise classifies against. */
+export const RISK_TIERS = Object.freeze(["low", "standard", "high"]);
+
+/** This module's own repo-relative path: the taskKind catalogue's home. */
+export const TASK_KIND_CATALOGUE_PATH = "src/plan/template.mjs";
+
+/**
+ * Which of the caller's `runtimeDefaults` roles resolves this contract's
+ * single node. A draft or revise is authored by the worker role; a review or
+ * spec-review is graded by the judge role — there is no gate on this
+ * single-node contract, so the role only decides which runtime id the node
+ * itself carries.
+ *
+ * @type {Record<PlanningKind, "worker"|"judge">}
+ */
+const KIND_ROLE = Object.freeze({
+  draft: "worker",
+  revise: "worker",
+  "spec-author": "worker",
+  review: "judge",
+  "spec-review": "judge",
+});
+
+/** @type {Record<PlanningKind, string[]>} */
+const REQUIRED_INPUTS = Object.freeze({
+  draft: ["specPath", "repoFactsPath"],
+  revise: ["specPath", "repoFactsPath", "findingsPath"],
+  review: ["specPath", "repoFactsPath", "planPath"],
+  "spec-author": ["notesPath"],
+  "spec-review": ["specPath"],
+});
+
+const PLAN_OUTPUT_SHAPE = "{nodes: [{id, objective, taskKind, riskTier, dependsOn, readFiles, writeFiles, definitionOfDone, verification}], justification?}";
+const FINDINGS_SHAPE = "[{id, severity, nodeId, text}]";
+
+/** @type {Record<PlanningKind, string>} */
+const OBJECTIVES = Object.freeze({
+  draft: "Draft an execution plan for this phase: classify every node's taskKind and riskTier from the spec and the repository facts, and propose the dependency graph.",
+  revise: "Revise the plan to resolve every one of the reviewer's findings, keeping the same classification and graph shape as a fresh draft.",
+  review: "Review this plan against the spec and the repository facts, and report only findings.",
+  "spec-author": "Turn free notes into a structured spec document following the spec format.",
+  "spec-review": "Review this spec for traceability and completeness, and report only findings.",
+});
+
+/** @type {Record<PlanningKind, string[]>} */
+const INSTRUCTIONS = Object.freeze({
+  draft: [
+    `Consult ${TASK_KIND_CATALOGUE_PATH}'s exported TASK_KINDS before classifying any node; taskKind must be one of that catalogue and riskTier must be one of ${RISK_TIERS.join(", ")}.`,
+    `Return exactly one worker-result JSON object. Put the plan in output.plan as ${PLAN_OUTPUT_SHAPE} and nothing else in output.`,
+    "Never name a runtime, harness, model, or vendor anywhere in output.plan. taskKind and riskTier are the only classification a draft makes; a routing table assigns a runtime afterward, from those two fields alone.",
+  ],
+  revise: [
+    "Read the findings and resolve every one; do not leave a critical or major finding unaddressed.",
+    `Consult ${TASK_KIND_CATALOGUE_PATH}'s exported TASK_KINDS before classifying any node; taskKind must be one of that catalogue and riskTier must be one of ${RISK_TIERS.join(", ")}.`,
+    `Return exactly one worker-result JSON object. Put the revised plan in output.plan as ${PLAN_OUTPUT_SHAPE} and nothing else in output.`,
+    "Never name a runtime, harness, model, or vendor anywhere in output.plan.",
+  ],
+  review: [
+    "You are given only the spec, the repository facts, and the plan under review; you have not seen how the plan was produced or any reasoning behind it. Review the artefact alone.",
+    `Return exactly one worker-result JSON object. Put your findings in output.findings as ${FINDINGS_SHAPE} and nothing else in output.`,
+    "severity must be one of critical, major, minor. Every finding's nodeId must name a node id that actually appears in the plan under review.",
+  ],
+  "spec-author": [
+    "Read the notes and turn them into a structured spec document: front matter, Intent, Requirements (each with a stable R<n> id and a proof), Non-goals, Constraints, Success criteria, and Risks.",
+    "Return exactly one worker-result JSON object. Put the authored spec text, as one markdown document, in output.spec and nothing else in output.",
+  ],
+  "spec-review": [
+    "You are given only the spec under review; you have not seen the author's notes or reasoning. Review the document alone.",
+    `Return exactly one worker-result JSON object. Put your findings in output.findings as ${FINDINGS_SHAPE} and nothing else in output.`,
+    "severity must be one of critical, major, minor. Every finding's nodeId must name the requirement id, or section heading, it concerns.",
+  ],
+});
+
+/** @type {Record<PlanningKind, string[]>} */
+const NON_GOALS = Object.freeze({
+  draft: ["Assigning a runtime, harness, or model to any node."],
+  revise: ["Assigning a runtime, harness, or model to any node.", "Reopening a finding the reviewer did not raise."],
+  review: ["Proposing a replacement plan.", "Assigning a runtime, harness, or model to any node."],
+  "spec-author": ["Declaring nodes, phases, or architecture in the spec."],
+  "spec-review": ["Proposing a replacement spec."],
+});
+
+/**
+ * @param {PlanningKind} kind
+ * @param {PlanningContractInputs} inputs
+ * @returns {string[]}
+ */
+function readFilesForKind(kind, inputs) {
+  if (kind === "draft") return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.repoFactsPath), TASK_KIND_CATALOGUE_PATH];
+  if (kind === "revise") {
+    return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.repoFactsPath), TASK_KIND_CATALOGUE_PATH, /** @type {string} */ (inputs.findingsPath)];
+  }
+  if (kind === "review") return [/** @type {string} */ (inputs.specPath), /** @type {string} */ (inputs.repoFactsPath), /** @type {string} */ (inputs.planPath)];
+  if (kind === "spec-author") return [/** @type {string} */ (inputs.notesPath)];
+  return [/** @type {string} */ (inputs.specPath)];
+}
+
+/**
+ * Build one of the planning pipeline's one-node discovery contracts. Pure:
+ * no file is read or written, and no model is invoked. The returned object is
+ * the raw, not-yet-validated contract JSON `validateContract` accepts.
+ *
+ * @param {PlanningKind} kind
+ * @param {PlanningContractInputs} inputs
+ * @returns {JsonObject}
+ */
+export function buildPlanningContract(kind, inputs) {
+  const required = REQUIRED_INPUTS[kind];
+  if (!required) throw new TypeError(`buildPlanningContract: unknown kind ${kind}`);
+  requireId(inputs.campaignId, "inputs.campaignId");
+  requireString(inputs.phase, "inputs.phase");
+  if (!Number.isInteger(inputs.n) || inputs.n <= 0) throw new TypeError("inputs.n must be a positive integer");
+  assertObject(inputs.runtimes, "inputs.runtimes");
+  assertObject(inputs.runtimeDefaults ?? {}, "inputs.runtimeDefaults");
+  const inputRecord = /** @type {Record<string, unknown>} */ (inputs);
+  for (const field of required) requireString(inputRecord[field], `inputs.${field}`);
+
+  const readFiles = readFilesForKind(kind, inputs);
+  const role = KIND_ROLE[kind];
+  const runtimeId = (inputs.runtimeDefaults ?? {})[role];
+
+  /** @type {JsonObject} */
+  const taskPacket = {
+    mode: "discovery",
+    objective: OBJECTIVES[kind],
+    instructions: INSTRUCTIONS[kind],
+    readFiles,
+    writeFiles: [],
+    symbols: [],
+    decisions: [],
+    nonGoals: NON_GOALS[kind],
+    verification: [],
+  };
+
+  return {
+    schemaVersion: PROTOCOL_SCHEMA_VERSION,
+    contractVersion: CONTRACT_VERSION,
+    id: `${inputs.campaignId}-plan-${inputs.phase}-${kind}-${inputs.n}`,
+    campaignId: inputs.campaignId,
+    goal: inputs.goal ?? `Plan ${kind} for phase ${inputs.phase}`,
+    cwd: inputs.cwd ?? ".",
+    runtimes: inputs.runtimes,
+    runtimeDefaults: inputs.runtimeDefaults ?? {},
+    nodes: [
+      {
+        id: kind,
+        type: kind,
+        phase: inputs.phase,
+        dependsOn: [],
+        ...(runtimeId === undefined ? {} : { runtime: runtimeId }),
+        taskPacket,
+        gate: false,
+      },
+    ],
+  };
+}
+
+const PLAN_FIELDS = new Set(["nodes", "justification"]);
+const PLAN_NODE_FIELDS = new Set(["id", "objective", "taskKind", "riskTier", "dependsOn", "readFiles", "writeFiles", "definitionOfDone", "verification"]);
+
+/**
+ * Validate a draft or revise worker's `output.plan`. Rejects a node naming a
+ * runtime, harness, model, or vendor (an unknown field, since a plan node's
+ * shape never includes one) and a node missing taskKind or riskTier.
+ *
+ * @param {unknown} plan
+ * @returns {PlanOutput}
+ */
+export function validatePlanOutput(plan) {
+  assertObject(plan, "plan");
+  const record = /** @type {Record<string, unknown>} */ (plan);
+  rejectUnknown(record, PLAN_FIELDS, "plan");
+  if (!Array.isArray(record.nodes) || record.nodes.length === 0) {
+    throw new TypeError("plan.nodes must be a non-empty array");
+  }
+  const nodes = record.nodes.map((node, index) => {
+    const label = `plan.nodes[${index}]`;
+    assertObject(node, label);
+    const nodeRecord = /** @type {Record<string, unknown>} */ (node);
+    rejectUnknown(nodeRecord, PLAN_NODE_FIELDS, label);
+    requireId(nodeRecord.id, `${label}.id`);
+    requireString(nodeRecord.objective, `${label}.objective`);
+    if (typeof nodeRecord.taskKind !== "string" || !TASK_KINDS.includes(nodeRecord.taskKind)) {
+      throw new TypeError(`${label}.taskKind must be one of ${TASK_KINDS.join(", ")}`);
+    }
+    if (typeof nodeRecord.riskTier !== "string" || !RISK_TIERS.includes(nodeRecord.riskTier)) {
+      throw new TypeError(`${label}.riskTier must be one of ${RISK_TIERS.join(", ")}`);
+    }
+    const dependsOn = nodeRecord.dependsOn ?? [];
+    requireStringArray(dependsOn, `${label}.dependsOn`);
+    const readFiles = nodeRecord.readFiles ?? [];
+    requireStringArray(readFiles, `${label}.readFiles`);
+    const writeFiles = nodeRecord.writeFiles ?? [];
+    requireStringArray(writeFiles, `${label}.writeFiles`);
+    const definitionOfDone = validateDefinitionOfDone(nodeRecord.definitionOfDone ?? [], `${label}.definitionOfDone`);
+    const verification = validateVerificationCommands(nodeRecord.verification ?? [], `${label}.verification`);
+    return /** @type {PlanOutputNode} */ ({
+      id: /** @type {string} */ (nodeRecord.id),
+      objective: /** @type {string} */ (nodeRecord.objective),
+      taskKind: /** @type {string} */ (nodeRecord.taskKind),
+      riskTier: /** @type {RiskTier} */ (nodeRecord.riskTier),
+      dependsOn: /** @type {string[]} */ (dependsOn),
+      readFiles: /** @type {string[]} */ (readFiles),
+      writeFiles: /** @type {string[]} */ (writeFiles),
+      definitionOfDone,
+      verification,
+    });
+  });
+  if (record.justification !== undefined) requireString(record.justification, "plan.justification");
+  return {
+    nodes,
+    ...(record.justification === undefined ? {} : { justification: /** @type {string} */ (record.justification) }),
+  };
+}
+
+const FINDING_FIELDS = new Set(["id", "severity", "nodeId", "text"]);
+const FINDING_SEVERITIES = new Set(["critical", "major", "minor"]);
+
+/**
+ * Validate a review or spec-review worker's `output.findings`. A finding
+ * without `severity` or `nodeId` is invalid.
+ *
+ * @param {unknown} findings
+ * @returns {PlanFindingOutput[]}
+ */
+export function validateFindings(findings) {
+  if (!Array.isArray(findings)) throw new TypeError("findings must be an array");
+  return findings.map((finding, index) => {
+    const label = `findings[${index}]`;
+    assertObject(finding, label);
+    const record = /** @type {Record<string, unknown>} */ (finding);
+    rejectUnknown(record, FINDING_FIELDS, label);
+    requireId(record.id, `${label}.id`);
+    if (typeof record.severity !== "string" || !FINDING_SEVERITIES.has(record.severity)) {
+      throw new TypeError(`${label}.severity must be one of critical, major, minor`);
+    }
+    requireString(record.nodeId, `${label}.nodeId`);
+    requireString(record.text, `${label}.text`);
+    return /** @type {PlanFindingOutput} */ ({
+      id: /** @type {string} */ (record.id),
+      severity: /** @type {"critical"|"major"|"minor"} */ (record.severity),
+      nodeId: /** @type {string} */ (record.nodeId),
+      text: /** @type {string} */ (record.text),
+    });
+  });
+}

package/src/seat/allowance.mjs

@@ -0,0 +1,177 @@
+/**
+ * Owns sampling the seat's allowance -- a coarse, harness-reported rate-limit
+ * signal -- from one minimal live invocation, and the delta between two
+ * samples. Separate from every other file in `seat/` because this is the one
+ * that spends a real call, however small; `seat/harnesses.mjs` only launches
+ * and detects, `seat/index.mjs` only composes tmux with that registry.
+ *
+ * Measured 2026-09-17 against `claude -p 'Reply with exactly OK and use no
+ * tools.' --output-format stream-json --verbose`, at a cost of
+ * `total_cost_usd: 0.27848` for that one probe (see `protocol.mjs`'s
+ * `extractClaudeAllowance` header for the raw measured line and the scale
+ * evidence): the stream carries one `rate_limit_event` line, not a field on
+ * the terminal `result` event, and no other operator harness (codex, zcode,
+ * dsh, agy) has been measured. `defaultInvoke` below only ever spawns a
+ * process for `claude`; every other harness name returns null without
+ * spending a call, which is also what happens once a claude call runs but the
+ * adapter finds no signal on it (`normalize(...).allowance` with every member
+ * null). Every sampling call site pays this cost again: `campaign init`
+ * (once) and `plan freeze` (once per phase) each spend one probe when the
+ * sampled harness is claude.
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import { getHarness } from "../harnesses/index.mjs";
+
+// `window` is optional on the type (not every construction site names one --
+// `plan/pipeline.mjs` rebuilds a start sample from journal fields that predate
+// this field) even though every live sample from `sampleAllowance` always
+// carries it, `null` included.
+/** @typedef {{remaining: number|null, limit: number|null, resetsAt: string|null, window?: string|null}} Allowance */
+/** @typedef {{stdout: string, exitCode: number|null, signal: string|null}} InvokeResult */
+
+const ALLOWANCE_PROBE_PROMPT = "Reply with exactly OK and use no tools.";
+const ALLOWANCE_PROBE_TIMEOUT_MS = 30_000;
+// The signal is account-wide (see protocol.mjs's extractClaudeAllowance
+// header), not per-model, so the probe's own model choice does not affect
+// what it measures; claude-sonnet-5 is the cheapest claude model this
+// registry already names (src/engine/runtime-discovery.mjs), which keeps a
+// spent probe call cheap without inventing an unlisted model string.
+const ALLOWANCE_PROBE_MODEL = "claude-sonnet-5";
+
+/**
+ * The argv/executable for one minimal claude probe, built through the claude
+ * adapter's own `command` so the probe pays the same preamble discipline
+ * (`claudePreambleArgs`: no skills, no MCP, no settings, a bare tool list)
+ * every worker invocation already pays instead of a hand-written argv that
+ * skips it -- measured 2026-09-01 on that discipline alone, ~4,300
+ * uncached input tokens per turn against 65,170 with the ambient
+ * configuration (see `harnesses/claude/index.mjs`).
+ *
+ * @returns {import("../harnesses/index.mjs").HarnessCommand}
+ */
+function claudeProbeCommand() {
+  return getHarness("claude").command({ harness: "claude", model: ALLOWANCE_PROBE_MODEL }, ALLOWANCE_PROBE_PROMPT, {});
+}
+
+/**
+ * One minimal claude call, its stdout handed back raw for the adapter's own
+ * `normalize` to parse. Every other harness resolves to null without
+ * spawning anything: the signal has only ever been measured on claude's
+ * stream, and probing a harness that is known to expose nothing would spend a
+ * call for no reading.
+ *
+ * @param {string} harness
+ * @param {{spawn?: typeof nodeSpawn}} [options]
+ * @returns {Promise<InvokeResult|null>}
+ */
+export function defaultInvoke(harness, { spawn = nodeSpawn } = {}) {
+  if (harness !== "claude") return Promise.resolve(null);
+  const command = claudeProbeCommand();
+  return new Promise((settle) => {
+    let child;
+    try {
+      child = spawn(command.executable, command.args, {
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+    } catch {
+      settle(null);
+      return;
+    }
+    let stdout = "";
+    let settled = false;
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        // ESRCH: the child is already gone.
+      }
+    }, ALLOWANCE_PROBE_TIMEOUT_MS);
+    // A missing or early-dying binary can make the write below fail with
+    // EPIPE on the stdin stream itself, which is a different EventEmitter
+    // from the child process object below and needs its own listener (see
+    // `engine/process.mjs`'s stdin-transport branch for the same guard).
+    child.stdin.on("error", () => {});
+    child.stdin.end(command.input ?? "");
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.on("data", () => {});
+    child.once("error", () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      settle(null);
+    });
+    child.once("close", (exitCode, signalName) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      settle({ stdout, exitCode, signal: signalName });
+    });
+  });
+}
+
+/**
+ * The current seat allowance, from one minimal invocation, or null when the
+ * harness is unset, the invocation fails, or the harness's adapter reports no
+ * signal. Never throws: an allowance sample is advisory, and a probe failure
+ * must not fail the campaign operation sampling it.
+ *
+ * @param {{harness: string|null, invoke?: (harness: string) => Promise<InvokeResult|null>|InvokeResult|null}} options
+ * @returns {Promise<Allowance|null>}
+ */
+export async function sampleAllowance({ harness, invoke = defaultInvoke }) {
+  if (!harness) return null;
+  /** @type {InvokeResult|null} */
+  let raw;
+  try {
+    raw = await invoke(harness);
+  } catch {
+    return null;
+  }
+  if (!raw || typeof raw.stdout !== "string") return null;
+  try {
+    const envelope = /** @type {{allowance?: Allowance|null}} */ (getHarness(harness).normalize(raw.stdout, raw.exitCode ?? null, raw.signal ?? null));
+    // The adapter always returns the shape (never omits it), with every
+    // member null when its stream carried no signal: that all-null shape and
+    // "no signal" are the same fact, so both collapse to null here.
+    return envelope.allowance && envelope.allowance.remaining !== null ? envelope.allowance : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The change in remaining allowance between two samples, or null when either
+ * sample is absent, itself carries no remaining figure, or the two samples
+ * name different rate-limit windows: a `five_hour` utilization minus a
+ * `seven_day` one is not a delta, even though both are 0..1 fractions that
+ * subtract without error.
+ *
+ * @param {Allowance|null} start
+ * @param {Allowance|null} freeze
+ * @returns {number|null}
+ */
+export function allowanceDelta(start, freeze) {
+  if (!start || !freeze || start.remaining === null || freeze.remaining === null) return null;
+  if (!start.window || !freeze.window || start.window !== freeze.window) return null;
+  return freeze.remaining - start.remaining;
+}
+
+/**
+ * The four sampled fields a `seat.allowance` journal event carries, from a
+ * sample or its absence: every member null when there is no sample, so a
+ * call site building the event never repeats this null-coalescing itself. The
+ * one place both `campaign init`'s start write and `plan freeze`'s freeze
+ * write get these fields from, alongside `appendSeatAllowanceEvent`
+ * (`campaign/journal.mjs`) being the one place either write actually happens.
+ *
+ * @param {Allowance|null} sample
+ * @returns {{remaining: number|null, limit: number|null, resetsAt: string|null, window: string|null}}
+ */
+export function allowanceEventFields(sample) {
+  return {
+    remaining: sample?.remaining ?? null,
+    limit: sample?.limit ?? null,
+    resetsAt: sample?.resetsAt ?? null,
+    window: sample?.window ?? null,
+  };
+}