pincer-workflow 0.5.0 → 0.6.0

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,
+};

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

@@ -16,6 +16,7 @@ const runner = require('./runner.cjs');
 const { sanitizeText, inlineSecretLine } = require('./sanitize.cjs');
 const { nowIso } = require('./fsutil.cjs');
 const statusModule = require('./status.cjs');
+const gates = require('./gates.cjs');
 
 const EXIT = { OK: 0, FAILED: 1, INVALID: 4 };
 class Refusal extends Error {
@@ -77,10 +78,24 @@ function usablePrd(root, t) {
   if (!statusModule.usablePrd(assoc.prdResult)) die(`${assoc.prd}: PRD is draft; complete the authorized breakdown before starting (expected ticketed or built)`, { prefix: 'pincer' });
   return assoc;
 }
-function modeFor(root, prd) {
+// The mode of the ticket's PRD. In changes mode the command passes the shared
+// guard (docs/runtime-contracts.md, "Command gates") before anything is written
+// or launched; the guard's binding carries the change, current agreement and
+// legacy receipts for readiness, attempts and closure.
+const gateExit = code => (code === 'STATE_BUSY' ? 3 : ['INPUT_INVALID', 'INVENTORY_INVALID', 'COVERAGE_INVALID', 'MALFORMED', 'UNSUPPORTED_SCHEMA', 'HISTORY_INVALID', 'STATE_INCOMPLETE'].includes(code) ? EXIT.INVALID : EXIT.FAILED);
+function modeFor(root, prd, { command, ticket } = {}) {
   const bind = identity.loadBinding(root, { prd });
   if (bind.binding && !bind.code) return { mode: 'migrated', binding: bind.binding };
   if (bind.code === 'CHANGE_REQUIRED') return { mode: 'legacy' };
+  if (bind.code === 'CHANGES_MODE') {
+    try {
+      const g = gates.guard(root, { command, ticket: ticket ? { file: ticket.file, fields: ticket.fields } : null, prd });
+      return { mode: 'changes', binding: g.binding, guard: g };
+    } catch (error) {
+      if (error && error.refusal) die(`${error.code}: ${error.message}`, { prefix: 'pincer', exit: gateExit(error.code), code: error.code });
+      throw error;
+    }
+  }
   die(`${bind.code}: ${bind.problem}`, { prefix: 'pincer', exit: EXIT.INVALID, code: bind.code });
   return null;
 }
@@ -101,7 +116,7 @@ function migratedReadiness(root, t, binding, inputs) {
     if (before) changedPaths = source.diffManifests(before, inputs.manifest);
   }
   const legacyReceipt = (binding.legacy_receipts && binding.legacy_receipts[t.id]) || (t.fields.verified || t.fields.last_check ? { verified: t.fields.verified, last_check: t.fields.last_check } : null);
-  const r = readiness.migratedTicketReadiness({ text: t.text, fields: t.fields, timeout: t.timeout, attempt, legacyReceipt, current: inputs.current, sourceProblems: inputs.manifest.problems, changedPaths, contextKey: key, pointedId: inputs.index ? inputs.index.current[key] || null : null });
+  const r = readiness.migratedTicketReadiness({ text: t.text, fields: t.fields, timeout: t.timeout, attempt, legacyReceipt, current: inputs.current, sourceProblems: inputs.manifest.problems, changedPaths, contextKey: key, pointedId: inputs.index ? inputs.index.current[key] || null : null, mode: binding.mode || 'migrated', strict: Boolean(binding.strict) });
   r.attempt = attempt;
   return r;
 }
@@ -125,14 +140,14 @@ function bind(root, input, ref) {
 function start(root, input, { quiet = false } = {}) {
   const t = resolve(root, input);
   const assoc = usablePrd(root, t);
-  const { mode, binding } = modeFor(root, assoc.prd);
+  const { mode, binding } = modeFor(root, assoc.prd, { command: 'start', ticket: t });
   const st = t.fields.status;
   if (st === 'in_progress') {
     if (!t.fields.prd) writeTicket(root, t.file, fmSet(t.text, 'prd', assoc.prd));
     return { out: quiet ? '' : `${t.id} already in progress (started ${t.fields.started || ''})\n`, mode, binding };
   }
   if (st === 'done') die(`${t.id} is already done`);
-  const inputs = mode === 'migrated' ? currentInputs(root, binding) : null;
+  const inputs = mode !== 'legacy' ? currentInputs(root, binding) : null;
   for (const dep of parse.dependencies(t.fields)) {
     const df = parse.ticketFile(root, dep);
     if (df.problem) die(df.problem);
@@ -168,8 +183,12 @@ function executeLegacy(root, block) {
 async function verify(root, input, { write = process.stdout, error = process.stderr } = {}) {
   const t0 = resolve(root, input);
   const assoc = usablePrd(root, t0);
-  const { mode, binding } = modeFor(root, assoc.prd);
-  if (t0.fields.status === 'open') { const s = start(root, t0.id); write.write(s.out); }
+  const { mode, binding } = modeFor(root, assoc.prd, { command: 'verify', ticket: t0 });
+  if (t0.fields.status === 'open') {
+    // A verify on an open ticket starts it; in changes mode that needs an active change.
+    if (mode === 'changes') modeFor(root, assoc.prd, { command: 'start', ticket: t0 });
+    const s = start(root, t0.id); write.write(s.out);
+  }
   const t = load(root, t0.file, t0.id);
   if (mode === 'legacy') return verifyLegacy(root, t, write, error);
   return verifyMigrated(root, t, binding, write, error);
@@ -215,11 +234,14 @@ async function verifyMigrated(root, t, binding, write, error) {
   const commands = parse.verificationCommands(t.text);
   const secretLine = inlineSecretLine(commands);
   if (secretLine) die(`${t.file}: Verification block line ${secretLine} assigns a secret-like literal; reference it from the environment instead (the block is recorded as display text)`, { exit: EXIT.INVALID, code: 'INPUT_INVALID' });
-  write.write(`── ${id} verification ──\n`);
-  for (const c of commands) write.write(`  $ ${sanitizeText(c).text}\n`);
-  const context = { kind: 'ticket', change: binding.change, prd: binding.prd, prd_revision: binding.prd_revision, base: binding.base, ticket: id, ticket_digest: parse.ticketDigest(t.text) };
-  const result = await runner.runAttempt({ root, context, commands, timeoutSeconds: t.timeout, command: `verify ${id}` });
-  if (result.code) die(`${result.code}: ${result.problem}`, { prefix: 'pincer', exit: result.code === 'STATE_BUSY' ? 3 : EXIT.INVALID, code: result.code });
+  const announce = () => { write.write(`── ${id} verification ──\n`); for (const c of commands) write.write(`  $ ${sanitizeText(c).text}\n`); };
+  const contextFor = b => ({ kind: 'ticket', change: b.change, prd: b.prd, prd_revision: b.prd_revision, base: b.base, ticket: id, ticket_digest: parse.ticketDigest(t.text), ...(b.agreement ? { agreement: b.agreement } : {}), ...(b.strict ? { inventory: b.inventory, coverage: b.coverage } : {}) });
+  // In changes mode the guard runs again under the runner's lock (docs/runtime-contracts.md,
+  // "Command gates"): a transition, revision or authorization committed since the
+  // pre-launch evaluation refuses the attempt or is the agreement it records.
+  const revalidate = binding.mode === 'changes' ? () => contextFor(gates.guard(root, { command: 'verify', ticket: { file: t.file, fields: t.fields } }).binding) : null;
+  const result = await runner.runAttempt({ root, context: contextFor(binding), commands, timeoutSeconds: t.timeout, command: `verify ${id}`, revalidate, announce });
+  if (result.code) die(`${result.code}: ${result.problem}`, { prefix: 'pincer', exit: result.refused ? gateExit(result.code) : result.code === 'STATE_BUSY' ? 3 : EXIT.INVALID, code: result.code });
   const a = result.attempt;
   const logs = `${state.RUNTIME_DIR}/attempts/${a.id}/`;
   if (a.outcome === 'passed') {
@@ -238,7 +260,7 @@ async function done(root, input, io = {}) {
   const write = io.write || process.stdout, error = io.error || process.stderr;
   const t = resolve(root, input);
   const assoc = usablePrd(root, t);
-  const { mode, binding } = modeFor(root, assoc.prd);
+  const { mode, binding } = modeFor(root, assoc.prd, { command: 'done', ticket: t });
   const id = t.id, st = t.fields.status;
   if (st !== 'in_progress' && st !== 'done') die(`${id} is '${st}' — run 'scripts/pincer-ticket.sh verify ${id}' first`);
   if (mode === 'legacy') return doneLegacy(root, t, write, error);

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

@@ -0,0 +1,158 @@
+'use strict';
+// PINCER runtime — evaluation locators (docs/runtime-contracts.md, "Evaluation
+// locator"). In changes mode the evaluations of a change are located by
+// `.prd/evidence/changes/<change-id>.json`, tracked in git, appended only by
+// `evidence export` through a transaction. It lives under the fixed source
+// exclusion, is listed in no manifest (no digest refers to itself), and is one
+// of the paths allowed to follow the candidate. Root NOTES.md stays a human
+// summary of whichever change was evaluated last; the locator is the identity.
+const fs = require('node:fs');
+const path = require('node:path');
+const parse = require('./parse.cjs');
+const evidence = require('./evidence.cjs');
+const transaction = require('./transaction.cjs');
+const { readJson, tryGit } = require('./fsutil.cjs');
+
+const SCHEMA = 1;
+const DIR = '.prd/evidence/changes';
+const KEYS = ['schema', 'change', 'evaluations'];
+const ENTRY_KEYS = ['candidate', 'base', 'prd', 'prd_revision', 'agreement', 'manifest', 'recorded'];
+const SHA256 = /^[0-9a-f]{64}$/;
+const isObject = v => v !== null && typeof v === 'object' && !Array.isArray(v);
+const file = id => `${DIR}/${id}.json`;
+
+function validate(doc, id) {
+  const bad = p => ({ code: 'MALFORMED', problem: `${file(id)}: ${p}` });
+  if (!isObject(doc)) return bad('locator must be a JSON object');
+  if (doc.schema !== SCHEMA) return { code: 'UNSUPPORTED_SCHEMA', problem: `${file(id)}: unsupported evaluation locator schema ${JSON.stringify(doc.schema)}` };
+  for (const k of Object.keys(doc)) if (!KEYS.includes(k)) return bad(`unknown key "${k}"`);
+  for (const k of KEYS) if (!(k in doc)) return bad(`missing key "${k}"`);
+  if (doc.change !== id) return bad(`locator names change "${doc.change}", not ${id}`);
+  if (!Array.isArray(doc.evaluations)) return bad('evaluations must be an array');
+  for (const [i, e] of doc.evaluations.entries()) {
+    if (!isObject(e)) return bad(`evaluations[${i}] must be an object`);
+    for (const k of Object.keys(e)) if (!ENTRY_KEYS.includes(k)) return bad(`evaluations[${i}].${k} is not allowed`);
+    for (const k of ENTRY_KEYS) if (!(k in e)) return bad(`evaluations[${i}].${k} is missing`);
+    if (!parse.HEX40.test(e.candidate) || !parse.HEX40.test(e.base)) return bad(`evaluations[${i}]: candidate and base must be full 40-hex commit IDs`);
+    if (!parse.PRD_REF.test(e.prd)) return bad(`evaluations[${i}]: prd must be .prd/prd-vN.md`);
+    if (!SHA256.test(e.prd_revision) || !SHA256.test(e.agreement)) return bad(`evaluations[${i}]: prd_revision and agreement must be 64-hex digests`);
+    if (e.manifest !== `.prd/evidence/prd-v${e.prd.match(parse.PRD_REF)[1]}/${e.candidate}/manifest.json`) return bad(`evaluations[${i}]: manifest must be .prd/evidence/prd-v<N>/${e.candidate}/manifest.json for ${e.prd}`);
+    if (!parse.TIMESTAMP.test(e.recorded)) return bad(`evaluations[${i}]: recorded must be an ISO UTC timestamp`);
+  }
+  return null;
+}
+// { locator } (possibly empty), or { code, problem }. A missing file is an empty locator.
+function read(root, id) {
+  const r = readJson(path.join(root, file(id)));
+  if (r.error === 'missing') return { locator: { schema: SCHEMA, change: id, evaluations: [] }, missing: true };
+  if (r.error) return { code: 'MALFORMED', problem: `${file(id)}: ${r.error}` };
+  const invalid = validate(r.data, id);
+  if (invalid) return invalid;
+  return { locator: r.data };
+}
+const latest = locator => (locator.evaluations.length ? locator.evaluations[locator.evaluations.length - 1] : null);
+
+// Append an evaluation reference (after the manifest was written and validated).
+function append(root, id, entry) {
+  try {
+    const out = transaction.run(root, { command: `evidence export ${id}` }, ctx => {
+      const r = read(root, id);
+      if (r.code) ctx.refuse(r.code, r.problem);
+      const doc = r.locator;
+      const same = doc.evaluations.find(e => e.candidate === entry.candidate && e.manifest === entry.manifest && e.agreement === entry.agreement && e.prd_revision === entry.prd_revision && e.base === entry.base);
+      if (same) return { action: 'unchanged', entry: same };
+      doc.evaluations.push(entry);
+      const invalid = validate(doc, id);
+      if (invalid) ctx.refuse(invalid.code, invalid.problem);
+      ctx.write(file(id), doc);
+      return { action: 'recorded', entry };
+    });
+    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;
+  }
+}
+
+// The paths that may differ from `candidate` (docs/runtime-contracts.md,
+// "Evaluation locator"): NOTES.md, every locator under .prd/evidence/changes/ that
+// parses and validates for its own id, and, for each of their entries naming this
+// candidate whose manifest validates with file digests for its candidate, base and
+// PRD, that manifest and the files it lists. The set is computed from validated
+// content, never from a directory or filename pattern: an unlisted file inside an
+// evidence directory, an altered listed artifact and an unreadable or misnamed
+// locator are candidate changes. Returns a Set of repository-relative paths.
+function followers(root, candidate) {
+  const allowed = new Set(['NOTES.md']);
+  let names = [];
+  try { names = fs.readdirSync(path.join(root, DIR)).filter(n => n.endsWith('.json')); } catch { names = []; }
+  for (const name of names.sort()) {
+    const id = name.slice(0, -'.json'.length);
+    const r = read(root, id);
+    if (r.code || r.missing) continue;
+    allowed.add(file(id));
+    for (const e of r.locator.evaluations) {
+      if (e.candidate !== candidate) continue;
+      const opts = { files: true, candidate: e.candidate, base: e.base, prd: e.prd };
+      const problems = evidence.validate(path.resolve(root, e.manifest), opts, root);
+      if (problems.length || !Array.isArray(opts.list)) continue;
+      for (const listed of opts.list) allowed.add(listed);
+    }
+  }
+  return allowed;
+}
+
+// The candidate of a change from its locator, in the shape status reports for
+// NOTES.md: { text, state: 'current' | 'stale' | 'missing', candidate, base,
+// manifest, entry }. Current means: the latest entry's manifest validates for its
+// candidate, base and PRD, the candidate is an ancestor of HEAD, and the diff
+// from the candidate to HEAD plus the dirty tree contain nothing but the
+// candidate's followers (NOTES.md, valid locators, validated listed artifacts).
+function current(root, record) {
+  const r = read(root, record.change);
+  if (r.code) return { text: `stale: ${r.problem}`, state: 'stale', problem: r };
+  const entry = latest(r.locator);
+  if (!entry) return { text: `missing (no evaluation recorded in ${file(record.change)})`, state: 'missing' };
+  const base = { candidate: entry.candidate, base: entry.base, manifest: entry.manifest, entry, fields: { prd: entry.prd, candidate: entry.candidate, base: entry.base, evidence: entry.manifest } };
+  if (entry.prd !== record.prd) return { ...base, text: `stale: the evaluation is for ${entry.prd}, not ${record.prd}`, state: 'stale' };
+  const ok = args => !tryGit(root, args).error;
+  if (!ok(['rev-parse', '--verify', `${entry.candidate}^{commit}`]) || !ok(['rev-parse', '--verify', `${entry.base}^{commit}`]) ||
+      !ok(['merge-base', '--is-ancestor', entry.base, entry.candidate]) || !ok(['merge-base', '--is-ancestor', entry.candidate, 'HEAD'])) {
+    return { ...base, text: 'stale: evaluation commits or ancestry unavailable', state: 'stale' };
+  }
+  const opts = { files: true, candidate: entry.candidate, base: entry.base, prd: entry.prd };
+  const problems = evidence.validate(path.resolve(root, entry.manifest), opts, root);
+  if (problems.length) return { ...base, text: `stale: evidence invalid: ${problems[0]}`, state: 'stale' };
+  let manifestDoc = null;
+  try { manifestDoc = JSON.parse(fs.readFileSync(path.resolve(root, entry.manifest), 'utf8')); } catch { manifestDoc = null; }
+  if (!manifestDoc || !manifestDoc.change || manifestDoc.change.id !== record.change) return { ...base, text: `stale: ${entry.manifest} records change ${manifestDoc && manifestDoc.change ? manifestDoc.change.id : 'none'}, not ${record.change}`, state: 'stale' };
+  for (const f of opts.list) {
+    const tracked = tryGit(root, ['ls-files', '--error-unmatch', '--', f]);
+    if (tracked.error || !tracked.out.trim()) return { ...base, text: `stale: evidence not tracked: ${f}`, state: 'stale' };
+  }
+  const set = followers(root, entry.candidate);
+  const allowed = p => set.has(p);
+  const diff = tryGit(root, ['diff', '--name-only', '--relative', entry.candidate, 'HEAD']);
+  if (diff.error) return { ...base, text: 'stale: evaluation commits or ancestry unavailable', state: 'stale' };
+  const offending = diff.out.split('\n').filter(l => l && !allowed(l))[0];
+  if (offending) return { ...base, text: `stale: candidate changed after evaluation: ${offending}`, state: 'stale' };
+  const dirty = tryGit(root, ['status', '--porcelain', '--untracked-files=all']);
+  if (dirty.error) return { ...base, text: 'stale: git status failed', state: 'stale' };
+  const dirtyPath = dirty.out.split('\n').filter(Boolean).map(l => l.slice(3).replace(/^"(.*)"$/, '$1')).filter(p => !allowed(p))[0];
+  if (dirtyPath) return { ...base, text: `stale: working tree has changes outside the candidate's evidence: ${dirtyPath}`, state: 'stale' };
+  return { ...base, text: `current (${entry.candidate})`, state: 'current' };
+}
+// The Evidence line for the locator's latest manifest, independent of currency.
+function evidenceLine(root, record) {
+  const r = read(root, record.change);
+  if (r.code) return { manifest: file(record.change), ok: false, reason: r.problem, schema: null };
+  const entry = latest(r.locator);
+  if (!entry) return null;
+  const problems = evidence.validate(path.resolve(root, entry.manifest), { candidate: entry.candidate, base: entry.base, prd: entry.prd }, root);
+  let schema = null;
+  try { schema = JSON.parse(fs.readFileSync(path.resolve(root, entry.manifest), 'utf8')).schema; } catch { schema = null; }
+  return { manifest: entry.manifest, ok: problems.length === 0, reason: problems[0] || null, schema };
+}
+
+module.exports = { SCHEMA, DIR, file, validate, read, latest, append, followers, current, evidenceLine };