pincer-workflow 0.5.0 → 0.6.0

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

@@ -13,6 +13,9 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const { execFileSync } = require('node:child_process');
 const { validateAttempt, contextKey } = require('./state.cjs');
+const requirements = require('./requirements.cjs');
+const coverage = require('./coverage.cjs');
+const { tryGit } = require('./fsutil.cjs');
 
 const SCHEMA = 1;
 const HEX40 = /^[0-9a-f]{40}$/;
@@ -36,9 +39,19 @@ const KINDS = ['command', 'visual', 'review'];
 const RESULTS = ['passed', 'failed', 'unverified'];
 // Schema 2 (docs/runtime-contracts.md, "Evidence schema 2"): a change binding,
 // provenance per check, and attempt provenance on runtime command checks.
-const SCHEMAS = [1, 2];
+// Schema 3 (docs/runtime-contracts.md, "Evidence schema 3"): the complete reconciled
+// coverage of the candidate — inventory and map snapshots, scenario rows, derived
+// dispositions, the adequacy judgment and the delivery summary.
+const SCHEMAS = [1, 2, 3];
 const TOP_KEYS_2 = [...TOP_KEYS, 'change'];
+const TOP_KEYS_3 = [...TOP_KEYS_2, 'coverage', 'scenarios', 'adequacy', 'delivery'];
+const REQ_KEYS_3 = ['id', 'disposition', 'tickets', 'checks', 'scenarios', 'decision', 'authorization', 'note'];
+const SCENARIO_KEYS = ['id', 'requirement', 'disposition', 'tickets', 'checks', 'decision', 'authorization', 'note'];
+const DISPOSITIONS_3 = ['delivered', 'deferred', 'removed', 'blocked'];
+const COVERAGE_KEYS = ['agreement', 'authorization', 'inventory', 'map', 'snapshots'];
+const ADEQUACY = ['adequate', 'inadequate'];
 const CHECK_KEYS_2 = [...CHECK_KEYS, 'provenance', 'attempt'];
+const CHECK_KEYS_3 = [...CHECK_KEYS_2, 'declared'];
 const PROVENANCE = ['runtime', 'authored'];
 const ATTEMPT_KEYS = ['id', 'sequence', 'outcome', 'exit_code', 'started', 'finished', 'source_before', 'source_after', 'check_digest', 'runner', 'cwd', 'log_sha256', 'truncated'];
 const OUTCOMES = ['passed', 'failed', 'timed_out', 'interrupted', 'error'];
@@ -95,10 +108,14 @@ function validate(manifestArg, opts, rootArg) {
   let doc;
   try { doc = JSON.parse(raw); } catch (error) { return [`malformed JSON (${error.message})`]; }
   if (!isObject(doc)) return ['malformed: the manifest must be a JSON object'];
-  if (!SCHEMAS.includes(doc.schema)) return [`unknown evidence schema ${JSON.stringify(doc.schema)} — this runtime validates schemas ${SCHEMAS.join(' and ')}`];
-  const schema2 = doc.schema === 2;
-  const topKeys = schema2 ? TOP_KEYS_2 : TOP_KEYS;
-  const checkKeys = schema2 ? CHECK_KEYS_2 : CHECK_KEYS;
+  if (!SCHEMAS.includes(doc.schema)) return [`unknown evidence schema ${JSON.stringify(doc.schema)} — this runtime validates schemas ${SCHEMAS.slice(0, -1).join(', ')} and ${SCHEMAS.at(-1)}`];
+  const schema2 = doc.schema >= 2;
+  const schema3 = doc.schema === 3;
+  const topKeys = schema3 ? TOP_KEYS_3 : schema2 ? TOP_KEYS_2 : TOP_KEYS;
+  const checkKeys = schema3 ? CHECK_KEYS_3 : schema2 ? CHECK_KEYS_2 : CHECK_KEYS;
+  const reqKeys = schema3 ? REQ_KEYS_3 : REQ_KEYS;
+  const dispositions = schema3 ? DISPOSITIONS_3 : DISPOSITIONS;
+  opts.limitations = [];
 
   const problems = [];
   const problem = message => problems.push(message);
@@ -189,6 +206,8 @@ function validate(manifestArg, opts, rootArg) {
     for (const key of Object.keys(check)) if (!checkKeys.includes(key)) problem(`check ${name}: unknown key "${key}"`);
     if (!KINDS.includes(check.kind)) problem(`check ${name}: kind must be one of ${KINDS.join(', ')}`);
     if (schema2) validateProvenance(check, name, doc, problem);
+    if (schema3 && !(typeof check.declared === 'string' && SHA256.test(check.declared))) problem(`check ${name}: declared must be the 64-hex definition digest from the coverage map`);
+    if (schema3 && (check.kind === 'review' || check.kind === 'visual') && Array.isArray(check.artifacts) && check.artifacts.length === 0) problem(`check ${name}: a ${check.kind} obligation needs at least one candidate-bound artifact`);
     if (typeof check.required !== 'boolean') problem(`check ${name}: required must be true or false`);
     if (!RESULTS.includes(check.result)) problem(`check ${name}: result must be one of ${RESULTS.join(', ')}`);
     if (typeof check.timestamp !== 'string' || !ISO_UTC.test(check.timestamp)) problem(`check ${name}: timestamp must be an ISO-8601 UTC timestamp`);
@@ -215,7 +234,8 @@ function validate(manifestArg, opts, rootArg) {
       problem(`required check ${name} is ${check.result} — readiness is blocked until it passes on a new candidate or the requirement is deferred with authorization`);
     }
   });
-  for (const [p, referenced] of artifacts) if (!referenced) problem(`artifact ${p}: not referenced by any check`);
+  const strictSnapshots = schema3 && isObject(doc.coverage) && isObject(doc.coverage.snapshots) ? Object.values(doc.coverage.snapshots).filter(p => typeof p === 'string') : [];
+  for (const [p, referenced] of artifacts) if (!referenced && !strictSnapshots.includes(p)) problem(`artifact ${p}: not referenced by any check`);
 
   // Requirements: every ID dispositioned; deferrals authorized; checks resolve.
   const requirements = new Set();
