gcf-aif-ext 0.4.0 → 0.5.0

package/README.md

@@ -50,6 +50,29 @@ 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.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:
+
+- An unplayed item's `frozen:` now covers its `live:` delta as well as its body. Items closed by 0.4.0 keep working. `tune`, `kill` and `drop` refuse an unplayed item edited since its close: restore the file first.
+- With `PILLARS.md` present, a mechanic or resource with `pillars: TBD` is not ready to `take`. `gcf pillar rename` and `gcf pillar retire` revise a pillar where units and items cite it.
+- `design check` blocks a `depends:` cycle and an id with two terminal lines (a merge of branches).
+- The commit gate refuses a `LIVE.md` ref into `gcf/` that names no file.
+- `gcf init` writes an agent instructions block into `AGENTS.md` (and into a `CLAUDE.md` that does not import it), between `<!-- gcf:start -->` and `<!-- gcf:end -->`. Any agent session then knows where work lives and which commands own it. Run `gcf init` again after an update to refresh it.
+
 ### Upgrading from 0.3.x
 
 0.4.0 replaces the cards with work items and does **not migrate** them. A schema 2 card in `gcf/cards/` is no longer read: while any is left there, the pre-commit gate refuses every commit that touches `gcf/`, and `gcf audit` reports it first. In order:
@@ -97,7 +120,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',
 ];
 
 /**
@@ -151,7 +152,8 @@ function registerInit(gcf, program) {
   gcf
     .command('init')
     .description(
-      'Create the gcf/ skeleton from templates (idempotent, never overwrites); offers the harness',
+      'Create the gcf/ skeleton from templates (idempotent, never overwrites) and the agent ' +
+        'instructions block in AGENTS.md (replaced in place); offers the harness',
     )
     .option('--harness', `also install ${HARNESS} and run gcf-harness init (Claude Code only)`)
     .option('--no-harness', 'do not offer the harness')
@@ -160,6 +162,10 @@ function registerInit(gcf, program) {
       await seedSkeleton(root);
       const { writeIndex } = await lib('index-gen');
       await writeIndex(root);
+      // Re-run on every update: the block is replaced in place, so it follows the extension.
+      const block = await readFile(path.join(EXT_ROOT, 'templates', 'agents-block.md'), 'utf8');
+      const agents = await (await lib('agents-block')).writeAgentsBlock(process.cwd(), block);
+      if (agents.length) console.log(`agent instructions written: ${agents.join(', ')}`);
       console.log(
         'gcf/ ready. Write PILLARS.md through /gcf-init, then import a GDD with /gcf-ingest ' +
           'or start the design with /gcf-vision.',
@@ -239,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')
@@ -254,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)})` : '');
@@ -570,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(), {
@@ -584,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);
     });
@@ -700,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
@@ -733,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')
@@ -780,8 +949,36 @@ function registerLint(gcf) {
     });
 }
 
+function registerPillar(gcf) {
+  const pillar = gcf
+    .command('pillar')
+    .description('Revise PILLARS.md where units and items cite it (the human decides)');
+  pillar
+    .command('rename <from> <to>')
+    .description('Rename a pillar id in PILLARS.md, units and items (commit gcf(pillar))')
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (from, to, o) => {
+      const r = await (await lib('pillars')).renamePillar(process.cwd(), from, to, o);
+      console.log(`renamed ${from} → ${to}${shortHash(r.hash)}`);
+    });
+  pillar
+    .command('retire <id>')
+    .description('Take a pillar out; units left with none read pillars: TBD (commit gcf(pillar))')
+    .requiredOption('--reason <text>', 'why the game no longer holds it')
+    .option('--no-commit', 'skip the commit (tests only)')
+    .action(async (id, o) => {
+      const r = await (await lib('pillars')).retirePillar(process.cwd(), id, o);
+      console.log(`retired ${id}${shortHash(r.hash)}`);
+      if (r.bare.length)
+        console.log(
+          `items now citing no pillar — give each one or accept it: ${r.bare.join(', ')}`,
+        );
+    });
+}
+
 export function register(program) {
   const gcf = program.command('gcf').description('Game Context Framework core');
+  registerPillar(gcf);
   registerInit(gcf, program);
   registerIndex(gcf);
   registerContext(gcf);
@@ -800,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.0",
+  "version": "0.5.0",
   "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 { bodyHash } 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,42 +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 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`);
-}
+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 — ` +
@@ -104,25 +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.
-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 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/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/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/context.js

@@ -5,7 +5,7 @@ import { listItems, listSystems, readConfig, tokensEst } from './gcf-paths.js';
 
 /**
  * Readset assembly — the whole command is deterministic (GCF-PRD §9.1, §10.1):
- * PILLARS + LIVE.md + touched systems + the item + 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, itemId) {
@@ -36,14 +36,19 @@ export async function buildContext(projectDir, itemId) {
   };
 }
 
-/** PILLARS, LIVE.md, touched systems, the item, its depends — in order, skipping absent files. */
+/**
+ * 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');
@@ -54,6 +59,8 @@ async function readsetFiles(root, item, items) {
   }
 
   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}`);