gcf-aif-ext 0.31.0 → 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/README.md CHANGED
@@ -50,6 +50,15 @@ Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook. Run `ai-f
50
50
 
51
51
  On Windows, run `extension add` and `extension update` from PowerShell or cmd, not Git Bash: the installer unpacks with `tar`, and Git Bash's GNU tar reads `C:\…` as a remote host (`Cannot connect to C: resolve failed`). The Windows `tar.exe` handles it.
52
52
 
53
+ ### 0.32.0
54
+
55
+ Update together with gcf-board 0.32.0 (`gcf board --json` is `schema: 6`; each refuses the other's old schema) and gcf-harness-aif-ext 0.31.0 ([Fallback-Fidelity-Plan](https://github.com/VirtualMaestro/GCF/blob/main/docs/Fallback-Fidelity-Plan.md)). Then run `ai-factory gcf init`: the `AGENTS.md` block changed.
56
+
57
+ - **`run_mode` is `main` by default.** To keep parallel runs in worktrees, set `run_mode: worktree` in `gcf/config.yml` (or Settings). An item whose worktree copy or `work/<id>` branch still lives runs in `worktree` until the copy closes, whatever the default; a kept session resumes where it ran. `gcf audit` says `run_mode is main by default now; set worktree to keep parallel runs` while `run_mode` is unset and worktree copies live. The board read gives each card `runs_in`: its own `run_mode`, else its kept session's place, else `worktree` while its copy lives, else the project's.
58
+ - **Review defaults:** `review.plan` is `codex:astra:medium`, `claude:fable:medium`, `claude:fable:medium`; `review.code` is `codex:sol:high`, `claude:opus:high`. Lists already in `gcf/config.yml` stay as they are.
59
+ - **Stand-ins:** a review row that cannot make its pass gives way to the next of its stand-ins: a Codex `medium` row to `claude:fable:medium`, then `claude:opus:high`; a Codex `high` row to `claude:opus:high`; `claude:fable:medium` to `claude:opus:high`; any other row has none. After the last one, the session's own model makes the pass. `gcf review row --json` gives the row's `fallback`; the board read carries the table as `review_fallback`.
60
+ - **`gcf plan pass --for <row>`:** a pass made by a stand-in or by the session records the row it stands for (`, for agent:model:effort` in the pass line); the verdict counts the same. An older board loses the Passes fold on such a line: update it together.
61
+
53
62
  ### 0.27.0
54
63
 
55
64
  - **`gcf changes push` and `gcf changes pull`** ([Push-Plan](https://github.com/VirtualMaestro/GCF/blob/main/docs/Push-Plan.md)): the board's Push and Pull. Push sends the main checkout's branch to its upstream, fast-forward only: no `+`, no `--force`, no `--no-verify`, and no flag that adds one. With no upstream it pushes to `origin`, or the only remote, with `-u`; `--remote <name>` picks another. Pull is `fetch` and `merge --ff-only` of the same target: a branch with commits of its own over the remote's is refused as `diverged`, main untouched, and the merge is the agent's (`git pull --no-rebase`). Pull claims the checkout as a build by click does: no run starts meanwhile.
@@ -307,7 +316,7 @@ Update together with gcf-harness-aif-ext 0.12.0 and gcf-board 0.6.0 (docs/Sessio
307
316
  - `ai-factory gcf question answer <q-id> --text="<answer>"` writes the human's answer into its record of `gcf/open-questions.md` and commits. An answered D1 no longer blocks its units; the next agent on the unit puts the answer into its slot (`answer: q-NNN`) and removes the record. `gcf board --json` questions carry `question`, `proposed`, `blocks` and `answer`.
308
317
  - `ai-factory gcf claim <id>` / `release <id>`: an agent session working an item in the main checkout marks it running. The session's own `context`, `plan check` and `verify` on the item keep the mark fresh (so do a harness run on main and its readset-guard hook), a move on the item clears it, and 2 hours without either expire it. The board and the audit read it as `running`, so a harness run does not take the item, and the core refuses any move on it but the session's own (`submit`, `close`, `block` with `--claimed`). The mark names its owner (`GCF_RUN_OWNER` of a harness run, else `CLAUDE_CODE_SESSION_ID`): another owner's claim and `--claimed` moves are refused while it is fresh.
309
318
  - `prioritize` leaves the rank of a ready item it does not name (a running one): the named items take the free ranks around it.
310
- - `run_mode: worktree | main` in `gcf/config.yml` (Methodology §7): a project whose agent works through an editor bound to the project folder sets `main`. `gcf board --json` carries it.
319
+ - `run_mode: main | worktree` in `gcf/config.yml` (Methodology §7): `main` by default (one card at a time in the project folder); set `worktree` to keep parallel runs, each in its own copy. A card the harness keeps a session record of (`.gcf-session/runs/<id>.agent.json` `mode`) runs where that session ran, and one whose worktree copy or `work/<id>` branch lives runs in `worktree` until it is closed, whatever the default (its own `run_mode` comes first); `gcf audit` names a project that leaves `run_mode` unset while such copies live. `gcf board --json` carries the project's mode and each item's `runs_in`.
311
320
  - `/gcf-card` cuts several items along subsystem boundaries, marks two items of one subsystem that change different files `parallel: ok`, ranks them with `prioritize`, and keeps `depends` for real needs only.
312
321
 
313
322
  ### 0.6.0
@@ -427,7 +436,7 @@ Every move of an item makes one commit `gcf(<move>): <id>` with every file it to
427
436
  **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`.
