gcf-aif-ext 0.3.0 → 0.4.0

package/lib/live.js

@@ -0,0 +1,179 @@
+// 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.
+ */
+export function revertDelta(capabilities, delta) {
+  if (!delta || 'none' in delta) return capabilities;
+  const added = delta.changes.filter((c) => c.change === 'added').map((c) => c.id);
+
+  return capabilities.filter((r) => !added.includes(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/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);
 }