pincer-workflow 0.5.0 → 0.6.0

package/template/scripts/pincer-evidence.cjs

@@ -22,10 +22,11 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { HEX40, PRD_REF, validate, digestFile } = require('./pincer-runtime/evidence.cjs');
+const io = require('./pincer-runtime/io.cjs');
 
 function usage(message) {
-  if (message) process.stderr.write(`pincer-evidence: ${message}\n`);
-  process.stderr.write('usage: pincer-evidence.cjs validate <manifest> [--candidate <sha>] [--base <sha>] [--prd .prd/prd-vN.md] [--files]\n       pincer-evidence.cjs digest <file>...\n');
+  if (message) io.err(`pincer-evidence: ${message}\n`);
+  io.err('usage: pincer-evidence.cjs validate <manifest> [--candidate <sha>] [--base <sha>] [--prd .prd/prd-vN.md] [--files]\n       pincer-evidence.cjs digest <file>...\n');
   process.exit(2);
 }
 
@@ -51,20 +52,21 @@ function main(argv) {
     if (opts.prd !== undefined && !PRD_REF.test(opts.prd)) usage('--prd must be of the form .prd/prd-vN.md');
     const problems = validate(manifest, opts);
     if (problems.length > 0) {
-      for (const p of problems) process.stderr.write(`evidence: ${manifest}: ${p}\n`);
+      for (const p of problems) io.err(`evidence: ${manifest}: ${p}\n`);
       process.exit(1);
     }
     const doc = JSON.parse(fs.readFileSync(path.resolve(manifest), 'utf8'));
-    process.stdout.write(`ok ${doc.candidate}${doc.schema === 2 ? ' schema 2' : ''}\n`);
-    if (opts.files) for (const p of opts.list) process.stdout.write(`${p}\n`);
+    io.out(`ok ${doc.candidate}${doc.schema >= 2 ? ` schema ${doc.schema}` : ''}\n`);
+    for (const l of opts.limitations || []) io.err(`evidence: limitation: ${l}\n`);
+    if (opts.files) for (const p of opts.list) io.out(`${p}\n`);
     return;
   }
   if (command === 'digest') {
     if (rest.length === 0) usage('digest requires at least one file');
     for (const file of rest) {
       let digest;
-      try { digest = digestFile(file); } catch (error) { process.stderr.write(`pincer-evidence: ${file}: ${error.code === 'ENOENT' ? 'missing' : error.message}\n`); process.exit(1); }
-      process.stdout.write(`${digest}  ${file}\n`);
+      try { digest = digestFile(file); } catch (error) { io.err(`pincer-evidence: ${file}: ${error.code === 'ENOENT' ? 'missing' : error.message}\n`); process.exit(1); }
+      io.out(`${digest}  ${file}\n`);
     }
     return;
   }

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

