pincer-workflow 0.7.0 → 1.0.1

package/template/scripts/pincer/status.cjs

@@ -0,0 +1,173 @@
+'use strict';
+// PINCER engine — where the work stands (docs/engine.md, "Stage gate"), read
+// from harness.json and the artifacts on disk. Read-only: nothing here writes
+// a file or runs a check. Every stage skill runs the gate first.
+const fs = require('node:fs');
+const path = require('node:path');
+const parse = require('./parse.cjs');
+const harnessModule = require('./harness.cjs');
+const models = require('./models.cjs');
+const generate = require('./generate.cjs');
+
+const SCRIPT = 'scripts/pincer-ticket.sh';
+const { STAGES, ALWAYS_ON, HARNESS_FILE } = harnessModule;
+
+// Only a Codex-only install unambiguously chooses dollar-style skill mentions.
+// Mixed installs keep the shared slash spelling; shell paths are never rewritten.
+function commandMentions(root, text) {
+  const platforms = generate.manifestPlatforms(root);
+  return platforms.length === 1 && platforms[0] === 'codex' ? generate.codexMentions(text) : text;
+}
+
+// Is a ticket's receipt current? Lifted from 0.7: the wording is what a done
+// ticket that needs attention has always shown.
+function readiness(text, fields) {
+  const receipt = fields.verified || '';
+  const attempt = fields.last_check || '';
+  const hash = parse.blockHash(text);
+  const fail = (message) => ({ ready: false, message });
+  if (!attempt) return fail('missing latest verification outcome — re-run verify');
+  const parts = attempt.split(/[ \t]+/);
+  if (!(parts.length === 3 && parse.TIMESTAMP.test(parts[0]) && parts[1] === 'passed' && /^[a-f0-9]{12}$/.test(parts[2])) || parts[2] !== hash) {
+    return fail(`latest verification: ${attempt} — re-run verify`);
+  }
+  if (!receipt) return fail('done without a verification receipt — re-run verify');
+  const rparts = receipt.split(/[ \t]+/);
+  if (!(rparts.length === 2 && parse.TIMESTAMP.test(rparts[0]) && /^[a-f0-9]{12}$/.test(rparts[1])) || rparts[1] !== hash) {
+    return fail('stale or malformed verification receipt — re-run verify');
+  }
+  if (parse.unticked(text).length) return fail('unticked acceptance criteria — complete and re-run verify');
+  return { ready: true, message: null };
+}
+
+const idOf = (file) => (path.basename(file).match(/^T-[0-9]+/) || [''])[0];
+const readText = (root, file) => { try { return fs.readFileSync(path.join(root, file), 'utf8'); } catch (error) { return null; } };
+
+function specEntries(root, specsDir) {
+  const dir = path.join(root, specsDir);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((name) => name.endsWith('.md')).sort().map((name) => {
+    const file = path.posix.join(specsDir, name);
+    const text = readText(root, file) || '';
+    return { file, status: parse.frontmatterField(text, 'status') || null };
+  });
+}
+function ticketEntry(root, file) {
+  const text = readText(root, file);
+  const entry = { id: idOf(file), file, status: null, started: null, verified: null, lastCheck: null, accepted: null, acceptedBy: null, ready: false, problem: null, depends: [] };
+  if (text === null) { entry.problem = 'cannot read the file'; return entry; }
+  const v = parse.validateTicket(file, text);
+  const fields = v.fields;
+  entry.status = fields.status || null;
+  entry.started = fields.started || null;
+  entry.verified = fields.verified || null;
+  entry.lastCheck = fields.last_check || null;
+  entry.accepted = fields.accepted || null;
+  entry.acceptedBy = fields.accepted_by || null;
+  entry.depends = parse.dependencies(fields);
+  if (!v.ok) { entry.problem = v.problems.join('; '); return entry; }
+  entry.id = fields.ticket;
+  const r = readiness(text, fields);
+  entry.ready = r.ready;
+  entry.readiness = r.message;
+  return entry;
+}
+function manifests(root, evidenceDir) {
+  const dir = path.join(root, evidenceDir);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).sort()
+    .map((name) => path.posix.join(evidenceDir, name, 'manifest.json'))
+    .filter((file) => fs.existsSync(path.join(root, file)));
+}
+
+// The whole picture, as data. `harness` is null without a valid agreement;
+// `harnessProblem` says why when the file exists but does not validate.
+function gather(root) {
+  const report = { name: path.basename(root), harness: null, harnessProblem: null, stages: {}, models: null, specs: [], tickets: [], evidence: [], warnings: [], next: '' };
+  const loaded = harnessModule.load(root);
+  let homes = harnessModule.homes(null);
+  if (loaded.ok) {
+    report.harness = loaded.harness;
+    if (loaded.harness.project.name) report.name = loaded.harness.project.name;
+    for (const name of STAGES) report.stages[name] = harnessModule.stageOn(loaded.harness, name) ? 'on' : 'off';
+    report.models = models.effective(loaded.harness, generate.libraryDir(root));
+    homes = harnessModule.homes(loaded.harness);
+  } else if (!loaded.missing) {
+    report.harnessProblem = loaded.message;
+    report.warnings.push(`${HARNESS_FILE}: ${loaded.message}`);
+  }
+  report.specs = specEntries(root, homes.specs);
+  report.tickets = parse.ticketFiles(root, homes.tickets).map((file) => ticketEntry(root, file));
+  report.evidence = manifests(root, homes.evidence);
+  for (const t of report.tickets) {
+    if (t.problem) { report.warnings.push(`${t.file}: ${t.problem}`); continue; }
+    if (t.status === 'done' && !t.ready) report.warnings.push(`${t.id} done: ${t.readiness}`);
+    if (t.status === 'done' && !t.accepted) report.warnings.push(`${t.id} done without acceptance`);
+  }
+  report.next = commandMentions(root, nextCommand(report));
+  return report;
+}
+
+// The one thing to do next, first rule that matches.
+function nextCommand(report) {
+  if (!report.harness) return '/pincer-blueprint';
+  const tickets = report.tickets;
+  const broken = tickets.find((t) => t.problem);
+  if (broken) return `fix ${broken.file}`;
+  const draft = report.stages.plan === 'on' && report.specs.find((s) => !['approved', 'built'].includes(s.status));
+  if (report.stages.plan === 'on' && report.specs.length === 0 && tickets.length === 0) return '/pincer-plan <brief>';
+  if (tickets.length === 0) {
+    if (draft) return `/pincer-plan ${draft.file} (awaiting approval)`;
+    return report.stages.narrow === 'on' ? '/pincer-narrow' : '/pincer-code';
+  }
+  const inProgress = tickets.find((t) => t.status === 'in_progress');
+  if (inProgress) return `${SCRIPT} verify ${inProgress.id}`;
+  if (tickets.some((t) => t.status === 'open')) return '/pincer-code';
+  const stale = tickets.find((t) => t.status === 'done' && !t.ready);
+  if (stale) return `${SCRIPT} verify ${stale.id}`;
+  if (draft) return `/pincer-plan ${draft.file} (awaiting approval)`;
+  if (report.stages.evaluate === 'on' && report.harness.stages.evaluate.evidence && report.evidence.length === 0) return '/pincer-evaluate';
+  const unaccepted = tickets.find((t) => t.status === 'done' && !t.accepted);
+  if (unaccepted) {
+    // Acceptance is the floor even with release off: then the next step is the accept call itself.
+    if (harnessModule.stageOn(report.harness, 'release')) return '/pincer-release';
+    return `${SCRIPT} accept ${unaccepted.id} --by "<name>" --words "<their words>"`;
+  }
+  return 'all tickets done and accepted';
+}
+
+function ticketLine(t) {
+  if (t.problem) return `${t.id || t.file} invalid: ${t.problem}`;
+  let line = `${t.id} ${t.status}`;
+  if (t.status === 'in_progress' && t.started) line += ` started ${t.started}`;
+  if (t.verified) line += ` verified ${t.verified.split(/\s+/)[0]}`;
+  if (t.acceptedBy) line += ` accepted by ${t.acceptedBy}`;
+  return line;
+}
+function render(report) {
+  const lines = [];
+  const h = report.harness;
+  lines.push(h ? `PINCER — ${report.name} (${h.project.kind})` : 'PINCER — no agreement yet');
+  if (h) lines.push(`Stages: ${STAGES.map((name) => `${name} ${report.stages[name]}`).join(', ')}`);
+  const tiers = report.models ? models.statusLine(report.models) : '';
+  if (tiers) lines.push(`Models: ${tiers}`);
+  if (report.specs.length) lines.push(`Specs: ${report.specs.map((s) => `${s.file} (${s.status || 'no status'})`).join(', ')}`);
+  for (const t of report.tickets) lines.push(ticketLine(t));
+  if (report.warnings.length) { lines.push('Warnings:'); for (const w of report.warnings) lines.push(`  ${w}`); }
+  lines.push(`Next: ${report.next}`);
+  return `${lines.join('\n')}\n`;
+}
+
+// The gate every stage runs first. Exit 0 and "on", or exit 3 and the reason;
+// exit 2 for a name that is not a stage. The always-on stages pass without an
+// agreement, because the blueprint is what writes it.
+function stageGate(root, name) {
+  if (!STAGES.includes(name)) return { exit: 2, message: `${name} is not a stage (${STAGES.join(', ')})` };
+  if (ALWAYS_ON.includes(name)) return { exit: 0, message: 'on' };
+  const loaded = harnessModule.load(root);
+  if (!loaded.ok) return { exit: 3, message: loaded.missing ? commandMentions(root, loaded.message) : `${HARNESS_FILE}: ${loaded.message}` };
+  if (!harnessModule.stageOn(loaded.harness, name)) return { exit: 3, message: `stage ${name} is off in ${HARNESS_FILE}` };
+  return { exit: 0, message: 'on' };
+}
+
+module.exports = { readiness, gather, nextCommand, render, stageGate, commandMentions };

