gcf-aif-ext 0.2.7 → 0.4.0

package/hooks/pre-commit.js

@@ -4,14 +4,17 @@
 // The gate reads the WORKING TREE, so it only runs when the commit touches gcf/ and
 // refuses to judge a gcf/ whose working tree and index disagree.
 import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
-import { listCards, listSystems } from '../lib/gcf-paths.js';
-import { validateCard, validateUntil } from '../lib/validate-card.js';
+import { listSystems, legacyCards } from '../lib/gcf-paths.js';
+import { validateItem, validateUntil } from '../lib/validate-item.js';
 import { stemMatches } from '../lib/id.js';
 import { writeIndex } from '../lib/index-gen.js';
 import { lint } from '../lib/linter.js';
+import { buildLedger } from '../lib/ledger.js';
+import { designCheck } from '../lib/design-check.js';
+import { bodyHash } from '../lib/work-ops.js';
+import { checkLive } from '../lib/live.js';
 
 const projectDir = process.cwd();
 const root = path.join(projectDir, 'gcf');
@@ -25,72 +28,97 @@ const fail = (msg) => {
 // null when git itself failed (unborn HEAD, no work tree) — then fall through to the gate
 // rather than letting a broken probe wave a commit past every check.
 function git(args) {
-  const res = spawnSync('git', args, { cwd: projectDir, encoding: 'utf8' });
+  // quotePath off: a non-ASCII path in the refusal reads as itself, not as octal escapes.
+  const res = spawnSync('git', ['-c', 'core.quotePath=false', ...args], {
+    cwd: projectDir,
+    encoding: 'utf8',
+  });
 
   return res.status === 0 ? res.stdout.trim() : null;
 }
 
-const staged = git(['diff', '--cached', '--name-only', '--', root]);
+// gcf/.metrics is left out: `gcf audit` and `gcf context` append to it on every run, and the
+// gate reads none of it. Hooks run from the repository root, so the pathspecs are relative.
+const scope = ['--', 'gcf', ':(exclude)gcf/.metrics'];
+const staged = git(['diff', '--cached', '--name-only', ...scope]);
 if (staged === '') process.exit(0); // this commit does not touch gcf/
 if (staged !== null) {
-  // Untracked counts: listCards reads the directory, so an uncommitted card file would be
-  // validated and written into the staged INDEX while not being in the repository at all.
-  const unstaged = git(['diff', '--name-only', '--', root]);
-  const untracked = git(['ls-files', '--others', '--exclude-standard', '--', root]);
-  if (unstaged || untracked) {
+  // Untracked counts: items and units are found by reading directories, so an uncommitted file
+  // would be validated and written into the staged INDEX while not being in the repository.
+  const outside = [
+    git(['diff', '--name-only', ...scope]),
+    git(['ls-files', '--others', '--exclude-standard', ...scope]),
+  ]
+    .filter(Boolean)
+    .join('\n');
+  if (outside) {
+    // A move (verdict, take, close, drop…) commits only its own files, so staging does not help it.
     fail(
-      'gcf/ has changes outside the index — stage them, or commit gcf/ separately ' +
+      `gcf/ has changes outside the index (${outside.split('\n').join(', ')}) — stage them, ` +
+        'or commit gcf/ separately; before a gcf move, commit or stash them ' +
         '(the gate reads the working tree)',
     );
   }
 }
 
-const cards = await listCards(root);
-const cardIds = new Set(cards.map((c) => c.data.id));
-const systemDocs = await listSystems(root);
+// Schema 2 cards are not read by 0.4: left in place they would silently stop being checked.
+const legacy = legacyCards(root);
+if (legacy.length)
+  fail(
+    `gcf/cards/ holds schema 2 card(s) (${legacy.join(', ')}): GCF 0.4 keeps work in ` +
+      'gcf/work/<id>.md with schema 3 and does not migrate — put each card back into ' +
+      'gcf/design/ as a unit and run ai-factory gcf take, then delete gcf/cards/',
+  );
+
+const ledger = await buildLedger(projectDir);
 
 // 1-2: frontmatter validity, storable statuses, until grammar, filename invariant.
-for (const c of cards) {
+for (const c of ledger.items) {
   const errors = [
-    ...validateCard(c.data),
+    ...validateItem(c.data),
     ...validateUntil(c.body),
-    ...(stemMatches(c.file, c.data.id, c.data.slug)
-      ? []
-      : [`filename must be ${c.data.id}-${c.data.slug}.md`]),
+    ...(stemMatches(c.file, c.data.id) ? [] : [`filename must be ${c.data.id}.md`]),
   ];
-  if (errors.length) fail(`${c.name}: ${errors[0]}`);
+  if (errors.length) fail(`work/${c.name}: ${errors[0]}`);
 }
 
-for (const s of systemDocs) {
+for (const s of await listSystems(root)) {
   const errors = validateUntil(s.body);
   if (errors.length) fail(`systems/${s.name}: ${errors[0]}`);
 }
 
-// 4: depends reference known cards; a built card must not sit on un-collapsed depends.
-// A collapsed card leaves no file, so its trace is the verdict commit or the graveyard line.
-const verdictLog = git(['log', '--grep', '^gcf(verdict):', '--format=%s']) ?? '';
-const gyFile = path.join(root, 'graveyard.md');
-const graveyard = existsSync(gyFile) ? await readFile(gyFile, 'utf8') : '';
-const collapsed = (id) =>
-  new RegExp(`^gcf\\(verdict\\): \\w+ ${id}\\b`, 'm').test(verdictLog) ||
-  new RegExp(`^- ${id} \\|`, 'm').test(graveyard);
-
-function checkDep(c, dep) {
-  if (cardIds.has(dep)) {
-    if (c.data.status === 'built') {
-      fail(`${c.data.id} is built on top of unplayed ${dep} (collapse it first — GCF-PRD §7.2)`);
-    }
-  } else if (!collapsed(dep)) {
-    fail(`${c.data.id} depends on unknown ${dep} (no card, no verdict, no graveyard line)`);
-  }
+// An unplayed item's body is the source of its systems/ lines (Methodology §5.4): edited after
+// its close, a tune or a kill would take the wrong lines out. `close` froze it by hash.
+for (const c of ledger.items.filter((x) => x.data.status === 'unplayed')) {
+  if (bodyHash(c.body) !== c.data.frozen)
+    fail(`work/${c.name}: an unplayed item's body is frozen — tune it to change it`);
 }
 
-for (const c of cards) {
-  for (const dep of c.data.depends ?? []) checkDep(c, dep);
+// A unit or item leaving without its move loses its reason, not its integrity: one still citing
+// it fails M2 below, in this commit. A warning, not a refusal — a revert of the commit that
+// added it removes an id legitimately.
+for (const id of ledger.vanished()) {
+  console.error(
+    `gcf pre-commit: warning: ${id} left design/ or work/ without a move — ` +
+      'no history or graveyard line keeps why',
+  );
 }
 
+// Design model and item bodies: every finding of severity `block` refuses the commit.
+const first = (await designCheck(projectDir)).issues.find((i) => i.severity === 'block');
+if (first) fail(`${first.file}:${first.line}: ${first.check}: ${first.message}`);
+
+// Dependencies are held by the moves, not here (Methodology §4.1): `submit` refuses an unplayed
+// one, `close` and `keep` a not-yet-kept one. A gate check would refuse the tune or the kill of
+// a dependency whose dependent is already waiting for its verdict — a legal move, blocked.
+
+// LIVE.md form: a malformed record would hide from every reader of the snapshot.
+const live = await checkLive(projectDir);
+const form = live.problems[0] ?? live.issues.find((i) => /summary|twice/.test(i));
+if (form) fail(`LIVE.md: ${form}`);
+
 // 5: П2 linter over systems docs.
-for (const s of systemDocs) {
+for (const s of await listSystems(root)) {
   const { issues } = lint(s.body);
   if (issues.length)
     fail(`systems/${s.name}:${issues[0].line}: ${issues[0].rule}: ${issues[0].text}`);

package/injections/commit-status.md

@@ -1,6 +1,9 @@
-## GCF: card status before commit (from gcf-aif-ext)
+## GCF: work item status after commit (from gcf-aif-ext)
 
 gcf_commit:
-- when `gcf/` exists and the commit implements a card, verify the card frontmatter is current
-- an implementation commit that completes a build flips `status:` to `built` and records `built_at:` with the commit hash in the same commit
-- do not commit a card file whose `status:` is `validated` or `killed`: those are terminal and never stored
+- when `gcf/` exists and the commit implements a work item, commit the implementation first, then move the item with its own command in a follow-up commit
+- gate `verdict` or `decision`: run `ai-factory gcf submit <item-id>` — it waits for the operator, `since:` records where the wait began
+- gate `auto`, every check green: write the item's `live:` delta, then run `ai-factory gcf close <item-id>` — never edit `status:` by hand
+- the work cannot go on: run `ai-factory gcf block <item-id> --reason "<why or the question>"`
+- do not write a terminal status into an item file: a terminal move deletes the file and writes the history or graveyard line itself
+- when the commit makes the tests of a hard unit still in `gcf/design/` green, run `ai-factory gcf done <id>` after it

package/injections/plan-context.md

@@ -1,8 +1,12 @@
 ## GCF: readset before planning (from gcf-aif-ext)
 
 gcf_gate:
-- when `gcf/` exists and the task names a card, run `ai-factory gcf context <card-id>` first
-- the returned file list is the readset: read those files and nothing else under `gcf/`
+- when `gcf/` exists and the task names a work item, run `ai-factory gcf context <item-id>` first
+- the returned file list is the readset: read those files and nothing else under `gcf/`; `gcf/LIVE.md` in it says what the game already does
 - `over_budget: true` in the result: stop and record a D1 question instead of planning
-- a card in `depends:` that still exists as a file is unplayed: do not plan on top of it, stop
-- shape the plan by the card slots: behavior, contract, feel envelope, interactions, negative constraints, miss criterion
+- an id in `depends:` that lives in `gcf/design/`, or as an item in any status but unplayed, parked or awaiting-verdict, is not played: do not plan on top of it, stop
+- a dependency awaiting its verdict is planned on: the close of this item then waits for that verdict (`ai-factory gcf block <id> --reason "waits for <dep>"`)
+- write the plan to the item's `plan:` path, by default `.ai-factory/plans/<item-id>.md`, with task checkboxes
+- a design-unit item: shape the plan by its slots — intent, behavior, refusal, boundaries, persistence, feel envelopes, contract, interactions, constraints, miss criterion; a hard unit plans its tests from `statement`, `threshold` or `fields`
+- a bug item: the first task writes the test that reproduces `repro:`, the fix comes after it
+- after the plan, run `ai-factory gcf plan check <item-id>`: a failure is fixed in the plan before implementation

package/injections/review-pillars.md

@@ -1,7 +1,8 @@
 ## GCF: pillar and constraint review (from gcf-aif-ext)
 
 gcf_review:
-- when `gcf/` exists and the change implements a card, read the card and `gcf/PILLARS.md` when it exists (it stays absent until the pillars interview)
-- check the diff against every negative constraint of the card: name each violation with file and line
+- when `gcf/` exists and the change implements a work item, read the item and `gcf/PILLARS.md` when it exists (it stays absent until the pillars interview)
+- check the diff against every negative constraint of the item: name each violation with file and line
 - check the diff against each pillar's review question: a contradiction is a finding, not a note
-- numeric feel values in code outside the card's envelope: report the value and the envelope bounds
+- numeric feel values in code outside the item's envelope: report the value and the envelope bounds
+- a capability the diff adds, changes or removes that the item's `live:` delta does not name: a finding

package/lib/anchors.js

@@ -26,6 +26,28 @@ const EMPTY_HASH = h8('');
 // human with D1 questions about a GDD nobody edited.
 export const HASH_VERSION = 2;
 
+/**
+ * Line indexes inside a closed fenced block: a `# comment` there is code, not a heading. A fence
+ * that never closes is ignored — a stray ``` must not swallow every heading after it.
+ */
+function fencedLines(lines) {
+  const inside = new Set();
+  let open = -1;
+  let fence = '';
+  for (const [i, line] of lines.entries()) {
+    const f = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+    if (!f) continue;
+    if (open < 0) [open, fence] = [i, f[1]];
+    // CommonMark: the closing fence is the same character, at least as long, with no info string.
+    else if (f[1][0] === fence[0] && f[1].length >= fence.length && !f[2].trim()) {
+      for (let j = open + 1; j < i; j++) inside.add(j);
+      open = -1;
+    }
+  }
+
+  return inside;
+}
+
 /**
  * Split markdown into heading-addressed sections.
  * Text before the first heading is `GDD#preamble`.
@@ -44,8 +66,9 @@ export function splitSections(markdown) {
     sections.push(current);
   };
 
+  const fenced = fencedLines(lines);
   for (const [i, line] of lines.entries()) {
-    const m = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+    const m = !fenced.has(i) && line.match(/^(#{1,6})\s+(.+?)\s*$/);
     if (m) {
       flush();
       current = { heading: m[2], level: m[1].length, start: i + 1, lines: [] };
@@ -155,27 +178,10 @@ export async function readSection(projectDir, baseName, anchor) {
   return splitSections(await readFile(file, 'utf8')).find((s) => s.anchor === anchor) ?? null;
 }
 
-/**
- * Provenance check over gcf/backlog.md (GCF-PRD §11.2.3): every line citing `src: GDD#…`
- * must carry `q: "…"`, and the quote must be a verbatim substring of that section in some
- * gcf/source/ file. Line wraps in the GDD are not edits, so runs of whitespace compare equal.
- */
-export async function checkQuotes(projectDir) {
-  const root = path.join(path.resolve(projectDir), 'gcf');
-  const backlog = path.join(root, 'backlog.md');
-  if (!existsSync(backlog)) return [];
-  const bodies = await sourceBodies(path.join(root, 'source'));
-
-  return (await readFile(backlog, 'utf8'))
-    .split('\n')
-    .map((line) => quoteProblem(line, bodies))
-    .filter((p) => p !== null);
-}
-
 const ws = (t) => String(t).replace(/\s+/g, ' ').trim();
 
 /** anchor -> whitespace-collapsed bodies across every gcf/source/ file */
-async function sourceBodies(sourceDir) {
+export async function sourceBodies(sourceDir) {
   /** @type {Map<string, string[]>} */
   const bodies = new Map();
   if (!existsSync(sourceDir)) return bodies;
@@ -188,20 +194,39 @@ async function sourceBodies(sourceDir) {
   return bodies;
 }
 
-/** The provenance problem of one backlog line, or null when it has none or cites no GDD. */
-function quoteProblem(line, bodies) {
-  const id = line.match(/^- (cand-\d+)/)?.[1];
-  const anchor = line.match(/\|\s*src:\s*(GDD#[\w-]+)/)?.[1];
-  if (!id || !anchor) return null;
-  // The closing quote is the one before the next field, so a quote may itself hold `"`.
-  const quote = line.match(/\|\s*q:\s*"(.*?)"\s*(?:\||$)/)?.[1];
-  const found = bodies.get(anchor);
-  /** @type {string | null} */
-  let problem = null;
-  if (!found) problem = 'anchor not found in gcf/source/';
-  else if (!quote) problem = 'no q: "<verbatim quote>"';
-  else if (!found.some((b) => b.includes(ws(quote))))
-    problem = 'quote is not verbatim in the section';
-
-  return problem && { id, anchor, problem };
+/** gcf-relative files that cite anchors: units, work items, and the `sections:` of questions. */
+async function anchorCiters(root) {
+  const out = [];
+  for (const dir of ['design', 'work']) {
+    if (!existsSync(path.join(root, dir))) continue;
+    const names = (await readdir(path.join(root, dir))).filter((n) => n.endsWith('.md'));
+    out.push(...names.map((n) => `${dir}/${n}`));
+  }
+
+  if (existsSync(path.join(root, 'open-questions.md'))) out.push('open-questions.md');
+
+  return out;
+}
+
+/**
+ * A renamed heading changes its anchor (GCF-PRD §11.6): rewrite `GDD#<from>` to `GDD#<to>` in
+ * design/, work/ and open-questions.md, so provenance, `source:` and `sections:` follow the
+ * section instead of pointing at an anchor that no longer exists. Returns the files it changed.
+ */
+export async function rewriteAnchors(projectDir, renamed) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const changed = [];
+  for (const rel of renamed.length ? await anchorCiters(root) : []) {
+    const file = path.join(root, rel);
+    const text = await readFile(file, 'utf8');
+    const next = renamed.reduce(
+      (t, r) => t.replace(new RegExp(`${r.from}(?![\\w-])`, 'g'), () => r.to),
+      text,
+    );
+    if (next === text) continue;
+    await writeFile(file, next, 'utf8');
+    changed.push(rel);
+  }
+
+  return changed;
 }