gcf-aif-ext 0.12.4 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -50,6 +50,22 @@ 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.14.0
54
+
55
+ The functional base, part A (docs/Base-A-Plan.md). Update together with gcf-harness-aif-ext 0.14.0 and gcf-board 0.10.0; run `ai-factory gcf init` after it (the AGENTS.md block learns the project's model and `gcf-harness gate --each`).
56
+
57
+ - `session_timeout_min` in `gcf/config.yml` (120): minutes one agent session on an item may run; above 0 (`gcf config set session_timeout_min --value=90`). The harness takes it when `run` has no `--timeout`.
58
+ - `agent.model` and `agent.effort`: what an item or a chat thread without its own runs on (`gcf config set agent.model --value=sonnet`; empty or `default` takes it off). One plain word each, as an item's; a setting of kind `word` with `presets: model|effort` (the board suggests the agent's presets). `gcf board --json` carries them in `agent`, and `session_timeout_min` beside `context`.
59
+ - `gcf board --json` adds `items[].attachments` (the files `gcf item attach` gave it, project paths) and offers no `run` move to a feature (the run gate refuses one).
60
+
61
+ ### 0.13.0
62
+
63
+ Board v2's data (docs/Board-V2-Data-Plan.md). Update together with gcf-harness-aif-ext 0.13.0 and gcf-board 0.9.0; run `ai-factory gcf init` after it (the AGENTS.md block learns `item history` and `gcf-harness runs`).
64
+
65
+ - `ai-factory gcf item history <id> [--json]`: the item's moves from git, newest first, up to 200, an ended item's too: `{id, moves: [{at, commit, move, subject, by}]}` (`at` ISO with offset, `commit` short hash, `move` the domain's move key: `submit`, `verdict:keep`, `decide:go`, `prioritize`, `item-new`, `agent`, `depends`, `integrate`…).
66
+ - Every move's commit ends with a trailer paragraph: `GCF-Items: <ids>` (every item and unit it touched: a feature's kill names its live children, a child's death its feature, a removal item the one it made), `GCF-Move: <move key>` and `GCF-By: run|session|operator` (`GCF_MOVE_BY` when set, else `GCF_RUN_OWNER` → run, `CLAUDE_CODE_SESSION_ID` → session, else operator). The integrator's merge and plan commits carry `GCF-Move: integrate`, `verify --mark` `verified`. A commit older than the trailers is read by its subject, `by: null`; the children a feature's old kill took along do not see it.
67
+ - `gcf board --json` adds `items[].needs` (its dependencies not ended in history: items on the board, design units, graveyard and unknown ids) and `units[]`, the live design units `{id, title, type, system, file, tbd, blocked_by[], ready}`. The domain's fields get `filter` (type, gate, severity, system, milestone) and `group` (system, parent, milestone); `parent` is `kind: ids`; `needs` follows `needed_by`, both on the card; `depends` has `edit: depends`, and the new item's `depends` is `kind: ids`. `sections.graveyard.match: system`, `sections.units: {label}`. The schema stays 3.
68
+
53
69
  ### 0.12.0
54
70
 
55
71
  Update together with gcf-harness-aif-ext 0.12.0 and gcf-board 0.6.0 (docs/Session-Engine.md).
package/commands/gcf.js CHANGED
@@ -707,8 +707,14 @@ function registerItem(gcf) {
707
707
  .option('--release <version>', 'a release: the version it ships')
708
708
  .option('--channel <name>', 'a release: where it ships, e.g. steam')
709
709
  .option('--priority <rank>', 'its rank: 1, 2, 3… (lower runs sooner)')
710
- .option('--model <name>', 'the model its run uses, e.g. opus (default: the agent picks)')
711
- .option('--effort <level>', 'the effort its run uses, e.g. high (default: the agent picks)')
710
+ .option(
711
+ '--model <name>',
712
+ "the model its run uses, e.g. opus (default: agent.model of gcf/config.yml, else the agent's)",
713
+ )
714
+ .option(
715
+ '--effort <level>',
716
+ "the effort its run uses, e.g. high (default: agent.effort of gcf/config.yml, else the agent's)",
717
+ )
712
718
  .option('--note <text>', "what its run should know: the item's note:, up to 4000 characters")
713
719
  .option('--note-file <path>', 'the note from a file, - for stdin: several lines')
714
720
  .option('--commit', 'commit it (gcf(item)): for a caller with no console, e.g. a board')
@@ -741,14 +747,41 @@ function registerItem(gcf) {
741
747
  });
742
748
  registerAttach(item);
743
749
  registerAgent(item);
750
+ registerHistory(item);
751
+ }
752
+
753
+ function registerHistory(item) {
754
+ item
755
+ .command('history <id>')
756
+ .description("An item's moves from git, newest first (an ended item's too)")
757
+ .option('--json', 'as JSON: {id, moves: [{at, commit, move, subject, by}]}')
758
+ .action(async (id, o) => {
759
+ if (!(await lib('id')).isValidId(id)) throw new Error(`${id} is not an item id`);
760
+ const moves = (await lib('history')).itemHistory(process.cwd(), id);
761
+ if (o.json) {
762
+ console.log(JSON.stringify({ id, moves }, null, 2));
763
+
764
+ return;
765
+ }
766
+
767
+ if (!moves.length) console.log(`${id}: no moves in git`);
768
+ for (const m of moves)
769
+ console.log(`${m.at} ${m.commit} ${m.move} (${m.by ?? '?'}) ${m.subject}`);
770
+ });
744
771
  }
745
772
 
746
773
  function registerAgent(item) {
747
774
  item
748
775
  .command('agent <id>')
749
776
  .description("Set the model and effort of an item's runs: from its next run (commit)")
750
- .option('--model <name>', 'e.g. opus; default takes the field off: the agent picks')
751
- .option('--effort <level>', 'e.g. high; default takes the field off: the agent picks')
777
+ .option(
778
+ '--model <name>',
779
+ "e.g. opus; default takes the field off: the project's, else the agent's",
780
+ )
781
+ .option(
782
+ '--effort <level>',
783
+ "e.g. high; default takes the field off: the project's, else the agent's",
784
+ )
752
785
  .option('--no-commit', 'skip the commit (tests only)')
753
786
  .action(async (id, o) => {
754
787
  const r = await (
@@ -907,8 +940,9 @@ function registerDecide(gcf) {
907
940
  * @param {boolean | undefined} commit
908
941
  * @param {string} message
909
942
  * @param {{files: string[], inputs?: string[], apply: () => Promise<unknown>}} plan
943
+ * @param {string} key the domain's move key, for the commit's trailer
910
944
  */
911
- async function inboxMove(commit, message, plan) {
945
+ async function inboxMove(commit, message, plan, key) {
912
946
  if (!commit) {
913
947
  await plan.apply();
914
948
 
@@ -925,6 +959,7 @@ async function inboxMove(commit, message, plan) {
925
959
  await plan.apply();
926
960
  },
927
961
  commit: true,
962
+ key,
928
963
  });
929
964
  }
930
965
 
@@ -950,7 +985,7 @@ function registerInboxTag(inbox) {
950
985
  add: splitList(o.add),
951
986
  remove: splitList(o.remove),
952
987
  });
953
- const hash = await inboxMove(o.commit, `gcf(inbox): tag ${id}`, plan);
988
+ const hash = await inboxMove(o.commit, `gcf(inbox): tag ${id}`, plan, 'inbox-tag');
954
989
  console.log(`${id} tags: ${plan.tags.join(', ') || 'none'}${shortHash(hash)}`);
955
990
  });
956
991
  }
@@ -986,7 +1021,12 @@ function registerInboxDrop(inbox) {
986
1021
  const { inHead } = await lib('git');
987
1022
  const committed = inHead(process.cwd(), plan.files[0]);
988
1023
  // An entry never committed leaves nothing to commit: it is only erased, from the index too.
989
- const hash = await inboxMove(o.commit && committed, `gcf(inbox): drop ${id}`, plan);
1024
+ const hash = await inboxMove(
1025
+ o.commit && committed,
1026
+ `gcf(inbox): drop ${id}`,
1027
+ plan,
1028
+ 'inbox-drop',
1029
+ );
990
1030
  if (!committed)
991
1031
  spawnSync('git', ['rm', '--cached', '-q', '--ignore-unmatch', '--', ...plan.files], {
992
1032
  cwd: process.cwd(),
@@ -1041,7 +1081,7 @@ function registerInbox(gcf) {
1041
1081
  const { planAdd } = await lib('inbox');
1042
1082
  const { gcfRoot } = await lib('gcf-paths');
1043
1083
  const plan = planAdd(gcfRoot(), text, o.source, { tags: splitList(o.tags) });
1044
- const hash = await inboxMove(o.commit, 'gcf(inbox): add', plan);
1084
+ const hash = await inboxMove(o.commit, 'gcf(inbox): add', plan, 'inbox-add');
1045
1085
  console.log(`${plan.entry.id}${shortHash(hash)}`);
1046
1086
  });
1047
1087
  registerInboxTag(inbox);
@@ -1082,7 +1122,7 @@ function registerLessons(gcf) {
1082
1122
  if (!list.length) return console.log(`recorded 0 lessons for ${id}`);
1083
1123
  const { gcfRoot } = await lib('gcf-paths');
1084
1124
  const plan = planLessons(gcfRoot(), id, list);
1085
- const hash = await inboxMove(o.commit, `gcf(lessons): ${id}`, plan);
1125
+ const hash = await inboxMove(o.commit, `gcf(lessons): ${id}`, plan, 'lessons');
1086
1126
  console.log(`recorded ${plan.entries.length} lessons for ${id}${shortHash(hash)}`);
1087
1127
  });
1088
1128
  }
@@ -1233,7 +1273,7 @@ function registerSettings(gcf) {
1233
1273
  });