package/template/scripts/pincer/ticket.cjs

@@ -0,0 +1,204 @@
+'use strict';
+// PINCER engine — the ticket lifecycle (docs/engine.md, "Ticket fields and
+// receipts"): start, verify, done, accept. The only writer of a ticket's
+// lifecycle fields. `verify` runs the Verification block and stamps a receipt
+// only on exit 0; `done` re-runs the check and refuses on unticked criteria or
+// a stale receipt; `accept` records a named person's words on a done ticket.
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const parse = require('./parse.cjs');
+const harnessModule = require('./harness.cjs');
+const { commandMentions } = require('./status.cjs');
+const { nowIso, atomicWrite } = require('./util.cjs');
+
+const EXIT = { OK: 0, REFUSED: 1, USAGE: 2, HARNESS: 3, INTERRUPTED: 130 };
+const GRACE_MS = 5000;
+const SCRIPT = 'scripts/pincer-ticket.sh';
+
+class Refusal extends Error {
+  constructor(message, { exit = EXIT.REFUSED, prefix = 'pincer-ticket' } = {}) { super(message); this.exit = exit; this.prefix = prefix; }
+}
+const refuse = (message, options) => { throw new Refusal(message, options); };
+
+// --- The agreement ---------------------------------------------------------
+// Every verb needs an agreement with the code stage on; tickets live in its home.
+function agreement(root) {
+  const loaded = harnessModule.load(root);
+  if (!loaded.ok) refuse(`${harnessModule.HARNESS_FILE}: ${loaded.missing ? commandMentions(root, loaded.message) : loaded.message}`, { exit: EXIT.HARNESS, prefix: '' });
+  if (!harnessModule.stageOn(loaded.harness, 'code')) refuse(`stage code is off in ${harnessModule.HARNESS_FILE}`, { exit: EXIT.HARNESS, prefix: '' });
+  return { harness: loaded.harness, tickets: harnessModule.homes(loaded.harness).tickets };
+}
+
+// --- Tickets ---------------------------------------------------------------
+const readTicket = (root, file) => fs.readFileSync(path.join(root, file), 'utf8');
+const writeTicket = (root, file, text) => atomicWrite(path.join(root, file), text);
+
+function loadTicket(root, file, id) {
+  const text = readTicket(root, file);
+  const v = parse.validateTicket(file, text);
+  if (!v.ok) refuse(v.problems.map((p) => `${file}: ${p}`).join('\n'));
+  return { id: id || v.fields.ticket, file, text, fields: v.fields, timeout: v.timeout };
+}
+function resolve(root, ticketsDir, input) {
+  const tf = parse.ticketFile(root, ticketsDir, input);
+  if (tf.problem) refuse(tf.problem);
+  return loadTicket(root, tf.file, tf.id);
+}
+
+// Why a ticket's receipt is not current, or null when it is: a receipt exists,
+// its hash matches the Verification block as it stands, and the latest check
+// of that block passed.
+function receiptProblem(text, fields) {
+  const receipt = fields.verified || '';
+  if (!receipt) return 'no verification receipt';
+  const hash = parse.blockHash(text);
+  const receiptHash = receipt.split(/\s+/).pop();
+  if (receiptHash !== hash) return `receipt hash ${receiptHash} does not match the current Verification block (${hash})`;
+  const last = (fields.last_check || '').split(/\s+/);
+  if (last.length === 3 && last[2] === hash && last[1] !== 'passed') return `last check ${last[1]}`;
+  return null;
+}
+
+// --- start -----------------------------------------------------------------
+function startLoaded(root, ticketsDir, t) {
+  if (t.fields.status === 'in_progress') return { exit: EXIT.OK, out: `${t.id} already in progress (started ${t.fields.started || ''})\n` };
+  if (t.fields.status === 'done') refuse(`${t.id} is already done`);
+  for (const dep of parse.dependencies(t.fields)) {
+    const df = parse.ticketFile(root, ticketsDir, dep);
+    if (df.problem) refuse(`${t.id} depends on ${dep}: ${df.problem}`);
+    const d = loadTicket(root, df.file, dep);
+    if (d.fields.status !== 'done') refuse(`${t.id} depends on ${dep}, which is '${d.fields.status}' — finish ${dep} first (or fix depends_on in ${t.file})`);
+    const problem = receiptProblem(d.text, d.fields);
+    if (problem) refuse(`${t.id} depends on ${dep}: ${problem} — run '${SCRIPT} verify ${dep}' again`);
+  }
+  let text = parse.fmSet(t.text, 'status', 'in_progress');
+  if (!t.fields.started) text = parse.fmSet(text, 'started', nowIso());
+  writeTicket(root, t.file, text);
+  return { exit: EXIT.OK, out: `▶ ${t.id} started ${parse.frontmatterField(text, 'started')} — ${t.file}\n` };
+}
+function start(root, input) {
+  const { tickets } = agreement(root);
+  return startLoaded(root, tickets, resolve(root, tickets, input));
+}
+
+// --- verify ----------------------------------------------------------------
+// The block runs under bash with inherited stdio in its own process group;
+// SIGINT/SIGTERM to the engine terminate it and are reported as interrupted, and
+// so is the ticket's timeout (seconds) when the block outlives it.
+function execute(root, block, timeoutSeconds) {
+  return new Promise((done) => {
+    const child = spawn('bash', ['-eo', 'pipefail', '-c', block], { cwd: root, detached: true, stdio: 'inherit', env: process.env });
+    let interrupted = null, timedOut = false;
+    const terminate = () => {
+      try { process.kill(-child.pid, 'SIGTERM'); } catch { try { child.kill('SIGTERM'); } catch { /* gone */ } }
+      setTimeout(() => { try { process.kill(-child.pid, 'SIGKILL'); } catch { /* gone */ } }, GRACE_MS).unref();
+    };
+    const onSignal = (signal) => { interrupted = signal; terminate(); };
+    const timer = timeoutSeconds > 0 ? setTimeout(() => { timedOut = true; terminate(); }, timeoutSeconds * 1000) : null;
+    const release = () => { process.off('SIGINT', onSignal); process.off('SIGTERM', onSignal); if (timer) clearTimeout(timer); };
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+    child.on('error', (error) => { release(); done({ code: 127, signal: null, interrupted, timedOut, error: error.message }); });
+    child.on('exit', (code, signal) => { release(); done({ code, signal, interrupted, timedOut }); });
+  });
+}
+
+async function runCheck(root, t, io) {
+  const { id, file } = t;
+  if (t.fields.status === 'done') io.out(`${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);
+  const hash = parse.blockHash(t.text);
+  let text = parse.fmUnset(t.text, 'verified');
+  text = parse.fmSet(text, 'last_check', `${nowIso()} running ${hash}`);
+  writeTicket(root, file, text);
+  if (!commands.some((c) => !/^[ \t]*(#.*)?$/.test(c))) refuse(`no runnable command in the Verification block of ${file}`);
+  io.out(`── ${id} verification ──\n`);
+  for (const c of commands) io.out(`  $ ${c}\n`);
+  const timeout = parse.effectiveTimeout(t.fields);
+  const result = await execute(root, block, timeout);
+  const stamp = (outcome) => writeTicket(root, file, parse.fmSet(readTicket(root, file), 'last_check', `${nowIso()} ${outcome} ${hash}`));
+  if (result.timedOut) {
+    stamp('interrupted');
+    io.err(`✗ ${id} verification TIMED OUT after ${timeout}s — recorded as interrupted in last_check of ${file}. Raise timeout: in the frontmatter or fix the check, then re-run verify.\n`);
+    return { exit: EXIT.INTERRUPTED };
+  }
+  if (result.interrupted) { stamp('interrupted'); return { exit: EXIT.INTERRUPTED }; }
+  const rc = result.code === null ? 1 : result.code;
+  if (rc !== 0) {
+    stamp('failed');
+    io.err(`✗ ${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: EXIT.REFUSED };
+  }
+  const after = readTicket(root, file);
+  if (parse.blockHash(after) !== hash) { stamp('failed'); refuse('Verification block changed during execution — re-run verify'); }
+  if (!parse.validateTicket(file, after).ok) { stamp('failed'); refuse('ticket became invalid during verification — fix it and re-run verify'); }
+  let passed = parse.fmSet(after, 'last_check', `${nowIso()} passed ${hash}`);
+  passed = parse.fmSet(passed, 'verified', `${nowIso()} ${hash}`);
+  writeTicket(root, file, passed);
+  io.out(`✓ ${id} verified — receipt: ${parse.frontmatterField(passed, 'verified')}\n`);
+  return { exit: EXIT.OK };
+}
+
+const defaultIo = () => ({ out: (text) => process.stdout.write(text), err: (text) => process.stderr.write(text) });
+
+async function verify(root, input, io = defaultIo()) {
+  const { tickets } = agreement(root);
+  const t0 = resolve(root, tickets, input);
+  if (t0.fields.status === 'open') io.out(startLoaded(root, tickets, t0).out);
+  return runCheck(root, loadTicket(root, t0.file, t0.id), io);
+}
+
+// --- done ------------------------------------------------------------------
+const slugWords = (file) => path.basename(file, '.md').replace(/^T-[0-9]+-/, '').replace(/-/g, ' ');
+
+async function done(root, input, io = defaultIo()) {
+  const { tickets } = agreement(root);
+  const t = resolve(root, tickets, input);
+  const { id, file } = t;
+  const status = t.fields.status;
+  if (status !== 'in_progress' && status !== 'done') refuse(`${id} is '${status}' — run '${SCRIPT} verify ${id}' first`);
+  const receipt = t.fields.verified || '';
+  if (!receipt) refuse(`no verification receipt on ${id} — run '${SCRIPT} verify ${id}' and get a green check first`);
+  const current = parse.blockHash(t.text);
+  const receiptHash = receipt.split(/\s+/).pop();
+  if (receiptHash !== current) refuse(`receipt hash ${receiptHash} does not match the current Verification block (${current}): the check changed after it passed — run '${SCRIPT} verify ${id}' again`);
+  const unticked = parse.unticked(t.text);
+  if (unticked.length) refuse(`unticked acceptance criteria on ${id}:\n${unticked.join('\n')}\nTick each verified criterion; a criterion that was cut is a scope change to record in the spec, not a box to skip.`);
+  const result = await runCheck(root, t, io);
+  if (result.exit !== EXIT.OK) return result;
+  const after = loadTicket(root, file, id);
+  const still = parse.unticked(after.text);
+  if (still.length) refuse(`unticked acceptance criteria on ${id} after verification:\n${still.join('\n')}`);
+  if (status === 'done') { io.out(`${id} already done — current check passed\n`); return { exit: EXIT.OK }; }
+  let text = parse.fmSet(after.text, 'status', 'done');
+  text = parse.fmSet(text, 'finished', nowIso());
+  writeTicket(root, file, text);
+  io.out(`✓ ${id} done. Inspect staged work, stage only this ticket's paths, review git diff --cached, then commit: ${id}: ${slugWords(file)}\n`);
+  return { exit: EXIT.OK };
+}
+
+// --- accept ----------------------------------------------------------------
+// The floor's second half: a named person, from the agreement's acceptors,
+// and their words, on one line. Run only after the person said so.
+function accept(root, input, { by, words } = {}) {
+  const { harness, tickets } = agreement(root);
+  const t = resolve(root, tickets, input);
+  if (t.fields.status !== 'done') refuse(`${t.id} is '${t.fields.status}' — acceptance is recorded on a done ticket; run verify and done first`);
+  const stale = receiptProblem(t.text, t.fields);
+  if (stale) refuse(`${t.id}: ${stale} — run '${SCRIPT} verify ${t.id}' and get a green check before recording acceptance`);
+  const people = harnessModule.acceptors(harness);
+  const name = String(by || '').trim();
+  if (!people.includes(name)) refuse(`${name ? `'${name}'` : 'nobody'} is not an acceptor in ${harnessModule.HARNESS_FILE} — the people who accept are: ${people.join(', ')}`);
+  const said = String(words || '').replace(/\s*\r?\n\s*/g, ' ').trim();
+  if (!said) refuse(`${t.id}: --words must quote what ${name} said when accepting`);
+  const previous = t.fields.accepted ? `${t.id} already accepted by ${t.fields.accepted_by} at ${t.fields.accepted} — overwriting\n` : '';
+  let text = parse.fmSet(t.text, 'accepted', nowIso());
+  text = parse.fmSet(text, 'accepted_by', name);
+  text = parse.fmSet(text, 'accepted_words', said);
+  writeTicket(root, t.file, text);
+  return { exit: EXIT.OK, out: `${previous}✓ ${t.id} accepted by ${name}: ${said}\n` };
+}
+
+module.exports = { EXIT, Refusal, receiptProblem, start, verify, done, accept };

