gcf-aif-ext 0.4.1 → 0.5.1

package/README.md

@@ -50,6 +50,25 @@ Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook. Run `ai-f
 
 On Windows, run `extension add` and `extension update` from PowerShell or cmd, not Git Bash: the installer unpacks with `tar`, and Git Bash's GNU tar reads `C:\…` as a remote host (`Cannot connect to C: resolve failed`). The Windows `tar.exe` handles it.
 
+### 0.5.1
+
+- A provenance record `assumed: q-NNN` must name a record still in `gcf/open-questions.md` (M9). A D2 record lives until its `until:` fires; once the human confirms the value, cite `answer: q-NNN` instead and remove it. After updating, run `ai-factory gcf design check`: every citation of a removed question blocks the commit gate until it is rewritten.
+- An unplayed item's body is frozen, so a word added to the glossary or a removed question is reported there, not blocked.
+- The `AGENTS.md` block has no `##` heading any more: a CNL-P guide is flat. A project that checks `AGENTS.md` with `cnlp check` adds `gcf_context`, `gcf_work`, `gcf_forbidden` and `gcf_skills` to `custom_sections` of its guide profile.
+
+### 0.5.0
+
+The run layer of the methodology. Update both extensions together — `gcf-harness-aif-ext` 0.6.0 requires this core — and run `ai-factory gcf init` to refresh the agent block in `AGENTS.md`. New commands:
+
+- `gcf verify <id>` — the auto-DoD in code: the commit gate's checks, the item's `live:` delta against `LIVE.md`, then `dod.build` and `dod.test`. Fill both in `gcf/config.yml`; an empty one fails, `none` says the project has no such step.
+- `gcf phase` and `gcf phase next [--reason]` — the project phase (prototype → vertical-slice → alpha → beta → release → live), kept as `phase:` in the `LIVE.md` frontmatter, with exit criteria checked in code. `item new` and `take` refuse a type the phase does not take. **A project with no phase yet is in prototype, and a prototype takes no `asset` item**: move the phase on (`gcf phase next --reason "…"`) if your game is past it. A `phases:` list in `config.yml` replaces the set.
+- A release item carries `version:` and `channel:` (`item new <id> --type release --release 1.0.0 --channel steam`); its end writes the `release:` block of `LIVE.md`. `item new --milestone <name>` tags an item.
+- `gcf playtest session [--build]` — the build of main and a checklist per item: what to check, how to get there, what to feel.
+- `gcf worktree <id>`, `gcf verify <id> --mark`, `gcf integrate [<id>…]` — an item in its own worktree, the `GCF-Verified` trailer, the merge into main and the item's move. Every committed move now holds `.gcf-session/main.lock`.
+- `gcf board [--json]` — everything a board shows in one read.
+
+A move that writes `LIVE.md` now refuses a malformed one instead of rewriting it without what it could not read: fix the file by hand in its own commit.
+
 ### 0.4.1
 
 A fix release over 0.4.0; update in place. What you may notice:
@@ -107,7 +126,9 @@ Removal leaves `gcf/` and `cnlp.config.json` in place. It also leaves the pre-co
 
 - work items — `take <ids...> [--feature <id>]`, `item new <id> --type <type>`, `submit`, `close`, `verdict <id> keep|tune|kill`, `decide <id> go|no|wontfix|known|close|continue|kill`, `block`, `unblock`, `drop`, `done`, `where`
 - inbox and snapshot — `inbox [add <text> | drop <in-id>]`, `live`, `live check`
-- runs and play — `context`, `plan check <id>`, `playtest`, `audit`
+- runs and play — `context`, `plan check <id>`, `verify <id>`, `playtest`, `playtest session [--build]`, `audit`
+- project phase and board — `phase`, `phase next [--reason]`, `board [--json]` (everything a board shows, in one read)
+- branches — `worktree <id>`, `verify <id> --mark`, `integrate [<id>...]`: a run in its own worktree, the `GCF-Verified` trailer, the merge into main and the move; every committed move holds `.gcf-session/main.lock`
 - design and sources — `design check`, `design export`, `design import`, `design migrate`, `anchor`, `section`, `quotes`, `lint`
 - setup — `init`, `index`, `hooks-install`
 

