ultra-builder-pro-cli 5.0.1 → 6.0.0

package/engine/merge.cjs

@@ -0,0 +1,273 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+const { gitAsync, bindGit, mergeOptions } = require('./git-state.cjs');
+const { problem } = require('./formats.cjs');
+const { status } = require('./states.cjs');
+const { execute } = require('./checks.cjs');
+const { acquireLock } = require('./ledger.cjs');
+const { load } = require('./loading.cjs');
+const { planProblems } = require('./plan.cjs');
+const INTERRUPTS = require('./signals.cjs');
+
+const mergeGit = (root, args, options) => gitAsync(root, [...mergeOptions, ...args], options);
+const passing = (record) => record.outcome === 'pass' && !record.dirty;
+const text = (value) => value.toString('utf8').trim();
+const paths = (value) => value.toString('utf8').split('\0').filter(Boolean);
+const firstError = (error) => String(error.stderr || error.message).split('\n')
+  .find((line) => line.trim()) ?? 'Git failed';
+
+async function resolveCommit(run, root, ref) {
+  try { return text(await run(root, ['rev-parse', '--verify', `${ref}^{commit}`])); }
+  catch (error) {
+    if (error.exitCode) throw error;
+    throw new Error(`Cannot resolve commit ${ref}. Use a valid Git commit or branch.`);
+  }
+}
+
+async function ancestor(run, root, before, after) {
+  try { await run(root, ['merge-base', '--is-ancestor', before, after]); return true; }
+  catch (error) { if (error.code === 1) return false; throw error; }
+}
+
+async function mergeInto(run, root, commit, branch) {
+  try {
+    await run(root, ['merge', '--no-ff', '--no-edit', '-m',
+      `Merge ${branch} (ubp merge gate)`, commit]);
+    return [];
+  } catch (error) {
+    if (error.exitCode) throw error;
+    const conflicts = paths(await run(root, ['diff', '--name-only', '--diff-filter=U', '-z']));
+    if (!conflicts.length) throw error;
+    return conflicts;
+  }
+}
+
+function makeWritable(directory) {
+  const entry = fs.lstatSync(directory, { throwIfNoEntry: false });
+  if (!entry?.isDirectory()) return;
+  fs.chmodSync(directory, entry.mode | 0o700);
+  for (const child of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (child.isDirectory()) makeWritable(path.join(directory, child.name));
+  }
+}
+
+async function removeTree(root, directory, warnings) {
+  try { await mergeGit(root, ['worktree', 'remove', '--force', directory]); return; }
+  catch { /* A check may have made directories read-only, or left an unregistered tree. */ }
+  try {
+    makeWritable(directory);
+    fs.rmSync(directory, { recursive: true, force: true });
+  } catch (error) { warnings.push(`Could not remove ${directory}: ${error.message}`); }
+  try {
+    const registered = paths(await mergeGit(root, ['worktree', 'list', '--porcelain', '-z']))
+      .includes(`worktree ${directory}`);
+    if (registered) await mergeGit(root, ['worktree', 'remove', '--force', directory]);
+  } catch (error) { warnings.push(`Could not unregister ${directory}: ${firstError(error)}`); }
+}
+
+async function dirtyUltra(run, root) {
+  const changed = paths(await run(root, ['diff', '--name-only', '-z', '--', '.ultra']));
+  const staged = paths(await run(root,
+    ['diff', '--cached', '--name-only', '-z', 'HEAD', '--', '.ultra']));
+  const untracked = paths(await run(root,
+    ['ls-files', '--others', '--exclude-standard', '-z', '--', '.ultra']));
+  return [...new Set([...changed, ...staged, ...untracked])].filter((file) =>
+    file !== '.ultra/.runtime' && !file.startsWith('.ultra/.runtime/'));
+}
+
+async function firstBad(run, probe, root, head, branch, commits, check, greenAtHead) {
+  const reset = async () => {
+    await run(root, ['reset', '--hard', head]);
+    await run(root, ['clean', '-fdx']);
+  };
+  if (!greenAtHead) return 'not green at HEAD before the merge';
+  let left = 0;
+  let right = commits.length - 1;
+  while (left < right) {
+    const middle = Math.floor((left + right) / 2);
+    await reset();
+    const conflicts = await mergeInto(run, root, commits[middle], branch);
+    const green = !conflicts.length && passing(await probe(check));
+    if (green) left = middle + 1;
+    else right = middle;
+  }
+  const sha = commits[left];
+  const subject = text(await run(root, ['show', '-s', '--format=%s', sha]));
+  return `first bad commit ${sha} ${subject}`;
+}
+
+async function merge(project, branch, expected) {
+  if (!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/iu.test(expected)) {
+    throw new Error('--expect-head requires a full commit id (40 or 64 hex digits).');
+  }
+  const root = project.root;
+  const warnings = [];
+  const cleanupWarnings = [];
+  const refused = (code, message, hint) => ({ ok: false, merged: null,
+    problems: [problem(code, message, hint)], warnings });
+  const moved = () => refused('head-moved', 'HEAD differs from --expect-head',
+    'Review the current HEAD and retry with its full commit id.');
+  const release = acquireLock(root, 'merge');
+  if (!release) return refused('merge-busy', 'Another merge holds merge.lock',
+    'Retry after the running merge finishes.');
+  let temporary;
+  let unbind;
+  let interrupted = 0;
+  let forwarding = false;
+  const controller = new AbortController();
+  const ensureRunning = () => {
+    if (interrupted) {
+      throw Object.assign(new Error('Merge interrupted.'), { exitCode: interrupted });
+    }
+  };
+  const handlers = Object.entries(INTERRUPTS).map(([signal, exitCode]) => [signal, () => {
+    if (!forwarding) { interrupted = exitCode; controller.abort(); }
+  }]);
+  const run = async (directory, args) => {
+    ensureRunning();
+    try {
+      const result = await mergeGit(directory, args, forwarding
+        ? { detached: true } : { signal: controller.signal });
+      ensureRunning();
+      return result;
+    } catch (error) {
+      interrupted ||= INTERRUPTS[error.signal] ?? 0;
+      ensureRunning();
+      throw error;
+    }
+  };
+  for (const [signal, handler] of handlers) process.on(signal, handler);
+  try {
+    const tip = await resolveCommit(run, root, branch);
+    const head = await resolveCommit(run, root, expected);
+    const directory = path.join(root, '.ultra', '.runtime', 'merge');
+    fs.mkdirSync(directory, { recursive: true });
+    const registered = paths(await run(root, ['worktree', 'list', '--porcelain', '-z']))
+      .filter((entry) => entry.startsWith('worktree ')).map((entry) => entry.slice(9))
+      .filter((entry) => entry.startsWith(`${directory}${path.sep}`));
+    const leftovers = new Set([...registered,
+      ...fs.readdirSync(directory).map((entry) => path.join(directory, entry))]);
+    for (const entry of leftovers) {
+      await removeTree(root, entry, cleanupWarnings);
+      ensureRunning();
+    }
+    const state = status(project);
+    if (await resolveCommit(run, root, 'HEAD') !== head) return moved();
+    const dirty = await dirtyUltra(run, root);
+    if (state.dirty || dirty.length) return refused('dirty-tree',
+      dirty.length ? `Uncommitted code or .ultra files: ${dirty.join(', ')}` : 'Uncommitted code',
+      'Commit code and .ultra/ first, then retry.');
+    if (state.gate !== 'pass') return refused('plan-gate', `Plan gate is ${state.gate}`,
+      'Fix plan problems and rerun gate.');
+    if (await ancestor(run, root, tip, head)) return refused('nothing-to-merge',
+      `${branch} is already in HEAD`, 'Choose a branch with commits not yet merged.');
+    const base = text(await run(root, ['merge-base', head, tip]));
+    temporary = path.join(directory, randomUUID());
+    await run(root, ['worktree', 'add', '--detach', temporary, head]);
+    unbind = bindGit(temporary);
+    const conflicts = await mergeInto(run, temporary, tip, branch);
+    if (conflicts.length) return refused('merge-conflict',
+      `Conflicting paths: ${conflicts.join(', ')}`,
+      conflicts.some((file) => file.startsWith('.ultra/ledger/'))
+        ? 'Add .ultra/ledger/*.jsonl merge=union to .gitattributes on the main line.'
+        : 'Resolve conflicts on the branch and retry.');
+    const merged = await resolveCommit(run, temporary, 'HEAD');
+    const changes = paths(await run(root,
+      ['diff-tree', '-r', '--no-renames', '-z', head, merged, '--', ':(icase).ultra']));
+    const problems = [];
+    for (let i = 0; i < changes.length; i += 2) {
+      const [, mode, , , kind] = changes[i].split(' ');
+      const file = changes[i + 1];
+      const allowed = ['.ultra/ledger/evidence.jsonl', '.ultra/ledger/nodes.jsonl',
+        '.ultra/rulings.md'].includes(file) || file.startsWith('.ultra/records/');
+      if (!allowed || !['A', 'M'].includes(kind) || !['100644', '100755'].includes(mode)) {
+        problems.push(problem('truth-changed', `${branch} changes ${file}`,
+          'Have the planner or controller change protected files on the main line.'));
+      }
+    }
+    if (problems.length) return { ok: false, merged: null, problems, warnings };
+    const mergedProject = load(temporary);
+    const mergedProblems = planProblems(mergedProject);
+    if (mergedProblems.length) return refused('merged-gate',
+      `Merged plan problems: ${mergedProblems.map((p) => p.code).join(', ')}`,
+      'Repair plan problems on the branch and retry.');
+    const closed = project.milestones
+      .filter((m) => project.closures.some((c) => c.milestone === m.id))
+      .flatMap((m) => m.requirements);
+    const current = project.milestones.find((m) => m.id === state.milestone)?.requirements ?? [];
+    const finished = project.nodes
+      .filter((n) => mergedProject.completions.some((c) => c.node === n.id));
+    const probe = async (check) => {
+      ensureRunning();
+      const record = await execute({ ...project, root: temporary }, check);
+      ensureRunning();
+      return record;
+    };
+    const failing = [];
+    for (const check of project.checks) {
+      const record = await probe(check);
+      if (!passing(record)) failing.push({ check, record });
+    }
+    if (failing.length) {
+      const history = await run(root,
+        ['rev-list', '--first-parent', '--reverse', `${base}..${tip}`]);
+      const commits = text(history).split('\n').filter(Boolean);
+      for (const { check, record } of failing) {
+        const needed = finished.filter((n) => n.covers.some((r) => check.covers.includes(r)));
+        const fixed = Object.hasOwn(check, 'fix') || check.covers.some((r) => closed.includes(r))
+          || needed.some((n) => project.completions.some((c) => c.node === n.id));
+        const frontier = check.covers.some((r) => current.includes(r));
+        if (!fixed && !needed.length && !frontier) continue;
+        await run(temporary, ['reset', '--hard', head]);
+        await run(temporary, ['clean', '-fdx']);
+        const green = passing(await probe(check));
+        if (!fixed && !needed.length && !green) {
+          warnings.push(`${check.id} is not green after the merge and was not green before it; `
+            + 'no finished work needs it');
+          continue;
+        }
+        const bad = !fixed && needed.length && (!frontier || !green)
+          ? `the branch marks ${needed[0].id} done`
+          : await firstBad(run, probe, temporary, head, branch, commits, check, green);
+        const reason = record.dirty && record.outcome === 'pass'
+          ? 'dirty-run' : record.error_line || record.reason;
+        problems.push(problem('check-not-green',
+          `${check.id} is not green: ${reason}; ${bad}`,
+          check.fix ?? 'Repair the failing check on the branch and retry.'));
+      }
+    }
+    ensureRunning();
+    if (problems.length) return { ok: false, merged: null, problems, warnings };
+    if (await resolveCommit(run, root, 'HEAD') !== head) return moved();
+    forwarding = true;
+    try { await run(root, ['merge', '--ff-only', merged]); }
+    catch (error) {
+      if (await resolveCommit(run, root, 'HEAD') !== head) return moved();
+      return refused('fast-forward-failed', firstError(error),
+        'Restore the main tree and commit .ultra/ before retrying.');
+    }
+    return { ok: true, merged, problems: [], warnings };
+  } catch (error) {
+    interrupted ||= INTERRUPTS[error.signal] ?? 0;
+    ensureRunning();
+    throw error;
+  } finally {
+    try { if (temporary) await removeTree(root, temporary, cleanupWarnings); }
+    finally {
+      warnings.push(...cleanupWarnings);
+      unbind?.();
+      release();
+      const detach = () => {
+        for (const [signal, handler] of handlers) process.off(signal, handler);
+      };
+      // A completed fast-forward stays protected while the CLI flushes its result.
+      if (forwarding) process.once('exit', detach);
+      else detach();
+    }
+  }
+}
+
+module.exports = { merge };

