gcf-board 0.9.1 → 0.10.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,106 +1,108 @@
1
- # gcf-board
2
-
3
- A local web board for game projects on [GCF](../gcf-aif-ext): the items by status, the phase, WIP, the inbox, the playtest session, what was accepted and what was killed — and buttons that run the same `ai-factory gcf` commands an operator runs in a console. The board is a view: it stores nothing, and without it the work goes on in the console unchanged (Methodology §11).
4
-
5
- ## Requirements
6
-
7
- - Node.js ≥ 22.18
8
- - [`ai-factory`](https://www.npmjs.com/package/ai-factory) installed globally, and in each project [`gcf-aif-ext`](../gcf-aif-ext) ≥ 0.10 (`gcf board --json` with `schema: 3`: the columns, the moves, the item's fields, the blocks and the Help terms come from it as data)
9
- - for runs: [`gcf-harness-aif-ext`](../gcf-harness-aif-ext) ≥ 0.11 (every board run opens its chat: `--chat`, `gcf-harness chat`; it waits the project's answer time) and Claude Code (`claude -p`); ≥ 0.12 to wait for the usage limit's reset and for queued runs (`--wait-limit`)
10
- - for the project chat: `gcf-aif-ext` ≥ 0.12 (`domain.chat`, `agent.rules`) and Claude Code
11
- - for board v2 (0.9): `gcf-aif-ext` ≥ 0.13 for an item's History, `needs`, the design units, filters and lanes; `gcf-harness-aif-ext` ≥ 0.13 for past runs and a run's model and effort. On older ones these hide or say which version they need
12
- - gcf-board 0.2 needs `gcf-aif-ext` ≥ 0.7 (priority, questions, session marks, `run_mode`)
13
-
14
- ## Run
15
-
16
- ```bash
17
- npm i -g gcf-board
18
- gcf-board # http://127.0.0.1:4317
19
- gcf-board --port 4400
20
- gcf-board --version # the installed version
21
- ```
22
-
23
- It opens the board in your browser (the URL with the token, `http://127.0.0.1:4317/?t=<token>`, is printed too; `--no-open` skips the browser). Started again while it runs, it just opens the running board. Add a project by its folder (one that has `gcf/`) under **Projects**.
24
-
25
- **Desktop shortcut**: run once
26
-
27
- ```bash
28
- gcf-board shortcut # or: gcf-board shortcut --port 4400
29
- ```
30
-
31
- It puts **GCF Board** on the desktop (Windows: a shortcut whose server console starts minimized; macOS: `GCF Board.command`; Linux: an application entry). Double-click it: the board starts and opens, or opens if it already runs. Run the command again after moving Node.js.
32
-
33
- ## What it does
34
-
35
- The board knows no domain by name: the project's board read gives its columns, moves with their forms, item fields, blocks and Help terms (`domain`, Board-PRD decision 16). The page follows design B (`docs/design/mockup`): a left nav with the project switcher (add a project, take one off the board), the screens **Command**, **Board**, **Chat**, **Inbox**, **Runs**, **Playtest**, **Ended**, **Agent**, **Settings** and **Metrics** (a domain without a block has no screen for it, a project without a harness no Runs and no Metrics), and a header with the phase, the runs, the limit wait, the quota, WIP, the release, **waiting for me**, **+ item** and **?**. The project and the screen are in the URL hash. On a phone a bottom bar holds Command, Board, Chat, Inbox and More. When the server is gone, the page says so and reconnects by itself. For a GCF project:
36
-
37
- - **Command**: **waiting for me**, what only the operator moves on (Board-PRD §1.3), by group: failed run reports and a paused queue, a card waiting in a chat (a permission is answered right there, **Always** naming the rule it saves), D1 questions, the items to play and judge, to decide, to unblock (the columns the domain marks `human`), and a `paused: limit` item to resume. Beside it **Live**: the runs going on with their plan progress, **Follow** and **Stop**, the console runs and sessions, **Run next**, the queue, the run reports, and what the board did by itself.
38
- - **Board**: columns ready, running, blocked, awaiting-verdict, awaiting-decision, unplayed, parked. A card shows the type, the gate, the plan progress (`2/5`), the severity, `verified`, the model, **needs N** and **needed by N**. A running card shows when its run log was last written (`active 12 s ago`), and `quiet 6 min` when the log has been silent for 5 minutes or more. A run's end report gives each item's cost when the agent reported it. Pointing at a card (or focusing it from the keyboard) lights up the cards it needs and the cards that need it, each saying how, and dims the rest. The toolbar (board 0.9.0, core 0.13.0) searches ids and titles, keeps **waiting for me**, filters by the fields the domain marks `filter` (GCF: type, gate, severity, system, milestone; several values at once, each a chip to take off) and lays the board out in lanes by a field it marks `group` (system, parent, milestone): an item with two systems stands in both lanes, one with none in **none**, a parent lane is named by the feature's title. The mouse drags the board sideways from its empty space; the wheel over a column with no scroll of its own pans it.
39
- - **An item**: its file, its plan and its run log as it grows, its fields, and the moves the core offers for it (`items[].moves`, Methodology §4.1): run, verdict, decide, block, unblock, drop, close, submit, depends. Each move's form comes from the core; the core still checks the rest itself, and the board shows its answer. **Dependencies**: what it needs that has not ended in history (an item with its column, a design unit with its TBDs or the questions that block it, a graveyard line, an unknown id) and the items that need it, each a link; **Edit…** opens the picker of the board's items and design units (search by id and title, or type an id), and Save sends the `depends` move's adds and removes. **History** (core 0.13.0): its moves newest first, when, which, who (a run, your session, you; unknown on a commit older than the framework's marks), the commit and its subject; then its runs, as on the Runs screen. **Related**: its feature's other children, and the graveyard lines tagged with its system ("did we kill this before?"). An item that ended opens from **Ended** with its History.
40
- - **Runs** (harness 0.13.0): what runs now with the run's model and effort, its last log lines, **Whole log** and **Stop**; the queue with what each item will run on; the past runs of the harness's run log, newest first, 50 at a time: start, end, mode, cost, and per item its result word, the reason word for word, cost, tokens, turns, handoffs, a broken step and what it ran on. **log** opens the part of the item's log that run wrote, **chat** that run's chat. Every start the operator asks for (Run selected, Run next, a drop on running, this screen) asks first with a model and effort picker for that run only (**default: each item's own**); the drawer's Run is one click. An older harness shows the active runs only, and the dialog has no pickers. The API: `GET /api/p/<project>/runs/past?limit=` (`gcf-harness runs --json`; 404 without a harness that keeps them), `GET …/item/<id>/history` (`{id, moves, runs}`), `GET …/log/<id>?from=&to=` (a past run's part, once: `{text, cut}`, at most its last 2 MB; without `from` and `to` the log as it grows), `POST …/run` with `model` and `effort`, `POST …/inbox/<entry>/draft` (`{thread, created}`).
41
- - **Drag**:
42
- - a ready card into **running** starts its run;
43
- - a blocked or parked card into **ready** unblocks it;
44
- - a card onto **graveyard** drops it.
45
-
46
- Every other move is a button.
47
- - **Run**: **run** on an item, or select ready cards and **Run selected**. It starts `ai-factory gcf-harness run <ids> --json` in the project's run mode:
48
- - `run_mode: worktree`: one worktree and one agent session per item, all at once, then the integrator;
49
- - `run_mode: main`: one item at a time in the project folder. A run asked for meanwhile waits in the board's **queue**; **remove from queue** takes it out.
50
-
51
- A run asks first: it spends the subscription. **Stop** on a running item ends its session; the item stays ready and its work is kept. **Stop** during the wait for the usage limit's reset leaves the item **paused: limit** with its reset, and the queue goes on. A queued main run that the next one would repeat (the harness did not start, or another run works the checkout) pauses the queue: the header shows **queue paused — resume**; fix the cause, then resume. A card marked **interrupted** had a run that stopped (a timeout, a stop, a crash, the usage limit): **resume** continues its agent session with all its context, **start fresh** drops it. After the usage limit the run itself waits for the reset and goes on in the same session (harness 0.12): the card reads **limit: resumes HH:MM**, and **Stop** ends the wait. A run that could not wait (the week's limit, an unknown reset) ends **paused: limit** and pauses the main queue; **resume** on the header goes on after the reset. When a run ends, a report card lists each item's result and stays until closed, across page reloads. **What the board did by itself** lists its automatic acts with their times: a usage limit, a context handoff, the queue paused, resumed or started. A run confirmation names what each interrupted item picks up. The header shows the usage limit as the last run read it, from the newest `.gcf-session/runs/quota.json` of the board's projects: `quota 19% left · resets 03:00`, the window with the least left, every window in its tooltip; `quota ?` before any reading, or once every window has reset since. The queue, the reports and that list live in the board's memory: a board restart forgets them. A run itself outlives the board: closing it or Ctrl+C in its console leaves the run going, and the board started again shows it running, then its report (a run in flight keeps its record in `~/.gcf/runs/`).
52
- - **Who runs it** (core 0.7.13): a running card tells a console run and **your session** (a `gcf claim` mark) from the board's own run; a session offers **release mark** instead of **stop**. A ready card whose dependencies are not built yet shows **waits for <dep>**; the drawer shows when an item began to wait (`since_at`).
53
- - **Run next N independent**: the framework's gate picks the ready items that can run together now, by priority, and the board runs them after asking.
54
- - **Priority**: drop a ready card on another to put it before; the column's ranks are committed (`gcf prioritize`).
55
- - **Questions**: each D1 shows its question and proposed answer; **Answer** writes yours into its record (`gcf question answer`), and the next agent on its units puts it in place.
56
- - **New item**: `gcf item new … --commit`, its form from the core: a bug asks its severity, a release its version and channel. The item's `model` and `effort` go to its run.
57
- - **Help** (**?**): the domain's terms, columns, moves and field values with what each means, and the words of runs, under one filter.
58
- - **Settings**: the keys of `gcf/config.yml` and the agents' language (`language.ui`, `language.artifacts` of `.ai-factory/config.yaml`), by the core's groups, each a `gcf config set` commit.
59
- - **Agent**: the deny groups to tick, the rules the ticked groups add, the operator's own deny rules (add, remove) and the allow rules of `agent.allow`, apart; the context limits, read only.
60
- - **An item's chat** (its drawer's **Chat** tab; harness 0.11.1, core 0.11.1): every run the board starts keeps its agent sessions open; the project's `chat:` settings (Settings: `chat.ask`, `chat.answer_timeout_min`) say what the agent asks and how long a question waits. The tab shows the run's chat, then the item's own thread of the project chat: the talk, question cards (picks, several questions, **Submit**), the run's milestones, its sessions, the limit wait, the context share. A message goes where the server puts it: the live run (its limit wait too), else the item's thread, and the line under the box says where it went. `GET /api/p/<project>/chat/<id>` follows the item's chat from its start, in raw chunks of JSON lines (the page splits them). `POST` there sends `{type: 'say', text, images?, attach?}`, `{type: 'interrupt'}` or `{type: 'answer', request_id, answers}` through `gcf-harness chat`; with no live run a message goes to the item's thread (answer `{talk}`), else a message with no session to read it gets 409, bad input 400. `attach` (`[{kind: item | unit | file, ref}]`) goes into the message's text as a line the agent reads; a design unit (the composer's **+ unit**, from the board read's `units`) goes as `unit <id> (<file>)`. `GET /api/p/<project>/chat/<id>/att/<file>` serves a chat picture; **attach to item…** under a picture gives it to an item (`gcf item attach`).
61
- - **Model and effort** (board 0.8.0, core 0.12.3): pickers in the New item form, in the drawer (**change** beside the model and effort, and **model / effort** under **More**) and in a thread's composer: **default** (the agent picks), the agent's presets, or an own word. An item's next run takes them; a thread's next session does (`chats/<t>/agent.json`), and its line in the chat says so.
62
- - **Project chat** (the **Chat** screen; core 0.12): threads of an agent in the project's folder, listed newest first and filtered by their item; a new thread is made when its first message is sent. Each thread is run by the bundled session engine (`gcf-session`) through the same detached relay as runs. It asks a card before each edit, git command and framework move (**allow once**, **always** — saved in `.claude/settings.local.json`; the card says saved only when it was — or **deny**); a new item it proposes through the board's MCP server `gcf` (tool `propose_item_new`, asked with no card: the proposal card is the question), the proposal card shows every field it proposed, and the operator's **Create** makes it with `POST /move` (`proposal: {talk, id}`), **Edit…** first in the new-item form. A thread's list entry names the card that waits in it and its limit wait (`card`, `limit_until`); a running item names the card of its run's chat (`chat_card`). A long talk hands over to a fresh agent from a summary; an idle agent closes after `chat.answer_timeout_min` (0 means 15) and the next message resumes it. Each item has at most one thread: a message to an item with no live run goes there. `GET /api/p/<project>/talks[?item=]` lists the threads with their proposals' states; `POST` there makes one (`{item?}`); `GET /api/p/<project>/talk/<t>` follows a thread's events; `POST` there sends `say`, `interrupt`, `answer`, `allow`, `deny` or `handoff`; `POST …/talk/<t>/stop` is the composer's **close agent** (board 0.8.1): the thread's agent ends with everything it started, or its limit wait does, and what it had not taken in is dropped with a "not sent" line; the next message resumes the talk; `GET …/talk/<t>/att/<file>` serves its pictures. The files live in `.gcf-session/chats/` (docs/Chat-Plan.md §3).
63
- - **Inbox**: add an entry (Enter adds, Shift+Enter breaks the line; its source and tags), tag it, erase it, or turn it into an item (its first line the title, the rest the note); search the entries, filter them by tag and by lesson kind. The D1 questions and the agent's D2 assumptions are listed there too. **Draft with agent** opens a project chat thread bound to the entry and sends "Draft an item from inbox entry <id>:" with its text; a second click opens the same thread. The first proposal's **Create** takes the entry (it is erased); a later one makes an item with no entry. Off while the usage limit holds.
64
- - **Keys**: `/` search, `i` a new inbox entry, `n` a new item, `j` / `k` between cards, Enter opens one, `r` runs the focused card (it asks), `1`–`7` a column, `?` Help, Esc closes a dialog, Help or the drawer; none while a field has the focus.
65
- - **Lessons** (core 0.7.10, harness 0.9.2): what got in an agent's way, asked at the end of each session, lands in the inbox with its kind (`tool`, `rules`, `framework`, `template`, `other`) and its item. The inbox filters them; a card shows `N lessons`, and the drawer lists the item's lessons with the inbox's buttons. A run's report line ends with `, N lessons`, and with `— code written outside aif-implement` when a session skipped that skill.
66
- - **Playtest**: `gcf playtest session` with the checklist grouped by subsystem; keep, tune or kill each item from the list. **Build** runs `dod.build`. A note goes to the inbox as `--source playtest`.
67
- - **Ended**: history (accepted) and graveyard (killed, dropped, won't-fix); a line opens the item's History.
68
- - **Metrics**: `gcf-harness metrics --json` of the project — how many runs reached submit or close, what they cost, handoffs, plan checks, DoD attempts, guard firings, block reasons — and, with harness 0.9.5, the cost per item over all its runs and per week and day.
69
-
70
- The page updates by itself: the server watches each project's `gcf/` and `.gcf-session/runs/`.
71
-
72
- ## Security
73
-
74
- The board starts agents that write code and commit: whoever can talk to it runs code on this machine.
75
-
76
- - It listens on `127.0.0.1` only.
77
- - The token, kept in `~/.gcf/board-token`, opens the board once per server start; delete that file to make a new one. The browser then holds a session cookie that dies with the server: a browser sends a `127.0.0.1` cookie to every local port, so the cookie is never the token.
78
- - Started while another program holds its port, it refuses rather than hand the token to that program.
79
- - A request must also name host `127.0.0.1` or `localhost` with the board's port.
80
- - A change must come from the board's own page (`Origin`). This blocks another site in the same browser.
81
- - Commands run without a shell: the operator's text reaches `ai-factory` as one argument, never as a command line.
82
- - The API shows only item files, plans and run logs inside a project.
83
- - A project chat's agent may not read the board's folder (`~/.gcf`, the token's): not by read, search or a shell command that names it. A command that spells the path another way still could; a separate secret for a card's answer comes with remote access.
84
-
85
- Do not put the port on a network. Remote and phone access is planned for v2, behind its own authentication.
86
-
87
- ## Files
88
-
89
- - `~/.gcf/projects.json`: the projects on the board, `{projects: [{name, path}]}`.
90
- - `~/.gcf/board-token`: the token.
91
- - `~/.gcf/runs/`: the record of each run in flight, which a board started again finds.
92
- - `GCF_BOARD_HOME` moves them all; `GCF_BOARD_AIF` points at another `ai-factory` entry script; `GCF_SESSION_AGENT` puts another agent command in place of `claude` in project chats (tests).
93
-
94
- ## Roadmap (v2)
95
-
96
- - **Phone and remote access**: Tailscale or Claude Remote Control, with their own authentication; push notifications when an item blocks or waits for a verdict.
97
-
98
- ## Develop
99
-
100
- ```bash
101
- npm install
102
- npm test # server and web tests on Node's type stripping
103
- npm run typecheck
104
- npm run build # vite → dist/web, tsc → dist/server
105
- node dist/server/main.js --port 4318
106
- ```
1
+ # gcf-board
2
+
3
+ A local web board for game projects on [GCF](../gcf-aif-ext): the items by status, the phase, WIP, the inbox, the playtest session, what was accepted and what was killed — and buttons that run the same `ai-factory gcf` commands an operator runs in a console. The board is a view: it stores nothing, and without it the work goes on in the console unchanged (Methodology §11).
4
+
5
+ ## Requirements
6
+
7
+ - Node.js ≥ 22.18
8
+ - [`ai-factory`](https://www.npmjs.com/package/ai-factory) installed globally, and in each project [`gcf-aif-ext`](../gcf-aif-ext) ≥ 0.10 (`gcf board --json` with `schema: 3`: the columns, the moves, the item's fields, the blocks and the Help terms come from it as data)
9
+ - for runs: [`gcf-harness-aif-ext`](../gcf-harness-aif-ext) ≥ 0.11 (every board run opens its chat: `--chat`, `gcf-harness chat`; it waits the project's answer time) and Claude Code (`claude -p`); ≥ 0.12 to wait for the usage limit's reset and for queued runs (`--wait-limit`)
10
+ - for the project chat: `gcf-aif-ext` ≥ 0.12 (`domain.chat`, `agent.rules`) and Claude Code
11
+ - for 0.10: `gcf-aif-ext` ≥ 0.14 for an item's attachments and the project's model and effort; `gcf-harness-aif-ext` ≥ 0.14 for the run gate's refusal before the click (an older one: the click is gated, as before)
12
+ - for board v2 (0.9): `gcf-aif-ext` ≥ 0.13 for an item's History, `needs`, the design units, filters and lanes; `gcf-harness-aif-ext` ≥ 0.13 for past runs and a run's model and effort. On older ones these hide or say which version they need
13
+ - gcf-board 0.2 needs `gcf-aif-ext` ≥ 0.7 (priority, questions, session marks, `run_mode`)
14
+
15
+ ## Run
16
+
17
+ ```bash
18
+ npm i -g gcf-board
19
+ gcf-board # http://127.0.0.1:4317
20
+ gcf-board --port 4400
21
+ gcf-board --version # the installed version
22
+ ```
23
+
24
+ It opens the board in your browser (the URL with the token, `http://127.0.0.1:4317/?t=<token>`, is printed too; `--no-open` skips the browser). Started again while it runs, it just opens the running board. Add a project by its folder (one that has `gcf/`) under **Projects**.
25
+
26
+ **Desktop shortcut**: run once
27
+
28
+ ```bash
29
+ gcf-board shortcut # or: gcf-board shortcut --port 4400
30
+ ```
31
+
32
+ It puts **GCF Board** on the desktop (Windows: a shortcut whose server console starts minimized; macOS: `GCF Board.command`; Linux: an application entry). Double-click it: the board starts and opens, or opens if it already runs. Run the command again after moving Node.js.
33
+
34
+ ## What it does
35
+
36
+ The board knows no domain by name: the project's board read gives its columns, moves with their forms, item fields, blocks and Help terms (`domain`, Board-PRD decision 16). The page follows design B (`docs/design/mockup`): a left nav with the project switcher (add a project, take one off the board), the screens **Command**, **Board**, **Chat**, **Inbox**, **Runs**, **Playtest**, **Ended**, **Agent**, **Settings** and **Metrics** (a domain without a block has no screen for it, a project without a harness no Runs and no Metrics), and a header with the phase, the runs, the limit wait, the quota, WIP, the release, **waiting for me**, **+ item** and **?**. The project and the screen are in the URL hash. On a phone a bottom bar holds Command, Board, Chat, Inbox and More. When the server is gone, the page says so and reconnects by itself. For a GCF project:
37
+
38
+ - **Command**: **waiting for me**, what only the operator moves on (Board-PRD §1.3), by group: failed run reports and a paused queue, a card waiting in a chat (a permission is answered right there, **Always** naming the rule it saves), D1 questions, the items to play and judge, to decide, to unblock (the columns the domain marks `human`), and a `paused: limit` item to resume. Beside it **Live**: the runs going on with their plan progress, **Follow** and **Stop**, the console runs and sessions, **Run next**, the queue, the run reports, and what the board did by itself.
39
+ - **Board**: columns ready, running, blocked, awaiting-verdict, awaiting-decision, unplayed, parked. A card shows the type, the gate, the plan progress (`2/5`), the severity, `verified`, the model, **needs N** and **needed by N**. A running card shows when its run log was last written (`active 12 s ago`), and `quiet 6 min` when the log has been silent for 5 minutes or more. A run's end report gives each item's cost when the agent reported it. Pointing at a card (or focusing it from the keyboard) lights up the cards it needs and the cards that need it, each saying how, and dims the rest. The toolbar (board 0.9.0, core 0.13.0) searches ids and titles, keeps **waiting for me**, filters by the fields the domain marks `filter` (GCF: type, gate, severity, system, milestone; several values at once, each a chip to take off) and lays the board out in lanes by a field it marks `group` (system, parent, milestone): an item with two systems stands in both lanes, one with none in **none**, a parent lane is named by the feature's title. The mouse drags the board sideways from its empty space; the wheel over a column with no scroll of its own pans it.
40
+ - **An item**: its file, its plan and its run log as it grows, its fields, and the moves the core offers for it (`items[].moves`, Methodology §4.1): run, verdict, decide, block, unblock, drop, close, submit, depends. Each move's form comes from the core; the core still checks the rest itself, and the board shows its answer. **Dependencies**: what it needs that has not ended in history (an item with its column, a design unit with its TBDs or the questions that block it, a graveyard line, an unknown id) and the items that need it, each a link; **Edit…** opens the picker of the board's items and design units (search by id and title, or type an id), and Save sends the `depends` move's adds and removes. **History** (core 0.13.0): its moves newest first, when, which, who (a run, your session, you; unknown on a commit older than the framework's marks), the commit and its subject; then its runs, as on the Runs screen. **Related**: its feature's other children, and the graveyard lines tagged with its system ("did we kill this before?"). An item that ended opens from **Ended** with its History.
41
+ - **Runs** (harness 0.13.0): what runs now with the run's model and effort, its last log lines, **Whole log** and **Stop**; the queue with what each item will run on; the past runs of the harness's run log, newest first, 50 at a time: start, end, mode, cost, and per item its result word, the reason word for word, cost, tokens, turns, handoffs, a broken step and what it ran on. **log** opens the part of the item's log that run wrote, **chat** that run's chat. Every start the operator asks for (Run selected, Run next, a drop on running, this screen) asks first with a model and effort picker for that run only (**default: each item's own**); the drawer's Run is one click. An older harness shows the active runs only, and the dialog has no pickers. The API: `GET /api/p/<project>/runs/past?limit=` (`gcf-harness runs --json`; 404 without a harness that keeps them), `GET …/item/<id>/history` (`{id, moves, runs}`), `GET …/log/<id>?from=&to=` (a past run's part, once: `{text, cut}`, at most its last 2 MB; without `from` and `to` the log as it grows), `POST …/run` with `model` and `effort`, `POST …/inbox/<entry>/draft` (`{thread, created}`).
42
+ - **Drag**:
43
+ - a ready card into **running** starts its run;
44
+ - a blocked or parked card into **ready** unblocks it;
45
+ - a card onto **graveyard** drops it.
46
+
47
+ Every other move is a button.
48
+ - **Run**: **run** on an item, or select ready cards and **Run selected**. It starts `ai-factory gcf-harness run <ids> --json` in the project's run mode:
49
+ - `run_mode: worktree`: one worktree and one agent session per item, all at once, then the integrator;
50
+ - `run_mode: main`: one item at a time in the project folder. A run asked for meanwhile waits in the board's **queue**; **remove from queue** takes it out.
51
+
52
+ A run asks first: it spends the subscription. **Stop** on a running item ends its session; the item stays ready and its work is kept. **Stop** during the wait for the usage limit's reset leaves the item **paused: limit** with its reset, and the queue goes on. A queued main run that the next one would repeat (the harness did not start, or another run works the checkout) pauses the queue: the header shows **queue paused — resume**; fix the cause, then resume. A card marked **interrupted** had a run that stopped (a timeout, a stop, a crash, the usage limit): **resume** continues its agent session with all its context, **start fresh** drops it. After the usage limit the run itself waits for the reset and goes on in the same session (harness 0.12): the card reads **limit: resumes HH:MM**, and **Stop** ends the wait. A run that could not wait (the week's limit, an unknown reset) ends **paused: limit** and pauses the main queue; **resume** on the header goes on after the reset. When a run ends, a report card lists each item's result and stays until closed, across page reloads. **What the board did by itself** lists its automatic acts with their times: a usage limit, a context handoff, the queue paused, resumed or started. A run confirmation names what each interrupted item picks up. The header shows the usage limit as the last run read it, from the newest `.gcf-session/runs/quota.json` of the board's projects: `quota 19% left · resets 03:00`, the window with the least left, every window in its tooltip; `quota ?` before any reading, or once every window has reset since. The queue, its pause, the reports and that list live in the board home too (`~/.gcf/queue.json`, board 0.10): a board started again goes on with them. It first takes in its runs; then a queue not paused, with no main run going, goes on (`queue-restored` in the list); a run that died while the board was down (a restart of the machine) pauses it, and a limit's pause shows its reset time. Two boards on one home both go on with the same queue: start one. A run itself outlives the board: closing it or Ctrl+C in its console leaves the run going, and the board started again shows it running, then its report (a run in flight keeps its record in `~/.gcf/runs/`).
53
+ - **Who runs it** (core 0.7.13): a running card tells a console run and **your session** (a `gcf claim` mark) from the board's own run; a session offers **release mark** instead of **stop**. A ready card whose dependencies are not built yet shows **waits for <dep>**; the drawer shows when an item began to wait (`since_at`).
54
+ - **Run next N independent**: the framework's gate picks the ready items that can run together now, by priority, and the board runs them after asking.
55
+ - **Priority**: drop a ready card on another to put it before; the column's ranks are committed (`gcf prioritize`).
56
+ - **Questions**: each D1 shows its question and proposed answer; **Answer** writes yours into its record (`gcf question answer`), and the next agent on its units puts it in place.
57
+ - **New item**: `gcf item new … --commit`, its form from the core: a bug asks its severity, a release its version and channel. The item's `model` and `effort` go to its run.
58
+ - **Help** (**?**): the domain's terms, columns, moves and field values with what each means, and the words of runs, under one filter.
59
+ - **Settings**: the keys of `gcf/config.yml` and the agents' language (`language.ui`, `language.artifacts` of `.ai-factory/config.yaml`), by the core's groups, each a `gcf config set` commit.
60
+ - **Agent**: the deny groups to tick, the rules the ticked groups add, the operator's own deny rules (add, remove) and the allow rules of `agent.allow`, apart; the context limits, read only.
61
+ - **An item's chat** (its drawer's **Chat** tab; harness 0.11.1, core 0.11.1): every run the board starts keeps its agent sessions open; the project's `chat:` settings (Settings: `chat.ask`, `chat.answer_timeout_min`) say what the agent asks and how long a question waits. The tab shows the run's chat, then the item's own thread of the project chat: the talk, question cards (picks, several questions, **Submit**), the run's milestones, its sessions, the limit wait, the context share. A message goes where the server puts it: the live run (its limit wait too), else the item's thread, and the line under the box says where it went. `GET /api/p/<project>/chat/<id>` follows the item's chat from its start, in raw chunks of JSON lines (the page splits them). `POST` there sends `{type: 'say', text, images?, attach?}`, `{type: 'interrupt'}` or `{type: 'answer', request_id, answers}` through `gcf-harness chat`; with no live run a message goes to the item's thread (answer `{talk}`), else a message with no session to read it gets 409, bad input 400. `attach` (`[{kind: item | unit | file, ref}]`) goes into the message's text as a line the agent reads; a design unit (the composer's **+ unit**, from the board read's `units`) goes as `unit <id> (<file>)`. `GET /api/p/<project>/chat/<id>/att/<file>` serves a chat picture; **attach to item…** under a picture gives it to an item (`gcf item attach`).
62
+ - **Functional base A** (board 0.10.0, core and harness 0.14.0; docs/Base-A-Plan.md): Settings has `session_timeout_min` and the project's `agent.model` / `agent.effort` (suggested from the agent's presets); the drawer shows the project's model on an item without its own, "(project)". The drawer's Run is off with the run gate's reason when the gate refuses the item now, and the start dialog marks each refused item and runs the rest (`GET /api/p/<project>/gate?ids=` runs `gcf-harness gate --each`). An item's attachments and an inbox entry's pictures are links (`GET /api/p/<project>/attachment?path=`: only `gcf/work/<id>/attachments/` and `gcf/inbox/in-<hex>/attachments/`, no `..`, no link on the way, a picture shown, any other file a download, `nosniff` and `default-src 'none'`), and a picture or link in File or Plan that points there loads through it. A permission card for one MCP tool offers Always, saying it allows every call of the tool with any arguments.
63
+ - **Model and effort** (board 0.8.0, core 0.12.3): pickers in the New item form, in the drawer (**change** beside the model and effort, and **model / effort** under **More**) and in a thread's composer: **default** (the agent picks), the agent's presets, or an own word. An item's next run takes them; a thread's next session does (`chats/<t>/agent.json`), and its line in the chat says so.
64
+ - **Project chat** (the **Chat** screen; core 0.12): threads of an agent in the project's folder, listed newest first and filtered by their item; a new thread is made when its first message is sent. Each thread is run by the bundled session engine (`gcf-session`) through the same detached relay as runs. It asks a card before each edit, git command and framework move (**allow once**, **always** — saved in `.claude/settings.local.json`; the card says saved only when it was — or **deny**); a new item it proposes through the board's MCP server `gcf` (tool `propose_item_new`, asked with no card: the proposal card is the question), the proposal card shows every field it proposed, and the operator's **Create** makes it with `POST /move` (`proposal: {talk, id}`), **Edit…** first in the new-item form. A thread's list entry names the card that waits in it and its limit wait (`card`, `limit_until`); a running item names the card of its run's chat (`chat_card`). A long talk hands over to a fresh agent from a summary; an idle agent closes after `chat.answer_timeout_min` (0 means 15) and the next message resumes it. Each item has at most one thread: a message to an item with no live run goes there. `GET /api/p/<project>/talks[?item=]` lists the threads with their proposals' states; `POST` there makes one (`{item?}`); `GET /api/p/<project>/talk/<t>` follows a thread's events; `POST` there sends `say`, `interrupt`, `answer`, `allow`, `deny` or `handoff`; `POST …/talk/<t>/stop` is the composer's **close agent** (board 0.8.1): the thread's agent ends with everything it started, or its limit wait does, and what it had not taken in is dropped with a "not sent" line; the next message resumes the talk; `GET …/talk/<t>/att/<file>` serves its pictures. The files live in `.gcf-session/chats/` (docs/Chat-Plan.md §3).
65
+ - **Inbox**: add an entry (Enter adds, Shift+Enter breaks the line; its source and tags), tag it, erase it, or turn it into an item (its first line the title, the rest the note); search the entries, filter them by tag and by lesson kind. The D1 questions and the agent's D2 assumptions are listed there too. **Draft with agent** opens a project chat thread bound to the entry and sends "Draft an item from inbox entry <id>:" with its text; a second click opens the same thread. The first proposal's **Create** takes the entry (it is erased); a later one makes an item with no entry. Off while the usage limit holds.
66
+ - **Keys**: `/` search, `i` a new inbox entry, `n` a new item, `j` / `k` between cards, Enter opens one, `r` runs the focused card (it asks), `1`–`7` a column, `?` Help, Esc closes a dialog, Help or the drawer; none while a field has the focus.
67
+ - **Lessons** (core 0.7.10, harness 0.9.2): what got in an agent's way, asked at the end of each session, lands in the inbox with its kind (`tool`, `rules`, `framework`, `template`, `other`) and its item. The inbox filters them; a card shows `N lessons`, and the drawer lists the item's lessons with the inbox's buttons. A run's report line ends with `, N lessons`, and with `— code written outside aif-implement` when a session skipped that skill.
68
+ - **Playtest**: `gcf playtest session` with the checklist grouped by subsystem; keep, tune or kill each item from the list. **Build** runs `dod.build`. A note goes to the inbox as `--source playtest`.
69
+ - **Ended**: history (accepted) and graveyard (killed, dropped, won't-fix); a line opens the item's History.
70
+ - **Metrics**: `gcf-harness metrics --json` of the project — how many runs reached submit or close, what they cost, handoffs, plan checks, DoD attempts, guard firings, block reasons — and, with harness 0.9.5, the cost per item over all its runs and per week and day.
71
+
72
+ The page updates by itself: the server watches each project's `gcf/` and `.gcf-session/runs/`.
73
+
74
+ ## Security
75
+
76
+ The board starts agents that write code and commit: whoever can talk to it runs code on this machine.
77
+
78
+ - It listens on `127.0.0.1` only.
79
+ - The token, kept in `~/.gcf/board-token`, opens the board once per server start; delete that file to make a new one. The browser then holds a session cookie that dies with the server: a browser sends a `127.0.0.1` cookie to every local port, so the cookie is never the token.
80
+ - Started while another program holds its port, it refuses rather than hand the token to that program.
81
+ - A request must also name host `127.0.0.1` or `localhost` with the board's port.
82
+ - A change must come from the board's own page (`Origin`). This blocks another site in the same browser.
83
+ - Commands run without a shell: the operator's text reaches `ai-factory` as one argument, never as a command line.
84
+ - The API shows only item files, plans and run logs inside a project.
85
+ - A project chat's agent may not read the board's folder (`~/.gcf`, the token's): not by read, search or a shell command that names it. A command that spells the path another way still could; a separate secret for a card's answer comes with remote access.
86
+
87
+ Do not put the port on a network. Remote and phone access is planned for v2, behind its own authentication.
88
+
89
+ ## Files
90
+
91
+ - `~/.gcf/projects.json`: the projects on the board, `{projects: [{name, path}]}`.
92
+ - `~/.gcf/board-token`: the token.
93
+ - `~/.gcf/runs/`: the record of each run in flight, which a board started again finds.
94
+ - `GCF_BOARD_HOME` moves them all; `GCF_BOARD_AIF` points at another `ai-factory` entry script; `GCF_SESSION_AGENT` puts another agent command in place of `claude` in project chats (tests).
95
+
96
+ ## Roadmap (v2)
97
+
98
+ - **Phone and remote access**: Tailscale or Claude Remote Control, with their own authentication; push notifications when an item blocks or waits for a verdict.
99
+
100
+ ## Develop
101
+
102
+ ```bash
103
+ npm install
104
+ npm test # server and web tests on Node's type stripping
105
+ npm run typecheck
106
+ npm run build # vite → dist/web, tsc → dist/server
107
+ node dist/server/main.js --port 4318
108
+ ```
@@ -6,8 +6,9 @@
6
6
  import { execFile } from 'node:child_process';
7
7
  import { randomBytes } from 'node:crypto';
8
8
  import { createServer } from 'node:http';
9
- import { existsSync, statSync, writeFileSync } from 'node:fs';
10
- import { lstat, mkdtemp, readFile, rm } from 'node:fs/promises';
9
+ import { createReadStream, existsSync, statSync, writeFileSync } from 'node:fs';
10
+ import { lstat, mkdtemp, readFile, rm, stat } from 'node:fs/promises';
11
+ import { pipeline } from 'node:stream/promises';
11
12
  import os from 'node:os';
12
13
  import path from 'node:path';
13
14
  import { BOARD_SCHEMA, } from '../shared/board.js';
@@ -15,11 +16,11 @@ import { admit, cookieName, hostAllowed, tokenInUrl } from './auth.js';
15
16
  import { briefError, runCli } from './cli.js';
16
17
  import { broadcast, planRev, subscribe, watchProject } from './events.js';
17
18
  import { attachesUnit, CHAT_BODY_MAX, chatInput, IMAGE_EXT, talkInput, } from './chat.js';
18
- import { follow, followLog, logPart, readShown, shownShape } from './files.js';
19
+ import { attachmentOf, follow, followLog, logPart, readShown, shownShape } from './files.js';
19
20
  import { HttpError } from './http-error.js';
20
21
  import { isCenterMove, moveArgs, moveInput, runIds } from './moves.js';
21
22
  import { addProject, listProjects, projectOf, removeProject } from './registry.js';
22
- import { adoptRuns, closeReport, forgetProject, resumeQueue, runsOf, startRun, unqueue, } from './runs.js';
23
+ import { adoptRuns, keepProjects, closeReport, forgetProject, resumeQueue, runsOf, startRun, unqueue, } from './runs.js';
23
24
  import { acceptProposal, agentPresets, chatCard, chatOf, entryTalk, listTalks, openTalk, pickTalk, prepareTalk, startTalk, stopTalk, talkEntry, talkId, talkLive, talkSaid, talkWaits, watchTalks, writeTalk, } from './talks.js';
24
25
  import { threadDir, threadOfEntry } from 'gcf-session';
25
26
  const send = (res, status, body) => {
@@ -47,6 +48,23 @@ async function bodyOf(req, limit = 1_000_000) {
47
48
  throw new HttpError(400, 'the body must be a JSON object');
48
49
  }
49
50
  }
51
+ /**
52
+ * A file of the project, never read as a page: no type sniffing, no script, no fetch from it;
53
+ * streamed, as an attachment may be large. `disposition`: a download's, for one not a picture.
54
+ */
55
+ async function sendFile(res, type, file, disposition = null) {
56
+ const { size } = await stat(file);
57
+ res.writeHead(200, {
58
+ 'content-type': type,
59
+ 'content-length': size,
60
+ 'cache-control': 'private',
61
+ 'x-content-type-options': 'nosniff',
62
+ 'content-security-policy': "default-src 'none'",
63
+ ...(disposition ? { 'content-disposition': disposition } : {}),
64
+ });
65
+ // A read that breaks after the head is sent can only cut the answer short.
66
+ await pipeline(createReadStream(file), res).catch(() => res.destroy());
67
+ }
50
68
  /** Parse the JSON a command printed, or say what it printed instead. */
51
69
  function jsonOf(r, what) {
52
70
  try {
@@ -142,6 +160,8 @@ export function createApp(o) {
142
160
  let closed = false;
143
161
  const watchAll = async () => {
144
162
  const projects = await listProjects();
163
+ // The kept queues of projects no longer on the board go: one added back starts empty.
164
+ keepProjects(projects.map((p) => p.name));
145
165
  // A watcher set up after the server closed would keep the process alive.
146
166
  if (closed)
147
167
  return;
@@ -157,6 +177,8 @@ export function createApp(o) {
157
177
  }
158
178
  };
159
179
  const cli = (p, args, timeout, input) => runCli(o.entry, p.path, args, timeout, input);
180
+ // The run gate's answers being worked out, by project and ids (GET …/gate).
181
+ const gates = new Map();
160
182
  // The last domain each project's board read gave: an item move is built from its form.
161
183
  const domains = new Map();
162
184
  /**
@@ -344,12 +366,47 @@ export function createApp(o) {
344
366
  const file = path.join(att, m[3]);
345
367
  for (const f of [session, path.dirname(att), att, file]) {
346
368
  const st = await lstat(f).catch(() => null);
347
- if (!st || st.isSymbolicLink())
369
+ if (!st || st.isSymbolicLink() || (f === file && !st.isFile()))
348
370
  throw new HttpError(404, `no picture ${m[3]}`);
349
371
  }
350
372
  const type = m[4] === 'jpg' ? 'jpeg' : m[4];
351
- res.writeHead(200, { 'content-type': `image/${type}`, 'cache-control': 'private' });
352
- res.end(await readFile(file));
373
+ await sendFile(res, `image/${type}`, file);
374
+ },
375
+ ],
376
+ [
377
+ // A file given to an item or an inbox entry (`gcf item attach`, an entry's pictures).
378
+ 'GET',
379
+ /^\/api\/p\/([^/]+)\/attachment$/,
380
+ async (_req, res, m, url) => {
381
+ const p = await projectOf(m[1]);
382
+ const rel = url.searchParams.get('path') ?? '';
383
+ const { file, type, download } = await attachmentOf(p.path, rel);
384
+ // RFC 5987: encodeURIComponent leaves ' ( ) * and ! as they are.
385
+ const name = encodeURIComponent(path.basename(file)).replace(/['()*!]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
386
+ await sendFile(res, type, file, download ? `attachment; filename*=UTF-8''${name}` : null);
387
+ },
388
+ ],
389
+ [
390
+ // The run gate of each named item (none: every ready one) alone now (Board-PRD §5.3):
391
+ // what a Run would be refused for, before the click. An older harness: nothing known.
392
+ 'GET',
393
+ /^\/api\/p\/([^/]+)\/gate$/,
394
+ async (_req, res, m, url) => {
395
+ const p = await projectOf(m[1]);
396
+ const names = (url.searchParams.get('ids') ?? '').split(',').filter(Boolean);
397
+ const ids = names.length ? runIds({ ids: names }) : [];
398
+ const harness = await harnessOf(p);
399
+ // One audit for the same question at once: a drawer and a dialog may ask together.
400
+ const key = `${p.name}/${ids.join(',')}`;
401
+ let asked = gates.get(key);
402
+ if (!asked) {
403
+ asked = cli(p, [harness, 'gate', '--each', ...ids, '--json']).finally(() => gates.delete(key));
404
+ gates.set(key, asked);
405
+ }
406
+ const r = await asked;
407
+ if (!r.ok && /unknown option '--each'/.test(r.err))
408
+ return send(res, 200, { items: {} });
409
+ send(res, 200, jsonOf(r, `${harness} gate --each`));
353
410
  },
354
411
  ],
355
412
  [
@@ -502,12 +559,11 @@ export function createApp(o) {
502
559
  const chats = path.dirname(td);
503
560
  for (const f of [path.dirname(chats), chats, td, path.dirname(file), file]) {
504
561
  const st = await lstat(f).catch(() => null);
505
- if (!st || st.isSymbolicLink())
562
+ if (!st || st.isSymbolicLink() || (f === file && !st.isFile()))
506
563
  throw new HttpError(404, `no picture ${m[3]}`);
507
564
  }
508
565
  const type = m[4] === 'jpg' ? 'jpeg' : m[4];
509
- res.writeHead(200, { 'content-type': `image/${type}`, 'cache-control': 'private' });
510
- res.end(await readFile(file));
566
+ await sendFile(res, `image/${type}`, file);
511
567
  },
512
568
  ],
513
569
  [
@@ -1,3 +1,4 @@
1
+ import { renameSync, rmSync, writeFileSync } from 'node:fs';
1
2
  import { rename, writeFile } from 'node:fs/promises';
2
3
  /** Write a file whole or not at all: a crash mid-write leaves the old one, never a torn one. */
3
4
  export async function writeAtomic(file, text, mode) {
@@ -5,3 +6,26 @@ export async function writeAtomic(file, text, mode) {
5
6
  await writeFile(tmp, text, { mode });
6
7
  await rename(tmp, file);
7
8
  }
9
+ // What a rename over a file another process holds open meets on Windows (a scanner, an indexer).
10
+ const HELD = new Set(['EPERM', 'EACCES', 'EBUSY']);
11
+ /**
12
+ * The same, at once: for state written as it changes, where two writes must not interleave. A
13
+ * file held for a moment is tried again for up to half a second; then the error goes up and the
14
+ * temporary file goes.
15
+ */
16
+ export function writeAtomicSync(file, text) {
17
+ const tmp = `${file}.${process.pid}.tmp`;
18
+ writeFileSync(tmp, text);
19
+ for (let i = 0;; i++)
20
+ try {
21
+ renameSync(tmp, file);
22
+ return;
23
+ }
24
+ catch (e) {
25
+ if (!HELD.has(e.code ?? '') || i >= 10) {
26
+ rmSync(tmp, { force: true });
27
+ throw e;
28
+ }
29
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
30
+ }
31
+ }
@@ -1,8 +1,9 @@
1
1
  // The files a board shows: an item, its plan, its run log. Only those shapes (or a plan an item
2
2
  // links), only inside the project, symlinks resolved: the API is not a way to read the disk.
3
- import { realpath, readFile, stat, open } from 'node:fs/promises';
3
+ import { lstat, realpath, readFile, stat, open } from 'node:fs/promises';
4
4
  import path from 'node:path';
5
5
  import { StringDecoder } from 'node:string_decoder';
6
+ import { attachedShape } from '../shared/board.js';
6
7
  import { HttpError } from './http-error.js';
7
8
  import { openStream } from './events.js';
8
9
  const SHOWN = [
@@ -119,3 +120,31 @@ export function follow(root, file, res, whole) {
119
120
  const timer = setInterval(tick, 1000);
120
121
  res.on('close', () => clearInterval(timer));
121
122
  }
123
+ const PICTURE = /\.(png|jpe?g|gif|webp)$/i;
124
+ /**
125
+ * An attachment of the project to hand out: its absolute path, its type, and whether it goes as
126
+ * a download. Refused, as a 404: a path of another place, one with `..`, a backslash, a drive or
127
+ * a stream (`:`), a NUL, or a link (a junction too) anywhere on it from the project's root, and
128
+ * one that resolves outside the project. A picture shows (svg is none: it may hold a script);
129
+ * any other file goes as a download. A hard link is not seen: it is the file it names.
130
+ */
131
+ export async function attachmentOf(root, rel) {
132
+ const no = () => new HttpError(404, `no attachment ${rel}`);
133
+ if (!attachedShape(rel) || /[\\:\0]/.test(rel))
134
+ throw no();
135
+ const parts = rel.split('/');
136
+ if (parts.some((s) => s === '' || s === '.' || s === '..'))
137
+ throw no();
138
+ for (let i = 1; i <= parts.length; i++) {
139
+ const st = await lstat(path.join(root, ...parts.slice(0, i))).catch(() => null);
140
+ if (!st || st.isSymbolicLink() || (i === parts.length && !st.isFile()))
141
+ throw no();
142
+ }
143
+ const file = path.join(root, ...parts);
144
+ if (!(await inside(root, file)))
145
+ throw no();
146
+ const ext = PICTURE.exec(rel)?.[1].toLowerCase();
147
+ return ext
148
+ ? { file, type: `image/${ext === 'jpg' ? 'jpeg' : ext}`, download: false }
149
+ : { file, type: 'application/octet-stream', download: true };
150
+ }