gcf-aif-ext 0.2.7 → 0.4.0

package/lib/work-ops.js

@@ -0,0 +1,727 @@
+// The moves of a work item (Methodology §4.1): submit, close, verdict, decide, block, unblock,
+// drop — plus `item new`. Each committed move is one fixed-format commit `gcf(<move>): <id>`
+// that carries every file it touched: the item, history or graveyard, LIVE.md, the systems
+// docs, the parent feature, a removal item, the archived plan. Atomic: a refused commit rolls
+// every file back.
+import { readFile, unlink } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { serialize } from './frontmatter.js';
+import { buildLedger } from './ledger.js';
+import { readConfig } from './gcf-paths.js';
+import { atomicWrite, withFileRollback } from './safe-path.js';
+import { writeIndex } from './index-gen.js';
+import { allowedFrom, fromOf } from './transitions.js';
+import { ITEM_TYPES, DEFAULT_GATE, GATES, SEVERITIES, UNIT_ITEM_TYPES } from './validate-item.js';
+import { isValidId } from './id.js';
+import { commitMove, addConstraints } from './unit-ops.js';
+import { openSystemDoc, upsertBlock } from './systems-doc.js';
+import {
+  collapseLines,
+  mergeIntoSystem,
+  unmergeFromSystem,
+  systemFiles,
+  buryLine,
+  recordLine,
+} from './verdict-fs.js';
+import { readLive, writeLive, liveFile, applyDelta, revertDelta, knownIssueOf } from './live.js';
+import { dropInbox } from './inbox.js';
+
+/**
+ * Options of a committed move; each move reads the ones it needs.
+ * @typedef {object} MoveOpts
+ * @property {string} [note]
+ * @property {string} [reason]
+ * @property {string[]} [tags]
+ * @property {boolean} [remove] create a removal item; absent = the move's default
+ * @property {string[]} [constraints]
+ * @property {boolean} [commit]
+ */
+
+const SOFT = ['mechanic', 'resource'];
+const HARD = ['rule', 'constraint', 'entity'];
+const today = () => new Date().toISOString().slice(0, 10);
+const gcfOf = (projectDir) => path.join(path.resolve(projectDir), 'gcf');
+
+/** HEAD's hash, null outside a repository or before the first commit. */
+function headHash(projectDir) {
+  const res = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: projectDir, encoding: 'utf8' });
+
+  return res.status === 0 ? res.stdout.trim() : null;
+}
+
+/** The live work item `id`, or an error naming where the id lives instead. */
+function itemOf(ledger, id) {
+  const item = ledger.item(id);
+  if (item) return item;
+  const { live, terminal } = ledger.where(id);
+  const at = live.map((p) => p.file).join(', ') || terminal.join(', ') || 'nowhere';
+  throw new Error(`${id} is not a work item of gcf/work/ (it is: ${at})`);
+}
+
+function need(move, item) {
+  if (allowedFrom(move, item.data.status)) return;
+  throw new Error(
+    `${move.replace(':', ' ')} ${item.data.id}: it is ${item.data.status}, the move needs ` +
+      `${fromOf(move).join(' or ')}`,
+  );
+}
+
+/**
+ * Dependencies not yet played (Methodology §4.1): a dependency counts once its id ended in
+ * history, or is unplayed or parked. A design unit or an item in any other status is open.
+ * `waiting` also lets through one awaiting its verdict: two linked mechanics are played in the
+ * same session, so the second may be submitted while the first waits.
+ */
+export function openDepends(ledger, depends = [], { waiting = false } = {}) {
+  const played = waiting ? ['unplayed', 'parked', 'awaiting-verdict'] : ['unplayed', 'parked'];
+
+  return depends.filter((d) => {
+    const { live, terminal } = ledger.where(d);
+    const place = live[0];
+    // Built on something killed: not played, never will be — take it out of depends, or drop.
+    // Unknown anywhere is not played either: a dependency that vanished cannot be built on.
+    if (!place) return terminal.every((t) => t === 'killed');
+    if (place.state === 'design') return true;
+
+    return !played.includes(ledger.item(d)?.data.status);
+  });
+}
+
+/** The hash an unplayed item's body is frozen at (Methodology §5.4). */
+export const bodyHash = (body) =>
+  createHash('sha1').update(String(body).replace(/\r\n/g, '\n').trim()).digest('hex');
+
+/** Children of a feature that are not finished: live in any status but unplayed and parked. */
+function unfinishedChildren(ledger, feature) {
+  return (feature.data.children ?? []).filter((c) => {
+    const child = ledger.item(c);
+
+    return child && !['unplayed', 'parked'].includes(child.data.status);
+  });
+}
+
+/**
+ * Open a move on item `id` from the statuses `move` allows: the files it touches, its steps,
+ * and the LIVE.md edits folded into a single write at the end.
+ */
+async function begin(projectDir, id, move) {
+  const root = gcfOf(projectDir);
+  const ledger = await buildLedger(projectDir);
+  const item = itemOf(ledger, id);
+  need(move, item);
+  const files = [item.file];
+  const steps = [];
+  const liveOps = [];
+
+  return {
+    projectDir,
+    root,
+    ledger,
+    item,
+    /** @type {Set<string>} ids leaving systems/ in this move */
+    leaving: new Set(),
+    files,
+    touch: (...f) => files.push(...f.filter((x) => !files.includes(x))),
+    step: (fn) => steps.push(fn),
+    live: (fn) => {
+      if (!files.includes(liveFile(root))) files.push(liveFile(root));
+      liveOps.push(fn);
+    },
+    run: async () => {
+      for (const s of steps) await s();
+      if (!liveOps.length) return;
+      let live = await readLive(root);
+      for (const op of liveOps) live = op(live);
+      await writeLive(root, live);
+    },
+  };
+}
+
+/** Commit the move as `gcf(<move>): <tail>` with every file it touched (item edits included). */
+const finish = (m, move, tail, commit) =>
+  commitMove(m.projectDir, `gcf(${move}): ${tail}`, {
+    files: m.files,
+    mutate: m.run,
+    commit,
+    inputs: [m.item.file],
+  });
+
+const writeItem = (item, data, body = item.body) => atomicWrite(item.file, serialize(data, body));
+
+/** `data` without the keys named — a field that no longer applies leaves the frontmatter. */
+const without = (data, ...keys) =>
+  Object.fromEntries(Object.entries(data).filter(([k]) => !keys.includes(k)));
+
+/**
+ * The item's lines leave its systems docs and its added capability leaves LIVE.md. A line
+ * another unplayed item also wrote stays: that item's body still owes it to systems/.
+ */
+function unplay(m, item) {
+  const systems = item.data.system ?? [];
+  m.leaving.add(String(item.data.id));
+  m.touch(...systemFiles(m.root, systems));
+  m.step(async () => {
+    // Read at run time: siblings leaving in the same move (a feature kill) owe nothing either.
+    const keep = m.ledger.items
+      .filter((i) => i.data.status === 'unplayed' && !m.leaving.has(String(i.data.id)))
+      .flatMap((i) => Object.values(collapseLines(i.body)).flat());
+    for (const s of systems) await unmergeFromSystem(m.root, s, item, keep);
+  });
+  m.live((l) => ({ ...l, capabilities: revertDelta(l.capabilities, item.data.live) }));
+}
+
+const dropKnownIssue = (m, id) =>
+  m.live((l) => ({ ...l, knownIssues: l.knownIssues.filter((r) => r.id !== id) }));
+
+/** True when git tracks `file`: an ignored or new plan stays out of the move's commit. */
+function tracked(projectDir, file) {
+  const res = spawnSync('git', ['ls-files', '--error-unmatch', '--', file], {
+    cwd: projectDir,
+    stdio: 'ignore',
+  });
+
+  return res.status === 0;
+}
+
+/**
+ * The item's plan moves to the AIF archive in the move's own commit (Methodology §3.3), so a
+ * LIVE.md ref to it holds the moment the item ends. No tracked plan — nothing to do. Returns
+ * the archived path, or null.
+ */
+function archivePlan(m, item) {
+  const rel = item.data.plan ?? `.ai-factory/plans/${item.data.id}.md`;
+  const src = path.resolve(m.projectDir, rel);
+  if (!existsSync(src) || !tracked(m.projectDir, src)) return null;
+  const destRel = `.ai-factory/archive/plans/${path.basename(src)}`;
+  const dest = path.resolve(m.projectDir, destRel);
+  if (existsSync(dest)) return null;
+  m.touch(src, dest);
+  m.step(async () => {
+    await atomicWrite(dest, await readFile(src, 'utf8'));
+    await unlink(src);
+  });
+
+  return destRel;
+}
+
+/** A delta whose changes name no refs points at where the item's detail now lives. */
+function withRefs(delta, refs) {
+  if (!delta || 'none' in delta || !refs) return delta;
+  const ref = (c) => (c.refs || c.change === 'removed' ? c : { ...c, refs });
+
+  return { changes: delta.changes.map(ref) };
+}
+
+/** Where a capability of `item` is described in detail: its systems doc or its archived plan. */
+const detailOf = (item, archived) =>
+  SOFT.includes(item.data.type) && item.data.system?.length
+    ? `gcf/systems/${item.data.system[0]}.md`
+    : archived;
+
+/**
+ * An item ends accepted: its history line, its LIVE.md delta, its plan archived, its file
+ * gone. An unplayed item's delta went into LIVE.md at its close already.
+ */
+function endToHistory(m, item, event, { applyLive = true } = {}) {
+  const id = String(item.data.id);
+  m.touch(path.join(m.root, 'history.md'));
+  m.step(() => recordLine(m.root, id, event));
+  const archived = archivePlan(m, item);
+  if (applyLive) {
+    const delta = withRefs(item.data.live, detailOf(item, archived));
+    m.live((l) => ({ ...l, capabilities: applyDelta(l.capabilities, delta, id) }));
+  }
+
+  dropKnownIssue(m, id);
+  m.step(() => unlink(item.file));
+}
+
+/** A fresh id from `base`: base, base-2, base-3 … — ids are never reused. */
+function freshId(ledger, base) {
+  let id = base;
+  for (let n = 2; ledger.known(id); n++) id = `${base}-${n}`;
+
+  return id;
+}
+
+/** The item that takes the code of a dead id out of main (Methodology §4.1). */
+function removalItem(m, item, reason) {
+  const id = freshId(m.ledger, `remove-${item.data.id}`);
+  const file = path.join(m.root, 'work', `${id}.md`);
+  const data = {
+    schema: 3,
+    id,
+    type: 'tech',
+    gate: 'auto',
+    status: 'ready',
+    system: item.data.system ?? [],
+    depends: [],
+    reopens: String(item.data.id),
+    live: { none: `removes the code of ${item.data.id}, which never reached LIVE.md or left it` },
+    created: today(),
+  };
+  const body = `\nintent:\n- take the code of ${item.data.id} out of the game: ${reason}\n`;
+  m.touch(file);
+  m.step(() => atomicWrite(file, serialize(data, body)));
+
+  return id;
+}
+
+/** A child went to the graveyard: its live feature waits for the operator's decision (§3.2). */
+function parentWaits(m, item) {
+  const parent = item.data.parent ? m.ledger.item(item.data.parent) : null;
+  if (!parent || parent.data.type !== 'feature') return;
+  const { status } = parent.data;
+  if (status !== 'ready' && status !== 'blocked') return;
+  m.touch(parent.file);
+  // A blocked feature keeps its reason: the dead child is added to it, unblock decides later.
+  const data =
+    status === 'blocked'
+      ? { ...parent.data, blocked: `${parent.data.blocked}; child ${item.data.id} died` }
+      : { ...parent.data, status: 'awaiting-decision', since: headHash(m.projectDir) };
+  m.step(() => writeItem(parent, data));
+}
+
+/**
+ * An item ends dead: its graveyard line, its systems lines out if unplayed, its plan archived,
+ * its file gone; a removal item when its code is in main. `quiet` keeps the parent as it is —
+ * the parent is going down in the same move.
+ */
+function endToGraveyard(
+  m,
+  item,
+  { reason, tags = /** @type {string[]} */ ([]), removal, quiet = false },
+) {
+  const id = String(item.data.id);
+  const why = String(reason ?? '').trim();
+  if (!why) throw new Error(`${id}: the graveyard keeps a reason — give one`);
+  m.touch(path.join(m.root, 'graveyard.md'), item.file);
+  const lineTags = tags.length ? tags : (item.data.system ?? []);
+  m.step(() => buryLine(m.root, id, { type: item.data.type, reason: why, tags: lineTags }));
+  if (item.data.status === 'unplayed') unplay(m, item);
+  archivePlan(m, item);
+  dropKnownIssue(m, id);
+  if (!quiet) parentWaits(m, item);
+  const removed = removal ? removalItem(m, item, why) : null;
+  m.step(() => unlink(item.file));
+
+  return removed;
+}
+
+/**
+ * Whether a dead item's code is in main by default: it waited for the operator, was closed,
+ * was built before a tune — or, in 0.4 where the agent works on main, it got blocked after its
+ * code was committed. `--no-remove` overrides it.
+ */
+const IN_MAIN = ['awaiting-verdict', 'awaiting-decision', 'unplayed', 'blocked', 'parked'];
+const codeInMain = (item) =>
+  item.data.type !== 'spike' &&
+  (IN_MAIN.includes(item.data.status) || (item.data.tune_count ?? 0) > 0);
+
+/**
+ * A feature's own status says nothing about its code: it is in main when a child ended
+ * accepted, or a live child's code is.
+ */
+const featureShipped = (ledger, feature) =>
+  (feature.data.children ?? []).some((c) => {
+    const child = ledger.item(c);
+
+    return child ? codeInMain(child) : ledger.where(c).terminal.some((t) => t !== 'killed');
+  });
+
+function refuseOpenDepends(m, move, opts = {}) {
+  const open = openDepends(m.ledger, m.item.data.depends ?? [], opts);
+  if (!open.length) return;
+  const id = m.item.data.id;
+  throw new Error(
+    `${move} ${id}: it depends on ${open.join(', ')}, not played yet ` +
+      '(a dependency counts once it ended in history, or is unplayed or parked; ' +
+      'a killed one never will — take it out of depends, or drop)' +
+      (move === 'close' ? `; done but waiting: gcf block ${id} --reason "waits for …"` : ''),
+  );
+}
+
+/** ready → awaiting-verdict / awaiting-decision; `since` marks where the wait began.
+ * @param {MoveOpts} [opts]
+ */
+export async function submitItem(projectDir, id, opts = {}) {
+  const { commit = true } = opts;
+  const m = await begin(projectDir, id, 'submit');
+  if (m.item.data.gate === 'auto')
+    throw new Error(`${id} has gate auto: nobody waits for it — close it with gcf close ${id}`);
+  refuseOpenDepends(m, 'submit', { waiting: true });
+  const status = m.item.data.gate === 'verdict' ? 'awaiting-verdict' : 'awaiting-decision';
+  const data = { ...without(m.item.data, 'blocked'), status, since: headHash(projectDir) };
+  m.step(() => writeItem(m.item, data));
+
+  return { id, status, hash: await finish(m, 'submit', id, commit) };
+}
+
+/**
+ * A soft unit closed without a playtest (Methodology §5.4): its lines go into its systems docs,
+ * its capability into LIVE.md, and the file stays unplayed with its body frozen by hash — that
+ * body is what a tune or a kill takes back out. Only an `added` delta can be taken back.
+ */
+function closeUnplayed(m) {
+  const { item } = m;
+  const id = String(item.data.id);
+  if ((item.data.live?.changes ?? []).some((c) => c.change !== 'added'))
+    throw new Error(
+      `${id}: an unplayed close can only add capabilities (a modified or removed one cannot be ` +
+        'taken back) — set gate: verdict and submit it',
+    );
+  const systems = item.data.system ?? [];
+  m.touch(...systemFiles(m.root, systems));
+  m.step(async () => {
+    for (const s of systems) await mergeIntoSystem(m.root, s, item);
+  });
+  const delta = withRefs(item.data.live, detailOf(item, null));
+  m.live((l) => ({ ...l, capabilities: applyDelta(l.capabilities, delta, id) }));
+  m.step(() => writeItem(item, { ...item.data, status: 'unplayed', frozen: bodyHash(item.body) }));
+}
+
+/** Any other gate-auto item ends in history; a hard unit may leave lines in `constraints:`. */
+async function closeEnding(m, constraints) {
+  if (constraints.length) {
+    const { id, type, system = [] } = m.item.data;
+    if (!HARD.includes(type) || !system.length)
+      throw new Error(`${id}: --constraint belongs to a hard unit (rule, constraint, entity)`);
+    const doc = await openSystemDoc(m.root, system[0]);
+    m.touch(doc.file);
+    m.step(() => addConstraints(doc, String(m.item.data.id), constraints));
+  }
+
+  endToHistory(m, m.item, 'done');
+}
+
+/** A feature closes once every child is finished: ended, unplayed or parked (§3.2). */
+function closeFeature(m) {
+  refuseOpenDepends(m, 'close');
+  const open = unfinishedChildren(m.ledger, m.item);
+  if (open.length)
+    throw new Error(`${m.item.data.id}: children not finished yet: ${open.join(', ')}`);
+  endToHistory(m, m.item, 'done');
+}
+
+/**
+ * A gate-auto item passed its DoD. A feature closes once its children are finished; a soft
+ * unit collapses into its systems docs and stays as unplayed; anything else ends in history.
+ * @param {MoveOpts} [opts]
+ */
+export async function closeItem(projectDir, id, opts = {}) {
+  const { constraints = [], commit = true } = opts;
+  const m = await begin(projectDir, id, 'close');
+  const unplayed = SOFT.includes(m.item.data.type);
+  if (m.item.data.type === 'feature') closeFeature(m);
+  else {
+    if (m.item.data.gate !== 'auto')
+      throw new Error(`${id} has gate ${m.item.data.gate}: submit it, the operator closes it`);
+    refuseOpenDepends(m, 'close');
+    if (unplayed) closeUnplayed(m);
+    else await closeEnding(m, constraints);
+  }
+
+  const hash = await finish(m, 'close', `${id}${unplayed ? ' → unplayed' : ''}`, commit);
+
+  return { id, hash, unplayed };
+}
+
+/**
+ * keep: an unplayed item is in systems/ and LIVE.md already; a soft unit collapses now; anything
+ * else ends done. A keep needs its dependencies played — they shared the session, not the verdict.
+ */
+async function keep(m, constraints) {
+  const { item } = m;
+  refuseOpenDepends(m, 'verdict keep');
+  if (item.data.status === 'unplayed') {
+    endToHistory(m, item, 'collapsed', { applyLive: false });
+
+    return;
+  }
+
+  if (!SOFT.includes(item.data.type)) {
+    // A hard unit played by a human still leaves its constraint lines, as its close would.
+    await closeEnding(m, constraints);
+
+    return;
+  }
+
+  const systems = item.data.system ?? [];
+  m.touch(...systemFiles(m.root, systems));
+  m.step(async () => {
+    for (const s of systems) await mergeIntoSystem(m.root, s, item);
+  });
+  endToHistory(m, item, 'collapsed');
+}
+
+/** tune: back to ready with the note; an unplayed item's lines and capability come back out. */
+async function tune(m, note) {
+  const { item } = m;
+  // Only a tune reads the config: a broken config.yml must not block keep or kill.
+  const tunes = item.data.tune_count ?? 0;
+  const { tune_limit: limit } = await readConfig(m.root);
+  if (tunes >= limit)
+    throw new Error(
+      `${item.data.id} is at the tune limit (tune_count ${tunes} of ${limit}) — kill it; a ` +
+        'redesigned envelope is a new item with reopens: <this id>',
+    );
+  if (item.data.status === 'unplayed') unplay(m, item);
+  const body = note ? upsertBlock(item.body, 'tuning', [`- ${note}`]) : item.body;
+  const data = {
+    ...without(item.data, 'frozen'),
+    status: 'ready',
+    tune_count: tunes + 1,
+    since: null,
+  };
+  m.step(() => writeItem(item, data, body));
+}
+
+/** keep | tune | kill on an item waiting for its verdict or unplayed (Methodology §5.4).
+ * @param {MoveOpts} [opts]
+ */
+export async function verdictItem(projectDir, id, verdict, opts = {}) {
+  const { note = '', tags = [], remove, constraints = [], commit = true } = opts;
+  if (!['keep', 'tune', 'kill'].includes(verdict)) throw new Error(`Unknown verdict: ${verdict}`);
+  const m = await begin(projectDir, id, `verdict:${verdict}`);
+  const systems = m.item.data.system ?? [];
+  let removal = null;
+  if (verdict === 'keep') await keep(m, constraints);
+  else if (verdict === 'tune') await tune(m, note);
+  else removal = endToGraveyard(m, m.item, { reason: note, tags, removal: remove ?? true });
+  const hash = await finish(m, 'verdict', `${verdict} ${id} → ${systems.join(',')}`, commit);
+
+  return { verdict, id, systems, hash, removal };
+}
+
+/** decide kill: the live children go down with the feature, without removal items of their own. */
+function killFeature(m, { reason, remove }) {
+  const { item, ledger } = m;
+  const shipped = featureShipped(ledger, item);
+  for (const c of item.data.children ?? []) {
+    const child = ledger.item(c);
+    if (!child) continue;
+    endToGraveyard(m, child, {
+      reason: `feature ${item.data.id} killed: ${reason}`,
+      removal: false,
+      quiet: true,
+    });
+  }
+
+  return endToGraveyard(m, item, { reason, removal: remove ?? shipped });
+}
+
+function park(m) {
+  const rec = knownIssueOf(m.item);
+  m.step(() => writeItem(m.item, { ...without(m.item.data, 'blocked'), status: 'parked' }));
+  m.live((l) => ({ ...l, knownIssues: [...l.knownIssues.filter((r) => r.id !== rec.id), rec] }));
+
+  return null;
+}
+
+// What each decision does; it returns the removal item it created, or null.
+const DECIDE = {
+  go: (m) => endToHistory(m, m.item, 'decided') ?? null,
+  no: (m, o) =>
+    endToGraveyard(m, m.item, { reason: o.reason, removal: o.remove ?? codeInMain(m.item) }),
+  // A bug not to be fixed has fix code in main only when a started fix got blocked.
+  wontfix: (m, o) =>
+    endToGraveyard(m, m.item, {
+      reason: o.reason,
+      removal: o.remove ?? m.item.data.status === 'blocked',
+    }),
+  known: park,
+  close: (m) => closeFeature(m) ?? null,
+  continue: (m) => {
+    m.step(() => writeItem(m.item, { ...m.item.data, status: 'ready' }));
+
+    return null;
+  },
+  kill: killFeature,
+};
+const FEATURE_ONLY = ['close', 'continue', 'kill'];
+
+/** Refuse a decision that does not fit the item's type. */
+function fitDecision(choice, item) {
+  const feature = item.data.type === 'feature';
+  if (FEATURE_ONLY.includes(choice) !== feature)
+    throw new Error(
+      feature
+        ? `${item.data.id} is a feature: decide close | continue | kill`
+        : `decide ${choice} is for a feature; ${item.data.id} is a ${item.data.type}`,
+    );
+  if (['wontfix', 'known'].includes(choice) && item.data.type !== 'bug')
+    throw new Error(`decide ${choice} is for a bug; ${item.data.id} is a ${item.data.type}`);
+}
+
+/** The operator's decisions (Methodology §4.1): spikes, decision items, bugs and features.
+ * @param {MoveOpts} [opts]
+ */
+export async function decideItem(projectDir, id, choice, opts = {}) {
+  const { reason = '', remove, commit = true } = opts;
+  if (!DECIDE[choice])
+    throw new Error(`Unknown decision: ${choice} (${Object.keys(DECIDE).join(' | ')})`);
+  const m = await begin(projectDir, id, `decide:${choice}`);
+  fitDecision(choice, m.item);
+  const removal = DECIDE[choice](m, { reason, remove }) ?? null;
+  const hash = await finish(m, 'decide', `${choice} ${id}`, commit);
+
+  return { id, choice, hash, removal };
+}
+
+/** ready → blocked, with the reason or the question for the operator.
+ * @param {MoveOpts} [opts]
+ */
+export async function blockItem(projectDir, id, opts = {}) {
+  const { reason, commit = true } = opts;
+  const why = String(reason ?? '').trim();
+  if (!why) throw new Error('a block needs a reason or a question');
+  const m = await begin(projectDir, id, 'block');
+  const data = { ...m.item.data, status: 'blocked', blocked: why, since: headHash(projectDir) };
+  m.step(() => writeItem(m.item, data));
+
+  return { id, hash: await finish(m, 'block', id, commit) };
+}
+
+/** blocked | parked → ready; a note (an answer, a delivered asset file) goes to `notes:`.
+ * @param {MoveOpts} [opts]
+ */
+export async function unblockItem(projectDir, id, opts = {}) {
+  const { note = '', commit = true } = opts;
+  const m = await begin(projectDir, id, 'unblock');
+  if (m.item.data.status === 'parked') dropKnownIssue(m, id);
+  const body = note ? upsertBlock(m.item.body, 'notes', [`- ${note}`]) : m.item.body;
+  // A feature whose child died while it was blocked owes the operator that decision first; the
+  // death is the one parentWaits wrote into `blocked:`, not any death of the feature's past.
+  const childDied = / child \S+ died/.test(String(m.item.data.blocked ?? ''));
+  const waits = m.item.data.type === 'feature' && childDied;
+  const data = {
+    ...without(m.item.data, 'blocked'),
+    status: waits ? 'awaiting-decision' : 'ready',
+    since: waits ? headHash(projectDir) : null,
+  };
+  m.step(() => writeItem(m.item, data, body));
+
+  return { id, hash: await finish(m, 'unblock', id, commit) };
+}
+
+/** Any stored status → graveyard; an unplayed item leaves as a kill does.
+ * @param {MoveOpts} [opts]
+ */
+export async function dropItem(projectDir, id, opts = {}) {
+  const { reason, tags = [], remove, commit = true } = opts;
+  const m = await begin(projectDir, id, 'drop');
+  if (m.item.data.type === 'feature' && (m.item.data.children ?? []).some((c) => m.ledger.item(c)))
+    throw new Error(`${id} still has live children: drop them first, or decide kill ${id}`);
+  const shipped =
+    m.item.data.type === 'feature' ? featureShipped(m.ledger, m.item) : codeInMain(m.item);
+  const removal = endToGraveyard(m, m.item, { reason, tags, removal: remove ?? shipped });
+
+  return { id, hash: await finish(m, 'drop', id, commit), removal };
+}
+
+/** Refuse a spec `item new` cannot honour; returns the gate the item gets. */
+function checkNew(ledger, spec) {
+  const { id, type, gate, severity } = spec;
+  if (!isValidId(id)) throw new Error(`${id} is not a lowercase hyphen slug`);
+  if (ledger.known(id)) throw new Error(`${id} is taken already: ids are never reused`);
+  if (!ITEM_TYPES.includes(type)) throw new Error(`type must be ${ITEM_TYPES.join(' | ')}`);
+  if (UNIT_ITEM_TYPES.includes(type))
+    throw new Error(`a ${type} is a design unit: write it in gcf/design/, then gcf take ${id}`);
+  const g = gate ?? DEFAULT_GATE[type];
+  if (!GATES.includes(g)) throw new Error(`gate must be ${GATES.join(' | ')}`);
+  if (type === 'feature' && g !== 'auto') throw new Error('a feature always has gate auto');
+  if (type === 'bug' && !SEVERITIES.includes(severity))
+    throw new Error(`a bug needs --severity ${SEVERITIES.join('|')}`);
+
+  return g;
+}
+
+/** Fields a new item carries only in some cases. */
+// Types that change no capability of the game (Methodology §3.1): their delta is known upfront.
+const NO_CAPABILITY = {
+  bug: 'a fix restores a capability, it adds none',
+  spike: 'a spike answers a question, its code never ships',
+  asset: 'an asset dresses a capability, it adds none',
+  perf: 'a budget met changes no capability',
+};
+
+/** The `live:` a new item starts with, or null when its author owes one. */
+function startingLive({ parent, type }) {
+  // A child's capability is its feature's: the feature writes the one LIVE.md record.
+  if (parent) return { none: 'parent' };
+
+  return NO_CAPABILITY[type] ? { none: NO_CAPABILITY[type] } : null;
+}
+
+function optionalFields(spec, gate, since) {
+  const { title, parent, blocked, type, severity, reopens } = spec;
+  const live = startingLive(spec);
+
+  return {
+    ...(title ? { title } : {}),
+    ...(blocked ? { blocked, since } : {}),
+    ...(parent ? { parent } : {}),
+    ...(reopens ? { reopens } : {}),
+    ...(gate === 'verdict' ? { tune_count: 0 } : {}),
+    ...(type === 'bug' ? { severity } : {}),
+    ...(live ? { live } : {}),
+  };
+}
+
+/** The frontmatter and body of a new item. */
+function newItemText(spec, gate, since) {
+  const { id, type, title, blocked } = spec;
+  const data = {
+    schema: 3,
+    id,
+    type,
+    gate,
+    status: blocked ? 'blocked' : 'ready',
+    system: spec.system ?? [],
+    depends: spec.depends ?? [],
+    ...optionalFields(spec, gate, since),
+    created: spec.date ?? today(),
+  };
+  const body =
+    `\nintent:\n- ${title ?? 'TBD: what this item changes'}\n` +
+    (type === 'bug' ? '\nrepro:\n- TBD: the steps that show the bug\n' : '');
+
+  return serialize(data, body);
+}
+
+/**
+ * A new work item in ready (or blocked), no commit. A design unit enters work through `take`,
+ * not here: its body is the unit's slots. `from` erases the inbox entry it came from.
+ */
+export async function newItem(projectDir, spec) {
+  const root = gcfOf(projectDir);
+  const ledger = await buildLedger(projectDir);
+  const gate = checkNew(ledger, spec);
+  if (spec.reopens && !ledger.where(spec.reopens).terminal.length)
+    throw new Error(`reopens names ${spec.reopens}, which has not ended`);
+  const file = path.join(root, 'work', `${spec.id}.md`);
+  if (existsSync(file)) throw new Error(`gcf/work/${spec.id}.md already exists`);
+
+  const writes = [[file, newItemText(spec, gate, headHash(projectDir))]];
+  if (spec.parent) {
+    const p = ledger.item(spec.parent);
+    if (!p || p.data.type !== 'feature')
+      throw new Error(`${spec.parent} is not a live feature item`);
+    const children = [...new Set([...(p.data.children ?? []), spec.id])];
+    writes.push([p.file, serialize({ ...p.data, children }, p.body)]);
+  }
+
+  await withFileRollback(
+    [...writes.map((w) => w[0]), path.join(root, 'inbox.md'), path.join(root, 'INDEX.md')],
+    async () => {
+      for (const [f, text] of writes) await atomicWrite(f, text);
+      if (spec.from) await dropInbox(root, spec.from);
+      await writeIndex(root);
+    },
+  );
+
+  return { item: `gcf/work/${spec.id}.md` };
+}