gcf-aif-ext 0.29.2 → 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.
package/GLOSSARY.md CHANGED
@@ -34,5 +34,5 @@ terms:
34
34
  avoid: quota buffer
35
35
 
36
36
  - term: planning stall
37
- means: a plan whose improve passes keep finding blocking issues past `plan_passes`: the item waits for the human's more passes or implement as is
37
+ means: a plan or code whose review passes still find blocking issues when the rows of `review.plan|code` are over: the item waits for the human's more passes or go on as is
38
38
  avoid: non-convergence
package/README.md CHANGED
@@ -200,6 +200,7 @@ The functional base, part A (docs/Base-A-Plan.md). Update together with gcf-harn
200
200
 
201
201
  - `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`.
202
202
  - `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`.
203
+ - `config set` (core 0.30, Operator-Tasks-Plan t3): each setting of `gcf config` carries `title`, `hint` and `help` (its long text, with its key and file; `label` holds the same text), a number its `min`, `max`, `step` and `unit`, a setting with no default by its sense an `example`. A number outside its range is refused, from the CLI and the board alike. An empty `--value=` takes any key off, a mode or a command too (`gates.*`, `run_mode`, `chat.ask`, `dod.*`), so its default holds. `--pair` takes a list's lines too.
203
204
  - `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).
204
205
 
205
206
  ### 0.13.0
@@ -426,7 +427,7 @@ Every move of an item makes one commit `gcf(<move>): <id>` with every file it to
426
427
  **CNLP profiles and a work item schema** for the documents the agent reads — one profile per unit type, shared by a unit and its item — plus injections into `aif-plan`, `aif-review` and `aif-commit`.
427
428
 
428
429
 
429
- Improve passes (Hold-Plan): `gcf plan pass <id> --blocking N --polish M` records each pass in the plan's `## Passes` and answers continue, converged or stalled; `gcf plan stall` blocks a plan that does not converge, and the human answers with `gcf plan more <id> --passes N` or `gcf plan accept <id>`.
430
+ Review passes (Hold-Plan, Operator-Tasks-Plan t2): `review.plan` and `review.code` of `gcf/config.yml` are lists of rows `{agent: claude|codex, model, effort}` (`gcf config set review.plan --value "claude:opus:high, codex:astra:medium"`, `none`: no review; defaults opus·high ×2 and Codex astra·medium for the plan, opus·high ×2 for the code); row k makes pass k, the next only while the last found something blocking. `gcf review row <id> --kind plan|code --pass k [--diff] --json` names the row (and writes the code's diff for the reviewer to `.gcf-session/review/<id>.diff`: from where the card's work started to the disk, new files in, `gcf/` and `no_diff` out). `gcf plan pass <id> --blocking N --polish M [--by agent:model:effort] [--kind code]` records each pass in the plan's `## Passes` (the code's `## Reviews`) and answers continue, converged or stalled; `gcf review stall <id> --kind plan|code` blocks a review that does not converge (`stall.plan|code`; a card's old `stall` is the plan's), and the human answers with `gcf review more <id> --passes N` or `gcf review accept <id>`. `plan_passes` and `plan_review:` are gone: `gcf audit` names the one `config set review.plan` command that moves them, and that set drops them.
430
431
 
431
432
  ## Docs
432
433
 
package/commands/gcf.js CHANGED
@@ -2119,7 +2119,8 @@ function registerPlanPasses(plan) {
2119
2119
  )
2120
2120
  .requiredOption('--blocking <n>', 'findings that block the plan')
2121
2121
  .requiredOption('--polish <n>', 'findings that only polish it')
2122
- .option('--by <reviewer>', 'the pass was made by another reviewer (codex)')
2122
+ .option('--by <reviewer>', 'who made the pass: agent:model:effort (gcf review row), or self')
2123
+ .option('--kind <kind>', 'plan (## Passes) or code (## Reviews)', 'plan')
2123
2124
  .option('--json', 'machine output')
2124
2125
  .action(async (id, o) => {
2125
2126
  await touchSession(id);
@@ -2129,51 +2130,94 @@ function registerPlanPasses(plan) {
2129
2130
  blocking: Number(o.blocking),
2130
2131
  polish: Number(o.polish),
2131
2132
  by: o.by,
2133
+ kind: o.kind,
2132
2134
  });
2133
2135
  out(o.json, r, (x) => `pass ${x.pass}: ${x.verdict} (${x.passes.join(', ')})`);
2134
2136
  });
