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/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.32.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,10 @@ 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`, and its `fallback`: the stand-ins in order when that row cannot make the pass
23
+ - a pass a stand-in or you made records both: `ai-factory gcf plan pass <id> … --by <who made it> --for <the row>`
24
+ - a `stalled` verdict: `ai-factory gcf review stall <id> --kind plan|code --passes <counts>` blocks the card
25
+ - `gcf review more` and `gcf review accept` answer a stall, and they are the human's
23
26
  - 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
27
  - 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
28
  - 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 +36,11 @@ gcf_work:
33
36
  - `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
37
  - 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
38
  - 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`
39
+ - `### Question` never restates the `miss_criterion`: the board shows it above; write only what this run adds to it
36
40
  - 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`
41
+ - 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
42
+ - keep its headings and the `<build> <device> [os]` of each row as the template gives them
43
+ - `ai-factory gcf play-notes <id>` names what the board would show as a warning: fix each before the commit
37
44
  - `submit` names what the notes lack as warnings; a move back to `ready` takes them out of the plan
38
45
  - 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
46
  - work that cannot go on: run `ai-factory gcf block <id> --reason "<why or the question>"`
@@ -72,6 +79,7 @@ gcf_work:
72
79
  - 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
80
  - 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
81
  - `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
82
+ - `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
83
  - 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
84
  - 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
85
  - 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,24 @@ 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. A row that cannot make its pass (no Codex, its limit,
31
+ # a failure) gives way to a model of its size: Codex medium to Fable medium then Opus high, Codex
32
+ # high and Fable medium to Opus high. Uncomment to change, or set it in Settings
33
+ # (ai-factory gcf config set review.plan --value "claude:opus:high, codex:astra:medium"):
34
+ # review:
35
+ # plan:
36
+ # - {agent: codex, model: astra, effort: medium}
37
+ # - {agent: claude, model: fable, effort: medium}
38
+ # - {agent: claude, model: fable, effort: medium}
39
+ # code:
40
+ # - {agent: codex, model: sol, effort: high}
41
+ # - {agent: claude, model: opus, effort: high}
42
+ # How a run drives an item: main (one at a time in the project folder, the default) or worktree
43
+ # (several at once, each in its own copy). A card whose worktree copy lives stays there:
44
+ # run_mode: worktree
36
45
  # Lessons (Methodology §5.2.2): at the end of each session on an item its agent says what got in
37
46
  # its way, into the inbox. `ai-factory gcf lessons prompt <id>` prints the questions. Uncomment to
38
47
  # turn them off, to ask what the project's template should learn, or to add questions:
@@ -55,7 +64,8 @@ dod:
55
64
  build:
56
65
  # How to build and start the game to play a finished card (ai-factory gcf playtest setup): a build
57
66
  # 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.
67
+ # is that card's build, `{port}` the target's port (the one it had last while nothing else holds
68
+ # it, so a phone's `adb reverse tcp:{port}` holds over the starts), `{lan}` this machine's address.
59
69
  # A name with a space in it: "{dir}/My Game.exe".
60
70
  # play:
61
71
  # build: <the command that builds the game>