gcf-aif-ext 0.13.0 → 0.14.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,277 +1,285 @@
1
- # gcf-aif-ext
2
-
3
- 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**.
4
-
5
- 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/` holds raw input waiting for triage, one file an entry. 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.
6
-
7
- The methodology is [Methodology.md](https://github.com/VirtualMaestro/GCF/blob/main/docs/Methodology.md) (RU).
8
-
9
- 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.
10
-
11
- ## Requirements
12
-
13
- - AI Factory 2.x
14
- - Node.js ≥ 22.14
15
- - git (the enforcement gate is a pre-commit hook)
16
-
17
- ## Install
18
-
19
- Install into an initialized AI Factory project from npm or a local checkout:
20
-
21
- ```bash
22
- ai-factory init
23
- ai-factory extension add gcf-aif-ext # npm
24
- # ai-factory extension add ../GCF/packages/gcf-aif-ext # local checkout
25
- ```
26
-
27
- 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:
28
-
29
- ```bash
30
- ai-factory gcf init # seeds gcf/, cnlp.config.json and .gitattributes (PILLARS.md is written by /gcf-init)
31
- ai-factory gcf hooks-install # arms the pre-commit gate
32
- ```
33
-
34
- `gcf init` is idempotent: it creates what is missing and overwrites nothing. Among what it seeds: `gcf/work/` for the work items, `gcf/inbox/` for raw input (one file an entry), `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 two lines in `.gitattributes` (`gcf/history.md merge=union`, `gcf/graveyard.md merge=union`) so that two branches appending different lines to those files never conflict there.
35
-
36
- 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.
37
-
38
- `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.
39
-
40
- 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.
41
-
42
- ## Upgrade
43
-
44
- ```bash
45
- ai-factory extension update gcf-aif-ext # pulls the new version
46
- ai-factory extension update --force # refresh even if the version is unchanged
47
- ```
48
-
49
- 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.
50
-
51
- 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.
52
-
53
- ### 0.13.0
54
-
55
- Board v2's data (docs/Board-V2-Data-Plan.md). Update together with gcf-harness-aif-ext 0.13.0 and gcf-board 0.9.0; run `ai-factory gcf init` after it (the AGENTS.md block learns `item history` and `gcf-harness runs`).
56
-
57
- - `ai-factory gcf item history <id> [--json]`: the item's moves from git, newest first, up to 200, an ended item's too: `{id, moves: [{at, commit, move, subject, by}]}` (`at` ISO with offset, `commit` short hash, `move` the domain's move key: `submit`, `verdict:keep`, `decide:go`, `prioritize`, `item-new`, `agent`, `depends`, `integrate`…).
58
- - Every move's commit ends with a trailer paragraph: `GCF-Items: <ids>` (every item and unit it touched: a feature's kill names its live children, a child's death its feature, a removal item the one it made), `GCF-Move: <move key>` and `GCF-By: run|session|operator` (`GCF_MOVE_BY` when set, else `GCF_RUN_OWNER` → run, `CLAUDE_CODE_SESSION_ID` → session, else operator). The integrator's merge and plan commits carry `GCF-Move: integrate`, `verify --mark` `verified`. A commit older than the trailers is read by its subject, `by: null`; the children a feature's old kill took along do not see it.
59
- - `gcf board --json` adds `items[].needs` (its dependencies not ended in history: items on the board, design units, graveyard and unknown ids) and `units[]`, the live design units `{id, title, type, system, file, tbd, blocked_by[], ready}`. The domain's fields get `filter` (type, gate, severity, system, milestone) and `group` (system, parent, milestone); `parent` is `kind: ids`; `needs` follows `needed_by`, both on the card; `depends` has `edit: depends`, and the new item's `depends` is `kind: ids`. `sections.graveyard.match: system`, `sections.units: {label}`. The schema stays 3.
60
-
61
- ### 0.12.0
62
-
63
- Update together with gcf-harness-aif-ext 0.12.0 and gcf-board 0.6.0 (docs/Session-Engine.md).
64
- - `submit` and `close` of an item with a plan refuse while the plan has unticked tasks: `<id>: plan tasks not ticked: N of M — tick what is done, or block the item`. The human passes it with `--unticked "<why>"`, which goes into the commit like `--unverified`. A feature and an item without a plan are not checked; `/gcf-run` ticks the tasks the run did itself (verify, review) before its commit. The integrator is held to it too: `gcf integrate` blocks a merged item whose plan has unticked tasks, with the reason.
65
- - `item new --note=<text>` or `--note-file <path|->` writes what the item's run should know into its `note:`, up to 4000 characters; the board passes it on stdin.
66
- - The board read adds `agent.rules` (every deny rule neutral, `{kind, pattern}`: `shell`, `read`, `edit`…), `domain.chat` (the project chat's skill and the commands it asks for) and `propose` on the `item-new` move. Own deny rules are taken in the neutral form (`shell: curl *`) or claude's (`Bash(curl *)`); `gcf permissions` lists them neutral. The `edit` kind denies MultiEdit and NotebookEdit too, not only Edit and Write.
67
- - The new skill `gcf-chat`: the board's project chat. It answers from `gcf/` and the runs, proposes a new item with the board's MCP tool `propose_item_new` rather than making it, and makes a move only when the human approves its card. A thread bound to an item reads the item's file, plan, run log and run chat first. The AGENTS.md block says the same, and gives the exact form of an item's `live:` delta.
68
- - `gcf context --readset` writes the readset manifest with its owner (the run's `GCF_RUN_OWNER` or the Claude Code session) and item: the guards act only on that session.
69
-
70
- ### 0.11.1
71
-
72
- - The inbox is one file an entry: `gcf/inbox/in-<8 hex>.md` with frontmatter `source`, `at`, `tags` (a lesson also `kind`, `item`) and the text as markdown of any number of lines; its first non-empty line is the title. Pictures go by hand into `gcf/inbox/in-<id>/attachments/`, linked from the text. `inbox add` takes the text one way: an argument, `--text=`, or `--text-file <path|->` (`-` reads stdin; use it for several lines: from cmd.exe the `.cmd` shim cuts an argument at a newline). `gcf inbox` lists `in-x [source] <title> (+N lines) (tags: …)`; `--json` and the board read give `{id, source, at, title, text, tags[], kind?, item?, attachments?}`, sorted by `at`. `inbox tag`, `inbox drop` and `item new --from` refuse on a `work/` branch; `drop` deletes the entry with its pictures. `item new --from` without `--title` takes the entry's title and puts the rest, quoted (`> `), in a `note:` block (with another `--title` the whole text), and moves its pictures to `gcf/work/<id>/attachments/`. No `merge=union` any more: branches add different files, and `gcf integrate` merges an entry a `work/` branch added. The audit reports `inbox: {legacy, bad_names, untitled, broken_links, orphan_dirs}`. An old `gcf/inbox.md` is read by nothing: the audit and `gcf inbox` say so; move its lines with `inbox add` (or by hand) and delete it — there is no migration.
73
- - `chat:` in `gcf/config.yml`: `ask` (`d1` by default, `all`, `none`: what a harness run's agent asks the operator by a question card) and `answer_timeout_min` (15; 0: nobody watches, the default answer goes at once). `gcf config set chat.ask --value=all` and `chat.answer_timeout_min` set them; `gcf board --json` carries `chat`, and a setting of kind `mode` its `options`. gcf-harness-aif-ext 0.11.1 reads them.
74
- - `ai-factory gcf item agent <id> --model <m> --effort <e>` sets the model and effort of an item's runs (`default` takes one off: the agent picks); refused while a run drives the item, committed `gcf(item)`; the item's next run takes them. The board offers it as the item move **model / effort**, and as **change** beside those fields.
75
- - `ai-factory gcf item attach <id> --file <path>` gives an item a file (a chat picture, a reference): copied into `gcf/work/<id>/attachments/` under its own name (`-2`, `-3`… on a clash) and committed alone, `gcf(attach): <id>`, also while the item runs, as long as `gcf/` has no uncommitted changes (a main-mode session edits the item file, and the commit gate then refuses; a worktree run sees the file only in its next run). A link, a file over 10 MB and a `work/` branch are refused. The board offers it as the item move **attach**; the AGENTS.md block tells agents to read an item's attachments.
76
-
77
- ### 0.10.3
78
-
79
- - `gcf audit --json` says who works a running item: `running_by` is `run` (a harness run's lock), `you` (a session mark this session or its harness run owns), `unowned` (a mark that names nobody; a claim takes both), `session` (another session's mark), or null. Before, `running: true` alone left a `/gcf-run` on main to guess whether its own run's mark would refuse its claim.
80
-
81
- ### 0.10.2
82
-
83
- - `gcf claim` is exclusive. The session mark names its owner: `GCF_RUN_OWNER` (a harness run sets it, its agent sessions inherit it), else the Claude Code session's `CLAUDE_CODE_SESSION_ID`. While the mark is fresh, a claim by another owner, or by none, is refused, and so is a `--claimed` move from another owner. A mark that names nobody (written before 0.10.2, or claimed from a console with neither id), a stale one, or one of a harness run whose process is gone holds nobody. Only the owner's own commands on the item keep its mark fresh (a fresh mark that names nobody, any session's), and only the named owner revives a stale one. `gcf release` stays the human's way out, also for a session whose id changed (`/clear`). Update together with gcf-harness-aif-ext 0.9.10: an older harness started from inside a Claude Code session would claim under that session's id, and its own agent would be refused.
84
-
85
- ### 0.10.1
86
-
87
- - `gcf board --json` has `extensions_error`: why `.ai-factory.json` is there but cannot be read (null otherwise). With such a file the board knows no harness and hides its run buttons; gcf-board 0.4.1 says so in its top bar.
88
- - A `depends` cycle through a feature says "a feature waits for its children" only when a step of it is the feature waiting for a child, not when the feature is in it by `depends` alone.
89
-
90
- ### 0.10.0
91
-
92
- - `gcf board --json` is `schema: 3`: `domain` describes the whole GCF domain for a board (Methodology §11, Board-PRD decision 16). It names the harness (`gcf-harness` when the project has gcf-harness-aif-ext, else null), the agent's move `run` (offered first in `items[].moves` to a ready item without a green verify, only with the harness), every move's form with its full `ai-factory` words (`gcf …`) — the new item, the phase, the inbox, the answers, the run order and `depends` included —, the item's fields for the card and the drawer, its blocks (`sections`) and the Help terms. `depends` is offered to every item; `waits_for` is empty while a run drives the item. gcf-board 0.4.0 reads it; update both together.
93
- - `gcf config set language.ui --value=ru` (and `language.artifacts`) sets the agents' language in AI Factory's `.ai-factory/config.yaml`: that key only, its comments kept, one `gcf(config)` commit (an uncommitted file is committed whole; a file git ignores is written, not committed, with a warning). An empty value takes the key off. `gcf config` and the board's settings list them.
94
- - AGENTS.md: agents leave the language to the human. Run `ai-factory gcf init` after the update.
95
-
96
- ### 0.9.0
97
-
98
- - `gcf board --json` is `schema: 2`. The new `domain` field gives the board its columns in order (label, tooltip), the status runs start from, and the form of every item move: label, tooltip, command words, fields, and the drop zone that means it (Methodology §11, Board-PRD decision 16). The `columns` map (status → ids) is gone: filter `items` by `status`. gcf-board reads it from 0.3.0 on; an older board refuses schema 2, and gcf-board 0.3.0 refuses an older core: update both together.
99
-
100
- ### 0.7.14
101
-
102
- - `gcf anchor --json` gives each section its `body`, the text `/gcf-run-ingest` hands its workflow. The delta counts from the last *finished* import: `anchor` holds the map it started from in `gcf/source/<file>.import.json` until `gcf anchor <file> --done`, so an import that died after anchoring reports the same delta again (`resumed`) instead of an empty one. `/gcf-ingest` ends with `--done`.
103
- - Instructions, from an audit of the agents' rules (2026-10-16): the commit injection makes no move on a `work/<id>` branch (verify `--mark`, the integrator moves it); the plan injection allows `gcf/INDEX.md` and `gcf/config.yml` besides the readset and names its graveyard and D2 lines; the review injection checks a feature child's capability against its parent's `live:`.
104
- - Skills: `/gcf-card` puts `--severity` and `--release --channel` on `item new` and writes a bug's `repro:`, and removes an answered D1 only after every unit it blocks has it; `/gcf-triage` leaves a tune note in the inbox until `/gcf-verdict … tune --note` records it; a re-check after a red verify counts against `dod_attempts`; `cnlp-kit check` is named for what it covers. The item template keeps the architecture rule in `constraints:`; the systems profile keeps an `until:` line in its own block.
105
- - Run `ai-factory extension update gcf-aif-ext`: the injections and skills come with it. Update `gcf-harness-aif-ext` to 0.9.6 with it: an older `/gcf-run-ingest` never runs `anchor --done`, so every later import would come back `resumed` with the delta of the first one.
106
-
107
- ### 0.7.13
108
-
109
- - `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.
110
-
111
- - `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.
112
- - 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.
113
-
114
- ### 0.7.10
115
-
116
- - 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.
117
-
118
- - `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.
119
- - `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.
120
- - `gcf playtest session` lists the items awaiting a decision in a section of their own: before, they were missing from the sheet.
121
- - `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.
122
-
123
- ### 0.7.9
124
-
125
- - `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.
126
- - `gcf claim` says the mark lives 2 hours without a gcf command, as it does (it said 30 minutes).
127
-
128
- ### 0.7.8
129
-
130
- - 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:
131
- - 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;
132
- - a blank line inside a block no longer ends the record: before, the fields after it were lost;
133
- - `gcf question answer` replaces an old answer written as a block whole: before, it replaced only the block's first line;
134
- - an empty `answer:` is no answer: `design check` now holds the D1's units, as the board already showed it unanswered.
135
-
136
- ### 0.7.7
137
-
138
- - `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`.
139
- - `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.
140
-
141
- ### 0.7.6
142
-
143
- - `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`).
144
- - 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}`.
145
- - The AGENTS.md block tells the agent that the permissions are the human's.
146
-
147
- ### 0.7.1
148
-
149
- - `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).
150
-
151
- ### 0.7.0
152
-
153
- - `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`.
154
- - `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`.
155
- - `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`). The mark names its owner (`GCF_RUN_OWNER` of a harness run, else `CLAUDE_CODE_SESSION_ID`): another owner's claim and `--claimed` moves are refused while it is fresh.
156
- - `prioritize` leaves the rank of a ready item it does not name (a running one): the named items take the free ranks around it.
157
- - `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.
158
- - `/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.
159
-
160
- ### 0.6.0
161
-
162
- - `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`.
163
- - `item new --model <m> --effort <e>`: the run of the item uses them (gcf-harness-aif-ext 0.7). One word each.
164
- - `playtest session --json` and `live check --json` answer JSON: the flag went to the parent command, which printed text.
165
- - `--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.
166
- - `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.
167
-
168
- ### 0.5.3
169
-
170
- - `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.
171
- - 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}`.
172
- - 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.
173
- - `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.
174
- - An unplayed tune or kill keeps a systems-doc line the doc held before the item's close.
175
- - `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.
176
-
177
- ### 0.5.2
178
-
179
- - Bundles `cnlp-kit` 3.9, so `gcf design check` and the commit gate accept a bullet written in Cyrillic alone.
180
- - 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.
181
-
182
- ### 0.5.1
183
-
184
- - 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.
185
- - An unplayed item's body is frozen, so a word added to the glossary or a removed question is reported there, not blocked.
186
- - 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.
187
-
188
- ### 0.5.0
189
-
190
- 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:
191
-
192
- - `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.
193
- - `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.
194
- - 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.
195
- - `gcf playtest session [--build]` — the build of main and a checklist per item: what to check, how to get there, what to feel.
196
- - `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`.
197
- - `gcf board [--json]` — everything a board shows in one read.
198
-
199
- 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.
200
-
201
- ### 0.4.1
202
-
203
- A fix release over 0.4.0; update in place. What you may notice:
204
-
205
- - 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.
206
- - 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.
207
- - `design check` blocks a `depends:` cycle and an id with two terminal lines (a merge of branches).
208
- - The commit gate refuses a `LIVE.md` ref into `gcf/` that names no file.
209
- - `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.
210
-
211
- ### Upgrading from 0.3.x
212
-
213
- 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:
214
-
215
- 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.
216
- 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.
217
- 3. Delete `gcf/cards/` and commit it with the new items.
218
-
219
- 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.
220
-
221
- ### Upgrading from 0.3.0
222
-
223
- 0.3.1 is a patch release with no migration step. It changes behavior in these ways:
224
-
225
- - 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`
226
- - `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`
227
- - `gcf audit` reports open questions older than `question_stale_after_commits` (`stale_questions`) and a `PILLARS.md` with more than 7 pillars
228
- - a card with an unquoted numeric `id:` (YAML reads `id: 2024` as a number) is refused: quote the slug
229
- - `built_at` is recorded in a follow-up commit after the implementation commit, with that commit's hash
230
- - 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`
231
- - 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
232
-
233
- ### Upgrading from 0.2.x
234
-
235
- 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:
236
-
237
- 1. `ai-factory extension update` and `ai-factory gcf init` (adds `history.md` and the `.gitattributes` lines).
238
- 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.
239
- 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.
240
- 4. `ai-factory gcf design check`, fix what it reports — typically a digit in a description — and commit.
241
-
242
- To remove the extension:
243
-
244
- ```bash
245
- ai-factory extension remove gcf-aif-ext
246
- ```
247
-
248
- 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.
249
-
250
- ## What it adds
251
-
252
- **Skills** — `gcf-init`, `gcf-adopt`, `gcf-chat` (the board's project chat: answers, proposes new items, makes the moves the human approves), `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`.
253
-
254
- **A deterministic core** behind `ai-factory gcf …`:
255
-
256
- - 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`
257
- - inbox and snapshot — `inbox [add <text> | add --text-file <path|-> | tag <in-id> | drop <in-id>]`, `live`, `live check`
258
- - runs and play — `context`, `plan check <id>`, `verify <id>`, `playtest`, `playtest session [--build]`, `audit`
259
- - project phase and board — `phase`, `phase next [--reason]`, `board [--json]` (everything a board shows, in one read)
260
- - 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`
261
- - design and sources — `design check`, `design export`, `design import`, `design migrate`, `anchor`, `section`, `quotes`, `lint`
262
- - setup — `init`, `index`, `hooks-install`
263
-
264
- 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.
265
-
266
- **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.
267
-
268
- **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`.
269
-
270
-
271
- ## Docs
272
-
273
- 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.
274
-
275
- ## License
276
-
277
- MIT
1
+ # gcf-aif-ext
2
+
3
+ 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**.
4
+
5
+ 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/` holds raw input waiting for triage, one file an entry. 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.
6
+
7
+ The methodology is [Methodology.md](https://github.com/VirtualMaestro/GCF/blob/main/docs/Methodology.md) (RU).
8
+
9
+ 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.
10
+
11
+ ## Requirements
12
+
13
+ - AI Factory 2.x
14
+ - Node.js ≥ 22.14
15
+ - git (the enforcement gate is a pre-commit hook)
16
+
17
+ ## Install
18
+
19
+ Install into an initialized AI Factory project from npm or a local checkout:
20
+
21
+ ```bash
22
+ ai-factory init
23
+ ai-factory extension add gcf-aif-ext # npm
24
+ # ai-factory extension add ../GCF/packages/gcf-aif-ext # local checkout
25
+ ```
26
+
27
+ 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:
28
+
29
+ ```bash
30
+ ai-factory gcf init # seeds gcf/, cnlp.config.json and .gitattributes (PILLARS.md is written by /gcf-init)
31
+ ai-factory gcf hooks-install # arms the pre-commit gate
32
+ ```
33
+
34
+ `gcf init` is idempotent: it creates what is missing and overwrites nothing. Among what it seeds: `gcf/work/` for the work items, `gcf/inbox/` for raw input (one file an entry), `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 two lines in `.gitattributes` (`gcf/history.md merge=union`, `gcf/graveyard.md merge=union`) so that two branches appending different lines to those files never conflict there.
35
+
36
+ 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.
37
+
38
+ `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.
39
+
40
+ 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.
41
+
42
+ ## Upgrade
43
+
44
+ ```bash
45
+ ai-factory extension update gcf-aif-ext # pulls the new version
46
+ ai-factory extension update --force # refresh even if the version is unchanged
47
+ ```
48
+
49
+ 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.
50
+
51
+ 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.
52
+
53
+ ### 0.14.0
54
+
55
+ The functional base, part A (docs/Base-A-Plan.md). Update together with gcf-harness-aif-ext 0.14.0 and gcf-board 0.10.0; run `ai-factory gcf init` after it (the AGENTS.md block learns the project's model and `gcf-harness gate --each`).
56
+
57
+ - `session_timeout_min` in `gcf/config.yml` (120): minutes one agent session on an item may run; above 0 (`gcf config set session_timeout_min --value=90`). The harness takes it when `run` has no `--timeout`.
58
+ - `agent.model` and `agent.effort`: what an item or a chat thread without its own runs on (`gcf config set agent.model --value=sonnet`; empty or `default` takes it off). One plain word each, as an item's; a setting of kind `word` with `presets: model|effort` (the board suggests the agent's presets). `gcf board --json` carries them in `agent`, and `session_timeout_min` beside `context`.
59
+ - `gcf board --json` adds `items[].attachments` (the files `gcf item attach` gave it, project paths) and offers no `run` move to a feature (the run gate refuses one).
60
+
61
+ ### 0.13.0
62
+
63
+ Board v2's data (docs/Board-V2-Data-Plan.md). Update together with gcf-harness-aif-ext 0.13.0 and gcf-board 0.9.0; run `ai-factory gcf init` after it (the AGENTS.md block learns `item history` and `gcf-harness runs`).
64
+
65
+ - `ai-factory gcf item history <id> [--json]`: the item's moves from git, newest first, up to 200, an ended item's too: `{id, moves: [{at, commit, move, subject, by}]}` (`at` ISO with offset, `commit` short hash, `move` the domain's move key: `submit`, `verdict:keep`, `decide:go`, `prioritize`, `item-new`, `agent`, `depends`, `integrate`…).
66
+ - Every move's commit ends with a trailer paragraph: `GCF-Items: <ids>` (every item and unit it touched: a feature's kill names its live children, a child's death its feature, a removal item the one it made), `GCF-Move: <move key>` and `GCF-By: run|session|operator` (`GCF_MOVE_BY` when set, else `GCF_RUN_OWNER` → run, `CLAUDE_CODE_SESSION_ID` → session, else operator). The integrator's merge and plan commits carry `GCF-Move: integrate`, `verify --mark` `verified`. A commit older than the trailers is read by its subject, `by: null`; the children a feature's old kill took along do not see it.
67
+ - `gcf board --json` adds `items[].needs` (its dependencies not ended in history: items on the board, design units, graveyard and unknown ids) and `units[]`, the live design units `{id, title, type, system, file, tbd, blocked_by[], ready}`. The domain's fields get `filter` (type, gate, severity, system, milestone) and `group` (system, parent, milestone); `parent` is `kind: ids`; `needs` follows `needed_by`, both on the card; `depends` has `edit: depends`, and the new item's `depends` is `kind: ids`. `sections.graveyard.match: system`, `sections.units: {label}`. The schema stays 3.
68
+
69
+ ### 0.12.0
70
+
71
+ Update together with gcf-harness-aif-ext 0.12.0 and gcf-board 0.6.0 (docs/Session-Engine.md).
72
+ - `submit` and `close` of an item with a plan refuse while the plan has unticked tasks: `<id>: plan tasks not ticked: N of M — tick what is done, or block the item`. The human passes it with `--unticked "<why>"`, which goes into the commit like `--unverified`. A feature and an item without a plan are not checked; `/gcf-run` ticks the tasks the run did itself (verify, review) before its commit. The integrator is held to it too: `gcf integrate` blocks a merged item whose plan has unticked tasks, with the reason.
73
+ - `item new --note=<text>` or `--note-file <path|->` writes what the item's run should know into its `note:`, up to 4000 characters; the board passes it on stdin.
74
+ - The board read adds `agent.rules` (every deny rule neutral, `{kind, pattern}`: `shell`, `read`, `edit`…), `domain.chat` (the project chat's skill and the commands it asks for) and `propose` on the `item-new` move. Own deny rules are taken in the neutral form (`shell: curl *`) or claude's (`Bash(curl *)`); `gcf permissions` lists them neutral. The `edit` kind denies MultiEdit and NotebookEdit too, not only Edit and Write.
75
+ - The new skill `gcf-chat`: the board's project chat. It answers from `gcf/` and the runs, proposes a new item with the board's MCP tool `propose_item_new` rather than making it, and makes a move only when the human approves its card. A thread bound to an item reads the item's file, plan, run log and run chat first. The AGENTS.md block says the same, and gives the exact form of an item's `live:` delta.
76
+ - `gcf context --readset` writes the readset manifest with its owner (the run's `GCF_RUN_OWNER` or the Claude Code session) and item: the guards act only on that session.
77
+
78
+ ### 0.11.1
79
+
80
+ - The inbox is one file an entry: `gcf/inbox/in-<8 hex>.md` with frontmatter `source`, `at`, `tags` (a lesson also `kind`, `item`) and the text as markdown of any number of lines; its first non-empty line is the title. Pictures go by hand into `gcf/inbox/in-<id>/attachments/`, linked from the text. `inbox add` takes the text one way: an argument, `--text=`, or `--text-file <path|->` (`-` reads stdin; use it for several lines: from cmd.exe the `.cmd` shim cuts an argument at a newline). `gcf inbox` lists `in-x [source] <title> (+N lines) (tags: …)`; `--json` and the board read give `{id, source, at, title, text, tags[], kind?, item?, attachments?}`, sorted by `at`. `inbox tag`, `inbox drop` and `item new --from` refuse on a `work/` branch; `drop` deletes the entry with its pictures. `item new --from` without `--title` takes the entry's title and puts the rest, quoted (`> `), in a `note:` block (with another `--title` the whole text), and moves its pictures to `gcf/work/<id>/attachments/`. No `merge=union` any more: branches add different files, and `gcf integrate` merges an entry a `work/` branch added. The audit reports `inbox: {legacy, bad_names, untitled, broken_links, orphan_dirs}`. An old `gcf/inbox.md` is read by nothing: the audit and `gcf inbox` say so; move its lines with `inbox add` (or by hand) and delete it — there is no migration.
81
+ - `chat:` in `gcf/config.yml`: `ask` (`d1` by default, `all`, `none`: what a harness run's agent asks the operator by a question card) and `answer_timeout_min` (15; 0: nobody watches, the default answer goes at once). `gcf config set chat.ask --value=all` and `chat.answer_timeout_min` set them; `gcf board --json` carries `chat`, and a setting of kind `mode` its `options`. gcf-harness-aif-ext 0.11.1 reads them.
82
+ - `ai-factory gcf item agent <id> --model <m> --effort <e>` sets the model and effort of an item's runs (`default` takes one off: the agent picks); refused while a run drives the item, committed `gcf(item)`; the item's next run takes them. The board offers it as the item move **model / effort**, and as **change** beside those fields.
83
+ - `ai-factory gcf item attach <id> --file <path>` gives an item a file (a chat picture, a reference): copied into `gcf/work/<id>/attachments/` under its own name (`-2`, `-3`… on a clash) and committed alone, `gcf(attach): <id>`, also while the item runs, as long as `gcf/` has no uncommitted changes (a main-mode session edits the item file, and the commit gate then refuses; a worktree run sees the file only in its next run). A link, a file over 10 MB and a `work/` branch are refused. The board offers it as the item move **attach**; the AGENTS.md block tells agents to read an item's attachments.
84
+
85
+ ### 0.10.3
86
+
87
+ - `gcf audit --json` says who works a running item: `running_by` is `run` (a harness run's lock), `you` (a session mark this session or its harness run owns), `unowned` (a mark that names nobody; a claim takes both), `session` (another session's mark), or null. Before, `running: true` alone left a `/gcf-run` on main to guess whether its own run's mark would refuse its claim.
88
+
89
+ ### 0.10.2
90
+
91
+ - `gcf claim` is exclusive. The session mark names its owner: `GCF_RUN_OWNER` (a harness run sets it, its agent sessions inherit it), else the Claude Code session's `CLAUDE_CODE_SESSION_ID`. While the mark is fresh, a claim by another owner, or by none, is refused, and so is a `--claimed` move from another owner. A mark that names nobody (written before 0.10.2, or claimed from a console with neither id), a stale one, or one of a harness run whose process is gone holds nobody. Only the owner's own commands on the item keep its mark fresh (a fresh mark that names nobody, any session's), and only the named owner revives a stale one. `gcf release` stays the human's way out, also for a session whose id changed (`/clear`). Update together with gcf-harness-aif-ext 0.9.10: an older harness started from inside a Claude Code session would claim under that session's id, and its own agent would be refused.
92
+
93
+ ### 0.10.1
94
+
95
+ - `gcf board --json` has `extensions_error`: why `.ai-factory.json` is there but cannot be read (null otherwise). With such a file the board knows no harness and hides its run buttons; gcf-board 0.4.1 says so in its top bar.
96
+ - A `depends` cycle through a feature says "a feature waits for its children" only when a step of it is the feature waiting for a child, not when the feature is in it by `depends` alone.
97
+
98
+ ### 0.10.0
99
+
100
+ - `gcf board --json` is `schema: 3`: `domain` describes the whole GCF domain for a board (Methodology §11, Board-PRD decision 16). It names the harness (`gcf-harness` when the project has gcf-harness-aif-ext, else null), the agent's move `run` (offered first in `items[].moves` to a ready item without a green verify, only with the harness), every move's form with its full `ai-factory` words (`gcf …`) — the new item, the phase, the inbox, the answers, the run order and `depends` included —, the item's fields for the card and the drawer, its blocks (`sections`) and the Help terms. `depends` is offered to every item; `waits_for` is empty while a run drives the item. gcf-board 0.4.0 reads it; update both together.
101
+ - `gcf config set language.ui --value=ru` (and `language.artifacts`) sets the agents' language in AI Factory's `.ai-factory/config.yaml`: that key only, its comments kept, one `gcf(config)` commit (an uncommitted file is committed whole; a file git ignores is written, not committed, with a warning). An empty value takes the key off. `gcf config` and the board's settings list them.
102
+ - AGENTS.md: agents leave the language to the human. Run `ai-factory gcf init` after the update.
103
+
104
+ ### 0.9.0
105
+
106
+ - `gcf board --json` is `schema: 2`. The new `domain` field gives the board its columns in order (label, tooltip), the status runs start from, and the form of every item move: label, tooltip, command words, fields, and the drop zone that means it (Methodology §11, Board-PRD decision 16). The `columns` map (status → ids) is gone: filter `items` by `status`. gcf-board reads it from 0.3.0 on; an older board refuses schema 2, and gcf-board 0.3.0 refuses an older core: update both together.
107
+
108
+ ### 0.7.14
109
+
110
+ - `gcf anchor --json` gives each section its `body`, the text `/gcf-run-ingest` hands its workflow. The delta counts from the last *finished* import: `anchor` holds the map it started from in `gcf/source/<file>.import.json` until `gcf anchor <file> --done`, so an import that died after anchoring reports the same delta again (`resumed`) instead of an empty one. `/gcf-ingest` ends with `--done`.
111
+ - Instructions, from an audit of the agents' rules (2026-10-16): the commit injection makes no move on a `work/<id>` branch (verify `--mark`, the integrator moves it); the plan injection allows `gcf/INDEX.md` and `gcf/config.yml` besides the readset and names its graveyard and D2 lines; the review injection checks a feature child's capability against its parent's `live:`.
112
+ - Skills: `/gcf-card` puts `--severity` and `--release --channel` on `item new` and writes a bug's `repro:`, and removes an answered D1 only after every unit it blocks has it; `/gcf-triage` leaves a tune note in the inbox until `/gcf-verdict … tune --note` records it; a re-check after a red verify counts against `dod_attempts`; `cnlp-kit check` is named for what it covers. The item template keeps the architecture rule in `constraints:`; the systems profile keeps an `until:` line in its own block.
113
+ - Run `ai-factory extension update gcf-aif-ext`: the injections and skills come with it. Update `gcf-harness-aif-ext` to 0.9.6 with it: an older `/gcf-run-ingest` never runs `anchor --done`, so every later import would come back `resumed` with the delta of the first one.
114
+
115
+ ### 0.7.13
116
+
117
+ - `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.
118
+
119
+ - `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.
120
+ - 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.
121
+
122
+ ### 0.7.10
123
+
124
+ - 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.
125
+
126
+ - `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.
127
+ - `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.
128
+ - `gcf playtest session` lists the items awaiting a decision in a section of their own: before, they were missing from the sheet.
129
+ - `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.
130
+
131
+ ### 0.7.9
132
+
133
+ - `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.
134
+ - `gcf claim` says the mark lives 2 hours without a gcf command, as it does (it said 30 minutes).
135
+
136
+ ### 0.7.8
137
+
138
+ - 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:
139
+ - 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;
140
+ - a blank line inside a block no longer ends the record: before, the fields after it were lost;
141
+ - `gcf question answer` replaces an old answer written as a block whole: before, it replaced only the block's first line;
142
+ - an empty `answer:` is no answer: `design check` now holds the D1's units, as the board already showed it unanswered.
143
+
144
+ ### 0.7.7
145
+
146
+ - `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`.
147
+ - `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.
148
+
149
+ ### 0.7.6
150
+
151
+ - `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`).
152
+ - 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}`.
153
+ - The AGENTS.md block tells the agent that the permissions are the human's.
154
+
155
+ ### 0.7.1
156
+
157
+ - `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).
158
+
159
+ ### 0.7.0
160
+
161
+ - `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`.
162
+ - `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`.
163
+ - `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`). The mark names its owner (`GCF_RUN_OWNER` of a harness run, else `CLAUDE_CODE_SESSION_ID`): another owner's claim and `--claimed` moves are refused while it is fresh.
164
+ - `prioritize` leaves the rank of a ready item it does not name (a running one): the named items take the free ranks around it.
165
+ - `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.
166
+ - `/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.
167
+
168
+ ### 0.6.0
169
+
170
+ - `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`.
171
+ - `item new --model <m> --effort <e>`: the run of the item uses them (gcf-harness-aif-ext 0.7). One word each.
172
+ - `playtest session --json` and `live check --json` answer JSON: the flag went to the parent command, which printed text.
173
+ - `--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.
174
+ - `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.
175
+
176
+ ### 0.5.3
177
+
178
+ - `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.
179
+ - 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}`.
180
+ - 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.
181
+ - `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.
182
+ - An unplayed tune or kill keeps a systems-doc line the doc held before the item's close.
183
+ - `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.
184
+
185
+ ### 0.5.2
186
+
187
+ - Bundles `cnlp-kit` 3.9, so `gcf design check` and the commit gate accept a bullet written in Cyrillic alone.
188
+ - 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.
189
+
190
+ ### 0.5.1
191
+
192
+ - 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.
193
+ - An unplayed item's body is frozen, so a word added to the glossary or a removed question is reported there, not blocked.
194
+ - 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.
195
+
196
+ ### 0.5.0
197
+
198
+ 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:
199
+
200
+ - `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.
201
+ - `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.
202
+ - 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.
203
+ - `gcf playtest session [--build]` — the build of main and a checklist per item: what to check, how to get there, what to feel.
204
+ - `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`.
205
+ - `gcf board [--json]` — everything a board shows in one read.
206
+
207
+ 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.
208
+
209
+ ### 0.4.1
210
+
211
+ A fix release over 0.4.0; update in place. What you may notice:
212
+
213
+ - 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.
214
+ - 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.
215
+ - `design check` blocks a `depends:` cycle and an id with two terminal lines (a merge of branches).
216
+ - The commit gate refuses a `LIVE.md` ref into `gcf/` that names no file.
217
+ - `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.
218
+
219
+ ### Upgrading from 0.3.x
220
+
221
+ 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:
222
+
223
+ 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.
224
+ 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.
225
+ 3. Delete `gcf/cards/` and commit it with the new items.
226
+
227
+ 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.
228
+
229
+ ### Upgrading from 0.3.0
230
+
231
+ 0.3.1 is a patch release with no migration step. It changes behavior in these ways:
232
+
233
+ - 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`
234
+ - `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`
235
+ - `gcf audit` reports open questions older than `question_stale_after_commits` (`stale_questions`) and a `PILLARS.md` with more than 7 pillars
236
+ - a card with an unquoted numeric `id:` (YAML reads `id: 2024` as a number) is refused: quote the slug
237
+ - `built_at` is recorded in a follow-up commit after the implementation commit, with that commit's hash
238
+ - 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`
239
+ - 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
240
+
241
+ ### Upgrading from 0.2.x
242
+
243
+ 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:
244
+
245
+ 1. `ai-factory extension update` and `ai-factory gcf init` (adds `history.md` and the `.gitattributes` lines).
246
+ 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.
247
+ 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.
248
+ 4. `ai-factory gcf design check`, fix what it reports — typically a digit in a description — and commit.
249
+
250
+ To remove the extension:
251
+
252
+ ```bash
253
+ ai-factory extension remove gcf-aif-ext
254
+ ```
255
+
256
+ 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.
257
+
258
+ ## What it adds
259
+
260
+ **Skills** — `gcf-init`, `gcf-adopt`, `gcf-chat` (the board's project chat: answers, proposes new items, makes the moves the human approves), `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`.
261
+
262
+ **A deterministic core** behind `ai-factory gcf …`:
263
+
264
+ - 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`
265
+ - inbox and snapshot — `inbox [add <text> | add --text-file <path|-> | tag <in-id> | drop <in-id>]`, `live`, `live check`
266
+ - runs and play — `context`, `plan check <id>`, `verify <id>`, `playtest`, `playtest session [--build]`, `audit`
267
+ - project phase and board — `phase`, `phase next [--reason]`, `board [--json]` (everything a board shows, in one read)
268
+ - 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`
269
+ - design and sources — `design check`, `design export`, `design import`, `design migrate`, `anchor`, `section`, `quotes`, `lint`
270
+ - setup — `init`, `index`, `hooks-install`
271
+
272
+ 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.
273
+
274
+ **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.
275
+
276
+ **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`.
277
+
278
+
279
+ ## Docs
280
+
281
+ 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.
282
+
283
+ ## License
284
+
285
+ MIT
package/commands/gcf.js CHANGED
@@ -707,8 +707,14 @@ function registerItem(gcf) {
707
707
  .option('--release <version>', 'a release: the version it ships')
708
708
  .option('--channel <name>', 'a release: where it ships, e.g. steam')
709
709
  .option('--priority <rank>', 'its rank: 1, 2, 3… (lower runs sooner)')
710
- .option('--model <name>', 'the model its run uses, e.g. opus (default: the agent picks)')
711
- .option('--effort <level>', 'the effort its run uses, e.g. high (default: the agent picks)')
710
+ .option(
711
+ '--model <name>',
712
+ "the model its run uses, e.g. opus (default: agent.model of gcf/config.yml, else the agent's)",
713
+ )
714
+ .option(
715
+ '--effort <level>',
716
+ "the effort its run uses, e.g. high (default: agent.effort of gcf/config.yml, else the agent's)",
717
+ )
712
718
  .option('--note <text>', "what its run should know: the item's note:, up to 4000 characters")
713
719
  .option('--note-file <path>', 'the note from a file, - for stdin: several lines')
714
720
  .option('--commit', 'commit it (gcf(item)): for a caller with no console, e.g. a board')
@@ -768,8 +774,14 @@ function registerAgent(item) {
768
774
  item
769
775
  .command('agent <id>')
770
776
  .description("Set the model and effort of an item's runs: from its next run (commit)")
771
- .option('--model <name>', 'e.g. opus; default takes the field off: the agent picks')
772
- .option('--effort <level>', 'e.g. high; default takes the field off: the agent picks')
777
+ .option(
778
+ '--model <name>',
779
+ "e.g. opus; default takes the field off: the project's, else the agent's",
780
+ )
781
+ .option(
782
+ '--effort <level>',
783
+ "e.g. high; default takes the field off: the project's, else the agent's",
784
+ )
773
785
  .option('--no-commit', 'skip the commit (tests only)')
774
786
  .action(async (id, o) => {
775
787
  const r = await (
@@ -1261,7 +1273,7 @@ function registerSettings(gcf) {
1261
1273
  });
1262
1274
  config
1263
1275
  .command('set <key>')
1264
- .description('Set one key; an empty --value= takes a number back to its default')
1276
+ .description('Set one key; an empty --value= takes a number back to its default, a word off')
1265
1277
  // The value only through --value: `set plan_passes 7` must not read as a reset. A value
1266
1278
  // may start with a hyphen (a command's flag); as `--value=<text>` it stays one value.
1267
1279
  .allowExcessArguments(false)
package/extension.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
3
3
  "name": "gcf-aif-ext",
4
- "version": "0.13.0",
4
+ "version": "0.14.0",
5
5
  "description": "Game Context Framework for AI Factory",
6
6
  "skills": [
7
7
  "skills/gcf-init",
@@ -9,7 +9,7 @@ import { existsSync } from 'node:fs';
9
9
  import path from 'node:path';
10
10
  import { commitMove } from './unit-ops.js';
11
11
  import { atomicWrite } from './safe-path.js';
12
- import { gcfRoot } from './gcf-paths.js';
12
+ import { gcfRoot, RUN_WORD } from './gcf-paths.js';
13
13
  import { configDoc, ensureMap } from './config-set.js';
14
14
 
15
15
  const GROUPS_SHAPE = 'gcf/config.yml: agent.groups must map a group id to true or false';
@@ -265,10 +265,28 @@ function choices(agent) {
265
265
  }
266
266
 
267
267
  /**
268
- * The `agent:` section resolved: each group on or off, the deny rules the run gets, the extra
269
- * allow rules (for an agent run without bypass). No section: the default groups. `rules` holds
270
- * them neutral (AD-4), `deny` and `allow` as claude rules for a harness before 0.12;
271
- * `deny_extra` is the operator's own deny lines as written, `extra` the same neutral.
268
+ * The project's model and effort (`agent.model`, `agent.effort`): what an item or a thread
269
+ * without its own pick runs on; null, or `default` written by hand, leaves it to the agent. One
270
+ * word each, as an item's.
271
+ */
272
+ function picksOf(agent) {
273
+ const pick = (k) => {
274
+ const v = agent[k] ?? null;
275
+ if (v !== null && !(typeof v === 'string' && RUN_WORD.test(v)))
276
+ throw new Error(`gcf/config.yml: agent.${k} must be one plain word, e.g. opus`);
277
+
278
+ return v?.toLowerCase() === 'default' ? null : v;
279
+ };
280
+
281
+ return { model: pick('model'), effort: pick('effort') };
282
+ }
283
+
284
+ /**
285
+ * The `agent:` section resolved: the project's model and effort, each group on or off, the deny
286
+ * rules the run gets, the extra allow rules (for an agent run without bypass). No section: the
287
+ * default groups. `rules` holds them neutral (AD-4), `deny` and `allow` as claude rules for a
288
+ * harness before 0.12; `deny_extra` is the operator's own deny lines as written, `extra` the
289
+ * same neutral.
272
290
  */
273
291
  export function agentOf(config) {
274
292
  const agent = config.agent ?? {};
@@ -284,6 +302,7 @@ export function agentOf(config) {
284
302
  ].filter((r, i, all) => all.findIndex((x) => sameRule(x, r)) === i);
285
303
 
286
304
  return {
305
+ ...picksOf(agent),
287
306
  groups,
288
307
  deny_extra: extra,
289
308
  deny: claudeOf(denied),
package/lib/board.js CHANGED
@@ -7,7 +7,7 @@ import path from 'node:path';
7
7
  import { buildLedger } from './ledger.js';
8
8
  import { readConfig } from './gcf-paths.js';
9
9
  import { readLive } from './live.js';
10
- import { listInbox } from './inbox.js';
10
+ import { filesUnder, listInbox } from './inbox.js';
11
11
  import { phaseStatus } from './phase.js';
12
12
  import { verifiedBranches, worktreeOf } from './integrate.js';
13
13
  import { resolveInside } from './safe-path.js';
@@ -275,11 +275,12 @@ function runningKind(projectDir, id) {
275
275
 
276
276
  /**
277
277
  * What a board may offer (§4.1): nothing while a run drives the item; with the harness, the
278
- * agent's run to an item that waits for one and has no green verify yet.
278
+ * agent's run to an item that waits for one and has no green verify yet. A feature runs through
279
+ * its children: the run gate refuses it.
279
280
  */
280
281
  function offered(c, { running, verified, harness }) {
281
282
  if (running) return [];
282
- const runs = harness && c.data.status === RUNS_FROM && !verified;
283
+ const runs = harness && c.data.status === RUNS_FROM && !verified && c.data.type !== 'feature';
283
284
 
284
285
  return [...(runs ? ['run'] : []), ...movesOf(c.data)];
285
286
  }
@@ -293,6 +294,16 @@ const waitsOf = (c, running, ledger) =>
293
294
  ? openDepends(ledger, c.data.depends ?? [], { waiting: true })
294
295
  : [];
295
296
 
297
+ /** The files `gcf item attach` gave the item, as project paths; none: no field. */
298
+ async function attachmentsOf(projectDir, id) {
299
+ const dir = path.join(path.resolve(projectDir), 'gcf', 'work', id, 'attachments');
300
+ const files = (await filesUnder(dir))
301
+ .map((f) => path.relative(path.resolve(projectDir), f).replaceAll('\\', '/'))
302
+ .sort();
303
+
304
+ return files.length ? { attachments: files } : {};
305
+ }
306
+
296
307
  /** One item of the board. */
297
308
  async function itemOf(projectDir, c, { verified, ledger, harness }) {
298
309
  const id = String(c.data.id);
@@ -330,6 +341,7 @@ async function itemOf(projectDir, c, { verified, ledger, harness }) {
330
341
  needs: needsOf(ledger, c.data.depends ?? []),
331
342
  moves: offered(c, { running, verified: ready, harness }),
332
343
  file: `gcf/work/${c.name}`,
344
+ ...(await attachmentsOf(projectDir, id)),
333
345
  log: logOf(projectDir, id),
334
346
  // Filled by board() from the inbox.
335
347
  lessons: 0,
@@ -371,6 +383,8 @@ export async function board(projectDir) {
371
383
  // The human's settings of config.yml and the agents' language, each with its value and
372
384
  // default (`gcf config set`).
373
385
  settings: await projectSettings(projectDir),
386
+ // Minutes one agent session on an item may run: the harness's limit without --timeout.
387
+ session_timeout_min: config.session_timeout_min,
374
388
  context: {
375
389
  handoff_pct: config.context_handoff_pct,
376
390
  window: config.context_window,
package/lib/config-set.js CHANGED
@@ -1,7 +1,8 @@
1
1
  // `gcf config set` (GCF-PRD §12.4): the human's settings of gcf/config.yml, one key at a time,
2
2
  // so a board edits them through the core and never writes the file itself. A change is checked
3
3
  // by the same rules a read applies before it is written; the rest of the file keeps its keys
4
- // and comments. `phases:` and `agent:` have their own commands and are not set here. The
4
+ // and comments. `phases:` and the permissions of `agent:` have their own commands and are not
5
+ // set here; the project's model and effort (`agent.model`, `agent.effort`) are. The
5
6
  // language agents write in is AI Factory's (`.ai-factory/config.yaml`), set here for the board
6
7
  // too, since AI Factory has no command for it (Board-PRD decision 12).
7
8
  import { readFile } from 'node:fs/promises';
@@ -21,10 +22,12 @@ import {
21
22
  gcfRoot,
22
23
  readRawConfig,
23
24
  RUN_MODES,
25
+ RUN_WORD,
24
26
  } from './gcf-paths.js';
25
27
  import { AIF_CONFIG, LANGUAGE_RE, languageIn, readAifConfig } from './aif-config.js';
28
+ import { agentOf } from './agent-permissions.js';
26
29
 
27
- /** @typedef {'number' | 'share' | 'mode' | 'command' | 'language'} Kind */
30
+ /** @typedef {'number' | 'share' | 'mode' | 'command' | 'language' | 'word'} Kind */
28
31
 
29
32
  // Thrown inside the move to leave without a write or a commit.
30
33
  const NO_CHANGE = new Error('no change');
@@ -52,7 +55,12 @@ export function ensureMap(doc, keys, error) {
52
55
  doc.setIn(keys, doc.createNode({}));
53
56
  }
54
57
 
55
- /** @type {{ key: string, kind: Kind, label: string, file?: string, options?: string[] }[]} */
58
+ /**
59
+ * `presets`: a word whose suggestions are the agent's own (`presets` of the board read), not the
60
+ * framework's.
61
+ * @type {{ key: string, kind: Kind, label: string, file?: string, options?: string[],
62
+ * presets?: 'model' | 'effort' }[]}
63
+ */
56
64
  export const SETTINGS = [
57
65
  {
58
66
  key: 'language.ui',
@@ -78,6 +86,25 @@ export const SETTINGS = [
78
86
  'how a run drives an item: worktree (several at once) or main (one at a time in the ' +
79
87
  'project folder)',
80
88
  },
89
+ {
90
+ key: 'session_timeout_min',
91
+ kind: 'number',
92
+ label:
93
+ 'minutes one agent session on an item may run before it is stopped and the item stays ' +
94
+ 'ready (waits for your answer do not count; above 0, unlike the DoD limit)',
95
+ },
96
+ {
97
+ key: 'agent.model',
98
+ kind: 'word',
99
+ presets: 'model',
100
+ label: "the model an item or a chat thread without its own runs on (empty: the agent's choice)",
101
+ },
102
+ {
103
+ key: 'agent.effort',
104
+ kind: 'word',
105
+ presets: 'effort',
106
+ label: "the effort an item or a chat thread without its own runs with (empty: the agent's)",
107
+ },
81
108
  {
82
109
  key: 'chat.ask',
83
110
  kind: 'mode',
@@ -150,7 +177,17 @@ const BY_KEY = new Map(SETTINGS.map((s) => [s.key, s]));
150
177
  /** @type {[string, string[]][]} */
151
178
  const GROUPS = [
152
179
  ['Language', ['language.ui', 'language.artifacts']],
153
- ['Runs', ['run_mode', 'plan_passes', 'dod_attempts']],
180
+ [
181
+ 'Runs',
182
+ [
183
+ 'run_mode',
184
+ 'session_timeout_min',
185
+ 'agent.model',
186
+ 'agent.effort',
187
+ 'plan_passes',
188
+ 'dod_attempts',
189
+ ],
190
+ ],
154
191
  ['Checks (DoD)', ['dod.test', 'dod.build', 'dod_timeout_min']],
155
192
  ['Chat', ['chat.ask', 'chat.answer_timeout_min']],
156
193
  ['Context', ['context_handoff_pct', 'context_window', 'auto_compact_pct']],
@@ -228,6 +265,15 @@ function valueOf(setting, text) {
228
265
  return t;
229
266
  }
230
267
 
268
+ // `default`, as an item's, leaves the choice to the agent.
269
+ if (setting.kind === 'word') {
270
+ if (!t || t.toLowerCase() === 'default') return null;
271
+ if (!RUN_WORD.test(t))
272
+ throw new Error(`${setting.key} must be one plain word (letters, digits, . - _), e.g. opus`);
273
+
274
+ return t;
275
+ }
276
+
231
277
  if (setting.kind === 'mode') {
232
278
  const options = setting.options ?? [];
233
279
  if (!options.includes(t)) throw new Error(`${setting.key} must be ${options.join(' | ')}`);
@@ -291,7 +337,8 @@ export async function setConfig(projectDir, key, text, { commit = true } = {}) {
291
337
  if (value === null) doc.deleteIn(keys);
292
338
  else doc.setIn(keys, value);
293
339
  const raw = doc.toJS();
294
- if (!setting.file) configOf(raw);
340
+ // `agent:` is read by its own rules: a key set here must not leave a broken section.
341
+ if (!setting.file) agentOf(configOf(raw));
295
342
  const out = doc.toString();
296
343
  // The values, not the text: YAML's output may differ in form (a final newline, `{}`).
297
344
  if (isDeepStrictEqual(YAML.parse(text) ?? {}, raw ?? {})) {
package/lib/domain.js CHANGED
@@ -71,8 +71,9 @@ const decide = (choice, help, fields = [], danger) => ({
71
71
  });
72
72
  const text = (key, label, extra = {}) => ({ key, label, kind: 'text', ...extra });
73
73
  // How an item's run goes: a board offers its agent's presets (`presets`), and `default`, which
74
- // leaves the choice to the agent; a word of the operator's own goes too.
75
- const PICKS = 'default: the agent picks';
74
+ // leaves the choice to the project's `agent.model|effort`, else the agent; a word of the
75
+ // operator's own goes too.
76
+ const PICKS = "default: the project's, else the agent picks";
76
77
  const MODEL = text('model', 'Model of its run', { presets: 'model', help: PICKS });
77
78
  const EFFORT = text('effort', 'Effort of its run', { presets: 'effort', help: PICKS });
78
79
 
package/lib/gcf-paths.js CHANGED
@@ -24,8 +24,16 @@ export const DEFAULT_CONFIG = {
24
24
  context_window: 0,
25
25
  // CLAUDE_AUTOCOMPACT_PCT_OVERRIDE for the run (0: the agent's own default).
26
26
  auto_compact_pct: 0,
27
+ // Minutes one agent session on an item may run (waits for the operator's answer do not
28
+ // count); a context handoff starts the next session with its own. Never 0: a session with no
29
+ // limit could hold a night queue until morning.
30
+ session_timeout_min: 120,
27
31
  };
28
32
 
33
+ // A model or effort word as the agent's command line takes it; a leading hyphen would read as a
34
+ // flag of it.
35
+ export const RUN_WORD = /^[A-Za-z0-9][\w.-]*$/;
36
+
29
37
  const PCT_KEYS = ['context_handoff_pct', 'auto_compact_pct'];
30
38
 
31
39
  /** `gcf/` lives at the repository root (GCF-PRD §5.1). Throws when absent. */
@@ -109,6 +117,8 @@ export function configOf(parsed) {
109
117
  }
110
118
  }
111
119
 
120
+ if (config.session_timeout_min === 0)
121
+ throw new Error('gcf/config.yml: session_timeout_min must be above 0: a session needs a limit');
112
122
  for (const key of PCT_KEYS)
113
123
  if (config[key] > 100)
114
124
  throw new Error(`gcf/config.yml: ${key} is a share of the window, 0-100, got ${config[key]}`);
package/lib/inbox.js CHANGED
@@ -47,7 +47,7 @@ export function checkTags(tags) {
47
47
  }
48
48
 
49
49
  /** Every file under a folder, deepest last; none when it is not there. */
50
- async function filesUnder(dir) {
50
+ export async function filesUnder(dir) {
51
51
  if (!existsSync(dir)) return [];
52
52
  const entries = await readdir(dir, { recursive: true, withFileTypes: true });
53
53
 
package/lib/work-ops.js CHANGED
@@ -10,7 +10,7 @@ import { createHash } from 'node:crypto';
10
10
  import path from 'node:path';
11
11
  import { parse, serialize } from './frontmatter.js';
12
12
  import { buildLedger } from './ledger.js';
13
- import { readConfig } from './gcf-paths.js';
13
+ import { readConfig, RUN_WORD } from './gcf-paths.js';
14
14
  import { atomicWrite, resolveInside } from './safe-path.js';
15
15
  import { allowedFrom, decisionFits, FEATURE_ONLY, fromOf } from './transitions.js';
16
16
  import { ITEM_TYPES, DEFAULT_GATE, GATES, SEVERITIES, UNIT_ITEM_TYPES } from './validate-item.js';
@@ -828,9 +828,6 @@ async function dropItemUnlocked(projectDir, id, opts = {}) {
828
828
  return { id, hash: await finish(m, 'drop', id, commit), removal };
829
829
  }
830
830
 
831
- // A leading hyphen would read as a flag of the agent's command line.
832
- export const RUN_WORD = /^[A-Za-z0-9][\w.-]*$/;
833
-
834
831
  /** The version and channel of a new item: well-formed, and only on a release. */
835
832
  function checkRelease(spec) {
836
833
  const { type, version, channel } = spec;
@@ -1073,7 +1070,7 @@ async function setDependsUnlocked(projectDir, id, { add = [], remove = [], commi
1073
1070
 
1074
1071
  /**
1075
1072
  * Set how item `id`'s runs go: its `model` and `effort`, each given one a plain word, `default`
1076
- * taking the field off (the agent's own choice). One commit `gcf(item)`. A run in progress keeps
1073
+ * taking the field off (the project's `agent.model|effort`, else the agent's own choice). One commit `gcf(item)`. A run in progress keeps
1077
1074
  * its own; the item's next run takes the new value.
1078
1075
  * @param {string} projectDir
1079
1076
  * @param {string} id
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-aif-ext",
3
- "version": "0.13.0",
3
+ "version": "0.14.0",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -24,7 +24,8 @@ gcf_work:
24
24
  - 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>"`
25
25
  - 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`
26
26
  - `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
27
- - 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; an existing item changes with `ai-factory gcf item agent <id> --model <m> --effort <e>` (`default` takes one off: the agent picks), never a hand edit; its next run takes them
27
+ - 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; an existing item changes with `ai-factory gcf item agent <id> --model <m> --effort <e>` (`default` takes one off), never a hand edit; its next run takes them; an item without its own runs on the project's `agent.model` and `agent.effort` of `gcf/config.yml`, a setting of the human
28
+ - before starting a run, `ai-factory gcf-harness gate --each <ids...> --json` says what the run gate refuses each item alone for now (it exits 0; a batch is still gated as a whole by `gate <ids...>`, exit 1); a session stops after `session_timeout_min` of `gcf/config.yml`, its item stays ready
28
29
  - 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: `ai-factory gcf depends <id> --add <ids>` or `--remove <ids>`, never a hand edit
29
30
  - what happened to an item before (who submitted, blocked, tuned or reranked it, and when) is `ai-factory gcf item history <id>`: its moves from git, an ended item's too
30
31
  - a picture or file the human gives an item goes to `ai-factory gcf item attach <id> --file <path>` (its `gcf/work/<id>/attachments/`, committed); read an item's attachments before you plan it