1234
1274
  config
1235
1275
  .command('set <key>')
1236
- .description('Set one key; an empty --value= takes a number back to its default')
1276
+ .description('Set one key; an empty --value= takes a number back to its default, a word off')
1237
1277
  // The value only through --value: `set plan_passes 7` must not read as a reset. A value
1238
1278
  // may start with a hyphen (a command's flag); as `--value=<text>` it stays one value.
1239
1279
  .allowExcessArguments(false)
package/extension.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
3
3
  "name": "gcf-aif-ext",
4
- "version": "0.12.4",
4
+ "version": "0.14.0",
5
5
  "description": "Game Context Framework for AI Factory",
6
6
  "skills": [
7
7
  "skills/gcf-init",
@@ -9,7 +9,7 @@ import { existsSync } from 'node:fs';
9
9
  import path from 'node:path';
10
10
  import { commitMove } from './unit-ops.js';
11
11
  import { atomicWrite } from './safe-path.js';
12
- import { gcfRoot } from './gcf-paths.js';
12
+ import { gcfRoot, RUN_WORD } from './gcf-paths.js';
13
13
  import { configDoc, ensureMap } from './config-set.js';
14
14
 
15
15
  const GROUPS_SHAPE = 'gcf/config.yml: agent.groups must map a group id to true or false';
@@ -265,10 +265,28 @@ function choices(agent) {
265
265
  }
266
266
 
267
267
  /**
268
- * The `agent:` section resolved: each group on or off, the deny rules the run gets, the extra
269
- * allow rules (for an agent run without bypass). No section: the default groups. `rules` holds
270
- * them neutral (AD-4), `deny` and `allow` as claude rules for a harness before 0.12;
271
- * `deny_extra` is the operator's own deny lines as written, `extra` the same neutral.
268
+ * The project's model and effort (`agent.model`, `agent.effort`): what an item or a thread
269
+ * without its own pick runs on; null, or `default` written by hand, leaves it to the agent. One
270
+ * word each, as an item's.
271
+ */
272
+ function picksOf(agent) {
273
+ const pick = (k) => {
274
+ const v = agent[k] ?? null;
275
+ if (v !== null && !(typeof v === 'string' && RUN_WORD.test(v)))
276
+ throw new Error(`gcf/config.yml: agent.${k} must be one plain word, e.g. opus`);
277
+
278
+ return v?.toLowerCase() === 'default' ? null : v;
279
+ };
280
+
281
+ return { model: pick('model'), effort: pick('effort') };
282
+ }
283
+
284
+ /**
285
+ * The `agent:` section resolved: the project's model and effort, each group on or off, the deny
286
+ * rules the run gets, the extra allow rules (for an agent run without bypass). No section: the
287
+ * default groups. `rules` holds them neutral (AD-4), `deny` and `allow` as claude rules for a
288
+ * harness before 0.12; `deny_extra` is the operator's own deny lines as written, `extra` the
289
+ * same neutral.
272
290
  */
273
291
  export function agentOf(config) {
274
292
  const agent = config.agent ?? {};
@@ -284,6 +302,7 @@ export function agentOf(config) {
284
302
  ].filter((r, i, all) => all.findIndex((x) => sameRule(x, r)) === i);
285
303
 
286
304
  return {
305
+ ...picksOf(agent),
287
306
  groups,
288
307
  deny_extra: extra,
289
308
  deny: claudeOf(denied),
@@ -337,6 +356,7 @@ export async function setPermissions(projectDir, change, { commit = true } = {})
337
356
  await atomicWrite(file, doc.toString());
338
357
  },
339
358
  commit,
359
+ key: 'permissions',
340
360
  });
341
361
 
342
362
  return { ...result, hash };