package/template/scripts/pincer/util.cjs

@@ -0,0 +1,104 @@
+'use strict';
+// PINCER engine — small helpers shared by the engine modules: time, atomic
+// writes, JSON, git, and the output sanitizer. Dependency-free.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+
+// UTC to the second, the timestamp format every ticket field uses.
+const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+// Write via a temporary file in the same directory and rename into place, so a
+// reader never sees a partial file and a crash leaves the old file or the new one.
+function atomicWrite(file, text) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true });
+  const temp = path.join(dir, `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`);
+  fs.writeFileSync(temp, text);
+  fs.renameSync(temp, file);
+}
+
+// The parsed file, or null when it is missing or not JSON. Callers that need
+// to tell the two apart read the file themselves.
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+// Run git in `root`; stdout without its trailing newline. Throws on a non-zero
+// exit (the error carries stderr).
+function git(root, args) {
+  return execFileSync('git', ['-C', root, '-c', 'core.quotePath=false', ...args], {
+    encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024,
+  }).trimEnd();
+}
+function tryGit(root, args) {
+  try { return git(root, args); } catch { return null; }
+}
+
+// Output sanitizer: documented secret patterns are replaced by [redacted]
+// before anything captured is persisted. A safety net, not a guarantee.
+const PATTERNS = [
+  // Bearer tokens first, so an `Authorization: Bearer <token>` header keeps the
+  // token, not the word Bearer, as the redacted value.
+  { re: /((?:bearer|basic|token|digest)\s+)[A-Za-z0-9\-._~+/=]+/gi, replace: '$1[redacted]' },
+  // key/secret/password/token/authorization assignments and JSON fields; a
+  // quoted value is redacted up to its closing quote, an unquoted one to the
+  // next whitespace or separator. Bounded quantifiers: an unbounded prefix would
+  // backtrack quadratically on long lines.
+  { re: /((?:^|[^A-Za-z0-9_.-])[A-Za-z0-9_.-]{0,64}?(?:key|secret|password|passwd|token|authorization)[A-Za-z0-9_.-]{0,64}["']?[ \t]{0,8}[:=][ \t]{0,8})(?:"([^"\n]{0,512})"|'([^'\n]{0,512})'|([^\s"',;]+))/gi, replace: (m, head, dq, sq) => `${head}${dq !== undefined ? '"[redacted]"' : sq !== undefined ? "'[redacted]'" : '[redacted]'}` },
+  { re: /AKIA[0-9A-Z]{16}/g, replace: '[redacted]' },
+  { re: /gh[pousr]_[A-Za-z0-9]{20,}/g, replace: '[redacted]' },
+];
+const PEM_BEGIN = /-----BEGIN [A-Z ]*PRIVATE KEY-----/;
+const PEM_END = /-----END [A-Z ]*PRIVATE KEY-----/;
+
+// Stateful: PEM private key blocks span lines. `state` is a plain object the
+// caller keeps per stream.
+function sanitizeLine(line, state = {}) {
+  if (state.inPem) {
+    if (PEM_END.test(line)) state.inPem = false;
+    return '[redacted]';
+  }
+  if (PEM_BEGIN.test(line)) {
+    state.inPem = !PEM_END.test(line);
+    return '[redacted]';
+  }
+  let text = line;
+  for (const { re, replace } of PATTERNS) {
+    text = text.replace(re, (...args) => (typeof replace === 'function' ? replace(...args) : replace.replace(/\$(\d)/g, (_, n) => args[Number(n)])));
+  }
+  return text;
+}
+function sanitizeText(text) {
+  const state = {};
+  return String(text).split('\n').map((line) => sanitizeLine(line, state)).join('\n');
+}
+
+// Complete output on every exit path. process.stdout is asynchronous when it
+// is a pipe, so a report larger than the pipe buffer is cut short by an early
+// exit; writing the descriptor synchronously puts the bytes in the pipe before
+// the call returns. A reader that went away (EPIPE) or a closed descriptor
+// (EBADF) stays silent and keeps the command's own exit code.
+const IDLE = new Int32Array(new SharedArrayBuffer(4));
+function writeFd(fd, text) {
+  if (!text) return;
+  const buffer = Buffer.from(String(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;
+    }
+  }
+}
+const out = (text) => writeFd(1, text);
+const err = (text) => writeFd(2, text);
+
+// A URL without the credentials that may sit before its host (https://user:token@host/...).
+const stripUserinfo = (url) => (typeof url === 'string' ? url.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/@]*@/i, '$1') : url);
+
+module.exports = { nowIso, atomicWrite, readJson, git, tryGit, sanitizeLine, sanitizeText, stripUserinfo, writeFd, out, err };

