gcf-harness-aif-ext 0.9.1 → 0.9.2

package/README.md

@@ -33,7 +33,7 @@ This installs the `gcf-run` and `gcf-run-ingest` skills and registers the `gcf-h
 ai-factory gcf-harness init    # per project: .claude/settings.json + .gitignore
 ```
 
-It is **per project**, not global — run it again in every game repository: it adds the readset-guard `PreToolUse` entry to the project's `.claude/settings.json` (never `~/.claude`) and `.gcf-session/` to `.gitignore`. It also allows what an unattended `claude -p` run needs at least — `Edit`, `Write`, `Bash(git *)`, `Bash(ai-factory *)`, and the same two as `PowerShell(…)` rules, the tool the agent runs commands with on Windows — because print mode cannot ask and denies the rest; add your engine's tools yourself (for example `mcp__<editor-server>` for an editor driven over MCP). Commit `.claude/settings.json`: the rules apply to every Claude session in the project. It is idempotent — a re-run after moving or cloning the project repoints the hook at the new path — refuses when the `gcf` command is not registered, and refuses to rewrite a `settings.json` it cannot parse. It is a separate step for the same reason as `gcf hooks-install`: an AI Factory manifest cannot install Claude Code hooks.
+It is **per project**, not global — run it again in every game repository: it adds the readset-guard and implement-guard entries to the project's `.claude/settings.json` (never `~/.claude`) and `.gcf-session/` to `.gitignore`. It also allows what an unattended `claude -p` run needs at least — `Edit`, `Write`, `Bash(git *)`, `Bash(ai-factory *)`, and the same two as `PowerShell(…)` rules, the tool the agent runs commands with on Windows — because print mode cannot ask and denies the rest; add your engine's tools yourself (for example `mcp__<editor-server>` for an editor driven over MCP). Commit `.claude/settings.json`: the rules apply to every Claude session in the project. It is idempotent — a re-run after moving or cloning the project repoints the hook at the new path — refuses when the `gcf` command is not registered, and refuses to rewrite a `settings.json` it cannot parse. It is a separate step for the same reason as `gcf hooks-install`: an AI Factory manifest cannot install Claude Code hooks.
 
 ## Upgrade
 
@@ -47,6 +47,13 @@ Updating keeps the hook entry valid — it points into the extension's install d
 
 0.5.1 is a fix release. During a run, `gcf/config.yml` is always readable, and a Grep inside `gcf/` reads only readset files. An import breaks a `depends:` cycle the pair checks closed and asks a D1 about it. It cuts a section longer than a segment at paragraphs, and lens and pair prompts carry a window around the quote. `/gcf-run` checks the plan against each pillar's invariant and asks each pillar's review question over the diff. Use it with core 0.4.1, which brings the parent feature into the readset.
 
+0.9.2 holds `/gcf-run` to aif-implement. Run `ai-factory gcf-harness init` again after the update: it registers the new hook.
+- The implement guard: in a session that runs `/gcf-run`, a write to a code file is denied until the session invokes the aif-implement skill (gcf-run step 13), and so is a plan tick, which only aif-implement sets. Planning stays free: `gcf/`, `.ai-factory/`, `.gcf-session/` and any markdown file. After aif-implement every write is free, the fixes of a red DoD and of the review included. It works in the harness's runs and in an interactive `/gcf-run` alike, and touches no other session.
+- `/gcf-run` converges a plan when an improve pass finds nothing blocking: a wrong or missing behavior or task, a broken pillar invariant, a rule conflict, a task no check can prove. Polish (wording, splitting tasks, order) is applied, but no longer keeps the loop going. Before, a pass that changed any task asked for one more, and a fresh reviewer almost always changes something. The report row per pass gives the blocking and polish counts.
+- `/gcf-run` answers aif-plan's own questions (tests, logging, docs) itself, from the item, its DoD and the project's rules.
+- The run report marks an item whose session wrote code without aif-implement: `— code written outside aif-implement` on its line, `process` in `--json` and in its kept record. It reads the session's own events, its subagents' included, so it also covers a project without the guard registered. A write through Bash is seen by neither: the review of the diff is the check there.
+- Lessons (with core 0.7.10): after each agent session the run asks the same session, resumed, what got in its way - tools, rules, the framework, the project template - with the questions of `ai-factory gcf lessons prompt`. Its answers go to the inbox on main as lessons (`gcf lessons add`), and the board shows them on the card, in the drawer and in the inbox. The run passes `--no-lessons` to `/gcf-run`, so the agent carries no lessons instruction while it works. The turn follows a result, a handoff (before the fresh session), a timeout or an error; not a usage limit or a stop, and only for a `claude` agent with a session id. Another agent asks its lessons itself at the end of a run on main; in a worktree it records none. It takes up to 10 minutes; its cost goes on the item, and the report line says `, N lessons`. A failed lessons turn is logged and changes nothing else. A project that turns lessons off, or a core before 0.7.10, gets no turn and no flag.
+
 0.9.1 is a fix release:
 - A stopped session reads as `no result (stopped)`, and its kept record as `ended: stopped`: before, the kill's exit code (`agent exit 1` on Windows).
 - `gcf-harness stop <id>` never kills the run: a stop before the item's session starts (or between two sessions of a handoff) leaves `.gcf-session/runs/<id>.stop`, and that session is stopped as it starts. Before, a stop then killed the whole run with the other items of its batch. A run hung before its first session (in its worktree setup) is not stopped. On main, a stop marks the item too once the run has reached it. Known limit: a stop in the moment between a worktree run's claim of the item and its clearing of an old mark is lost.
@@ -82,11 +89,11 @@ To remove the extension:
 ai-factory extension remove gcf-harness-aif-ext
 ```
 
-Removal does not touch `.claude/settings.json`: delete the `PreToolUse` entry whose command ends in `# gcf-readset-guard` by hand, or every Read, Grep and Glob will report a hook error.
+Removal does not touch `.claude/settings.json`: delete the entries whose command ends in `# gcf-readset-guard` or `# gcf-implement-guard` (under `PreToolUse` and `UserPromptSubmit`) by hand, or the tools they match will report a hook error.
 
 ## What it adds
 
