pincer-workflow 0.7.0 → 1.0.0

package/template/scripts/pincer/generate.cjs

@@ -0,0 +1,373 @@
+'use strict';
+// PINCER blueprint — the generator (docs/engine.md, "Generate"). From the library
+// and harness.json it writes, for every stage that is on, the project copy of the
+// stage folder, a thin command and, per platform, the Codex skill and the Copilot
+// prompt derived from the project copy; for every agent in an active roster, its
+// Claude file (the library copy with the model and effort of its tier) and, with
+// Codex installed, its Codex agent file. Baselines live in .pincer.json when the
+// installer wrote one. A target whose hash matches neither its baseline nor the
+// fresh content was edited by hand: it is kept and the fresh content lands beside
+// it as <file>.new. The model and effort lines of an agent file and a project copy
+// are the generator's; the tier belongs in the agreement.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const util = require('./util.cjs');
+const harness = require('./harness.cjs');
+const models = require('./models.cjs');
+
+const LIBRARY = '.claude/pincer/library';
+const MANIFEST = '.pincer.json';
+const PLATFORMS = harness.PLATFORMS;
+const COPILOT_INPUT = '${input:request:Task brief or arguments (optional)}';
+const KEEP_DIRS = new Set(['.claude', '.agents', '.github', '.codex']);
+const MODEL_FIELDS = ['tier', 'model', 'effort'];
+
+const sha = (data) => crypto.createHash('sha256').update(data).digest('hex');
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+const hashOf = (abs) => (fs.existsSync(abs) ? sha(fs.readFileSync(abs)) : null);
+const MARKER_TEXT = 'Generated by scripts/pincer/cli.cjs generate from ';
+const generatedComment = (source) => `<!-- ${MARKER_TEXT}${source} — edit the project copy, not this file -->`;
+const tomlComment = (source) => `# ${MARKER_TEXT}${source} — edit the agreement and the library, not this file`;
+// Derived files (command, Codex skill, Copilot prompt, Codex agent) carry the marker;
+// without a baseline, one that still does is the generator's to overwrite or remove.
+const DERIVED_PATH = /^(\.claude\/commands\/pincer-[a-z-]+\.md|\.agents\/skills\/pincer-[a-z-]+\/SKILL\.md|\.github\/prompts\/pincer-[a-z-]+\.prompt\.md|\.codex\/agents\/[a-z-]+\.toml)$/;
+const carriesMarker = (abs) => { try { return fs.readFileSync(abs, 'utf8').includes(MARKER_TEXT); } catch { return false; } };
+
+// A baseline key is usable only when it names a file inside the root: no absolute
+// path, no `..` segment, and the resolved path stays under the root.
+function safeRel(root, rel) {
+  if (typeof rel !== 'string' || !rel || path.isAbsolute(rel) || /^[A-Za-z]:/.test(rel)) return false;
+  if (rel.split(/[\\/]/).includes('..')) return false;
+  const base = path.resolve(root);
+  const abs = path.resolve(base, rel);
+  return abs !== base && abs.startsWith(base + path.sep);
+}
+
+// The project's library when it has one, else the kit's own copy next to this file.
+function libraryDir(root, override) {
+  if (override) return path.resolve(root, override);
+  const own = path.join(root, LIBRARY);
+  return fs.existsSync(own) ? own : path.resolve(__dirname, '..', '..', LIBRARY);
+}
+
+// The platforms the installer recorded; all three when there is no usable manifest.
+function manifestPlatforms(root) {
+  const manifest = util.readJson(path.join(root, MANIFEST));
+  const list = manifest && Array.isArray(manifest.platforms) ? manifest.platforms : null;
+  return list && list.length && list.every((p) => PLATFORMS.includes(p)) ? [...new Set(list)] : [...PLATFORMS];
+}
+
+// Every file under dir as sorted posix paths relative to it.
+function listFiles(dir, rel = '') {
+  const abs = path.join(dir, rel);
+  if (!isDir(abs)) return [];
+  const out = [];
+  const entries = fs.readdirSync(abs, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1));
+  for (const entry of entries) {
+    if (entry.name === '.DS_Store') continue;
+    const child = rel ? `${rel}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...listFiles(dir, child));
+    else if (entry.isFile()) out.push(child);
+  }
+  return out;
+}
+
+// key: value lines between the first two --- lines; quotes around a value are dropped.
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+function splitFrontmatter(text) {
+  const match = FRONTMATTER.exec(text);
+  if (!match) return { fields: {}, body: text };
+  const fields = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const kv = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(line);
+    if (!kv) continue;
+    let value = kv[2].trim();
+    const q = value[0];
+    if (value.length >= 2 && (q === '"' || q === "'") && value.endsWith(q)) value = value.slice(1, -1);
+    fields[kv[1]] = value;
+  }
+  return { fields, body: text.slice(match[0].length) };
+}
+const quoted = (value) => JSON.stringify(String(value));
+const bare = (value) => (/^[A-Za-z0-9._-]+$/.test(String(value)) ? String(value) : quoted(value));
+const bodyText = (body) => { const text = body.replace(/^\n+/, ''); return text.endsWith('\n') ? text : `${text}\n`; };
+const describe = (stage, fields) => fields.description || `PINCER ${stage} stage`;
+const skillDir = (stage) => `.claude/skills/pincer-${stage}`;
+const skillFile = (stage) => `${skillDir(stage)}/SKILL.md`;
+const agentPath = (name) => `.claude/agents/${name}.md`;
+const codexAgentPath = (name) => `.codex/agents/${name}.toml`;
+
+// The frontmatter with the `drop` keys removed and the `add` pairs appended before
+// the closing ---; the input unchanged when there is nothing to do.
+function rewriteFrontmatter(text, { drop = [], add = {} } = {}) {
+  const entries = Object.entries(add).filter(([, value]) => typeof value === 'string' && value !== '');
+  const match = FRONTMATTER.exec(text);
+  if (!match) return entries.length ? `---\n${entries.map(([k, v]) => `${k}: ${bare(v)}`).join('\n')}\n---\n${text}` : text;
+  const lines = match[1].split(/\r?\n/);
+  const kept = lines.filter((line) => { const kv = /^([A-Za-z][\w-]*):/.exec(line); return !(kv && drop.includes(kv[1])); });
+  if (kept.length === lines.length && !entries.length) return text;
+  return `---\n${[...kept, ...entries.map(([k, v]) => `${k}: ${bare(v)}`)].join('\n')}\n---\n${text.slice(match[0].length)}`;
+}
+const stripModelFields = (text) => rewriteFrontmatter(String(text), { drop: MODEL_FIELDS });
+// The same file once the model, effort and tier lines are set aside.
+const equalIgnoringModelFields = (a, b) => stripModelFields(a) === stripModelFields(b);
+const given = (value) => (typeof value === 'string' && value !== '' ? value : '');
+
+// The Claude agent file: the library copy with the tier line dropped and the
+// resolved model and effort appended.
+function renderAgent(text, { model, effort } = {}) {
+  const add = {};
+  if (given(model)) add.model = model;
+  if (given(effort)) add.effort = effort;
+  return rewriteFrontmatter(text, { drop: MODEL_FIELDS, add });
+}
+// The Codex agent file: name, description, the model lines and the body as the
+// developer instructions, in TOML.
+function renderCodexAgent(name, text, { model, effort } = {}) {
+  const { fields, body } = splitFrontmatter(text);
+  const content = bodyText(body);
+  if (content.includes("'''")) throw new Error(`agents/${name}.md: the body contains ''' and cannot be a Codex agent`);
+  const lines = [tomlComment(`${LIBRARY}/agents/${name}.md`), `name = ${quoted(fields.name || name)}`, `description = ${quoted(fields.description || '')}`];
+  if (given(model)) lines.push(`model = ${quoted(model)}`);
+  if (given(effort)) lines.push(`model_reasoning_effort = ${quoted(effort)}`);
+  lines.push("developer_instructions = '''", content.replace(/\n$/, ''), "'''");
+  return `${lines.join('\n')}\n`;
+}
+
+// /pincer-x becomes $pincer-x where it is a command mention: at a line start or
+// after a character that cannot be part of a path, so scripts/pincer-status.sh stays.
+const codexMentions = (text) => text.replace(/(^|[^A-Za-z0-9_./])\/pincer-([a-z][a-z-]*)/gm, (_, before, name) => `${before}$pincer-${name}`);
+
+// The model and effort lines a stage's tier adds to a frontmatter.
+const modelLines = ({ model, effort } = {}) => `${given(model) ? `model: ${bare(model)}\n` : ''}${given(effort) ? `effort: ${bare(effort)}\n` : ''}`;
+// The Codex skill has no model field: one line tells the session what was agreed.
+function codexHint({ model, effort, tier } = {}) {
+  if (given(model)) return `Model: this stage was agreed to run on the ${tier} tier (${model}${given(effort) ? `, effort ${effort}` : ''}). If this session runs on another model, say so before starting or restart with \`codex -m ${model}\`.\n\n`;
+  if (given(effort)) return `Effort: this stage was agreed to run at ${effort} effort on the session's model; if this session is set lower, restart with \`codex -c model_reasoning_effort=${effort}\`.\n\n`;
+  return '';
+}
+
+function renderCommand(stage, fields, claude) {
+  const hint = fields['argument-hint'] ? `argument-hint: ${quoted(fields['argument-hint'])}\n` : '';
+  return `---\ndescription: ${quoted(describe(stage, fields))}\n${hint}${modelLines(claude)}---\n${generatedComment(skillFile(stage))}\n\nRead ${skillFile(stage)} and follow it. Arguments: $ARGUMENTS\n`;
+}
+function renderCodex(stage, fields, body, codex) {
+  const optional = !fields['argument-hint'] || /optional/i.test(fields['argument-hint']);
+  const sentence = optional
+    ? `the text that follows the \`$pincer-${stage}\` mention, if any (when omitted, use the skill's documented default)`
+    : `the text that follows the \`$pincer-${stage}\` mention in the user's message (ask only if the required input is missing)`;
+  const text = codexMentions(body.split('$ARGUMENTS').join(sentence));
+  return `---\nname: pincer-${stage}\ndescription: ${quoted(describe(stage, fields))}\n---\n${generatedComment(skillFile(stage))}\n\n${codexHint(codex)}${bodyText(text)}`;
+}
+function renderCopilot(stage, fields, body, copilot) {
+  const text = body.split('$ARGUMENTS').join(COPILOT_INPUT);
+  const model = copilot && given(copilot.model) ? `model: ${quoted(copilot.model)}\n` : '';
+  return `---\nmode: agent\ndescription: ${quoted(describe(stage, fields))}\n${model}---\n${generatedComment(skillFile(stage))}\n\n${bodyText(text)}`;
+}
+// The files derived from a stage's SKILL.md text, keyed by path (every platform).
+// `models` carries the stage's resolved { model, effort, tier } per platform; the
+// derived files take the model from the resolution, never from the copy's frontmatter.
+function derived(stage, skillText, models = {}) {
+  const { fields, body } = splitFrontmatter(skillText);
+  return {
+    [`.claude/commands/pincer-${stage}.md`]: renderCommand(stage, fields, models.claude),
+    [`.agents/skills/pincer-${stage}/SKILL.md`]: renderCodex(stage, fields, body, models.codex),
+    [`.github/prompts/pincer-${stage}.prompt.md`]: renderCopilot(stage, fields, body, models.copilot),
+  };
+}
+function derivedPaths(stage, platforms) {
+  const out = [`.claude/commands/pincer-${stage}.md`];
+  if (platforms.includes('codex')) out.push(`.agents/skills/pincer-${stage}/SKILL.md`);
+  if (platforms.includes('copilot')) out.push(`.github/prompts/pincer-${stage}.prompt.md`);
+  return out;
+}
+// A path belongs to the platforms asked about; others are left alone.
+const inScope = (rel, platforms) => (rel.startsWith('.agents/') || rel.startsWith('.codex/') ? platforms.includes('codex') : rel.startsWith('.github/') ? platforms.includes('copilot') : true);
+
+// The agents named by the rosters of the stages that are on (harness.cjs owns it).
+const activeAgents = harness.activeAgents;
+
+// Every path the generator owns for this agreement and these platforms. With a
+// library the project copies list the whole stage folder, else SKILL.md alone.
+function generatedPaths(doc, platforms = PLATFORMS, { library } = {}) {
+  const h = harness.normalize(doc);
+  const out = [];
+  for (const stage of harness.STAGES) {
+    if (!harness.stageOn(h, stage)) continue;
+    const files = library ? listFiles(path.join(library, 'stages', stage)) : [];
+    for (const file of files.length ? files : ['SKILL.md']) out.push(`${skillDir(stage)}/${file}`);
+    out.push(...derivedPaths(stage, platforms));
+  }
+  for (const name of activeAgents(h)) {
+    out.push(agentPath(name));
+    if (platforms.includes('codex')) out.push(codexAgentPath(name));
+  }
+  return out;
+}
+
+// Remove empty directories upward, never the platform roots or the project root.
+function pruneEmpty(root, dir) {
+  for (;;) {
+    const rel = path.relative(root, dir);
+    if (!rel || rel.startsWith('..') || KEEP_DIRS.has(rel)) return;
+    try { if (fs.readdirSync(dir).length) return; fs.rmdirSync(dir); } catch { return; }
+    dir = path.dirname(dir);
+  }
+}
+
+function generate(root, { harness: doc, platforms = manifestPlatforms(root), library, overwrite = false } = {}) {
+  if (!isObject(doc)) throw new TypeError('generate needs a harness');
+  const h = harness.normalize(doc);
+  const lib = libraryDir(root, library);
+  const manifestFile = path.join(root, MANIFEST);
+  const manifest = util.readJson(manifestFile);
+  const report = { written: [], skipped: [], conflicted: [], retained: [], removed: [], missing: [], unsafe: [] };
+  // Baseline keys that point outside the root are dropped and reported, never acted on.
+  const baseline = {};
+  for (const [rel, hash] of Object.entries(manifest && isObject(manifest.generated) ? manifest.generated : {})) {
+    if (safeRel(root, rel)) baseline[rel] = hash; else report.unsafe.push(rel);
+  }
+  const next = {};
+  const expected = new Set();
+
+  // Models: the library table with the agreement's map over it. A tier the table
+  // cannot translate, or a table that is not there, is reported once per lookup
+  // kind and the model field is left out.
+  const tableRead = models.readTable(lib);
+  const table = tableRead.ok ? models.overlay(tableRead.table, h.models.map) : null;
+  // A table that is there but broken is reported by its fault, never as missing.
+  const tableProblem = !tableRead.ok && !tableRead.missing ? tableRead.problem : null;
+  const eff = models.effective(h, lib);
+  const unresolved = new Set();
+  const resolve = (platform, entry) => {
+    const tier = given(entry && entry.tier), effort = given(entry && entry.effort);
+    let model = null;
+    if (tier && tier !== 'inherit') {
+      if (!table) unresolved.add(tableProblem || models.TABLE_FILE);
+      else {
+        model = models.modelFor(table, platform, tier);
+        if (model === undefined) { unresolved.add(`models/${platform}/${tier}`); model = null; }
+      }
+    }
+    return { model, effort };
+  };
+
+  // Every agent is rendered before anything is written, so a refusal writes nothing.
+  const agents = activeAgents(h);
+  const rendered = [];
+  for (const name of agents) {
+    const src = path.join(lib, 'agents', `${name}.md`);
+    if (!fs.existsSync(src)) { report.missing.push(`agents/${name}`); continue; }
+    const text = fs.readFileSync(src, 'utf8');
+    const item = { name, text, claude: renderAgent(text, resolve('claude', eff.agents[name])) };
+    if (platforms.includes('codex')) item.codex = renderCodexAgent(name, text, resolve('codex', eff.agents[name]));
+    rendered.push(item);
+  }
+
+  // Put fresh content at rel unless the file there was edited by hand; returns the
+  // content now on disk, which the derived files follow. `ours` may widen what
+  // counts as the generator's own, but only where no baseline can tell an edit
+  // from a re-render: with a baseline, a hand-written model line conflicts too.
+  const place = (rel, fresh, { ours: alsoOurs } = {}) => {
+    expected.add(rel);
+    const abs = path.join(root, rel);
+    const buf = Buffer.isBuffer(fresh) ? fresh : Buffer.from(fresh, 'utf8');
+    const freshHash = sha(buf);
+    const current = hashOf(abs);
+    let ours = overwrite || current === freshHash || current === baseline[rel] || (baseline[rel] === undefined && DERIVED_PATH.test(rel) && carriesMarker(abs));
+    if (!ours && current !== null && baseline[rel] === undefined && typeof alsoOurs === 'function') ours = alsoOurs(fs.readFileSync(abs, 'utf8'));
+    if (current !== null && !ours) {
+      const sidecar = `${abs}.new`;
+      if (hashOf(sidecar) !== freshHash) util.atomicWrite(sidecar, buf);
+      report.conflicted.push(rel);
+      if (baseline[rel]) next[rel] = baseline[rel];
+      return fs.readFileSync(abs);
+    }
+    if (current === freshHash) report.skipped.push(rel);
+    else { util.atomicWrite(abs, buf); report.written.push(rel); }
+    next[rel] = freshHash;
+    return buf;
+  };
+
+  for (const stage of harness.STAGES) {
+    if (!harness.stageOn(h, stage)) continue;
+    const src = path.join(lib, 'stages', stage);
+    if (!fs.existsSync(path.join(src, 'SKILL.md'))) { report.missing.push(stage); continue; }
+    const entry = eff.stages[stage];
+    const tiers = Object.fromEntries(PLATFORMS.map((platform) => [platform, { ...resolve(platform, entry), tier: given(entry && entry.tier) }]));
+    let skillText = '';
+    for (const file of listFiles(src)) {
+      const raw = fs.readFileSync(path.join(src, file));
+      if (file !== 'SKILL.md') { place(`${skillDir(stage)}/${file}`, raw); continue; }
+      // The project copy: the library's SKILL.md with the stage's Claude model lines.
+      const libraryText = raw.toString('utf8');
+      const fresh = rewriteFrontmatter(libraryText, { drop: ['model', 'effort'], add: { model: tiers.claude.model || '', effort: tiers.claude.effort } });
+      skillText = place(`${skillDir(stage)}/${file}`, fresh, { ours: (current) => equalIgnoringModelFields(current, libraryText) }).toString('utf8');
+    }
+    const outputs = derived(stage, skillText, tiers);
+    for (const rel of derivedPaths(stage, platforms)) place(rel, outputs[rel]);
+  }
+  for (const item of rendered) {
+    place(agentPath(item.name), item.claude, { ours: (current) => equalIgnoringModelFields(current, item.text) });
+    if (item.codex !== undefined) place(codexAgentPath(item.name), item.codex);
+  }
+  report.missing.push(...[...unresolved].sort());
+
+  // Removals: what an earlier run recorded, or what an off stage or a dropped agent
+  // would own, when it is not expected now and still reads as generated: equal to
+  // its baseline or to the library's copy (an agent file: ignoring its model
+  // lines), or a derived file carrying the marker.
+  const pristine = {};
+  const libraryText = {};
+  const candidates = new Set();
+  for (const rel of Object.keys(baseline)) { if (inScope(rel, platforms)) candidates.add(rel); else next[rel] = baseline[rel]; }
+  for (const stage of harness.STAGES) {
+    if (harness.stageOn(h, stage)) continue;
+    const src = path.join(lib, 'stages', stage);
+    for (const file of listFiles(src)) {
+      const raw = fs.readFileSync(path.join(src, file));
+      pristine[`${skillDir(stage)}/${file}`] = sha(raw);
+      if (file === 'SKILL.md') libraryText[skillFile(stage)] = raw.toString('utf8');
+    }
+    for (const file of listFiles(path.join(root, skillDir(stage)))) if (!file.endsWith('.new')) candidates.add(`${skillDir(stage)}/${file}`);
+    for (const rel of derivedPaths(stage, platforms)) candidates.add(rel);
+  }
+  for (const name of harness.AGENT_NAMES) {
+    if (agents.includes(name)) continue;
+    const src = path.join(lib, 'agents', `${name}.md`);
+    if (fs.existsSync(src)) libraryText[agentPath(name)] = fs.readFileSync(src, 'utf8');
+    candidates.add(agentPath(name));
+    if (platforms.includes('codex')) candidates.add(codexAgentPath(name));
+  }
+  for (const rel of [...candidates].sort()) {
+    if (expected.has(rel)) continue;
+    const abs = path.join(root, rel);
+    const current = hashOf(abs);
+    if (current === null) continue;
+    const generated = overwrite || current === baseline[rel] || current === pristine[rel]
+      || (baseline[rel] === undefined && DERIVED_PATH.test(rel) && carriesMarker(abs))
+      || (baseline[rel] === undefined && libraryText[rel] !== undefined && equalIgnoringModelFields(fs.readFileSync(abs, 'utf8'), libraryText[rel]));
+    if (generated) {
+      fs.unlinkSync(abs);
+      report.removed.push(rel);
+      pruneEmpty(root, path.dirname(abs));
+    } else {
+      // Edited or user-added: kept where it is, reported without a sidecar.
+      report.retained.push(rel);
+      if (baseline[rel]) next[rel] = baseline[rel];
+    }
+  }
+
+  if (isObject(manifest)) {
+    manifest.generated = Object.fromEntries(Object.keys(next).sort().map((rel) => [rel, next[rel]]));
+    util.atomicWrite(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`);
+  }
+  return report;
+}
+
+module.exports = {
+  LIBRARY, MANIFEST, PLATFORMS, MARKER_TEXT, generate, generatedPaths, manifestPlatforms, libraryDir, splitFrontmatter, codexMentions, activeAgents, safeRel,
+  rewriteFrontmatter, renderAgent, renderCodexAgent, equalIgnoringModelFields, codexAgentPath,
+};

package/template/scripts/pincer/harness.cjs

@@ -0,0 +1,269 @@
+'use strict';
+// PINCER engine — harness.json, the machine-readable agreement every stage
+// reads (docs/engine.md, "harness.json"). Schema 1. Dependency-free.
+const fs = require('node:fs');
+const path = require('node:path');
+const { stripUserinfo } = require('./util.cjs');
+
+const HARNESS_FILE = 'harness.json';
+const STAGES = ['blueprint', 'plan', 'narrow', 'code', 'evaluate', 'release', 'status'];
+const ALWAYS_ON = ['blueprint', 'status'];
+const OPTIONAL_STAGES = STAGES.filter((name) => !ALWAYS_ON.includes(name));
+const ROSTER_STAGES = ['plan', 'narrow', 'code', 'evaluate'];
+const AGENT_NAMES = [
+  'codebase-explorer', 'implementer', 'code-quality-reviewer', 'silent-failure-hunter', 'security-reviewer',
+  'test-coverage-reviewer', 'history-reviewer', 'standards-reviewer', 'accessibility-reviewer', 'fix-agent',
+];
+const KINDS = ['greenfield', 'brownfield'];
+const MISSING_MESSAGE = 'no agreement yet: run /pincer-blueprint';
+// Model tiers: what the agreement says about which model a role runs on. The
+// empty string is "not set" (the library's default, else inherit).
+const TIERS = ['strong', 'standard', 'fast', 'inherit'];
+const MAP_TIERS = ['strong', 'standard', 'fast'];
+const EFFORTS = ['low', 'medium', 'high'];
+const PLATFORMS = ['claude', 'codex', 'copilot'];
+const MODEL_ENTRY = { tier: '', effort: '' };
+
+const DEFAULT_STAGES = {
+  plan: { on: true, spec: 'file', gate: '' },
+  narrow: { on: true, tickets: 'file' },
+  code: { on: true, implementer: false },
+  evaluate: { on: true, where: 'local', evidence: true },
+  release: { on: true, audit: 'tree' },
+};
+const DEFAULTS = {
+  project: { name: '', reason: '' },
+  person: { name: '', role: '', accepts: false },
+  systems: { forge: 'none', remote: '', ci: false, deploy: '', secrets: '' },
+  repo: { branches: 'main', pr: false, merge: 'merge', protection: '', checks: [] },
+  homes: { specs: 'specs', tickets: 'tickets', evidence: 'evidence' },
+  models: { stages: {}, agents: {}, map: {} },
+};
+// Allowed values per field; a field not listed here is a string.
+const RULES = {
+  'systems.forge': ['github', 'none', 'other'],
+  'systems.ci': 'boolean',
+  'repo.branches': ['per-ticket', 'main'],
+  'repo.pr': 'boolean',
+  'repo.merge': ['merge', 'squash', 'rebase'],
+  'repo.checks': 'strings',
+  'stages.plan.spec': ['file', 'forge'],
+  'stages.narrow.tickets': ['file', 'forge'],
+  'stages.code.implementer': 'boolean',
+  'stages.evaluate.where': ['local', 'pr'],
+  'stages.evaluate.evidence': 'boolean',
+  'stages.release.audit': ['tree', 'pr'],
+};
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const obj = (value) => (isObject(value) ? value : {});
+const trimSlash = (value) => (typeof value === 'string' ? value.replace(/\/+$/, '') : value);
+
+function check(problems, label, value) {
+  const rule = RULES[label] || 'string';
+  if (Array.isArray(rule)) { if (!rule.includes(value)) problems.push(`${label} must be ${rule.join(' or ')}`); }
+  else if (rule === 'boolean') { if (typeof value !== 'boolean') problems.push(`${label} must be true or false`); }
+  else if (rule === 'strings') { if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) problems.push(`${label} must be a list of strings`); }
+  else if (typeof value !== 'string') problems.push(`${label} must be a string`);
+}
+function checkSection(problems, doc, section, defaults) {
+  if (doc[section] === undefined) return;
+  if (!isObject(doc[section])) { problems.push(`${section} must be an object`); return; }
+  for (const [key, value] of Object.entries(doc[section])) if (key in defaults) check(problems, `${section}.${key}`, value);
+}
+function homeProblem(value) {
+  if (typeof value !== 'string' || !value.trim()) return 'must be a relative path';
+  if (value.startsWith('/') || /^[A-Za-z]:/.test(value) || value.split(/[\\/]/).includes('..')) return 'must be a relative path inside the repository (no leading / or ..)';
+  return null;
+}
+
+// models.stages.<name> and models.agents.<name>: a tier word or { tier, effort }.
+function checkModelEntry(problems, label, value) {
+  const tierProblem = `${label}.tier must be strong, standard, fast or inherit`;
+  if (typeof value === 'string') { if (value !== '' && !TIERS.includes(value)) problems.push(tierProblem); return; }
+  if (!isObject(value)) { problems.push(`${label} must be a tier or an object`); return; }
+  if ('tier' in value && (typeof value.tier !== 'string' || (value.tier !== '' && !TIERS.includes(value.tier)))) problems.push(tierProblem);
+  if ('effort' in value && (typeof value.effort !== 'string' || (value.effort !== '' && !EFFORTS.includes(value.effort)))) problems.push(`${label}.effort must be low, medium or high`);
+}
+function checkModels(problems, doc) {
+  if (doc.models === undefined) return;
+  if (!isObject(doc.models)) { problems.push('models must be an object'); return; }
+  const { stages, agents, map } = doc.models;
+  if (stages !== undefined) {
+    if (!isObject(stages)) problems.push('models.stages must be an object');
+    else {
+      for (const [name, value] of Object.entries(stages)) {
+        if (ALWAYS_ON.includes(name)) { problems.push(`models.stages.${name}: ${name} is always on and runs on the session's model`); continue; }
+        if (!OPTIONAL_STAGES.includes(name)) { problems.push(`models.stages.${name} is not a stage (stages: ${OPTIONAL_STAGES.join(', ')})`); continue; }
+        checkModelEntry(problems, `models.stages.${name}`, value);
+      }
+    }
+  }
+  if (agents !== undefined) {
+    if (!isObject(agents)) problems.push('models.agents must be an object');
+    else {
+      for (const [name, value] of Object.entries(agents)) {
+        if (!AGENT_NAMES.includes(name)) { problems.push(`models.agents.${name}: unknown agent (agents: ${AGENT_NAMES.join(', ')})`); continue; }
+        checkModelEntry(problems, `models.agents.${name}`, value);
+      }
+    }
+  }
+  if (map !== undefined) {
+    if (!isObject(map)) problems.push('models.map must be an object');
+    else {
+      for (const [platform, row] of Object.entries(map)) {
+        if (!PLATFORMS.includes(platform)) { problems.push(`models.map.${platform} is not a platform (${PLATFORMS.join(', ')})`); continue; }
+        if (!isObject(row)) { problems.push(`models.map.${platform} must be an object`); continue; }
+        for (const [tier, value] of Object.entries(row)) {
+          if (!MAP_TIERS.includes(tier)) { problems.push(`models.map.${platform}.${tier} is not a tier (${MAP_TIERS.join(', ')})`); continue; }
+          if (typeof value !== 'string' || !value.trim()) problems.push(`models.map.${platform}.${tier} must be a non-empty string`);
+        }
+      }
+    }
+  }
+}
+
+// Every problem with the document, in reading order; [] when it is valid.
+function validate(doc) {
+  if (!isObject(doc)) return ['must be a JSON object'];
+  const problems = [];
+  if (doc.schema !== 1) problems.push('schema must be 1');
+  const project = obj(doc.project);
+  if (!KINDS.includes(project.kind)) problems.push(`project.kind must be ${KINDS.join(' or ')}`);
+  for (const key of ['name', 'reason']) if (key in project) check(problems, `project.${key}`, project[key]);
+  if (!Array.isArray(doc.people)) problems.push('people must be a list');
+  else {
+    doc.people.forEach((person, i) => {
+      if (!isObject(person) || typeof person.name !== 'string' || !person.name.trim()) problems.push(`people[${i}] needs a name`);
+      if (isObject(person) && 'accepts' in person && typeof person.accepts !== 'boolean') problems.push(`people[${i}].accepts must be true or false`);
+    });
+    if (!doc.people.some((person) => isObject(person) && person.accepts === true)) problems.push('people must include at least one person with accepts: true (who accepts the result)');
+  }
+  checkSection(problems, doc, 'systems', DEFAULTS.systems);
+  checkSection(problems, doc, 'repo', DEFAULTS.repo);
+  if (doc.homes !== undefined) {
+    if (!isObject(doc.homes)) problems.push('homes must be an object');
+    else for (const [key, value] of Object.entries(doc.homes)) { const p = homeProblem(value); if (p) problems.push(`homes.${key} ${p}`); }
+  }
+  if (doc.stages !== undefined) {
+    if (!isObject(doc.stages)) problems.push('stages must be an object');
+    else {
+      for (const [name, stage] of Object.entries(doc.stages)) {
+        if (ALWAYS_ON.includes(name)) { problems.push(`stages.${name}: ${name} is always on; remove the entry`); continue; }
+        if (!OPTIONAL_STAGES.includes(name)) { problems.push(`stages.${name} is not a stage (stages: ${OPTIONAL_STAGES.join(', ')})`); continue; }
+        if (!isObject(stage)) { problems.push(`stages.${name} must be an object`); continue; }
+        if ('on' in stage && typeof stage.on !== 'boolean') problems.push(`stages.${name}.on must be true or false`);
+        if ('reason' in stage) check(problems, `stages.${name}.reason`, stage.reason);
+        for (const key of Object.keys(DEFAULT_STAGES[name])) if (key !== 'on' && key in stage) check(problems, `stages.${name}.${key}`, stage[key]);
+      }
+    }
+  }
+  if (doc.roster !== undefined) {
+    if (!isObject(doc.roster)) problems.push('roster must be an object');
+    else {
+      for (const [stage, list] of Object.entries(doc.roster)) {
+        if (!ROSTER_STAGES.includes(stage)) { problems.push(`roster.${stage} is not a stage with a roster (${ROSTER_STAGES.join(', ')})`); continue; }
+        if (!Array.isArray(list)) { problems.push(`roster.${stage} must be a list of agent names`); continue; }
+        for (const name of list) if (!AGENT_NAMES.includes(name)) problems.push(`roster.${stage}: unknown agent ${JSON.stringify(name)} (agents: ${AGENT_NAMES.join(', ')})`);
+      }
+    }
+  }
+  checkModels(problems, doc);
+  if (doc.open !== undefined && (!Array.isArray(doc.open) || doc.open.some((item) => typeof item !== 'string'))) problems.push('open must be a list of strings');
+  if (doc.firstJob !== undefined) check(problems, 'firstJob', doc.firstJob);
+  return problems;
+}
+
+// A copy with every default filled. Unknown keys are kept; the always-on
+// stages never appear under `stages`. Does not validate.
+function normalize(doc) {
+  const src = obj(doc);
+  const out = { ...src };
+  out.schema = src.schema === undefined ? 1 : src.schema;
+  out.project = { ...DEFAULTS.project, ...obj(src.project) };
+  out.people = (Array.isArray(src.people) ? src.people : []).map((person) => ({ ...DEFAULTS.person, ...obj(person) }));
+  out.systems = { ...DEFAULTS.systems, ...obj(src.systems) };
+  out.systems.remote = stripUserinfo(out.systems.remote); // never carry credentials into the agreement
+  out.repo = { ...DEFAULTS.repo, ...obj(src.repo) };
+  out.repo.checks = Array.isArray(out.repo.checks) ? [...out.repo.checks] : [];
+  out.homes = Object.fromEntries(Object.entries({ ...DEFAULTS.homes, ...obj(src.homes) }).map(([key, value]) => [key, trimSlash(value)]));
+  const stages = obj(src.stages);
+  out.stages = {};
+  for (const name of OPTIONAL_STAGES) out.stages[name] = { ...DEFAULT_STAGES[name], ...obj(stages[name]) };
+  for (const [name, stage] of Object.entries(stages)) if (!(name in out.stages)) out.stages[name] = stage;
+  const roster = obj(src.roster);
+  out.roster = {};
+  for (const stage of ROSTER_STAGES) out.roster[stage] = Array.isArray(roster[stage]) ? [...roster[stage]] : [];
+  for (const [stage, list] of Object.entries(roster)) if (!(stage in out.roster)) out.roster[stage] = list;
+  const models = obj(src.models);
+  const modelEntry = (value) => (typeof value === 'string' ? { tier: value, effort: '' } : { ...MODEL_ENTRY, ...obj(value) });
+  const mStages = obj(models.stages), mAgents = obj(models.agents);
+  out.models = { stages: {}, agents: {}, map: {} };
+  for (const name of OPTIONAL_STAGES) out.models.stages[name] = modelEntry(mStages[name]);
+  for (const [name, value] of Object.entries(mStages)) if (!(name in out.models.stages)) out.models.stages[name] = value;
+  for (const name of AGENT_NAMES) out.models.agents[name] = modelEntry(mAgents[name]);
+  for (const [name, value] of Object.entries(mAgents)) if (!(name in out.models.agents)) out.models.agents[name] = value;
+  for (const [platform, row] of Object.entries(obj(models.map))) out.models.map[platform] = isObject(row) ? { ...row } : row;
+  out.open = Array.isArray(src.open) ? [...src.open] : [];
+  out.firstJob = typeof src.firstJob === 'string' ? src.firstJob : '';
+  return out;
+}
+
+// Read, parse, validate and normalize <root>/harness.json (or another file).
+function load(root, file = path.join(root, HARNESS_FILE)) {
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); } catch (error) {
+    if (error.code === 'ENOENT') return { ok: false, missing: true, message: MISSING_MESSAGE };
+    return { ok: false, problems: [error.message], message: error.message };
+  }
+  let doc;
+  try { doc = JSON.parse(raw); } catch (error) {
+    const problem = `invalid JSON (${error.message})`;
+    return { ok: false, problems: [problem], message: problem };
+  }
+  const problems = validate(doc);
+  if (problems.length) return { ok: false, problems, message: problems.join('; ') };
+  return { ok: true, harness: normalize(doc), file };
+}
+
+// True when the stage runs: the always-on two, and every other stage unless
+// the agreement switched it off. Unknown names are off.
+function stageOn(harness, name) {
+  if (ALWAYS_ON.includes(name)) return true;
+  if (!OPTIONAL_STAGES.includes(name)) return false;
+  const stage = obj(obj(harness).stages)[name];
+  return isObject(stage) ? stage.on !== false : true;
+}
+// Where specs, tickets and evidence live, relative to the root, defaults filled.
+function homes(harness) {
+  return Object.fromEntries(Object.entries({ ...DEFAULTS.homes, ...obj(obj(harness).homes) }).map(([key, value]) => [key, trimSlash(value)]));
+}
+// The names in the rosters of the stages that are on, sorted and unique.
+function activeAgents(harness) {
+  const h = obj(harness);
+  const names = new Set();
+  for (const stage of ROSTER_STAGES) {
+    if (!stageOn(h, stage)) continue;
+    const list = obj(h.roster)[stage];
+    if (Array.isArray(list)) for (const name of list) if (typeof name === 'string') names.add(name);
+  }
+  return [...names].sort();
+}
+// The names of the people who accept results.
+function acceptors(harness) {
+  const people = obj(harness).people;
+  return (Array.isArray(people) ? people : [])
+    .filter((person) => isObject(person) && person.accepts === true && typeof person.name === 'string' && person.name.trim())
+    .map((person) => person.name.trim());
+}
+// The entry points' convention for a load failure: one line, exit 3.
+function die(message, exit = 3) {
+  process.stderr.write(`${HARNESS_FILE}: ${message}\n`);
+  process.exit(exit);
+}
+
+module.exports = {
+  HARNESS_FILE, STAGES, ALWAYS_ON, OPTIONAL_STAGES, ROSTER_STAGES, AGENT_NAMES, KINDS, DEFAULT_STAGES, DEFAULTS, MISSING_MESSAGE,
+  TIERS, MAP_TIERS, EFFORTS, PLATFORMS,
+  load, validate, normalize, stageOn, homes, acceptors, activeAgents, die,
+};