gcf-harness-aif-ext 0.9.1 → 0.9.4

package/README.md

@@ -1,105 +1,118 @@
-# gcf-harness-aif-ext
-
-Claude-Code-specific orchestration for the [Game Context Framework](../gcf-aif-ext). Optional: GCF works without it, by hand.
-
-> **Claude Code only.** Codex and the other AI Factory runtimes are not supported: the harness is built on Claude Code
-> dynamic workflows and `PreToolUse` hooks, which they do not have. AI Factory still copies the `gcf-run` skills into
-> every runtime the project is configured for, where they do not work — on a project without Claude Code, do not
-> install the harness. GCF itself keeps working on any runtime.
-
-The harness turns policy-as-text into an executable pipeline. It has **no memory of its own** — everything it knows between two agent calls is on disk in `gcf/`, so a run killed at any point restarts and reaches the same state.
-
-## Requirements
-
-- [`gcf-aif-ext`](../gcf-aif-ext) `^0.7.0` installed, with a `gcf/` tree in the project — declared as a peer dependency, and `gcf-harness init` refuses when the `gcf` command is not registered
-- Claude Code 2.1.270+ (hooks, dynamic workflows) — the only supported runtime
-- AI Factory 2.x, Node.js ≥ 22.14
-
-## Install
-
-The shortest way is from the core: `ai-factory gcf init` asks whether to install the harness too, and on yes runs both steps below. It asks only in a terminal and only when the project has the Claude Code agent; `gcf init --harness` installs it without asking, `--no-harness` skips the question.
-
-By hand, into a project that already has the core, from npm or a local checkout:
-
-```bash
-ai-factory extension add gcf-aif-ext                                # the core, if not yet installed
-ai-factory extension add gcf-harness-aif-ext                        # npm
-# ai-factory extension add ../GCF/packages/gcf-harness-aif-ext      # local checkout
-```
-
-This installs the `gcf-run` and `gcf-run-ingest` skills and registers the `gcf-harness` command. Then initialize the harness in the project — like `gcf init`, once per project:
-
-```bash
-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.
-
-## Upgrade
-
-```bash
-ai-factory extension update gcf-harness-aif-ext
-```
-
-Updating keeps the hook entry valid — it points into the extension's install directory, which an update refreshes in place.
-
-0.5.0 drives work items (`gcf/work/<id>.md`, schema 3) instead of cards and requires `gcf-aif-ext` 0.4.0 — update both together; against an older core the gate refuses with `gcf-aif-ext >= 0.4.0 is required`. A project still holding schema 2 cards in `gcf/cards/` re-creates them first (see the core's "Upgrading from 0.3.x"). What changes for you: `/gcf-run` takes ids of items in `ready`; it no longer stops at `built` but ends each item with `submit`, `close` or `block`; the plan is improved in passes until it converges; the WIP cap counts only items that end waiting for a verdict.
-
-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.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.
-- A stop that comes while the session starts no longer misses it.
-
-0.9.0, to update together with core 0.7.6:
-- The harness's own agent runs with `--permission-mode bypassPermissions`: it may do everything but the project's deny rules, which hold in every mode. The rules come from the deny groups of `gcf/config.yml` (`ai-factory gcf permissions`, or the board): git history and uncommitted work, recursive delete, publishing, the human's GCF moves and the guards are on by default; secrets, changes outside the project and killing processes are off. `git push` is allowed. Deny rules match the command as written: they catch accidents, not a rewording, and `/gcf-run` makes a refused command a stop with `needs permission: <command>`.
-- A run loads the project's settings and MCP servers only (`--setting-sources project,local --strict-mcp-config --mcp-config .mcp.json`): the operator's plugins, hooks and claude.ai connectors stay out. So does `env` or `apiKeyHelper` in `~/.claude/settings.json`: an operator who logs in through them, not `claude login`, names the agent with `--agent`. The deny rules and the handoff guard come in `.gcf-session/runs/agent-settings.json` (`--settings`), so a worktree gets them without a commit.
-- Context handoff: past `context_handoff_pct` (60 by default) of the window, or at a compaction, the run flags the session; the handoff guard then denies every call of the main agent but the plan's read and edit with the instruction to write `## Handoff` into the plan and end. The run starts a fresh session with `/gcf-run <id> --handoff`, which goes on from the plan: the ticked tasks stay done. A session that works on past its flag is stopped; after 3 handoffs in a row the item is blocked with `context handoff limit`. The window is `context_window`, else the one a result of the same model reported (`.gcf-session/runs/windows.json`); with neither, the first session of a model runs without a handoff and says so. The sessions of an item share one timeout, and their costs add up; `--json` gives `handoffs`.
-- `auto_compact_pct` sets the agent's `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`, at least 15 points above the handoff share.
-- The readset-guard reads the manifest of the directory the session started in (`CLAUDE_PROJECT_DIR`): an agent's `cd` no longer lifts the readset.
-- `/gcf-run` writes a plan task's code through aif-implement, so the plan ticks show the item's progress, and answers aif-implement's questions itself: no commit, stash or merge.
-
-0.8.0, to update together with core 0.7.0:
-- `run_mode: main` in `gcf/config.yml` (or `run --mode main`): items run one after another in the main checkout, for an agent that works through an editor bound to the project folder. The item carries the core's session mark (`gcf claim`), not a run lock, so the agent records its own move; one run works the checkout at a time (`.gcf-session/runs/.main-run.lock`).
-- `gcf-harness next [N] --json`: the ready items that can run together now, by priority; each is taken while the batch with it passes the gate.
-- `gcf-harness stop <id>`: stops the session that works the item (its run lock names it); the run records no result for it and goes on with the rest. The item stays ready and its work is kept. Known limit: the session is killed at once, so a `gcf` move it was in the middle of may leave `.gcf-session/main.lock` behind (taken over once its pid is gone).
-- A run on main refreshes its item's mark every 5 minutes, and the readset-guard hook refreshes live marks on each read: a long build without a gcf command does not expire it.
-- `run` refuses an id that is not a slug before it names a lock file or builds the agent's command line.
-- The gate lets a session through for the item its own run marked (`GCF_RUN_ITEM`); `/gcf-run` outside a worktree claims each item after its gate and releases one it leaves without a move.
-
-0.7.0, to update together with core 0.6.0: an item's `model:` and `effort:` (`gcf item new --model <m> --effort <e>`) go to its agent as `--model <m> --effort <e>`, read from `gcf board --json`; a value that is not one plain word fails that item and starts no session. `--timeout <minutes>` (120 by default) stops a session that runs longer, with every process it started; its item stays ready, and its run lock is freed. The gate counts the items other runs drive now: their places under the WIP limit, and their systems — a board starts one run per click. Requires `gcf-aif-ext` 0.6.
-
-0.6.1 is a fix release, to update together with core 0.5.3. The run lock `.gcf-session/runs/<id>.lock` is created exclusively, and a lock left by a dead run is taken over; while it is live, the gate refuses the item to another run and the core refuses any move on it, `/gcf-run` on main included. A session whose log cannot open ends as an error and releases its claim.
-
-0.6.0 adds `ai-factory gcf-harness run` (a batch at once, a worktree and an agent session per item, then the integrator) and the `--worktree` mode of `/gcf-run`, whose session ritual now integrates the verified branches a dead run left. It requires `gcf-aif-ext` 0.5.0 (`gcf worktree`, `gcf integrate`, `gcf verify`) — update both together and run `ai-factory gcf init`. The DoD of `/gcf-run` is `ai-factory gcf verify <id>`, and the item's `live:` delta is written before it.
-
-0.4.1 is a patch release. `/gcf-run` now commits the implementation first, then flips the card to `built` in a second commit, with `built_at` set to the implementation commit's hash. Update the core to 0.3.1 together with the harness: without it, an audit run before a verdict makes the pre-commit gate refuse that verdict.
-
-To remove the extension:
-
-```bash
-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.
-
-## 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.
-
-**`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.
-
-**`ai-factory gcf-harness run <item-id…> [--agent "<cmd>"]`** — runs a batch at once, each item in its own worktree (`gcf worktree <id>`) with its own agent session: `claude -p --output-format stream-json --verbose "/gcf-run <id> --worktree"` by default, or the command in `--agent` / `GCF_RUN_AGENT`. The sessions run unattended, so set the agent's permissions for print mode first. A session ends with a commit and `gcf verify <id> --mark` (the `GCF-Verified` trailer); a question for the human goes into `.gcf-session/outcome.json` in its worktree, and `run` records the block on main. Then `gcf integrate` merges the verified branches and records each move, and `run` prints the playtest session. Its first step, like `/gcf-run`'s, integrates the verified branches a dead run left. A session that ended with no result leaves its item `ready`; the next `run` resumes its worktree and the agent's own session (`--resume <session_id>`, kept in `.gcf-session/runs/<id>.agent.json`), in either run mode; `--fresh` starts a new session instead. A session cut off by Claude's usage limit reports `paused (usage limit, resets 3am (…))` and `limit_resets`. Logs: `.gcf-session/runs/<id>.log`, written as the session works: a `start:` line, then one stamped line per agent message, tool call (`tool: Edit <file>`, `tool: Bash <command>`) and failed tool result, and at the end the agent's final text and `done in 34m, 212 turns, $3.41 (…tokens)`; stderr goes in as it is, and a non-Claude `--agent` keeps its own lines. With `--json`, each item carries the session's `cost_usd`, `tokens`, `turns` and `duration_ms` when the agent reported them. One run drives an item at a time (`.gcf-session/runs/<id>.lock`), and a resumed worktree first gets main merged in, so the answer from an `unblock` reaches the session. A worktree sees only what is committed: keep `.ai-factory.json`, the installed extensions and `.claude/` (skills, the readset-guard hook) in git, or the session has no `/gcf-run` and no `ai-factory gcf`.
-
-**`/gcf-run-ingest <gdd.md>`** — imports a design document as a fan-out workflow: parallel aspect extraction, provenance verified by code rather than by an agent (a quote either is a verbatim substring of its section or it is not), completeness lenses per candidate, and an interaction matrix computed from the candidates that write the same state.
-
-**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.
-
-## 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.
-
-## License
-
-MIT
+# gcf-harness-aif-ext
+
+Claude-Code-specific orchestration for the [Game Context Framework](../gcf-aif-ext). Optional: GCF works without it, by hand.
+
+> **Claude Code only.** Codex and the other AI Factory runtimes are not supported: the harness is built on Claude Code
+> dynamic workflows and `PreToolUse` hooks, which they do not have. AI Factory still copies the `gcf-run` skills into
+> every runtime the project is configured for, where they do not work — on a project without Claude Code, do not
+> install the harness. GCF itself keeps working on any runtime.
+
+The harness turns policy-as-text into an executable pipeline. It has **no memory of its own** — everything it knows between two agent calls is on disk in `gcf/`, so a run killed at any point restarts and reaches the same state.
+
+## Requirements
+
+- [`gcf-aif-ext`](../gcf-aif-ext) `^0.7.0` installed, with a `gcf/` tree in the project — declared as a peer dependency, and `gcf-harness init` refuses when the `gcf` command is not registered
+- Claude Code 2.1.270+ (hooks, dynamic workflows) — the only supported runtime
+- AI Factory 2.x, Node.js ≥ 22.14
+
+## Install
+
+The shortest way is from the core: `ai-factory gcf init` asks whether to install the harness too, and on yes runs both steps below. It asks only in a terminal and only when the project has the Claude Code agent; `gcf init --harness` installs it without asking, `--no-harness` skips the question.
+
+By hand, into a project that already has the core, from npm or a local checkout:
+
+```bash
+ai-factory extension add gcf-aif-ext                                # the core, if not yet installed
+ai-factory extension add gcf-harness-aif-ext                        # npm
+# ai-factory extension add ../GCF/packages/gcf-harness-aif-ext      # local checkout
+```
+
+This installs the `gcf-run` and `gcf-run-ingest` skills and registers the `gcf-harness` command. Then initialize the harness in the project — like `gcf init`, once per project:
+
+```bash
+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 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
+
+```bash
+ai-factory extension update gcf-harness-aif-ext
+```
+
+Updating keeps the hook entry valid — it points into the extension's install directory, which an update refreshes in place.
+
+0.5.0 drives work items (`gcf/work/<id>.md`, schema 3) instead of cards and requires `gcf-aif-ext` 0.4.0 — update both together; against an older core the gate refuses with `gcf-aif-ext >= 0.4.0 is required`. A project still holding schema 2 cards in `gcf/cards/` re-creates them first (see the core's "Upgrading from 0.3.x"). What changes for you: `/gcf-run` takes ids of items in `ready`; it no longer stops at `built` but ends each item with `submit`, `close` or `block`; the plan is improved in passes until it converges; the WIP cap counts only items that end waiting for a verdict.
+
+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.4 keeps run metrics (Harness-PRD §11) and adds `ai-factory gcf-harness metrics`. Use it with core 0.7.13, which logs the plan checks and the DoD attempts, and refuses `close` and `submit` without a green `gcf verify` of the code as it is. `/gcf-run` runs the verify again after a review fix; implement-guard refuses `gcf close` or `gcf submit` with `--unverified` in a `/gcf-run` session, since a move past the DoD gate is the human's call. A main-mode item whose move went past it anyway (the commit says `(unverified: …)`) reads `— moved without a green gcf verify` on its report line, and `gcf-harness metrics` counts such moves.
+
+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.
+- A stop that comes while the session starts no longer misses it.
+
+0.9.0, to update together with core 0.7.6:
+- The harness's own agent runs with `--permission-mode bypassPermissions`: it may do everything but the project's deny rules, which hold in every mode. The rules come from the deny groups of `gcf/config.yml` (`ai-factory gcf permissions`, or the board): git history and uncommitted work, recursive delete, publishing, the human's GCF moves and the guards are on by default; secrets, changes outside the project and killing processes are off. `git push` is allowed. Deny rules match the command as written: they catch accidents, not a rewording, and `/gcf-run` makes a refused command a stop with `needs permission: <command>`.
+- A run loads the project's settings and MCP servers only (`--setting-sources project,local --strict-mcp-config --mcp-config .mcp.json`): the operator's plugins, hooks and claude.ai connectors stay out. So does `env` or `apiKeyHelper` in `~/.claude/settings.json`: an operator who logs in through them, not `claude login`, names the agent with `--agent`. The deny rules and the handoff guard come in `.gcf-session/runs/agent-settings.json` (`--settings`), so a worktree gets them without a commit.
+- Context handoff: past `context_handoff_pct` (60 by default) of the window, or at a compaction, the run flags the session; the handoff guard then denies every call of the main agent but the plan's read and edit with the instruction to write `## Handoff` into the plan and end. The run starts a fresh session with `/gcf-run <id> --handoff`, which goes on from the plan: the ticked tasks stay done. A session that works on past its flag is stopped; after 3 handoffs in a row the item is blocked with `context handoff limit`. The window is `context_window`, else the one a result of the same model reported (`.gcf-session/runs/windows.json`); with neither, the first session of a model runs without a handoff and says so. The sessions of an item share one timeout, and their costs add up; `--json` gives `handoffs`.
+- `auto_compact_pct` sets the agent's `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`, at least 15 points above the handoff share.
+- The readset-guard reads the manifest of the directory the session started in (`CLAUDE_PROJECT_DIR`): an agent's `cd` no longer lifts the readset.
+- `/gcf-run` writes a plan task's code through aif-implement, so the plan ticks show the item's progress, and answers aif-implement's questions itself: no commit, stash or merge.
+
+0.8.0, to update together with core 0.7.0:
+- `run_mode: main` in `gcf/config.yml` (or `run --mode main`): items run one after another in the main checkout, for an agent that works through an editor bound to the project folder. The item carries the core's session mark (`gcf claim`), not a run lock, so the agent records its own move; one run works the checkout at a time (`.gcf-session/runs/.main-run.lock`).
+- `gcf-harness next [N] --json`: the ready items that can run together now, by priority; each is taken while the batch with it passes the gate.
+- `gcf-harness stop <id>`: stops the session that works the item (its run lock names it); the run records no result for it and goes on with the rest. The item stays ready and its work is kept. Known limit: the session is killed at once, so a `gcf` move it was in the middle of may leave `.gcf-session/main.lock` behind (taken over once its pid is gone).
+- A run on main refreshes its item's mark every 5 minutes, and the readset-guard hook refreshes live marks on each read: a long build without a gcf command does not expire it.
+- `run` refuses an id that is not a slug before it names a lock file or builds the agent's command line.
+- The gate lets a session through for the item its own run marked (`GCF_RUN_ITEM`); `/gcf-run` outside a worktree claims each item after its gate and releases one it leaves without a move.
+
+0.7.0, to update together with core 0.6.0: an item's `model:` and `effort:` (`gcf item new --model <m> --effort <e>`) go to its agent as `--model <m> --effort <e>`, read from `gcf board --json`; a value that is not one plain word fails that item and starts no session. `--timeout <minutes>` (120 by default) stops a session that runs longer, with every process it started; its item stays ready, and its run lock is freed. The gate counts the items other runs drive now: their places under the WIP limit, and their systems — a board starts one run per click. Requires `gcf-aif-ext` 0.6.
+
+0.6.1 is a fix release, to update together with core 0.5.3. The run lock `.gcf-session/runs/<id>.lock` is created exclusively, and a lock left by a dead run is taken over; while it is live, the gate refuses the item to another run and the core refuses any move on it, `/gcf-run` on main included. A session whose log cannot open ends as an error and releases its claim.
+
+0.6.0 adds `ai-factory gcf-harness run` (a batch at once, a worktree and an agent session per item, then the integrator) and the `--worktree` mode of `/gcf-run`, whose session ritual now integrates the verified branches a dead run left. It requires `gcf-aif-ext` 0.5.0 (`gcf worktree`, `gcf integrate`, `gcf verify`) — update both together and run `ai-factory gcf init`. The DoD of `/gcf-run` is `ai-factory gcf verify <id>`, and the item's `live:` delta is written before it.
+
+0.4.1 is a patch release. `/gcf-run` now commits the implementation first, then flips the card to `built` in a second commit, with `built_at` set to the implementation commit's hash. Update the core to 0.3.1 together with the harness: without it, an audit run before a verdict makes the pre-commit gate refuse that verdict.
+
+To remove the extension:
+
+```bash
+ai-factory extension remove gcf-harness-aif-ext
+```
+
+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 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.
+
+**`ai-factory gcf-harness run <item-id…> [--agent "<cmd>"]`** — runs a batch at once, each item in its own worktree (`gcf worktree <id>`) with its own agent session: `claude -p --output-format stream-json --verbose "/gcf-run <id> --worktree"` by default, or the command in `--agent` / `GCF_RUN_AGENT`. The sessions run unattended, so set the agent's permissions for print mode first. A session ends with a commit and `gcf verify <id> --mark` (the `GCF-Verified` trailer); a question for the human goes into `.gcf-session/outcome.json` in its worktree, and `run` records the block on main. Then `gcf integrate` merges the verified branches and records each move, and `run` prints the playtest session. Its first step, like `/gcf-run`'s, integrates the verified branches a dead run left. A session that ended with no result leaves its item `ready`; the next `run` resumes its worktree and the agent's own session (`--resume <session_id>`, kept in `.gcf-session/runs/<id>.agent.json`), in either run mode; `--fresh` starts a new session instead. A session cut off by Claude's usage limit reports `paused (usage limit, resets 3am (…))` and `limit_resets`. Logs: `.gcf-session/runs/<id>.log`, written as the session works: a `start:` line, then one stamped line per agent message, tool call (`tool: Edit <file>`, `tool: Bash <command>`) and failed tool result, and at the end the agent's final text and `done in 34m, 212 turns, $3.41 (…tokens)`; stderr goes in as it is, and a non-Claude `--agent` keeps its own lines. With `--json`, each item carries the session's `cost_usd`, `tokens`, `turns` and `duration_ms` when the agent reported them. One run drives an item at a time (`.gcf-session/runs/<id>.lock`), and a resumed worktree first gets main merged in, so the answer from an `unblock` reaches the session. A worktree sees only what is committed: keep `.ai-factory.json`, the installed extensions and `.claude/` (skills, the readset-guard hook) in git, or the session has no `/gcf-run` and no `ai-factory gcf`.
+
+**`ai-factory gcf-harness metrics [--since <date>] [--json]`** — the run metrics of Harness-PRD §11 from `gcf/.metrics`: how many item runs reached `submit` or `close` (a run the usage limit paused or a session cut short does not count as finished), the block reasons, what the runs cost (dollars, minutes, turns, handoffs, code written outside aif-implement), the plan checks per item (the improve passes), the DoD attempts per item and the checks that failed them, and the guard firings by hook and by item. The logs: `run-log.csv` (one line per item of each `run`), `guard-log.csv` (each denial of readset-guard and implement-guard, by hook: `readset`, `implement`, or `verify` for a move past the verify gate), and the core's `plan-log.csv` and `verify-log.csv`. A worktree session's lines go to the main checkout's logs; the next `gcf integrate` commits them.
+
+**`/gcf-run-ingest <gdd.md>`** — imports a design document as a fan-out workflow: parallel aspect extraction, provenance verified by code rather than by an agent (a quote either is a verbatim substring of its section or it is not), completeness lenses per candidate, and an interaction matrix computed from the candidates that write the same state.
+
+**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. A `gcf submit` or `gcf close` with `--unverified` is refused in such a session, after its end move too (a close the core refused does not free it for a skip): only the human moves an item past the DoD gate, from a terminal of their own. Such a refusal is logged with the hook name `verify`. 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.
+
+## License
+
+MIT

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).
@@ -8,10 +8,10 @@ import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { metricsCommand } from './metrics.js';
 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 +185,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 +249,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 +301,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 +338,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));
 
@@ -327,6 +375,12 @@ export function register(program) {
       const ids = nextBatch(auditReport(), Math.max(1, Number(count ?? 1) || 1));
       console.log(o.json ? JSON.stringify(ids) : ids.join('\n') || 'nothing can run now');
     });
+  harness
+    .command('metrics')
+    .description('Run metrics from gcf/.metrics: reached moves, cost, plan checks, DoD, guards')
+    .option('--since <date>', 'only lines at or after this ISO date or time')
+    .option('--json', 'machine output')
+    .action(metricsCommand);
   harness
     .command('stop <id>')
     .description('Stop the session that works an item; the run goes on, the item stays ready')
@@ -398,15 +452,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()}`);
 }