-**`/gcf-run <item-id…>`** — drives work items through plan, implementation and DoD, with every gate checked *before* the tokens are spent: the audit ritual, the gate below, the context budget. The plan is written by `aif-plan`, then improved in passes, each by a fresh subagent that reads only the plan and the readset and records every default it picks; `ai-factory gcf plan check <id>` runs after each pass, and a pass that changes no task ends the loop. A plan still changing after `plan_passes` passes, or a question only the human can answer (a save format, a public API, a new dependency, a pillar conflict), blocks the item before any code is written. The DoD is `ai-factory gcf verify <id>` — the gate's checks, the item's `live:` delta, and the project's `dod.build` and `dod.test` commands from `gcf/config.yml` — plus a review by a fresh subagent, up to `dod_attempts` attempts. Every item ends in a state the core records: `gcf submit` (gate `verdict` or `decision` — waits for the human), `gcf close` (gate `auto` — done, or a soft unit closed as `unplayed`) or `gcf block` with the reason. The verdict and the decision belong to the human: the pipeline stops at `submit` and prints the playtest list.
+**`/gcf-run <item-id…>`** — drives work items through plan, implementation and DoD, with every gate checked *before* the tokens are spent: the audit ritual, the gate below, the context budget. The plan is written by `aif-plan`, then improved in passes, each by a fresh subagent that reads only the plan and the readset and records every default it picks; `ai-factory gcf plan check <id>` runs after each pass, and a pass with no blocking finding (a wrong or missing behavior or task, a broken pillar invariant, a rule conflict, an unprovable task) ends the loop. A blocking finding left after `plan_passes` passes (3 by default), or a question only the human can answer (a save format, a public API, a new dependency, a pillar conflict), blocks the item before any code is written. The DoD is `ai-factory gcf verify <id>` — the gate's checks, the item's `live:` delta, and the project's `dod.build` and `dod.test` commands from `gcf/config.yml` — plus a review by a fresh subagent, up to `dod_attempts` attempts. Every item ends in a state the core records: `gcf submit` (gate `verdict` or `decision` — waits for the human), `gcf close` (gate `auto` — done, or a soft unit closed as `unplayed`) or `gcf block` with the reason. The verdict and the decision belong to the human: the pipeline stops at `submit` and prints the playtest list.
 
 **`ai-factory gcf-harness gate <item-id…>`** — the `/gcf-run` gate as code. It reads one `gcf audit --json` report and exits 1 with a one-line reason when the items may not go: a core older than 0.4.0, a `schema:` other than 1 in `gcf/config.yml`, an id with no work item, a feature (run its children; the feature closes when they are finished), an item that is not `ready`, an unplayed dependency, no WIP room for the batch (items awaiting a verdict + the batch's `gate: verdict` items over `wip_built_limit`), or two items of the batch touching the same system unless both say `parallel: ok`. The tune limit is not a gate rule: `verdict tune` itself refuses at the limit, and an item tuned up to it still gets its last build. The skill runs it and stops on a non-zero exit — no model compares the numbers.
 
@@ -96,6 +103,8 @@ Removal does not touch `.claude/settings.json`: delete the `PreToolUse` entry wh
 
 **readset-guard** — a `PreToolUse` hook on Read/Grep/Glob. While a run manifest exists at `.gcf-session/readset.json`, a path inside `gcf/` that is not in the readset is denied, and so is a Grep from the project root (no `path`, or a `path` above `gcf/`) unless its `glob` starts with a literal directory other than `gcf` (`src/**`, not `**/*.md`), because such a content search would read the whole tree past the gate. Glob and Greps scoped to the game code are never restricted. No manifest means no restriction: manual work is never gated. An honest limit — `cat` through Bash still bypasses it. This is a discipline tool, not a security perimeter.
 
+**implement-guard** — a `UserPromptSubmit` and `PreToolUse` hook (Skill, the write tools, Bash and PowerShell). A session that starts `/gcf-run` (typed, passed to `claude -p`, or invoked as a skill) gets a state in `.gcf-session/guard/<session_id>.json`; until it invokes the aif-implement skill, Edit, Write, MultiEdit and NotebookEdit are denied outside `gcf/`, `.ai-factory/`, `.gcf-session/` and markdown, and a markdown write that adds a `- [x]` tick is denied too. Any other session is never touched, and an error lets the call through. The move that ends the item (`gcf block`, `submit` or `close`, through Bash or PowerShell) lets the session go, so the operator's own edits after a blocked run are free again. A plugin's skill (`<plugin>:aif-implement`) counts too. Limits: the flag is per session, so in a batch the first item's aif-implement frees the rest; a write through Bash is not seen, by the run report either.
+
 ## Docs
 
 [Harness-PRD](https://github.com/VirtualMaestro/GCF/blob/main/docs/Harness-PRD.md) is the spec: pipeline stages, gates, execution surfaces, the guard's contract.

package/commands/activity.js

@@ -109,10 +109,13 @@ function limitIn(text, whole = true) {
  * @param {string} line
  * The main agent's turns also carry `context`, the tokens its window holds (a subagent's turns,
  * `parent_tool_use_id` set, fill a window of their own); the init names the `model`, the result
- * the `windows` of its models, and a compaction says `compacted`.
+ * the `windows` of its models, and a compaction says `compacted`. A turn's tool calls give
+ * `implement` (the aif-implement skill) and `writes` (the files written, by call id); a tool
+ * result gives `failed`, the calls that wrote nothing.
  * @returns {{lines: string[], cost?: Cost, session_id?: string, limit?: {resets: string | null},
  *   context?: number, turn?: string, model?: string, windows?: Record<string, number>,
- *   compacted?: boolean}}
+ *   compacted?: boolean, implement?: boolean, writes?: {id: string, file: string}[],
+ *   failed?: string[]}}
  */
 export function activity(line, now = new Date()) {
   let e;
@@ -128,12 +131,18 @@ export function activity(line, now = new Date()) {
   const content = Array.isArray(e.message?.content) ? e.message.content : [];
   if (e.type === 'system') return system(e, at);
   if (e.type === 'assistant') return { ...said(content, at), ...contextOf(e) };
-  if (e.type === 'user')
+  if (e.type === 'user') {
+    const errors = content.filter((b) => b.type === 'tool_result' && b.is_error);
+
     return {
-      lines: content
-        .filter((b) => b.type === 'tool_result' && b.is_error)
-        .map((b) => `${at} tool error: ${cut(firstLines(resultText(b.content), 1), 300)}`),
+      lines: errors.map(
+        (b) => `${at} tool error: ${cut(firstLines(resultText(b.content), 1), 300)}`,
+      ),
+      // A refused or failed call wrote nothing: its write does not count.
+      ...(errors.length ? { failed: errors.map((b) => String(b.tool_use_id)) } : {}),
     };
+  }
+
   if (e.type === 'result') return ended(e, at);
 
   return { lines: [] };
@@ -167,12 +176,32 @@ function contextOf(e) {
   return { context: tokens, ...(e.message.id ? { turn: String(e.message.id) } : {}) };
 }
 
+const WRITES = ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'];
+
+/**
+ * What a turn's tool calls tell of gcf-run step 13: `implement` when one invokes the aif-implement
+ * skill, `writes` the files its write tools name. A subagent's turns count too.
+ */
+function steps(uses) {
+  const writes = uses
+    .filter((u) => WRITES.includes(u.name))
+    .map((u) => ({ id: String(u.id), file: u.input?.file_path ?? u.input?.notebook_path }))
+    .filter((w) => typeof w.file === 'string');
+  // A plugin's skill comes as <plugin>:aif-implement.
+  const implement = uses.some(
+    (u) => u.name === 'Skill' && /(^|:)aif-implement$/.test(String(u.input?.skill ?? '')),
+  );
+
+  return { ...(implement ? { implement } : {}), ...(writes.length ? { writes } : {}) };
+}
+
 /** An assistant turn: its tool calls and its text, which may be the usage-limit message. */
 function said(content, at) {
   const texts = content.filter((b) => b.type === 'text').map((b) => b.text);
 
   return {
     ...(texts.map((t) => limitIn(t)).find((l) => l.limit) ?? {}),
+    ...steps(content.filter((b) => b.type === 'tool_use')),
     lines: content.flatMap((b) => {
       if (b.type === 'tool_use') return [`${at} ${toolLine(b)}`];
       const text = b.type === 'text' ? cut(firstLines(b.text, 2), 300) : '';
@@ -197,6 +226,8 @@ function ended(e, at) {
 
   return {
     lines: [...text, `${at} ${summary(e, cost, Boolean(limit.limit))}`],
+    // The reply itself: a lessons turn answers with its JSON here.
+    ...(typeof e.result === 'string' ? { result: e.result } : {}),
     cost,
     ...limit,
     ...(windows.length ? { windows: Object.fromEntries(windows) } : {}),

package/commands/harness.js

@@ -1,4 +1,4 @@
-// `ai-factory gcf-harness init` — registers the readset-guard PreToolUse hook in the
+// `ai-factory gcf-harness init` — registers the readset-guard and implement-guard hooks in the
 // project's .claude/settings.json (the AIF manifest cannot install Claude Code hooks —
 // same decision as gcf hooks-install for git hooks). Idempotent by marker comment. It also
 // allows what a headless agent run needs (AGENT_ALLOW).
@@ -11,7 +11,6 @@ import { fileURLToPath } from 'node:url';
 import { run, cliCore, DEFAULT_AGENT, DEFAULT_TIMEOUT_MIN, MAIN_RUN, stopOf } from './run.js';
 
 const EXT_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
-const MARKER = 'gcf-readset-guard';
 const SCHEMA = 1; // the only gcf/config.yml schema this harness drives
 const SESSION_RULE = /^(\/|\*\*\/)?\.gcf-session\/?$/;
 
@@ -185,20 +184,62 @@ async function readSettings(settingsFile) {
   }
 }
 
+// The hooks `init` registers: the file, the event, its matcher (none for a prompt event).
+/** @type {Array<{name: string, event: string, matcher?: string}>} */
+const GUARDS = [
+  { name: 'readset-guard', event: 'PreToolUse', matcher: 'Read|Grep|Glob' },
+  {
+    name: 'implement-guard',
+    event: 'PreToolUse',
+    // Bash and PowerShell: a `gcf block|submit|close` ends the run, and the guard lets go.
+    matcher: 'Skill|Edit|Write|MultiEdit|NotebookEdit|Bash|PowerShell',
+  },
+  { name: 'implement-guard', event: 'UserPromptSubmit' },
+];
+
+const hooksOf = (e) => (Array.isArray(e?.hooks) ? e.hooks : []);
+
+/**
+ * A newer version may watch more tools. An entry of ours alone takes the new matcher; one we
+ * share with the operator's own hooks keeps theirs, and ours moves to an entry of its own, at
+ * most one: a hook copied into several entries, or one already moved, makes no second. Returns
+ * how many entries changed.
+ */
+function widen(list, matcher, ours, command) {
+  const before = JSON.stringify(list);
+  const holding = list.filter((x) => hooksOf(x).some((h) => ours.includes(h)));
+  const alone = (e) => e.hooks.every((h) => ours.includes(h));
+  // Ours alone, the right matcher first; else a new one. It keeps one hook of ours, with the
+  // operator's own settings on it (a timeout).
+  let own = holding.find((e) => e.matcher === matcher && alone(e)) ?? holding.find(alone);
+  if (own) own.hooks = own.hooks.slice(0, 1);
+  else list.push((own = { hooks: [{ ...ours[0], command }] }));
+  own.matcher = matcher;
+  for (const e of holding) if (e !== own) e.hooks = e.hooks.filter((h) => !ours.includes(h));
+  // An entry that held only ours is empty now: it goes.
+  for (const e of holding) if (e !== own && !e.hooks.length) list.splice(list.indexOf(e), 1);
+
+  return JSON.stringify(list) === before ? 0 : 1;
+}
+
 /**
- * Adds the guard entry, or repoints an existing one: a moved or cloned project keeps the old
- * absolute path under the marker, and the registered hook would keep launching a missing file.
- * Returns what happened, or null when the settings already hold the right command.
+ * Adds the guard entry of `event`, or repoints an existing one: a moved or cloned project keeps
+ * the old absolute path under the marker, and the registered hook would keep launching a missing
+ * file. Returns what happened, or null when the settings already hold the right command.
+ * @param {Record<string, any>} settings
+ * @param {{event: string, matcher?: string}} guard
+ * @param {string} marker
+ * @param {string} command
  */
-function registerGuard(settings, command) {
+function registerGuard(settings, { event, matcher }, marker, command) {
   settings.hooks ??= {};
-  settings.hooks.PreToolUse ??= [];
-  const ours = settings.hooks.PreToolUse.flatMap((e) => e?.hooks ?? []).filter(
-    (h) => typeof h?.command === 'string' && h.command.includes(MARKER),
-  );
+  settings.hooks[event] ??= [];
+  const ours = settings.hooks[event]
+    .flatMap(hooksOf)
+    .filter((h) => typeof h?.command === 'string' && h.command.includes(marker));
   if (!ours.length) {
-    settings.hooks.PreToolUse.push({
-      matcher: 'Read|Grep|Glob',
+    settings.hooks[event].push({
+      ...(matcher ? { matcher } : {}),
       hooks: [{ type: 'command', command }],
     });
 
@@ -207,8 +248,9 @@ function registerGuard(settings, command) {
 
   const stale = ours.filter((h) => h.command !== command);
   for (const h of stale) h.command = command;
+  const widened = matcher ? widen(settings.hooks[event], matcher, ours, command) : 0;
 
-  return stale.length ? 'repointed' : null;
+  return stale.length || widened ? 'repointed' : null;
 }
 
 // What a headless `claude -p` run needs at least: it cannot ask, so anything not allowed is
@@ -258,18 +300,22 @@ async function init(program) {
 
   const projectDir = process.cwd();
   const settingsFile = path.join(projectDir, '.claude', 'settings.json');
-  const guard = path.join(EXT_ROOT, 'hooks', 'readset-guard.js').replaceAll('\\', '/');
   const settings = await readSettings(settingsFile);
-  const change = registerGuard(settings, `node "${guard}" # ${MARKER}`);
+  const changes = GUARDS.map((g) => {
+    const file = path.join(EXT_ROOT, 'hooks', `${g.name}.js`).replaceAll('\\', '/');
+    const marker = `gcf-${g.name}`;
+    const change = registerGuard(settings, g, marker, `node "${file}" # ${marker}`);
+
+    return change && `${g.name} (${g.event}) ${change}`;
+  }).filter(Boolean);
   const allowed = allowAgent(settings);
-  if (change || allowed.length) {
+  if (changes.length || allowed.length) {
     await mkdir(path.dirname(settingsFile), { recursive: true });
     await writeFile(settingsFile, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
   }
 
-  console.log(
-    change ? `readset-guard ${change} → ${settingsFile}` : 'readset-guard already registered',
-  );
+  for (const c of changes) console.log(`${c} → ${settingsFile}`);
+  if (!changes.length) console.log('readset-guard and implement-guard already registered');
   if (allowed.length) console.log(`agent runs may now: ${allowed.join(', ')}`);
 
   await ignoreSession(projectDir);
@@ -291,7 +337,8 @@ export function register(program) {
   harness
     .command('init')
     .description(
-      'Initialize the harness in this project: readset-guard hook, agent permissions (idempotent)',
+      'Initialize the harness in this project: readset and implement guards, agent permissions ' +
+        '(idempotent)',
     )
     .action(() => init(program));
 
@@ -398,15 +445,21 @@ export function stopRun(projectDir, id, core = cliCore(projectDir)) {
   return lock ? `stopped the run of ${id}; it stays ready` : `no run drives ${id}`;
 }
 
+/**
+ * An item's line of the run report: its result, why, a skipped step of the process, and the
+ * lessons its sessions left in the inbox.
+ */
+export const itemLine = (i) =>
+  [`${i.id}: ${i.result}`, i.reason ?? i.conflict ?? i.error ?? i.skipped, i.process]
+    .filter(Boolean)
+    .join(' — ') + (i.lessons ? `, ${i.lessons} lesson${i.lessons > 1 ? 's' : ''}` : '');
+
 /** The run report a human reads, then the playtest sheet of what now waits for play. */
 function printRun(r) {
   for (const o of r.orphans)
     console.log(`orphan ${o.id}: ${o.move ?? o.conflict ?? o.error ?? o.skipped}`);
   if (r.gate) console.error(`gcf gate: ${r.gate}`);
-  for (const i of r.items) {
-    const why = i.reason ?? i.conflict ?? i.error ?? i.skipped;
-    console.log(`${i.id}: ${i.result}${why ? ` — ${why}` : ''}`);
-  }
+  for (const i of r.items) console.log(itemLine(i));
 
   if (!r.gate) console.log(`\n${cliCore(process.cwd())(['playtest', 'session']).out.trim()}`);
 }

package/commands/run.js

@@ -8,6 +8,7 @@ import { mkdir, open, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { activity, clock, count } from './activity.js';
+import { planning, readState } from '../hooks/implement-guard.js';
 
 // The event stream, not the final answer alone: the log shows the session at work as it goes.
 export const DEFAULT_AGENT = 'claude -p --output-format stream-json --verbose';
@@ -202,9 +203,15 @@ function byLine(stream, take) {
 // What `claude --resume` prints on stderr for a session it does not have.
 const NO_SESSION = /No conversation found with session ID/;
 
-/** Keep what a session's activity told: the last of each, the model's window from the result. */
-function absorb(seen, a) {
+/**
+ * Keep what a session's activity told: the last of each, the model's window from the result,
+ * and for gcf-run step 13 whether it invoked aif-implement and wrote code (`dir`'s planning
+ * files are no code).
+ */
+function absorb(seen, a, dir) {
+  trackWrites(seen, a, dir);
   seen.cost = a.cost ?? seen.cost;
+  seen.result = a.result ?? seen.result;
   seen.session_id = a.session_id ?? seen.session_id;
   seen.limit = a.limit ?? seen.limit;
   seen.model = a.model ?? seen.model;
@@ -212,6 +219,15 @@ function absorb(seen, a) {
   if (a.windows) seen.window = a.windows[seen.model] ?? Math.max(...Object.values(a.windows));
 }
 
+/** Step 13: aif-implement, and the code writes by call id until a failed result drops one. */
+function trackWrites(seen, a, dir) {
+  seen.implement ||= Boolean(a.implement);
+  seen.writes ??= new Map();
+  for (const w of a.writes ?? []) if (!planning(dir, w.file)) seen.writes.set(w.id, w.file);
+  for (const id of a.failed ?? []) seen.writes.delete(id);
+  seen.wrote = seen.writes.size > 0;
+}
+
 /** Write the flag the handoff guard reads into the session's checkout. */
 function writeFlag(dir, flag) {
   try {
@@ -300,7 +316,7 @@ function handoffWatch(handoff, dir, write, stop) {
  * stopped. `handoff: true` says the session was told to hand over, `handedOver` that it did.
  * @returns {Promise<{code: number | string, cost?: import('./activity.js').Cost,
  *   session_id?: string, limit?: {resets: string | null}, gone: boolean, handoff: boolean,
- *   handedOver: boolean, model?: string, window?: number}>}
+ *   handedOver: boolean, model?: string, window?: number, result?: string}>}
  */
 function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn, env = {}, handoff }) {
   return new Promise((resolve) => {
@@ -328,7 +344,7 @@ function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn, env = {},
     });
     const flushOut = byLine(child.stdout, (line) => {
       const a = activity(line);
-      absorb(seen, a);
+      absorb(seen, a, dir);
       write(a.lines);
       if (open) watch.see(a, seen.model);
     });
@@ -539,7 +555,7 @@ async function prepare({ claimed, failed }, core, agentOf) {
       const agent = agentOf(id);
       const wt = json(await core(['worktree', id, '--json']), `worktree ${id}`);
       if (wt.sync) throw new Error(wt.sync);
-      ready.push({ id, dir: wt.path, agent, release });
+      ready.push({ id, dir: wt.path, agent, release, lessonsPrompt: await lessonsFor(core, id) });
     } catch (e) {
       await release();
       failed.push({ id, result: 'error', error: e.message });
@@ -610,6 +626,7 @@ function recordFor(r) {
     // The fresh session a counted handoff started ended with no id: the next one is no new
     // handoff, only the same fresh start again.
     ...(!r.handoffPending && !r.session_id ? { counted: true } : {}),
+    ...(r.skipped ? { process: OUTSIDE_IMPLEMENT } : {}),
     at: new Date().toISOString(),
   };
 }
@@ -661,7 +678,12 @@ function noResult(r, rerun) {
 
 const STAYED = / stays ready, a rerun /;
 
-const taskOf = (r) => (r.main ? `/gcf-run ${r.id}` : `/gcf-run ${r.id} --worktree`);
+// `--no-lessons`: the run asks the lessons itself, after the session (see `askLessons`).
+// Only a claude agent gets the turn. Another asks its lessons itself at the run's end on main;
+// in a worktree it records none (shortcut: ask them on main after the merge if it matters).
+const taskOf = (r) =>
+  `/gcf-run ${r.id}${r.main ? '' : ' --worktree'}` +
+  (r.lessonsPrompt && /^claude(\s|$)/.test(r.agent) ? ' --no-lessons' : '');
 
 /**
  * The agent command and prompt of an item's session: `/gcf-run`, or the resume of the session
@@ -754,9 +776,147 @@ function resumeLost(rec, ran) {
   return false;
 }
 
+/** The report note of an item whose session skipped gcf-run step 13. */
+export const OUTSIDE_IMPLEMENT = 'code written outside aif-implement';
+
+/**
+ * Whether a session wrote code with no aif-implement before it: its stream shows none, and
+ * neither does the implement guard's state of its session, which a resumed session inherits.
+ * shortcut: without the guard registered, a resumed session whose skill ran before the resume
+ * reads as skipped; `gcf-harness init` registers it.
+ */
+const skippedImplement = (r, ran) =>
+  Boolean(ran.wrote && !ran.implement && !readState(r.dir, ran.session_id)?.implement);
+
+/**
+ * The project's lessons prompt for item `id` (`gcf lessons prompt`), or null when the project
+ * turned lessons off or the core has no lessons command (before 0.7.10).
+ */
+async function lessonsFor(core, id) {
+  const res = await core(['lessons', 'prompt', id, '--json']);
+  if (!res.ok) return null;
+  try {
+    const l = JSON.parse(res.out);
+
+    return l?.off || typeof l?.prompt !== 'string' ? null : l.prompt;
+  } catch {
+    return null;
+  }
+}
+
+const KINDS = ['tool', 'rules', 'framework', 'template', 'other'];
+
+/**
+ * The lessons in a lessons turn's reply: its JSON array, bare or in a ```json fence, each entry
+ * held to `{kind, text, where}`. A reply that is no array is one lesson of kind `other`, so what
+ * the agent said is not lost; no reply is none.
+ */
+export function lessonsOf(reply) {
+  if (typeof reply !== 'string' || !reply.trim()) return [];
+  const fenced = reply.match(/```(?:json)?\s*([\s\S]*?)```/)?.[1];
+  // A bare array with words around it: from its first [ to its last ].
+  const bare = reply.slice(reply.indexOf('['), reply.lastIndexOf(']') + 1);
+  /** @type {any} */
+  let list = null;
+  for (const body of [fenced, reply, bare].filter(Boolean)) {
+    try {
+      list = JSON.parse(String(body).trim());
+      if (Array.isArray(list)) break;
+    } catch {
+      list = null;
+    }
+  }
+
+  if (!Array.isArray(list))
+    return [{ kind: 'other', text: reply.trim().slice(0, 500), where: null }];
+
+  return list
+    .filter((l) => typeof l?.text === 'string' && l.text.trim())
+    .map((l) => ({
+      kind: KINDS.includes(l.kind) ? l.kind : 'other',
+      text: l.text.trim(),
+      where: typeof l.where === 'string' && l.where.trim() ? l.where.trim() : null,
+    }));
+}
+
+// A lessons turn is one reply: past this it is stopped, and the item's result stands.
+const LESSONS_MS = 10 * 60_000;
+
+/** Whether the session `ran` gets a lessons turn: one to resume, not cut by a limit or a stop. */
+const asksLessons = (r, ran) =>
+  Boolean(r.lessonsPrompt && SESSION_ID.test(String(ran.session_id))) &&
+  !ran.limit &&
+  !ran.stopped &&
+  !ran.gone &&
+  /^claude(\s|$)/.test(r.agent);
+
+/** Record `list` in the inbox on main and log it; returns how many went in. */
+async function recordLessons(s, list) {
+  const file = path.join(s.logs, `${s.r.id}.lessons.json`);
+  await writeFile(file, `${JSON.stringify(list, null, 2)}\n`);
+  // An empty list records nothing: the core makes no commit for it.
+  const added = list.length
+    ? await s.core(['lessons', 'add', s.r.id, '--from', file, '--commit'])
+    : { ok: true };
+  const note = added.ok ? `${list.length} recorded` : (added.err || added.out).trim();
+  writeSync(s.fd, `[${clock()}] lessons: ${note}\n`);
+
+  return added.ok ? list.length : 0;
+}
+
+/**
+ * The lessons turn after a session: the same agent, resumed, answers the project's lessons
+ * prompt, and its answers go to the inbox on main (`gcf lessons add`). Not after a usage limit
+ * or a stop, not without a session to resume or a `claude` agent. The prompt goes in a file:
+ * its text is the project's, and a shell must not read it. Returns `{count, cost}`; a failure
+ * is logged and changes nothing else.
+ */
+async function askLessons(s, ran) {
+  const { r, fd, launch } = s;
+  if (!asksLessons(r, ran)) return { count: 0 };
+  const promptFile = path.join(r.dir, '.gcf-session', 'lessons.md');
+  try {
+    await mkdir(path.dirname(promptFile), { recursive: true });
+    await writeFile(promptFile, r.lessonsPrompt);
+    const flags = launch?.flags(r.dir);
+    const agent = `${r.agent} --resume ${ran.session_id}${flags ? ` ${flags}` : ''}`;
+    const ask =
+      'Answer the questions in .gcf-session/lessons.md: your reply is the JSON array it asks for';
+    // No handoff watch: one reply, and the session is past its work.
+    const turn = await startAgent(agent, ask, r.dir, {
+      fd,
+      timeoutMs: LESSONS_MS,
+      id: r.id,
+      onSpawn: s.onSpawn,
+      env: launch?.env,
+      handoff: null,
+    });
+    writeFileSync(s.lock, `${process.pid}\n${r.id}\n`);
+    // A turn cut by the limit, a timeout, a stop or an error has no answer: its text is not one.
+    if (turn.limit || turn.gone || turn.code !== 0) {
+      writeSync(fd, `[${clock()}] lessons: the turn ended without an answer, none recorded\n`);
+
+      return { count: 0, cost: turn.cost };
+    }
+
+    const count = await recordLessons(s, lessonsOf(turn.result));
+
+    return { count, cost: turn.cost };
+  } catch (e) {
+    writeSync(fd, `[${clock()}] lessons: ${e.message}\n`);
+
+    return { count: 0 };
+  } finally {
+    await rm(promptFile, { force: true });
+    // A stop that came during the turn holds for the session after it too.
+    ran.stopped ||= existsSync(stopOf(s.logs, r.id));
+  }
+}
+
 /**
  * The sessions of one item: the first runs its command; while one hands over as told, a fresh
- * one goes on from the plan, up to MAX_HANDOFFS.
+ * one goes on from the plan, up to MAX_HANDOFFS. `skipped` says one of them wrote code outside
+ * aif-implement. After each session its lessons turn, before the fresh one that follows it.
  */
 async function handOver(s, { agent, prompt, rec }) {
   const { r } = s;
@@ -766,20 +926,28 @@ async function handOver(s, { agent, prompt, rec }) {
   if (fromHandoff && !rec.counted && (await capped(count, r)))
     return { code: 0, handoffs: count.handoffs, handoffLimit: true, handoffPending: false };
   let ran = await agentSession(s, agent, prompt);
-  let cost = ran.cost;
   const lost = resumeLost(rec, ran);
+  let skipped = skippedImplement(r, ran);
+  let learned = await askLessons(s, ran);
+  let cost = addCost(ran.cost, learned.cost);
+  let lessons = learned.count;
   while ((await goesOn(s, ran)) && !(await capped(count, r))) {
     writeSync(
       s.fd,
       `[${clock()}] handoff ${count.handoffs}: a fresh session goes on from the plan\n`,
     );
     ran = await agentSession(s, r.agent, `${taskOf(r)} --handoff`);
-    cost = addCost(cost, ran.cost);
+    skipped ||= skippedImplement(r, ran);
+    learned = await askLessons(s, ran);
+    cost = addCost(addCost(cost, ran.cost), learned.cost);
+    lessons += learned.count;
   }
 
   return {
     ...ran,
     cost,
+    skipped,
+    lessons,
     handoffs: count.handoffs,
     handoffLimit: count.limit,
     // The session was told to hand over and no fresh one took it: the next run does.
@@ -793,7 +961,7 @@ async function handOver(s, { agent, prompt, rec }) {
  * One session per item, its output in `.gcf-session/runs/<id>.log`. In a worktree the skill runs
  * its worktree mode; on main it records the item's move itself.
  */
-async function session(r, { logs, timeoutMs, fresh, launch }) {
+async function session(r, { core, logs, timeoutMs, fresh, launch }) {
   /** @type {import('node:fs/promises').FileHandle | null} */
   let log = null;
   // The lock names the item and its session: `stop <id>` ends that session alone, not the run.
@@ -815,7 +983,7 @@ async function session(r, { logs, timeoutMs, fresh, launch }) {
 
     return {
       ...r,
-      ...(await handOver({ r, logs, lock, fd: log.fd, deadline, launch, onSpawn }, cmd)),
+      ...(await handOver({ r, core, logs, lock, fd: log.fd, deadline, launch, onSpawn }, cmd)),
     };
   } catch (e) {
     return { ...r, code: null, error: e.message };
@@ -1004,7 +1172,16 @@ async function mainItem(projectDir, id, ctx) {
       }
     };
 
-    const s = { id, dir: projectDir, agent: agentOf(id), release: none, main: true, done };
+    const lessonsPrompt = await lessonsFor(core, id);
+    const s = {
+      id,
+      dir: projectDir,
+      agent: agentOf(id),
+      release: none,
+      main: true,
+      done,
+      lessonsPrompt,
+    };
     r = await session(s, ctx);
   } catch (e) {
     r = { id, error: e.message };
@@ -1015,9 +1192,16 @@ async function mainItem(projectDir, id, ctx) {
   const item = await mainResult(core, r);
   await remember(logs, r, item);
 
-  return { ...item, ...r.cost, ...(r.handoffs ? { handoffs: r.handoffs } : {}) };
+  return { ...item, ...r.cost, ...extras(r) };
 }
 
+/** What rides on an item's line beside its result: its handoffs, and a skipped step 13. */
+const extras = (r) => ({
+  ...(r?.handoffs ? { handoffs: r.handoffs } : {}),
+  ...(r?.skipped ? { process: OUTSIDE_IMPLEMENT } : {}),
+  ...(r?.lessons ? { lessons: r.lessons } : {}),
+});
+
 /** Every claimed item in its worktree at once; blocks recorded on main, verified ones merged. */
 async function runWorktrees(claims, ctx) {
   const { core, logs, agentOf } = ctx;
@@ -1051,7 +1235,7 @@ async function runWorktrees(claims, ctx) {
   return items.map((i) => {
     const r = runs.find((x) => x.id === i.id);
 
-    return { ...i, ...r?.cost, ...(r?.handoffs ? { handoffs: r.handoffs } : {}) };
+    return { ...i, ...r?.cost, ...extras(r) };
   });
 }
 

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-harness-aif-ext",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
   "skills": [
     "skills/gcf-run",

package/hooks/implement-guard.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+// Implement guard (gcf-run step 13): a UserPromptSubmit and PreToolUse hook. In a session that
+// runs /gcf-run, the first implementation of a plan task goes through the aif-implement skill:
+// until the session invokes it, a write to a code file is denied, and so is a plan tick, which
+// only aif-implement sets. Planning stays free: gcf/, .ai-factory/, .gcf-session/ and any
+// markdown file. After aif-implement every write is free, the fixes of a red DoD and of the
+// review included. A session that never ran /gcf-run is never touched.
+// shortcut: the flag is per session, not per item: in a batch, the first item's aif-implement,
+// or its end move, frees the rest; key it by item when batches share one session.
+// shortcut: a write through Bash is not seen here, nor by the run's check: the diff review is.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+const WRITES = ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'];
+const PLANNING_DIRS = ['gcf', '.ai-factory', '.gcf-session'];
+const TICK = /^\s*- \[[xX]\] /gm;
+
+const DENY =
+  'the first implementation of a plan task goes through the aif-implement skill ' +
+  '(gcf-run step 13): run it on the plan. Planning may write gcf/, .ai-factory/ and markdown; ' +
+  'the fixes of a red DoD or a review finding are free after aif-implement.';
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether a write to `file` is planning, not code: a path under gcf/, .ai-factory/ or
+ * .gcf-session/, any markdown file, or a file outside the project.
+ */
+export function planning(projectDir, file) {
+  const rel = path.relative(path.resolve(projectDir), path.resolve(projectDir, file));
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return true;
+  const first = rel.split(/[\\/]/)[0];
+
+  return PLANNING_DIRS.includes(first) || /\.md$/i.test(rel);
+}
+
+const ticks = (text) => (String(text ?? '').match(TICK) ?? []).length;
+
+/** The ticks a markdown write adds: its new text against the text it replaces. */
+function addedTicks(input, abs) {
+  const t = input.tool_input ?? {};
+  if (input.tool_name === 'Write') {
+    const old = existsSync(abs) ? readFileSync(abs, 'utf8') : '';
+
+    return ticks(t.content) - ticks(old);
+  }
+
+  const edits = input.tool_name === 'MultiEdit' ? (t.edits ?? []) : [t];
+
+  return edits.reduce((n, e) => n + ticks(e?.new_string) - ticks(e?.old_string), 0);
+}
+
+// A plugin's skill comes as <plugin>:<skill>.
+const skillIs = (input, name) =>
+  input.tool_name === 'Skill' &&
+  new RegExp(`(^|:)${name}$`).test(String(input.tool_input?.skill ?? ''));
+const promptIs = (input, command) =>
+  new RegExp(`^\\s*/${command}(\\s|$)`).test(String(input.prompt ?? ''));
+const started = (input, name) => skillIs(input, name) || promptIs(input, name);
+// The move that ends a run's item, run as a command (not echoed or searched for): the session's
+// work on it is over. A move the core then refuses frees the session too: fail open.
+const CLI = String.raw`((npx\s+|pnpm\s+exec\s+|\S*[\\/])?ai-factory(\.cmd)?\s+)?`;
+const ENDS = new RegExp(String.raw`(^|[;&|(])\s*${CLI}gcf\s+(block|submit|close)\s+[a-z0-9]`, 'm');
+const endsRun = (input) =>
+  ['Bash', 'PowerShell'].includes(input.tool_name) &&
+  ENDS.test(String(input.tool_input?.command ?? ''));
+
+/**
+ * The session's state after `input`, and the verdict on it: `{state, allow, reason?}`. `state`
+ * is `{run, implement}`; /gcf-run and aif-implement set it, the move that ends the item clears
+ * `run`, so the operator's own edits after a blocked run are free again. `implement` stays: the
+ * run's check reads it for a session resumed after a limit, whose stream has no Skill call.
+ */
+export function decide(input, projectDir, state) {
+  if (input && endsRun(input))
+    return { state: { run: false, implement: Boolean(state?.implement) }, allow: true };
+  const next = { run: Boolean(state?.run), implement: Boolean(state?.implement) };
+  if (!input) return { state: next, allow: true };
+  next.run ||= started(input, 'gcf-run');
+  next.implement ||= started(input, 'aif-implement');
+  const guarded = next.run && !next.implement && WRITES.includes(input.tool_name);
+
+  return { state: next, ...(guarded ? writeVerdict(input, projectDir) : { allow: true }) };
+}
+
+/** A write before aif-implement: code is denied, and so is a tick in markdown. */
+function writeVerdict(input, projectDir) {
+  const file = input.tool_input?.file_path ?? input.tool_input?.notebook_path;
+  if (typeof file !== 'string') return { allow: true };
+  const abs = path.resolve(projectDir, file);
+  if (!planning(projectDir, abs)) return { allow: false, reason: DENY };
+  if (/\.md$/i.test(abs) && addedTicks(input, abs) > 0)
+    return { allow: false, reason: `a plan tick is aif-implement's: ${DENY}` };
+
+  return { allow: true };
+}
+
+/** The session's state file; a session id is a UUID, anything else gets no file. */
+export const stateFile = (projectDir, sessionId) =>
+  /^[\w-]+$/.test(String(sessionId ?? ''))
+    ? path.join(projectDir, '.gcf-session', 'guard', `${sessionId}.json`)
+    : null;
+
+/** A session's state: `{run, implement}`, or null without one. */
+export function readState(projectDir, sessionId) {
+  const file = stateFile(projectDir, sessionId);
+  try {
+    return file ? JSON.parse(readFileSync(file, 'utf8')) : null;
+  } catch {
+    return null;
+  }
+}
+
+// Hook entry: only runs when executed directly, so tests and run.js can import decide().
+const entry = process.argv[1]?.replaceAll('\\', '/');
+if (import.meta.url === `file://${entry}` || entry?.endsWith('implement-guard.js')) {
+  // Fail open: a hook that breaks on its own error must not stop the session's work.
+  try {
+    const input = readStdin();
+    const projectDir = process.env.CLAUDE_PROJECT_DIR ?? input?.cwd ?? process.cwd();
+    const old = readState(projectDir, input?.session_id);
+    const verdict = decide(input, projectDir, old);
+    const file = stateFile(projectDir, input?.session_id);
+    const changed =
+      verdict.state.run !== Boolean(old?.run) ||
+      verdict.state.implement !== Boolean(old?.implement);
+    if (file && changed) {
+      mkdirSync(path.dirname(file), { recursive: true });
+      writeFileSync(file, `${JSON.stringify(verdict.state)}\n`);
+    }
+
+    // A prompt is never refused: exit 2 there would drop the operator's message.
+    if (!verdict.allow && input?.hook_event_name !== 'UserPromptSubmit') {
+      console.error(`gcf implement-guard: ${verdict.reason}`);
+      process.exit(2);
+    }
+  } catch {
+    // Allow.
+  }
+
+  process.exit(0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-harness-aif-ext",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
   "type": "module",
   "license": "MIT",

package/skills/gcf-run/SKILL.md

@@ -15,6 +15,7 @@ inputs:
 - 1 or more work item or design unit ids; a batch shares one build and one playtest list
 - `--worktree` when `ai-factory gcf-harness run` started this session inside the item's worktree
 - `--handoff` when the harness started this session after the last one filled its context: the plan's `## Handoff` says where it stopped
+- `--no-lessons` when the harness asks this session's lessons itself, in a turn after it ends
 
 preconditions:
 - `gcf/` exists and `ai-factory gcf audit` runs (the gcf-aif-ext extension provides it)
@@ -25,6 +26,10 @@ forbidden_behaviors:
 - do not continue past a failed gate: report the one-line reason, delete `.gcf-session/readset.json`, and stop - a stop is a normal outcome
 - do not compare the audit numbers yourself: the gate command is the only judge of whether an item may go
 - do not ask the human about a reversible choice during planning: pick the safe default and write it into the plan
+- answer aif-plan's own questions (tests, logging, docs, other preferences) yourself from the item, its DoD and the project's rules, and write each answer into the plan
+- a plan pass sorts each finding as blocking or polish, and reports how many of each it found
+- blocking: a wrong or missing behavior, a missing or wrong task, a broken pillar invariant, a conflict with a project rule, a task no check can prove
+- polish: wording, splitting or merging tasks, their order, more detail - the pass applies it, and it does not keep the plan from converging
 - do not edit `status:` or `gcf/LIVE.md` by hand: `submit`, `close` and `block` own them
 - do not write a plan task's first implementation outside the aif-implement skill: it ticks the task done in the plan, and the board shows the item's progress from those ticks
 - a fix for a red DoD or a review finding goes in directly, without aif-implement
@@ -52,8 +57,8 @@ workflow:
 7. plan: run aif-plan full for the item into its `plan:` path, by default `.ai-factory/plans/<id>.md`, reading only the readset files; an existing plan (the item came back after a tune, an unblock or a continue) is kept, not rewritten
 8. improve the plan in passes, each pass a fresh subagent that reads only the plan and the readset and applies aif-improve without questions, writing each default it picks into the plan
 9. each pass also checks every task against the `invariant` of each pillar in `gcf/PILLARS.md`: the pass reworks a task that breaks one, and a conflict no rework removes is a pillar conflict of step 12
-10. after each pass run `ai-factory gcf plan check <id>`; a failure blocks the item with its reason; a pass that changes no task ends the loop - the plan converged
-11. passes <= `plan_passes` from `gcf/config.yml` (5 by default); a plan still changing after the last pass: run `ai-factory gcf block <id> --reason "plan did not converge"` and stop
+10. after each pass run `ai-factory gcf plan check <id>`; a failure blocks the item with its reason; a pass with no blocking finding ends the loop - the plan converged, its polish applied
+11. passes <= `plan_passes` from `gcf/config.yml` (3 by default); a blocking finding left after the last pass: run `ai-factory gcf block <id> --reason "plan did not converge: <the finding>"` and stop
 12. a question only the human can answer - a save format, a public API, a new dependency, a pillar conflict: run `ai-factory gcf block <id> --reason "<question>"` and stop
 13. run the aif-implement skill on `@<plan path>`, write the item's `live:` delta, then run `ai-factory gcf verify <id>` and check the item's negative constraints; a non-zero exit is a red DoD; attempts <= `dod_attempts`, each with a diagnosis
 14. review the diff with a fresh subagent; fix what it finds before the commit; DoD still red after the attempts: commit no code, run `ai-factory gcf block <id> --reason "<diagnosis>"` - its commit carries the item file with its delta
@@ -61,7 +66,7 @@ workflow:
 16. commit the implementation, its plan and the `live:` delta via aif-commit
 17. gate `verdict` or `decision`: run `ai-factory gcf submit <id>`; gate `auto`: run `ai-factory gcf close <id>` - a soft unit closes unplayed
 18. a dependency still waiting for its verdict refuses the close: run `ai-factory gcf block <id> --reason "waits for <dep>"`
-19. close the run: delete `.gcf-session/readset.json`, run `ai-factory gcf playtest session` and hand its checklist to the human, with one report row per plan pass: pass, tasks changed, result
+19. close the run: delete `.gcf-session/readset.json`, run `ai-factory gcf playtest session` and hand its checklist to the human, with one report row per plan pass: pass, blocking, polish, result
 20. after a tune verdict or an unblock, re-enter this pipeline at step 5: the gates re-run because the counters moved
 21. with `--worktree`: skip the integrate of step 1, steps 2-4 and the playtest of step 19, and change no `gcf/` file but the item's `live:`
 22. with `--worktree`, every stop - a failed gate, an over budget readset, a failed plan check, a refused command, steps 11, 12, 14, 18 - writes `{"block": "<reason>"}` to `.gcf-session/outcome.json` and ends the session
@@ -69,6 +74,7 @@ workflow:
 24. with `--worktree`, step 17 is: commit everything but `gcf/.metrics`, then run `ai-factory gcf verify <id> --mark`; the harness merges the branch
 25. with `--handoff`: run steps 1, 5 and 6, read the plan's `## Handoff`, skip steps 7-11 unless it says the plan passes were not done, then go on at step 13; a plan with no `## Handoff` goes on at step 13 from its ticks
 26. with `--handoff`, take the review findings and the DoD diagnosis of `## Handoff` into steps 13-15, and delete the section before the commit of step 16
+27. without `--no-lessons` and without `--worktree`, end the run with the lessons: run `ai-factory gcf lessons prompt <id>` for each item of the run and do what it says
 
 invocation:
 - run when the user names a work item or a unit to drive; batches share steps 1 and 19