gcf-aif-ext 0.29.2 → 0.32.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/lib/config-set.js CHANGED
@@ -22,6 +22,8 @@ import {
22
22
  GATE_POLICY,
23
23
  gcfRoot,
24
24
  readRawConfig,
25
+ REVIEW_DEFAULTS,
26
+ reviewRowProblem,
25
27
  RUN_MODES,
26
28
  RUN_WORD,
27
29
  } from './gcf-paths.js';
@@ -29,7 +31,10 @@ import { AIF_CONFIG, LANGUAGE_RE, languageIn, readAifConfig } from './aif-config
29
31
  import { agentOf } from './agent-permissions.js';
30
32
  import { configDoc, ensureMap } from './config-doc.js';
31
33
 
32
- /** @typedef {'number' | 'share' | 'mode' | 'command' | 'language' | 'word' | 'list'} Kind */
34
+ /**
35
+ * @typedef {'number' | 'share' | 'mode' | 'command' | 'language' | 'word' | 'list' | 'passes'}
36
+ * Kind
37
+ */
33
38
 
34
39
  // Thrown inside the move to leave without a write or a commit.
35
40
  const NO_CHANGE = new Error('no change');
@@ -40,8 +45,11 @@ const LANGUAGES = ['en', 'ru', 'de', 'fr', 'es', 'zh', 'ja', 'ko', 'pt', 'it'];
40
45
  /**
41
46
  * `presets`: a word whose suggestions are the agent's own (`presets` of the board read), not the
42
47
  * framework's.
48
+ * `title`, `hint`, `help`, the range (`min`, `max`, `step`, `unit`) and `example` are added
49
+ * below (Operator-Tasks-Plan t3).
43
50
  * @type {{ key: string, kind: Kind, label: string, file?: string, options?: string[],
44
- * presets?: 'model' | 'effort' }[]}
51
+ * presets?: 'model' | 'effort', title?: string, hint?: string, help?: string, min?: number,
52
+ * max?: number, step?: number, unit?: string, example?: string }[]}
45
53
  */
