gcf-aif-ext 0.7.9 → 0.7.13

package/lib/playtest-list.js

@@ -41,6 +41,19 @@ export async function playtestList(root) {
     }));
 }
 
+/** Items awaiting a decision: no verdict, but the human may need the build to make it. */
+async function decisionList(root) {
+  return (await listItems(root))
+    .filter((c) => c.data.status === 'awaiting-decision')
+    .map((c) => ({
+      id: c.data.id,
+      title: c.data.title ?? null,
+      system: c.data.system ?? [],
+      intent: firstBullet(c.body, 'intent') || null,
+    }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
 const git = (projectDir, args) => {
   const res = spawnSync('git', args, { cwd: projectDir, encoding: 'utf8' });
 
@@ -73,10 +86,11 @@ export async function playtestSession(
     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: /** @type {ReturnType<typeof runDod> | null} */ (null),
+    build: /** @type {Awaited<ReturnType<typeof runDod>> | null} */ (null),
     items,
+    decisions: await decisionList(root),
   };
-  if (build) session.build = runDod(projectDir, await readConfig(root), 'build', stdio);
+  if (build) session.build = await runDod(projectDir, await readConfig(root), 'build', stdio);
 
   return session;
 }

package/lib/verify-stamp.js

@@ -0,0 +1,102 @@
+// The record of a green `gcf verify` on main (Methodology §6): `close` and `submit` need one for
+// the code as it is now, so a DoD run some other way cannot stand in for it. The record holds
+// the hash of the project's code, not of a commit: committing the verified code keeps it valid,
+// and any edit after the verify (a review's fix) asks for a new one. In a worktree the
+// `GCF-Verified` trailer does this job, and the integrator's moves need no record.
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, readFileSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// Not code: the framework's own files, the plans, the run files. A move or a plan tick there
+// after the verify does not change what the DoD proved.
+const NOT_CODE = ['gcf', '.ai-factory', '.gcf-session'];
+
+const stampFile = (projectDir, id) =>
+  path.join(path.resolve(projectDir), '.gcf-session', 'runs', `${id}.verified`);
+
+const git = (projectDir, args, env = {}) =>
+  spawnSync('git', args, { cwd: projectDir, encoding: 'utf8', env: { ...process.env, ...env } });
+
+/**
+ * The git tree of the project's code as it is on disk, committed or not, new files included
+ * (ignored ones are not); null outside a repository. A git that fails on the code (a file it
+ * cannot read, `core.safecrlf`) throws: a gate that cannot see the code must not let it pass. A
+ * copy of the index keeps git's stat cache, so only changed files are hashed again.
+ */
+export function codeTree(projectDir) {
+  const index = git(projectDir, ['rev-parse', '--git-path', 'index']);
+  if (index.status !== 0) return null;
+  const real = path.resolve(projectDir, index.stdout.trim());
+  const tmp = path.join(os.tmpdir(), `gcf-code-index-${process.pid}-${Date.now()}`);
+  const env = { GIT_INDEX_FILE: tmp };
+  const step = (args) => {
+    const r = git(projectDir, args, env);
+    if (r.status !== 0) throw new Error(`git ${args[0]} on the code failed: ${r.stderr.trim()}`);
+
+    return r.stdout.trim();
+  };
+
+  try {
+    if (existsSync(real)) copyFileSync(real, tmp);
+    step(['add', '-A', '--', '.', ...NOT_CODE.map((p) => `:(exclude)${p}`)]);
+    step(['rm', '-r', '-q', '--cached', '--ignore-unmatch', '--', ...NOT_CODE]);
+
+    return step(['write-tree']);
+  } finally {
+    rmSync(tmp, { force: true });
+  }
+}
+
+/** Record a green verify of the code as it is now. */
+export function stampVerified(projectDir, id) {
+  const tree = codeTree(projectDir);
+  if (!tree) return;
+  const file = stampFile(projectDir, id);
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({ tree, at: new Date().toISOString() })}\n`);
+}
+
+/** A move ended the item's work: its record goes with it. */
+export const dropStamp = (projectDir, id) => rmSync(stampFile(projectDir, id), { force: true });
+
+/** The files that differ between two trees, the first few, for a refusal to name. */
+function changed(projectDir, from, to) {
+  const r = git(projectDir, ['diff-tree', '-r', '--name-only', from, to]);
+  const files = r.status === 0 ? r.stdout.split('\n').filter(Boolean) : [];
+  const more = files.length > 5 ? ` and ${files.length - 5} more` : '';
+
+  return files.length ? ` (${files.slice(0, 5).join(', ')}${more})` : '';
+}
+
+/**
+ * Why `close` or `submit` may not take the item now, or null: no green verify on record, or
+ * the code changed since. A feature closes over its children and has no code of its own. The
+ * way past it is named as the human's: an agent reads this text.
+ */
+export function unverifiedProblem(projectDir, id, type) {
+  if (type === 'feature') return null;
+  const tree = codeTree(projectDir);
+  if (!tree) return null;
+  const how =
+    `run ai-factory gcf verify ${id} until it is green; only the human may move it without ` +
+    'one (--unverified "<why>")';
+  const stamp = readStamp(projectDir, id);
+  if (!stamp) return `${id}: no green gcf verify on record — ${how}`;
+  if (stamp.tree !== tree) {
+    const files = changed(projectDir, stamp.tree, tree);
+
+    return `${id}: the code changed since its green gcf verify${files} — ${how}`;
+  }
+
+  return null;
+}
+
+/** @returns {{tree: string, at: string} | null} the record, or null when there is none. */
+function readStamp(projectDir, id) {
+  try {
+    return JSON.parse(readFileSync(stampFile(projectDir, id), 'utf8'));
+  } catch {
+    return null;
+  }
+}

package/lib/verify.js

@@ -1,15 +1,111 @@
 // `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 { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 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';
 
+/**
+ * Every process's parent, `[pid, ppid]` (POSIX): from /proc on Linux, which a slim image has
+ * with no procps; from `ps` elsewhere.
+ */
+function parents() {
+  if (existsSync('/proc/self/stat'))
+    return readdirSync('/proc')
+      .filter((d) => /^\d+$/.test(d))
+      .flatMap((d) => {
+        try {
+          // `pid (comm) state ppid …`: comm may hold spaces and parentheses.
+          const stat = readFileSync(`/proc/${d}/stat`, 'utf8');
+
+          return [[Number(d), Number(stat.slice(stat.lastIndexOf(')') + 2).split(' ')[1])]];
+        } catch {
+          return [];
+        }
+      });
+  const res = spawnSync('ps', ['-A', '-o', 'pid=,ppid='], { encoding: 'utf8' });
+
+  return (res.stdout ?? '')
+    .split('\n')
+    .map((l) => l.trim().split(/\s+/).map(Number))
+    .filter((p) => p.length === 2 && p.every(Number.isFinite));
+}
+
+/** Stop `p` where it is, or kill it; a process gone already is no error. */
+const signal = (p, sig) => {
+  try {
+    process.kill(p, sig);
+  } catch {
+    // Gone already.
+  }
+};
+
+/**
+ * End a command with everything it started: an engine the shell spawned outlives the shell. The
+ * command stays in its caller's process group, so a harness that kills its session's group
+ * kills the command too. On POSIX each process found is stopped first, so none forks a child the
+ * walk would miss; then all are killed.
+ * shortcut: a grandchild whose parent exited before the walk is init's and is not found; a
+ * process group of its own per command would catch it, at the cost of the harness's group kill.
+ */
+function killTree(pid) {
+  if (process.platform === 'win32') {
+    spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
+
+    return;
+  }
+
+  const doomed = new Set([pid]);
+  // finally: a walk that throws (an unreadable /proc) must not leave what it stopped frozen.
+  try {
+    while (stopChildren(doomed));
+  } finally {
+    for (const p of doomed) signal(p, 'SIGKILL');
+  }
+}
+
+/** Stop every process of `doomed`, then add their children; true when one was added. */
+function stopChildren(doomed) {
+  let grew = false;
+  for (const p of doomed) signal(p, 'SIGSTOP');
+  for (const [p, parent] of parents())
+    if (doomed.has(parent) && !doomed.has(p)) grew = Boolean(doomed.add(p));
+
+  return grew;
+}
+
+/**
+ * Run `cmd` in a shell; past `ms` (0: never) it is killed with its whole tree. `exit`, not
+ * `close`: a helper the command left running may hold the inherited stdio open.
+ */
+function runCommand(cmd, cwd, stdio, ms) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, { cwd, shell: true, stdio });
+    let timedOut = false;
+    const timer =
+      ms > 0
+        ? setTimeout(() => {
+            timedOut = true;
+            killTree(child.pid);
+          }, ms)
+        : null;
+    child.on('error', (error) => {
+      clearTimeout(timer ?? undefined);
+      resolve({ error, timedOut });
+    });
+    child.on('exit', (status, signal) => {
+      clearTimeout(timer ?? undefined);
+      resolve({ status, signal, timedOut });
+    });
+  });
+}
+
 /** Run a `dod.<key>` command in the project; `none` says the project has no such step. */
