gcf-aif-ext 0.10.0 → 0.11.1
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 +23 -4
- package/commands/gcf.js +106 -57
- package/extension.json +1 -1
- package/lib/audit-core.js +46 -6
- package/lib/board.js +31 -13
- package/lib/config-set.js +28 -2
- package/lib/context.js +11 -1
- package/lib/design-check.js +14 -4
- package/lib/domain.js +9 -2
- package/lib/gcf-paths.js +26 -2
- package/lib/git.js +11 -2
- package/lib/inbox.js +265 -108
- package/lib/index-gen.js +7 -4
- package/lib/integrate.js +45 -8
- package/lib/lessons.js +31 -15
- package/lib/main-lock.js +1 -1
- package/lib/safe-path.js +2 -1
- package/lib/session-mark.js +58 -9
- package/lib/transitions.js +2 -0
- package/lib/unit-ops.js +9 -2
- package/lib/validate-item.js +2 -0
- package/lib/work-ops.js +113 -15
- package/package.json +1 -1
- package/skills/gcf-triage/SKILL.md +10 -8
- package/templates/agents-block.md +6 -4
- package/templates/config.yml +7 -0
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
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
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
|
|
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
6
|
|
|
7
7
|
The methodology is [Methodology.md](https://github.com/VirtualMaestro/GCF/blob/main/docs/Methodology.md) (RU).
|
|
8
8
|
|
|
@@ -31,7 +31,7 @@ ai-factory gcf init # seeds gcf/, cnlp.config.json and .gitattributes
|
|
|
31
31
|
ai-factory gcf hooks-install # arms the pre-commit gate
|
|
32
32
|
```
|
|
33
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
|
|
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
35
|
|
|
36
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
37
|
|
|
@@ -50,6 +50,25 @@ Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook. Run `ai-f
|
|
|
50
50
|
|
|
51
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
52
|
|
|
53
|
+
### 0.11.1
|
|
54
|
+
|
|
55
|
+
- 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.
|
|
56
|
+
- `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.
|
|
57
|
+
- `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.
|
|
58
|
+
|
|
59
|
+
### 0.10.3
|
|
60
|
+
|
|
61
|
+
- `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.
|
|
62
|
+
|
|
63
|
+
### 0.10.2
|
|
64
|
+
|
|
65
|
+
- `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.
|
|
66
|
+
|
|
67
|
+
### 0.10.1
|
|
68
|
+
|
|
69
|
+
- `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.
|
|
70
|
+
- 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.
|
|
71
|
+
|
|
53
72
|
### 0.10.0
|
|
54
73
|
|
|
55
74
|
- `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.
|
|
@@ -115,7 +134,7 @@ On Windows, run `extension add` and `extension update` from PowerShell or cmd, n
|
|
|
115
134
|
|
|
116
135
|
- `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`.
|
|
117
136
|
- `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`.
|
|
118
|
-
- `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`).
|
|
137
|
+
- `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.
|
|
119
138
|
- `prioritize` leaves the rank of a ready item it does not name (a running one): the named items take the free ranks around it.
|
|
120
139
|
- `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.
|
|
121
140
|
- `/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.
|
|
@@ -217,7 +236,7 @@ Removal leaves `gcf/` and `cnlp.config.json` in place. It also leaves the pre-co
|
|
|
217
236
|
**A deterministic core** behind `ai-factory gcf …`:
|
|
218
237
|
|
|
219
238
|
- 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`
|
|
220
|
-
- inbox and snapshot — `inbox [add <text> | drop <in-id>]`, `live`, `live check`
|
|
239
|
+
- inbox and snapshot — `inbox [add <text> | add --text-file <path|-> | tag <in-id> | drop <in-id>]`, `live`, `live check`
|
|
221
240
|
- runs and play — `context`, `plan check <id>`, `verify <id>`, `playtest`, `playtest session [--build]`, `audit`
|
|
222
241
|
- project phase and board — `phase`, `phase next [--reason]`, `board [--json]` (everything a board shows, in one read)
|
|
223
242
|
- 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`
|
package/commands/gcf.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// CLI wrapper over the deterministic core (GCF-PRD §10.1): harness and human call
|
|
2
2
|
// the same functions. Registered by AIF via extension.json `commands`.
|
|
3
3
|
import { mkdir, copyFile, readFile, writeFile } from 'node:fs/promises';
|
|
4
|
-
import { existsSync } from 'node:fs';
|
|
4
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
5
5
|
import { spawnSync } from 'node:child_process';
|
|
6
6
|
import path from 'node:path';
|
|
7
7
|
import { fileURLToPath } from 'node:url';
|
|
@@ -124,13 +124,12 @@ const today = () => new Date().toISOString().slice(0, 10);
|
|
|
124
124
|
const UNION = [
|
|
125
125
|
'gcf/history.md merge=union',
|
|
126
126
|
'gcf/graveyard.md merge=union',
|
|
127
|
-
'gcf/inbox.md merge=union',
|
|
128
127
|
'gcf/.metrics/*.csv merge=union',
|
|
129
128
|
];
|
|
130
129
|
|
|
131
130
|
/**
|
|
132
|
-
* Two branches that end different lives may add their lines at the same spot of history.md
|
|
133
|
-
* graveyard.md
|
|
131
|
+
* Two branches that end different lives may add their lines at the same spot of history.md or
|
|
132
|
+
* graveyard.md: a union merge keeps both instead of a conflict whose "ours" loses
|
|
134
133
|
* one. Adds the missing rules to `<dir>/.gitattributes`; a project that ran an older init gets
|
|
135
134
|
* them on re-run.
|
|
136
135
|
*/
|
|
@@ -144,7 +143,7 @@ export async function unionAttributes(dir) {
|
|
|
144
143
|
}
|
|
145
144
|
|
|
146
145
|
async function seedSkeleton(root) {
|
|
147
|
-
for (const dir of ['design', 'work', 'systems', 'source', '.metrics']) {
|
|
146
|
+
for (const dir of ['design', 'work', 'systems', 'source', 'inbox', '.metrics']) {
|
|
148
147
|
await mkdir(path.join(root, dir), { recursive: true });
|
|
149
148
|
}
|
|
150
149
|
|
|
@@ -160,12 +159,10 @@ async function seedSkeleton(root) {
|
|
|
160
159
|
}
|
|
161
160
|
|
|
162
161
|
const { HISTORY_HEAD, GRAVEYARD_HEAD } = await lib('verdict-fs');
|
|
163
|
-
const { INBOX_HEAD } = await lib('inbox');
|
|
164
162
|
const { serializeLive } = await lib('live');
|
|
165
163
|
for (const [name, header] of [
|
|
166
164
|
['history.md', HISTORY_HEAD],
|
|
167
165
|
['graveyard.md', GRAVEYARD_HEAD],
|
|
168
|
-
['inbox.md', INBOX_HEAD],
|
|
169
166
|
['LIVE.md', serializeLive({ capabilities: [], knownIssues: [] })],
|
|
170
167
|
[
|
|
171
168
|
'open-questions.md',
|
|
@@ -729,6 +726,21 @@ function registerItem(gcf) {
|
|
|
729
726
|
});
|
|
730
727
|
console.log(`${r.item}${shortHash(r.hash)}`);
|
|
731
728
|
});
|
|
729
|
+
registerAttach(item);
|
|
730
|
+
}
|
|
731
|
+
|
|
732
|
+
function registerAttach(item) {
|
|
733
|
+
item
|
|
734
|
+
.command('attach <id>')
|
|
735
|
+
.description('Give an item a file: copied into gcf/work/<id>/attachments/ (commit)')
|
|
736
|
+
.requiredOption('--file <path>', 'the file, e.g. a chat image')
|
|
737
|
+
.option('--no-commit', 'skip the commit (tests only)')
|
|
738
|
+
.action(async (id, o) => {
|
|
739
|
+
const r = await (
|
|
740
|
+
await lib('work-ops')
|
|
741
|
+
).attachItem(process.cwd(), id, o.file, { commit: o.commit });
|
|
742
|
+
console.log(`${r.file}${shortHash(r.hash)}`);
|
|
743
|
+
});
|
|
732
744
|
}
|
|
733
745
|
|
|
734
746
|
function registerDepends(gcf) {
|
|
@@ -854,35 +866,41 @@ function registerDecide(gcf) {
|
|
|
854
866
|
}
|
|
855
867
|
|
|
856
868
|
/**
|
|
857
|
-
* An inbox
|
|
858
|
-
* commit
|
|
869
|
+
* An inbox move (`plan`: its files, the ones that may carry edits not yet committed, and how to
|
|
870
|
+
* make it); with `commit`, committed alone under the main lock — a board has no console to
|
|
871
|
+
* commit from. Entries added before without a commit ride along with it. Returns the commit
|
|
872
|
+
* hash, or null.
|
|
859
873
|
* @param {boolean | undefined} commit
|
|
860
874
|
* @param {string} message
|
|
861
|
-
* @param {
|
|
875
|
+
* @param {{files: string[], inputs?: string[], apply: () => Promise<unknown>}} plan
|
|
862
876
|
*/
|
|
863
|
-
async function inboxMove(commit, message,
|
|
864
|
-
const { gcfRoot } = await lib('gcf-paths');
|
|
865
|
-
const root = gcfRoot();
|
|
877
|
+
async function inboxMove(commit, message, plan) {
|
|
866
878
|
if (!commit) {
|
|
867
|
-
await
|
|
879
|
+
await plan.apply();
|
|
868
880
|
|
|
869
881
|
return null;
|
|
870
882
|
}
|
|
871
883
|
|
|
872
884
|
const { commitMove } = await lib('unit-ops');
|
|
873
|
-
const
|
|
885
|
+
const loose = (await lib('inbox')).untrackedEntries(process.cwd());
|
|
874
886
|
|
|
875
|
-
// Raw input (merge=union): lines added before without a commit ride along with this one.
|
|
876
887
|
return commitMove(process.cwd(), message, {
|
|
877
|
-
files: [
|
|
878
|
-
inputs: [
|
|
888
|
+
files: [...plan.files, ...loose],
|
|
889
|
+
inputs: [...(plan.inputs ?? plan.files), ...loose],
|
|
879
890
|
mutate: async () => {
|
|
880
|
-
await
|
|
891
|
+
await plan.apply();
|
|
881
892
|
},
|
|
882
893
|
commit: true,
|
|
883
894
|
});
|
|
884
895
|
}
|
|
885
896
|
|
|
897
|
+
/** A work/ branch's gcf/ state is main's: an inbox entry is tagged or erased on main. */
|
|
898
|
+
async function refuseOnWork(what) {
|
|
899
|
+
const { onWorkBranch } = await lib('unit-ops');
|
|
900
|
+
if (onWorkBranch(process.cwd()))
|
|
901
|
+
throw new Error(`${what} on main: a work/ branch records no inbox move`);
|
|
902
|
+
}
|
|
903
|
+
|
|
886
904
|
function registerInboxTag(inbox) {
|
|
887
905
|
inbox
|
|
888
906
|
.command('tag <in-id>')
|
|
@@ -891,34 +909,78 @@ function registerInboxTag(inbox) {
|
|
|
891
909
|
.option('--remove <tags>', 'tags to remove, comma-separated')
|
|
892
910
|
.option('--commit', 'commit it (gcf(inbox)): for a caller with no console, e.g. a board')
|
|
893
911
|
.action(async (id, o) => {
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
const
|
|
897
|
-
|
|
898
|
-
|
|
899
|
-
|
|
900
|
-
}));
|
|
912
|
+
await refuseOnWork('tag an entry');
|
|
913
|
+
const { planTag } = await lib('inbox');
|
|
914
|
+
const { gcfRoot } = await lib('gcf-paths');
|
|
915
|
+
const plan = await planTag(gcfRoot(), id, {
|
|
916
|
+
add: splitList(o.add),
|
|
917
|
+
remove: splitList(o.remove),
|
|
901
918
|
});
|
|
902
|
-
|
|
919
|
+
const hash = await inboxMove(o.commit, `gcf(inbox): tag ${id}`, plan);
|
|
920
|
+
console.log(`${id} tags: ${plan.tags.join(', ') || 'none'}${shortHash(hash)}`);
|
|
921
|
+
});
|
|
922
|
+
}
|
|
923
|
+
|
|
924
|
+
/** The text of `inbox add`: its argument, `--text`, or `--text-file` (`-`: stdin), one of them. */
|
|
925
|
+
function entryText(arg, o) {
|
|
926
|
+
const given = [arg, o.text, o.textFile].filter((x) => x !== undefined);
|
|
927
|
+
if (given.length !== 1)
|
|
928
|
+
throw new Error('give the entry once: as the argument, --text=<text> or --text-file <path|->');
|
|
929
|
+
if (o.textFile === undefined) return given[0];
|
|
930
|
+
const text = readFileSync(o.textFile === '-' ? 0 : o.textFile, 'utf8');
|
|
931
|
+
|
|
932
|
+
// A file Notepad saved starts with a byte-order mark.
|
|
933
|
+
return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
|
|
934
|
+
}
|
|
935
|
+
|
|
936
|
+
function registerInboxDrop(inbox) {
|
|
937
|
+
inbox
|
|
938
|
+
.command('drop <in-id>')
|
|
939
|
+
.description('Erase an entry: triaged as noise, a duplicate, or turned into an item')
|
|
940
|
+
.option('--commit', 'commit it (gcf(inbox)): for a caller with no console, e.g. a board')
|
|
941
|
+
.action(async (id, o) => {
|
|
942
|
+
await refuseOnWork('erase an entry');
|
|
943
|
+
const { planDrop } = await lib('inbox');
|
|
944
|
+
const { gcfRoot } = await lib('gcf-paths');
|
|
945
|
+
const plan = await planDrop(gcfRoot(), id);
|
|
946
|
+
const { inHead } = await lib('git');
|
|
947
|
+
const committed = inHead(process.cwd(), plan.files[0]);
|
|
948
|
+
// An entry never committed leaves nothing to commit: it is only erased, from the index too.
|
|
949
|
+
const hash = await inboxMove(o.commit && committed, `gcf(inbox): drop ${id}`, plan);
|
|
950
|
+
if (!committed)
|
|
951
|
+
spawnSync('git', ['rm', '--cached', '-q', '--ignore-unmatch', '--', ...plan.files], {
|
|
952
|
+
cwd: process.cwd(),
|
|
953
|
+
stdio: 'ignore',
|
|
954
|
+
});
|
|
955
|
+
console.log(`erased ${id}${shortHash(hash)}`);
|
|
903
956
|
});
|
|
904
957
|
}
|
|
905
958
|
|
|
906
959
|
function registerInbox(gcf) {
|
|
907
960
|
const inbox = gcf
|
|
908
961
|
.command('inbox')
|
|
909
|
-
.description('Raw input waiting for triage (gcf/inbox
|
|
962
|
+
.description('Raw input waiting for triage (gcf/inbox/, one file an entry); no commit')
|
|
910
963
|
.option('--json', 'machine output')
|
|
911
964
|
.action(async (o) => {
|
|
912
965
|
const { gcfRoot } = await lib('gcf-paths');
|
|
913
|
-
const
|
|
966
|
+
const { legacyInbox, listInbox } = await lib('inbox');
|
|
967
|
+
const root = gcfRoot();
|
|
968
|
+
if (legacyInbox(root))
|
|
969
|
+
console.error(
|
|
970
|
+
'gcf/inbox.md is the old one-line inbox: the core reads gcf/inbox/ only — move its ' +
|
|
971
|
+
"lines with ai-factory gcf inbox add (the operator's call), then delete it",
|
|
972
|
+
);
|
|
973
|
+
const list = await listInbox(root);
|
|
914
974
|
out(o.json, list, (l) =>
|
|
915
975
|
l.length
|
|
916
976
|
? l
|
|
917
977
|
.map((e) => {
|
|
918
978
|
const source = e.kind ? `lesson:${e.kind}:${e.item}` : e.source;
|
|
979
|
+
const more = e.text.split('\n').length - 1;
|
|
980
|
+
const lines = more ? ` (+${more} lines)` : '';
|
|
919
981
|
const tags = e.tags.length ? ` (tags: ${e.tags.join(', ')})` : '';
|
|
920
982
|
|
|
921
|
-
return `${e.id} [${source}] ${e.
|
|
983
|
+
return `${e.id} [${source}] ${e.title}${lines}${tags}`;
|
|
922
984
|
})
|
|
923
985
|
.join('\n')
|
|
924
986
|
: 'inbox empty',
|
|
@@ -926,36 +988,24 @@ function registerInbox(gcf) {
|
|
|
926
988
|
});
|
|
927
989
|
inbox
|
|
928
990
|
.command('add [text]')
|
|
929
|
-
.description('
|
|
991
|
+
.description('Add an entry: gcf/inbox/in-<id>.md; its first line is its title')
|
|
930
992
|
.option('--source <source>', 'playtest | ci | agent | operator', 'operator')
|
|
931
993
|
// A text that starts with a hyphen ("-5 fps on level 3") reads as a flag at every level of
|
|
932
994
|
// ai-factory's commands, `--` included: as `--text=<text>` it stays one value.
|
|
933
995
|
.option('--text <text>', 'the entry, when it starts with a hyphen')
|
|
996
|
+
.option('--text-file <path>', 'the entry from a file, - for stdin: several lines')
|
|
934
997
|
.option('--tags <tags>', 'its tags, comma-separated: idea, later, ui:hud')
|
|
935
998
|
.option('--commit', 'commit it (gcf(inbox)): for a caller with no console, e.g. a board')
|
|
936
999
|
.action(async (arg, o) => {
|
|
937
|
-
const text = o
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
const
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
id = (await addInbox(root, text, o.source, { tags: splitList(o.tags) })).id;
|
|
944
|
-
});
|
|
945
|
-
console.log(`${id}${shortHash(hash)}`);
|
|
1000
|
+
const text = entryText(arg, o);
|
|
1001
|
+
const { planAdd } = await lib('inbox');
|
|
1002
|
+
const { gcfRoot } = await lib('gcf-paths');
|
|
1003
|
+
const plan = planAdd(gcfRoot(), text, o.source, { tags: splitList(o.tags) });
|
|
1004
|
+
const hash = await inboxMove(o.commit, 'gcf(inbox): add', plan);
|
|
1005
|
+
console.log(`${plan.entry.id}${shortHash(hash)}`);
|
|
946
1006
|
});
|
|
947
1007
|
registerInboxTag(inbox);
|
|
948
|
-
inbox
|
|
949
|
-
.command('drop <in-id>')
|
|
950
|
-
.description('Erase an entry: triaged as noise, a duplicate, or turned into an item')
|
|
951
|
-
.option('--commit', 'commit it (gcf(inbox)): for a caller with no console, e.g. a board')
|
|
952
|
-
.action(async (id, o) => {
|
|
953
|
-
const { dropInbox } = await lib('inbox');
|
|
954
|
-
const hash = await inboxMove(o.commit, `gcf(inbox): drop ${id}`, (root) =>
|
|
955
|
-
dropInbox(root, id),
|
|
956
|
-
);
|
|
957
|
-
console.log(`erased ${id}${shortHash(hash)}`);
|
|
958
|
-
});
|
|
1008
|
+
registerInboxDrop(inbox);
|
|
959
1009
|
}
|
|
960
1010
|
|
|
961
1011
|
function registerLessons(gcf) {
|
|
@@ -981,7 +1031,7 @@ function registerLessons(gcf) {
|
|
|
981
1031
|
.option('--from <file>', 'a JSON array [{kind, text, where}] instead of --kind/--text')
|
|
982
1032
|
.option('--commit', 'commit it (gcf(lessons)): for a caller with no console, e.g. the harness')
|
|
983
1033
|
.action(async (id, o) => {
|
|
984
|
-
const {
|
|
1034
|
+
const { planLessons, lessonsFile, KINDS } = await lib('lessons');
|
|
985
1035
|
if (Boolean(o.from) === Boolean(o.text))
|
|
986
1036
|
throw new Error('give the lessons once: --from <file>, or --kind and --text');
|
|
987
1037
|
if (o.text && !KINDS.includes(o.kind)) throw new Error(`--kind must be ${KINDS.join(' | ')}`);
|
|
@@ -990,11 +1040,10 @@ function registerLessons(gcf) {
|
|
|
990
1040
|
: [{ kind: o.kind, text: o.text, where: o.where }];
|
|
991
1041
|
if (!Array.isArray(list)) throw new Error(`${o.from}: lessons must be a JSON array`);
|
|
992
1042
|
if (!list.length) return console.log(`recorded 0 lessons for ${id}`);
|
|
993
|
-
|
|
994
|
-
const
|
|
995
|
-
|
|
996
|
-
});
|
|
997
|
-
console.log(`recorded ${n} lessons for ${id}${shortHash(hash)}`);
|
|
1043
|
+
const { gcfRoot } = await lib('gcf-paths');
|
|
1044
|
+
const plan = planLessons(gcfRoot(), id, list);
|
|
1045
|
+
const hash = await inboxMove(o.commit, `gcf(lessons): ${id}`, plan);
|
|
1046
|
+
console.log(`recorded ${plan.entries.length} lessons for ${id}${shortHash(hash)}`);
|
|
998
1047
|
});
|
|
999
1048
|
}
|
|
1000
1049
|
|
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.
|
|
4
|
+
"version": "0.11.1",
|
|
5
5
|
"description": "Game Context Framework for AI Factory",
|
|
6
6
|
"skills": [
|
|
7
7
|
"skills/gcf-init",
|
package/lib/audit-core.js
CHANGED
|
@@ -10,8 +10,9 @@ import { buildLedger } from './ledger.js';
|
|
|
10
10
|
import { STORED } from './transitions.js';
|
|
11
11
|
import { openDepends } from './work-ops.js';
|
|
12
12
|
import { runHolder } from './main-lock.js';
|
|
13
|
-
import { sessionActive } from './session-mark.js';
|
|
13
|
+
import { markOwner, ownerOf, sessionActive } from './session-mark.js';
|
|
14
14
|
import { fieldOf } from './question-fields.js';
|
|
15
|
+
import { inboxProblems } from './inbox.js';
|
|
15
16
|
|
|
16
17
|
function git(args, cwd) {
|
|
17
18
|
// A blame of a long file overflows the 1 MiB default, and an overflow reads as a git failure.
|
|
@@ -23,6 +24,27 @@ function git(args, cwd) {
|
|
|
23
24
|
const UNTIL_RE = /\[until:\s*(verdict\([a-z0-9-]+\)|retune\([a-z0-9-]+\)|manual\([^)]*\))\]/g;
|
|
24
25
|
const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
25
26
|
|
|
27
|
+
/**
|
|
28
|
+
* Whether an item runs, and who works it (`running_by`): `run`, a harness run's live lock; `you`,
|
|
29
|
+
* a fresh session mark this session or its run owns (`GCF_RUN_OWNER`, else
|
|
30
|
+
* `CLAUDE_CODE_SESSION_ID`); `unowned`, a mark that names nobody (a claim takes it); `session`,
|
|
31
|
+
* another session's mark. Null when nobody does.
|
|
32
|
+
*/
|
|
33
|
+
function runningOf(projectDir, id) {
|
|
34
|
+
const held = () => {
|
|
35
|
+
if (runHolder(projectDir, id) !== null) return 'run';
|
|
36
|
+
if (!sessionActive(projectDir, id)) return null;
|
|
37
|
+
const mark = markOwner(projectDir, id);
|
|
38
|
+
if (!mark) return 'unowned';
|
|
39
|
+
|
|
40
|
+
return mark === ownerOf() ? 'you' : 'session';
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
const by = held();
|
|
44
|
+
|
|
45
|
+
return { running: by !== null, running_by: by };
|
|
46
|
+
}
|
|
47
|
+
|
|
26
48
|
/**
|
|
27
49
|
* @typedef {object} AuditReport
|
|
28
50
|
* @property {string} first_line
|
|
@@ -44,8 +66,10 @@ const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
|
44
66
|
* @property {number} [schema]
|
|
45
67
|
* @property {Array<{id: string, type: string, gate: string, status: string, system: string[],
|
|
46
68
|
* depends: string[], parent: string | null, tune_count: number, parallel: string,
|
|
47
|
-
* priority: number | null, running: boolean}>} [items]
|
|
69
|
+
* priority: number | null, running: boolean, running_by: string | null}>} [items]
|
|
48
70
|
* @property {{blocking: number, units: number, ready: number}} [design]
|
|
71
|
+
* @property {{legacy: boolean, bad_names: string[], untitled: string[], broken_links: string[],
|
|
72
|
+
* orphan_dirs: string[]}} inbox
|
|
49
73
|
*/
|
|
50
74
|
|
|
51
75
|
/**
|
|
@@ -85,6 +109,7 @@ export async function audit(projectDir) {
|
|
|
85
109
|
index_drift: await drifted(root),
|
|
86
110
|
illegal_status: [],
|
|
87
111
|
stale_questions: staleQuestions(projectDir, root, config),
|
|
112
|
+
inbox: await inboxProblems(root),
|
|
88
113
|
};
|
|
89
114
|
// The harness gate reads everything from this one report — it never parses gcf/ itself.
|
|
90
115
|
report.schema = config.schema;
|
|
@@ -99,9 +124,7 @@ export async function audit(projectDir) {
|
|
|
99
124
|
tune_count: c.data.tune_count ?? 0,
|
|
100
125
|
parallel: c.data.parallel ?? 'serial',
|
|
101
126
|
priority: c.data.priority ?? null,
|
|
102
|
-
|
|
103
|
-
running:
|
|
104
|
-
runHolder(projectDir, c.data.id) !== null || sessionActive(projectDir, String(c.data.id)),
|
|
127
|
+
...runningOf(projectDir, String(c.data.id)),
|
|
105
128
|
}));
|
|
106
129
|
const design = await designCheck(projectDir);
|
|
107
130
|
checkItems(report, items, config, { projectDir, ledger });
|
|
@@ -290,7 +313,12 @@ function untilRecords(items, systems, fired, questions) {
|
|
|
290
313
|
];
|
|
291
314
|
const until = [];
|
|
292
315
|
for (const doc of docs) {
|
|
293
|
-
|
|
316
|
+
// A quoted line (an inbox entry's text in a note:) holds no annotation, as for the gate.
|
|
317
|
+
const own = doc.body
|
|
318
|
+
.split('\n')
|
|
319
|
+
.filter((l) => !l.startsWith('>'))
|
|
320
|
+
.join('\n');
|
|
321
|
+
for (const m of own.matchAll(UNTIL_RE)) {
|
|
294
322
|
until.push({ file: `gcf/${doc.rel}`, trigger: m[1], status: untilStatus(m[1], fired) });
|
|
295
323
|
}
|
|
296
324
|
}
|
|
@@ -345,6 +373,18 @@ const docAlerts = (report) => [
|
|
|
345
373
|
Object.keys(report.linter).length && 'П2 linter findings in systems docs',
|
|
346
374
|
report.index_drift && 'INDEX drift (regenerate)',
|
|
347
375
|
report.design?.blocking && `${report.design.blocking} blocking design finding(s)`,
|
|
376
|
+
...inboxAlerts(report.inbox),
|
|
377
|
+
];
|
|
378
|
+
|
|
379
|
+
/** Alerts about gcf/inbox/: the old one-line file, files that are no entry, broken pictures. */
|
|
380
|
+
const inboxAlerts = (i) => [
|
|
381
|
+
i.legacy &&
|
|
382
|
+
'gcf/inbox.md is the old one-line inbox: the core reads gcf/inbox/ only — move its lines ' +
|
|
383
|
+
"with ai-factory gcf inbox add (the operator's call), then delete it",
|
|
384
|
+
i.bad_names.length && `${i.bad_names.length} file(s) in gcf/inbox/ are no entry`,
|
|
385
|
+
i.untitled.length && `${i.untitled.length} inbox entr(ies) without a title line`,
|
|
386
|
+
i.broken_links.length && `${i.broken_links.length} inbox picture link(s) lead nowhere`,
|
|
387
|
+
i.orphan_dirs.length && `${i.orphan_dirs.length} inbox picture folder(s) without their entry`,
|
|
348
388
|
];
|
|
349
389
|
|
|
350
390
|
/** @param {AuditReport} report */
|
package/lib/board.js
CHANGED
|
@@ -135,21 +135,36 @@ async function phaseOf(projectDir) {
|
|
|
135
135
|
|
|
136
136
|
/**
|
|
137
137
|
* The AI Factory extensions the project has, name → version, from `.ai-factory.json`: the board
|
|
138
|
-
* shows which framework packages a project runs. `{}` when the file is missing
|
|
138
|
+
* shows which framework packages a project runs. `extensions` is `{}` when the file is missing
|
|
139
|
+
* or unreadable;
|
|
140
|
+
* `error` says why a file that is there cannot be read: the run buttons hide with no harness.
|
|
139
141
|
*/
|
|
140
142
|
async function extensionsOf(projectDir) {
|
|
143
|
+
const file = path.join(path.resolve(projectDir), '.ai-factory.json');
|
|
144
|
+
let text;
|
|
141
145
|
try {
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
146
|
+
text = await readFile(file, 'utf8');
|
|
147
|
+
} catch (e) {
|
|
148
|
+
return { extensions: {}, error: e.code === 'ENOENT' ? null : e.message };
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
try {
|
|
152
|
+
const cfg = JSON.parse(text);
|
|
153
|
+
if (cfg === null || typeof cfg !== 'object' || Array.isArray(cfg))
|
|
154
|
+
throw new Error('it is not a JSON object');
|
|
155
|
+
const list = cfg.extensions ?? [];
|
|
156
|
+
if (!Array.isArray(list)) throw new Error('"extensions" is not a list');
|
|
157
|
+
|
|
158
|
+
return {
|
|
159
|
+
extensions: Object.fromEntries(
|
|
160
|
+
list
|
|
161
|
+
.filter((e) => typeof e?.name === 'string')
|
|
162
|
+
.map((e) => [e.name, typeof e.version === 'string' ? e.version : null]),
|
|
163
|
+
),
|
|
164
|
+
error: null,
|
|
165
|
+
};
|
|
166
|
+
} catch (e) {
|
|
167
|
+
return { extensions: {}, error: e.message };
|
|
153
168
|
}
|
|
154
169
|
}
|
|
155
170
|
|
|
@@ -294,7 +309,7 @@ export async function board(projectDir) {
|
|
|
294
309
|
const root = path.join(path.resolve(projectDir), 'gcf');
|
|
295
310
|
const ledger = await buildLedger(projectDir);
|
|
296
311
|
const verified = verifiedOf(projectDir);
|
|
297
|
-
const extensions = await extensionsOf(projectDir);
|
|
312
|
+
const { extensions, error: extensionsError } = await extensionsOf(projectDir);
|
|
298
313
|
const harness = hasHarness(extensions);
|
|
299
314
|
const items = [];
|
|
300
315
|
for (const c of ledger.items)
|
|
@@ -329,8 +344,11 @@ export async function board(projectDir) {
|
|
|
329
344
|
window: config.context_window,
|
|
330
345
|
compact_pct: config.auto_compact_pct,
|
|
331
346
|
},
|
|
347
|
+
// A run's chat with the operator (`chat:` in config.yml): what it asks, how long it waits.
|
|
348
|
+
chat: config.chat,
|
|
332
349
|
phase: await phaseOf(projectDir),
|
|
333
350
|
extensions,
|
|
351
|
+
extensions_error: extensionsError,
|
|
334
352
|
// A malformed block reads with fields missing (live check names it): null, not absent.
|
|
335
353
|
release: releaseOf(live.release),
|
|
336
354
|
// The domain as data (Board-PRD decision 16): its columns, blocks, fields, moves and terms.
|
package/lib/config-set.js
CHANGED
|
@@ -13,7 +13,15 @@ import YAML from 'yaml';
|
|
|
13
13
|
import { commitMove } from './unit-ops.js';
|
|
14
14
|
import { withMainLock } from './main-lock.js';
|
|
15
15
|
import { atomicWrite } from './safe-path.js';
|
|
16
|
-
import {
|
|
16
|
+
import {
|
|
17
|
+
CHAT_ASK,
|
|
18
|
+
CHAT_DEFAULTS,
|
|
19
|
+
configOf,
|
|
20
|
+
DEFAULT_CONFIG,
|
|
21
|
+
gcfRoot,
|
|
22
|
+
readRawConfig,
|
|
23
|
+
RUN_MODES,
|
|
24
|
+
} from './gcf-paths.js';
|
|
17
25
|
import { AIF_CONFIG, LANGUAGE_RE, languageIn, readAifConfig } from './aif-config.js';
|
|
18
26
|
|
|
19
27
|
/** @typedef {'number' | 'share' | 'mode' | 'command' | 'language'} Kind */
|
|
@@ -65,10 +73,26 @@ export const SETTINGS = [
|
|
|
65
73
|
{
|
|
66
74
|
key: 'run_mode',
|
|
67
75
|
kind: 'mode',
|
|
76
|
+
options: RUN_MODES,
|
|
68
77
|
label:
|
|
69
78
|
'how a run drives an item: worktree (several at once) or main (one at a time in the ' +
|
|
70
79
|
'project folder)',
|
|
71
80
|
},
|
|
81
|
+
{
|
|
82
|
+
key: 'chat.ask',
|
|
83
|
+
kind: 'mode',
|
|
84
|
+
options: CHAT_ASK,
|
|
85
|
+
label:
|
|
86
|
+
'what an agent run asks you by a question card: d1 (only your decisions), all (every ' +
|
|
87
|
+
'question of substance), none (nothing, it decides)',
|
|
88
|
+
},
|
|
89
|
+
{
|
|
90
|
+
key: 'chat.answer_timeout_min',
|
|
91
|
+
kind: 'number',
|
|
92
|
+
label:
|
|
93
|
+
'minutes a question waits for your answer before the agent takes its default (0: nobody ' +
|
|
94
|
+
'watches, as for a night run; a main run waits with its whole queue)',
|
|
95
|
+
},
|
|
72
96
|
{ key: 'dod.test', kind: 'command', label: "the project's test command for the DoD, or none" },
|
|
73
97
|
{ key: 'dod.build', kind: 'command', label: "the project's build command for the DoD, or none" },
|
|
74
98
|
{
|
|
@@ -127,6 +151,7 @@ function defaultOf(s, aif) {
|
|
|
127
151
|
const [head, sub] = s.key.split('.');
|
|
128
152
|
if (s.key === 'language.artifacts') return languageIn(aif, 'ui') ?? 'en';
|
|
129
153
|
if (s.kind === 'language') return 'en';
|
|
154
|
+
if (head === 'chat') return CHAT_DEFAULTS[sub];
|
|
130
155
|
if (sub) return null;
|
|
131
156
|
|
|
132
157
|
return head === 'run_mode' ? 'worktree' : (DEFAULT_CONFIG[head] ?? null);
|
|
@@ -177,7 +202,8 @@ function valueOf(setting, text) {
|
|
|
177
202
|
}
|
|
178
203
|
|
|
179
204
|
if (setting.kind === 'mode') {
|
|
180
|
-
|
|
205
|
+
const options = setting.options ?? [];
|
|
206
|
+
if (!options.includes(t)) throw new Error(`${setting.key} must be ${options.join(' | ')}`);
|
|
181
207
|
|
|
182
208
|
return t;
|
|
183
209
|
}
|
package/lib/context.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { readFile } from 'node:fs/promises';
|
|
1
|
+
import { readFile, readdir } from 'node:fs/promises';
|
|
2
2
|
import { existsSync } from 'node:fs';
|
|
3
3
|
import path from 'node:path';
|
|
4
4
|
import { listItems, listSystems, readConfig, tokensEst } from './gcf-paths.js';
|
|
@@ -60,6 +60,16 @@ async function readsetFiles(root, item, items) {
|
|
|
60
60
|
}
|
|
61
61
|
|
|
62
62
|
await push(`work/${item.name}`);
|
|
63
|
+
// The files the human gave the item (`gcf item attach`): read, not counted against the budget,
|
|
64
|
+
// which measures text.
|
|
65
|
+
const attached = path.join(root, 'work', String(item.data.id), 'attachments');
|
|
66
|
+
if (existsSync(attached))
|
|
67
|
+
for (const e of await readdir(attached, { recursive: true, withFileTypes: true })) {
|
|
68
|
+
if (!e.isFile()) continue;
|
|
69
|
+
const rel = path.relative(root, path.join(e.parentPath, e.name)).replaceAll('\\', '/');
|
|
70
|
+
files.push({ path: `gcf/${rel}`, tokens_est: 0 });
|
|
71
|
+
}
|
|
72
|
+
|
|
63
73
|
const parent = items.find((c) => c.data.id === item.data.parent);
|
|
64
74
|
if (parent) await push(`work/${parent.name}`);
|
|
65
75
|
for (const depId of item.data.depends ?? []) {
|
package/lib/design-check.js
CHANGED
|
@@ -589,13 +589,23 @@ export function pathTo(graph, from, to, seen = new Set()) {
|
|
|
589
589
|
return null;
|
|
590
590
|
}
|
|
591
591
|
|
|
592
|
-
/**
|
|
593
|
-
|
|
594
|
-
|
|
592
|
+
/**
|
|
593
|
+
* Why a depends `cycle` (its ids, the first again at the end) never gets played. The feature
|
|
594
|
+
* hint only when a step of the cycle is a feature waiting for a child: one in its `children`,
|
|
595
|
+
* or a new one the move is about to add (`children`, [feature, child] pairs).
|
|
596
|
+
*/
|
|
597
|
+
export function cycleMessage(ledger, cycle, children = []) {
|
|
598
|
+
const childStep = cycle.slice(1).some((to, i) => {
|
|
599
|
+
const from = cycle[i];
|
|
600
|
+
const item = ledger.item(from);
|
|
601
|
+
const kids = item?.data.type === 'feature' ? (item.data.children ?? []) : [];
|
|
602
|
+
|
|
603
|
+
return kids.includes(to) || children.some(([f, c]) => f === from && c === to);
|
|
604
|
+
});
|
|
595
605
|
|
|
596
606
|
return (
|
|
597
607
|
`depends cycle ${cycle.join(' -> ')}: none of them can be played first` +
|
|
598
|
-
(
|
|
608
|
+
(childStep ? ' (a feature waits for its children)' : '')
|
|
599
609
|
);
|
|
600
610
|
}
|
|
601
611
|
|