gcf-aif-ext 0.3.0 → 0.4.1

package/extension.json

@@ -1,24 +1,41 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-aif-ext",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",
     "skills/gcf-adopt",
     "skills/gcf-card",
     "skills/gcf-verdict",
+    "skills/gcf-triage",
     "skills/gcf-audit",
     "skills/gcf-vision",
     "skills/gcf-debate",
     "skills/gcf-ingest"
   ],
   "commands": [
-    { "name": "gcf", "description": "Game Context Framework core", "module": "commands/gcf.js" }
+    {
+      "name": "gcf",
+      "description": "Game Context Framework core",
+      "module": "commands/gcf.js"
+    }
   ],
   "injections": [
-    { "target": "aif-plan", "position": "append", "file": "./injections/plan-context.md" },
-    { "target": "aif-review", "position": "append", "file": "./injections/review-pillars.md" },
-    { "target": "aif-commit", "position": "append", "file": "./injections/commit-status.md" }
+    {
+      "target": "aif-plan",
+      "position": "append",
+      "file": "./injections/plan-context.md"
+    },
+    {
+      "target": "aif-review",
+      "position": "append",
+      "file": "./injections/review-pillars.md"
+    },
+    {
+      "target": "aif-commit",
+      "position": "append",
+      "file": "./injections/commit-status.md"
+    }
   ]
 }

package/hooks/pre-commit.js

@@ -6,13 +6,15 @@
 import { existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
-import { 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 { matchesFrozen } from '../lib/work-ops.js';
+import { checkLive } from '../lib/live.js';
 
 const projectDir = process.cwd();
 const root = path.join(projectDir, 'gcf');
@@ -26,36 +28,58 @@ 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: cards and units are found by reading directories, so an uncommitted file
+  // 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 unstaged = git(['diff', '--name-only', '--', root]);
-  const untracked = git(['ls-files', '--others', '--exclude-standard', '--', root]);
-  if (unstaged || untracked) {
+  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)',
     );
   }
 }
 
