gcf-aif-ext 0.4.0 → 0.5.0

package/lib/live.js

@@ -9,53 +9,94 @@ import { atomicWrite } from './safe-path.js';
 import { listItems } from './gcf-paths.js';
 import { summaryProblem } from './validate-item.js';
 
-const SECTIONS = { capabilities: 'capabilities', 'known-issues': 'knownIssues' };
+const SECTIONS = {
+  release: 'release',
+  capabilities: 'capabilities',
+  'known-issues': 'knownIssues',
+};
+const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const NONE = {
   capabilities: '- none: no capability recorded yet',
   'known-issues': '- none: no known issue',
 };
 
 /** @typedef {{id: string, summary: string, refs?: string}} LiveRecord */
+/** @typedef {{version: string, channel?: string, date?: string, phase?: string}} LiveRelease */
+
+/**
+ * A line of the one-record `release:` block (Methodology §13): the last release, which the end
+ * of the next release item replaces. False when the line is none of the block's lines.
+ */
+function releaseLine(out, line) {
+  const start = line.match(/^- version:\s*(\S+)\s*$/);
+  if (start) {
+    if (out.release) out.problems.push('release: holds one record, the last release');
+    out.release = { version: start[1] };
+
+    return true;
+  }
+
+  const field = line.match(/^ {2}(channel|date|phase):\s*(\S+)\s*$/);
+  if (!field || !out.release) return false;
+  out.release[field[1]] = field[2];
 
-/** Parse LIVE.md text: `{capabilities, knownIssues, problems}`. */
+  return true;
+}
+
+/**
+ * Parse LIVE.md text: `{phase, release, capabilities, knownIssues, problems}`. `phase`
+ * (Methodology §10) sits in the frontmatter, null until the first `gcf phase next`; `release`
+ * is null until a release item ends.
+ */
 export function parseLive(text) {
-  /** @type {{capabilities: LiveRecord[], knownIssues: LiveRecord[], problems: string[]}} */
-  const out = { capabilities: [], knownIssues: [], problems: [] };
-  const body = String(text)
-    .replace(/\r\n/g, '\n')
-    .replace(/^---\n[\s\S]*?\n---\n?/, '');
-  /** @type {'capabilities' | 'knownIssues' | null} */
+  /** @type {{phase: string | null, release: LiveRelease | null, capabilities: LiveRecord[],
+   *   knownIssues: LiveRecord[], problems: string[]}} */
+  const out = { phase: null, release: null, capabilities: [], knownIssues: [], problems: [] };
+  const norm = String(text).replace(/\r\n/g, '\n');
+  const front = norm.match(/^---\n([\s\S]*?)\n---\n?/);
+  const phase = front?.[1].match(/^phase:(.*)$/m)?.[1].trim();
+  if (phase !== undefined && !SLUG.test(phase))
+    out.problems.push(`phase: ${phase} is not a phase name`);
+  else out.phase = phase ?? null;
+  const body = front ? norm.slice(front[0].length) : norm;
+  /** @type {'release' | 'capabilities' | 'knownIssues' | null} */
   let section = null;
   /** @type {LiveRecord | null} */
   let rec = null;
-  body.split('\n').forEach((line, i) => {
-    const head = line.match(/^([a-z-]+):\s*$/);
-    if (head) {
-      section = SECTIONS[head[1]] ?? null;
-      if (!section) out.problems.push(`line ${i + 1}: unknown section ${head[1]}:`);
-      rec = null;
-
-      return;
-    }
-
+  /** A record line of capabilities or known-issues; false when the line is not one. */
+  const recordLine = (line) => {
     const start = line.match(/^- id:\s*(\S+)\s*$/);
     if (start && section) {
       rec = { id: start[1], summary: '' };
       out[section].push(rec);
 
-      return;
+      return true;
     }
 
     const field = line.match(/^ {2}(summary|refs):\s*(.+?)\s*$/);
-    if (field && rec) {
-      rec[field[1]] = field[2];
+    if (!field || !rec) return false;
+    rec[field[1]] = field[2];
+
+    return true;
+  };
+
+  body.split('\n').forEach((line, i) => {
+    const head = line.match(/^([a-z-]+):\s*$/);
+    if (head) {
+      section = SECTIONS[head[1]] ?? null;
+      if (!section) out.problems.push(`line ${i + 1}: unknown section ${head[1]}:`);
+      rec = null;
 
       return;
     }
 
+    if (section === 'release' ? releaseLine(out, line) : recordLine(line)) return;
     if (line.trim() && !/^- none\b/.test(line) && !line.startsWith('#'))
       out.problems.push(`line ${i + 1}: not a record line: ${line.trim()}`);
   });
+  const r = out.release;
+  if (r && !(SLUG.test(r.channel ?? '') && /^\d{4}-\d{2}-\d{2}$/.test(r.date ?? '')))
+    out.problems.push('release: needs version, a slug channel and a YYYY-MM-DD date');
 
   return out;
 }
@@ -66,12 +107,18 @@ const recordText = (r) =>
 const byId = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
 
 /** LIVE.md text: records sorted by id, so two branches touching different ids merge cleanly. */
-export function serializeLive({ capabilities, knownIssues }) {
+export function serializeLive({ phase = null, release = null, capabilities, knownIssues }) {
   const block = (key, list) =>
     `${key}:\n${list.length ? [...list].sort(byId).map(recordText).join('\n') : NONE[key]}\n`;
 
   return [
-    '---\ntype: live\n---\n',
+    `---\ntype: live\n${phase ? `phase: ${phase}\n` : ''}---\n`,
+    ...(release
+      ? [
+          `release:\n- version: ${release.version}\n  channel: ${release.channel}\n` +
+            `  date: ${release.date}\n${release.phase ? `  phase: ${release.phase}\n` : ''}`,
+        ]
+      : []),
     block('capabilities', capabilities),
     block('known-issues', knownIssues),
   ].join('\n');
@@ -85,6 +132,18 @@ export async function readLive(root) {
   return parseLive(existsSync(file) ? await readFile(file, 'utf8') : '');
 }
 
+/**
+ * LIVE.md for a command that writes it or acts on its phase: a malformed file refuses, since
+ * rewriting it would drop what the parser could not read.
+ */
+export async function readLiveStrict(root) {
+  const live = await readLive(root);
+  if (live.problems.length)
+    throw new Error(`gcf/LIVE.md: ${live.problems[0]} — fix it by hand in its own commit first`);
+
+  return live;
+}
+
 export async function writeLive(root, live) {
   await atomicWrite(liveFile(root), serializeLive(live));
 }
@@ -117,13 +176,25 @@ export function applyDelta(capabilities, delta, itemId) {
 /**
  * The capabilities without what `delta` added: an unplayed mechanic killed, dropped or sent back
  * to tuning leaves the game, so its record leaves LIVE.md with it. `modified` and `removed`
- * cannot be undone from the delta alone and stay as they are.
+ * cannot be undone from the delta alone and stay as they are. A record another item modified
+ * since is refused: taking it out would erase that item's accepted change.
  */
-export function revertDelta(capabilities, delta) {
+export function revertDelta(capabilities, delta, itemId) {
   if (!delta || 'none' in delta) return capabilities;
-  const added = delta.changes.filter((c) => c.change === 'added').map((c) => c.id);
+  const added = delta.changes.filter((c) => c.change === 'added');
+  for (const c of added) {
+    const now = capabilities.find((r) => r.id === c.id);
+    // LIVE.md keeps fields trimmed: compare in that form, or a trailing space reads as an edit.
+    const same = (a, b) => String(a ?? '').trim() === String(b ?? '').trim();
+    if (now && !(same(now.summary, c.summary) && same(now.refs, c.refs)))
+      throw new Error(
+        `${itemId}: capability ${c.id} was modified after ${itemId} added it — taking it out ` +
+          'would erase that change: remove the record from LIVE.md by hand in its own commit ' +
+          'and repeat, or keep the item',
+      );
+  }
 
-  return capabilities.filter((r) => !added.includes(r.id));
+  return capabilities.filter((r) => !added.some((c) => c.id === r.id));
 }
 
 /** The known-issue record of a parked bug: its title or first intent bullet, and its file. */

package/lib/main-lock.js

@@ -0,0 +1,112 @@
+// Writes to main serialize through `.gcf-session/main.lock` (Methodology §7): every committed gcf
+// move and the integrator hold it while they write and commit, so a run and the operator wait for
+// each other instead of committing over each other. Re-entrant along one call chain: `integrate`
+// holds it across the merge and the move it records.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { link, mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+
+const chain = new AsyncLocalStorage();
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export const lockFile = (projectDir) =>
+  path.join(path.resolve(projectDir), '.gcf-session', 'main.lock');
+
+const alive = (pid) => {
+  try {
+    process.kill(pid, 0);
+
+    return true;
+  } catch (e) {
+    // EPERM: alive under another user. ESRCH: gone.
+    return e.code === 'EPERM';
+  }
+};
+
+/** The lock's text when its holder is gone, else null. The file appears whole: see `take`. */
+async function staleText(file) {
+  try {
+    const text = await readFile(file, 'utf8');
+    const pid = Number(text.split('\n')[0]);
+    if (Number.isInteger(pid) && pid > 0) return alive(pid) ? null : text;
+
+    // Not ours to read: a lock in some other shape counts as dead only once it is old.
+    return Date.now() - (await stat(file)).mtimeMs > 10000 ? text : null;
+  } catch {
+    return null; // released meanwhile
+  }
+}
+
+/**
+ * Take the lock atomically: the pid goes into a file of its own first, and a hard link puts it
+ * in place whole or fails with EEXIST — no reader ever sees a lock without its pid.
+ */
+async function take(file, token) {
+  const tmp = `${file}.${token}`;
+  await writeFile(tmp, `${process.pid}\n${token}\n`);
+  try {
+    await link(tmp, file);
+
+    return true;
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+
+    return false;
+  } finally {
+    await unlink(tmp).catch(() => {});
+  }
+}
+
+/**
+ * Move a dead holder's lock aside. shortcut: two takers that judged the same dead lock may race
+ * here — the rename lets one of them win, a fresh lock renamed by the loser is put back.
+ */
+async function clearStale(file, text) {
+  const aside = `${file}.stale-${randomUUID()}`;
+  try {
+    await rename(file, aside);
+  } catch {
+    return;
+  }
+
+  if ((await readFile(aside, 'utf8').catch(() => text)) !== text)
+    await link(aside, file).catch(() => {});
+  await unlink(aside).catch(() => {});
+}
+
+/**
+ * Run `fn` holding the main lock. Waits up to `waitMs` for another holder; a lock whose process
+ * died is taken over.
+ * @template T
+ * @param {string} projectDir
+ * @param {() => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export async function withMainLock(projectDir, fn, { waitMs = 60000 } = {}) {
+  const file = lockFile(projectDir);
+  const held = chain.getStore() ?? new Set();
+  if (held.has(file)) return fn();
+
+  await mkdir(path.dirname(file), { recursive: true });
+  const token = randomUUID();
+  const until = Date.now() + waitMs;
+  while (!(await take(file, token))) {
+    const dead = await staleText(file);
+    if (dead !== null) await clearStale(file, dead);
+    else if (Date.now() > until)
+      throw new Error(
+        `gcf/ is busy: another gcf move holds ${path.relative(projectDir, file)} — retry when ` +
+          'it ends, or delete the file if no gcf command is running',
+      );
+    else await sleep(100);
+  }
+
+  try {
+    return await chain.run(new Set([...held, file]), fn);
+  } finally {
+    // Only our own lock leaves: one taken over as dead meanwhile belongs to its new holder.
+    const text = await readFile(file, 'utf8').catch(() => '');
+    if (text.includes(token)) await unlink(file).catch(() => {});
+  }
+}

package/lib/phase.js

@@ -0,0 +1,228 @@
+// Phases (Methodology §10): the project's stage decides which item types it takes, and each
+// stage has exit criteria. The current phase is `phase:` in the LIVE.md frontmatter, the first
+// phase while it is absent; the set comes from code, and `phases:` in gcf/config.yml replaces it.
+// Only the operator moves the phase on: `phase next`, against unmet criteria with a reason.
+import path from 'node:path';
+import { readConfig } from './gcf-paths.js';
+import { readLiveStrict, writeLive, liveFile } from './live.js';
+import { buildLedger } from './ledger.js';
+import { ITEM_TYPES } from './validate-item.js';
+import { commitMove } from './unit-ops.js';
+
+const ALL = ITEM_TYPES;
+const SOFT = ['mechanic', 'resource'];
+
+/**
+ * @typedef {{name: string, accepts: string[], with_reopens: string[], exit: string[],
+ *   milestone?: string}} Phase
+ */
+
+/** @type {Phase[]} */
+export const DEFAULT_PHASES = [
+  // Final assets are not requested in a prototype (§5.6): placeholders need no item.
+  {
+    name: 'prototype',
+    accepts: ALL.filter((t) => t !== 'asset'),
+    with_reopens: [],
+    exit: ['mechanic-kept'],
+  },
+  {
+    name: 'vertical-slice',
+    accepts: ALL,
+    with_reopens: [],
+    exit: ['milestone-done', 'no-placeholders'],
+  },
+  { name: 'alpha', accepts: ALL, with_reopens: [], exit: ['features-done'] },
+  {
+    name: 'beta',
+    accepts: ['bug', 'perf', 'content', 'asset', 'release'],
+    with_reopens: SOFT,
+    exit: ['no-open-bugs'],
+  },
+  { name: 'release', accepts: ['bug', 'release'], with_reopens: [], exit: ['release-done'] },
+  { name: 'live', accepts: ['bug', 'content', 'perf', 'release'], with_reopens: SOFT, exit: [] },
+];
+
+const finished = ['unplayed', 'parked'];
+const milestoneOf = (phase) => phase.milestone ?? phase.name;
+
+/**
+ * Exit criteria: `true` met, `false` not, `null` for one only the operator can see. Each gets
+ * the ledger, LIVE.md and the phase, and returns `[met, detail]`.
+ */
+const CRITERIA = {
+  'mechanic-kept': (ledger) => {
+    const kept = ledger.ids().filter((id) => ledger.where(id).terminal.includes('collapsed'));
+
+    return [
+      kept.length > 0,
+      kept.length ? `kept: ${kept.join(', ')}` : 'no mechanic or resource kept yet',
+    ];
+  },
+  // An ended item leaves no file, so "nothing open" cannot tell a done milestone from one never
+  // tagged: the operator reads that case, the code only names what is still open.
+  'milestone-done': (ledger, live, phase) => {
+    const m = milestoneOf(phase);
+    const open = [
+      ...ledger.design.flatMap((d) => d.units).filter((u) => u.header.milestone === m),
+      ...ledger.items
+        .filter((c) => c.data.milestone === m && !finished.includes(c.data.status))
+        .map((c) => ({ id: c.data.id })),
+    ].map((x) => x.id);
+
+    return open.length
+      ? [false, `milestone ${m} still open: ${open.join(', ')}`]
+      : [null, `nothing open carries milestone ${m}: check by hand it is done, not untagged`];
+  },
+  // Feature complete: a live feature of this milestone, or one with no milestone at all, is open.
+  'features-done': (ledger, live, phase) => {
+    const m = milestoneOf(phase);
+    const open = ledger.items
+      .filter((c) => c.data.type === 'feature' && [m, null, undefined].includes(c.data.milestone))
+      .map((c) => c.data.id);
+
+    return [
+      !open.length,
+      open.length ? `features open: ${open.join(', ')}` : `no feature of ${m} or untagged open`,
+    ];
+  },
+  'no-open-bugs': (ledger) => {
+    const open = ledger.items
+      .filter(
+        (c) =>
+          c.data.type === 'bug' &&
+          ['critical', 'high'].includes(c.data.severity) &&
+          c.data.status !== 'parked',
+      )
+      .map((c) => c.data.id);
+
+    return [
+      !open.length,
+      open.length ? `critical/high bugs open: ${open.join(', ')}` : 'no critical or high bug open',
+    ];
+  },
+  // Only a release shipped in this phase: a demo shipped in alpha does not end the release phase.
+  'release-done': (ledger, live) => {
+    const r = live.release;
+    const ours = Boolean(r) && (r.phase ?? null) === live.phase;
+
+    return [
+      ours,
+      ours
+        ? `released ${r.version} to ${r.channel}`
+        : 'no release of this phase in LIVE.md: its release item has not ended yet',
+    ];
+  },
+  'no-placeholders': () => [null, 'check by hand: the slice holds no placeholder'],
+};
+export const CRITERIA_NAMES = Object.keys(CRITERIA);
+
+const isList = (v, of) => Array.isArray(v) && v.every((x) => of.includes(x));
+const isSlug = (v) => typeof v === 'string' && /^[a-z0-9]+(-[a-z0-9]+)*$/.test(v);
+
+/** The phases of a project: `phases:` of gcf/config.yml, checked, or the default set. */
+export function phasesOf(config) {
+  const list = config.phases;
+  if (list === undefined) return DEFAULT_PHASES;
+  const bad = (msg) => new Error(`gcf/config.yml phases: ${msg}`);
+  if (!Array.isArray(list) || !list.length) throw bad('a non-empty list of phases');
+  const names = list.map((p) => p?.name);
+  const twice = names.find((n, i) => names.indexOf(n) !== i);
+  if (twice !== undefined) throw bad(`${twice} is listed twice`);
+
+  return list.map((p, i) => {
+    const name = p?.name;
+    if (!isSlug(name)) throw bad(`entry ${i + 1} needs a slug name`);
+    if (p.milestone !== undefined && !isSlug(p.milestone))
+      throw bad(`${name}: milestone is a milestone name`);
+    const accepts = p.accepts === 'all' ? ALL : p.accepts;
+    if (!isList(accepts, ALL)) throw bad(`${name}: accepts is all or a list of ${ALL.join(', ')}`);
+    const withReopens = p.with_reopens ?? [];
+    if (!isList(withReopens, ALL)) throw bad(`${name}: with_reopens is a list of item types`);
+    const exit = p.exit ?? [];
+    if (!isList(exit, CRITERIA_NAMES))
+      throw bad(`${name}: exit is a list of ${CRITERIA_NAMES.join(', ')}`);
+
+    return {
+      name,
+      accepts,
+      with_reopens: withReopens,
+      exit,
+      ...(p.milestone ? { milestone: p.milestone } : {}),
+    };
+  });
+}
+
+/** The phases, the current one and LIVE.md. A `phase:` the set does not name is an error. */
+async function load(projectDir) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const phases = phasesOf(await readConfig(root));
+  const live = await readLiveStrict(root);
+  const at = live.phase === null ? 0 : phases.findIndex((p) => p.name === live.phase);
+  if (at < 0) {
+    const names = phases.map((p) => p.name).join(', ');
+    throw new Error(`LIVE.md phase ${live.phase} is not a phase of the project (${names})`);
+  }
+
+  return { root, phases, at, live };
+}
+
+/** Refuse a new item of `type` the current phase does not take. */
+export async function refuseByPhase(projectDir, type, reopens = null) {
+  const { phases, at } = await load(projectDir);
+  const phase = phases[at];
+  if (phase.accepts.includes(type) || (reopens && phase.with_reopens.includes(type))) return;
+  const takes = phase.with_reopens.length
+    ? `${phase.accepts.join(', ')}; ${phase.with_reopens.join(', ')} only with reopens`
+    : phase.accepts.join(', ');
+  throw new Error(
+    `phase ${phase.name} takes no ${type} item (it takes ${takes}) — the operator moves the ` +
+      'phase on with gcf phase next',
+  );
+}
+
+/** `gcf phase`: the current phase, what it takes, its exit criteria and the next phase. */
+export async function phaseStatus(projectDir) {
+  const { phases, at, live } = await load(projectDir);
+  const phase = phases[at];
+  const ledger = await buildLedger(projectDir);
+  const criteria = phase.exit.map((name) => {
+    const [met, detail] = CRITERIA[name](ledger, live, phase);
+
+    return { name, met, detail };
+  });
+
+  return {
+    phase: phase.name,
+    accepts: phase.accepts,
+    with_reopens: phase.with_reopens,
+    criteria,
+    next: phases[at + 1]?.name ?? null,
+    ready: criteria.every((c) => c.met !== false),
+  };
+}
+
+/**
+ * The operator moves the phase on, commit `gcf(phase): <from> → <to>`. An unmet criterion needs
+ * `reason`, which the commit carries; the move itself is the operator's word on one that only
+ * the operator can check.
+ */
+export async function nextPhase(projectDir, { reason = '', commit = true } = {}) {
+  const status = await phaseStatus(projectDir);
+  if (!status.next) throw new Error(`${status.phase} is the last phase`);
+  const unmet = status.criteria.filter((c) => c.met === false);
+  if (unmet.length && !reason.trim())
+    throw new Error(
+      `${status.phase} exit criteria not met (${unmet.map((c) => c.detail).join('; ')}) — ` +
+        'move on anyway with --reason "<why>"',
+    );
+  const { root, live } = await load(projectDir);
+  const tail = `${status.phase} → ${status.next}${reason.trim() ? `: ${reason.trim()}` : ''}`;
+  const hash = await commitMove(projectDir, `gcf(phase): ${tail}`, {
+    files: [liveFile(root)],
+    mutate: () => writeLive(root, { ...live, phase: status.next }),
+    commit,
+  });
+
+  return { from: status.phase, to: status.next, forced: unmet.map((c) => c.name), hash };
+}

package/lib/pillars.js

@@ -0,0 +1,113 @@
+// Revising PILLARS.md after units and items cite it: a rename follows the id everywhere it is
+// cited, a retire takes it out and sends every unit left without a pillar back to the human.
+// Pillars are human authorship (gcf-init): these moves only carry out the human's decision.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { serialize } from './frontmatter.js';
+import { SLUG_RE, listOf, parseDesign } from './design.js';
+import { recordsIn } from './design-check.js';
+import { buildLedger } from './ledger.js';
+import { atomicWrite } from './safe-path.js';
+import { commitMove } from './unit-ops.js';
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** The `id: <id>` line of a PILLARS.md record; `\r` and the line break stay outside it. */
+const idLine = (id) =>
+  new RegExp(`^([ \\t]*(?:- )?id:[ \\t]*)${escapeRe(id)}[ \\t]*(?=\\r?$)`, 'm');
+
+/**
+ * The design file with `edit` applied to each unit's header `pillars:` line — the header only:
+ * a `pillars:` line in a body or the preamble is not a citation. TBD stays TBD; a list left
+ * empty reads TBD, so the unit is not ready until the human gives it a pillar again.
+ */
+function rewriteHeaders(text, edit) {
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const lines = text.split(/\r?\n/);
+  for (const u of parseDesign(text, '').units) {
+    const at = u.headerLines.pillars;
+    const list = listOf(u.header.pillars ?? '');
+    if (at === undefined || list === 'TBD') continue;
+    const next = edit(list);
+    if (next.join() !== list.join())
+      lines[at - 1] = `pillars: ${next.length ? `[${next.join(', ')}]` : 'TBD'}`;
+  }
+
+  return lines.join(eol);
+}
+
+/**
+ * Apply `edit` to every citing list — unit headers in design/, item frontmatter in work/ — and
+ * `editPillars` to PILLARS.md, in one commit `gcf(pillar): <tail>`. Returns the items left
+ * citing no pillar: an item in work has no TBD to fall back to, so the human hears about it.
+ */
+async function revise(projectDir, id, { edit, editPillars, tail, commit }) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const pillarsFile = path.join(root, 'PILLARS.md');
+  const text = existsSync(pillarsFile) ? await readFile(pillarsFile, 'utf8') : '';
+  const ids = recordsIn(text, 'pillars').map((p) => p.id);
+  if (!ids.includes(id)) throw new Error(`${id} is not a pillar of gcf/PILLARS.md`);
+  const ledger = await buildLedger(projectDir);
+  const designFiles = ledger.design.map((d) => path.join(root, d.file));
+  const items = ledger.items.filter((c) => (c.data.pillars ?? []).includes(id));
+  const files = [pillarsFile, ...designFiles, ...items.map((c) => c.file)];
+  const mutate = async () => {
+    await atomicWrite(pillarsFile, editPillars(text));
+    for (const f of designFiles) {
+      const old = await readFile(f, 'utf8');
+      const next = rewriteHeaders(old, edit);
+      if (next !== old) await atomicWrite(f, next);
+    }
+
+    for (const c of items) {
+      await atomicWrite(c.file, serialize({ ...c.data, pillars: edit(c.data.pillars) }, c.body));
+    }
+  };
+
+  return {
+    id,
+    hash: await commitMove(projectDir, `gcf(pillar): ${tail}`, { files, mutate, commit }),
+    bare: items.filter((c) => !edit(c.data.pillars).length).map((c) => String(c.data.id)),
+  };
+}
+
+/** `pillar rename <from> <to>`: the id changes in PILLARS.md and every unit and item citing it. */
+export async function renamePillar(projectDir, from, to, { commit = true } = {}) {
+  if (!SLUG_RE.test(to)) throw new Error(`${to}: a pillar id is a lowercase hyphen slug`);
+  const text = await readFile(path.join(projectDir, 'gcf', 'PILLARS.md'), 'utf8').catch(() => '');
+  if (recordsIn(text, 'pillars').some((p) => p.id === to))
+    throw new Error(`${to} is a pillar already`);
+
+  return revise(projectDir, from, {
+    edit: (list) => list.map((p) => (p === from ? to : p)),
+    editPillars: (t) => t.replace(idLine(from), (_, head) => `${head}${to}`),
+    tail: `rename ${from} → ${to}`,
+    commit,
+  });
+}
+
+/**
+ * `pillar retire <id> --reason`: the record leaves PILLARS.md and the id leaves every list. A
+ * unit left citing no pillar reads `pillars: TBD` again — it is not ready until the human gives
+ * it one, or decides it is out of scope. The reason is kept in the commit.
+ */
+export async function retirePillar(projectDir, id, { reason, commit = true }) {
+  const why = String(reason ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!why) throw new Error('a retire needs a reason: the commit keeps it');
+  const own = idLine(id);
+
+  return revise(projectDir, id, {
+    edit: (list) => list.filter((p) => p !== id),
+    // A record starts at a `- ` line; the one holding `id: <id>` goes, blank lines and all.
+    editPillars: (t) =>
+      t
+        .split(/\n(?=- )/)
+        .filter((rec) => !own.test(rec))
+        .join('\n'),
+    tail: `retire ${id}: ${why}`,
+    commit,
+  });
+}