ultra-builder-pro-cli 5.0.0 → 6.0.0

package/engine/checks.cjs

@@ -0,0 +1,139 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+const { spawn } = require('node:child_process');
+const { codeState, gitEnvironment } = require('./git-state.cjs');
+const { append } = require('./ledger.cjs');
+const { expectOutput } = require('./expect.cjs');
+const { load } = require('./loading.cjs');
+const { status } = require('./states.cjs');
+const INTERRUPTS = require('./signals.cjs');
+// The output tail: the last 4 MiB of the log, where `expect` and `error_line` look.
+function readTail(fd) {
+  const size = fs.fstatSync(fd).size;
+  const buffer = Buffer.alloc(Math.min(size, 4 * 1024 * 1024));
+  fs.readSync(fd, buffer, 0, buffer.length, size - buffer.length);
+  return buffer.toString('utf8');
+}
+function killGroup(child, signal = 'SIGKILL') {
+  if (!(child.pid > 0)) return;
+  try { process.kill(-child.pid, signal); }
+  catch (error) { if (!['ESRCH', 'EPERM'].includes(error.code)) throw error; }
+}
+// The shell writes straight into the log file: no pipe is read, so output size never
+// costs memory and a descendant that escaped the group cannot keep the engine waiting.
+function runShell(root, check, fd, extraEnv = {}, graceMs = 0) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('/bin/sh', ['-c', check.run], { cwd: root,
+      env: { ...gitEnvironment(root), ...extraEnv },
+      detached: true, stdio: ['ignore', fd, fd] });
+    const result = { code: null, signal: null, timedOut: false, spawnError: false,
+      interrupted: 0 };
+    let graceTimer, exited = false;
+    const finish = (error) => {
+      for (const t of [timer, graceTimer]) clearTimeout(t);
+      for (const [signal, handler] of handlers) process.off(signal, handler);
+      if (error) reject(error); else resolve(result);
+    };
+    const kill = (signal) => {
+      try { killGroup(child, signal); } catch (error) { finish(error); }
+    };
+    const stop = () => {
+      if (!graceMs) return kill();
+      if (graceTimer) return;
+      kill('SIGTERM');
+      graceTimer = setTimeout(() => {
+        graceTimer = null;
+        kill();
+        if (exited) finish();
+      }, graceMs);
+    };
+    const handlers = Object.entries(INTERRUPTS).map(([signal, exitCode]) =>
+      [signal, () => { result.interrupted = exitCode; stop(); }]);
+    const timer = setTimeout(() => { result.timedOut = true; stop(); }, check.timeout * 1000);
+    for (const [signal, handler] of handlers) process.on(signal, handler);
+    child.on('error', (error) => {
+      result.spawnError = true;
+      fs.writeSync(fd, `${error.message}\n`);
+      finish();
+    });
+    child.on('exit', (code, signal) => {
+      Object.assign(result, { code, signal });
+      exited = true;
+      clearTimeout(timer);
+      // Let an inner ubp stop its detached checks even when its shell exits first.
+      if (graceMs && !graceTimer) {
+        try { process.kill(-child.pid, 0); stop(); }
+        catch (error) { if (!['ESRCH', 'EPERM'].includes(error.code)) return finish(error); }
+      }
+      if (!graceTimer) { kill(); finish(); }
+    });
+  });
+}
+async function outcomeFor(exit, check, output) {
+  if (exit.timedOut) return ['unknown', 'timeout'];
+  if (exit.spawnError) return ['unknown', 'spawn-error'];
+  if (exit.signal) return ['unknown', `signal-${exit.signal}`];
+  if (exit.code === 126 || exit.code === 127) return ['unknown', 'not-runnable'];
+  if (exit.code !== 0) return ['fail', `exit-${exit.code}`];
+  const reason = await expectOutput(check.expect, output);
+  return [reason === 'exit-0' ? 'pass' : 'unknown', reason];
+}
+function errorLine(output) {
+  const lines = output.split(/\r?\n/u).filter((line) => line.trim());
+  const pattern = /^\s*(?:✖|not ok\b|FAIL(?:ED)?\b)|\b(?:[A-Z][A-Za-z]*)?Error\b/u;
+  return (lines.find((line) => pattern.test(line)) ?? lines.at(-1) ?? '').slice(0, 200);
+}
+async function execute(project, check) {
+  const run = randomUUID();
+  const log = `.ultra/.runtime/checks/${run}.log`;
+  fs.mkdirSync(path.dirname(path.join(project.root, log)), { recursive: true });
+  const fd = fs.openSync(path.join(project.root, log), 'w+');
+  const started = performance.now();
+  const before = codeState(project.root);
+  let exit, output;
+  try {
+    exit = await runShell(project.root, check, fd);
+    output = readTail(fd);
+  } finally { fs.closeSync(fd); }
+  if (exit.interrupted) throw Object.assign(new Error('Check interrupted.'),
+    { exitCode: exit.interrupted });
+  const [outcome, reason] = await outcomeFor(exit, check, output);
+  const after = codeState(project.root);
+  const record = { v: 1, run, check: check.id, at: new Date().toISOString(), outcome, reason,
+    exit_code: exit.code, duration_ms: Math.round(performance.now() - started), code: before.code,
+    dirty: before.dirty || after.dirty || before.code !== after.code, check_fp: check.fp,
+    reqs: Object.fromEntries(check.covers.filter((id) => project.reqs.has(id))
+      .map((id) => [id, project.reqs.get(id)])),
+    shared: project.shared, log, error_line: outcome === 'pass' ? null : errorLine(output) };
+  append(project.root, 'evidence', record);
+  return record;
+}
+function selectedChecks(project, opts) {
+  const { words } = opts;
+  if (words.length && opts.selector) throw new Error('Choose check ids or a check selector.');
+  const badId = words.find((id) => !project.checks.some((c) => c.id === id));
+  if (badId !== undefined) throw new Error(`Unknown check ${badId}. Use an id from checks.json.`);
+  if (opts.req !== null && !project.reqs.has(opts.req))
+    throw new Error(`Unknown requirement ${opts.req}. Use an id from spec.md.`);
+  const scope = project.checks.filter((c) => words.length ? words.includes(c.id)
+    : opts.selector !== 'req' || c.covers.includes(opts.req));
+  const stale = !words.length && (!opts.selector || opts.selector === 'stale');
+  const pending = stale ? status(project).checks
+    .filter((c) => ['stale', 'unknown'].includes(c.state)).map((c) => c.id) : null;
+  return { scope, selected: pending ? scope.filter((c) => pending.includes(c.id)) : scope };
+}
+async function runChecks(project, opts) {
+  const runs = [];
+  const { scope, selected } = selectedChecks(project, opts);
+  for (const check of selected) {
+    const { check: id, run, outcome, reason, dirty } = await execute(project, check);
+    runs.push({ check: id, run, outcome, reason, dirty });
+  }
+  const after = status(load(project.root));
+  const ok = after.checks.filter((c) => scope.some((check) => check.id === c.id))
+    .every((c) => c.state === 'green');
+  return { result: { dirty: after.dirty, runs }, ok, after };
+}
+module.exports = { execute, runShell, runChecks };