-export function runDod(projectDir, config, key, stdio) {
+export async 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];
@@ -20,13 +116,26 @@ export function runDod(projectDir, config, key, stdio) {
       ok: false,
       problems: [`dod.${key} is not set in gcf/config.yml — the project's command, or none`],
     };
-  // shortcut: no timeout; stdin is closed, but a command that never ends (a watch mode, a
-  // server) hangs `gcf verify`, and a harness run until its own timeout; add one when it bites.
-  const res = spawnSync(cmd, { cwd: projectDir, shell: true, stdio });
-  const ok = res.status === 0;
+  // stdin is closed; a command that never ends (a hung engine, a watch mode) meets the timeout.
+  const minutes = config.dod_timeout_min ?? 0;
+  const problem = failureOf(
+    key,
+    cmd,
+    minutes,
+    await runCommand(cmd, projectDir, stdio, minutes * 60000),
+  );
+
+  return { name: key, ok: !problem, problems: problem ? [problem] : [] };
+}
+
+/** Why a finished DoD command failed, or null when it passed. */
+function failureOf(key, cmd, minutes, res) {
+  if (res.timedOut)
+    return `dod.${key} timed out after ${minutes} min (dod_timeout_min), killed: ${cmd}`;
+  if (res.status === 0) return null;
   const why = res.error ? res.error.message : `exit ${res.status ?? res.signal}`;
 
-  return { name: key, ok, problems: ok ? [] : [`dod.${key} failed (${why}): ${cmd}`] };
+  return `dod.${key} failed (${why}): ${cmd}`;
 }
 
 /**
@@ -65,8 +174,8 @@ export async function verifyItem(projectDir, id, { stdio = ['ignore', 2, 2] } =
   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),
+    await runDod(projectDir, config, 'build', stdio),
+    await runDod(projectDir, config, 'test', stdio),
   ];
 
   return { id, checks, ok: checks.every((c) => c.ok) };

package/lib/work-ops.js

@@ -39,6 +39,7 @@ import { dropInbox } from './inbox.js';
 import { refuseByPhase } from './phase.js';
 import { locked, runHolder } from './main-lock.js';
 import { dropAgentSession, releaseSession, sessionActive } from './session-mark.js';
+import { dropStamp, unverifiedProblem } from './verify-stamp.js';
 
 /**
  * Options of a committed move; each move reads the ones it needs.
@@ -232,10 +233,38 @@ async function finish(m, move, tail, commit) {
   // and no rerun resumes it.
   releaseSession(m.projectDir, String(m.item.data.id));
   dropAgentSession(m.projectDir, String(m.item.data.id));
+  dropStamp(m.projectDir, String(m.item.data.id));
 
   return hash;
 }
 
+/**
+ * `close` and `submit` from a command (Methodology §6): the code as it is now needs a green
+ * `gcf verify`, unless the operator says why not (`unverified`, written into the move's
+ * commit). The integrator's moves rest on the branch's trailer instead.
+ */
+function needVerified(m, opts) {
+  if (!opts.requireVerify || opts.unverified) return;
+  const id = String(m.item.data.id);
+  const problem = verifyGateProblem(m.projectDir, id, m.item.data.type);
+  if (problem) throw new Error(problem);
+}
+
+/** The verify gate's refusal, or null; a git that cannot hash the code refuses too. */
+function verifyGateProblem(projectDir, id, type) {
+  try {
+    return unverifiedProblem(projectDir, id, type);
+  } catch (e) {
+    return (
+      `${id}: cannot hash the code for the verify gate (${e.message}) — fix that, or the ` +
+      'human passes --unverified "<why>"'
+    );
+  }
+}
+
+/** The commit's tail of a move made without a green verify. */
+const unverifiedTail = (opts) => (opts.unverified ? ` (unverified: ${opts.unverified})` : '');
+
 const writeItem = (item, data, body = item.body) => atomicWrite(item.file, serialize(data, body));
 
 /** `data` without the keys named — a field that no longer applies leaves the frontmatter. */
