gcf-aif-ext 0.29.1 → 0.31.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.
Files changed (54) hide show
  1. package/GLOSSARY.md +1 -1
  2. package/README.md +2 -1
  3. package/commands/gcf.js +176 -74
  4. package/extension.json +1 -1
  5. package/hooks/pre-commit.js +2 -0
  6. package/lib/agent-permissions.js +11 -6
  7. package/lib/audit-core.js +43 -19
  8. package/lib/board.js +10 -4
  9. package/lib/changes.js +2 -1
  10. package/lib/commit-files.js +2 -1
  11. package/lib/commit-move.js +114 -0
  12. package/lib/config-doc.js +22 -0
  13. package/lib/config-set.js +189 -83
  14. package/lib/design-check.js +8 -3
  15. package/lib/design-parts.js +111 -80
  16. package/lib/devices.js +3 -8
  17. package/lib/domain.js +17 -12
  18. package/lib/edits.js +7 -3
  19. package/lib/frozen.js +24 -0
  20. package/lib/gate.js +1 -1
  21. package/lib/gcf-paths.js +81 -11
  22. package/lib/git.js +18 -4
  23. package/lib/handoff.js +25 -10
  24. package/lib/history.js +1 -1
  25. package/lib/inbox-categories.js +32 -39
  26. package/lib/inbox.js +46 -34
  27. package/lib/integrate.js +3 -12
  28. package/lib/ledger.js +1 -1
  29. package/lib/lessons.js +4 -1
  30. package/lib/metrics.js +1 -0
  31. package/lib/migrate.js +1 -1
  32. package/lib/milestone-state.js +1 -1
  33. package/lib/phase.js +1 -1
  34. package/lib/pillars.js +1 -1
  35. package/lib/plan-check.js +80 -43
  36. package/lib/play-notes.js +115 -21
  37. package/lib/play.js +63 -12
  38. package/lib/playtest-list.js +1 -1
  39. package/lib/push.js +2 -1
  40. package/lib/questions.js +1 -1
  41. package/lib/review.js +106 -0
  42. package/lib/session-mark.js +21 -2
  43. package/lib/shelf.js +1 -0
  44. package/lib/systems-doc.js +27 -17
  45. package/lib/unit-ops.js +31 -109
  46. package/lib/validate-item.js +30 -7
  47. package/lib/verdict-fs.js +2 -1
  48. package/lib/verify-stamp.js +7 -2
  49. package/lib/verify.js +6 -2
  50. package/lib/work-ops.js +197 -104
  51. package/package.json +3 -3
  52. package/schemas/item.schema.json +24 -9
  53. package/templates/agents-block.md +9 -1
  54. package/templates/config.yml +15 -10