@@ -228,16 +248,16 @@ function validate(manifestArg, opts, rootArg) {
     else if (requirements.has(id)) problem(`duplicate requirement ID ${id}`);
     else requirements.add(id);
     const name = id || label;
-    for (const key of Object.keys(req)) if (!REQ_KEYS.includes(key)) problem(`requirement ${name}: unknown key "${key}"`);
-    if (!DISPOSITIONS.includes(req.disposition)) problem(`requirement ${name}: disposition must be one of ${DISPOSITIONS.join(', ')}`);
+    for (const key of Object.keys(req)) if (!reqKeys.includes(key)) problem(`requirement ${name}: unknown key "${key}"`);
+    if (!dispositions.includes(req.disposition)) problem(`requirement ${name}: disposition must be one of ${dispositions.join(', ')}`);
     if (!Array.isArray(req.tickets) || !req.tickets.every(t => typeof t === 'string' && TICKET_ID.test(t))) problem(`requirement ${name}: tickets must be an array of ticket IDs such as T-01`);
     if (!Array.isArray(req.checks)) problem(`requirement ${name}: checks must be an array of check IDs`);
     else for (const c of req.checks) {
       if (typeof c !== 'string' || !checks.has(c)) problem(`requirement ${name}: references unknown check ${JSON.stringify(c)} (dangling reference)`);
     }
-    for (const key of ['note', 'authorized_by']) if (key in req && !shortText(req[key])) problem(`requirement ${name}: ${key} must be a short string`);
-    if (req.disposition === 'deferred' && !nonempty(req.authorized_by)) problem(`requirement ${name}: deferred requires authorized_by naming the explicit user authorization`);
-    if (req.disposition === 'delivered' && Array.isArray(req.checks) && req.checks.length === 0) problem(`requirement ${name}: delivered requires at least one check`);
+    for (const key of ['note', 'authorized_by']) if (key in req && req[key] !== null && !shortText(req[key])) problem(`requirement ${name}: ${key} must be a short string`);
+    if (!schema3 && req.disposition === 'deferred' && !nonempty(req.authorized_by)) problem(`requirement ${name}: deferred requires authorized_by naming the explicit user authorization`);
+    if (!schema3 && req.disposition === 'delivered' && Array.isArray(req.checks) && req.checks.length === 0) problem(`requirement ${name}: delivered requires at least one check`);
     if (req.disposition === 'blocked') problem(`requirement ${name} is blocked — readiness is blocked until it is delivered on a new candidate or deferred with authorization`);
   });
 
@@ -250,11 +270,195 @@ function validate(manifestArg, opts, rootArg) {
     if ('reason' in visual && !shortText(visual.reason)) problem('visual_review.reason must be a short string');
   }
 
+  if (schema3) validateStrict(doc, { root, rel, dirRel, checks, requirements: requirementsSeen(doc), opts }, problem);
+
   if (problems.length === 0 && opts.files) {
     opts.list = [rel, ...doc.artifacts.map(a => a.path)];
   }
   return problems;
 }
+const requirementsSeen = doc => new Map((Array.isArray(doc.requirements) ? doc.requirements : []).filter(r => isObject(r) && typeof r.id === 'string').map(r => [r.id, r]));
+
+// --- Schema 3: reconciled candidate coverage --------------------------------------
+// The manifest cannot choose its own obligations: the scenario and requirement rows
+// are exactly the inventory snapshot's set plus tombstones, the links are the map
+// snapshot's, every declared check appears with its declaration digest, dispositions
+// are derived from the outcomes, and (inside a repository) the snapshots recompute
+// from the committed candidate's own PRD, map and change record.
+function validateStrict(doc, { root, dirRel, checks, requirements: reqRows, opts }, problem) {
+  const cov = doc.coverage;
+  if (!isObject(cov)) { problem('coverage must be an object { agreement, authorization, inventory, map, snapshots }'); return; }
+  for (const k of Object.keys(cov)) if (!COVERAGE_KEYS.includes(k)) problem(`coverage.${k} is not allowed`);
+  for (const k of COVERAGE_KEYS) if (!(k in cov)) problem(`coverage.${k} is missing`);
+  for (const k of ['agreement', 'inventory', 'map']) if (typeof cov[k] !== 'string' || !SHA256.test(cov[k])) problem(`coverage.${k} must be a 64-hex digest`);
+  if (typeof cov.authorization !== 'string' || !/^A-[0-9]{2,6}$/.test(cov.authorization)) problem('coverage.authorization must name the authorization A-NN that covered the evaluation');
+  const changeId = isObject(doc.change) && typeof doc.change.id === 'string' ? doc.change.id : null;
+  const expectedSnapshots = { inventory: `${dirRel}/coverage/inventory.json`, map: `${dirRel}/coverage/map.json` };
+  if (!isObject(cov.snapshots)) { problem('coverage.snapshots must be { inventory, map }'); return; }
+  for (const k of ['inventory', 'map']) if (cov.snapshots[k] !== expectedSnapshots[k]) problem(`coverage.snapshots.${k} must be ${expectedSnapshots[k]}`);
+  for (const k of Object.keys(cov.snapshots)) if (!['inventory', 'map'].includes(k)) problem(`coverage.snapshots.${k} is not allowed`);
+  const listed = new Set((Array.isArray(doc.artifacts) ? doc.artifacts : []).filter(isObject).map(a => a.path));
+  for (const k of ['inventory', 'map']) if (!listed.has(expectedSnapshots[k])) problem(`coverage snapshot ${expectedSnapshots[k]} must be a listed artifact`);
+  // Snapshots: the inventory recomputes from its definitions; the map normalizes to its digest.
+  let inv = null, mapDoc = null, mapNormalized = null;
+  const readSnap = k => { try { return JSON.parse(fs.readFileSync(path.join(root, expectedSnapshots[k]), 'utf8')); } catch (error) { problem(`coverage snapshot ${expectedSnapshots[k]}: ${error.code === 'ENOENT' ? 'missing' : `malformed JSON (${error.message})`}`); return null; } };
+  const invSnap = readSnap('inventory'), mapSnap = readSnap('map');
+  if (invSnap) {
+    if (!isObject(invSnap) || invSnap.schema !== 1 || invSnap.prd !== doc.prd) problem(`coverage snapshot ${expectedSnapshots.inventory}: must be schema 1 for ${doc.prd}`);
+    else {
+      const bad = requirements.validateSnapshot({ digest: invSnap.digest, projection: invSnap.projection, requirements: invSnap.requirements, scenarios: invSnap.scenarios }, doc.prd);
+      if (bad) problem(`coverage snapshot ${expectedSnapshots.inventory}: ${bad}`);
+      else if (invSnap.digest !== cov.inventory) problem(`coverage.inventory ${String(cov.inventory).slice(0, 12)} does not equal the inventory snapshot digest ${invSnap.digest.slice(0, 12)}`);
+      else inv = invSnap;
+    }
+  }
+  if (mapSnap) {
+    if (!isObject(mapSnap) || mapSnap.schema !== 1 || !isObject(mapSnap.map)) problem(`coverage snapshot ${expectedSnapshots.map}: must be schema 1 with the map object`);
+    else {
+      const why = changeId ? coverage.validateMap(mapSnap.map, { change: changeId, prd: doc.prd, root: null }) : 'no change id';
+      if (why) problem(`coverage snapshot ${expectedSnapshots.map}: ${why}`);
+      else {
+        mapNormalized = coverage.normalize(mapSnap.map);
+        if (coverage.digestOf(mapNormalized) !== cov.map || mapSnap.digest !== cov.map) problem(`coverage.map ${String(cov.map).slice(0, 12)} does not equal the map snapshot digest`);
+        else if (mapSnap.path !== coverage.file(changeId)) problem(`coverage snapshot ${expectedSnapshots.map}: path must be ${coverage.file(changeId)}`);
+        else mapDoc = mapSnap.map;
+      }
+    }
+  }
+  // Adequacy and delivery shape.
+  const adequacy = doc.adequacy;
+  if (!isObject(adequacy) || !ADEQUACY.includes(adequacy.verdict) || !nonempty(adequacy.note) || Object.keys(adequacy).some(k => !['verdict', 'note'].includes(k))) problem('adequacy must be { verdict: "adequate" | "inadequate", note } with a nonempty note (the reviewer\'s judgment)');
+  else if (adequacy.verdict === 'inadequate') problem(`adequacy verdict is inadequate ("${adequacy.note}") — readiness is blocked until the reviewer judges the checks adequate on a new evaluation`);
+  const delivery = doc.delivery;
+  if (!isObject(delivery) || typeof delivery.original !== 'boolean' || typeof delivery.agreed !== 'boolean' || Object.keys(delivery).some(k => !['original', 'agreed'].includes(k))) problem('delivery must be { original: boolean, agreed: boolean }');
+  if (!inv || !mapDoc) return;
+  // Declared checks: every one appears, with its kind, required flag and definition digest; nothing undeclared.
+  for (const [id, c] of Object.entries(mapDoc.checks)) {
+    const row = checks.get(id);
+    if (!row) { problem(`declared check ${id} (${c.required ? 'required' : 'optional'} ${c.kind}) is missing from checks — an unused failing required check cannot be omitted`); continue; }
+    if (row.kind !== c.kind) problem(`check ${id}: kind ${row.kind} disagrees with the declaration (${c.kind})`);
+    if (row.required !== c.required) problem(`check ${id}: required ${row.required} disagrees with the declaration (${c.required})`);
+    const declared = coverage.definitionDigest(c);
+    if (row.declared !== declared) problem(`check ${id}: declared ${String(row.declared).slice(0, 12)} is not the declaration's digest ${declared.slice(0, 12)}`);
+    if (c.kind === 'command' && isObject(row.attempt) && row.attempt.check_digest !== declared) problem(`check ${id}: the attempt ran ${String(row.attempt.check_digest).slice(0, 12)}, not the declared command and timeout (${declared.slice(0, 12)}) — a substituted command is not evidence for the declaration`);
+  }
+  for (const id of checks.keys()) if (!mapDoc.checks[id]) problem(`check ${id} is not declared in the coverage map snapshot`);
+  // Scenario rows: exactly the inventory's scenarios plus removed tombstones, once each, with the map's links.
+  const tombstones = Object.keys(mapDoc.scope).filter(id => mapDoc.scope[id].disposition === 'removed' && !inv.scenarios[id]);
+  const expectedRows = new Set([...Object.keys(inv.scenarios), ...tombstones]);
+  const rows = new Map();
+  if (!Array.isArray(doc.scenarios)) { problem('scenarios must be an array with one row per scenario of the inventory snapshot'); return; }
+  const passed = id => { const c = checks.get(id); return Boolean(c) && c.result === 'passed'; };
+  for (const [sid, srow] of Object.entries(mapDoc.scenarios || {}))
+    for (const c of (srow && Array.isArray(srow.checks) ? srow.checks : []))
+      if (!mapDoc.checks[c]) problem(`the coverage snapshot links ${sid} to ${c}, which it does not declare`);
+  const derive = (id, row) => {
+    const scope = mapDoc.scope[id];
+    if (scope) return scope.disposition;
+    const linked = mapDoc.scenarios[id] ? mapDoc.scenarios[id].checks : [];
+    // A link to a check the map snapshot does not declare is not a satisfied
+    // obligation: it is an obligation nothing can have verified.
+    return linked.length && linked.every(c => mapDoc.checks[c] && (!mapDoc.checks[c].required || passed(c))) ? 'delivered' : 'blocked';
+  };
+  doc.scenarios.forEach((row, index) => {
+    const label = `scenarios[${index}]`;
+    if (!isObject(row)) { problem(`${label} must be an object`); return; }
+    for (const k of Object.keys(row)) if (!SCENARIO_KEYS.includes(k)) problem(`${label}: unknown key "${k}"`);
+    for (const k of SCENARIO_KEYS) if (!(k in row)) problem(`${label}: missing key "${k}"`);
+    const id = typeof row.id === 'string' ? row.id : null;
+    if (!id) { problem(`${label}.id must be a scenario ID`); return; }
+    if (rows.has(id)) { problem(`duplicate scenario row ${id}`); return; }
+    rows.set(id, row);
+    if (!expectedRows.has(id)) { problem(`scenario ${id} is not a scenario of the inventory snapshot (an invented row)`); return; }
+    const live = inv.scenarios[id];
+    if (live && row.requirement !== live.requirement) problem(`scenario ${id}: requirement ${row.requirement} disagrees with the inventory (${live.requirement})`);
+    if (!DISPOSITIONS_3.includes(row.disposition)) problem(`scenario ${id}: disposition must be one of ${DISPOSITIONS_3.join(', ')}`);
+    const expected = derive(id, row);
+    if (row.disposition !== expected) problem(`scenario ${id}: disposition ${row.disposition} is not what the map and the outcomes give (${expected})`);
+    const mapRow = mapDoc.scenarios[id];
+    const same = (a, b) => JSON.stringify([...a].sort()) === JSON.stringify([...b].sort());
+    if (mapRow) {
+      if (!Array.isArray(row.tickets) || !same(row.tickets, mapRow.tickets)) problem(`scenario ${id}: tickets disagree with the map (${mapRow.tickets.join(', ')})`);
+      if (!Array.isArray(row.checks) || !same(row.checks, mapRow.checks)) problem(`scenario ${id}: checks disagree with the map (${mapRow.checks.join(', ')})`);
+      if (row.decision !== null || row.authorization !== null) problem(`scenario ${id}: an in-scope row carries null decision and authorization`);
+    } else {
+      if (!Array.isArray(row.tickets) || row.tickets.length || !Array.isArray(row.checks) || row.checks.length) problem(`scenario ${id}: a dispositioned row carries no tickets or checks`);
+      if (typeof row.decision !== 'string' || !/^D-[0-9]{2,6}$/.test(row.decision) || row.decision !== mapDoc.scope[id].decision) problem(`scenario ${id}: decision must be the map's ${mapDoc.scope[id].decision}`);
+      if (typeof row.authorization !== 'string' || !/^A-[0-9]{2,6}$/.test(row.authorization)) problem(`scenario ${id}: a ${row.disposition} row names the user authorization A-NN that covers its decision`);
+    }
+    if (row.note !== null && !shortText(row.note)) problem(`scenario ${id}: note must be null or a short string`);
+    if (row.disposition === 'blocked') problem(`scenario ${id} is blocked — readiness is blocked until every required check it links passes on a new candidate or the scenario is dispositioned with authorization`);
+  });
+  for (const id of expectedRows) if (!rows.has(id)) problem(`scenario ${id} of the inventory snapshot has no row (an omitted obligation)`);
+  // Requirement rows: exactly the inventory's requirements; rolled up from their scenarios.
+  for (const id of Object.keys(inv.requirements)) {
+    const req = reqRows.get(id);
+    if (!req) { problem(`requirement ${id} of the inventory snapshot has no row`); continue; }
+    const expectedScenarios = inv.requirements[id].scenarios;
+    if (!Array.isArray(req.scenarios) || JSON.stringify([...req.scenarios].sort()) !== JSON.stringify([...expectedScenarios].sort())) problem(`requirement ${id}: scenarios disagree with the inventory (${expectedScenarios.join(', ')})`);
+    const states = expectedScenarios.map(sid => (rows.get(sid) || {}).disposition);
+    const roll = states.every(x => x === 'delivered') ? 'delivered' : states.every(x => x === 'removed') ? 'removed' : states.every(x => ['delivered', 'deferred', 'removed'].includes(x)) ? 'deferred' : 'blocked';
+    if (req.disposition !== roll) problem(`requirement ${id}: disposition ${req.disposition} is not the roll-up of its scenarios (${roll})`);
+  }
+  for (const id of reqRows.keys()) if (!inv.requirements[id]) problem(`requirement ${id} is not a requirement of the inventory snapshot (an invented row)`);
+  const original = [...expectedRows].every(id => inv.scenarios[id] && (rows.get(id) || {}).disposition === 'delivered');
+  const agreed = [...expectedRows].every(id => ['delivered', 'deferred', 'removed'].includes((rows.get(id) || {}).disposition));
+  if (isObject(delivery) && (delivery.original !== original || delivery.agreed !== agreed)) problem(`delivery { original: ${original}, agreed: ${agreed} } is what the rows give, not { original: ${delivery.original}, agreed: ${delivery.agreed} }`);
+  // Independent reconciliation with the committed candidate, when the repository is available.
+  if (typeof doc.candidate !== 'string' || !HEX40.test(doc.candidate) || !changeId) return;
+  const show = rel => tryGit(root, ['show', `${doc.candidate}:${rel}`]);
+  // Only a commit that does not resolve is "not available": a commit that is present
+  // but missing a blob is a problem with the evidence, and the map and the change
+  // record must still be reconciled against it.
+  if (tryGit(root, ['rev-parse', '--verify', `${doc.candidate}^{commit}`]).error) {
+    opts.limitations.push(`the candidate ${doc.candidate.slice(0, 7)} is not available in this repository; the snapshots were validated against themselves only`);
+    return;
+  }
+  const prdShown = show(doc.prd);
+  const parsed = prdShown.error ? null : requirements.parseInventory(prdShown.out, { prd: doc.prd });
+  if (prdShown.error) problem(`the candidate carries no ${doc.prd}`);
+  else if (!parsed.ok) problem(`the candidate's PRD does not parse strictly (${parsed.problems[0]})`);
+  else if (parsed.inventory.digest !== cov.inventory) {
+    const d = requirements.difference(inv, requirements.snapshotOf(parsed.inventory));
+    const extra = d.scenarios.added.length ? `the candidate's PRD defines ${d.scenarios.added.join(', ')}, which the manifest omits` : d.scenarios.removed.length ? `the manifest lists ${d.scenarios.removed.join(', ')}, which the candidate's PRD does not define` : d.scenarios.changed.length ? `${d.scenarios.changed.map(c => c.id).join(', ')} differ from the candidate's PRD` : 'the inventory differs';
+    problem(`coverage.inventory does not equal the inventory of the candidate's PRD: ${extra}`);
+  }
+  const mapShown = show(coverage.file(changeId));
+  if (mapShown.error) problem(`the candidate carries no ${coverage.file(changeId)}`);
+  else {
+    const v = coverage.validateText(mapShown.out, { change: changeId, prd: doc.prd });
+    if (v.problem) problem(`the candidate's coverage map cannot be read (${v.problem})`);
+    else if (v.digest !== cov.map) problem(`coverage.map does not equal the digest of the candidate's ${coverage.file(changeId)} (a substituted map)`);
+  }
+  const recShown = show(`.prd/changes/${changeId}.json`);
+  if (recShown.error) problem(`the candidate carries no change record .prd/changes/${changeId}.json`);
+  else {
+    let rec = null;
+    try { rec = JSON.parse(recShown.out); } catch { rec = null; }
+    if (!rec || rec.schema !== 3) problem(`the candidate's change record is not a strict (schema 3) record`);
+    else {
+      const entry = (rec.agreements || []).find(g => g.digest === cov.agreement);
+      if (!entry) problem(`coverage.agreement ${cov.agreement.slice(0, 12)} is not an agreement of the candidate's change record`);
+      else if (entry.inventory !== cov.inventory || entry.coverage !== cov.map) problem(`agreement ${entry.id} binds inventory ${String(entry.inventory).slice(0, 12)} and map ${String(entry.coverage).slice(0, 12)}, not the manifest's`);
+      const auth = (rec.authorizations || []).find(a => a.id === cov.authorization);
+      if (!auth || auth.digest !== cov.agreement) problem(`coverage.authorization ${cov.authorization} does not bind agreement ${cov.agreement.slice(0, 12)} in the candidate's change record`);
+      // A non-delivered row is only as good as the decision and the user authorization
+      // the candidate's own record carries — the same rule the local report applies.
+      const dispositions = require('./dispositions.cjs');
+      for (const [id, row] of rows) {
+        if (row.disposition !== 'deferred' && row.disposition !== 'removed') continue;
+        const decision = (rec.decisions || []).find(d => d.id === row.decision);
+        if (!decision) { problem(`scenario ${id}: decision ${row.decision} is not a decision of the candidate's change record`); continue; }
+        if (decision.status !== 'resolved') { problem(`scenario ${id}: decision ${row.decision} is ${decision.status} in the candidate's change record, not resolved`); continue; }
+        if (!dispositions.namesId(decision, id)) { problem(`scenario ${id}: decision ${row.decision} does not name ${id}`); continue; }
+        const named = (rec.authorizations || []).find(a => a.id === row.authorization);
+        if (!named) { problem(`scenario ${id}: authorization ${row.authorization} is not an authorization of the candidate's change record`); continue; }
+        const applicable = dispositions.applicableUserAuthorization(rec, named, row.decision);
+        if (!applicable.authorization) problem(`scenario ${id}: authorization ${row.authorization} does not carry a user decision for ${row.decision} (${applicable.reason})`);
+      }
+    }
+  }
+}
 
 // Schema 2: every check declares its provenance; a passed or failed command
 // result exists only as a runtime attempt whose log digest the manifest carries.
@@ -294,16 +498,46 @@ function validateProvenance(check, name, doc, problem) {
 // Build the candidate evidence set from a draft of authored fields and the
 // runtime's attempts for the candidate. Never invents a review transcript and
 // never converts a review judgment into a command result.
-function exportEvidence(root, { candidate, base, prd, draft, binding, attemptsFor, environment, now, atomicWrite }) {
+// `strict` (schema 3): { inventory, map, mapDigest, graph, scope: [{ id, disposition,
+// decision, authorization }], agreement, authorization } — the draft then carries
+// no requirements (dispositions are derived), every declared check appears once,
+// command entries are populated from the declaration, and the inventory and map
+// snapshots are written as listed artifacts.
+function exportEvidence(root, { candidate, base, prd, draft, binding, attemptsFor, environment, now, atomicWrite, strict = null }) {
   const version = prd.match(PRD_REF)[1];
   const dirRel = `.prd/evidence/prd-v${version}/${candidate}`;
   const dirAbs = path.join(root, dirRel);
   const problems = [];
   if (!isObject(draft)) return { problems: ['draft must be a JSON object'] };
-  const allowed = ['environment', 'coverage_review', 'requirements', 'checks', 'visual_review'];
-  for (const key of Object.keys(draft)) if (!allowed.includes(key)) problems.push(`draft: unknown key "${key}" (allowed: ${allowed.join(', ')})`);
+  const allowed = strict ? ['environment', 'coverage_review', 'adequacy', 'checks', 'visual_review'] : ['environment', 'coverage_review', 'requirements', 'checks', 'visual_review'];
+  for (const key of Object.keys(draft)) if (!allowed.includes(key)) problems.push(`draft: unknown key "${key}" (allowed: ${allowed.join(', ')})${strict && key === 'requirements' ? ' — dispositions are derived from the map and the outcomes in a strict change' : ''}`);
   if (!Array.isArray(draft.checks)) problems.push('draft.checks must be an array');
+  if (strict && (!isObject(draft.adequacy) || !ADEQUACY.includes(draft.adequacy.verdict) || !nonempty(draft.adequacy.note))) problems.push('draft.adequacy must be { verdict: "adequate" | "inadequate", note } — the reviewer\'s judgment that the checks establish their scenarios');
   if (problems.length) return { problems };
+  if (strict) {
+    // Every declared check exactly once; nothing undeclared; command entries come from the declaration.
+    const ids = draft.checks.filter(isObject).map(s => s.id);
+    for (const [id, c] of Object.entries(strict.map.checks)) if (!ids.includes(id)) problems.push(`draft check ${id} (${c.required ? 'required' : 'optional'} ${c.kind}) is missing: every declared check appears in the draft — an unused failing required check cannot be omitted`);
+    for (const id of ids) if (!strict.map.checks[id]) problems.push(`draft check ${id} is not declared in the coverage map`);
+    if (new Set(ids).size !== ids.length) problems.push('draft checks name a declared check twice');
+    if (problems.length) return { problems };
+    draft = { ...draft, checks: draft.checks.map(s => {
+      const c = strict.map.checks[s.id];
+      if (c.kind === 'command') {
+        if ('kind' in s && s.kind !== 'command') problems.push(`draft check ${s.id}: kind ${s.kind} disagrees with the declaration (command)`);
+        if ('required' in s && s.required !== c.required) problems.push(`draft check ${s.id}: required ${s.required} disagrees with the declaration (${c.required})`);
+        if ('command' in s && s.command !== c.command) problems.push(`draft check ${s.id}: the command text disagrees with the declaration`);
+        if ('result' in s) problems.push(`draft check ${s.id}: a command result cannot be authored; it is populated from the runtime attempt`);
+        return { id: s.id, kind: 'command', required: c.required, ...(s.note ? { note: s.note } : {}), ...(Array.isArray(s.artifacts) ? { artifacts: s.artifacts } : {}) };
+      }
+      if ('required' in s && s.required !== c.required) problems.push(`draft check ${s.id}: required ${s.required} disagrees with the declaration (${c.required})`);
+      if ('kind' in s && s.kind !== c.kind) problems.push(`draft check ${s.id}: kind ${s.kind} disagrees with the declaration (${c.kind})`);
+      return { ...s, kind: c.kind, required: c.required };
+    }) };
+    const reviews = require('./checks.cjs').reviewProblems(strict.map, Object.fromEntries(draft.checks.map(s => [s.id, s])), { dirRel, root });
+    for (const p of reviews) problems.push(`${p.code}: ${p.detail}`);
+    if (problems.length) return { problems };
+  }
   const env = isObject(draft.environment) ? draft.environment : {};
   const checks = [];
   const artifactPaths = new Set();
@@ -330,8 +564,12 @@ function exportEvidence(root, { candidate, base, prd, draft, binding, attemptsFo
     if (!attempt) { problems.push(`draft check ${stub.id}: no runtime attempt for candidate ${candidate}; run: node scripts/pincer-runtime.cjs check ${stub.id} --candidate ${candidate} -- <command>`); continue; }
     // The record must be complete, written for this check, and its captured
     // logs must still match the digests it recorded; anything else is refused.
-    const invalid = validateAttempt(attempt, contextKey({ kind: 'candidate', candidate, check: stub.id }), pointed || null);
+    const changesMode = binding.mode === 'changes';
+    const invalid = validateAttempt(attempt, contextKey({ kind: 'candidate', change: binding.change, candidate, check: stub.id, mode: binding.mode }), pointed || null);
     if (invalid) { problems.push(`draft check ${stub.id}: attempt ${typeof attempt.id === 'string' ? attempt.id : '?'} ${invalid}; run the check again`); continue; }
+    const wanted = changesMode ? (binding.strict ? 3 : 2) : 1;
+    if (changesMode && attempt.schema !== wanted) { problems.push(`draft check ${stub.id}: attempt ${attempt.id} was recorded under schema ${attempt.schema} (${attempt.schema < wanted ? (wanted === 3 ? 'before this change adopted strict coverage' : 'before this project used change records') : 'for a strict change; this change has not adopted strict coverage'}) and is history; run the check again`); continue; }
+    if (changesMode && attempt.context.change !== binding.change) { problems.push(`draft check ${stub.id}: attempt ${attempt.id} belongs to change ${attempt.context.change}, not ${binding.change}; run the check again`); continue; }
     if (attempt.outcome === 'running') { problems.push(`draft check ${stub.id}: attempt ${attempt.id} is still running`); continue; }
     const logRel = `${dirRel}/checks/${stub.id}.log`;
     const pieces = [`$ ${(attempt.check && attempt.check.display) || ''}`.replace(/\n$/, ''), ''];
@@ -368,6 +606,17 @@ function exportEvidence(root, { candidate, base, prd, draft, binding, attemptsFo
     });
   }
   if (problems.length) return { problems };
+  // Strict: the declaration digest per check, the inventory and map snapshots as listed artifacts.
+  let strictParts = null;
+  if (strict) {
+    for (const c of checks) c.declared = coverage.definitionDigest(strict.map.checks[c.id]);
+    const invSnap = requirements.snapshotOf(strict.inventory);
+    const inventoryRel = `${dirRel}/coverage/inventory.json`, mapRel = `${dirRel}/coverage/map.json`;
+    atomicWrite(path.join(root, inventoryRel), `${JSON.stringify({ schema: 1, prd, digest: invSnap.digest, projection: invSnap.projection, requirements: invSnap.requirements, scenarios: invSnap.scenarios }, null, 2)}\n`);
+    atomicWrite(path.join(root, mapRel), `${JSON.stringify({ schema: 1, path: coverage.file(binding.change), digest: strict.mapDigest, map: strict.map }, null, 2)}\n`);
+    artifactPaths.add(inventoryRel); artifactPaths.add(mapRel);
+    strictParts = { inventoryRel, mapRel, invSnap };
+  }
   const artifacts = [];
   for (const p of [...artifactPaths].sort()) {
     const abs = path.join(root, p);
@@ -376,15 +625,51 @@ function exportEvidence(root, { candidate, base, prd, draft, binding, attemptsFo
   }
   if (problems.length) return { problems };
   const manifest = {
-    schema: 2, prd, base, candidate, created: now,
+    schema: strict ? 3 : 2, prd, base, candidate, created: now,
     environment: { os: environment.os, node: environment.node, tools: env.tools || [], limitations: env.limitations || [] },
     coverage_review: draft.coverage_review, requirements: draft.requirements, checks, visual_review: draft.visual_review, artifacts,
     change: { id: binding.change, prd_revision: binding.prd_revision, base: binding.base },
   };
+  if (strict) {
+    // Rows are derived: a scenario is delivered when every required check it links passed;
+    // a dispositioned one names its decision and the user authorization covering it.
+    const passed = new Set(checks.filter(c => c.result === 'passed').map(c => c.id));
+    const inv = strictParts.invSnap;
+    const scopeAuth = Object.fromEntries((strict.scope || []).map(s => [s.id, s]));
+    const scenarioRows = [];
+    const ids = requirements.sortIds([...new Set([...Object.keys(inv.scenarios), ...Object.keys(strict.map.scope).filter(id => strict.map.scope[id].disposition === 'removed')])]);
+    for (const id of ids) {
+      const scope = strict.map.scope[id];
+      if (scope) {
+        const g = strict.graph.scope[id] || {};
+        scenarioRows.push({ id, requirement: inv.scenarios[id] ? inv.scenarios[id].requirement : g.requirement || null, disposition: scope.disposition, tickets: [], checks: [], decision: scope.decision, authorization: scopeAuth[id] ? scopeAuth[id].authorization : null, note: scope.note });
+        continue;
+      }
+      const row = strict.map.scenarios[id];
+      const delivered = row.checks.every(c => !strict.map.checks[c].required || passed.has(c));
+      scenarioRows.push({ id, requirement: inv.scenarios[id].requirement, disposition: delivered ? 'delivered' : 'blocked', tickets: requirements.sortIds(row.tickets), checks: requirements.sortIds(row.checks), decision: null, authorization: null, note: null });
+    }
+    const rowOf = Object.fromEntries(scenarioRows.map(r => [r.id, r]));
+    const requirementRows = requirements.sortIds(Object.keys(inv.requirements)).map(id => {
+      const scen = inv.requirements[id].scenarios;
+      const states = scen.map(sid => rowOf[sid].disposition);
+      const disposition = states.every(x => x === 'delivered') ? 'delivered' : states.every(x => x === 'removed') ? 'removed' : states.every(x => ['delivered', 'deferred', 'removed'].includes(x)) ? 'deferred' : 'blocked';
+      const tickets = requirements.sortIds([...new Set(scen.flatMap(sid => rowOf[sid].tickets))]);
+      const checkIds = requirements.sortIds([...new Set(scen.flatMap(sid => rowOf[sid].checks))]);
+      const decisions = [...new Set(scen.map(sid => rowOf[sid].decision).filter(Boolean))];
+      return { id, disposition, tickets, checks: checkIds, scenarios: [...scen], decision: decisions.length === 1 && disposition !== 'delivered' && disposition !== 'blocked' ? decisions[0] : null, authorization: decisions.length === 1 && disposition !== 'delivered' && disposition !== 'blocked' ? (scen.map(sid => rowOf[sid].authorization).find(Boolean) || null) : null, note: null };
+    });
+    manifest.requirements = requirementRows;
+    manifest.coverage = { agreement: strict.agreement, authorization: strict.authorization, inventory: inv.digest, map: strict.mapDigest, snapshots: { inventory: strictParts.inventoryRel, map: strictParts.mapRel } };
+    manifest.scenarios = scenarioRows;
+    manifest.adequacy = { verdict: draft.adequacy.verdict, note: draft.adequacy.note };
+    manifest.delivery = { original: scenarioRows.every(r => inv.scenarios[r.id] && r.disposition === 'delivered'), agreed: scenarioRows.every(r => ['delivered', 'deferred', 'removed'].includes(r.disposition)) };
+  }
   const manifestRel = `${dirRel}/manifest.json`;
   atomicWrite(path.join(root, manifestRel), `${JSON.stringify(manifest, null, 2)}\n`);
-  const validation = validate(path.join(root, manifestRel), { candidate, base, prd }, root);
-  return { manifest: manifestRel, problems: validation };
+  const validationOpts = { candidate, base, prd };
+  const validation = validate(path.join(root, manifestRel), validationOpts, root);
+  return { manifest: manifestRel, problems: validation, limitations: validationOpts.limitations || [], schema: manifest.schema, delivery: manifest.delivery || null };
 }
 
 

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

@@ -0,0 +1,73 @@
+'use strict';
+// PINCER runtime — command gates (docs/runtime-contracts.md, "Command gates").
+// In changes mode every execution or lifecycle-writing command passes this one
+// guard before a child process is spawned or a ticket file written: the
+// records must be readable, a change must be selected and own the ticket (or
+// PRD), its lifecycle state must permit the command, the repository view must
+// be compatible, and the authorization verdict must be `current`. Refusals carry
+// the contracted code, in the contracted order, and nothing has been written.
+const changes = require('./changes.cjs');
+const agreement = require('./agreement.cjs');
+const authorization = require('./authorization.cjs');
+const { refuse } = require('./transaction.cjs');
+
+// Lifecycle states that permit each command.
+const PERMITTED = {
+  start: ['active'], done: ['active'], verify: ['active', 'completed'],
+  check: ['completed'], export: ['completed'],
+};
+const ORDER = ['INPUT_INVALID', 'INVENTORY_INVALID', 'COVERAGE_INVALID', 'MALFORMED', 'UNSUPPORTED_SCHEMA', 'HISTORY_INVALID', 'STATE_INCOMPLETE', 'SELECTION_REQUIRED', 'SELECTION_INVALID', 'WRONG_CHANGE', 'LIFECYCLE_BLOCKED', 'BASE_MISMATCH', 'DECISION_REQUIRED', 'AUTHORIZATION_REQUIRED', 'AGREEMENT_CHANGED'];
+
+// guard(root, { command, ticket: { file, fields } | null, prd: string | null })
+// Returns { id, record, file, selection, view, computed, verdict, binding } where
+// `binding` is the context every attempt, readiness and export consumes:
+// { change, prd, prd_revision, base, agreement, legacy_receipts, mode: 'changes' }.
+// Throws a transaction Refusal on the first failing gate.
+function guard(root, { command, ticket = null, prd = null }) {
+  const resolved = changes.resolveSelected(root, {});
+  if (resolved.code) {
+    const hint = resolved.code === 'SELECTION_REQUIRED' || resolved.code === 'SELECTION_INVALID' ? ` (execution needs the selected change; ${resolved.problem})` : `: ${resolved.problem}`;
+    refuse(resolved.code, `${command} refused${hint}`);
+  }
+  const { id, record, file, selection, loaded } = resolved;
+  // Ownership: the ticket's PRD, or the named PRD, must belong to the selected change.
+  let owner = null;
+  if (ticket) {
+    const o = changes.ticketOwner(root, loaded, ticket.file, ticket.fields);
+    if (o.problem) refuse(o.id ? 'WRONG_CHANGE' : 'INPUT_INVALID', `${command} refused: ${o.problem}`);
+    owner = o;
+  } else if (prd) {
+    const o = changes.ownerOf(loaded, prd);
+    if (!o) refuse('INPUT_INVALID', `${command} refused: ${prd} is owned by no change record; register it first`);
+    owner = { id: o[0], prd };
+  }
+  if (owner && owner.id !== id) refuse('WRONG_CHANGE', `${command} refused: ${ticket ? `${ticket.fields.ticket} (${owner.prd})` : owner.prd} belongs to change ${owner.id}, but ${id} is selected; select it first: node scripts/pincer-runtime.cjs change select ${owner.id}`);
+  const st = record.lifecycle.state;
+  if (!PERMITTED[command].includes(st)) {
+    const next = changes.TERMINAL.includes(st) ? `the change is ${st}${record.lifecycle.superseded_by ? ` by ${record.lifecycle.superseded_by}` : ''}; register a new change and reference this one`
+      : st === 'planned' ? `activate it first: node scripts/pincer-runtime.cjs change activate ${id}`
+        : st === 'paused' ? `resume it first: node scripts/pincer-runtime.cjs change resume ${id}${record.lifecycle.reason ? ` (paused: ${record.lifecycle.reason})` : ''}`
+          : st === 'completed' ? `${command} needs an active change; reopen it first: node scripts/pincer-runtime.cjs change reopen ${id} --reason <text>`
+            : `${command} needs a completed change; complete it first: node scripts/pincer-runtime.cjs change complete ${id}`;
+    refuse('LIFECYCLE_BLOCKED', `${command} refused: change ${id} is ${st} (${command} runs on ${PERMITTED[command].join(' or ')} changes); ${next}`);
+  }
+  const view = changes.view(root, record);
+  if (view.problems.length) refuse('BASE_MISMATCH', `${command} refused: ${view.problems[0].detail}`);
+  const computed = agreement.compute(root, record);
+  if (computed.code) refuse(computed.code, `${command} refused: ${computed.problem}`);
+  const verdict = authorization.verdict(root, record, computed);
+  if (verdict.verdict !== 'current') refuse(verdict.verdict, `${command} refused: ${verdict.detail}`);
+  // A strict change's binding carries its inventory and coverage map digests (attempt schema 3).
+  const binding = { change: id, prd: record.prd, prd_revision: computed.prd.revision, base: record.base, agreement: computed.digest, legacy_receipts: record.legacy.receipts, mode: 'changes', strict: Boolean(computed.inventory), ...(computed.inventory ? { inventory: computed.inventory.digest, coverage: computed.coverage.digest } : {}) };
+  return { id, record, file, selection, view, computed, verdict, binding, loaded };
+}
+
+// The read-only counterpart for status/ready: the same checks as reasons, none thrown.
+function reasons(root, { command, ticket = null, prd = null }) {
+  try { guard(root, { command, ticket, prd }); return []; } catch (error) {
+    if (error && error.refusal) return [{ code: error.code, detail: error.message }];
+    throw error;
+  }
+}
+
+module.exports = { guard, reasons, PERMITTED, ORDER };

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

@@ -14,6 +14,7 @@ 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');
+const CHANGES_HINT = 'this project keeps change records (schema 2) under .prd/changes/; inspect them with: node scripts/pincer-runtime.cjs change list';
 function listBindings(root) {
   const dir = bindingsDir(root);
   if (!fs.existsSync(dir)) return [];
@@ -41,6 +42,22 @@ function validateBinding(doc) {
 // 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 } = {}) {
+  // Mode first (docs/runtime-contracts.md, "Modes"): schema 2 records are the
+  // changes mode and never fall back to a binding or to legacy; mixed or
+  // unreadable directories are invalid.
+  const scan = require('./changes.cjs').scan(root);
+  if (scan.mode === 'changes') return { code: 'CHANGES_MODE', problem: `${CHANGES_HINT}`, scan };
+  if (scan.mode === 'invalid') return { code: scan.problems[0].code, problem: scan.problems[0].detail, scan };
+  // A committed transaction that was not fully applied is unsafe in every mode, not
+  // only in changes mode: `recover` finishes it by renaming its staged files into
+  // place, over anything written since. Changes mode raises this through
+  // changes.scan(); a migrated or legacy project reaches it here, and a migrated
+  // project is the one `migrate --apply` crashes in.
+  const pending = require('./transaction.cjs').pending(root);
+  if (pending.committed.length) {
+    const first = pending.committed[0];
+    return { code: 'STATE_INCOMPLETE', problem: `a committed transaction (${first.command || first.id}) was not fully applied; run: node scripts/pincer-runtime.cjs recover` };
+  }
   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';
@@ -117,11 +134,11 @@ function register(root, { prd, change, authorization = null, replace = false, re
     if (invalid) return { code: 'MALFORMED', problem: `${files[0]}: ${invalid} — repair or remove it before registering` };
     existing = { file: files[0], binding: read.data };
   }
+  // v0.5.0 replaced the binding here (deleting the other PRD's); several changes
+  // are retained only by schema 2 records, so a second PRD needs the migration.
+  if (replace) return { code: 'MIGRATION_REQUIRED', problem: `--replace would delete ${existing ? existing.file : 'the binding'}; change records are retained instead — migrate first: node scripts/pincer-runtime.cjs migrate --preview --prd ${existing ? existing.binding.prd : prd}, then register ${prd} and select the change to work on with change select (retire one with change supersede or change cancel)` };
   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 };
+    return { code: 'MIGRATION_REQUIRED', problem: `${existing.file} binds ${existing.binding.prd} as change "${existing.binding.change}"; one binding per worktree in migrated mode — migrate to change records first: node scripts/pincer-runtime.cjs migrate --preview --prd ${existing.binding.prd}, then register ${prd}` };
   }
   if (existing) {
     const current = existing.binding;