gcf-aif-ext 0.3.0 → 0.4.1

package/lib/live.js

@@ -0,0 +1,191 @@
+// LIVE.md (Methodology §8): what the game is now, one short record per capability and per known
+// issue, no history. Capabilities change only through the live: delta of an item, applied in the
+// commit of the move that ends it; known issues are the parked bugs, written by `decide known`
+// and taken out by any end of that bug.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+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 NONE = {
+  capabilities: '- none: no capability recorded yet',
+  'known-issues': '- none: no known issue',
+};
+
+/** @typedef {{id: string, summary: string, refs?: string}} LiveRecord */
+
+/** Parse LIVE.md text: `{capabilities, knownIssues, problems}`. */
+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} */
+  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;
+    }
+
+    const start = line.match(/^- id:\s*(\S+)\s*$/);
+    if (start && section) {
+      rec = { id: start[1], summary: '' };
+      out[section].push(rec);
+
+      return;
+    }
+
+    const field = line.match(/^ {2}(summary|refs):\s*(.+?)\s*$/);
+    if (field && rec) {
+      rec[field[1]] = field[2];
+
+      return;
+    }
+
+    if (line.trim() && !/^- none\b/.test(line) && !line.startsWith('#'))
+      out.problems.push(`line ${i + 1}: not a record line: ${line.trim()}`);
+  });
+
+  return out;
+}
+
+const recordText = (r) =>
+  [`- id: ${r.id}`, `  summary: ${r.summary}`, ...(r.refs ? [`  refs: ${r.refs}`] : [])].join('\n');
+
+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 }) {
+  const block = (key, list) =>
+    `${key}:\n${list.length ? [...list].sort(byId).map(recordText).join('\n') : NONE[key]}\n`;
+
+  return [
+    '---\ntype: live\n---\n',
+    block('capabilities', capabilities),
+    block('known-issues', knownIssues),
+  ].join('\n');
+}
+
+export const liveFile = (root) => path.join(root, 'LIVE.md');
+
+export async function readLive(root) {
+  const file = liveFile(root);
+
+  return parseLive(existsSync(file) ? await readFile(file, 'utf8') : '');
+}
+
+export async function writeLive(root, live) {
+  await atomicWrite(liveFile(root), serializeLive(live));
+}
+
+/**
+ * The capabilities after `delta` (an item's `live:`), or a thrown reason. `none` changes nothing;
+ * `added` needs a new id, `modified` and `removed` an existing one.
+ */
+export function applyDelta(capabilities, delta, itemId) {
+  if (!delta) throw new Error(`${itemId} has no live: delta — say what it changes, or none: <why>`);
+  if ('none' in delta) return capabilities;
+  let next = [...capabilities];
+  for (const c of delta.changes) {
+    const at = next.findIndex((r) => r.id === c.id);
+    if (c.change === 'added' && at >= 0)
+      throw new Error(`${itemId}: capability ${c.id} already exists — use change: modified`);
+    if (c.change !== 'added' && at < 0)
+      throw new Error(`${itemId}: capability ${c.id} is not in LIVE.md — nothing to ${c.change}`);
+    if (c.change === 'removed') next = next.filter((r) => r.id !== c.id);
+    else {
+      const rec = { id: c.id, summary: c.summary, ...(c.refs ? { refs: c.refs } : {}) };
+      if (at >= 0) next[at] = { ...next[at], ...rec };
+      else next.push(rec);
+    }
+  }
+
+  return next;
+}
+
+/**
+ * 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. A record another item modified
+ * since is refused: taking it out would erase that item's accepted change.
+ */
+export function revertDelta(capabilities, delta, itemId) {
+  if (!delta || 'none' in delta) return capabilities;
+  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.some((c) => c.id === r.id));
+}
+
+/** The known-issue record of a parked bug: its title or first intent bullet, and its file. */
+export function knownIssueOf(item) {
+  const intent = String(item.body ?? '').match(/^intent:\s*\n- (.+)$/m)?.[1];
+  const summary = String(item.data.title ?? intent ?? item.data.id).trim();
+
+  return { id: String(item.data.id), summary, refs: `gcf/work/${item.data.id}.md` };
+}
+
+/** The refs of a record that name no file of the project. */
+const brokenRefs = (projectDir, r) =>
+  String(r.refs ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter((ref) => ref && !existsSync(path.join(projectDir, ref.split('#')[0])));
+
+/**
+ * `live check`: record form, duplicate ids, refs that name no file, a known issue without its
+ * parked bug and a parked bug without its known issue.
+ */
+export async function checkLive(projectDir) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const live = await readLive(root);
+  const issues = [...live.problems];
+  /** @type {Array<[string, LiveRecord[]]>} */
+  const kinds = [
+    ['capability', live.capabilities],
+    ['known issue', live.knownIssues],
+  ];
+  for (const [name, list] of kinds) {
+    const seen = new Set();
+    for (const r of list) {
+      if (seen.has(r.id)) issues.push(`${name} ${r.id} is listed twice`);
+      seen.add(r.id);
+      const bad = summaryProblem(r.summary);
+      if (bad) issues.push(`${name} ${r.id}: ${bad}`);
+      issues.push(
+        ...brokenRefs(projectDir, r).map((ref) => `${name} ${r.id}: refs ${ref} names no file`),
+      );
+    }
+  }
+
+  const parked = (await listItems(root)).filter((i) => i.data.status === 'parked');
+  const known = new Set(live.knownIssues.map((r) => r.id));
+  for (const p of parked)
+    if (!known.has(p.data.id)) issues.push(`parked bug ${p.data.id} has no known-issue record`);
+  for (const id of known)
+    if (!parked.some((p) => p.data.id === id))
+      issues.push(`known issue ${id} has no parked bug in gcf/work/`);
+
+  return { ...live, issues };
+}

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,
+  });
+}

