pincer-workflow 0.4.1 → 0.6.0

package/template/scripts/pincer-runtime/fsutil.cjs

@@ -0,0 +1,37 @@
+'use strict';
+// Small filesystem helpers shared by the runtime modules.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+
+const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+// Write via a temporary file in the same directory (or the journal directory on
+// the same filesystem) and rename into place, so a reader never sees a partial
+// file and a crash leaves either the old file or the new one.
+function atomicWrite(file, content, { journalDir } = {}) {
+  const dir = journalDir || path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = path.join(dir, `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`);
+  fs.writeFileSync(temp, content);
+  fs.renameSync(temp, file);
+}
+
+function readJson(file) {
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); } catch (error) { return { error: error.code === 'ENOENT' ? 'missing' : error.message }; }
+  try { return { data: JSON.parse(raw) }; } catch (error) { return { error: `malformed JSON (${error.message})` }; }
+}
+
+function git(root, args, options = {}) {
+  return execFileSync('git', ['-C', root, '-c', 'core.quotePath=false', ...args], {
+    encoding: options.buffer ? 'buffer' : 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 256 * 1024 * 1024, ...options,
+  });
+}
+function tryGit(root, args, options) {
+  try { return { out: git(root, args, options) }; } catch (error) { return { error: (error.stderr && error.stderr.toString().trim()) || error.message }; }
+}
+
+module.exports = { nowIso, atomicWrite, readJson, git, tryGit };

package/template/scripts/pincer-runtime/gates.cjs

@@ -0,0 +1,73 @@
+'use strict';
+// PINCER runtime — command gates (docs/runtime-contracts.md, "Command gates").
+// In changes mode every execution or lifecycle-writing command passes this one
+// guard before a child process is spawned or a ticket file written: the
+// records must be readable, a change must be selected and own the ticket (or
+// PRD), its lifecycle state must permit the command, the repository view must
+// be compatible, and the authorization verdict must be `current`. Refusals carry
+// the contracted code, in the contracted order, and nothing has been written.
+const changes = require('./changes.cjs');
+const agreement = require('./agreement.cjs');
+const authorization = require('./authorization.cjs');
+const { refuse } = require('./transaction.cjs');
+
+// Lifecycle states that permit each command.
+const PERMITTED = {
+  start: ['active'], done: ['active'], verify: ['active', 'completed'],
+  check: ['completed'], export: ['completed'],
+};
+const ORDER = ['INPUT_INVALID', 'INVENTORY_INVALID', 'COVERAGE_INVALID', 'MALFORMED', 'UNSUPPORTED_SCHEMA', 'HISTORY_INVALID', 'STATE_INCOMPLETE', 'SELECTION_REQUIRED', 'SELECTION_INVALID', 'WRONG_CHANGE', 'LIFECYCLE_BLOCKED', 'BASE_MISMATCH', 'DECISION_REQUIRED', 'AUTHORIZATION_REQUIRED', 'AGREEMENT_CHANGED'];
+
+// guard(root, { command, ticket: { file, fields } | null, prd: string | null })
+// Returns { id, record, file, selection, view, computed, verdict, binding } where
+// `binding` is the context every attempt, readiness and export consumes:
+// { change, prd, prd_revision, base, agreement, legacy_receipts, mode: 'changes' }.
+// Throws a transaction Refusal on the first failing gate.
+function guard(root, { command, ticket = null, prd = null }) {
+  const resolved = changes.resolveSelected(root, {});
+  if (resolved.code) {
+    const hint = resolved.code === 'SELECTION_REQUIRED' || resolved.code === 'SELECTION_INVALID' ? ` (execution needs the selected change; ${resolved.problem})` : `: ${resolved.problem}`;
+    refuse(resolved.code, `${command} refused${hint}`);
+  }
+  const { id, record, file, selection, loaded } = resolved;
+  // Ownership: the ticket's PRD, or the named PRD, must belong to the selected change.
+  let owner = null;
+  if (ticket) {
+    const o = changes.ticketOwner(root, loaded, ticket.file, ticket.fields);
+    if (o.problem) refuse(o.id ? 'WRONG_CHANGE' : 'INPUT_INVALID', `${command} refused: ${o.problem}`);
+    owner = o;
+  } else if (prd) {
+    const o = changes.ownerOf(loaded, prd);
+    if (!o) refuse('INPUT_INVALID', `${command} refused: ${prd} is owned by no change record; register it first`);
+    owner = { id: o[0], prd };
+  }
+  if (owner && owner.id !== id) refuse('WRONG_CHANGE', `${command} refused: ${ticket ? `${ticket.fields.ticket} (${owner.prd})` : owner.prd} belongs to change ${owner.id}, but ${id} is selected; select it first: node scripts/pincer-runtime.cjs change select ${owner.id}`);
+  const st = record.lifecycle.state;
+  if (!PERMITTED[command].includes(st)) {
+    const next = changes.TERMINAL.includes(st) ? `the change is ${st}${record.lifecycle.superseded_by ? ` by ${record.lifecycle.superseded_by}` : ''}; register a new change and reference this one`
+      : st === 'planned' ? `activate it first: node scripts/pincer-runtime.cjs change activate ${id}`
+        : st === 'paused' ? `resume it first: node scripts/pincer-runtime.cjs change resume ${id}${record.lifecycle.reason ? ` (paused: ${record.lifecycle.reason})` : ''}`
+          : st === 'completed' ? `${command} needs an active change; reopen it first: node scripts/pincer-runtime.cjs change reopen ${id} --reason <text>`
+            : `${command} needs a completed change; complete it first: node scripts/pincer-runtime.cjs change complete ${id}`;
+    refuse('LIFECYCLE_BLOCKED', `${command} refused: change ${id} is ${st} (${command} runs on ${PERMITTED[command].join(' or ')} changes); ${next}`);
+  }
+  const view = changes.view(root, record);
+  if (view.problems.length) refuse('BASE_MISMATCH', `${command} refused: ${view.problems[0].detail}`);
+  const computed = agreement.compute(root, record);
+  if (computed.code) refuse(computed.code, `${command} refused: ${computed.problem}`);
+  const verdict = authorization.verdict(root, record, computed);
+  if (verdict.verdict !== 'current') refuse(verdict.verdict, `${command} refused: ${verdict.detail}`);
+  // A strict change's binding carries its inventory and coverage map digests (attempt schema 3).
+  const binding = { change: id, prd: record.prd, prd_revision: computed.prd.revision, base: record.base, agreement: computed.digest, legacy_receipts: record.legacy.receipts, mode: 'changes', strict: Boolean(computed.inventory), ...(computed.inventory ? { inventory: computed.inventory.digest, coverage: computed.coverage.digest } : {}) };
+  return { id, record, file, selection, view, computed, verdict, binding, loaded };
+}
+
+// The read-only counterpart for status/ready: the same checks as reasons, none thrown.
+function reasons(root, { command, ticket = null, prd = null }) {
+  try { guard(root, { command, ticket, prd }); return []; } catch (error) {
+    if (error && error.refusal) return [{ code: error.code, detail: error.message }];
+    throw error;
+  }
+}
+
+module.exports = { guard, reasons, PERMITTED, ORDER };

