gcf-aif-ext 0.4.0 → 0.5.0

package/lib/design-check.js

@@ -496,6 +496,10 @@ function ledgerIssues(ledger) {
       out.push({ check: 'M12', severity: 'block', file, line: 1, id, message });
     if (live.length > 1)
       add(`${id} lives in ${live.length} places: ${live.map((p) => p.file).join(', ')}`);
+    // An id ends once; two ends (a merge of branches that each ended it) leave its dependents
+    // counting it as played or dead depending on which line wins.
+    if (terminal.length > 1)
+      add(`${id} ended ${terminal.join(' and ')}: keep one line in history.md or graveyard.md`);
     if (live.length && terminal.length) {
       add(
         `${id} is ${terminal.join(' and ')} already: ids are never reused — give the new one ` +
@@ -508,6 +512,49 @@ function ledgerIssues(ledger) {
   return out;
 }
 
+/**
+ * M2 over `depends:` of units and items together: a cycle never gets played — every id in it
+ * waits for the next one. Each cycle is reported once, from the id DFS meets it at.
+ */
+export function dependsCycles(ledger) {
+  /** @type {Map<string, string[]>} */
+  const graph = new Map();
+  for (const u of ledger.design.flatMap((d) => d.units)) {
+    const list = listOf(u.header.depends ?? '');
+    graph.set(u.id, Array.isArray(list) ? list : []);
+  }
+
+  for (const c of ledger.items) graph.set(String(c.data.id), c.data.depends ?? []);
+  /** @type {Issue[]} */
+  const out = [];
+  const state = new Map(); // id → 'open' while on the DFS path, 'done' after
+  const visit = (id, trail) => {
+    if (state.get(id) === 'done') return;
+    if (state.get(id) === 'open') {
+      const cycle = [...trail.slice(trail.indexOf(id)), id];
+      const file = ledger.where(id).live[0]?.file ?? 'design';
+      out.push({
+        check: 'M2',
+        severity: 'block',
+        file,
+        line: 1,
+        id,
+        message: `depends cycle ${cycle.join(' -> ')}: none of them can be played first`,
+      });
+
+      return;
+    }
+
+    state.set(id, 'open');
+    for (const d of graph.get(id) ?? []) visit(d, [...trail, id]);
+    state.set(id, 'done');
+  };
+
+  for (const id of graph.keys()) visit(id, []);
+
+  return out;
+}
+
 /** M14: backlog.md is the order of the units in design/, each exactly once. */
 function backlogIssues(text, unitIds) {
   /** @type {Issue[]} */
@@ -577,6 +624,31 @@ function pillarReport(units, ctx) {
   };
 }
 
+/** A unit's line in the report: its TBD count and whether it is ready to take. */
+function unitSummary(u, own, values, ctx) {
+  const pillars = listOf(u.header.pillars ?? '');
+  // Once PILLARS.md exists, a mechanic or resource says which pillar it serves before work:
+  // `take` would turn the TBD into an empty list and the unit would serve nothing silently.
+  const pillarsTbd =
+    pillars === 'TBD' && ctx.pillarIds.length && CARD_TYPES.includes(u.header.type) ? 1 : 0;
+  const tbd = values.filter((v) => isTbd(v.value)).length + pillarsTbd;
+  const blockedBy = ctx.questions.d1.get(u.id) ?? [];
+
+  return {
+    id: u.id,
+    file: u.file,
+    system: u.system,
+    type: u.header.type ?? null,
+    milestone: u.header.milestone ?? 'TBD',
+    pillars,
+    pillars_owed: Boolean(pillarsTbd),
+    values: values.length,
+    tbd,
+    blocked_by: blockedBy,
+    ready: tbd === 0 && !blockedBy.length && !own.some((i) => i.severity === 'block'),
+  };
+}
+
 /**
  * Run every design check over a project. `blocking` counts the issues that refuse a commit;
  * the rest of the report (completeness, readiness, pillars) is a reading, not a gate.
@@ -591,28 +663,14 @@ export async function designCheck(projectDir) {
   for (const u of ledger.design.flatMap((d) => d.units)) {
     const { issues: own, values } = await checkUnit(u, ctx, ledger);
     issues.push(...own);
-    const tbd = values.filter((v) => isTbd(v.value)).length;
-    const blockedBy = ctx.questions.d1.get(u.id) ?? [];
-    const pillars = listOf(u.header.pillars ?? '');
-    units.push({
-      id: u.id,
-      file: u.file,
-      system: u.system,
-      type: u.header.type ?? null,
-      milestone: u.header.milestone ?? 'TBD',
-      pillars,
-      values: values.length,
-      tbd,
-      blocked_by: blockedBy,
-      ready: tbd === 0 && !blockedBy.length && !own.some((i) => i.severity === 'block'),
-    });
+    units.push(unitSummary(u, own, values, ctx));
   }
 
   for (const c of ledger.items) issues.push(...(await checkItem(c, ctx, ledger)));
   issues.push(...(await unplayedIssues(root, ledger)));
   for (const doc of ['game', 'glossary']) issues.push(...(await checkDoc(root, doc, ctx)));
   issues.push(...preambleIssues(ledger.design));
-  issues.push(...ledgerIssues(ledger), ...questionIssues(ctx, ledger));
+  issues.push(...ledgerIssues(ledger), ...dependsCycles(ledger), ...questionIssues(ctx, ledger));
   if (ledger.design.length) {
     const backlog = await readIf(path.join(root, 'backlog.md'));
     issues.push(...backlogIssues(backlog, new Set(units.map((u) => u.id))));

package/lib/gate.js

@@ -0,0 +1,106 @@
+// The GCF checks of the pre-commit gate (GCF-PRD §13.1) over the working tree, cheap ones first.
+// The gate refuses on the first problem; `gcf verify` reports them all as the GCF part of the DoD.
+import path from 'node:path';
+import { listSystems, legacyCards, readConfig } from './gcf-paths.js';
+import { phasesOf } from './phase.js';
+import { validateItem, validateUntil } from './validate-item.js';
+import { stemMatches } from './id.js';
+import { lint } from './linter.js';
+import { buildLedger } from './ledger.js';
+import { designCheck } from './design-check.js';
+import { matchesFrozen } from './work-ops.js';
+import { checkLive } from './live.js';
+
+/** Problems of form: legacy cards, item frontmatter and filenames, `until` grammar. */
+function formProblems(root, ledger, systems) {
+  const problems = [];
+  // Schema 2 cards are not read by 0.4: left in place they would silently stop being checked.
+  const legacy = legacyCards(root);
+  if (legacy.length)
+    problems.push(
+      `gcf/cards/ holds schema 2 card(s) (${legacy.join(', ')}): GCF 0.4 keeps work in ` +
+        'gcf/work/<id>.md with schema 3 and does not migrate — put each card back into ' +
+        'gcf/design/ as a unit and run ai-factory gcf take, then delete gcf/cards/',
+    );
+
+  // 1-2: frontmatter validity, storable statuses, until grammar, filename invariant.
+  for (const c of ledger.items) {
+    const errors = [
+      ...validateItem(c.data),
+      ...validateUntil(c.body),
+      ...(stemMatches(c.file, c.data.id) ? [] : [`filename must be ${c.data.id}.md`]),
+    ];
+    if (errors.length) problems.push(`work/${c.name}: ${errors[0]}`);
+  }
+
+  for (const s of systems) {
+    const errors = validateUntil(s.body);
+    if (errors.length) problems.push(`systems/${s.name}: ${errors[0]}`);
+  }
+
+  return problems;
+}
+
+/** The `phases:` of config.yml, and the LIVE.md phase among them (Methodology §10). */
+async function phaseProblems(root, phase) {
+  let names;
+  try {
+    names = phasesOf(await readConfig(root)).map((p) => p.name);
+  } catch {
+    // A broken config is for the command that reads it to refuse: a kill must still commit.
+    return [];
+  }
+
+  return phase && !names.includes(phase)
+    ? [`LIVE.md: phase ${phase} is not a phase of the project (${names.join(', ')})`]
+    : [];
+}
+
+/** Every problem the gate refuses a commit for, one line each, and the ledger it read. */
+export async function gateProblems(projectDir) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const ledger = await buildLedger(projectDir);
+  const systems = await listSystems(root);
+  const problems = formProblems(root, ledger, systems);
+  // The checks below read these files and trust their form.
+  if (problems.length) return { problems, ledger };
+
+  // An unplayed item's body and live: are the source of its systems/ lines and its capability
+  // (Methodology §5.4): edited after its close, a tune or a kill would take the wrong ones out.
+  for (const c of ledger.items.filter((x) => x.data.status === 'unplayed')) {
+    if (!matchesFrozen(c))
+      problems.push(
+        `work/${c.name}: an unplayed item's body and live: are frozen — restore them, tune it, ` +
+          'then edit',
+      );
+  }
+
+  // Design model and item bodies: every finding of severity `block` refuses the commit.
+  for (const i of (await designCheck(projectDir)).issues.filter((x) => x.severity === 'block'))
+    problems.push(`${i.file}:${i.line}: ${i.check}: ${i.message}`);
+
+  // Dependencies are held by the moves, not here (Methodology §4.1): `submit` refuses an unplayed
+  // one, `close` and `keep` a not-yet-kept one. A gate check would refuse the tune or the kill of
+  // a dependency whose dependent is already waiting for its verdict — a legal move, blocked.
+
+  // LIVE.md form: a malformed record would hide from every reader of the snapshot. A broken ref
+  // into gcf/ is this commit's own doing (a move deleted the file); one into the code is not
+  // refused — a code commit outside gcf/ may have moved it and the gate never saw that.
+  const live = await checkLive(projectDir);
+  const form = [
+    ...live.problems,
+    ...live.issues.filter((i) => !live.problems.includes(i) && /summary|twice|refs gcf\//.test(i)),
+  ];
+  problems.push(...form.map((f) => `LIVE.md: ${f}`));
+  // A phase the project does not name would refuse every later item new and take.
+  problems.push(...(await phaseProblems(root, live.phase)));
+
+  // 5: П2 linter over systems docs.
+  for (const s of systems) {
+    const { issues } = lint(s.body);
+    if (issues.length)
+      problems.push(`systems/${s.name}:${issues[0].line}: ${issues[0].rule}: ${issues[0].text}`);
+  }
+
+  return { problems, ledger };
+}

package/lib/integrate.js

@@ -0,0 +1,322 @@
+// The integrator (Methodology §7): an item runs in its worktree on branch `work/<id>`, and the
+// branch is ready once its tip carries the trailer `GCF-Verified: <id>` — readiness lives in git,
+// not in memory. `integrate` merges such a branch into main and records the item's move there,
+// under the main lock; without an id it picks up every verified branch a dead run left behind.
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { buildLedger } from './ledger.js';
+import { parse } from './frontmatter.js';
+import { withMainLock } from './main-lock.js';
+import { verifyItem, deltaProblems } from './verify.js';
+import { submitItem, closeItem, blockItem } from './work-ops.js';
+import { isValidId } from './id.js';
+
+const TRAILER = 'GCF-Verified';
+export const branchOf = (id) => `work/${id}`;
+export const worktreeOf = (projectDir, id) =>
+  path.join(path.resolve(projectDir), '.gcf-session', 'worktrees', id);
+
+function git(cwd, args, { check = true } = {}) {
+  const res = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  const err = (res.stderr || res.stdout || '').trim();
+  if (check && res.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${err}`);
+
+  return { ok: res.status === 0, out: (res.stdout ?? '').trim(), err };
+}
+
+/** `.gcf-session/` stays out of `git status` without a tracked .gitignore change. */
+async function excludeSession(projectDir) {
+  const common = path.resolve(projectDir, git(projectDir, ['rev-parse', '--git-common-dir']).out);
+  const file = path.join(common, 'info', 'exclude');
+  const text = existsSync(file) ? await readFile(file, 'utf8') : '';
+  if (text.split(/\r?\n/).includes('/.gcf-session/')) return;
+  await mkdir(path.dirname(file), { recursive: true });
+  await appendFile(file, `${text && !text.endsWith('\n') ? '\n' : ''}/.gcf-session/\n`);
+}
+
+const METRICS = ':(exclude)gcf/.metrics';
+
+/**
+ * Bring the main checkout's branch into a resumed worktree: the operator's answer from
+ * `unblock`, a newer LIVE.md and the other items' states live on main only.
+ */
+function syncWithMain(projectDir, dir) {
+  const main = git(projectDir, ['rev-parse', '--abbrev-ref', 'HEAD']).out;
+  if (main === 'HEAD' || main.startsWith('work/')) return {};
+  const res = git(dir, ['merge', '--no-edit', '-m', `gcf(sync): ${main}`, main], { check: false });
+  if (res.ok) return {};
+  if (git(dir, ['rev-parse', '-q', '--verify', 'MERGE_HEAD'], { check: false }).ok)
+    git(dir, ['merge', '--abort'], { check: false });
+
+  return { sync: `${main} does not merge into the worktree: ${res.err}` };
+}
+
+/**
+ * A worktree for a ready item: `.gcf-session/worktrees/<id>` on branch `work/<id>` from HEAD.
+ * An existing one is resumed with main merged in; `sync` names a merge that did not go.
+ */
+export async function addWorktree(projectDir, id) {
+  if (!isValidId(id)) throw new Error(`${id} is not an item id`);
+  const item = (await buildLedger(projectDir)).item(id);
+  if (!item) throw new Error(`${id} is not a work item of gcf/work/`);
+  const dir = worktreeOf(projectDir, id);
+  if (existsSync(dir))
+    return {
+      id,
+      path: dir,
+      branch: branchOf(id),
+      created: false,
+      ...syncWithMain(projectDir, dir),
+    };
+  if (item.data.status !== 'ready')
+    throw new Error(`${id} is ${item.data.status}: a run starts on a ready item`);
+  await excludeSession(projectDir);
+  // A worktree folder deleted by hand leaves its registration behind: add would refuse.
+  git(projectDir, ['worktree', 'prune']);
+  const ref = `refs/heads/${branchOf(id)}`;
+  const exists = git(projectDir, ['rev-parse', '--verify', '--quiet', ref], { check: false }).ok;
+  const from = exists ? [dir, branchOf(id)] : ['-b', branchOf(id), dir, 'HEAD'];
+  git(projectDir, ['worktree', 'add', ...from]);
+
+  return { id, path: dir, branch: branchOf(id), created: true };
+}
+
+/**
+ * `verify --mark`: the DoD is green on branch `work/<id>` with everything committed — an empty
+ * commit carrying the trailer says so in git. Refuses on red checks or uncommitted work.
+ */
+export async function markVerified(worktreeDir, id, opts = {}) {
+  const branch = git(worktreeDir, ['rev-parse', '--abbrev-ref', 'HEAD']).out;
+  if (branch !== branchOf(id))
+    throw new Error(`${id} is verified on its branch ${branchOf(id)}, this is ${branch}`);
+  if (git(worktreeDir, ['status', '--porcelain', '--', '.', METRICS]).out)
+    throw new Error('commit the work first: the trailer marks a commit, not a working tree');
+  const r = await verifyItem(worktreeDir, id, opts);
+  if (!r.ok) return { ...r, marked: false };
+  const msg = ['-m', `gcf(verified): ${id}`, '-m', `${TRAILER}: ${id}`];
+  git(worktreeDir, ['commit', '--allow-empty', ...msg]);
+
+  return { ...r, marked: true };
+}
+
+function isVerified(projectDir, id) {
+  const format = `--format=%(trailers:key=${TRAILER},valueonly)`;
+  const trailers = git(projectDir, ['log', '-1', format, branchOf(id)], { check: false }).out;
+
+  return trailers.split('\n').some((v) => v.trim() === id);
+}
+
+/** The ids of branches `work/<id>` whose tip carries `GCF-Verified: <id>`. */
+export function verifiedBranches(projectDir) {
+  const refs = git(projectDir, ['for-each-ref', '--format=%(refname:short)', 'refs/heads/work/']);
+
+  return refs.out
+    .split('\n')
+    .filter(Boolean)
+    .map((b) => b.slice('work/'.length))
+    .filter((id) => isVerified(projectDir, id));
+}
+
+/**
+ * Take the worktree and the branch away once the branch is in main (or tagged, for a spike).
+ * Without --force: work left uncommitted in the worktree stops the removal and is named.
+ */
+function cleanUp(projectDir, id, { force = false } = {}) {
+  const notes = [];
+  const dir = worktreeOf(projectDir, id);
+  if (existsSync(dir)) {
+    // The run's own audit and context lines are no work to keep.
+    git(dir, ['checkout', '--', 'gcf/.metrics'], { check: false });
+    git(dir, ['clean', '-fdq', '--', 'gcf/.metrics'], { check: false });
+    const res = git(projectDir, ['worktree', 'remove', dir], { check: false });
+    if (!res.ok) notes.push(`worktree kept: ${res.err}`);
+  }
+
+  git(projectDir, ['worktree', 'prune'], { check: false });
+  const res = git(projectDir, ['branch', force ? '-D' : '-d', branchOf(id)], { check: false });
+  if (!res.ok) notes.push(`branch kept: ${res.err}`);
+
+  return notes.length ? { cleanup: notes } : {};
+}
+
+/** The item file at `rev` without its `live:`: what a branch must leave as main has it. */
+function itemBeyondLive(projectDir, rev, id) {
+  const res = git(projectDir, ['show', `${rev}:./gcf/work/${id}.md`], { check: false });
+  if (!res.ok) return null;
+  const { data, body } = parse(res.out);
+  const { live, ...rest } = data;
+
+  return JSON.stringify([rest, String(body).trim()]);
+}
+
+/**
+ * The branch may change in gcf/ only its own item's `live:` (Methodology §5.2): status, other
+ * items and the config move on main through their commands.
+ */
+function foreignGcfEdits(projectDir, id) {
+  const own = `gcf/work/${id}.md`;
+  const range = `HEAD...${branchOf(id)}`;
+  const changed = git(projectDir, ['diff', '--name-only', range, '--', 'gcf/'])
+    .out.split('\n')
+    .filter((f) => f && f !== own && f !== 'gcf/INDEX.md' && !f.startsWith('gcf/.metrics/'));
+  const base = git(projectDir, ['merge-base', 'HEAD', branchOf(id)]).out;
+  if (itemBeyondLive(projectDir, base, id) !== itemBeyondLive(projectDir, branchOf(id), id))
+    changed.push(`${own} beyond its live:`);
+
+  return changed;
+}
+
+/** Whether the item's move was recorded after its branch merged: a crash may fall in between. */
+function movedSinceMerge(projectDir, id) {
+  const grep = ['--fixed-strings', `--grep=gcf(integrate): ${id}`];
+  const merge = git(projectDir, ['log', '-1', '--format=%H', ...grep]).out;
+  if (!merge) return false;
+  const after = git(projectDir, ['log', '--format=%s', `${merge}..HEAD`]).out.split('\n');
+  const move = new RegExp(`^gcf\\((submit|close|block)\\): ${id}( |$)`);
+
+  return after.some((s) => move.test(s));
+}
+
+/**
+ * The move a merged item ends its run with. Its delta is checked against main first — the
+ * worktree's LIVE.md may be behind. A move the item refuses blocks it with the reason; when even
+ * the block fails, the error goes up and the next integrate records the move again.
+ */
+async function recordMove(projectDir, item) {
+  const { id, gate } = item.data;
+  const stale = await deltaProblems(projectDir, item);
+  try {
+    if (stale.length) throw new Error(stale.join('; '));
+    if (gate === 'auto') return { move: 'close', ...(await closeItem(projectDir, id)) };
+
+    return { move: 'submit', ...(await submitItem(projectDir, id)) };
+  } catch (e) {
+    const reason = `integrate: ${e.message}`;
+
+    return { move: 'block', reason, ...(await blockItem(projectDir, id, { reason })) };
+  }
+}
+
+/** A spike's code never reaches main (§5.5): only its plan does, and a tag keeps the branch. */
+async function integrateSpike(projectDir, item) {
+  const id = String(item.data.id);
+  const plan = item.data.plan ?? `.ai-factory/plans/${id}.md`;
+  if (git(projectDir, ['cat-file', '-e', `${branchOf(id)}:./${plan}`], { check: false }).ok) {
+    git(projectDir, ['checkout', branchOf(id), '--', plan]);
+    // A plan main already holds as it is (a rerun after a crash) has nothing to commit.
+    if (!git(projectDir, ['diff', '--cached', '--quiet', '--', plan], { check: false }).ok)
+      git(projectDir, ['commit', '-m', `gcf(integrate): ${id} plan`, '--only', '--', plan]);
+  }
+
+  git(projectDir, ['tag', '-f', `spike/${id}`, branchOf(id)]);
+  const moved = await recordMove(projectDir, item);
+
+  return { ...moved, ...cleanUp(projectDir, id, { force: true }) };
+}
+
+/** Merge the branch; null when it went in, else the conflict or the refusal. */
+function mergeBranch(projectDir, id) {
+  const args = ['merge', '--no-ff', '--no-edit', '-m', `gcf(integrate): ${id}`, branchOf(id)];
+  const merge = git(projectDir, args, { check: false });
+  if (merge.ok) return null;
+  const head = ['rev-parse', '-q', '--verify', 'MERGE_HEAD'];
+  if (!git(projectDir, head, { check: false }).ok)
+    return { error: `merge of ${branchOf(id)} refused: ${merge.err}` };
+  git(projectDir, ['merge', '--abort'], { check: false });
+
+  return {
+    conflict:
+      `${branchOf(id)} conflicts with main: in its worktree merge main, resolve, run ` +
+      `gcf verify ${id} --mark again, then gcf integrate ${id}`,
+  };
+}
+
+/** A branch main already holds: its move may still be owed, after a crash in between. */
+async function integrateMerged(projectDir, id, item) {
+  if (!item || item.data.status !== 'ready' || movedSinceMerge(projectDir, id))
+    return { id, skipped: `${branchOf(id)} is in main already`, ...cleanUp(projectDir, id) };
+
+  return { id, ...(await recordMove(projectDir, item)), ...cleanUp(projectDir, id) };
+}
+
+async function integrateOne(projectDir, id) {
+  const item = (await buildLedger(projectDir)).item(id);
+  const ancestor = ['merge-base', '--is-ancestor', branchOf(id), 'HEAD'];
+  if (git(projectDir, ancestor, { check: false }).ok) return integrateMerged(projectDir, id, item);
+  if (!item || item.data.status !== 'ready')
+    return { id, skipped: `${id} is ${item ? item.data.status : 'not a work item'} on main` };
+  if (item.data.type === 'spike') return { id, ...(await integrateSpike(projectDir, item)) };
+  const foreign = foreignGcfEdits(projectDir, id);
+  if (foreign.length)
+    return {
+      id,
+      error:
+        `${branchOf(id)} changes gcf/ beyond the item's live: (${foreign.join(', ')}) — take ` +
+        'those edits out of the branch: they reach main through their commands',
+    };
+  const failed = mergeBranch(projectDir, id);
+  if (failed) return { id, ...failed };
+  const moved = await recordMove(projectDir, (await buildLedger(projectDir)).item(id));
+
+  return { id, ...moved, ...cleanUp(projectDir, id) };
+}
+
+/**
+ * Audit and context append to tracked logs in gcf/.metrics on every call: commit them, or a
+ * branch bringing its own lines could not merge over them. Union merge joins the lines.
+ */
+function commitMetrics(projectDir) {
+  const dirty = git(projectDir, [
+    'status',
+    '--porcelain',
+    '--untracked-files=no',
+    '--',
+    'gcf/.metrics',
+  ]);
+  if (dirty.out)
+    git(projectDir, [
+      'commit',
+      '-q',
+      '--no-verify',
+      '-m',
+      'gcf(metrics): run logs',
+      '--only',
+      '--',
+      'gcf/.metrics',
+    ]);
+}
+
+/**
+ * Merge verified branches into main and record each item's move: gate auto closes, the others
+ * submit; a move the item refuses blocks it with the reason. `ids` empty: every verified branch.
+ * One item's failure is reported and the others still go.
+ */
+export async function integrate(projectDir, ids = []) {
+  const branch = git(projectDir, ['rev-parse', '--abbrev-ref', 'HEAD']).out;
+  if (branch === 'HEAD' || branch.startsWith('work/'))
+    throw new Error(`integrate runs in the main checkout on its branch, not on ${branch}`);
+
+  return withMainLock(projectDir, async () => {
+    if (git(projectDir, ['status', '--porcelain', '--untracked-files=no', '--', '.', METRICS]).out)
+      throw new Error('main has uncommitted changes: commit or stash them before integrating');
+    commitMetrics(projectDir);
+    for (const id of ids)
+      if (!isVerified(projectDir, id))
+        throw new Error(
+          `${branchOf(id)} carries no ${TRAILER}: ${id} trailer — run gcf verify ${id} --mark ` +
+            'in its worktree once the DoD is green',
+        );
+    const results = [];
+    for (const id of ids.length ? ids : verifiedBranches(projectDir)) {
+      try {
+        results.push(await integrateOne(projectDir, id));
+      } catch (e) {
+        results.push({ id, error: e.message });
+      }
+    }
+
+    return results;
+  });
+}