428
437
 
429
438
 
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.
439
+ 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 Codex astra·medium and fable·medium ×2 for the plan, Codex sol·high and opus·high for the code); row k makes pass k, the next only while the last found something blocking. A row that cannot make its pass gives way to a model of its size (Fallback-Fidelity-Plan d2): Codex medium to fable·medium then opus·high, Codex high and fable·medium to opus·high, any other to none; `gcf board --json` carries the rules as `review_fallback`. `gcf review row <id> --kind plan|code --pass k [--diff] --json` names the row and its `fallback` (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 [--for agent:model:effort]] [--kind code]` records each pass (`, for` the row, when someone else made it: `self` or a stand-in) 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.
431
440
 
432
441
  ## Docs
433
442
 
package/commands/gcf.js CHANGED
@@ -1541,7 +1541,11 @@ function registerAgent(item) {
1541
1541
  .description(
1542
1542
  "Set where an item's runs go: main or worktree over the project's run_mode (commit)",
1543
1543
  )
1544
- .requiredOption('--run <mode>', "main, worktree, or default: the project's run_mode")
1544
+ .requiredOption(
1545
+ '--run <mode>',
1546
+ 'main, worktree, or default: where its kept session ran, else its live worktree copy, ' +
1547
+ "else the project's run_mode",
1548
+ )
1545
1549
  .option('--no-commit', 'skip the commit (tests only)')
1546
1550
  .action(async (id, o) => {
1547
1551
  const r = await (
@@ -2120,6 +2124,10 @@ function registerPlanPasses(plan) {
2120
2124
  .requiredOption('--blocking <n>', 'findings that block the plan')
2121
2125
  .requiredOption('--polish <n>', 'findings that only polish it')
2122
2126
  .option('--by <reviewer>', 'who made the pass: agent:model:effort (gcf review row), or self')
2127
+ .option(
2128
+ '--for <row>',
2129
+ 'the row the pass was asked of (agent:model:effort) when --by stood in for it',
2130
+ )
2123
2131
  .option('--kind <kind>', 'plan (## Passes) or code (## Reviews)', 'plan')
2124
2132
  .option('--json', 'machine output')
2125
2133
  .action(async (id, o) => {
@@ -2130,6 +2138,7 @@ function registerPlanPasses(plan) {
2130
2138
  blocking: Number(o.blocking),
2131
2139
  polish: Number(o.polish),
2132
2140
  by: o.by,
2141
+ for: o.for,
2133
2142
  kind: o.kind,
2134
2143
  });
2135
2144
  out(o.json, r, (x) => `pass ${x.pass}: ${x.verdict} (${x.passes.join(', ')})`);
@@ -2161,6 +2170,9 @@ function registerReview(gcf) {
2161
2170
  out(o.json, r, (x) =>
2162
2171
  [
2163
2172
  `pass ${x.pass}: ${x.by ?? 'no review'}`,
2173
+ ...(x.fallback.length
2174
+ ? [`fallback: ${x.fallback.map((f) => `${f.agent}:${f.model}:${f.effort}`).join(', ')}`]
2175
+ : []),
2164
2176
  ...(x.diff ? [`diff: ${x.diff.file}`] : []),
2165
2177
  ].join('\n'),
2166
2178
  );
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.31.0",
4
+ "version": "0.32.0",
5
5
  "description": "Game Context Framework for AI Factory",
6
6
  "skills": [
7
7
  "skills/gcf-init",
package/lib/audit-core.js CHANGED
@@ -26,6 +26,7 @@ import { inboxVocabulary } from './domain.js';
26
26
  import { gatePolicy, verdictDeferred } from './gates.js';
27
27
  import { milestoneState } from './milestone-state.js';
28
28
  import { mainWork } from './shelf.js';
29
+ import { cardRunMode, liveCopies } from './integrate.js';
29
30
  import { playOnIssues } from './play-on.js';
30
31
  import { platformsOf } from './playtest-list.js';
31
32
 
@@ -94,6 +95,7 @@ function runningOf(projectDir, id) {
94
95
  * orphan_dirs: string[], unmigrated: string[], unknown_category: string[],
95
96
  * unsorted: string[]}} inbox
96
97
  * @property {string | null} [review_migration]
98
+ * @property {boolean} [run_mode_default] run_mode unset while worktree copies live
97
99
  */
98
100
 
99
101
  /**
@@ -104,6 +106,8 @@ function runningOf(projectDir, id) {
104
106
  export async function audit(projectDir) {
105
107
  const root = path.join(path.resolve(projectDir), 'gcf');
106
108
  const config = await readConfig(root);
109
+ const raw = await readRawConfig(root);
110
+ const live = liveCopies(projectDir);
107
111
  const items = await listItems(root);
108
112
  const systems = await listSystems(root);
109
113
  const ledger = await buildLedger(projectDir);
@@ -141,11 +145,13 @@ export async function audit(projectDir) {
141
145
  inbox: await inboxProblems(root, inboxVocabulary()),
142
146
  play_on: playOnIssues(items, config, await platformsOf(root)),
143
147
  // A config from before the review rows (Operator-Tasks-Plan t2 d1): the command that moves it.
144
- review_migration: reviewMigration(await readRawConfig(root)),
148
+ review_migration: reviewMigration(raw),
149
+ // run_mode unset while worktree copies live (Fallback-Fidelity-Plan d1): main by default now.
150
+ run_mode_default: (raw.run_mode ?? null) === null && live.size > 0,
145
151
  };
146
152
  // The harness gate reads everything from this one report — it never parses gcf/ itself.
147
153
  Object.assign(report, { schema: config.schema, gates: config.gates });
148
- report.items = items.map((c) => itemRow(projectDir, config, c));
154
+ report.items = items.map((c) => itemRow(projectDir, config, live, c));
149
155
  // The card whose unfinished work lies in the folder (lib/shelf.js): the next claim shelves it.
150
156
  const work = mainWork(projectDir);
151
157
  if (work) report.main_work = work;
@@ -165,7 +171,7 @@ export async function audit(projectDir) {
165
171
  }
166
172
 
167
173
  /** An item as the report lists it for the harness gate. */
168
- function itemRow(projectDir, config, c) {
174
+ function itemRow(projectDir, config, live, c) {
169
175
  return {
170
176
  id: c.data.id,
171
177
  type: c.data.type,
@@ -178,8 +184,13 @@ function itemRow(projectDir, config, c) {
178
184
  parallel: c.data.parallel ?? 'serial',
179
185
  priority: c.data.priority ?? null,
180
186
  milestone: c.data.milestone ?? null,
181
- // Where its run goes: its own run_mode, else the project's (an autopilot batches by it).
182
- run_mode: c.data.run_mode ?? config.run_mode,
187
+ // Where its run goes: its own run_mode, where its kept session ran, worktree while its copy
188
+ // lives, else the project's (an autopilot batches by it).
189
+ run_mode: cardRunMode(projectDir, String(c.data.id), {
190
+ own: c.data.run_mode,
191
+ project: config.run_mode,
192
+ live,
193
+ }),
183
194
  // The gates in force (docs/Autonomy-Plan.md, B); `deferred`: its submit closes unplayed.
184
195
  gates: gatePolicy(config, c.data),
185
196
  deferred: verdictDeferred(config, c.data),
@@ -419,11 +430,17 @@ const docAlerts = (report) => [
419
430
  Object.keys(report.linter).length && 'П2 linter findings in systems docs',
420
431
  report.index_drift && 'INDEX drift (regenerate)',
421
432
  report.design?.blocking && `${report.design.blocking} blocking design finding(s)`,
433
+ ...configAlerts(report),
434
+ ...playOnAlerts(report.play_on),
435
+ ...inboxAlerts(report.inbox),
436
+ ];
437
+
438
+ /** Alerts about gcf/config.yml. @param {AuditReport} report */
439
+ const configAlerts = (report) => [
422
440
  report.review_migration &&
423
441
  `plan_passes and plan_review: are gone, review.plan holds the passes: ` +
424
442
  report.review_migration,
425
- ...playOnAlerts(report.play_on),
426
- ...inboxAlerts(report.inbox),
443
+ report.run_mode_default && 'run_mode is main by default now; set worktree to keep parallel runs',
427
444
  ];
428
445
 
429
446
  /** A card's play_on and played_on name builds (docs/Handoff-Plan.md d8). */
package/lib/board.js CHANGED
@@ -5,11 +5,11 @@ import { readFile } from 'node:fs/promises';
5
5
  import { existsSync } from 'node:fs';
6
6
  import path from 'node:path';
7
7
  import { buildLedger } from './ledger.js';
8
- import { readConfig } from './gcf-paths.js';
8
+ import { readConfig, REVIEW_FALLBACK } from './gcf-paths.js';
9
9
  import { readLive } from './live.js';
10
10
  import { filesUnder, listInbox } from './inbox.js';
11
11
  import { phaseStatus } from './phase.js';
12
- import { verifiedBranches, worktreeOf } from './integrate.js';
12
+ import { cardRunMode, liveCopies, verifiedBranches, worktreeOf } from './integrate.js';
13
13
  import { resolveInside } from './safe-path.js';
14
14
  import { wipOf } from './audit-core.js';
15
15
  import { MAIN_RUN, lockedItem, runHolder } from './main-lock.js';
@@ -32,7 +32,7 @@ import { handoffOf } from './handoff.js';
32
32
 
33
33
  // The version of the JSON below (Methodology §11): a board refuses one it does not know. Bump it
34
34
  // when a field changes meaning or goes away; a new field does not bump it.
35
- export const BOARD_SCHEMA = 5;
35
+ export const BOARD_SCHEMA = 6;
36
36
 
37
37
  /**
38
38
  * Plan progress `{tasks, done}` from its checkboxes and the plan's project path, both null
@@ -335,7 +335,7 @@ async function handoffPart(projectDir, id, read) {
335
335
  return handoff ? { handoff } : {};
336
336
  }
337
337
 
338
- async function itemOf(projectDir, c, { verified, shelved, ledger, harness, config, links }) {
338
+ async function itemOf(projectDir, c, { verified, shelved, live, ledger, harness, config, links }) {
339
339
  const builds = itemBuilds(projectDir, String(c.data.id), c.data.status, links);
340
340
  const id = String(c.data.id);
341
341
  // A trailer counts only while the item waits on main for its integrate.
@@ -369,6 +369,13 @@ async function itemOf(projectDir, c, { verified, shelved, ledger, harness, confi
369
369
  running_kind: kind,
370
370
  resumable,
371
371
  resume,
372
+ // Where a run that asks no mode takes it (Fallback-Fidelity-Plan d1): its own, where its kept
373
+ // session ran, worktree while its copy lives, the project's.
374
+ runs_in: cardRunMode(projectDir, id, {
375
+ own: c.data.run_mode,
376
+ project: config.run_mode,
377
+ live,
378
+ }),
372
379
  verified: ready,
373
380
  // Its unfinished work waits on its branch (lib/shelf.js); a run brings it back.
374
381
  ...(shelved.has(id) ? { shelved: shelved.get(id) } : {}),
@@ -398,9 +405,12 @@ async function itemsOf(projectDir, { ledger, harness, config }) {
398
405
  const verified = verifiedOf(projectDir);
399
406
  const shelved = shelvedCards(projectDir);
400
407
  const links = linksOf(projectDir);
408
+ const live = liveCopies(projectDir);
401
409
  const items = [];
402
410
  for (const c of ledger.items)
403
- items.push(await itemOf(projectDir, c, { verified, shelved, ledger, harness, config, links }));
411
+ items.push(
412
+ await itemOf(projectDir, c, { verified, shelved, live, ledger, harness, config, links }),
413
+ );
404
414
  inRunOrder(items);
405
415
  // When the wait began: the time of the commit `since` names (Board-PRD §13).
406
416
  const times = commitTimes(
@@ -454,6 +464,8 @@ export async function board(projectDir) {
454
464
  chat: config.chat,
455
465
  // The review passes of the plan and the code (Operator-Tasks-Plan t2): the rows that hold.
456
466
  review: config.review,
467
+ // Who makes a pass its row cannot make (Fallback-Fidelity-Plan d2): the rules, as data.
468
+ review_fallback: REVIEW_FALLBACK,
457
469
  // How the game is played: the project's targets and the running player; null when not set up.
458
470
  play: playFacts(projectDir, config),
459
471
  phase: await phaseOf(projectDir),
package/lib/config-set.js CHANGED
@@ -331,7 +331,7 @@ function defaultOf(s, aif) {
331
331
  if (head === 'review') return passesText(REVIEW_DEFAULTS[sub]);
332
332
  if (sub) return null;
333
333
 
334
- return head === 'run_mode' ? 'worktree' : (DEFAULT_CONFIG[head] ?? null);
334
+ return head === 'run_mode' ? 'main' : (DEFAULT_CONFIG[head] ?? null);
335
335
  }
336
336
 
337
337
  /**
package/lib/domain.js CHANGED
@@ -261,7 +261,12 @@ const ITEM_SPECS = {
261
261
  kind: 'choice',
262
262
  required: true,
263
263
  options: [
264
- { value: 'default', label: "default: the project's run_mode" },
264
+ {
265
+ value: 'default',
266
+ label:
267
+ 'default: where its kept session ran, else its live worktree copy, ' +
268
+ "else the project's run_mode",
269
+ },
265
270
  ...RUN_MODES.map((m) => ({ value: m, label: m, help: RUN_MODE_HELP[m] })),
266
271
  ],
267
272
  },
package/lib/gcf-paths.js CHANGED
@@ -46,9 +46,11 @@ export function gcfRoot(projectDir = process.cwd()) {
46
46
  // How a harness run drives an item (Methodology §7): `worktree` — each in its own copy, several
47
47
  // at once; `main` — one at a time in the project's own folder, for an agent that works through
48
48
  // a running editor bound to that folder. The project chooses; the framework knows no engine.
49
+ // `main` unless set (Fallback-Fidelity-Plan d1); a card whose copy lives stays in its worktree
50
+ // (integrate.js `cardRunMode`).
49
51
  export const RUN_MODES = ['worktree', 'main'];
50
52
 
51
- function runModeOf(v = 'worktree') {
53
+ function runModeOf(v = 'main') {
52
54
  if (!RUN_MODES.includes(v))
53
55
  throw new Error(`gcf/config.yml: run_mode must be ${RUN_MODES.join(' | ')}, got ${v}`);
54
56
 
@@ -115,16 +117,42 @@ function gatesOf(v = {}) {
115
117
  export const REVIEW_AGENTS = ['claude', 'codex'];
116
118
  export const REVIEW_DEFAULTS = {
117
119
  plan: [
118
- { agent: 'claude', model: 'opus', effort: 'high' },
119
- { agent: 'claude', model: 'opus', effort: 'high' },
120
120
  { agent: 'codex', model: 'astra', effort: 'medium' },
121
+ { agent: 'claude', model: 'fable', effort: 'medium' },
122
+ { agent: 'claude', model: 'fable', effort: 'medium' },
121
123
  ],
122
124
  code: [
123
- { agent: 'claude', model: 'opus', effort: 'high' },
125
+ { agent: 'codex', model: 'sol', effort: 'high' },
124
126
  { agent: 'claude', model: 'opus', effort: 'high' },
125
127
  ],
126
128
  };
127
129
 
130
+ // Who makes a pass its row cannot make (Fallback-Fidelity-Plan d2): the first rule that matches
131
+ // the row (`model` null: any) gives its stand-ins in order; no rule, none. The board reads it.
132
+ const FABLE_MEDIUM = { agent: 'claude', model: 'fable', effort: 'medium' };
133
+ const OPUS_HIGH = { agent: 'claude', model: 'opus', effort: 'high' };
134
+ export const REVIEW_FALLBACK = [
135
+ { agent: 'codex', model: null, effort: 'medium', rows: [FABLE_MEDIUM, OPUS_HIGH] },
136
+ { agent: 'codex', model: null, effort: 'high', rows: [OPUS_HIGH] },
137
+ { agent: 'claude', model: 'fable', effort: 'medium', rows: [OPUS_HIGH] },
138
+ ];
139
+
140
+ /** A Codex model as its family: the slug `gpt-6-astra` is `astra` (gcf-session `familyOf`). */
141
+ export const modelFamily = (model) =>
142
+ /^[a-z]+-\d+(?:\.\d+)*-([a-z]+)$/.exec(String(model))?.[1] ?? String(model);
143
+
144
+ /** The stand-ins of a review row `{agent, model, effort}`, in order; none: `[]`. */
145
+ export function fallbackOf(row) {
146
+ const rule = REVIEW_FALLBACK.find(
147
+ (r) =>
148
+ r.agent === row?.agent &&
149
+ r.effort === row.effort &&
150
+ (r.model === null || r.model === modelFamily(row.model)),
151
+ );
152
+
153
+ return rule ? rule.rows.map((r) => ({ ...r })) : [];
154
+ }
155
+
128
156
  /** A review row's refusal, if any: three plain words, the agent one GCF runs. */
129
157
  export function reviewRowProblem(r) {
130
158
  if (typeof r !== 'object' || r === null || Array.isArray(r))
package/lib/integrate.js CHANGED
@@ -3,7 +3,7 @@
3
3
  // not in memory. `integrate` merges such a branch into main and records the item's move there,
4
4
  // under the main lock; without an id it picks up every verified branch a dead run left behind.
5
5
  import { readFile, writeFile } from 'node:fs/promises';
6
- import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
6
+ import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
7
7
  import { spawnSync } from 'node:child_process';
8
8
  import path from 'node:path';
9
9
  import { buildLedger } from './ledger.js';
@@ -208,6 +208,63 @@ export function verifiedBranches(projectDir) {
208
208
  .filter((id) => isVerified(projectDir, id));
209
209
  }
210
210
 
211
+ /**
212
+ * The ids whose worktree run left a copy that lives (Fallback-Fidelity-Plan d1): its folder, or
213
+ * its branch `work/<id>` whose tip is no main-mode shelf (lib/shelf.js `GCF-Shelved`). None
214
+ * outside a repository.
215
+ */
216
+ export function liveCopies(projectDir) {
217
+ const home = path.dirname(worktreeOf(projectDir, 'x'));
218
+ const ids = new Set();
219
+ try {
220
+ for (const e of readdirSync(home, { withFileTypes: true }))
221
+ if (e.isDirectory() && isValidId(e.name)) ids.add(e.name);
222
+ } catch {
223
+ // No worktree folder: no copy there.
224
+ }
225
+
226
+ const format = '--format=%(refname:short)%00%(trailers:key=GCF-Shelved,valueonly,separator=%x2C)';
227
+ const refs = git(projectDir, ['for-each-ref', format, 'refs/heads/work/'], { check: false });
228
+ for (const l of refs.ok ? refs.out.split('\n') : []) {
229
+ const [ref, shelved = ''] = l.split('\0');
230
+ const id = ref.slice('work/'.length);
231
+ if (ref.startsWith('work/') && !shelved.split(',').some((v) => v.trim() === id)) ids.add(id);
232
+ }
233
+
234
+ return ids;
235
+ }
236
+
237
+ /**
238
+ * The mode a run of the card takes when the run asks none (Fallback-Fidelity-Plan d1): the
239
+ * card's own `run_mode`; the mode its last session ran in, while the harness keeps its record
240
+ * (`.gcf-session/runs/<id>.agent.json` `mode`: a resume goes on where its work is, a fresh
241
+ * start too); `worktree` while a copy of it lives; else the project's. Its work is not left
242
+ * behind when the project's mode or its default changes. `live`: one `liveCopies` read for many.
243
+ * @param {string} projectDir
244
+ * @param {string} id
245
+ * @param {{own?: string | null, project: string, live?: Set<string>}} o
246
+ */
247
+ export function cardRunMode(projectDir, id, { own, project, live }) {
248
+ if (own) return own;
249
+ const saved = savedMode(projectDir, id);
250
+ if (saved) return saved;
251
+
252
+ return (live ?? liveCopies(projectDir)).has(id) ? 'worktree' : project;
253
+ }
254
+
255
+ /** The mode the harness's record of the card's last session names, or null. */
256
+ function savedMode(projectDir, id) {
257
+ if (!isValidId(id)) return null;
258
+ const file = path.join(path.resolve(projectDir), '.gcf-session', 'runs', `${id}.agent.json`);
259
+ try {
260
+ const mode = JSON.parse(readFileSync(file, 'utf8'))?.mode;
261
+
262
+ return mode === 'main' || mode === 'worktree' ? mode : null;
263
+ } catch {
264
+ return null; // No record, or none to read.
265
+ }
266
+ }
267
+
211
268
  /**
212
269
  * Take the worktree and the branch away once the branch is in main (or tagged, for a spike).
213
270
  * Without --force: work left uncommitted in the worktree stops the removal and is named.
package/lib/plan-check.js CHANGED
@@ -10,13 +10,17 @@ import { glossaryAvoids, GLOSSARY_NAME } from 'cnlp-kit/config';
10
10
  import { buildLedger } from './ledger.js';
11
11
  import { buildContext } from './context.js';
12
12
  import { loadDocProfile } from './design.js';
13
- import { readConfig, REVIEW_DEFAULTS } from './gcf-paths.js';
13
+ import { modelFamily, readConfig, REVIEW_DEFAULTS } from './gcf-paths.js';
14
14
 
15
15
  // A review pass (Hold-Plan d12, Operator-Tasks-Plan t2 d3): `- pass K[ (cycle C)]: blocking N,