package/lib/plan-check.js

@@ -0,0 +1,31 @@
+// `gcf plan check <id>` (Methodology §5.2.1): the deterministic check after each improve pass —
+// the plan exists, it holds task checkboxes, and the item's readset fits the context budget.
+// Whether the plan is any good is the improve passes' job; this only says it is usable.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { buildLedger } from './ledger.js';
+import { buildContext } from './context.js';
+
+export async function planCheck(projectDir, id) {
+  const item = (await buildLedger(projectDir)).item(id);
+  if (!item) throw new Error(`${id} is not a work item of gcf/work/`);
+  const plan = item.data.plan ?? `.ai-factory/plans/${id}.md`;
+  const file = path.resolve(projectDir, plan);
+  const problems = [];
+  let tasks = 0;
+  let done = 0;
+  if (!existsSync(file)) problems.push(`no plan at ${plan}`);
+  else {
+    const text = await readFile(file, 'utf8');
+    tasks = (text.match(/^\s*- \[[ xX]\] /gm) ?? []).length;
+    done = (text.match(/^\s*- \[[xX]\] /gm) ?? []).length;
+    if (!tasks) problems.push(`${plan} has no task checkboxes (- [ ] …)`);
+  }
+
+  const ctx = await buildContext(projectDir, id);
+  if (ctx.over_budget)
+    problems.push(`readset ~${ctx.total_tokens_est} tokens is over the budget ${ctx.budget}`);
+
+  return { id, plan, tasks, done, problems, ok: problems.length === 0 };
+}

package/lib/playtest-list.js

@@ -1,12 +1,16 @@
-import { listCards, scalarOf } from './gcf-paths.js';
+import { listItems, scalarOf } from './gcf-paths.js';
 