package/engine/cli.cjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+'use strict';
+
+const { load, status, gate, complete } = require('./project.cjs');
+const { runChecks } = require('./checks.cjs');
+const { drive } = require('./drive.cjs');
+const { close } = require('./milestone.cjs');
+const { context } = require('./context.cjs');
+const { approve } = require('./plan.cjs');
+const { retro } = require('./states.cjs');
+const { merge } = require('./merge.cjs');
+
+function options(args, command) {
+  const local = { check: ['--all', '--stale', '--req'],
+    milestone: ['--owner', '--review', '--proxy'], approve: ['--owner', '--proxy'],
+    context: ['--budget'], merge: ['--expect-head'],
+    drive: ['--writer', '--reviewer', '--attempts', '--max-writers', '--timeout-sec'] };
+  const allowed = new Set(['--root', '--json', ...(local[command] || [])]);
+  const result = { root: process.cwd(), json: false, words: [], selector: null, req: null,
+    owner: null, review: null, proxy: false, budget: 32768,
+    attempts: 3, 'max-writers': 10, 'timeout-sec': 3600 };
+  const values = ['--root', '--req', '--owner', '--review', '--budget', '--expect-head',
+    ...local.drive];
+  const seen = new Set();
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('-') && !allowed.has(arg)) {
+      throw new Error(`Option ${arg} is not valid for ${command}.`);
+    }
+    if (values.includes(arg)) {
+      if (!['--root', '--req'].includes(arg) && seen.has(arg)) {
+        throw new Error(`${arg} may only be given once.`);
+      }
+      seen.add(arg);
+      let value = args[++i];
+      if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value.`);
+      if (arg === '--req') {
+        if (result.selector) throw new Error('Choose only one check selector.');
+        result.selector = 'req';
+      } else if (['--budget', '--attempts', '--max-writers', '--timeout-sec'].includes(arg)) {
+        const n = Number(value), max = arg === '--timeout-sec' ? 86400 : Number.MAX_SAFE_INTEGER;
+        if (!/^\d+$/u.test(value) || !Number.isSafeInteger(n) || n < 1 || n > max) {
+          throw new Error(`${arg} requires a positive integer no greater than ${max}.`);
+        }
+        value = n;
+      }
+      result[arg.slice(2)] = value;
+    } else if (arg === '--json') result.json = true;
+    else if (arg === '--proxy') result.proxy = true;
+    else if (arg === '--all' || arg === '--stale') {
+      if (result.selector) throw new Error('Choose only one check selector.');
+      result.selector = arg.slice(2);
+    } else result.words.push(arg);
+  }
+  return result;
+}
+
+function printResult(command, opts, result, project, after) {
+  if (opts.json) { console.log(JSON.stringify(result)); return; }
+  for (const warning of project.warnings) console.error(warning);
+  if (command === 'status') console.log(result.line);
+  else if (command === 'drive') return;
+  else if (command === 'approve') console.log(`approved: ${result.items.join(', ')}`);
+  else if (command === 'retro') {
+    for (const c of result.classes) {
+      console.log(`${c.count} × ${c.class} · ${c.checks.join(', ')}`);
+    }
+    console.log(`重复两次及以上：${result.classes.filter((c) => c.count >= 2).length} 类`);
+  } else if (command === 'merge') {
+    const verdict = result.ok ? `pass ${result.merged.slice(0, 7)}` : 'refused';
+    console.log(`merge ${opts.words[0]}: ${verdict}`);
+    for (const p of result.problems) console.log(`${p.code}: ${p.message} — ${p.hint}`);
+    for (const warning of result.warnings) console.error(`warning: ${warning}`);
+  } else if (command === 'context') {
+    if (result.ok) process.stdout.write(result.brief);
+    else for (const p of result.problems) console.error(`${p.code}: ${p.message} — ${p.hint}`);
+  } else if (command === 'check') {
+    for (const r of result.runs) {
+      const reason = r.reason + (r.dirty ? ', dirty: not counted' : '');
+      console.log(`${r.check}: ${r.outcome} (${reason})`);
+      const check = project.checks.find((c) => c.id === r.check);
+      if (check.fix !== undefined && r.outcome !== 'pass') console.log(`  fix: ${check.fix}`);
+    }
+    console.log(after.line);
+  } else {
+    const name = ['node', 'milestone'].includes(command)
+      ? `${command} ${result[command]}` : 'gate';
+    console.log(`${name}: ${result.ok ? 'pass' : 'fail'}`);
+    for (const p of result.problems) console.log(`${p.code}: ${p.message} — ${p.hint}`);
+  }
+}
+
+async function handle(args) {
+  try {
+    const [command, ...rest] = args;
+    if (process.env.UBP_DRIVE !== undefined
+        && ['approve', 'milestone', 'merge', 'drive'].includes(command)) {
+      throw new Error('Not allowed inside ubp drive.');
+    }
+    const commands = ['status', 'gate', 'check', 'node', 'milestone', 'context', 'approve',
+      'retro', 'merge', 'drive'];
+    if (!commands.includes(command)) {
+      throw new Error(`Unknown command ${command ?? ''}. Use ${commands.join(', ')}.`);
+    }
+    const opts = options(rest, command);
+    const { words } = opts;
+    if ((['status', 'gate', 'retro'].includes(command) && words.length)
+        || (command === 'node' && (words.length !== 2 || words[0] !== 'done'))
+        || (command === 'milestone' && (words.length !== 2 || words[0] !== 'close'))
+        || (command === 'context' && words.length !== 1)
+        || (command === 'merge' && (words.length !== 1 || !opts['expect-head']))
+        || (command === 'approve' && !words.length)) {
+      const usage = { node: 'node done <id>',
+        milestone: 'milestone close <id> --owner <words> --review <path>',
+        context: 'context <id>', approve: 'approve <milestone>/<id>… --owner <words>',
+        merge: 'merge <branch> --expect-head <commit>'
+      }[command] || command;
+      throw new Error(`Usage: ${usage} [--root <dir>] [--json]`);
+    }
+    if (command === 'milestone' && (!opts.owner?.trim() || !opts.review)) {
+      throw new Error('milestone close requires --owner <non-empty words> and --review <path>.');
+    }
+    if (command === 'approve' && !opts.owner?.trim()) {
+      throw new Error('approve requires --owner <non-empty words>.');
+    }
+    const project = load(opts.root);
+    const actions = { status, gate, retro,
+      node: (p) => complete(p, words[1]), milestone: (p) => close(p, words[1], opts),
+      context: (p) => context(p, words[0], opts.budget), approve: (p) => approve(p, words, opts),
+      merge: (p) => merge(p, words[0], opts['expect-head']), drive: (p) => drive(p, opts) };
+    const checked = command === 'check' ? await runChecks(project, opts) : null;
+    const result = checked ? checked.result : await actions[command](project);
+    printResult(command, opts, result, project, checked?.after);
+    if (command === 'drive') return Number(result.verdict === 'revise'
+      || !['milestone-gate', 'all-done'].includes(result.stop));
+    if (['status', 'retro'].includes(command)) return 0;
+    return (checked ? checked.ok : result.ok) ? 0 : 1;
+  } catch (error) {
+    console.error(error.message);
+    return error.exitCode ?? 2;
+  }
+}
+
+if (require.main === module) {
+  handle(process.argv.slice(2)).then((code) => { process.exitCode = code; });
+}
+
+module.exports = { handle };

package/engine/completion.cjs

@@ -0,0 +1,48 @@
+'use strict';
+
+const { unique, problem } = require('./formats.cjs');
+const { withLock, append } = require('./ledger.cjs');
+const { load } = require('./loading.cjs');
+const { status, invariantProblems, dependencies } = require('./states.cjs');
+
+const complete = ({ root }, id) => withLock(root, () => recordCompletion(load(root), id));
+
+function recordCompletion(project, id) {
+  const node = project.nodes.find((n) => n.id === id);
+  if (!node) throw new Error(`Unknown node ${id}. Use an id from plan.json.`);
+  const state = status(project);
+  const problems = [];
+  if (state.gate !== 'pass') problems.push(problem('plan-gate', `Plan gate is ${state.gate}`,
+    'Fix plan problems and rerun gate.'));
+  if (state.dirty) problems.push(problem('dirty-tree', 'Code tree is dirty',
+    'Commit or restore code changes before completing the node.'));
+  problems.push(...dependencies(project, node).filter((dep) =>
+    !state.nodes.some((n) => n.id === dep && n.state === 'done'))
+    .map((dep) => problem('dependency-not-done', `${dep} is not done`,
+      'Complete the dependency first.')));
+  let required = node.covers;
+  if (node.kind === 'cleanup') {
+    const closed = new Set(project.closures.map((c) => c.milestone));
+    const done = project.nodes.filter((n) => n.milestone === node.milestone
+      && state.nodes.some((s) => s.id === n.id && s.state === 'done'));
+    const covered = new Set(done.flatMap((n) => n.covers));
+    required = unique(project.milestones.flatMap((m) => closed.has(m.id) ? m.requirements
+      : m.id === node.milestone ? m.requirements.filter((r) => covered.has(r)) : []));
+  }
+  problems.push(...required.filter((req) => !state.requirements.some((r) =>
+    r.id === req && r.state === 'green'))
+    .map((req) => problem('requirement-not-green', `${req} is not green`,
+      'Run its checks on clean, current code.')));
+  problems.push(...invariantProblems(state));
+  if (!problems.length) {
+    const ids = state.requirements.filter((r) => node.covers.includes(r.id))
+      .flatMap((r) => r.checks.map((c) => c.id));
+    append(project.root, 'nodes', { v: 1, node: id, at: new Date().toISOString(),
+      code: project.code, shared: project.shared,
+      reqs: Object.fromEntries(node.covers.map((r) => [r, project.reqs.get(r)])),
+      runs: unique(state.checks.filter((c) => ids.includes(c.id)).map((c) => c.last_run)) }, true);
+  }
+  return { ok: !problems.length, node: id, problems };
+}
+
+module.exports = { complete };

package/engine/context.cjs

@@ -0,0 +1,94 @@
+'use strict';
+
+const { problem, readRecord } = require('./formats.cjs');
+const { status } = require('./states.cjs');
+
+function rules(id, checks) {
+  const ids = checks.map((c) => c.id).join(' ') || '--stale';
+  return [
+    '- Do not edit .ultra/spec.md, .ultra/checks.json, .ultra/plan.json, .ultra/ledger/ '
+      + 'or the files the checks above run. If a check or a requirement looks wrong, '
+      + 'stop and escalate.',
+    '- Change only files inside the scope, and commit your work: '
+      + 'evidence from an uncommitted tree never counts.',
+    `- Run \`ubp check ${ids}\` until every check above is green, then \`ubp check\` `
+      + '(every stale check: invariants and finished requirements must stay green), '
+      + `then \`ubp node done ${id}\`.`,
+    '- Escalate instead of deciding: a change of direction (L0) and any deletion or '
+      + 'narrowing of a requirement go to the Owner.',
+    '- Record every other decision you made without asking as one line in .ultra/rulings.md: '
+      + '`- YYYY-MM-DD Lx 裁决：<决定> — 因为 <理由> '
+      + '— 如果判断错了，代价是 <代价>`.',
+    `- Before \`ubp node done ${id}\`, write .ultra/records/handoffs/${id}.md: `
+      + 'the interfaces you created, what dependent nodes must know, and what is left unfinished.',
+    '- If three attempts leave a check red, stop and report the check, '
+      + 'its error line and what you tried.',
+  ].join('\n');
+}
+
+function compile(project, node, state, handoffs) {
+  const milestone = project.milestones.find((m) => m.id === node.milestone);
+  const checks = project.checks.filter((c) => node.kind === 'cleanup' ? Object.hasOwn(c, 'fix')
+    : c.covers.some((r) => node.covers.includes(r)));
+  return [
+    `# Node ${node.id}: ${node.title}`,
+    `Milestone ${node.milestone}: ${milestone?.title ?? 'not in .ultra/plan.json'} · node state `
+      + state.nodes.find((n) => n.id === node.id).state,
+    '## Requirements',
+    node.covers.map((r) => project.requirementText.get(r) ?? `${r}: not in .ultra/spec.md`)
+      .join('\n\n') || 'None.',
+    '## Checks that must turn green (read-only)',
+    checks.map((c) => `- ${c.id} · ${state.checks.find((s) => s.id === c.id).state} · `
+      + `\`${c.run}\`` + (node.kind === 'cleanup' ? ` · fix: ${c.fix}` : ''))
+      .join('\n') || 'None.',
+    '## Scope',
+    node.scope?.length ? node.scope.map((prefix) => `- ${prefix}`).join('\n')
+      : 'Not declared: change only what the requirements need.',
+    '## Handoffs from dependencies',
+    handoffs.length ? handoffs.map((h) => `### ${h.id}\n\n${h.text}`).join('\n\n') : 'None.',
+    '## Rules',
+    rules(node.id, checks),
+  ].join('\n\n') + '\n';
+}
+
+function handoff(root, id) {
+  const relative = `.ultra/records/handoffs/${id}.md`;
+  const { exists, bytes } = readRecord(root, relative);
+  if (!exists) return { text: 'No handoff written.', fromFile: false };
+  if (!bytes) {
+    return { text: 'Not read: not a regular file inside the project.', fromFile: false };
+  }
+  const text = bytes.toString('utf8').replace(/\r\n/gu, '\n')
+    .replace(/^(?:[^\S\n]*\n)+/u, '').trimEnd();
+  return { text: text || 'No handoff written.', fromFile: true };
+}
+
+function context(project, id, budget) {
+  const node = project.nodes.find((n) => n.id === id);
+  if (!node) throw new Error(`Unknown node ${id}. Use an id from plan.json.`);
+  const state = status(project);
+  const handoffs = node.depends.map((dep) => ({ id: dep,
+    ...(project.nodes.some((n) => n.id === dep) ? handoff(project.root, dep)
+      : { text: 'Not a node in .ultra/plan.json.', fromFile: false }) }));
+  let brief = compile(project, node, state, handoffs);
+  let bytes = Buffer.byteLength(brief);
+  const omitted = [];
+  for (let i = handoffs.length - 1; bytes > budget && i >= 0; i--) {
+    const handoff = handoffs[i];
+    const replacement = `Omitted to fit the budget: read .ultra/records/handoffs/${handoff.id}.md`;
+    if (!handoff.fromFile || Buffer.byteLength(handoff.text) <= Buffer.byteLength(replacement)) {
+      continue;
+    }
+    handoff.text = replacement;
+    omitted.push(handoff.id);
+    brief = compile(project, node, state, handoffs);
+    bytes = Buffer.byteLength(brief);
+  }
+  const ok = bytes <= budget;
+  const problems = ok ? [] : [problem('brief-over-budget',
+    `Node ${id} brief is ${bytes} bytes, exceeding the ${budget} byte budget`,
+    'Split the node so its requirements, checks and rules fit the budget.')];
+  return { ok, node: id, bytes, omitted, brief: ok ? brief : null, problems };
+}
+
+module.exports = { context };