package/template/scripts/pincer-runtime/identity.cjs

@@ -0,0 +1,163 @@
+'use strict';
+// PINCER runtime — change identity (docs/runtime-contracts.md, "Change binding").
+// A change binding under .prd/changes/<id>.json ties runtime verification to one
+// explicitly selected PRD and its content revision. Written only here and by
+// migration; never inferred from the highest PRD number.
+const fs = require('node:fs');
+const path = require('node:path');
+const parse = require('./parse.cjs');
+const { nowIso, atomicWrite, readJson, tryGit } = require('./fsutil.cjs');
+
+const CHANGE_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const RUNTIME = 1;
+const BINDING_KEYS = ['schema', 'change', 'prd', 'prd_revision', 'base', 'registered', 'authorization', 'runtime', 'legacy_receipts'];
+
+const bindingsDir = root => path.join(root, '.prd', 'changes');
+const CHANGES_HINT = 'this project keeps change records (schema 2) under .prd/changes/; inspect them with: node scripts/pincer-runtime.cjs change list';
+function listBindings(root) {
+  const dir = bindingsDir(root);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter(name => name.endsWith('.json')).sort().map(name => `.prd/changes/${name}`);
+}
+
+function validateBinding(doc) {
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return 'binding must be a JSON object';
+  if (doc.schema !== 1) return `unsupported binding schema ${JSON.stringify(doc.schema)} (this runtime reads schema 1)`;
+  for (const key of Object.keys(doc)) if (!BINDING_KEYS.includes(key)) return `unknown binding key "${key}"`;
+  for (const key of BINDING_KEYS) if (!(key in doc)) return `missing binding key "${key}"`;
+  if (typeof doc.change !== 'string' || !CHANGE_ID.test(doc.change)) return 'change must match [a-z0-9][a-z0-9-]{0,63}';
+  if (typeof doc.prd !== 'string' || !parse.PRD_REF.test(doc.prd)) return 'prd must be of the form .prd/prd-vN.md';
+  if (typeof doc.prd_revision !== 'string' || !SHA256.test(doc.prd_revision)) return 'prd_revision must be a 64-hex SHA-256 digest';
+  if (typeof doc.base !== 'string' || !parse.HEX40.test(doc.base)) return 'base must be a full 40-hex commit ID';
+  if (typeof doc.registered !== 'string' || !parse.TIMESTAMP.test(doc.registered)) return 'registered must be an ISO UTC timestamp';
+  if (doc.authorization !== null && (typeof doc.authorization !== 'string' || doc.authorization.length > 2000)) return 'authorization must be null or a short string';
+  if (doc.runtime !== RUNTIME) return `unsupported runtime contract ${JSON.stringify(doc.runtime)}`;
+  if (!doc.legacy_receipts || typeof doc.legacy_receipts !== 'object' || Array.isArray(doc.legacy_receipts)) return 'legacy_receipts must be an object';
+  return null;
+}
+
+// Resolve the binding for this worktree. Returns { binding, file, prd } or
+// { code, problem } with the contracted codes; `prd`, when given, is the PRD the
+// caller needs — a binding for another PRD is CHANGE_REQUIRED with `other` set so
+// callers can treat that PRD as legacy.
+function loadBinding(root, { prd } = {}) {
+  // Mode first (docs/runtime-contracts.md, "Modes"): schema 2 records are the
+  // changes mode and never fall back to a binding or to legacy; mixed or
+  // unreadable directories are invalid.
+  const scan = require('./changes.cjs').scan(root);
+  if (scan.mode === 'changes') return { code: 'CHANGES_MODE', problem: `${CHANGES_HINT}`, scan };
+  if (scan.mode === 'invalid') return { code: scan.problems[0].code, problem: scan.problems[0].detail, scan };
+  // A committed transaction that was not fully applied is unsafe in every mode, not
+  // only in changes mode: `recover` finishes it by renaming its staged files into
+  // place, over anything written since. Changes mode raises this through
+  // changes.scan(); a migrated or legacy project reaches it here, and a migrated
+  // project is the one `migrate --apply` crashes in.
+  const pending = require('./transaction.cjs').pending(root);
+  if (pending.committed.length) {
+    const first = pending.committed[0];
+    return { code: 'STATE_INCOMPLETE', problem: `a committed transaction (${first.command || first.id}) was not fully applied; run: node scripts/pincer-runtime.cjs recover` };
+  }
+  const files = listBindings(root);
+  if (files.length === 0) {
+    const hint = prd ? `register it with: node scripts/pincer-runtime.cjs register --prd ${prd}` : 'run register or migrate';
+    return { code: 'CHANGE_REQUIRED', problem: `no change binding under .prd/changes/ — ${hint}` };
+  }
+  if (files.length > 1) return { code: 'AMBIGUOUS', problem: `several change bindings under .prd/changes/ (${files.map(f => path.basename(f)).join(', ')}) — keep exactly one` };
+  const file = files[0];
+  const read = readJson(path.join(root, file));
+  if (read.error) return { code: 'MALFORMED', problem: `${file}: ${read.error}`, file };
+  const invalid = validateBinding(read.data);
+  if (invalid) return { code: /schema|runtime contract/.test(invalid) ? 'UNSUPPORTED_SCHEMA' : 'MALFORMED', problem: `${file}: ${invalid}`, file };
+  const binding = read.data;
+  if (path.basename(file, '.json') !== binding.change) return { code: 'MALFORMED', problem: `${file}: filename does not match change "${binding.change}"`, file };
+  if (prd && binding.prd !== prd) return { code: 'CHANGE_REQUIRED', other: true, binding, file, problem: `${file} binds ${binding.prd}, not ${prd}` };
+  const prdResult = parse.validatePrd(root, binding.prd);
+  if (!prdResult.ok) return { code: 'INPUT_INVALID', problem: `${binding.prd}: ${prdResult.problems[0]}`, binding, file };
+  const revision = parse.prdDigest(prdResult.text);
+  if (revision !== binding.prd_revision) {
+    return { code: 'REVISION_CHANGED', binding, file, revision, problem: `${binding.prd} content changed since registration (revision ${binding.prd_revision.slice(0, 12)} → ${revision.slice(0, 12)}) — rebind explicitly with: node scripts/pincer-runtime.cjs register --prd ${binding.prd} --rebind` };
+  }
+  return { binding, file, prd: prdResult };
+}
+
+function head(root) {
+  const result = tryGit(root, ['rev-parse', '--verify', 'HEAD^{commit}']);
+  if (result.error || !parse.HEX40.test(result.out.trim())) return null;
+  return result.out.trim();
+}
+
+const IGNORE_LINE = '.pincer/';
+function gitignoreHas(root) {
+  const file = path.join(root, '.gitignore');
+  if (!fs.existsSync(file)) return false;
+  return fs.readFileSync(file, 'utf8').split('\n').map(l => l.trim()).some(l => l === IGNORE_LINE || l === '/.pincer/' || l === '.pincer');
+}
+// Local runtime state must never become an untracked change: registration and
+// migration both make sure .pincer/ is ignored before the binding is written.
+function ensureIgnored(root) {
+  if (gitignoreHas(root)) return false;
+  const file = path.join(root, '.gitignore');
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const lead = existing && !existing.endsWith('\n') ? '\n' : '';
+  fs.appendFileSync(file, `${lead}${existing ? '\n' : ''}# pincer runtime state (added by the runtime)\n${IGNORE_LINE}\n`);
+  return true;
+}
+
+function writeBinding(root, binding) {
+  ensureIgnored(root);
+  const file = path.join(bindingsDir(root), `${binding.change}.json`);
+  atomicWrite(file, `${JSON.stringify(binding, null, 2)}\n`);
+  return `.prd/changes/${binding.change}.json`;
+}
+
+// Register (or rebind / replace) the selected PRD. Returns { binding, file,
+// action: 'registered' | 'unchanged' | 'updated' | 'rebound' | 'replaced', notes }
+// or { code, problem }.
+function register(root, { prd, change, authorization = null, replace = false, rebind = false } = {}) {
+  const prdResult = parse.validatePrd(root, prd);
+  if (!prdResult.ok) return { code: 'INPUT_INVALID', problem: `${prdResult.file || prd}: ${prdResult.problems[0]}` };
+  const version = prd.match(parse.PRD_REF)[1];
+  const id = change || `prd-v${version}`;
+  if (!CHANGE_ID.test(id)) return { code: 'INPUT_INVALID', problem: `change ID must match [a-z0-9][a-z0-9-]{0,63}: ${id}` };
+  const base = head(root);
+  if (!base) return { code: 'UNSUPPORTED_INPUT', problem: 'registration needs a git repository with at least one commit (base = HEAD)' };
+  const revision = parse.prdDigest(prdResult.text);
+  const notes = [];
+  if (authorization === null) notes.push('no --authorization recorded; running registration does not prove human approval');
+  const files = listBindings(root);
+  if (files.length > 1) return { code: 'AMBIGUOUS', problem: `several change bindings under .prd/changes/ (${files.map(f => path.basename(f)).join(', ')}) — keep exactly one before registering` };
+  let existing = null;
+  if (files.length === 1) {
+    const read = readJson(path.join(root, files[0]));
+    const invalid = read.error || validateBinding(read.data);
+    if (invalid) return { code: 'MALFORMED', problem: `${files[0]}: ${invalid} — repair or remove it before registering` };
+    existing = { file: files[0], binding: read.data };
+  }
+  // v0.5.0 replaced the binding here (deleting the other PRD's); several changes
+  // are retained only by schema 2 records, so a second PRD needs the migration.
+  if (replace) return { code: 'MIGRATION_REQUIRED', problem: `--replace would delete ${existing ? existing.file : 'the binding'}; change records are retained instead — migrate first: node scripts/pincer-runtime.cjs migrate --preview --prd ${existing ? existing.binding.prd : prd}, then register ${prd} and select the change to work on with change select (retire one with change supersede or change cancel)` };
+  if (existing && (existing.binding.prd !== prd || existing.binding.change !== id)) {
+    return { code: 'MIGRATION_REQUIRED', problem: `${existing.file} binds ${existing.binding.prd} as change "${existing.binding.change}"; one binding per worktree in migrated mode — migrate to change records first: node scripts/pincer-runtime.cjs migrate --preview --prd ${existing.binding.prd}, then register ${prd}` };
+  }
+  if (existing) {
+    const current = existing.binding;
+    if (current.prd_revision === revision) {
+      if (authorization !== null && authorization !== current.authorization) {
+        const binding = { ...current, authorization };
+        return { binding, file: writeBinding(root, binding), action: 'updated', notes };
+      }
+      return { binding: current, file: existing.file, action: 'unchanged', notes };
+    }
+    if (!rebind) {
+      return { code: 'REVISION_CHANGED', problem: `${prd} content changed since registration (revision ${current.prd_revision.slice(0, 12)} → ${revision.slice(0, 12)}); pass --rebind to bind the new revision — readiness recorded for the old revision no longer applies` };
+    }
+    const binding = { ...current, prd_revision: revision, registered: nowIso(), authorization: authorization ?? current.authorization };
+    notes.push(`rebound to revision ${revision.slice(0, 12)}; attempts recorded for ${current.prd_revision.slice(0, 12)} no longer establish readiness`);
+    return { binding, file: writeBinding(root, binding), action: 'rebound', notes };
+  }
+  const binding = { schema: 1, change: id, prd, prd_revision: revision, base, registered: nowIso(), authorization, runtime: RUNTIME, legacy_receipts: {} };
+  return { binding, file: writeBinding(root, binding), action: 'registered', notes };
+}
+
+module.exports = { CHANGE_ID, RUNTIME, BINDING_KEYS, IGNORE_LINE, listBindings, validateBinding, loadBinding, register, writeBinding, head, gitignoreHas, ensureIgnored };

