gcf-aif-ext 0.4.0 → 0.5.0

package/lib/playtest-list.js

@@ -1,4 +1,24 @@
-import { listItems, scalarOf } from './gcf-paths.js';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { listItems, scalarOf, readConfig, firstBullet } from './gcf-paths.js';
+import { recordsOf } from './verdict-fs.js';
+import { runDod } from './verify.js';
+
+const ENVELOPE = /^\S+\.\.\S+ /;
+
+/** What the play should feel: a mechanic's feel envelopes, a resource's rate envelopes. */
+function feelOf(body) {
+  const feel = recordsOf(body, 'feel')
+    .filter((r) => r.name && r.envelope)
+    .map((r) => `${r.name}: ${r.envelope}`);
+  const rates = ['sources', 'sinks'].flatMap((key) =>
+    recordsOf(body, key)
+      .filter((r) => r.name && ENVELOPE.test(`${r.rate} `))
+      .map((r) => `${r.name} rate: ${r.rate}`),
+  );
+
+  return [...feel, ...rates];
+}
 
 /**
  * Playtest list (Methodology §5.3): every item waiting for its verdict, and every unplayed one,
@@ -13,5 +33,44 @@ export async function playtestList(root) {
       status: c.data.status,
       system: c.data.system ?? [],
       question: scalarOf(c.body, 'miss_criterion') || '(miss_criterion is empty)',
+      reach: recordsOf(c.body, 'behavior')
+        .map((r) => r.input)
+        .filter(Boolean),
+      feel: feelOf(c.body),
+      intent: firstBullet(c.body, 'intent') || null,
     }));
 }
+
+const git = (projectDir, args) => {
+  const res = spawnSync('git', args, { cwd: projectDir, encoding: 'utf8' });
+
+  return res.status === 0 ? res.stdout.trim() : null;
+};
+
+/**
+ * `playtest session` (Methodology §5.3): one build of main and the checklist of everything that
+ * waits for play, grouped by subsystem — built from the items on every call, no file of its own.
+ * `build` runs the project's `dod.build` first.
+ */
+export async function playtestSession(
+  projectDir,
+  { build = false, stdio = ['ignore', 2, 2] } = {},
+) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const items = (await playtestList(root)).sort(
+    (a, b) => (a.system[0] ?? '').localeCompare(b.system[0] ?? '') || a.id.localeCompare(b.id),
+  );
+  // gcf/.metrics changes on every audit and context run: it does not make the build differ.
+  const dirty = git(projectDir, ['status', '--porcelain', '--', '.', ':(exclude)gcf/.metrics']);
+  const session = {
+    branch: git(projectDir, ['rev-parse', '--abbrev-ref', 'HEAD']),
+    commit: git(projectDir, ['rev-parse', '--short', 'HEAD']),
+    // No commit (no repository, or none yet): the build is unknown, not clean.
+    dirty: dirty === null ? null : Boolean(dirty),
+    build: null,
+    items,
+  };
+  if (build) session.build = runDod(projectDir, await readConfig(root), 'build', stdio);
+
+  return session;
+}

package/lib/unit-ops.js

@@ -15,6 +15,8 @@ import { operationInProgress, commitPaths } from './git.js';
 import { upsertBlock, openSystemDoc } from './systems-doc.js';
 import { buryLine, recordLine } from './verdict-fs.js';
 import { DEFAULT_GATE } from './validate-item.js';
