gcf-aif-ext 0.7.8 → 0.7.10

package/README.md

@@ -50,6 +50,20 @@ 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.7.10
+
+- Lessons: what got in an agent's way, asked at the end of its session (Methodology §5.2.2). `gcf lessons prompt <id>` prints the questions: tools and their workarounds, project rules that are missing or conflict, trouble with GCF itself, and, with `lessons.template` in `gcf/config.yml`, what the project's template should learn; `lessons.questions` adds the operator's own, `lessons.off: true` turns them off. `gcf lessons add <id>` records each answer as an inbox entry with the source `lesson:<kind>:<item>`; `gcf board --json` gives such an entry `source: lesson`, `kind` and `item`, and each item its `lessons` count. The harness 0.9.2 asks them in a turn of its own after each session, so they stay out of the agent's working context; `/gcf-run` without the harness asks them at its end. `/gcf-triage` proposes a fix for each.
+
+- `gcf verify` kills a `dod.test` or `dod.build` command that runs longer than `dod_timeout_min` minutes (60 by default, 0 for no limit), with every process it started, and fails the DoD: `dod.test timed out after 60 min (dod_timeout_min), killed: <command>`. Before, a hung engine held the check, and a run with it, for hours.
+- `gcf prioritize` takes an item made with `gcf item new` and never committed, and commits it with its rank. Before, it refused the item as an uncommitted file. An item with uncommitted edits is still refused.
+- `gcf playtest session` lists the items awaiting a decision in a section of their own: before, they were missing from the sheet.
+- `plan_passes` defaults to 3 (was 5). A plan converges when an improve pass finds nothing blocking (Methodology §5.2.1); a project that sets `plan_passes` keeps its value.
+
+### 0.7.9
+
+- `gcf done`, `gcf drop` (a design unit), `gcf pillar rename|retire`, `gcf phase next` and `gcf question answer` hold the main lock from their first read to their commit, as the work item moves do. Before, two at once could both pass their checks and write over each other: an answer lost, a unit in the history twice.
+- `gcf claim` says the mark lives 2 hours without a gcf command, as it does (it said 30 minutes).
+
 ### 0.7.8
 
 - An open question's field written as a YAML block (`assumed: |` or `>`, and the lines under it) reads as its text: before, `gcf board --json` gave the block sign `|`. Every reader of `gcf/open-questions.md` (the board, `design check`, the audit, `context`, the index) reads the fields the same way:

package/commands/gcf.js

