gcf-aif-ext 0.7.9 → 0.7.13

package/commands/gcf.js

@@ -19,6 +19,23 @@ const out = (json, value, human) =>
 const HARNESS = 'gcf-harness-aif-ext';
 
 const CLAIMED = 'the agent session that claimed the item (gcf claim) records its own move';
+/** close and submit from a command: they need a green verify unless told why not. */
+const verifiedMove = (o) => ({
+  commit: o.commit,
+  requireVerify: true,
+  unverified: o.unverified === undefined ? undefined : reasonOf(o.unverified),
+});
+
+/** The reason of `--unverified`, one line in the commit's subject; an empty one is no reason. */
+function reasonOf(text) {
+  const why = String(text).replace(/\s+/g, ' ').trim();
+  if (!why) throw new Error('--unverified needs the reason the move goes without a green verify');
+
+  return why;
+}
+
+const UNVERIFIED =
+  'move without a green gcf verify of the code as it is now; the reason goes into the commit';
 
 /** `--claimed`: this move comes from the session that holds the item's mark. */
 const claimedBy = (o, id) => {
@@ -308,7 +325,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 +352,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');
 }
@@ -736,10 +764,11 @@ function registerItemMoves(gcf) {
     .command('submit <id>')
     .description('ready → awaiting-verdict / awaiting-decision (commit gcf(submit))')
     .option('--claimed', CLAIMED)
+    .option('--unverified <why>', UNVERIFIED)
     .option('--no-commit', 'skip the commit (tests only)')
     .action(async (id, o) => {
       claimedBy(o, id);
-      const r = await (await ops()).submitItem(process.cwd(), id, { commit: o.commit });
+      const r = await (await ops()).submitItem(process.cwd(), id, verifiedMove(o));
       console.log(`${r.id} → ${r.status}${shortHash(r.hash)}`);
     });
   gcf
@@ -752,12 +781,13 @@ function registerItemMoves(gcf) {
       [],
     )
     .option('--claimed', CLAIMED)
+    .option('--unverified <why>', UNVERIFIED)
     .option('--no-commit', 'skip the commit (tests only)')
     .action(async (id, o) => {
       claimedBy(o, id);
       const r = await (
         await ops()
-      ).closeItem(process.cwd(), id, { constraints: o.constraint, commit: o.commit });
+      ).closeItem(process.cwd(), id, { ...verifiedMove(o), constraints: o.constraint });
       console.log(`closed ${r.id}${r.unplayed ? ' → unplayed' : ''}${shortHash(r.hash)}`);
     });
 }