+import { refuseByPhase } from './phase.js';
+import { withMainLock } from './main-lock.js';
 
 /** A design file's text without the `## <id>` section. */
 export function removeUnit(text, id) {
@@ -129,7 +131,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`);
   }
 }
@@ -149,6 +152,8 @@ export async function takeUnits(
   const ledger = await buildLedger(projectDir);
   const units = ids.map((id) => designUnitOf(ledger, id));
   refuseUnready(units, (await designCheck(projectDir)).units);
+  for (const u of units) await refuseByPhase(projectDir, u.header.type, u.header.reopens ?? null);
+  if (feature && !ledger.item(feature)) await refuseByPhase(projectDir, 'feature');
   const writes = units.map((unit) => ({
     file: path.join(root, 'work', `${unit.id}.md`),
     text: serialize(unitItemData(unit, today, feature), `\n${unit.body.trim()}\n`),
@@ -205,7 +210,28 @@ function uncommitted(projectDir, file) {
  * @param {string} message
  * @param {{files: string[], mutate: () => Promise<void>, commit: boolean, inputs?: string[]}} move
  */
-export async function commitMove(projectDir, message, { files, mutate, commit, inputs = [] }) {
+/** A worktree of the integrator (Methodology §7): its gcf/ state is main's to move. */
+const onWorkBranch = (projectDir) =>
+  /^work\//.test(
+    spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: projectDir,
+      encoding: 'utf8',
+    }).stdout?.trim() ?? '',
+  );
+
+export async function commitMove(projectDir, message, move) {
+  // A move that commits holds the main lock while it writes and commits (Methodology §7).
+  return move.commit
+    ? withMainLock(projectDir, () => record(projectDir, message, move))
+    : record(projectDir, message, move);
+}
+
+async function record(projectDir, message, { files, mutate, commit, inputs = [] }) {
+  if (commit && onWorkBranch(projectDir))
+    throw new Error(
+      `cannot record ${message} on a work/ branch: a worktree records no move — the run ` +
+        'leaves .gcf-session/outcome.json, and the main checkout records it',
+    );
   const busy = commit ? operationInProgress(projectDir) : null;
   if (busy) throw new Error(`cannot record ${message} while ${busy} is in progress`);
   const dirty = commit

package/lib/validate-item.js

@@ -65,6 +65,8 @@ const FIELDS = [
   'live',
   'model',
   'effort',
+  'version',
+  'channel',
   'created',
 ];
 const REQUIRED = ['schema', 'id', 'type', 'gate', 'status', 'created'];
@@ -154,6 +156,10 @@ const RULES = {
   live: (v) => liveProblem(v) ?? true,
   model: (v) => nullable(isText)(v) || 'model must be text or null',
   effort: (v) => nullable(isText)(v) || 'effort must be text or null',
+  version: (v) =>
+    nullable((x) => typeof x === 'string' && /^\S+$/.test(x))(v) ||
+    'version must be one word of text (quote a number: "1.0")',
+  channel: (v) => nullable(isSlug)(v) || 'channel must be a slug, e.g. steam',
   created: (v) => /^\d{4}-\d{2}-\d{2}$/.test(dateStr(v)) || 'created must be YYYY-MM-DD',
 };
 
@@ -214,6 +220,10 @@ const CROSS = [
   ],
   [(d) => isUnit(d) && d.source === undefined, 'a design-unit item keeps its source:'],
   [(d) => Boolean(d.parent) && d.parent === d.id, 'an item cannot be its own parent'],
+  [
+    (d) => d.type !== 'release' && Boolean(d.version || d.channel),
+    'version and channel belong to a release',
+  ],
 ];
 
 /** Validate work item frontmatter. Returns a list of one-line errors (empty = valid). */

package/lib/verdict-fs.js

@@ -12,7 +12,8 @@ import { blockLines, upsertBlock, removeLines, openSystemDoc } from './systems-d
 const ENVELOPE = /^\S+\.\.\S+ /;
 const real = (lines) => lines.filter((l) => !/^- none\b/.test(l));
 
-function recordsOf(body, key) {
+/** The records of a `key:` block, each as `{field: value}`. */
+export function recordsOf(body, key) {
   const { lines, sections } = parseBlocks(body);
   const at = sections.find((s) => s.key === key && !s.value);
 
@@ -114,8 +115,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/verify.js

@@ -0,0 +1,72 @@
+// `gcf verify <id>` (Methodology §6): the auto-DoD checks code can run — the GCF checks of the
+// pre-commit gate, the item's live: delta against LIVE.md, then the project's `dod.build` and
+// `dod.test`. The second-agent review is the run's job; the attempt count lives in the run.
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { readConfig } from './gcf-paths.js';
+import { readLive, applyDelta } from './live.js';
+import { gateProblems } from './gate.js';
+import { unplayedCloseProblem } from './work-ops.js';
+
+/** Run a `dod.<key>` command in the project; `none` says the project has no such step. */
+export function runDod(projectDir, config, key, stdio) {
+  if (config.dod !== undefined && (typeof config.dod !== 'object' || Array.isArray(config.dod)))
+    return { name: key, ok: false, problems: ['dod in gcf/config.yml must map test: and build:'] };
+  const cmd = config.dod?.[key];
+  if (cmd === 'none') return { name: key, ok: true, problems: [], skipped: true };
+  if (typeof cmd !== 'string' || !cmd.trim())
+    return {
+      name: key,
+      ok: false,
+      problems: [`dod.${key} is not set in gcf/config.yml — the project's command, or none`],
+    };
+  // shortcut: no timeout, a command that waits for input hangs the run; add one when it bites.
+  const res = spawnSync(cmd, { cwd: projectDir, shell: true, stdio });
+  const ok = res.status === 0;
+  const why = res.error ? res.error.message : `exit ${res.status ?? res.signal}`;
+
+  return { name: key, ok, problems: ok ? [] : [`dod.${key} failed (${why}): ${cmd}`] };
+}
+
+/**
+ * Why the item's `live:` delta would fail its end against this checkout's LIVE.md: it does not
+ * apply, or an unplayed close could not take it back.
+ */
+export async function deltaProblems(projectDir, item) {
+  const problems = [];
+  try {
+    const root = path.join(path.resolve(projectDir), 'gcf');
+    applyDelta((await readLive(root)).capabilities, item.data.live, String(item.data.id));
+  } catch (e) {
+    problems.push(e.message);
+  }
+
+  const unplayed = unplayedCloseProblem(item);
+  if (unplayed) problems.push(unplayed);
+
+  return problems;
+}
+
+/**
+ * Every DoD check over item `id`, each run even when an earlier one failed: one attempt sees
+ * all it has to fix. The commands' own output goes to `stdio` (stderr by default).
+ */
+export async function verifyItem(projectDir, id, { stdio = ['ignore', 2, 2] } = {}) {
+  const { problems, ledger } = await gateProblems(projectDir);
+  const item = ledger.item(id);
+  if (!item) throw new Error(`${id} is not a work item of gcf/work/`);
+  if (item.data.status !== 'ready')
+    throw new Error(`${id} is ${item.data.status}: the DoD runs on a ready item, before its move`);
+
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const live = await deltaProblems(projectDir, item);
+  const config = await readConfig(root);
+  const checks = [
+    { name: 'gcf', ok: !problems.length, problems },
+    { name: 'live', ok: !live.length, problems: live },
+    runDod(projectDir, config, 'build', stdio),
+    runDod(projectDir, config, 'test', stdio),
+  ];
+
+  return { id, checks, ok: checks.every((c) => c.ok) };
+}

