gcf-aif-ext 0.4.0 → 0.4.1

package/README.md

@@ -50,6 +50,16 @@ 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.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:

package/commands/gcf.js

@@ -151,7 +151,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 +161,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.',
@@ -780,8 +785,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);

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.4.1",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

package/hooks/pre-commit.js

@@ -13,7 +13,7 @@ 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 { matchesFrozen } from '../lib/work-ops.js';
 import { checkLive } from '../lib/live.js';
 
 const projectDir = process.cwd();
@@ -87,11 +87,14 @@ for (const s of await listSystems(root)) {
   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.
+// 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 (bodyHash(c.body) !== c.data.frozen)
-    fail(`work/${c.name}: an unplayed item's body is frozen — tune it to change it`);
+  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
@@ -112,9 +115,11 @@ if (first) fail(`${first.file}:${first.line}: ${first.check}: ${first.message}`)
 // 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.
+// 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/.test(i));
+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.

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/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}`);

package/lib/design-check.js

@@ -496,6 +496,10 @@ function ledgerIssues(ledger) {
       out.push({ check: 'M12', severity: 'block', file, line: 1, id, message });
     if (live.length > 1)
       add(`${id} lives in ${live.length} places: ${live.map((p) => p.file).join(', ')}`);
+    // An id ends once; two ends (a merge of branches that each ended it) leave its dependents
+    // counting it as played or dead depending on which line wins.
+    if (terminal.length > 1)
+      add(`${id} ended ${terminal.join(' and ')}: keep one line in history.md or graveyard.md`);
     if (live.length && terminal.length) {
       add(
         `${id} is ${terminal.join(' and ')} already: ids are never reused — give the new one ` +
@@ -508,6 +512,49 @@ function ledgerIssues(ledger) {
   return out;
 }
 
+/**
+ * M2 over `depends:` of units and items together: a cycle never gets played — every id in it
+ * waits for the next one. Each cycle is reported once, from the id DFS meets it at.
+ */
+export function dependsCycles(ledger) {
+  /** @type {Map<string, string[]>} */
+  const graph = new Map();
+  for (const u of ledger.design.flatMap((d) => d.units)) {
+    const list = listOf(u.header.depends ?? '');
+    graph.set(u.id, Array.isArray(list) ? list : []);
+  }
+
+  for (const c of ledger.items) graph.set(String(c.data.id), c.data.depends ?? []);
+  /** @type {Issue[]} */
+  const out = [];
+  const state = new Map(); // id → 'open' while on the DFS path, 'done' after
+  const visit = (id, trail) => {
+    if (state.get(id) === 'done') return;
+    if (state.get(id) === 'open') {
+      const cycle = [...trail.slice(trail.indexOf(id)), id];
+      const file = ledger.where(id).live[0]?.file ?? 'design';
+      out.push({
+        check: 'M2',
+        severity: 'block',
+        file,
+        line: 1,
+        id,
+        message: `depends cycle ${cycle.join(' -> ')}: none of them can be played first`,
+      });
+
+      return;
+    }
+
+    state.set(id, 'open');
+    for (const d of graph.get(id) ?? []) visit(d, [...trail, id]);
+    state.set(id, 'done');
+  };
+
+  for (const id of graph.keys()) visit(id, []);
+
+  return out;
+}
+
 /** M14: backlog.md is the order of the units in design/, each exactly once. */
 function backlogIssues(text, unitIds) {
   /** @type {Issue[]} */
@@ -577,6 +624,31 @@ function pillarReport(units, ctx) {
   };
 }
 
+/** A unit's line in the report: its TBD count and whether it is ready to take. */
+function unitSummary(u, own, values, ctx) {
+  const pillars = listOf(u.header.pillars ?? '');
+  // Once PILLARS.md exists, a mechanic or resource says which pillar it serves before work:
+  // `take` would turn the TBD into an empty list and the unit would serve nothing silently.
+  const pillarsTbd =
+    pillars === 'TBD' && ctx.pillarIds.length && CARD_TYPES.includes(u.header.type) ? 1 : 0;
+  const tbd = values.filter((v) => isTbd(v.value)).length + pillarsTbd;
+  const blockedBy = ctx.questions.d1.get(u.id) ?? [];
+
+  return {
+    id: u.id,
+    file: u.file,
+    system: u.system,
+    type: u.header.type ?? null,
+    milestone: u.header.milestone ?? 'TBD',
+    pillars,
+    pillars_owed: Boolean(pillarsTbd),
+    values: values.length,
+    tbd,
+    blocked_by: blockedBy,
+    ready: tbd === 0 && !blockedBy.length && !own.some((i) => i.severity === 'block'),
+  };
+}
+
 /**
  * Run every design check over a project. `blocking` counts the issues that refuse a commit;
  * the rest of the report (completeness, readiness, pillars) is a reading, not a gate.
@@ -591,28 +663,14 @@ export async function designCheck(projectDir) {
   for (const u of ledger.design.flatMap((d) => d.units)) {
     const { issues: own, values } = await checkUnit(u, ctx, ledger);
     issues.push(...own);
-    const tbd = values.filter((v) => isTbd(v.value)).length;
-    const blockedBy = ctx.questions.d1.get(u.id) ?? [];
-    const pillars = listOf(u.header.pillars ?? '');
-    units.push({
-      id: u.id,
-      file: u.file,
-      system: u.system,
-      type: u.header.type ?? null,
-      milestone: u.header.milestone ?? 'TBD',
-      pillars,
-      values: values.length,
-      tbd,
-      blocked_by: blockedBy,
-      ready: tbd === 0 && !blockedBy.length && !own.some((i) => i.severity === 'block'),
-    });
+    units.push(unitSummary(u, own, values, ctx));
   }
 
   for (const c of ledger.items) issues.push(...(await checkItem(c, ctx, ledger)));
   issues.push(...(await unplayedIssues(root, ledger)));
   for (const doc of ['game', 'glossary']) issues.push(...(await checkDoc(root, doc, ctx)));
   issues.push(...preambleIssues(ledger.design));
-  issues.push(...ledgerIssues(ledger), ...questionIssues(ctx, ledger));
+  issues.push(...ledgerIssues(ledger), ...dependsCycles(ledger), ...questionIssues(ctx, ledger));
   if (ledger.design.length) {
     const backlog = await readIf(path.join(root, 'backlog.md'));
     issues.push(...backlogIssues(backlog, new Set(units.map((u) => u.id))));

package/lib/live.js

@@ -117,13 +117,25 @@ export function applyDelta(capabilities, delta, itemId) {
 /**
  * The capabilities without what `delta` added: an unplayed mechanic killed, dropped or sent back
  * to tuning leaves the game, so its record leaves LIVE.md with it. `modified` and `removed`
- * cannot be undone from the delta alone and stay as they are.
+ * cannot be undone from the delta alone and stay as they are. A record another item modified
+ * since is refused: taking it out would erase that item's accepted change.
  */
-export function revertDelta(capabilities, delta) {
+export function revertDelta(capabilities, delta, itemId) {
   if (!delta || 'none' in delta) return capabilities;
-  const added = delta.changes.filter((c) => c.change === 'added').map((c) => c.id);
+  const added = delta.changes.filter((c) => c.change === 'added');
+  for (const c of added) {
+    const now = capabilities.find((r) => r.id === c.id);
+    // LIVE.md keeps fields trimmed: compare in that form, or a trailing space reads as an edit.
+    const same = (a, b) => String(a ?? '').trim() === String(b ?? '').trim();
+    if (now && !(same(now.summary, c.summary) && same(now.refs, c.refs)))
+      throw new Error(
+        `${itemId}: capability ${c.id} was modified after ${itemId} added it — taking it out ` +
+          'would erase that change: remove the record from LIVE.md by hand in its own commit ' +
+          'and repeat, or keep the item',
+      );
+  }
 
-  return capabilities.filter((r) => !added.includes(r.id));
+  return capabilities.filter((r) => !added.some((c) => c.id === r.id));
 }
 
 /** The known-issue record of a parked bug: its title or first intent bullet, and its file. */

package/lib/pillars.js

@@ -0,0 +1,113 @@
+// Revising PILLARS.md after units and items cite it: a rename follows the id everywhere it is
+// cited, a retire takes it out and sends every unit left without a pillar back to the human.
+// Pillars are human authorship (gcf-init): these moves only carry out the human's decision.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { serialize } from './frontmatter.js';
+import { SLUG_RE, listOf, parseDesign } from './design.js';
+import { recordsIn } from './design-check.js';
+import { buildLedger } from './ledger.js';
+import { atomicWrite } from './safe-path.js';
+import { commitMove } from './unit-ops.js';
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** The `id: <id>` line of a PILLARS.md record; `\r` and the line break stay outside it. */
+const idLine = (id) =>
+  new RegExp(`^([ \\t]*(?:- )?id:[ \\t]*)${escapeRe(id)}[ \\t]*(?=\\r?$)`, 'm');
+
+/**
+ * The design file with `edit` applied to each unit's header `pillars:` line — the header only:
+ * a `pillars:` line in a body or the preamble is not a citation. TBD stays TBD; a list left
+ * empty reads TBD, so the unit is not ready until the human gives it a pillar again.
+ */
+function rewriteHeaders(text, edit) {
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const lines = text.split(/\r?\n/);
+  for (const u of parseDesign(text, '').units) {
+    const at = u.headerLines.pillars;
+    const list = listOf(u.header.pillars ?? '');
+    if (at === undefined || list === 'TBD') continue;
+    const next = edit(list);
+    if (next.join() !== list.join())
+      lines[at - 1] = `pillars: ${next.length ? `[${next.join(', ')}]` : 'TBD'}`;
+  }
+
+  return lines.join(eol);
+}
+
+/**
+ * Apply `edit` to every citing list — unit headers in design/, item frontmatter in work/ — and
+ * `editPillars` to PILLARS.md, in one commit `gcf(pillar): <tail>`. Returns the items left
+ * citing no pillar: an item in work has no TBD to fall back to, so the human hears about it.
+ */
+async function revise(projectDir, id, { edit, editPillars, tail, commit }) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const pillarsFile = path.join(root, 'PILLARS.md');
+  const text = existsSync(pillarsFile) ? await readFile(pillarsFile, 'utf8') : '';
+  const ids = recordsIn(text, 'pillars').map((p) => p.id);
+  if (!ids.includes(id)) throw new Error(`${id} is not a pillar of gcf/PILLARS.md`);
+  const ledger = await buildLedger(projectDir);
+  const designFiles = ledger.design.map((d) => path.join(root, d.file));
+  const items = ledger.items.filter((c) => (c.data.pillars ?? []).includes(id));
+  const files = [pillarsFile, ...designFiles, ...items.map((c) => c.file)];
+  const mutate = async () => {
+    await atomicWrite(pillarsFile, editPillars(text));
+    for (const f of designFiles) {
+      const old = await readFile(f, 'utf8');
+      const next = rewriteHeaders(old, edit);
+      if (next !== old) await atomicWrite(f, next);
+    }
+
+    for (const c of items) {
+      await atomicWrite(c.file, serialize({ ...c.data, pillars: edit(c.data.pillars) }, c.body));
+    }
+  };
+
+  return {
+    id,
+    hash: await commitMove(projectDir, `gcf(pillar): ${tail}`, { files, mutate, commit }),
+    bare: items.filter((c) => !edit(c.data.pillars).length).map((c) => String(c.data.id)),
+  };
+}
+
+/** `pillar rename <from> <to>`: the id changes in PILLARS.md and every unit and item citing it. */
+export async function renamePillar(projectDir, from, to, { commit = true } = {}) {
+  if (!SLUG_RE.test(to)) throw new Error(`${to}: a pillar id is a lowercase hyphen slug`);
+  const text = await readFile(path.join(projectDir, 'gcf', 'PILLARS.md'), 'utf8').catch(() => '');
+  if (recordsIn(text, 'pillars').some((p) => p.id === to))
+    throw new Error(`${to} is a pillar already`);
+
+  return revise(projectDir, from, {
+    edit: (list) => list.map((p) => (p === from ? to : p)),
+    editPillars: (t) => t.replace(idLine(from), (_, head) => `${head}${to}`),
+    tail: `rename ${from} → ${to}`,
+    commit,
+  });
+}
+
+/**
+ * `pillar retire <id> --reason`: the record leaves PILLARS.md and the id leaves every list. A
+ * unit left citing no pillar reads `pillars: TBD` again — it is not ready until the human gives
+ * it one, or decides it is out of scope. The reason is kept in the commit.
+ */
+export async function retirePillar(projectDir, id, { reason, commit = true }) {
+  const why = String(reason ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!why) throw new Error('a retire needs a reason: the commit keeps it');
+  const own = idLine(id);
+
+  return revise(projectDir, id, {
+    edit: (list) => list.filter((p) => p !== id),
+    // A record starts at a `- ` line; the one holding `id: <id>` goes, blank lines and all.
+    editPillars: (t) =>
+      t
+        .split(/\n(?=- )/)
+        .filter((rec) => !own.test(rec))
+        .join('\n'),
+    tail: `retire ${id}: ${why}`,
+    commit,
+  });
+}

package/lib/unit-ops.js

@@ -129,7 +129,8 @@ function refuseUnready(units, summaries) {
     if (summary?.ready) continue;
     const why = summary?.blocked_by.length
       ? `blocked by ${summary.blocked_by.join(', ')}`
-      : `${summary?.tbd ?? '?'} TBD or a blocking design-check finding`;
+      : `${summary?.tbd ?? '?'} TBD${summary?.pillars_owed ? ', pillars among them' : ''} ` +
+        'or a blocking design-check finding';
     throw new Error(`${unit.id} is not ready (${why}): answer it in design/ first`);
   }
 }

package/lib/verdict-fs.js

@@ -114,8 +114,14 @@ export async function buryLine(root, id, { type, reason, tags }) {
   // A hand-edited file may end without a newline: the line would glue onto the last one.
   const eol = existing.match(/\r?\n/)?.[0] ?? '\n';
   const head = existing && !existing.endsWith('\n') ? existing + eol : existing;
-  const why = String(reason || 'no reason recorded').replace(/\s*\|\s*/g, '; ');
-  const line = `- ${id} | ${type} | ${why} | tags: ${tags.join(', ')}${eol}`;
+  // One record per line: a line break would split the reason from its tags, a pipe its fields.
+  const flat = (s) =>
+    String(s)
+      .replace(/\s*\|\s*/g, '; ')
+      .replace(/\s*\r?\n\s*/g, ' ')
+      .trim();
+  const why = flat(reason || 'no reason recorded');
+  const line = `- ${id} | ${type} | ${why} | tags: ${tags.map(flat).join(', ')}${eol}`;
   await atomicWrite(gyFile, head + line);
 }
 

package/lib/work-ops.js

@@ -90,9 +90,25 @@ export function openDepends(ledger, depends = [], { waiting = false } = {}) {
   });
 }
 
-/** The hash an unplayed item's body is frozen at (Methodology §5.4). */
-export const bodyHash = (body) =>
-  createHash('sha1').update(String(body).replace(/\r\n/g, '\n').trim()).digest('hex');
+/**
+ * The hash an unplayed item is frozen at (Methodology §5.4): its body and its `live:` delta —
+ * the two things a tune or a kill takes back out of systems/ and LIVE.md.
+ */
+export const frozenHash = (item) =>
+  createHash('sha1')
+    .update(String(item.body).replace(/\r\n/g, '\n').trim())
+    .update(`\nlive: ${JSON.stringify(item.data.live ?? null)}`)
+    .digest('hex');
+
+/**
+ * Whether an unplayed item still matches its `frozen:`. An item closed by 0.4.0 holds the sha1
+ * of its body alone: it still guards the body. shortcut: such an item's live: stays unguarded
+ * until it is closed again; drop the legacy form once no 0.4.0 unplayed item is left.
+ */
+export const matchesFrozen = (item) =>
+  item.data.frozen === frozenHash(item) ||
+  item.data.frozen ===
+    createHash('sha1').update(String(item.body).replace(/\r\n/g, '\n').trim()).digest('hex');
 
 /** Children of a feature that are not finished: live in any status but unplayed and parked. */
 function unfinishedChildren(ledger, feature) {
@@ -160,6 +176,14 @@ const without = (data, ...keys) =>
  * another unplayed item also wrote stays: that item's body still owes it to systems/.
  */
 function unplay(m, item) {
+  // The gate checks `frozen` only on a file that stays unplayed: a tune or a kill of an edited
+  // item would take the edited lines out and leave the frozen ones in systems/ for good.
+  if (!matchesFrozen(item))
+    throw new Error(
+      `${item.data.id}: an unplayed item's body and live: are frozen, and this one was edited — ` +
+        `save the edit aside, restore the file (git restore gcf/work/${item.data.id}.md ` +
+        'discards it), make the move, then apply the edit to the ready item',
+    );
   const systems = item.data.system ?? [];
   m.leaving.add(String(item.data.id));
   m.touch(...systemFiles(m.root, systems));
