the-high-council 0.6.0

package/src/replay.js

@@ -0,0 +1,40 @@
+// v5 §1 candidate 9: a numbered, indented, step-by-step transcript of a
+// run's reasoning - a CLI-native complement to the HTML export (candidate
+// 8): CLI-stepped replay for a maintainer debugging a run, vs. a
+// shareable artifact for a stranger. Read-only, derived from report.json.
+
+/**
+ * An ordered list of transcript steps from a run's report.json: proposals,
+ * then each recorded stage, then the final verdict. Each step is
+ * `{ n, kind, indent, text }` so a renderer can number and indent without
+ * re-deriving structure.
+ */
+export function buildTranscript(report) {
+  const steps = [];
+  let n = 1;
+  const push = (kind, indent, text) => steps.push({ n: n++, kind, indent, text });
+
+  push('meta', 0, `Chain: ${report.chain || 'unknown'}${report.runId ? `, run: ${report.runId}` : ''}`);
+
+  for (const p of report.proposals || []) {
+    push('proposal', 0, `Proposal ${p.id} (${p.lab}): ${p.title}`);
+    if (p.what) push('proposal-detail', 1, `What: ${p.what}`);
+    if (p.withdrawn) push('proposal-detail', 1, `WITHDRAWN${p.replaced_by ? ` in favour of ${p.replaced_by}` : ''}`);
+  }
+
+  for (const s of report.stages || []) {
+    push('stage', 0, `Stage ${s.label} (${s.provider}/${s.model})`);
+  }
+
+  for (const s of report.signoff || []) {
+    push('signoff', 1, `${s.provider}: ${s.signedOff === null ? 'abstained' : s.signedOff ? 'signed off' : 'objected'}`);
+  }
+
+  push('verdict', 0, report.passed ? 'Verdict: PASSED - every lab signed off' : 'Verdict: OPEN OBJECTIONS');
+
+  return steps;
+}
+
+export function renderTranscriptText(steps) {
+  return steps.map(s => `${String(s.n).padStart(4)}. ${'  '.repeat(s.indent)}${s.text}`).join('\n');
+}

package/src/resume-brief.js

