pincer-workflow 0.7.0 → 1.0.0

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

@@ -1,242 +0,0 @@
-'use strict';
-// PINCER runtime — the attempt runner (docs/runtime-contracts.md, "Attempts",
-// "Capture and sanitization"). Persists a `running` record before launch (which
-// supersedes prior readiness for the context immediately), snapshots inputs
-// before and after, executes the check through `bash -eo pipefail` in its own
-// process group with bounded sanitized capture, enforces the timeout with
-// escalation, handles signals, and finalizes the record from what actually
-// happened. Nothing here decides readiness; readiness.cjs reads the records.
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const { spawn, execFileSync } = require('node:child_process');
-const parse = require('./parse.cjs');
-const source = require('./source.cjs');
-const state = require('./state.cjs');
-const { sanitizeLine, sanitizeText } = require('./sanitize.cjs');
-const { nowIso } = require('./fsutil.cjs');
-
-const CAPTURE_LIMIT = 1024 * 1024;
-const PARTIAL_LINE_LIMIT = 64 * 1024;
-const GRACE_MS = 5000;
-const DRAIN_MS = 2000;
-const RUNNER_ARGS = ['-eo', 'pipefail', '-c'];
-
-let bashInfo = null;
-function runnerInfo() {
-  if (bashInfo) return bashInfo;
-  let shell = 'bash', version = 'unknown';
-  try { shell = execFileSync('bash', ['-c', 'command -v bash'], { encoding: 'utf8' }).trim() || 'bash'; } catch { /* keep default */ }
-  try { version = execFileSync('bash', ['--version'], { encoding: 'utf8' }).split('\n')[0]; } catch { /* keep default */ }
-  bashInfo = { shell, args: RUNNER_ARGS, version };
-  return bashInfo;
-}
-
-// A bounded, sanitized capture of one stream into a file, echoed to `echo` when given.
-class Capture {
-  constructor(file, echo) {
-    this.file = file; this.echo = echo;
-    this.fd = fs.openSync(file, 'w');
-    this.bytes = 0; this.dropped = 0; this.redactions = 0; this.truncated = false;
-    this.partial = ''; this.state = {}; this.failed = null;
-  }
-  write(chunk) {
-    this.partial += chunk.toString('utf8');
-    let index;
-    while ((index = this.partial.indexOf('\n')) !== -1) {
-      this.emit(this.partial.slice(0, index), true);
-      this.partial = this.partial.slice(index + 1);
-    }
-    if (this.partial.length > PARTIAL_LINE_LIMIT) { this.emit(this.partial, false); this.partial = ''; }
-  }
-  emit(line, newline) {
-    const { text, redactions } = sanitizeLine(line, this.state);
-    this.redactions += redactions;
-    const out = newline ? `${text}\n` : text;
-    if (this.echo) this.echo.write(out);
-    const buffer = Buffer.from(out, 'utf8');
-    if (this.bytes + buffer.length <= CAPTURE_LIMIT) {
-      try { fs.writeSync(this.fd, buffer); this.bytes += buffer.length; } catch (error) { this.failed = this.failed || error.message; }
-    } else {
-      if (!this.truncated) {
-        const room = CAPTURE_LIMIT - this.bytes;
-        if (room > 0) { try { fs.writeSync(this.fd, buffer.subarray(0, room)); this.bytes += room; } catch (error) { this.failed = this.failed || error.message; } }
-        this.truncated = true;
-        this.dropped += buffer.length - Math.max(room, 0);
-      } else this.dropped += buffer.length;
-    }
-  }
-  close() {
-    if (this.partial) { this.emit(this.partial, false); this.partial = ''; }
-    if (this.truncated) {
-      try { fs.writeSync(this.fd, `\n[pincer: truncated, ${this.dropped} more bytes not stored]\n`); } catch (error) { this.failed = this.failed || error.message; }
-    }
-    fs.closeSync(this.fd);
-    return { bytes: this.bytes, truncated: this.truncated, redactions: this.redactions, failed: this.failed };
-  }
-}
-
-// Run one attempt. `context` is the attempt context (kind, change, prd, prd_revision,
-// base, ticket/ticket_digest or candidate/check); `commands` the block lines;
-// `timeoutSeconds` the effective timeout; `echo` when the output should also reach
-// the terminal. `revalidate`, when given, is called under the worktree lock
-// immediately before the `running` record is written and returns the context to
-// record (docs/runtime-contracts.md, "Command gates"): the gates the caller passed
-// before the lock are evaluated again there, so a transition, revision or
-// authorization committed in between is seen and the attempt is refused (a thrown
-// transaction Refusal becomes { code, problem, refused: true }) or recorded against
-// the current agreement. `announce` is called once the record is registered and
-// before the launch, so a refusal prints nothing. Returns { attempt } or { code,
-// problem } for refusals before launch; nothing is written for a refusal.
-async function runAttempt({ root, context, commands, timeoutSeconds, command = 'verify', echo = true, declared = {}, revalidate = null, announce = null, cwd = null }) {
-  const block = commands.length ? `${commands.join('\n')}\n` : '';
-  const checkDigest = parse.sha256(`${block}timeout=${timeoutSeconds}\n`);
-  const display = sanitizeText(block).text.slice(0, 2000);
-  const before = source.snapshot(root);
-  if (before.problems.length) return { code: before.problems[0].code, problem: before.problems.map(p => `${p.code}: ${p.detail}`).join('\n'), problems: before.problems };
-
-  let attempt, logDir, relLogDir;
-  try {
-    state.withLock(root, () => {
-      // Finish any committed transaction before writing: its staged files would
-      // otherwise be renamed over this attempt and its index pointer later.
-      require('./transaction.cjs').recoverPending(root);
-      if (revalidate) context = revalidate();
-      const key = state.contextKey(context);
-      // Changes mode records (schema 2) carry the agreement digest; `mode` only
-      // selects the key format and is not part of the record.
-      const { mode, ...persisted } = context;
-      const schema = persisted.coverage ? 3 : persisted.agreement ? 2 : 1;
-      const read = state.readIndex(root);
-      if (read.error) { const e = new Error(read.error); e.code = 'INVALID'; throw e; }
-      const index = read.index;
-      const sequence = index.sequence + 1;
-      const id = state.attemptId(sequence);
-      source.storeManifest(root, before);
-      relLogDir = `${state.RUNTIME_DIR}/attempts/${id}`;
-      logDir = path.join(root, relLogDir);
-      fs.mkdirSync(logDir, { recursive: true });
-      attempt = {
-        schema, runtime: schema, id, sequence, context: persisted,
-        check: { digest: checkDigest, display, timeout_seconds: timeoutSeconds },
-        outcome: 'running', exit_code: null, signal: null,
-        runner: runnerInfo(), cwd: cwd || '.',
-        environment: { os: `${os.platform()} ${os.release()}`, node: process.version, declared },
-        started: nowIso(), finished: null,
-        source: { before: before.digest, after: null, files: before.files.length, limitations: before.limitations },
-        artifacts: { stdout: { path: `${relLogDir}/stdout.log`, sha256: null, bytes: 0, truncated: false, redactions: 0 }, stderr: { path: `${relLogDir}/stderr.log`, sha256: null, bytes: 0, truncated: false, redactions: 0 } },
-        owner: { pid: process.pid, ppid: process.ppid, host: os.hostname() }, child: null,
-        limitations: [],
-      };
-      state.writeAttempt(root, attempt);
-      index.sequence = sequence;
-      index.current[key] = id;
-      index.running.push(id);
-      state.writeIndex(root, index);
-    }, { command });
-  } catch (error) {
-    if (error && error.refusal) return { code: error.code, problem: error.message, refused: true };
-    if (error.code === 'STATE_BUSY') return { code: 'STATE_BUSY', problem: error.message };
-    if (error.code === 'INVALID') return { code: 'INPUT_INVALID', problem: error.message };
-    return { code: 'ATTEMPT_ERROR', problem: `cannot persist the attempt record: ${error.message}` };
-  }
-
-  if (announce) announce(attempt);
-  // Execute in a fresh process group so timeouts and signals reach every descendant.
-  let child, launchError = null;
-  const stdout = new Capture(path.join(logDir, 'stdout.log'), echo ? process.stdout : null);
-  const stderr = new Capture(path.join(logDir, 'stderr.log'), echo ? process.stderr : null);
-  let timedOut = false, interruptedBy = null, abandoned = false, killTimer = null, graceTimer = null, drainTimer = null, settle = null;
-  const sent = [];
-  // Signal the whole group, whether or not the shell itself has exited: a
-  // background child that inherited the output pipes keeps the run alive and
-  // must be terminated the same way. The bare pid is a fallback only while the
-  // shell is known to be alive (after it is reaped the pid may be reused). The
-  // group id itself can be reused only once every member is gone; the window
-  // between the two attempts is a documented limit, not something detected here.
-  // `sent` records only signals a kill call delivered.
-  const signalGroup = signal => {
-    try { process.kill(-child.pid, signal); sent.push(signal); return; } catch { /* no group left */ }
-    if (child.exitCode === null && child.signalCode === null) { try { process.kill(child.pid, signal); sent.push(signal); } catch { /* gone */ } }
-  };
-  let terminating = false;
-  const terminate = () => {
-    if (!child || !child.pid || terminating) return;
-    terminating = true;
-    signalGroup('SIGTERM');
-    graceTimer = setTimeout(() => {
-      signalGroup('SIGKILL');
-      // Bound the wait for the pipes to close: a descendant that survives
-      // SIGKILL (or was never reachable) must not hold the run open forever.
-      drainTimer = setTimeout(() => {
-        abandoned = true;
-        try { child.stdout.destroy(); child.stderr.destroy(); child.unref(); } catch { /* best effort */ }
-        settle({ code: child.exitCode, signal: child.signalCode });
-      }, DRAIN_MS);
-    }, GRACE_MS);
-  };
-  const onSignal = signal => { interruptedBy = signal; terminate(); };
-  const exit = await new Promise(resolve => {
-    let settled = false;
-    settle = result => { if (!settled) { settled = true; resolve(result); } };
-    try {
-      child = spawn(runnerInfo().shell, [...RUNNER_ARGS, block], { cwd: cwd ? path.join(root, cwd) : root, detached: true, stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
-    } catch (error) { launchError = error.message; return settle({ code: null, signal: null }); }
-    child.on('error', error => { launchError = error.message; });
-    if (child.pid) {
-      attempt.child = { pid: child.pid };
-      try { state.withLock(root, () => state.writeAttempt(root, attempt), { command }); } catch { /* the final write records it */ }
-    }
-    child.stdout.on('data', chunk => stdout.write(chunk));
-    child.stderr.on('data', chunk => stderr.write(chunk));
-    process.on('SIGINT', onSignal); process.on('SIGTERM', onSignal);
-    killTimer = setTimeout(() => { timedOut = true; terminate(); }, timeoutSeconds * 1000);
-    child.on('close', (code, signal) => settle({ code, signal }));
-  });
-  clearTimeout(killTimer); clearTimeout(graceTimer); clearTimeout(drainTimer);
-  process.off('SIGINT', onSignal); process.off('SIGTERM', onSignal);
-  const outInfo = stdout.close(), errInfo = stderr.close();
-  const termination = `${sent.length ? `the child process group was sent ${sent.join(' then ')}` : 'no reachable process remained in the child\'s group (the shell had exited and its descendants left the group)'}${abandoned ? `; output capture was abandoned ${DRAIN_MS / 1000} s after the SIGKILL point and a descendant may still be running` : ''}`;
-
-  const after = source.snapshot(root);
-  const changed = after.digest && before.digest !== after.digest ? source.diffManifests(before, after) : [];
-  attempt.finished = nowIso();
-  attempt.exit_code = exit.code;
-  attempt.signal = exit.signal;
-  attempt.source.after = after.digest;
-  for (const [name, info] of [['stdout', outInfo], ['stderr', errInfo]]) {
-    const file = path.join(logDir, `${name}.log`);
-    let sha = null;
-    try { sha = parse.sha256(fs.readFileSync(file)); } catch { sha = null; }
-    attempt.artifacts[name] = { ...attempt.artifacts[name], sha256: sha, bytes: info.bytes, truncated: info.truncated, redactions: info.redactions };
-  }
-  const captureFailure = outInfo.failed || errInfo.failed;
-  if (launchError) { attempt.outcome = 'error'; attempt.error = `cannot launch the check: ${launchError}`; }
-  else if (interruptedBy) { attempt.outcome = 'interrupted'; attempt.limitations.push(`interrupted by ${interruptedBy}; ${termination}`); }
-  else if (timedOut) { attempt.outcome = 'timed_out'; attempt.limitations.push(`terminated after ${timeoutSeconds} s; ${termination}`); }
-  else if (captureFailure) { attempt.outcome = 'error'; attempt.error = `capture failed: ${captureFailure}`; }
-  else if (after.problems.length) { attempt.outcome = 'error'; attempt.error = `source view invalid after the run: ${after.problems[0].code} ${after.problems[0].detail}`; }
-  else if (exit.code === 0 && changed.length) { attempt.outcome = 'error'; attempt.error = `SOURCE_CHANGED: the check mutated source: ${changed.slice(0, 5).join(', ')}${changed.length > 5 ? ` (+${changed.length - 5})` : ''}`; }
-  else if (exit.code === 0) attempt.outcome = 'passed';
-  else attempt.outcome = 'failed';
-  if (changed.length && attempt.outcome !== 'error') attempt.limitations.push(`source changed during the run: ${changed.slice(0, 5).join(', ')}`);
-  if (after.digest) { try { source.storeManifest(root, after); } catch { /* best effort; the digest is recorded */ } }
-
-  try {
-    state.withLock(root, () => {
-      const read = state.readIndex(root);
-      if (read.error) { const e = new Error(read.error); e.code = 'INVALID'; throw e; }
-      const index = read.index;
-      state.writeAttempt(root, attempt);
-      index.running = index.running.filter(id => id !== attempt.id);
-      state.writeIndex(root, index);
-    }, { command });
-  } catch (error) {
-    return { code: 'ATTEMPT_ERROR', problem: `attempt ${attempt.id} finished ${attempt.outcome} but the record could not be finalized: ${error.message}`, attempt };
-  }
-  return { attempt, changed };
-}
-
-const exitFor = attempt => ({ passed: 0, failed: 1, timed_out: 124, interrupted: 130, error: 4 })[attempt.outcome] ?? 4;
-
-module.exports = { runAttempt, exitFor, CAPTURE_LIMIT, GRACE_MS, DRAIN_MS, runnerInfo };

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

@@ -1,63 +0,0 @@
-'use strict';
-// PINCER runtime — output sanitizer (docs/runtime-contracts.md, "Capture and
-// sanitization"). A safety net applied to every captured line and to command
-// display text before anything is persisted: documented secret patterns are
-// replaced by [redacted] and counted. It is not a guarantee; checks must avoid
-// printing secrets, and no raw log is ever exported.
-const PATTERNS = [
-  // Bearer tokens first, so an `Authorization: Bearer <token>` header keeps the
-  // token, not the word Bearer, as the redacted value.
-  { re: /((?:bearer|basic|token|digest)\s+)[A-Za-z0-9\-._~+/=]+/gi, replace: '$1[redacted]' },
-  // key/secret/password/token/authorization assignments and JSON fields; a
-  // quoted value is redacted up to its closing quote, an unquoted one to the
-  // next whitespace or separator. Bounded quantifiers: an unbounded prefix would
-  // backtrack quadratically on long lines.
-  { re: /((?:^|[^A-Za-z0-9_.-])[A-Za-z0-9_.-]{0,64}?(?:key|secret|password|passwd|token|authorization)[A-Za-z0-9_.-]{0,64}["']?[ \t]{0,8}[:=][ \t]{0,8})(?:"([^"\n]{0,512})"|'([^'\n]{0,512})'|([^\s"',;]+))/gi, replace: (m, head, dq, sq, bare) => `${head}${dq !== undefined ? '"[redacted]"' : sq !== undefined ? "'[redacted]'" : '[redacted]'}` },
-  { re: /AKIA[0-9A-Z]{16}/g, replace: '[redacted]' },
-  { re: /gh[pousr]_[A-Za-z0-9]{20,}/g, replace: '[redacted]' },
-];
-const PEM_BEGIN = /-----BEGIN [A-Z ]*PRIVATE KEY-----/;
-const PEM_END = /-----END [A-Z ]*PRIVATE KEY-----/;
-
-// Stateful: PEM private key blocks span lines. `state` is a plain object the
-// caller keeps per stream.
-function sanitizeLine(line, state = {}) {
-  let redactions = 0;
-  if (state.inPem) {
-    if (PEM_END.test(line)) state.inPem = false;
-    return { text: '[redacted]', redactions: 1 };
-  }
-  if (PEM_BEGIN.test(line)) {
-    state.inPem = !PEM_END.test(line);
-    return { text: '[redacted]', redactions: 1 };
-  }
-  let text = line;
-  for (const { re, replace } of PATTERNS) {
-    text = text.replace(re, (...args) => {
-      redactions++;
-      return typeof replace === 'function' ? replace(...args) : replace.replace(/\$(\d)/g, (_, n) => args[Number(n)]);
-    });
-  }
-  return { text, redactions };
-}
-
-function sanitizeText(text) {
-  const state = {};
-  let redactions = 0;
-  const lines = String(text).split('\n').map(line => { const r = sanitizeLine(line, state); redactions += r.redactions; return r.text; });
-  return { text: lines.join('\n'), redactions };
-}
-
-// A Verification block must not carry an inline secret literal: the block is
-// recorded as display text and would persist the value. `$references` and
-// empty values are fine.
-// An assignment anywhere in the line (after a word boundary, so `env TOKEN=x cmd`
-// and `true; TOKEN=x cmd` count); `$VAR`, `"$VAR"`, `$(…)` and backtick
-// references are allowed, literals are not.
-const INLINE_SECRET = /(?:^|[\s;&|(])(?:export\s+)?[A-Za-z0-9_]*(?:KEY|SECRET|PASSWORD|PASSWD|TOKEN)[A-Za-z0-9_]*=(?!["']?\$|["']?`|\s|$)\S/i;
-function inlineSecretLine(commands) {
-  const index = commands.findIndex(line => INLINE_SECRET.test(line));
-  return index === -1 ? null : index + 1;
-}
-
-module.exports = { sanitizeLine, sanitizeText, inlineSecretLine, PATTERNS };

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

@@ -1,254 +0,0 @@
-'use strict';
-// PINCER runtime — the coverage draft (docs/runtime-contracts.md, "Coverage draft").
-// `coverage scaffold --change <id>` projects the validated PRD inventory, the change's
-// tickets and any authored map into one reviewable draft. It exists because authoring
-// `.prd/coverage/<id>.json` means transcribing every live scenario, every ticket role
-// and every check declaration out of documents the runtime has already parsed; that
-// transcription is the measured cost this removes (docs/prd-v7-pilots.md).
-//
-// What it must never do is decide. The draft carries no semantic judgment: an
-// unresolved scenario stays unresolved, a check command is never invented, a ticket
-// role is never guessed, and a scope disposition is never chosen. Candidate tickets
-// and their existing verification text are listed as *material to read*, with their
-// file provenance, never promoted into a link or a declaration.
-//
-// The envelope is `draft: 1` with no `schema` key, so `coverage.validateMap` refuses
-// it: a draft written to disk is not a coverage map and cannot become one by being
-// saved. The real map is authored by hand, validated by `coverage`, adopted by
-// `coverage adopt` and authorized by `change authorize`, exactly as before.
-//
-// Pure and read-only: nothing here writes a file, launches a check, changes a
-// selection or records an approval. The draft body carries no timestamp, so two calls
-// on identical authored inputs produce byte-identical output.
-const fs = require('node:fs');
-const path = require('node:path');
-const parse = require('./parse.cjs');
-const requirements = require('./requirements.cjs');
-const coverage = require('./coverage.cjs');
-
-const DRAFT = 1;
-const KIND = 'coverage-draft';
-const RUNTIME = 'node scripts/pincer-runtime.cjs';
-// Unresolved codes, in report order. These describe the draft, not the runtime state:
-// they say what a human still has to author, never what a gate will refuse.
-const UNRESOLVED_ORDER = ['SCENARIO_UNLINKED', 'CHECK_UNDECLARED', 'TICKET_UNCLASSIFIED', 'SCENARIO_STALE', 'TICKET_FOREIGN'];
-
-const AUTHORED = 'authored';
-const UNRESOLVED = 'unresolved';
-
-// The first line under a ticket heading, used as the objective a reviewer reads.
-function firstLine(text, heading) {
-  const rows = parse.lines(text);
-  const i = rows.findIndex(l => l.trim() === heading);
-  if (i === -1) return null;
-  const next = rows.slice(i + 1).find(l => l.trim() !== '');
-  return next ? next.trim() : null;
-}
-// The IDs a ticket's own Context section claims ("- Implements: R-04." and
-// "- Scenarios: S-10, S-11."). Classified against the live inventory rather than by
-// prefix, because tickets name other tickets on the same lines — T-03 of the strict
-// fixture says "Implements: none (enables T-01, T-02)", and reading that as two
-// scenario claims would be the draft inventing a link out of prose. An ID the
-// inventory does not define is not reported at all.
-const CLAIM_LINE = /^[ \t]*[-+*][ \t]+(?:Implements|Scenarios|Requirements):/;
-function claimsOf(text, inventory) {
-  const ids = new Set();
-  for (const row of parse.lines(text)) {
-    if (!CLAIM_LINE.test(row)) continue;
-    for (const id of row.match(new RegExp(requirements.ID, 'g')) || []) ids.add(id);
-  }
-  const claimed = [...ids];
-  return {
-    requirements: requirements.sortIds(claimed.filter(id => inventory.requirements[id])),
-    scenarios: requirements.sortIds(claimed.filter(id => inventory.scenarios[id])),
-  };
-}
-// The ticket's own Verification fence, verbatim, as provenance for a reviewer. It is
-// quoted, never turned into a check declaration: whether it proves the scenario is a
-// judgment the draft does not make.
-function verificationOf(text) {
-  const commands = parse.verificationCommands(text);
-  return commands && commands.length ? commands.join('\n') : null;
-}
-
-// build(root, record) → { ok, code, problems, draft }
-// `code` is set only when the inputs cannot be read; a missing map is the normal case
-// this command exists for, not an error.
-function build(root, record) {
-  const fail = (code, problems) => ({ ok: false, code, problems, draft: null });
-  const inv = requirements.readInventory(root, record.prd);
-  if (!inv.ok) return fail(inv.code, inv.problems);
-  const inventory = inv.inventory;
-
-  // An absent map is expected; an unreadable one is not — silently dropping authored
-  // content would be the one way this command could destroy work.
-  const rel = coverage.file(record.change);
-  const real = coverage.realFile(root, rel);
-  let authored = null;
-  if (!real) {
-    const m = coverage.readMap(root, record);
-    if (!m.ok) return fail(m.code, m.problems);
-    authored = m;
-  } else if (!real.endsWith(': missing')) {
-    return fail('COVERAGE_INVALID', [`${rel}: ${real.slice(rel.length + 2)}`]);
-  }
-
-  const t = coverage.ticketsOf(root, record);
-  if (!t.ok) return fail(t.code, t.problems);
-
-  const map = authored ? authored.map : null;
-  const unresolved = [];
-  const note = (code, id, detail) => unresolved.push({ code, id, detail });
-
-  // --- scenarios: every live scenario exactly once, authored rows preserved ----------
-  const scenarios = {};
-  const scope = {};
-  for (const id of requirements.sortIds(Object.keys(inventory.scenarios))) {
-    const live = inventory.scenarios[id];
-    const authoredScope = map && map.scope ? map.scope[id] : null;
-    if (authoredScope) {
-      scope[id] = { ...authoredScope, state: AUTHORED };
-      continue;
-    }
-    const row = map && map.scenarios ? map.scenarios[id] : null;
-    const tickets = row ? [...row.tickets] : [];
-    const checks = row ? [...row.checks] : [];
-    const resolved = Boolean(row) && tickets.length > 0 && checks.length > 0;
-    scenarios[id] = { requirement: live.requirement, state: resolved ? AUTHORED : UNRESOLVED, tickets, checks };
-    if (!row) note('SCENARIO_UNLINKED', id, `${id} (${live.requirement}) has no row in scenarios or scope`);
-    else if (!tickets.length) note('SCENARIO_UNLINKED', id, `${id} is linked to no ticket`);
-    else if (!checks.length) note('CHECK_UNDECLARED', id, `${id} is linked to no check`);
-  }
-  // A map row naming a scenario the inventory no longer defines is authored content:
-  // it is preserved and flagged, never deleted, because removing an obligation is a
-  // decision with its own disposition and authorization.
-  if (map) {
-    for (const id of requirements.sortIds(Object.keys(map.scenarios))) {
-      if (scenarios[id] || scope[id]) continue;
-      scenarios[id] = { requirement: null, state: UNRESOLVED, tickets: [...map.scenarios[id].tickets], checks: [...map.scenarios[id].checks] };
-      note('SCENARIO_STALE', id, `${id} has a row but is not a scenario of ${record.prd}`);
-    }
-    for (const id of requirements.sortIds(Object.keys(map.scope))) {
-      if (scope[id] || inventory.scenarios[id]) continue;
-      scope[id] = { ...map.scope[id], state: UNRESOLVED };
-      note('SCENARIO_STALE', id, `${id} has a scope row but is not a scenario of ${record.prd}`);
-    }
-  }
-
-  // --- tickets: authored roles preserved; unclassified tickets named, not classified --
-  const tickets = {};
-  for (const id of requirements.sortIds(Object.keys(t.tickets))) {
-    const row = map && map.tickets ? map.tickets[id] : null;
-    if (row) tickets[id] = { role: row.role, rationale: row.rationale, state: AUTHORED };
-    else {
-      tickets[id] = { role: null, rationale: null, state: UNRESOLVED };
-      note('TICKET_UNCLASSIFIED', id, `${id} has no role; classify it as implements or enables (an enabling ticket needs a rationale)`);
-    }
-  }
-  if (map) {
-    for (const id of requirements.sortIds(Object.keys(map.tickets))) {
-      if (tickets[id]) continue;
-      tickets[id] = { role: map.tickets[id].role, rationale: map.tickets[id].rationale, state: UNRESOLVED };
-      note(t.others[id] ? 'TICKET_FOREIGN' : 'SCENARIO_STALE', id,
-        t.others[id] ? `${id} is a ticket of ${t.others[id]}, not of ${record.prd}` : `${id} has a row but no ticket file is associated with ${record.prd}`);
-    }
-  }
-
-  // --- checks: authored declarations preserved verbatim; none invented ---------------
-  const checks = {};
-  if (map) for (const id of Object.keys(map.checks).sort()) checks[id] = { ...map.checks[id], state: AUTHORED };
-  // Every check a scenario links to must be declared; an undeclared one is named.
-  for (const [sid, row] of Object.entries(scenarios)) {
-    for (const c of row.checks) {
-      if (checks[c]) continue;
-      note('CHECK_UNDECLARED', c, `${c} is linked from ${sid} but has no declaration`);
-    }
-  }
-
-  // --- candidates: material to read, with provenance. Never a link. -----------------
-  const candidates = { tickets: {} };
-  for (const id of requirements.sortIds(Object.keys(t.tickets))) {
-    const entry = t.tickets[id];
-    const claims = claimsOf(entry.text, inventory);
-    candidates.tickets[id] = {
-      file: entry.file,
-      objective: firstLine(entry.text, '## Objective'),
-      implements: claims.requirements,
-      scenarios: claims.scenarios,
-      verification: verificationOf(entry.text),
-    };
-  }
-
-  unresolved.sort((a, b) => (UNRESOLVED_ORDER.indexOf(a.code) - UNRESOLVED_ORDER.indexOf(b.code)) || requirements.compareIds(a.id, b.id));
-  const draft = {
-    draft: DRAFT,
-    kind: KIND,
-    change: record.change,
-    prd: record.prd,
-    inventory: { digest: inventory.digest, requirements: Object.keys(inventory.requirements).length, scenarios: Object.keys(inventory.scenarios).length },
-    authored: { map: authored ? authored.file : null, digest: authored ? authored.digest : null },
-    scenarios, scope, tickets, checks, candidates, unresolved,
-    next: nextAction(record, unresolved, authored),
-  };
-  return { ok: true, code: null, problems: [], draft };
-}
-
-// What the reader does next. A complete draft does not adopt anything: it says the map
-// is ready to be reviewed and validated, which is a different claim from "correct".
-function nextAction(record, unresolved, authored) {
-  if (unresolved.length) {
-    const first = unresolved[0];
-    return { action: `author the unresolved entries (${unresolved.length}), starting with ${first.id}`, command: `edit ${coverage.file(record.change)} — ${first.detail}` };
-  }
-  if (!authored) return { action: 'author the map from this draft, then validate it', command: `edit ${coverage.file(record.change)}, then ${RUNTIME} coverage --change ${record.change}` };
-  return { action: 'review the authored map, then preview adoption', command: `${RUNTIME} coverage adopt --preview --change ${record.change}` };
-}
-
-function render(d) {
-  const lines = [];
-  const count = o => Object.keys(o).length;
-  lines.push(`PINCER coverage draft · change ${d.change} · ${d.prd}`);
-  lines.push(`Inventory  ${d.inventory.requirements} requirement(s), ${d.inventory.scenarios} scenario(s) · digest ${d.inventory.digest.slice(0, 12)}`);
-  lines.push(`Authored   ${d.authored.map ? `${d.authored.map} · digest ${d.authored.digest.slice(0, 12)}` : 'no map yet'}`);
-  lines.push('');
-  lines.push(`Scenarios  ${count(d.scenarios)} linked row(s), ${count(d.scope)} scope row(s)`);
-  for (const [id, s] of Object.entries(d.scenarios)) {
-    const marker = s.state === AUTHORED ? ' ' : '?';
-    lines.push(`  ${marker} ${id}  ${s.requirement || '(not in the inventory)'}  tickets ${s.tickets.length ? s.tickets.join(', ') : '—'}  checks ${s.checks.length ? s.checks.join(', ') : '—'}`);
-  }
-  for (const [id, s] of Object.entries(d.scope)) {
-    lines.push(`  ${s.state === AUTHORED ? ' ' : '?'} ${id}  scope: ${s.disposition}${s.decision ? ` (${s.decision})` : ''}${s.note ? ` — ${s.note}` : ''}`);
-  }
-  lines.push('');
-  lines.push(`Tickets    ${count(d.tickets)}`);
-  for (const [id, t] of Object.entries(d.tickets)) {
-    const c = d.candidates.tickets[id];
-    lines.push(`  ${t.state === AUTHORED ? ' ' : '?'} ${id}  role ${t.role || '—'}${t.rationale ? ` (${t.rationale})` : ''}${c && c.objective ? `  · ${c.objective}` : ''}`);
-    if (t.state !== AUTHORED && c) {
-      const claimed = [...c.implements, ...c.scenarios];
-      if (claimed.length) lines.push(`      the ticket says it implements ${claimed.join(', ')} (${c.file}) — a statement to check, not a link`);
-      if (c.verification) lines.push(`      its Verification block runs: ${c.verification.split('\n')[0]}${c.verification.includes('\n') ? ' …' : ''}`);
-    }
-  }
-  lines.push('');
-  lines.push(`Checks     ${count(d.checks)}`);
-  for (const [id, c] of Object.entries(d.checks)) {
-    lines.push(`  ${c.state === AUTHORED ? ' ' : '?'} ${id}  ${c.kind}${c.required ? ', required' : ''}  ${c.kind === 'command' ? c.command : c.obligation}`);
-  }
-  if (!count(d.checks)) lines.push('    none declared — a check is authored, never derived from a ticket');
-  lines.push('');
-  if (d.unresolved.length) {
-    lines.push(`Unresolved ${d.unresolved.length}`);
-    for (const u of d.unresolved) lines.push(`  ${u.code}  ${u.detail}`);
-  } else {
-    lines.push('Unresolved none — every scenario has a row, every ticket a role, every linked check a declaration');
-  }
-  lines.push('');
-  lines.push('This is a draft, not a coverage map: it carries no schema, and `coverage`,');
-  lines.push('`coverage adopt` and the agreement digest do not accept it. Author');
-  lines.push(`${coverage.file(d.change)} yourself, review the links, then validate and adopt it.`);
-  lines.push(`Next       ${d.next.action}: ${d.next.command}`);
-  return `${lines.join('\n')}\n`;
-}
-
-module.exports = { DRAFT, KIND, UNRESOLVED_ORDER, AUTHORED, UNRESOLVED, build, render, nextAction };