package/engine/milestone.cjs

@@ -0,0 +1,89 @@
+'use strict';
+
+const path = require('node:path');
+const { hash, problem, unique, markdown, readRecord } = require('./formats.cjs');
+const { withLock, append } = require('./ledger.cjs');
+const { load } = require('./loading.cjs');
+const { status, invariantProblems } = require('./states.cjs');
+
+function reviewPath(root, requested) {
+  const relative = path.relative(root, path.resolve(root, requested));
+  if (!relative || path.isAbsolute(requested) || relative === '..'
+      || relative.startsWith(`..${path.sep}`)) {
+    throw new Error('--review must be a relative path inside the project root.');
+  }
+  return relative.split(path.sep).join('/');
+}
+
+function reviewVerdict(bytes, requireReviewer = false) {
+  const text = bytes?.toString('utf8').replace(/^\uFEFF/u, '');
+  if (!text || (requireReviewer && !text.startsWith('Reviewer: '))) return null;
+  const verdicts = [];
+  markdown(text, (line, number, outside) => {
+    if (outside && line.startsWith('Verdict:')) verdicts.push(line.trimEnd());
+  });
+  return verdicts.length === 1 && /^Verdict: (accept|revise)$/u.test(verdicts[0])
+    ? verdicts[0].slice(9) : null;
+}
+
+function readReview(root, relative, add) {
+  const { bytes } = readRecord(root, relative);
+  if (!bytes) {
+    add('review-missing', `${relative} is not a regular file`,
+      'Write the milestone review as a regular file at this path.');
+    return null;
+  }
+  if (reviewVerdict(bytes) !== 'accept') {
+    add('review-not-accepted', `${relative} does not hold exactly one accepting verdict`,
+      'Have the reviewer write exactly one Verdict: accept line after accepting the review.');
+  }
+  return { path: relative, sha256: hash(bytes) };
+}
+
+function recordClosure(project, id, opts) {
+  const milestone = project.milestones.find((m) => m.id === id);
+  if (!milestone) throw new Error(`Unknown milestone ${id}. Use an id from plan.json.`);
+  const relative = reviewPath(project.root, opts.review);
+  const state = status(project);
+  const problems = [];
+  const add = (code, message, hint) => problems.push(problem(code, message, hint));
+  if (state.gate !== 'pass') add('plan-gate', `Plan gate is ${state.gate}`,
+    'Fix plan problems and rerun gate.');
+  if (state.dirty) add('dirty-tree', 'Code tree is dirty',
+    'Commit or restore code changes before closing the milestone.');
+  const closed = new Set(project.closures.map((c) => c.milestone));
+  if (closed.has(id) || project.milestones.find((m) => !closed.has(m.id))?.id !== id) {
+    add('not-current', `${id} is already closed or is not the first open milestone`,
+      'Close milestones in plan order, once each.');
+  }
+  for (const node of state.nodes.filter((n) => n.milestone === id)) {
+    if (node.state !== 'done') add('node-not-done', `${node.id} is not done`,
+      'Complete the milestone node first.');
+  }
+  const required = unique(project.milestones.filter((m) => m.id === id || closed.has(m.id))
+    .flatMap((m) => m.requirements));
+  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.')));
+  if (milestone.journey === undefined) add('no-journey', `${id} names no journey check`,
+    'Set journey to the registered end-to-end check for this milestone.');
+  const journey = state.checks.find((c) => c.id === milestone.journey);
+  if (journey && journey.state !== 'green') {
+    add('journey-not-green', `${journey.id} is not green`,
+      'Run the journey check on clean, current code.');
+  }
+  problems.push(...invariantProblems(state));
+  const review = readReview(project.root, relative, add);
+  if (!problems.length) {
+    append(project.root, 'milestones', { v: 1, milestone: id, code: project.code,
+      reqs: Object.fromEntries(milestone.requirements.map((r) => [r, project.reqs.get(r)])),
+      journey: { check: milestone.journey, run: journey.last_run },
+      review, owner: { words: opts.owner, proxy: opts.proxy } }, true);
+  }
+  return { ok: !problems.length, milestone: id, problems };
+}
+
+const close = ({ root }, id, opts) => withLock(root, () => recordClosure(load(root), id, opts));
+
+module.exports = { close, reviewVerdict };