@@ -170,7 +194,15 @@ function unplay(m, item) {
       .flatMap((i) => Object.values(collapseLines(i.body)).flat());
     for (const s of systems) await unmergeFromSystem(m.root, s, item, keep);
   });
-  m.live((l) => ({ ...l, capabilities: revertDelta(l.capabilities, item.data.live) }));
+  m.live((l) => ({
+    ...l,
+    // The delta as the close applied it, refs included, so a later refs-only edit shows.
+    capabilities: revertDelta(
+      l.capabilities,
+      withRefs(item.data.live, detailOf(item, null)),
+      item.data.id,
+    ),
+  }));
 }
 
 const dropKnownIssue = (m, id) =>
@@ -380,7 +412,7 @@ function closeUnplayed(m) {
   });
   const delta = withRefs(item.data.live, detailOf(item, null));
   m.live((l) => ({ ...l, capabilities: applyDelta(l.capabilities, delta, id) }));
-  m.step(() => writeItem(item, { ...item.data, status: 'unplayed', frozen: bodyHash(item.body) }));
+  m.step(() => writeItem(item, { ...item.data, status: 'unplayed', frozen: frozenHash(item) }));
 }
 
 /** Any other gate-auto item ends in history; a hard unit may leave lines in `constraints:`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-aif-ext",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Game Context Framework for AI Factory",
   "type": "module",
   "license": "MIT",
@@ -24,8 +24,9 @@
     "node": ">=22.14"
   },
   "scripts": {
-    "test": "node --test",
-    "prepack": "node -e \"const p=require('./package.json'),e=require('./extension.json');if(p.version!==e.version)throw new Error('version mismatch: package.json '+p.version+' vs extension.json '+e.version)\""
+    "test": "node --test && npm run test:gate",
+    "prepack": "node -e \"const p=require('./package.json'),e=require('./extension.json');if(p.version!==e.version)throw new Error('version mismatch: package.json '+p.version+' vs extension.json '+e.version)\"",
+    "test:gate": "node -e \"process.env.GCF_TEST_GATE='1';require('node:child_process').execFileSync(process.execPath,['--test'],{stdio:'inherit'})\""
   },
   "files": [
     "extension.json",

package/skills/gcf-card/SKILL.md

@@ -39,12 +39,14 @@ workflow:
 7. for a unit with `flags: src-changed` re-read each changed anchor with `ai-factory gcf section`, rebuild the slots whose quote moved, and remove the flag
 8. confirm the route: ask "can an autotest accept this without a human playing?"; yes = hard, no or mixed = soft; a mixed unit splits into a soft mechanic and a hard rule before work
 9. ask the human one question per `TBD` slot, each with your proposed answer, questions per message <= 2
-10. write each answer into the unit in place, with its `answer:` provenance record
-11. run `ai-factory gcf design check --json` until the unit's entry in `units` reads `ready: true`, then commit the answered unit
-12. run `ai-factory gcf take <id>` for one unit, or `ai-factory gcf take <id> <id> --feature <feature-id>` to group several under a feature; it writes `gcf/work/<id>.md` and removes the sections and backlog lines in one step
-13. in each design-unit item write `contract:` from the code tree and `interactions:` from the units and items that write the same state; a soft unit whose human wants no playtest gets `gate: auto` - it will close as unplayed
-14. write the item's `live:` delta (a feature's children keep `none: parent`; the feature writes the capability), run `ai-factory gcf design check`, and commit
-15. report the item paths, each item's gate, and for a verdict item the one question the playtest will answer
+10. for `pillars: TBD` propose the ids from `gcf/PILLARS.md` whose statement the unit serves and whose invariant it keeps
+11. when no pillar fits, ask whether the unit is out of scope or a pillar is missing, and write a D1 question for the answer
+12. write each answer into the unit in place, with its `answer:` provenance record
+13. run `ai-factory gcf design check --json` until the unit's entry in `units` reads `ready: true`, then commit the answered unit
+14. run `ai-factory gcf take <id>` for one unit, or `ai-factory gcf take <id> <id> --feature <feature-id>` to group several under a feature; it writes `gcf/work/<id>.md` and removes the sections and backlog lines in one step
+15. in each design-unit item write `contract:` from the code tree and `interactions:` from the units and items that write the same state; a soft unit whose human wants no playtest gets `gate: auto` - it will close as unplayed
+16. write the item's `live:` delta (a feature's children keep `none: parent`; the feature writes the capability), run `ai-factory gcf design check`, and commit
+17. report the item paths, each item's gate, and for a verdict item the one question the playtest will answer
 
 invocation:
 - run when work starts on a unit or a group of units, when non-design work needs an item, or when a fresh idea needs a home

package/skills/gcf-init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gcf-init
-description: Bootstrap the gcf/ documentary layer - skeleton, pillars interview, hooks reminder. Use when a game project adopts GCF or when the user says "set up gcf".
+description: Bootstrap the gcf/ documentary layer - skeleton, pillars interview, hooks reminder - and revise pillars later. Use when a game project adopts GCF, when the user says "set up gcf", or "поменяем столпы" / "revise pillars".
 ---
 
 mode: bootstrap
@@ -21,13 +21,16 @@ forbidden_behaviors:
 
 workflow:
 1. when `.ai-factory/DESCRIPTION.md` is absent, tell the human to run `/aif` first: `aif-plan` reads it, and a work item cannot reach a plan without it
-2. run `ai-factory gcf init` and report which files it created, `gcf/design/` among them; it writes no `PILLARS.md`, so no example ever reads as the game's truth
+2. run `ai-factory gcf init` and report which files it created, `gcf/design/` and the agent instructions in `AGENTS.md` among them; it writes no `PILLARS.md`
 3. when the human is about to import a GDD, leave `PILLARS.md` absent: the import proposes pillar candidates, and the interview runs after it
 4. otherwise ask the human for the game's core promise, then for 2..7 pillars: each needs an id (a lowercase hyphen slug the design units cite), a statement, a negative invariant and a review question
 5. write `gcf/PILLARS.md` with the confirmed pillars in the record-list form of `.ai-factory/extensions/gcf-aif-ext/templates/PILLARS.md`
 6. run `npx --yes cnlp-kit check` and fix form issues it reports
 7. ask the human to run `ai-factory gcf hooks-install`: the commit gate is theirs to arm
 8. state the next step: import a GDD with `/gcf-ingest`, or start the design with `/gcf-vision` when there is none
+9. to add one pillar later, ask only for its id, statement, invariant and review question; append it as one record to `gcf/PILLARS.md`, keep the others, keep the count <= 7, then run step 6
+10. to rename a pillar, run `ai-factory gcf pillar rename <from> <to>`: every unit and item citing it follows
+11. to drop a pillar, run `ai-factory gcf pillar retire <id> --reason "<why>"`; a unit it leaves at `pillars: TBD` goes back through the pillars steps of the gcf-card skill
 
 invocation:
-- run when the user asks to set up gcf in a project
+- run when the user asks to set up gcf in a project, or to revise its pillars

package/templates/agents-block.md

@@ -0,0 +1,28 @@
+## Game Context Framework (from gcf-aif-ext)
+
+gcf_context:
+- the game's design and its work live in `gcf/`, and the `ai-factory gcf` commands and the gcf skills change them
+- read `gcf/INDEX.md` before anything else under `gcf/`: it lists every subsystem, design unit and work item
+- `gcf/LIVE.md` says what the game does now, and `gcf/PILLARS.md` says what it must stay
+
+gcf_work:
+- every piece of work is one work item `gcf/work/<id>.md`: find the item before writing code for a feature, a bug or a tech task, or create it with the gcf-card skill
+- a raw idea, a playtest note or a CI finding that is not work yet goes to `ai-factory gcf inbox add "<text>"`, and the gcf-triage skill sorts it later
+- before planning an item, run `ai-factory gcf context <id>` and read only the files it lists under `gcf/`
+- drive a ready item with the gcf-run skill when the project has gcf-harness-aif-ext, otherwise with aif-plan and aif-implement
+- end the work on an item with its command: `ai-factory gcf submit <id>` for gate verdict or decision, `ai-factory gcf close <id>` for gate auto with every check green
+- work that cannot go on: run `ai-factory gcf block <id> --reason "<why or the question>"`
+- a design question only the human can answer becomes a D1 record in `gcf/open-questions.md`
+
+gcf_forbidden:
+- do not edit `status:`, `frozen:`, `gcf/LIVE.md`, `gcf/history.md`, `gcf/graveyard.md` or `gcf/INDEX.md` by hand: the commands own them
+- do not give a verdict or a decision: `verdict` and `decide` belong to the human, through the gcf-verdict skill
+- do not answer a `TBD` of a design unit yourself: ask the human and offer your draft as the proposed answer
+- do not reuse an ended id: rework gets a new id with `reopens: <old id>`
+- do not commit past the gate with `--no-verify`: a refused commit names what to fix
+
+gcf_skills:
+- gcf-vision starts a game that has no design yet, and gcf-ingest imports a GDD into `gcf/design/`
+- gcf-card puts work into `gcf/work/`, and gcf-triage sorts `gcf/inbox.md`
+- gcf-verdict records the human's verdict or decision, and gcf-audit reports the health of `gcf/`
+- gcf-debate stresses the design, gcf-adopt puts existing code on GCF, and gcf-init sets up `gcf/` and revises the pillars