@@ -846,7 +876,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 +919,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')
@@ -923,6 +1001,10 @@ function registerPlan(gcf) {
     .action(async (id, o) => {
       await touchSession(id);
       const r = await (await lib('plan-check')).planCheck(process.cwd(), id);
+      // Harness-PRD §11: the checks a plan took to converge.
+      await (
+        await lib('metrics')
+      ).logMetric(process.cwd(), 'plan-log.csv', [id, r.ok ? 1 : 0, r.problems?.length ?? 0]);
       out(o.json, r, (x) =>
         x.ok ? `${x.plan}: ${x.done}/${x.tasks} tasks done` : x.problems.join('\n'),
       );
@@ -941,6 +1023,26 @@ function registerVerify(gcf) {
       const r = o.mark
         ? await (await lib('integrate')).markVerified(process.cwd(), id)
         : await (await lib('verify')).verifyItem(process.cwd(), id);
+      // Methodology §6: a green DoD on main is what close and submit ask for, for this code.
+      // A record git cannot write leaves the DoD unproven for the gate: the verify fails.
+      if (r.ok && !o.mark)
+        try {
+          (await lib('verify-stamp')).stampVerified(process.cwd(), id);
+        } catch (e) {
+          r.ok = false;
+          r.checks.push({ name: 'record', ok: false, problems: [e.message] });
+        }
+
+      // Harness-PRD §11: DoD attempts and what failed them.
+      const failed = r.checks.filter((c) => !c.ok).map((c) => c.name);
+      await (
+        await lib('metrics')
+      ).logMetric(process.cwd(), 'verify-log.csv', [
+        id,
+        r.ok ? 1 : 0,
+        failed.join(' '),
+        o.mark ? 1 : 0,
+      ]);
       out(o.json, r, (x) =>
         [
           ...x.checks.flatMap((c) =>
@@ -1188,6 +1290,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.13",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

package/injections/commit-status.md

@@ -1,9 +1,10 @@
-## GCF: work item status after commit (from gcf-aif-ext)
-
-gcf_commit:
-- when `gcf/` exists and the commit implements a work item, commit the implementation first, then move the item with its own command in a follow-up commit
-- gate `verdict` or `decision`: run `ai-factory gcf submit <item-id>` — it waits for the operator, `since:` records where the wait began
-- gate `auto`, every check green: write the item's `live:` delta, then run `ai-factory gcf close <item-id>` — never edit `status:` by hand
-- the work cannot go on: run `ai-factory gcf block <item-id> --reason "<why or the question>"`
-- do not write a terminal status into an item file: a terminal move deletes the file and writes the history or graveyard line itself
-- when the commit makes the tests of a hard unit still in `gcf/design/` green, run `ai-factory gcf done <id>` after it
+## GCF: work item status after commit (from gcf-aif-ext)
+
+gcf_commit:
+- when `gcf/` exists and the commit implements a work item, commit the implementation first, then move the item with its own command in a follow-up commit
+- gate `verdict` or `decision`: run `ai-factory gcf submit <item-id>` — it waits for the operator, `since:` records where the wait began
+- gate `auto`, every check green: write the item's `live:` delta, then run `ai-factory gcf close <item-id>` — never edit `status:` by hand
+- `submit` and `close` refuse code that changed since its last green `ai-factory gcf verify <item-id>`: run it again after any fix; `--unverified` is the human's call
+- the work cannot go on: run `ai-factory gcf block <item-id> --reason "<why or the question>"`
+- do not write a terminal status into an item file: a terminal move deletes the file and writes the history or graveyard line itself
+- when the commit makes the tests of a hard unit still in `gcf/design/` green, run `ai-factory gcf done <id>` after it

package/lib/board.js

@@ -1,5 +1,6 @@
 // `gcf board --json` (Methodology §11): everything a board shows, in one read. The board is a
 // view: it shows these data and runs the same commands as the console; nothing here is stored.
+import { spawnSync } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
@@ -14,6 +15,7 @@ import { wipOf } from './audit-core.js';
 import { runHolder } from './main-lock.js';
 import { ITEM_TYPES } from './validate-item.js';
 import { movesOf } from './transitions.js';
+import { openDepends } from './work-ops.js';
 import { listQuestions } from './questions.js';
 import { sessionActive } from './session-mark.js';
 import { agentOf } from './agent-permissions.js';
@@ -90,6 +92,30 @@ const graveyardOf = async (root) =>
     };
   });
 
+/**
+ * The commit time of each `since` hash, by hash: one git call for the whole board. A hash git
+ * does not know (rebased away), a short one (the core writes it whole) or text that is no hash
+ * gets no time.
+ */
+function commitTimes(projectDir, hashes) {
+  const asked = [...new Set(hashes.filter((h) => /^([0-9a-f]{40}|[0-9a-f]{64})$/.test(h ?? '')))];
+  if (!asked.length) return new Map();
+  const res = spawnSync(
+    'git',
+    ['log', '--no-walk=unsorted', '--ignore-missing', '--format=%H %cI', ...asked],
+    { cwd: projectDir, encoding: 'utf8' },
+  );
+  const found = (res.status === 0 ? res.stdout : '').split('\n').filter(Boolean);
+
+  return new Map(
+    asked.flatMap((h) => {
+      const line = found.find((l) => l.split(' ')[0] === h);
+
+      return line ? [[h, line.split(' ')[1]]] : [];
+    }),
+  );
+}
+
 /** Verified branches; none outside a repository. */
 function verifiedOf(projectDir) {
   try {
@@ -179,8 +205,15 @@ function inRunOrder(items) {
 
 const LISTS = ['children', 'system', 'depends'];
 
+/** `run`, `session` or null. A harness run's lock wins over the mark its run on main holds. */
+function runningKind(projectDir, id) {
+  if (runHolder(projectDir, id) !== null) return 'run';
+
+  return sessionActive(projectDir, id) ? 'session' : null;
+}
+
 /** One item of the board. */
-async function itemOf(projectDir, c, verified) {
+async function itemOf(projectDir, c, verified, ledger) {
   const id = String(c.data.id);
   // A trailer counts only while the item waits on main for its integrate.
   const ready = c.data.status === 'ready' && verified.has(id);
@@ -188,7 +221,8 @@ async function itemOf(projectDir, c, verified) {
   // is a run; a trailer is a passed DoD. A worktree with neither is a run that stopped (a
   // timeout, a stop, a crash): the item is ready, and its next run resumes that worktree. A
   // session the harness kept (`resume`) is resumed by the next run in either mode.
-  const running = runHolder(projectDir, id) !== null || sessionActive(projectDir, id);
+  const kind = runningKind(projectDir, id);
+  const running = kind !== null;
   const resume = c.data.status === 'ready' ? await resumeOf(projectDir, id) : null;
   const resumable =
     !running &&
@@ -206,13 +240,20 @@ async function itemOf(projectDir, c, verified) {
     ...(c.data.severity ? { severity: c.data.severity } : {}),
     ...(c.data.blocked ? { blocked: c.data.blocked } : {}),
     running,
+    // `run`: a harness run's lock; `session`: an operator's or agent's session mark (`gcf claim`).
+    running_kind: kind,
     resumable,
     resume,
     verified: ready,
+    // The dependencies the run gate would refuse a ready item on now (Board-PRD §5.2).
+    waits_for:
+      c.data.status === 'ready' ? openDepends(ledger, c.data.depends ?? [], { waiting: true }) : [],
     // What a board may offer (§4.1): nothing while a run drives the item.
     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)),
   };
 }
@@ -222,8 +263,17 @@ export async function board(projectDir) {
   const ledger = await buildLedger(projectDir);
   const verified = verifiedOf(projectDir);
   const items = [];
-  for (const c of ledger.items) items.push(await itemOf(projectDir, c, verified));
+  for (const c of ledger.items) items.push(await itemOf(projectDir, c, verified, ledger));
   inRunOrder(items);
+  // When the wait began: the time of the commit `since` names (Board-PRD §13).
+  const times = commitTimes(
+    projectDir,
+    items.map((i) => i.since),
+  );
+  for (const i of items) i.since_at = times.get(i.since) ?? null;
+  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 +298,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/integrate.js

@@ -271,6 +271,9 @@ async function integrateOne(projectDir, id) {
  * branch bringing its own lines could not merge over them. Union merge joins the lines.
  */
 function commitMetrics(projectDir) {
+  // A log the harness started on main (run-log, guard-log) is new to git: add it first; only
+  // the logs, never an editor's swap file beside them.
+  git(projectDir, ['add', '--', 'gcf/.metrics/*.csv'], { check: false });
   const dirty = git(projectDir, [
     'status',
     '--porcelain',
@@ -278,17 +281,23 @@ function commitMetrics(projectDir) {
     '--',
     'gcf/.metrics',
   ]);
+  // Best effort: a main mid-rebase or mid-merge keeps its logs for the next integrate, and a
+  // run still starts.
   if (dirty.out)
-    git(projectDir, [
-      'commit',
-      '-q',
-      '--no-verify',
-      '-m',
-      'gcf(metrics): run logs',
-      '--only',
-      '--',
-      'gcf/.metrics',
-    ]);
+    git(
+      projectDir,
+      [
+        'commit',
+        '-q',
+        '--no-verify',
+        '-m',
+        'gcf(metrics): run logs',
+        '--only',
+        '--',
+        'gcf/.metrics',
+      ],
+      { check: false },
+    );
 }
 
 /**
@@ -302,11 +311,13 @@ export async function integrate(projectDir, ids = []) {
     throw new Error(`integrate runs in the main checkout on its branch, not on ${branch}`);
 
   return withMainLock(projectDir, async () => {
-    // Nothing to merge leaves main alone: a run's first integrate must not refuse a dirty tree.
+    // The run logs go in at every integrate, a main-mode run's first one too: nothing else
+    // commits them there. Nothing to merge leaves the rest of main alone: a run's first
+    // integrate must not refuse a dirty tree.
+    commitMetrics(projectDir);
     if (!ids.length && !verifiedBranches(projectDir).length) return [];
     if (git(projectDir, ['status', '--porcelain', '--untracked-files=no', '--', '.', METRICS]).out)
       throw new Error('main has uncommitted changes: commit or stash them before integrating');
-    commitMetrics(projectDir);
     for (const id of ids)
       if (!isVerified(projectDir, id))
         throw new Error(

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

@@ -0,0 +1,41 @@
+// The run logs this module writes to gcf/.metrics (Harness-PRD §11): append-only csv, one
+// line per call, merged by union. A worktree's lines go to the main checkout's logs: the
+// worktree's own gcf/.metrics is thrown away when its branch merges.
+import { spawnSync } from 'node:child_process';
+import { appendFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+/** gcf/.metrics of the main checkout of `projectDir`; its own outside a repository. */
+export function metricsDir(projectDir) {
+  const res = spawnSync('git', ['rev-parse', '--git-common-dir'], {
+    cwd: projectDir,
+    encoding: 'utf8',
+  });
+  const common = res.status === 0 ? path.resolve(projectDir, res.stdout.trim()) : '';
+  const main = path.basename(common) === '.git' ? path.dirname(common) : projectDir;
+
+  return path.join(main, 'gcf', '.metrics');
+}
+
+/** A field as csv takes it: no comma, no line break, at most 120 characters. */
+const field = (v) =>
+  String(v ?? '')
+    .replace(/[,\r\n]+/g, ';')
+    .slice(0, 120);
+
+/**
+ * Append one line to a log, timestamped; a project without gcf/ keeps no logs. Best effort: a
+ * log that cannot be written (a csv held open by a spreadsheet) never fails the command.
+ */
+export async function logMetric(projectDir, file, fields) {
+  try {
+    const dir = metricsDir(projectDir);
+    if (!existsSync(path.dirname(dir))) return;
+    await mkdir(dir, { recursive: true });
+    const line = [new Date().toISOString(), ...fields].map(field).join(',');
+    await appendFile(path.join(dir, file), `${line}\n`, 'utf8');
+  } catch {
+    // No line this time.
+  }
+}