package/lib/board.js CHANGED
@@ -110,7 +110,7 @@ function commitTimes(projectDir, hashes) {
110
110
  const res = spawnSync(
111
111
  'git',
112
112
  ['log', '--no-walk=unsorted', '--ignore-missing', '--format=%H %cI', ...asked],
113
- { cwd: projectDir, encoding: 'utf8' },
113
+ { windowsHide: true, cwd: projectDir, encoding: 'utf8' },
114
114
  );
115
115
  const found = (res.status === 0 ? res.stdout : '').split('\n').filter(Boolean);
116
116
 
@@ -194,6 +194,12 @@ function logOf(projectDir, id) {
194
194
  * How the agent session of the item's last run ended, when the harness kept it for a rerun to
195
195
  * resume (`<id>.agent.json`): `{ended, resets?}`, or null. A file that is not a record is none.
196
196
  */
197
+ /** A kept record's reset, and whether the quota's reserve waits for it, not the limit (t1 d5). */
198
+ const resetsOf = (rec) =>
199
+ rec.resets
200
+ ? { resets: String(rec.resets), ...(rec.reserve === true ? { reserve: true } : {}) }
201
+ : {};
202
+
197
203
  async function resumeOf(projectDir, id) {
198
204
  try {
199
205
  const file = path.join(projectDir, '.gcf-session', 'runs', `${id}.agent.json`);
@@ -205,7 +211,7 @@ async function resumeOf(projectDir, id) {
205
211
 
206
212
  return {
207
213
  ended: String(rec.ended ?? ''),
208
- ...(rec.resets ? { resets: String(rec.resets) } : {}),
214
+ ...resetsOf(rec),
209
215
  ...(rec.handoffs ? { handoffs: Number(rec.handoffs) } : {}),
210
216
  };
211
217
  } catch {
@@ -446,8 +452,8 @@ export async function board(projectDir) {
446
452
  },
447
453
  // A run's chat with the operator (`chat:` in config.yml): what it asks, how long it waits.
448
454
  chat: config.chat,
449
- // The plan's outside reviewer (`plan_review:`, Hold-Plan d17): null when not set.
450
- plan_review: config.plan_review ?? null,
455
+ // The review passes of the plan and the code (Operator-Tasks-Plan t2): the rows that hold.
456
+ review: config.review,
451
457
  // How the game is played: the project's targets and the running player; null when not set up.
452
458
  play: playFacts(projectDir, config),
453
459
  phase: await phaseOf(projectDir),
package/lib/changes.js CHANGED
@@ -45,6 +45,7 @@ const PICTURES = {
45
45
 
46
46
  const run = (dir, args, opts = {}) =>
47
47
  spawnSync('git', ['-c', 'core.quotePath=false', ...args], {
48
+ windowsHide: true,
48
49
  cwd: dir,
49
50
  encoding: 'utf8',
50
51
  maxBuffer: LIST_READ,
@@ -551,7 +552,7 @@ async function rowOf(projectDir, p, worktree) {
551
552
  const said = (d) => /^(?!diff --git |index ).+/m.test(d);
552
553
 
553
554
  /** `text` by the limits; `overrun`: git's pipe was cut, or the file longer than was read. */
554
- function cutOf(text, overrun = false) {
555
+ export function cutOf(text, overrun = false) {
555
556
  const clean = text.replace(/\r$/gm, '');
556
557
  const lines = clean.split('\n');
557
558
  const total = lines.at(-1) === '' ? lines.length - 1 : lines.length;
@@ -20,7 +20,7 @@ import {
20
20
  import { writeIndex } from './index-gen.js';
21
21
  import { MAIN_RUN, runHolder, withMainLock } from './main-lock.js';
22
22
  import { refusal } from './refusal.js';
23
- import { onWorkBranch } from './unit-ops.js';
23
+ import { onWorkBranch } from './commit-move.js';
24
24
 
25
25
  const INDEX = 'gcf/INDEX.md';
26
26
  // The ids a commit touches, as `gcf edits commit` finds them: item history reads them.
@@ -36,6 +36,7 @@ const inGate = (p) =>
36
36
 
37
37
  const git = (dir, args, opts = {}) =>
38
38
  spawnSync('git', ['-c', 'core.quotePath=false', ...args], {
39
+ windowsHide: true,
39
40
  cwd: dir,
40
41
  encoding: 'utf8',
41
42
  ...opts,
@@ -0,0 +1,114 @@
1
+ // The fixed-format commit every committed move ends with (Methodology §4.1): all of the move or
2
+ // none of it, under the main lock, refused on a work/ branch or over uncommitted edits.
3
+ import { existsSync, readFileSync } from 'node:fs';
4
+ import { spawnSync } from 'node:child_process';
5
+ import path from 'node:path';
6
+ import { withFileRollback } from './safe-path.js';
7
+ import { writeIndex } from './index-gen.js';
8
+ import { operationInProgress, commitPaths, dirtyGcf, dirtyRefusal } from './git.js';
9
+ import { withMainLock } from './main-lock.js';
10
+
11
+ /** A file's text at a git revision spec (`HEAD:./x`, `:./x` for the index), '' when absent. */
12
+ function gitText(projectDir, spec) {
13
+ const res = spawnSync('git', ['show', spec], {
14
+ windowsHide: true,
15
+ cwd: projectDir,
16
+ encoding: 'utf8',
17
+ });
18
+
19
+ return res.status === 0 ? res.stdout : '';
20
+ }
21
+
22
+ /**
23
+ * True when `file` differs from HEAD in the index or on disk. Line endings do not count: a file
24
+ * stored with CRLF and checked out with LF is not an edit.
25
+ */
26
+ function uncommitted(projectDir, file) {
27
+ const rel = `./${path.relative(projectDir, file).replaceAll('\\', '/')}`;
28
+ const norm = (t) => String(t).replace(/\r\n/g, '\n').trimEnd();
29
+ const head = norm(gitText(projectDir, `HEAD:${rel}`));
30
+ const disk = norm(existsSync(file) ? readFileSync(file, 'utf8') : '');
31
+
32
+ return head !== norm(gitText(projectDir, `:${rel}`)) || head !== disk;
33
+ }
34
+
35
+ /** A worktree of the integrator (Methodology §7): its gcf/ state is main's to move. */
36
+ export const onWorkBranch = (projectDir) =>
37
+ /^work\//.test(
38
+ spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
39
+ windowsHide: true,
40
+ cwd: projectDir,
41
+ encoding: 'utf8',
42
+ }).stdout?.trim() ?? '',
43
+ );
44
+
45
+ /**
46
+ * @typedef {{files: string[], mutate: () => Promise<unknown>, commit: boolean, inputs?: string[],
47
+ * key?: string, items?: string[], proposal?: string}} Move
48
+ */
49
+
50
+ /**
51
+ * Run a move that ends with its fixed-format commit, all of it or none of it. The commit takes
52
+ * whole files and deletes the unit's section, so any uncommitted edit in them refuses the move
53
+ * up front — an answer in the unit itself included: it would leave in a commit that never held
54
+ * it, and no history would keep it. `inputs` are the item files the move reads and rewrites:
55
+ * their own uncommitted edits (an answer, a live: delta) ride along on purpose.
56
+ * @param {string} projectDir
57
+ * @param {string} message
58
+ * `key` is the domain's move key, `items` the ids it touched and `proposal` the board's proposal
59
+ * it carries out: the commit's trailers (moveTrailers).
60
+ * @param {Move} move
61
+ * @returns {Promise<string | null>} the commit's hash, null when it does not commit
62
+ */
63
+ export async function commitMove(projectDir, message, move) {
64
+ // A move that commits holds the main lock while it writes and commits (Methodology §7).
65
+ return move.commit
66
+ ? withMainLock(projectDir, () => record(projectDir, message, move))
67
+ : record(projectDir, message, move);
68
+ }
69
+
70
+ /** @param {string} projectDir @param {string} message @param {Move} move */
71
+ async function record(
72
+ projectDir,
73
+ message,
74
+ { files, mutate, commit, inputs = [], key, items, proposal },
75
+ ) {
76
+ if (commit && onWorkBranch(projectDir))
77
+ throw new Error(
78
+ `cannot record ${message} on a work/ branch: a worktree records no move — the run ` +
79
+ 'leaves .gcf-session/outcome.json, and the main checkout records it',
80
+ );
81
+ const busy = commit ? operationInProgress(projectDir) : null;
82
+ if (busy) throw new Error(`cannot record ${message} while ${busy} is in progress`);
83
+ const dirty = commit
84
+ ? files.filter((f) => !inputs.includes(f) && uncommitted(projectDir, f))
85
+ : [];
86
+ if (dirty.length) {
87
+ const rels = dirty.map((f) => path.relative(projectDir, f).replaceAll('\\', '/'));
88
+ // The whole of gcf/'s edits, not only these: the gate would refuse the next one at once.
89
+ // Only when that set holds them all: a move's own file outside it (an archived plan) is no
90
+ // edit `gcf edits` takes, and a Commit of the rest would be refused again.
91
+ const all = dirtyGcf(projectDir, inputs);
92
+ throw dirtyRefusal(
93
+ rels.every((r) => all.includes(r)) ? all : [],
94
+ `commit or stash these first (an answered unit is committed before its move), ` +
95
+ `${message} would carry them: ${rels.join(', ')}`,
96
+ );
97
+ }
98
+
99
+ const root = path.join(path.resolve(projectDir), 'gcf');
100
+ const touched = [...files, path.join(root, 'INDEX.md')];
101
+ /** @type {string | null} */
102
+ let hash = null;
103
+ await withFileRollback(
104
+ touched,
105
+ async () => {
106
+ await mutate();
107
+ await writeIndex(root);
108
+ if (commit) hash = commitPaths(projectDir, message, touched, { key, items, proposal });
109
+ },
110
+ { gitCwd: commit ? path.resolve(projectDir) : null },
111
+ );
112
+
113
+ return hash;
114
+ }
@@ -0,0 +1,22 @@
1
+ // A YAML settings file as an editable document: the edit keeps the file's comments.
2
+ import YAML from 'yaml';
3
+
4
+ /** A YAML file as a document with a map on top: an edit keeps its comments. */
5
+ export function configDoc(text, name = 'gcf/config.yml') {
6
+ const doc = YAML.parseDocument(text);
7
+ if (doc.errors.length) throw new Error(`${name}: ${doc.errors[0].message}`);
8
+ // A file of a list or a word on top is not a settings file: replacing it would lose it.
9
+ if (doc.contents != null && !YAML.isMap(doc.contents) && doc.contents.toJSON() != null)
10
+ throw new Error(`${name} must map its keys`);
11
+ if (!YAML.isMap(doc.contents)) doc.contents = /** @type {any} */ (doc.createNode({}));
12
+
13
+ return doc;
14
+ }
15
+
16
+ /** Make `keys` a map. A blank key (`dod:` with nothing or only comments under it) is none yet. */
17
+ export function ensureMap(doc, keys, error) {
18
+ const node = doc.getIn(keys, true);
19
+ if (YAML.isMap(node)) return;
20
+ if (node != null && !(YAML.isScalar(node) && node.value == null)) throw new Error(error);
21
+ doc.setIn(keys, doc.createNode({}));
22
+ }
package/lib/config-set.js CHANGED
@@ -11,7 +11,7 @@ import { spawnSync } from 'node:child_process';
11
11
  import path from 'node:path';
12
12
  import { isDeepStrictEqual } from 'node:util';
13
13
  import YAML from 'yaml';
14
- import { commitMove } from './unit-ops.js';
14
+ import { commitMove } from './commit-move.js';
15
15
  import { withMainLock } from './main-lock.js';
16
16
  import { atomicWrite } from './safe-path.js';
17
17
  import {
@@ -22,13 +22,19 @@ 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';
28
30
  import { AIF_CONFIG, LANGUAGE_RE, languageIn, readAifConfig } from './aif-config.js';
29
31
  import { agentOf } from './agent-permissions.js';
32
+ import { configDoc, ensureMap } from './config-doc.js';
30
33
 
31
- /** @typedef {'number' | 'share' | 'mode' | 'command' | 'language' | 'word' | 'list'} Kind */
34
+ /**
35
+ * @typedef {'number' | 'share' | 'mode' | 'command' | 'language' | 'word' | 'list' | 'passes'}
36
+ * Kind
37
+ */
32
38
 
33
39
  // Thrown inside the move to leave without a write or a commit.
34
40
  const NO_CHANGE = new Error('no change');
@@ -36,31 +42,14 @@ const NO_CHANGE = new Error('no change');
36
42
  // The languages AI Factory's own setup offers; any other name or code is taken too.
37
43
  const LANGUAGES = ['en', 'ru', 'de', 'fr', 'es', 'zh', 'ja', 'ko', 'pt', 'it'];
38
44
 
39
- /** A YAML file as a document with a map on top: an edit keeps its comments. */
40
- export function configDoc(text, name = 'gcf/config.yml') {
41
- const doc = YAML.parseDocument(text);
42
- if (doc.errors.length) throw new Error(`${name}: ${doc.errors[0].message}`);
43
- // A file of a list or a word on top is not a settings file: replacing it would lose it.
44
- if (doc.contents != null && !YAML.isMap(doc.contents) && doc.contents.toJSON() != null)
45
- throw new Error(`${name} must map its keys`);
46
- if (!YAML.isMap(doc.contents)) doc.contents = /** @type {any} */ (doc.createNode({}));
47
-
48
- return doc;
49
- }
50
-
51
- /** Make `keys` a map. A blank key (`dod:` with nothing or only comments under it) is none yet. */
52
- export function ensureMap(doc, keys, error) {
53
- const node = doc.getIn(keys, true);
54
- if (YAML.isMap(node)) return;
55
- if (node != null && !(YAML.isScalar(node) && node.value == null)) throw new Error(error);
56
- doc.setIn(keys, doc.createNode({}));
57
- }
58
-
59
45
  /**
60
46
  * `presets`: a word whose suggestions are the agent's own (`presets` of the board read), not the
61
47
  * framework's.
48
+ * `title`, `hint`, `help`, the range (`min`, `max`, `step`, `unit`) and `example` are added
49
+ * below (Operator-Tasks-Plan t3).
62
50
  * @type {{ key: string, kind: Kind, label: string, file?: string, options?: string[],
63
- * presets?: 'model' | 'effort' }[]}
51
+ * presets?: 'model' | 'effort', title?: string, hint?: string, help?: string, min?: number,
52
+ * max?: number, step?: number, unit?: string, example?: string }[]}
64
53
  */
65
54
  export const SETTINGS = [
66
55
  {
@@ -98,38 +87,28 @@ export const SETTINGS = [
98
87
  key: 'agent.model',
99
88
  kind: 'word',
100
89
  presets: 'model',
101
- 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',
102
91
  },
103
92
  {
104
93
  key: 'agent.effort',
105
94
  kind: 'word',
106
95
  presets: 'effort',
107
- 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',
108
97
  },
109
- // 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`.
110
99
  {
111
- key: 'plan_review.agent',
112
- kind: 'word',
100
+ key: 'review.plan',
101
+ kind: 'passes',
113
102
  label:
114
- 'the outside reviewer of a plan that keeps finding blocking issues ' +
115
- '(not set: codex; none: off)',
116
- },
117
- {
118
- key: 'plan_review.model',
119
- kind: 'word',
120
- label: 'the model of the plan review (not set: gpt-6-astra)',
121
- },
122
- {
123
- key: 'plan_review.effort',
124
- kind: 'word',
125
- label: 'the effort of the plan review (not set: medium)',
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)',
126
105
  },
127
106
  {
128
- key: 'plan_review.at',
129
- kind: 'number',
107
+ key: 'review.code',
108
+ kind: 'passes',
130
109
  label:
131
- 'the improve pass the outside reviewer makes, when the one before found blocking ' +
132
- '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)',
133
112
  },
134
113
  {
135
114
  key: 'chat.ask',
@@ -181,11 +160,7 @@ export const SETTINGS = [
181
160
  },
182
161
  { key: 'dod.test', kind: 'command', label: "the project's test command for the DoD, or none" },
183
162
  { key: 'dod.build', kind: 'command', label: "the project's build command for the DoD, or none" },
184
- {
185
- key: 'plan_passes',
186
- kind: 'number',
187
- label: 'improve passes a plan may take before the item blocks',
188
- },
163
+
189
164
  { key: 'dod_attempts', kind: 'number', label: 'DoD attempts before the item blocks' },
190
165
  {
191
166
  key: 'dod_timeout_min',
@@ -235,27 +210,98 @@ export const SETTINGS = [
235
210
  },
236
211
  ];
237
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
+
238
297
  const BY_KEY = new Map(SETTINGS.map((s) => [s.key, s]));
239
298
 
240
299
  // What a settings screen groups the keys under, in its order.
241
300
  /** @type {[string, string[]][]} */
242
301
  const GROUPS = [
243
302
  ['Language', ['language.ui', 'language.artifacts']],
244
- [
245
- 'Runs',
246
- [
247
- 'run_mode',
248
- 'session_timeout_min',
249
- 'agent.model',
250
- 'agent.effort',
251
- 'plan_passes',
252
- 'plan_review.agent',
253
- 'plan_review.model',
254
- 'plan_review.effort',
255
- 'plan_review.at',
256
- 'dod_attempts',
257
- ],
258
- ],
303
+ ['Runs', ['run_mode', 'session_timeout_min', 'agent.model', 'agent.effort', 'dod_attempts']],
304
+ ['Review', ['review.plan', 'review.code']],
259
305
  ['Checks (DoD)', ['dod.test', 'dod.build', 'dod_timeout_min']],
260
306
  ['Autonomy', ['gates.milestone', 'gates.verdict', 'gates.decision', 'gates.question']],
261
307
  ['Chat', ['chat.ask', 'chat.answer_timeout_min']],
@@ -282,6 +328,7 @@ function defaultOf(s, aif) {
282
328
  if (s.kind === 'language') return 'en';
283
329
  if (head === 'chat') return CHAT_DEFAULTS[sub];
284
330
  if (head === 'gates') return 'wait';
331
+ if (head === 'review') return passesText(REVIEW_DEFAULTS[sub]);
285
332
  if (sub) return null;
286
333
 
287
334
  return head === 'run_mode' ? 'worktree' : (DEFAULT_CONFIG[head] ?? null);
@@ -302,7 +349,11 @@ export function settingsOf(raw, aif = {}) {
302
349
  : null
303
350
  : (parent ?? null);
304
351
  // AI Factory's file is not checked by GCF's rules: a value that is no language shows unset.
305
- 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;
306
357
 
307
358
  return {
308
359
  ...s,
@@ -317,6 +368,34 @@ export function settingsOf(raw, aif = {}) {
317
368
  export const projectSettings = async (projectDir) =>
318
369
  settingsOf(await readRawConfig(gcfRoot(projectDir)), await readAifConfig(projectDir));
319
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
+
320
399
  /** A language name or code; empty takes the key off, and AI Factory's default holds. */
321
400
  function languageOf(setting, t) {
322
401
  if (t && !LANGUAGE_RE.test(t))
@@ -342,43 +421,68 @@ function valueOf(setting, text) {
342
421
 
343
422
  if (setting.kind === 'list') return linesOf(t);
344
423
 
345
- if (setting.kind === 'command') {
346
- if (!t) throw new Error(`${setting.key}: name the command, or none`);
424
+ if (setting.kind === 'command') return commandOf(setting, t);
347
425
 
348
- return t;
349
- }
426
+ if (setting.kind === 'word') return wordOf(setting, t);
350
427
 
351
- // `default`, as an item's, leaves the choice to the agent.
352
- if (setting.kind === 'word') {
353
- if (!t || t.toLowerCase() === 'default') return null;
354
- if (!RUN_WORD.test(t))
355
- throw new Error(`${setting.key} must be one plain word (letters, digits, . - _), e.g. opus`);
428
+ if (setting.kind === 'mode') return modeOf(setting, t);
356
429
 
357
- return t;
358
- }
430
+ if (setting.kind === 'passes') return passesOf(setting, t);
359
431
 
360
- if (setting.kind === 'mode') {
361
- const options = setting.options ?? [];
362
- if (!options.includes(t)) throw new Error(`${setting.key} must be ${options.join(' | ')}`);
432
+ return numberOf(setting, t);
433
+ }
363
434
 
364
- return t;
365
- }
435
+ // Empty takes the key off (t3 d3): the default, or no command, holds.
436
+ function commandOf(setting, t) {
437
+ return t || null;
438
+ }
439
+
440
+ // `default`, as an item's, leaves the choice to the agent.
441
+ function wordOf(setting, t) {
442
+ if (!t || t.toLowerCase() === 'default') return null;
443
+ if (!RUN_WORD.test(t))
444
+ throw new Error(`${setting.key} must be one plain word (letters, digits, . - _), e.g. opus`);
445
+
446
+ return t;
447
+ }
366
448
 
449
+ function modeOf(setting, t) {
450
+ if (!t) return null;
451
+ const options = setting.options ?? [];
452
+ if (!options.includes(t)) throw new Error(`${setting.key} must be ${options.join(' | ')}`);
453
+
454
+ return t;
455
+ }
456
+
457
+ function numberOf(setting, t) {
367
458
  if (!t) return null;
368
459
  // Plain decimals only: Number() would also take 0x10, 1e3 and 0b1.
369
460
  if (!/^\d+(\.\d+)?$/.test(t)) throw new Error(`${setting.key} must be a number, got ${t}`);
370
461
  const n = Number(t);
371
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}`);
372
465
 
373
466
  return n;
374
467
  }
375
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
+
376
476
  /** Whether git ignores `file`: a commit cannot carry it, and a worktree does not have it. */
377
477
  const ignoredByGit = (projectDir, file) =>
378
- spawnSync('git', ['check-ignore', '-q', '--', file], { cwd: projectDir }).status === 0;
478
+ spawnSync('git', ['check-ignore', '-q', '--', file], { windowsHide: true, cwd: projectDir })
479
+ .status === 0;
379
480
 
380
481
  const trackedByGit = (projectDir, file) =>
381
- spawnSync('git', ['ls-files', '--error-unmatch', '--', file], { cwd: projectDir }).status === 0;
482
+ spawnSync('git', ['ls-files', '--error-unmatch', '--', file], {
483
+ windowsHide: true,
484
+ cwd: projectDir,
485
+ }).status === 0;
382
486
 
383
487
  /**
384
488
  * Set one key of gcf/config.yml, or the language of `.ai-factory/config.yaml`, and commit
@@ -419,6 +523,7 @@ export async function setConfig(projectDir, key, text, { commit = true } = {}) {
419
523
  if (keys.length > 1) ensureMap(doc, [keys[0]], `${name}: ${keys[0]} must map its keys`);
420
524
  if (value === null) doc.deleteIn(keys);
421
525
  else doc.setIn(keys, value);
526
+ dropOldReview(doc, keys);
422
527
  const raw = doc.toJS();
423
528
  // `agent:` is read by its own rules: a key set here must not leave a broken section.
424
529
  if (!setting.file) agentOf(configOf(raw));
@@ -473,6 +578,7 @@ export async function setConfigs(projectDir, pairs, { commit = true } = {}) {
473
578
  ensureMap(doc, [c.keys[0]], `gcf/config.yml: ${c.keys[0]} must map its keys`);
474
579
  if (c.value === null) doc.deleteIn(c.keys);
475
580
  else doc.setIn(c.keys, c.value);
581
+ dropOldReview(doc, c.keys);
476
582
  }
477
583
 
478
584
  const raw = doc.toJS();
@@ -517,6 +517,13 @@ function preambleIssues(design) {
517
517
  }));
518
518
  }
519
519
 
520
+ function parentKnown(id, ledger) {
521
+ // A parent that already ended is fine: a parked bug may outlive its feature.
522
+ const parent = ledger.item(id);
523
+
524
+ return parent ? parent.data.type === 'feature' : ledger.known(id);
525
+ }
526
+
520
527
  /** M2 over a work item's references: depends, parent, children, reopens, milestone. */
521
528
  function itemRefIssues(item, ctx, ledger, add) {
522
529
  const d = item.data;
@@ -526,9 +533,7 @@ function itemRefIssues(item, ctx, ledger, add) {
526
533
  add('M2', 1, `milestone ${d.milestone} is not a milestone of game.md`, 'report');
527
534
  const unknown = (d.depends ?? []).filter((x) => x === d.id || !ledger.known(x));
528
535
  if (unknown.length) add('M2', 1, `depends on unknown ${unknown.join(', ')}`);
529
- // A parent that already ended is fine: a parked bug may outlive its feature.
530
- const parent = d.parent ? ledger.item(d.parent) : null;
531
- if (d.parent && !(parent ? parent.data.type === 'feature' : ledger.known(d.parent)))
536
+ if (d.parent && !parentKnown(d.parent, ledger))
532
537
  add('M2', 1, `parent ${d.parent} is neither a feature item nor an ended id`);
533
538
  const lost = (d.children ?? []).filter((c) => !ledger.known(c));
534
539
  if (lost.length) add('M2', 1, `children unknown: ${lost.join(', ')}`);