package/template/scripts/pincer-runtime/impact.cjs

@@ -0,0 +1,177 @@
+'use strict';
+// PINCER runtime — structural impact (docs/runtime-contracts.md, "Strict coverage"
+// → "Coverage and impact commands"). Compares the current authored inputs of a
+// strict change with a retained agreement (`--from G-NN|A-NN`, else the latest
+// authorization's agreement, else the latest agreement with an inventory) and
+// reports added, removed, changed and unchanged requirements and scenarios, changed
+// links, scope entries, declarations and tickets, the affected scenarios, tickets
+// and checks with the reason each is included, dependency dependents separately,
+// and unscoped PRD changes. History it cannot read is `unavailable`, never "no
+// impact". Read-only and structural: it never judges semantics, approves, launches
+// or rewrites anything, and it does not touch evidence freshness.
+const changes = require('./changes.cjs');
+const agreement = require('./agreement.cjs');
+const coverage = require('./coverage.cjs');
+const requirements = require('./requirements.cjs');
+const parse = require('./parse.cjs');
+const { nowIso } = require('./fsutil.cjs');
+
+const SCHEMA = 1;
+const FRESHNESS = 'a narrow impact is not permission to reuse evidence whose source identity changed';
+const sortIds = requirements.sortIds;
+const byNumber = (a, b) => Number(a.slice(2)) - Number(b.slice(2));
+const setDiff = (before, after) => ({ added: sortIds(after.filter(x => !before.includes(x))), removed: sortIds(before.filter(x => !after.includes(x))) });
+
+// Resolve the baseline entry. Returns { entry, authorization } or { reason }.
+function baselineEntry(record, from) {
+  const entryFor = gid => record.agreements.find(g => g.id === gid) || null;
+  if (from) {
+    if (/^A-[0-9]{2,6}$/.test(from)) {
+      const a = record.authorizations.find(x => x.id === from);
+      if (!a) return { reason: `no authorization ${from} on change ${record.change} (recorded: ${record.authorizations.map(x => x.id).join(', ') || 'none'})` };
+      return { entry: entryFor(a.agreement), authorization: a.id };
+    }
+    if (/^G-[0-9]{2,6}$/.test(from)) {
+      const g = entryFor(from);
+      if (!g) return { reason: `no agreement ${from} on change ${record.change} (recorded: ${record.agreements.map(x => x.id).join(', ') || 'none'})` };
+      const auth = record.authorizations.filter(a => a.agreement === g.id).map(a => a.id).pop() || null;
+      return { entry: g, authorization: auth };
+    }
+    return { reason: `--from must name an agreement G-NN or an authorization A-NN (got ${from})` };
+  }
+  const latestAuth = record.authorizations.length ? record.authorizations[record.authorizations.length - 1] : null;
+  if (latestAuth) return { entry: entryFor(latestAuth.agreement), authorization: latestAuth.id };
+  for (let i = record.agreements.length - 1; i >= 0; i--) if (record.agreements[i].inventory) return { entry: record.agreements[i], authorization: null };
+  return { reason: 'no retained agreement carries an inventory snapshot' };
+}
+
+// compute(root, record, { from }) → the impact report, or { code, problem } for invalid input.
+function compute(root, record, { from = null } = {}) {
+  const base = { schema: SCHEMA, runtime: changes.RUNTIME_STRICT, generated: nowIso(), root, change: record.change, baseline: null, current: null, verdict: 'unavailable', reason: null, requirements: null, scenarios: null, links: null, scope: null, checks: null, tickets: null, affected: null, unscoped: null, freshness: { note: FRESHNESS } };
+  if (!changes.isStrict(record)) return { ...base, reason: `strict coverage not adopted by change ${record.change}; impact needs a retained inventory (node scripts/pincer-runtime.cjs coverage adopt --preview --change ${record.change})` };
+  const now = agreement.compute(root, record);
+  if (now.code) return { code: now.code, problem: now.problem };
+  base.current = { digest: now.digest, inventory: now.inventory.digest, coverage: now.coverage.digest };
+  const resolved = baselineEntry(record, from);
+  if (resolved.reason) return { ...base, reason: resolved.reason };
+  const entry = resolved.entry;
+  if (!entry.inventory) return { ...base, baseline: { agreement: entry.id, authorization: resolved.authorization, recorded: entry.recorded, digest: entry.digest }, reason: `agreement ${entry.id} predates strict coverage (no inventory snapshot); the earliest comparable agreement is ${record.coverage.agreement}` };
+  const snap = agreement.readSnapshot(root, record, entry);
+  if (snap.code) return { ...base, baseline: { agreement: entry.id, authorization: resolved.authorization, recorded: entry.recorded, digest: entry.digest }, reason: `${snap.code}: ${snap.problem}` };
+  const s = snap.snapshot;
+  base.baseline = { agreement: entry.id, authorization: resolved.authorization, recorded: entry.recorded, digest: entry.digest };
+  const baseMap = coverage.validateText(s.coverage.text, { change: record.change, prd: s.prd.path });
+  if (baseMap.problem) return { ...base, reason: `the snapshot coverage map of ${entry.id} cannot be read: ${baseMap.problem}` };
+  const curMap = now.graphInputs.map.map;
+  const inv = requirements.difference(s.inventory, now.inventory);
+  const scenarios = { added: inv.scenarios.added, removed: inv.scenarios.removed.map(id => ({ id, tombstone: Boolean(curMap.scope[id] && curMap.scope[id].disposition === 'removed') })), changed: inv.scenarios.changed, unchanged: inv.scenarios.unchanged };
+  const reqs = inv.requirements;
+  // Links: scenarios present in both maps whose tickets or checks changed.
+  // Links: rows added or removed for a scenario, and scenarios present in both maps whose tickets or checks changed.
+  const links = { added: sortIds(Object.keys(curMap.scenarios).filter(id => !baseMap.map.scenarios[id])), removed: sortIds(Object.keys(baseMap.map.scenarios).filter(id => !curMap.scenarios[id])), changed: [] };
+  for (const id of sortIds(Object.keys(curMap.scenarios))) {
+    const b = baseMap.map.scenarios[id];
+    if (!b) continue;
+    const t = setDiff(b.tickets, curMap.scenarios[id].tickets), c = setDiff(b.checks, curMap.scenarios[id].checks);
+    if (t.added.length || t.removed.length || c.added.length || c.removed.length) links.changed.push({ id, tickets: t, checks: c });
+  }
+  const scope = { added: [], removed: [], changed: [] };
+  for (const id of sortIds(Object.keys(curMap.scope))) { const b = baseMap.map.scope[id]; if (!b) scope.added.push({ id, disposition: curMap.scope[id].disposition }); else if (b.disposition !== curMap.scope[id].disposition || b.decision !== curMap.scope[id].decision || b.prior !== curMap.scope[id].prior) scope.changed.push({ id, from: b.disposition, to: curMap.scope[id].disposition }); }
+  scope.removed = sortIds(Object.keys(baseMap.map.scope).filter(id => !curMap.scope[id]));
+  const checks = { added: [], removed: [], changed: [] };
+  for (const id of Object.keys(curMap.checks).sort()) {
+    const b = baseMap.map.checks[id];
+    if (!b) { checks.added.push(id); continue; }
+    const parts = ['kind', 'command', 'timeout', 'cwd', 'obligation', 'required'].filter(k => b[k] !== curMap.checks[id][k]);
+    if (parts.length) checks.changed.push({ id, parts });
+  }
+  checks.removed = Object.keys(baseMap.map.checks).filter(id => !curMap.checks[id]).sort();
+  const tickets = { added: [], removed: [], changed: [] };
+  const ticketDiff = agreement.difference(s, now);
+  tickets.added = ticketDiff.tickets_added; tickets.removed = ticketDiff.tickets_removed;
+  const changedTickets = new Map(ticketDiff.tickets_changed.map(t => [t.id, [...t.parts]]));
+  for (const id of Object.keys(curMap.tickets).sort(byNumber)) {
+    const b = baseMap.map.tickets[id];
+    if (!b) { if (!tickets.added.includes(id)) changedTickets.set(id, [...(changedTickets.get(id) || []), 'classification']); continue; }
+    if (b.role !== curMap.tickets[id].role || b.rationale !== curMap.tickets[id].rationale) changedTickets.set(id, [...(changedTickets.get(id) || []), 'classification']);
+  }
+  tickets.changed = [...changedTickets.entries()].sort(([a], [b]) => byNumber(a, b)).map(([id, parts]) => ({ id, parts }));
+  // Affected: scenarios by text/owner change, link change, changed declaration or changed ticket, addition, or scope change.
+  const affectedScenarios = new Map();
+  const because = (id, why) => { if (!affectedScenarios.has(id)) affectedScenarios.set(id, []); if (!affectedScenarios.get(id).includes(why)) affectedScenarios.get(id).push(why); };
+  for (const c of scenarios.changed) because(c.id, `scenario ${c.parts.join(' and ')} changed`);
+  for (const id of scenarios.added) because(id, 'scenario added');
+  for (const l of links.changed) because(l.id, 'links changed');
+  for (const id of links.added) if (!scenarios.added.includes(id)) because(id, 'links added (a row the baseline lacked)');
+  for (const id of links.removed) if (curMap.scenarios[id] || inv.scenarios.unchanged.includes(id) || inv.scenarios.changed.some(c => c.id === id)) because(id, 'links removed (the row is gone)');
+  for (const e of [...scope.added, ...scope.changed]) because(e.id, `scope disposition ${e.to ? `changed to ${e.to}` : e.disposition}`);
+  for (const id of scope.removed) if (curMap.scenarios[id]) because(id, 'scope disposition removed (back in scope)');
+  for (const [id, row] of Object.entries(curMap.scenarios)) {
+    for (const c of checks.changed) if (row.checks.includes(c.id)) because(id, `declaration of ${c.id} changed (${c.parts.join(', ')})`);
+    for (const t of tickets.changed) if (row.tickets.includes(t.id)) because(id, `ticket ${t.id} changed (${t.parts.join(', ')})`);
+  }
+  const affectedTickets = new Map(), affectedChecks = new Map();
+  const add = (map, id, why) => { if (!map.has(id)) map.set(id, []); if (!map.get(id).includes(why)) map.get(id).push(why); };
+  for (const id of sortIds([...affectedScenarios.keys()])) {
+    const row = curMap.scenarios[id];
+    if (!row) continue;
+    for (const t of row.tickets) add(affectedTickets, t, `linked from ${id}`);
+    for (const c of row.checks) add(affectedChecks, c, `linked from ${id}`);
+  }
+  for (const t of tickets.changed) add(affectedTickets, t.id, `ticket ${t.parts.join(', ')} changed`);
+  for (const c of checks.changed) add(affectedChecks, c.id, `declaration changed (${c.parts.join(', ')})`);
+  // Dependents: tickets of the change that depend (transitively) on an affected ticket and are not affected themselves.
+  const dependents = [];
+  const fields = Object.fromEntries(Object.entries(now.graphInputs.tickets || {}).map(([id, t]) => [id, parse.dependencies(t.fields)]));
+  const allTickets = Object.keys(now.tickets);
+  const deps = id => (fields[id] || (now.tickets[id] ? parse.dependencies(parse.validateTicket(now.tickets[id].file, now.tickets[id].text).fields) : []));
+  const affectedSet = new Set(affectedTickets.keys());
+  let grew = true; const dependentVia = new Map();
+  while (grew) {
+    grew = false;
+    for (const id of allTickets) {
+      if (affectedSet.has(id) || dependentVia.has(id)) continue;
+      const via = deps(id).find(d => affectedSet.has(d) || dependentVia.has(d));
+      if (via) { dependentVia.set(id, via); grew = true; }
+    }
+  }
+  for (const [id, via] of [...dependentVia.entries()].sort(([a], [b]) => byNumber(a, b))) dependents.push({ id, via, because: 'depends_on' });
+  const definitionsUnchanged = inv.same;
+  const unscoped = { prd: Boolean(ticketDiff.prd_changed && definitionsUnchanged), detail: ticketDiff.prd_changed && definitionsUnchanged ? 'unscoped PRD change requiring review: the PRD revision changed while every requirement and scenario definition is unchanged (a constraint, table or note outside the definitions)' : ticketDiff.prd_changed ? 'the PRD revision changed together with its definitions; review the prose outside the definitions too' : null };
+  const same = entry.digest === now.digest;
+  return {
+    ...base, verdict: same ? 'unchanged' : 'changed', reason: same ? null : unscoped.prd && !links.changed.length && !checks.changed.length && !tickets.changed.length && !scope.added.length && !scope.changed.length && !scope.removed.length ? unscoped.detail : null,
+    requirements: reqs, scenarios, links, scope, checks, tickets,
+    affected: { scenarios: sortIds([...affectedScenarios.keys()]).map(id => ({ id, because: affectedScenarios.get(id) })), tickets: [...affectedTickets.keys()].sort(byNumber).map(id => ({ id, because: affectedTickets.get(id) })), checks: [...affectedChecks.keys()].sort().map(id => ({ id, because: affectedChecks.get(id) })), dependents },
+    unscoped,
+  };
+}
+
+function render(r) {
+  const lines = [];
+  lines.push(`PINCER impact · ${r.generated} · ${r.root}`);
+  lines.push(`Change     ${r.change}${r.current ? ` · current agreement ${r.current.digest.slice(0, 12)} (inventory ${r.current.inventory.slice(0, 12)}, coverage ${r.current.coverage.slice(0, 12)})` : ''}`);
+  lines.push(`Baseline   ${r.baseline ? `${r.baseline.agreement}${r.baseline.authorization ? ` (authorized by ${r.baseline.authorization})` : ' (not authorized)'} recorded ${r.baseline.recorded} · ${r.baseline.digest.slice(0, 12)}` : 'none'}`);
+  lines.push(`Verdict    ${r.verdict}${r.reason ? ` — ${r.reason}` : ''}`);
+  if (r.verdict === 'unavailable') { lines.push(`Freshness  ${r.freshness.note}`); return `${lines.join('\n')}\n`; }
+  const list = (label, items, fmt = x => x) => { if (items.length) lines.push(`${label.padEnd(10)} ${items.map(fmt).join(', ')}`); };
+  list('Requirements added', r.requirements.added); list('Requirements removed', r.requirements.removed);
+  list('Requirements changed', r.requirements.changed, c => `${c.id} (${c.parts.join(', ')})`);
+  list('Scenarios added', r.scenarios.added); list('Scenarios removed', r.scenarios.removed, s => `${s.id}${s.tombstone ? ' (tombstone)' : ' (no tombstone)'}`);
+  list('Scenarios changed', r.scenarios.changed, c => `${c.id} (${c.parts.join(', ')})`);
+  list('Links added', r.links.added); list('Links removed', r.links.removed);
+  list('Links changed', r.links.changed, l => `${l.id} (tickets +${l.tickets.added.join(' ') || '—'} -${l.tickets.removed.join(' ') || '—'}; checks +${l.checks.added.join(' ') || '—'} -${l.checks.removed.join(' ') || '—'})`);
+  list('Scope added', r.scope.added, s => `${s.id} (${s.disposition})`); list('Scope removed', r.scope.removed); list('Scope changed', r.scope.changed, s => `${s.id} (${s.from} → ${s.to})`);
+  list('Checks added', r.checks.added); list('Checks removed', r.checks.removed); list('Checks changed', r.checks.changed, c => `${c.id} (${c.parts.join(', ')})`);
+  list('Tickets added', r.tickets.added); list('Tickets removed', r.tickets.removed); list('Tickets changed', r.tickets.changed, t => `${t.id} (${t.parts.join(', ')})`);
+  lines.push(`Unchanged  ${r.requirements.unchanged.length} requirement(s), ${r.scenarios.unchanged.length} scenario(s)${r.scenarios.unchanged.length ? `: ${r.scenarios.unchanged.join(', ')}` : ''}`);
+  lines.push(`Affected   scenarios ${r.affected.scenarios.map(s => `${s.id} [${s.because.join('; ')}]`).join(', ') || 'none'}`);
+  lines.push(`           tickets ${r.affected.tickets.map(t => `${t.id} [${t.because.join('; ')}]`).join(', ') || 'none'}`);
+  lines.push(`           checks ${r.affected.checks.map(c => `${c.id} [${c.because.join('; ')}]`).join(', ') || 'none'}`);
+  lines.push(`Dependents ${r.affected.dependents.map(d => `${d.id} (via ${d.via}, ${d.because})`).join(', ') || 'none'}`);
+  lines.push(`Unscoped   ${r.unscoped.prd ? 'yes' : 'no'}${r.unscoped.detail ? ` — ${r.unscoped.detail}` : ''}`);
+  lines.push(`Freshness  ${r.freshness.note}`);
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = { SCHEMA, FRESHNESS, baselineEntry, compute, render };

package/template/scripts/pincer-runtime/io.cjs

@@ -0,0 +1,41 @@
+'use strict';
+// Complete output on every exit path.
+//
+// `process.stdout` is asynchronous when it is a pipe: a write larger than the
+// pipe buffer is queued on the event loop, and `process.exit()` throws away
+// whatever has not drained. The CLI uses `process.exit()` as its return
+// statement, so any command whose report outgrows one pipe buffer prints a
+// prefix of itself and still exits 0 — `snapshot --json` is 237 KB on this
+// repository and arrives as 64 KB of invalid JSON through a pipe, on every
+// supported Node version. Writing the file descriptor synchronously removes the
+// queue: when `out` returns, the bytes are in the pipe.
+//
+// A slow reader on a non-blocking pipe answers EAGAIN; wait for it rather than
+// spin. A reader that has gone away answers EPIPE, and a closed descriptor
+// answers EBADF: neither is an error here — `pincer status | head -3` and
+// `pincer status 1>&-` are both things a person can type, and both must stay
+// silent and keep the command's own exit code.
+const fs = require('node:fs');
+
+const IDLE = new Int32Array(new SharedArrayBuffer(4));
+
+function write(fd, text) {
+  if (!text) return;
+  const buffer = Buffer.from(text, 'utf8');
+  let offset = 0;
+  while (offset < buffer.length) {
+    try {
+      offset += fs.writeSync(fd, buffer, offset, buffer.length - offset);
+    } catch (error) {
+      if (error.code === 'EAGAIN' || error.code === 'EINTR') { Atomics.wait(IDLE, 0, 0, 1); continue; }
+      if (error.code === 'EPIPE' || error.code === 'EBADF') return;
+      throw error;
+    }
+  }
+}
+
+module.exports = {
+  out: text => write(1, text),
+  err: text => write(2, text),
+  write,
+};