+// 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 ledger.cards) {
+for (const c of ledger.items) {
   const errors = [
-    ...validateCard(c.data),
+    ...validateItem(c.data),
     ...validateUntil(c.body),
     ...(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 await listSystems(root)) {
@@ -63,35 +87,40 @@ for (const s of await listSystems(root)) {
   if (errors.length) fail(`systems/${s.name}: ${errors[0]}`);
 }
 
-// A unit or card leaving without its move (take, done, drop, a verdict) loses its reason, not
-// its integrity: a card or unit 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.
+// An unplayed item's body and live: are the source of its systems/ lines and its capability
+// (Methodology §5.4): edited after its close, a tune or a kill would take the wrong ones out.
+for (const c of ledger.items.filter((x) => x.data.status === 'unplayed')) {
+  if (!matchesFrozen(c))
+    fail(
+      `work/${c.name}: an unplayed item's body and live: are frozen — restore them, tune it, ` +
+        'then edit',
+    );
+}
+
+// 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 cards/ without done, drop or a verdict — ` +
+    `gcf pre-commit: warning: ${id} left design/ or work/ without a move — ` +
       'no history or graveyard line keeps why',
   );
 }
 
-// Design model and card bodies: every finding of severity `block` refuses the commit.
+// 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}`);
 
-// 4: a built card must not sit on an unplayed dependency — a live card, or a unit still in
-// design/. A collapsed, done or killed id is played; an unknown one is a typo (design check).
-for (const c of ledger.cards.filter((x) => x.data.status === 'built')) {
-  for (const dep of c.data.depends ?? []) {
-    const live = ledger.where(dep).live[0];
-    if (live)
-      fail(`${c.data.id} is built on top of unplayed ${dep} (${live.state} — GCF-PRD §7.2)`);
-  }
-}
+// 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.
 
-for (const c of ledger.cards) {
-  const unknown = (c.data.depends ?? []).find((d) => !ledger.known(d));
-  if (unknown)
-    fail(`${c.data.id} depends on unknown ${unknown} (no unit, card, history or graveyard line)`);
-}
+// LIVE.md form: a malformed record would hide from every reader of the snapshot. A broken ref
+// into gcf/ is this commit's own doing (a move deleted the file); one into the code is not
+// refused — a code commit outside gcf/ may have moved it and the gate never saw that.
+const live = await checkLive(projectDir);
+const form = live.problems[0] ?? live.issues.find((i) => /summary|twice|refs gcf\//.test(i));
+if (form) fail(`LIVE.md: ${form}`);
 
 // 5: П2 linter over systems docs.
 for (const s of await listSystems(root)) {

package/injections/commit-status.md

@@ -1,7 +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 the commit makes a hard unit's tests green, run `ai-factory gcf done <id>` after it: the unit leaves `gcf/design/` in its own fixed-format commit
+- 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,9 +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
-- an id in `depends:` that still lives as a card or as a unit of `gcf/design/` is unplayed: do not plan on top of it, stop
-- shape the plan by the card slots: intent, behavior, refusal, boundaries, persistence, feel envelopes, contract, interactions, constraints, miss criterion
-- when the task names a hard unit (rule, constraint, entity), there is no card: read its section only, from the file `ai-factory gcf where <id>` names, and plan its tests from `statement`, `threshold` or `fields`
+- 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/agents-block.js

@@ -0,0 +1,66 @@
+// The project's instructions for any agent (Methodology §1): a session that runs no gcf skill
+// still has to know that work lives in gcf/ and which commands own it. `gcf init` keeps one
+// marked block in AGENTS.md, and in a CLAUDE.md that does not import AGENTS.md already.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { atomicWrite } from './safe-path.js';
+
+export const START = '<!-- gcf:start -->';
+export const END = '<!-- gcf:end -->';
+
+/** `text` with the marked block put in place of the old one, or appended. */
+export function withBlock(text, block) {
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const body = `${START}${eol}${block.trim().replace(/\r?\n/g, eol)}${eol}${END}`;
+  const at = text.indexOf(START);
+  const end = text.indexOf(END, at);
+  if (at >= 0 && end > at) return text.slice(0, at) + body + text.slice(end + END.length);
+  // One blank line between the old text and the block, however the text ended.
+  const sep = !text || text.endsWith(eol + eol) ? '' : eol.repeat(text.endsWith(eol) ? 1 : 2);
+
+  return `${text}${sep}${body}${eol}`;
+}
+
+/** Whether the AIF project lists Claude Code among its agents (`.ai-factory.json`). */
+async function claudeAgent(projectDir) {
+  const file = path.join(projectDir, '.ai-factory.json');
+  if (!existsSync(file)) return false;
+  try {
+    const cfg = JSON.parse(await readFile(file, 'utf8'));
+
+    return (cfg.agents ?? []).some((a) => a?.id === 'claude');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Write the block where agents read it. AGENTS.md always gets it (created when absent — /aif
+ * writes that file, gcf-init runs after /aif). A CLAUDE.md that imports `@AGENTS.md` sees it
+ * there; one that does not gets its own copy. With Claude among the AIF agents and no
+ * CLAUDE.md, one is created importing AGENTS.md. Returns the files written, relative.
+ */
+export async function writeAgentsBlock(projectDir, block) {
+  const written = [];
+  const put = async (name, base) => {
+    const file = path.join(projectDir, name);
+    const old = existsSync(file) ? await readFile(file, 'utf8') : base;
+    const next = withBlock(old, block);
+    if (next === old && existsSync(file)) return;
+    await atomicWrite(file, next);
+    written.push(name);
+  };
+
+  await put('AGENTS.md', '');
+  const claude = path.join(projectDir, 'CLAUDE.md');
+  if (existsSync(claude)) {
+    const text = await readFile(claude, 'utf8');
+    if (!/^@AGENTS\.md\s*$/m.test(text) || text.includes(START)) await put('CLAUDE.md', text);
+  } else if (await claudeAgent(projectDir)) {
+    await atomicWrite(claude, '@AGENTS.md\n');
+    written.push('CLAUDE.md');
+  }
+
+  return written;
+}

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: [] };
@@ -171,10 +194,10 @@ export async function sourceBodies(sourceDir) {
   return bodies;
 }
 
-/** gcf-relative files that cite anchors: units, cards, and the `sections:` of questions. */
+/** 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', 'cards']) {
+  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}`));
@@ -187,7 +210,7 @@ async function anchorCiters(root) {
 
 /**
  * A renamed heading changes its anchor (GCF-PRD §11.6): rewrite `GDD#<from>` to `GDD#<to>` in
- * design/, cards/ and open-questions.md, so provenance, `source:` and `sections:` follow the
+ * 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) {