@@ -0,0 +1,114 @@
+// Resume-brief mechanism (v2 plan §5, DEEPSEEK-4 / GLM-4 / MISTRAL-4 merged design).
+//
+// A short, deterministic, regenerable summary of one run's state, so a driving session
+// returning after time away - possibly with fully fresh context - can re-enter the run
+// by reading one short file instead of reconstructing state from raw board files.
+//
+// Load-bearing property: RESUME.md is never itself authoritative. It is always
+// regenerable from the run's actual state on disk (run.json + which stage files exist),
+// so a deleted, stale, or hand-edited copy can never become a lying source of truth -
+// the next call just rebuilds it identically. No LLM call: an LLM-generated brief could
+// itself hallucinate state and become a new silent-failure vector, which this project has
+// already been burned by once (the lab-dropout incident) and does not want a second version of.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { stageKindOf, stageKindsFor } from './stage-contract.js';
+import { checkClaimStaleness } from './peer-claim.js';
+
+// Mirrors src/mcp/server.js's waiting(dir), duplicated rather than imported: server.js is
+// the MCP entrypoint (constructs and owns the server instance as a side effect of import),
+// not a library other modules should pull in just to read run-folder state.
+function pendingStage(dir) {
+  if (!existsSync(dir)) return null;
+  const w = readdirSync(dir).filter(f => f.startsWith('NEEDS-')).map(f => f.slice(6, -3)).filter(l => !existsSync(join(dir, `${l}.md`)));
+  return w[0] || null;
+}
+
+function oneLineTaskSummary(taskPath) {
+  if (!taskPath || !existsSync(taskPath)) return '(task file not found on disk)';
+  const text = readFileSync(taskPath, 'utf8').trim();
+  const firstLine = text.split('\n').find(l => l.trim().length > 0) || text;
+  const clean = firstLine.replace(/^#+\s*/, '').trim();
+  return clean.length > 140 ? `${clean.slice(0, 137)}...` : clean;
+}
+
+/**
+ * Which stage-kind labels have at least one completed stage file on disk, in the order
+ * chain.js would have run them (per stageKindsFor). A "completed" label is any file
+ * `<label>.md` in the run folder whose label maps to a known stage kind - dedup by kind
+ * since chain.js emits one label per lab/round for several kinds.
+ */
+function completedKinds(dir, chainConfig) {
+  if (!existsSync(dir)) return [];
+  const files = readdirSync(dir).filter(f => f.endsWith('.md') && !f.startsWith('NEEDS-') && f !== 'RESUME.md' && f !== 'BOARD.md' && f !== 'HANDOFF.md' && f !== 'deliverable.md' && f !== 'WARNINGS.md' && f !== 'proposals.md' && f !== 'proposals-pool.md');
+  const seen = new Set();
+  for (const f of files) {
+    const kind = stageKindOf(f.replace(/\.md$/, ''));
+    if (kind) seen.add(kind);
+  }
+  // Preserve chain-run order rather than filesystem order, so the brief reads as a timeline.
+  return stageKindsFor(chainConfig).filter(k => seen.has(k));
+}
+
+/**
+ * Build the resume brief for one run. Pure given its inputs: same run.json + same files on
+ * disk always produce the same text (aside from being able to note new files appearing).
+ */
+export function generateResumeBrief({ runId, dir, runMeta, chainConfig }) {
+  const kindsInOrder = chainConfig ? stageKindsFor(chainConfig) : [];
+  const done = chainConfig ? completedKinds(dir, chainConfig) : [];
+  const pending = pendingStage(dir);
+  const deliverableDone = existsSync(join(dir, 'deliverable.md'));
+
+  const lines = [];
+  lines.push(`# RESUME BRIEF — run ${runId}`);
+  lines.push(`Task: ${oneLineTaskSummary(runMeta?.task)}`);
+  lines.push(`Status: ${deliverableDone ? kindsInOrder.length : done.length} of ${kindsInOrder.length || '?'} stages complete`);
+  lines.push('');
+  lines.push('## Decided so far');
+  if (done.length === 0) lines.push('- (nothing completed yet)');
+  else for (const kind of done) lines.push(`- ${kind}: complete`);
+  // v3 §2: a declared scope amendment goes on the record here - the one block every
+  // subsequent stage's prompt already reads - so a critic sees it instead of an
+  // unexplained late requirement.
+  const amendmentsPath = join(dir, 'AMENDMENTS.md');
+  if (existsSync(amendmentsPath)) {
+    lines.push('- Scope amendment(s) recorded, see below:');
+    lines.push(readFileSync(amendmentsPath, 'utf8').trim());
+  }
+  lines.push('');
+  lines.push('## Currently pending');
+  if (deliverableDone) {
+    lines.push('Stage: none - run is complete');
+  } else if (pending) {
+    lines.push(`Stage: ${pending}`);
+    lines.push('Waiting on: an external seat\'s reply (see NEEDS-<stage>.md, or dispatch it with prepare_stage_prompt)');
+    // v3 plan §1: surfaced here too, not only from external_prompt, so a returning session
+    // sees a stalled or contested claim without an extra tool call.
+    const claim = checkClaimStaleness(dir, pending);
+    lines.push(`Claim: ${claim ? claim.type : 'none'}`);
+  } else {
+    lines.push('Stage: in progress or between stages');
+    lines.push('Waiting on: nothing external right now');
+  }
+  lines.push(`Warnings: ${existsSync(join(dir, 'WARNINGS.md')) ? 'see WARNINGS.md' : 'none recorded'}`);
+  // v5 §1 candidate 3: read back from report.json rather than recomputing -
+  // by the time this runs (post-deliverable), the ledger is already settled
+  // and recorded there; a resume brief has no reason to duplicate the walk.
+  const reportPath = join(dir, 'report.json');
+  if (existsSync(reportPath)) {
+    try {
+      const report = JSON.parse(readFileSync(reportPath, 'utf8'));
+      if (report.orphanSections?.length) {
+        lines.push(`Orphaned withdrawals: ${report.withdrawalCycles} cycle(s), no surviving owner for ${report.orphanSections.join(', ')} - see BOARD.md`);
+      }
+    } catch { /* malformed report.json: say nothing rather than guess */ }
+  }
+  lines.push('');
+  lines.push('## Next action for the driving session');
+  if (deliverableDone) lines.push(`Run is complete. Deliverable at ${join(dir, 'deliverable.md')}.`);
+  else if (pending) lines.push(`Call prepare_stage_prompt(${JSON.stringify(runId)}, ${JSON.stringify(pending)}), or answer it directly and call submit_stage.`);
+  else lines.push(`Call resume_run(${JSON.stringify(runId)}) or run_status(${JSON.stringify(runId)}) to check current progress.`);
+
+  return `${lines.join('\n')}\n`;
+}

package/src/role-diagnostics.js

@@ -0,0 +1,181 @@
+// v6 §7: four failure-mode detectors, reconsidered against the corrected
+// framing (Muad, 2026-09-13): the feature is not "catch more planted
+// defects" - it is debate diversity among real model seats reasoning
+// differently about a real infrastructure decision. A deterministic
+// heuristic probe (v6 phase 4) cannot have a philosophy, so it cannot
+// see the thing this feature is for. See docs/v6-decisions.md for the
+// full argument: two of the plan's four detectors originally read
+// per-seat catch-rate data from the phase 4 probe; both are redesigned
+// here to read real debate-stage output (a run's own report.json)
+// instead, so all four detectors measure something the feature's actual
+// purpose can be judged by, not a proxy for a question the feature was
+// never trying to answer.
+//
+// Every function here is pure and read-only: no ledger, nothing
+// transmitted, computed from `report.debate.posts` on disk exactly the
+// same way verdict-stats.js and cost-forecast.js already derive their
+// numbers from run folders.
+
+const QUOTE_RE = /"([^"]{3,})"/g;
+
+function quotedSpans(text) {
+  return [...String(text || '').matchAll(QUOTE_RE)].map(m => m[1]);
+}
+
+function wordSet(text) {
+  return new Set(String(text || '').toLowerCase().match(/[a-z0-9]{4,}/g) || []);
+}
+
+function jaccard(a, b) {
+  if (!a.size && !b.size) return null;
+  const inter = [...a].filter(x => b.has(x)).length;
+  const union = new Set([...a, ...b]).size;
+  return union ? inter / union : null;
+}
+
+/**
+ * Per-seat (by `by`, the anonymised or real lab tag on each post)
+ * substance and evidence-share metrics, computed only from a run's own
+ * debate.posts. Returns `null` for a lab with no posts requiring a
+ * quote (support posts don't - DEBATE_SYSTEM only asks for one on
+ * object/merge), rather than a misleading 0.
+ *
+ * substanceRatio: v6 §7 failure mode 1, character-performed-not-
+ * reviewed. Fraction of a seat's object/merge posts that contain at
+ * least one quoted span, since DEBATE_SYSTEM's own instructions
+ * require quoting the phrase being objected to or merged - a seat that
+ * never quotes despite the prompt asking for it is arguing without
+ * engaging the text in front of it, whatever its role.
+ *
+ * evidenceTokenShare: v6 §7 failure mode 4, token spend shifting from
+ * substance to voice. Fraction of a seat's total post-text words that
+ * fall inside a quoted span, across every post regardless of stance.
+ */
+export function perSeatMetrics(posts) {
+  const byLab = new Map();
+  for (const p of posts || []) {
+    if (!p.by) continue;
+    if (!byLab.has(p.by)) byLab.set(p.by, { evidencePosts: 0, quotedPosts: 0, totalWords: 0, quotedWords: 0 });
+    const m = byLab.get(p.by);
+    const text = String(p.text || '');
+    const words = (text.match(/\S+/g) || []).length;
+    m.totalWords += words;
+    const spans = quotedSpans(text);
+    const quotedWords = spans.reduce((s, q) => s + (q.match(/\S+/g) || []).length, 0);
+    m.quotedWords += quotedWords;
+    if (p.stance === 'object' || p.stance === 'merge') {
+      m.evidencePosts += 1;
+      if (spans.length) m.quotedPosts += 1;
+    }
+  }
+  const out = {};
+  for (const [lab, m] of byLab) {
+    out[lab] = {
+      substanceRatio: m.evidencePosts ? m.quotedPosts / m.evidencePosts : null,
+      evidenceTokenShare: m.totalWords ? m.quotedWords / m.totalWords : null,
+    };
+  }
+  return out;
+}
+
+/**
+ * v6 §7 failure mode 2, role-correlation collapse - reconsidered.
+ * Originally specified as a comparison against the phase 4 probe's
+ * plain-arm baseline; that baseline is a deterministic heuristic mock,
+ * not a real model, and cannot speak to real debate diversity. This
+ * instead measures the mean pairwise textual overlap (Jaccard over
+ * 4+ letter words) between different labs' posts on the SAME proposal,
+ * within one real debate stage - a lens meant to diversify argument
+ * that instead makes every seat's objection read the same is a real,
+ * checkable signal computed from what seats actually wrote. Returns
+ * `null` when there are fewer than two comparable posts (nothing to
+ * compare, not evidence of agreement).
+ */
+export function pairwiseAgreement(posts) {
+  const byTarget = new Map();
+  for (const p of posts || []) {
+    if (!p.on || !p.by) continue;
+    if (!byTarget.has(p.on)) byTarget.set(p.on, []);
+    byTarget.get(p.on).push(p);
+  }
+  const scores = [];
+  for (const group of byTarget.values()) {
+    for (let i = 0; i < group.length; i++) {
+      for (let j = i + 1; j < group.length; j++) {
+        if (group[i].by === group[j].by) continue;
+        const score = jaccard(wordSet(group[i].text), wordSet(group[j].text));
+        if (score !== null) scores.push(score);
+      }
+    }
+  }
+  return scores.length ? scores.reduce((a, b) => a + b, 0) / scores.length : null;
+}
+
+/**
+ * v6 §7 failure mode 3, a role degrading a weaker model - reconsidered.
+ * Originally specified as a per-seat catch-rate delta read from the
+ * phase 4 probe; catch rate against planted synthetic defects is not
+ * what this feature is for (see module header). This instead compares,
+ * within the SAME real run, the mean substanceRatio (above) of seats
+ * carrying a role against seats that do not - a same-run, cross-
+ * sectional read, not a longitudinal one (it cannot tell you whether
+ * role-bearing seat X got worse than seat X used to be without a role,
+ * only whether role-bearing seats collectively argued less
+ * substantively than role-less seats in this one run). Returns `null`
+ * when a run has no mix of role-bearing and role-less seats to compare
+ * - a chain where every seat has the same role status has nothing this
+ * detector can say.
+ */
+export function roleVsPlainSubstanceGap(perSeat, roleLabs) {
+  const roleSeats = [];
+  const plainSeats = [];
+  for (const [lab, m] of Object.entries(perSeat)) {
+    if (m.substanceRatio === null) continue;
+    (roleLabs.has(lab) ? roleSeats : plainSeats).push(m.substanceRatio);
+  }
+  if (!roleSeats.length || !plainSeats.length) return null;
+  const mean = xs => xs.reduce((a, b) => a + b, 0) / xs.length;
+  return mean(roleSeats) - mean(plainSeats);
+}
+
+// Placeholder thresholds, author to tighten (v6 Decisions left to the
+// author already names this class of number as open) - not derived
+// from any measurement, only from "clearly bad" being obviously below/
+// above a midpoint.
+const SUBSTANCE_FLOOR = 0.5;
+const EVIDENCE_SHARE_FLOOR = 0.15;
+const AGREEMENT_CEILING = 0.6;
+const SUBSTANCE_GAP_FLOOR = -0.2;
+
+/**
+ * The full diagnostics object for one run's `report.debate`, meant to
+ * be attached at `report.json`'s `debate.diagnostics` per v6 §7. Never
+ * throws on a run with no debate stage or no posts - returns nulls and
+ * empty flags, not an error, matching every other read-only reporting
+ * module in this project.
+ */
+export function computeRoleDiagnostics(debate, roleLabs = new Set()) {
+  const posts = debate?.posts || [];
+  const perSeat = perSeatMetrics(posts);
+  const agreement = pairwiseAgreement(posts);
+  const substanceGap = roleVsPlainSubstanceGap(perSeat, roleLabs);
+
+  const characterPerformedNotReviewed = Object.entries(perSeat)
+    .filter(([, m]) => m.substanceRatio !== null && m.substanceRatio < SUBSTANCE_FLOOR)
+    .map(([lab]) => lab);
+  const tokenShiftToVoice = Object.entries(perSeat)
+    .filter(([, m]) => m.evidenceTokenShare !== null && m.evidenceTokenShare < EVIDENCE_SHARE_FLOOR)
+    .map(([lab]) => lab);
+
+  return {
+    perSeat,
+    pairwiseAgreement: agreement,
+    roleVsPlainSubstanceGap: substanceGap,
+    flags: {
+      characterPerformedNotReviewed,
+      tokenShiftToVoice,
+      roleCorrelationCollapse: agreement !== null && agreement > AGREEMENT_CEILING,
+      roleDegradesOutput: substanceGap !== null && substanceGap < SUBSTANCE_GAP_FLOOR,
+    },
+  };
+}