package/engine/drive.cjs

@@ -0,0 +1,220 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+const { load, status, gate } = require('./project.cjs');
+const { context } = require('./context.cjs');
+const { runChecks, runShell } = require('./checks.cjs');
+const { git, codeState } = require('./git-state.cjs');
+const { problem, readRecord, hash } = require('./formats.cjs');
+const { acquireLock } = require('./ledger.cjs');
+const { reviewVerdict } = require('./milestone.cjs');
+const truth = ['.ultra/spec.md', '.ultra/checks.json', '.ultra/plan.json',
+  '.ultra/ledger/milestones.jsonl', '.ultra/ledger/approvals.jsonl',
+  '.ultra/ledger/plan-log.jsonl'];
+const exempt = [...truth, '.ultra/ledger/evidence.jsonl', '.ultra/ledger/nodes.jsonl'];
+const quote = (word) => `'${word.replace(/'/gu, "'\\''")}'`;
+const issue = (code, subject) => problem(code, `${subject}: ${code}`,
+  'Resolve this stop before resuming drive.');
+const paths = (root, args) => git(root, args).toString('utf8').split('\0').filter(Boolean);
+const within = (file, prefix) => file === prefix || file.startsWith(`${prefix}/`);
+const clean = (root, review) => !paths(root, ['ls-files', '-v', '-z'])
+  .some((entry) => /^[a-zS]/u.test(entry)) && !codeState(root, (file) => file === review
+  || ['.ultra/.runtime', '.ultra/ledger'].some((dir) => within(file, dir))).dirty;
+function snapshot(root) {
+  const head = git(root, ['rev-parse', 'HEAD']).toString('utf8').trim();
+  const entries = new Map(paths(root, ['ls-tree', '-r', '-z', head, '--', ...truth])
+    .map((entry) => [entry.slice(entry.indexOf('\t') + 1), entry.split(/[ \t]/u)[2]]));
+  const settings = ['config', 'config.worktree', 'info/exclude'].map((name) => {
+    const file = git(root, ['rev-parse', '--git-path', name]).toString('utf8').trim();
+    try { return hash(fs.readFileSync(path.resolve(root, file))); }
+    catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  });
+  return { head, settings: JSON.stringify(settings), truth: truth.map((file) => {
+    const { bytes, exists } = readRecord(root, file);
+    return [bytes ? hash(bytes) : exists ? 'not-regular' : null,
+      entries.has(file) ? hash(git(root, ['cat-file', 'blob', entries.get(file)])) : null];
+  }) };
+}
+const touched = (before, after) => truth.filter((file, i) =>
+  after.truth[i][0] !== before.truth[i][0] || !before.truth[i].includes(after.truth[i][1]));
+function boundary(root, before, after, node, project) {
+  const problems = touched(before, after).map((file) => issue('truth-touched', file));
+  if (problems.length) return problems;
+  try { git(root, ['merge-base', '--is-ancestor', before.head, after.head]); }
+  catch (error) {
+    if (error.status !== 1) throw error;
+    return [issue('history-rewritten', node.id)];
+  }
+  if (before.settings !== after.settings || !clean(root))
+    return [issue('writer-left-dirty', node.id)];
+  const named = new Set(project.checks.flatMap((c) => c.run.split(/\s+/u)
+    .map((word) => word.replace(/^["']|["']$/gu, '').replace(/^\.\//u, ''))));
+  const scopes = [...node.scope, '.ultra/rulings.md', '.ultra/records/handoffs']
+    .map((prefix) => prefix.replace(/\/+$/u, ''));
+  return paths(root, ['diff', '--no-renames', '--name-only', '-z', before.head, after.head])
+    .filter((file) => !exempt.includes(file)).sort().flatMap((file) => {
+      const code = named.has(file) ? 'check-touched'
+        : scopes.some((prefix) => within(file, prefix)) ? null : 'out-of-scope';
+      return code ? [issue(code, file)] : [];
+    });
+}
+function additions(before, after) {
+  const previous = before.map((r) => JSON.stringify(r));
+  return after.filter((r) => {
+    const index = previous.indexOf(JSON.stringify(r));
+    if (index >= 0) previous.splice(index, 1);
+    return index < 0;
+  });
+}
+async function verify(project, node, before, after, baseline) {
+  const problems = boundary(project.root, before, after, node, project);
+  if (problems.some((p) => !['out-of-scope', 'check-touched'].includes(p.code))) return problems;
+  const current = load(project.root);
+  const added = additions(project.completions, current.completions);
+  problems.push(...project.nodes.filter((n) => n.id !== node.id
+    && added.some((r) => r.node === n.id)).map((n) => issue('out-of-scope', n.id)));
+  if (problems.length) return problems;
+  const state = status(current);
+  if (state.gate !== 'pass') return [issue('plan-gate', node.id), ...state.problems];
+  const evidence = additions(project.evidence, current.evidence);
+  const requiredCheck = (c) => Object.hasOwn(c, 'fix')
+    || c.covers.some((id) => node.covers.includes(id));
+  const checks = current.checks.filter((c) => requiredCheck(c)
+    || evidence.some((r) => r.check === c.id)
+    || state.checks.some((s) => s.id === c.id && ['stale', 'unknown'].includes(s.state)));
+  const checked = await runChecks(current, { words: checks.map((c) => c.id), req: null });
+  const required = new Set([baseline.milestone, ...project.closures.map((c) => c.milestone)]);
+  problems.push(...baseline.requirements.filter((r) => required.has(r.milestone)
+    && r.state === 'green' && !checked.after.requirements.some((s) => s.id === r.id
+      && s.state === 'green')).map((r) => issue('ratchet-broken', r.id)));
+  if (problems.length) return problems;
+  if (!checked.after.nodes.some((n) => n.id === node.id && n.state === 'done'))
+    return [issue('node-not-done', node.id)];
+  return checked.after.checks.filter((s) => s.state !== 'green' && current.checks.some((c) =>
+    c.id === s.id && requiredCheck(c)))
+    .map((c) => issue('node-not-green', c.id));
+}
+async function drive(project, opts) {
+  if (opts.words.length || !opts.writer?.trim()
+      || (opts.reviewer !== undefined && !opts.reviewer.trim()))
+    throw new Error('drive requires --writer <command> and an optional non-empty --reviewer.');
+  const { root } = project;
+  const result = { run: randomUUID(), stop: null, verdict: null, steps: [], problems: [] };
+  (opts.json ? console.error : console.log)(`drive: run ${result.run}`);
+  const directory = path.join(root, '.ultra/.runtime/drive', result.run);
+  const bin = path.join(directory, 'bin');
+  const base = { UBP_ROOT: root, UBP_DRIVE: '1', PATH: `${bin}:${process.env.PATH ?? ''}`,
+    UBP: [process.execPath, path.join(__dirname, 'cli.cjs')].map(quote).join(' ') };
+  const record = (action, subject, attempt, value, problems = [], exit = null) => {
+    result.steps.push({ action, subject, attempt, result: value, exit, problems });
+    if (!opts.json) console.log(`drive: ${action} ${subject}: ${value}`
+      + (['writer', 'reviewer'].includes(action) ? ` (exit ${exit})` : ''));
+  };
+  const stop = (reason, problems = []) => {
+    if (!opts.json) {
+      for (const p of problems) console.log(`${p.code}: ${p.message} — ${p.hint}`);
+      console.log(`drive: stop ${reason}`);
+    }
+    return Object.assign(result, { stop: reason, problems });
+  };
+  const release = acquireLock(root, 'drive');
+  if (!release) return stop('drive-running', [problem('drive-running', 'A drive is running.',
+    'Wait for the running drive to exit; `ubp status` shows it.')]);
+  process.once('exit', release); // at exit, after the result is printed; only cli.cjs calls drive
+  const shell = async (command, log, env) => {
+    fs.mkdirSync(bin, { recursive: true });
+    fs.writeFileSync(path.join(bin, 'ubp'), `#!/bin/sh\nexec ${base.UBP} "$@"\n`, { mode: 0o755 });
+    const fd = fs.openSync(path.join(directory, log), 'w');
+    let exit;
+    try { exit = await runShell(root, { run: command, timeout: opts['timeout-sec'] }, fd,
+      { ...base, ...env }, 5000); } finally { fs.closeSync(fd); }
+    if (exit.interrupted) throw Object.assign(new Error('Drive interrupted.'),
+      { exitCode: exit.interrupted });
+    return exit.timedOut ? 'timeout' : exit.signal ? `signal-${exit.signal}` : exit.code;
+  };
+  const check = async (selector) => {
+    const checked = await runChecks(load(root), { words: [], req: null, selector });
+    const pass = checked.result.runs.every((r) => r.outcome === 'pass' && !r.dirty);
+    record('check', selector, null, pass ? 'pass' : 'fail');
+    return checked.after;
+  };
+  const tried = new Map();
+  let writers = 0;
+  for (;;) {
+    if (!clean(root)) return stop('dirty-tree', [issue('dirty-tree', root)]);
+    project = load(root);
+    let state = status(project);
+    if (state.gate !== 'pass') {
+      if (state.gate === 'fail') return stop('plan-gate', state.problems);
+      const gated = gate(project);
+      record('gate', state.milestone, null, gated.ok ? 'pass' : 'fail', gated.problems);
+      if (!gated.ok) return stop('plan-gate', gated.problems);
+      continue;
+    }
+    const node = project.nodes.find((n) => n.id === state.next);
+    if (node) {
+      if (!node.scope?.length) return stop('scope-missing', [issue('scope-missing', node.id)]);
+      const brief = context(project, node.id, 32768);
+      if (!brief.ok) {
+        record('context', node.id, null, 'brief-over-budget', brief.problems);
+        return stop('brief-over-budget', brief.problems);
+      }
+      if (writers >= opts['max-writers']) return stop('writer-budget',
+        [issue('writer-budget', node.id)]);
+      if (state.checks.some((c) => ['stale', 'unknown'].includes(c.state))) {
+        state = await check('stale');
+        project = load(root);
+      }
+      const file = path.join(root, '.ultra/.runtime/briefs', `${node.id}.md`);
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, brief.brief);
+      const before = snapshot(root);
+      const attempt = (tried.get(node.id) ?? 0) + 1;
+      tried.set(node.id, attempt);
+      writers++;
+      const exit = await shell(opts.writer, `${node.id}-${attempt}.log`,
+        { UBP_NODE: node.id, UBP_BRIEF: file, UBP_ATTEMPT: String(attempt) });
+      const problems = await verify(project, node, before, snapshot(root), state);
+      const failure = problems[0]?.code;
+      record('writer', node.id, attempt, failure ?? 'done', problems, exit);
+      if (failure && failure !== 'node-not-done') return stop(failure, problems);
+      if (failure && attempt >= opts.attempts) return stop('attempts-exhausted', problems);
+      continue;
+    }
+    if (state.next === '检查') {
+      if ((await check('stale')).next === '检查') return stop('checks-not-green',
+        [issue('checks-not-green', state.milestone)]);
+      continue;
+    }
+    if (state.next === '里程碑门') {
+      if ((await check('all')).next !== '里程碑门') continue;
+      if (opts.reviewer) {
+        const relative = `.ultra/records/milestones/${state.milestone}-review.md`;
+        const file = path.join(root, relative);
+        let failure = readRecord(root, relative).exists ? 'review-exists' : null;
+        let exit = null;
+        if (!failure) {
+          fs.mkdirSync(path.dirname(file), { recursive: true });
+          const before = snapshot(root);
+          exit = await shell(opts.reviewer, 'review.log',
+            { UBP_MILESTONE: state.milestone, UBP_REVIEW: file });
+          const after = snapshot(root);
+          if (before.head !== after.head || touched(before, after).length || !clean(root, relative)
+              || before.settings !== after.settings || status(load(root)).next !== '里程碑门')
+            failure = 'reviewer-changed-tree';
+          else {
+            result.verdict = reviewVerdict(readRecord(root, relative).bytes, true);
+            if (!result.verdict) failure = 'review-invalid';
+          }
+        }
+        const problems = failure ? [issue(failure, relative)] : [];
+        record('reviewer', state.milestone, null, failure ?? result.verdict, problems, exit);
+        if (failure) return stop(failure, problems);
+      }
+      return stop('milestone-gate');
+    }
+    return stop(state.next === '全部完成' ? 'all-done' : 'blocked');
+  }
+}
+module.exports = { drive };

package/engine/expect-worker.cjs

@@ -0,0 +1,5 @@
+'use strict';
+
+const { parentPort, workerData } = require('node:worker_threads');
+
+parentPort.postMessage(new RegExp(workerData.expect, 'mu').test(workerData.output));