gcf-harness-aif-ext 0.12.1 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,143 +1,149 @@
1
- # gcf-harness-aif-ext
2
-
3
- Claude-Code-specific orchestration for the [Game Context Framework](../gcf-aif-ext). Optional: GCF works without it, by hand.
4
-
5
- > **Claude Code only.** Codex and the other AI Factory runtimes are not supported: the harness is built on Claude Code
6
- > dynamic workflows and `PreToolUse` hooks, which they do not have. AI Factory still copies the `gcf-run` skills into
7
- > every runtime the project is configured for, where they do not work — on a project without Claude Code, do not
8
- > install the harness. GCF itself keeps working on any runtime.
9
-
10
- The harness turns policy-as-text into an executable pipeline. The game's state is on disk in `gcf/` and git, so a run killed at any point restarts and reaches the same state. The runs' own state is in `.gcf-session/`: the agent sessions a rerun resumes, the item worktrees with their uncommitted work, locks and logs. Losing it never breaks the game's model, but it loses those resumes, that work and the diagnosis: delete a single stale file, never the folder.
11
-
12
- ## Requirements
13
-
14
- - [`gcf-aif-ext`](../gcf-aif-ext) `^0.7.14 || ^0.8.0 || ^0.9.0 || ^0.10.0` installed (the peer range of `package.json`), with a `gcf/` tree in the project — declared as a peer dependency, and `gcf-harness init` refuses when the `gcf` command is not registered
15
- - Claude Code 2.1.270+ (hooks, dynamic workflows) — the only supported runtime
16
- - AI Factory 2.x, Node.js ≥ 22.14
17
-
18
- ## Install
19
-
20
- 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.
21
-
22
- By hand, into a project that already has the core, from npm or a local checkout:
23
-
24
- ```bash
25
- ai-factory extension add gcf-aif-ext # the core, if not yet installed
26
- ai-factory extension add gcf-harness-aif-ext # npm
27
- # ai-factory extension add ../GCF/packages/gcf-harness-aif-ext # local checkout
28
- ```
29
-
30
- 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:
31
-
32
- ```bash
33
- ai-factory gcf-harness init # per project: .claude/settings.json + .gitignore
34
- ```
35
-
36
- 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.
37
-
38
- ## Upgrade
39
-
40
- ```bash
41
- ai-factory extension update gcf-harness-aif-ext
42
- ```
43
-
44
- Updating keeps the hook entry valid — it points into the extension's install directory, which an update refreshes in place.
45
-
46
- 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.
47
-
48
- 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.
49
-
50
- 0.12.0 moves the session mechanics into the bundled session engine `gcf-session` (docs/Session-Engine.md) and needs gcf-aif-ext 0.12.0: a core without neutral rules (`agent.rules`) is refused before any item is claimed. The hooks keep their files and matchers: no new `init` is needed.
51
- - **The usage limit waits.** A session cut by the limit with a known reset waits for it (plus 60 s) and goes on in the same session. Before the wait its record is written (`<id>.agent.json`, `ended: limit`, `resets` as ISO), so a run killed meanwhile resumes the same session; the chat gets `limit {until}`; the wait does not count against `--timeout`; `gcf-harness stop` ends it. It does not wait for the week's limit, an unknown reset, a reset over 6 h away, an item's third limit in a run, or a lessons turn: those end `paused` as before. `--wait-limit` (a queued start from the board) also holds each session while a known reset is ahead. `--json` says `limit_wait: true`.
52
- - **Owners.** The handoff flag and the readset manifest name their owner and item: the guards act only on that session, so a project chat or an interactive claude in the same folder goes on. The guards are each a neutral decision and a claude shim, with the same files and input as before.
53
- - **Milestones from what the work left:** the DoD's `ok` comes from the item's row of main's `gcf/.metrics/verify-log.csv` between the call and its result (`null` with none or two), a commit's from the new HEAD; a worktree's move is main's to record.
54
- - A background subagent keeps the session open with no timer and no default answer (`background`, then `working`); the context window is known from the first turn (the live `modelUsage`), and the chat shows the share during a turn (`context`).
55
- - `GCF_SESSION_AGENT` puts another agent in place of `claude` (tests); `GCF_RUN_AGENT` still works.
56
-
57
- 0.11.1 reworks the chat (docs/Chat-Plan.md) and needs gcf-aif-ext 0.11.1 for its settings (an older core gives the defaults):
58
- - `chat:` of `gcf/config.yml` decides who waits for whom: `ask` (`d1` by default: only the human's decisions by a question card; `all`; `none`: each card is denied, the agent decides) goes to the skill as `/gcf-run <id> --ask d1|all`; `answer_timeout_min` (15) is how long a question waits, 0 when nobody watches (then `ask` is `none`). `--chat-timeout` has no default any more: it overrides the setting for one run, 0 allowed.
59
- - `ai-factory gcf-harness chat <id> say [text] [--text-file <path|->] [--image <path>]…`, `answer <request_id> [text] [--answers-file <path|->]`, `interrupt` writes the operator's input: checked (text up to 64 000 characters, up to 10 png/jpg/gif/webp pictures of 5 MB each, an answer to an open card only), never through a link, and only while a live session reads it. Exit 1: bad input; 3: no live chat session; 4: the write failed. A picture is copied into `.gcf-session/runs/<id>.att/`, not git; `chat-in.jsonl` names it by path.
60
- - `<id>.chat.jsonl` adds the run's milestones from the main agent's tool calls (`step`: the plan converged with its passes, the DoD, the review subagent the skill names `gcf review`, a commit, the item's move; in a worktree the move main recorded), each session's start and end, the handoff flag, the context share at each turn's end, and an `error` for input that reached no one (a dropped card, a missing picture, a message after the item's last session).
61
- - A turn whose messages the agent never echoed as read frees the session after 10 s with no new turn. After the operator's interrupt the session waits for them with no default answer, while the session's timeout runs on. A session flagged for a handoff closes at its turn's end, as without the chat: no more reminder to hand over. A card a session took with it at its end is dropped.
62
-
63
- 0.10.0 adds the chat (docs/Chat-Plan.md, stage 1): `run --chat` keeps each agent session open to the operator. The prompt goes in as the session's first stream-json message on stdin. The operator writes into `.gcf-session/runs/<id>.chat-in.jsonl`, one JSON a line: `{"type":"say","text":…,"images":[{media_type,data}]}`, `{"type":"interrupt"}` (stops the agent's step, the session stays), `{"type":"answer","request_id":…,"answers":{…}}` (a question card). What the operator reads goes to `<id>.chat.jsonl`: the agent's text, each message sent and when the agent read it, question cards and their answers, the end of each turn. A question waits `--chat-timeout` minutes (15 by default), and the session's own timeout stands still meanwhile; then the run answers: the card's recommended option, or `take your safe default, or block the item`. A turn that ends without the item's move waits the same way, once. Without `--chat` nothing changes. A session flagged for a handoff closes once it went on past its flag, and the fresh one takes the chat on; flagged on its turn's last message, it is first told to hand over. A message sent while a question card is open leaves the card its timeout. `--chat` adds `claude`'s stream-json flags to the agent's command: another `--agent` must take them. Any other tool approval the agent asks for is denied: the run's permissions decide. Checked live with `claude` (Haiku): the prompt on stdin, an interrupt, the operator's message, the item blocked, the session closed.
64
-
65
- 0.9.10 makes a main run's session marks its own (with core 0.10.2): the run sets `GCF_RUN_OWNER=run:<pid>`, its core calls and every agent session it starts (a fresh one after a handoff too) inherit it, and the core refuses the mark to anyone else. An item another session has claimed is refused with `worked by another agent session`. `/gcf-run` reports a refused claim and goes on with the next item; it never releases another session's mark, and neither does the run (`gcf-harness stop` still does: that is the human's). The readset-guard hook keeps only its own session's marks fresh (and marks that name nobody), so another session's mark expires when that session stops.
66
-
67
- 0.9.9 changes no code: its peer range adds core 0.10.0, whose board read is schema 3 and names this harness as the domain's runner (the harness reads neither).
68
-
69
- 0.9.8 changes no code: its peer range adds core 0.9.0, whose board read is schema 2 (the harness does not read it).
70
-
71
- 0.9.6 (with core 0.7.14, now the peer range): `/gcf-run-ingest` hands its workflow the sections with their bodies, gets the same delta again after a failed run and ends the import with `gcf anchor --done`; it takes the text of a changed section as `/gcf-ingest` does, and adds resources, entities and measurable constraints by the sequential pass. The workflow marks the GDD as data in every prompt and asks a lens's D2 as a D1. `/gcf-run` reads only `INDEX.md` and `config.yml` beyond the readset, hands fresh subagents the context's graveyard and D2 lines, counts a re-verify after review against `dod_attempts`, files a D1 for a design question on main, never widens the readset by a false `depends:`, and runs in Claude Code only.
72
-
73
- 0.9.5: `gcf-harness metrics` also sums the cost per item over all its runs and per day and week (`items`, `by_day`, `by_week` in `--json`, a `weeks:` line in the text); `gcf-board` 0.2.18 shows them in its Metrics tab. A resumed session's cost no longer counts twice: `claude` reports a resumed session's whole dollar total, so the lessons turn and a rerun after a limit or a cut now count from what the session had already spent (it is kept in `<id>.agent.json`); before, a lessons turn added its session's cost again. The `done in …` line of the log still shows claude's own figure. A core refusal reads as its whole message: a failed `git worktree add` names its cause, not only git's first line.
74
-
75
- 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.
76
-
77
- 0.9.2 holds `/gcf-run` to aif-implement. Run `ai-factory gcf-harness init` again after the update: it registers the new hook.
78
- - 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.
79
- - `/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.
80
- - `/gcf-run` answers aif-plan's own questions (tests, logging, docs) itself, from the item, its DoD and the project's rules.
81
- - 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.
82
- - 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.
83
-
84
- 0.9.1 is a fix release:
85
- - 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).
86
- - `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.
87
- - A stop that comes while the session starts no longer misses it.
88
-
89
- 0.9.0, to update together with core 0.7.6:
90
- - 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>`.
91
- - 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.
92
- - 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`.
93
- - `auto_compact_pct` sets the agent's `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`, at least 15 points above the handoff share.
94
- - 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.
95
- - `/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.
96
-
97
- 0.8.0, to update together with core 0.7.0:
98
- - `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`).
99
- - `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.
100
- - `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).
101
- - 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.
102
- - `run` refuses an id that is not a slug before it names a lock file or builds the agent's command line.
103
- - 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.
104
-
105
- 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.
106
-
107
- 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.
108
-
109
- 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.
110
-
111
- 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.
112
-
113
- To remove the extension:
114
-
115
- ```bash
116
- ai-factory extension remove gcf-harness-aif-ext
117
- ```
118
-
119
- 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.
120
-
121
- ## What it adds
122
-
123
- **`/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.
124
-
125
- **`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.
126
-
127
- **`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 with their `node_modules` (a `node_modules/` line in `.gitignore` drops the core's `yaml` and `cnlp-kit`, and `ai-factory gcf` fails in the worktree) and `.claude/` (skills, the readset-guard hook) in git, or the session has no `/gcf-run` and no `ai-factory gcf`. On Windows a project in a deep folder needs `git config core.longpaths true`, or `git worktree add` fails on `Filename too long`.
128
-
129
- **`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.
130
-
131
- **`/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.
132
-
133
- **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.
134
-
135
- **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.
136
-
137
- ## Docs
138
-
139
- [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.
140
-
141
- ## License
142
-
143
- MIT
1
+ # gcf-harness-aif-ext
2
+
3
+ Claude-Code-specific orchestration for the [Game Context Framework](../gcf-aif-ext). Optional: GCF works without it, by hand.
4
+
5
+ > **Claude Code only.** Codex and the other AI Factory runtimes are not supported: the harness is built on Claude Code
6
+ > dynamic workflows and `PreToolUse` hooks, which they do not have. AI Factory still copies the `gcf-run` skills into
7
+ > every runtime the project is configured for, where they do not work — on a project without Claude Code, do not
8
+ > install the harness. GCF itself keeps working on any runtime.
9
+
10
+ The harness turns policy-as-text into an executable pipeline. The game's state is on disk in `gcf/` and git, so a run killed at any point restarts and reaches the same state. The runs' own state is in `.gcf-session/`: the agent sessions a rerun resumes, the item worktrees with their uncommitted work, locks and logs. Losing it never breaks the game's model, but it loses those resumes, that work and the diagnosis: delete a single stale file, never the folder.
11
+
12
+ ## Requirements
13
+
14
+ - [`gcf-aif-ext`](../gcf-aif-ext) `^0.7.14 || ^0.8.0 || ^0.9.0 || ^0.10.0` installed (the peer range of `package.json`), with a `gcf/` tree in the project — declared as a peer dependency, and `gcf-harness init` refuses when the `gcf` command is not registered
15
+ - Claude Code 2.1.270+ (hooks, dynamic workflows) — the only supported runtime
16
+ - AI Factory 2.x, Node.js ≥ 22.14
17
+
18
+ ## Install
19
+
20
+ 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.
21
+
22
+ By hand, into a project that already has the core, from npm or a local checkout:
23
+
24
+ ```bash
25
+ ai-factory extension add gcf-aif-ext # the core, if not yet installed
26
+ ai-factory extension add gcf-harness-aif-ext # npm
27
+ # ai-factory extension add ../GCF/packages/gcf-harness-aif-ext # local checkout
28
+ ```
29
+
30
+ 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:
31
+
32
+ ```bash
33
+ ai-factory gcf-harness init # per project: .claude/settings.json + .gitignore
34
+ ```
35
+
36
+ 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.
37
+
38
+ ## Upgrade
39
+
40
+ ```bash
41
+ ai-factory extension update gcf-harness-aif-ext
42
+ ```
43
+
44
+ Updating keeps the hook entry valid — it points into the extension's install directory, which an update refreshes in place.
45
+
46
+ 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.
47
+
48
+ 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.
49
+
50
+ 0.13.0 keeps its past runs for the board (docs/Board-V2-Data-Plan.md) and needs gcf-aif-ext 0.13.0 for the moves' `GCF-By`. `run-log.csv` lines get six columns at their end (`run_id, started, model, effort, log_from, log_to`; older lines still read); `ai-factory gcf-harness runs [--item <id>] [--limit <n>] --json` lists the runs; `run --model <m> --effort <e>` runs every item on another model for that run only, the item unchanged; a run sets `GCF_MOVE_BY=run` for its core calls and its agents.
51
+
52
+ 0.12.2 reads an item as it starts it: in a main-mode batch, an item the run has yet to reach takes a model or effort set meanwhile (`ai-factory gcf item agent`, core 0.12.3; a worktree run locks its items first). A stored `default` gives no `--model` or `--effort` flag.
53
+
54
+ 0.12.0 moves the session mechanics into the bundled session engine `gcf-session` (docs/Session-Engine.md) and needs gcf-aif-ext 0.12.0: a core without neutral rules (`agent.rules`) is refused before any item is claimed. The hooks keep their files and matchers: no new `init` is needed.
55
+ - **The usage limit waits.** A session cut by the limit with a known reset waits for it (plus 60 s) and goes on in the same session. Before the wait its record is written (`<id>.agent.json`, `ended: limit`, `resets` as ISO), so a run killed meanwhile resumes the same session; the chat gets `limit {until}`; the wait does not count against `--timeout`; `gcf-harness stop` ends it. It does not wait for the week's limit, an unknown reset, a reset over 6 h away, an item's third limit in a run, or a lessons turn: those end `paused` as before. `--wait-limit` (a queued start from the board) also holds each session while a known reset is ahead. `--json` says `limit_wait: true`.
56
+ - **Owners.** The handoff flag and the readset manifest name their owner and item: the guards act only on that session, so a project chat or an interactive claude in the same folder goes on. The guards are each a neutral decision and a claude shim, with the same files and input as before.
57
+ - **Milestones from what the work left:** the DoD's `ok` comes from the item's row of main's `gcf/.metrics/verify-log.csv` between the call and its result (`null` with none or two), a commit's from the new HEAD; a worktree's move is main's to record.
58
+ - A background subagent keeps the session open with no timer and no default answer (`background`, then `working`); the context window is known from the first turn (the live `modelUsage`), and the chat shows the share during a turn (`context`).
59
+ - `GCF_SESSION_AGENT` puts another agent in place of `claude` (tests); `GCF_RUN_AGENT` still works.
60
+
61
+ 0.11.1 reworks the chat (docs/Chat-Plan.md) and needs gcf-aif-ext 0.11.1 for its settings (an older core gives the defaults):
62
+ - `chat:` of `gcf/config.yml` decides who waits for whom: `ask` (`d1` by default: only the human's decisions by a question card; `all`; `none`: each card is denied, the agent decides) goes to the skill as `/gcf-run <id> --ask d1|all`; `answer_timeout_min` (15) is how long a question waits, 0 when nobody watches (then `ask` is `none`). `--chat-timeout` has no default any more: it overrides the setting for one run, 0 allowed.
63
+ - `ai-factory gcf-harness chat <id> say [text] [--text-file <path|->] [--image <path>]…`, `answer <request_id> [text] [--answers-file <path|->]`, `interrupt` writes the operator's input: checked (text up to 64 000 characters, up to 10 png/jpg/gif/webp pictures of 5 MB each, an answer to an open card only), never through a link, and only while a live session reads it. Exit 1: bad input; 3: no live chat session; 4: the write failed. A picture is copied into `.gcf-session/runs/<id>.att/`, not git; `chat-in.jsonl` names it by path.
64
+ - `<id>.chat.jsonl` adds the run's milestones from the main agent's tool calls (`step`: the plan converged with its passes, the DoD, the review subagent the skill names `gcf review`, a commit, the item's move; in a worktree the move main recorded), each session's start and end, the handoff flag, the context share at each turn's end, and an `error` for input that reached no one (a dropped card, a missing picture, a message after the item's last session).
65
+ - A turn whose messages the agent never echoed as read frees the session after 10 s with no new turn. After the operator's interrupt the session waits for them with no default answer, while the session's timeout runs on. A session flagged for a handoff closes at its turn's end, as without the chat: no more reminder to hand over. A card a session took with it at its end is dropped.
66
+
67
+ 0.10.0 adds the chat (docs/Chat-Plan.md, stage 1): `run --chat` keeps each agent session open to the operator. The prompt goes in as the session's first stream-json message on stdin. The operator writes into `.gcf-session/runs/<id>.chat-in.jsonl`, one JSON a line: `{"type":"say","text":…,"images":[{media_type,data}]}`, `{"type":"interrupt"}` (stops the agent's step, the session stays), `{"type":"answer","request_id":…,"answers":{…}}` (a question card). What the operator reads goes to `<id>.chat.jsonl`: the agent's text, each message sent and when the agent read it, question cards and their answers, the end of each turn. A question waits `--chat-timeout` minutes (15 by default), and the session's own timeout stands still meanwhile; then the run answers: the card's recommended option, or `take your safe default, or block the item`. A turn that ends without the item's move waits the same way, once. Without `--chat` nothing changes. A session flagged for a handoff closes once it went on past its flag, and the fresh one takes the chat on; flagged on its turn's last message, it is first told to hand over. A message sent while a question card is open leaves the card its timeout. `--chat` adds `claude`'s stream-json flags to the agent's command: another `--agent` must take them. Any other tool approval the agent asks for is denied: the run's permissions decide. Checked live with `claude` (Haiku): the prompt on stdin, an interrupt, the operator's message, the item blocked, the session closed.
68
+
69
+ 0.9.10 makes a main run's session marks its own (with core 0.10.2): the run sets `GCF_RUN_OWNER=run:<pid>`, its core calls and every agent session it starts (a fresh one after a handoff too) inherit it, and the core refuses the mark to anyone else. An item another session has claimed is refused with `worked by another agent session`. `/gcf-run` reports a refused claim and goes on with the next item; it never releases another session's mark, and neither does the run (`gcf-harness stop` still does: that is the human's). The readset-guard hook keeps only its own session's marks fresh (and marks that name nobody), so another session's mark expires when that session stops.
70
+
71
+ 0.9.9 changes no code: its peer range adds core 0.10.0, whose board read is schema 3 and names this harness as the domain's runner (the harness reads neither).
72
+
73
+ 0.9.8 changes no code: its peer range adds core 0.9.0, whose board read is schema 2 (the harness does not read it).
74
+
75
+ 0.9.6 (with core 0.7.14, now the peer range): `/gcf-run-ingest` hands its workflow the sections with their bodies, gets the same delta again after a failed run and ends the import with `gcf anchor --done`; it takes the text of a changed section as `/gcf-ingest` does, and adds resources, entities and measurable constraints by the sequential pass. The workflow marks the GDD as data in every prompt and asks a lens's D2 as a D1. `/gcf-run` reads only `INDEX.md` and `config.yml` beyond the readset, hands fresh subagents the context's graveyard and D2 lines, counts a re-verify after review against `dod_attempts`, files a D1 for a design question on main, never widens the readset by a false `depends:`, and runs in Claude Code only.
76
+
77
+ 0.9.5: `gcf-harness metrics` also sums the cost per item over all its runs and per day and week (`items`, `by_day`, `by_week` in `--json`, a `weeks:` line in the text); `gcf-board` 0.2.18 shows them in its Metrics tab. A resumed session's cost no longer counts twice: `claude` reports a resumed session's whole dollar total, so the lessons turn and a rerun after a limit or a cut now count from what the session had already spent (it is kept in `<id>.agent.json`); before, a lessons turn added its session's cost again. The `done in …` line of the log still shows claude's own figure. A core refusal reads as its whole message: a failed `git worktree add` names its cause, not only git's first line.
78
+
79
+ 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.
80
+
81
+ 0.9.2 holds `/gcf-run` to aif-implement. Run `ai-factory gcf-harness init` again after the update: it registers the new hook.
82
+ - 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.
83
+ - `/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.
84
+ - `/gcf-run` answers aif-plan's own questions (tests, logging, docs) itself, from the item, its DoD and the project's rules.
85
+ - 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.
86
+ - 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.
87
+
88
+ 0.9.1 is a fix release:
89
+ - 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).
90
+ - `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.
91
+ - A stop that comes while the session starts no longer misses it.
92
+
93
+ 0.9.0, to update together with core 0.7.6:
94
+ - 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>`.
95
+ - 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.
96
+ - 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`.
97
+ - `auto_compact_pct` sets the agent's `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`, at least 15 points above the handoff share.
98
+ - 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.
99
+ - `/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.
100
+
101
+ 0.8.0, to update together with core 0.7.0:
102
+ - `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`).
103
+ - `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.
104
+ - `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).
105
+ - 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.
106
+ - `run` refuses an id that is not a slug before it names a lock file or builds the agent's command line.
107
+ - 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.
108
+
109
+ 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.
110
+
111
+ 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.
112
+
113
+ 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.
114
+
115
+ 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.
116
+
117
+ To remove the extension:
118
+
119
+ ```bash
120
+ ai-factory extension remove gcf-harness-aif-ext
121
+ ```
122
+
123
+ 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.
124
+
125
+ ## What it adds
126
+
127
+ **`/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.
128
+
129
+ **`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.
130
+
131
+ **`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, what it ran on (`model`, `effort`; null: the agent's own) and `log: {from, to}`, the bytes of its log this run wrote. `--model <m>` and `--effort <e>` set the model and effort of every item for this run only, over the item's own `model:` and `effort:` (`default` or none: the item's); the item file is not changed. A run sets `GCF_MOVE_BY=run` for its core calls and every agent it starts, in either mode, so the core's moves name the run as their maker. 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 with their `node_modules` (a `node_modules/` line in `.gitignore` drops the core's `yaml` and `cnlp-kit`, and `ai-factory gcf` fails in the worktree) and `.claude/` (skills, the readset-guard hook) in git, or the session has no `/gcf-run` and no `ai-factory gcf`. On Windows a project in a deep folder needs `git config core.longpaths true`, or `git worktree add` fails on `Filename too long`.
132
+
133
+ **`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`: `at, item, mode, result, reason, cost_usd, input, output, cache_read, turns, duration_ms, handoffs, process, run_id, started, model, effort, log_from, log_to`; `result` is `submit`, `close`, `block`, `error`, `conflict`, `skipped`, `paused` for the usage limit, `no-result` for a session cut short, `not-started`; `run_id` is `<started>-<pid>` of the run; `model` and `effort` what the item ran on, empty for the agent's own; `log_from`, `log_to` the bytes of `.gcf-session/runs/<id>.log` this run wrote; older lines end at `process`), `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.
134
+
135
+ **`ai-factory gcf-harness runs [--item <id>] [--limit <n>] [--json]`** — the past runs in `run-log.csv`, the latest first, at most `--limit` (50 by default); `--item` keeps the runs that hold that item. `--json` gives `{runs: [{id, started, ended, mode, cost_usd, items: [{id, result, reason, cost_usd, tokens: {input, output, cache_read}, turns, duration_ms, handoffs, process, model, effort, log: {from, to} | null}]}]}`. A run's lines share its `run_id`; a line older than it is grouped by its `at` (all lines of one run share it), with `id` and `started` null and `log` null (the whole log). Known limits: two such older runs that ended in the same millisecond read as one; a reason's commas read as `;` (the csv turns them so). A run that fails as a whole (its gate refused it, an error of `run` itself) or whose process was killed leaves no lines, so it is not listed. A stop (`gcf-harness stop`, the board's Stop) ends only the item's session: the run writes its line, `no-result` with reason `stopped`; a stop while the session waits for the usage limit's reset writes `paused` with `usage limit; resets <when>; stopped during the wait`.
136
+
137
+ **`/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.
138
+
139
+ **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.
140
+
141
+ **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.
142
+
143
+ ## Docs
144
+
145
+ [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.
146
+
147
+ ## License
148
+
149
+ MIT
@@ -8,7 +8,7 @@ import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
8
8
  import { spawnSync } from 'node:child_process';
9
9
  import path from 'node:path';
10
10
  import { fileURLToPath } from 'node:url';
11
- import { metricsCommand } from './metrics.js';
11
+ import { metricsCommand, runsCommand } from './metrics.js';
12
12
  import { run, cliCore, DEFAULT_AGENT, DEFAULT_TIMEOUT_MIN, MAIN_RUN, stopOf } from './run.js';
13
13
  import { CHAT_TIMEOUT_MIN, ChatRefusal, alive, chatInput, killTree, readText } from 'gcf-session';
14
14
 
@@ -366,6 +366,13 @@ export function register(program) {
366
366
  .option('--since <date>', 'only lines at or after this ISO date or time')
367
367
  .option('--json', 'machine output')
368
368
  .action(metricsCommand);
369
+ harness
370
+ .command('runs')
371
+ .description('Past runs from gcf/.metrics/run-log.csv, the latest first: items, results, cost')
372
+ .option('--item <id>', 'only the runs that hold this item')
373
+ .option('--limit <n>', 'at most this many runs', '50')
374
+ .option('--json', 'machine output: {runs: [...]}')
375
+ .action(runsCommand);
369
376
  harness
370
377
  .command('stop <id>')
371
378
  .description('Stop the session that works an item; the run goes on, the item stays ready')
@@ -403,6 +410,12 @@ function registerRun(harness) {
403
410
  'how long a chat question waits for the operator (default: chat.answer_timeout_min of ' +
404
411
  `gcf/config.yml, else ${CHAT_TIMEOUT_MIN}; 0: nobody watches)`,
405
412
  )
413
+ .option(
414
+ '--model <model>',
415
+ "this run's model for every item, over the item's own (default: the item's); the item " +
416
+ 'file is not changed',
417
+ )
418
+ .option('--effort <effort>', "this run's effort for every item, as --model")
406
419
  .option('--json', 'machine output')
407
420
  .action(runItems);
408
421
  }
@@ -534,6 +547,8 @@ async function runItems(ids, opts) {
534
547
  fresh: Boolean(opts.fresh),
535
548
  waitLimit: Boolean(opts.waitLimit),
536
549
  chat: opts.chat ? { answerMin: answer } : null,
550
+ model: opts.model,
551
+ effort: opts.effort,
537
552
  });
538
553
  if (opts.json) console.log(JSON.stringify(r, null, 2));
539
554
  else printRun(r);
@@ -83,7 +83,7 @@ const UNFINISHED = ['paused', 'no-result', 'not-started'];
83
83
  /** The summary of the logs in `dir`, from `since` on. */
84
84
  export function summarize(dir, since = '') {
85
85
  // run-log: at, item, mode, result, reason, cost_usd, input, output, cache_read, turns,
86
- // duration_ms, handoffs, process
86
+ // duration_ms, handoffs, process (then run_id, started, model, effort, log_from, log_to)
87
87
  const runs = rows(dir, 'run-log.csv', since);
88
88
  const finished = runs.filter((r) => !UNFINISHED.includes(r[3]));
89
89
  const reached = finished.filter((r) => ['submit', 'close'].includes(r[3]));
@@ -183,6 +183,68 @@ export function formatMetrics(s) {
183
183
  ].join('\n');
184
184
  }
185
185
 
186
+ /** An item's line of run-log.csv as a past run shows it (gcf-board `PastRunItem`). */
187
+ const pastItem = (r) => ({
188
+ id: r[1],
189
+ result: r[3],
190
+ reason: r[4] || null,
191
+ cost_usd: num(r[5]),
192
+ tokens: { input: num(r[6]), output: num(r[7]), cache_read: num(r[8]) },
193
+ turns: num(r[9]),
194
+ duration_ms: num(r[10]),
195
+ handoffs: num(r[11]) ?? 0,
196
+ process: r[12] || null,
197
+ model: r[15] || null,
198
+ effort: r[16] || null,
199
+ // A line older than the offsets names none: the whole log is the item's.
200
+ log: r[17] && r[18] ? { from: Number(r[17]), to: Number(r[18]) } : null,
201
+ });
202
+
203
+ /**
204
+ * The past runs in `dir`'s run-log.csv (gcf-board `PastRun`), the latest first, at most `limit`;
205
+ * with `item`, only the runs that hold it. A run's lines share its `run_id`; a line older than
206
+ * it goes by its `at`, the one stamp all lines of a run share.
207
+ * shortcut: two such older runs that ended in the same millisecond read as one.
208
+ * @param {string} dir
209
+ * @param {{item?: string | null, limit?: number}} [o]
210
+ */
211
+ export function pastRuns(dir, { item = null, limit = 50 } = {}) {
212
+ const runs = new Map();
213
+ for (const r of rows(dir, 'run-log.csv', '')) {
214
+ const key = r[13] ? `id ${r[13]}` : `at ${r[0]}`;
215
+ const run = runs.get(key) ?? {
216
+ ...{ id: r[13] || null, started: r[14] || null, ended: r[0], mode: r[2] },
217
+ ...{ cost_usd: null, items: [] },
218
+ };
219
+ const i = pastItem(r);
220
+ run.items.push(i);
221
+ // Cents of many lines add up to float noise.
222
+ if (i.cost_usd !== null)
223
+ run.cost_usd = Math.round(((run.cost_usd ?? 0) + i.cost_usd) * 1e6) / 1e6;
224
+ runs.set(key, run);
225
+ }
226
+
227
+ return [...runs.values()]
228
+ .filter((x) => !item || x.items.some((i) => i.id === item))
229
+ .sort((a, b) => (a.ended < b.ended ? 1 : a.ended > b.ended ? -1 : 0))
230
+ .slice(0, limit);
231
+ }
232
+
233
+ /** The `runs` command: the project's past runs, the latest first. */
234
+ export function runsCommand(o) {
235
+ const limit = Number(o.limit ?? 50);
236
+ if (!Number.isInteger(limit) || limit < 1) throw new Error('--limit is a whole number above 0');
237
+ const runs = pastRuns(metricsDir(process.cwd()), { item: o.item ?? null, limit });
238
+ if (o.json) return console.log(JSON.stringify({ runs }, null, 2));
239
+ const cost = (v) => (v === null ? '' : ` $${v.toFixed(2)}`);
240
+ for (const r of runs)
241
+ console.log(
242
+ `${r.ended} ${r.mode}${cost(r.cost_usd)}: ` +
243
+ r.items.map((i) => `${i.id} ${i.result}`).join(', '),
244
+ );
245
+ if (!runs.length) console.log('no runs');
246
+ }
247
+
186
248
  /** The `metrics` command: the project's logs, from `--since` on. */
187
249
  export function metricsCommand(o) {
188
250
  // The logs stamp UTC: a local date or time is turned into one before the comparison. A bare