pincer-workflow 0.4.1 → 0.6.0

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

@@ -0,0 +1,245 @@
+'use strict';
+// PINCER runtime — phase-specific coverage (docs/runtime-contracts.md, "Strict
+// coverage" → "Phase-specific coverage"). One pure computation over the validated
+// graph, consumed by `coverage`, `change complete`, `evidence export`, `ready`,
+// status and resume: `structure` (every obligation linked or authorized as not
+// delivered, nothing missing from the baseline), `implementation` (structure plus
+// every ticket done and ready under the v5 rules) and `candidate` (the evaluated
+// candidate's reconciled evidence). The three are separate fields; none implies
+// another, and a linked check, a done ticket or a passing syntax check never
+// becomes a delivery or adequacy verdict. A change without the capability is
+// labeled `unverified`. Nothing here writes, launches or judges semantics.
+const changes = require('./changes.cjs');
+const routing = require('./routing.cjs');
+const agreement = require('./agreement.cjs');
+const authorization = require('./authorization.cjs');
+const coverage = require('./coverage.cjs');
+const dispositions = require('./dispositions.cjs');
+const requirements = require('./requirements.cjs');
+const locator = require('./locator.cjs');
+const state = require('./state.cjs');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const STRUCTURE_ORDER = ['INPUT_INVALID', 'INVENTORY_INVALID', 'COVERAGE_INVALID', 'COVERAGE_INCOMPLETE', 'SCOPE_UNAUTHORIZED', 'OBLIGATION_MISSING'];
+const byOrder = (a, b) => STRUCTURE_ORDER.indexOf(a.code) - STRUCTURE_ORDER.indexOf(b.code);
+
+const unverified = reason => ({ strict: false, label: 'unverified', reason, inventory: null, map: null, graph: null, scope: [], structure: null, implementation: null, candidate: null, blockers: [] });
+
+// compute(root, record, { gathered, verdict }) — `gathered` is status.render(...).gathered
+// for the record (computed here when absent); `verdict` the authorization verdict.
+function compute(root, record, { gathered = null, verdict = null } = {}) {
+  if (!record) return unverified('no change record');
+  if (!changes.isStrict(record)) return unverified(`strict coverage not adopted (node scripts/pincer-runtime.cjs coverage adopt --preview --change ${record.change})`);
+  const out = { strict: true, label: 'strict', reason: null, inventory: null, map: null, graph: null, scope: [], structure: { complete: false, problems: [] }, implementation: { complete: false, scenarios: {}, problems: [] }, candidate: { evaluated: false, candidate: null, manifest: null, delivery: null, adequacy: null, scenarios: {}, problems: [] }, blockers: [] };
+  const priorInventory = gid => agreement.inventoryOf(root, record, record.agreements.find(g => g.id === gid) || null);
+  const cov = coverage.load(root, record, { priorInventory });
+  out.inventory = cov.inventory ? { digest: cov.inventory.digest, requirements: Object.fromEntries(Object.entries(cov.inventory.requirements).map(([id, r]) => [id, { title: r.title, line: r.line, end: r.end, scenarios: r.scenarios }])), scenarios: Object.fromEntries(Object.entries(cov.inventory.scenarios).map(([id, s]) => [id, { requirement: s.requirement, line: s.line, end: s.end }])) } : null;
+  out.map = cov.map ? { path: cov.map.file, digest: cov.map.digest, checks: Object.fromEntries(Object.entries(cov.map.map.checks).map(([id, c]) => [id, { kind: c.kind, required: c.required, declared: coverage.definitionDigest(c) }])) } : null;
+  if (cov.code && cov.code !== 'COVERAGE_INCOMPLETE') {
+    out.structure.problems = cov.problems.map(detail => ({ code: cov.code, detail, ids: [] }));
+    out.blockers = out.structure.problems.map(p => ({ code: p.code, detail: p.detail }));
+    return out;
+  }
+  out.graph = cov.graph;
+  const v = verdict || authorization.verdict(root, record);
+  const scope = dispositions.scopeProblems(record, cov.graph, v);
+  out.scope = scope.resolved;
+  const problems = [...cov.graph.problems, ...scope.problems, ...dispositions.obligationProblems(dispositions.baseline(root, record), cov.inventory, cov.map.map)].sort(byOrder);
+  out.structure = { complete: problems.length === 0, problems };
+  // Implementation: every in-scope scenario's tickets done and ready; every ticket of the change done and ready.
+  const g = gathered || require('./status.cjs').render(root, { change: record.change }).gathered;
+  // A fresh clone (no local attempt history) of a completed change validates the saved
+  // candidate record only: a done ticket's missing local attempt is its stated limit, not
+  // unfinished work. Before completion the v5 rule holds: a fresh clone must verify.
+  const localUnavailable = !state.hasIndex(root) && record.lifecycle.state === 'completed';
+  out.implementation.limitations = localUnavailable ? ['local verification history unavailable; done tickets rely on the saved candidate evidence until verified here'] : [];
+  const ticketState = id => {
+    const t = g && g.tickets ? g.tickets.find(x => x.fields.ticket === id) : null;
+    if (!t) return { id, status: null, ready: false, code: 'EVIDENCE_MISSING', detail: 'no ticket file' };
+    const r = g.computeReadiness(t);
+    if (localUnavailable && t.fields.status === 'done' && !r.ready && r.reasons[0].code === 'EVIDENCE_MISSING') return { id, status: 'done', ready: true, code: null, detail: null, limitation: 'no local attempt history' };
+    return { id, status: t.fields.status, ready: r.ready, code: r.ready ? null : r.reasons[0].code, detail: r.ready ? null : `${r.reasons[0].detail} — ${r.reasons[0].next}` };
+  };
+  const implProblems = [];
+  const seen = new Set();
+  for (const id of requirements.sortIds(Object.keys(cov.graph.scenarios))) {
+    const s = cov.graph.scenarios[id];
+    const tickets = s.tickets.map(ticketState);
+    const unfinished = tickets.find(t => t.status !== 'done');
+    const unverifiedT = tickets.find(t => t.status === 'done' && !t.ready);
+    const state = unfinished ? 'unfinished' : unverifiedT ? 'unverified' : 'complete';
+    const detail = unfinished ? `${unfinished.id} is ${unfinished.status || 'missing'}, not done` : unverifiedT ? `${unverifiedT.id} ${unverifiedT.code}: ${unverifiedT.detail}` : null;
+    out.implementation.scenarios[id] = { scope: 'in-scope', requirement: s.requirement, implementation: state, tickets, checks: s.checks, detail };
+    if (state !== 'complete' && !seen.has(detail)) { seen.add(detail); implProblems.push({ code: unfinished ? 'LIFECYCLE_BLOCKED' : unverifiedT.code, detail: `${id}: ${detail}`, ids: [id, (unfinished || unverifiedT).id] }); }
+  }
+  for (const id of requirements.sortIds(Object.keys(cov.graph.scope))) {
+    const s = cov.graph.scope[id];
+    out.implementation.scenarios[id] = { scope: s.disposition, requirement: s.requirement, implementation: 'not applicable', tickets: [], checks: [], detail: `${s.disposition} by decision ${s.decision}` };
+  }
+  // Enabling tickets and any other ticket of the change must be done and ready too.
+  for (const id of Object.keys(cov.tickets || {})) {
+    const t = ticketState(id);
+    if (t.status === 'done' && t.ready) continue;
+    const detail = t.status !== 'done' ? `${id} is ${t.status}, not done` : `${id} ${t.code}: ${t.detail}`;
+    if (!implProblems.some(p => p.ids.includes(id))) implProblems.push({ code: t.status !== 'done' ? 'LIFECYCLE_BLOCKED' : t.code, detail, ids: [id] });
+  }
+  out.implementation.problems = implProblems;
+  out.implementation.complete = out.structure.complete && implProblems.length === 0;
+  candidateCoverage(root, record, out.candidate);
+  // A missing or stale evaluation blocks only a completed change: before completion no candidate is expected.
+  out.blockers = [...out.structure.problems, ...implProblems, ...(record.lifecycle.state === 'completed' ? out.candidate.problems : [])].map(p => ({ code: p.code, detail: p.detail }));
+  return out;
+}
+
+// Candidate coverage: the change's latest evaluation (schema 3) reconciled by the
+// locator, with per-scenario dispositions and the codes that block release.
+function candidateCoverage(root, record, out) {
+  const loc = locator.current(root, record);
+  if (loc.state === 'missing') { out.problems = [{ code: 'EVIDENCE_MISSING', detail: 'candidate: not evaluated', ids: [] }]; return; }
+  out.evaluated = true; out.candidate = loc.candidate || null; out.manifest = loc.manifest || null;
+  let m = null;
+  try { m = JSON.parse(fs.readFileSync(path.join(root, loc.manifest), 'utf8')); } catch { m = null; }
+  const problems = [];
+  if (loc.state === 'stale') problems.push({ code: 'CANDIDATE_STALE', detail: loc.text, ids: [] });
+  if (!m || m.schema !== 3) { problems.push({ code: 'EVIDENCE_MISSING', detail: `candidate evidence is ${m && m.schema ? `schema ${m.schema}` : 'unreadable'}, not the strict schema 3; evaluate again`, ids: [] }); out.problems = problems; return; }
+  const checkOf = Object.fromEntries((m.checks || []).filter(c => c && c.id).map(c => [c.id, c]));
+  for (const row of m.scenarios || []) {
+    if (!row || !row.id) continue;
+    const checks = (row.checks || []).map(id => { const c = checkOf[id] || {}; return { id, kind: c.kind || null, required: c.required ?? null, result: c.result || null }; });
+    const failing = checks.filter(c => c.required && c.result !== 'passed');
+    out.scenarios[row.id] = { disposition: row.disposition, checks, detail: row.disposition === 'blocked' ? `blocked by ${failing.map(c => `${c.id} (${c.kind} ${c.result || 'missing'})`).join(', ') || 'a missing check'}` : row.disposition === 'delivered' ? 'every required check passed' : `${row.disposition} by decision ${row.decision} (${row.authorization || 'unauthorized'})` };
+    for (const c of failing) problems.push({ code: c.kind === 'command' ? ({ failed: 'CHECK_FAILED', unverified: 'ATTEMPT_ERROR' }[c.result] || 'CHECK_FAILED') : 'REVIEW_MISSING', detail: `${row.id}: ${c.id} (${c.kind}) is ${c.result || 'missing'}`, ids: [row.id, c.id] });
+  }
+  out.delivery = m.delivery || null;
+  out.adequacy = m.adequacy || null;
+  if (!m.adequacy || m.adequacy.verdict !== 'adequate') problems.push({ code: 'ADEQUACY_REQUIRED', detail: m.adequacy ? `the reviewer judged the checks inadequate: ${m.adequacy.note}` : 'no adequacy judgment recorded', ids: [] });
+  out.problems = problems;
+}
+
+// The first blocking problem for a phase, in the contract's order, or null.
+function firstBlocker(report, phase) {
+  if (!report.strict) return null;
+  if (report.structure.problems.length) return report.structure.problems[0];
+  if (phase === 'structure') return null;
+  if (report.implementation.problems.length) return report.implementation.problems[0];
+  if (phase === 'implementation') return null;
+  return report.candidate.problems[0] || null;
+}
+
+// --- The coverage report (docs/runtime-contracts.md, "Coverage and impact commands") ------
+const RUNTIME_CMD = 'node scripts/pincer-runtime.cjs';
+// One ordered next action for a strict change: the first blocking code, else the
+// phase that is due (verify/start/complete/evaluate/release), or nothing to do.
+function nextAction(report, record, { verdict = null, running = [], selected = true } = {}) {
+  const cmd = (action, command, extra = {}) => ({ action, command, ticket: null, check: null, decision: null, ...extra });
+  if (!report.strict) return cmd('adopt strict coverage when wanted', `${RUNTIME_CMD} coverage adopt --preview --change ${record.change}`);
+  const id = record.change;
+  // Rules 2 and 3 outrank everything below, including the agreement verdict: a
+  // historical change is never routed to execution or to authorization, and a
+  // running attempt is waited for rather than raced.
+  const ahead = routing.preface({ id, lifecycle: record.lifecycle, base: record.base, running });
+  if (ahead) return { ...cmd(ahead.action, ahead.command), ...ahead };
+  if (verdict && verdict.verdict !== 'current') {
+    if (verdict.verdict === 'DECISION_REQUIRED') return cmd("record the user's decision", `${RUNTIME_CMD} change decide ${id} --resolve ${verdict.open[0]} --reference <text> --excerpt <text>`, { decision: verdict.open[0] });
+    if (['AUTHORIZATION_REQUIRED', 'AGREEMENT_CHANGED'].includes(verdict.verdict)) return cmd("record the user's authorization of the current agreement", `${RUNTIME_CMD} change authorize ${id} --agreement ${verdict.current} --reference <text> --excerpt <text>`);
+    if (verdict.verdict === 'COVERAGE_INVALID') return cmd('repair the coverage map', verdict.detail);
+    if (verdict.verdict === 'INVENTORY_INVALID') return cmd('repair the PRD definitions', verdict.detail);
+    return cmd('repair the agreement inputs', `${verdict.verdict}: ${verdict.detail}`);
+  }
+  const p = report.structure.problems[0];
+  if (p) {
+    if (p.code === 'INVENTORY_INVALID') return cmd('repair the PRD definitions', p.detail);
+    if (p.code === 'COVERAGE_INVALID') return cmd('repair the coverage map', p.detail);
+    if (p.code === 'COVERAGE_INCOMPLETE') return cmd('author the missing coverage rows, then authorize', `edit .prd/coverage/${id}.json: ${p.detail}; then ${RUNTIME_CMD} change authorize ${id} --agreement <digest> …`);
+    if (p.code === 'SCOPE_UNAUTHORIZED') return cmd('record the scope decision and its user authorization', `${RUNTIME_CMD} change decide ${id} --summary <text> / --resolve D-NN …, then change authorize ${id} --agreement <digest> --decision D-NN …`, { decision: p.decision || null });
+    if (p.code === 'OBLIGATION_MISSING') return cmd('restore the obligation, or record the decision and the removed tombstone', p.detail);
+    return cmd('repair the coverage inputs', `${p.code}: ${p.detail}`);
+  }
+  const staged = routing.lifecycleAction({ id, lifecycle: record.lifecycle });
+  if (staged) return { ...cmd(staged.action, staged.command), ...staged };
+  const i = report.implementation.problems[0];
+  if (i) {
+    const ticket = i.ids.find(x => /^T-/.test(x)) || null;
+    if (i.code === 'LIFECYCLE_BLOCKED' && ticket) return cmd(`finish ${ticket}`, `scripts/pincer-ticket.sh start ${ticket} → verify ${ticket} → done ${ticket}`, { ticket });
+    if (ticket) return cmd(`re-verify ${ticket} (${i.code})`, `scripts/pincer-ticket.sh verify ${ticket}`, { ticket });
+    return cmd('finish the mapped work', i.detail);
+  }
+  if (record.lifecycle.state === 'active') return cmd('complete the change', `${RUNTIME_CMD} change complete ${id}`);
+  const c = report.candidate.problems[0];
+  if (c) {
+    const check = c.ids.find(x => /^C-/.test(x)) || null;
+    if (c.code === 'EVIDENCE_MISSING' && !report.candidate.evaluated) return cmd('evaluate the candidate', '/pincer-evaluate (declare the candidate, run every declared check, record the reviews and the adequacy judgment, export)');
+    if (['CHECK_FAILED', 'ATTEMPT_ERROR'].includes(c.code) && check) return cmd(`re-run ${check} and re-evaluate`, `${RUNTIME_CMD} check ${check} --candidate <sha>, then /pincer-evaluate`, { check });
+    if (c.code === 'REVIEW_MISSING' && check) return cmd(`perform and record the review ${check}`, `record ${check} with its candidate-bound artifact in the draft, then /pincer-evaluate`, { check });
+    if (c.code === 'ADEQUACY_REQUIRED') return cmd("record the reviewer's adequacy judgment", '/pincer-evaluate with adequacy { verdict, note } in the draft');
+    return cmd('evaluate the candidate again', `${c.code}: ${c.detail}`);
+  }
+  return cmd('read-only release audit', '/pincer-release');
+}
+
+// report(root, record, { gathered, verdict, generated }) → coverage JSON schema 1.
+function report(root, record, { gathered = null, verdict = null, generated = null, selected = true } = {}) {
+  const authorization = require('./authorization.cjs');
+  const running = record ? require('./transaction.cjs').runningAttempts(root, record.change) : [];
+  const v = verdict || (record ? authorization.verdict(root, record) : null);
+  const r = compute(root, record, { gathered, verdict: v });
+  const reviewed = v && v.authorized && record ? (() => { const g = record.agreements.find(x => x.id === v.authorized.agreement); return g ? { agreement: g.id, authorization: v.authorized.id, digest: g.digest } : null; })() : null;
+  const base = record && r.strict ? require('./dispositions.cjs').baseline(root, record) : null;
+  const out = {
+    schema: 1, runtime: changes.RUNTIME_STRICT, generated: generated || require('./fsutil.cjs').nowIso(), root, mode: 'changes', change: record ? record.change : null,
+    strict: r.strict, label: r.label, reason: r.reason,
+    inventory: r.inventory ? { digest: r.inventory.digest, requirements: Object.entries(r.inventory.requirements).map(([id, x]) => ({ id, title: x.title, line: x.line, end: x.end, scenarios: x.scenarios })), scenarios: Object.entries(r.inventory.scenarios).map(([id, x]) => ({ id, requirement: x.requirement, line: x.line, end: x.end })) } : null,
+    map: r.map ? { path: r.map.path, digest: r.map.digest, checks: Object.entries(r.map.checks).map(([id, c]) => ({ id, ...c })) } : null,
+    agreement: { current: v && v.current ? v.current : null, reviewed, verdict: v ? v.verdict : null },
+    baseline: base ? { agreements: base.agreements, scenarios: Object.keys(base.scenarios) } : null,
+    structure: r.structure, implementation: r.implementation, candidate: r.candidate, scope: r.scope,
+    blockers: [
+      ...(running.length ? [{ code: 'ATTEMPT_RUNNING', detail: `attempt ${running[0].id} of change ${record.change} is running${running[0].alive === false ? ' (its owner is no longer running)' : ''}` }] : []),
+      ...(v && v.verdict !== 'current' ? [{ code: v.verdict, detail: v.detail }] : []), ...r.blockers],
+    next: routing.qualify(nextAction(r, record, { verdict: v, running, selected }), { id: record ? record.change : null, selected }),
+  };
+  return out;
+}
+
+function render(j) {
+  const lines = [];
+  const short = s => (typeof s === 'string' ? s.slice(0, 12) : '—');
+  lines.push(`PINCER coverage · ${j.generated} · ${j.root}`);
+  lines.push(`Change     ${j.change || 'none'} · coverage ${j.label}${j.reason ? ` (${j.reason})` : ''}`);
+  if (j.strict) {
+    lines.push(`Agreement  current ${short(j.agreement.current)} · reviewed ${j.agreement.reviewed ? `${j.agreement.reviewed.agreement} (${j.agreement.reviewed.authorization}, ${short(j.agreement.reviewed.digest)})` : 'none'} · verdict ${j.agreement.verdict}`);
+    lines.push(`Inventory  ${j.inventory ? `${j.inventory.requirements.length} requirement(s), ${j.inventory.scenarios.length} scenario(s) · ${short(j.inventory.digest)}` : 'unreadable'}`);
+    lines.push(`Map        ${j.map ? `${j.map.path} · ${short(j.map.digest)} · checks ${j.map.checks.map(c => `${c.id} (${c.kind}${c.required ? ', required' : ''})`).join(', ')}` : 'unreadable'}`);
+    lines.push(`Structure  ${j.structure.complete ? 'complete' : `incomplete: ${j.structure.problems.map(p => `${p.code} ${p.detail}`).join('; ')}`}`);
+    const sc = Object.entries(j.implementation.scenarios);
+    lines.push(`Implementation ${j.implementation.complete ? 'complete' : 'incomplete'} · ${sc.filter(([, s]) => s.implementation === 'complete').length}/${sc.filter(([, s]) => s.scope === 'in-scope').length} in-scope scenario(s) complete${sc.some(([, s]) => s.scope !== 'in-scope') ? ` · ${sc.filter(([, s]) => s.scope !== 'in-scope').map(([id, s]) => `${id} ${s.scope}`).join(', ')}` : ''}`);
+    for (const [id, s] of sc) lines.push(`  ${id.padEnd(6)} ${s.scope === 'in-scope' ? s.implementation.padEnd(14) : s.scope.padEnd(14)} ${s.scope === 'in-scope' ? `tickets ${s.tickets.map(t => `${t.id} ${t.status || 'missing'}${t.ready ? '' : t.code ? ` (${t.code})` : ''}`).join(', ')} · checks ${s.checks.join(', ')}` : s.detail}${j.candidate.scenarios[id] ? ` · candidate ${j.candidate.scenarios[id].disposition}` : ''}`);
+    const c = j.candidate;
+    lines.push(`Candidate  ${c.evaluated ? `${c.candidate ? c.candidate.slice(0, 7) : '?'} · delivery original ${c.delivery ? c.delivery.original : '?'}, agreed ${c.delivery ? c.delivery.agreed : '?'} · adequacy ${c.adequacy ? `${c.adequacy.verdict} ("${c.adequacy.note}")` : 'not recorded'}` : 'not evaluated · adequacy: not recorded'}${c.problems.length ? ` · ${c.problems.map(p => `${p.code} ${p.detail}`).join('; ')}` : ''}`);
+    if (j.scope.length) lines.push(`Scope      ${j.scope.map(s => `${s.id} ${s.disposition} by ${s.decision} (${s.authorization}; reviewer judgment: "${s.excerpt}" must support it)`).join('; ')}`);
+  }
+  lines.push(`Blockers   ${j.blockers.length ? j.blockers.map(b => `${b.code} ${b.detail}`).join('\n           ') : 'none'}`);
+  lines.push(`Next       ${j.next.action}: ${j.next.command}`);
+  return `${lines.join('\n')}\n`;
+}
+
+// A one-line summary for status and resume.
+function summary(r) {
+  if (!r.strict) return { strict: false, label: 'unverified', reason: r.reason, structure: null, implementation: null, candidate: null };
+  const sc = Object.values(r.implementation.scenarios);
+  return {
+    strict: true, label: 'strict', reason: null,
+    structure: { complete: r.structure.complete, problems: r.structure.problems.map(p => ({ code: p.code, detail: p.detail })) },
+    implementation: { complete: r.implementation.complete, scenarios: { total: sc.length, complete: sc.filter(s => s.implementation === 'complete').length, unfinished: sc.filter(s => s.implementation === 'unfinished').length, unverified: sc.filter(s => s.implementation === 'unverified').length, dispositioned: sc.filter(s => s.scope !== 'in-scope').length } },
+    candidate: r.candidate.evaluated ? { evaluated: true, delivery: r.candidate.delivery, adequacy: r.candidate.adequacy ? r.candidate.adequacy.verdict : null } : { evaluated: false, delivery: null, adequacy: null },
+  };
+}
+function summaryLine(r, record) {
+  if (!r.strict) return `Coverage unverified · ${r.reason}`;
+  const s = summary(r);
+  const reviewed = record && record.authorizations.length ? `${record.authorizations.at(-1).agreement} (${record.authorizations.at(-1).id})` : 'none';
+  return `Coverage strict · agreement ${reviewed} · structure ${s.structure.complete ? 'complete' : `incomplete (${s.structure.problems[0].code})`} · implementation ${s.implementation.scenarios.complete}/${s.implementation.scenarios.total - s.implementation.scenarios.dispositioned} scenarios${s.implementation.scenarios.dispositioned ? ` (${s.implementation.scenarios.dispositioned} dispositioned)` : ''} · candidate ${s.candidate.evaluated ? `${s.candidate.delivery ? `delivery original ${s.candidate.delivery.original}, agreed ${s.candidate.delivery.agreed}` : 'delivery not recorded (evidence predates strict coverage)'}, adequacy ${s.candidate.adequacy || 'not recorded'}` : 'not evaluated'}`;
+}
+
+module.exports = { STRUCTURE_ORDER, compute, firstBlocker, nextAction, report, render, summary, summaryLine };

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

