gcf-harness-aif-ext 0.9.2 → 0.9.4

package/README.md

@@ -1,114 +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 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.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`.
-
-**`/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. 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
+# 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/harness.js

@@ -8,6 +8,7 @@ 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)), '..');
@@ -374,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')

package/commands/metrics.js

@@ -0,0 +1,144 @@
+// `ai-factory gcf-harness metrics`: the run metrics of Harness-PRD §11 from the logs in
+// gcf/.metrics — runs that reached the core's move, what they cost, the plan checks and DoD
+// attempts they took, the guard firings. A view of the logs: it stores nothing.
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { metricsDir } from '../hooks/metrics.js';
+
+/** The rows of a log at or after `since` (an ISO date or time); none when it is not there. */
+function rows(dir, file, since) {
+  const f = path.join(dir, file);
+  if (!existsSync(f)) return [];
+
+  return readFileSync(f, 'utf8')
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((l) => l.split(','))
+    .filter((r) => !since || r[0] >= since);
+}
+
+const num = (v) => (v === '' || v === undefined ? null : Number(v));
+const sum = (xs) => xs.reduce((a, b) => a + b, 0);
+const avg = (xs) => (xs.length ? sum(xs) / xs.length : null);
+
+/** `{key: count}` of a list, the most frequent first, at most `top` keys. */
+function counts(xs, top = Infinity) {
+  const m = new Map();
+  for (const x of xs) m.set(x, (m.get(x) ?? 0) + 1);
+
+  return Object.fromEntries([...m].sort((a, b) => b[1] - a[1]).slice(0, top));
+}
+
+/** How many rows each item has: the checks or attempts per item. */
+const perItem = (rs) => Object.values(counts(rs.map((r) => r[1])));
+
+// A run ended by the usage limit or cut short (timeout, stop, crash) did not finish: its item
+// goes on in the next run, and the share counts only the runs that did. An item refused before
+// its session (`not-started`: another run holds it, its worktree failed) never ran at all.
+const UNFINISHED = ['paused', 'no-result', 'not-started'];
+
+/** The summary of the logs in `dir`, from `since` on. */
+export function summarize(dir, since = '') {
+  // run-log: at, item, mode, result, reason, cost_usd, input, output, cache_read, turns,
+  // duration_ms, handoffs, process
+  const runs = rows(dir, 'run-log.csv', since);
+  const finished = runs.filter((r) => !UNFINISHED.includes(r[3]));
+  const reached = finished.filter((r) => ['submit', 'close'].includes(r[3]));
+  const spent = runs.map((r) => num(r[5])).filter((v) => v !== null);
+  // plan-log: at, item, ok, problems; verify-log: at, item, ok, failed checks, mark
+  const plans = rows(dir, 'plan-log.csv', since);
+  const verifies = rows(dir, 'verify-log.csv', since).filter((r) => r[4] !== '1');
+  // guard-log: at, item, hook, tool
+  const guards = rows(dir, 'guard-log.csv', since);
+
+  return {
+    since: since || null,
+    runs: {
+      count: runs.length,
+      results: counts(runs.map((r) => r[3])),
+      finished: finished.length,
+      reached: reached.length,
+      share: finished.length ? reached.length / finished.length : null,
+      blocks: counts(
+        runs.filter((r) => r[3] === 'block').map((r) => r[4] || '(no reason)'),
+        5,
+      ),
+      cost_usd: sum(spent),
+      avg_cost_usd: avg(spent),
+      avg_duration_ms: avg(runs.map((r) => num(r[10])).filter((v) => v !== null)),
+      avg_turns: avg(runs.map((r) => num(r[9])).filter((v) => v !== null)),
+      handoffs: sum(runs.map((r) => num(r[11]) ?? 0)),
+      outside_implement: runs.filter((r) => r[12]?.includes('outside aif-implement')).length,
+      unverified: runs.filter((r) => r[12]?.includes('without a green gcf verify')).length,
+    },
+    plan: {
+      items: perItem(plans).length,
+      checks: plans.length,
+      failed: plans.filter((r) => r[2] !== '1').length,
+      avg_checks: avg(perItem(plans)),
+    },
+    verify: {
+      items: perItem(verifies).length,
+      attempts: verifies.length,
+      red: verifies.filter((r) => r[2] !== '1').length,
+      avg_attempts: avg(perItem(verifies)),
+      failing: counts(verifies.flatMap((r) => (r[3] ? r[3].split(' ') : []))),
+    },
+    guard: {
+      count: guards.length,
+      by_hook: counts(guards.map((r) => r[2])),
+      by_item: counts(
+        guards.map((r) => r[1] || '(no item)'),
+        5,
+      ),
+    },
+  };
+}
+
+const list = (o) =>
+  Object.entries(o)
+    .map(([k, n]) => `${k} ${n}`)
+    .join(', ');
+const one = (v, digits = 1) => (v === null ? '-' : v.toFixed(digits));
+
+/** The summary as an operator reads it. */
+export function formatMetrics(s) {
+  const r = s.runs;
+  const share = r.share === null ? '' : ` (${Math.round(r.share * 100)}%)`;
+  const failing = list(s.verify.failing);
+  const minutes = r.avg_duration_ms === null ? '-' : one(r.avg_duration_ms / 60_000, 0);
+
+  return [
+    ...(s.since ? [`since ${s.since}`] : []),
+    `runs: ${r.count} item runs (${list(r.results) || 'none'}); ` +
+      `${r.reached}/${r.finished} finished ones reached submit or close${share}`,
+    ...(Object.keys(r.blocks).length
+      ? [
+          `blocks: ${Object.entries(r.blocks)
+            .map(([why, n]) => `${why} ×${n}`)
+            .join('; ')}`,
+        ]
+      : []),
+    `cost: $${r.cost_usd.toFixed(2)}, $${one(r.avg_cost_usd, 2)} a run, ${minutes} min, ` +
+      `${one(r.avg_turns, 0)} turns; ${r.handoffs} handoffs; ` +
+      `${r.outside_implement} with code outside aif-implement, ` +
+      `${r.unverified} moved without a green verify`,
+    `plan: ${s.plan.items} items, ${one(s.plan.avg_checks)} checks each, ${s.plan.failed} failed`,
+    `verify: ${s.verify.items} items, ${one(s.verify.avg_attempts)} attempts each, ` +
+      `${s.verify.red} red${failing ? ` (${failing})` : ''}`,
+    `guard: ${s.guard.count} firings` +
+      (s.guard.count ? ` (${list(s.guard.by_hook)}); most: ${list(s.guard.by_item)}` : ''),
+  ].join('\n');
+}
+
+/** The `metrics` command: the project's logs, from `--since` on. */
+export function metricsCommand(o) {
+  // The logs stamp UTC: a local date or time is turned into one before the comparison. A bare
+  // date is local midnight (JavaScript would read it as UTC).
+  const local = /^\d{4}-\d\d-\d\d$/.test(o.since ?? '') ? `${o.since}T00:00` : o.since;
+  const at = o.since ? new Date(local) : null;
+  if (at && Number.isNaN(at.getTime()))
+    throw new Error(`--since ${o.since} is not a date (YYYY-MM-DD or an ISO time)`);
+  const s = summarize(metricsDir(process.cwd()), at ? at.toISOString() : '');
+  console.log(o.json ? JSON.stringify(s, null, 2) : formatMetrics(s));
+}