@@ -0,0 +1,132 @@
+'use strict';
+// PINCER runtime — strict coverage adoption (docs/runtime-contracts.md, "Strict
+// coverage" → "Adoption and rollback"). `coverage adopt --preview` computes the plan
+// and writes nothing; `--apply` is one transaction that backs up the schema 2
+// record, records the adoption agreement (projection 2, snapshot schema 2) and
+// rewrites the record as schema 3 with the retained capability and one `adopt`
+// event. It validates the authored inputs (inventory, map, graph), refuses on a
+// running attempt, a terminal state, an incomplete transaction or changed inputs,
+// grants no authorization, and is idempotent. Migration never adopts.
+const fs = require('node:fs');
+const path = require('node:path');
+const changes = require('./changes.cjs');
+const agreement = require('./agreement.cjs');
+const authorization = require('./authorization.cjs');
+const coverage = require('./coverage.cjs');
+const dispositions = require('./dispositions.cjs');
+const transaction = require('./transaction.cjs');
+const state = require('./state.cjs');
+const { nowIso } = require('./fsutil.cjs');
+
+// Compute the plan. Returns { change, conflicts: [{ code, detail }], already, record,
+// file, agreement: { id, digest }, inventory: { requirements, scenarios, digest },
+// map: { path, digest }, historical, scope: [...], backup }.
+function plan(root, { change } = {}) {
+  const conflicts = [];
+  const conflict = (code, detail) => conflicts.push({ code, detail });
+  const out = { change, conflicts, already: false, record: null, file: null };
+  if (typeof change !== 'string' || !changes.CHANGE_ID.test(change)) { conflict('INPUT_INVALID', `change ID must match [a-z0-9][a-z0-9-]{0,63}: ${change}`); return out; }
+  const loaded = changes.loadRecords(root);
+  if (loaded.mode === 'legacy') { conflict('CHANGE_REQUIRED', `no change record under ${changes.CHANGES_DIR}/ — register the change first (node scripts/pincer-runtime.cjs register --prd .prd/prd-vN.md); migration and registration never adopt strict coverage`); return out; }
+  if (loaded.mode === 'migrated') { conflict('MIGRATION_REQUIRED', `${changes.CHANGES_DIR}/ holds a v0.5.0 binding; migrate to change records first (migrate --preview --prd <prd>); migration never adopts strict coverage`); return out; }
+  for (const p of loaded.problems) conflict(p.code, p.detail);
+  if (conflicts.length) return out;
+  const entry = loaded.records.get(change);
+  if (!entry) { conflict('INPUT_INVALID', `no change record ${changes.recordFile(change)} (retained: ${[...loaded.records.keys()].join(', ') || 'none'})`); return out; }
+  out.record = entry.record; out.file = entry.file;
+  if (changes.isStrict(entry.record)) { out.already = true; return out; }
+  const record = entry.record;
+  if (changes.TERMINAL.includes(record.lifecycle.state)) conflict('LIFECYCLE_BLOCKED', `change ${change} is ${record.lifecycle.state}; its history cannot adopt strict coverage — register a new change`);
+  const running = transaction.runningAttempts(root, change);
+  if (running.length) { const a = running[0]; const hint = a.alive === false ? ' (its owner is no longer running: run recover first)' : a.alive === true ? ` (pid ${a.owner.pid} is still running)` : ` (owned by ${a.owner.host || 'another host'})`; conflict('ATTEMPT_RUNNING', `attempt ${a.id} of change ${change} is running${hint}; adoption waits for it`); }
+  const cov = coverage.load(root, record);
+  if (cov.code && cov.code !== 'COVERAGE_INCOMPLETE') { for (const p of cov.problems) conflict(cov.code, p); return out; }
+  if (cov.code === 'COVERAGE_INCOMPLETE') for (const p of cov.problems) conflict('COVERAGE_INCOMPLETE', p);
+  if (conflicts.length) return out;
+  const computed = agreement.compute(root, { ...record, schema: changes.SCHEMA_STRICT });
+  if (computed.code) { conflict(computed.code, computed.problem); return out; }
+  const gid = `G-${String(record.agreements.length + 1).padStart(2, '0')}`;
+  out.agreement = { id: gid, digest: computed.digest };
+  out.computed = computed;
+  out.inventory = { requirements: Object.keys(cov.inventory.requirements).length, scenarios: Object.keys(cov.inventory.scenarios).length, digest: cov.inventory.digest };
+  out.map = { path: cov.map.file, digest: cov.map.digest };
+  out.historical = state.exists(root) ? state.listAttempts(root).filter(a => a.context && a.context.change === change && a.schema !== 3).length : 0;
+  // Scope dispositions are reported for information: their authorization is recorded after adoption.
+  const verdict = authorization.verdict(root, record);
+  out.scope = Object.values(cov.graph.scope).map(s => ({ id: s.id, disposition: s.disposition, decision: s.decision }));
+  out.scopeProblems = dispositions.scopeProblems(record, cov.graph, verdict).problems.map(p => p.detail);
+  out.backup = `.pincer/backups/<UTC timestamp>/${entry.file}`;
+  return out;
+}
+
+function renderPlan(p) {
+  const lines = [];
+  if (p.conflicts.length) {
+    for (const c of p.conflicts) lines.push(`conflict  ${c.code}: ${c.detail}`);
+    lines.push('adoption refused: resolve the conflicts above; nothing was written');
+    return `${lines.join('\n')}\n`;
+  }
+  if (p.already) {
+    lines.push(`already adopted: change ${p.change} is strict since ${p.record.coverage.adopted} (map ${p.record.coverage.map}, adoption agreement ${p.record.coverage.agreement}); nothing to do`);
+    return `${lines.join('\n')}\n`;
+  }
+  lines.push(`adoption plan for change ${p.change} (${p.file}, ${p.record.lifecycle.state})`);
+  lines.push(`  inventory ${p.inventory.requirements} requirement(s), ${p.inventory.scenarios} scenario(s) · digest ${p.inventory.digest.slice(0, 12)}`);
+  lines.push(`  map       ${p.map.path} · digest ${p.map.digest.slice(0, 12)} · structure complete`);
+  for (const s of p.scope) lines.push(`  scope     ${s.id} ${s.disposition} by decision ${s.decision}${p.scopeProblems.find(d => d.startsWith(`${s.id} (`)) ? ` — not yet authorized: ${p.scopeProblems.find(d => d.startsWith(`${s.id} (`)).replace(/^[^:]*: /, '')}` : ''}`);
+  lines.push(`  agreement ${p.agreement.id} ${p.agreement.digest.slice(0, 12)} (projection 2: PRD revision, inventory, coverage map, tickets, resolved decisions) recorded with its snapshot`);
+  lines.push(`  record    ${p.file} → schema 3 with coverage { map, adopted, agreement ${p.agreement.id} } and one adopt event; ${p.record.agreements.length} earlier agreement(s) kept (inventory history unavailable before ${p.agreement.id})`);
+  lines.push(`  history   ${p.historical} existing attempt(s) of this change become HISTORICAL_EVIDENCE until verified again`);
+  lines.push(`  backup    ${p.backup}`);
+  lines.push('  note      adoption grants no authorization: the agreement above needs `change authorize` (user, or --delegated --basis A-NN) before execution');
+  lines.push(`apply with: node scripts/pincer-runtime.cjs coverage adopt --apply --change ${p.change} --agreement ${p.agreement.digest}`);
+  return `${lines.join('\n')}\n`;
+}
+
+// Apply as one transaction. Returns { plan, applied, record, backup } | { plan, already } |
+// { plan, applied: false } (conflicts) | { plan, error, code }.
+function apply(root, { change, agreement: expected = null, hooks = null } = {}) {
+  const first = plan(root, { change });
+  if (first.conflicts.length) return { plan: first, applied: false };
+  if (first.already) return { plan: first, applied: false, already: true };
+  const stamp = nowIso().replace(/[-:]/g, '');
+  let backupRel = null;
+  try {
+    const out = transaction.run(root, { command: `coverage adopt ${change}`, hooks }, ctx => {
+      const p = plan(root, { change });
+      if (p.conflicts.length) ctx.refuse(p.conflicts[0].code, p.conflicts[0].detail);
+      if (p.already) return { plan: p, already: true };
+      if (expected !== null && expected !== p.agreement.digest) ctx.refuse('AGREEMENT_CHANGED', `--agreement ${expected.slice(0, 12)} is not the agreement adoption would record now (${p.agreement.digest.slice(0, 12)}); the inventory, the map, a ticket or a decision changed since the preview — preview again and adopt the current digest`);
+      ctx.idle(change);
+      const old = p.record;
+      // Backup before anything is staged (the copy is outside the transaction's targets).
+      const src = path.join(root, p.file);
+      const dest = path.join(root, '.pincer', 'backups', stamp, p.file);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(src, dest);
+      backupRel = `.pincer/backups/${stamp}/${p.file}`;
+      const record = {};
+      for (const k of changes.RECORD_KEYS_STRICT) record[k] = k === 'coverage' ? null : JSON.parse(JSON.stringify(old[k]));
+      record.schema = changes.SCHEMA_STRICT; record.runtime = changes.RUNTIME_STRICT;
+      record.agreements = old.agreements.map(g => { const e = {}; for (const k of changes.AGREEMENT_KEYS_STRICT) e[k] = k === 'inventory' || k === 'coverage' ? null : g[k]; return e; });
+      record.coverage = { map: coverage.file(change), adopted: ctx.now, agreement: p.agreement.id };
+      const appended = agreement.appendAgreement(ctx, changes, record, p.file, p.computed, { stage: false, event: false });
+      if (appended.agreement.id !== p.agreement.id) ctx.refuse('STATE_CHANGED', `the record changed since the operation was prepared (agreement ${appended.agreement.id} instead of ${p.agreement.id})`);
+      const sequence = record.sequence + 1;
+      record.events.push({ sequence, kind: 'adopt', from: record.lifecycle.state, to: record.lifecycle.state, at: ctx.now, reason: null, agreement: p.agreement.id, authorization: null, decision: null, replacement: null, note: null });
+      record.sequence = sequence;
+      const invalid = changes.validateRecord(record, p.file);
+      if (invalid) ctx.refuse(invalid.code, invalid.problem);
+      ctx.write(p.file, record);
+      return { plan: p, record };
+    });
+    if (out.result.already) return { plan: out.result.plan, applied: false, already: true };
+    return { plan: out.result.plan, applied: true, record: out.result.record, backup: backupRel };
+  } catch (error) {
+    if (error.refusal) return { plan: first, applied: false, error: error.message, code: error.code };
+    if (error.code === 'STATE_BUSY') return { plan: first, applied: false, error: error.message, code: 'STATE_BUSY' };
+    throw error;
+  }
+}
+
+module.exports = { plan, renderPlan, apply };

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

@@ -0,0 +1,240 @@
+'use strict';
+// PINCER runtime — agreements (docs/runtime-contracts.md, "Agreements and
+// authorization"). An agreement is the reviewed content a user authorized: the
+// change, the PRD's authored revision, the breakdown (every ticket of the PRD,
+// normalized as in "Content revisions") and the resolved consequential
+// decisions. Its digest is SHA-256 over the projection text below, version 1.
+// Agreement entries carry a tracked snapshot of the normalized inputs so an old
+// agreement stays reviewable and its digest recomputable from the file alone;
+// the structural difference between two agreements is computed here too. Nothing
+// here judges semantics or grants approval.
+const fs = require('node:fs');
+const path = require('node:path');
+const parse = require('./parse.cjs');
+const transaction = require('./transaction.cjs');
+const requirements = require('./requirements.cjs');
+const coverage = require('./coverage.cjs');
+const { readJson } = require('./fsutil.cjs');
+
+const PROJECTION_VERSION = 1;
+const SNAPSHOT_SCHEMA = 1;
+// Strict coverage (PRD v6): projection version 2 adds the inventory and coverage
+// map digests; snapshot schema 2 carries the normalized inventory and map text.
+const PROJECTION_VERSION_STRICT = 2;
+const SNAPSHOT_SCHEMA_STRICT = 2;
+const SNAPSHOT_KEYS = ['schema', 'change', 'agreement', 'digest', 'projection', 'prd', 'tickets', 'decisions', 'recorded'];
+const SNAPSHOT_KEYS_STRICT = ['schema', 'change', 'agreement', 'digest', 'projection', 'prd', 'inventory', 'coverage', 'tickets', 'decisions', 'recorded'];
+const isObject = v => v !== null && typeof v === 'object' && !Array.isArray(v);
+const ticketNumber = id => Number(id.slice(2));
+
+const decisionDigest = d => parse.sha256(`${d.id}\n${d.summary}\n${d.reference}\n${d.excerpt}\n`);
+
+// The exact projection text (each line terminated by \n).
+function projectionText({ change, prd, tickets, decisions, inventory = null, coverage: map = null }) {
+  const strict = Boolean(inventory && map);
+  const lines = [`pincer agreement ${strict ? PROJECTION_VERSION_STRICT : PROJECTION_VERSION}`, `change ${change}`, `prd ${prd.path} ${prd.revision}`];
+  if (strict) { lines.push(`inventory ${inventory.digest}`); lines.push(`coverage ${map.path} ${map.digest}`); }
+  for (const id of Object.keys(tickets).sort((a, b) => ticketNumber(a) - ticketNumber(b))) lines.push(`ticket ${id} ${tickets[id].digest}`);
+  for (const id of Object.keys(decisions).sort()) lines.push(`decision ${id} ${decisionDigest({ id, ...decisions[id] })}`);
+  return `${lines.join('\n')}\n`;
+}
+const breakdownDigest = tickets => parse.sha256(Object.keys(tickets).sort((a, b) => ticketNumber(a) - ticketNumber(b)).map(id => `ticket ${id} ${tickets[id].digest}\n`).join(''));
+
+// Compute the current agreement of a record from the files on disk. Returns
+// { digest, projection, prd, tickets, decisions, breakdown } or { code, problem }.
+function compute(root, record) {
+  const prdResult = parse.validatePrd(root, record.prd);
+  if (!prdResult.ok) return { code: 'INPUT_INVALID', problem: `${record.prd}: ${prdResult.problems[0]}` };
+  const set = parse.validateTicketSet(root);
+  if (!set.ok) return { code: 'INPUT_INVALID', problem: `pincer-ticket: ${set.file ? `${set.file}: ` : ''}${set.problems[0]}` };
+  const statusModule = require('./status.cjs');
+  const tickets = {};
+  for (const file of set.files) {
+    const text = fs.readFileSync(path.join(root, file), 'utf8');
+    const v = parse.validateTicket(file, text);
+    const assoc = statusModule.ticketPrd(root, file, v.fields);
+    if (assoc.problem) return { code: 'INPUT_INVALID', problem: assoc.problem };
+    if (assoc.prd !== record.prd) continue;
+    tickets[v.fields.ticket] = { file, digest: parse.ticketDigest(text), text: parse.normalizeTicket(text) };
+  }
+  const decisions = {};
+  for (const d of record.decisions) if (d.status === 'resolved') decisions[d.id] = { summary: d.summary, reference: d.reference, excerpt: d.excerpt };
+  const prd = { path: record.prd, revision: parse.prdDigest(prdResult.text), text: parse.normalizePrd(prdResult.text) };
+  const inputs = { change: record.change, prd, tickets, decisions };
+  if (record.schema === 3) {
+    // A strict change binds its inventory and its coverage map (docs/runtime-contracts.md,
+    // "Strict change records"); when either cannot be read the agreement cannot be computed.
+    const inv = requirements.readInventory(root, record.prd);
+    if (!inv.ok) return { code: inv.code, problem: inv.problems[0] };
+    const m = coverage.readMap(root, record);
+    if (!m.ok) return { code: m.code, problem: m.problems[0] };
+    inputs.inventory = requirements.snapshotOf(inv.inventory);
+    inputs.coverage = { path: m.file, digest: m.digest, text: m.normalized };
+    inputs.graphInputs = { inventory: inv.inventory, map: m };
+  }
+  const projection = projectionText(inputs);
+  return { ...inputs, projection, digest: parse.sha256(projection), breakdown: breakdownDigest(tickets) };
+}
+
+// --- Snapshots -----------------------------------------------------------------------
+function snapshotDoc(record, agreementId, computed, recorded) {
+  if (computed.inventory && computed.coverage) return { schema: SNAPSHOT_SCHEMA_STRICT, change: record.change, agreement: agreementId, digest: computed.digest, projection: computed.projection, prd: computed.prd, inventory: computed.inventory, coverage: computed.coverage, tickets: computed.tickets, decisions: computed.decisions, recorded };
+  return { schema: SNAPSHOT_SCHEMA, change: record.change, agreement: agreementId, digest: computed.digest, projection: computed.projection, prd: computed.prd, tickets: computed.tickets, decisions: computed.decisions, recorded };
+}
+// Read and verify one agreement's snapshot: the file exists, has the documented
+// shape, its projection recomputes from its own inputs, and the digest is the
+// SHA-256 of that projection and equals the entry's. Returns { snapshot } or
+// { code: 'HISTORY_INVALID', problem }.
+function readSnapshot(root, record, agreement) {
+  const rel = agreement.snapshot;
+  const invalid = p => ({ code: 'HISTORY_INVALID', problem: `${rel}: ${p} — the agreement ${agreement.id} of change "${record.change}" cannot be reviewed from a digest alone` });
+  const read = readJson(path.join(root, rel));
+  if (read.error === 'missing') return invalid('snapshot missing');
+  if (read.error) return invalid(read.error);
+  const s = read.data;
+  if (!isObject(s) || ![SNAPSHOT_SCHEMA, SNAPSHOT_SCHEMA_STRICT].includes(s.schema)) return invalid('not a schema 1 or 2 agreement snapshot');
+  const keys = s.schema === SNAPSHOT_SCHEMA_STRICT ? SNAPSHOT_KEYS_STRICT : SNAPSHOT_KEYS;
+  if (Object.keys(s).some(k => !keys.includes(k)) || !keys.every(k => k in s)) return invalid(`not a schema ${s.schema} agreement snapshot (keys)`);
+  if (s.schema === SNAPSHOT_SCHEMA_STRICT) {
+    if (!isObject(s.prd) || typeof s.prd.path !== 'string') return invalid('snapshot prd must be { path, revision, text }');
+    const inv = requirements.validateSnapshot(s.inventory, s.prd.path);
+    if (inv) return invalid(`snapshot inventory: ${inv}`);
+    if (!isObject(s.coverage) || typeof s.coverage.path !== 'string' || typeof s.coverage.digest !== 'string' || typeof s.coverage.text !== 'string') return invalid('snapshot coverage must be { path, digest, text }');
+    if (s.coverage.path !== coverage.file(record.change)) return invalid(`snapshot coverage path must be ${coverage.file(record.change)}`);
+    const m = coverage.validateText(s.coverage.text, { change: record.change, prd: s.prd.path });
+    if (m.problem) return invalid(`snapshot coverage map: ${m.problem}`);
+    if (m.digest !== s.coverage.digest || parse.sha256(s.coverage.text) !== s.coverage.digest) return invalid('the snapshot coverage map text does not hash to its recorded digest');
+    if (agreement.inventory !== undefined && (agreement.inventory !== s.inventory.digest || agreement.coverage !== s.coverage.digest)) return invalid('the snapshot inventory and coverage digests do not match the record entry');
+  } else if (agreement.inventory !== undefined && (agreement.inventory !== null || agreement.coverage !== null)) return invalid('a schema 1 snapshot carries no inventory or coverage digest, but the record entry does');
+  if (s.change !== record.change || s.agreement !== agreement.id) return invalid(`snapshot belongs to ${s.change}/${s.agreement}`);
+  if (!isObject(s.prd) || typeof s.prd.path !== 'string' || typeof s.prd.revision !== 'string' || typeof s.prd.text !== 'string') return invalid('snapshot prd must be { path, revision, text }');
+  if (!isObject(s.tickets) || !Object.values(s.tickets).every(t => isObject(t) && typeof t.file === 'string' && typeof t.digest === 'string' && typeof t.text === 'string')) return invalid('snapshot tickets must map IDs to { file, digest, text }');
+  if (!isObject(s.decisions)) return invalid('snapshot decisions must be an object');
+  if (parse.sha256(s.prd.text) !== s.prd.revision) return invalid('the snapshot PRD text does not hash to its recorded revision');
+  for (const [id, t] of Object.entries(s.tickets)) if (parse.sha256(t.text) !== t.digest) return invalid(`the snapshot text of ${id} does not hash to its recorded digest`);
+  const recomputed = projectionText({ change: s.change, prd: s.prd, tickets: s.tickets, decisions: s.decisions, inventory: s.inventory || null, coverage: s.coverage || null });
+  if (recomputed !== s.projection) return invalid('the snapshot projection does not recompute from its inputs');
+  if (parse.sha256(s.projection) !== s.digest || s.digest !== agreement.digest) return invalid('the snapshot digest does not match the projection or the record entry');
+  return { snapshot: s };
+}
+
+// --- Structural difference ------------------------------------------------------------
+// Which parts of two normalized ticket texts differ: frontmatter, acceptance,
+// verification, other. Never a semantic judgment.
+function ticketParts(a, b) {
+  const sa = parse.ticketSections(a), sb = parse.ticketSections(b);
+  return ['frontmatter', 'acceptance', 'verification', 'other'].filter(k => sa[k] !== sb[k]);
+}
+// difference(from, to): `from` is a snapshot (or computed inputs) and `to` the
+// current computed inputs.
+function difference(from, to) {
+  const before = new Set(Object.keys(from.tickets)), after = new Set(Object.keys(to.tickets));
+  const byNumber = (a, b) => ticketNumber(a) - ticketNumber(b);
+  const added = [...after].filter(id => !before.has(id)).sort(byNumber);
+  const removed = [...before].filter(id => !after.has(id)).sort(byNumber);
+  const changed = [...after].filter(id => before.has(id) && from.tickets[id].digest !== to.tickets[id].digest).sort(byNumber).map(id => ({ id, parts: ticketParts(from.tickets[id].text, to.tickets[id].text) }));
+  const decisionsBefore = Object.keys(from.decisions), decisionsAfter = Object.keys(to.decisions);
+  const both = from.inventory && to.inventory && from.coverage && to.coverage;
+  const out = {
+    same: from.digest === to.digest,
+    prd_changed: from.prd.revision !== to.prd.revision,
+    tickets_added: added, tickets_removed: removed, tickets_changed: changed,
+    decisions_added: decisionsAfter.filter(id => !decisionsBefore.includes(id)).sort(),
+    decisions_removed: decisionsBefore.filter(id => !decisionsAfter.includes(id)).sort(),
+  };
+  // Strict coverage (either side strict): the inventory difference, or null with
+  // strict_history false when one side has no inventory (history unavailable).
+  // A difference between two non-strict agreements keeps the v5 shape exactly.
+  if (from.inventory || to.inventory) {
+    out.inventory = both ? requirements.difference(from.inventory, to.inventory) : null;
+    out.coverage_changed = both ? from.coverage.digest !== to.coverage.digest : null;
+    out.strict_history = Boolean(both);
+  }
+  return out;
+}
+function renderDifference(d) {
+  if (d.same) return 'unchanged';
+  const bits = [];
+  if (d.prd_changed) bits.push('PRD body changed');
+  if (d.tickets_added.length) bits.push(`tickets added: ${d.tickets_added.join(', ')}`);
+  if (d.tickets_removed.length) bits.push(`tickets removed: ${d.tickets_removed.join(', ')}`);
+  if (d.tickets_changed.length) bits.push(`tickets changed: ${d.tickets_changed.map(t => `${t.id} (${t.parts.join(', ') || 'content'})`).join(', ')}`);
+  if (d.decisions_added.length) bits.push(`decisions resolved: ${d.decisions_added.join(', ')}`);
+  if (d.decisions_removed.length) bits.push(`decisions no longer recorded: ${d.decisions_removed.join(', ')}`);
+  if (d.inventory && !d.inventory.same) {
+    const inv = d.inventory, parts = [];
+    if (inv.requirements.added.length) parts.push(`requirements added: ${inv.requirements.added.join(', ')}`);
+    if (inv.requirements.removed.length) parts.push(`requirements removed: ${inv.requirements.removed.join(', ')}`);
+    if (inv.requirements.changed.length) parts.push(`requirements changed: ${inv.requirements.changed.map(r => `${r.id} (${r.parts.join(', ')})`).join(', ')}`);
+    if (inv.scenarios.added.length) parts.push(`scenarios added: ${inv.scenarios.added.join(', ')}`);
+    if (inv.scenarios.removed.length) parts.push(`scenarios removed: ${inv.scenarios.removed.join(', ')}`);
+    if (inv.scenarios.changed.length) parts.push(`scenarios changed: ${inv.scenarios.changed.map(r => `${r.id} (${r.parts.join(', ')})`).join(', ')}`);
+    bits.push(`inventory changed (${parts.join('; ') || 'digest'})`);
+  }
+  if (d.coverage_changed) bits.push('coverage map changed');
+  if (d.strict_history === false) bits.push('inventory history unavailable for one side');
+  return bits.join('; ') || 'digest differs';
+}
+
+// The latest recorded agreement entry, and whether it matches the current digest.
+const latestEntry = record => (record.agreements.length ? record.agreements[record.agreements.length - 1] : null);
+const entryFor = (record, digest) => record.agreements.find(g => g.digest === digest) || null;
+
+// --- change revise ---------------------------------------------------------------------
+// Record the current agreement as G-NN with its snapshot when it differs from the
+// latest recorded one; a no-op otherwise. Authorizes nothing. `expect` is the
+// record sequence the caller prepared against. Returns { action: 'recorded' |
+// 'unchanged', agreement, record, difference } or { code, problem }.
+function revise(root, id, { expect = null, hooks = null } = {}) {
+  const changes = require('./changes.cjs');
+  try {
+    const out = transaction.run(root, { command: `change revise ${id}`, hooks }, ctx => {
+      const resolved = changes.resolveSelected(root, { change: id });
+      if (resolved.code) ctx.refuse(resolved.code, resolved.problem);
+      if (expect !== null) ctx.expect(resolved.file, 'sequence', expect);
+      const record = resolved.record;
+      if (changes.TERMINAL.includes(record.lifecycle.state)) ctx.refuse('LIFECYCLE_BLOCKED', `change ${id} is ${record.lifecycle.state}; its agreements are history and cannot be revised — register a new change`);
+      const computed = compute(root, record);
+      if (computed.code) ctx.refuse(computed.code, computed.problem);
+      const latest = latestEntry(record);
+      if (latest && latest.digest === computed.digest) return { action: 'unchanged', agreement: latest, record, difference: null };
+      const previous = latest ? readSnapshot(root, record, latest) : null;
+      if (previous && previous.code) ctx.refuse(previous.code, previous.problem);
+      return appendAgreement(ctx, changes, record, resolved.file, computed, { previous: previous ? previous.snapshot : null });
+    });
+    return out.result;
+  } catch (error) {
+    if (error.refusal) return { code: error.code, problem: error.message };
+    if (error.code === 'STATE_BUSY') return { code: 'STATE_BUSY', problem: error.message };
+    throw error;
+  }
+}
+// Stage a new agreement entry, its snapshot and the `agreement` event on an
+// in-memory record; shared with `change authorize` (which records the agreement
+// it binds when it is not recorded yet). Mutates `record`; the caller must stage
+// the record write when it adds more.
+function appendAgreement(ctx, changes, record, file, computed, { previous = null, stage = true, event = true } = {}) {
+  const gid = `G-${String(record.agreements.length + 1).padStart(2, '0')}`;
+  const snapshotRel = changes.snapshotFile(record.change, gid);
+  const entry = record.schema === 3
+    ? { id: gid, digest: computed.digest, prd_revision: computed.prd.revision, breakdown: computed.breakdown, inventory: computed.inventory ? computed.inventory.digest : null, coverage: computed.coverage ? computed.coverage.digest : null, tickets: Object.keys(computed.tickets).sort((a, b) => ticketNumber(a) - ticketNumber(b)), decisions: Object.keys(computed.decisions).sort(), snapshot: snapshotRel, recorded: ctx.now }
+    : { id: gid, digest: computed.digest, prd_revision: computed.prd.revision, breakdown: computed.breakdown, tickets: Object.keys(computed.tickets).sort((a, b) => ticketNumber(a) - ticketNumber(b)), decisions: Object.keys(computed.decisions).sort(), snapshot: snapshotRel, recorded: ctx.now };
+  record.agreements.push(entry);
+  if (event) {
+    // `change authorize` records the entry inside its own event instead.
+    const sequence = record.sequence + 1;
+    record.events.push({ sequence, kind: 'agreement', from: record.lifecycle.state, to: record.lifecycle.state, at: ctx.now, reason: null, agreement: gid, authorization: null, decision: null, replacement: null, note: null });
+    record.sequence = sequence;
+  }
+  ctx.write(snapshotRel, snapshotDoc(record, gid, computed, ctx.now));
+  if (stage) ctx.write(file, record);
+  return { action: 'recorded', agreement: entry, record, difference: previous ? difference(previous, computed) : null };
+}
+
+// The inventory snapshot of an agreement entry (null when the entry predates strict coverage or is unreadable).
+function inventoryOf(root, record, entry) {
+  if (!entry || entry.inventory === null || entry.inventory === undefined) return null;
+  const snap = readSnapshot(root, record, entry);
+  return snap.code ? null : snap.snapshot.inventory;
+}
+module.exports = { PROJECTION_VERSION, PROJECTION_VERSION_STRICT, SNAPSHOT_SCHEMA, SNAPSHOT_SCHEMA_STRICT, inventoryOf, projectionText, decisionDigest, breakdownDigest, compute, snapshotDoc, readSnapshot, difference, renderDifference, latestEntry, entryFor, revise, appendAgreement };

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

@@ -0,0 +1,167 @@
+'use strict';
+// PINCER runtime — authorization and decisions (docs/runtime-contracts.md,
+// "Agreements and authorization"). An authorization record binds one agreement
+// digest to the user's actual instruction (disposition `user`) or to an earlier
+// authorization it stays within (disposition `delegated`, a reviewer's judgment
+// recorded with its explanation). Decisions are the consequential choices that
+// need the user: raised as `open`, which blocks execution, and resolved with the
+// user's decision, which changes the agreement. The verdict computed here is the
+// one every gate, status and resume consume. Nothing here infers approval from a
+// status, a passing check, a registration or the v0.5.0 free text.
+const transaction = require('./transaction.cjs');
+const agreement = require('./agreement.cjs');
+const { inlineSecretLine } = require('./sanitize.cjs');
+
+const SHA256 = /^[0-9a-f]{64}$/;
+const DECISION_ID = /^D-[0-9]{2,6}$/;
+const AUTHORIZATION_ID = /^A-[0-9]{2,6}$/;
+const nextId = (prefix, list) => `${prefix}-${String(list.length + 1).padStart(2, '0')}`;
+
+// --- Verdict (pure over the record and the computed agreement) -------------------------
+// { verdict: 'current' | 'DECISION_REQUIRED' | 'AUTHORIZATION_REQUIRED' | 'AGREEMENT_CHANGED',
+//   detail, authorized, current, latest, open, difference } — or, when the agreement
+// cannot be computed, { verdict: <input code>, detail }.
+function verdict(root, record, computed = null) {
+  const now = computed || agreement.compute(root, record);
+  if (now.code) return { verdict: now.code, detail: now.problem, authorized: null, current: null, latest: null, open: [], difference: null };
+  const open = record.decisions.filter(d => d.status === 'open');
+  const authorized = record.authorizations.find(a => a.digest === now.digest) || null;
+  const latest = record.authorizations.length ? record.authorizations[record.authorizations.length - 1] : null;
+  let difference = null;
+  if (!authorized && latest) {
+    const entry = record.agreements.find(g => g.id === latest.agreement);
+    const snap = entry ? agreement.readSnapshot(root, record, entry) : { code: 'HISTORY_INVALID' };
+    if (!snap.code) difference = agreement.difference(snap.snapshot, now);
+  }
+  const base = { authorized, current: now.digest, latest, open: open.map(d => d.id), difference };
+  if (open.length) return { ...base, verdict: 'DECISION_REQUIRED', detail: `decision ${open[0].id} is open (${open[0].summary}); record the user's decision with: node scripts/pincer-runtime.cjs change decide ${record.change} --resolve ${open[0].id} --reference <text> --excerpt <text>` };
+  if (!record.authorizations.length) return { ...base, verdict: 'AUTHORIZATION_REQUIRED', detail: `change ${record.change} has no authorization record${record.legacy.authorization_text ? ' (the v0.5.0 free text is retained as history only)' : ''}; record the user's instruction with: node scripts/pincer-runtime.cjs change authorize ${record.change} --agreement ${now.digest} --reference <text> --excerpt <text>` };
+  if (!authorized) return { ...base, verdict: 'AGREEMENT_CHANGED', detail: `the latest authorization ${latest.id} covers agreement ${latest.agreement} ${latest.digest.slice(0, 12)}, the current agreement is ${now.digest.slice(0, 12)}${difference ? ` (${agreement.renderDifference(difference)})` : ''}; record the disposition with: node scripts/pincer-runtime.cjs change authorize ${record.change} --agreement ${now.digest} … (user) or --delegated --basis ${latest.id} --explanation <text>` };
+  return { ...base, verdict: 'current', detail: `${authorized.id} (${authorized.disposition}) covers the current agreement ${now.digest.slice(0, 12)}` };
+}
+
+// --- Shared validation of authored texts ----------------------------------------------------
+function text(value, name, options) {
+  const v = transaction.boundedText(value, name, options);
+  if (v !== null && inlineSecretLine([v])) transaction.refuse('INPUT_INVALID', `--${name} assigns a secret-like literal; reference secrets by name, never by value`);
+  return v;
+}
+
+// --- change authorize ---------------------------------------------------------------------------
+// Returns { action: 'recorded' | 'unchanged', authorization, agreement, record } or { code, problem }.
+function authorize(root, id, opts = {}) {
+  const changes = require('./changes.cjs');
+  try {
+    const out = transaction.run(root, { command: `change authorize ${id}`, hooks: opts.hooks || null }, ctx => {
+      const resolved = changes.resolveSelected(root, { change: id });
+      if (resolved.code) ctx.refuse(resolved.code, resolved.problem);
+      if (opts.expect !== undefined && opts.expect !== null) ctx.expect(resolved.file, 'sequence', opts.expect);
+      const record = resolved.record;
+      if (changes.TERMINAL.includes(record.lifecycle.state)) ctx.refuse('LIFECYCLE_BLOCKED', `change ${id} is ${record.lifecycle.state}; it cannot be authorized — register a new change and reference this record`);
+      if (typeof opts.agreement !== 'string' || !SHA256.test(opts.agreement)) ctx.refuse('INPUT_INVALID', '--agreement must be the 64-hex agreement digest (shown by change show and status)');
+      const disposition = opts.delegated ? 'delegated' : 'user';
+      const reference = disposition === 'user' ? text(opts.reference, 'reference') : (opts.reference !== undefined && opts.reference !== null ? ctx.refuse('INPUT_INVALID', 'a delegated authorization carries no --reference/--excerpt; name its basis and explanation instead') : null);
+      const excerpt = disposition === 'user' ? text(opts.excerpt, 'excerpt') : (opts.excerpt !== undefined && opts.excerpt !== null ? ctx.refuse('INPUT_INVALID', 'a delegated authorization carries no --reference/--excerpt; name its basis and explanation instead') : null);
+      const constraints = text(opts.constraints, 'constraints', { required: false });
+      let basis = null, explanation = null;
+      if (disposition === 'delegated') {
+        if (typeof opts.basis !== 'string' || !AUTHORIZATION_ID.test(opts.basis)) ctx.refuse('INPUT_INVALID', '--delegated requires --basis A-NN (an earlier authorization of this change)');
+        if (!record.authorizations.some(a => a.id === opts.basis)) ctx.refuse('INPUT_INVALID', `--basis ${opts.basis} is not an authorization of change ${id} (recorded: ${record.authorizations.map(a => a.id).join(', ') || 'none'})`);
+        basis = opts.basis;
+        explanation = text(opts.explanation, 'explanation');
+      } else if (opts.basis || opts.explanation) ctx.refuse('INPUT_INVALID', '--basis and --explanation belong to --delegated authorizations');
+      const decisions = [...new Set(opts.decisions || [])].sort();
+      for (const d of decisions) {
+        if (!DECISION_ID.test(d)) ctx.refuse('INPUT_INVALID', `--decision must name a decision such as D-01 (got ${d})`);
+        const found = record.decisions.find(x => x.id === d);
+        if (!found) ctx.refuse('INPUT_INVALID', `--decision ${d} is not a decision of change ${id} (recorded: ${record.decisions.map(x => x.id).join(', ') || 'none'})`);
+        if (found.status !== 'resolved') ctx.refuse('DECISION_REQUIRED', `decision ${d} is still open; resolve it first with: node scripts/pincer-runtime.cjs change decide ${id} --resolve ${d} --reference <text> --excerpt <text>`);
+      }
+      const computed = agreement.compute(root, record);
+      if (computed.code) ctx.refuse(computed.code, computed.problem);
+      if (computed.digest !== opts.agreement) ctx.refuse('AGREEMENT_CHANGED', `--agreement ${opts.agreement.slice(0, 12)} is not the current agreement of ${id} (${computed.digest.slice(0, 12)}); the authored inputs changed since it was prepared — review them (change show ${id}) and authorize the current digest`);
+      const same = record.authorizations.find(a => a.digest === computed.digest && a.disposition === disposition && a.reference === reference && a.excerpt === excerpt && a.constraints === constraints && a.basis === basis && a.explanation === explanation && JSON.stringify(a.decisions) === JSON.stringify(decisions));
+      if (same) return { action: 'unchanged', authorization: same, agreement: record.agreements.find(g => g.id === same.agreement), record };
+      let entry = agreement.entryFor(record, computed.digest);
+      if (!entry) {
+        const latest = agreement.latestEntry(record);
+        const previous = latest ? agreement.readSnapshot(root, record, latest) : null;
+        if (previous && previous.code) ctx.refuse(previous.code, previous.problem);
+        entry = agreement.appendAgreement(ctx, changes, record, resolved.file, computed, { stage: false, event: false }).agreement;
+      }
+      const auth = { id: nextId('A', record.authorizations), agreement: entry.id, digest: computed.digest, disposition, reference, excerpt, constraints, basis, explanation, decisions, recorded: ctx.now };
+      record.authorizations.push(auth);
+      const sequence = record.sequence + 1;
+      record.events.push({ sequence, kind: 'authorize', from: record.lifecycle.state, to: record.lifecycle.state, at: ctx.now, reason: null, agreement: entry.id, authorization: auth.id, decision: decisions[0] || null, replacement: null, note: null });
+      record.sequence = sequence;
+      ctx.write(resolved.file, record);
+      return { action: 'recorded', authorization: auth, agreement: entry, record };
+    });
+    return out.result;
+  } catch (error) {
+    if (error.refusal) return { code: error.code, problem: error.message };
+    if (error.code === 'STATE_BUSY') return { code: 'STATE_BUSY', problem: error.message };
+    throw error;
+  }
+}
+
+// --- change decide ---------------------------------------------------------------------------
+// Raise: { action: 'raised' | 'unchanged', decision, record }; resolve: { action:
+// 'resolved' | 'unchanged', decision, record, agreement: <new digest> }.
+function decide(root, id, opts = {}) {
+  const changes = require('./changes.cjs');
+  try {
+    const out = transaction.run(root, { command: `change decide ${id}`, hooks: opts.hooks || null }, ctx => {
+      const resolved = changes.resolveSelected(root, { change: id });
+      if (resolved.code) ctx.refuse(resolved.code, resolved.problem);
+      if (opts.expect !== undefined && opts.expect !== null) ctx.expect(resolved.file, 'sequence', opts.expect);
+      const record = resolved.record;
+      if (changes.TERMINAL.includes(record.lifecycle.state)) ctx.refuse('LIFECYCLE_BLOCKED', `change ${id} is ${record.lifecycle.state}; decisions belong to a new change`);
+      if (opts.resolve) {
+        if (!DECISION_ID.test(opts.resolve)) ctx.refuse('INPUT_INVALID', '--resolve must name a decision such as D-01');
+        const decision = record.decisions.find(d => d.id === opts.resolve);
+        if (!decision) ctx.refuse('INPUT_INVALID', `no decision ${opts.resolve} on change ${id} (recorded: ${record.decisions.map(d => d.id).join(', ') || 'none'})`);
+        const reference = text(opts.reference, 'reference');
+        const excerpt = text(opts.excerpt, 'excerpt');
+        if (decision.status === 'resolved') {
+          if (decision.reference === reference && decision.excerpt === excerpt) return { action: 'unchanged', decision, record, agreement: agreement.compute(root, record).digest || null };
+          ctx.refuse('INPUT_INVALID', `${decision.id} is already resolved ("${decision.excerpt}", ${decision.reference}); a different decision needs a new decision record`);
+        }
+        decision.status = 'resolved'; decision.reference = reference; decision.excerpt = excerpt; decision.resolved = ctx.now;
+        const sequence = record.sequence + 1;
+        record.events.push({ sequence, kind: 'resolve', from: record.lifecycle.state, to: record.lifecycle.state, at: ctx.now, reason: null, agreement: null, authorization: null, decision: decision.id, replacement: null, note: null });
+        record.sequence = sequence;
+        ctx.write(resolved.file, record);
+        const after = agreement.compute(root, record);
+        return { action: 'resolved', decision, record, agreement: after.code ? null : after.digest };
+      }
+      const summary = text(opts.summary, 'summary');
+      const expectedId = nextId('D', record.decisions);
+      if (opts.id !== undefined && opts.id !== null) {
+        if (!DECISION_ID.test(opts.id)) ctx.refuse('INPUT_INVALID', '--id must be a decision ID such as D-01');
+        const existing = record.decisions.find(d => d.id === opts.id);
+        if (existing) {
+          if (existing.status === 'open' && existing.summary === summary) return { action: 'unchanged', decision: existing, record };
+          ctx.refuse('INPUT_INVALID', `${opts.id} already exists on change ${id} (${existing.status}: ${existing.summary}); decisions are never rewritten — raise a new one`);
+        }
+        if (opts.id !== expectedId) ctx.refuse('INPUT_INVALID', `the next decision of change ${id} is ${expectedId}, not ${opts.id}`);
+      }
+      const same = record.decisions.find(d => d.status === 'open' && d.summary === summary);
+      if (same) return { action: 'unchanged', decision: same, record };
+      const decision = { id: expectedId, status: 'open', summary, reference: null, excerpt: null, raised: ctx.now, resolved: null };
+      record.decisions.push(decision);
+      const sequence = record.sequence + 1;
+      record.events.push({ sequence, kind: 'decide', from: record.lifecycle.state, to: record.lifecycle.state, at: ctx.now, reason: null, agreement: null, authorization: null, decision: decision.id, replacement: null, note: null });
+      record.sequence = sequence;
+      ctx.write(resolved.file, record);
+      return { action: 'raised', decision, record };
+    });
+    return out.result;
+  } catch (error) {
+    if (error.refusal) return { code: error.code, problem: error.message };
+    if (error.code === 'STATE_BUSY') return { code: 'STATE_BUSY', problem: error.message };
+    throw error;
+  }
+}
+
+module.exports = { verdict, authorize, decide, DECISION_ID, AUTHORIZATION_ID };