@@ -0,0 +1,97 @@
+'use strict';
+// PINCER runtime — the one readiness computation (docs/runtime-contracts.md,
+// "Readiness and reason codes"). Pure functions over parsed inputs: the human
+// status, the JSON status, `ready`, `done`, `start` and release all consume
+// these so they cannot disagree. Nothing here reads the clock, executes a
+// command or writes a file.
+const parse = require('./parse.cjs');
+const { validateAttempt } = require('./state.cjs');
+
+const reason = (code, detail, next) => ({ code, detail, next });
+
+// Legacy mode: the v0.4.1 rules over the ticket's own receipts. Returns
+// { ready, reasons, legacyMessage } where legacyMessage is the exact wording
+// the Bash helper printed for a done ticket that needs attention.
+function legacyTicketReadiness(text, fields) {
+  const receipt = fields.verified || '';
+  const attempt = fields.last_check || '';
+  const hash = parse.legacyBlockHash(text);
+  const fail = (message, code, detail = message) => ({ ready: false, legacyMessage: message, reasons: [reason(code, detail, 're-run verify')] });
+  if (!attempt) return fail('missing latest verification outcome — re-run verify', 'EVIDENCE_MISSING', 'no recorded verification attempt');
+  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) {
+    const outcomeCode = parts[1] === 'running' ? 'ATTEMPT_RUNNING' : parts[1] === 'interrupted' ? 'ATTEMPT_INTERRUPTED' : parts[1] === 'failed' ? 'CHECK_FAILED' : 'CHECK_CHANGED';
+    const code = parts[1] === 'passed' && parts[2] !== hash ? 'CHECK_CHANGED' : outcomeCode;
+    return fail(`latest verification: ${attempt} — re-run verify`, code, code === 'CHECK_CHANGED' ? 'the Verification block changed after the latest pass' : `latest verification: ${attempt}`);
+  }
+  if (!receipt) return fail('done without a verification receipt — re-run verify', 'EVIDENCE_MISSING', 'done without a verification receipt');
+  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', 'CHECK_CHANGED', 'stale or malformed verification receipt');
+  }
+  if (parse.unticked(text).length) return fail('unticked acceptance criteria — complete and re-run verify', 'CRITERIA_UNTICKED', 'unticked acceptance criteria');
+  return { ready: true, reasons: [] };
+}
+
+// Migrated mode: readiness derives from the latest attempt for the ticket's
+// context and the current inputs. `current` carries the digests computed now;
+// `sourceProblems` are snapshot problems (secret path, unsupported input);
+// `contextKey` is the key the attempt was read for and `pointedId` the id the
+// index names for it (the record must match both); the attempt's artifacts
+// carry `missing`/`altered` from state.inspectArtifacts.
+function migratedTicketReadiness({ text, fields, timeout, attempt, legacyReceipt, current, sourceProblems = [], changedPaths = [], contextKey = null, pointedId = null, mode = 'migrated', strict = false }) {
+  const reasons = [];
+  for (const p of sourceProblems) reasons.push(reason(p.code, p.detail, p.code === 'SECRET_PATH' ? 'remove or ignore the secret file' : 'remove the input or change the configuration'));
+  if (reasons.length) return { ready: false, reasons };
+  if (!attempt) {
+    if (legacyReceipt) return { ready: false, reasons: [reason('LEGACY_RECEIPT', `migrated legacy receipt (${legacyReceipt.verified || legacyReceipt.last_check || 'present'}) is history, not runtime evidence`, 'verify')] };
+    return { ready: false, reasons: [reason('EVIDENCE_MISSING', 'no runtime attempt recorded', 'verify')] };
+  }
+  const id = typeof attempt.id === 'string' && attempt.id ? attempt.id : '?';
+  // The record must be complete and written for this context before any
+  // outcome is honored: a stripped or foreign record is never a pass.
+  const invalid = validateAttempt(attempt, contextKey, pointedId);
+  if (invalid) return { ready: false, reasons: [reason('ATTEMPT_ERROR', `attempt ${id} ${invalid}`, 'verify')] };
+  // A record written before the migration to change records keeps its identity
+  // as history; it never becomes current evidence for the new change context.
+  if (mode === 'changes' && attempt.schema === 1) return { ready: false, reasons: [reason('HISTORICAL_EVIDENCE', `attempt ${id} was recorded under schema ${attempt.schema} (before this project used change records) and is history, not current evidence`, 'verify')] };
+  // Strict coverage (schema 3 attempts): an attempt recorded before adoption is history;
+  // a strict attempt read for a change without the capability is never evidence.
+  if (mode === 'changes' && strict && attempt.schema !== 3) return { ready: false, reasons: [reason('HISTORICAL_EVIDENCE', `attempt ${id} was recorded under schema ${attempt.schema} (before this change adopted strict coverage) and is history, not current evidence`, 'verify')] };
+  if (mode === 'changes' && !strict && attempt.schema === 3) return { ready: false, reasons: [reason('ATTEMPT_ERROR', `attempt ${id} is a strict-coverage (schema 3) attempt; this change has not adopted strict coverage`, 'verify')] };
+  if (mode !== 'changes' && attempt.schema !== 1) return { ready: false, reasons: [reason('ATTEMPT_ERROR', `attempt ${id} is a change-record (schema ${attempt.schema}) attempt; this project is not in changes mode`, 'verify')] };
+  switch (attempt.outcome) {
+    case 'running': return { ready: false, reasons: [reason('ATTEMPT_RUNNING', `attempt ${id} is running`, 'wait, or run recover if its owner died')] };
+    case 'interrupted': return { ready: false, reasons: [reason('ATTEMPT_INTERRUPTED', `attempt ${id} was interrupted`, 'verify')] };
+    case 'timed_out': return { ready: false, reasons: [reason('ATTEMPT_TIMED_OUT', `attempt ${id} timed out after ${attempt.check && attempt.check.timeout_seconds} s`, 'fix or raise timeout, then verify')] };
+    case 'error': return { ready: false, reasons: [reason('ATTEMPT_ERROR', `attempt ${id}: ${attempt.error || 'could not be recorded'}`, 'inspect the record, then verify')] };
+    case 'failed': return { ready: false, reasons: [reason('CHECK_FAILED', `attempt ${id} failed (exit ${attempt.exit_code ?? attempt.signal ?? '?'})`, 'fix, then verify')] };
+    case 'passed': break;
+    default: return { ready: false, reasons: [reason('ATTEMPT_ERROR', `attempt ${id} has unknown outcome ${JSON.stringify(attempt.outcome)}`, 'verify')] };
+  }
+  if (current.prdRevision && attempt.context && attempt.context.prd_revision !== current.prdRevision) {
+    reasons.push(reason('REVISION_CHANGED', 'the PRD revision changed since the passing attempt', 'register --rebind, then verify'));
+  }
+  if (attempt.check && attempt.check.digest !== parse.checkDigest(text, timeout)) {
+    reasons.push(reason('CHECK_CHANGED', 'the Verification block or timeout changed since the passing attempt', 'verify'));
+  }
+  if (attempt.context && attempt.context.ticket_digest !== parse.ticketDigest(text)) {
+    reasons.push(reason('SOURCE_CHANGED', 'the ticket\'s authored content changed since the passing attempt', 'verify'));
+  }
+  if (current.sourceDigest && attempt.source && attempt.source.after !== current.sourceDigest) {
+    const shown = changedPaths.slice(0, 5).join(', ') + (changedPaths.length > 5 ? `, … (${changedPaths.length} paths)` : '');
+    reasons.push(reason('SOURCE_CHANGED', `source changed since the passing attempt${shown ? `: ${shown}` : ''}`, 'verify'));
+  }
+  const streams = ['stdout', 'stderr'];
+  if (streams.some(k => attempt.artifacts[k].missing)) {
+    reasons.push(reason('EVIDENCE_MISSING', 'the attempt\'s captured log is missing from local state', 'verify'));
+  }
+  const altered = streams.filter(k => attempt.artifacts[k].altered);
+  if (altered.length) {
+    reasons.push(reason('EVIDENCE_MISSING', `the attempt's captured ${altered.join(' and ')} log was altered after the run and no longer matches the recorded digest`, 'verify'));
+  }
+  if (parse.unticked(text).length) reasons.push(reason('CRITERIA_UNTICKED', 'unticked acceptance criteria', 'tick verified criteria'));
+  return { ready: reasons.length === 0, reasons };
+}
+
+module.exports = { reason, legacyTicketReadiness, migratedTicketReadiness };

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