package/commands/gcf.js

@@ -74,6 +74,7 @@ const UNION = [
   'gcf/history.md merge=union',
   'gcf/graveyard.md merge=union',
   'gcf/inbox.md merge=union',
+  'gcf/.metrics/*.csv merge=union',
 ];
 
 /**
@@ -244,8 +245,44 @@ function registerAudit(gcf) {
     });
 }
 
+/** How the session's build went: built, no step, failed, or left to the human. */
+function buildText(b) {
+  if (!b) return 'build it from this commit';
+  if (!b.ok) return b.problems.join('; ');
+
+  return b.skipped ? 'no build step (dod.build: none)' : 'built with dod.build';
+}
+
+/** The session sheet: the build, then per item what to check and how to get there. */
+function sessionText(s) {
+  const build = buildText(s.build);
+  const lines = [
+    s.commit ? `build: ${s.branch} @ ${s.commit} — ${build}` : 'build: no commit to build yet',
+    // shortcut: the main branch is named main; read the remote default when a project differs.
+    ...(s.branch !== 'main' ? ['warning: not on main — the session plays main'] : []),
+    ...(s.dirty ? ['warning: uncommitted changes — the build is not the commit'] : []),
+  ];
+  if (!s.items.length) return [...lines, 'nothing waits for a playtest'].join('\n');
+  for (const c of s.items) {
+    lines.push(
+      '',
+      `[ ] ${c.id} (${c.status}) [${c.system.join(',')}] ${c.title ?? c.intent ?? ''}`,
+    );
+    lines.push(`    check: ${c.question}`);
+    for (const r of c.reach) lines.push(`    try: ${r}`);
+    for (const f of c.feel) lines.push(`    feel: ${f}`);
+  }
+
+  return [
+    ...lines,
+    '',
+    'after play: a verdict per item — /gcf-verdict <id> keep|tune|kill;',
+    'free notes — ai-factory gcf inbox add --source playtest "<note>"',
+  ].join('\n');
+}
+
 function registerPlaytest(gcf) {
-  gcf
+  const playtest = gcf
     .command('playtest')
     .description('List items awaiting a verdict and unplayed ones, with their questions')
     .option('--json', 'machine output')
@@ -259,6 +296,18 @@ function registerPlaytest(gcf) {
           : 'nothing waits for a playtest',
       );
     });
+  playtest
+    .command('session')
+    .description('A playtest session: the build of main and the checklist, built from the items')
+    .option('--build', 'run dod.build first')
+    .option('--json', 'machine output')
+    .action(async (o) => {
+      const r = await (
+        await lib('playtest-list')
+      ).playtestSession(process.cwd(), { build: Boolean(o.build) });
+      out(o.json, r, sessionText);
+      if (r.build && !r.build.ok) process.exitCode = 1;
+    });
 }
 
 const shortHash = (h) => (h ? ` (${h.slice(0, 7)})` : '');