package/lib/work-ops.js

@@ -26,8 +26,16 @@ import {
   buryLine,
   recordLine,
 } from './verdict-fs.js';
-import { readLive, writeLive, liveFile, applyDelta, revertDelta, knownIssueOf } from './live.js';
+import {
+  readLiveStrict,
+  writeLive,
+  liveFile,
+  applyDelta,
+  revertDelta,
+  knownIssueOf,
+} from './live.js';
 import { dropInbox } from './inbox.js';
+import { refuseByPhase } from './phase.js';
 
 /**
  * Options of a committed move; each move reads the ones it needs.
@@ -90,9 +98,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) {
@@ -133,7 +157,7 @@ async function begin(projectDir, id, move) {
     run: async () => {
       for (const s of steps) await s();
       if (!liveOps.length) return;
-      let live = await readLive(root);
+      let live = await readLiveStrict(root);
       for (const op of liveOps) live = op(live);
       await writeLive(root, live);
     },
@@ -160,6 +184,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 +202,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) =>
@@ -227,6 +267,7 @@ const detailOf = (item, archived) =>
  */
 function endToHistory(m, item, event, { applyLive = true } = {}) {
   const id = String(item.data.id);
+  if (item.data.type === 'release') recordRelease(m, item);
   m.touch(path.join(m.root, 'history.md'));
   m.step(() => recordLine(m.root, id, event));
   const archived = archivePlan(m, item);
@@ -239,6 +280,24 @@ function endToHistory(m, item, event, { applyLive = true } = {}) {
   m.step(() => unlink(item.file));
 }
 
+/**
+ * A release item that ends writes the `release:` block of LIVE.md (Methodology §13): its
+ * version, channel and the date; the previous release stays only in history.md.
+ */
+function recordRelease(m, item) {
+  const { id, version, channel } = item.data;
+  if (!version || !channel)
+    throw new Error(`${id} is a release: write its version: and channel: before it ends`);
+  // The item file leaves in this commit: the gate never sees a hand-edited version: here.
+  if (typeof version !== 'string' || !/^\S+$/.test(version) || !isValidId(channel))
+    throw new Error(`${id}: version: is one quoted word ("1.10"), channel: a slug (steam)`);
+  // The phase it shipped in: the release phase exits on a release of its own (Methodology §10).
+  m.live((l) => ({
+    ...l,
+    release: { version, channel, date: today(), ...(l.phase ? { phase: l.phase } : {}) },
+  }));
+}
+
 /** A fresh id from `base`: base, base-2, base-3 … — ids are never reused. */
 function freshId(ledger, base) {
   let id = base;
@@ -360,6 +419,17 @@ export async function submitItem(projectDir, id, opts = {}) {
   return { id, status, hash: await finish(m, 'submit', id, commit) };
 }
 
+/** Why a soft gate-auto item cannot close unplayed, or null: only an `added` comes back out. */
+export function unplayedCloseProblem(item) {
+  if (!SOFT.includes(item.data.type) || item.data.gate !== 'auto') return null;
+  if (!(item.data.live?.changes ?? []).some((c) => c.change !== 'added')) return null;
+
+  return (
+    `${item.data.id}: an unplayed close can only add capabilities (a modified or removed one ` +
+    'cannot be taken back) — set gate: verdict and submit it'
+  );
+}
+
 /**
  * A soft unit closed without a playtest (Methodology §5.4): its lines go into its systems docs,
  * its capability into LIVE.md, and the file stays unplayed with its body frozen by hash — that
@@ -368,11 +438,8 @@ export async function submitItem(projectDir, id, opts = {}) {
 function closeUnplayed(m) {
   const { item } = m;
   const id = String(item.data.id);
-  if ((item.data.live?.changes ?? []).some((c) => c.change !== 'added'))
-    throw new Error(
-      `${id}: an unplayed close can only add capabilities (a modified or removed one cannot be ` +
-        'taken back) — set gate: verdict and submit it',
-    );
+  const refused = unplayedCloseProblem(item);
+  if (refused) throw new Error(refused);
   const systems = item.data.system ?? [];
   m.touch(...systemFiles(m.root, systems));
   m.step(async () => {
@@ -380,7 +447,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:`. */
@@ -622,6 +689,19 @@ export async function dropItem(projectDir, id, opts = {}) {
   return { id, hash: await finish(m, 'drop', id, commit), removal };
 }
 
+/** The version and channel of a new item: well-formed, and only on a release. */
+function checkRelease(spec) {
+  const { type, version, channel } = spec;
+  if (version !== undefined && !/^\S+$/.test(version))
+    throw new Error('--release is one word, e.g. 1.2.0');
+  if (spec.milestone !== undefined && !isValidId(spec.milestone))
+    throw new Error('--milestone is a milestone name of game.md');
+  if (channel !== undefined && !isValidId(channel))
+    throw new Error('--channel is a lowercase hyphen slug, e.g. steam');
+  if ((version || channel) && type !== 'release')
+    throw new Error('--release and --channel belong to a release item');
+}
+
 /** Refuse a spec `item new` cannot honour; returns the gate the item gets. */
 function checkNew(ledger, spec) {
   const { id, type, gate, severity } = spec;
@@ -635,6 +715,7 @@ function checkNew(ledger, spec) {
   if (type === 'feature' && g !== 'auto') throw new Error('a feature always has gate auto');
   if (type === 'bug' && !SEVERITIES.includes(severity))
     throw new Error(`a bug needs --severity ${SEVERITIES.join('|')}`);
+  checkRelease(spec);
 
   return g;
 }
@@ -646,6 +727,7 @@ const NO_CAPABILITY = {
   spike: 'a spike answers a question, its code never ships',
   asset: 'an asset dresses a capability, it adds none',
   perf: 'a budget met changes no capability',
+  release: 'a release ships what is built, it adds no capability',
 };
 
 /** The `live:` a new item starts with, or null when its author owes one. */
@@ -667,6 +749,9 @@ function optionalFields(spec, gate, since) {
     ...(reopens ? { reopens } : {}),
     ...(gate === 'verdict' ? { tune_count: 0 } : {}),
     ...(type === 'bug' ? { severity } : {}),
+    ...(spec.milestone ? { milestone: spec.milestone } : {}),
+    ...(spec.version ? { version: spec.version } : {}),
+    ...(spec.channel ? { channel: spec.channel } : {}),
     ...(live ? { live } : {}),
   };
 }
@@ -700,6 +785,7 @@ export async function newItem(projectDir, spec) {
   const root = gcfOf(projectDir);
   const ledger = await buildLedger(projectDir);
   const gate = checkNew(ledger, spec);
+  await refuseByPhase(projectDir, spec.type, spec.reopens);
   if (spec.reopens && !ledger.where(spec.reopens).terminal.length)
     throw new Error(`reopens names ${spec.reopens}, which has not ended`);
   const file = path.join(root, 'work', `${spec.id}.md`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-aif-ext",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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/schemas/item.schema.json

@@ -100,6 +100,10 @@
     },
     "model": { "$ref": "#/definitions/textOrNull" },
     "effort": { "$ref": "#/definitions/textOrNull" },
+    "version": {
+      "anyOf": [{ "type": "null" }, { "type": "string", "pattern": "^\\S+$" }]
+    },
+    "channel": { "$ref": "#/definitions/slugOrNull" },
     "created": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }
   }
 }