package/engine/plan.cjs

@@ -0,0 +1,232 @@
+'use strict';
+
+const { unique, problem, rulingProblems } = require('./formats.cjs');
+const { latest, withLock, append, approvalItem } = require('./ledger.cjs');
+const { load } = require('./loading.cjs');
+
+function requirementProblems(project, add) {
+  const { reqs, checks, milestones, nodes } = project;
+  for (const [entries, field] of [[milestones, 'requirements'], [nodes, 'covers'],
+    [checks, 'covers']]) {
+    for (const entry of entries) {
+      for (const id of entry[field]) {
+        if (!reqs.has(id)) add('unknown-requirement', `${entry.id} names unknown requirement ${id}`,
+          'Add the requirement to spec.md or correct the reference.');
+      }
+    }
+  }
+  for (const id of reqs.keys()) {
+    const owners = milestones.filter((m) => m.requirements.includes(id));
+    if (!owners.length) add('unplanned-requirement', `${id} has no milestone`,
+      'Assign the requirement to a milestone.');
+    if (owners.length > 1) add('requirement-in-multiple-milestones',
+      `${id} belongs to multiple milestones`, 'Keep the requirement in exactly one milestone.');
+  }
+  if (!milestones.length) add('empty-plan', 'The plan has no milestones', 'Add a milestone.');
+  for (const m of milestones) {
+    const ownNodes = nodes.filter((n) => n.milestone === m.id);
+    if (!m.requirements.length || !ownNodes.length) add('empty-milestone',
+      `${m.id} has no requirements or nodes`, 'Add requirements and nodes or remove the milestone');
+    for (const id of unique(m.requirements)) {
+      if (!checks.some((c) => c.covers.includes(id))) add('uncovered-requirement',
+        `${id} has no check`, 'Register a check covering this requirement in checks.json.');
+      if (!ownNodes.some((n) => n.covers.includes(id))) add('requirement-without-node',
+        `${id} has no node in ${m.id}`, 'Add a node covering this requirement to its milestone.');
+    }
+  }
+}
+
+function nodeProblems(project, add) {
+  const ms = new Map(project.milestones.map((m, i) => [m.id, { ...m, order: i }]));
+  const ns = new Map(project.nodes.map((n) => [n.id, n]));
+  for (const n of project.nodes) {
+    const m = ms.get(n.milestone);
+    if (!m) add('unknown-milestone', `${n.id} names unknown milestone ${n.milestone}`,
+      'Correct the milestone reference or add the milestone.');
+    if (!n.covers.length && n.kind !== 'cleanup') add('empty-node', `${n.id} covers no requirement`,
+      'Link the node to a requirement or remove it.');
+    for (const id of n.covers) {
+      if (m && project.reqs.has(id) && !m.requirements.includes(id)) {
+        add('node-outside-milestone', `${n.id} covers ${id} outside ${m.id}`,
+          'Move the node or correct its requirement links.');
+      }
+    }
+    for (const dep of n.depends) {
+      const dependency = ns.get(dep);
+      if (!dependency) add('unknown-dependency', `${n.id} depends on unknown node ${dep}`,
+        'Add the dependency node or correct the reference.');
+      else if (m && ms.has(dependency.milestone) && ms.get(dependency.milestone).order > m.order) {
+        add('dependency-on-later-milestone', `${n.id} depends on later milestone node ${dep}`,
+          'Move the dependency to this or an earlier milestone.');
+      }
+    }
+  }
+  const visited = new Set();
+  const active = new Set();
+  const visit = (id) => {
+    if (active.has(id)) {
+      add('dependency-cycle', `Dependency cycle at ${id}`,
+        'Remove a dependency edge to break the cycle.');
+      return;
+    }
+    if (visited.has(id) || !ns.has(id)) return;
+    visited.add(id);
+    active.add(id);
+    ns.get(id).depends.forEach(visit);
+    active.delete(id);
+  };
+  project.nodes.forEach((n) => visit(n.id));
+}
+
+function planProblems(project) {
+  const problems = [];
+  const add = (code, message, hint) => problems.push(problem(code, message, hint));
+  requirementProblems(project, add);
+  nodeProblems(project, add);
+  for (const m of project.milestones) {
+    if (m.journey === undefined) continue;
+    const check = project.checks.find((c) => c.id === m.journey);
+    if (!check) add('unknown-journey', `${m.id} names unknown journey ${m.journey}`,
+      'Register the journey check in checks.json or correct its id.');
+    else if (!check.covers.some((id) => m.requirements.includes(id))) {
+      add('journey-outside-milestone', `${m.journey} covers no requirement of ${m.id}`,
+        'Choose a journey check covering a requirement of this milestone.');
+    }
+  }
+  if (project.cleanup_every !== undefined) {
+    for (const m of project.milestones) {
+      const nodes = project.nodes.filter((n) => n.milestone === m.id);
+      let consecutive = 0;
+      const tooMany = nodes.some((n) => {
+        consecutive = n.kind === 'cleanup' ? 0 : consecutive + 1;
+        return consecutive > project.cleanup_every;
+      });
+      if (tooMany || nodes.at(-1)?.kind !== 'cleanup') {
+        add('cleanup-missing', `${m.id} needs cleanup every ${project.cleanup_every} nodes`,
+          'End the milestone with cleanup and insert cleanup nodes at the required cadence.');
+      }
+    }
+  }
+  reductionProblems(project, add);
+  return problems.concat(rulingProblems(project.rulings));
+}
+
+function snapshot(project, milestone) {
+  const requirements = unique(milestone.requirements).filter((id) => project.reqs.has(id)).sort();
+  return {
+    shared: project.shared,
+    requirements: Object.fromEntries(requirements.map((id) => [id, project.reqs.get(id)])),
+    nodes: project.nodes.filter((n) => n.milestone === milestone.id).map((n) => n.id).sort(),
+    checks: Object.fromEntries(project.checks.filter((check) =>
+      check.covers.some((id) => requirements.includes(id))).map((check) =>
+      [check.id, { fp: check.fp, covers: unique(check.covers.filter((id) =>
+        requirements.includes(id))).sort() }])),
+  };
+}
+
+function sameSnapshot(current, previous) {
+  if (!previous || previous.type === 'removed') return false;
+  return Object.values(snapshotDiff(current, previous))
+    .every((value) => Array.isArray(value) && value.length === 0);
+}
+
+const has = (object, id) => Object.hasOwn(object, id);
+
+function snapshotDiff(now, before) {
+  return {
+    added: Object.keys(now.requirements).filter((id) => !has(before.requirements, id)).sort(),
+    removed: Object.keys(before.requirements).filter((id) => !has(now.requirements, id)).sort(),
+    modified: Object.keys(now.requirements).filter((id) => has(before.requirements, id)
+      && now.requirements[id] !== before.requirements[id]).sort(),
+    nodes_added: now.nodes.filter((id) => !before.nodes.includes(id)).sort(),
+    nodes_removed: before.nodes.filter((id) => !now.nodes.includes(id)).sort(),
+    checks_added: Object.keys(now.checks).filter((id) => !has(before.checks, id)).sort(),
+    checks_removed: Object.keys(before.checks).filter((id) => !has(now.checks, id)).sort(),
+    checks_modified: Object.keys(now.checks).filter((id) => has(before.checks, id)
+      && (now.checks[id].fp !== before.checks[id].fp
+        || JSON.stringify(now.checks[id].covers) !== JSON.stringify(before.checks[id].covers)))
+      .sort(),
+    ...(now.shared !== before.shared ? { shared: true } : {}),
+  };
+}
+
+function emptySnapshot(project) {
+  return { shared: project.shared, requirements: {}, nodes: [], checks: {} };
+}
+
+function reductionProblems(project, add) {
+  for (const id of unique(project.plans.map((p) => p.milestone))) {
+    const before = latest(project.plans, 'milestone', id);
+    if (before.type === 'removed') continue;
+    const milestone = project.milestones.find((m) => m.id === id);
+    const now = milestone ? snapshot(project, milestone) : emptySnapshot(project);
+    const removed = Object.keys(before.requirements)
+      .filter((req) => !Object.hasOwn(now.requirements, req)).sort();
+    const checks = Object.keys(before.checks).filter((check) =>
+      !Object.hasOwn(now.checks, check) || before.checks[check].covers.some((req) =>
+        Object.hasOwn(now.requirements, req) && !now.checks[check].covers.includes(req))).sort();
+    // An approval answers the plan as it stood: one given before a later plan change or a
+    // closure of the milestone no longer counts.
+    const closed = latest(project.closures, 'milestone', id);
+    const floor = closed && closed.at > before.at ? closed.at : before.at;
+    for (const item of unique([...removed, ...checks]).map((entry) => `${id}/${entry}`)) {
+      if (!project.approvals.some((a) => a.at > floor && a.items.includes(item))) {
+        add('reduction-unapproved', `Reduction ${item} needs the Owner's approval`,
+          `Record approval with ubp approve ${item} --owner "<words>".`);
+      }
+    }
+  }
+}
+
+function pendingPlans(project) {
+  const pending = [];
+  const add = (id, now, before, type) => {
+    const record = { v: 1, type, milestone: id, at: new Date().toISOString(), ...now };
+    if (before) record.diff = snapshotDiff(now, before);
+    pending.push(record);
+  };
+  for (const m of project.milestones) {
+    const now = snapshot(project, m);
+    const before = latest(project.plans, 'milestone', m.id);
+    if (!sameSnapshot(now, before)) add(m.id, now, before, before ? 'change' : 'baseline');
+  }
+  for (const id of unique(project.plans.map((p) => p.milestone))) {
+    const before = latest(project.plans, 'milestone', id);
+    if (before.type !== 'removed' && !project.milestones.some((m) => m.id === id)) {
+      add(id, emptySnapshot(project), before, 'removed');
+    }
+  }
+  return pending;
+}
+
+function gate(project) {
+  return withLock(project.root, () => {
+    const current = load(project.root);
+    const problems = planProblems(current);
+    const records = problems.length ? [] : pendingPlans(current);
+    for (const record of records) append(current.root, 'plan-log', record, true);
+    return { ok: !problems.length, problems,
+      recorded: records.map(({ milestone, type }) => ({ milestone, type })) };
+  });
+}
+
+function approve(project, items, opts) {
+  return withLock(project.root, () => {
+    const current = load(project.root);
+    const sorted = unique(items).sort();
+    for (const item of sorted) {
+      const [milestone, id] = item.split('/');
+      const before = latest(current.plans, 'milestone', milestone);
+      if (!approvalItem(item) || !before || before.type === 'removed'
+          || !(Object.hasOwn(before.requirements, id) || Object.hasOwn(before.checks, id))) {
+        throw new Error(`Invalid approval item ${item}. Use <milestone>/<requirement or check>`
+          + ' from the milestone\'s latest plan-log snapshot.');
+      }
+    }
+    append(current.root, 'approvals', { v: 1, items: sorted,
+      owner: { words: opts.owner, proxy: opts.proxy } }, true);
+    return { ok: true, items: sorted };
+  });
+}
+
+module.exports = { planProblems, pendingPlans, gate, approve };

package/engine/project.cjs

@@ -0,0 +1,5 @@
+'use strict';
+module.exports = {
+  load: require('./loading.cjs').load, status: require('./states.cjs').status,
+  gate: require('./plan.cjs').gate, complete: require('./completion.cjs').complete,
+};

package/engine/signals.cjs

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 };