gcf-aif-ext 0.7.10 → 0.7.13

package/README.md

@@ -1,216 +1,223 @@
-# gcf-aif-ext
-
-The Game Context Framework as an [AI Factory](https://github.com/lee-to/ai-factory) extension: a documentary layer for building games with an AI agent, where the documents hold **state instead of history**.
-
-A Design Model: the design lives in `gcf/design/<system>.md` as units with typed slots — what the GDD says, quoted and anchored, and `TBD` for everything it does not. Every piece of work — a mechanic, a bug, tech, an asset, a spike, a release — is a work item `gcf/work/<id>.md` with a `type` and a `gate`: who closes it, the human after play (`verdict`), a check (`auto`), or the human without a build (`decision`). A unit taken into work moves into its item with the same body; a soft unit collapses into its subsystem's document on a human playtest verdict and the item ceases to exist. `gcf/LIVE.md` is a short snapshot of what the game is now — capabilities and known issues. `gcf/inbox.md` holds raw input waiting for triage. A history and a graveyard keep how each id ended and why things were killed. Read rules keep the token cost of a task flat as the project ages.
-
-The methodology is [Methodology.md](https://github.com/VirtualMaestro/GCF/blob/main/docs/Methodology.md) (RU).
-
-Runtime-agnostic — everything here works on any AI Factory runtime. The Claude-Code-specific orchestration lives in [`gcf-harness-aif-ext`](../gcf-harness-aif-ext), which is optional.
-
-## Requirements
-
-- AI Factory 2.x
-- Node.js ≥ 22.14
-- git (the enforcement gate is a pre-commit hook)
-
-## Install
-
-Install into an initialized AI Factory project from npm or a local checkout:
-
-```bash
-ai-factory init
-ai-factory extension add gcf-aif-ext                        # npm
-# ai-factory extension add ../GCF/packages/gcf-aif-ext      # local checkout
-```
-
-This installs the 9 skills into each configured runtime, registers the `gcf` command and appends the injections to `aif-plan`, `aif-review` and `aif-commit`. Then set up the project — two steps, run once:
-
-```bash
-ai-factory gcf init            # seeds gcf/, cnlp.config.json and .gitattributes (PILLARS.md is written by /gcf-init)
-ai-factory gcf hooks-install   # arms the pre-commit gate
-```
-
-`gcf init` is idempotent: it creates what is missing and overwrites nothing. Among what it seeds: `gcf/work/` for the work items, `gcf/inbox.md` for raw input, `gcf/LIVE.md` for the project snapshot, `gcf/history.md` and `gcf/graveyard.md` — the two files that record how an id's life ended — and three lines in `.gitattributes` (`gcf/history.md merge=union`, `gcf/graveyard.md merge=union`, `gcf/inbox.md merge=union`) so that two branches appending different lines to those files never conflict there.
-
-It then offers the optional [harness](../gcf-harness-aif-ext) — orchestration and a readset guard for **Claude Code only** — and on yes runs `ai-factory extension add gcf-harness-aif-ext` and `ai-factory gcf-harness init`. It asks only in a terminal and only when `.ai-factory.json` lists the Claude Code agent; an agent or CI run is never asked and installs nothing. `--harness` installs it without asking, `--no-harness` skips the question.
-
-`hooks-install` is a separate step because an AI Factory manifest can declare skills, commands and injections but cannot install a git hook — and because arming a gate that can break your commits is your call, not the extension's. It needs a git repository, and it will not overwrite a `pre-commit` it did not write: if husky or lefthook already owns the hook, it prints the one line to chain from it instead. Without the hook GCF still works; nothing enforces it at commit time.
-
-Then `/gcf-vision` for a brand-new game, `/gcf-adopt` for a project that already has code, `/gcf-ingest <gdd.md>` for an existing design doc, or `/gcf-card` to start work by hand.
-
-## Upgrade
-
-```bash
-ai-factory extension update gcf-aif-ext     # pulls the new version
-ai-factory extension update --force         # refresh even if the version is unchanged
-```
-
-Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook. Run `ai-factory gcf init` again after an update: it adds only what a newer version seeds and the project lacks.
-
-On Windows, run `extension add` and `extension update` from PowerShell or cmd, not Git Bash: the installer unpacks with `tar`, and Git Bash's GNU tar reads `C:\…` as a remote host (`Cannot connect to C: resolve failed`). The Windows `tar.exe` handles it.
-
-### 0.7.10
-
-- Lessons: what got in an agent's way, asked at the end of its session (Methodology §5.2.2). `gcf lessons prompt <id>` prints the questions: tools and their workarounds, project rules that are missing or conflict, trouble with GCF itself, and, with `lessons.template` in `gcf/config.yml`, what the project's template should learn; `lessons.questions` adds the operator's own, `lessons.off: true` turns them off. `gcf lessons add <id>` records each answer as an inbox entry with the source `lesson:<kind>:<item>`; `gcf board --json` gives such an entry `source: lesson`, `kind` and `item`, and each item its `lessons` count. The harness 0.9.2 asks them in a turn of its own after each session, so they stay out of the agent's working context; `/gcf-run` without the harness asks them at its end. `/gcf-triage` proposes a fix for each.
-
-- `gcf verify` kills a `dod.test` or `dod.build` command that runs longer than `dod_timeout_min` minutes (60 by default, 0 for no limit), with every process it started, and fails the DoD: `dod.test timed out after 60 min (dod_timeout_min), killed: <command>`. Before, a hung engine held the check, and a run with it, for hours.
-- `gcf prioritize` takes an item made with `gcf item new` and never committed, and commits it with its rank. Before, it refused the item as an uncommitted file. An item with uncommitted edits is still refused.
-- `gcf playtest session` lists the items awaiting a decision in a section of their own: before, they were missing from the sheet.
-- `plan_passes` defaults to 3 (was 5). A plan converges when an improve pass finds nothing blocking (Methodology §5.2.1); a project that sets `plan_passes` keeps its value.
-
-### 0.7.9
-
-- `gcf done`, `gcf drop` (a design unit), `gcf pillar rename|retire`, `gcf phase next` and `gcf question answer` hold the main lock from their first read to their commit, as the work item moves do. Before, two at once could both pass their checks and write over each other: an answer lost, a unit in the history twice.
-- `gcf claim` says the mark lives 2 hours without a gcf command, as it does (it said 30 minutes).
-
-### 0.7.8
-
-- An open question's field written as a YAML block (`assumed: |` or `>`, and the lines under it) reads as its text: before, `gcf board --json` gave the block sign `|`. Every reader of `gcf/open-questions.md` (the board, `design check`, the audit, `context`, the index) reads the fields the same way:
-  - a field is a line at the record's field indent, so a block line such as `answer: x` is text: before, it made a D1 read as answered;
-  - a blank line inside a block no longer ends the record: before, the fields after it were lost;
-  - `gcf question answer` replaces an old answer written as a block whole: before, it replaced only the block's first line;
-  - an empty `answer:` is no answer: `design check` now holds the D1's units, as the board already showed it unanswered.
-
-### 0.7.7
-
-- `ai-factory gcf config [--json]` lists the human's settings of `gcf/config.yml` with what each means; `gcf config set <key> --value=<v>` sets one, checked by the rules a read applies, the comments kept, one `gcf(config)` commit. An empty number goes back to its default. `gcf board --json` carries them as `settings`.
-- `gcf board --json` questions also carry `assumed`, `until`, `sys`, `lens` and `sections`: a D2 shows what it assumed and when it comes back, and every record where it came from.
-
-### 0.7.6
-
-- `ai-factory gcf permissions [--on <group>] [--off <group>] [--deny <rule>] [--undeny <rule>]` — what agent runs may not do: deny groups and the human's own rules in the `agent:` section of `gcf/config.yml`, one `gcf(permissions)` commit; with no change it lists them. On by default: `git-destroy`, `mass-delete`, `publish`, `human-moves`, `guards`; off: `secrets`, `outside`, `processes`. `agent.groups` keeps only the human's choices (`secrets: true`): a group it does not name keeps its default, so one a later version adds comes on. `git push` is in none. `gcf board --json` carries `agent` (`groups`, `deny_extra`, the resolved `deny`, `allow`).
-- New `config.yml` keys for harness runs: `context_handoff_pct` (60; 0 turns the handoff off), `context_window` (0: the model's) and `auto_compact_pct` (0: the agent's default; at least the handoff share + 15). `gcf board --json` carries them as `context`; a kept session that handed over reads `resume: {ended: 'handoff', handoffs}`.
-- The AGENTS.md block tells the agent that the permissions are the human's.
-
-### 0.7.1
-
-- `gcf board --json`: a ready item's worktree with no run lock and no session mark is a run that stopped (a timeout, a stop, a crash), not a run: the item reads `running: false`, `resumable: true`, and keeps its moves; its next run resumes the worktree. An agent session the harness kept (`.gcf-session/runs/<id>.agent.json`) makes a ready item `resumable` too, in either run mode, and shows as `resume: {ended, resets?}` (null without one).
-
-### 0.7.0
-
-- `priority:` on an item: a rank, lower runs sooner. `ai-factory gcf prioritize <id> <id> …` ranks items in that order in one commit; `item new --priority <n>`. `gcf board --json` lists ranked items first and carries `priority`.
-- `ai-factory gcf question answer <q-id> --text="<answer>"` writes the human's answer into its record of `gcf/open-questions.md` and commits. An answered D1 no longer blocks its units; the next agent on the unit puts the answer into its slot (`answer: q-NNN`) and removes the record. `gcf board --json` questions carry `question`, `proposed`, `blocks` and `answer`.
-- `ai-factory gcf claim <id>` / `release <id>`: an agent session working an item in the main checkout marks it running. The session's own `context`, `plan check` and `verify` on the item keep the mark fresh (so do a harness run on main and its readset-guard hook), a move on the item clears it, and 2 hours without either expire it. The board and the audit read it as `running`, so a harness run does not take the item, and the core refuses any move on it but the session's own (`submit`, `close`, `block` with `--claimed`).
-- `prioritize` leaves the rank of a ready item it does not name (a running one): the named items take the free ranks around it.
-- `run_mode: worktree | main` in `gcf/config.yml` (Methodology §7): a project whose agent works through an editor bound to the project folder sets `main`. `gcf board --json` carries it.
-- `/gcf-card` cuts several items along subsystem boundaries, marks two items of one subsystem that change different files `parallel: ok`, ranks them with `prioritize`, and keeps `depends` for real needs only.
-
-### 0.6.0
-
-- `gcf board --json` carries `schema: 1`, the version of its format (Methodology §11 lists every field); a board refuses a version it does not know. New fields: per item `file`, `plan_file`, `log`, `depends`, `milestone`, `tune_count`, `since`, `model`, `effort` and `moves` (what the item takes now by Methodology §4.1, empty while a run drives it); at the top `history` and `graveyard`.
-- `item new --model <m> --effort <e>`: the run of the item uses them (gcf-harness-aif-ext 0.7). One word each.
-- `playtest session --json` and `live check --json` answer JSON: the flag went to the parent command, which printed text.
-- `--commit` on `item new`, `inbox add` and `inbox drop` records the move alone (`gcf(item): <id>`, `gcf(inbox): …`) for a caller with no console, a board. Without it nothing is committed, as before. Inbox lines added earlier without a commit go into the same commit: the inbox is raw input.
-- `inbox add --text=<text>`: a text that starts with a hyphen ("-5 fps on level 3") reads as a flag at every level of ai-factory's commands, `--` included.
-
-### 0.5.3
-
-- `gcf init` restamps an unplayed item frozen by 0.4.0 (the hash of its body alone), so its `live:` is guarded too — only while that `live:` is still the one its close committed. Commit the restamped items it names.
-- While a harness run drives an item (`.gcf-session/runs/<id>.lock` held by a live process), the core refuses any move on it, `/gcf-run` on main included, and `gcf integrate` leaves its branch unmerged; the audit and the board read it as `running`. A lock left by a run that died is taken over. `gcf board --json` reports WIP as `{count, limit, over}`.
-- The audit reads the `until:` of every D2 record in `open-questions.md`: a fired one is a stale until record, and the assumption goes back to the human.
-- `gcf design check` reads the text of an HTML comment in a unit or an item for forbidden words (M4) and numbers (M5); a `gcf:allow` pragma and a tool's marked region are skipped.
-- An unplayed tune or kill keeps a systems-doc line the doc held before the item's close.
-- `gcf playtest session` groups the checklist by subsystem and warns when the build is not of main: the remote's default branch when the clone knows it, else any branch but a detached HEAD or a `work/` one.
-
-### 0.5.2
-
-- Bundles `cnlp-kit` 3.9, so `gcf design check` and the commit gate accept a bullet written in Cyrillic alone.
-- With `cnlp-kit` 3.9 or later, the `AGENTS.md` block between `<!-- gcf:start -->` and `<!-- gcf:end -->` is a marked region that the project's guide profile does not shape: the `custom_sections` entries 0.5.1 asked for are no longer needed. Update the `cnlp-kit` your project runs `npx cnlp check` with.
-
-### 0.5.1
-
-- A provenance record `assumed: q-NNN` must name a record still in `gcf/open-questions.md` (M9). A D2 record lives until its `until:` fires; once the human confirms the value, cite `answer: q-NNN` instead and remove it. After updating, run `ai-factory gcf design check`: every citation of a removed question blocks the commit gate until it is rewritten.
-- An unplayed item's body is frozen, so a word added to the glossary or a removed question is reported there, not blocked.
-- The `AGENTS.md` block has no `##` heading any more: a CNL-P guide is flat. A project that checks `AGENTS.md` with `cnlp check` adds `gcf_context`, `gcf_work`, `gcf_forbidden` and `gcf_skills` to `custom_sections` of its guide profile.
-
-### 0.5.0
-
-The run layer of the methodology. Update both extensions together — `gcf-harness-aif-ext` 0.6.0 requires this core — and run `ai-factory gcf init` to refresh the agent block in `AGENTS.md`. New commands:
-
-- `gcf verify <id>` — the auto-DoD in code: the commit gate's checks, the item's `live:` delta against `LIVE.md`, then `dod.build` and `dod.test`. Fill both in `gcf/config.yml`; an empty one fails, `none` says the project has no such step.
-- `gcf phase` and `gcf phase next [--reason]` — the project phase (prototype → vertical-slice → alpha → beta → release → live), kept as `phase:` in the `LIVE.md` frontmatter, with exit criteria checked in code. `item new` and `take` refuse a type the phase does not take. **A project with no phase yet is in prototype, and a prototype takes no `asset` item**: move the phase on (`gcf phase next --reason "…"`) if your game is past it. A `phases:` list in `config.yml` replaces the set.
-- A release item carries `version:` and `channel:` (`item new <id> --type release --release 1.0.0 --channel steam`); its end writes the `release:` block of `LIVE.md`. `item new --milestone <name>` tags an item.
-- `gcf playtest session [--build]` — the build of main and a checklist per item: what to check, how to get there, what to feel.
-- `gcf worktree <id>`, `gcf verify <id> --mark`, `gcf integrate [<id>…]` — an item in its own worktree, the `GCF-Verified` trailer, the merge into main and the item's move. Every committed move now holds `.gcf-session/main.lock`.
-- `gcf board [--json]` — everything a board shows in one read.
-
-A move that writes `LIVE.md` now refuses a malformed one instead of rewriting it without what it could not read: fix the file by hand in its own commit.
-
-### 0.4.1
-
-A fix release over 0.4.0; update in place. What you may notice:
-
-- An unplayed item's `frozen:` now covers its `live:` delta as well as its body. Items closed by 0.4.0 keep working. `tune`, `kill` and `drop` refuse an unplayed item edited since its close: restore the file first.
-- With `PILLARS.md` present, a mechanic or resource with `pillars: TBD` is not ready to `take`. `gcf pillar rename` and `gcf pillar retire` revise a pillar where units and items cite it.
-- `design check` blocks a `depends:` cycle and an id with two terminal lines (a merge of branches).
-- The commit gate refuses a `LIVE.md` ref into `gcf/` that names no file.
-- `gcf init` writes an agent instructions block into `AGENTS.md` (and into a `CLAUDE.md` that does not import it), between `<!-- gcf:start -->` and `<!-- gcf:end -->`. Any agent session then knows where work lives and which commands own it. Run `gcf init` again after an update to refresh it.
-
-### Upgrading from 0.3.x
-
-0.4.0 replaces the cards with work items and does **not migrate** them. A schema 2 card in `gcf/cards/` is no longer read: while any is left there, the pre-commit gate refuses every commit that touches `gcf/`, and `gcf audit` reports it first. In order:
-
-1. Update both extensions together — `gcf-harness-aif-ext` 0.5.0 requires this core — and run `ai-factory gcf init`: it seeds `gcf/work/`, `gcf/inbox.md`, `gcf/LIVE.md` and the `gcf/inbox.md merge=union` line. Your `config.yml` is kept; the new keys `unplayed_warn_after`, `plan_passes` and `dod_attempts` take their defaults, and `dod.test` / `dod.build` (the project's test and build commands) are yours to fill in.
-2. Re-create each card. A 0.3 card is a mechanic or a resource, which `item new` does not create: put its body back as a `## <id>` section in `gcf/design/<system>.md` with a `- <id>` line in `backlog.md`, commit, and run `ai-factory gcf take <id>`. A card that was `built` then goes `ai-factory gcf submit <id>` (its code is in main already); `tune_count` starts at 0 unless you carry it over by hand.
-3. Delete `gcf/cards/` and commit it with the new items.
-
-What else changes: statuses are `ready`, `awaiting-verdict`, `awaiting-decision`, `blocked`, `parked` and `unplayed` (`proposed` and `tuning` are `ready`, `built` is `awaiting-verdict`); `built_at` is `since`; `submit` replaces the hand flip to `built`; `reopens:` names an ended id and rework gets a new id; a kill or drop of code already in main creates a `remove-<id>` item; graveyard lines carry the type (0.3 lines without it still read); history gains the `decided` event; every item needs a `live:` delta before it ends.
-
-### Upgrading from 0.3.0
-
-0.3.1 is a patch release with no migration step. It changes behavior in these ways:
-
-- the pre-commit gate ignores `gcf/.metrics/`: a `gcf audit` or `gcf context` run no longer makes the next verdict, `take`, `done` or `drop` fail with `gcf/ has changes outside the index`
-- `ai-factory gcf verdict <id> tune` refuses a card at `tune_limit` (`gcf/config.yml`, 3 by default): kill it, or redesign the envelope and reset `tune_count`
-- `gcf audit` reports open questions older than `question_stale_after_commits` (`stale_questions`) and a `PILLARS.md` with more than 7 pillars
-- a card with an unquoted numeric `id:` (YAML reads `id: 2024` as a number) is refused: quote the slug
-- `built_at` is recorded in a follow-up commit after the implementation commit, with that commit's hash
-- the form check is `npx --yes cnlp-kit check`; `npx cnlp check` fails on a machine without a global cnlp-kit, because no npm package is named `cnlp`
-- a GDD with `#` lines inside closed code fences reports a one-time delta on its next re-import: those lines were wrongly read as headings before
-
-### Upgrading from 0.2.x
-
-0.3.0 replaces the candidate backlog with the Design Model: a card is schema 2 (`cards/<id>.md` with a slug id, `type`, `pillars`, no `slug` and no `route`; the gate names the steps for a schema 1 card), and the design lives in `gcf/design/`. In order:
-
-1. `ai-factory extension update` and `ai-factory gcf init` (adds `history.md` and the `.gitattributes` lines).
-2. `ai-factory gcf design migrate` — deterministic, no commit. Each `cand-NNN | …` backlog line becomes a unit: the quote goes to provenance, every slot the line did not carry reads `TBD`, every gap note survives as a `TBD`, the backlog keeps its order, and `cand-NNN` references in `open-questions.md` and `graveyard.md` are rewritten. The keeps and dones of old commit messages are copied into `gcf/history.md` once.
-3. Candidates you already turned into units by hand: `--skip cand-012=tile-placement` drops the line and sends dependencies on it to that unit; `--skip cand-014=take-back+undo-and-clear` does the same for a candidate you split in two. The command prints the dependencies it could not map, the units that look like duplicates of hand-written ones, and the gap notes of skipped candidates to check in their units.
-4. `ai-factory gcf design check`, fix what it reports — typically a digit in a description — and commit.
-
-To remove the extension:
-
-```bash
-ai-factory extension remove gcf-aif-ext
-```
-
-Removal leaves `gcf/` and `cnlp.config.json` in place. It also leaves the pre-commit hook, which calls into the removed extension and will now fail every commit — delete `.git/hooks/pre-commit` (or the chained line) by hand.
-
-## What it adds
-
-**Skills** — `gcf-init`, `gcf-adopt`, `gcf-card` (put work into `gcf/work/`: take units, group them under a feature, or create a non-design item), `gcf-verdict` (verdicts and decisions), `gcf-triage` (inbox entries into items, tunes, units or nothing, with the human approving each), `gcf-audit`, `gcf-vision`, `gcf-debate`, `gcf-ingest`.
-
-**A deterministic core** behind `ai-factory gcf …`:
-
-- work items — `take <ids...> [--feature <id>]`, `item new <id> --type <type>`, `submit`, `close`, `verdict <id> keep|tune|kill`, `decide <id> go|no|wontfix|known|close|continue|kill`, `block`, `unblock`, `drop`, `done`, `where`
-- inbox and snapshot — `inbox [add <text> | drop <in-id>]`, `live`, `live check`
-- runs and play — `context`, `plan check <id>`, `verify <id>`, `playtest`, `playtest session [--build]`, `audit`
-- project phase and board — `phase`, `phase next [--reason]`, `board [--json]` (everything a board shows, in one read)
-- branches — `worktree <id>`, `verify <id> --mark`, `integrate [<id>...]`: a run in its own worktree, the `GCF-Verified` trailer, the merge into main and the move; every committed move holds `.gcf-session/main.lock`
-- design and sources — `design check`, `design export`, `design import`, `design migrate`, `anchor`, `section`, `quotes`, `lint`
-- setup — `init`, `index`, `hooks-install`
-
-Every move of an item makes one commit `gcf(<move>): <id>` with every file it touched — the item, history or graveyard, `LIVE.md`, the systems documents, the parent feature, a removal item, the archived plan. `take`, `item new` and `inbox` do not commit. These are plain Node scripts with no LLM in the loop: the same functions the skills call, the pre-commit gate runs, and the harness gates against.
-
-**A pre-commit gate** that breaks the commit on a schema 2 card left in `gcf/cards/`, an invalid item (an unknown field, a status that is not stored or does not fit its gate or type, a file name that is not its id), a malformed `[until:]` annotation, an edited body of an `unplayed` item, a malformed `gcf/LIVE.md`, a П2 linter finding in a subsystem document, or a blocking design-check finding: a malformed unit or item, a digit in prose, a forbidden synonym, a quote that is not verbatim in its GDD section, a dependency that names no known id, an id living in two places, a backlog out of step with `gcf/design/`. An unfinished unit (`TBD`) never breaks a commit. A unit or item that leaves `gcf/design/` or `gcf/work/` without a move only draws a warning — its reason is lost, but an item still depending on it fails in that same commit. The gate regenerates `gcf/INDEX.md` and stages it for you.
-
-**CNLP profiles and a work item schema** for the documents the agent reads — one profile per unit type, shared by a unit and its item — plus injections into `aif-plan`, `aif-review` and `aif-commit`.
-
-
-## Docs
-
-Full documentation lives in the [repository](https://github.com/VirtualMaestro/GCF): the [Usage Guide](https://github.com/VirtualMaestro/GCF/blob/main/docs/Usage-Guide.md) (RU) for day-to-day work, and [GCF-PRD](https://github.com/VirtualMaestro/GCF/blob/main/docs/GCF-PRD.md) for the spec — principles, data model, lifecycle, enforcement.
-
-## License
-
-MIT
+# gcf-aif-ext
+
+The Game Context Framework as an [AI Factory](https://github.com/lee-to/ai-factory) extension: a documentary layer for building games with an AI agent, where the documents hold **state instead of history**.
+
+A Design Model: the design lives in `gcf/design/<system>.md` as units with typed slots — what the GDD says, quoted and anchored, and `TBD` for everything it does not. Every piece of work — a mechanic, a bug, tech, an asset, a spike, a release — is a work item `gcf/work/<id>.md` with a `type` and a `gate`: who closes it, the human after play (`verdict`), a check (`auto`), or the human without a build (`decision`). A unit taken into work moves into its item with the same body; a soft unit collapses into its subsystem's document on a human playtest verdict and the item ceases to exist. `gcf/LIVE.md` is a short snapshot of what the game is now — capabilities and known issues. `gcf/inbox.md` holds raw input waiting for triage. A history and a graveyard keep how each id ended and why things were killed. Read rules keep the token cost of a task flat as the project ages.
+
+The methodology is [Methodology.md](https://github.com/VirtualMaestro/GCF/blob/main/docs/Methodology.md) (RU).
+
+Runtime-agnostic — everything here works on any AI Factory runtime. The Claude-Code-specific orchestration lives in [`gcf-harness-aif-ext`](../gcf-harness-aif-ext), which is optional.
+
+## Requirements
+
+- AI Factory 2.x
+- Node.js ≥ 22.14
+- git (the enforcement gate is a pre-commit hook)
+
+## Install
+
+Install into an initialized AI Factory project from npm or a local checkout:
+
+```bash
+ai-factory init
+ai-factory extension add gcf-aif-ext                        # npm
+# ai-factory extension add ../GCF/packages/gcf-aif-ext      # local checkout
+```
+
+This installs the 9 skills into each configured runtime, registers the `gcf` command and appends the injections to `aif-plan`, `aif-review` and `aif-commit`. Then set up the project — two steps, run once:
+
+```bash
+ai-factory gcf init            # seeds gcf/, cnlp.config.json and .gitattributes (PILLARS.md is written by /gcf-init)
+ai-factory gcf hooks-install   # arms the pre-commit gate
+```
+
+`gcf init` is idempotent: it creates what is missing and overwrites nothing. Among what it seeds: `gcf/work/` for the work items, `gcf/inbox.md` for raw input, `gcf/LIVE.md` for the project snapshot, `gcf/history.md` and `gcf/graveyard.md` — the two files that record how an id's life ended — and three lines in `.gitattributes` (`gcf/history.md merge=union`, `gcf/graveyard.md merge=union`, `gcf/inbox.md merge=union`) so that two branches appending different lines to those files never conflict there.
+
+It then offers the optional [harness](../gcf-harness-aif-ext) — orchestration and a readset guard for **Claude Code only** — and on yes runs `ai-factory extension add gcf-harness-aif-ext` and `ai-factory gcf-harness init`. It asks only in a terminal and only when `.ai-factory.json` lists the Claude Code agent; an agent or CI run is never asked and installs nothing. `--harness` installs it without asking, `--no-harness` skips the question.
+
+`hooks-install` is a separate step because an AI Factory manifest can declare skills, commands and injections but cannot install a git hook — and because arming a gate that can break your commits is your call, not the extension's. It needs a git repository, and it will not overwrite a `pre-commit` it did not write: if husky or lefthook already owns the hook, it prints the one line to chain from it instead. Without the hook GCF still works; nothing enforces it at commit time.
+
+Then `/gcf-vision` for a brand-new game, `/gcf-adopt` for a project that already has code, `/gcf-ingest <gdd.md>` for an existing design doc, or `/gcf-card` to start work by hand.
+
+## Upgrade
+
+```bash
+ai-factory extension update gcf-aif-ext     # pulls the new version
+ai-factory extension update --force         # refresh even if the version is unchanged
+```
+
+Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook. Run `ai-factory gcf init` again after an update: it adds only what a newer version seeds and the project lacks.
+
+On Windows, run `extension add` and `extension update` from PowerShell or cmd, not Git Bash: the installer unpacks with `tar`, and Git Bash's GNU tar reads `C:\…` as a remote host (`Cannot connect to C: resolve failed`). The Windows `tar.exe` handles it.
+
+### 0.7.13
+
+- `gcf close` and `gcf submit` need a green `gcf verify <id>` of the code as it is now (Methodology §6). A green verify records the hash of the project's code (everything but `gcf/`, `.ai-factory/` and `.gcf-session/`, committed or not) in `.gcf-session/runs/<id>.verified`; committing that code keeps the record valid, any later edit asks for a new verify. Without one the move refuses: `<id>: no green gcf verify on record — run ai-factory gcf verify <id> until it is green; only the human may move it without one (--unverified "<why>")`; a changed code names the files that changed. `--unverified "<why>"` is the operator's way past it, and the reason goes into the move's commit (`gcf(close): <id> (unverified: <why>)`). A feature's close and the integrator's moves (they rest on the `GCF-Verified` trailer) need no record.
+
+- `gcf board --json` gives each item `running_kind` (`run` for a harness run's lock, `session` for a session mark, null), `since_at` (the time of the `since` commit, null when git does not know it) and `waits_for` (a ready item's dependencies the run gate would refuse it on now). New fields: the schema stays 1.
+- Run logs for the harness metrics (Harness-PRD §11): `gcf plan check` appends to `gcf/.metrics/plan-log.csv` (`at, item, ok, problems`), `gcf verify` to `verify-log.csv` (`at, item, ok, failed checks, mark`). A session in a worktree writes them into the main checkout's logs: its own `gcf/.metrics` is thrown away at the merge. `gcf integrate` commits a log that is new to git too.
+
+### 0.7.10
+
+- Lessons: what got in an agent's way, asked at the end of its session (Methodology §5.2.2). `gcf lessons prompt <id>` prints the questions: tools and their workarounds, project rules that are missing or conflict, trouble with GCF itself, and, with `lessons.template` in `gcf/config.yml`, what the project's template should learn; `lessons.questions` adds the operator's own, `lessons.off: true` turns them off. `gcf lessons add <id>` records each answer as an inbox entry with the source `lesson:<kind>:<item>`; `gcf board --json` gives such an entry `source: lesson`, `kind` and `item`, and each item its `lessons` count. The harness 0.9.2 asks them in a turn of its own after each session, so they stay out of the agent's working context; `/gcf-run` without the harness asks them at its end. `/gcf-triage` proposes a fix for each.
+
+- `gcf verify` kills a `dod.test` or `dod.build` command that runs longer than `dod_timeout_min` minutes (60 by default, 0 for no limit), with every process it started, and fails the DoD: `dod.test timed out after 60 min (dod_timeout_min), killed: <command>`. Before, a hung engine held the check, and a run with it, for hours.
+- `gcf prioritize` takes an item made with `gcf item new` and never committed, and commits it with its rank. Before, it refused the item as an uncommitted file. An item with uncommitted edits is still refused.
+- `gcf playtest session` lists the items awaiting a decision in a section of their own: before, they were missing from the sheet.
+- `plan_passes` defaults to 3 (was 5). A plan converges when an improve pass finds nothing blocking (Methodology §5.2.1); a project that sets `plan_passes` keeps its value.
+
+### 0.7.9
+
+- `gcf done`, `gcf drop` (a design unit), `gcf pillar rename|retire`, `gcf phase next` and `gcf question answer` hold the main lock from their first read to their commit, as the work item moves do. Before, two at once could both pass their checks and write over each other: an answer lost, a unit in the history twice.
+- `gcf claim` says the mark lives 2 hours without a gcf command, as it does (it said 30 minutes).
+
+### 0.7.8
+
+- An open question's field written as a YAML block (`assumed: |` or `>`, and the lines under it) reads as its text: before, `gcf board --json` gave the block sign `|`. Every reader of `gcf/open-questions.md` (the board, `design check`, the audit, `context`, the index) reads the fields the same way:
+  - a field is a line at the record's field indent, so a block line such as `answer: x` is text: before, it made a D1 read as answered;
+  - a blank line inside a block no longer ends the record: before, the fields after it were lost;
+  - `gcf question answer` replaces an old answer written as a block whole: before, it replaced only the block's first line;
+  - an empty `answer:` is no answer: `design check` now holds the D1's units, as the board already showed it unanswered.
+
+### 0.7.7
+
+- `ai-factory gcf config [--json]` lists the human's settings of `gcf/config.yml` with what each means; `gcf config set <key> --value=<v>` sets one, checked by the rules a read applies, the comments kept, one `gcf(config)` commit. An empty number goes back to its default. `gcf board --json` carries them as `settings`.
+- `gcf board --json` questions also carry `assumed`, `until`, `sys`, `lens` and `sections`: a D2 shows what it assumed and when it comes back, and every record where it came from.
+
+### 0.7.6
+
+- `ai-factory gcf permissions [--on <group>] [--off <group>] [--deny <rule>] [--undeny <rule>]` — what agent runs may not do: deny groups and the human's own rules in the `agent:` section of `gcf/config.yml`, one `gcf(permissions)` commit; with no change it lists them. On by default: `git-destroy`, `mass-delete`, `publish`, `human-moves`, `guards`; off: `secrets`, `outside`, `processes`. `agent.groups` keeps only the human's choices (`secrets: true`): a group it does not name keeps its default, so one a later version adds comes on. `git push` is in none. `gcf board --json` carries `agent` (`groups`, `deny_extra`, the resolved `deny`, `allow`).
+- New `config.yml` keys for harness runs: `context_handoff_pct` (60; 0 turns the handoff off), `context_window` (0: the model's) and `auto_compact_pct` (0: the agent's default; at least the handoff share + 15). `gcf board --json` carries them as `context`; a kept session that handed over reads `resume: {ended: 'handoff', handoffs}`.
+- The AGENTS.md block tells the agent that the permissions are the human's.
+
+### 0.7.1
+
+- `gcf board --json`: a ready item's worktree with no run lock and no session mark is a run that stopped (a timeout, a stop, a crash), not a run: the item reads `running: false`, `resumable: true`, and keeps its moves; its next run resumes the worktree. An agent session the harness kept (`.gcf-session/runs/<id>.agent.json`) makes a ready item `resumable` too, in either run mode, and shows as `resume: {ended, resets?}` (null without one).
+
+### 0.7.0
+
+- `priority:` on an item: a rank, lower runs sooner. `ai-factory gcf prioritize <id> <id> …` ranks items in that order in one commit; `item new --priority <n>`. `gcf board --json` lists ranked items first and carries `priority`.
+- `ai-factory gcf question answer <q-id> --text="<answer>"` writes the human's answer into its record of `gcf/open-questions.md` and commits. An answered D1 no longer blocks its units; the next agent on the unit puts the answer into its slot (`answer: q-NNN`) and removes the record. `gcf board --json` questions carry `question`, `proposed`, `blocks` and `answer`.
+- `ai-factory gcf claim <id>` / `release <id>`: an agent session working an item in the main checkout marks it running. The session's own `context`, `plan check` and `verify` on the item keep the mark fresh (so do a harness run on main and its readset-guard hook), a move on the item clears it, and 2 hours without either expire it. The board and the audit read it as `running`, so a harness run does not take the item, and the core refuses any move on it but the session's own (`submit`, `close`, `block` with `--claimed`).
+- `prioritize` leaves the rank of a ready item it does not name (a running one): the named items take the free ranks around it.
+- `run_mode: worktree | main` in `gcf/config.yml` (Methodology §7): a project whose agent works through an editor bound to the project folder sets `main`. `gcf board --json` carries it.
+- `/gcf-card` cuts several items along subsystem boundaries, marks two items of one subsystem that change different files `parallel: ok`, ranks them with `prioritize`, and keeps `depends` for real needs only.
+
+### 0.6.0
+
+- `gcf board --json` carries `schema: 1`, the version of its format (Methodology §11 lists every field); a board refuses a version it does not know. New fields: per item `file`, `plan_file`, `log`, `depends`, `milestone`, `tune_count`, `since`, `model`, `effort` and `moves` (what the item takes now by Methodology §4.1, empty while a run drives it); at the top `history` and `graveyard`.
+- `item new --model <m> --effort <e>`: the run of the item uses them (gcf-harness-aif-ext 0.7). One word each.
+- `playtest session --json` and `live check --json` answer JSON: the flag went to the parent command, which printed text.
+- `--commit` on `item new`, `inbox add` and `inbox drop` records the move alone (`gcf(item): <id>`, `gcf(inbox): …`) for a caller with no console, a board. Without it nothing is committed, as before. Inbox lines added earlier without a commit go into the same commit: the inbox is raw input.
+- `inbox add --text=<text>`: a text that starts with a hyphen ("-5 fps on level 3") reads as a flag at every level of ai-factory's commands, `--` included.
+
+### 0.5.3
+
+- `gcf init` restamps an unplayed item frozen by 0.4.0 (the hash of its body alone), so its `live:` is guarded too — only while that `live:` is still the one its close committed. Commit the restamped items it names.
+- While a harness run drives an item (`.gcf-session/runs/<id>.lock` held by a live process), the core refuses any move on it, `/gcf-run` on main included, and `gcf integrate` leaves its branch unmerged; the audit and the board read it as `running`. A lock left by a run that died is taken over. `gcf board --json` reports WIP as `{count, limit, over}`.
+- The audit reads the `until:` of every D2 record in `open-questions.md`: a fired one is a stale until record, and the assumption goes back to the human.
+- `gcf design check` reads the text of an HTML comment in a unit or an item for forbidden words (M4) and numbers (M5); a `gcf:allow` pragma and a tool's marked region are skipped.
+- An unplayed tune or kill keeps a systems-doc line the doc held before the item's close.
+- `gcf playtest session` groups the checklist by subsystem and warns when the build is not of main: the remote's default branch when the clone knows it, else any branch but a detached HEAD or a `work/` one.
+
+### 0.5.2
+
+- Bundles `cnlp-kit` 3.9, so `gcf design check` and the commit gate accept a bullet written in Cyrillic alone.
+- With `cnlp-kit` 3.9 or later, the `AGENTS.md` block between `<!-- gcf:start -->` and `<!-- gcf:end -->` is a marked region that the project's guide profile does not shape: the `custom_sections` entries 0.5.1 asked for are no longer needed. Update the `cnlp-kit` your project runs `npx cnlp check` with.
+
+### 0.5.1
+
+- A provenance record `assumed: q-NNN` must name a record still in `gcf/open-questions.md` (M9). A D2 record lives until its `until:` fires; once the human confirms the value, cite `answer: q-NNN` instead and remove it. After updating, run `ai-factory gcf design check`: every citation of a removed question blocks the commit gate until it is rewritten.
+- An unplayed item's body is frozen, so a word added to the glossary or a removed question is reported there, not blocked.
+- The `AGENTS.md` block has no `##` heading any more: a CNL-P guide is flat. A project that checks `AGENTS.md` with `cnlp check` adds `gcf_context`, `gcf_work`, `gcf_forbidden` and `gcf_skills` to `custom_sections` of its guide profile.
+
+### 0.5.0
+
+The run layer of the methodology. Update both extensions together — `gcf-harness-aif-ext` 0.6.0 requires this core — and run `ai-factory gcf init` to refresh the agent block in `AGENTS.md`. New commands:
+
+- `gcf verify <id>` — the auto-DoD in code: the commit gate's checks, the item's `live:` delta against `LIVE.md`, then `dod.build` and `dod.test`. Fill both in `gcf/config.yml`; an empty one fails, `none` says the project has no such step.
+- `gcf phase` and `gcf phase next [--reason]` — the project phase (prototype → vertical-slice → alpha → beta → release → live), kept as `phase:` in the `LIVE.md` frontmatter, with exit criteria checked in code. `item new` and `take` refuse a type the phase does not take. **A project with no phase yet is in prototype, and a prototype takes no `asset` item**: move the phase on (`gcf phase next --reason "…"`) if your game is past it. A `phases:` list in `config.yml` replaces the set.
+- A release item carries `version:` and `channel:` (`item new <id> --type release --release 1.0.0 --channel steam`); its end writes the `release:` block of `LIVE.md`. `item new --milestone <name>` tags an item.
+- `gcf playtest session [--build]` — the build of main and a checklist per item: what to check, how to get there, what to feel.
+- `gcf worktree <id>`, `gcf verify <id> --mark`, `gcf integrate [<id>…]` — an item in its own worktree, the `GCF-Verified` trailer, the merge into main and the item's move. Every committed move now holds `.gcf-session/main.lock`.
+- `gcf board [--json]` — everything a board shows in one read.
+
+A move that writes `LIVE.md` now refuses a malformed one instead of rewriting it without what it could not read: fix the file by hand in its own commit.
+
+### 0.4.1
+
+A fix release over 0.4.0; update in place. What you may notice:
+
+- An unplayed item's `frozen:` now covers its `live:` delta as well as its body. Items closed by 0.4.0 keep working. `tune`, `kill` and `drop` refuse an unplayed item edited since its close: restore the file first.
+- With `PILLARS.md` present, a mechanic or resource with `pillars: TBD` is not ready to `take`. `gcf pillar rename` and `gcf pillar retire` revise a pillar where units and items cite it.
+- `design check` blocks a `depends:` cycle and an id with two terminal lines (a merge of branches).
+- The commit gate refuses a `LIVE.md` ref into `gcf/` that names no file.
+- `gcf init` writes an agent instructions block into `AGENTS.md` (and into a `CLAUDE.md` that does not import it), between `<!-- gcf:start -->` and `<!-- gcf:end -->`. Any agent session then knows where work lives and which commands own it. Run `gcf init` again after an update to refresh it.
+
+### Upgrading from 0.3.x
+
+0.4.0 replaces the cards with work items and does **not migrate** them. A schema 2 card in `gcf/cards/` is no longer read: while any is left there, the pre-commit gate refuses every commit that touches `gcf/`, and `gcf audit` reports it first. In order:
+
+1. Update both extensions together — `gcf-harness-aif-ext` 0.5.0 requires this core — and run `ai-factory gcf init`: it seeds `gcf/work/`, `gcf/inbox.md`, `gcf/LIVE.md` and the `gcf/inbox.md merge=union` line. Your `config.yml` is kept; the new keys `unplayed_warn_after`, `plan_passes` and `dod_attempts` take their defaults, and `dod.test` / `dod.build` (the project's test and build commands) are yours to fill in.
+2. Re-create each card. A 0.3 card is a mechanic or a resource, which `item new` does not create: put its body back as a `## <id>` section in `gcf/design/<system>.md` with a `- <id>` line in `backlog.md`, commit, and run `ai-factory gcf take <id>`. A card that was `built` then goes `ai-factory gcf verify <id>` and `ai-factory gcf submit <id>` (its code is in main already; since core 0.7.13 `submit` needs that green verify); `tune_count` starts at 0 unless you carry it over by hand.
+3. Delete `gcf/cards/` and commit it with the new items.
+
+What else changes: statuses are `ready`, `awaiting-verdict`, `awaiting-decision`, `blocked`, `parked` and `unplayed` (`proposed` and `tuning` are `ready`, `built` is `awaiting-verdict`); `built_at` is `since`; `submit` replaces the hand flip to `built`; `reopens:` names an ended id and rework gets a new id; a kill or drop of code already in main creates a `remove-<id>` item; graveyard lines carry the type (0.3 lines without it still read); history gains the `decided` event; every item needs a `live:` delta before it ends.
+
+### Upgrading from 0.3.0
+
+0.3.1 is a patch release with no migration step. It changes behavior in these ways:
+
+- the pre-commit gate ignores `gcf/.metrics/`: a `gcf audit` or `gcf context` run no longer makes the next verdict, `take`, `done` or `drop` fail with `gcf/ has changes outside the index`
+- `ai-factory gcf verdict <id> tune` refuses a card at `tune_limit` (`gcf/config.yml`, 3 by default): kill it, or redesign the envelope and reset `tune_count`
+- `gcf audit` reports open questions older than `question_stale_after_commits` (`stale_questions`) and a `PILLARS.md` with more than 7 pillars
+- a card with an unquoted numeric `id:` (YAML reads `id: 2024` as a number) is refused: quote the slug
+- `built_at` is recorded in a follow-up commit after the implementation commit, with that commit's hash
+- the form check is `npx --yes cnlp-kit check`; `npx cnlp check` fails on a machine without a global cnlp-kit, because no npm package is named `cnlp`
+- a GDD with `#` lines inside closed code fences reports a one-time delta on its next re-import: those lines were wrongly read as headings before
+
+### Upgrading from 0.2.x
+
+0.3.0 replaces the candidate backlog with the Design Model: a card is schema 2 (`cards/<id>.md` with a slug id, `type`, `pillars`, no `slug` and no `route`; the gate names the steps for a schema 1 card), and the design lives in `gcf/design/`. In order:
+
+1. `ai-factory extension update` and `ai-factory gcf init` (adds `history.md` and the `.gitattributes` lines).
+2. `ai-factory gcf design migrate` — deterministic, no commit. Each `cand-NNN | …` backlog line becomes a unit: the quote goes to provenance, every slot the line did not carry reads `TBD`, every gap note survives as a `TBD`, the backlog keeps its order, and `cand-NNN` references in `open-questions.md` and `graveyard.md` are rewritten. The keeps and dones of old commit messages are copied into `gcf/history.md` once.
+3. Candidates you already turned into units by hand: `--skip cand-012=tile-placement` drops the line and sends dependencies on it to that unit; `--skip cand-014=take-back+undo-and-clear` does the same for a candidate you split in two. The command prints the dependencies it could not map, the units that look like duplicates of hand-written ones, and the gap notes of skipped candidates to check in their units.
+4. `ai-factory gcf design check`, fix what it reports — typically a digit in a description — and commit.
+
+To remove the extension:
+
+```bash
+ai-factory extension remove gcf-aif-ext
+```
+
+Removal leaves `gcf/` and `cnlp.config.json` in place. It also leaves the pre-commit hook, which calls into the removed extension and will now fail every commit — delete `.git/hooks/pre-commit` (or the chained line) by hand.
+
+## What it adds
+
+**Skills** — `gcf-init`, `gcf-adopt`, `gcf-card` (put work into `gcf/work/`: take units, group them under a feature, or create a non-design item), `gcf-verdict` (verdicts and decisions), `gcf-triage` (inbox entries into items, tunes, units or nothing, with the human approving each), `gcf-audit`, `gcf-vision`, `gcf-debate`, `gcf-ingest`.
+
+**A deterministic core** behind `ai-factory gcf …`:
+
+- work items — `take <ids...> [--feature <id>]`, `item new <id> --type <type>`, `submit`, `close`, `verdict <id> keep|tune|kill`, `decide <id> go|no|wontfix|known|close|continue|kill`, `block`, `unblock`, `drop`, `done`, `where`
+- inbox and snapshot — `inbox [add <text> | drop <in-id>]`, `live`, `live check`
+- runs and play — `context`, `plan check <id>`, `verify <id>`, `playtest`, `playtest session [--build]`, `audit`
+- project phase and board — `phase`, `phase next [--reason]`, `board [--json]` (everything a board shows, in one read)
+- branches — `worktree <id>`, `verify <id> --mark`, `integrate [<id>...]`: a run in its own worktree, the `GCF-Verified` trailer, the merge into main and the move; every committed move holds `.gcf-session/main.lock`
+- design and sources — `design check`, `design export`, `design import`, `design migrate`, `anchor`, `section`, `quotes`, `lint`
+- setup — `init`, `index`, `hooks-install`
+
+Every move of an item makes one commit `gcf(<move>): <id>` with every file it touched — the item, history or graveyard, `LIVE.md`, the systems documents, the parent feature, a removal item, the archived plan. `take`, `item new` and `inbox` do not commit. These are plain Node scripts with no LLM in the loop: the same functions the skills call, the pre-commit gate runs, and the harness gates against.
+
+**A pre-commit gate** that breaks the commit on a schema 2 card left in `gcf/cards/`, an invalid item (an unknown field, a status that is not stored or does not fit its gate or type, a file name that is not its id), a malformed `[until:]` annotation, an edited body of an `unplayed` item, a malformed `gcf/LIVE.md`, a П2 linter finding in a subsystem document, or a blocking design-check finding: a malformed unit or item, a digit in prose, a forbidden synonym, a quote that is not verbatim in its GDD section, a dependency that names no known id, an id living in two places, a backlog out of step with `gcf/design/`. An unfinished unit (`TBD`) never breaks a commit. A unit or item that leaves `gcf/design/` or `gcf/work/` without a move only draws a warning — its reason is lost, but an item still depending on it fails in that same commit. The gate regenerates `gcf/INDEX.md` and stages it for you.
+
+**CNLP profiles and a work item schema** for the documents the agent reads — one profile per unit type, shared by a unit and its item — plus injections into `aif-plan`, `aif-review` and `aif-commit`.
+
+
+## Docs
+
+Full documentation lives in the [repository](https://github.com/VirtualMaestro/GCF): the [Usage Guide](https://github.com/VirtualMaestro/GCF/blob/main/docs/Usage-Guide.md) (RU) for day-to-day work, and [GCF-PRD](https://github.com/VirtualMaestro/GCF/blob/main/docs/GCF-PRD.md) for the spec — principles, data model, lifecycle, enforcement.
+
+## License
+
+MIT

package/commands/gcf.js

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

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-aif-ext",
-  "version": "0.7.10",
+  "version": "0.7.13",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

package/injections/commit-status.md

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

package/lib/board.js

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

package/lib/integrate.js

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

package/lib/metrics.js

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

package/lib/verify-stamp.js

@@ -0,0 +1,102 @@
+// The record of a green `gcf verify` on main (Methodology §6): `close` and `submit` need one for
+// the code as it is now, so a DoD run some other way cannot stand in for it. The record holds
+// the hash of the project's code, not of a commit: committing the verified code keeps it valid,
+// and any edit after the verify (a review's fix) asks for a new one. In a worktree the
+// `GCF-Verified` trailer does this job, and the integrator's moves need no record.
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, readFileSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// Not code: the framework's own files, the plans, the run files. A move or a plan tick there
+// after the verify does not change what the DoD proved.
+const NOT_CODE = ['gcf', '.ai-factory', '.gcf-session'];
+
+const stampFile = (projectDir, id) =>
+  path.join(path.resolve(projectDir), '.gcf-session', 'runs', `${id}.verified`);
+
+const git = (projectDir, args, env = {}) =>
+  spawnSync('git', args, { cwd: projectDir, encoding: 'utf8', env: { ...process.env, ...env } });
+
+/**
+ * The git tree of the project's code as it is on disk, committed or not, new files included
+ * (ignored ones are not); null outside a repository. A git that fails on the code (a file it
+ * cannot read, `core.safecrlf`) throws: a gate that cannot see the code must not let it pass. A
+ * copy of the index keeps git's stat cache, so only changed files are hashed again.
+ */
+export function codeTree(projectDir) {
+  const index = git(projectDir, ['rev-parse', '--git-path', 'index']);
+  if (index.status !== 0) return null;
+  const real = path.resolve(projectDir, index.stdout.trim());
+  const tmp = path.join(os.tmpdir(), `gcf-code-index-${process.pid}-${Date.now()}`);
+  const env = { GIT_INDEX_FILE: tmp };
+  const step = (args) => {
+    const r = git(projectDir, args, env);
+    if (r.status !== 0) throw new Error(`git ${args[0]} on the code failed: ${r.stderr.trim()}`);
+
+    return r.stdout.trim();
+  };
+
+  try {
+    if (existsSync(real)) copyFileSync(real, tmp);
+    step(['add', '-A', '--', '.', ...NOT_CODE.map((p) => `:(exclude)${p}`)]);
+    step(['rm', '-r', '-q', '--cached', '--ignore-unmatch', '--', ...NOT_CODE]);
+
+    return step(['write-tree']);
+  } finally {
+    rmSync(tmp, { force: true });
+  }
+}
+
+/** Record a green verify of the code as it is now. */
+export function stampVerified(projectDir, id) {
+  const tree = codeTree(projectDir);
+  if (!tree) return;
+  const file = stampFile(projectDir, id);
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({ tree, at: new Date().toISOString() })}\n`);
+}
+
+/** A move ended the item's work: its record goes with it. */
+export const dropStamp = (projectDir, id) => rmSync(stampFile(projectDir, id), { force: true });
+
+/** The files that differ between two trees, the first few, for a refusal to name. */
+function changed(projectDir, from, to) {
+  const r = git(projectDir, ['diff-tree', '-r', '--name-only', from, to]);
+  const files = r.status === 0 ? r.stdout.split('\n').filter(Boolean) : [];
+  const more = files.length > 5 ? ` and ${files.length - 5} more` : '';
+
+  return files.length ? ` (${files.slice(0, 5).join(', ')}${more})` : '';
+}
+
+/**
+ * Why `close` or `submit` may not take the item now, or null: no green verify on record, or
+ * the code changed since. A feature closes over its children and has no code of its own. The
+ * way past it is named as the human's: an agent reads this text.
+ */
+export function unverifiedProblem(projectDir, id, type) {
+  if (type === 'feature') return null;
+  const tree = codeTree(projectDir);
+  if (!tree) return null;
+  const how =
+    `run ai-factory gcf verify ${id} until it is green; only the human may move it without ` +
+    'one (--unverified "<why>")';
+  const stamp = readStamp(projectDir, id);
+  if (!stamp) return `${id}: no green gcf verify on record — ${how}`;
+  if (stamp.tree !== tree) {
+    const files = changed(projectDir, stamp.tree, tree);
+
+    return `${id}: the code changed since its green gcf verify${files} — ${how}`;
+  }
+
+  return null;
+}
+
+/** @returns {{tree: string, at: string} | null} the record, or null when there is none. */
+function readStamp(projectDir, id) {
+  try {
+    return JSON.parse(readFileSync(stampFile(projectDir, id), 'utf8'));
+  } catch {
+    return null;
+  }
+}

package/lib/work-ops.js

@@ -39,6 +39,7 @@ import { dropInbox } from './inbox.js';
 import { refuseByPhase } from './phase.js';
 import { locked, runHolder } from './main-lock.js';
 import { dropAgentSession, releaseSession, sessionActive } from './session-mark.js';
+import { dropStamp, unverifiedProblem } from './verify-stamp.js';
 
 /**
  * Options of a committed move; each move reads the ones it needs.
@@ -232,10 +233,38 @@ async function finish(m, move, tail, commit) {
   // and no rerun resumes it.
   releaseSession(m.projectDir, String(m.item.data.id));
   dropAgentSession(m.projectDir, String(m.item.data.id));
+  dropStamp(m.projectDir, String(m.item.data.id));
 
   return hash;
 }
 
+/**
+ * `close` and `submit` from a command (Methodology §6): the code as it is now needs a green
+ * `gcf verify`, unless the operator says why not (`unverified`, written into the move's
+ * commit). The integrator's moves rest on the branch's trailer instead.
+ */
+function needVerified(m, opts) {
+  if (!opts.requireVerify || opts.unverified) return;
+  const id = String(m.item.data.id);
+  const problem = verifyGateProblem(m.projectDir, id, m.item.data.type);
+  if (problem) throw new Error(problem);
+}
+
+/** The verify gate's refusal, or null; a git that cannot hash the code refuses too. */
+function verifyGateProblem(projectDir, id, type) {
+  try {
+    return unverifiedProblem(projectDir, id, type);
+  } catch (e) {
+    return (
+      `${id}: cannot hash the code for the verify gate (${e.message}) — fix that, or the ` +
+      'human passes --unverified "<why>"'
+    );
+  }
+}
+
+/** The commit's tail of a move made without a green verify. */
+const unverifiedTail = (opts) => (opts.unverified ? ` (unverified: ${opts.unverified})` : '');
+
 const writeItem = (item, data, body = item.body) => atomicWrite(item.file, serialize(data, body));
 
 /** `data` without the keys named — a field that no longer applies leaves the frontmatter. */
@@ -481,11 +510,12 @@ async function submitItemUnlocked(projectDir, id, opts = {}) {
   if (m.item.data.gate === 'auto')
     throw new Error(`${id} has gate auto: nobody waits for it — close it with gcf close ${id}`);
   refuseOpenDepends(m, 'submit', { waiting: true });
+  needVerified(m, opts);
   const status = m.item.data.gate === 'verdict' ? 'awaiting-verdict' : 'awaiting-decision';
   const data = { ...without(m.item.data, 'blocked'), status, since: headHash(projectDir) };
   m.step(() => writeItem(m.item, data));
 
-  return { id, status, hash: await finish(m, 'submit', id, commit) };
+  return { id, status, hash: await finish(m, 'submit', `${id}${unverifiedTail(opts)}`, commit) };
 }
 
 /** Why a soft gate-auto item cannot close unplayed, or null: only an `added` comes back out. */
@@ -556,11 +586,13 @@ async function closeItemUnlocked(projectDir, id, opts = {}) {
     if (m.item.data.gate !== 'auto')
       throw new Error(`${id} has gate ${m.item.data.gate}: submit it, the operator closes it`);
     refuseOpenDepends(m, 'close');
+    needVerified(m, opts);
     if (unplayed) closeUnplayed(m);
     else await closeEnding(m, constraints);
   }
 
-  const hash = await finish(m, 'close', `${id}${unplayed ? ' → unplayed' : ''}`, commit);
+  const tail = `${id}${unplayed ? ' → unplayed' : ''}${unverifiedTail(opts)}`;
+  const hash = await finish(m, 'close', tail, commit);
 
   return { id, hash, unplayed };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-aif-ext",
-  "version": "0.7.10",
+  "version": "0.7.13",
   "description": "Game Context Framework for AI Factory",
   "type": "module",
   "license": "MIT",

package/templates/agents-block.md

@@ -1,40 +1,42 @@
-gcf_context:
-- the game's design and its work live in `gcf/`, and the `ai-factory gcf` commands and the gcf skills change them
-- read `gcf/INDEX.md` before anything else under `gcf/`: it lists every subsystem, design unit and work item
-- `gcf/LIVE.md` says what the game does now, and `gcf/PILLARS.md` says what it must stay
-- `ai-factory gcf board --json` gives the whole state in one read: the phase, the items by status with plan progress, the inbox and the open questions
-
-gcf_work:
-- every piece of work is one work item `gcf/work/<id>.md`: find the item before writing code for a feature, a bug or a tech task, or create it with the gcf-card skill
-- a raw idea, a playtest note or a CI finding that is not work yet goes to `ai-factory gcf inbox add "<text>"`, and the gcf-triage skill sorts it later; a text that starts with a hyphen goes as `inbox add --text="<text>"`
-- before planning an item, run `ai-factory gcf context <id>` and read only the files it lists under `gcf/`
-- drive a ready item with the gcf-run skill when the project has gcf-harness-aif-ext (a batch at once: `ai-factory gcf-harness run <ids...>`), otherwise with aif-plan and aif-implement
-- after the code, write the item's `live:` delta and run `ai-factory gcf verify <id>`: fix what it reports and run it again until every check is green
-- then end the work on the item with its command: `ai-factory gcf submit <id>` for gate verdict or decision, `ai-factory gcf close <id>` for gate auto
-- work that cannot go on: run `ai-factory gcf block <id> --reason "<why or the question>"`
-- in a worktree on branch `work/<id>` change no `gcf/` file but the item's `live:`, commit all, then run `ai-factory gcf verify <id> --mark`: `ai-factory gcf integrate` in the main checkout merges it and records the move
-- a design question only the human can answer becomes a D1 record in `gcf/open-questions.md`
-- a word added to a `not:` of `gcf/glossary.md` leaves `gcf/design/` and every item but an unplayed one in the same commit: `ai-factory gcf design check` names each hit as M4
-- the human plays from `ai-factory gcf playtest session`; each free note from that play goes to `ai-factory gcf inbox add --source playtest "<note>"`
-- a release item carries `version:` and `channel:` (`item new <id> --type release --release <v> --channel <c>`): its end writes the `release:` block of `gcf/LIVE.md`
-- `item new` and `take` refuse a type the current phase does not take: run `ai-factory gcf phase` and bring the refusal to the human
-- an item the human wants run on a given model or effort gets `item new <id> --model <m> --effort <e>`: the harness run passes both to the agent
-- ready items run in `priority:` order, lower first: rank a set of items with `ai-factory gcf prioritize <id> <id> …`, and put an id in `depends` only when the item uses that one's data or code
-- a D1 record that carries the human's `answer:` goes into the slot of each unit it blocks, with `answer: q-NNN`, and then leaves `gcf/open-questions.md`
-- a pillar changes only on the human's word: `ai-factory gcf pillar rename <from> <to>`, or `ai-factory gcf pillar retire <id> --reason "<why>"`
-
-gcf_forbidden:
-- do not edit `status:`, `frozen:`, `gcf/LIVE.md`, `gcf/history.md`, `gcf/graveyard.md` or `gcf/INDEX.md` by hand: the commands own them
-- do not give a verdict or a decision: `verdict` and `decide` belong to the human, through the gcf-verdict skill
-- do not answer a `TBD` of a design unit yourself: ask the human and offer your draft as the proposed answer
-- do not run `ai-factory gcf phase next`: the phase moves on the human's word only
-- do not change what agent runs may do: `ai-factory gcf permissions` and its deny groups belong to the human
-- do not change a setting of `gcf/config.yml`: `ai-factory gcf config set` belongs to the human
-- do not reuse an ended id: rework gets a new id with `reopens: <old id>`
-- do not commit past the gate with `--no-verify`: a refused commit names what to fix
-
-gcf_skills:
-- gcf-vision starts a game that has no design yet, and gcf-ingest imports a GDD into `gcf/design/`
-- gcf-card puts work into `gcf/work/`, and gcf-triage sorts `gcf/inbox.md`
-- gcf-verdict records the human's verdict or decision, and gcf-audit reports the health of `gcf/`
-- gcf-debate stresses the design, gcf-adopt puts existing code on GCF, and gcf-init sets up `gcf/` and revises the pillars
+gcf_context:
+- the game's design and its work live in `gcf/`, and the `ai-factory gcf` commands and the gcf skills change them
+- read `gcf/INDEX.md` before anything else under `gcf/`: it lists every subsystem, design unit and work item
+- `gcf/LIVE.md` says what the game does now, and `gcf/PILLARS.md` says what it must stay
+- `ai-factory gcf board --json` gives the whole state in one read: the phase, the items by status with plan progress, the inbox and the open questions
+
+gcf_work:
+- every piece of work is one work item `gcf/work/<id>.md`: find the item before writing code for a feature, a bug or a tech task, or create it with the gcf-card skill
+- a raw idea, a playtest note or a CI finding that is not work yet goes to `ai-factory gcf inbox add "<text>"`, and the gcf-triage skill sorts it later; a text that starts with a hyphen goes as `inbox add --text="<text>"`
+- before planning an item, run `ai-factory gcf context <id>` and read only the files it lists under `gcf/`
+- drive a ready item with the gcf-run skill when the project has gcf-harness-aif-ext (a batch at once: `ai-factory gcf-harness run <ids...>`), otherwise with aif-plan and aif-implement
+- a question about how the runs go (the share that reached their move, cost, plan checks, DoD attempts, guard firings) is answered by `ai-factory gcf-harness metrics`
+- after the code, write the item's `live:` delta and run `ai-factory gcf verify <id>`: fix what it reports and run it again until every check is green
+- `submit` and `close` refuse code that changed since its last green `gcf verify`: run it again after any fix; `--unverified "<why>"` is the human's call, never the agent's
+- then end the work on the item with its command: `ai-factory gcf submit <id>` for gate verdict or decision, `ai-factory gcf close <id>` for gate auto
+- work that cannot go on: run `ai-factory gcf block <id> --reason "<why or the question>"`
+- in a worktree on branch `work/<id>` change no `gcf/` file but the item's `live:`, commit all, then run `ai-factory gcf verify <id> --mark`: `ai-factory gcf integrate` in the main checkout merges it and records the move
+- a design question only the human can answer becomes a D1 record in `gcf/open-questions.md`
+- a word added to a `not:` of `gcf/glossary.md` leaves `gcf/design/` and every item but an unplayed one in the same commit: `ai-factory gcf design check` names each hit as M4
+- the human plays from `ai-factory gcf playtest session`; each free note from that play goes to `ai-factory gcf inbox add --source playtest "<note>"`
+- a release item carries `version:` and `channel:` (`item new <id> --type release --release <v> --channel <c>`): its end writes the `release:` block of `gcf/LIVE.md`
+- `item new` and `take` refuse a type the current phase does not take: run `ai-factory gcf phase` and bring the refusal to the human
+- an item the human wants run on a given model or effort gets `item new <id> --model <m> --effort <e>`: the harness run passes both to the agent
+- ready items run in `priority:` order, lower first: rank a set of items with `ai-factory gcf prioritize <id> <id> …`, and put an id in `depends` only when the item uses that one's data or code
+- a D1 record that carries the human's `answer:` goes into the slot of each unit it blocks, with `answer: q-NNN`, and then leaves `gcf/open-questions.md`
+- a pillar changes only on the human's word: `ai-factory gcf pillar rename <from> <to>`, or `ai-factory gcf pillar retire <id> --reason "<why>"`
+
+gcf_forbidden:
+- do not edit `status:`, `frozen:`, `gcf/LIVE.md`, `gcf/history.md`, `gcf/graveyard.md` or `gcf/INDEX.md` by hand: the commands own them
+- do not give a verdict or a decision: `verdict` and `decide` belong to the human, through the gcf-verdict skill
+- do not answer a `TBD` of a design unit yourself: ask the human and offer your draft as the proposed answer
+- do not run `ai-factory gcf phase next`: the phase moves on the human's word only
+- do not change what agent runs may do: `ai-factory gcf permissions` and its deny groups belong to the human
+- do not change a setting of `gcf/config.yml`: `ai-factory gcf config set` belongs to the human
+- do not reuse an ended id: rework gets a new id with `reopens: <old id>`
+- do not commit past the gate with `--no-verify`: a refused commit names what to fix
+
+gcf_skills:
+- gcf-vision starts a game that has no design yet, and gcf-ingest imports a GDD into `gcf/design/`
+- gcf-card puts work into `gcf/work/`, and gcf-triage sorts `gcf/inbox.md`
+- gcf-verdict records the human's verdict or decision, and gcf-audit reports the health of `gcf/`
+- gcf-debate stresses the design, gcf-adopt puts existing code on GCF, and gcf-init sets up `gcf/` and revises the pillars