@@ -481,11 +510,12 @@ async function submitItemUnlocked(projectDir, id, opts = {}) {
   if (m.item.data.gate === 'auto')
     throw new Error(`${id} has gate auto: nobody waits for it — close it with gcf close ${id}`);
   refuseOpenDepends(m, 'submit', { waiting: true });
+  needVerified(m, opts);
   const status = m.item.data.gate === 'verdict' ? 'awaiting-verdict' : 'awaiting-decision';
   const data = { ...without(m.item.data, 'blocked'), status, since: headHash(projectDir) };
   m.step(() => writeItem(m.item, data));
 
-  return { id, status, hash: await finish(m, 'submit', id, commit) };
+  return { id, status, hash: await finish(m, 'submit', `${id}${unverifiedTail(opts)}`, commit) };
 }
 
 /** Why a soft gate-auto item cannot close unplayed, or null: only an `added` comes back out. */
@@ -556,11 +586,13 @@ async function closeItemUnlocked(projectDir, id, opts = {}) {
     if (m.item.data.gate !== 'auto')
       throw new Error(`${id} has gate ${m.item.data.gate}: submit it, the operator closes it`);
     refuseOpenDepends(m, 'close');
+    needVerified(m, opts);
     if (unplayed) closeUnplayed(m);
     else await closeEnding(m, constraints);
   }
 