package/skills/gcf-card/SKILL.md

@@ -31,20 +31,22 @@ outputs:
 
 workflow:
 1. for a free-text design idea: ask "into work now, or park it?"; write a unit in the matching `gcf/design/<system>.md` with `source: manual` and `TBD` slots, append `- <id>` to `gcf/backlog.md`, and on "park" stop here
-2. for non-design work: pick the type - tech, bug, spike, asset, content, perf, release - and propose the gate its type gives; the human may flip it (`--gate auto` is "no playtest")
-3. a bug needs `--severity` and a `repro:` the human confirms
+2. for non-design work: pick the type - tech, bug, spike, asset, content, perf, release - among those `ai-factory gcf phase` says the phase takes, and propose the gate its type gives; the human may flip it (`--gate auto` is "no playtest")
+3. a bug needs `--severity` and a `repro:` the human confirms; a release needs `--release <version> --channel <name>` from the human
 4. run `ai-factory gcf item new <id> --type <type> [--gate <gate>] [--parent <feature>] [--title "<line>"]`, add `--from <in-id>` when it comes from the inbox, `--blocked "file needed"` for a final asset; then write `intent:` and `live:` and stop
 5. for a design unit: run `ai-factory gcf where <id>`; the id must be a single unit of `gcf/design/`; read its section from the file the command names
 6. for a unit with `flags: impl?` ask the human first whether the mechanic already ships; on "yes" run `ai-factory gcf drop <id> --reason "already ships"` and stop
 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/skills/gcf-verdict/SKILL.md