-/** Playtest list (GCF-PRD §10): every built card with its miss-criterion question. */
+/**
+ * Playtest list (Methodology §5.3): every item waiting for its verdict, and every unplayed one,
+ * with the question the play must answer.
+ */
 export async function playtestList(root) {
-  return (await listCards(root))
-    .filter((c) => c.data.status === 'built')
+  return (await listItems(root))
+    .filter((c) => ['awaiting-verdict', 'unplayed'].includes(c.data.status))
     .map((c) => ({
       id: c.data.id,
       title: c.data.title ?? null,
+      status: c.data.status,
       system: c.data.system ?? [],
       question: scalarOf(c.body, 'miss_criterion') || '(miss_criterion is empty)',
     }));

package/lib/systems-doc.js

@@ -7,7 +7,7 @@ import { parseBlocks, itemsOf } from 'cnlp-kit';
 import { parse } from './frontmatter.js';
 import { scalarIn } from './design.js';
 
-const NONE_LINE = '- none: no card of this subsystem has collapsed yet';
+const NONE_LINE = '- none: no item of this subsystem has collapsed yet';
 
 export function blockLines(body, key) {
   const { lines, sections } = parseBlocks(body);
@@ -36,6 +36,21 @@ export function upsertBlock(rawBody, key, addLines) {
   return `${body.trimEnd()}\n\n${block}`;
 }
 
+/**
+ * The `key:` bullet block without `dropLines` — the inverse of upsertBlock. A block left empty
+ * gets the `- none:` placeholder back, as a new systems doc starts.
+ */
+export function removeLines(rawBody, key, dropLines) {
+  const body = lf(rawBody);
+  const existing = blockLines(body, key);
+  const kept = existing.filter((l) => !dropLines.includes(l));
+  if (kept.length === existing.length) return body;
+  const block = `${key}:\n${(kept.length ? kept : [NONE_LINE]).join('\n')}\n`;
+  const re = new RegExp(`^${key}:[^\\n]*\\n(?:(?!\\S+:).*\\n?)*`, 'm');
+
+  return body.replace(re, () => `${block}\n`).replace(/\n{3,}/g, '\n\n');
+}
+
 const lf = (text) => String(text).replace(/\r\n/g, '\n');
 
 /** Purpose lines a new systems doc starts with: design/<sys>.md's `purpose:`, or a marker. */

package/lib/transitions.js

@@ -1,28 +1,43 @@
-// GCF-PRD §7.1. `none` = materialization (no card file yet).
-// `validated` and `killed` are terminal and NEVER stored: the verdict that produces them
-// also deletes the card file, so a card file carrying one is a П1 violation (pre-commit check).
-const STORED = new Set(['proposed', 'built', 'tuning']);
-export const TERMINAL = new Set(['validated', 'killed']);
+// Methodology §4. A work item FILE carries one of the stored statuses; `running` and `verify` are
+// read from the run (worktree + session), never written. A terminal move deletes the file and
+// writes a history or graveyard line in the same commit, so no terminal status is ever stored.
+export const STORED = [
+  'ready',
+  'awaiting-verdict',
+  'awaiting-decision',
+  'blocked',
+  'parked',
+  'unplayed',
+];
 
-const LEGAL = new Set([
-  'none>proposed',
-  'proposed>built', // agent flips frontmatter itself on implementation commit (GCF-PRD §5.1)
-  'built>tuning', //   /gcf-verdict tune
-  'tuning>built', //   agent re-built after tuning
-  'built>validated', // /gcf-verdict keep — file is deleted in the same atomic commit
-  'built>killed', //   /gcf-verdict kill — file is deleted in the same atomic commit
-]);
+// The status each command takes an item from (§4.1). `drop` leaves from any stored status.
+const FROM = {
+  submit: ['ready'],
+  close: ['ready'],
+  'verdict:keep': ['awaiting-verdict', 'unplayed'],
+  'verdict:tune': ['awaiting-verdict', 'unplayed'],
+  'verdict:kill': ['awaiting-verdict', 'unplayed'],
+  'decide:go': ['awaiting-decision'],
+  'decide:no': ['awaiting-decision', 'ready'],
+  'decide:wontfix': ['ready', 'blocked', 'parked'],
+  'decide:known': ['ready', 'blocked'],
+  'decide:close': ['awaiting-decision'],
+  'decide:continue': ['awaiting-decision'],
+  'decide:kill': ['awaiting-decision', 'ready'],
+  block: ['ready'],
+  unblock: ['blocked', 'parked'],
+  drop: STORED,
+};
 
-export function isLegal(from, to) {
-  return LEGAL.has(`${from}>${to}`);
+/** True when `move` (`close`, `verdict:keep`, …) may start from `status`. */
+export function allowedFrom(move, status) {
+  return (FROM[move] ?? []).includes(status);
 }
 
-/** Statuses reachable from `from`, for error messages. */
-export function legalTargets(from) {
-  return [...LEGAL].filter((t) => t.startsWith(`${from}>`)).map((t) => t.split('>')[1]);
-}
+/** Statuses `move` starts from, for error messages. */
+export const fromOf = (move) => FROM[move] ?? [];
 
-/** A status a card FILE may carry. Terminal statuses exist only in the transition itself. */
+/** A status an item FILE may carry. */
 export function isStorable(status) {
-  return STORED.has(status);
+  return STORED.includes(status);
 }