package/template/scripts/pincer-blueprint.cjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// Entry point for the blueprint stage's scripts: recon prints the classification
+// with its reasons and the answers it could pre-fill (offline unless --network);
+// write turns an answers file into harness.json, the agreement in AGENTS.md and
+// the project copies.
+'use strict';
+require('./pincer/cli.cjs').blueprint(process.argv.slice(2)).then((code) => { process.exitCode = code; });

package/template/scripts/pincer-evidence.cjs

@@ -1,76 +1,8 @@
 #!/usr/bin/env node
 'use strict';
-// PINCER evidence — read-only validator for candidate evidence manifests.
-// Dependency-free; runs under `node` on any platform. The implementation lives
-// in scripts/pincer-runtime/evidence.cjs (shared with status and release).
+// PINCER evidence — validate an evidence manifest, or digest files for one
+// (docs/engine.md, "Evidence manifest schema 1"). Read-only.
 //
-//   node scripts/pincer-evidence.cjs validate .prd/evidence/prd-vN/<candidate>/manifest.json \
-//        [--candidate <sha>] [--base <sha>] [--prd .prd/prd-vN.md] [--files]
-//   node scripts/pincer-evidence.cjs digest <file>...
-//
-// `validate` exits 0 and prints `ok <candidate>` when the manifest is
-// consistent; with --files it also lists the manifest and every artifact path
-// (repository-relative, one per line). Otherwise it prints one
-// `evidence: <manifest>: <reason>` line per problem to stderr and exits 1.
-// Usage errors exit 2. Nothing is ever written.
-//
-// What validation establishes: that the locally authored record is internally
-// consistent — schema, references, candidate association, required results,
-// artifact existence and digests, repository containment. It is NOT independent
-// attestation that the recorded commands ran or that images depict the stated
-// application; that judgment stays with the reviewer.
-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) 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);
-}
-
-function main(argv) {
-  const [command, ...rest] = argv;
-  if (command === 'validate') {
-    const opts = { files: false };
-    let manifest = null;
-    for (let i = 0; i < rest.length; i++) {
-      const arg = rest[i];
-      if (arg === '--files') opts.files = true;
-      else if (arg === '--candidate' || arg === '--base' || arg === '--prd') {
-        const value = rest[++i];
-        if (value === undefined) usage(`${arg} requires a value`);
-        opts[arg.slice(2)] = value;
-      } else if (arg.startsWith('--')) usage(`unknown option ${arg}`);
-      else if (manifest === null) manifest = arg;
-      else usage('validate takes exactly one manifest path');
-    }
-    if (manifest === null) usage('validate requires a manifest path');
-    if (opts.candidate !== undefined && !HEX40.test(opts.candidate)) usage('--candidate must be a full 40-hex commit ID');
-    if (opts.base !== undefined && !HEX40.test(opts.base)) usage('--base must be a full 40-hex commit ID');
-    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) io.err(`evidence: ${manifest}: ${p}\n`);
-      process.exit(1);
-    }
-    const doc = JSON.parse(fs.readFileSync(path.resolve(manifest), 'utf8'));
-    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) { io.err(`pincer-evidence: ${file}: ${error.code === 'ENOENT' ? 'missing' : error.message}\n`); process.exit(1); }
-      io.out(`${digest}  ${file}\n`);
-    }
-    return;
-  }
-  usage(command ? `unknown command ${command}` : undefined);
-}
-
-main(process.argv.slice(2));
+//   scripts/pincer-evidence.cjs validate <manifest> [--candidate <sha>]   prints "ok <candidate>", or one problem per line and exits 1
+//   scripts/pincer-evidence.cjs digest <file>...                          prints "<sha256>  <file>" per line
+require('./pincer/cli.cjs').main(['evidence', ...process.argv.slice(2)]).then((code) => { process.exitCode = code; });