@@ -21,7 +21,7 @@ forbidden_behaviors:
 - do not edit systems docs, `LIVE.md`, history or graveyard by hand: the commands own them
 
 workflow:
-1. with no arguments: run `ai-factory gcf playtest` and stop - that list, awaiting-verdict and unplayed items, is the session's playtest sheet
+1. with no arguments: run `ai-factory gcf playtest session` and stop - its build line and checklist of awaiting-verdict and unplayed items are the session's playtest sheet
 2. read the item; for a verdict ask the human the miss_criterion question and record the answer in one line
 3. for `tune` at the tune limit (`tune_limit` in `gcf/config.yml`, 3 by default): the command refuses; the way out is a kill, and a redesigned envelope becomes a new item with `reopens: <id>`
 4. for `keep` of a design-unit item still awaiting its verdict: compress it first - the collapse copies lines verbatim, 1 line per behavior record, refusal and boundary

package/templates/agents-block.md

@@ -0,0 +1,36 @@
+## 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
+- `ai-factory gcf board --json` gives the whole state in one read: the phase, the items by status with plan progress, the inbox and the open questions
+
+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 (a batch at once: `ai-factory gcf-harness run <ids...>`), otherwise with aif-plan and aif-implement
+- after the code, write the item's `live:` delta and run `ai-factory gcf verify <id>`: fix what it reports and run it again until every check is green
+- then end the work on the item with its command: `ai-factory gcf submit <id>` for gate verdict or decision, `ai-factory gcf close <id>` for gate auto
+- work that cannot go on: run `ai-factory gcf block <id> --reason "<why or the question>"`
+- in a worktree on branch `work/<id>` change no `gcf/` file but the item's `live:`, commit all, then run `ai-factory gcf verify <id> --mark`: `ai-factory gcf integrate` in the main checkout merges it and records the move
+- a design question only the human can answer becomes a D1 record in `gcf/open-questions.md`
+- the human plays from `ai-factory gcf playtest session`; each free note from that play goes to `ai-factory gcf inbox add --source playtest "<note>"`
+- a release item carries `version:` and `channel:` (`item new <id> --type release --release <v> --channel <c>`): its end writes the `release:` block of `gcf/LIVE.md`
+- `item new` and `take` refuse a type the current phase does not take: run `ai-factory gcf phase` and bring the refusal to the human
+- a pillar changes only on the human's word: `ai-factory gcf pillar rename <from> <to>`, or `ai-factory gcf pillar retire <id> --reason "<why>"`
+
+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 run `ai-factory gcf phase next`: the phase moves on the human's word only
+- 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

package/templates/config.yml

@@ -10,6 +10,8 @@ unplayed_warn_after: 5
 plan_passes: 5
 dod_attempts: 2
 # The project's own commands for the auto DoD (Methodology §6); the engine does not matter.
+# gcf verify fails on an empty one; `none` says the project has no such step.
+# Phases (Methodology §10) come from code; a `phases:` list here replaces the whole set.
 dod:
   test:
   build: