pincer-workflow 0.4.1 → 0.6.0

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

@@ -0,0 +1,204 @@
+'use strict';
+// PINCER runtime — migration (docs/runtime-contracts.md, "Migration and
+// rollback"). Preview is read-only; apply is one transaction that backs up every
+// authored file it changes, strips legacy receipts into the change record's
+// `legacy.receipts` (history, never runtime evidence), converts a v0.5.0 schema 1
+// binding into a schema 2 record (same id, base and registration; the free-text
+// authorization retained as unvalidated history), rewrites the local candidate
+// pointers that no longer resolve, ignores .pincer/, and selects the change in
+// this worktree. The migrated change is planned with no authorization; existing
+// attempts and evaluations stay history until verified again. Conflicts fail
+// closed before the first write; repeated apply is a no-op.
+const fs = require('node:fs');
+const path = require('node:path');
+const parse = require('./parse.cjs');
+const identity = require('./identity.cjs');
+const changes = require('./changes.cjs');
+const statusModule = require('./status.cjs');
+const state = require('./state.cjs');
+const transaction = require('./transaction.cjs');
+const { fmUnset } = require('./lifecycle.cjs');
+const { nowIso, readJson } = require('./fsutil.cjs');
+
+const IGNORE_LINE = '.pincer/';
+const gitignoreHas = root => changes.gitignoreHas(fs.existsSync(path.join(root, '.gitignore')) ? fs.readFileSync(path.join(root, '.gitignore'), 'utf8') : '');
+const OLD_CANDIDATE_KEY = /^candidate:([0-9a-f]{40}):(C-[0-9]{2,6})$/;
+
+// Compute the plan. Returns { prd, change, source: 'legacy' | 'binding' | 'record',
+// conflicts, binding: { file, existing, action }, tickets, gitignore, index,
+// selection, alreadyMigrated, partial, authorization }.
+function plan(root, { prd, change, authorization = null } = {}) {
+  const conflicts = [];
+  const conflict = (code, detail) => conflicts.push({ code, detail });
+  const prdResult = parse.validatePrd(root, prd);
+  if (!prdResult.ok) { conflict('INPUT_INVALID', `${prdResult.file || prd}: ${prdResult.problems[0]}`); return { prd, conflicts }; }
+  let id = change || `prd-v${prd.match(parse.PRD_REF)[1]}`;
+  if (!changes.CHANGE_ID.test(id)) conflict('INPUT_INVALID', `change ID must match [a-z0-9][a-z0-9-]{0,63}: ${id}`);
+  if (!identity.head(root)) conflict('UNSUPPORTED_INPUT', 'migration needs a git repository with at least one commit');
+  const scan = changes.scan(root);
+  let source = 'legacy', binding = null, existing = null, bindingFile = null;
+  if (scan.mode === 'invalid') for (const p of scan.problems) conflict(p.code, p.detail);
+  else if (scan.mode === 'migrated') {
+    const bindings = scan.entries.filter(e => e.schema === 1);
+    const bad = scan.entries.filter(e => e.code);
+    if (bindings.length > 1 || bad.length) conflict('AMBIGUOUS', `several files under .prd/changes/ (${scan.entries.map(e => path.basename(e.file)).join(', ')}); keep exactly one v0.5.0 binding`);
+    else {
+      const b = bindings[0].doc;
+      const invalid = identity.validateBinding(b);
+      if (invalid) conflict(/schema|runtime contract/.test(invalid) ? 'UNSUPPORTED_SCHEMA' : 'INPUT_INVALID', `${bindings[0].file}: ${invalid}`);
+      else if (path.basename(bindings[0].file, '.json') !== b.change) conflict('INPUT_INVALID', `${bindings[0].file}: filename does not match change "${b.change}"`);
+      else if (b.prd !== prd) conflict('AMBIGUOUS', `${bindings[0].file} binds ${b.prd}, not ${prd}; a v0.5.0 binding is converted first — migrate it with: node scripts/pincer-runtime.cjs migrate --preview --prd ${b.prd}, then register ${prd}`);
+      else if (change && change !== b.change) conflict('AMBIGUOUS', `${bindings[0].file} already binds ${prd} as change "${b.change}"; pass --change ${b.change}`);
+      else { id = b.change; source = 'binding'; binding = b; bindingFile = bindings[0].file; }
+    }
+  } else if (scan.mode === 'changes') {
+    const loaded = changes.loadRecords(root);
+    for (const p of loaded.problems) conflict(p.code, p.detail);
+    if (!loaded.problems.length) {
+      const owner = changes.ownerOf(loaded, prd);
+      if (owner && owner[0] !== id) conflict('INPUT_INVALID', `${prd} is owned by change "${owner[0]}" (${owner[1].file}); pass --change ${owner[0]}`);
+      else {
+        const rec = loaded.records.get(id);
+        if (rec && rec.record.prd !== prd) conflict('INPUT_INVALID', `${rec.file} names change "${id}" for ${rec.record.prd}; choose another --change ID for ${prd}`);
+        else if (rec) { existing = rec; source = 'record'; }
+      }
+    }
+  }
+  const set = parse.validateTicketSet(root);
+  if (!set.ok) conflict('INPUT_INVALID', `pincer-ticket: ${set.file ? `${set.file}: ` : ''}${set.problems[0]}`);
+  const tickets = [];
+  if (set.ok) {
+    for (const file of set.files) {
+      const text = fs.readFileSync(path.join(root, file), 'utf8');
+      const fields = parse.validateTicket(file, text).fields;
+      const assoc = statusModule.ticketPrd(root, file, fields);
+      if (assoc.problem) { conflict('INPUT_INVALID', `pincer: ${assoc.problem}`); continue; }
+      if (assoc.prd !== prd) continue;
+      if (fields.verified || fields.last_check) tickets.push({ file, id: fields.ticket, verified: fields.verified || null, last_check: fields.last_check || null, text });
+    }
+  }
+  const gitignore = !gitignoreHas(root);
+  // Local pointers of a converted binding: candidate keys gain the change segment.
+  let index = null;
+  if (source === 'binding' && state.exists(root)) {
+    const read = state.readIndex(root);
+    if (read.error) conflict('INPUT_INVALID', read.error);
+    else {
+      const stale = Object.keys(read.index.current).filter(k => OLD_CANDIDATE_KEY.test(k));
+      if (stale.length) index = { stale, doc: read.index };
+    }
+  }
+  const sel = changes.readSelection(root);
+  const selection = sel.code || sel.change !== id ? id : null;
+  const alreadyMigrated = source === 'record' && tickets.length === 0 && !gitignore;
+  const partial = source === 'record' && tickets.length > 0;
+  return {
+    prd, change: id, source, authorization, conflicts, bindingFile,
+    binding: { file: changes.recordFile(id), existing: existing ? existing.record : binding, bindingFile, action: source === 'binding' ? 'convert' : source === 'record' ? (partial ? 'complete' : 'keep') : 'register' },
+    tickets, gitignore, index, selection, alreadyMigrated, partial,
+    historical: { attempts: state.exists(root) ? state.listAttempts(root).filter(a => a.schema === 1).length : 0 },
+  };
+}
+
+function renderPlan(p) {
+  const lines = [];
+  if (p.conflicts.length) {
+    for (const c of p.conflicts) lines.push(`conflict  ${c.code}: ${c.detail}`);
+    lines.push('migration refused: resolve the conflicts above; nothing was written');
+    return lines.join('\n') + '\n';
+  }
+  lines.push(`migration plan for ${p.prd} (change ${p.change})`);
+  if (p.alreadyMigrated) { lines.push('  already migrated: change record present, no legacy receipts remain, .pincer/ ignored'); if (p.selection) lines.push(`  selection .pincer/runtime/selection.json → ${p.change} is not set in this worktree; select with: node scripts/pincer-runtime.cjs change select ${p.change}`); return lines.join('\n') + '\n'; }
+  if (p.source === 'binding') {
+    const b = p.binding.existing;
+    lines.push(`  binding   ${p.bindingFile || p.binding.file} (v0.5.0, schema 1) → change record (schema 2) at the same path: change ${b.change}, base ${b.base.slice(0, 7)} and registration ${b.registered} kept; ${Object.keys(b.legacy_receipts).length} receipt(s) already imported carried over`);
+    if (b.authorization) lines.push(`  note      the binding's authorization text "${b.authorization}" is retained as legacy.authorization_text (unvalidated history); it never authorizes execution`);
+  } else if (p.source === 'record') lines.push(`  record    ${p.binding.file} (present; ${p.tickets.length} receipt(s) imported into legacy.receipts by a migrate event)`);
+  else lines.push(`  record    ${p.binding.file} (new schema 2 record; base = HEAD; planned)`);
+  if (p.partial) lines.push('  note      an earlier migration was partially applied (record present, receipts remain); apply completes it');
+  for (const t of p.tickets) lines.push(`  ticket    ${t.file}: remove ${[t.verified ? 'verified' : null, t.last_check ? 'last_check' : null].filter(Boolean).join(', ')} → legacy.receipts[${t.id}] (history, not runtime evidence)`);
+  if (!p.tickets.length) lines.push('  tickets   no legacy receipts to import');
+  lines.push(p.gitignore ? `  gitignore add \`${IGNORE_LINE}\`` : '  gitignore already ignores .pincer/');
+  if (p.index) lines.push(`  index     .pincer/runtime/index.json: ${p.index.stale.length} candidate pointer(s) dropped — a v0.5.0 attempt record cannot satisfy the change-scoped key, so its check is run again (attempt records untouched, kept as history)`);
+  lines.push(`  history   ${p.historical.attempts} existing attempt(s) and any saved evaluation stay history (HISTORICAL_EVIDENCE) until verified again; the change is planned with no authorization`);
+  if (p.selection) lines.push(`  selection .pincer/runtime/selection.json → ${p.change} (this worktree only; a fresh clone selects explicitly)`);
+  lines.push('  backups   .pincer/backups/<timestamp>/ for every changed authored file (tickets, .gitignore, the binding, the local index)');
+  if (p.authorization) lines.push(`  note      --authorization "${p.authorization}" is retained as legacy.authorization_text (unvalidated history); record the user's actual instruction afterwards with: node scripts/pincer-runtime.cjs change authorize ${p.change} --agreement <digest> --reference <text> --excerpt <text>`);
+  else if (!(p.source === 'binding' && p.binding.existing.authorization)) lines.push(`  note      no --authorization given; migration grants no authorization — record the user's instruction afterwards with: node scripts/pincer-runtime.cjs change authorize ${p.change} …`);
+  lines.push(`apply with: node scripts/pincer-runtime.cjs migrate --apply --prd ${p.prd}${p.change !== `prd-v${p.prd.match(parse.PRD_REF)[1]}` ? ` --change ${p.change}` : ''}`);
+  return lines.join('\n') + '\n';
+}
+
+// Apply the plan as one transaction: backups first (copies of the originals),
+// then tickets, .gitignore, the record, the index and the selection together.
+function apply(root, options) {
+  const first = plan(root, options);
+  if (first.conflicts.length) return { plan: first, applied: false };
+  if (first.alreadyMigrated) return { plan: first, applied: false, already: true };
+  const stamp = nowIso().replace(/[-:]/g, '');
+  const backupDir = path.join(root, '.pincer', 'backups', stamp);
+  const backups = [];
+  const backup = rel => {
+    const src = path.join(root, rel);
+    if (!fs.existsSync(src)) return;
+    const dest = path.join(backupDir, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+    backups.push(`.pincer/backups/${stamp}/${rel}`);
+  };
+  try {
+    const out = transaction.run(root, { command: `migrate --apply ${options.prd}`, hooks: options.hooks || null }, ctx => {
+      const p = plan(root, options);
+      if (p.conflicts.length) ctx.refuse(p.conflicts[0].code, p.conflicts[0].detail);
+      if (p.alreadyMigrated) return { plan: p, already: true };
+      for (const t of p.tickets) backup(t.file);
+      if (p.gitignore) backup('.gitignore');
+      if (p.source === 'binding') backup(p.bindingFile);
+      if (p.index) backup(`${state.RUNTIME_DIR}/index.json`);
+      const receipts = {};
+      for (const t of p.tickets) {
+        receipts[t.id] = { verified: t.verified, last_check: t.last_check };
+        ctx.write(t.file, fmUnset(fmUnset(t.text, 'verified'), 'last_check'));
+      }
+      if (p.gitignore) {
+        const existing = ctx.text('.gitignore') || '';
+        const lead = existing && !existing.endsWith('\n') ? '\n' : '';
+        ctx.write('.gitignore', `${existing}${lead}${existing ? '\n' : ''}# pincer runtime state (added by migrate)\n${IGNORE_LINE}\n`);
+      }
+      let record;
+      if (p.source === 'record') {
+        record = JSON.parse(JSON.stringify(p.binding.existing));
+        record.legacy.receipts = { ...record.legacy.receipts, ...receipts };
+        if (options.authorization) record.legacy.authorization_text = options.authorization;
+        const sequence = record.sequence + 1;
+        record.events.push({ sequence, kind: 'migrate', from: record.lifecycle.state, to: record.lifecycle.state, at: ctx.now, reason: null, agreement: null, authorization: null, decision: null, replacement: null, note: `${Object.keys(receipts).length} legacy receipt(s) imported` });
+        record.sequence = sequence;
+      } else if (p.source === 'binding') {
+        const b = p.binding.existing;
+        record = changes.newRecord({ change: b.change, prd: b.prd, base: b.base, now: ctx.now, kind: 'migrate', legacy: { receipts: { ...b.legacy_receipts, ...receipts }, authorization_text: options.authorization || b.authorization || null, migrated_from: 'binding', migrated: ctx.now } });
+        record.registered = b.registered;
+        record.events[0].note = `converted from the v0.5.0 binding (registered ${b.registered})`;
+      } else {
+        record = changes.newRecord({ change: p.change, prd: p.prd, base: identity.head(root), now: ctx.now, kind: 'migrate', legacy: { receipts, authorization_text: options.authorization || null, migrated_from: 'legacy', migrated: ctx.now } });
+      }
+      const invalid = changes.validateRecord(record, p.binding.file);
+      if (invalid) ctx.refuse(invalid.code, invalid.problem);
+      ctx.write(p.binding.file, record);
+      if (p.index) {
+        const doc = p.index.doc;
+        for (const key of p.index.stale) delete doc.current[key];
+        ctx.write(`${state.RUNTIME_DIR}/index.json`, doc);
+      }
+      if (p.selection) ctx.write(changes.SELECTION_FILE, { schema: 1, change: p.change, selected: ctx.now });
+      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, backups, backupDir: backups.length ? `.pincer/backups/${stamp}/` : null };
+  } catch (error) {
+    if (error.refusal) return { plan: first, applied: false, error: error.message, code: error.code, backups };
+    if (error.code === 'STATE_BUSY') return { plan: first, applied: false, error: error.message, code: 'STATE_BUSY', backups };
+    throw error;
+  }
+}
+
+module.exports = { plan, renderPlan, apply, IGNORE_LINE, gitignoreHas };

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

@@ -0,0 +1,316 @@
+'use strict';
+// PINCER runtime — parser and validator for the supported Markdown grammar
+// (docs/runtime-contracts.md, "Supported grammar" and "Content revisions").
+// Dependency-free. The rules and diagnostics match the v0.4.1 Bash validators
+// so the two never disagree; the Node module is now the only implementation.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+
+const TIMESTAMP = /^\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 HEX40 = /^[0-9a-f]{40}$/;
+const DEFAULT_TIMEOUT = 600;
+const MAX_TIMEOUT = 2147483; // setTimeout's 32-bit millisecond limit, in seconds
+const LIFECYCLE_FIELDS = ['status', 'started', 'finished', 'verified', 'last_check'];
+const CHECKBOX_LINE = /^([ \t]*(?:[-+*]|[0-9]+[.)])[ \t]+)\[([ xX])\]/;
+
+const sha256 = text => crypto.createHash('sha256').update(text).digest('hex');
+const lines = text => {
+  const all = String(text).split('\n');
+  if (all.length && all[all.length - 1] === '') all.pop();
+  return all;
+};
+
+// CLI shorthand -> canonical ID ("3" -> "T-03"); null when not a ticket id.
+function normalizeId(input) {
+  let n = String(input);
+  if (n.startsWith('T-') || n.startsWith('t-')) n = n.slice(2);
+  if (!/^[0-9]{1,6}$/.test(n) || Number(n) === 0) return null;
+  return `T-${String(Number(n)).padStart(2, '0')}`;
+}
+function canonicalId(s) {
+  if (typeof s !== 'string' || !/^T-[0-9][0-9]+$/.test(s)) return false;
+  const n = s.slice(2);
+  return n.length <= 6 && Number(n) > 0 && `T-${String(Number(n)).padStart(2, '0')}` === s;
+}
+
+// Frontmatter: `---`, unindented unique `key: value` lines (inline `#` comments,
+// blank and comment lines allowed), `---`. Returns the fields and the index of
+// the closing line, or the single structural problem.
+function parseFrontmatter(text, kind = 'ticket') {
+  const rows = lines(text);
+  const fields = {};
+  const order = [];
+  if (rows[0] !== '---') return { problem: 'frontmatter must begin with ---', rows };
+  for (let i = 1; i < rows.length; i++) {
+    const line = rows[i];
+    if (line === '---') return { fields, order, end: i, rows };
+    if (/^[ \t]*(#.*)?$/.test(line)) continue;
+    if (!/^[a-z_][a-z0-9_]*:[ \t]*/.test(line)) {
+      return { problem: kind === 'ticket' ? 'frontmatter requires unindented key: value fields' : 'expected unindented key: value metadata', rows };
+    }
+    const key = line.slice(0, line.indexOf(':'));
+    if (key in fields) return { problem: `duplicate ${kind === 'ticket' ? 'frontmatter' : 'metadata'} key: ${key}`, rows };
+    let value = line.slice(key.length + 1);
+    value = value.replace(/#.*/, '').trim();
+    fields[key] = value;
+    order.push(key);
+  }
+  return { problem: 'frontmatter must close with ---', rows };
+}
+
+// Read one frontmatter field the way the Bash helper did (first match, comment
+// stripped), tolerating files without valid frontmatter.
+function frontmatterField(text, key) {
+  const fm = parseFrontmatter(text);
+  if (fm.problem && fm.problem !== 'frontmatter must close with ---') {
+    if (fm.problem === 'frontmatter must begin with ---') return '';
+  }
+  for (const line of lines(text).slice(1)) {
+    if (line === '---') break;
+    if (line.startsWith(`${key}:`)) return line.slice(key.length + 1).replace(/#.*/, '').trim();
+  }
+  return '';
+}
+
+function verificationCommands(text) {
+  const out = [];
+  let inBlock = false, otherFence = false, inVerify = false;
+  for (const line of lines(text)) {
+    if (inBlock) { if (/^[ \t]*```[ \t]*$/.test(line)) break; out.push(line); continue; }
+    if (otherFence) { if (/^[ \t]*```/.test(line)) otherFence = false; continue; }
+    if (/^## Verification[ \t]*$/.test(line)) { inVerify = true; continue; }
+    if (inVerify && /^[ \t]*```bash[ \t]*$/.test(line)) { inBlock = true; continue; }
+    if (inVerify && /^## /.test(line)) break;
+    if (/^[ \t]*```/.test(line)) otherFence = true;
+  }
+  return out;
+}
+// The block as the legacy helper hashed and executed it: joined lines, one trailing newline.
+const blockText = text => { const c = verificationCommands(text); return c.length ? `${c.join('\n')}\n` : ''; };
+const legacyBlockHash = text => sha256(blockText(text)).slice(0, 12);
+
+function unticked(text) {
+  const out = [];
+  let otherFence = false, inAccept = false;
+  for (const line of lines(text)) {
+    if (otherFence) { if (/^[ \t]*```/.test(line)) otherFence = false; continue; }
+    if (/^[ \t]*```/.test(line)) { otherFence = true; continue; }
+    if (/^## Acceptance Criteria[ \t]*$/.test(line)) { inAccept = true; continue; }
+    if (inAccept && /^## /.test(line)) break;
+    if (inAccept && /^[ \t]*([-+*]|[0-9]+[.)])[ \t]+\[ \]/.test(line)) out.push(line);
+  }
+  return out;
+}
+
+function effectiveTimeout(fields) {
+  return fields.timeout ? Number(fields.timeout) : DEFAULT_TIMEOUT;
+}
+
+// Full ticket validation. Returns { ok, problems, fields, timeout }.
+function validateTicket(file, text) {
+  const problems = [];
+  const fm = parseFrontmatter(text, 'ticket');
+  if (fm.problem) return { ok: false, problems: [fm.problem], fields: {} };
+  const { fields, rows } = fm;
+  let inVerify = false, otherFence = false, section = '';
+  let accept = 0, verify = 0, boxes = 0, fences = 0, runnable = 0;
+  for (let i = fm.end + 1; i < rows.length; i++) {
+    const line = rows[i];
+    if (inVerify) {
+      if (/^[ \t]*```[ \t]*$/.test(line)) { inVerify = false; continue; }
+      if (/^[ \t]*```/.test(line)) { problems.push('Verification requires one closed bash fence'); continue; }
+      if (!/^[ \t]*(#.*)?$/.test(line)) runnable++;
+      continue;
+    }
+    if (otherFence) { if (/^[ \t]*```/.test(line)) otherFence = false; continue; }
+    if (/^## Acceptance Criteria[ \t]*$/.test(line)) { if (accept++) problems.push('duplicate Acceptance Criteria section'); section = 'accept'; continue; }
+    if (/^## Verification[ \t]*$/.test(line)) { if (verify++) problems.push('duplicate Verification section'); section = 'verify'; continue; }
+    if (/^## /.test(line)) { section = ''; continue; }
+    if (section === 'accept') {
+      if (/^[ \t]*(```|~~~)/.test(line)) { problems.push('Acceptance Criteria must contain visible checkboxes, not fences'); continue; }
+      if (/^[ \t]*([-+*]|[0-9]+[.)])[ \t]+/.test(line) || /^[ \t]*([-+*]|[0-9]+[.)])?[ \t]*\[/.test(line)) {
+        if (!/^[ \t]*([-+*]|[0-9]+[.)])[ \t]+\[[ xX]\][ \t]+[^ \t]/.test(line)) {
+          problems.push('malformed acceptance checkbox; use - [ ] text or - [x] text (indented/list marker variants supported)');
+        }
+        boxes++;
+      }
+    }
+    if (/^[ \t]*~~~/.test(line)) { problems.push('use backtick fences; tilde fences are unsupported'); continue; }
+    if (/^[ \t]*```/.test(line)) {
+      if (section === 'verify') {
+        if (!/^[ \t]*```bash[ \t]*$/.test(line) || fences++) problems.push('Verification requires exactly one bash fence');
+        inVerify = true;
+      } else otherFence = true;
+    }
+  }
+  if (!('ticket' in fields) || !canonicalId(fields.ticket)) problems.push('ticket must be a canonical ID between T-01 and T-999999');
+  else {
+    const base = path.basename(file);
+    const prefix = `${fields.ticket}-`;
+    if (!base.startsWith(prefix) || !/.+\.md$/.test(base) || base.length <= prefix.length + 3) problems.push('ticket ID must match filename T-NN-slug.md');
+  }
+  if (!['open', 'in_progress', 'done'].includes(fields.status)) problems.push('status must be open, in_progress, or done');
+  if (!['S', 'M', 'L'].includes(fields.size)) problems.push('size must be S, M, or L');
+  for (const key of ['started', 'finished']) if (key in fields && !TIMESTAMP.test(fields[key])) problems.push(`${key} must be an ISO UTC timestamp`);
+  for (const key of ['verified', 'last_check']) {
+    if (!(key in fields)) continue;
+    const parts = fields[key].split(/[ \t]+/);
+    const expected = key === 'verified' ? 2 : 3;
+    if (parts.length !== expected || !TIMESTAMP.test(parts[0]) || !/^[0-9a-f]{12}$/.test(parts[parts.length - 1])) problems.push(`malformed ${key} timestamp/hash`);
+    else if (key === 'last_check' && !['running', 'passed', 'failed', 'interrupted'].includes(parts[1])) problems.push('invalid last_check outcome');
+  }
+  if ('timeout' in fields && (!/^[1-9][0-9]{0,8}$/.test(fields.timeout) || Number(fields.timeout) > MAX_TIMEOUT)) problems.push(`timeout must be a positive integer number of seconds (at most ${MAX_TIMEOUT})`);
+  const deps = fields.depends_on;
+  if (!('depends_on' in fields) || !/^\[[ \t]*(T-[0-9]+([ \t]*,[ \t]*T-[0-9]+)*)?[ \t]*\]$/.test(deps)) problems.push('depends_on must be an inline list such as [T-01, T-02]');
+  else {
+    const seen = new Set();
+    for (const entry of deps.replace(/^\[[ \t]*/, '').replace(/[ \t]*\]$/, '').split(',')) {
+      const dep = entry.trim();
+      if (dep === '') continue;
+      if (!canonicalId(dep)) problems.push(`depends_on contains noncanonical ticket ID: ${dep}`);
+      if (dep === fields.ticket) problems.push('ticket cannot depend on itself');
+      if (seen.has(dep)) problems.push(`duplicate depends_on ID: ${dep}`);
+      seen.add(dep);
+    }
+  }
+  if (!accept || !boxes) problems.push('Acceptance Criteria requires at least one nonempty checkbox');
+  if (!verify || fences !== 1 || inVerify || !runnable) problems.push('Verification requires exactly one closed runnable bash fence');
+  if (problems.length === 0) {
+    const syntax = spawnSync('bash', ['-n', '-c', blockText(text)], { encoding: 'utf8' });
+    if (syntax.error) problems.push(`cannot run bash to check the Verification block (${syntax.error.message})`);
+    else if (syntax.status !== 0) problems.push('invalid bash syntax in Verification block');
+  }
+  return { ok: problems.length === 0, problems, fields, timeout: effectiveTimeout(fields) };
+}
+
+function dependencies(fields) {
+  return ((fields.depends_on || '').match(/T-[0-9]+/g) || []);
+}
+
+// PRDs and evaluation notes use the same deliberately small metadata format.
+function validateMetadata(text) {
+  const fm = parseFrontmatter(text, 'metadata');
+  return fm.problem ? { ok: false, problems: [fm.problem], fields: {} } : { ok: true, problems: [], fields: fm.fields };
+}
+
+function validatePrd(root, ref) {
+  const match = typeof ref === 'string' ? ref.match(PRD_REF) : null;
+  if (!match) return { ok: false, problems: [`invalid PRD reference ${ref}; use .prd/prd-vN.md`], prefix: 'pincer' };
+  const file = path.join(root, ref);
+  if (!fs.existsSync(file)) return { ok: false, problems: [`PRD does not exist: ${ref}`], prefix: 'pincer' };
+  const text = fs.readFileSync(file, 'utf8');
+  const meta = validateMetadata(text);
+  if (!meta.ok) return { ok: false, problems: meta.problems, file: ref };
+  const problems = [];
+  const { fields } = meta;
+  if (fields.version !== match[1]) problems.push(`version must match filename (${match[1]})`);
+  if (!['draft', 'ticketed', 'built'].includes(fields.status)) problems.push('PRD status must be draft, ticketed, or built');
+  if (!['', 'small', 'standard', undefined].includes(fields.profile)) problems.push('profile must be small or standard (omit for standard)');
+  return { ok: problems.length === 0, problems, file: ref, fields, text, profile: fields.profile || 'standard' };
+}
+
+// Normalizations (contract "Content revisions"): lifecycle fields and checkbox
+// marks are the only exceptions; everything else contributes to identity.
+function normalizeTicket(text) {
+  const rows = lines(text);
+  const out = [];
+  let closed = rows[0] !== '---';
+  let otherFence = false, inAccept = false;
+  for (let i = 0; i < rows.length; i++) {
+    const line = rows[i];
+    if (!closed) {
+      if (i > 0 && line === '---') closed = true;
+      else if (i > 0) {
+        const key = (line.match(/^([a-z_][a-z0-9_]*):/) || [])[1];
+        if (key && LIFECYCLE_FIELDS.includes(key)) continue;
+      }
+      out.push(line);
+      continue;
+    }
+    if (otherFence) { if (/^[ \t]*```/.test(line)) otherFence = false; out.push(line); continue; }
+    if (/^[ \t]*```/.test(line)) { otherFence = true; out.push(line); continue; }
+    if (/^## Acceptance Criteria[ \t]*$/.test(line)) inAccept = true;
+    else if (/^## /.test(line)) inAccept = false;
+    out.push(inAccept ? line.replace(CHECKBOX_LINE, '$1[ ]') : line);
+  }
+  return `${out.join('\n')}\n`;
+}
+function normalizePrd(text) {
+  const rows = lines(text);
+  const out = [];
+  let closed = rows[0] !== '---';
+  for (let i = 0; i < rows.length; i++) {
+    const line = rows[i];
+    if (!closed) {
+      if (i > 0 && line === '---') closed = true;
+      else if (i > 0 && /^status:/.test(line)) continue;
+    }
+    out.push(line);
+  }
+  return `${out.join('\n')}\n`;
+}
+// Split a ticket text into the parts the structural agreement difference names:
+// the frontmatter, the Acceptance Criteria section, the Verification section and
+// everything else (headings inside fenced blocks are ignored, as elsewhere).
+function ticketSections(text) {
+  const rows = lines(text);
+  const parts = { frontmatter: [], acceptance: [], verification: [], other: [] };
+  let inFront = rows[0] === '---', section = 'other', fence = false;
+  for (let i = 0; i < rows.length; i++) {
+    const line = rows[i];
+    if (inFront) { parts.frontmatter.push(line); if (i > 0 && line === '---') inFront = false; continue; }
+    if (fence) { parts[section].push(line); if (/^[ \t]*```/.test(line)) fence = false; continue; }
+    if (/^[ \t]*```/.test(line)) { fence = true; parts[section].push(line); continue; }
+    if (/^## Acceptance Criteria[ \t]*$/.test(line)) section = 'acceptance';
+    else if (/^## Verification[ \t]*$/.test(line)) section = 'verification';
+    else if (/^## /.test(line)) section = 'other';
+    parts[section].push(line);
+  }
+  return Object.fromEntries(Object.entries(parts).map(([k, v]) => [k, v.join('\n')]));
+}
+const ticketDigest = text => sha256(normalizeTicket(text));
+const prdDigest = text => sha256(normalizePrd(text));
+const checkDigest = (text, timeoutSeconds = DEFAULT_TIMEOUT) => sha256(`${blockText(text)}timeout=${timeoutSeconds}\n`);
+
+// tickets/T-NN-*.md resolution and set validation.
+function ticketFiles(root) {
+  const dir = path.join(root, 'tickets');
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter(name => /^T-[0-9]+.*\.md$/.test(name)).sort().map(name => `tickets/${name}`);
+}
+function ticketFile(root, input) {
+  const id = normalizeId(input);
+  if (!id) return { problem: `not a ticket id (expected 1..999999): ${input}` };
+  const matches = ticketFiles(root).filter(f => path.basename(f).startsWith(`${id}-`));
+  if (matches.length > 1) return { problem: `several files match tickets/${id}-*.md` };
+  if (matches.length === 0) return { problem: `no ticket file tickets/${id}-*.md` };
+  return { id, file: matches[0] };
+}
+function validateTicketSet(root) {
+  const files = ticketFiles(root);
+  const ids = new Set();
+  for (const file of files) {
+    const id = frontmatterField(fs.readFileSync(path.join(root, file), 'utf8'), 'ticket');
+    if (id) {
+      if (ids.has(id)) return { ok: false, problems: [`duplicate ticket ID: ${id}`] };
+      ids.add(id);
+    }
+  }
+  for (const file of files) {
+    const result = validateTicket(file, fs.readFileSync(path.join(root, file), 'utf8'));
+    if (!result.ok) return { ok: false, file, problems: result.problems };
+  }
+  return { ok: true, files };
+}
+
+module.exports = {
+  TIMESTAMP, PRD_REF, HEX40, DEFAULT_TIMEOUT, MAX_TIMEOUT, LIFECYCLE_FIELDS,
+  sha256, lines, normalizeId, canonicalId, parseFrontmatter, frontmatterField,
+  verificationCommands, blockText, legacyBlockHash, unticked, effectiveTimeout,
+  validateTicket, dependencies, validateMetadata, validatePrd,
+  normalizeTicket, normalizePrd, ticketDigest, prdDigest, checkDigest, ticketSections,
+  ticketFiles, ticketFile, validateTicketSet,
+};