package/template/scripts/pincer-status.sh

@@ -1,17 +1,15 @@
 #!/bin/bash
-# PINCER status — where the workflow stands, read from the artifacts on disk.
-# Read-only. Every playbook runs this first; /pincer-status wraps it.
+# PINCER status — where the work stands, read from harness.json and the
+# artifacts on disk (docs/engine.md, "Stage gate"). Read-only. Every stage
+# skill runs the gate first; /pincer-status wraps the report.
 #
-#   scripts/pincer-status.sh [--json]
+#   scripts/pincer-status.sh                  stages, specs, every ticket, warnings, and the next command
+#   scripts/pincer-status.sh --json           the same report as JSON
+#   scripts/pincer-status.sh --stage <name>   the gate: prints "on" and exits 0, or the reason and exits 3
 #
-# Compatibility wrapper: the report is computed by scripts/pincer-runtime.cjs
-# (`status`), which prints the PRD state and profile, every ticket with its
-# state and clock-based elapsed time, the wall-clock elapsed build line while a
-# ticket is in progress or PINCER_BUILD_BUDGET_MIN is set, the evidence verdict,
-# readiness warnings, and the next command. Exit codes follow
-# docs/runtime-contracts.md (0 inspected, 4 invalid input).
+# Exit codes: 0 ok, 2 usage, 3 no agreement, invalid harness.json or stage off.
 command -v node >/dev/null 2>&1 || {
-  echo 'pincer-status: Node.js 22+ is required — the runtime is scripts/pincer-runtime.cjs' >&2
-  exit 4
+  echo 'pincer-status: Node.js 22+ is required — the engine is scripts/pincer/cli.cjs' >&2
+  exit 1
 }