@@ -575,6 +624,9 @@ function registerItem(gcf) {
     .option('--blocked <why>', 'start blocked, e.g. "file needed" for an asset')
     .option('--from <in-id>', 'the inbox entry it comes from: erased')
     .option('--reopens <id>', 'the ended id this item reworks')
+    .option('--milestone <name>', 'the milestone of game.md it belongs to')
+    .option('--release <version>', 'a release: the version it ships')
+    .option('--channel <name>', 'a release: where it ships, e.g. steam')
     .action(async (id, o) => {
       const { newItem } = await lib('work-ops');
       const r = await newItem(process.cwd(), {
@@ -589,6 +641,9 @@ function registerItem(gcf) {
         blocked: o.blocked,
         from: o.from,
         reopens: o.reopens,
+        milestone: o.milestone,
+        version: o.release,
+        channel: o.channel,
       });
       console.log(r.item);
     });
@@ -705,10 +760,16 @@ function registerLive(gcf) {
       const { gcfRoot } = await lib('gcf-paths');
       const l = await (await lib('live')).readLive(gcfRoot());
       const rows = (list) => list.map((r) => `  ${r.id}: ${r.summary}`);
+      const r = l.release;
       out(o.json, l, (x) =>
-        ['capabilities:', ...rows(x.capabilities), 'known-issues:', ...rows(x.knownIssues)].join(
-          '\n',
-        ),
+        [
+          ...(x.phase ? [`phase: ${x.phase}`] : []),
+          ...(r ? [`release: ${r.version} to ${r.channel} on ${r.date}`] : []),
+          'capabilities:',
+          ...rows(x.capabilities),
+          'known-issues:',
+          ...rows(x.knownIssues),
+        ].join('\n'),
       );
     });
   live
@@ -738,6 +799,109 @@ function registerPlan(gcf) {
     });
 }
 
+function registerVerify(gcf) {
+  gcf
+    .command('verify <id>')
+    .description('auto-DoD of a ready item: GCF checks, its live: delta, dod.build, dod.test')
+    .option('--mark', 'in its worktree: green and committed → commit the GCF-Verified trailer')
+    .option('--json', 'machine output')
+    .action(async (id, o) => {
+      const r = o.mark
+        ? await (await lib('integrate')).markVerified(process.cwd(), id)
+        : await (await lib('verify')).verifyItem(process.cwd(), id);
+      out(o.json, r, (x) =>
+        [
+          ...x.checks.flatMap((c) =>
+            c.ok
+              ? [`${c.name}: ${c.skipped ? 'none' : 'ok'}`]
+              : c.problems.map((p) => `${c.name}: ${p}`),
+          ),
+          ...(x.marked ? [`marked: GCF-Verified: ${id}`] : []),
+        ].join('\n'),
+      );
+      if (!r.ok) process.exitCode = 1;
+    });
+}
+
+function registerBoard(gcf) {
+  gcf
+    .command('board')
+    .description('Everything a board shows in one read: phase, columns, plans, inbox, questions')
+    .option('--json', 'machine output')
+    .action(async (o) => {
+      const r = await (await lib('board')).board(process.cwd());
+      const tag = (i) =>
+        `${i.id}${i.plan?.tasks !== undefined ? ` ${i.plan.done}/${i.plan.tasks}` : ''}` +
+        `${i.running ? ' (running)' : ''}${i.verified ? ' (verified)' : ''}`;
+      const byId = new Map(r.items.map((i) => [i.id, i]));
+      out(o.json, r, (x) =>
+        [
+          `phase: ${x.phase.phase ?? x.phase.error}`,
+          ...Object.entries(x.columns).map(
+            ([s, ids]) => `${s}: ${ids.map((id) => tag(byId.get(id))).join(', ') || '-'}`,
+          ),
+          `wip: ${x.wip.verdict}/${x.wip.limit}`,
+          `inbox: ${x.inbox.length}, open questions: ${x.questions.length}`,
+        ].join('\n'),
+      );
+    });
+}
+
+function registerIntegrate(gcf) {
+  gcf
+    .command('worktree <id>')
+    .description('A worktree for a ready item: .gcf-session/worktrees/<id> on branch work/<id>')
+    .option('--json', 'machine output')
+    .action(async (id, o) => {
+      const r = await (await lib('integrate')).addWorktree(process.cwd(), id);
+      out(o.json, r, (x) => `${x.path} (${x.branch}${x.created ? ', new' : ', resumed'})`);
+    });
+  gcf
+    .command('integrate [ids...]')
+    .description('Merge verified work/<id> branches into main and record each move; none: all')
+    .option('--json', 'machine output')
+    .action(async (ids, o) => {
+      const r = await (await lib('integrate')).integrate(process.cwd(), ids ?? []);
+      const line = (x) =>
+        x.skipped ?? x.conflict ?? `${x.id}: ${x.move}${x.reason ? ` (${x.reason})` : ''}`;
+      out(o.json, r, (l) => (l.length ? l.map(line).join('\n') : 'no verified branch'));
+      if (r.some((x) => x.conflict)) process.exitCode = 1;
+    });
+}
+
+function registerPhase(gcf) {
+  const phase = gcf
+    .command('phase')
+    .description('The project phase (Methodology §10): what it takes, its exit criteria')
+    .option('--json', 'machine output')
+    .action(async (o) => {
+      const r = await (await lib('phase')).phaseStatus(process.cwd());
+      const mark = { true: 'met', false: 'NOT met', null: 'check by hand' };
+      out(o.json, r, (x) =>
+        [
+          `phase: ${x.phase}${x.next ? ` (next: ${x.next})` : ' (last)'}`,
+          `takes: ${x.accepts.join(', ')}`,
+          ...(x.with_reopens.length ? [`with reopens: ${x.with_reopens.join(', ')}`] : []),
+          ...x.criteria.map((c) => `exit ${c.name}: ${mark[String(c.met)]} — ${c.detail}`),
+        ].join('\n'),
+      );
+    });
+  phase
+    .command('next')
+    .description('Move to the next phase (commit gcf(phase)); the operator decides')
+    .option('--reason <text>', 'why, when an exit criterion is not met')
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (o) => {
+      const r = await (
+        await lib('phase')
+      ).nextPhase(process.cwd(), { reason: o.reason ?? '', commit: o.commit });
+      console.log(
+        `${r.from} → ${r.to}${r.forced.length ? ` (unmet: ${r.forced.join(', ')})` : ''}` +
+          shortHash(r.hash),
+      );
+    });
+}
+
 function registerHooksInstall(gcf) {
   gcf
     .command('hooks-install')
@@ -833,6 +997,10 @@ export function register(program) {
   registerInbox(gcf);
   registerLive(gcf);
   registerPlan(gcf);
+  registerVerify(gcf);
+  registerIntegrate(gcf);
+  registerBoard(gcf);
+  registerPhase(gcf);
   registerHooksInstall(gcf);
   registerLint(gcf);
 }

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-aif-ext",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

package/hooks/pre-commit.js

@@ -6,15 +6,8 @@
 import { existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
-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';
+import { gateProblems } from '../lib/gate.js';
 
 const projectDir = process.cwd();
 const root = path.join(projectDir, 'gcf');
@@ -61,45 +54,11 @@ if (staged !== null) {
   }
 }
 
-// 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.items) {
-  const errors = [
-    ...validateItem(c.data),
-    ...validateUntil(c.body),
-    ...(stemMatches(c.file, c.data.id) ? [] : [`filename must be ${c.data.id}.md`]),
-  ];
-  if (errors.length) fail(`work/${c.name}: ${errors[0]}`);
-}
-
-for (const s of await listSystems(root)) {
-  const errors = validateUntil(s.body);
-  if (errors.length) fail(`systems/${s.name}: ${errors[0]}`);
-}
-
-// 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',
-    );
-}
+const { problems, ledger } = await gateProblems(projectDir);
 
 // 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.
+// it fails M2, 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 — ` +
@@ -107,27 +66,7 @@ for (const id of ledger.vanished()) {
   );
 }
 
-// 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. 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)) {
-  const { issues } = lint(s.body);
-  if (issues.length)
-    fail(`systems/${s.name}:${issues[0].line}: ${issues[0].rule}: ${issues[0].text}`);
-}
+if (problems.length) fail(problems[0]);
 
 // 3: regenerate INDEX and stage it (deterministic artifact, not a human error).
 await writeIndex(root);

package/lib/board.js