package/commands/run.js

@@ -9,6 +9,7 @@ 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';
+import { logMetrics } from '../hooks/metrics.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';
@@ -778,6 +779,8 @@ function resumeLost(rec, ran) {
 
 /** The report note of an item whose session skipped gcf-run step 13. */
 export const OUTSIDE_IMPLEMENT = 'code written outside aif-implement';
+/** The report note of a main-mode item moved with `--unverified` (its commit says so). */
+export const UNVERIFIED_MOVE = 'moved without a green gcf verify';
 
 /**
  * Whether a session wrote code with no aif-implement before it: its stream shows none, and
@@ -1136,6 +1139,7 @@ async function runMain(projectDir, ids, ctx) {
       id,
       result: 'error',
       error: 'another run works in the main checkout: wait for it, or stop it',
+      started: false,
     }));
 
   const items = [];
@@ -1152,6 +1156,8 @@ async function runMain(projectDir, ids, ctx) {
 async function mainItem(projectDir, id, ctx) {
   const { core, logs, agentOf } = ctx;
   let r;
+  let started = false;
+  const head = headOf(projectDir);
   await rm(stopOf(logs, id), { force: true });
   // The checkout's lock names the item from now on: a stop before its session marks it.
   writeFileSync(path.join(logs, `${MAIN_RUN}.lock`), `${process.pid}\n${id}\n`);
@@ -1182,6 +1188,7 @@ async function mainItem(projectDir, id, ctx) {
       done,
       lessonsPrompt,
     };
+    started = true;
     r = await session(s, ctx);
   } catch (e) {
     r = { id, error: e.message };
@@ -1192,15 +1199,87 @@ async function mainItem(projectDir, id, ctx) {
   const item = await mainResult(core, r);
   await remember(logs, r, item);
 
-  return { ...item, ...r.cost, ...extras(r) };
+  // The core lets a move with no green verify through only with `--unverified`, which its
+  // commit names: the session went past its DoD gate.
+  const note = started && movedUnverified(projectDir, id, head) ? UNVERIFIED_MOVE : null;
+
+  // An item refused before its session spent nothing: the metrics keep it out of the share (§11).
+  return { ...item, ...r.cost, ...extras(r, note), ...(started ? {} : { started: false }) };
+}
+
+/** The checkout's HEAD, or null before its first commit. */
+function headOf(dir) {
+  const r = spawnSync('git', ['rev-parse', '--verify', '-q', 'HEAD'], {
+    cwd: dir,
+    encoding: 'utf8',
+  });
+
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+/**
+ * Whether a commit since `head` moved the item with `--unverified`:
+ * `gcf(close): <id> (unverified: …)`.
+ */
+export function movedUnverified(dir, id, head) {
+  if (!head) return false;
+  const r = spawnSync('git', ['log', '--format=%s', `${head}..HEAD`], {
+    cwd: dir,
+    encoding: 'utf8',
+  });
+  // `tray` must not match `tray-2`: the id ends at a space (an id is [a-z0-9-] only).
+  const move = new RegExp(`^gcf\\((submit|close)\\): ${id} .*\\(unverified: `);
+
+  return r.status === 0 && r.stdout.split('\n').some((s) => move.test(s));
 }
 
-/** 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 } : {}),
-});
+/**
+ * An item's result word and why: `paused (usage limit, resets 3am (…)): …` and
+ * `no result (timeout): …` give their cause in the parentheses.
+ */
+function outcome(i) {
+  const text = String(i.result);
+  const cut = text.startsWith('no result') ? 'no-result' : text.split(/[ (]/)[0];
+  const word = i.started === false ? 'not-started' : cut;
+  const cause = /^[^(]*\((.*?)\)(?::|$)/.exec(text)?.[1];
+
+  return [word, i.reason ?? i.error ?? i.conflict ?? cause];
+}
+
+/**
+ * An item's line of run-log.csv (Harness-PRD §11): its result word (`paused` for the usage
+ * limit, `no-result` for a session cut short), why, and what its sessions spent. A missing
+ * value is an empty field.
+ */
+export const runRow = (mode) => (i) => [
+  i.id,
+  mode,
+  ...outcome(i),
+  i.cost_usd,
+  i.tokens?.input,
+  i.tokens?.output,
+  i.tokens?.cache_read,
+  i.turns,
+  i.duration_ms,
+  i.handoffs ?? 0,
+  i.process,
+];
+
+/**
+ * What rides on an item's line beside its result: its handoffs, and its broken steps (a
+ * skipped step 13, a move with no green verify).
+ * @param {any} r
+ * @param {string | null} [note]
+ */
+const extras = (r, note = null) => {
+  const notes = [r?.skipped && OUTSIDE_IMPLEMENT, note].filter(Boolean).join('; ');
+
+  return {
+    ...(r?.handoffs ? { handoffs: r.handoffs } : {}),
+    ...(notes ? { process: notes } : {}),
+    ...(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) {
@@ -1210,7 +1289,8 @@ async function runWorktrees(claims, ctx) {
   const done = (r) => () =>
     verified(r.dir, r.id) || existsSync(path.join(r.dir, '.gcf-session', 'outcome.json'));
   const runs = await Promise.all(ready.map((r) => session({ ...r, done: done(r) }, ctx)));
-  const items = [...failed];
+  // Refused before a session: the metrics keep them out of the share (§11).
+  const items = failed.map((f) => ({ ...f, started: false }));
   for (const r of runs) {
     const outcome = await outcomeOf(r.dir);
     if (outcome?.block) items.push(await recordBlock(r, outcome, core));
@@ -1287,6 +1367,7 @@ export async function run(
   try {
     const items =
       runMode === 'main' ? await runMain(projectDir, ids, ctx) : await runWorktrees(claims, ctx);
+    logMetrics(projectDir, 'run-log.csv', items.map(runRow(runMode)));
 
     return { orphans, mode: runMode, items };
   } finally {

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.2",
+  "version": "0.9.4",
   "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
   "skills": [
     "skills/gcf-run",

package/hooks/implement-guard.js

@@ -10,6 +10,7 @@
 // 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';
+import { logMetrics } from './metrics.js';
 
 const WRITES = ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'];
 const PLANNING_DIRS = ['gcf', '.ai-factory', '.gcf-session'];
@@ -70,17 +71,43 @@ const ENDS = new RegExp(String.raw`(^|[;&|(])\s*${CLI}gcf\s+(block|submit|close)
 const endsRun = (input) =>
   ['Bash', 'PowerShell'].includes(input.tool_name) &&
   ENDS.test(String(input.tool_input?.command ?? ''));
+// A move past the DoD gate (Methodology §6) is the human's: a session that ran /gcf-run never
+// makes one, even after its end move (a close the core refused must not free it for a skip).
+// The flag may stand anywhere after the move, before the id too, and a line may go on past a
+// `\` or a PowerShell backtick.
+// shortcut: the call forms are CLI's (ai-factory, npx, a path, .cmd); an env prefix, `npx -y`,
+// `bash -c` or a quoted path slip past, as they do past ENDS; widen CLI if a run shows one.
+const SKIPS = new RegExp(
+  String.raw`(^|[;&|(])\s*${CLI}gcf\s+(submit|close)\b[^\n]*?[\s'"]--unverified\b`,
+  'm',
+);
+export const skipsVerify = (input) =>
+  ['Bash', 'PowerShell'].includes(input.tool_name) &&
+  SKIPS.test(String(input.tool_input?.command ?? '').replace(/[\\`]\r?\n/g, ' '));
+const NO_SKIP =
+  "a move without a green gcf verify (--unverified) is the human's call: run ai-factory gcf " +
+  'verify <id> until it is green, or block the item with what keeps the DoD red';
 
 /**
  * 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.
+ * `gated` stays after the end move of a run: a move past the verify gate is refused in such a
+ * session, and its state is kept.
  */
-export function decide(input, projectDir, state) {
+export const decide = (input, projectDir, state) =>
+  input && (state?.run || state?.gated) && skipsVerify(input)
+    ? { state: { ...state }, allow: false, reason: NO_SKIP }
+    : decideMove(input, projectDir, state);
+
+/** `decide` for any input but a move past the verify gate. */
+function decideMove(input, projectDir, state) {
+  const old = state ?? {};
+  // The end move: the run is over, its gate on a skip of the verify stays.
   if (input && endsRun(input))
-    return { state: { run: false, implement: Boolean(state?.implement) }, allow: true };
-  const next = { run: Boolean(state?.run), implement: Boolean(state?.implement) };
+    return { state: stateOf(false, old.implement, old.run || old.gated), allow: true };
+  const next = stateOf(old.run, old.implement, old.gated);
   if (!input) return { state: next, allow: true };
   next.run ||= started(input, 'gcf-run');
   next.implement ||= started(input, 'aif-implement');
@@ -89,6 +116,13 @@ export function decide(input, projectDir, state) {
   return { state: next, ...(guarded ? writeVerdict(input, projectDir) : { allow: true }) };
 }
 
+/** A session's state; `gated` only when set, so a session that never ran /gcf-run has none. */
+const stateOf = (run, implement, gated) => ({
+  run: Boolean(run),
+  implement: Boolean(implement),
+  ...(gated ? { gated: 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;
@@ -107,7 +141,7 @@ export const stateFile = (projectDir, sessionId) =>
     ? path.join(projectDir, '.gcf-session', 'guard', `${sessionId}.json`)
     : null;
 
-/** A session's state: `{run, implement}`, or null without one. */
+/** A session's state: `{run, implement, gated?}`, or null without one. */
 export function readState(projectDir, sessionId) {
   const file = stateFile(projectDir, sessionId);
   try {
@@ -129,7 +163,8 @@ if (import.meta.url === `file://${entry}` || entry?.endsWith('implement-guard.js
     const file = stateFile(projectDir, input?.session_id);
     const changed =
       verdict.state.run !== Boolean(old?.run) ||
-      verdict.state.implement !== Boolean(old?.implement);
+      verdict.state.implement !== Boolean(old?.implement) ||
+      Boolean(verdict.state.gated) !== Boolean(old?.gated);
     if (file && changed) {
       mkdirSync(path.dirname(file), { recursive: true });
       writeFileSync(file, `${JSON.stringify(verdict.state)}\n`);
@@ -137,6 +172,10 @@ if (import.meta.url === `file://${entry}` || entry?.endsWith('implement-guard.js
 
     // A prompt is never refused: exit 2 there would drop the operator's message.
     if (!verdict.allow && input?.hook_event_name !== 'UserPromptSubmit') {
+      const item = process.env.GCF_RUN_ITEM ?? '';
+      // A skip of the verify gate counts apart from a write before aif-implement.
+      const hook = skipsVerify(input) ? 'verify' : 'implement';
+      logMetrics(projectDir, 'guard-log.csv', [[item, hook, input?.tool_name]]);
       console.error(`gcf implement-guard: ${verdict.reason}`);
       process.exit(2);
     }

package/hooks/metrics.js

@@ -0,0 +1,41 @@
+// The harness's lines in gcf/.metrics (Harness-PRD §11), in the main checkout's logs: a
+// worktree's own gcf/.metrics is thrown away when its branch merges. The same layout as the
+// core's lib/metrics.js; the harness calls no core module, only its CLI.
+import { spawnSync } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+
+/** gcf/.metrics of the main checkout of `projectDir`; its own outside a repository. */
+export function metricsDir(projectDir) {
+  const res = spawnSync('git', ['rev-parse', '--git-common-dir'], {
+    cwd: projectDir,
+    encoding: 'utf8',
+  });
+  const common = res.status === 0 ? path.resolve(projectDir, res.stdout.trim()) : '';
+  const main = path.basename(common) === '.git' ? path.dirname(common) : projectDir;
+
+  return path.join(main, 'gcf', '.metrics');
+}
+
+/** A field as csv takes it: no comma, no line break, at most 120 characters. */
+const field = (v) =>
+  String(v ?? '')
+    .replace(/[,\r\n]+/g, ';')
+    .slice(0, 120);
+
+/**
+ * Append timestamped lines to a log; a project without gcf/ keeps none. Best effort: a log
+ * that cannot be written never stops a run or a hook.
+ */
+export function logMetrics(projectDir, file, rows) {
+  try {
+    const dir = metricsDir(projectDir);
+    if (!rows.length || !existsSync(path.dirname(dir))) return;
+    mkdirSync(dir, { recursive: true });
+    const at = new Date().toISOString();
+    const text = rows.map((r) => `${[at, ...r].map(field).join(',')}\n`).join('');
+    appendFileSync(path.join(dir, file), text, 'utf8');
+  } catch {
+    // No log this time.
+  }
+}

package/hooks/readset-guard.js

@@ -8,6 +8,7 @@
 // tool for a solo developer, not a security perimeter.
 import { readFileSync, readdirSync, statSync, utimesSync } from 'node:fs';
 import path from 'node:path';
+import { logMetrics } from './metrics.js';
 
 function readStdin() {
   try {
@@ -145,8 +146,12 @@ if (import.meta.url === `file://${entry}` || entry?.endsWith('readset-guard.js')
   // not found there would allow every read.
   const projectDir = process.env.CLAUDE_PROJECT_DIR ?? input?.cwd ?? process.cwd();
   keepSessionsAlive(projectDir);
-  const verdict = decide(input, projectDir, readManifest(projectDir));
+  const manifest = readManifest(projectDir);
+  const verdict = decide(input, projectDir, manifest);
   if (!verdict.allow) {
+    // Harness-PRD §11, metric 3: each firing is a hole in the readset or a wandering agent.
+    const item = process.env.GCF_RUN_ITEM ?? manifest?.item ?? '';
+    logMetrics(projectDir, 'guard-log.csv', [[item, 'readset', input?.tool_name]]);
     console.error(`gcf readset-guard: ${verdict.reason}`);
     process.exit(2);
   }

package/package.json

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

package/skills/gcf-run/SKILL.md

@@ -1,80 +1,80 @@
----
-name: gcf-run
-description: Drive one or more GCF work items through plan, implement and DoD in a single run - gates before tokens, a converging plan, readset discipline, then submit, close or block. Use when the user says "прогони задачу" / "прогони карточку" / "run the item".
----
-
-mode: pipeline
-
-purpose:
-- drive a work item through gate, readset, plan, implement and its DoD with the stop rules checked before each paid stage
-- end every item in a state the core records: `submit` (waits for the human), `close` (gate auto, done) or `block` (needs the human)
-- outside `--worktree`, mark each item running after its gate passes: `ai-factory gcf claim <id>`; a move clears the mark, and an item left without one gets `ai-factory gcf release <id>`
-- a claimed item takes only its session's moves: run `submit`, `close` and `block` on it with `--claimed`
-
-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)
-
-forbidden_behaviors:
-- do not give a verdict or a decision: `verdict` and `decide` belong to the human, this pipeline stops at `submit`
-- do not read a `gcf/` file outside the readset from `ai-factory gcf context`
-- 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
-- do not let aif-implement commit, stash or merge: answer its questions yourself
-- at aif-implement's uncommitted-changes question pick none of its three options - not "No", which stashes - and go on with the plan
-- at aif-implement's commit checkpoints go on to the next task; skip its rules and docs checkpoints; keep the plan file; at its merge question answer that you handle it
-- a ticked task whose code aif-implement's re-entry check finds missing stays pending and gets implemented, with no question to the human
-- at aif-implement's last question, verify or commit, pick neither: go on with step 13, which verifies, and steps 14-16, which review and commit
-- do not leave a task ticked that the tune note or the answer reopens: untick it and add the note before step 13, or aif-implement's re-entry check ticks it again over the old code
-- do not route a command the permission system refused through a script, a wrapper or another spelling or shell (a full exe path, `cmd /c`, `node`, `npm run`)
-- do not write a refused command into a DoD command or a config that `ai-factory gcf` runs
-- a dedicated tool doing the same job (Read, Grep, Glob, Edit) is no wrapper, nor is a refused pipe or `;` chain split into single allowed commands
-- a refusal none of those replaces is a stop: run `ai-factory gcf block <id> --reason "needs permission: <command>"` and stop the item; under `--worktree` step 22 records it instead
-- a call the handoff guard denies with "context at" is no refusal: block nothing, write the `## Handoff` it asks for and end the reply
-- a read the readset guard denies is no refusal either: drop that read, and widen the readset only through the item's `system:` or `depends:`
-- delete one file with `rm -f <file>` or `Remove-Item -Force <file>`, never with `-r`: the deny rules refuse a recursive delete
-
-workflow:
-1. session ritual: delete a `.gcf-session/readset.json` left by a killed run; run `ai-factory gcf integrate` to merge the verified branches a dead run left; run `ai-factory gcf audit --json`; read `gcf/INDEX.md`; report the audit first line
-2. for a unit still in `gcf/design/`: take it with the gcf-card skill first
-3. for a feature id: replace it with its `ready` children from the audit report's `items` (`parent` names the feature) that are not in `open_depends`; a feature in `awaiting-decision` starts none of them
-4. of those children, keep one per subsystem unless every child sharing it says `parallel: ok`; the rest wait for the next run; an empty list: report "nothing to run" and stop
-5. gate: run `ai-factory gcf-harness gate <item-ids...>` over the whole batch; a non-zero exit is a failed gate, its stderr line is the reason
-6. readset: run `ai-factory gcf context <item-id> --json`; write `{"item":"<id>","files": ctx.files.map(f => f.path)}` to `.gcf-session/readset.json` - paths, not objects; `over_budget: true` stops the run with a D1 question naming the subsystem
-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 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
-15. the reviewer also answers the `review_question` of each pillar in `gcf/PILLARS.md` over the diff: an answer that breaks the pillar is a finding
-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, 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
-23. with `--worktree`, run no `ai-factory gcf block`, `submit` or `close`: the core refuses them on a `work/` branch, and the harness records the move on main
-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
+---
+name: gcf-run
+description: Drive one or more GCF work items through plan, implement and DoD in a single run - gates before tokens, a converging plan, readset discipline, then submit, close or block. Use when the user says "прогони задачу" / "прогони карточку" / "run the item".
+---
+
+mode: pipeline
+
+purpose:
+- drive a work item through gate, readset, plan, implement and its DoD with the stop rules checked before each paid stage
+- end every item in a state the core records: `submit` (waits for the human), `close` (gate auto, done) or `block` (needs the human)
+- outside `--worktree`, mark each item running after its gate passes: `ai-factory gcf claim <id>`; a move clears the mark, and an item left without one gets `ai-factory gcf release <id>`
+- a claimed item takes only its session's moves: run `submit`, `close` and `block` on it with `--claimed`
+
+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)
+
+forbidden_behaviors:
+- do not give a verdict or a decision: `verdict` and `decide` belong to the human, this pipeline stops at `submit`
+- do not read a `gcf/` file outside the readset from `ai-factory gcf context`
+- 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
+- do not let aif-implement commit, stash or merge: answer its questions yourself
+- at aif-implement's uncommitted-changes question pick none of its three options - not "No", which stashes - and go on with the plan
+- at aif-implement's commit checkpoints go on to the next task; skip its rules and docs checkpoints; keep the plan file; at its merge question answer that you handle it
+- a ticked task whose code aif-implement's re-entry check finds missing stays pending and gets implemented, with no question to the human
+- at aif-implement's last question, verify or commit, pick neither: go on with step 13, which verifies, and steps 14-16, which review and commit
+- do not leave a task ticked that the tune note or the answer reopens: untick it and add the note before step 13, or aif-implement's re-entry check ticks it again over the old code
+- do not route a command the permission system refused through a script, a wrapper or another spelling or shell (a full exe path, `cmd /c`, `node`, `npm run`)
+- do not write a refused command into a DoD command or a config that `ai-factory gcf` runs
+- a dedicated tool doing the same job (Read, Grep, Glob, Edit) is no wrapper, nor is a refused pipe or `;` chain split into single allowed commands
+- a refusal none of those replaces is a stop: run `ai-factory gcf block <id> --reason "needs permission: <command>"` and stop the item; under `--worktree` step 22 records it instead
+- a call the handoff guard denies with "context at" is no refusal: block nothing, write the `## Handoff` it asks for and end the reply
+- a read the readset guard denies is no refusal either: drop that read, and widen the readset only through the item's `system:` or `depends:`
+- delete one file with `rm -f <file>` or `Remove-Item -Force <file>`, never with `-r`: the deny rules refuse a recursive delete
+
+workflow:
+1. session ritual: delete a `.gcf-session/readset.json` left by a killed run; run `ai-factory gcf integrate` to merge the verified branches a dead run left; run `ai-factory gcf audit --json`; read `gcf/INDEX.md`; report the audit first line
+2. for a unit still in `gcf/design/`: take it with the gcf-card skill first
+3. for a feature id: replace it with its `ready` children from the audit report's `items` (`parent` names the feature) that are not in `open_depends`; a feature in `awaiting-decision` starts none of them
+4. of those children, keep one per subsystem unless every child sharing it says `parallel: ok`; the rest wait for the next run; an empty list: report "nothing to run" and stop
+5. gate: run `ai-factory gcf-harness gate <item-ids...>` over the whole batch; a non-zero exit is a failed gate, its stderr line is the reason
+6. readset: run `ai-factory gcf context <item-id> --json`; write `{"item":"<id>","files": ctx.files.map(f => f.path)}` to `.gcf-session/readset.json` - paths, not objects; `over_budget: true` stops the run with a D1 question naming the subsystem
+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 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
+15. the reviewer also answers the `review_question` of each pillar in `gcf/PILLARS.md` over the diff: an answer that breaks the pillar is a finding
+16. after a review fix, run `ai-factory gcf verify <id>` again until green - `submit` and `close` refuse changed code; then 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; never pass `--unverified`: a move without a green verify is the human's call
+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, 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
+23. with `--worktree`, run no `ai-factory gcf block`, `submit` or `close`: the core refuses them on a `work/` branch, and the harness records the move on main
+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