gcf-aif-ext 0.3.0 → 0.4.1

package/lib/audit-core.js

@@ -2,74 +2,96 @@ import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { listCards, listSystems, readConfig, tokensEst } from './gcf-paths.js';
+import { listItems, listSystems, readConfig, tokensEst, legacyCards } from './gcf-paths.js';
 import { lint } from './linter.js';
 import { drifted } from './index-gen.js';
-import { designCheck } from './design-check.js';
+import { designCheck, recordsIn } from './design-check.js';
 import { buildLedger } from './ledger.js';
+import { STORED } from './transitions.js';
+import { openDepends } from './work-ops.js';
 
 function git(args, cwd) {
-  const res = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  // A blame of a long file overflows the 1 MiB default, and an overflow reads as a git failure.
+  const res = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
 
   return res.status === 0 ? res.stdout.trim() : null;
 }
 
 const UNTIL_RE = /\[until:\s*(verdict\([a-z0-9-]+\)|retune\([a-z0-9-]+\)|manual\([^)]*\))\]/g;
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-const LEGAL_STATUS = ['proposed', 'built', 'tuning'];
 
 /**
  * @typedef {object} AuditReport
  * @property {string} first_line
- * @property {Array<{id: string, commits: number | null, limit: number}>} stale_built
+ * @property {Array<{id: string, status: string, commits: number | null, limit: number}>}
+ *   stale_waiting
  * @property {Array<{id: string, tune_count: number, limit: number}>} tune_limit
  * @property {Array<{id: string, depends: string[]}>} open_depends
  * @property {{count: number, limit: number, over: boolean}} wip
- * @property {{tokens: number, budget: number, over: boolean} | null} pillars
+ * @property {{count: number, warn_after: number, over: boolean}} unplayed
+ * @property {string[]} legacy_cards
+ * @property {{tokens: number, budget: number, over: boolean, count: number, too_many: boolean}
+ *   | null} pillars
  * @property {Array<{file: string, trigger: string, status: string}>} until
  * @property {Record<string, object[]>} linter
  * @property {object[]} pragmas
  * @property {boolean} index_drift
  * @property {Array<{id: string, status: string}>} illegal_status
+ * @property {Array<{id: string, commits: number | null, limit: number}>} stale_questions
  * @property {number} [schema]
- * @property {Array<{id: string, status: string, system: string[], depends: string[]}>} [cards]
+ * @property {Array<{id: string, type: string, gate: string, status: string, system: string[],
+ *   depends: string[], parent: string | null, tune_count: number}>} [items]
  * @property {{blocking: number, units: number, ready: number}} [design]
  */
 
 /**
- * Deterministic audit core (GCF-PRD §10.1): until triggers, built staleness, tune
- * limits, WIP, PILLARS budget, П2 linter, INDEX drift. No LLM anywhere; the
+ * Deterministic audit core (GCF-PRD §10.1): until triggers, waiting staleness, tune limits,
+ * WIP, unplayed count, PILLARS budget, П2 linter, INDEX drift. No LLM anywhere; the
  * contradiction hunt is a separate optional skill pass.
  */
 export async function audit(projectDir) {
   const root = path.join(path.resolve(projectDir), 'gcf');
   const config = await readConfig(root);
-  const cards = await listCards(root);
+  const items = await listItems(root);
   const systems = await listSystems(root);
+  const ledger = await buildLedger(projectDir);
+  const unplayed = items.filter((c) => c.data.status === 'unplayed').length;
   /** @type {AuditReport} */
   const report = {
     first_line: '',
-    stale_built: [],
+    stale_waiting: [],
     tune_limit: [],
     open_depends: [],
-    wip: wipOf(cards, config),
+    wip: wipOf(items, config),
+    unplayed: {
+      count: unplayed,
+      warn_after: config.unplayed_warn_after,
+      over: unplayed > config.unplayed_warn_after,
+    },
+    legacy_cards: legacyCards(root),
     pillars: await pillarsOf(root, config),
-    until: untilRecords(cards, systems, projectDir, await buildLedger(projectDir)),
+    until: untilRecords(items, systems, projectDir, ledger),
     linter: {},
     pragmas: [],
     index_drift: await drifted(root),
     illegal_status: [],
+    stale_questions: staleQuestions(projectDir, root, config),
   };
   // The harness gate reads everything from this one report — it never parses gcf/ itself.
   report.schema = config.schema;
-  report.cards = cards.map((c) => ({
+  report.items = items.map((c) => ({
     id: c.data.id,
+    type: c.data.type,
+    gate: c.data.gate,
     status: c.data.status,
     system: c.data.system ?? [],
     depends: c.data.depends ?? [],
+    parent: c.data.parent ?? null,
+    tune_count: c.data.tune_count ?? 0,
+    parallel: c.data.parallel ?? 'serial',
   }));
   const design = await designCheck(projectDir);
-  checkCards(report, cards, config, { projectDir, designIds: design.units.map((u) => u.id) });
+  checkItems(report, items, config, { projectDir, ledger });
   report.design = {
     blocking: design.blocking,
     units: design.units.length,
@@ -82,24 +104,25 @@ export async function audit(projectDir) {
 }
 
 /**
- * Per-card checks: illegal status, built staleness, tune limit, open depends. `designIds` are
- * units still in gcf/design/: a card depending on one builds on what nobody has played yet.
+ * Per-item checks: illegal status, waiting staleness, tune limit, open depends — a dependency
+ * still in design/ or in work, not unplayed or parked, is what nobody has played yet.
  */
-function checkCards(report, cards, config, { projectDir, designIds }) {
-  const liveIds = new Set([...cards.map((c) => c.data.id), ...designIds]);
+function checkItems(report, items, config, { projectDir, ledger }) {
   // Staleness is measured in commits, so outside a repository there is no answer to give.
-  // Without this probe every built card would read as stale and stop the harness.
+  // Without this probe every waiting item would read as stale and stop the harness.
   const inRepo = git(['rev-parse', '--git-dir'], projectDir) !== null;
 
-  for (const c of cards) {
-    if (!LEGAL_STATUS.includes(c.data.status)) {
+  for (const c of items) {
+    if (!STORED.includes(c.data.status)) {
       report.illegal_status.push({ id: c.data.id, status: c.data.status });
     }
 
     const stale = inRepo ? staleEntry(c, config, projectDir) : null;
-    if (stale) report.stale_built.push(stale);
+    if (stale) report.stale_waiting.push(stale);
 
-    if ((c.data.tune_count ?? 0) >= config.tune_limit) {
+    // At the limit, only the next verdict matters: a ready item still gets its last build.
+    const verdictDue = ['awaiting-verdict', 'unplayed'].includes(c.data.status);
+    if (verdictDue && (c.data.tune_count ?? 0) >= config.tune_limit) {
       report.tune_limit.push({
         id: c.data.id,
         tune_count: c.data.tune_count,
@@ -107,23 +130,26 @@ function checkCards(report, cards, config, { projectDir, designIds }) {
       });
     }
 
-    // A depends id that still has a card file is unplayed (GCF-PRD §7.2). Data for the
-    // harness gate, not an alert: a proposed card waiting on its dependency is normal.
-    const open = (c.data.depends ?? []).filter((d) => liveIds.has(d));
+    // Data for the harness gate, not an alert: a ready item waiting on its dependency is normal.
+    // A run may start on a dependency awaiting its verdict (Methodology §3.2); close and keep
+    // check the stricter rule themselves.
+    const open = openDepends(ledger, c.data.depends ?? [], { waiting: true });
     if (open.length) report.open_depends.push({ id: c.data.id, depends: open });
   }
 }
 
-/** A stale_built entry for a built card past the commit limit, else null. */
+/** A stale_waiting entry for an item waiting on the operator past the commit limit, else null. */
 function staleEntry(c, config, projectDir) {
-  if (c.data.status !== 'built' || !c.data.built_at) return null;
+  const waits = ['awaiting-verdict', 'awaiting-decision', 'blocked'].includes(c.data.status);
+  if (!waits || !c.data.since) return null;
   // git() is null when the ref no longer resolves (rebase, squash, amend, shallow clone).
   // Number(null) is 0, which reads as "fresh" — the one answer that must never be guessed.
-  const raw = git(['rev-list', '--count', `${c.data.built_at}..HEAD`], projectDir);
+  const raw = git(['rev-list', '--count', `${c.data.since}..HEAD`], projectDir);
   const n = raw === null ? NaN : Number(raw);
   if (!Number.isFinite(n) || n > config.built_stale_after_commits) {
     return {
       id: c.data.id,
+      status: c.data.status,
       commits: Number.isFinite(n) ? n : null,
       limit: config.built_stale_after_commits,
     };
@@ -132,33 +158,84 @@ function staleEntry(c, config, projectDir) {
   return null;
 }
 
-function wipOf(cards, config) {
-  const count = cards.filter((c) => c.data.status === 'built').length;
+/** WIP counts what waits for the playtest; unplayed items have their own warning (§4). */
+function wipOf(items, config) {
+  const count = items.filter((c) => c.data.status === 'awaiting-verdict').length;
 
   return { count, limit: config.wip_built_limit, over: count > config.wip_built_limit };
 }
 
+// GCF-PRD §5.3: no more than 7 pillars.
+const PILLARS_MAX = 7;
+
 async function pillarsOf(root, config) {
   const pillarsFile = path.join(root, 'PILLARS.md');
   if (!existsSync(pillarsFile)) return null;
-  const tokens = tokensEst(await readFile(pillarsFile, 'utf8'));
+  const text = await readFile(pillarsFile, 'utf8');
+  const tokens = tokensEst(text);
+  const count = recordsIn(text, 'pillars').length;
+
+  return {
+    tokens,
+    budget: config.pillars_budget,
+    over: tokens > config.pillars_budget,
+    count,
+    too_many: count > PILLARS_MAX,
+  };
+}
+
+/**
+ * Open questions older than the limit, aged by the last commit that changed their `- id:` line
+ * beyond whitespace (GCF-PRD §7.4): a pile of unanswered ones means the human has dropped out
+ * of the loop.
+ */
+function staleQuestions(projectDir, root, config) {
+  if (!existsSync(path.join(root, 'open-questions.md'))) return [];
+  // null for an untracked file or outside a repository: no commit to age from. -w: a respaced
+  // or re-ended (CRLF/LF) line keeps the commit that wrote it.
+  const blame = git(['blame', '-w', '--porcelain', '--', 'gcf/open-questions.md'], projectDir);
+  if (blame === null) return [];
+  const added = [];
+  let hash = '';
+  for (const line of blame.split('\n')) {
+    const head = line.match(/^([0-9a-f]{40,64}) \d+ \d+/);
+    if (head) hash = head[1];
+    const id = line.match(/^\t\uFEFF?- id:\s*(\S+)/)?.[1];
+    // An uncommitted line blames to the all-zero hash: it is new, not old.
+    if (id && !/^0+$/.test(hash)) added.push({ id, hash });
+  }
+
+  const ages = new Map();
+  const ageOf = (h) => {
+    if (!ages.has(h)) {
+      const raw = git(['rev-list', '--count', `${h}..HEAD`], projectDir);
+      // Number(null) is 0, "fresh" — the one answer that must never be guessed (see staleEntry).
+      ages.set(h, raw === null ? null : Number(raw));
+    }
+
+    return ages.get(h);
+  };
+
+  const limit = config.question_stale_after_commits;
 
-  return { tokens, budget: config.pillars_budget, over: tokens > config.pillars_budget };
+  return added
+    .map(({ id, hash: h }) => ({ id, commits: ageOf(h), limit }))
+    .filter((q) => q.commits === null || q.commits > limit);
 }
 
 /**
  * Whether a verdict fired. `verdict(id)` reads the files, as the ledger does (GCF-PRD §5.8): a
- * keep or kill left a history or graveyard line, a tune left the card's tune_count — so a
+ * keep or kill left a history or graveyard line, a tune left the item's tune_count — so a
  * squash or a shallow clone does not hide it, and a revert takes it back.
  */
-function verdictMatchers(projectDir, ledger, cards) {
-  const tuned = cards.filter((c) => (c.data.tune_count ?? 0) > 0);
+function verdictMatchers(projectDir, ledger, items) {
+  const tuned = items.filter((c) => (c.data.tune_count ?? 0) > 0);
   const verdictLog = git(['log', '--grep', '^gcf(verdict):', '--format=%s'], projectDir) ?? '';
 
   return {
     verdict: (id) =>
       ledger.where(id).terminal.some((t) => t !== 'done') || tuned.some((c) => c.data.id === id),
-    // shortcut: a kept card's tunes leave no file behind, so retune(sys) also greps the verdict
+    // shortcut: a kept item's tunes leave no file behind, so retune(sys) also greps the verdict
     // subjects; upgrade when tunes get their own history line.
     retune: (system) =>
       tuned.some((c) => (c.data.system ?? []).includes(system)) ||
@@ -180,11 +257,11 @@ function untilStatus(trigger, fired) {
   return 'manual';
 }
 
-/** Until annotations across cards and systems docs. */
-function untilRecords(cards, systems, projectDir, ledger) {
-  const fired = verdictMatchers(projectDir, ledger, cards);
+/** Until annotations across work items and systems docs. */
+function untilRecords(items, systems, projectDir, ledger) {
+  const fired = verdictMatchers(projectDir, ledger, items);
   const docs = [
-    ...cards.map((c) => ({ rel: `cards/${c.name}`, body: c.body })),
+    ...items.map((c) => ({ rel: `work/${c.name}`, body: c.body })),
     ...systems.map((s) => ({ rel: `systems/${s.name}`, body: s.body })),
   ];
   const until = [];
@@ -206,19 +283,29 @@ function lintSystems(report, systems) {
   }
 }
 
-/** Alerts about cards in flight, which lead the line. @param {AuditReport} report */
-const cardAlerts = (report) => [
-  report.illegal_status.length && `${report.illegal_status.length} card(s) in illegal status`,
-  report.stale_built.length && `${report.stale_built.length} built card(s) stale — playtest first`,
+/** Alerts about items in flight, which lead the line. @param {AuditReport} report */
+const itemAlerts = (report) => [
+  report.legacy_cards.length &&
+    `${report.legacy_cards.length} schema 2 card(s) in gcf/cards/ — back to gcf/design/, then take`,
+  report.illegal_status.length && `${report.illegal_status.length} item(s) in illegal status`,
+  report.stale_waiting.length &&
+    `${report.stale_waiting.length} item(s) waiting on you too long — playtest or answer first`,
   report.tune_limit.length &&
-    `${report.tune_limit.length} card(s) at tune limit — kill or redesign`,
+    `${report.tune_limit.length} item(s) at tune limit — kill or redesign`,
   report.wip.over && `WIP over limit (${report.wip.count}/${report.wip.limit})`,
+  report.unplayed.over &&
+    `${report.unplayed.count} unplayed item(s) (warn after ` +
+      `${report.unplayed.warn_after}) — play them`,
 ];
 
 /** Alerts about the documents. @param {AuditReport} report */
 const docAlerts = (report) => [
   report.until.filter((u) => u.status === 'stale').length && 'stale until-records present',
   report.pillars?.over && 'PILLARS over token budget',
+  report.pillars?.too_many && `PILLARS has ${report.pillars.count} pillars (max ${PILLARS_MAX})`,
+  report.stale_questions.length &&
+    `${report.stale_questions.length} open question(s) unanswered for over ` +
+      `${report.stale_questions[0].limit} commits`,
   Object.keys(report.linter).length && 'П2 linter findings in systems docs',
   report.index_drift && 'INDEX drift (regenerate)',
   report.design?.blocking && `${report.design.blocking} blocking design finding(s)`,
@@ -226,7 +313,7 @@ const docAlerts = (report) => [
 
 /** @param {AuditReport} report */
 function firstLine(report) {
-  const alerts = [...cardAlerts(report), ...docAlerts(report)].filter(Boolean);
+  const alerts = [...itemAlerts(report), ...docAlerts(report)].filter(Boolean);
 
   return alerts.length ? alerts.join('; ') : 'clean';
 }

package/lib/bundle.js

@@ -147,14 +147,17 @@ async function currentParts(root) {
 
 /** A design file with the `## <id>` section replaced by `text`, or appended when absent. */
 function putUnit(fileText, id, text) {
-  const lines = fileText.split('\n');
+  // A file kept with CRLF stays CRLF: work in LF, write back in the file's own line ending.
+  const eol = fileText.match(/\r?\n/)?.[0] ?? '\n';
+  const lf = fileText.replace(/\r\n/g, '\n');
+  const lines = lf.split('\n');
   const at = lines.findIndex((l) => l.trimEnd() === `## ${id}`);
-  const section = [`## ${id}`, '', ...text.split('\n'), ''];
-  if (at < 0) return `${fileText.trimEnd()}\n\n${section.join('\n')}`;
+  const section = [`## ${id}`, '', ...text.replace(/\r\n/g, '\n').split('\n'), ''];
+  if (at < 0) return `${lf.trimEnd()}\n\n${section.join('\n')}`.replace(/\n/g, eol);
   let end = lines.findIndex((l, i) => i > at && /^## \S/.test(l));
   if (end < 0) end = lines.length;
 
-  return [...lines.slice(0, at), ...section, ...lines.slice(end)].join('\n');
+  return [...lines.slice(0, at), ...section, ...lines.slice(end)].join('\n').replace(/\n/g, eol);
 }
 
 /** A design file with its preamble purpose replaced; a title of the file's own stays. */

package/lib/context.js

@@ -1,32 +1,32 @@
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { listCards, listSystems, readConfig, tokensEst } from './gcf-paths.js';
+import { listItems, listSystems, readConfig, tokensEst } from './gcf-paths.js';
 
 /**
  * Readset assembly — the whole command is deterministic (GCF-PRD §9.1, §10.1):
- * PILLARS + touched systems + the card + its depends + graveyard tag hits +
+ * PILLARS + LIVE.md + touched systems + the item + its parent + its depends + graveyard tag hits +
  * D2 assumptions whose sys overlaps. Never over_budget-throws: the caller gates.
  */
-export async function buildContext(projectDir, cardId) {
+export async function buildContext(projectDir, itemId) {
   const root = path.join(path.resolve(projectDir), 'gcf');
   const config = await readConfig(root);
-  const cards = await listCards(root);
-  const card = cards.find((c) => c.data.id === cardId);
-  if (!card) throw new Error(`Card not found: ${cardId}`);
+  const items = await listItems(root);
+  const item = items.find((c) => c.data.id === itemId);
+  if (!item) throw new Error(`Work item not found: ${itemId}`);
 
-  const systems = card.data.system ?? [];
-  const files = await readsetFiles(root, card, cards);
-  const cardText =
-    `${card.data.id} ${card.data.title ?? ''} ${systems.join(' ')} ${card.body}`.toLowerCase();
-  const graveyard_hits = await graveyardHits(root, cardText);
+  const systems = item.data.system ?? [];
+  const files = await readsetFiles(root, item, items);
+  const itemText =
+    `${item.data.id} ${item.data.title ?? ''} ${systems.join(' ')} ${item.body}`.toLowerCase();
+  const graveyard_hits = await graveyardHits(root, itemText);
   const d2 = await d2Assumptions(root, systems);
 
   const extraTokens = tokensEst(graveyard_hits.join('\n')) + tokensEst(d2.join('\n'));
   const total_tokens_est = files.reduce((sum, f) => sum + f.tokens_est, 0) + extraTokens;
 
   return {
-    card: cardId,
+    item: itemId,
     files,
     graveyard_hits,
     d2,
@@ -36,33 +36,41 @@ export async function buildContext(projectDir, cardId) {
   };
 }
 
-/** PILLARS, touched systems, the card, its depends — in that order, skipping absent files. */
-async function readsetFiles(root, card, cards) {
+/**
+ * PILLARS, LIVE.md, touched systems, the item, its parent feature (the goal a child serves),
+ * its depends — in order, skipping absent files.
+ */
+async function readsetFiles(root, item, items) {
   const files = [];
   const push = async (rel) => {
     const abs = path.join(root, rel);
-    if (!existsSync(abs)) return;
+    const at = `gcf/${rel.replaceAll('\\', '/')}`;
+    // A parent that is also a dependency is read once and counted once against the budget.
+    if (!existsSync(abs) || files.some((f) => f.path === at)) return;
     const text = await readFile(abs, 'utf8');
-    files.push({ path: `gcf/${rel.replaceAll('\\', '/')}`, tokens_est: tokensEst(text) });
+    files.push({ path: at, tokens_est: tokensEst(text) });
   };
 
   await push('PILLARS.md');
-  const systems = card.data.system ?? [];
+  await push('LIVE.md');
+  const systems = item.data.system ?? [];
   for (const s of (await listSystems(root)).filter((d) => systems.includes(d.data.system))) {
     await push(`systems/${s.name}`);
   }
 
-  await push(`cards/${card.name}`);
-  for (const depId of card.data.depends ?? []) {
-    const dep = cards.find((c) => c.data.id === depId);
-    if (dep) await push(`cards/${dep.name}`);
+  await push(`work/${item.name}`);
+  const parent = items.find((c) => c.data.id === item.data.parent);
+  if (parent) await push(`work/${parent.name}`);
+  for (const depId of item.data.depends ?? []) {
+    const dep = items.find((c) => c.data.id === depId);
+    if (dep) await push(`work/${dep.name}`);
   }
 
   return files;
 }
 
-/** Graveyard: headline tags only; a hit is a tag appearing in the card's own text. */
-async function graveyardHits(root, cardText) {
+/** Graveyard: headline tags only; a hit is a tag appearing in the item's own text. */
+async function graveyardHits(root, itemText) {
   const gyFile = path.join(root, 'graveyard.md');
   if (!existsSync(gyFile)) return [];
   const hits = [];
@@ -73,13 +81,13 @@ async function graveyardHits(root, cardText) {
       .split(',')
       .map((t) => t.trim().toLowerCase())
       .filter(Boolean);
-    if (tags.some((t) => cardText.includes(t))) hits.push(line.trim());
+    if (tags.some((t) => itemText.includes(t))) hits.push(line.trim());
   }
 
   return hits;
 }
 
-/** D2 assumptions whose sys: overlaps the card's systems (GCF-PRD §9.1). */
+/** D2 assumptions whose sys: overlaps the item's systems (GCF-PRD §9.1). */
 async function d2Assumptions(root, systems) {
   const oqFile = path.join(root, 'open-questions.md');
   if (!existsSync(oqFile)) return [];