@@ -0,0 +1,113 @@
+// `gcf board --json` (Methodology §11): everything a board shows, in one read. The board is a
+// view: it shows these data and runs the same commands as the console; nothing here is stored.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { buildLedger } from './ledger.js';
+import { readConfig } from './gcf-paths.js';
+import { readLive } from './live.js';
+import { listInbox } from './inbox.js';
+import { phaseStatus } from './phase.js';
+import { verifiedBranches, worktreeOf } from './integrate.js';
+import { resolveInside } from './safe-path.js';
+
+const COLUMNS = ['ready', 'blocked', 'awaiting-verdict', 'awaiting-decision', 'unplayed', 'parked'];
+
+/**
+ * Plan progress `{tasks, done}` from its checkboxes, null without a plan file (§3.3); a plan:
+ * outside the project or not a file reads as `{error}`, the rest of the board still shows.
+ */
+async function progress(projectDir, item) {
+  try {
+    const plan = item.data.plan ?? `.ai-factory/plans/${item.data.id}.md`;
+    const file = resolveInside(projectDir, plan);
+    if (!existsSync(file)) return null;
+    const text = await readFile(file, 'utf8');
+
+    return {
+      tasks: (text.match(/^\s*- \[[ xX]\] /gm) ?? []).length,
+      done: (text.match(/^\s*- \[[xX]\] /gm) ?? []).length,
+    };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+/** Verified branches; none outside a repository. */
+function verifiedOf(projectDir) {
+  try {
+    return new Set(verifiedBranches(projectDir));
+  } catch {
+    return new Set();
+  }
+}
+
+/** Open question records of open-questions.md: id and class. */
+async function questions(root) {
+  const file = path.join(root, 'open-questions.md');
+  if (!existsSync(file)) return [];
+
+  return (await readFile(file, 'utf8'))
+    .replace(/\r\n/g, '\n')
+    .split(/\n(?=- id:)/)
+    .flatMap((rec) => {
+      const id = rec.match(/^- id:\s*(\S+)/)?.[1];
+
+      return id ? [{ id, class: rec.match(/^\s+class:\s*(\S+)/m)?.[1] ?? null }] : [];
+    });
+}
+
+/** The phase status, or the reason it cannot be read: the board still shows the rest. */
+async function phaseOf(projectDir) {
+  try {
+    return await phaseStatus(projectDir);
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+export async function board(projectDir) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const ledger = await buildLedger(projectDir);
+  const verified = verifiedOf(projectDir);
+  const items = [];
+  for (const c of ledger.items) {
+    const id = String(c.data.id);
+    // A trailer counts only while the item waits on main for its integrate.
+    const ready = c.data.status === 'ready' && verified.has(id);
+    items.push({
+      id,
+      type: c.data.type,
+      gate: c.data.gate,
+      status: c.data.status,
+      title: c.data.title ?? null,
+      parent: c.data.parent ?? null,
+      children: c.data.children ?? [],
+      system: c.data.system ?? [],
+      ...(c.data.severity ? { severity: c.data.severity } : {}),
+      ...(c.data.blocked ? { blocked: c.data.blocked } : {}),
+      // `running` and `verify` are not stored (§4): a worktree is a run, a trailer a passed DoD.
+      running: existsSync(worktreeOf(projectDir, id)) && !ready,
+      verified: ready,
+      plan: await progress(projectDir, c),
+    });
+  }
+
+  const config = await readConfig(root);
+  const live = await readLive(root);
+
+  return {
+    phase: await phaseOf(projectDir),
+    release: live.release,
+    columns: Object.fromEntries(
+      COLUMNS.map((s) => [s, items.filter((i) => i.status === s).map((i) => i.id)]),
+    ),
+    items,
+    wip: {
+      verdict: items.filter((i) => i.status === 'awaiting-verdict').length,
+      limit: config.wip_built_limit,
+    },
+    inbox: await listInbox(root),
+    questions: await questions(root),
+  };
+}

package/lib/design-check.js

@@ -121,12 +121,14 @@ function itemsIn(text, key) {
 export const recordsIn = (text, key) =>
   readRecords(itemsIn(text, key)).records.map((r) => r.values);
 
-/** `blocks:` of open-questions.md: every reference, and the D1 ones per blocked id. */
+/** open-questions.md: every record id, every `blocks:` reference, the D1 ones per blocked id. */
 export function questionBlocks(text) {
   /** @type {Map<string, string[]>} */
   const d1 = new Map();
   const refs = [];
-  for (const rec of String(text ?? '').split(/\n(?=- id:)/)) {
+  const src = String(text ?? '');
+  const qids = new Set([...src.matchAll(/^\s*- id:\s*(\S+)/gm)].map((m) => m[1]));
+  for (const rec of src.split(/\n(?=- id:)/)) {
     const qid = rec.match(/^- id:\s*(\S+)/)?.[1];
     const ids = listOf(rec.match(/^\s+blocks:\s*(.+)$/m)?.[1] ?? '');
     if (!qid || ids === 'TBD' || !ids.length) continue;
@@ -135,7 +137,7 @@ export function questionBlocks(text) {
     for (const id of ids) d1.set(id, [...(d1.get(id) ?? []), qid]);
   }
 
-  return { d1, refs };
+  return { d1, refs, qids };
 }
 
 /** Everything outside a unit that its references resolve against. */
@@ -296,7 +298,15 @@ function recordProblem(r, ctx) {
   }
 
   if (r.answer) return /^(q-\d+|manual)$/.test(r.answer) ? null : 'answer is q-NNN or manual';
-  if (r.assumed) return /^q-\d+$/.test(r.assumed) ? null : 'assumed is q-NNN';
+  if (r.assumed) {
+    if (!/^q-\d+$/.test(r.assumed)) return 'assumed is q-NNN';
+
+    // The D2 record is what the readset and the human's skim list see: it outlives its citation.
+    return ctx.questions.qids.has(r.assumed)
+      ? null
+      : `assumed: ${r.assumed} is not in open-questions.md - a D2 record stays until its ` +
+          `until: fires; once the human confirms the value, cite answer: ${r.assumed} instead`;
+  }
 
   return 'a record carries src + quote, answer, or assumed';
 }
@@ -326,6 +336,9 @@ function uncovered(values, records) {
 export const isDrift = (problem) =>
   /^(quote is not verbatim|GDD#\S+ is not an anchor)/.test(problem ?? '');
 
+/** The D2 record an `assumed:` cites left open-questions.md. */
+const isGone = (problem) => /^assumed: q-\d+ is not in open-questions/.test(problem ?? '');
+
 /** M9: provenance records are well formed, quotes verbatim, every GDD-sourced slot backed. */
 function provenanceIssues(u, values, ctx) {
   const records = provenanceOf(u.body);
@@ -446,11 +459,16 @@ async function checkItem(item, ctx, ledger) {
   const values = slotValues(item.body, profile).filter((v) => !OPERATOR_BLOCKS.includes(v.block));
   for (const v of values.filter((x) => isTbd(x.value)))
     add('M1', v.line, `a unit in work carries no TBD: ${v.block}`);
-  for (const [c, line, m] of valueIssues(values, ctx)) add(c, line, m);
+  // An unplayed body is frozen (§5.4): a later glossary word or unit, or a gone question, cannot
+  // be fixed there, only reported until a tune or a kill takes the item back.
+  const frozen = item.data.status === 'unplayed' ? 'report' : 'block';
+  for (const [c, line, m] of valueIssues(values, ctx)) add(c, line, m, frozen);
   for (const r of provenanceOf(item.body)) {
     const problem = recordProblem(r, ctx);
     // An item's quotes go stale when the GDD moves on: that is a D1 for the human, not a gate.
-    if (problem) add('M9', r.line, problem, isDrift(problem) ? 'report' : 'block');
+    // A gone question is outside the frozen body too; a malformed record was malformed at close.
+    const sev = isDrift(problem) ? 'report' : isGone(problem) ? frozen : 'block';
+    if (problem) add('M9', r.line, problem, sev);
   }
 
   return issues;

package/lib/gate.js

@@ -0,0 +1,106 @@
+// The GCF checks of the pre-commit gate (GCF-PRD §13.1) over the working tree, cheap ones first.
+// The gate refuses on the first problem; `gcf verify` reports them all as the GCF part of the DoD.
+import path from 'node:path';
+import { listSystems, legacyCards, readConfig } from './gcf-paths.js';
+import { phasesOf } from './phase.js';
+import { validateItem, validateUntil } from './validate-item.js';
+import { stemMatches } from './id.js';
+import { lint } from './linter.js';
+import { buildLedger } from './ledger.js';
+import { designCheck } from './design-check.js';
+import { matchesFrozen } from './work-ops.js';
+import { checkLive } from './live.js';
+
+/** Problems of form: legacy cards, item frontmatter and filenames, `until` grammar. */
+function formProblems(root, ledger, systems) {
+  const problems = [];
+  // 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)
+    problems.push(
+      `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/',
+    );
+
+  // 1-2: frontmatter validity, storable statuses, until grammar, filename invariant.
+  for (const c of ledger.items) {
+    const errors = [
+      ...validateItem(c.data),
+      ...validateUntil(c.body),
+      ...(stemMatches(c.file, c.data.id) ? [] : [`filename must be ${c.data.id}.md`]),
+    ];
+    if (errors.length) problems.push(`work/${c.name}: ${errors[0]}`);
+  }
+
+  for (const s of systems) {
+    const errors = validateUntil(s.body);
+    if (errors.length) problems.push(`systems/${s.name}: ${errors[0]}`);
+  }
+
+  return problems;
+}
+
+/** The `phases:` of config.yml, and the LIVE.md phase among them (Methodology §10). */
+async function phaseProblems(root, phase) {
+  let names;
+  try {
+    names = phasesOf(await readConfig(root)).map((p) => p.name);
+  } catch {
+    // A broken config is for the command that reads it to refuse: a kill must still commit.
+    return [];
+  }
+
+  return phase && !names.includes(phase)
+    ? [`LIVE.md: phase ${phase} is not a phase of the project (${names.join(', ')})`]
+    : [];
+}
+
+/** Every problem the gate refuses a commit for, one line each, and the ledger it read. */
+export async function gateProblems(projectDir) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const ledger = await buildLedger(projectDir);
+  const systems = await listSystems(root);
+  const problems = formProblems(root, ledger, systems);
+  // The checks below read these files and trust their form.
+  if (problems.length) return { problems, ledger };
+
+  // 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))
+      problems.push(
+        `work/${c.name}: an unplayed item's body and live: are frozen — restore them, tune it, ` +
+          'then edit',
+      );
+  }
+
+  // Design model and item bodies: every finding of severity `block` refuses the commit.
+  for (const i of (await designCheck(projectDir)).issues.filter((x) => x.severity === 'block'))
+    problems.push(`${i.file}:${i.line}: ${i.check}: ${i.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. 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,
+    ...live.issues.filter((i) => !live.problems.includes(i) && /summary|twice|refs gcf\//.test(i)),
+  ];
+  problems.push(...form.map((f) => `LIVE.md: ${f}`));
+  // A phase the project does not name would refuse every later item new and take.
+  problems.push(...(await phaseProblems(root, live.phase)));
+
+  // 5: П2 linter over systems docs.
+  for (const s of systems) {
+    const { issues } = lint(s.body);
+    if (issues.length)
+      problems.push(`systems/${s.name}:${issues[0].line}: ${issues[0].rule}: ${issues[0].text}`);
+  }
+
+  return { problems, ledger };
+}