-exec node "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/pincer-runtime.cjs" status "$@"
+exec node "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/pincer/cli.cjs" status "$@"

package/template/scripts/pincer-ticket.sh

@@ -1,25 +1,22 @@
 #!/bin/bash
-# PINCER ticket state machine — the ONLY writer of a ticket's lifecycle fields.
-# Compatibility wrapper: every call is executed by scripts/pincer-runtime.cjs
-# (docs/runtime-contracts.md). On Claude Code a PreToolUse hook
-# (.claude/hooks/ticket-guard.sh) blocks hand edits of those fields so "done"
-# can only be reached through a passing check.
+# PINCER ticket lifecycle — the ONLY writer of a ticket's lifecycle fields
+# (docs/engine.md, "Ticket fields and receipts"). On Claude Code a PreToolUse
+# hook (.claude/hooks/ticket-guard.sh) blocks hand edits of those fields, so
+# "done" is reached only through a passing check and acceptance only through
+# a named person's words.
 #
-#   scripts/pincer-ticket.sh start  T-03   open -> in_progress; refuses while a depends_on ticket isn't ready
-#   scripts/pincer-ticket.sh verify T-03   runs the ticket's Verification block and records the outcome
-#   scripts/pincer-ticket.sh done   T-03   closes the ticket on a current passing check with all criteria ticked
-#   scripts/pincer-ticket.sh bind   T-03 .prd/prd-vN.md   associates a legacy ticket with its PRD
+#   scripts/pincer-ticket.sh start  T-03   open -> in_progress; refuses while a depends_on ticket is not done and verified
+#   scripts/pincer-ticket.sh verify T-03   runs the ticket's Verification block and stamps the receipt on exit 0
+#   scripts/pincer-ticket.sh done   T-03   closes the ticket on a current passing check with every criterion ticked
+#   scripts/pincer-ticket.sh accept T-03 --by "<name>" --words "<what they said>"   records the person's acceptance
 #
-# Unmigrated (legacy) projects keep the v0.4.1 receipts: `verify` writes
-# `last_check` and `verified` into the ticket and `done` re-runs the check.
-# Migrated projects record attempts under .pincer/runtime/ and `done` consumes
-# the current passing attempt. Exit codes follow docs/runtime-contracts.md.
+# Exit codes: 0 ok, 1 refused, 2 usage, 3 no agreement or stage off, 130 interrupted.
 command -v node >/dev/null 2>&1 || {
-  echo 'pincer-ticket: Node.js 22+ is required — the runtime is scripts/pincer-runtime.cjs' >&2
-  exit 4
+  echo 'pincer-ticket: Node.js 22+ is required — the engine is scripts/pincer/cli.cjs' >&2
+  exit 1
 }
 case "${1:-}" in
-  start|verify|done|bind) ;;
-  *) sed -n '8,11p' "$0" | sed 's/^# \{0,1\}//'; exit 2 ;;
+  start|verify|done|accept) ;;
+  *) sed -n '8,11p' "$0" | sed 's/^# \{0,1\}//' >&2; exit 2 ;;
 esac
-exec node "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/pincer-runtime.cjs" "$@"
+exec node "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/pincer/cli.cjs" ticket "$@"