@@ -33,7 +33,7 @@ function registerSession(gcf) {
     .command('claim <id>')
     .description(
       'An agent session starts working the item on main: the board shows it running until a ' +
-        'move ends it, release, or 30 minutes without a gcf command on it',
+        'move ends it, release, or 2 hours without a gcf command on it',
     )
     .action(async (id) => {
       const { buildLedger } = await lib('ledger');
@@ -308,7 +308,16 @@ function sessionHead(s) {
 /** The session sheet: the build, then per item what to check and how to get there. */
 function sessionText(s) {
   const lines = sessionHead(s);
-  if (!s.items.length) return [...lines, 'nothing waits for a playtest'].join('\n');
+  const decide = s.decisions.length
+    ? [
+        '',
+        '## decide: no verdict, a go or a no; play it first where the build shows it',
+        ...s.decisions.map(
+          (d) => `[ ] ${d.id} [${d.system.join(',')}] ${d.title ?? d.intent ?? ''}`,
+        ),
+      ]
+    : [];
+  if (!s.items.length) return [...lines, 'nothing waits for a playtest', ...decide].join('\n');
   let group = null;
   // Items come sorted by their first subsystem: one header each, so play goes system by system.
   for (const c of s.items) {
@@ -326,8 +335,10 @@ function sessionText(s) {
 
   return [
     ...lines,
+    ...decide,
     '',
     'after play: a verdict per item — /gcf-verdict <id> keep|tune|kill;',
+    ...(s.decisions.length ? ['a decision — /gcf-verdict <id> go|no;'] : []),
     'free notes — ai-factory gcf inbox add --source playtest "<note>"',
   ].join('\n');
 }
@@ -846,7 +857,15 @@ function registerInbox(gcf) {
       const { gcfRoot } = await lib('gcf-paths');
       const list = await (await lib('inbox')).listInbox(gcfRoot());
       out(o.json, list, (l) =>
-        l.length ? l.map((e) => `${e.id} [${e.source}] ${e.text}`).join('\n') : 'inbox empty',
+        l.length
+          ? l
+              .map((e) => {
+                const source = e.kind ? `lesson:${e.kind}:${e.item}` : e.source;
+
+                return `${e.id} [${source}] ${e.text}`;
+              })
+              .join('\n')
+          : 'inbox empty',
       );
     });
   inbox
@@ -881,6 +900,46 @@ function registerInbox(gcf) {
     });
 }
 
+function registerLessons(gcf) {
+  const lessons = gcf
+    .command('lessons')
+    .description("What got in an agent's way, asked at the end of its session (into the inbox)");
+  lessons
+    .command('prompt <id>')
+    .description('Print the end-of-session questions for the agent that worked item <id>')
+    .option('--json', 'machine output: {off, prompt}, the prompt asking for a JSON reply')
+    .action(async (id, o) => {
+      const r = await (
+        await lib('lessons')
+      ).lessonsPrompt(process.cwd(), id, { reply: o.json ? 'json' : 'cli' });
+      out(o.json, r, (p) => (p.off ? 'lessons are off (gcf/config.yml lessons.off)' : p.prompt));
+    });
+  lessons
+    .command('add <id>')
+    .description('Record lessons of item <id> as inbox entries')
+    .option('--kind <kind>', 'tool | rules | framework | template | other')
+    .option('--text <text>', 'one finding')
+    .option('--where <place>', 'file:line it is about')
+    .option('--from <file>', 'a JSON array [{kind, text, where}] instead of --kind/--text')
+    .option('--commit', 'commit it (gcf(lessons)): for a caller with no console, e.g. the harness')
+    .action(async (id, o) => {
+      const { addLessons, lessonsFile, KINDS } = await lib('lessons');
+      if (Boolean(o.from) === Boolean(o.text))
+        throw new Error('give the lessons once: --from <file>, or --kind and --text');
+      if (o.text && !KINDS.includes(o.kind)) throw new Error(`--kind must be ${KINDS.join(' | ')}`);
+      const list = o.from
+        ? await lessonsFile(o.from)
+        : [{ kind: o.kind, text: o.text, where: o.where }];
+      if (!Array.isArray(list)) throw new Error(`${o.from}: lessons must be a JSON array`);
+      if (!list.length) return console.log(`recorded 0 lessons for ${id}`);
+      let n = 0;
+      const hash = await inboxMove(o.commit, `gcf(lessons): ${id}`, async (root) => {
+        n = (await addLessons(root, id, list)).length;
+      });
+      console.log(`recorded ${n} lessons for ${id}${shortHash(hash)}`);
+    });
+}
+
 function registerLive(gcf) {
   const live = gcf
     .command('live')
@@ -977,6 +1036,10 @@ function registerBoard(gcf) {
         ].join('\n'),
       );
     });
+}
+
+/** The human's settings a board edits through the core: config keys and agent deny rules. */
+function registerSettings(gcf) {
   const config = gcf
     .command('config')
     .description("The human's settings of gcf/config.yml: list them, or set one (commit)")
@@ -1184,11 +1247,13 @@ export function register(program) {
   registerSession(gcf);
   registerDecide(gcf);
   registerInbox(gcf);
+  registerLessons(gcf);
   registerLive(gcf);
   registerPlan(gcf);
   registerVerify(gcf);
   registerIntegrate(gcf);
   registerBoard(gcf);
+  registerSettings(gcf);
   registerPhase(gcf);
   registerHooksInstall(gcf);
   registerLint(gcf);

package/extension.json

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

package/lib/agent-permissions.js

@@ -7,10 +7,12 @@
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import YAML from 'yaml';
 import { commitMove } from './unit-ops.js';
 import { atomicWrite } from './safe-path.js';
 import { gcfRoot } from './gcf-paths.js';
+import { configDoc, ensureMap } from './config-set.js';
+
+const GROUPS_SHAPE = 'gcf/config.yml: agent.groups must map a group id to true or false';
 
 // A shell command pattern turns into a rule for both shell tools: on Windows the agent runs
 // commands through PowerShell, which Bash rules do not cover.
@@ -75,7 +77,8 @@ export const DENY_GROUPS = [
   {
     id: 'human-moves',
     label:
-      "the human's GCF moves: verdict, decide, answer, unblock, phase, pillars, settings, permissions, setup",
+      "the human's GCF moves: verdict, decide, answer, unblock, phase, pillars, settings, " +
+      'permissions, setup',
     on: true,
     rules: shell(
       'ai-factory gcf verdict*',
@@ -159,12 +162,12 @@ function rules(agent, key) {
  */
 function choices(agent) {
   const g = agent.groups ?? {};
-  if (typeof g !== 'object' || Array.isArray(g))
-    throw new Error('gcf/config.yml: agent.groups must map a group id to true or false');
+  if (typeof g !== 'object' || Array.isArray(g)) throw new Error(GROUPS_SHAPE);
   for (const [id, on] of Object.entries(g))
     if (!known(id) || typeof on !== 'boolean')
       throw new Error(
-        `gcf/config.yml: agent.groups.${id} must be true or false, for one of ${GROUP_IDS.join(' | ')}`,
+        `gcf/config.yml: agent.groups.${id} must be true or false, ` +
+          `for one of ${GROUP_IDS.join(' | ')}`,
       );
 
   return g;
@@ -214,18 +217,9 @@ export async function setPermissions(projectDir, change, { commit = true } = {})
   const hash = await commitMove(projectDir, 'gcf(permissions): agent deny rules', {
     files: [file],
     mutate: async () => {
-      const doc = YAML.parseDocument(existsSync(file) ? await readFile(file, 'utf8') : '');
-      if (doc.errors.length) throw new Error(`gcf/config.yml: ${doc.errors[0].message}`);
-      if (!YAML.isMap(doc.contents)) doc.contents = doc.createNode({});
-      // A blank `agent:` (or one holding only comments) is no map yet.
-      const agent = doc.get('agent', true);
-      if (agent != null && !YAML.isMap(agent) && !(YAML.isScalar(agent) && agent.value == null))
-        throw new Error('gcf/config.yml: agent must be a mapping');
-      if (!YAML.isMap(agent)) doc.set('agent', doc.createNode({}));
-      const groups = doc.getIn(['agent', 'groups'], true);
-      if (groups != null && !YAML.isMap(groups) && !(YAML.isScalar(groups) && groups.value == null))
-        throw new Error('gcf/config.yml: agent.groups must map a group id to true or false');
-      if (!YAML.isMap(groups)) doc.setIn(['agent', 'groups'], doc.createNode({}));
+      const doc = configDoc(existsSync(file) ? await readFile(file, 'utf8') : '');
+      ensureMap(doc, ['agent'], 'gcf/config.yml: agent must be a mapping');
+      ensureMap(doc, ['agent', 'groups'], GROUPS_SHAPE);
       const current = agentOf({ agent: doc.toJS().agent });
       checkChange(change, current);
       for (const id of change.on ?? []) doc.setIn(['agent', 'groups', id], true);

package/lib/board.js

@@ -213,6 +213,8 @@ async function itemOf(projectDir, c, verified) {
     moves: running ? [] : movesOf(c.data),
     file: `gcf/work/${c.name}`,
     log: logOf(projectDir, id),
+    // Filled by board() from the inbox.
+    lessons: 0,
     ...(await progress(projectDir, c)),
   };
 }
@@ -224,6 +226,9 @@ export async function board(projectDir) {
   const items = [];
   for (const c of ledger.items) items.push(await itemOf(projectDir, c, verified));
   inRunOrder(items);
+  const inbox = await listInbox(root);
+  // Where agents struggle: the lessons in the inbox each item's sessions left.
+  for (const i of items) i.lessons = inbox.filter((e) => e.item === i.id).length;
 
   const config = await readConfig(root);
   const live = await readLive(root);
@@ -231,7 +236,7 @@ export async function board(projectDir) {
   return {
     schema: BOARD_SCHEMA,
     run_mode: config.run_mode,
-    // What the harness hands its agent runs (Harness-PRD §7): the deny rules and the context limits.
+    // What the harness hands its agent runs (Harness-PRD §7): deny rules and the context limits.
     agent: agentOf(config),
     // The human's settings of config.yml, each with its value and default (`gcf config set`).
     settings: settingsOf(await readRawConfig(root)),
@@ -248,7 +253,7 @@ export async function board(projectDir) {
     ),
     items,
     wip: wipOf(ledger.items, config),
-    inbox: await listInbox(root),
+    inbox,
     questions: await listQuestions(root),
     history: await historyOf(root),
     graveyard: await graveyardOf(root),

package/lib/config-set.js

@@ -16,13 +16,31 @@ import { configOf, DEFAULT_CONFIG, gcfRoot, RUN_MODES } from './gcf-paths.js';
 // Thrown inside the move to leave without a write or a commit.
 const NO_CHANGE = new Error('no change');
 
+/** gcf/config.yml as a YAML document with a map on top: an edit keeps its comments. */
+export function configDoc(text) {
+  const doc = YAML.parseDocument(text);
+  if (doc.errors.length) throw new Error(`gcf/config.yml: ${doc.errors[0].message}`);
+  if (!YAML.isMap(doc.contents)) doc.contents = /** @type {any} */ (doc.createNode({}));
+
+  return doc;
+}
+
+/** Make `keys` a map. A blank key (`dod:` with nothing or only comments under it) is none yet. */
+export function ensureMap(doc, keys, error) {
+  const node = doc.getIn(keys, true);
+  if (YAML.isMap(node)) return;
+  if (node != null && !(YAML.isScalar(node) && node.value == null)) throw new Error(error);
+  doc.setIn(keys, doc.createNode({}));
+}
+
 /** @type {{ key: string, kind: Kind, label: string }[]} */
 export const SETTINGS = [
   {
     key: 'run_mode',
     kind: 'mode',
     label:
-      'how a run drives an item: worktree (several at once) or main (one at a time in the project folder)',
+      'how a run drives an item: worktree (several at once) or main (one at a time in the ' +
+      'project folder)',
   },
   { key: 'dod.test', kind: 'command', label: "the project's test command for the DoD, or none" },
   { key: 'dod.build', kind: 'command', label: "the project's build command for the DoD, or none" },
@@ -32,6 +50,11 @@ export const SETTINGS = [
     label: 'improve passes a plan may take before the item blocks',
   },
   { key: 'dod_attempts', kind: 'number', label: 'DoD attempts before the item blocks' },
+  {
+    key: 'dod_timeout_min',
+    kind: 'number',
+    label: 'minutes a DoD command may take before it is killed (0: no limit)',
+  },
   {
     key: 'wip_built_limit',
     kind: 'number',
@@ -132,21 +155,9 @@ export async function setConfig(projectDir, key, text, { commit = true } = {}) {
     files: [file],
     mutate: async () => {
       const text = existsSync(file) ? await readFile(file, 'utf8') : '';
-      const doc = YAML.parseDocument(text);
-      if (doc.errors.length) throw new Error(`gcf/config.yml: ${doc.errors[0].message}`);
-      if (!YAML.isMap(doc.contents)) doc.contents = doc.createNode({});
-      // A blank parent (`dod:` with nothing under it) is no map yet.
-      if (keys.length > 1) {
-        const parent = doc.get(keys[0], true);
-        if (
-          parent != null &&
-          !YAML.isMap(parent) &&
-          !(YAML.isScalar(parent) && parent.value == null)
-        )
-          throw new Error(`gcf/config.yml: ${keys[0]} must map its keys`);
-        if (!YAML.isMap(parent)) doc.set(keys[0], doc.createNode({}));
-      }
-
+      const doc = configDoc(text);
+      if (keys.length > 1)
+        ensureMap(doc, [keys[0]], `gcf/config.yml: ${keys[0]} must map its keys`);
       if (value === null) doc.deleteIn(keys);
       else doc.setIn(keys, value);
       raw = doc.toJS();

package/lib/gcf-paths.js

@@ -14,8 +14,10 @@ export const DEFAULT_CONFIG = {
   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 (0: no limit).
+  dod_timeout_min: 60,
   // A run hands its item to a fresh session at this share of the context window (0: never);
   // the window comes from the model unless context_window sets it (Harness-PRD §7).
   context_handoff_pct: 60,
@@ -68,6 +70,7 @@ export function configOf(parsed) {
   if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
     throw new Error('gcf/config.yml must be a key: value mapping');
   // A blank `key:` parses as null and means "not set", like an absent key.
+  /** @type {Record<string, any>} */
   const config = {
     ...DEFAULT_CONFIG,
     ...Object.fromEntries(Object.entries(parsed).filter(([, v]) => v !== null)),

package/lib/inbox.js

@@ -12,18 +12,27 @@ export const INBOX_HEAD =
   'is erased\n';
 export const SOURCES = ['playtest', 'ci', 'agent', 'operator'];
 const LINE = /^- (in-[0-9a-f]+) \| (\S+) \| (.+)$/;
+// An agent's lesson (lessons.js): `lesson:<kind>:<item-id>`.
+const LESSON = /^lesson:([a-z]+):([a-z0-9][a-z0-9-]*)$/;
 
 const inboxFile = (root) => path.join(root, 'inbox.md');
 
-/** @returns {Promise<Array<{id: string, source: string, text: string}>>} */
+/**
+ * Every entry; a lesson reads as source `lesson` with its `kind` and the `item` it came from.
+ * @typedef {{id: string, source: string, text: string, kind?: string, item?: string}} Entry
+ * @returns {Promise<Entry[]>}
+ */
 export async function listInbox(root) {
   const file = inboxFile(root);
   if (!existsSync(file)) return [];
 
   return (await readFile(file, 'utf8')).split(/\r?\n/).flatMap((l) => {
     const m = l.match(LINE);
+    if (!m) return [];
+    const lesson = m[2].match(LESSON);
+    const entry = { id: m[1], source: m[2], text: m[3].trim() };
 
-    return m ? [{ id: m[1], source: m[2], text: m[3].trim() }] : [];
+    return [lesson ? { ...entry, source: 'lesson', kind: lesson[1], item: lesson[2] } : entry];
   });
 }
 
@@ -31,7 +40,8 @@ export async function listInbox(root) {
 export async function addInbox(root, text, source = 'operator', now = new Date().toISOString()) {
   const clean = String(text).replace(/\s+/g, ' ').trim();
   if (!clean) throw new Error('an inbox entry needs text');
-  if (!SOURCES.includes(source)) throw new Error(`source must be ${SOURCES.join(' | ')}`);
+  if (!SOURCES.includes(source) && !LESSON.test(source))
+    throw new Error(`source must be ${SOURCES.join(' | ')}`);
   const id = `in-${createHash('sha1').update(`${now}\n${clean}`).digest('hex').slice(0, 8)}`;
   const file = inboxFile(root);
   const old = existsSync(file) ? await readFile(file, 'utf8') : INBOX_HEAD;

package/lib/lessons.js

@@ -0,0 +1,131 @@
+// Lessons (Methodology §5.2.2): at the end of a session on a work item, its agent says what got in
+// its way — a tool, a rule, the framework, the project's template. Each answer is an inbox entry
+// with the source `lesson:<kind>:<item>`, so the operator triages it like any raw input and the
+// board shows where agents struggle. The questions stay out of the agent's working context until
+// the session ends: the harness asks them in one more turn, `/gcf-run` asks them at its close.
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { readRawConfig } from './gcf-paths.js';
+import { addInbox } from './inbox.js';
+import { isValidId } from './id.js';
+
+export const KINDS = ['tool', 'rules', 'framework', 'template', 'other'];
+
+const QUESTIONS = {
+  tool:
+    'a tool, the editor or the environment behaved wrongly or cost time: what happened, and ' +
+    'what was the workaround?',
+  rules:
+    'a project rule was missing, unclear or contradicted another: name the file and line of ' +
+    'each, and what the rule should say',
+  framework:
+    'GCF got in the way: ai-factory gcf, the gcf-run steps, the harness or its hooks - what ' +
+    'cost time, and what would have helped?',
+};
+
+/**
+ * The project's lessons settings from the `lessons:` section of gcf/config.yml: `off`, the
+ * project `template` the lessons may feed, and `questions` the operator adds. Throws on a
+ * section of the wrong shape.
+ */
+export function lessonsConfig(raw) {
+  const l = raw?.lessons ?? {};
+  if (typeof l !== 'object' || Array.isArray(l))
+    throw new Error('gcf/config.yml: lessons must map off:, template: and questions:');
+  const questions = l.questions ?? [];
+  if (!Array.isArray(questions) || questions.some((q) => typeof q !== 'string' || !q.trim()))
+    throw new Error('gcf/config.yml: lessons.questions must be a list of questions');
+  if (l.template != null && typeof l.template !== 'string')
+    throw new Error('gcf/config.yml: lessons.template must be a path');
+
+  return { off: l.off === true, template: l.template?.trim() || null, questions };
+}
+
+/** The questions the agent answers, each with the kind its answer records as. */
+function questionsOf(config) {
+  return [
+    ...Object.entries(QUESTIONS).map(([kind, text]) => ({ kind, text })),
+    ...(config.template
+      ? [
+          {
+            kind: 'template',
+            text:
+              `what would the next project made from the template ${config.template} need ` +
+              'that this one had to build, fix or work around?',
+          },
+        ]
+      : []),
+    ...config.questions.map((text) => ({ kind: 'other', text })),
+  ];
+}
+
+/**
+ * The end-of-session prompt for item `id`. `reply: 'json'` asks for a JSON array (the harness
+ * records it); `reply: 'cli'` asks the agent to record each answer with `gcf lessons add`.
+ */
+export async function lessonsPrompt(projectDir, id, { reply = 'cli' } = {}) {
+  if (!isValidId(id)) throw new Error(`${id} is not an item id`);
+  const config = lessonsConfig(await readRawConfig(path.join(path.resolve(projectDir), 'gcf')));
+  const asked = questionsOf(config)
+    .map((q, i) => `${i + 1}. ${q.kind}: ${q.text}`)
+    .join('\n');
+  const how =
+    reply === 'json'
+      ? 'Reply with ONLY a JSON array, no other text: ' +
+        '[{"kind": "<the kind of its question>", "text": "<one finding>", ' +
+        '"where": "<file:line or null>"}]; ' +
+        'reply [] when nothing got in the way.'
+      : `Record each finding with: ai-factory gcf lessons add ${id} --kind <the kind of its ` +
+        'question> --text "<one finding>" [--where <file:line>]. Record nothing when nothing ' +
+        'got in the way.';
+  const prompt = [
+    `The work on ${id} in this session is over. Before the session ends, tell the operator ` +
+      'what got in your way, so it can be removed.',
+    'Answer from this session only, one finding per entry, in a sentence or two; skip a ' +
+      'question with nothing to say, and never invent one.',
+    asked,
+    // The harness's turn comes after the item's commit and its verified trailer: an edit then
+    // would leave the checkout dirty or move the trailer off the tip.
+    reply === 'json'
+      ? 'Do not edit, write or commit any file in this turn: only answer.'
+      : 'If the project keeps its own lessons file (its rules name it), update it now as they say.',
+    how,
+  ].join('\n\n');
+
+  return { off: config.off, prompt };
+}
+
+/** A lesson as the agent gave it, checked: `{kind, text, where}`. */
+function lessonOf(raw, i) {
+  const kind = KINDS.includes(raw?.kind) ? raw.kind : 'other';
+  const text = String(raw?.text ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!text) throw new Error(`lesson ${i + 1} has no text`);
+  const where = raw?.where ? String(raw.where).replace(/\s+/g, ' ').trim() : '';
+
+  return { kind, text: where ? `${text} (${where})` : text };
+}
+
+/**
+ * Record `lessons` of item `id` as inbox entries; `{kind, text, where?}` each, a kind outside
+ * KINDS reads as other. Returns the entries written.
+ */
+export async function addLessons(root, id, lessons) {
+  if (!isValidId(id)) throw new Error(`${id} is not an item id`);
+  if (!Array.isArray(lessons)) throw new Error('lessons must be a JSON array');
+  const checked = lessons.map(lessonOf);
+  const out = [];
+  for (const l of checked) out.push(await addInbox(root, l.text, `lesson:${l.kind}:${id}`));
+
+  return out;
+}
+
+/** The lessons of a JSON file: an array, as the harness writes it. */
+export async function lessonsFile(file) {
+  try {
+    return JSON.parse(await readFile(file, 'utf8'));
+  } catch (e) {
+    throw new Error(`cannot read lessons from ${file}: ${e.message}`, { cause: e });
+  }
+}

package/lib/main-lock.js

@@ -140,3 +140,14 @@ export async function withMainLock(projectDir, fn, { waitMs = 60000 } = {}) {
     if (text.includes(token)) await unlink(file).catch(() => {});
   }
 }
+
+/**
+ * A committed move holds the main lock from its first read to its commit (Methodology §7): one
+ * that read the ledger before taking it would write over a move committed meanwhile.
+ * @template T
+ * @param {string} projectDir
+ * @param {boolean} commit
+ * @param {() => Promise<T>} move
+ */
+export const locked = (projectDir, commit, move) =>
+  commit ? withMainLock(projectDir, move) : move();

package/lib/phase.js

@@ -8,6 +8,7 @@ import { readLiveStrict, writeLive, liveFile } from './live.js';
 import { buildLedger } from './ledger.js';
 import { ITEM_TYPES } from './validate-item.js';
 import { commitMove } from './unit-ops.js';
+import { locked } from './main-lock.js';
 
 const ALL = ITEM_TYPES;
 const SOFT = ['mechanic', 'resource'];
@@ -206,8 +207,12 @@ export async function phaseStatus(projectDir) {
  * The operator moves the phase on, commit `gcf(phase): <from> → <to>`. An unmet criterion needs
  * `reason`, which the commit carries; the move itself is the operator's word on one that only
  * the operator can check.
+ * @type {typeof nextPhaseUnlocked}
  */
-export async function nextPhase(projectDir, { reason = '', commit = true } = {}) {
+export const nextPhase = (projectDir, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => nextPhaseUnlocked(projectDir, opts));
+
+async function nextPhaseUnlocked(projectDir, { reason = '', commit = true } = {}) {
   const status = await phaseStatus(projectDir);
   if (!status.next) throw new Error(`${status.phase} is the last phase`);
   const unmet = status.criteria.filter((c) => c.met === false);

package/lib/pillars.js

@@ -10,6 +10,7 @@ import { recordsIn } from './design-check.js';
 import { buildLedger } from './ledger.js';
 import { atomicWrite } from './safe-path.js';
 import { commitMove } from './unit-ops.js';
+import { locked } from './main-lock.js';
 
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
@@ -73,7 +74,7 @@ async function revise(projectDir, id, { edit, editPillars, tail, commit }) {
 }
 
 /** `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 } = {}) {
+async function renamePillarUnlocked(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))
@@ -92,7 +93,7 @@ export async function renamePillar(projectDir, from, to, { commit = true } = {})
  * 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 }) {
+async function retirePillarUnlocked(projectDir, id, { reason, commit = true }) {
   const why = String(reason ?? '')
     .replace(/\s+/g, ' ')
     .trim();
@@ -111,3 +112,11 @@ export async function retirePillar(projectDir, id, { reason, commit = true }) {
     commit,
   });
 }
+
+// PILLARS.md and the citing files are read for the edit: the lock holds from that read on.
+/** @type {typeof renamePillarUnlocked} */
+export const renamePillar = (projectDir, from, to, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => renamePillarUnlocked(projectDir, from, to, opts));
+/** @type {typeof retirePillarUnlocked} */
+export const retirePillar = (projectDir, id, opts) =>
+  locked(projectDir, opts.commit ?? true, () => retirePillarUnlocked(projectDir, id, opts));

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/question-fields.js

@@ -26,6 +26,7 @@ const BLOCK = /^([|>])[-+]?\d?[-+]?(\s+#.*)?$/;
  */
 function folded(lines) {
   let text = '';
+  /** @type {'text' | 'more' | null} */
   let prev = null;
   let blanks = 0;
   for (const l of lines) {

package/lib/questions.js

@@ -7,6 +7,7 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { atomicWrite } from './safe-path.js';
 import { commitMove } from './unit-ops.js';
+import { locked } from './main-lock.js';
 import { blockEnd, fieldOf, indentOf } from './question-fields.js';
 
 // A D2 carries its assumption and the trigger that brings it back; `lens`, `sections` and `sys`
@@ -93,8 +94,12 @@ function withAnswer(record, answer) {
 /**
  * The human answers question `qid` (`gcf question answer`): the answer goes into its record, one
  * line, and commits as `gcf(answer): <qid>`. Refuses an id the file does not hold.
+ * @type {typeof answerUnlocked}
  */
-export async function answerQuestion(projectDir, qid, answer, { commit = true } = {}) {
+export const answerQuestion = (projectDir, qid, answer, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => answerUnlocked(projectDir, qid, answer, opts));
+
+async function answerUnlocked(projectDir, qid, answer, { commit = true } = {}) {
   const text = String(answer ?? '')
     .replace(/\s+/g, ' ')
     .trim();

package/lib/unit-ops.js

@@ -16,7 +16,7 @@ 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';
+import { locked, withMainLock } from './main-lock.js';
 
 /** A design file's text without the `## <id>` section. */
 export function removeUnit(text, id) {
@@ -265,8 +265,12 @@ async function record(projectDir, message, { files, mutate, commit, inputs = []
 /**
  * A hard unit is built and its tests are green: it leaves design/ without a work item. A line
  * every future reader of the subsystem must remember goes to the systems doc's `constraints:`.
+ * @type {typeof doneUnitUnlocked}
  */
-export async function doneUnit(projectDir, id, { constraints = [], commit = true } = {}) {
+export const doneUnit = (projectDir, id, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => doneUnitUnlocked(projectDir, id, opts));
+
+async function doneUnitUnlocked(projectDir, id, { constraints = [], commit = true } = {}) {
   const root = path.join(path.resolve(projectDir), 'gcf');
   const unit = await designUnit(projectDir, id);
   if (CARD_TYPES.includes(unit.header.type))
@@ -300,8 +304,14 @@ export async function addConstraints(doc, id, constraints) {
   await atomicWrite(doc.file, serialize({ ...doc.data, updated_by: id }, body));
 }
 
-/** A unit is dropped before any work: a graveyard line keeps the reason (Methodology §9). */
-export async function dropUnit(projectDir, id, { reason, tags = [], commit = true }) {
+/**
+ * A unit is dropped before any work: a graveyard line keeps the reason (Methodology §9).
+ * @type {typeof dropUnitUnlocked}
+ */
+export const dropUnit = (projectDir, id, opts) =>
+  locked(projectDir, opts.commit ?? true, () => dropUnitUnlocked(projectDir, id, opts));
+
+async function dropUnitUnlocked(projectDir, id, { reason, tags = [], commit = true }) {
   if (!String(reason ?? '').trim())
     throw new Error('a drop needs a reason: the graveyard keeps it');
   const root = path.join(path.resolve(projectDir), 'gcf');

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,12 +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, 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;
+  // 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}`;
 }
 
 /**
@@ -64,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

@@ -37,7 +37,7 @@ import {
 } from './live.js';
 import { dropInbox } from './inbox.js';
 import { refuseByPhase } from './phase.js';
-import { runHolder, withMainLock } from './main-lock.js';
+import { locked, runHolder } from './main-lock.js';
 import { dropAgentSession, releaseSession, sessionActive } from './session-mark.js';
 
 /**
@@ -905,6 +905,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));
@@ -954,16 +956,6 @@ async function newItemUnlocked(projectDir, spec) {
   return { item: `gcf/work/${spec.id}.md`, hash };
 }
 
-/**
- * A committed move holds the main lock from its first read to its commit (Methodology §7): one
- * that read the ledger before taking it would write over a move committed meanwhile.
- * @template T
- * @param {string} projectDir
- * @param {boolean} commit
- * @param {() => Promise<T>} move
- */
-const locked = (projectDir, commit, move) => (commit ? withMainLock(projectDir, move) : move());
-
 /** @type {typeof submitItemUnlocked} */
 export const submitItem = (projectDir, id, opts = {}) =>
   locked(projectDir, opts.commit ?? true, () => submitItemUnlocked(projectDir, id, opts));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-aif-ext",
-  "version": "0.7.8",
+  "version": "0.7.10",
   "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/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.