46
54
  export const SETTINGS = [
47
55
  {
@@ -79,38 +87,28 @@ export const SETTINGS = [
79
87
  key: 'agent.model',
80
88
  kind: 'word',
81
89
  presets: 'model',
82
- label: 'the model an item or a chat thread without its own runs on (not set: Opus)',
90
+ label: 'the model an item or a chat thread without its own runs on',
83
91
  },
84
92
  {
85
93
  key: 'agent.effort',
86
94
  kind: 'word',
87
95
  presets: 'effort',
88
- label: 'the effort an item or a chat thread without its own runs with (not set: High)',
96
+ label: 'the effort an item or a chat thread without its own runs with',
89
97
  },
90
- // The plan's outside reviewer (Hold-Plan d17): a read-only audit pass, Claude's when it fails.
98
+ // The review passes (Operator-Tasks-Plan t2 d1): row k makes pass k, as `agent:model:effort`.
91
99
  {
92
- key: 'plan_review.agent',
93
- kind: 'word',
100
+ key: 'review.plan',
101
+ kind: 'passes',
94
102
  label:
95
- 'the outside reviewer of a plan that keeps finding blocking issues ' +
96
- '(not set: codex; none: off)',
97
- },
98
- {
99
- key: 'plan_review.model',
100
- kind: 'word',
101
- label: 'the model of the plan review (not set: gpt-6-astra)',
103
+ 'the passes of a plan review, row k makes pass k: the next goes only while the last found ' +
104
+ 'something blocking; the rows over, the card blocks for you (none: no review)',
102
105
  },
103
106
  {
104
- key: 'plan_review.effort',
105
- kind: 'word',
106
- label: 'the effort of the plan review (not set: medium)',
107
- },
108
- {
109
- key: 'plan_review.at',
110
- kind: 'number',
107
+ key: 'review.code',
108
+ kind: 'passes',
111
109
  label:
112
- 'the improve pass the outside reviewer makes, when the one before found blocking ' +
113
- 'issues (not set: 3)',
110
+ 'the passes of a code review before the commit, as the plan review: the rows over with a ' +
111
+ 'blocking finding open, the code is committed and the card blocks for you (none: no review)',
114
112
  },
115
113
  {
116
114
  key: 'chat.ask',
@@ -162,11 +160,7 @@ export const SETTINGS = [
162
160
  },
163
161
  { key: 'dod.test', kind: 'command', label: "the project's test command for the DoD, or none" },
164
162
  { key: 'dod.build', kind: 'command', label: "the project's build command for the DoD, or none" },
165
- {
166
- key: 'plan_passes',
167
- kind: 'number',
168
- label: 'improve passes a plan may take before the item blocks',
169
- },
163
+
170
164
  { key: 'dod_attempts', kind: 'number', label: 'DoD attempts before the item blocks' },
171
165
  {
172
166
  key: 'dod_timeout_min',
@@ -216,27 +210,98 @@ export const SETTINGS = [
216
210
  },
217
211
  ];
218
212
 
213
+ /**
214
+ * Each setting's name and one-line hint for a settings screen (Operator-Tasks-Plan t3 d2): data
215
+ * of the core, the board only shows them. `help` is the long text (`label`), with its key and
216
+ * file.
217
+ * @type {Record<string, [string, string]>}
218
+ */
219
+ const TEXT = {
220
+ 'language.ui': ['Agent language', 'Language the agents write to you in'],
221
+ 'language.artifacts': ['Document language', 'Language of plans and item texts'],
222
+ run_mode: ['Run mode', 'Several items in worktrees, or one in the project folder'],
223
+ session_timeout_min: ['Session time limit', 'Minutes one agent session may run'],
224
+ 'agent.model': ['Model', 'Model of runs and chats without their own'],
225
+ 'agent.effort': ['Effort', 'Effort of runs and chats without their own'],
226
+ 'review.plan': ['Plan review', 'Who reviews a plan, pass by pass'],
227
+ 'review.code': ['Code review', 'Who reviews the code before its commit, pass by pass'],
228
+ 'chat.ask': ['Questions to you', 'Which questions an agent asks by a card'],
229
+ 'chat.answer_timeout_min': [
230
+ 'Answer wait',
231
+ 'Minutes a question waits before the agent takes its default',
232
+ ],
233
+ 'gates.milestone': ['Built milestone', 'Stop for your play, or build the next one'],
234
+ 'gates.verdict': ['Verdict items', 'Wait for your play, or close unplayed'],
235
+ 'gates.decision': ['Spikes and decisions', 'You decide, or the agent decides'],
236
+ 'gates.question': ['Open questions', 'The item waits, or the agent assumes'],
237
+ 'dod.test': ['Test command', "Runs the project's tests for the DoD"],
238
+ 'dod.build': ['Build command', 'Builds the project for the DoD'],
239
+ dod_attempts: ['DoD attempts', 'Tries to make the DoD green before the item blocks'],
240
+ dod_timeout_min: ['DoD time limit', 'Minutes a DoD command may take'],
241
+ wip_built_limit: ['Built items waiting', 'Items waiting for your verdict before new work stops'],
242
+ context_handoff_pct: ['Handoff at', 'Context share at which a fresh session takes over'],
243
+ context_window: ['Context window', "Tokens; 0 is the model's own"],
244
+ auto_compact_pct: ['Compact at', 'Context share at which the agent compacts'],
245
+ tune_limit: ['Tune limit', 'Tune verdicts one item may take'],
246
+ unplayed_warn_after: ['Unplayed warning', 'Unplayed items before a warning'],
247
+ built_stale_after_commits: ['Stale item after', 'Commits before a waiting item counts as stale'],
248
+ question_stale_after_commits: [
249
+ 'Stale question after',
250
+ 'Commits before an open question counts as stale',
251
+ ],
252
+ context_budget: ['Readset budget', 'Tokens of the files an item reads'],
253
+ pillars_budget: ['Pillars budget', 'Tokens of PILLARS.md'],
254
+ envelope_default_spread: ['Feel spread', 'Default ± around a design number'],
255
+ no_diff: ['Files without diff', 'Globs the Changes screen lists but never opens'],
256
+ };
257
+
258
+ /**
259
+ * The range of a number (t3 d4), by the code that reads it: `min`, `max`, `step`, `unit`. The core
260
+ * refuses a value outside it; a screen offers none.
261
+ * @type {Record<string, {min: number, max: number, step?: number, unit?: string}>}
262
+ */
263
+ const RANGE = {
264
+ // Never 0: a session with no limit could hold a night queue until morning (configOf).
265
+ session_timeout_min: { min: 1, max: 1440, unit: 'min' },
266
+ 'chat.answer_timeout_min': { min: 0, max: 1440, unit: 'min' },
267
+ dod_attempts: { min: 1, max: 20 },
268
+ dod_timeout_min: { min: 0, max: 1440, unit: 'min' },
269
+ wip_built_limit: { min: 0, max: 100, unit: 'items' },
270
+ context_handoff_pct: { min: 0, max: 100, unit: '%' },
271
+ context_window: { min: 0, max: 10_000_000, step: 1000, unit: 'tokens' },
272
+ auto_compact_pct: { min: 0, max: 100, unit: '%' },
273
+ tune_limit: { min: 0, max: 100 },
274
+ unplayed_warn_after: { min: 0, max: 1000, unit: 'items' },
275
+ built_stale_after_commits: { min: 0, max: 10_000, unit: 'commits' },
276
+ question_stale_after_commits: { min: 0, max: 10_000, unit: 'commits' },
277
+ context_budget: { min: 0, max: 1_000_000, step: 1000, unit: 'tokens' },
278
+ pillars_budget: { min: 0, max: 100_000, step: 100, unit: 'tokens' },
279
+ envelope_default_spread: { min: 0, max: 1, step: 0.05 },
280
+ };
281
+
282
+ // A placeholder for a setting with no default by its sense (t3 d3): an example, not a value.
283
+ const EXAMPLE = {
284
+ 'dod.test': 'npm test',
285
+ 'dod.build': 'npm run build',
286
+ no_diff: '**/*.prefab',
287
+ };
288
+
289
+ for (const s of SETTINGS) {
290
+ const [title, hint] = TEXT[s.key] ?? [s.key, s.label];
291
+ // The board before t3 reads `label`: it carries the same long text.
292
+ const help = `${s.label} · ${s.key} · ${s.file ?? 'gcf/config.yml'}`;
293
+ Object.assign(s, { title, hint, help, label: help, ...RANGE[s.key] });
294
+ if (EXAMPLE[s.key]) Object.assign(s, { example: EXAMPLE[s.key] });
295
+ }
296
+
219
297
  const BY_KEY = new Map(SETTINGS.map((s) => [s.key, s]));
220
298
 
221
299
  // What a settings screen groups the keys under, in its order.
222
300
  /** @type {[string, string[]][]} */
223
301
  const GROUPS = [
224
302
  ['Language', ['language.ui', 'language.artifacts']],
225
- [
226
- 'Runs',
227
- [
228
- 'run_mode',
229
- 'session_timeout_min',
230
- 'agent.model',
231
- 'agent.effort',
232
- 'plan_passes',
233
- 'plan_review.agent',
234
- 'plan_review.model',
235
- 'plan_review.effort',
236
- 'plan_review.at',
237
- 'dod_attempts',
238
- ],
239
- ],
303
+ ['Runs', ['run_mode', 'session_timeout_min', 'agent.model', 'agent.effort', 'dod_attempts']],
304
+ ['Review', ['review.plan', 'review.code']],
240
305
  ['Checks (DoD)', ['dod.test', 'dod.build', 'dod_timeout_min']],
241
306
  ['Autonomy', ['gates.milestone', 'gates.verdict', 'gates.decision', 'gates.question']],
242
307
  ['Chat', ['chat.ask', 'chat.answer_timeout_min']],
@@ -263,9 +328,10 @@ function defaultOf(s, aif) {
263
328
  if (s.kind === 'language') return 'en';
264
329
  if (head === 'chat') return CHAT_DEFAULTS[sub];
265
330
  if (head === 'gates') return 'wait';
331
+ if (head === 'review') return passesText(REVIEW_DEFAULTS[sub]);
266
332
  if (sub) return null;
267
333
 
268
- return head === 'run_mode' ? 'worktree' : (DEFAULT_CONFIG[head] ?? null);
334
+ return head === 'run_mode' ? 'main' : (DEFAULT_CONFIG[head] ?? null);
269
335
  }
270
336
 
271
337
  /**
@@ -283,7 +349,11 @@ export function settingsOf(raw, aif = {}) {
283
349
  : null
284
350
  : (parent ?? null);
285
351
  // AI Factory's file is not checked by GCF's rules: a value that is no language shows unset.
286
- const shown = s.file ? languageIn(aif, sub) : value;
352
+ const shown = s.file
353
+ ? languageIn(aif, sub)
354
+ : s.kind === 'passes' && value !== null
355
+ ? passesText(value)
356
+ : value;
287
357
 
288
358
  return {
289
359
  ...s,
@@ -298,6 +368,34 @@ export function settingsOf(raw, aif = {}) {
298
368
  export const projectSettings = async (projectDir) =>
299
369
  settingsOf(await readRawConfig(gcfRoot(projectDir)), await readAifConfig(projectDir));
300
370
 
371
+ /**
372
+ * Review rows in the CLI's words (t2 d5): `claude:opus:high, codex:astra:medium`, `none` for
373
+ * no review. A list the file broke reads as it is: the config's own check names it.
374
+ * @param {any} rows
375
+ */
376
+ export function passesText(rows) {
377
+ if (!Array.isArray(rows)) return String(rows);
378
+ if (!rows.length) return 'none';
379
+
380
+ return rows.map((r) => `${r?.agent}:${r?.model}:${r?.effort}`).join(', ');
381
+ }
382
+
383
+ /** Rows from the CLI's words: `none` none; empty takes the key off, the default holds. */
384
+ function passesOf(setting, t) {
385
+ if (!t) return null;
386
+ if (t.toLowerCase() === 'none') return [];
387
+
388
+ return t.split(/[,\n]/).map((part, n) => {
389
+ const words = part.trim().split(':');
390
+ const [agent, model, effort] = words;
391
+ const row = { agent, model, effort };
392
+ const why = words.length === 3 ? reviewRowProblem(row) : 'a row is agent:model:effort';
393
+ if (why) throw new Error(`${setting.key} row ${n + 1} (${part.trim()}): ${why}`);
394
+
395
+ return row;
396
+ });
397
+ }
398
+
301
399
  /** A language name or code; empty takes the key off, and AI Factory's default holds. */
302
400
  function languageOf(setting, t) {
303
401
  if (t && !LANGUAGE_RE.test(t))
@@ -329,13 +427,14 @@ function valueOf(setting, text) {
329
427
 
330
428
  if (setting.kind === 'mode') return modeOf(setting, t);
331
429
 
430
+ if (setting.kind === 'passes') return passesOf(setting, t);
431
+
332
432
  return numberOf(setting, t);
333
433
  }
334
434
 
435
+ // Empty takes the key off (t3 d3): the default, or no command, holds.
335
436
  function commandOf(setting, t) {
336
- if (!t) throw new Error(`${setting.key}: name the command, or none`);
337
-
338
- return t;
437
+ return t || null;
339
438
  }
340
439
 
341
440
  // `default`, as an item's, leaves the choice to the agent.
@@ -348,6 +447,7 @@ function wordOf(setting, t) {
348
447
  }
349
448
 
350
449
  function modeOf(setting, t) {
450
+ if (!t) return null;
351
451
  const options = setting.options ?? [];
352
452
  if (!options.includes(t)) throw new Error(`${setting.key} must be ${options.join(' | ')}`);
353
453
 
@@ -360,10 +460,19 @@ function numberOf(setting, t) {
360
460
  if (!/^\d+(\.\d+)?$/.test(t)) throw new Error(`${setting.key} must be a number, got ${t}`);
361
461
  const n = Number(t);
362
462
  if (!Number.isFinite(n)) throw new Error(`${setting.key} must be a number, got ${t}`);
463
+ if (n < (setting.min ?? 0) || n > (setting.max ?? Infinity))
464
+ throw new Error(`${setting.key} must be ${setting.min ?? 0}-${setting.max}, got ${t}`);
363
465
 
364
466
  return n;
365
467
  }
366
468
 
469
+ /** `review.*` set: the keys it replaces go with it, in the same commit (t2 d1). */
470
+ function dropOldReview(doc, keys) {
471
+ if (keys[0] !== 'review') return;
472
+ doc.delete('plan_passes');
473
+ doc.delete('plan_review');
474
+ }
475
+
367
476
  /** Whether git ignores `file`: a commit cannot carry it, and a worktree does not have it. */
368
477
  const ignoredByGit = (projectDir, file) =>
369
478
  spawnSync('git', ['check-ignore', '-q', '--', file], { windowsHide: true, cwd: projectDir })
@@ -414,6 +523,7 @@ export async function setConfig(projectDir, key, text, { commit = true } = {}) {
414
523
  if (keys.length > 1) ensureMap(doc, [keys[0]], `${name}: ${keys[0]} must map its keys`);
415
524
  if (value === null) doc.deleteIn(keys);
416
525
  else doc.setIn(keys, value);
526
+ dropOldReview(doc, keys);
417
527
  const raw = doc.toJS();
418
528
  // `agent:` is read by its own rules: a key set here must not leave a broken section.
419
529
  if (!setting.file) agentOf(configOf(raw));
@@ -468,6 +578,7 @@ export async function setConfigs(projectDir, pairs, { commit = true } = {}) {
468
578
  ensureMap(doc, [c.keys[0]], `gcf/config.yml: ${c.keys[0]} must map its keys`);
469
579
  if (c.value === null) doc.deleteIn(c.keys);
470
580
  else doc.setIn(c.keys, c.value);
581
+ dropOldReview(doc, c.keys);
471
582
  }
472
583
 
473
584
  const raw = doc.toJS();
package/lib/domain.js CHANGED
@@ -212,11 +212,12 @@ const ITEM_SPECS = {
212
212
  },
213
213
  ],
214
214
  },
215
- // Planning that does not converge (Hold-Plan d16): the run's stall, the operator's two answers.
215
+ // A review that does not converge (Hold-Plan d16, Operator-Tasks-Plan t2): the plan's or the
216
+ // code's; the run's stall, the operator's two answers, which take the kind the card stands on.
216
217
  plan_stall: {
217
- label: 'planning stall',
218
- help: "The run's stop: the plan's passes keep finding blocking issues past plan_passes",
219
- args: ['gcf', 'plan', 'stall', '{id}'],
218
+ label: 'review stall',
219
+ help: "The run's stop: the review's rows are over and a pass still finds blocking issues",
220
+ args: ['gcf', 'review', 'stall', '{id}'],
220
221
  fields: [
221
222
  { key: 'passes', label: 'Blocking findings of each pass', kind: 'text', required: true },
222
223
  { key: 'reason', label: 'Reason', kind: 'longtext' },
@@ -224,8 +225,10 @@ const ITEM_SPECS = {
224
225
  },
225
226
  plan_more: {
226
227
  label: 'more passes',
227
- help: 'The plan improves N more passes, then the same check decides',
228
- args: ['gcf', 'plan', 'more', '{id}'],
228
+ help:
229
+ 'The plan or the code gets N more review passes on the last row, then the same check ' +
230
+ 'decides',
231
+ args: ['gcf', 'review', 'more', '{id}'],
229
232
  fields: [
230
233
  {
231
234
  key: 'passes',
@@ -238,9 +241,11 @@ const ITEM_SPECS = {
238
241
  ],
239
242
  },
240
243
  plan_accept: {
241
- label: 'implement as is',
242
- help: 'The plan goes to implementation as it is, its open findings with it',
243
- args: ['gcf', 'plan', 'accept', '{id}'],
244
+ label: 'go on as is',
245
+ help:
246
+ 'The plan goes to implementation, or the code to its submit, as it is, its open ' +
247
+ 'findings with it',
248
+ args: ['gcf', 'review', 'accept', '{id}'],
244
249
  fields: [],
245
250
  },
246
251
  mode: {
@@ -256,7 +261,12 @@ const ITEM_SPECS = {
256
261
  kind: 'choice',
257
262
  required: true,
258
263
  options: [
259
- { value: 'default', label: "default: the project's run_mode" },
264
+ {
265
+ value: 'default',
266
+ label:
267
+ 'default: where its kept session ran, else its live worktree copy, ' +
268
+ "else the project's run_mode",
269
+ },
260
270
  ...RUN_MODES.map((m) => ({ value: m, label: m, help: RUN_MODE_HELP[m] })),
261
271
  ],
262
272
  },
@@ -1014,9 +1024,9 @@ const CHANGES = [
1014
1024
  'block',
1015
1025
  'unblock',
1016
1026
  'plan pass',
1017
- 'plan stall',
1018
- 'plan more',
1019
- 'plan accept',
1027
+ 'review stall',
1028
+ 'review more',
1029
+ 'review accept',
1020
1030
  'inbox add',
1021
1031
  'inbox category',
1022
1032
  'inbox later',
package/lib/gcf-paths.js CHANGED
@@ -14,7 +14,6 @@ export const DEFAULT_CONFIG = {
14
14
  pillars_budget: 1500,
15
15
  envelope_default_spread: 0.3,
16
16
  unplayed_warn_after: 5,
17
- plan_passes: 3,
18
17
  dod_attempts: 2,
19
18
  // Minutes a dod.test or dod.build command may take before it is killed (0: no limit).
20
19
  dod_timeout_min: 60,
@@ -47,9 +46,11 @@ export function gcfRoot(projectDir = process.cwd()) {
47
46
  // How a harness run drives an item (Methodology §7): `worktree` — each in its own copy, several
48
47
  // at once; `main` — one at a time in the project's own folder, for an agent that works through
49
48
  // a running editor bound to that folder. The project chooses; the framework knows no engine.
49
+ // `main` unless set (Fallback-Fidelity-Plan d1); a card whose copy lives stays in its worktree
50
+ // (integrate.js `cardRunMode`).
50
51
  export const RUN_MODES = ['worktree', 'main'];
51
52
 
52
- function runModeOf(v = 'worktree') {
53
+ function runModeOf(v = 'main') {
53
54
  if (!RUN_MODES.includes(v))
54
55
  throw new Error(`gcf/config.yml: run_mode must be ${RUN_MODES.join(' | ')}, got ${v}`);
55
56
 
@@ -110,6 +111,99 @@ function gatesOf(v = {}) {
110
111
  );
111
112
  }
112
113
 
114
+ // The review passes of a plan and of the code (Operator-Tasks-Plan t2 d1): row k makes pass k,
115
+ // the next goes only while the last found something blocking; the rows over, the operator
116
+ // decides. An empty list: no review of that kind.
117
+ export const REVIEW_AGENTS = ['claude', 'codex'];
118
+ export const REVIEW_DEFAULTS = {
119
+ plan: [
120
+ { agent: 'codex', model: 'astra', effort: 'medium' },
121
+ { agent: 'claude', model: 'fable', effort: 'medium' },
122
+ { agent: 'claude', model: 'fable', effort: 'medium' },
123
+ ],
124
+ code: [
125
+ { agent: 'codex', model: 'sol', effort: 'high' },
126
+ { agent: 'claude', model: 'opus', effort: 'high' },
127
+ ],
128
+ };
129
+
130
+ // Who makes a pass its row cannot make (Fallback-Fidelity-Plan d2): the first rule that matches
131
+ // the row (`model` null: any) gives its stand-ins in order; no rule, none. The board reads it.
132
+ const FABLE_MEDIUM = { agent: 'claude', model: 'fable', effort: 'medium' };
133
+ const OPUS_HIGH = { agent: 'claude', model: 'opus', effort: 'high' };
134
+ export const REVIEW_FALLBACK = [
135
+ { agent: 'codex', model: null, effort: 'medium', rows: [FABLE_MEDIUM, OPUS_HIGH] },
136
+ { agent: 'codex', model: null, effort: 'high', rows: [OPUS_HIGH] },
137
+ { agent: 'claude', model: 'fable', effort: 'medium', rows: [OPUS_HIGH] },
138
+ ];
139
+
140
+ /** A Codex model as its family: the slug `gpt-6-astra` is `astra` (gcf-session `familyOf`). */
141
+ export const modelFamily = (model) =>
142
+ /^[a-z]+-\d+(?:\.\d+)*-([a-z]+)$/.exec(String(model))?.[1] ?? String(model);
143
+
144
+ /** The stand-ins of a review row `{agent, model, effort}`, in order; none: `[]`. */
145
+ export function fallbackOf(row) {
146
+ const rule = REVIEW_FALLBACK.find(
147
+ (r) =>
148
+ r.agent === row?.agent &&
149
+ r.effort === row.effort &&
150
+ (r.model === null || r.model === modelFamily(row.model)),
151
+ );
152
+
153
+ return rule ? rule.rows.map((r) => ({ ...r })) : [];
154
+ }
155
+
156
+ /** A review row's refusal, if any: three plain words, the agent one GCF runs. */
157
+ export function reviewRowProblem(r) {
158
+ if (typeof r !== 'object' || r === null || Array.isArray(r))
159
+ return 'a row is {agent, model, effort}';
160
+ if (!REVIEW_AGENTS.includes(r.agent))
161
+ return `agent must be ${REVIEW_AGENTS.join(' | ')}, got ${r.agent}`;
162
+ for (const k of ['model', 'effort'])
163
+ if (typeof r[k] !== 'string' || !RUN_WORD.test(r[k])) return `${k} must be one plain word`;
164
+
165
+ return null;
166
+ }
167
+
168
+ /**
169
+ * The one command that moves a config from before t2 (`plan_passes`, `plan_review:`) to
170
+ * `review.plan` (t2 d1), or null: `plan_passes N` gives N Claude rows, the pass `plan_review.at`
171
+ * the outside reviewer's (Codex unless `agent: none`). `config set review.*` drops the old keys.
172
+ * @param {Record<string, any>} raw config.yml as the file has it
173
+ */
174
+ export function reviewMigration(raw) {
175
+ const old = raw?.plan_review;
176
+ if (raw?.plan_passes === undefined && old === undefined) return null;
177
+ const n = Number.isInteger(raw.plan_passes) ? raw.plan_passes : 3;
178
+ const at = Number(old?.at ?? 3);
179
+ const codex = (old?.agent ?? 'codex') === 'codex';
180
+ const rows = Array.from({ length: n }, (_, k) =>
181
+ codex && k + 1 === at
182
+ ? `codex:${old?.model ?? 'astra'}:${old?.effort ?? 'medium'}`
183
+ : 'claude:opus:high',
184
+ );
185
+
186
+ return `ai-factory gcf config set review.plan --value "${rows.join(', ') || 'none'}"`;
187
+ }
188
+
189
+ function reviewOf(v = {}) {
190
+ if (typeof v !== 'object' || v === null || Array.isArray(v))
191
+ throw new Error('gcf/config.yml: review must map plan and code to their rows');
192
+ const out = {};
193
+ for (const kind of ['plan', 'code']) {
194
+ const rows = v[kind] ?? REVIEW_DEFAULTS[kind];
195
+ if (!Array.isArray(rows))
196
+ throw new Error(`gcf/config.yml: review.${kind} must be a list of rows`);
197
+ rows.forEach((r, n) => {
198
+ const why = reviewRowProblem(r);
199
+ if (why) throw new Error(`gcf/config.yml: review.${kind} row ${n + 1}: ${why}`);
200
+ });
201
+ out[kind] = rows.map(({ agent, model, effort }) => ({ agent, model, effort }));
202
+ }
203
+
204
+ return out;
205
+ }
206
+
113
207
  // Files listed and never opened on the board's Changes screen (Board-PRD §5.25): the project's
114
208
  // call, GCF names no stack's files.
115
209
  function noDiffOf(v = []) {
@@ -179,6 +273,7 @@ export function configOf(parsed) {
179
273
  chat: chatOf(config.chat),
180
274
  gates: gatesOf(config.gates),
181
275
  no_diff: noDiffOf(config.no_diff),
276
+ review: reviewOf(config.review),
182
277
  };
183
278
  }
184
279
 
package/lib/handoff.js CHANGED
@@ -11,7 +11,7 @@ import { planPasses, planTicks } from './plan-check.js';
11
11
  import { listQuestions } from './questions.js';
12
12
  import { recordsOf } from './verdict-fs.js';
13
13
  import { serves } from './devices.js';
14
- import { planTextOf, playNotesOf, playNotesProblems, rowsFor } from './play-notes.js';
14
+ import { planTextOf, playNotesIssues, playNotesOf, rowsFor, unplacedOf } from './play-notes.js';
15
15
 
16
16
  /** A row's state without asking devices: what is set up and built (the panel asks the rest). */
17
17
  function rowOf(play, build, ok, row) {
@@ -208,15 +208,20 @@ function playedBlocks(c) {
208
208
  };
209
209
  }
210
210
 
211
- /** What the handoff lacks: the agent's notes, the card's criterion. */
212
- function warningsOf(c, question) {
213
- const warnings = c.decision
214
- ? []
215
- : playNotesProblems(c.notes, rowsFor(c.play, c.item.data.play_on));
211
+ /**
212
+ * What the handoff lacks (the agent's notes, the card's criterion), each with its kind and parts
213
+ * (Round14-Plan d1); `warnings` keeps their words for the CLI and an older board.
214
+ * @returns {import('./play-notes.js').PlayNotesIssue[]}
215
+ */
216
+ function issuesOf(c, question) {
217
+ const issues = c.decision ? [] : playNotesIssues(c.notes, rowsOf(c));
216
218
  if (!question.has_criterion)
217
- warnings.push("the card has no miss criterion: the question is the agent's");
219
+ issues.push({
220
+ kind: 'no_criterion',
221
+ text: "the card has no miss criterion: the question is the agent's",
222
+ });
218
223
 
219
- return warnings;
224
+ return issues;
220
225
  }
221
226
 
222
227
  /** A row of block 2 as words, and the command the board has a button for. */
@@ -234,6 +239,9 @@ function rowLines(id, build, r) {
234
239
 
235
240
  const list = (head, items) => (items?.length ? [head, ...items.map((x) => ` - ${x}`)] : []);
236
241
 
242
+ /** The card's rows; null with no readable `play:`: unknown, not none (Round14-Plan d1). */
243
+ const rowsOf = (c) => (c.play ? rowsFor(c.play, c.item.data.play_on) : null);
244
+
237
245
  /** The outcome line (block 0). */
238
246
  function outcomeLine(o) {
239
247
  const b = o.build;
@@ -278,6 +286,10 @@ export function handoffLines(id, h) {
278
286
  h.waits.map((w) => (w.kind === 'question' ? `${w.id}: ${w.text}` : w.text)),
279
287
  ),
280
288
  ...technicalLine(h.technical),
289
+ ...list(
290
+ 'notes on no row:',
291
+ (h.unplaced ?? []).map((n) => (n.row ? `${n.row}: ${n.text}` : n.text)),
292
+ ),
281
293
  ...list('warnings:', h.warnings),
282
294
  ];
283
295
  }
@@ -308,6 +320,7 @@ export async function handoffOf(projectDir, id, { ledger = null, config = null,
308
320
  };
309
321
  c.build = ownBuild(c.play, item, c.builds);
310
322
  const question = questionOf(item, c.notes, decision);
323
+ const warned = issuesOf(c, question);
311
324
 
312
325
  return {
313
326
  outcome: outcomeOf(item, c.build, queueOf(dir)),
@@ -316,6 +329,8 @@ export async function handoffOf(projectDir, id, { ledger = null, config = null,
316
329
  ...playedBlocks(c),
317
330
  waits: await waitsOf(dir, id),
318
331
  technical: technicalOf(c),
319
- warnings: warningsOf(c, question),
332
+ warnings: warned.map((x) => x.text),
333
+ warned,
334
+ unplaced: decision ? [] : unplacedOf(c.notes, rowsOf(c) ?? []),
320
335
  };
321
336
  }
package/lib/integrate.js CHANGED
@@ -3,7 +3,7 @@
3
3
  // not in memory. `integrate` merges such a branch into main and records the item's move there,
4
4
  // under the main lock; without an id it picks up every verified branch a dead run left behind.
5
5
  import { readFile, writeFile } from 'node:fs/promises';
6
- import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
6
+ import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
7
7
  import { spawnSync } from 'node:child_process';
8
8
  import path from 'node:path';
9
9
  import { buildLedger } from './ledger.js';
@@ -208,6 +208,63 @@ export function verifiedBranches(projectDir) {
208
208
  .filter((id) => isVerified(projectDir, id));
209
209
  }
210
210
 
211
+ /**
212
+ * The ids whose worktree run left a copy that lives (Fallback-Fidelity-Plan d1): its folder, or
213
+ * its branch `work/<id>` whose tip is no main-mode shelf (lib/shelf.js `GCF-Shelved`). None
214
+ * outside a repository.
215
+ */
216
+ export function liveCopies(projectDir) {
217
+ const home = path.dirname(worktreeOf(projectDir, 'x'));
218
+ const ids = new Set();
219
+ try {
220
+ for (const e of readdirSync(home, { withFileTypes: true }))
221
+ if (e.isDirectory() && isValidId(e.name)) ids.add(e.name);
222
+ } catch {
223
+ // No worktree folder: no copy there.
224
+ }
225
+
226
+ const format = '--format=%(refname:short)%00%(trailers:key=GCF-Shelved,valueonly,separator=%x2C)';
227
+ const refs = git(projectDir, ['for-each-ref', format, 'refs/heads/work/'], { check: false });
228
+ for (const l of refs.ok ? refs.out.split('\n') : []) {
229
+ const [ref, shelved = ''] = l.split('\0');
230
+ const id = ref.slice('work/'.length);
231
+ if (ref.startsWith('work/') && !shelved.split(',').some((v) => v.trim() === id)) ids.add(id);
232
+ }
233
+
234
+ return ids;
235
+ }
236
+
237
+ /**
238
+ * The mode a run of the card takes when the run asks none (Fallback-Fidelity-Plan d1): the
239
+ * card's own `run_mode`; the mode its last session ran in, while the harness keeps its record
240
+ * (`.gcf-session/runs/<id>.agent.json` `mode`: a resume goes on where its work is, a fresh
241
+ * start too); `worktree` while a copy of it lives; else the project's. Its work is not left
242
+ * behind when the project's mode or its default changes. `live`: one `liveCopies` read for many.
243
+ * @param {string} projectDir
244
+ * @param {string} id
245
+ * @param {{own?: string | null, project: string, live?: Set<string>}} o
246
+ */
247
+ export function cardRunMode(projectDir, id, { own, project, live }) {
248
+ if (own) return own;
249
+ const saved = savedMode(projectDir, id);
250
+ if (saved) return saved;
251
+
252
+ return (live ?? liveCopies(projectDir)).has(id) ? 'worktree' : project;
253
+ }
254
+
255
+ /** The mode the harness's record of the card's last session names, or null. */
256
+ function savedMode(projectDir, id) {
257
+ if (!isValidId(id)) return null;
258
+ const file = path.join(path.resolve(projectDir), '.gcf-session', 'runs', `${id}.agent.json`);
259
+ try {
260
+ const mode = JSON.parse(readFileSync(file, 'utf8'))?.mode;
261
+
262
+ return mode === 'main' || mode === 'worktree' ? mode : null;
263
+ } catch {
264
+ return null; // No record, or none to read.
265
+ }
266
+ }
267
+
211
268
  /**
212
269
  * Take the worktree and the branch away once the branch is in main (or tagged, for a spike).
213
270
  * Without --force: work left uncommitted in the worktree stops the removal and is named.