gcf-aif-ext 0.7.9 → 0.7.10

package/README.md

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

package/commands/gcf.js

@@ -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')
@@ -1188,6 +1247,7 @@ export function register(program) {
   registerSession(gcf);
   registerDecide(gcf);
   registerInbox(gcf);
+  registerLessons(gcf);
   registerLive(gcf);
   registerPlan(gcf);
   registerVerify(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.9",
+  "version": "0.7.10",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

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);
@@ -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

@@ -50,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',

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,

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/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.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

@@ -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));

package/package.json

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