pincer-workflow 0.4.0 → 0.5.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/identity.cjs

@@ -0,0 +1,146 @@
+'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');
+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 } = {}) {
+  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 };
+  }
+  if (existing && (existing.binding.prd !== prd || existing.binding.change !== id)) {
+    if (!replace) return { code: 'AMBIGUOUS', problem: `${existing.file} already binds ${existing.binding.prd} as change "${existing.binding.change}"; one change per worktree — pass --replace to replace it (its attempts stay in local history)` };
+    fs.unlinkSync(path.join(root, existing.file));
+    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: 'replaced', replaced: existing.file, notes };
+  }
+  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/lifecycle.cjs

@@ -0,0 +1,289 @@
+'use strict';
+// PINCER runtime — ticket lifecycle (docs/runtime-contracts.md, "Modes"). The
+// only writer of ticket lifecycle fields. Legacy mode reproduces the v0.4.1
+// contract word for word (receipts in the ticket, `done` re-runs the check);
+// migrated mode records attempts under .pincer/runtime/ and `done` consumes the
+// current passing attempt without rewriting receipts.
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const parse = require('./parse.cjs');
+const identity = require('./identity.cjs');
+const source = require('./source.cjs');
+const state = require('./state.cjs');
+const readiness = require('./readiness.cjs');
+const runner = require('./runner.cjs');
+const { sanitizeText, inlineSecretLine } = require('./sanitize.cjs');
+const { nowIso } = require('./fsutil.cjs');
+const statusModule = require('./status.cjs');
+
+const EXIT = { OK: 0, FAILED: 1, INVALID: 4 };
+class Refusal extends Error {
+  constructor(message, { prefix = 'pincer-ticket', exit = EXIT.FAILED, code } = {}) { super(message); this.prefix = prefix; this.exit = exit; this.reasonCode = code; }
+}
+const die = (message, options) => { throw new Refusal(message, options); };
+
+// --- Frontmatter writes (the fm_set / fm_unset contract) --------------------
+// Replace a field inside the frontmatter keeping an inline comment, or add it
+// before the closing ---. Values are written as `key: value`.
+function fmSet(text, key, value) {
+  const rows = parse.lines(text);
+  let done = false, closed = false;
+  const out = rows.map((line, i) => {
+    if (i === 0 || closed) return line;
+    if (!done && line.startsWith(`${key}:`)) {
+      done = true;
+      const hash = line.indexOf('#');
+      return hash === -1 ? `${key}: ${value}` : `${key}: ${value}   ${line.slice(hash)}`;
+    }
+    if (line === '---') { closed = true; return done ? line : `${key}: ${value}\n---`; }
+    return line;
+  });
+  if (!done && !closed) out.push(`${key}: ${value}`);
+  return `${out.join('\n')}\n`;
+}
+function fmUnset(text, key) {
+  const rows = parse.lines(text);
+  let closed = false;
+  const out = rows.filter((line, i) => {
+    if (i === 0) return true;
+    if (closed) return true;
+    if (line === '---') { closed = true; return true; }
+    return !line.startsWith(`${key}:`);
+  });
+  return `${out.join('\n')}\n`;
+}
+const readTicket = (root, file) => fs.readFileSync(path.join(root, file), 'utf8');
+const writeTicket = (root, file, text) => fs.writeFileSync(path.join(root, file), text);
+
+// --- Resolution --------------------------------------------------------------
+function resolve(root, input) {
+  const set = parse.validateTicketSet(root);
+  if (!set.ok) die(set.problems.map(p => (set.file ? `${set.file}: ${p}` : p)).join('\n'), { exit: EXIT.INVALID, code: 'INPUT_INVALID' });
+  const tf = parse.ticketFile(root, input);
+  if (tf.problem) die(tf.problem, { exit: EXIT.INVALID, code: 'INPUT_INVALID' });
+  return load(root, tf.file, tf.id);
+}
+function load(root, file, id) {
+  const text = readTicket(root, file);
+  const v = parse.validateTicket(file, text);
+  if (!v.ok) die(v.problems.map(p => `${file}: ${p}`).join('\n'), { exit: EXIT.INVALID, code: 'INPUT_INVALID' });
+  return { id: id || v.fields.ticket, file, text, fields: v.fields, timeout: v.timeout };
+}
+// usable_ticket_prd: association plus a ticketed/built PRD.
+function usablePrd(root, t) {
+  const assoc = statusModule.ticketPrd(root, t.file, t.fields);
+  if (assoc.problem) die(assoc.problem, { prefix: 'pincer' });
+  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) {
+  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' };
+  die(`${bind.code}: ${bind.problem}`, { prefix: 'pincer', exit: EXIT.INVALID, code: bind.code });
+  return null;
+}
+
+// --- Readiness of a dependency or of the ticket itself ------------------------
+function currentInputs(root, binding) {
+  const manifest = source.snapshot(root);
+  const indexRead = state.exists(root) ? state.readIndex(root) : { index: null };
+  if (indexRead.error) die(indexRead.error, { prefix: 'pincer', exit: EXIT.INVALID, code: 'INPUT_INVALID' });
+  return { manifest, index: indexRead.index, current: { prdRevision: binding.prd_revision, sourceDigest: manifest.digest } };
+}
+function migratedReadiness(root, t, binding, inputs) {
+  const key = state.contextKey({ kind: 'ticket', change: binding.change, ticket: t.id });
+  const attempt = inputs.index ? state.inspectArtifacts(root, state.latestAttempt(root, key, inputs.index)) : null;
+  let changedPaths = [];
+  if (attempt && attempt.source && inputs.manifest.digest && attempt.source.after !== inputs.manifest.digest) {
+    const before = source.readManifest(root, attempt.source.after);
+    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 });
+  r.attempt = attempt;
+  return r;
+}
+function ticketReady(root, t, mode, binding, inputs) {
+  if (mode === 'legacy') { const r = readiness.legacyTicketReadiness(t.text, t.fields); return r.ready ? null : r.legacyMessage; }
+  const r = migratedReadiness(root, t, binding, inputs);
+  return r.ready ? null : `${r.reasons[0].code}: ${r.reasons[0].detail} — ${r.reasons[0].next}`;
+}
+
+// --- Commands ----------------------------------------------------------------
+function bind(root, input, ref) {
+  const t = resolve(root, input);
+  const v = parse.validatePrd(root, ref);
+  if (!v.ok) die(`${v.file ? `${v.file}: ` : ''}${v.problems[0]}`, { prefix: 'pincer' });
+  const existing = t.fields.prd || '';
+  if (existing && existing !== ref) die(`${t.id} already references ${existing}; refusing to rebind it to ${ref}`);
+  if (existing !== ref) writeTicket(root, t.file, fmSet(t.text, 'prd', ref));
+  return { out: `${t.id} bound to PRD ${ref}\n` };
+}
+
+function start(root, input, { quiet = false } = {}) {
+  const t = resolve(root, input);
+  const assoc = usablePrd(root, t);
+  const { mode, binding } = modeFor(root, assoc.prd);
+  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;
+  for (const dep of parse.dependencies(t.fields)) {
+    const df = parse.ticketFile(root, dep);
+    if (df.problem) die(df.problem);
+    const d = load(root, df.file, dep);
+    if (d.fields.status !== 'done') die(`${t.id} depends on ${dep}, which is '${d.fields.status}' — finish ${dep} first (or fix depends_on in ${t.file})`);
+    const depAssoc = usablePrd(root, d);
+    if (depAssoc.prd !== assoc.prd) die(`${t.id} references ${assoc.prd} but dependency ${dep} references ${depAssoc.prd}`);
+    const problem = ticketReady(root, d, mode, binding, inputs);
+    if (problem) die(`${t.id} depends on ${dep}: ${problem}`);
+  }
+  let text = t.text;
+  if (!t.fields.prd) text = fmSet(text, 'prd', assoc.prd);
+  text = fmSet(text, 'status', 'in_progress');
+  if (!t.fields.started) text = fmSet(text, 'started', nowIso());
+  writeTicket(root, t.file, text);
+  const started = parse.frontmatterField(text, 'started');
+  return { out: `▶ ${t.id} started ${started} — ${t.file}\n`, mode, binding };
+}
+
+// Legacy execution: the block runs with inherited stdio in its own process group;
+// SIGINT/SIGTERM to the runtime terminate it and are reported as interrupted.
+function executeLegacy(root, block) {
+  return new Promise(resolve => {
+    const child = spawn(runner.runnerInfo().shell, ['-eo', 'pipefail', '-c', block], { cwd: root, detached: true, stdio: 'inherit', env: process.env });
+    let interrupted = null;
+    const onSignal = signal => { interrupted = signal; try { process.kill(-child.pid, 'SIGTERM'); } catch { try { child.kill('SIGTERM'); } catch { /* gone */ } } setTimeout(() => { try { process.kill(-child.pid, 'SIGKILL'); } catch { /* gone */ } }, runner.GRACE_MS).unref(); };
+    process.on('SIGINT', onSignal); process.on('SIGTERM', onSignal);
+    child.on('error', error => { process.off('SIGINT', onSignal); process.off('SIGTERM', onSignal); resolve({ code: 127, signal: null, interrupted, error: error.message }); });
+    child.on('exit', (code, signal) => { process.off('SIGINT', onSignal); process.off('SIGTERM', onSignal); resolve({ code, signal, interrupted }); });
+  });
+}
+
+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 t = load(root, t0.file, t0.id);
+  if (mode === 'legacy') return verifyLegacy(root, t, write, error);
+  return verifyMigrated(root, t, binding, write, error);
+}
+
+async function verifyLegacy(root, t, write, error) {
+  const id = t.id, file = t.file;
+  if (t.fields.status === 'done') write.write(`${id} is done — re-running its check and updating the latest outcome\n`);
+  const commands = parse.verificationCommands(t.text);
+  const block = parse.blockText(t.text);
+  let text = fmUnset(t.text, 'verified');
+  const hash = parse.legacyBlockHash(t.text);
+  text = fmSet(text, 'last_check', `${nowIso()} running ${hash}`);
+  writeTicket(root, file, text);
+  if (!commands.some(c => !/^[ \t]*(#.*)?$/.test(c))) die(`no runnable command in the Verification block of ${file}`);
+  write.write(`── ${id} verification ──\n`);
+  for (const c of commands) write.write(`  $ ${c}\n`);
+  const result = await executeLegacy(root, block);
+  const stamp = outcome => writeTicket(root, file, fmSet(readTicket(root, file), 'last_check', `${nowIso()} ${outcome} ${hash}`));
+  if (result.interrupted) { stamp('interrupted'); return { exit: 130 }; }
+  const rc = result.code === null ? 1 : result.code;
+  if (rc !== 0) {
+    stamp('failed');
+    error.write(`✗ ${id} verification FAILED (exit ${rc}) — failure recorded in last_check of ${file}; any prior successful receipt was revoked. Fix, then re-run verify.\n`);
+    return { exit: rc };
+  }
+  const after = readTicket(root, file);
+  if (parse.legacyBlockHash(after) !== hash) { stamp('failed'); die('Verification block changed during execution — re-run verify'); }
+  const v = parse.validateTicket(file, after);
+  let usable = v.ok;
+  if (usable) { try { usablePrd(root, { file, fields: v.fields }); } catch { usable = false; } }
+  if (!usable) { stamp('failed'); die('ticket became invalid during verification — fix it and re-run verify'); }
+  let done = fmSet(after, 'last_check', `${nowIso()} passed ${hash}`);
+  done = fmSet(done, 'verified', `${nowIso()} ${hash}`);
+  writeTicket(root, file, done);
+  write.write(`✓ ${id} verified — receipt: ${parse.frontmatterField(done, 'verified')}\n`);
+  return { exit: 0 };
+}
+
+async function verifyMigrated(root, t, binding, write, error) {
+  const id = t.id;
+  if (t.fields.status === 'done') write.write(`${id} is done — re-running its check and recording the latest outcome\n`);
+  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 a = result.attempt;
+  const logs = `${state.RUNTIME_DIR}/attempts/${a.id}/`;
+  if (a.outcome === 'passed') {
+    write.write(`✓ ${id} verified — attempt ${a.id} passed (source ${a.source.after.slice(0, 12)}, logs ${logs})\n`);
+    return { exit: 0, attempt: a };
+  }
+  const why = a.outcome === 'failed' ? `FAILED (exit ${a.exit_code ?? a.signal})` : a.outcome === 'timed_out' ? `TIMED OUT after ${a.check.timeout_seconds} s` : a.outcome === 'interrupted' ? 'INTERRUPTED' : `ERROR: ${a.error}`;
+  error.write(`✗ ${id} verification ${why} — recorded as attempt ${a.id} (logs ${logs}); any prior passing attempt is superseded. Fix, then re-run verify.\n`);
+  return { exit: runner.exitFor(a), attempt: a };
+}
+
+const slugWords = file => path.basename(file, '.md').replace(/^T-[0-9]+-/, '').replace(/-/g, ' ');
+const closeHint = (id, file) => `✓ ${id} done. Inspect staged work, stage only this ticket's paths, review git diff --cached, then commit: ${id}: ${slugWords(file)}\n`;
+
+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 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);
+  return doneMigrated(root, t, binding, write);
+}
+
+async function doneLegacy(root, t, write, error) {
+  const id = t.id, file = t.file, st = t.fields.status;
+  const rec = t.fields.verified || '';
+  if (!rec) die(`no verification receipt on ${id} — run 'scripts/pincer-ticket.sh verify ${id}' and get a green check first`);
+  const cur = parse.legacyBlockHash(t.text);
+  const recHash = rec.split(/\s+/).pop();
+  if (recHash !== cur) die(`receipt hash ${recHash} does not match the current Verification block (${cur}): the check changed after it passed — run 'scripts/pincer-ticket.sh verify ${id}' again`);
+  const u = parse.unticked(t.text);
+  if (u.length) die(`unticked acceptance criteria on ${id}:\n${u.join('\n')}\nTick each verified criterion; a criterion that was cut is a scope change to record in the PRD, not a box to skip.`);
+  const result = await verifyLegacy(root, t, write, error);
+  if (result.exit !== 0) return result;
+  const after = load(root, file, id);
+  const u2 = parse.unticked(after.text);
+  if (u2.length) die(`unticked acceptance criteria on ${id} after verification:\n${u2.join('\n')}`);
+  if (st === 'done') { write.write(`${id} already done — current check passed\n`); return { exit: 0 }; }
+  let text = fmSet(after.text, 'status', 'done');
+  text = fmSet(text, 'finished', nowIso());
+  writeTicket(root, file, text);
+  write.write(closeHint(id, file));
+  return { exit: 0 };
+}
+
+// Migrated closure consumes the latest passing attempt against current inputs
+// and checked criteria; it never launches the check and writes the ticket once.
+async function doneMigrated(root, t, binding, write) {
+  const id = t.id, file = t.file, st = t.fields.status;
+  const inputs = currentInputs(root, binding);
+  const r = migratedReadiness(root, t, binding, inputs);
+  if (!r.ready) {
+    const first = r.reasons[0];
+    const lines = r.reasons.map(x => `${x.code}: ${x.detail}`);
+    die(`${id} cannot close — ${lines.join('; ')}\nnext: ${first.next}`, { code: first.code });
+  }
+  if (st === 'done') { write.write(`${id} already done — current attempt ${r.attempt.id} passed\n`); return { exit: 0 }; }
+  let text = fmSet(t.text, 'status', 'done');
+  text = fmSet(text, 'finished', nowIso());
+  writeTicket(root, file, text);
+  write.write(closeHint(id, file));
+  return { exit: 0 };
+}
+
+module.exports = { Refusal, fmSet, fmUnset, bind, start, verify, done, migratedReadiness, currentInputs };

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

@@ -0,0 +1,127 @@
+'use strict';
+// PINCER runtime — migration (docs/runtime-contracts.md, "Migration and
+// rollback"). Preview is read-only; apply backs up every authored file it
+// changes, strips legacy receipts into the binding's legacy_receipts (history,
+// never runtime evidence), ignores .pincer/, and writes the binding last.
+// Conflicts fail closed before the first write; repeated apply is a no-op.
+const fs = require('node:fs');
+const path = require('node:path');
+const parse = require('./parse.cjs');
+const identity = require('./identity.cjs');
+const statusModule = require('./status.cjs');
+const { fmUnset } = require('./lifecycle.cjs');
+const { nowIso, atomicWrite } = require('./fsutil.cjs');
+
+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');
+}
+
+// Compute the plan. Returns { prd, change, conflicts: [{code, detail}], binding:
+// { file, exists, action }, tickets: [{file, id, verified, last_check}],
+// gitignore: boolean (needs the line), alreadyMigrated }.
+function plan(root, { prd, change, authorization = null } = {}) {
+  const conflicts = [];
+  const conflict = (code, detail) => conflicts.push({ code, detail });
+  const prdResult = parse.validatePrd(root, prd);
+  if (!prdResult.ok) { conflict('INPUT_INVALID', `${prdResult.file || prd}: ${prdResult.problems[0]}`); return { prd, conflicts }; }
+  const id = change || `prd-v${prd.match(parse.PRD_REF)[1]}`;
+  if (!identity.CHANGE_ID.test(id)) conflict('INPUT_INVALID', `change ID must match [a-z0-9][a-z0-9-]{0,63}: ${id}`);
+  if (!identity.head(root)) conflict('UNSUPPORTED_INPUT', 'migration needs a git repository with at least one commit');
+  const bindings = identity.listBindings(root);
+  let existing = null;
+  if (bindings.length > 1) conflict('AMBIGUOUS', `several change bindings under .prd/changes/ (${bindings.map(b => path.basename(b)).join(', ')}); keep exactly one`);
+  else if (bindings.length === 1) {
+    const loaded = identity.loadBinding(root, { prd });
+    if (loaded.code && loaded.code !== 'REVISION_CHANGED' && !loaded.other) conflict(loaded.code === 'UNSUPPORTED_SCHEMA' ? 'UNSUPPORTED_SCHEMA' : 'INPUT_INVALID', loaded.problem);
+    else if (loaded.other) conflict('AMBIGUOUS', `${loaded.file} binds ${loaded.binding.prd}, not ${prd}; one change per worktree — register --replace or remove it first`);
+    else if (loaded.binding && loaded.binding.change !== id) conflict('AMBIGUOUS', `${loaded.file} already binds ${prd} as change "${loaded.binding.change}"; pass --change ${loaded.binding.change}`);
+    else existing = loaded.binding || null;
+  }
+  const set = parse.validateTicketSet(root);
+  if (!set.ok) conflict('INPUT_INVALID', `pincer-ticket: ${set.file ? `${set.file}: ` : ''}${set.problems[0]}`);
+  const tickets = [];
+  if (set.ok) {
+    for (const file of set.files) {
+      const text = fs.readFileSync(path.join(root, file), 'utf8');
+      const fields = parse.validateTicket(file, text).fields;
+      const assoc = statusModule.ticketPrd(root, file, fields);
+      if (assoc.problem) { conflict('INPUT_INVALID', `pincer: ${assoc.problem}`); continue; }
+      if (assoc.prd !== prd) continue;
+      if (fields.verified || fields.last_check) tickets.push({ file, id: fields.ticket, verified: fields.verified || null, last_check: fields.last_check || null, text });
+    }
+  }
+  const gitignore = !gitignoreHas(root);
+  const alreadyMigrated = Boolean(existing) && tickets.length === 0 && !gitignore;
+  const partial = Boolean(existing) && tickets.length > 0;
+  return { prd, change: id, authorization, conflicts, binding: { file: `.prd/changes/${id}.json`, exists: Boolean(existing), existing, action: existing ? (partial ? 'complete' : 'keep') : 'register' }, tickets, gitignore, alreadyMigrated, partial };
+}
+
+function renderPlan(p) {
+  const lines = [];
+  if (p.conflicts.length) {
+    for (const c of p.conflicts) lines.push(`conflict  ${c.code}: ${c.detail}`);
+    lines.push('migration refused: resolve the conflicts above; nothing was written');
+    return lines.join('\n') + '\n';
+  }
+  lines.push(`migration plan for ${p.prd} (change ${p.change})`);
+  if (p.alreadyMigrated) { lines.push('  already migrated: binding present, no legacy receipts remain, .pincer/ ignored'); return lines.join('\n') + '\n'; }
+  if (p.partial) lines.push('  note      an earlier migration was partially applied (binding present, receipts remain); apply completes it');
+  lines.push(`  binding   ${p.binding.file} (${p.binding.exists ? 'present, legacy_receipts extended' : 'new; base = HEAD'})`);
+  for (const t of p.tickets) lines.push(`  ticket    ${t.file}: remove ${[t.verified ? 'verified' : null, t.last_check ? 'last_check' : null].filter(Boolean).join(', ')} → legacy_receipts[${t.id}] (history, not runtime evidence)`);
+  if (!p.tickets.length) lines.push('  tickets   no legacy receipts to import');
+  lines.push(p.gitignore ? `  gitignore add \`${IGNORE_LINE}\`` : '  gitignore already ignores .pincer/');
+  lines.push(`  backups   .pincer/backups/<timestamp>/ for every changed authored file`);
+  if (!p.authorization) lines.push('  note      no --authorization given; registration does not prove human approval');
+  lines.push(`apply with: node scripts/pincer-runtime.cjs migrate --apply --prd ${p.prd}${p.change !== `prd-v${p.prd.match(parse.PRD_REF)[1]}` ? ` --change ${p.change}` : ''}`);
+  return lines.join('\n') + '\n';
+}
+
+// Apply the plan: backups, tickets, .gitignore, then the binding last.
+function apply(root, options) {
+  const p = plan(root, options);
+  if (p.conflicts.length) return { plan: p, applied: false };
+  if (p.alreadyMigrated) return { plan: p, applied: false, already: true };
+  const stamp = nowIso().replace(/[-:]/g, '');
+  const backupDir = path.join(root, '.pincer', 'backups', stamp);
+  const backups = [];
+  const backup = rel => {
+    const src = path.join(root, rel);
+    if (!fs.existsSync(src)) return;
+    const dest = path.join(backupDir, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+    backups.push(`.pincer/backups/${stamp}/${rel}`);
+  };
+  const receipts = {};
+  for (const t of p.tickets) {
+    backup(t.file);
+    receipts[t.id] = { verified: t.verified, last_check: t.last_check };
+    let text = fmUnset(t.text, 'verified');
+    text = fmUnset(text, 'last_check');
+    atomicWrite(path.join(root, t.file), text);
+  }
+  if (p.gitignore) {
+    backup('.gitignore');
+    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 migrate)\n${IGNORE_LINE}\n`);
+  }
+  let binding;
+  if (p.binding.existing) {
+    binding = { ...p.binding.existing, legacy_receipts: { ...p.binding.existing.legacy_receipts, ...receipts } };
+    if (options.authorization) binding.authorization = options.authorization;
+  } else {
+    const registered = identity.register(root, { prd: p.prd, change: p.change, authorization: options.authorization || null });
+    if (registered.code) return { plan: p, applied: false, error: registered.problem, backups };
+    binding = { ...registered.binding, legacy_receipts: receipts };
+  }
+  identity.writeBinding(root, binding);
+  return { plan: p, applied: true, binding, backups, backupDir: backups.length ? `.pincer/backups/${stamp}/` : null };
+}
+
+module.exports = { plan, renderPlan, apply, IGNORE_LINE, gitignoreHas };