package/lib/audit-core.js CHANGED
@@ -266,7 +266,8 @@ function staleQuestions(projectDir, root, config) {
266
266
  */
267
267
  function verdictMatchers(projectDir, ledger, items) {
268
268
  const tuned = items.filter((c) => (c.data.tune_count ?? 0) > 0);
269
- const verdictLog = git(['log', '--grep', '^gcf(verdict):', '--format=%s'], projectDir) ?? '';
269
+ const verdictLog =
270
+ git(['log', '--basic-regexp', '--grep', '^gcf(verdict):', '--format=%s'], projectDir) ?? '';
270
271
 
271
272
  return {
272
273
  verdict: (id) =>
package/lib/board.js CHANGED
@@ -7,7 +7,7 @@ import path from 'node:path';
7
7
  import { buildLedger } from './ledger.js';
8
8
  import { readConfig } from './gcf-paths.js';
9
9
  import { readLive } from './live.js';
10
- import { listInbox } from './inbox.js';
10
+ import { filesUnder, listInbox } from './inbox.js';
11
11
  import { phaseStatus } from './phase.js';
12
12
  import { verifiedBranches, worktreeOf } from './integrate.js';
13
13
  import { resolveInside } from './safe-path.js';
@@ -21,6 +21,7 @@ import { listQuestions } from './questions.js';
21
21
  import { sessionActive } from './session-mark.js';
22
22
  import { agentOf } from './agent-permissions.js';
23
23
  import { projectSettings } from './config-set.js';
24
+ import { designUnits } from './design-check.js';
24
25
 
25
26
  // The version of the JSON below (Methodology §11): a board refuses one it does not know. Bump it
26
27
  // when a field changes meaning or goes away; a new field does not bump it.
@@ -241,6 +242,30 @@ function inRunOrder(items) {
241
242
 
242
243
  const LISTS = ['children', 'system', 'depends'];
243
244
 
245
+ /**
246
+ * Its dependencies not ended in history (Board-PRD §5.2): items on the board, design units,
247
+ * graveyard ids and unknown ones. `waits_for` is the part the run gate refuses on now.
248
+ */
249
+ const needsOf = (ledger, depends) =>
250
+ depends.filter((d) => {
251
+ const { live, terminal } = ledger.where(d);
252
+
253
+ return live.length > 0 || !terminal.some((t) => t !== 'killed');
254
+ });
255
+
256
+ /** The live design units for the board's pickers: the design check's summary of each. */
257
+ const unitsOf = async (projectDir, ledger) =>
258
+ (await designUnits(projectDir, ledger)).map((u) => ({
259
+ id: u.id,
260
+ title: u.title,
261
+ type: u.type,
262
+ system: u.system,
263
+ file: `gcf/${u.file}`,
264
+ tbd: u.tbd,
265
+ blocked_by: u.blocked_by,
266
+ ready: u.ready,
267
+ }));
268
+
244
269
  /** `run`, `session` or null. A harness run's lock wins over the mark its run on main holds. */
245
270
  function runningKind(projectDir, id) {
246
271
  if (runHolder(projectDir, id) !== null) return 'run';
@@ -250,15 +275,35 @@ function runningKind(projectDir, id) {
250
275
 
251
276
  /**
252
277
  * What a board may offer (§4.1): nothing while a run drives the item; with the harness, the
253
- * agent's run to an item that waits for one and has no green verify yet.
278
+ * agent's run to an item that waits for one and has no green verify yet. A feature runs through
279
+ * its children: the run gate refuses it.
254
280
  */
255
281
  function offered(c, { running, verified, harness }) {
256
282
  if (running) return [];
257
- const runs = harness && c.data.status === RUNS_FROM && !verified;
283
+ const runs = harness && c.data.status === RUNS_FROM && !verified && c.data.type !== 'feature';
258
284
 
259
285
  return [...(runs ? ['run'] : []), ...movesOf(c.data)];
260
286
  }
261
287
 
288
+ /**
289
+ * The dependencies the run gate would refuse a ready item on now (Board-PRD §5.2); none while
290
+ * it runs, past the gate.
291
+ */
292
+ const waitsOf = (c, running, ledger) =>
293
+ c.data.status === 'ready' && !running
294
+ ? openDepends(ledger, c.data.depends ?? [], { waiting: true })
295
+ : [];
296
+
297
+ /** The files `gcf item attach` gave the item, as project paths; none: no field. */
298
+ async function attachmentsOf(projectDir, id) {
299
+ const dir = path.join(path.resolve(projectDir), 'gcf', 'work', id, 'attachments');
300
+ const files = (await filesUnder(dir))
301
+ .map((f) => path.relative(path.resolve(projectDir), f).replaceAll('\\', '/'))
302
+ .sort();
303
+
304
+ return files.length ? { attachments: files } : {};
305
+ }
306
+
262
307
  /** One item of the board. */
263
308
  async function itemOf(projectDir, c, { verified, ledger, harness }) {
264
309
  const id = String(c.data.id);
@@ -292,14 +337,11 @@ async function itemOf(projectDir, c, { verified, ledger, harness }) {
292
337
  resumable,
293
338
  resume,
294
339
  verified: ready,
295
- // The dependencies the run gate would refuse a ready item on now (Board-PRD §5.2); none
296
- // while it runs, past the gate.
297
- waits_for:
298
- c.data.status === 'ready' && !running
299
- ? openDepends(ledger, c.data.depends ?? [], { waiting: true })
300
- : [],
340
+ waits_for: waitsOf(c, running, ledger),
341
+ needs: needsOf(ledger, c.data.depends ?? []),
301
342
  moves: offered(c, { running, verified: ready, harness }),
302
343
  file: `gcf/work/${c.name}`,
344
+ ...(await attachmentsOf(projectDir, id)),
303
345
  log: logOf(projectDir, id),
304
346
  // Filled by board() from the inbox.
305
347
  lessons: 0,
@@ -341,6 +383,8 @@ export async function board(projectDir) {
341
383
  // The human's settings of config.yml and the agents' language, each with its value and
342
384
  // default (`gcf config set`).
343
385
  settings: await projectSettings(projectDir),
386
+ // Minutes one agent session on an item may run: the harness's limit without --timeout.
387
+ session_timeout_min: config.session_timeout_min,
344
388
  context: {
345
389
  handoff_pct: config.context_handoff_pct,
346
390
  window: config.context_window,
@@ -361,5 +405,6 @@ export async function board(projectDir) {
361
405
  questions: await listQuestions(root),
362
406
  history: await historyOf(root),
363
407
  graveyard: await graveyardOf(root),
408
+ units: await unitsOf(projectDir, ledger),
364
409
  };
365
410
  }
package/lib/config-set.js CHANGED
@@ -1,7 +1,8 @@
1
1
  // `gcf config set` (GCF-PRD §12.4): the human's settings of gcf/config.yml, one key at a time,
2
2
  // so a board edits them through the core and never writes the file itself. A change is checked
3
3
  // by the same rules a read applies before it is written; the rest of the file keeps its keys
4
- // and comments. `phases:` and `agent:` have their own commands and are not set here. The
4
+ // and comments. `phases:` and the permissions of `agent:` have their own commands and are not
5
+ // set here; the project's model and effort (`agent.model`, `agent.effort`) are. The
5
6
  // language agents write in is AI Factory's (`.ai-factory/config.yaml`), set here for the board
6
7
  // too, since AI Factory has no command for it (Board-PRD decision 12).
7
8
  import { readFile } from 'node:fs/promises';
@@ -21,10 +22,12 @@ import {
21
22
  gcfRoot,
22
23
  readRawConfig,
23
24
  RUN_MODES,
25
+ RUN_WORD,
24
26
  } from './gcf-paths.js';
25
27
  import { AIF_CONFIG, LANGUAGE_RE, languageIn, readAifConfig } from './aif-config.js';
28
+ import { agentOf } from './agent-permissions.js';
26
29
 
27
- /** @typedef {'number' | 'share' | 'mode' | 'command' | 'language'} Kind */
30
+ /** @typedef {'number' | 'share' | 'mode' | 'command' | 'language' | 'word'} Kind */
28
31
 
29
32
  // Thrown inside the move to leave without a write or a commit.
30
33
  const NO_CHANGE = new Error('no change');
@@ -52,7 +55,12 @@ export function ensureMap(doc, keys, error) {
52
55
  doc.setIn(keys, doc.createNode({}));
53
56
  }
54
57
 
55
- /** @type {{ key: string, kind: Kind, label: string, file?: string, options?: string[] }[]} */
58
+ /**
59
+ * `presets`: a word whose suggestions are the agent's own (`presets` of the board read), not the
60
+ * framework's.
61
+ * @type {{ key: string, kind: Kind, label: string, file?: string, options?: string[],
62
+ * presets?: 'model' | 'effort' }[]}
63
+ */
56
64
  export const SETTINGS = [
57
65
  {
58
66
  key: 'language.ui',
@@ -78,6 +86,25 @@ export const SETTINGS = [
78
86
  'how a run drives an item: worktree (several at once) or main (one at a time in the ' +
79
87
  'project folder)',
80
88
  },
89
+ {
90
+ key: 'session_timeout_min',
91
+ kind: 'number',
92
+ label:
93
+ 'minutes one agent session on an item may run before it is stopped and the item stays ' +
94
+ 'ready (waits for your answer do not count; above 0, unlike the DoD limit)',
95
+ },
96
+ {
97
+ key: 'agent.model',
98
+ kind: 'word',
99
+ presets: 'model',
100
+ label: "the model an item or a chat thread without its own runs on (empty: the agent's choice)",
101
+ },
102
+ {
103
+ key: 'agent.effort',
104
+ kind: 'word',
105
+ presets: 'effort',
106
+ label: "the effort an item or a chat thread without its own runs with (empty: the agent's)",
107
+ },
81
108
  {
82
109
  key: 'chat.ask',
83
110
  kind: 'mode',
@@ -150,7 +177,17 @@ const BY_KEY = new Map(SETTINGS.map((s) => [s.key, s]));
150
177
  /** @type {[string, string[]][]} */
151
178
  const GROUPS = [
152
179
  ['Language', ['language.ui', 'language.artifacts']],
153
- ['Runs', ['run_mode', 'plan_passes', 'dod_attempts']],
180
+ [
181
+ 'Runs',
182
+ [
183
+ 'run_mode',
184
+ 'session_timeout_min',
185
+ 'agent.model',
186
+ 'agent.effort',
187
+ 'plan_passes',
188
+ 'dod_attempts',
189
+ ],
190
+ ],
154
191
  ['Checks (DoD)', ['dod.test', 'dod.build', 'dod_timeout_min']],
155
192
  ['Chat', ['chat.ask', 'chat.answer_timeout_min']],
156
193
  ['Context', ['context_handoff_pct', 'context_window', 'auto_compact_pct']],
@@ -228,6 +265,15 @@ function valueOf(setting, text) {
228
265
  return t;
229
266
  }
230
267
 
268
+ // `default`, as an item's, leaves the choice to the agent.
269
+ if (setting.kind === 'word') {
270
+ if (!t || t.toLowerCase() === 'default') return null;
271
+ if (!RUN_WORD.test(t))
272
+ throw new Error(`${setting.key} must be one plain word (letters, digits, . - _), e.g. opus`);
273
+
274
+ return t;
275
+ }
276
+
231
277
  if (setting.kind === 'mode') {
232
278
  const options = setting.options ?? [];
233
279
  if (!options.includes(t)) throw new Error(`${setting.key} must be ${options.join(' | ')}`);
@@ -276,6 +322,7 @@ export async function setConfig(projectDir, key, text, { commit = true } = {}) {
276
322
  inputs,
277
323
  mutate,
278
324
  commit: commit && !ignored,
325
+ key: 'config',
279
326
  });
280
327
  const mutate = async () => {
281
328
  const text = existsSync(file) ? await readFile(file, 'utf8') : '';
@@ -290,7 +337,8 @@ export async function setConfig(projectDir, key, text, { commit = true } = {}) {
290
337
  if (value === null) doc.deleteIn(keys);
291
338
  else doc.setIn(keys, value);
292
339
  const raw = doc.toJS();
293
- if (!setting.file) configOf(raw);
340
+ // `agent:` is read by its own rules: a key set here must not leave a broken section.
341
+ if (!setting.file) agentOf(configOf(raw));
294
342
  const out = doc.toString();
295
343
  // The values, not the text: YAML's output may differ in form (a final newline, `{}`).
296
344
  if (isDeepStrictEqual(YAML.parse(text) ?? {}, raw ?? {})) {
@@ -726,6 +726,7 @@ function unitSummary(u, own, values, ctx) {
726
726
 
727
727
  return {
728
728
  id: u.id,
729
+ title: u.header.title ?? null,
729
730
  file: u.file,
730
731
  system: u.system,
731
732
  type: u.header.type ?? null,
@@ -739,14 +740,8 @@ function unitSummary(u, own, values, ctx) {
739
740
  };
740
741
  }
741
742
 
742
- /**
743
- * Run every design check over a project. `blocking` counts the issues that refuse a commit;
744
- * the rest of the report (completeness, readiness, pillars) is a reading, not a gate.
745
- */
746
- export async function designCheck(projectDir) {
747
- const root = path.join(path.resolve(projectDir), 'gcf');
748
- const ledger = await buildLedger(projectDir);
749
- const ctx = await loadContext(root);
743
+ /** The checks of each design unit: their issues and each unit's summary line. */
744
+ async function checkUnits(ledger, ctx) {
750
745
  /** @type {Issue[]} */
751
746
  const issues = [];
752
747
  const units = [];
@@ -756,6 +751,26 @@ export async function designCheck(projectDir) {
756
751
  units.push(unitSummary(u, own, values, ctx));
757
752
  }
758
753
 
754
+ return { issues, units };
755
+ }
756
+
757
+ /** The summary line of each live design unit, without the rest of the design check. */
758
+ export async function designUnits(projectDir, ledger) {
759
+ const root = path.join(path.resolve(projectDir), 'gcf');
760
+
761
+ return (await checkUnits(ledger, await loadContext(root))).units;
762
+ }
763
+
764
+ /**
765
+ * Run every design check over a project. `blocking` counts the issues that refuse a commit;
766
+ * the rest of the report (completeness, readiness, pillars) is a reading, not a gate.
767
+ */
768
+ export async function designCheck(projectDir) {
769
+ const root = path.join(path.resolve(projectDir), 'gcf');
770
+ const ledger = await buildLedger(projectDir);
771
+ const ctx = await loadContext(root);
772
+ const { issues, units } = await checkUnits(ledger, ctx);
773
+
759
774
  for (const c of ledger.items) issues.push(...(await checkItem(c, ctx, ledger)));
760
775
  issues.push(...(await unplayedIssues(root, ledger)));
761
776
  for (const doc of ['game', 'glossary']) issues.push(...(await checkDoc(root, doc, ctx)));
package/lib/domain.js CHANGED
@@ -71,8 +71,9 @@ const decide = (choice, help, fields = [], danger) => ({
71
71
  });
72
72
  const text = (key, label, extra = {}) => ({ key, label, kind: 'text', ...extra });
73
73
  // How an item's run goes: a board offers its agent's presets (`presets`), and `default`, which
74
- // leaves the choice to the agent; a word of the operator's own goes too.
75
- const PICKS = 'default: the agent picks';
74
+ // leaves the choice to the project's `agent.model|effort`, else the agent; a word of the
75
+ // operator's own goes too.
76
+ const PICKS = "default: the project's, else the agent picks";
76
77
  const MODEL = text('model', 'Model of its run', { presets: 'model', help: PICKS });
77
78
  const EFFORT = text('effort', 'Effort of its run', { presets: 'effort', help: PICKS });
78
79
 
@@ -235,7 +236,7 @@ const NEW_ITEM = {
235
236
  text('channel', 'Channel', { required: true, when: { key: 'type', is: ['release'] } }),
236
237
  text('title', 'Title: one line, what it gives'),
237
238
  text('system', 'Subsystems, comma-separated'),
238
- text('depends', 'Depends on ids, comma-separated'),
239
+ { key: 'depends', label: 'Depends on ids, comma-separated', kind: 'ids' },
239
240
  text('parent', 'Parent feature id'),
240
241
  text('milestone', 'Milestone'),
241
242
  text('blocked', 'Start blocked: why (e.g. "file needed")'),
@@ -318,10 +319,11 @@ const BLOCK_SPECS = {
318
319
  };
319
320
 
320
321
  // The item fields a board shows: on the card (`card`), in the drawer (all that have a value).
322
+ // `filter`: the board offers a filter by it; `group`: lanes by it.
321
323
  const GATE_FIELD_OPTIONS = GATES.map((g) => ({ value: g, label: g, help: GATE_HELP[g] }));
322
324
  const FIELDS = [
323
325
  { key: 'priority', label: 'priority', kind: 'rank', help: 'Rank: lower runs sooner', card: true },
324
- { key: 'type', label: 'type', kind: 'text', card: true, badge: true },
326
+ { key: 'type', label: 'type', kind: 'text', card: true, badge: true, filter: true },
325
327
  {
326
328
  key: 'gate',
327
329
  label: 'gate',
@@ -330,8 +332,9 @@ const FIELDS = [
330
332
  help: 'Who closes it',
331
333
  card: true,
332
334
  badge: true,
335
+ filter: true,
333
336
  },
334
- { key: 'severity', label: 'severity', kind: 'text', card: true, badge: true },
337
+ { key: 'severity', label: 'severity', kind: 'text', card: true, badge: true, filter: true },
335
338
  // `edit`: the move that changes it, from the drawer.
336
339
  { key: 'model', label: 'model', kind: 'text', card: true, edit: 'agent' },
337
340
  { key: 'effort', label: 'effort', kind: 'text', edit: 'agent' },
@@ -343,12 +346,26 @@ const FIELDS = [
343
346
  help: 'The run gate refuses it until these are played',
344
347
  card: true,
345
348
  },
346
- { key: 'depends', label: 'depends', kind: 'ids' },
347
- { key: 'needed_by', label: 'needed by', kind: 'ids', help: 'The items that wait for this one' },
348
- { key: 'system', label: 'system', kind: 'list' },
349
- { key: 'parent', label: 'parent', kind: 'text' },
349
+ { key: 'depends', label: 'depends', kind: 'ids', edit: 'depends' },
350
+ {
351
+ key: 'needed_by',
352
+ label: 'needed by',
353
+ kind: 'ids',
354
+ help: 'The items that wait for this one',
355
+ card: true,
356
+ },
357
+ {
358
+ key: 'needs',
359
+ label: 'needs',
360
+ kind: 'ids',
361
+ help: 'Its dependencies that have not ended in history yet',
362
+ card: true,
363
+ },
364
+ { key: 'system', label: 'system', kind: 'list', filter: true, group: true },
365
+ // One id: a board shows an `ids` field's single value as that one id.
366
+ { key: 'parent', label: 'parent', kind: 'ids', group: true },
350
367
  { key: 'children', label: 'children', kind: 'ids' },
351
- { key: 'milestone', label: 'milestone', kind: 'text' },
368
+ { key: 'milestone', label: 'milestone', kind: 'text', filter: true, group: true },
352
369
  { key: 'blocked', label: 'blocked', kind: 'longtext', help: 'Why it stopped', card: true },
353
370
  ];
354
371
 
@@ -388,7 +405,9 @@ const SECTIONS = {
388
405
  verdicts: ['verdict:keep', 'verdict:tune', 'verdict:kill'],
389
406
  },
390
407
  history: { label: 'Accepted' },
391
- graveyard: { label: 'Graveyard' },
408
+ // `match`: the item's field Related holds against the graveyard's tags.
409
+ graveyard: { label: 'Graveyard', match: 'system' },
410
+ units: { label: 'Design units' },
392
411
  };
393
412
 
394
413
  // The gcf commands that change the project: a project chat asks the operator before each one
package/lib/gcf-paths.js CHANGED
@@ -24,8 +24,16 @@ export const DEFAULT_CONFIG = {
24
24
  context_window: 0,
25
25
  // CLAUDE_AUTOCOMPACT_PCT_OVERRIDE for the run (0: the agent's own default).
26
26
  auto_compact_pct: 0,
27
+ // Minutes one agent session on an item may run (waits for the operator's answer do not
28
+ // count); a context handoff starts the next session with its own. Never 0: a session with no
29
+ // limit could hold a night queue until morning.
30
+ session_timeout_min: 120,
27
31
  };
28
32
 
33
+ // A model or effort word as the agent's command line takes it; a leading hyphen would read as a
34
+ // flag of it.
35
+ export const RUN_WORD = /^[A-Za-z0-9][\w.-]*$/;
36
+
29
37
  const PCT_KEYS = ['context_handoff_pct', 'auto_compact_pct'];
30
38
 
31
39
  /** `gcf/` lives at the repository root (GCF-PRD §5.1). Throws when absent. */
@@ -109,6 +117,8 @@ export function configOf(parsed) {
109
117
  }
110
118
  }
111
119
 
120
+ if (config.session_timeout_min === 0)
121
+ throw new Error('gcf/config.yml: session_timeout_min must be above 0: a session needs a limit');
112
122
  for (const key of PCT_KEYS)
113
123
  if (config[key] > 100)
114
124
  throw new Error(`gcf/config.yml: ${key} is a share of the window, 0-100, got ${config[key]}`);
package/lib/git.js CHANGED
@@ -51,17 +51,54 @@ export function dirtyPaths(projectDir, paths) {
51
51
  return res.status === 0 ? res.stdout.split('\n').filter(Boolean) : [];
52
52
  }
53
53
 
54
+ const BY = ['run', 'session', 'operator'];
55
+
56
+ /**
57
+ * Who makes a move: `GCF_MOVE_BY` when it names one (the harness sets `run` for both run modes),
58
+ * else a harness run's owner, else a Claude Code session, else the operator.
59
+ */
60
+ export function moveBy(env = process.env) {
61
+ if (BY.includes(env.GCF_MOVE_BY ?? '')) return /** @type {string} */ (env.GCF_MOVE_BY);
62
+ if (env.GCF_RUN_OWNER) return 'run';
63
+
64
+ return env.CLAUDE_CODE_SESSION_ID ? 'session' : 'operator';
65
+ }
66
+
67
+ /**
68
+ * The trailer paragraph of a move's commit as `git commit`/`git merge` arguments (`gcf item
69
+ * history` reads it): the items and units it touched, the domain's move key, who made it. A
70
+ * separate `-m`, not `--trailer`: any git version takes it. None without a move key.
71
+ * @param {{key?: string, items?: string[]}} [move]
72
+ */
73
+ export function moveTrailers({ key, items = [] } = {}) {
74
+ if (!key) return [];
75
+ const ids = [...new Set(items)];
76
+ const lines = [
77
+ ...(ids.length ? [`GCF-Items: ${ids.join(', ')}`] : []),
78
+ `GCF-Move: ${key}`,
79
+ `GCF-By: ${moveBy()}`,
80
+ ];
81
+
82
+ return ['-m', lines.join('\n')];
83
+ }
84
+
54
85
  /**
55
86
  * Stage and commit exactly `paths`: `git add -- gcf/` would stage a user's unrelated edits
56
87
  * under gcf/, and a rollback only restores what it snapshotted. A path that neither exists nor
57
- * is tracked is left out — git refuses a pathspec that matches nothing. Returns the new HEAD.
88
+ * is tracked is left out — git refuses a pathspec that matches nothing. `move` gives the
89
+ * commit its trailers (moveTrailers). Returns the new HEAD.
90
+ * @param {string} projectDir
91
+ * @param {string} message
92
+ * @param {string[]} paths
93
+ * @param {{key?: string, items?: string[]}} [move]
58
94
  */
59
- export function commitPaths(projectDir, message, paths) {
95
+ export function commitPaths(projectDir, message, paths, move = {}) {
60
96
  const staged = paths.filter((p) => existsSync(p) || tracked(projectDir, p));
61
97
  for (const p of staged) spawnSync('git', ['add', '--', p], { cwd: projectDir, stdio: 'ignore' });
62
98
  // A file staged but never committed and now deleted is out of the index too: no pathspec.
63
99
  const real = staged.filter((p) => existsSync(p) || inHead(projectDir, p));
64
- const res = spawnSync('git', ['commit', '-m', message, '--only', '--', ...real], {
100
+ const msg = ['-m', message, ...moveTrailers(move)];
101
+ const res = spawnSync('git', ['commit', ...msg, '--only', '--', ...real], {
65
102
  cwd: projectDir,
66
103
  encoding: 'utf8',
67
104
  });
package/lib/history.js ADDED
@@ -0,0 +1,105 @@
1
+ // `gcf item history <id>` (board v2): the moves an item went through, read from git. A move's
2
+ // commit carries trailers (git.js moveTrailers): GCF-Items, GCF-Move, GCF-By. A commit older
3
+ // than them is read by its subject's fixed format, the id taken only from its place in it.
4
+ import { spawnSync } from 'node:child_process';
5
+
6
+ export const HISTORY_MAX = 200;
7
+
8
+ /**
9
+ * The subjects of the moves before the trailers: each gives the domain's move key and the ids
10
+ * it moved. A system name in a verdict's tail (`keep dash → movement`) names no item.
11
+ * shortcut: a feature kill's children are not in its subject, so an old kill shows in the
12
+ * feature's history only; the trailers carry them from now on.
13
+ * @type {[RegExp, (m: RegExpMatchArray) => {move: string, ids: string[]}][]}
14
+ */
15
+ export const OLD_SUBJECTS = [
16
+ [/^gcf\(verdict\): (keep|tune|kill) (\S+) →/, (m) => ({ move: `verdict:${m[1]}`, ids: [m[2]] })],
17
+ // Before 2026-10-09 a verdict named the card's number, then its slug.
18
+ [
19
+ /^gcf\(verdict\): (keep|tune|kill) \S+ (\S+) →/,
20
+ (m) => ({ move: `verdict:${m[1]}`, ids: [m[2]] }),
21
+ ],
22
+ [/^gcf\(decide\): ([a-z]+) (\S+)$/, (m) => ({ move: `decide:${m[1]}`, ids: [m[2]] })],
23
+ [/^gcf\(priority\): (\S+(?:, \S+)*)$/, (m) => ({ move: 'prioritize', ids: m[1].split(', ') })],
24
+ [/^gcf\(item\): (\S+) model \S+, effort \S+$/, (m) => ({ move: 'agent', ids: [m[1]] })],
25
+ [/^gcf\(item\): (\S+)$/, (m) => ({ move: 'item-new', ids: [m[1]] })],
26
+ [/^gcf\(integrate\): (\S+)(?: plan)?$/, (m) => ({ move: 'integrate', ids: [m[1]] })],
27
+ // A submit or close may say why it went without a green verify or with tasks unticked.
28
+ [/^gcf\((submit|close)\): (\S+)(?: |$)/, (m) => ({ move: m[1], ids: [m[2]] })],
29
+ [
30
+ /^gcf\((block|unblock|drop|done|depends|attach|verified)\): (\S+)$/,
31
+ (m) => ({ move: m[1], ids: [m[2]] }),
32
+ ],
33
+ ];
34
+
35
+ /** The move key and ids of a commit subject older than the trailers, or null. */
36
+ export function oldMove(subject) {
37
+ for (const [re, read] of OLD_SUBJECTS) {
38
+ const m = subject.match(re);
39
+ if (m) return read(m);
40
+ }
41
+
42
+ return null;
43
+ }
44
+
45
+ /**
46
+ * A trailer's value in a commit body, or null: from its last paragraph only, where the trailers
47
+ * stand. Words an operator gave the commit (a phase's reason) come before it and name no move.
48
+ */
49
+ const trailer = (body, key) =>
50
+ (
51
+ body
52
+ .trim()
53
+ .split(/\n\s*\n/)
54
+ .at(-1) ?? ''
55
+ )
56
+ .match(new RegExp(`^${key}: *(.*)$`, 'm'))?.[1]
57
+ .trim() ?? null;
58
+
59
+ const BY = ['run', 'session', 'operator'];
60
+
61
+ /**
62
+ * What one commit says of item `id`: `{move, by}` when it moved the item, else null. A commit
63
+ * with a GCF-Move trailer is read by its trailers only.
64
+ */
65
+ export function moveOf(subject, body, id) {
66
+ const key = trailer(body, 'GCF-Move');
67
+ if (key) {
68
+ const items = (trailer(body, 'GCF-Items') ?? '').split(',').map((s) => s.trim());
69
+ if (!items.includes(id)) return null;
70
+ const by = trailer(body, 'GCF-By');
71
+
72
+ return { move: key, by: BY.includes(by ?? '') ? by : null };
73
+ }
74
+
75
+ const old = oldMove(subject);
76
+
77
+ return old?.ids.includes(id) ? { move: old.move, by: null } : null;
78
+ }
79
+
80
+ // Field and record separators git writes between the parts of each commit.
81
+ const FS = '\x1f';
82
+ const RS = '\x1e';
83
+
84
+ /**
85
+ * The moves of item `id`, newest first, up to `limit`: `{at, commit, move, subject, by}`. An item
86
+ * that ended (history, graveyard) keeps them: its commits stay in git. [] outside a repository.
87
+ */
88
+ export function itemHistory(projectDir, id, { limit = HISTORY_MAX } = {}) {
89
+ const res = spawnSync(
90
+ 'git',
91
+ ['log', `--format=%h${FS}%cI${FS}%s${FS}%b${RS}`, '--fixed-strings', '--grep=gcf(', '--'],
92
+ { cwd: projectDir, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 },
93
+ );
94
+ if (res.status !== 0) return [];
95
+ const moves = [];
96
+ for (const rec of res.stdout.split(RS)) {
97
+ const [commit, at, subject, body = ''] = rec.replace(/^\n/, '').split(FS);
98
+ if (!subject?.startsWith('gcf(')) continue;
99
+ const move = moveOf(subject, body, id);
100
+ if (move) moves.push({ at, commit, move: move.move, subject, by: move.by });
101
+ if (moves.length >= limit) break;
102
+ }
103
+
104
+ return moves;
105
+ }
package/lib/inbox.js CHANGED
@@ -47,7 +47,7 @@ export function checkTags(tags) {
47
47
  }
48
48
 
49
49
  /** Every file under a folder, deepest last; none when it is not there. */
50
- async function filesUnder(dir) {
50
+ export async function filesUnder(dir) {
51
51
  if (!existsSync(dir)) return [];
52
52
  const entries = await readdir(dir, { recursive: true, withFileTypes: true });
53
53
 
package/lib/integrate.js CHANGED
@@ -13,6 +13,7 @@ import { verifyItem, deltaProblems } from './verify.js';
13
13
  import { submitItem, closeItem, blockItem } from './work-ops.js';
14
14
  import { isValidId } from './id.js';
15
15
  import { writeIndex } from './index-gen.js';
16
+ import { moveTrailers } from './git.js';
16
17
 
17
18
  const TRAILER = 'GCF-Verified';
18
19
  export const branchOf = (id) => `work/${id}`;
@@ -129,7 +130,9 @@ export async function markVerified(worktreeDir, id, opts = {}) {
129
130
  throw new Error('commit the work first: the trailer marks a commit, not a working tree');
130
131
  const r = await verifyItem(worktreeDir, id, opts);
131
132
  if (!r.ok) return { ...r, marked: false };
132
- const msg = ['-m', `gcf(verified): ${id}`, '-m', `${TRAILER}: ${id}`];
133
+ // One trailer paragraph: git reads trailers from the last paragraph only.
134
+ const [, trailers] = moveTrailers({ key: 'verified', items: [id] });
135
+ const msg = ['-m', `gcf(verified): ${id}`, '-m', `${TRAILER}: ${id}\n${trailers}`];
133
136
  git(worktreeDir, ['commit', '--allow-empty', ...msg]);
134
137
 
135
138
  return { ...r, marked: true };
@@ -252,7 +255,15 @@ async function integrateSpike(projectDir, item) {
252
255
  git(projectDir, ['checkout', branchOf(id), '--', plan]);
253
256
  // A plan main already holds as it is (a rerun after a crash) has nothing to commit.
254
257
  if (!git(projectDir, ['diff', '--cached', '--quiet', '--', plan], { check: false }).ok)
255
- git(projectDir, ['commit', '-m', `gcf(integrate): ${id} plan`, '--only', '--', plan]);
258
+ git(projectDir, [
259
+ 'commit',
260
+ '-m',
261
+ `gcf(integrate): ${id} plan`,
262
+ ...moveTrailers({ key: 'integrate', items: [id] }),
263
+ '--only',
264
+ '--',
265
+ plan,
266
+ ]);
256
267
  }
257
268
 
258
269
  git(projectDir, ['tag', '-f', `spike/${id}`, branchOf(id)]);
@@ -263,7 +274,8 @@ async function integrateSpike(projectDir, item) {
263
274
 
264
275
  /** Merge the branch; null when it went in, else the conflict or the refusal. */
265
276
  async function mergeBranch(projectDir, id) {
266
- const args = ['merge', '--no-ff', '--no-edit', '-m', `gcf(integrate): ${id}`, branchOf(id)];
277
+ const msg = ['-m', `gcf(integrate): ${id}`, ...moveTrailers({ key: 'integrate', items: [id] })];
278
+ const args = ['merge', '--no-ff', '--no-edit', ...msg, branchOf(id)];
267
279
  const merge = git(projectDir, args, { check: false });
268
280
  if (merge.ok || (await mergedPastIndex(projectDir))) return null;
269
281
  const head = ['rev-parse', '-q', '--verify', 'MERGE_HEAD'];
@@ -337,6 +349,7 @@ function commitMetrics(projectDir) {
337
349
  '--no-verify',
338
350
  '-m',
339
351
  'gcf(metrics): run logs',
352
+ ...moveTrailers({ key: 'metrics' }),
340
353
  '--only',
341
354
  '--',
342
355
  'gcf/.metrics',
package/lib/phase.js CHANGED
@@ -227,6 +227,7 @@ async function nextPhaseUnlocked(projectDir, { reason = '', commit = true } = {}
227
227
  files: [liveFile(root)],
228
228
  mutate: () => writeLive(root, { ...live, phase: status.next }),
229
229
  commit,
230
+ key: 'phase-next',
230
231
  });
231
232
 
232
233
  return { from: status.phase, to: status.next, forced: unmet.map((c) => c.name), hash };
package/lib/pillars.js CHANGED
@@ -66,9 +66,19 @@ async function revise(projectDir, id, { edit, editPillars, tail, commit }) {
66
66
  }
67
67
  };
68
68
 
69
+ const units = ledger.design
70
+ .flatMap((d) => d.units)
71
+ .filter((u) => [listOf(u.header.pillars)].flat().includes(id));
72
+
69
73
  return {
70
74
  id,
71
- hash: await commitMove(projectDir, `gcf(pillar): ${tail}`, { files, mutate, commit }),
75
+ hash: await commitMove(projectDir, `gcf(pillar): ${tail}`, {
76
+ files,
77
+ mutate,
78
+ commit,
79
+ key: 'pillar',
80
+ items: [...units.map((u) => u.id), ...items.map((c) => String(c.data.id))],
81
+ }),
72
82
  bare: items.filter((c) => !edit(c.data.pillars).length).map((c) => String(c.data.id)),
73
83
  };
74
84
  }
package/lib/questions.js CHANGED
@@ -119,6 +119,7 @@ async function answerUnlocked(projectDir, qid, answer, { commit = true } = {}) {
119
119
  old.slice(rec.start + rec.text.length),
120
120
  ),
121
121
  commit,
122
+ key: 'question-answer',
122
123
  });
123
124
 
124
125
  return { id: qid, answer: text, hash };
package/lib/unit-ops.js CHANGED
@@ -230,7 +230,9 @@ function uncommitted(projectDir, file) {
230
230
  * their own uncommitted edits (an answer, a live: delta) ride along on purpose.
231
231
  * @param {string} projectDir
232
232
  * @param {string} message
233
- * @param {{files: string[], mutate: () => Promise<void>, commit: boolean, inputs?: string[]}} move
233
+ * `key` is the domain's move key and `items` the ids it touched: the commit's trailers.
234
+ * @param {{files: string[], mutate: () => Promise<void>, commit: boolean, inputs?: string[],
235
+ * key?: string, items?: string[]}} move
234
236
  */
235
237
  /** A worktree of the integrator (Methodology §7): its gcf/ state is main's to move. */
236
238
  export const onWorkBranch = (projectDir) =>
@@ -248,7 +250,7 @@ export async function commitMove(projectDir, message, move) {
248
250
  : record(projectDir, message, move);
249
251
  }
250
252
 
251
- async function record(projectDir, message, { files, mutate, commit, inputs = [] }) {
253
+ async function record(projectDir, message, { files, mutate, commit, inputs = [], key, items }) {
252
254
  if (commit && onWorkBranch(projectDir))
253
255
  throw new Error(
254
256
  `cannot record ${message} on a work/ branch: a worktree records no move — the run ` +
@@ -276,7 +278,7 @@ async function record(projectDir, message, { files, mutate, commit, inputs = []
276
278
  async () => {
277
279
  await mutate();
278
280
  await writeIndex(root);
279
- if (commit) hash = commitPaths(projectDir, message, touched);
281
+ if (commit) hash = commitPaths(projectDir, message, touched, { key, items });
280
282
  },
281
283
  { gitCwd: commit ? path.resolve(projectDir) : null },
282
284
  );
@@ -312,7 +314,13 @@ async function doneUnitUnlocked(projectDir, id, { constraints = [], commit = tru
312
314
 
313
315
  return {
314
316
  id,
315
- hash: await commitMove(projectDir, `gcf(done): ${id}`, { files, mutate, commit }),
317
+ hash: await commitMove(projectDir, `gcf(done): ${id}`, {
318
+ files,
319
+ mutate,
320
+ commit,
321
+ key: 'done',
322
+ items: [id],
323
+ }),
316
324
  };
317
325
  }
318
326
 
@@ -350,6 +358,12 @@ async function dropUnitUnlocked(projectDir, id, { reason, tags = [], commit = tr
350
358
 
351
359
  return {
352
360
  id,
353
- hash: await commitMove(projectDir, `gcf(drop): ${id}`, { files, mutate, commit }),
361
+ hash: await commitMove(projectDir, `gcf(drop): ${id}`, {
362
+ files,
363
+ mutate,
364
+ commit,
365
+ key: 'drop',
366
+ items: [id],
367
+ }),
354
368
  };
355
369
  }
package/lib/work-ops.js CHANGED
@@ -10,7 +10,7 @@ import { createHash } from 'node:crypto';
10
10
  import path from 'node:path';
11
11
  import { parse, serialize } from './frontmatter.js';
12
12
  import { buildLedger } from './ledger.js';
13
- import { readConfig } from './gcf-paths.js';
13
+ import { readConfig, RUN_WORD } from './gcf-paths.js';
14
14
  import { atomicWrite, resolveInside } from './safe-path.js';
15
15
  import { allowedFrom, decisionFits, FEATURE_ONLY, fromOf } from './transitions.js';
16
16
  import { ITEM_TYPES, DEFAULT_GATE, GATES, SEVERITIES, UNIT_ITEM_TYPES } from './validate-item.js';
@@ -206,6 +206,8 @@ async function begin(projectDir, id, move) {
206
206
  item,
207
207
  /** @type {Set<string>} ids leaving systems/ in this move */
208
208
  leaving: new Set(),
209
+ /** @type {Set<string>} every item the move touches, for its commit's GCF-Items */
210
+ items: new Set([id]),
209
211
  files,
210
212
  touch: (...f) => files.push(...f.filter((x) => !files.includes(x))),
211
213
  step: (fn) => steps.push(fn),
@@ -223,13 +225,19 @@ async function begin(projectDir, id, move) {
223
225
  };
224
226
  }
225
227
 
226
- /** Commit the move as `gcf(<move>): <tail>` with every file it touched (item edits included). */
227
- async function finish(m, move, tail, commit) {
228
+ /**
229
+ * Commit the move as `gcf(<move>): <tail>` with every file it touched (item edits included);
230
+ * `key` is the domain's move key its trailer carries (`verdict:keep`), its head the move.
231
+ */
232
+ async function finish(m, key, tail, commit) {
233
+ const move = key.split(':')[0];
228
234
  const hash = await commitMove(m.projectDir, `gcf(${move}): ${tail}`, {
229
235
  files: m.files,
230
236
  mutate: m.run,
231
237
  commit,
232
238
  inputs: [m.item.file],
239
+ key,
240
+ items: [...m.items],
233
241
  });
234
242
  // A move on the item ends the session that worked it: the board stops showing it running,
235
243
  // and no rerun resumes it.
@@ -429,6 +437,7 @@ function freshId(ledger, base) {
429
437
  function removalItem(m, item, reason) {
430
438
  const id = freshId(m.ledger, `remove-${item.data.id}`);
431
439
  const file = path.join(m.root, 'work', `${id}.md`);
440
+ m.items.add(id);
432
441
  const data = {
433
442
  schema: 3,
434
443
  id,
@@ -455,6 +464,7 @@ function parentWaits(m, item) {
455
464
  const { status } = parent.data;
456
465
  if (status !== 'ready' && status !== 'blocked') return;
457
466
  m.touch(parent.file);
467
+ m.items.add(String(parent.data.id));
458
468
  // A blocked feature keeps its reason: the dead child is added to it, unblock decides later.
459
469
  const data =
460
470
  status === 'blocked'
@@ -477,6 +487,8 @@ function endToGraveyard(
477
487
  const why = String(reason ?? '').trim();
478
488
  if (!why) throw new Error(`${id}: the graveyard keeps a reason — give one`);
479
489
  m.touch(path.join(m.root, 'graveyard.md'), item.file);
490
+ // A feature's kill takes its live children down in the same commit.
491
+ m.items.add(id);
480
492
  const lineTags = tags.length ? tags : (item.data.system ?? []);
481
493
  m.step(() => buryLine(m.root, id, { type: item.data.type, reason: why, tags: lineTags }));
482
494
  if (item.data.status === 'unplayed') unplay(m, item);
@@ -684,7 +696,8 @@ async function verdictItemUnlocked(projectDir, id, verdict, opts = {}) {
684
696
  if (verdict === 'keep') await keep(m, constraints);
685
697
  else if (verdict === 'tune') await tune(m, note);
686
698
  else removal = endToGraveyard(m, m.item, { reason: note, tags, removal: remove ?? true });
687
- const hash = await finish(m, 'verdict', `${verdict} ${id} → ${systems.join(',')}`, commit);
699
+ const tail = `${verdict} ${id} → ${systems.join(',')}`;
700
+ const hash = await finish(m, `verdict:${verdict}`, tail, commit);
688
701
 
689
702
  return { verdict, id, systems, hash, removal };
690
703
  }
@@ -759,7 +772,7 @@ async function decideItemUnlocked(projectDir, id, choice, opts = {}) {
759
772
  const m = await begin(projectDir, id, `decide:${choice}`);
760
773
  fitDecision(choice, m.item);
761
774
  const removal = DECIDE[choice](m, { reason, remove }) ?? null;
762
- const hash = await finish(m, 'decide', `${choice} ${id}`, commit);
775
+ const hash = await finish(m, `decide:${choice}`, `${choice} ${id}`, commit);
763
776
 
764
777
  return { id, choice, hash, removal };
765
778
  }
@@ -815,9 +828,6 @@ async function dropItemUnlocked(projectDir, id, opts = {}) {
815
828
  return { id, hash: await finish(m, 'drop', id, commit), removal };
816
829
  }
817
830
 
818
- // A leading hyphen would read as a flag of the agent's command line.
819
- export const RUN_WORD = /^[A-Za-z0-9][\w.-]*$/;
820
-
821
831
  /** The version and channel of a new item: well-formed, and only on a release. */
822
832
  function checkRelease(spec) {
823
833
  const { type, version, channel } = spec;
@@ -1013,6 +1023,8 @@ async function prioritizeItemsUnlocked(projectDir, ids, { commit = true } = {})
1013
1023
  await atomicWrite(i.file, serialize({ ...i.data, priority: ranks[n] }, i.body));
1014
1024
  },
1015
1025
  commit,
1026
+ key: 'prioritize',
1027
+ items: ids,
1016
1028
  });
1017
1029
 
1018
1030
  return { ids, hash };
@@ -1049,6 +1061,8 @@ async function setDependsUnlocked(projectDir, id, { add = [], remove = [], commi
1049
1061
  inputs: [item.file],
1050
1062
  mutate: () => atomicWrite(item.file, serialize({ ...item.data, depends }, item.body)),
1051
1063
  commit,
1064
+ key: 'depends',
1065
+ items: [id],
1052
1066
  });
1053
1067
 
1054
1068
  return { id, depends, hash };
@@ -1056,7 +1070,7 @@ async function setDependsUnlocked(projectDir, id, { add = [], remove = [], commi
1056
1070
 
1057
1071
  /**
1058
1072
  * Set how item `id`'s runs go: its `model` and `effort`, each given one a plain word, `default`
1059
- * taking the field off (the agent's own choice). One commit `gcf(item)`. A run in progress keeps
1073
+ * taking the field off (the project's `agent.model|effort`, else the agent's own choice). One commit `gcf(item)`. A run in progress keeps
1060
1074
  * its own; the item's next run takes the new value.
1061
1075
  * @param {string} projectDir
1062
1076
  * @param {string} id
@@ -1085,6 +1099,8 @@ async function setAgentUnlocked(projectDir, id, { model, effort, commit = true }
1085
1099
  inputs: [item.file],
1086
1100
  mutate: () => atomicWrite(item.file, serialize(data, item.body)),
1087
1101
  commit,
1102
+ key: 'agent',
1103
+ items: [id],
1088
1104
  },
1089
1105
  );
1090
1106
 
@@ -1118,6 +1134,8 @@ async function attachItemUnlocked(projectDir, id, file, { commit = true } = {})
1118
1134
  await copyFile(file, to);
1119
1135
  },
1120
1136
  commit,
1137
+ key: 'attach',
1138
+ items: [id],
1121
1139
  });
1122
1140
 
1123
1141
  return { id, file: path.relative(projectDir, to).replaceAll('\\', '/'), hash };
@@ -1142,6 +1160,16 @@ export const attachItem = (projectDir, id, file, opts = {}) =>
1142
1160
  /** The longest note a new item takes (AD-39): a proposal's, or the operator's. */
1143
1161
  export const NOTE_MAX = 4000;
1144
1162
 
1163
+ /** The parent feature's file with the new child in its `children`; none without a parent. */
1164
+ function parentWrite(ledger, spec) {
1165
+ if (!spec.parent) return [];
1166
+ const p = ledger.item(spec.parent);
1167
+ if (!p || p.data.type !== 'feature') throw new Error(`${spec.parent} is not a live feature item`);
1168
+ const children = [...new Set([...(p.data.children ?? []), spec.id])];
1169
+
1170
+ return [[p.file, serialize({ ...p.data, children }, p.body)]];
1171
+ }
1172
+
1145
1173
  async function newItemUnlocked(projectDir, spec) {
1146
1174
  const root = gcfOf(projectDir);
1147
1175
  const ledger = await buildLedger(projectDir);
@@ -1158,14 +1186,10 @@ async function newItemUnlocked(projectDir, spec) {
1158
1186
  const note = [spec.note, take.note].filter((x) => x?.trim()).join('\n\n') || undefined;
1159
1187
  const item = { ...spec, title: take.title, note };
1160
1188
 
1161
- const writes = [[file, newItemText(item, gate, headHash(projectDir))]];
1162
- if (spec.parent) {
1163
- const p = ledger.item(spec.parent);
1164
- if (!p || p.data.type !== 'feature')
1165
- throw new Error(`${spec.parent} is not a live feature item`);
1166
- const children = [...new Set([...(p.data.children ?? []), spec.id])];
1167
- writes.push([p.file, serialize({ ...p.data, children }, p.body)]);
1168
- }
1189
+ const writes = [
1190
+ [file, newItemText(item, gate, headHash(projectDir))],
1191
+ ...parentWrite(ledger, spec),
1192
+ ];
1169
1193
 
1170
1194
  // `commit` is for a caller with no console to commit from, a board: a run starts from HEAD.
1171
1195
  const hash = await commitMove(projectDir, `gcf(item): ${spec.id}`, {
@@ -1176,6 +1200,8 @@ async function newItemUnlocked(projectDir, spec) {
1176
1200
  await take.apply();
1177
1201
  },
1178
1202
  commit: spec.commit ?? false,
1203
+ key: 'item-new',
1204
+ items: [spec.id, ...(spec.parent ? [spec.parent] : [])],
1179
1205
  });
1180
1206
 
1181
1207
  return { item: `gcf/work/${spec.id}.md`, hash };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-aif-ext",
3
- "version": "0.12.4",
3
+ "version": "0.14.0",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -11,6 +11,7 @@ gcf_work:
11
11
  - before planning an item, run `ai-factory gcf context <id>` and read only the files it lists under `gcf/`
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
+ - a question about past runs (an item's results, what it ran on, its cost, the part of its log a run wrote) is answered by `ai-factory gcf-harness runs [--item <id>] --json`; `ai-factory gcf-harness run <ids...> --model <m> --effort <e>` runs items on another model for that run only, the item unchanged
14
15
  - 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
16
  - 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
17
  - 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
@@ -23,8 +24,10 @@ gcf_work:
23
24
  - the human plays from `ai-factory gcf playtest session`; each free note from that play goes to `ai-factory gcf inbox add --source playtest "<note>"`
24
25
  - a release item carries `version:` and `channel:` (`item new <id> --type release --release <v> --channel <c>`): its end writes the `release:` block of `gcf/LIVE.md`
25
26
  - `item new` and `take` refuse a type the current phase does not take: run `ai-factory gcf phase` and bring the refusal to the human
26
- - an item the human wants run on a given model or effort gets `item new <id> --model <m> --effort <e>`: the harness run passes both to the agent; an existing item changes with `ai-factory gcf item agent <id> --model <m> --effort <e>` (`default` takes one off: the agent picks), never a hand edit; its next run takes them
27
+ - an item the human wants run on a given model or effort gets `item new <id> --model <m> --effort <e>`: the harness run passes both to the agent; an existing item changes with `ai-factory gcf item agent <id> --model <m> --effort <e>` (`default` takes one off), never a hand edit; its next run takes them; an item without its own runs on the project's `agent.model` and `agent.effort` of `gcf/config.yml`, a setting of the human
28
+ - before starting a run, `ai-factory gcf-harness gate --each <ids...> --json` says what the run gate refuses each item alone for now (it exits 0; a batch is still gated as a whole by `gate <ids...>`, exit 1); a session stops after `session_timeout_min` of `gcf/config.yml`, its item stays ready
27
29
  - ready items run in `priority:` order, lower first: rank a set of items with `ai-factory gcf prioritize <id> <id> …`, and put an id in `depends` only when the item uses that one's data or code: `ai-factory gcf depends <id> --add <ids>` or `--remove <ids>`, never a hand edit
30
+ - what happened to an item before (who submitted, blocked, tuned or reranked it, and when) is `ai-factory gcf item history <id>`: its moves from git, an ended item's too
28
31
  - a picture or file the human gives an item goes to `ai-factory gcf item attach <id> --file <path>` (its `gcf/work/<id>/attachments/`, committed); read an item's attachments before you plan it
29
32
  - write what the human reads (a question, an assumption, a block reason, an inbox entry, a lesson, a report, an item's `title:`) in `language.ui` of `.ai-factory/config.yaml`, and the body of an item that is not a design unit in its `language.artifacts`
30
33
  - write in English whatever lands in a checked document: `gcf/design/`, `gcf/systems/`, `gcf/glossary.md`, `gcf/PILLARS.md`, `gcf/LIVE.md`, the body of a design unit's item but its `tuning:` and `notes:`, an item's `live:` summary; an answer that moves into a unit's slot goes there in English