2135
- plan
2137
+ }
2138
+
2139
+ /**
2140
+ * The review passes of a plan and of the code (Operator-Tasks-Plan t2): who makes pass k, and the
2141
+ * stop when the rows are over with a blocking finding open, which blocks the card for the
2142
+ * operator's more or accept.
2143
+ */
2144
+ function registerReview(gcf) {
2145
+ const review = gcf.command('review').description('The review passes of a work item');
2146
+ review
2147
+ .command('row <id>')
2148
+ .description(
2149
+ 'Who makes pass k of the plan or code review (review.plan|code of gcf/config.yml; past ' +
2150
+ 'the rows, the last); --diff writes the code diff the reviewer reads',
2151
+ )
2152
+ .requiredOption('--kind <kind>', 'plan or code')
2153
+ .requiredOption('--pass <k>', 'the pass number, 1 or more')
2154
+ .option('--diff', 'code: write .gcf-session/review/<id>.diff and name it')
2155
+ .option('--json', 'machine output')
2156
+ .action(async (id, o) => {
2157
+ await touchSession(id);
2158
+ const r = await (
2159
+ await lib('review')
2160
+ ).reviewRow(process.cwd(), id, { kind: o.kind, pass: Number(o.pass), diff: o.diff });
2161
+ out(o.json, r, (x) =>
2162
+ [
2163
+ `pass ${x.pass}: ${x.by ?? 'no review'}`,
2164
+ ...(x.diff ? [`diff: ${x.diff.file}`] : []),
2165
+ ].join('\n'),
2166
+ );
2167
+ });
2168
+ review
2136
2169
  .command('stall <id>')
2137
2170
  .description(
2138
- 'Planning does not converge: block the card with its passes (commit gcf(plan_stall))',
2171
+ 'The review does not converge: block the card with its passes (commit gcf(plan_stall))',
2139
2172
  )
2140
2173
  .requiredOption('--passes <list>', 'the blocking findings of each pass, comma-separated')
2174
+ .option('--kind <kind>', 'plan or code', 'plan')
2141
2175
  .option('--reason <text>', 'what keeps it from converging')
2176
+ .option('--base <commit>', "code: the commit the card's work started from")
2142
2177
  .action(async (id, o) => {
2143
2178
  const passes = splitList(o.passes).map(Number);
2144
2179
  const r = await (
2145
2180
  await lib('work-ops')
2146
2181
  ).stallItem(process.cwd(), id, {
2147
2182
  passes,
2183
+ kind: o.kind,
2148
2184
  reason: o.reason,
2185
+ base: o.base,
2149
2186
  });
2150
- console.log(`${r.id} → blocked: planning does not converge · ${r.stall.passes.join(', ')}`);
2187
+ const what = r.kind === 'code' ? 'code review' : 'planning';
2188
+ console.log(`${r.id} → blocked: ${what} does not converge · ${r.stall.passes.join(', ')}`);
2151
2189
  });
2152
- registerStallAnswers(plan);
2190
+ registerStallAnswers(review);
2153
2191
  }
2154
2192
 
