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/lib/review.js ADDED
@@ -0,0 +1,106 @@
1
+ // `gcf review row` (Operator-Tasks-Plan t2 d2): who makes pass k of an item's plan or code review,
2
+ // from `review.plan|code` of gcf/config.yml (row k, past the end the last), and, for the code,
3
+ // the diff the reviewer reads: from where the card's work started to the disk, new files in,
4
+ // the framework's own files out, the project's `no_diff` named and not shown, cut as Changes cuts.
5
+ import { spawnSync } from 'node:child_process';
6
+ import { mkdirSync, writeFileSync } from 'node:fs';
7
+ import path from 'node:path';
8
+ import { cutOf, globTest } from './changes.js';
9
+ import { onWorkBranch } from './commit-move.js';
10
+ import { gcfRoot, readConfig } from './gcf-paths.js';
11
+ import { buildLedger } from './ledger.js';
12
+ import { KINDS, stallOf } from './plan-check.js';
13
+ import { codeTree, NOT_CODE } from './verify-stamp.js';
14
+
15
+ const git = (dir, args) =>
16
+ spawnSync('git', args, { windowsHide: true, cwd: dir, encoding: 'utf8', maxBuffer: 64 << 20 });
17
+
18
+ const out = (dir, args) => {
19
+ const r = git(dir, args);
20
+
21
+ return r.status === 0 ? r.stdout.trim() : null;
22
+ };
23
+
24
+ /**
25
+ * Row k of the review of `kind` for item `id`: `{row: {agent, model, effort} | null, by, rows,
26
+ * more, accepted}`; with `diff` (the code's), the diff file the reviewer reads.
27
+ * @param {string} projectDir
28
+ * @param {string} id
29
+ * @param {{kind: string, pass: number, diff?: boolean}} o
30
+ */
31
+ export async function reviewRow(projectDir, id, { kind, pass, diff = false }) {
32
+ if (!KINDS.includes(kind)) throw new Error(`--kind is ${KINDS.join(' | ')}, got ${kind}`);
33
+ if (!Number.isInteger(pass) || pass < 1) throw new Error('--pass is the pass number, 1 or more');
34
+ const item = (await buildLedger(projectDir)).item(id);
35
+ if (!item) throw new Error(`${id} is not a work item of gcf/work/`);
36
+ const config = await readConfig(gcfRoot(projectDir));
37
+ const rows = config.review[kind];
38
+ const row = rows.length ? rows[Math.min(pass, rows.length) - 1] : null;
39
+ const stall = stallOf(item.data, kind) ?? {};
40
+ const withDiff = diff && kind === 'code';
41
+
42
+ return {
43
+ ...{ id, kind, pass, rows: rows.length, row },
44
+ plan: item.data.plan ?? `.ai-factory/plans/${id}.md`,
45
+ more: Number(stall.more ?? 0),
46
+ accepted: Boolean(stall.accepted),
47
+ by: byOf(row),
48
+ ...(withDiff
49
+ ? { diff: reviewDiff(projectDir, id, { base: stall.base, noDiff: config.no_diff }) }
50
+ : {}),
51
+ };
52
+ }
53
+
54
+ /** A row as a pass's `by`: `agent:model:effort` (t2 d2); null with no row. */
55
+ const byOf = (row) => (row ? `${row.agent}:${row.model}:${row.effort}` : null);
56
+
57
+ /**
58
+ * The base of a card's code review: in its worktree, where its branch left the main checkout;
59
+ * on main, the commit its work started from when a stall kept one, else HEAD (the review comes
60
+ * before the commit, so HEAD to the disk is the work).
61
+ */
62
+ function baseOf(dir, base) {
63
+ if (!onWorkBranch(dir)) return base ?? out(dir, ['rev-parse', 'HEAD']);
64
+ const common = out(dir, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
65
+ const main = common && out(path.dirname(common), ['rev-parse', 'HEAD']);
66
+
67
+ return (main && out(dir, ['merge-base', 'HEAD', main])) ?? out(dir, ['rev-parse', 'HEAD']);
68
+ }
69
+
70
+ /**
71
+ * Write the code's diff for the reviewer to `.gcf-session/review/<id>.diff`: `{file, files,
72
+ * no_diff, cut}`. The disk's code against the base, as `gcf verify` sees it (`codeTree`).
73
+ * @param {string} projectDir
74
+ * @param {string} id
75
+ * @param {{base?: string, noDiff?: string[]}} [o]
76
+ */
77
+ export function reviewDiff(projectDir, id, { base, noDiff = [] } = {}) {
78
+ const dir = path.resolve(projectDir);
79
+ const from = baseOf(dir, base);
80
+ const tree = codeTree(dir);
81
+ if (!from || !tree) throw new Error('the code review needs a git repository with a commit');
82
+ const own = (p) => NOT_CODE.some((d) => p === d || p.startsWith(`${d}/`));
83
+ const hidden = noDiff.map(globTest);
84
+ // NUL-separated: git quotes a name with non-ASCII letters otherwise, and the quoted name
85
+ // matches no path (Codex review of t2).
86
+ const listed = git(dir, ['diff', '--name-only', '-z', from, tree]);
87
+ if (listed.status !== 0) throw new Error(`git diff --name-only: ${listed.stderr.trim()}`);
88
+ const names = listed.stdout.split('\0').filter((p) => p && !own(p));
89
+ const shown = names.filter((p) => !hidden.some((t) => t(p)));
90
+ const unshown = names.filter((p) => !shown.includes(p));
91
+ const diffed = shown.length ? git(dir, ['diff', from, tree, '--', ...shown]) : null;
92
+ if (diffed && diffed.status !== 0) throw new Error(`git diff: ${diffed.stderr.trim()}`);
93
+ const raw = diffed?.stdout ?? '';
94
+ const { text, cut } = cutOf(raw);
95
+ const head = unshown.length ? `# no diff (no_diff): ${unshown.join(', ')}\n` : '';
96
+ const file = path.join(dir, '.gcf-session', 'review', `${id}.diff`);
97
+ mkdirSync(path.dirname(file), { recursive: true });
98
+ writeFileSync(file, `${head}${text}`);
99
+
100
+ return {
101
+ file: path.relative(dir, file).replaceAll('\\', '/'),
102
+ files: shown,
103
+ no_diff: unshown,
104
+ cut,
105
+ };
106
+ }
@@ -123,25 +123,48 @@ function changeProblem(c) {
123
123
 
124
124
  /** A live: delta (Methodology §8): `{none: <why>}` or `{changes: [{id, change, summary}]}`. */
125
125
  /**
126
- * What is wrong with an item's `stall:` (Hold-Plan d16), or null: `{passes, reason?, more?,
127
- * accepted?}`, the blocking counts of each pass, the operator's extra passes or their yes.
126
+ * Whether one review's stall entry holds (Hold-Plan d16, t2 d3): `{passes, reason?, more?,
127
+ * accepted?, base?}`, the blocking counts of each pass, the operator's extra passes or their yes,
128
+ * the commit a code review diffs from.
128
129
  */
129
- function stallProblem(v) {
130
+ function stallEntryOk(v, kind) {
130
131
  const count = (n) => Number.isInteger(n) && n >= 0;
131
- const keys = { passes: (x) => Array.isArray(x) && x.every(count) };
132
132
  const optional = {
133
133
  reason: (x) => typeof x === 'string',
134
134
  more: (x) => count(x) && x >= 1,
135
135
  accepted: (x) => x === true,
136
+ ...(kind === 'code'
137
+ ? { base: (x) => typeof x === 'string' && /^[0-9a-f]{7,40}$/.test(x) }
138
+ : {}),
136
139
  };
140
+
141
+ return (
142
+ v !== null &&
143
+ typeof v === 'object' &&
144
+ !Array.isArray(v) &&
145
+ Array.isArray(v.passes) &&
146
+ v.passes.every(count) &&
147
+ Object.entries(v).every(([k, x]) => k === 'passes' || optional[k]?.(x))
148
+ );
149
+ }
150
+
151
+ /**
152
+ * What is wrong with an item's `stall:`, or null: `{plan?, code?}`, each a review's stall (t2);
153
+ * the form before t2, one entry alone, is the plan's.
154
+ */
155
+ function stallProblem(v) {
156
+ if (stallEntryOk(v, 'plan')) return null;
137
157
  const ok =
138
158
  v !== null &&
139
159
  typeof v === 'object' &&
140
160
  !Array.isArray(v) &&
141
- keys.passes(v.passes) &&
142
- Object.entries(v).every(([k, x]) => k === 'passes' || optional[k]?.(x));
161
+ Object.keys(v).length > 0 &&
162
+ Object.entries(v).every(([k, x]) => (k === 'plan' || k === 'code') && stallEntryOk(x, k));
143
163
 
144
- return ok ? null : 'stall must be {passes: [counts], reason?, more?: n >= 1, accepted?: true}';
164
+ return ok
165
+ ? null
166
+ : 'stall must be {plan?, code?}, each {passes: [counts], reason?, more?: n >= 1, ' +
167
+ 'accepted?: true, base?: <commit> (code)}';
145
168
  }
146
169
 
147
170
  export function liveProblem(v) {
@@ -10,7 +10,7 @@ import path from 'node:path';
10
10
 
11
11
  // Not code: the framework's own files, the plans, the run files. A move or a plan tick there
12
12
  // after the verify does not change what the DoD proved.
13
- const NOT_CODE = ['gcf', '.ai-factory', '.gcf-session'];
13
+ export const NOT_CODE = ['gcf', '.ai-factory', '.gcf-session'];
14
14
 
15
15
  const stampFile = (projectDir, id) =>
16
16
  path.join(path.resolve(projectDir), '.gcf-session', 'runs', `${id}.verified`);
package/lib/work-ops.js CHANGED
@@ -1356,46 +1356,105 @@ async function amendItemUnlocked(projectDir, id, opts = {}) {
1356
1356
  return { id, changes, hash: await finish(m, 'amend', id, commit) };
1357
1357
  }
1358
1358
 
1359
+ // What a stall's block says, by its review (t2 d3): an answer finds its kind by it.
1360
+ const STALL_WORDS = {
1361
+ plan: 'planning does not converge',
1362
+ code: 'code review does not converge',
1363
+ };
1364
+
1365
+ /** A card's stalls by kind; the form before t2 (`{passes, …}` alone) is the plan's. */
1366
+ const stallsOf = (data) =>
1367
+ Array.isArray(data.stall?.passes) ? { plan: data.stall } : { ...(data.stall ?? {}) };
1368
+
1359
1369
  /**
1360
- * The run's stop of planning that does not converge (Hold-Plan d16): blocked, with the blocking
1361
- * counts of its passes kept in `stall`, for the operator's "more passes" or "implement as is".
1370
+ * The run's stop of a review that does not converge (Hold-Plan d16, t2 d3/d6): blocked, with
1371
+ * the blocking counts of its passes kept in `stall.<kind>`, for the operator's "more passes" or
1372
+ * "go on as is". A code stall keeps `base`, the commit the card's work started from: after more
1373
+ * passes on main the review diffs from it, not from the commit of the stalled code.
1362
1374
  * @param {string} projectDir
1363
1375
  * @param {string} id
1364
- * @param {{passes: number[], reason?: string, commit?: boolean}} opts
1376
+ * @param {{passes: number[], reason?: string, kind?: string, base?: string, commit?: boolean}} o
1365
1377
  */
1366
- async function stallItemUnlocked(projectDir, id, { passes, reason = '', commit = true }) {
1378
+ async function stallItemUnlocked(projectDir, id, o) {
1379
+ const { passes, reason = '', kind = 'plan', commit = true } = o;
1380
+ stallArgs(o);
1381
+ const m = await begin(projectDir, id, 'plan_stall');
1382
+ const why = String(reason).trim();
1383
+ const stalls = stallsOf(m.item.data);
1384
+ const entry = stallEntry(stalls[kind], { ...o, kind, reason: why });
1385
+ const stall = { ...stalls, [kind]: entry };
1386
+ const blocked = `${STALL_WORDS[kind]} · ${passes.join(', ')}${why ? `: ${why}` : ''}`;
1387
+ const data = { ...m.item.data, status: 'blocked', blocked, since: headHash(projectDir), stall };
1388
+ m.step(() => writeItem(m.item, data));
1389
+
1390
+ return { id, kind, stall: entry, hash: await finish(m, 'plan_stall', id, commit) };
1391
+ }
1392
+
1393
+ /**
1394
+ * The refusal of a stall's arguments, if any.
1395
+ * @param {any} o
1396
+ */
1397
+ function stallArgs({ passes, kind = 'plan', base }) {
1367
1398
  if (
1368
1399
  !Array.isArray(passes) ||
1369
1400
  !passes.length ||
1370
1401
  !passes.every((n) => Number.isInteger(n) && n >= 0)
1371
1402
  )
1372
1403
  throw new Error('--passes is the blocking count of each pass, e.g. 7,3,2,1');
1373
- const m = await begin(projectDir, id, 'plan_stall');
1374
- const why = String(reason).trim();
1375
- // The operator's extra passes of this cycle stay: a second stall counts past them (review 3).
1376
- const more = m.item.data.stall?.more;
1377
- const stall = { passes, ...(why ? { reason: why } : {}), ...(more ? { more } : {}) };
1378
- const blocked = `planning does not converge · ${passes.join(', ')}${why ? `: ${why}` : ''}`;
1379
- const data = { ...m.item.data, status: 'blocked', blocked, since: headHash(projectDir), stall };
1380
- m.step(() => writeItem(m.item, data));
1404
+ if (!(kind in STALL_WORDS)) throw new Error(`--kind is plan | code, got ${kind}`);
1405
+ if (base !== undefined && !/^[0-9a-f]{7,40}$/.test(base))
1406
+ throw new Error('--base is a commit hash');
1407
+ }
1408
+
1409
+ /**
1410
+ * A stall's entry: the operator's extra passes of this cycle stay, so a second stall counts past
1411
+ * them (review 3); a second stall of the code keeps the base of the first.
1412
+ */
1413
+ /**
1414
+ * @param {any} was
1415
+ * @param {any} o
1416
+ */
1417
+ function stallEntry(was, { passes, reason, kind, base }) {
1418
+ was ??= {};
1419
+
1420
+ return {
1421
+ passes,
1422
+ ...(reason ? { reason } : {}),
1423
+ ...(kind === 'code' && base ? { base } : {}),
1424
+ ...(was.more ? { more: was.more } : {}),
1425
+ ...(was.base ? { base: was.base } : {}),
1426
+ };
1427
+ }
1428
+
1429
+ /** The kind of the stall a card stands on: `--kind`, else its block's words say. */
1430
+ function stallKind(data, kind) {
1431
+ if (kind !== undefined) {
1432
+ if (!(kind in STALL_WORDS)) throw new Error(`--kind is plan | code, got ${kind}`);
1433
+
1434
+ return kind;
1435
+ }
1381
1436
 
1382
- return { id, stall, hash: await finish(m, 'plan_stall', id, commit) };
1437
+ return String(data.blocked ?? '').startsWith(STALL_WORDS.code) ? 'code' : 'plan';
1383
1438
  }
1384
1439
 
1385
1440
  /**
1386
- * The operator's answer to a stall (Hold-Plan d16): `more` passes past the limit, or `accept`
1387
- * the plan as it is; the card goes back to ready, its stall kept with the answer.
1441
+ * The operator's answer to a stall (Hold-Plan d16, t2 d6): `more` passes past the rows, or
1442
+ * `accept` the plan or the code as it is; the card goes back to ready, its stall kept with the
1443
+ * answer.
1388
1444
  * @param {string} projectDir
1389
1445
  * @param {string} id
1390
- * @param {{more?: number, accept?: boolean, commit?: boolean}} opts
1446
+ * @param {{more?: number, accept?: boolean, kind?: string, commit?: boolean}} opts
1391
1447
  */
1392
- async function answerStallUnlocked(projectDir, id, { more, accept = false, commit = true }) {
1448
+ async function answerStallUnlocked(projectDir, id, { more, accept = false, kind, commit = true }) {
1393
1449
  const move = accept ? 'plan_accept' : 'plan_more';
1394
1450
  if (!accept && !(more !== undefined && Number.isInteger(more) && more >= 1))
1395
1451
  throw new Error('more passes: a number, 1 or more');
1396
1452
  const m = await begin(projectDir, id, move);
1397
- const stall = m.item.data.stall;
1398
- if (!stall) throw new Error(`${id} is not stalled in planning: nothing to answer`);
1453
+ const k = stallKind(m.item.data, kind);
1454
+ const stalls = stallsOf(m.item.data);
1455
+ const stall = stalls[k];
1456
+ const what = k === 'plan' ? 'planning' : 'its code review';
1457
+ if (!stall) throw new Error(`${id} is not stalled in ${what}: nothing to answer`);
1399
1458
  const answered = accept
1400
1459
  ? { ...stall, accepted: true }
1401
1460
  : { ...stall, more: Number(stall.more ?? 0) + /** @type {number} */ (more) };
@@ -1403,12 +1462,12 @@ async function answerStallUnlocked(projectDir, id, { more, accept = false, commi
1403
1462
  ...without(m.item.data, 'blocked'),
1404
1463
  status: 'ready',
1405
1464
  since: null,
1406
- stall: answered,
1465
+ stall: { ...stalls, [k]: answered },
1407
1466
  };
1408
1467
  m.step(() => writeItem(m.item, data));
1409
1468
  dropPlayNotesOf(m);
1410
1469
 
1411
- return { id, stall: answered, hash: await finish(m, move, id, commit) };
1470
+ return { id, kind: k, stall: answered, hash: await finish(m, move, id, commit) };
1412
1471
  }
1413
1472
 
1414
1473
  /** What a fix asks for, trimmed: a blank field is none, an over-long or broken one refused. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-aif-ext",
3
- "version": "0.29.2",
3
+ "version": "0.31.0",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -24,9 +24,9 @@
24
24
  "node": ">=22.14"
25
25
  },
26
26
  "scripts": {
27
- "test": "node --test && npm run test:gate",
27
+ "test": "node --test \"test/**/*.test.js\" && npm run test:gate",
28
28
  "prepack": "node -e \"const p=require('./package.json'),e=require('./extension.json');if(p.version!==e.version)throw new Error('version mismatch: package.json '+p.version+' vs extension.json '+e.version)\"",
29
- "test:gate": "node -e \"process.env.GCF_TEST_GATE='1';require('node:child_process').execFileSync(process.execPath,['--test'],{stdio:'inherit'})\""
29
+ "test:gate": "node -e \"process.env.GCF_TEST_GATE='1';require('node:child_process').execFileSync(process.execPath,['--test','test/**/*.test.js'],{stdio:'inherit'})\""
30
30
  },
31
31
  "files": [
32
32
  "extension.json",
@@ -6,6 +6,18 @@
6
6
  "additionalProperties": false,
7
7
  "required": ["schema", "id", "type", "gate", "status", "created"],
8
8
  "definitions": {
9
+ "stallEntry": {
10
+ "type": "object",
11
+ "additionalProperties": false,
12
+ "required": ["passes"],
13
+ "properties": {
14
+ "passes": { "type": "array", "items": { "type": "integer", "minimum": 0 } },
15
+ "reason": { "type": "string" },
16
+ "more": { "type": "integer", "minimum": 1 },
17
+ "accepted": { "const": true },
18
+ "base": { "type": "string", "pattern": "^[0-9a-f]{7,40}$" }
19
+ }
20
+ },
9
21
  "slug": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
10
22
  "slugOrNull": {
11
23
  "anyOf": [{ "type": "null" }, { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }]
@@ -57,15 +69,18 @@
57
69
  "tune_count": { "type": "integer", "minimum": 0 },
58
70
  "plan_cycle": { "type": "integer", "minimum": 1 },
59
71
  "stall": {
60
- "type": "object",
61
- "additionalProperties": false,
62
- "required": ["passes"],
63
- "properties": {
64
- "passes": { "type": "array", "items": { "type": "integer", "minimum": 0 } },
65
- "reason": { "type": "string" },
66
- "more": { "type": "integer", "minimum": 1 },
67
- "accepted": { "const": true }
68
- }
72
+ "anyOf": [
73
+ { "$ref": "#/definitions/stallEntry" },
74
+ {
75
+ "type": "object",
76
+ "additionalProperties": false,
77
+ "minProperties": 1,
78
+ "properties": {
79
+ "plan": { "$ref": "#/definitions/stallEntry" },
80
+ "code": { "$ref": "#/definitions/stallEntry" }
81
+ }
82
+ }
83
+ ]
69
84
  },
70
85
  "severity": {
71
86
  "anyOf": [{ "type": "null" }, { "enum": ["critical", "high", "medium", "low"] }]
@@ -19,7 +19,9 @@ gcf_work:
19
19
  - an item's plan is in the plan form: blocks `context:`, `decisions:` (records `id`, `pick`, `why`), `tasks:` (`- [ ] t1 <action> (d1)`), `pillar_check:`, `verification:`, one idea a line
20
20
  - `ai-factory gcf plan check <id>` lists the plan's form problems as `format:` lines: fix them, they never block
21
21
  - record each improve pass of a plan with `ai-factory gcf plan pass <id> --blocking <n> --polish <m> --json`; its verdict decides: continue, converged or stalled
22
- - a `stalled` verdict: `ai-factory gcf plan stall <id> --passes <counts>` blocks the card; `gcf plan more` and `gcf plan accept` answer it, and they are the human's
22
+ - `ai-factory gcf review row <id> --kind plan|code --pass <k> --json` names who makes review pass k, by `review.plan|code` of `gcf/config.yml`
23
+ - a `stalled` verdict: `ai-factory gcf review stall <id> --kind plan|code --passes <counts>` blocks the card
24
+ - `gcf review more` and `gcf review accept` answer a stall, and they are the human's
23
25
  - a harness run plans in one session and implements in a fresh one (`GCF_RUN_PHASE`); in your own terminal stop after planning unless the human asked for `--through`
24
26
  - drive a ready item with the gcf-run skill when the project has gcf-harness-aif-ext and the agent is Claude Code (a batch at once: `ai-factory gcf-harness run <ids...>`), otherwise with aif-plan and aif-implement
25
27
  - answer a question about how the runs go (the share that reached their move, cost, plan checks, DoD attempts, guard firings) with `ai-factory gcf-harness metrics`
@@ -33,7 +35,11 @@ gcf_work:
33
35
  - `submit` and `close` refuse code that changed since its last green `gcf verify`: run it again after any fix; `--unverified "<why>"` is the human's call, never the agent's
34
36
  - before the commit that ends a gate-verdict item, write `## Play notes` into its plan from `ai-factory gcf play-notes <id> --template`, in main and in a worktree alike
35
37
  - its sections: `### Question` (notes under the card's `miss_criterion`), `### Try`, `### Rows` (a line per row the template lists: `- <build> <device> [os]: <note>`), `### Watch out`, `### Notes`
38
+ - `### Question` never restates the `miss_criterion`: the board shows it above; write only what this run adds to it
36
39
  - the fields for the player say what is seen and what to do in the game, never how to start it, no hashes, no paths, no commands: those go to `### Notes`
40
+ - write the text of `## Play notes` in `language.ui` of `.ai-factory/config.yaml`, though the rest of the plan is in `language.artifacts`: the human reads it on the board
41
+ - keep its headings and the `<build> <device> [os]` of each row as the template gives them
42
+ - `ai-factory gcf play-notes <id>` names what the board would show as a warning: fix each before the commit
37
43
  - `submit` names what the notes lack as warnings; a move back to `ready` takes them out of the plan
38
44
  - then end the work on the item with its command: `ai-factory gcf submit <id>` for gate verdict or decision, `ai-factory gcf close <id>` for gate auto
39
45
  - work that cannot go on: run `ai-factory gcf block <id> --reason "<why or the question>"`
@@ -72,6 +78,7 @@ gcf_work:
72
78
  - the stops that wait for the human are the `gates:` of `gcf/config.yml` (`milestone`, `verdict`, `decision`, `question`) and each card's `skip_gates:`, both the human's (`config set`, `item gates`); the core applies them itself
73
79
  - the board's autopilot starts the runs and the card sessions (`ai-factory gcf-harness card`) by itself and stops when a milestone is built for the human to play; an agent starts neither
74
80
  - `ai-factory gcf-harness hold <id>` and `hold --project` are the human's: a held session hands over at its next call, and an agent holds nothing
81
+ - `ai-factory gcf-harness wake <id>` (`--thread <t>`, `--all`) is the human's: it ends a usage-limit wait when the limit was reset early; an agent never runs it
75
82
  - the queue and the autopilot stand at the quota's reserve (`quota_reserve_pct` of `~/.gcf/settings.json`); the human's own Run does not
76
83
  - an item the human wants run on a given model or effort gets `item new --title "<title>" --model <m> --effort <e>`: the harness run passes both to the agent
77
84
  - an existing item changes with `ai-factory gcf item agent <id> --model <m> --effort <e>` (`default` takes one off), never a hand edit; its next run takes them
@@ -7,7 +7,6 @@ context_budget: 30000
7
7
  pillars_budget: 1500
8
8
  envelope_default_spread: 0.3
9
9
  unplayed_warn_after: 5
10
- plan_passes: 3
11
10
  dod_attempts: 2
12
11
  # Minutes a dod.test or dod.build command may take before it is killed with all it started
13
12
  # (0: no limit): a hung engine fails the DoD instead of holding the run.
@@ -25,14 +24,19 @@ auto_compact_pct: 0
25
24
  # chat:
26
25
  # ask: d1
27
26
  # answer_timeout_min: 15
28
- # The plan's improve passes (Hold-Plan d17): when a pass still finds blocking issues, pass `at`
29
- # goes to an outside reviewer, read-only (Codex CLI); without it, or when it fails, Claude makes
30
- # the pass. Uncomment to change (agent: none turns it off):
31
- # plan_review:
32
- # agent: codex
33
- # model: gpt-6-astra
34
- # effort: medium
35
- # at: 3
27
+ # The review passes of a plan and of the code before its commit (Operator-Tasks-Plan t2): row k
28
+ # makes pass k (agent claude or codex; a Claude model alias, a Codex family or slug; an effort);
29
+ # the next pass goes only while the last found something blocking; the rows over, the card
30
+ # blocks for you. An empty list: no review. Uncomment to change, or set it in Settings
31
+ # (ai-factory gcf config set review.plan --value "claude:opus:high, codex:astra:medium"):
32
+ # review:
33
+ # plan:
34
+ # - {agent: claude, model: opus, effort: high}
35
+ # - {agent: claude, model: opus, effort: high}
36
+ # - {agent: codex, model: astra, effort: medium}
37
+ # code:
38
+ # - {agent: claude, model: opus, effort: high}
39
+ # - {agent: claude, model: opus, effort: high}
36
40
  # Lessons (Methodology §5.2.2): at the end of each session on an item its agent says what got in
37
41
  # its way, into the inbox. `ai-factory gcf lessons prompt <id>` prints the questions. Uncomment to
38
42
  # turn them off, to ask what the project's template should learn, or to add questions:
@@ -55,7 +59,8 @@ dod:
55
59
  build:
56
60
  # How to build and start the game to play a finished card (ai-factory gcf playtest setup): a build
57
61
  # a card keeps for itself until its verdict. `output` is git-ignored, inside the project; `{dir}`
58
- # is that card's build, `{port}` a free port, `{lan}` this machine's address.
62
+ # is that card's build, `{port}` the target's port (the one it had last while nothing else holds
63
+ # it, so a phone's `adb reverse tcp:{port}` holds over the starts), `{lan}` this machine's address.
59
64
  # A name with a space in it: "{dir}/My Game.exe".
60
65
  # play:
61
66
  # build: <the command that builds the game>