16
- // polish M[, by <agent:model:effort>]`, one line each in its section: the plan's `## Passes`, the
17
- // code's `## Reviews`, written by `gcf plan pass`. `by` may name a slug with `-` and `.`.
18
- const PASS_LINE =
19
- /^- pass (\d+)(?: \(cycle (\d+)\))?: blocking (\d+), polish (\d+)(?:, by ([\w.:-]+))?$/;
16
+ // polish M[, by <agent:model:effort>[, for <agent:model:effort>]]`, one line each in its section:
17
+ // the plan's `## Passes`, the code's `## Reviews`, written by `gcf plan pass`. `by` may name a
18
+ // slug with `-` and `.`; `for`: the row it stood in for (Fallback-Fidelity-Plan d2).
19
+ const WHO = '[\\w.:-]+';
20
+ const PASS_LINE = new RegExp(
21
+ `^- pass (\\d+)(?: \\(cycle (\\d+)\\))?: blocking (\\d+), polish (\\d+)` +
22
+ `(?:, by (${WHO})(?:, for (${WHO}))?)?$`,
23
+ );
20
24
  const SECTION = { plan: /^## Passes\s*$/, code: /^## Reviews\s*$/ };
21
25
  const HEADING = { plan: '## Passes', code: '## Reviews' };
22
26
  const PASSES_ANY = /^## Passes\s*$/m;
@@ -32,7 +36,7 @@ export function planPasses(text, kind = 'plan') {
32
36
  if (/^## /.test(line)) inside = SECTION[kind].test(line);
33
37
  const m = inside ? PASS_LINE.exec(line.trim()) : null;
34
38
  if (!m) continue;
35
- const by = m[5] ? { by: m[5] } : {};
39
+ const by = m[5] ? { by: m[5], ...(m[6] ? { for: m[6] } : {}) } : {};
36
40
  out.push({ pass: +m[1], cycle: +(m[2] ?? 0), blocking: +m[3], polish: +m[4], ...by });
37
41
  }
38
42
 
@@ -180,13 +184,15 @@ export async function planCheck(projectDir, id) {
180
184
  /**
181
185
  * `gcf plan pass` (Hold-Plan d12, t2 d3): record pass K of the current cycle in the plan's
182
186
  * section of `kind` (`## Passes`, the code's `## Reviews`), K the next number, and answer the
183
- * verdict on the cycle's passes so far.
187
+ * verdict on the cycle's passes so far. `for`: the row the pass was asked of, written only when
188
+ * `by` is someone else (self or a stand-in, Fallback-Fidelity-Plan d2).
184
189
  * @param {string} projectDir
185
190
  * @param {string} id
186
- * @param {{blocking: number, polish: number, by?: string, kind?: string}} pass
191
+ * @param {{blocking: number, polish: number, by?: string, for?: string, kind?: string}} pass
187
192
  */
188
- export async function recordPass(projectDir, id, { blocking, polish, by, kind = 'plan' }) {
189
- passArgs(blocking, polish, by);
193
+ export async function recordPass(projectDir, id, pass) {
194
+ const { blocking, polish, by, kind = 'plan' } = pass;
195
+ passArgs(blocking, polish, by, pass.for);
190
196
  if (!KINDS.includes(kind)) throw new Error(`--kind is ${KINDS.join(' | ')}, got ${kind}`);
191
197
  const item = (await buildLedger(projectDir)).item(id);
192
198
  if (!item) throw new Error(`${id} is not a work item of gcf/work/`);
@@ -197,7 +203,7 @@ export async function recordPass(projectDir, id, { blocking, polish, by, kind =
197
203
  const cycle = Number(item.data.plan_cycle ?? 0);
198
204
  const k = planPasses(text, kind).filter((x) => x.cycle === cycle).length + 1;
199
205
  const tag = cycle ? ` (cycle ${cycle})` : '';
200
- const line = `- pass ${k}${tag}: blocking ${blocking}, polish ${polish}${by ? `, by ${by}` : ''}`;
206
+ const line = `- pass ${k}${tag}: blocking ${blocking}, polish ${polish}${whoOf(by, pass.for)}`;
201
207
  writeFileSync(file, withPass(text, line, kind));
202
208
  const r = await planCheck(projectDir, id);
203
209
  const now = kind === 'plan' ? { passes: r.passes, verdict: '' } : r.review;
@@ -213,12 +219,28 @@ export async function recordPass(projectDir, id, { blocking, polish, by, kind =
213
219
  return { id, kind, pass: k, cycle, verdict, passes: now.passes.map((x) => x.blocking) };
214
220
  }
215
221
 
222
+ /** A row as one: its Codex slug read as its family. */
223
+ const rowKey = (s) =>
224
+ s
225
+ .split(':')
226
+ .map((x, n) => (n === 1 ? modelFamily(x) : x))
227
+ .join(':');
228
+
229
+ /** A pass line's `, by …[, for …]`: `for` only when `by` is not that row. */
230
+ function whoOf(by, row) {
231
+ if (!by) return '';
232
+
233
+ return row && rowKey(by) !== rowKey(row) ? `, by ${by}, for ${row}` : `, by ${by}`;
234
+ }
235
+
216
236
  /** The refusal of a pass's counts and reviewer, if any. */
217
- function passArgs(blocking, polish, by) {
237
+ function passArgs(blocking, polish, by, row) {
218
238
  for (const [k, v] of Object.entries({ blocking, polish }))
219
239
  if (!Number.isInteger(v) || v < 0) throw new Error(`--${k} is a count of findings, 0 or more`);
220
240
  if (by !== undefined && !/^[\w.-]+(:[\w.-]+){0,2}$/.test(by))
221
241
  throw new Error('--by is the reviewer: agent:model:effort, or one word');
242
+ if (row !== undefined && (by === undefined || !/^[\w.-]+:[\w.-]+:[\w.-]+$/.test(row)))
243
+ throw new Error('--for is the row of the pass, agent:model:effort, beside --by');
222
244
  }
223
245
 
224
246
  /** The plan with `line` at the end of its section of `kind`, the section added when none. */
package/lib/play.js CHANGED
@@ -894,8 +894,9 @@ const headHolds = (dir, at) => codeTree(dir, 'HEAD') === codeTree(dir, at);
894
894
  * between a run's cards (docs/Handoff-Plan.md t19).
895
895
  */
896
896
  async function freeOfCheckout(dir, id, item) {
897
- const mode =
898
- item?.data.run_mode ?? (await readConfig(path.join(dir, 'gcf'))).run_mode ?? 'worktree';
897
+ const { cardRunMode } = await import('./integrate.js');
898
+ const project = (await readConfig(path.join(dir, 'gcf'))).run_mode;
899
+ const mode = cardRunMode(dir, id, { own: item?.data.run_mode, project });
899
900
  const at = mode === 'worktree' ? cardCode(dir, id, item) : null;
900
901
 
901
902
  return at !== null && !headHolds(dir, at);
package/lib/review.js CHANGED
@@ -7,7 +7,7 @@ import { mkdirSync, writeFileSync } from 'node:fs';
7
7
  import path from 'node:path';
8
8
  import { cutOf, globTest } from './changes.js';
9
9
  import { onWorkBranch } from './commit-move.js';
10
- import { gcfRoot, readConfig } from './gcf-paths.js';
10
+ import { fallbackOf, gcfRoot, readConfig } from './gcf-paths.js';
11
11
  import { buildLedger } from './ledger.js';
12
12
  import { KINDS, stallOf } from './plan-check.js';
13
13
  import { codeTree, NOT_CODE } from './verify-stamp.js';
@@ -22,8 +22,8 @@ const out = (dir, args) => {
22
22
  };
23
23
 
24
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.
25
+ * Row k of the review of `kind` for item `id`: `{row: {agent, model, effort} | null, by, fallback,
26
+ * rows, more, accepted}`; with `diff` (the code's), the diff file the reviewer reads.
27
27
  * @param {string} projectDir
28
28
  * @param {string} id
29
29
  * @param {{kind: string, pass: number, diff?: boolean}} o
@@ -45,6 +45,8 @@ export async function reviewRow(projectDir, id, { kind, pass, diff = false }) {
45
45
  more: Number(stall.more ?? 0),
46
46
  accepted: Boolean(stall.accepted),
47
47
  by: byOf(row),
48
+ // Who makes the pass when its row cannot, in order (Fallback-Fidelity-Plan d2).
49
+ fallback: fallbackOf(row),
48
50
  ...(withDiff
49
51
  ? { diff: reviewDiff(projectDir, id, { base: stall.base, noDiff: config.no_diff }) }
50
52
  : {}),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-aif-ext",
3
- "version": "0.31.0",
3
+ "version": "0.32.0",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -19,7 +19,8 @@ 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
- - `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`
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>`
23
24
  - a `stalled` verdict: `ai-factory gcf review stall <id> --kind plan|code --passes <counts>` blocks the card
24
25
  - `gcf review more` and `gcf review accept` answer a stall, and they are the human's
25
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`
@@ -27,16 +27,21 @@ auto_compact_pct: 0
27
27
  # The review passes of a plan and of the code before its commit (Operator-Tasks-Plan t2): row k
28
28
  # makes pass k (agent claude or codex; a Claude model alias, a Codex family or slug; an effort);
29
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
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
31
33
  # (ai-factory gcf config set review.plan --value "claude:opus:high, codex:astra:medium"):
32
34
  # review:
33
35
  # plan:
34
- # - {agent: claude, model: opus, effort: high}
35
- # - {agent: claude, model: opus, effort: high}
36
36
  # - {agent: codex, model: astra, effort: medium}
37
+ # - {agent: claude, model: fable, effort: medium}
38
+ # - {agent: claude, model: fable, effort: medium}
37
39
  # code:
40
+ # - {agent: codex, model: sol, effort: high}
38
41
  # - {agent: claude, model: opus, effort: high}
39
- # - {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
40
45
  # Lessons (Methodology §5.2.2): at the end of each session on an item its agent says what got in
41
46
  # its way, into the inbox. `ai-factory gcf lessons prompt <id>` prints the questions. Uncomment to
42
47
  # turn them off, to ask what the project's template should learn, or to add questions: