the-high-council 0.6.0

package/src/seat-role.js

@@ -0,0 +1,96 @@
+import { DEFAULT_PERSONAS as PERSONAS_DEFAULT, resolvePersona } from './personas.js';
+
+// v6 §1: an optional per-seat `role` field, alongside `provider`/`model`/
+// `maxTokens`/`lab`. Absent, prompt assembly is byte-identical to today -
+// proven by test/seat-role.test.js's golden-hash comparison against every
+// shipped chain config. Present, it augments the debate-stage system
+// prompt only (wired in src/chain.js at the debate-stage invoke call);
+// the panel stage never sees it (that structural guarantee is v6 §3,
+// phase 2 - this module only defines the field and the augmentation, it
+// does not itself enforce stage isolation).
+//
+// §2's argued position: `lens` and `persona` are separable because a lens
+// is what can plausibly change what a seat catches, and a persona only
+// changes how it talks - coupling them would make it impossible to
+// attribute a measured difference (v6 §5) to either one.
+
+// Fixed critique-function instruction blocks. Wording is a placeholder
+// pending author review (v6 plan, Decisions left to the author) - the
+// enum itself, and the fact that it is closed, is not.
+export const LENSES = {
+  adversary: 'Argue against this proposal as its strongest opponent would. Find the case where it fails, not the case where it usually works.',
+  integrator: 'Judge this proposal by how it fits with everything else in the plan, not in isolation. Name what it would break or duplicate elsewhere.',
+  'long-horizon': 'Judge this proposal by what it costs to maintain a year from now, not by how it looks today. Name the maintenance burden it adds.',
+  'user-advocate': 'Judge this proposal by what the person actually using this experiences, not by what is convenient to build. Name where it makes their life harder.',
+  'security-and-legal': 'Judge this proposal for what it exposes, leaks, or obligates - data, keys, liability. Name the concrete exposure, not a general risk.',
+};
+
+// v6 phase 7 integration fix: this used to be a second, independently
+// maintained literal of the same five names src/personas.js (phase 6,
+// built in parallel off master, unaware of this module) already owns
+// with full name/voice data - exactly the "two places quietly agree
+// today, nothing stops them drifting" class this project has been
+// bitten by before (v5 Phase 2's report.json writers). Derived from
+// personas.js's own keys now, so there is one source of the five names,
+// not two.
+export const DEFAULT_PERSONAS = Object.keys(PERSONAS_DEFAULT);
+
+/**
+ * Validate a seat's `role` field. Returns an array of problem strings -
+ * empty means valid. Never throws; a chain-config lint (v5's own
+ * lintChain, v6 §1) is expected to call this and surface problems the
+ * same fail-loud way it already surfaces a missing seats.critics.
+ */
+export function validateSeatRole(role) {
+  if (role === undefined || role === null) return [];
+  const problems = [];
+  if (typeof role !== 'object' || Array.isArray(role)) {
+    return [`role must be an object with an optional "lens" and/or "persona" field, got ${Array.isArray(role) ? 'an array' : typeof role}`];
+  }
+  const { lens, persona, ...rest } = role;
+  if (lens === undefined && persona === undefined) {
+    problems.push('role is set but has neither "lens" nor "persona" - at least one must be present');
+  }
+  if (lens !== undefined && !(lens in LENSES)) {
+    problems.push(`role.lens "${lens}" is not one of: ${Object.keys(LENSES).join(', ')}`);
+  }
+  if (persona !== undefined && typeof persona !== 'string') {
+    problems.push(`role.persona must be a string persona name, got ${typeof persona}`);
+  }
+  for (const key of Object.keys(rest)) {
+    problems.push(`role.${key} is not a recognized field - only "lens" and "persona" are`);
+  }
+  return problems;
+}
+
+/**
+ * The debate-stage system prompt for a seat, with its role (if any)
+ * appended after the chain's own instructions. A seat with no role
+ * produces `basePrompt` unchanged - not a copy with an empty suffix,
+ * the exact same string, so a golden-hash comparison is a real
+ * byte-identity check and not merely a "looks the same" one.
+ *
+ * v6 phase 7 bug-audit fix: `role.persona` used to be embedded as a
+ * bare, unresolved string, entirely disconnected from personas.js's
+ * curated name/voice data (built by phase 6, in parallel, unaware
+ * this module existed) - the exact safety net phase 6 exists for
+ * (keeping third-party names out of a public MIT repo) had nothing
+ * to do with what actually reached a live model prompt. Now resolved
+ * against `personas` (defaulting to the shipped set) when the key
+ * matches; an unresolved key still falls back to the raw string
+ * unchanged, since phase 6 also explicitly allows an operator to
+ * replace the whole set, and this module has no way to know which
+ * operator-supplied personas.json (if any) was loaded for this run.
+ */
+export function applySeatRole(basePrompt, role, personas = PERSONAS_DEFAULT) {
+  if (role === undefined || role === null) return basePrompt;
+  const blocks = [];
+  if (role.lens && LENSES[role.lens]) blocks.push(LENSES[role.lens]);
+  if (role.persona) {
+    const resolved = resolvePersona(role.persona, personas);
+    const detail = resolved ? ` (${resolved.name}). ${resolved.voice}` : '.';
+    blocks.push(`You are arguing as ${role.persona}${detail} Let that voice and point of view shape how you argue, without changing what you are actually judging.`);
+  }
+  if (!blocks.length) return basePrompt;
+  return `${basePrompt}\n\n[SEAT ROLE]\n${blocks.join('\n\n')}\n[END SEAT ROLE]`;
+}

package/src/shape-rounds.js

@@ -0,0 +1,58 @@
+// v5 §1 candidate 1: which critique rounds in a run were spent entirely on
+// document shape rather than substance. Reads each round's critique
+// file(s) already written to disk (panel-N-<lab>.md for a panel chain,
+// critique-N.md for a single-critic chain) - no new state, no ledger,
+// derived from what a run already writes.
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const readJson = p => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } };
+
+// The project has no existing format/substance objection classifier to
+// reuse - this is a fresh, deliberately conservative keyword heuristic
+// over a failure's criterion+problem text. A substance objection that
+// happens to mention one of these words could misclassify; the trade is
+// toward not flagging a round shape_only unless it's clearly shape talk.
+const FORMAT_PATTERN = /\b(format|formatting|structure|heading|header|section order|numbering|numbered|whitespace|indent(?:ation)?|markdown|bullet|list style|capitali[sz]ation|typo|wording|title case|json shape|schema shape)\b/i;
+
+export function classifyFailure(failure) {
+  const text = `${failure?.criterion || ''} ${failure?.problem || ''}`;
+  return FORMAT_PATTERN.test(text) ? 'format' : 'substance';
+}
+
+// Round number from a stage filename, e.g. "panel-2-glm.md" -> 2,
+// "critique-3.md" -> 3. Other stage files (criteria.md, build.md, ...)
+// return null.
+function roundOfFile(name) {
+  const m = name.match(/^(?:panel|critique)-(\d+)(?:-[a-z0-9]+)?\.md$/);
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * Which critique rounds in run folder `dir` spent entirely on document
+ * shape. A round counts as shape_only when it has at least one failure and
+ * every failure in it classifies as format-class; a round with zero
+ * failures (a clean pass) is not counted - nothing was spent on it.
+ * Never throws - a missing or unreadable dir means no rounds, not an error.
+ */
+export function shapeRounds(dir) {
+  let files = [];
+  try { files = existsSync(dir) ? readdirSync(dir) : []; } catch { return { rounds: [], shapeOnlyRounds: 0 }; }
+
+  const byRound = new Map();
+  for (const f of files) {
+    const round = roundOfFile(f);
+    if (round === null) continue;
+    const parsed = readJson(join(dir, f));
+    const failures = Array.isArray(parsed?.failures) ? parsed.failures : [];
+    if (!byRound.has(round)) byRound.set(round, []);
+    byRound.get(round).push(...failures);
+  }
+
+  const rounds = [...byRound.entries()].sort((a, b) => a[0] - b[0]).map(([round, failures]) => {
+    const shapeOnly = failures.length > 0 && failures.every(f => classifyFailure(f) === 'format');
+    return { round, failureCount: failures.length, shapeOnly };
+  });
+
+  return { rounds, shapeOnlyRounds: rounds.filter(r => r.shapeOnly).length };
+}

package/src/spend.js

@@ -0,0 +1,193 @@
+// Cross-run spend accounting.
+//
+// "What have I spent today, across every run" is not answerable from
+// run_status, which reports one run, or from the per-run cap, which governs
+// one run. This answers it.
+//
+// It is DERIVED, not recorded. There is no ledger file and nothing to append
+// to: every figure here is read back out of runs/<id>/ on disk, the same
+// disk-is-the-source-of-truth convention the rest of the project uses. That
+// choice buys four things a separate ledger cannot:
+//
+//   - It cannot drift. A ledger is a second copy of the truth, and a second
+//     copy that is written on a path that can fail is a copy that will
+//     eventually disagree with the run folders.
+//   - It has no failure mode to degrade from. Nothing is written, so a run
+//     can never fail, stall or warn because bookkeeping failed.
+//   - It is retroactive. Runs that completed before this file existed are
+//     already accounted for.
+//   - It respects deletion. Delete a run folder because the work was
+//     sensitive and its cost goes with it. An append-only ledger outside the
+//     project would keep a record of work the user deliberately destroyed.
+//
+// Privacy: chain name, cost and state only. Never the task path or any run
+// content - what a run was about is not spend data.
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const readJson = p => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } };
+
+// Run ids are ISO timestamps with : and . replaced, e.g.
+// 2026-09-11T10-06-06-899Z. Anything else in runs/ is not ours; skip it.
+export function runIdToDate(runId) {
+  const d = new Date(runId.replace(/T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z$/, 'T$1:$2:$3.$4Z'));
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+// A finished run's cost is in report.json. A run that is still going, or that
+// the cap stopped, has no report - but every stage it paid for left a
+// <label>.usage.json behind, so the spend is still on disk.
+function costOfRun(dir) {
+  const report = readJson(join(dir, 'report.json'));
+  if (report?.totals?.usd !== undefined && report?.totals?.usd !== null) {
+    return { usd: report.totals.usd, chain: report.chain ?? null, complete: true };
+  }
+  let usd = 0;
+  let stages = 0;
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith('.usage.json')) continue;
+    usd += readJson(join(dir, f))?.usd ?? 0;
+    stages += 1;
+  }
+  return { usd, chain: readJson(join(dir, 'run.json'))?.chain ?? null, complete: false, stages };
+}
+
+// v2 plan §8 (~/Projects/relay/runs/2026-09-11T12-19-34-184Z/deliverable.md), narrowed per
+// decision in DECISIONS.md: §8 proposed a new ledger file to get per-call cost granularity
+// and a calendar-day "cost-today" view. Both are already derivable from what's on disk -
+// report.json's `stages` array for a finished run, individual `<label>.usage.json` files for
+// one still going - so this extends the existing derivation instead of adding a ledger.
+//
+// Per-call/per-stage cost breakdown for one run: [{ label, provider, model, usd }, ...].
+function stagesOfRun(dir) {
+  const report = readJson(join(dir, 'report.json'));
+  if (Array.isArray(report?.stages)) {
+    return report.stages.map(s => ({ label: s.label, provider: s.provider ?? null, model: s.model ?? null, usd: s.usd ?? 0 }));
+  }
+  const stages = [];
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith('.usage.json')) continue;
+    const u = readJson(join(dir, f));
+    if (!u) continue;
+    stages.push({ label: f.replace(/\.usage\.json$/, ''), provider: u.provider ?? null, model: u.model ?? null, usd: u.usd ?? 0 });
+  }
+  return stages;
+}
+
+// Aggregate per-model spend across a list of run directories - the "per-call granularity"
+// §8 wanted, without a ledger: sum every stage's cost by provider/model across every run
+// given, in one pass over files already being read for their totals anyway.
+function perModelBreakdown(dirs) {
+  const byModel = new Map();
+  for (const dir of dirs) {
+    for (const s of stagesOfRun(dir)) {
+      const key = `${s.provider ?? '?'}/${s.model ?? '?'}`;
+      byModel.set(key, (byModel.get(key) ?? 0) + s.usd);
+    }
+  }
+  return [...byModel.entries()]
+    .map(([model, usd]) => ({ model, usd }))
+    .sort((a, b) => b.usd - a.usd);
+}
+
+function stateOf(dir) {
+  if (existsSync(join(dir, 'report.json'))) return 'complete';
+  if (existsSync(join(dir, 'STOPPED-budget.json'))) return 'stopped: spend cap';
+  if (readdirSync(dir).some(f => f.startsWith('NEEDS-'))) return 'paused';
+  return 'incomplete';
+}
+
+/**
+ * Spend across every run in `runsDir` within the last `days`.
+ *
+ * Never throws. A missing or unreadable runs/ is not an error - it means no
+ * runs, which is a true and useful answer.
+ */
+export function spendReport(runsDir, { days = 1, now = Date.now() } = {}) {
+  const cutoff = now - days * 24 * 3600 * 1000;
+  const runs = [];
+  let unreadable = 0;
+
+  let ids = [];
+  try {
+    ids = existsSync(runsDir) ? readdirSync(runsDir) : [];
+  } catch {
+    return { runsDir, days, since: new Date(cutoff), runs: [], totalUsd: 0, count: 0,
+             unreadable: 0, note: 'runs directory could not be read' };
+  }
+
+  for (const id of ids) {
+    const when = runIdToDate(id);
+    if (!when || when.getTime() < cutoff) continue;
+    const dir = join(runsDir, id);
+    try {
+      if (!statSync(dir).isDirectory()) continue;
+      const { usd, chain, complete } = costOfRun(dir);
+      runs.push({ id, when, chain, usd, state: stateOf(dir), complete });
+    } catch {
+      unreadable += 1;   // a run folder we cannot read is reported, not fatal
+    }
+  }
+
+  runs.sort((a, b) => b.when - a.when);
+  return {
+    runsDir, days,
+    since: new Date(cutoff),
+    runs,
+    totalUsd: runs.reduce((s, r) => s + r.usd, 0),
+    count: runs.length,
+    unreadable,
+  };
+}
+
+/**
+ * What has been spent today, by the local calendar day (midnight to midnight), not a
+ * rolling 24h window like spendReport's default - the distinction §8 asked for by name.
+ * Adds a per-model breakdown across every run counted, which is the per-call granularity
+ * §8 wanted a ledger for; both are derived from the same on-disk files spendReport already
+ * reads, so no new file is written anywhere.
+ *
+ * Never throws, same degradation contract as spendReport.
+ */
+export function costToday(runsDir, { date = new Date(), now = Date.now() } = {}) {
+  const day = new Date(date);
+  const startOfDay = new Date(day.getFullYear(), day.getMonth(), day.getDate()).getTime();
+  const endOfDay = startOfDay + 24 * 3600 * 1000;
+  const runs = [];
+  const countedDirs = [];
+  let unreadable = 0;
+
+  let ids = [];
+  try {
+    ids = existsSync(runsDir) ? readdirSync(runsDir) : [];
+  } catch {
+    return { runsDir, date: new Date(startOfDay), runs: [], totalUsd: 0, count: 0,
+             unreadable: 0, perModel: [], note: 'runs directory could not be read' };
+  }
+
+  for (const id of ids) {
+    const when = runIdToDate(id);
+    if (!when || when.getTime() < startOfDay || when.getTime() >= endOfDay) continue;
+    const dir = join(runsDir, id);
+    try {
+      if (!statSync(dir).isDirectory()) continue;
+      const { usd, chain, complete } = costOfRun(dir);
+      runs.push({ id, when, chain, usd, state: stateOf(dir), complete });
+      countedDirs.push(dir);
+    } catch {
+      unreadable += 1;
+    }
+  }
+
+  runs.sort((a, b) => b.when - a.when);
+  return {
+    runsDir,
+    date: new Date(startOfDay),
+    runs,
+    totalUsd: runs.reduce((s, r) => s + r.usd, 0),
+    count: runs.length,
+    perModel: perModelBreakdown(countedDirs),
+    unreadable,
+  };
+}

