gcf-aif-ext 0.11.1 → 0.12.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 CHANGED
@@ -50,6 +50,15 @@ 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.12.0
54
+
55
+ Update together with gcf-harness-aif-ext 0.12.0 and gcf-board 0.6.0 (docs/Session-Engine.md).
56
+ - `submit` and `close` of an item with a plan refuse while the plan has unticked tasks: `<id>: plan tasks not ticked: N of M — tick what is done, or block the item`. The human passes it with `--unticked "<why>"`, which goes into the commit like `--unverified`. A feature and an item without a plan are not checked; `/gcf-run` ticks the tasks the run did itself (verify, review) before its commit. The integrator is held to it too: `gcf integrate` blocks a merged item whose plan has unticked tasks, with the reason.
57
+ - `item new --note=<text>` or `--note-file <path|->` writes what the item's run should know into its `note:`, up to 4000 characters; the board passes it on stdin.
58
+ - The board read adds `agent.rules` (every deny rule neutral, `{kind, pattern}`: `shell`, `read`, `edit`…), `domain.chat` (the project chat's skill and the commands it asks for) and `propose` on the `item-new` move. Own deny rules are taken in the neutral form (`shell: curl *`) or claude's (`Bash(curl *)`); `gcf permissions` lists them neutral. The `edit` kind denies MultiEdit and NotebookEdit too, not only Edit and Write.
59
+ - The new skill `gcf-chat`: the board's project chat. It answers from `gcf/` and the runs, proposes a new item with the board's MCP tool `propose_item_new` rather than making it, and makes a move only when the human approves its card. A thread bound to an item reads the item's file, plan, run log and run chat first. The AGENTS.md block says the same, and gives the exact form of an item's `live:` delta.
60
+ - `gcf context --readset` writes the readset manifest with its owner (the run's `GCF_RUN_OWNER` or the Claude Code session) and item: the guards act only on that session.
61
+
53
62
  ### 0.11.1
54
63
 
55
64
  - 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.
@@ -231,7 +240,7 @@ Removal leaves `gcf/` and `cnlp.config.json` in place. It also leaves the pre-co
231
240
 
232
241
  ## What it adds
233
242
 
234
- **Skills** — `gcf-init`, `gcf-adopt`, `gcf-card` (put work into `gcf/work/`: take units, group them under a feature, or create a non-design item), `gcf-verdict` (verdicts and decisions), `gcf-triage` (inbox entries into items, tunes, units or nothing, with the human approving each), `gcf-audit`, `gcf-vision`, `gcf-debate`, `gcf-ingest`.
243
+ **Skills** — `gcf-init`, `gcf-adopt`, `gcf-chat` (the board's project chat: answers, proposes new items, makes the moves the human approves), `gcf-card` (put work into `gcf/work/`: take units, group them under a feature, or create a non-design item), `gcf-verdict` (verdicts and decisions), `gcf-triage` (inbox entries into items, tunes, units or nothing, with the human approving each), `gcf-audit`, `gcf-vision`, `gcf-debate`, `gcf-ingest`.
235
244
 
236
245
  **A deterministic core** behind `ai-factory gcf …`:
237
246
 
package/commands/gcf.js CHANGED
@@ -24,6 +24,7 @@ const verifiedMove = (o) => ({
24
24
  commit: o.commit,
25
25
  requireVerify: true,
26
26
  unverified: o.unverified === undefined ? undefined : reasonOf(o.unverified),
27
+ unticked: o.unticked === undefined ? undefined : reasonOf(o.unticked),
27
28
  });
28
29
 
29
30
  /** The reason of `--unverified`, one line in the commit's subject; an empty one is no reason. */
@@ -36,6 +37,8 @@ function reasonOf(text) {
36
37
 
37
38
  const UNVERIFIED =
38
39
  'move without a green gcf verify of the code as it is now; the reason goes into the commit';
40
+ const UNTICKED =
41
+ "move with plan tasks left unticked (the human's call); the reason goes into the commit";
39
42
 
40
43
  /** `--claimed`: this move comes from the session that holds the item's mark. */
41
44
  const claimedBy = (o, id) => {
@@ -242,10 +245,15 @@ function registerContext(gcf) {
242
245
  .command('context <item-id>')
243
246
  .description('Assemble the readset for a work item (GCF-PRD §9.1)')
244
247
  .option('--json', 'machine output')
248
+ .option(
249
+ '--readset',
250
+ "write .gcf-session/readset.json, the readset guard's manifest, for this session",
251
+ )
245
252
  .action(async (itemId, opts) => {
246
253
  await touchSession(itemId);
247
- const { buildContext } = await lib('context');
254
+ const { buildContext, writeReadset } = await lib('context');
248
255
  const ctx = await buildContext(process.cwd(), itemId);
256
+ if (opts.readset) await writeReadset(process.cwd(), ctx);
249
257
  // Metric 1 (GCF-PRD §14): readset size over time, one csv line per call.
250
258
  const { appendFile, mkdir } = await import('node:fs/promises');
251
259
  const metricsDir = path.join(process.cwd(), 'gcf', '.metrics');
@@ -701,8 +709,12 @@ function registerItem(gcf) {
701
709
  .option('--priority <rank>', 'its rank: 1, 2, 3… (lower runs sooner)')
702
710
  .option('--model <name>', 'the model its run uses, e.g. opus')
703
711
  .option('--effort <level>', 'the effort its run uses, e.g. high')
712
+ .option('--note <text>', "what its run should know: the item's note:, up to 4000 characters")
713
+ .option('--note-file <path>', 'the note from a file, - for stdin: several lines')
704
714
  .option('--commit', 'commit it (gcf(item)): for a caller with no console, e.g. a board')
705
715
  .action(async (id, o) => {
716
+ if (o.note !== undefined && o.noteFile !== undefined)
717
+ throw new Error('give the note once: --note=<text> or --note-file <path|->');
706
718
  const { newItem } = await lib('work-ops');
707
719
  const r = await newItem(process.cwd(), {
708
720
  id,
@@ -721,6 +733,7 @@ function registerItem(gcf) {
721
733
  channel: o.channel,
722
734
  model: o.model,
723
735
  effort: o.effort,
736
+ note: o.noteFile === undefined ? o.note : readTextFile(o.noteFile),
724
737
  priority: o.priority === undefined ? undefined : Number(o.priority),
725
738
  commit: o.commit === true,
726
739
  });
@@ -793,6 +806,7 @@ function registerItemMoves(gcf) {
793
806
  .description('ready → awaiting-verdict / awaiting-decision (commit gcf(submit))')
794
807
  .option('--claimed', CLAIMED)
795
808
  .option('--unverified <why>', UNVERIFIED)
809
+ .option('--unticked <why>', UNTICKED)
796
810
  .option('--no-commit', 'skip the commit (tests only)')
797
811
  .action(async (id, o) => {
798
812
  claimedBy(o, id);
@@ -810,6 +824,7 @@ function registerItemMoves(gcf) {
810
824
  )
811
825
  .option('--claimed', CLAIMED)
812
826
  .option('--unverified <why>', UNVERIFIED)
827
+ .option('--unticked <why>', UNTICKED)
813
828
  .option('--no-commit', 'skip the commit (tests only)')
814
829
  .action(async (id, o) => {
815
830
  claimedBy(o, id);
@@ -927,7 +942,13 @@ function entryText(arg, o) {
927
942
  if (given.length !== 1)
928
943
  throw new Error('give the entry once: as the argument, --text=<text> or --text-file <path|->');
929
944
  if (o.textFile === undefined) return given[0];
930
- const text = readFileSync(o.textFile === '-' ? 0 : o.textFile, 'utf8');
945
+
946
+ return readTextFile(o.textFile);
947
+ }
948
+
949
+ /** A text file's text, `-` for stdin. */
950
+ function readTextFile(file) {
951
+ const text = readFileSync(file === '-' ? 0 : file, 'utf8');
931
952
 
932
953
  // A file Notepad saved starts with a byte-order mark.
933
954
  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
@@ -1212,13 +1233,22 @@ function registerSettings(gcf) {
1212
1233
  : '';
1213
1234
  console.log(r.unchanged ? `${now} (unchanged)` : `${now}${shortHash(r.hash)}${note}`);
1214
1235
  });
1236
+ registerPermissions(gcf);
1237
+ }
1238
+
1239
+ /** `gcf permissions`: the deny groups and custom rules of agent runs. */
1240
+ function registerPermissions(gcf) {
1215
1241
  const many = (v, prev = []) => [...prev, v];
1216
1242
  gcf
1217
1243
  .command('permissions')
1218
1244
  .description("What agent runs may not do: deny groups and custom rules (the human's; commit)")
1219
1245
  .option('--on <group>', 'turn a deny group on (repeatable)', many)
1220
1246
  .option('--off <group>', 'turn a deny group off (repeatable)', many)
1221
- .option('--deny <rule>', 'add a custom deny rule, like Bash(cmd*) (repeatable)', many)
1247
+ .option(
1248
+ '--deny <rule>',
1249
+ 'add a custom deny rule, like "shell: cmd*" or Bash(cmd*) (repeatable)',
1250
+ many,
1251
+ )
1222
1252
  .option('--undeny <rule>', 'remove a custom deny rule (repeatable)', many)
1223
1253
  .option('--json', 'machine output')
1224
1254
  .option('--no-commit', 'skip the commit (tests only)')
@@ -1232,7 +1262,8 @@ function registerSettings(gcf) {
1232
1262
  out(o.json, r, (x) =>
1233
1263
  [
1234
1264
  ...x.groups.map((g) => `${g.on ? '[x]' : '[ ]'} ${g.id}: ${g.label}`),
1235
- ...x.deny_extra.map((d) => `deny: ${d}`),
1265
+ // The neutral form (AD-4): `deny: shell: curl *`, whichever way the line is written.
1266
+ ...x.deny_extra.map((d) => `deny: ${perms.ruleText(perms.parseRule(d))}`),
1236
1267
  ...(x.hash ? [`committed${shortHash(x.hash)}`] : []),
1237
1268
  ].join('\n'),
1238
1269
  );
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.11.1",
4
+ "version": "0.12.1",
5
5
  "description": "Game Context Framework for AI Factory",
6
6
  "skills": [
7
7
  "skills/gcf-init",
@@ -12,7 +12,8 @@
12
12
  "skills/gcf-audit",
13
13
  "skills/gcf-vision",
14
14
  "skills/gcf-debate",
15
- "skills/gcf-ingest"
15
+ "skills/gcf-ingest",
16
+ "skills/gcf-chat"
16
17
  ],
17
18
  "commands": [
18
19
  {
@@ -14,12 +14,95 @@ import { configDoc, ensureMap } from './config-set.js';
14
14
 
15
15
  const GROUPS_SHAPE = 'gcf/config.yml: agent.groups must map a group id to true or false';
16
16
 
17
- // A shell command pattern turns into a rule for both shell tools: on Windows the agent runs
18
- // commands through PowerShell, which Bash rules do not cover.
19
- const shell = (...patterns) => patterns.flatMap((p) => [`Bash(${p})`, `PowerShell(${p})`]);
20
- const files = (tools, ...globs) => globs.flatMap((g) => tools.map((t) => `${t}(${g})`));
17
+ /** @typedef {{ kind: string, pattern: string }} Rule a neutral rule (Session-Engine.md AD-4) */
21
18
 
22
- /** @type {{ id: string, label: string, on: boolean, rules: string[] }[]} */
19
+ // The claude tools of each neutral kind: a rule of the kind holds for each. A shell rule covers
20
+ // PowerShell too: on Windows the agent runs commands through it, which Bash rules do not cover.
21
+ const CLAUDE = {
22
+ read: ['Read'],
23
+ search: ['Grep', 'Glob'],
24
+ edit: ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'],
25
+ shell: ['Bash', 'PowerShell'],
26
+ web: ['WebFetch'],
27
+ subagent: ['Task', 'Agent'],
28
+ skill: ['Skill'],
29
+ question: ['AskUserQuestion'],
30
+ };
31
+
32
+ /** The kinds of tool a rule names: `mcp` (`server__tool`) and `other` (a claude rule as is). */
33
+ export const KINDS = [...Object.keys(CLAUDE), 'mcp', 'other'];
34
+
35
+ const NEUTRAL_RE = new RegExp(`^(${KINDS.join('|')}):\\s*(.*)$`);
36
+ // The kinds whose pattern is a path glob.
37
+ const PATHS = ['read', 'search', 'edit'];
38
+ // A claude rule: a tool name, optionally with a specifier — `Bash(npm test*)`, `Read`.
39
+ const CLAUDE_RE = /^([A-Za-z_][\w-]*)(?:\((.+)\))?$/;
40
+
41
+ /**
42
+ * A rule line in either form, neutral (`shell: git push --force*`) or claude's (`Bash(...)`,
43
+ * `mcp__server__tool`), as a neutral rule; null when it is neither.
44
+ * @param {unknown} line
45
+ * @returns {Rule | null}
46
+ */
47
+ export function parseRule(line) {
48
+ if (typeof line !== 'string') return null;
49
+ const n = NEUTRAL_RE.exec(line.trim());
50
+ if (n) return n[1] === 'other' && !CLAUDE_RE.test(n[2]) ? null : { kind: n[1], pattern: n[2] };
51
+ const c = CLAUDE_RE.exec(line);
52
+ if (!c) return null;
53
+ if (c[1].startsWith('mcp__') && !c[2]) return { kind: 'mcp', pattern: c[1].slice(5) };
54
+ const kind = Object.keys(CLAUDE).find((k) => CLAUDE[k].includes(c[1]));
55
+ if (!kind) return { kind: 'other', pattern: line };
56
+
57
+ return { kind, pattern: neutralSpec(kind, c[2] ?? '') };
58
+ }
59
+
60
+ /**
61
+ * A claude rule's specifier in the neutral form: a domain without `domain:`; a path `/x`, which
62
+ * claude reads from the project, as `x`, and `//x`, from the root, as `/x` (the engine's adapter
63
+ * writes them back so).
64
+ */
65
+ function neutralSpec(kind, spec) {
66
+ if (kind === 'web') return spec.replace(/^domain:/, '');
67
+
68
+ return PATHS.includes(kind) && spec.startsWith('/') ? spec.slice(1) : spec;
69
+ }
70
+
71
+ /**
72
+ * The claude rules of a neutral one: one per tool of its kind, `WebFetch(domain:…)` for `web`,
73
+ * `mcp__…` for `mcp`, an `other` as it is.
74
+ * @param {Rule} r
75
+ */
76
+ export function claudeRules(r) {
77
+ if (r.kind === 'other') return [r.pattern];
78
+ if (r.kind === 'mcp') return [`mcp__${r.pattern}`];
79
+ const web = r.kind === 'web' && r.pattern ? `domain:${r.pattern}` : r.pattern;
80
+ const spec = PATHS.includes(r.kind) ? claudePath(r.pattern) : web;
81
+
82
+ return CLAUDE[r.kind].map((t) => (spec ? `${t}(${spec})` : t));
83
+ }
84
+
85
+ /**
86
+ * A neutral path glob as claude reads it, as the engine's adapter writes it
87
+ * (gcf-session/lib/adapter/claude.js `pathRule`: change both): a project path as it is, an
88
+ * absolute one from the root (`//x`), a Windows drive as `//c/x`.
89
+ */
90
+ function claudePath(pattern) {
91
+ const drive = /^([A-Za-z]):[\\/](.*)$/.exec(pattern);
92
+ if (drive) return `//${drive[1].toLowerCase()}/${drive[2].replaceAll('\\', '/')}`;
93
+
94
+ return pattern.startsWith('/') && !pattern.startsWith('//') ? `/${pattern}` : pattern;
95
+ }
96
+
97
+ /** A rule as the operator reads it: `shell: git push --force*`. */
98
+ export const ruleText = (r) => `${r.kind}: ${r.pattern}`;
99
+
100
+ const sameRule = (a, b) => a?.kind === b?.kind && a?.pattern === b?.pattern;
101
+
102
+ const shell = (...patterns) => patterns.map((pattern) => ({ kind: 'shell', pattern }));
103
+ const files = (kind, ...globs) => globs.map((pattern) => ({ kind, pattern }));
104
+
105
+ /** @type {{ id: string, label: string, on: boolean, rules: Rule[] }[]} */
23
106
  export const DENY_GROUPS = [
24
107
  {
25
108
  id: 'git-destroy',
@@ -93,20 +176,25 @@ export const DENY_GROUPS = [
93
176
  'ai-factory gcf-harness init*',
94
177
  'ai-factory gcf-harness run*',
95
178
  'ai-factory gcf-harness stop*',
179
+ // The operator's chat input: an agent answering its own question would be no answer.
180
+ 'ai-factory gcf-harness chat*',
96
181
  'ai-factory extension*',
97
182
  ),
98
183
  },
99
184
  {
100
185
  id: 'guards',
101
- label: 'the guards: .claude/, extension code, gcf/LIVE.md, gcf/.metrics/, the run files',
186
+ label:
187
+ 'the guards: .claude/, extension code, gcf/LIVE.md, gcf/.metrics/, the run and chat files',
102
188
  on: true,
103
189
  rules: files(
104
- ['Edit', 'Write'],
190
+ 'edit',
105
191
  '.claude/**',
106
192
  '.ai-factory/extensions/**',
107
193
  'gcf/LIVE.md',
108
194
  'gcf/.metrics/**',
109
195
  '.gcf-session/runs/**',
196
+ // The project chat's threads: their records, input and settings are the center's.
197
+ '.gcf-session/chats/**',
110
198
  '.gcf-session/handoff.json',
111
199
  ),
112
200
  },
@@ -114,7 +202,7 @@ export const DENY_GROUPS = [
114
202
  id: 'secrets',
115
203
  label: 'reading secrets: ~/.npmrc, ~/.ssh, ~/.claude.json, .env',
116
204
  on: false,
117
- rules: files(['Read'], '~/.npmrc', '~/.ssh/**', '~/.claude.json', '**/.env'),
205
+ rules: files('read', '~/.npmrc', '~/.ssh/**', '~/.claude.json', '**/.env'),
118
206
  },
119
207
  {
120
208
  id: 'outside',
@@ -143,19 +231,22 @@ export const DENY_GROUPS = [
143
231
  ];
144
232
 
145
233
  const GROUP_IDS = DENY_GROUPS.map((g) => g.id);
146
- // A permission rule: a tool name, optionally with a specifier — `Bash(npm test*)`, `Read`.
147
- const RULE_RE = /^[A-Za-z_][\w-]*(\(.+\))?$/;
148
234
  const known = (x) => GROUP_IDS.includes(x);
149
- const rule = (x) => typeof x === 'string' && RULE_RE.test(x);
235
+ const rule = (x) => parseRule(x) !== null;
150
236
 
151
237
  function rules(agent, key) {
152
238
  const v = agent[key] ?? [];
153
239
  if (!Array.isArray(v) || !v.every(rule))
154
- throw new Error(`gcf/config.yml: agent.${key} must be a list of rules like Bash(cmd*) or Read`);
240
+ throw new Error(
241
+ `gcf/config.yml: agent.${key} must be a list of rules like shell: cmd*, Bash(cmd*) or Read`,
242
+ );
155
243
 
156
244
  return v;
157
245
  }
158
246
 
247
+ /** The claude rules of neutral ones, each once. */
248
+ const claudeOf = (list) => [...new Set(list.flatMap(claudeRules))];
249
+
159
250
  /**
160
251
  * The groups the human chose: `agent.groups` maps a group id to true or false. A group it does
161
252
  * not name keeps its default, so a group a later version adds on comes on in every project.
@@ -175,7 +266,9 @@ function choices(agent) {
175
266
 
176
267
  /**
177
268
  * The `agent:` section resolved: each group on or off, the deny rules the run gets, the extra
178
- * allow rules (for an agent run without bypass). No section: the default groups.
269
+ * allow rules (for an agent run without bypass). No section: the default groups. `rules` holds
270
+ * them neutral (AD-4), `deny` and `allow` as claude rules for a harness before 0.12;
271
+ * `deny_extra` is the operator's own deny lines as written, `extra` the same neutral.
179
272
  */
180
273
  export function agentOf(config) {
181
274
  const agent = config.agent ?? {};
@@ -183,13 +276,22 @@ export function agentOf(config) {
183
276
  throw new Error('gcf/config.yml: agent must be a mapping');
184
277
  const chosen = choices(agent);
185
278
  const extra = rules(agent, 'deny');
186
- const allow = rules(agent, 'allow');
279
+ const allowed = rules(agent, 'allow').map(parseRule);
187
280
  const groups = DENY_GROUPS.map((g) => ({ id: g.id, label: g.label, on: chosen[g.id] ?? g.on }));
188
- const deny = [
189
- ...new Set([...DENY_GROUPS.filter((g, i) => groups[i].on).flatMap((g) => g.rules), ...extra]),
190
- ];
281
+ const denied = [
282
+ ...DENY_GROUPS.filter((g, i) => groups[i].on).flatMap((g) => g.rules),
283
+ ...extra.map(parseRule),
284
+ ].filter((r, i, all) => all.findIndex((x) => sameRule(x, r)) === i);
191
285
 
192
- return { groups, deny_extra: extra, deny, allow };
286
+ return {
287
+ groups,
288
+ deny_extra: extra,
289
+ deny: claudeOf(denied),
290
+ allow: claudeOf(allowed),
291
+ rules: { deny: denied, allow: allowed },
292
+ // The operator's own deny lines neutral, in `deny_extra`'s order: what the board shows.
293
+ extra: extra.map(parseRule),
294
+ };
193
295
  }
194
296
 
195
297
  /** Refuse a change that names no group, a group twice, a bad rule, or a rule it cannot remove. */
@@ -202,7 +304,10 @@ function checkChange(change, current) {
202
304
  if (both) throw new Error(`${both} is turned on and off at once`);
203
305
  for (const r of [...(change.deny ?? []), ...(change.undeny ?? [])])
204
306
  if (!rule(r)) throw new Error(`not a permission rule: ${r}`);
205
- const missing = (change.undeny ?? []).find((r) => !current.deny_extra.includes(r));
307
+ // A line goes by its meaning: `shell: curl *` removes a written `Bash(curl *)`.
308
+ const missing = (change.undeny ?? []).find(
309
+ (r) => !current.deny_extra.some((d) => sameRule(parseRule(d), parseRule(r))),
310
+ );
206
311
  if (missing) throw new Error(`${missing} is not one of your own deny rules: turn its group off`);
207
312
  }
208
313
 
@@ -225,7 +330,7 @@ export async function setPermissions(projectDir, change, { commit = true } = {})
225
330
  for (const id of change.on ?? []) doc.setIn(['agent', 'groups', id], true);
226
331
  for (const id of change.off ?? []) doc.setIn(['agent', 'groups', id], false);
227
332
  const deny = [...new Set([...current.deny_extra, ...(change.deny ?? [])])].filter(
228
- (r) => !change.undeny?.includes(r),
333
+ (r) => !change.undeny?.some((u) => sameRule(parseRule(u), parseRule(r))),
229
334
  );
230
335
  doc.setIn(['agent', 'deny'], doc.createNode(deny, { flow: true }));
231
336
  result = agentOf({ agent: doc.toJS().agent });
package/lib/board.js CHANGED
@@ -190,8 +190,10 @@ async function resumeOf(projectDir, id) {
190
190
  try {
191
191
  const file = path.join(projectDir, '.gcf-session', 'runs', `${id}.agent.json`);
192
192
  const rec = JSON.parse(await readFile(file, 'utf8'));
193
- // A handoff needs no session: the next run starts a fresh one from the plan.
194
- if (typeof rec?.session_id !== 'string' && rec?.ended !== 'handoff') return null;
193
+ // A handoff needs no session: the next run starts a fresh one from the plan. Nor does a
194
+ // run that waits for the usage limit before its first session (AD-19).
195
+ const sessionless = rec?.ended === 'handoff' || rec?.ended === 'limit';
196
+ if (typeof rec?.session_id !== 'string' && !sessionless) return null;
195
197
 
196
198
  return {
197
199
  ended: String(rec.ended ?? ''),
package/lib/config-set.js CHANGED
@@ -146,6 +146,28 @@ export const SETTINGS = [
146
146
 
147
147
  const BY_KEY = new Map(SETTINGS.map((s) => [s.key, s]));
148
148
 
149
+ // What a settings screen groups the keys under, in its order.
150
+ /** @type {[string, string[]][]} */
151
+ const GROUPS = [
152
+ ['Language', ['language.ui', 'language.artifacts']],
153
+ ['Runs', ['run_mode', 'plan_passes', 'dod_attempts']],
154
+ ['Checks (DoD)', ['dod.test', 'dod.build', 'dod_timeout_min']],
155
+ ['Chat', ['chat.ask', 'chat.answer_timeout_min']],
156
+ ['Context', ['context_handoff_pct', 'context_window', 'auto_compact_pct']],
157
+ [
158
+ 'Limits',
159
+ [
160
+ 'wip_built_limit',
161
+ 'tune_limit',
162
+ 'unplayed_warn_after',
163
+ 'built_stale_after_commits',
164
+ 'question_stale_after_commits',
165
+ ],
166
+ ],
167
+ ['Design import', ['context_budget', 'pillars_budget', 'envelope_default_spread']],
168
+ ];
169
+ const GROUP_OF = new Map(GROUPS.flatMap(([group, keys]) => keys.map((k) => [k, group])));
170
+
149
171
  /** The default a setting holds while its file does not set it; the artifacts follow the ui. */
150
172
  function defaultOf(s, aif) {
151
173
  const [head, sub] = s.key.split('.');
@@ -158,9 +180,9 @@ function defaultOf(s, aif) {
158
180
  }
159
181
 
160
182
  /**
161
- * Each setting with what its file sets (null: not set, the default holds) and its default:
162
- * what a settings screen shows. `raw` is the parsed config.yml, before the defaults; `aif` the
163
- * parsed `.ai-factory/config.yaml`.
183
+ * Each setting with its group, what its file sets (null: not set, the default holds) and its
184
+ * default: what a settings screen shows, by group. `raw` is the parsed config.yml, before the
185
+ * defaults; `aif` the parsed `.ai-factory/config.yaml`.
164
186
  */
165
187
  export function settingsOf(raw, aif = {}) {
166
188
  return SETTINGS.map((s) => {
@@ -174,7 +196,12 @@ export function settingsOf(raw, aif = {}) {
174
196
  // AI Factory's file is not checked by GCF's rules: a value that is no language shows unset.
175
197
  const shown = s.file ? languageIn(aif, sub) : value;
176
198
 
177
- return { ...s, value: shown, default: defaultOf(s, aif) };
199
+ return {
200
+ ...s,
201
+ group: GROUP_OF.get(s.key) ?? 'Other',
202
+ value: shown,
203
+ default: defaultOf(s, aif),
204
+ };
178
205
  });
179
206
  }
180
207
 
package/lib/context.js CHANGED
@@ -1,8 +1,21 @@
1
- import { readFile, readdir } from 'node:fs/promises';
1
+ import { mkdir, 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';
5
5
  import { fieldOf } from './question-fields.js';
6
+ import { atomicWrite } from './safe-path.js';
7
+ import { ownerOf } from './session-mark.js';
8
+
9
+ /**
10
+ * The readset guard's manifest, `.gcf-session/readset.json`: the item, its readset's paths, and
11
+ * the session that owns it (`ownerOf`), so the guard holds for that session only.
12
+ */
13
+ export async function writeReadset(projectDir, ctx, env = process.env) {
14
+ const dir = path.join(path.resolve(projectDir), '.gcf-session');
15
+ await mkdir(dir, { recursive: true });
16
+ const manifest = { item: ctx.item, owner: ownerOf(env), files: ctx.files.map((f) => f.path) };
17
+ await atomicWrite(path.join(dir, 'readset.json'), `${JSON.stringify(manifest)}\n`);
18
+ }
6
19
 
7
20
  /**
8
21
  * Readset assembly — the whole command is deterministic (GCF-PRD §9.1, §10.1):
package/lib/domain.js CHANGED
@@ -5,6 +5,7 @@
5
5
  import { ITEM_MOVES, STORED } from './transitions.js';
6
6
  import { DEFAULT_GATE, GATES, ITEM_TYPES, SEVERITIES, UNIT_ITEM_TYPES } from './validate-item.js';
7
7
  import { SOURCES } from './inbox.js';
8
+ import { NOTE_MAX } from './work-ops.js';
8
9
 
9
10
  // The status a run starts from; the order of its column is the run order.
10
11
  export const RUNS_FROM = 'ready';
@@ -19,6 +20,10 @@ const COLUMN_TEXT = {
19
20
  parked: ['parked', 'A bug kept as a known issue; unblock takes it back to ready'],
20
21
  };
21
22
 
23
+ // The statuses where only the operator moves an item on (Board-PRD §1.3, "waiting for me"):
24
+ // a verdict, a decision, a playtest, an unblock. Parked waits by choice, not on the operator.
25
+ const HUMAN = new Set(['blocked', 'awaiting-verdict', 'awaiting-decision', 'unplayed']);
26
+
22
27
  const GATE_HELP = {
23
28
  verdict: 'Closed by a playtest: keep, tune or kill',
24
29
  auto: 'Closed by the run itself when its checks are green; no playtest',
@@ -42,6 +47,12 @@ const UNVERIFIED = {
42
47
  label: 'No green gcf verify? Why it goes anyway',
43
48
  kind: 'text',
44
49
  };
50
+ // And a plan with tasks left unticked (AD-50).
51
+ const UNTICKED = {
52
+ key: 'unticked',
53
+ label: 'Plan tasks unticked? Why it goes anyway',
54
+ kind: 'text',
55
+ };
45
56
 
46
57
  const verdict = (v, help, fields, danger) => ({
47
58
  label: v,
@@ -65,27 +76,34 @@ const ITEM_SPECS = {
65
76
  label: 'submit',
66
77
  help: 'Built: on to awaiting verdict or awaiting decision, by its gate',
67
78
  args: ['gcf', 'submit', '{id}'],
68
- fields: [UNVERIFIED],
79
+ fields: [UNVERIFIED, UNTICKED],
69
80
  rare: true,
70
81
  },
71
82
  close: {
72
83
  label: 'close',
73
84
  help: 'Done, gate auto: to history; a mechanic or a resource waits unplayed',
74
85
  args: ['gcf', 'close', '{id}'],
75
- fields: [CONSTRAINT, UNVERIFIED],
86
+ fields: [CONSTRAINT, UNVERIFIED, UNTICKED],
76
87
  rare: true,
77
88
  },
78
- 'verdict:keep': verdict('keep', 'Played and kept: it goes to history', [
79
- { key: 'note', label: 'Note', kind: 'text' },
80
- CONSTRAINT,
81
- ]),
89
+ // A keep stores no note (`gcf verdict --note` is a tune's remark, a kill's reason).
90
+ 'verdict:keep': verdict('keep', 'Played and kept: it goes to history', [CONSTRAINT]),
82
91
  'verdict:tune': verdict('tune', 'Played; needs a change: back to ready with the note', [
83
92
  { key: 'note', label: 'What to change', kind: 'longtext', required: true },
84
93
  ]),
85
94
  'verdict:kill': verdict(
86
95
  'kill',
87
96
  'Played and rejected: it goes to the graveyard',
88
- [{ key: 'note', label: 'Why', kind: 'longtext' }, REMOVE],
97
+ [
98
+ { key: 'note', label: 'Why', kind: 'longtext' },
99
+ {
100
+ key: 'tags',
101
+ label: 'Graveyard tags',
102
+ kind: 'tags',
103
+ help: 'How the graveyard finds it again; its systems when none',
104
+ },
105
+ REMOVE,
106
+ ],
89
107
  true,
90
108
  ),
91
109
  'decide:go': decide('go', 'Approved: it goes to history as decided'),
@@ -162,11 +180,13 @@ const RUN = {
162
180
  };
163
181
 
164
182
  // The new item form (`gcf item new`): work that is not a design unit; a design unit enters work
165
- // through the gcf-card skill and take.
183
+ // through the gcf-card skill and take. A project chat agent may propose it (AD-12): the board
184
+ // shows the proposal, the operator's click makes it.
166
185
  const NEW_ITEM = {
167
186
  label: 'create',
168
187
  help: 'A new work item, committed; the core refuses a type the phase does not take',
169
188
  args: ['gcf', 'item', 'new', '{id}', '--commit'],
189
+ propose: true,
170
190
  fields: [
171
191
  { key: 'id', label: 'Id (lowercase-hyphen slug)', kind: 'slug', required: true },
172
192
  {
@@ -208,6 +228,14 @@ const NEW_ITEM = {
208
228
  text('blocked', 'Start blocked: why (e.g. "file needed")'),
209
229
  text('model', 'Model of its run (e.g. opus)'),
210
230
  text('effort', 'Effort of its run (e.g. high)'),
231
+ // A board passes it on stdin (`stdin`: `--note-file -`, AD-39).
232
+ {
233
+ key: 'note',
234
+ label: 'Note: what its run should know',
235
+ kind: 'longtext',
236
+ max: NOTE_MAX,
237
+ stdin: true,
238
+ },
211
239
  // The inbox entry it comes from: the form fills it, the operator does not.
212
240
  text('from', 'From inbox entry', { hidden: true }),
213
241
  ],
@@ -341,6 +369,57 @@ const SECTIONS = {
341
369
  graveyard: { label: 'Graveyard' },
342
370
  };
343
371
 
372
+ // The gcf commands that change the project: a project chat asks the operator before each one
373
+ // (AD-5). The read-only ones (audit, board, context, verify, where, plan check…) go unasked.
374
+ // shortcut: the rules match `ai-factory gcf …` as written, as the deny groups do; `npx` or a
375
+ // path to the CLI slips past them.
376
+ const CHANGES = [
377
+ 'claim',
378
+ 'release',
379
+ 'init',
380
+ 'index',
381
+ 'anchor',
382
+ 'design export',
383
+ 'design import',
384
+ 'design migrate',
385
+ 'take',
386
+ 'done',
387
+ 'drop',
388
+ 'item',
389
+ 'depends',
390
+ 'prioritize',
391
+ 'question',
392
+ 'submit',
393
+ 'close',
394
+ 'verdict',
395
+ 'decide',
396
+ 'block',
397
+ 'unblock',
398
+ 'inbox add',
399
+ 'inbox tag',
400
+ 'inbox drop',
401
+ 'lessons add',
402
+ 'config set',
403
+ 'permissions',
404
+ 'worktree',
405
+ 'integrate',
406
+ 'phase next',
407
+ 'hooks-install',
408
+ 'pillar',
409
+ ];
410
+
411
+ // The project chat of a GCF project (AD-5, AD-6): its skill, and the commands it asks for.
412
+ const CHAT = {
413
+ skill: 'gcf-chat',
414
+ confirm: [
415
+ ...CHANGES.map((c) => ({ kind: 'shell', pattern: `ai-factory gcf ${c}*` })),
416
+ // `context` reads, but with `--readset` it takes the guard's manifest over (AD-30).
417
+ { kind: 'shell', pattern: 'ai-factory gcf context*--readset*' },
418
+ // `verify` reads, but with `--mark` it commits a branch's readiness to merge.
419
+ { kind: 'shell', pattern: 'ai-factory gcf verify*--mark*' },
420
+ ],
421
+ };
422
+
344
423
  // The extension whose CLI drives agent runs (run, next, stop, metrics with --json).
345
424
  const HARNESS = { extension: 'gcf-harness-aif-ext', cli: 'gcf-harness' };
346
425
 
@@ -362,6 +441,7 @@ export function domainOf(extensions = {}) {
362
441
  status,
363
442
  label: COLUMN_TEXT[status][0],
364
443
  help: COLUMN_TEXT[status][1],
444
+ ...(HUMAN.has(status) && { human: true }),
365
445
  })),
366
446
  moves: {
367
447
  ...(harness && { run: RUN }),
@@ -373,5 +453,6 @@ export function domainOf(extensions = {}) {
373
453
  sections: SECTIONS,
374
454
  new_item: 'item-new',
375
455
  rank: 'prioritize',
456
+ chat: CHAT,
376
457
  };
377
458
  }
package/lib/plan-check.js CHANGED
@@ -1,27 +1,36 @@
1
1
  // `gcf plan check <id>` (Methodology §5.2.1): the deterministic check after each improve pass —
2
2
  // the plan exists, it holds task checkboxes, and the item's readset fits the context budget.
3
3
  // Whether the plan is any good is the improve passes' job; this only says it is usable.
4
- import { readFile } from 'node:fs/promises';
5
- import { existsSync } from 'node:fs';
4
+ import { existsSync, readFileSync } from 'node:fs';
6
5
  import path from 'node:path';
7
6
  import { buildLedger } from './ledger.js';
8
7
  import { buildContext } from './context.js';
9
8
 
9
+ /**
10
+ * An item's plan and its task checkboxes: `{plan, tasks, done}`, `tasks` null when there is no
11
+ * plan file. `data` is the item's frontmatter.
12
+ */
13
+ export function planTicks(projectDir, data) {
14
+ const plan = data.plan ?? `.ai-factory/plans/${data.id}.md`;
15
+ const file = path.resolve(projectDir, plan);
16
+ if (!existsSync(file)) return { plan, tasks: null, done: 0 };
17
+ const text = readFileSync(file, 'utf8');
18
+
19
+ return {
20
+ plan,
21
+ tasks: (text.match(/^\s*- \[[ xX]\] /gm) ?? []).length,
22
+ done: (text.match(/^\s*- \[[xX]\] /gm) ?? []).length,
23
+ };
24
+ }
25
+
10
26
  export async function planCheck(projectDir, id) {
11
27
  const item = (await buildLedger(projectDir)).item(id);
12
28
  if (!item) throw new Error(`${id} is not a work item of gcf/work/`);
13
- const plan = item.data.plan ?? `.ai-factory/plans/${id}.md`;
14
- const file = path.resolve(projectDir, plan);
29
+ const { plan, tasks: found, done } = planTicks(projectDir, { ...item.data, id });
30
+ const tasks = found ?? 0;
15
31
  const problems = [];
16
- let tasks = 0;
17
- let done = 0;
18
- if (!existsSync(file)) problems.push(`no plan at ${plan}`);
19
- else {
20
- const text = await readFile(file, 'utf8');
21
- tasks = (text.match(/^\s*- \[[ xX]\] /gm) ?? []).length;
22
- done = (text.match(/^\s*- \[[xX]\] /gm) ?? []).length;
23
- if (!tasks) problems.push(`${plan} has no task checkboxes (- [ ] …)`);
24
- }
32
+ if (found === null) problems.push(`no plan at ${plan}`);
33
+ else if (!tasks) problems.push(`${plan} has no task checkboxes (- [ ] …)`);
25
34
 
26
35
  const ctx = await buildContext(projectDir, id);
27
36
  if (ctx.over_budget)
@@ -77,7 +77,11 @@ const isSlug = (v) => typeof v === 'string' && SLUG.test(v);
77
77
  const slugList = (v) => Array.isArray(v) && v.every(isSlug);
78
78
  const isText = (v) => typeof v === 'string' && v.trim().length > 0;
79
79
  const nullable = (check) => (v) => v === null || v === undefined || check(v);
80
- const LIVE_SHAPE = 'live must be {none: <why>} or {changes: [...]} with at least one change';
80
+ // The exact form (fix D): an agent read the old message and guessed its way to the shape.
81
+ const LIVE_SHAPE =
82
+ 'live must be {none: "<why it changes no capability>"} or {changes: [{id: <capability ' +
83
+ 'slug>, change: added | modified | removed, summary: "<at most two sentences>"}]} with at ' +
84
+ 'least one change; summary is not needed for removed';
81
85
 
82
86
  /** At most two sentences and 250 characters: a table of contents, not a description. */
83
87
  export function summaryProblem(s) {
package/lib/work-ops.js CHANGED
@@ -41,6 +41,7 @@ import { refuseByPhase } from './phase.js';
41
41
  import { locked, runHolder } from './main-lock.js';
42
42
  import { dropAgentSession, ownsMark, releaseSession, sessionActive } from './session-mark.js';
43
43
  import { dropStamp, unverifiedProblem } from './verify-stamp.js';
44
+ import { planTicks } from './plan-check.js';
44
45
 
45
46
  /**
46
47
  * Options of a committed move; each move reads the ones it needs.
@@ -263,8 +264,27 @@ function verifyGateProblem(projectDir, id, type) {
263
264
  }
264
265
  }
265
266
 
266
- /** The commit's tail of a move made without a green verify. */
267
- const unverifiedTail = (opts) => (opts.unverified ? ` (unverified: ${opts.unverified})` : '');
267
+ /**
268
+ * `close` and `submit` (AD-50), from a command and from the integrator alike: every task of the
269
+ * item's plan ticked, unless the human says why not (`unticked`, written into the move's
270
+ * commit). An item with no plan and a feature are not checked; the check trusts the ticks, not
271
+ * the agent's words. The integrator turns the refusal into a block.
272
+ */
273
+ function needTicked(m, opts) {
274
+ if (opts.unticked || m.item.data.type === 'feature') return;
275
+ const id = String(m.item.data.id);
276
+ const { tasks, done } = planTicks(m.projectDir, { ...m.item.data, id });
277
+ if (tasks !== null && done < tasks)
278
+ throw new Error(
279
+ `${id}: plan tasks not ticked: ${tasks - done} of ${tasks} — tick what is done, or block ` +
280
+ 'the item',
281
+ );
282
+ }
283
+
284
+ /** The commit's tail of a move made without a green verify, or with tasks left unticked. */
285
+ const unverifiedTail = (opts) =>
286
+ (opts.unverified ? ` (unverified: ${opts.unverified})` : '') +
287
+ (opts.unticked ? ` (unticked: ${opts.unticked})` : '');
268
288
 
269
289
  const writeItem = (item, data, body = item.body) => atomicWrite(item.file, serialize(data, body));
270
290
 
@@ -511,6 +531,7 @@ async function submitItemUnlocked(projectDir, id, opts = {}) {
511
531
  if (m.item.data.gate === 'auto')
512
532
  throw new Error(`${id} has gate auto: nobody waits for it — close it with gcf close ${id}`);
513
533
  refuseOpenDepends(m, 'submit', { waiting: true });
534
+ needTicked(m, opts);
514
535
  needVerified(m, opts);
515
536
  const status = m.item.data.gate === 'verdict' ? 'awaiting-verdict' : 'awaiting-decision';
516
537
  const data = { ...without(m.item.data, 'blocked'), status, since: headHash(projectDir) };
@@ -587,6 +608,7 @@ async function closeItemUnlocked(projectDir, id, opts = {}) {
587
608
  if (m.item.data.gate !== 'auto')
588
609
  throw new Error(`${id} has gate ${m.item.data.gate}: submit it, the operator closes it`);
589
610
  refuseOpenDepends(m, 'close');
611
+ needTicked(m, opts);
590
612
  needVerified(m, opts);
591
613
  if (unplayed) closeUnplayed(m);
592
614
  else await closeEnding(m, constraints);
@@ -1070,6 +1092,9 @@ export const attachItem = (projectDir, id, file, opts = {}) =>
1070
1092
  * A new work item in ready (or blocked), no commit. A design unit enters work through `take`,
1071
1093
  * not here: its body is the unit's slots. `from` erases the inbox entry it came from.
1072
1094
  */
1095
+ /** The longest note a new item takes (AD-39): a proposal's, or the operator's. */
1096
+ export const NOTE_MAX = 4000;
1097
+
1073
1098
  async function newItemUnlocked(projectDir, spec) {
1074
1099
  const root = gcfOf(projectDir);
1075
1100
  const ledger = await buildLedger(projectDir);
@@ -1079,8 +1104,12 @@ async function newItemUnlocked(projectDir, spec) {
1079
1104
  throw new Error(`reopens names ${spec.reopens}, which has not ended`);
1080
1105
  const file = path.join(root, 'work', `${spec.id}.md`);
1081
1106
  if (existsSync(file)) throw new Error(`gcf/work/${spec.id}.md already exists`);
1107
+ if (spec.note !== undefined && spec.note.length > NOTE_MAX)
1108
+ throw new Error(`the note is ${spec.note.length} characters: up to ${NOTE_MAX}`);
1082
1109
  const take = await takeEntry(projectDir, root, spec);
1083
- const item = { ...spec, title: take.title, note: take.note };
1110
+ // The note given first, then what the inbox entry it comes from says.
1111
+ const note = [spec.note, take.note].filter((x) => x?.trim()).join('\n\n') || undefined;
1112
+ const item = { ...spec, title: take.title, note };
1084
1113
 
1085
1114
  const writes = [[file, newItemText(item, gate, headHash(projectDir))]];
1086
1115
  if (spec.parent) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-aif-ext",
3
- "version": "0.11.1",
3
+ "version": "0.12.1",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: gcf-chat
3
+ description: Talk with the human about the GCF project in the board's project chat - answer questions from gcf/ and the runs, propose new work items, make the moves the human approves. Use when the session is a project chat thread of the board, or the user says "/gcf-chat".
4
+ ---
5
+
6
+ mode: human gate
7
+
8
+ purpose:
9
+ - answer the human's questions about the game, its design, its work items and its runs from what `gcf/` and the run files say
10
+ - turn a bug, an idea or a task the talk finds into a proposed work item the human accepts with one click
11
+ - make a move the human asks for through its `ai-factory gcf` command, which the chat shows the human as a card first
12
+
13
+ inputs:
14
+ - the human's messages, one turn each
15
+ - the thread's context file when the thread is bound to an item: the paths of the item's file, its plan, its run's log and run chat, its commits
16
+
17
+ preconditions:
18
+ - `gcf/` exists and `ai-factory gcf board --json` runs
19
+ - the board started this session: a project chat asks the human before each change
20
+
21
+ forbidden_behaviors:
22
+ - do not make the human's moves: `verdict`, `decide`, `question answer`, `unblock`, `phase next`, `pillar`, `permissions`, `config set`, `hooks-install`; the rules refuse them to any agent
23
+ - do not run `ai-factory gcf-harness run|stop|chat|init` or `ai-factory extension`: the rules refuse them; name the board's button instead
24
+ - do not make a new item with `ai-factory gcf item new`: propose it with the `propose_item_new` tool of the `gcf` MCP server, and the human's click makes it
25
+ - do not write code or edit files to fix what the talk finds: a fix is a work item, and its run builds it
26
+ - do not answer from memory what a file says: read the file, then answer
27
+ - do not ask again for a move the human refused: say what it would have done and leave it
28
+ - do not read the board's own folder: it holds the human's token
29
+
30
+ workflow:
31
+ 1. read `gcf/INDEX.md`, then run `ai-factory gcf board --json` for the phase, the items by status and the inbox
32
+ 2. a thread bound to an item: read the item's file, its plan, its run's log and run chat first, the paths the context file names, before the first answer
33
+ 3. answer the question from the files you read, with the paths that say it; for the runs' numbers run `ai-factory gcf-harness metrics` when the project has the harness
34
+ 4. a bug, an idea or a task that is new work: call `propose_item_new` with its id, type, title, subsystems and a note of what its run should know; note length <= 4000 characters
35
+ 5. a raw thought that is not work yet: propose to put it in the inbox with `ai-factory gcf inbox add`
36
+ 6. a move the human asks for: run its `ai-factory gcf` command; the human approves it on the card, or refuses it
37
+ 7. say in one line what changed, or that nothing did
38
+
39
+ invocation:
40
+ - run at the start of a project chat thread the board opens, and when the user types `/gcf-chat`
@@ -12,6 +12,8 @@ gcf_work:
12
12
  - drive a ready item with the gcf-run skill when the project has gcf-harness-aif-ext and the agent is Claude Code (a batch at once: `ai-factory gcf-harness run <ids...>`), otherwise with aif-plan and aif-implement
13
13
  - a question about how the runs go (the share that reached their move, cost, plan checks, DoD attempts, guard firings) is answered by `ai-factory gcf-harness metrics`
14
14
  - after the code, write the item's `live:` delta and run `ai-factory gcf verify <id>`: fix what it reports and run it again until every check is green, at most `dod_attempts` of `gcf/config.yml` red runs; still red: block the item with the diagnosis
15
+ - the `live:` delta is YAML in the item's frontmatter, one of two forms: `live: {none: "<why it changes no capability>"}`, or `live:` with `changes:`, a list of `{id: <capability slug>, change: added | modified | removed, summary: "<at most two sentences>"}` (a removed one needs no summary)
16
+ - before `submit` or `close`, tick every task of the item's plan that is done, the verify and the review included: both refuse a plan with unticked tasks; `--unticked "<why>"` is the human's call, never the agent's
15
17
  - `submit` and `close` refuse code that changed since its last green `gcf verify`: run it again after any fix; `--unverified "<why>"` is the human's call, never the agent's
16
18
  - then end the work on the item with its command: `ai-factory gcf submit <id>` for gate verdict or decision, `ai-factory gcf close <id>` for gate auto
17
19
  - work that cannot go on: run `ai-factory gcf block <id> --reason "<why or the question>"`
@@ -29,6 +31,9 @@ gcf_work:
29
31
  - never translate keys, statuses, ids, commands, `TBD`, `answer: q-NNN`, `## Handoff`, a `quote:` (it is verbatim from the GDD) or the fixed start of a block reason (`needs permission:`, `plan did not converge:`, `waits for`)
30
32
  - a D1 record that carries the human's `answer:` goes into the slot of each unit it blocks, with `answer: q-NNN`, and then leaves `gcf/open-questions.md`
31
33
  - a pillar changes only on the human's word: `ai-factory gcf pillar rename <from> <to>`, or `ai-factory gcf pillar retire <id> --reason "<why>"`
34
+ - a new item's `--note "<text>"` (or `--note-file -` for several lines) says what its run should know, up to 4000 characters
35
+ - in the project chat (the gcf-chat skill) a new item is proposed with the `propose_item_new` tool of the `gcf` MCP server, not made with `item new`: the human's click makes it
36
+ - a chat thread bound to an item reads the item's file, its plan, its run's log and run chat first (the paths its context names), answers the question, and only then proposes a move
32
37
 
33
38
  gcf_forbidden:
34
39
  - do not edit `status:`, `frozen:`, `gcf/LIVE.md`, `gcf/history.md`, `gcf/graveyard.md`, `gcf/inbox/` or `gcf/INDEX.md` by hand: the commands own them
@@ -45,3 +50,4 @@ gcf_skills:
45
50
  - gcf-card puts work into `gcf/work/`, and gcf-triage sorts the entries of `gcf/inbox/`
46
51
  - gcf-verdict records the human's verdict or decision, and gcf-audit reports the health of `gcf/`
47
52
  - gcf-debate stresses the design, gcf-adopt puts existing code on GCF, and gcf-init sets up `gcf/` and revises the pillars
53
+ - gcf-chat is the board's project chat: answers from `gcf/` and the runs, proposals of new items, the moves the human approves