-  const hash = await finish(m, 'close', `${id}${unplayed ? ' → unplayed' : ''}`, commit);
+  const tail = `${id}${unplayed ? ' → unplayed' : ''}${unverifiedTail(opts)}`;
+  const hash = await finish(m, 'close', tail, commit);
 
   return { id, hash, unplayed };
 }
@@ -905,6 +937,8 @@ async function prioritizeItemsUnlocked(projectDir, ids, { commit = true } = {})
   });
   const hash = await commitMove(projectDir, `gcf(priority): ${ids.join(', ')}`, {
     files: items.map((i) => i.file),
+    // An item made with `item new` and never committed rides along: all of it is new work.
+    inputs: items.map((i) => i.file).filter((f) => !tracked(projectDir, f)),
     mutate: async () => {
       for (const [n, i] of items.entries())
         await atomicWrite(i.file, serialize({ ...i.data, priority: ranks[n] }, i.body));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-aif-ext",
-  "version": "0.7.9",
+  "version": "0.7.13",
   "description": "Game Context Framework for AI Factory",
   "type": "module",
   "license": "MIT",

package/skills/gcf-triage/SKILL.md

@@ -23,13 +23,14 @@ forbidden_behaviors:
 workflow:
 1. run `ai-factory gcf inbox --json`; read `gcf/LIVE.md` and `gcf/INDEX.md` to know what exists and what is in work
 2. classify each entry: bug, tune of a live or unplayed item, idea for the design, request (an asset file, a question), duplicate, or noise; search `gcf/graveyard.md` for each idea and bug
-3. for each entry propose one call with its fields: a bug gets type `bug`, severity and a repro; a tune names the item and the note; an idea names the subsystem; a duplicate names the item it repeats
-4. present the calls to the human, calls per message <= 5, and apply only the approved ones
-5. a bug or other work: run `ai-factory gcf item new <id> --type <type> [--severity <level>] --from <in-id>`, then write its `intent:` and `repro:`
-6. a tune of an item waiting for its verdict: keep the note for the verdict session and run `ai-factory gcf inbox drop <in-id>`; the note goes in through `/gcf-verdict … tune --note`
-7. an idea for the design: write a unit with `TBD` slots in `gcf/design/<system>.md` and its backlog line, then run `ai-factory gcf inbox drop <in-id>`
-8. a duplicate or noise: run `ai-factory gcf inbox drop <in-id>`
-9. report what each entry became and how many entries remain
+3. a lesson (`source: lesson`, with its `kind` and the `item` it came from) is what got in an agent's way: propose the fix it asks for - a project rule, a tech item, a note for the framework or the template - or noise
+4. for each entry propose one call with its fields: a bug gets type `bug`, severity and a repro; a tune names the item and the note; an idea names the subsystem; a duplicate names the item it repeats
+5. present the calls to the human, calls per message <= 5, and apply only the approved ones
+6. a bug or other work: run `ai-factory gcf item new <id> --type <type> [--severity <level>] --from <in-id>`, then write its `intent:` and `repro:`
+7. a tune of an item waiting for its verdict: keep the note for the verdict session and run `ai-factory gcf inbox drop <in-id>`; the note goes in through `/gcf-verdict … tune --note`
+8. an idea for the design: write a unit with `TBD` slots in `gcf/design/<system>.md` and its backlog line, then run `ai-factory gcf inbox drop <in-id>`
+9. a duplicate or noise: run `ai-factory gcf inbox drop <in-id>`
+10. report what each entry became and how many entries remain
 
 invocation:
 - run after a playtest session, after a CI run that added entries, or when the user asks to triage

package/templates/agents-block.md

@@ -1,40 +1,42 @@
-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; a text that starts with a hyphen goes as `inbox add --text="<text>"`
-- 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`
-- a word added to a `not:` of `gcf/glossary.md` leaves `gcf/design/` and every item but an unplayed one in the same commit: `ai-factory gcf design check` names each hit as M4
-- 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
-- an item the human wants run on a given model or effort gets `item new <id> --model <m> --effort <e>`: the harness run passes both to the agent
-- ready items run in `priority:` order, lower first: rank a set of items with `ai-factory gcf prioritize <id> <id> …`, and put an id in `depends` only when the item uses that one's data or code
-- a D1 record that carries the human's `answer:` goes into the slot of each unit it blocks, with `answer: q-NNN`, and then leaves `gcf/open-questions.md`
-- 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 change what agent runs may do: `ai-factory gcf permissions` and its deny groups belong to the human
-- do not change a setting of `gcf/config.yml`: `ai-factory gcf config set` belongs to the human
-- 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
+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; a text that starts with a hyphen goes as `inbox add --text="<text>"`
+- 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
+- a question about how the runs go (the share that reached their move, cost, plan checks, DoD attempts, guard firings) is answered by `ai-factory gcf-harness metrics`
+- 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
+- `submit` and `close` refuse code that changed since its last green `gcf verify`: run it again after any fix; `--unverified "<why>"` is the human's call, never the agent's
+- 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`
+- a word added to a `not:` of `gcf/glossary.md` leaves `gcf/design/` and every item but an unplayed one in the same commit: `ai-factory gcf design check` names each hit as M4
+- 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
+- an item the human wants run on a given model or effort gets `item new <id> --model <m> --effort <e>`: the harness run passes both to the agent
+- ready items run in `priority:` order, lower first: rank a set of items with `ai-factory gcf prioritize <id> <id> …`, and put an id in `depends` only when the item uses that one's data or code
+- a D1 record that carries the human's `answer:` goes into the slot of each unit it blocks, with `answer: q-NNN`, and then leaves `gcf/open-questions.md`
+- 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 change what agent runs may do: `ai-factory gcf permissions` and its deny groups belong to the human
+- do not change a setting of `gcf/config.yml`: `ai-factory gcf config set` belongs to the human
+- 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

@@ -7,14 +7,25 @@ context_budget: 30000
 pillars_budget: 1500
 envelope_default_spread: 0.3
 unplayed_warn_after: 5
-plan_passes: 5
+plan_passes: 3
 dod_attempts: 2
+# Minutes a dod.test or dod.build command may take before it is killed with all it started
+# (0: no limit): a hung engine fails the DoD instead of holding the run.
+dod_timeout_min: 60
 # Agent runs (Harness-PRD §7): the share of the context window at which a run hands its item
 # to a fresh session (0: never), the window when the model's is unknown (0: the model's), and
 # the agent's auto-compaction share (0: its default; at least the handoff share + 15).
 context_handoff_pct: 60
 context_window: 0
 auto_compact_pct: 0
+# Lessons (Methodology §5.2.2): at the end of each session on an item its agent says what got in
+# its way, into the inbox. `ai-factory gcf lessons prompt <id>` prints the questions. Uncomment to
+# turn them off, to ask what the project's template should learn, or to add questions:
+# lessons:
+#   off: true
+#   template: ../my-template
+#   questions:
+#     - which step of this item took the longest, and why?
 # What agent runs may not do lives in an `agent:` section that `ai-factory gcf permissions`
 # and the board write; without it the default deny groups hold.
 # The project's own commands for the auto DoD (Methodology §6); the engine does not matter.