package/src/stage-contract.js

@@ -0,0 +1,223 @@
+// Stage contract schema (v2 plan §2.2, ~/Projects/relay/runs/2026-09-11T12-19-34-184Z/deliverable.md).
+//
+// A stage contract is a small, structured, self-contained description of
+// what a stage needs and must return, derived from a chain config alone -
+// no run state, no prior conversation. It is the one shared substrate that
+// prepare_stage_prompt (§3), the resume brief (§5), the pre-flight check
+// (§6) and partial-deliverable detection (§7.1) all read or write.
+//
+// This module only defines and derives the schema (Phase 1, items 1-2). It
+// does not yet drive prompt assembly, resume, pre-flight or completeness
+// checks - those are later phases and read this contract, not the other
+// way around.
+
+// Canonical stage kinds. chain.js emits per-lab/per-round labels
+// (`propose-glm`, `panel-2-mistral`, `revise-3`, ...); STAGE_KIND_PATTERNS
+// maps any such label back to one of these fixed kinds so the contract
+// vocabulary stays small and stable even as labs and round counts vary.
+const STAGE_DEFS = {
+  questions: {
+    role: 'Ask up to N clarifying questions that would change the plan, each with a stated default.',
+    required_sections: ['questions'],
+    return_instructions: 'Return JSON: { "questions": [{ "question": string, "default": string }] }.',
+  },
+  criteria: {
+    role: 'Write the acceptance criteria the eventual deliverable will be checked against, before the deliverable exists.',
+    required_sections: ['criteria'],
+    return_instructions: 'Return JSON: { "criteria": [string, ...] }.',
+  },
+  skeleton: {
+    role: 'Sketch the buildable shape of the deliverable that proposers will each independently fill in, blind to one another.',
+    required_sections: ['skeleton'],
+    return_instructions: 'Return the skeleton as plain text.',
+  },
+  propose: {
+    role: 'Blind proposal: offer up to N buildable parts against the skeleton and criteria, without seeing any other seat\'s proposal.',
+    required_sections: ['proposals'],
+    return_instructions: 'Return JSON: { "proposals": [{ "title": string, ... }] }.',
+  },
+  judge: {
+    role: 'Score a pool of proposals from one lab and keep the strongest, distinct subset.',
+    required_sections: ['kept'],
+    return_instructions: 'Return JSON naming which proposals to keep.',
+  },
+  debate: {
+    role: 'Post an anonymised objection, support, or merge suggestion against another seat\'s proposal, without knowing which lab wrote it.',
+    required_sections: ['posts'],
+    return_instructions: 'Return JSON: { "posts": [{ "on": string, "stance": string, "text": string }] }.',
+  },
+  reply: {
+    role: 'As the proposal\'s own author, decide whether to keep, amend, or withdraw it in light of the debate posts against it.',
+    required_sections: ['replies'],
+    return_instructions: 'Return JSON: { "replies": [{ "proposal": string, "action": "keep"|"amend"|"withdraw", "text": string }] }.',
+  },
+  build: {
+    role: 'Integrate the surviving proposals into one coherent first draft of the deliverable.',
+    required_sections: ['draft'],
+    return_instructions: 'Return the draft as plain text/markdown.',
+  },
+  panel: {
+    role: 'Critique the current draft against the acceptance criteria; pass or fail it, naming every objection if failing.',
+    required_sections: ['verdict', 'objections'],
+    return_instructions: 'Return JSON: { "verdict": "pass"|"fail", "objections": [string, ...] }.',
+  },
+  critique: {
+    role: 'Critique the current draft against the acceptance criteria; pass or fail it, naming every objection if failing.',
+    required_sections: ['verdict', 'objections'],
+    return_instructions: 'Return JSON: { "verdict": "pass"|"fail", "objections": [string, ...] }.',
+  },
+  revise: {
+    role: 'Revise the draft to address the union of every critic\'s objections from the prior round.',
+    required_sections: ['draft'],
+    return_instructions: 'Return the revised draft as plain text/markdown.',
+  },
+  final: {
+    role: 'Make one last editorial pass over the signed-off draft before handoff.',
+    required_sections: ['draft'],
+    return_instructions: 'Return the final draft as plain text/markdown.',
+  },
+  handoff: {
+    role: 'Turn the finished deliverable into a build-ready handoff: an ordered task list with acceptance tests per item.',
+    required_sections: ['tasks'],
+    return_instructions: 'Return the handoff document as plain text/markdown.',
+  },
+};
+
+// Order matters only for readability; STAGE_KIND_PATTERNS is checked in
+// order and the first match wins, so put more specific patterns first.
+const STAGE_KIND_PATTERNS = [
+  [/^questions$/, 'questions'],
+  [/^criteria$/, 'criteria'],
+  [/^skeleton$/, 'skeleton'],
+  [/^propose-.+-retry$/, 'propose'],
+  [/^propose-/, 'propose'],
+  [/^judge-/, 'judge'],
+  [/^debate-/, 'debate'],
+  [/^reply-/, 'reply'],
+  [/^build$/, 'build'],
+  [/^panel-/, 'panel'],
+  [/^critique-/, 'critique'],
+  [/^revise-/, 'revise'],
+  [/^final$/, 'final'],
+  [/^handoff$/, 'handoff'],
+];
+
+/** Map a chain.js stage label (e.g. "propose-glm", "panel-2-mistral") to a canonical stage kind, or null if unrecognised. */
+export function stageKindOf(label) {
+  const hit = STAGE_KIND_PATTERNS.find(([pattern]) => pattern.test(label));
+  return hit ? hit[1] : null;
+}
+
+/**
+ * List the canonical stage kinds a given chain config will actually run,
+ * in the order chain.js runs them. Mirrors the flag checks in runChain().
+ */
+export function stageKindsFor(config) {
+  const kinds = [];
+  if (config.questions) kinds.push('questions');
+  kinds.push('criteria');
+  if (config.proposals) {
+    kinds.push('skeleton', 'propose');
+    if ((config.proposals.samples ?? 1) > 1) kinds.push('judge');
+  }
+  if (config.debate) kinds.push('debate', 'reply');
+  kinds.push('build');
+  kinds.push(config.signoff === 'unanimous' ? 'panel' : 'critique');
+  kinds.push('revise');
+  kinds.push('final');
+  if (config.handoff) kinds.push('handoff');
+  return kinds;
+}
+
+/** Required section names for a stage kind alone, with no chain config needed. */
+export function requiredSectionsFor(stageKind) {
+  const def = STAGE_DEFS[stageKind];
+  if (!def) throw new Error(`requiredSectionsFor: unknown stage kind "${stageKind}"`);
+  return [...def.required_sections];
+}
+
+// Stage kinds whose return_instructions ask for JSON (required_sections names JSON keys to
+// check for) vs. freeform markdown/text (required_sections names a single symbolic slot,
+// satisfied by any non-empty text). Used by partial-deliverable detection (§7.1) to know how
+// to validate a stage's raw output without re-deriving it from return_instructions text.
+const STRUCTURED_STAGE_KINDS = new Set(['questions', 'criteria', 'propose', 'judge', 'debate', 'reply', 'panel', 'critique']);
+export function isStructuredStage(stageKind) {
+  return STRUCTURED_STAGE_KINDS.has(stageKind);
+}
+
+/**
+ * Build the stage contract for one stage kind of one chain config.
+ * Self-contained and derived purely from `config` - no run state - so it
+ * can be regenerated identically at any point in a run's life.
+ */
+export function buildStageContract(config, stageKind) {
+  const def = STAGE_DEFS[stageKind];
+  if (!def) throw new Error(`buildStageContract: unknown stage kind "${stageKind}"`);
+  const approxLength = stageKind === 'build' || stageKind === 'revise' || stageKind === 'final'
+    ? config.estimate?.draftTokens ?? null
+    : config.estimate?.promptTokens ?? null;
+  return {
+    stage_id: stageKind,
+    role: def.role,
+    no_prior_context: true,
+    deliverable_format: {
+      required_sections: [...def.required_sections],
+      approx_length: approxLength,
+    },
+    return_instructions: def.return_instructions,
+  };
+}
+
+/**
+ * Render the self-contained stage_prompt.md bundle (§3) for a paused external stage.
+ * Pure string assembly - no file IO - so it can be unit-tested without a run folder.
+ * `references` must be paths, never inlined content: that is the property that keeps
+ * the bundle small enough for a fresh, context-empty reader to hold comfortably.
+ */
+export function renderStagePromptBundle({ contract, taskText, chainName, label, run, references }) {
+  return `# STAGE CONTRACT
+stage_id: ${contract.stage_id}
+role: ${contract.role}
+no_prior_context: true
+deliverable_format:
+  required_sections: ${JSON.stringify(contract.deliverable_format.required_sections)}
+  approx_length: ${contract.deliverable_format.approx_length ?? 'not estimated'}
+return_instructions: ${contract.return_instructions}
+
+# TASK
+${taskText}
+
+# WHAT'S ALREADY DECIDED
+Chain: ${chainName ?? 'unknown'}. This run is paused waiting on stage "${label}".
+(A fuller resume brief is planned - runs/<id>/RESUME.md, not yet built. Until then, read
+run.log in the run folder for the full stage history if you need more than this line.)
+
+# CONTEXT REFERENCES
+The following documents are relevant background. Do not assume you have read them -
+you have not. If your deliverable needs their content, read them:
+${references.map(r => `  - ${r}`).join('\n')}
+
+# WHAT NOT TO ASSUME
+No static contract/criteria conflict check has run yet for this stage (planned, not
+yet built). If the task's acceptance criteria seem to conflict with this stage's
+required_sections above, say so in your deliverable rather than silently picking one.
+
+# RETURN
+Write your deliverable per return_instructions above. Give it back to the driving
+session, which will call submit_stage(${JSON.stringify(run)}, ${JSON.stringify(label)}, <your deliverable text>).
+`;
+}
+
+/** True iff every field a stage contract is required to carry is present and non-empty. */
+export function isValidStageContract(contract) {
+  return Boolean(
+    contract &&
+    typeof contract.stage_id === 'string' && contract.stage_id.length > 0 &&
+    typeof contract.role === 'string' && contract.role.length > 0 &&
+    contract.no_prior_context === true &&
+    contract.deliverable_format &&
+    Array.isArray(contract.deliverable_format.required_sections) &&
+    contract.deliverable_format.required_sections.length > 0 &&
+    typeof contract.return_instructions === 'string' && contract.return_instructions.length > 0
+  );
+}

