pincer-workflow 0.4.1 → 0.6.0

package/template/scripts/pincer-evidence.cjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 'use strict';
-// PINCER evidence — read-only validator for candidate evidence manifests
-// (evidence schema 1). Dependency-free; runs under `node` on any platform.
+// PINCER evidence — read-only validator for candidate evidence manifests.
+// Dependency-free; runs under `node` on any platform. The implementation lives
+// in scripts/pincer-runtime/evidence.cjs (shared with status and release).
 //
 //   node scripts/pincer-evidence.cjs validate .prd/evidence/prd-vN/<candidate>/manifest.json \
 //        [--candidate <sha>] [--base <sha>] [--prd .prd/prd-vN.md] [--files]
@@ -20,230 +21,12 @@
 // application; that judgment stays with the reviewer.
 const fs = require('node:fs');
 const path = require('node:path');
-const crypto = require('node:crypto');
-const { execFileSync } = require('node:child_process');
-
-const SCHEMA = 1;
-const HEX40 = /^[0-9a-f]{40}$/;
-const SHA256 = /^[0-9a-f]{64}$/;
-const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
-const PRD_REF = /^\.prd\/prd-v([1-9][0-9]{0,8})\.md$/;
-const MANIFEST_AT = /^\.prd\/evidence\/prd-v([1-9][0-9]{0,8})\/([0-9a-f]{40})\/manifest\.json$/;
-// Requirement IDs are the PRD's own: R-01 from the template, or a supplied PRD's
-// REQ-1 / AC-12 style, kept verbatim rather than renamed.
-const REQ_ID = /^[A-Z][A-Z0-9]{0,7}-[0-9]{1,6}$/;
-const TICKET_ID = /^T-[0-9]{2,6}$/;
-const CHECK_ID = /^C-[0-9]{2,6}$/;
-const IMAGE = /\.(png|jpe?g|webp)$/i;
-const MAX_TEXT = 2000; // guard against pasted environment dumps
-const TOP_KEYS = ['schema', 'prd', 'base', 'candidate', 'created', 'environment', 'coverage_review', 'requirements', 'checks', 'visual_review', 'artifacts'];
-const ENV_KEYS = ['os', 'node', 'tools', 'limitations'];
-const REQ_KEYS = ['id', 'disposition', 'tickets', 'checks', 'note', 'authorized_by'];
-const CHECK_KEYS = ['id', 'kind', 'required', 'result', 'command', 'timestamp', 'artifacts', 'scenario', 'viewport', 'observed', 'note'];
-const DISPOSITIONS = ['delivered', 'blocked', 'deferred'];
-const KINDS = ['command', 'visual', 'review'];
-const RESULTS = ['passed', 'failed', 'unverified'];
-
-const isObject = v => v !== null && typeof v === 'object' && !Array.isArray(v);
-const shortText = v => typeof v === 'string' && v.length <= MAX_TEXT;
-const nonempty = v => shortText(v) && v.trim() !== '';
-const toPosix = p => p.split(path.sep).join('/');
-
-function repoRoot() {
-  if (process.env.CLAUDE_PROJECT_DIR) return path.resolve(process.env.CLAUDE_PROJECT_DIR);
-  try {
-    return execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-  } catch {
-    return process.cwd();
-  }
-}
-
-// Resolve through symlinks above the repository (macOS /var -> /private/var)
-// without requiring the leaf to exist yet.
-function realpathDeep(p) {
-  try { return fs.realpathSync(p); } catch {
-    const parent = path.dirname(p);
-    return parent === p ? p : path.join(realpathDeep(parent), path.basename(p));
-  }
-}
-
-function digestFile(file) {
-  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
-}
-
-// Why a repository-relative path is unsafe, or null when it is acceptable.
-function unsafePath(p) {
-  if (p.startsWith('/')) return 'absolute paths are not allowed';
-  if (/^[A-Za-z]:/.test(p)) return 'drive-letter paths are not allowed';
-  if (p.includes('\\')) return 'backslashes are not allowed; use repository-relative POSIX paths';
-  if (p.split('/').some(s => s === '' || s === '.' || s === '..')) return 'path must be normalized and repository-relative (no "..", "." or empty segments)';
-  return null;
-}
-
-function validate(manifestArg, opts) {
-  const root = realpathDeep(repoRoot());
-  const abs = realpathDeep(path.resolve(manifestArg));
-  const rel = toPosix(path.relative(root, abs));
-  const at = rel.match(MANIFEST_AT);
-  if (!at) return [`manifest must live at .prd/evidence/prd-vN/<candidate>/manifest.json inside the repository (got ${rel})`];
-  const [, dirVersion, dirCandidate] = at;
-  const dirRel = path.posix.dirname(rel);
-
-  let raw;
-  try { raw = fs.readFileSync(abs, 'utf8'); } catch { return ['missing — run /pincer-evaluate to write evidence for this candidate']; }
-  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 (doc.schema !== SCHEMA) return [`unknown evidence schema ${JSON.stringify(doc.schema)} — this runtime validates schema ${SCHEMA}`];
-
-  const problems = [];
-  const problem = message => problems.push(message);
-  for (const key of Object.keys(doc)) if (!TOP_KEYS.includes(key)) problem(`unknown top-level key "${key}"`);
-  for (const key of TOP_KEYS) if (!(key in doc)) problem(`missing "${key}"`);
-
-  const prd = typeof doc.prd === 'string' ? doc.prd.match(PRD_REF) : null;
-  if (!prd) problem('prd must be a reference of the form .prd/prd-vN.md');
-  else if (prd[1] !== dirVersion) problem(`wrong PRD: manifest names ${doc.prd} but lives under prd-v${dirVersion}`);
-  if (opts.prd && doc.prd !== opts.prd) problem(`wrong PRD: manifest is for ${doc.prd}, expected ${opts.prd}`);
-
-  for (const key of ['base', 'candidate']) {
-    if (typeof doc[key] !== 'string' || !HEX40.test(doc[key])) problem(`${key} must be a full 40-hex commit ID`);
-  }
-  if (typeof doc.candidate === 'string' && HEX40.test(doc.candidate) && doc.candidate !== dirCandidate) {
-    problem(`wrong candidate: manifest names ${doc.candidate} but lives under ${dirCandidate}`);
-  }
-  if (opts.candidate && doc.candidate !== opts.candidate) problem(`wrong candidate: manifest is for ${doc.candidate}, expected ${opts.candidate}`);
-  if (opts.base && doc.base !== opts.base) problem(`wrong base: manifest records ${doc.base}, expected ${opts.base}`);
-  if (typeof doc.created !== 'string' || !ISO_UTC.test(doc.created)) problem('created must be an ISO-8601 UTC timestamp (YYYY-MM-DDTHH:MM:SSZ)');
-
-  const env = doc.environment;
-  if (!isObject(env)) problem('environment must be an object with os, node, tools and limitations');
-  else {
-    for (const key of ['os', 'node']) if (!nonempty(env[key])) problem(`environment.${key} must be a short nonempty string (redacted summary, not a dump)`);
-    for (const key of ['tools', 'limitations']) {
-      if (!Array.isArray(env[key]) || !env[key].every(nonempty)) problem(`environment.${key} must be an array of short strings`);
-    }
-    for (const key of Object.keys(env)) if (!ENV_KEYS.includes(key)) problem(`environment.${key} is not allowed — persist redacted summaries only`);
-  }
-  if (!nonempty(doc.coverage_review)) problem('coverage_review must be a nonempty string recording the reviewer judgment on requirement coverage');
-
-  // Artifacts: repository-contained regular files with matching digests.
-  const artifacts = new Map();
-  if (!Array.isArray(doc.artifacts)) problem('artifacts must be an array of {path, sha256}');
-  else doc.artifacts.forEach((entry, index) => {
-    const label = `artifacts[${index}]`;
-    if (!isObject(entry)) { problem(`${label} must be an object {path, sha256}`); return; }
-    for (const key of Object.keys(entry)) if (!['path', 'sha256'].includes(key)) problem(`${label}.${key} is not allowed`);
-    const p = entry.path;
-    if (typeof p !== 'string' || p === '') { problem(`${label}.path must be a nonempty string`); return; }
-    if (artifacts.has(p)) problem(`duplicate artifact path ${p}`);
-    artifacts.set(p, false);
-    const why = unsafePath(p);
-    if (why) { problem(`artifact ${p}: ${why}`); return; }
-    if (!p.startsWith(`${dirRel}/`)) { problem(`artifact ${p}: outside the evidence directory ${dirRel}/`); return; }
-    const digestOk = typeof entry.sha256 === 'string' && SHA256.test(entry.sha256);
-    if (!digestOk) problem(`artifact ${p}: sha256 must be a full 64-hex digest`);
-    const segments = p.split('/');
-    let current = root;
-    for (let i = 0; i < segments.length; i++) {
-      current = path.join(current, segments[i]);
-      let stat;
-      try { stat = fs.lstatSync(current); } catch { problem(`artifact ${p}: missing`); return; }
-      const last = i === segments.length - 1;
-      if (stat.isSymbolicLink()) {
-        problem(last ? `artifact ${p}: is a symlink (only regular files inside the repository are accepted)` : `artifact ${p}: path component ${segments.slice(0, i + 1).join('/')} is a symlink`);
-        return;
-      }
-      if (!last && !stat.isDirectory()) { problem(`artifact ${p}: ${segments.slice(0, i + 1).join('/')} is not a directory`); return; }
-      if (last && !stat.isFile()) { problem(`artifact ${p}: not a regular file`); return; }
-    }
-    if (digestOk && digestFile(current) !== entry.sha256) problem(`artifact ${p}: digest mismatch — the file changed after the evidence was recorded`);
-  });
-
-  // Checks: what was run or judged, with results and artifact references.
-  const checks = new Map();
-  let visualChecks = 0;
-  if (!Array.isArray(doc.checks)) problem('checks must be an array');
-  else doc.checks.forEach((check, index) => {
-    const label = `checks[${index}]`;
-    if (!isObject(check)) { problem(`${label} must be an object`); return; }
-    const id = typeof check.id === 'string' && CHECK_ID.test(check.id) ? check.id : null;
-    if (!id) problem(`${label}.id must be a check ID such as C-01`);
-    else if (checks.has(id)) problem(`duplicate check ID ${id}`);
-    else checks.set(id, check);
-    const name = id || label;
-    for (const key of Object.keys(check)) if (!CHECK_KEYS.includes(key)) problem(`check ${name}: unknown key "${key}"`);
-    if (!KINDS.includes(check.kind)) problem(`check ${name}: kind must be one of ${KINDS.join(', ')}`);
-    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`);
-    if (check.kind === 'command' && !nonempty(check.command)) problem(`check ${name}: command kind requires the command that was run`);
-    for (const key of ['command', 'scenario', 'viewport', 'observed', 'note']) {
-      if (key in check && !shortText(check[key])) problem(`check ${name}: ${key} must be a short string`);
-    }
-    let images = 0;
-    if (!Array.isArray(check.artifacts)) problem(`check ${name}: artifacts must be an array of repository-relative paths`);
-    else for (const p of check.artifacts) {
-      if (typeof p !== 'string') { problem(`check ${name}: artifact reference must be a string`); continue; }
-      if (!artifacts.has(p)) problem(`check ${name}: references unlisted artifact ${p} (dangling reference)`);
-      else artifacts.set(p, true);
-      if (IMAGE.test(p)) images++;
-    }
-    if (check.kind === 'visual') {
-      visualChecks++;
-      for (const key of ['scenario', 'viewport', 'observed']) if (!nonempty(check[key])) problem(`check ${name}: visual check requires ${key}`);
-      // A passed visual check must show its image; an unverified one (tool
-      // unavailable) is recorded honestly without one and, when required, blocks.
-      if (check.result === 'passed' && images === 0) problem(`check ${name}: a passed visual check requires a saved image artifact (.png, .jpg or .webp)`);
-    }
-    if (check.required === true && check.result !== 'passed') {
-      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`);
-
-  // Requirements: every ID dispositioned; deferrals authorized; checks resolve.
-  const requirements = new Set();
-  if (!Array.isArray(doc.requirements) || doc.requirements.length === 0) problem('requirements must be a nonempty array — every PRD requirement needs a disposition');
-  else doc.requirements.forEach((req, index) => {
-    const label = `requirements[${index}]`;
-    if (!isObject(req)) { problem(`${label} must be an object`); return; }
-    const id = typeof req.id === 'string' && REQ_ID.test(req.id) ? req.id : null;
-    if (!id) problem(`${label}.id must be a requirement ID such as R-01 or the PRD's own REQ-1 (uppercase prefix, dash, digits)`);
-    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(', ')}`);
-    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`);
-    if (req.disposition === 'blocked') problem(`requirement ${name} is blocked — readiness is blocked until it is delivered on a new candidate or deferred with authorization`);
-  });
-
-  const visual = doc.visual_review;
-  if (!isObject(visual) || typeof visual.applicable !== 'boolean') problem('visual_review must be {applicable: boolean, reason?: string}');
-  else {
-    for (const key of Object.keys(visual)) if (!['applicable', 'reason'].includes(key)) problem(`visual_review.${key} is not allowed`);
-    if (visual.applicable === false && !nonempty(visual.reason)) problem('visual_review.reason is required when visual review is not applicable (say why)');
-    if (visual.applicable === true && visualChecks === 0) problem('visual_review.applicable is true but no visual check is recorded');
-    if ('reason' in visual && !shortText(visual.reason)) problem('visual_review.reason must be a short string');
-  }
-
-  if (problems.length === 0 && opts.files) {
-    opts.list = [rel, ...doc.artifacts.map(a => a.path)];
-  }
-  return problems;
-}
+const { HEX40, PRD_REF, validate, digestFile } = require('./pincer-runtime/evidence.cjs');
+const io = require('./pincer-runtime/io.cjs');
 
 function usage(message) {
-  if (message) process.stderr.write(`pincer-evidence: ${message}\n`);
-  process.stderr.write('usage: pincer-evidence.cjs validate <manifest> [--candidate <sha>] [--base <sha>] [--prd .prd/prd-vN.md] [--files]\n       pincer-evidence.cjs digest <file>...\n');
+  if (message) io.err(`pincer-evidence: ${message}\n`);
+  io.err('usage: pincer-evidence.cjs validate <manifest> [--candidate <sha>] [--base <sha>] [--prd .prd/prd-vN.md] [--files]\n       pincer-evidence.cjs digest <file>...\n');
   process.exit(2);
 }
 
@@ -269,20 +52,21 @@ function main(argv) {
     if (opts.prd !== undefined && !PRD_REF.test(opts.prd)) usage('--prd must be of the form .prd/prd-vN.md');
     const problems = validate(manifest, opts);
     if (problems.length > 0) {
-      for (const p of problems) process.stderr.write(`evidence: ${manifest}: ${p}\n`);
+      for (const p of problems) io.err(`evidence: ${manifest}: ${p}\n`);
       process.exit(1);
     }
     const doc = JSON.parse(fs.readFileSync(path.resolve(manifest), 'utf8'));
-    process.stdout.write(`ok ${doc.candidate}\n`);
-    if (opts.files) for (const p of opts.list) process.stdout.write(`${p}\n`);
+    io.out(`ok ${doc.candidate}${doc.schema >= 2 ? ` schema ${doc.schema}` : ''}\n`);
+    for (const l of opts.limitations || []) io.err(`evidence: limitation: ${l}\n`);
+    if (opts.files) for (const p of opts.list) io.out(`${p}\n`);
     return;
   }
   if (command === 'digest') {
     if (rest.length === 0) usage('digest requires at least one file');
     for (const file of rest) {
       let digest;
-      try { digest = digestFile(file); } catch (error) { process.stderr.write(`pincer-evidence: ${file}: ${error.code === 'ENOENT' ? 'missing' : error.message}\n`); process.exit(1); }
-      process.stdout.write(`${digest}  ${file}\n`);
+      try { digest = digestFile(file); } catch (error) { io.err(`pincer-evidence: ${file}: ${error.code === 'ENOENT' ? 'missing' : error.message}\n`); process.exit(1); }
+      io.out(`${digest}  ${file}\n`);
     }
     return;
   }

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

@@ -0,0 +1,132 @@
+'use strict';
+// PINCER runtime — strict coverage adoption (docs/runtime-contracts.md, "Strict
+// coverage" → "Adoption and rollback"). `coverage adopt --preview` computes the plan
+// and writes nothing; `--apply` is one transaction that backs up the schema 2
+// record, records the adoption agreement (projection 2, snapshot schema 2) and
+// rewrites the record as schema 3 with the retained capability and one `adopt`
+// event. It validates the authored inputs (inventory, map, graph), refuses on a
+// running attempt, a terminal state, an incomplete transaction or changed inputs,
+// grants no authorization, and is idempotent. Migration never adopts.
+const fs = require('node:fs');
+const path = require('node:path');
+const changes = require('./changes.cjs');
+const agreement = require('./agreement.cjs');
+const authorization = require('./authorization.cjs');
+const coverage = require('./coverage.cjs');
+const dispositions = require('./dispositions.cjs');
+const transaction = require('./transaction.cjs');
+const state = require('./state.cjs');
+const { nowIso } = require('./fsutil.cjs');
+
+// Compute the plan. Returns { change, conflicts: [{ code, detail }], already, record,
+// file, agreement: { id, digest }, inventory: { requirements, scenarios, digest },
+// map: { path, digest }, historical, scope: [...], backup }.
+function plan(root, { change } = {}) {
+  const conflicts = [];
+  const conflict = (code, detail) => conflicts.push({ code, detail });
+  const out = { change, conflicts, already: false, record: null, file: null };
+  if (typeof change !== 'string' || !changes.CHANGE_ID.test(change)) { conflict('INPUT_INVALID', `change ID must match [a-z0-9][a-z0-9-]{0,63}: ${change}`); return out; }
+  const loaded = changes.loadRecords(root);
+  if (loaded.mode === 'legacy') { conflict('CHANGE_REQUIRED', `no change record under ${changes.CHANGES_DIR}/ — register the change first (node scripts/pincer-runtime.cjs register --prd .prd/prd-vN.md); migration and registration never adopt strict coverage`); return out; }
+  if (loaded.mode === 'migrated') { conflict('MIGRATION_REQUIRED', `${changes.CHANGES_DIR}/ holds a v0.5.0 binding; migrate to change records first (migrate --preview --prd <prd>); migration never adopts strict coverage`); return out; }
+  for (const p of loaded.problems) conflict(p.code, p.detail);
+  if (conflicts.length) return out;
+  const entry = loaded.records.get(change);
+  if (!entry) { conflict('INPUT_INVALID', `no change record ${changes.recordFile(change)} (retained: ${[...loaded.records.keys()].join(', ') || 'none'})`); return out; }
+  out.record = entry.record; out.file = entry.file;
+  if (changes.isStrict(entry.record)) { out.already = true; return out; }
+  const record = entry.record;
+  if (changes.TERMINAL.includes(record.lifecycle.state)) conflict('LIFECYCLE_BLOCKED', `change ${change} is ${record.lifecycle.state}; its history cannot adopt strict coverage — register a new change`);
+  const running = transaction.runningAttempts(root, change);
+  if (running.length) { const a = running[0]; const hint = a.alive === false ? ' (its owner is no longer running: run recover first)' : a.alive === true ? ` (pid ${a.owner.pid} is still running)` : ` (owned by ${a.owner.host || 'another host'})`; conflict('ATTEMPT_RUNNING', `attempt ${a.id} of change ${change} is running${hint}; adoption waits for it`); }
+  const cov = coverage.load(root, record);
+  if (cov.code && cov.code !== 'COVERAGE_INCOMPLETE') { for (const p of cov.problems) conflict(cov.code, p); return out; }
+  if (cov.code === 'COVERAGE_INCOMPLETE') for (const p of cov.problems) conflict('COVERAGE_INCOMPLETE', p);
+  if (conflicts.length) return out;
+  const computed = agreement.compute(root, { ...record, schema: changes.SCHEMA_STRICT });
+  if (computed.code) { conflict(computed.code, computed.problem); return out; }
+  const gid = `G-${String(record.agreements.length + 1).padStart(2, '0')}`;
+  out.agreement = { id: gid, digest: computed.digest };
+  out.computed = computed;
+  out.inventory = { requirements: Object.keys(cov.inventory.requirements).length, scenarios: Object.keys(cov.inventory.scenarios).length, digest: cov.inventory.digest };
+  out.map = { path: cov.map.file, digest: cov.map.digest };
+  out.historical = state.exists(root) ? state.listAttempts(root).filter(a => a.context && a.context.change === change && a.schema !== 3).length : 0;
+  // Scope dispositions are reported for information: their authorization is recorded after adoption.
+  const verdict = authorization.verdict(root, record);
+  out.scope = Object.values(cov.graph.scope).map(s => ({ id: s.id, disposition: s.disposition, decision: s.decision }));
+  out.scopeProblems = dispositions.scopeProblems(record, cov.graph, verdict).problems.map(p => p.detail);
+  out.backup = `.pincer/backups/<UTC timestamp>/${entry.file}`;
+  return out;
+}
+
+function renderPlan(p) {
+  const lines = [];
+  if (p.conflicts.length) {
+    for (const c of p.conflicts) lines.push(`conflict  ${c.code}: ${c.detail}`);
+    lines.push('adoption refused: resolve the conflicts above; nothing was written');
+    return `${lines.join('\n')}\n`;
+  }
+  if (p.already) {
+    lines.push(`already adopted: change ${p.change} is strict since ${p.record.coverage.adopted} (map ${p.record.coverage.map}, adoption agreement ${p.record.coverage.agreement}); nothing to do`);
+    return `${lines.join('\n')}\n`;
+  }
+  lines.push(`adoption plan for change ${p.change} (${p.file}, ${p.record.lifecycle.state})`);
+  lines.push(`  inventory ${p.inventory.requirements} requirement(s), ${p.inventory.scenarios} scenario(s) · digest ${p.inventory.digest.slice(0, 12)}`);
+  lines.push(`  map       ${p.map.path} · digest ${p.map.digest.slice(0, 12)} · structure complete`);
+  for (const s of p.scope) lines.push(`  scope     ${s.id} ${s.disposition} by decision ${s.decision}${p.scopeProblems.find(d => d.startsWith(`${s.id} (`)) ? ` — not yet authorized: ${p.scopeProblems.find(d => d.startsWith(`${s.id} (`)).replace(/^[^:]*: /, '')}` : ''}`);
+  lines.push(`  agreement ${p.agreement.id} ${p.agreement.digest.slice(0, 12)} (projection 2: PRD revision, inventory, coverage map, tickets, resolved decisions) recorded with its snapshot`);
+  lines.push(`  record    ${p.file} → schema 3 with coverage { map, adopted, agreement ${p.agreement.id} } and one adopt event; ${p.record.agreements.length} earlier agreement(s) kept (inventory history unavailable before ${p.agreement.id})`);
+  lines.push(`  history   ${p.historical} existing attempt(s) of this change become HISTORICAL_EVIDENCE until verified again`);
+  lines.push(`  backup    ${p.backup}`);
+  lines.push('  note      adoption grants no authorization: the agreement above needs `change authorize` (user, or --delegated --basis A-NN) before execution');
+  lines.push(`apply with: node scripts/pincer-runtime.cjs coverage adopt --apply --change ${p.change} --agreement ${p.agreement.digest}`);
+  return `${lines.join('\n')}\n`;
+}
+
+// Apply as one transaction. Returns { plan, applied, record, backup } | { plan, already } |
+// { plan, applied: false } (conflicts) | { plan, error, code }.
+function apply(root, { change, agreement: expected = null, hooks = null } = {}) {
+  const first = plan(root, { change });
+  if (first.conflicts.length) return { plan: first, applied: false };
+  if (first.already) return { plan: first, applied: false, already: true };
+  const stamp = nowIso().replace(/[-:]/g, '');
+  let backupRel = null;
+  try {
+    const out = transaction.run(root, { command: `coverage adopt ${change}`, hooks }, ctx => {
+      const p = plan(root, { change });
+      if (p.conflicts.length) ctx.refuse(p.conflicts[0].code, p.conflicts[0].detail);
+      if (p.already) return { plan: p, already: true };
+      if (expected !== null && expected !== p.agreement.digest) ctx.refuse('AGREEMENT_CHANGED', `--agreement ${expected.slice(0, 12)} is not the agreement adoption would record now (${p.agreement.digest.slice(0, 12)}); the inventory, the map, a ticket or a decision changed since the preview — preview again and adopt the current digest`);
+      ctx.idle(change);
+      const old = p.record;
+      // Backup before anything is staged (the copy is outside the transaction's targets).
+      const src = path.join(root, p.file);
+      const dest = path.join(root, '.pincer', 'backups', stamp, p.file);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(src, dest);
+      backupRel = `.pincer/backups/${stamp}/${p.file}`;
+      const record = {};
+      for (const k of changes.RECORD_KEYS_STRICT) record[k] = k === 'coverage' ? null : JSON.parse(JSON.stringify(old[k]));
+      record.schema = changes.SCHEMA_STRICT; record.runtime = changes.RUNTIME_STRICT;
+      record.agreements = old.agreements.map(g => { const e = {}; for (const k of changes.AGREEMENT_KEYS_STRICT) e[k] = k === 'inventory' || k === 'coverage' ? null : g[k]; return e; });
+      record.coverage = { map: coverage.file(change), adopted: ctx.now, agreement: p.agreement.id };
+      const appended = agreement.appendAgreement(ctx, changes, record, p.file, p.computed, { stage: false, event: false });
+      if (appended.agreement.id !== p.agreement.id) ctx.refuse('STATE_CHANGED', `the record changed since the operation was prepared (agreement ${appended.agreement.id} instead of ${p.agreement.id})`);
+      const sequence = record.sequence + 1;
+      record.events.push({ sequence, kind: 'adopt', from: record.lifecycle.state, to: record.lifecycle.state, at: ctx.now, reason: null, agreement: p.agreement.id, authorization: null, decision: null, replacement: null, note: null });
+      record.sequence = sequence;
+      const invalid = changes.validateRecord(record, p.file);
+      if (invalid) ctx.refuse(invalid.code, invalid.problem);
+      ctx.write(p.file, record);
+      return { plan: p, record };
+    });
+    if (out.result.already) return { plan: out.result.plan, applied: false, already: true };
+    return { plan: out.result.plan, applied: true, record: out.result.record, backup: backupRel };
+  } catch (error) {
+    if (error.refusal) return { plan: first, applied: false, error: error.message, code: error.code };
+    if (error.code === 'STATE_BUSY') return { plan: first, applied: false, error: error.message, code: 'STATE_BUSY' };
+    throw error;
+  }
+}
+
+module.exports = { plan, renderPlan, apply };