@@ -0,0 +1,255 @@
+'use strict';
+// PINCER runtime — the requirement inventory (docs/runtime-contracts.md, "Strict
+// coverage" → "Requirement inventory"). Parses a PRD into the complete set of
+// requirement and scenario definitions under the frozen, deliberately bounded
+// grammar: ATX headings `### R-NN — Title` define requirements, bold list items
+// `- **S-NN:** text` inside a requirement section define scenarios, fenced code,
+// table rows and quotes are reference contexts, and anything that looks like a
+// definition in another shape is refused. The PRD prose is authoritative: this
+// module derives a view and never edits, renumbers or infers a definition. No
+// partial inventory is returned for a PRD with a grammar problem.
+const fs = require('node:fs');
+const path = require('node:path');
+const parse = require('./parse.cjs');
+
+const PROJECTION_VERSION = 1;
+const ID = '[A-Z][A-Z0-9]{0,7}-[0-9]{1,6}';
+const ID_RE = new RegExp(`^${ID}$`);
+const HEADING = /^(#{1,6})[ \t]+(.*?)[ \t]*$/;
+const REQUIREMENT_DEF = new RegExp(`^(${ID})(?:[ \\t]+(?:—|–|-)[ \\t]+|:[ \\t]+)(.+)$`);
+const STARTS_WITH_ID = new RegExp(`^(${ID})(?![A-Z0-9-])`);
+const ITEM = /^([ \t]*)([-+*]|[0-9]+[.)])[ \t]+(.*)$/;
+const SCENARIO_DEF = new RegExp(`^\\*\\*(${ID})(:?)\\*\\*(:?)(?:[ \\t]+(?:—|–|-)[ \\t]+|[ \\t]+|$)(.*)$`);
+const SCENARIO_LIKE = new RegExp(`^(?:\\*\\*)?${ID}[:.]|^\\*\\*${ID}\\*\\*[ \\t]*$`);
+const FENCE = /^[ \t]*`{3,}/;
+const TILDE = /^[ \t]*~~~/;
+const REFERENCE_CONTEXT = /^[ \t]*[|>]/;
+const CONTINUATION = /^(?:[ ]{2,}|\t)(\S.*)$/;
+
+// Prefix in byte order, then numerically: R-02 < R-10, AC-1 < R-01.
+function compareIds(a, b) {
+  const [pa, na] = split(a), [pb, nb] = split(b);
+  if (pa !== pb) return pa < pb ? -1 : 1;
+  return na - nb;
+}
+const split = id => { const i = id.lastIndexOf('-'); return [id.slice(0, i), Number(id.slice(i + 1))]; };
+const sortIds = ids => [...ids].sort(compareIds);
+
+const rtrim = s => s.replace(/[ \t]+$/, '');
+// Right-trimmed lines, leading/trailing blank lines removed, blank runs collapsed.
+function normalizeBlock(lines) {
+  const out = [];
+  for (const raw of lines) {
+    const line = rtrim(raw);
+    if (line === '' && (out.length === 0 || out[out.length - 1] === '')) continue;
+    out.push(line);
+  }
+  while (out.length && out[out.length - 1] === '') out.pop();
+  return out.join('\n');
+}
+
+// Parse a PRD text. Returns { ok: true, inventory } or { ok: false, problems }
+// (each problem a string; the code is always INVENTORY_INVALID). `prd` is the
+// repository-relative PRD path recorded in the projection.
+function parseInventory(text, { prd } = {}) {
+  const rows = parse.lines(text);
+  const problems = [];
+  const defined = new Map(); // id -> { kind, line }
+  const requirements = {}; // id -> { title, lines: [], digest, line, end, scenarios: [] }
+  const scenarios = {}; // id -> { requirement, lines: [], digest, line, end }
+  const order = [];
+  let i = 0;
+  if (rows[0] === '---') { i = 1; while (i < rows.length && rows[i] !== '---') i++; i++; }
+  let fenceLine = null, current = null, lastScenario = null;
+  // Blank lines seen while a scenario is still open. A blank line does not end a
+  // list item, so they are held until the next line decides where they belong:
+  // to the scenario, when an indented line follows and the item had a second
+  // paragraph, or to the requirement, when anything else follows.
+  const pending = [];
+  const endScenario = () => {
+    if (current) for (const blank of pending) requirements[current].lines.push(blank);
+    pending.length = 0;
+    lastScenario = null;
+  };
+  // Close the open section at the line before `boundary` (1-based; rows.length + 1 at
+  // the end of the file): its span ends at its last nonblank line.
+  const closeRequirement = boundary => {
+    if (!current) return;
+    const r = requirements[current];
+    let end = boundary - 1;
+    while (end > r.line && rows[end - 1].trim() === '') end--;
+    r.end = end;
+    if (!r.scenarios.length) problems.push(`requirement ${current} at line ${r.line} has no scenario`);
+    endScenario(); current = null;
+  };
+  const define = (kind, id, line) => {
+    const prior = defined.get(id);
+    if (prior) { problems.push(`duplicate definition ${id} at line ${line}`); return false; }
+    defined.set(id, { kind, line });
+    return true;
+  };
+  for (; i < rows.length; i++) {
+    const line = rows[i], n = i + 1;
+    if (fenceLine !== null) {
+      if (FENCE.test(line)) fenceLine = null;
+      if (current) requirements[current].lines.push(line);
+      continue;
+    }
+    if (TILDE.test(line)) { problems.push(`tilde fences are unsupported (line ${n})`); endScenario(); if (current) requirements[current].lines.push(line); continue; }
+    if (FENCE.test(line)) { fenceLine = n; endScenario(); if (current) requirements[current].lines.push(line); continue; }
+    if (REFERENCE_CONTEXT.test(line)) { endScenario(); if (current) requirements[current].lines.push(line); continue; }
+    const heading = line.match(HEADING);
+    if (heading) {
+      endScenario();
+      const level = heading[1].length, textOf = heading[2];
+      const def = textOf.match(REQUIREMENT_DEF);
+      if (def && level >= 2 && level <= 4 && def[2].trim() !== '') {
+        closeRequirement(n);
+        if (define('requirement', def[1], n)) {
+          current = def[1];
+          requirements[current] = { title: def[2].trim(), lines: [], line: n, end: n, level, scenarios: [] };
+          order.push(current);
+        }
+        continue;
+      }
+      if (STARTS_WITH_ID.test(textOf)) { problems.push(`unsupported requirement definition syntax at line ${n}; use "### R-NN — Title"`); closeRequirement(n); continue; }
+      if (current && level <= requirements[current].level) { closeRequirement(n); continue; }
+      if (current) requirements[current].lines.push(line);
+      continue;
+    }
+    const item = line.match(ITEM);
+    if (item) {
+      endScenario();
+      const body = item[3].replace(/^\[[ xX]\][ \t]+/, '');
+      const def = body.match(SCENARIO_DEF);
+      const numbered = /^[0-9]/.test(item[2]);
+      if (def && !numbered) {
+        if (def[4].trim() === '') { problems.push(`empty definition ${def[1]} at line ${n}`); continue; }
+        if (!current) { problems.push(`orphan scenario ${def[1]} at line ${n}`); continue; }
+        if (define('scenario', def[1], n)) {
+          scenarios[def[1]] = { requirement: current, lines: [def[4].trim()], line: n, end: n };
+          requirements[current].scenarios.push(def[1]);
+          lastScenario = def[1];
+        }
+        continue;
+      }
+      if (SCENARIO_LIKE.test(body) || (def && numbered)) { problems.push(`unsupported scenario definition syntax at line ${n}; use "- **S-NN:** text"`); continue; }
+      if (current) requirements[current].lines.push(line);
+      continue;
+    }
+    if (lastScenario && line.trim() === '') { pending.push(line); continue; }
+    const cont = lastScenario ? line.match(CONTINUATION) : null;
+    if (cont) {
+      const s = scenarios[lastScenario];
+      while (pending.length) { pending.pop(); s.lines.push(''); }
+      s.lines.push(rtrim(cont[1])); s.end = n; continue;
+    }
+    endScenario();
+    if (current) requirements[current].lines.push(line);
+  }
+  if (fenceLine !== null) problems.push(`unclosed fence opened at line ${fenceLine}`);
+  closeRequirement(rows.length + 1);
+  if (!order.length) problems.push('no requirement definitions');
+  if (problems.length) return { ok: false, problems };
+  const inventory = { prd: prd || null, requirements: {}, scenarios: {} };
+  for (const id of sortIds(order)) {
+    const r = requirements[id];
+    const text = normalizeBlock([r.title, ...r.lines]);
+    inventory.requirements[id] = { title: r.title, text, digest: parse.sha256(`requirement ${id}\n${text}\n`), line: r.line, end: r.end, scenarios: sortIds(r.scenarios) };
+  }
+  for (const id of sortIds(Object.keys(scenarios))) {
+    const s = scenarios[id];
+    const text = rtrim(s.lines.join('\n'));
+    inventory.scenarios[id] = { requirement: s.requirement, text, digest: parse.sha256(`scenario ${id}\n${text}\n`), line: s.line, end: s.end };
+  }
+  inventory.projection = projectionText(inventory);
+  inventory.digest = parse.sha256(inventory.projection);
+  return { ok: true, inventory };
+}
+
+// The exact inventory projection (each line terminated by \n).
+function projectionText(inventory) {
+  const lines = [`pincer inventory ${PROJECTION_VERSION}`, `prd ${inventory.prd}`];
+  for (const id of sortIds(Object.keys(inventory.requirements))) lines.push(`requirement ${id} ${inventory.requirements[id].digest}`);
+  for (const id of sortIds(Object.keys(inventory.scenarios))) lines.push(`scenario ${id} ${inventory.scenarios[id].requirement} ${inventory.scenarios[id].digest}`);
+  return `${lines.join('\n')}\n`;
+}
+
+// Read and parse a PRD of the repository. Returns { ok, inventory } or
+// { ok: false, code: 'INPUT_INVALID' | 'INVENTORY_INVALID', problems }.
+function readInventory(root, prdRef) {
+  const v = parse.validatePrd(root, prdRef);
+  if (!v.ok) return { ok: false, code: 'INPUT_INVALID', problems: v.problems.map(p => `${prdRef}: ${p}`) };
+  const result = parseInventory(v.text, { prd: prdRef });
+  if (!result.ok) return { ok: false, code: 'INVENTORY_INVALID', problems: result.problems.map(p => `${prdRef}: ${p}`), prdResult: v };
+  return { ok: true, inventory: result.inventory, prdResult: v };
+}
+
+// Recompute a snapshot inventory's projection from its own digests (readSnapshot).
+function projectionOf({ prd, requirements, scenarios }) {
+  return projectionText({ prd, requirements, scenarios });
+}
+
+// The snapshot shape (agreement snapshot schema 2 and evidence coverage/inventory.json).
+function snapshotOf(inventory) {
+  const requirements = {}, scenarios = {};
+  for (const id of Object.keys(inventory.requirements)) { const r = inventory.requirements[id]; requirements[id] = { title: r.title, text: r.text, digest: r.digest, line: r.line, end: r.end, scenarios: [...r.scenarios] }; }
+  for (const id of Object.keys(inventory.scenarios)) { const s = inventory.scenarios[id]; scenarios[id] = { requirement: s.requirement, text: s.text, digest: s.digest, line: s.line, end: s.end }; }
+  return { digest: inventory.digest, projection: inventory.projection, requirements, scenarios };
+}
+
+// Validate a snapshot inventory read from a file: shape, per-definition digests
+// recompute from the texts, the projection recomputes and hashes to `digest`.
+// Returns null or a problem string.
+function validateSnapshot(snap, prd) {
+  const isObject = v => v !== null && typeof v === 'object' && !Array.isArray(v);
+  const SHA = /^[0-9a-f]{64}$/;
+  if (!isObject(snap)) return 'inventory must be an object';
+  for (const k of ['digest', 'projection', 'requirements', 'scenarios']) if (!(k in snap)) return `inventory.${k} is missing`;
+  for (const k of Object.keys(snap)) if (!['digest', 'projection', 'requirements', 'scenarios'].includes(k)) return `inventory.${k} is not allowed`;
+  if (!isObject(snap.requirements) || !isObject(snap.scenarios)) return 'inventory.requirements and inventory.scenarios must be objects';
+  for (const [id, r] of Object.entries(snap.requirements)) {
+    if (!ID_RE.test(id) || !isObject(r) || typeof r.title !== 'string' || typeof r.text !== 'string' || !SHA.test(r.digest || '') || !Number.isInteger(r.line) || !Number.isInteger(r.end) || !Array.isArray(r.scenarios)) return `inventory.requirements[${id}] is malformed`;
+    if (parse.sha256(`requirement ${id}\n${r.text}\n`) !== r.digest) return `requirement ${id} text does not hash to its recorded digest`;
+    for (const s of r.scenarios) if (!snap.scenarios[s] || snap.scenarios[s].requirement !== id) return `requirement ${id} lists scenario ${s}, which is not its scenario`;
+  }
+  for (const [id, s] of Object.entries(snap.scenarios)) {
+    if (!ID_RE.test(id) || !isObject(s) || typeof s.text !== 'string' || !SHA.test(s.digest || '') || !Number.isInteger(s.line) || !Number.isInteger(s.end) || !snap.requirements[s.requirement]) return `inventory.scenarios[${id}] is malformed`;
+    if (parse.sha256(`scenario ${id}\n${s.text}\n`) !== s.digest) return `scenario ${id} text does not hash to its recorded digest`;
+    if (!snap.requirements[s.requirement].scenarios.includes(id)) return `scenario ${id} is not listed by its requirement ${s.requirement}`;
+  }
+  const projection = projectionText({ prd, requirements: snap.requirements, scenarios: snap.scenarios });
+  if (projection !== snap.projection) return 'the inventory projection does not recompute from its definitions';
+  if (parse.sha256(projection) !== snap.digest) return 'the inventory digest does not match its projection';
+  return null;
+}
+
+// Structural difference between two inventories (snapshots or computed): what
+// impact and deletion detection read. Never a semantic judgment.
+function difference(from, to) {
+  const reqBefore = Object.keys(from.requirements), reqAfter = Object.keys(to.requirements);
+  const scBefore = Object.keys(from.scenarios), scAfter = Object.keys(to.scenarios);
+  const requirements = { added: sortIds(reqAfter.filter(id => !from.requirements[id])), removed: sortIds(reqBefore.filter(id => !to.requirements[id])), changed: [], unchanged: [] };
+  for (const id of sortIds(reqAfter.filter(id => from.requirements[id]))) {
+    const a = from.requirements[id], b = to.requirements[id];
+    const parts = [];
+    if (a.title !== b.title) parts.push('title');
+    if (a.digest !== b.digest && a.text !== b.text) parts.push('text');
+    if (JSON.stringify(sortIds(a.scenarios)) !== JSON.stringify(sortIds(b.scenarios))) parts.push('scenarios');
+    if (parts.length) requirements.changed.push({ id, parts }); else requirements.unchanged.push(id);
+  }
+  const scenarios = { added: sortIds(scAfter.filter(id => !from.scenarios[id])), removed: sortIds(scBefore.filter(id => !to.scenarios[id])), changed: [], unchanged: [] };
+  for (const id of sortIds(scAfter.filter(id => from.scenarios[id]))) {
+    const a = from.scenarios[id], b = to.scenarios[id];
+    const parts = [];
+    if (a.digest !== b.digest) parts.push('text');
+    if (a.requirement !== b.requirement) parts.push('requirement');
+    if (parts.length) scenarios.changed.push({ id, parts }); else scenarios.unchanged.push(id);
+  }
+  return { same: from.digest === to.digest, requirements, scenarios };
+}
+
+module.exports = { PROJECTION_VERSION, ID, ID_RE, compareIds, sortIds, parseInventory, projectionText, projectionOf, readInventory, snapshotOf, validateSnapshot, difference, normalizeBlock };
+
+// Convenience for callers that hold a file path rather than a repository.
+module.exports.parseFile = (file, prd) => parseInventory(fs.readFileSync(file, 'utf8'), { prd: prd || path.basename(file) });