package/src/stage-submission.js

@@ -0,0 +1,53 @@
+// v3 plan §1: the three warn-only checks `submit_stage` runs on a peer-submitted stage answer
+// before accepting it as the stage's final one, factored out of src/mcp/server.js's tool handler
+// so they're independently testable without spinning up the MCP transport (see
+// test/peer-claim.test.js). Pure file-based logic, no network, no subprocess.
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { stageKindOf } from './stage-contract.js';
+import { validateDeliverable } from './partial-deliverable.js';
+import { writeClaim, readClaimFor } from './peer-claim.js';
+import { words } from './ui/parse.js';
+
+/**
+ * Evaluate and write one stage answer. Never rejects: every check below produces a warning,
+ * not a refusal, and the existing required-arguments/return-shape contract for a caller that
+ * omits `claimedBy` is unchanged (see the caller in src/mcp/server.js).
+ *
+ * @param {string} dir - the run folder.
+ * @param {string} stage - the stage label (e.g. "build", "criteria").
+ * @param {string} content - the submitted answer text.
+ * @param {{ claimedBy?: string, chainConfig?: object }} opts
+ * @returns {{ warnings: Array<object>, writtenFile: string, isDuplicate: boolean }}
+ */
+export function submitStageAnswer(dir, stage, content, { claimedBy, chainConfig } = {}) {
+  const warnings = [];
+
+  // (1) claim_mismatch: claimedBy given, differs from an existing claim's claimed_by.
+  const existingClaim = readClaimFor(dir, stage);
+  if (claimedBy && existingClaim && existingClaim.claimed_by !== claimedBy) {
+    warnings.push({ type: 'claim_mismatch', stage, claimed_by: claimedBy, claim_holder: existingClaim.claimed_by });
+  }
+  if (claimedBy) writeClaim(dir, stage, claimedBy);
+
+  // (2) stage_validation_failed: reuse v2's own required-sections machinery
+  // (stage-contract.js/partial-deliverable.js), not a new validator.
+  const kind = stageKindOf(stage);
+  if (chainConfig && kind) {
+    const check = validateDeliverable(kind, content);
+    if (!check.ok) warnings.push({ type: 'stage_validation_failed', stage, reason: check.reason, missing: check.missing });
+  }
+
+  // (3) duplicate_answer: <stage>.md already exists - never silently overwrite (that would
+  // silently discard whichever peer answered first). Keep both; the harness picks neither.
+  const answerFile = join(dir, `${stage}.md`);
+  const isDuplicate = existsSync(answerFile);
+  const writtenFile = isDuplicate ? join(dir, `${stage}.late.md`) : answerFile;
+  const usageFile = isDuplicate ? join(dir, `${stage}.late.usage.json`) : join(dir, `${stage}.usage.json`);
+  if (isDuplicate) warnings.push({ type: 'duplicate_answer', stage, kept: [`${stage}.md`, `${stage}.late.md`] });
+
+  writeFileSync(writtenFile, content);
+  writeFileSync(usageFile, JSON.stringify({ provider: 'external', model: 'claude-code-session', usage: { input: 0, output: words(content) }, usd: 0, ms: 0 }));
+
+  return { warnings, writtenFile, isDuplicate };
+}