2155
- /** The operator's two answers to a planning stall (Hold-Plan d16). */
2156
- function registerStallAnswers(plan) {
2157
- plan
2193
+ /** The operator's two answers to a review stall (Hold-Plan d16, t2 d6); the kind is the stall's. */
2194
+ function registerStallAnswers(review) {
2195
+ review
2158
2196
  .command('more <id>')
2159
- .description("The operator's answer to a stall: N more passes, back to ready")
2197
+ .description("The operator's answer to a stall: N more passes on the last row, back to ready")
2160
2198
  .requiredOption('--passes <n>', 'how many more passes')
2199
+ .option('--kind <kind>', 'plan or code (default: the stall the card stands on)')
2161
2200
  .action(async (id, o) => {
2162
- await operatorOnly('plan more');
2201
+ await operatorOnly('review more');
2163
2202
  const r = await (
2164
2203
  await lib('work-ops')
2165
2204
  ).answerStall(process.cwd(), id, {
2166
2205
  more: Number(o.passes),
2206
+ kind: o.kind,
2167
2207
  });
2168
- console.log(`${r.id} → ready: ${r.stall.more} more pass(es) past plan_passes`);
2208
+ console.log(`${r.id} → ready: ${r.stall.more} more ${r.kind} pass(es) past the rows`);
2169
2209
  });
2170
- plan
2210
+ review
2171
2211
  .command('accept <id>')
2172
- .description("The operator's answer to a stall: implement the plan as it is, back to ready")
2173
- .action(async (id) => {
2174
- await operatorOnly('plan accept');
2175
- const r = await (await lib('work-ops')).answerStall(process.cwd(), id, { accept: true });
2176
- console.log(`${r.id} → ready: the plan goes to implementation as it is`);
2212
+ .description("The operator's answer to a stall: the plan or the code goes on as it is")
2213
+ .option('--kind <kind>', 'plan or code (default: the stall the card stands on)')
2214
+ .action(async (id, o) => {
2215
+ await operatorOnly('review accept');
2216
+ const r = await (
2217
+ await lib('work-ops')
2218
+ ).answerStall(process.cwd(), id, { accept: true, kind: o.kind });
2219
+ const goes = r.kind === 'code' ? 'the code goes on to its commit' : 'the plan goes on';
2220
+ console.log(`${r.id} → ready: ${goes} as it is`);
2177
2221
  });
2178
2222
  }
2179
2223
 
@@ -2553,6 +2597,7 @@ export function register(program) {
2553
2597
  registerLessons(gcf);
2554
2598
  registerLive(gcf);
2555
2599
  registerPlan(gcf);
2600
+ registerReview(gcf);
2556
2601
  registerVerify(gcf);
2557
2602
  registerIntegrate(gcf);
2558
2603
  registerBoard(gcf);
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.29.2",
4
+ "version": "0.31.0",
5
5
  "description": "Game Context Framework for AI Factory",
6
6
  "skills": [
7
7
  "skills/gcf-init",
@@ -190,9 +190,9 @@ export const DENY_GROUPS = [
190
190
  'ai-factory gcf verdict*',
191
191
  'ai-factory gcf question answer*',
192
192
  'ai-factory gcf unblock*',
193
- // The operator's answers to planning that does not converge (Hold-Plan d16).
194
- 'ai-factory gcf plan more*',
195
- 'ai-factory gcf plan accept*',
193
+ // The operator's answers to a review that does not converge (Hold-Plan d16, t2 d3).
194
+ 'ai-factory gcf review more*',
195
+ 'ai-factory gcf review accept*',
196
196
  'ai-factory gcf item gates*',
197
197
  'ai-factory gcf item amend*',
198
198
  'ai-factory gcf phase next*',
@@ -214,6 +214,8 @@ export const DENY_GROUPS = [
214
214
  'ai-factory gcf-harness stop*',
215
215
  // The operator's Hold of an item or the project (Hold-Plan d6): an agent holds nothing.
216
216
  'ai-factory gcf-harness hold*',
217
+ // Only the operator knows the limit was reset early; the wake lets the reserve go (t1 d1).
218
+ 'ai-factory gcf-harness wake*',
217
219
  // The operator's chat input: an agent answering its own question would be no answer.
218
220
  'ai-factory gcf-harness chat*',
219
221
  'ai-factory extension*',
package/lib/audit-core.js CHANGED
@@ -2,7 +2,15 @@ import { readFile } from 'node:fs/promises';
2
2
  import { existsSync } from 'node:fs';
3
3
  import path from 'node:path';
4
4
  import { spawnSync } from 'node:child_process';
5
- import { listItems, listSystems, readConfig, tokensEst, legacyCards } from './gcf-paths.js';
5
+ import {
6
+ listItems,
7
+ listSystems,
8
+ readConfig,
9
+ readRawConfig,
10
+ reviewMigration,
11
+ tokensEst,
12
+ legacyCards,
13
+ } from './gcf-paths.js';
6
14
  import { lint } from './linter.js';
7
15
  import { drifted } from './index-gen.js';
8
16
  import { designCheck, gameMilestones, recordsIn } from './design-check.js';
@@ -85,6 +93,7 @@ function runningOf(projectDir, id) {
85
93
  * @property {{legacy: boolean, bad_names: string[], untitled: string[], broken_links: string[],
86
94
  * orphan_dirs: string[], unmigrated: string[], unknown_category: string[],
87
95
  * unsorted: string[]}} inbox
96
+ * @property {string | null} [review_migration]
88
97
  */
89
98
 
90
99
  /**
@@ -131,6 +140,8 @@ export async function audit(projectDir) {
131
140
  stale_questions: staleQuestions(projectDir, root, config),
132
141
  inbox: await inboxProblems(root, inboxVocabulary()),
133
142
  play_on: playOnIssues(items, config, await platformsOf(root)),
143
+ // A config from before the review rows (Operator-Tasks-Plan t2 d1): the command that moves it.
144
+ review_migration: reviewMigration(await readRawConfig(root)),
134
145
  };
135
146
  // The harness gate reads everything from this one report — it never parses gcf/ itself.
136
147
  Object.assign(report, { schema: config.schema, gates: config.gates });
@@ -408,6 +419,9 @@ const docAlerts = (report) => [
408
419
  Object.keys(report.linter).length && 'П2 linter findings in systems docs',
409
420
  report.index_drift && 'INDEX drift (regenerate)',
410
421
  report.design?.blocking && `${report.design.blocking} blocking design finding(s)`,
422
+ report.review_migration &&
423
+ `plan_passes and plan_review: are gone, review.plan holds the passes: ` +
424
+ report.review_migration,
411
425
  ...playOnAlerts(report.play_on),
412
426
  ...inboxAlerts(report.inbox),
413
427
  ];
package/lib/board.js CHANGED
@@ -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
@@ -552,7 +552,7 @@ async function rowOf(projectDir, p, worktree) {
552
552
  const said = (d) => /^(?!diff --git |index ).+/m.test(d);
553
553
 
554
554
  /** `text` by the limits; `overrun`: git's pipe was cut, or the file longer than was read. */
555
- function cutOf(text, overrun = false) {
555
+ export function cutOf(text, overrun = false) {
556
556
  const clean = text.replace(/\r$/gm, '');
557
557
  const lines = clean.split('\n');
558
558
  const total = lines.at(-1) === '' ? lines.length - 1 : lines.length;
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,6 +328,7 @@ 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
334
  return head === 'run_mode' ? 'worktree' : (DEFAULT_CONFIG[head] ?? null);
@@ -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();