gcf-aif-ext 0.24.0 → 0.26.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
@@ -24,3 +24,15 @@ terms:
24
24
 
25
25
  - term: pillar
26
26
  means: a quality the game must keep, in `gcf/PILLARS.md`, changed only on the human's word
27
+
28
+ - term: hold
29
+ means: the human's stop of an item or the project that keeps its work: the session hands over at its next call and the item waits, ready
30
+ avoid: freeze
31
+
32
+ - term: quota reserve
33
+ means: the share of each usage window the queue and the autopilot leave to the human (`quota_reserve_pct`)
34
+ avoid: quota buffer
35
+
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
38
+ avoid: non-convergence
package/README.md CHANGED
@@ -337,7 +337,8 @@ The run layer of the methodology. Update both extensions together — `gcf-harne
337
337
  - `gcf verify <id>` — the auto-DoD in code: the commit gate's checks, the item's `live:` delta against `LIVE.md`, then `dod.build` and `dod.test`. Fill both in `gcf/config.yml`; an empty one fails, `none` says the project has no such step.
338
338
  - `gcf phase` and `gcf phase next [--reason]` — the project phase (prototype → vertical-slice → alpha → beta → release → live), kept as `phase:` in the `LIVE.md` frontmatter, with exit criteria checked in code. `item new` and `take` refuse a type the phase does not take. **A project with no phase yet is in prototype, and a prototype takes no `asset` item**: move the phase on (`gcf phase next --reason "…"`) if your game is past it. A `phases:` list in `config.yml` replaces the set.
339
339
  - A release item carries `version:` and `channel:` (`item new <id> --type release --release 1.0.0 --channel steam`); its end writes the `release:` block of `LIVE.md`. `item new --milestone <name>` tags an item with a milestone of `game.md` (any slug without `game.md`); `design check` reports (does not block) an item whose milestone `game.md` does not list, and the board read gives the list as `design.milestones`.
340
- - `gcf playtest session [--build]` — the build of main and a checklist per item: what to check, how to get there, what to feel.
340
+ - `gcf playtest session` — where main stands and a checklist per item: its build, what to check, how to get there, what to feel.
341
+ - `gcf playtest build <id> [--from <worktree>] [--fresh]`, `build --main [--fresh]`, `start <id>|--main --target <name>`, `stop`, `status`, `setup` — one build per code under `.gcf-session/snaps/<key>/`, held by a card's link `.gcf-session/builds/<id>.json` or the checkout's `snaps/main.link.json`, and its player, from `play:` in `gcf/config.yml`; a verdict stops the card's player and removes the build once no other card holds it. `setup` refuses an output git does not ignore. The deny group `run-play` keeps a run's agent from building; a chat thread may build on the human's ask.
341
342
  - `gcf worktree <id>`, `gcf verify <id> --mark`, `gcf integrate [<id>…]` — an item in its own worktree, the `GCF-Verified` trailer, the merge into main and the item's move. Every committed move now holds `.gcf-session/main.lock`.
342
343
  - `gcf board [--json]` — everything a board shows in one read.
343
344
 
@@ -400,7 +401,7 @@ Removal leaves `gcf/` and `cnlp.config.json` in place. It also leaves the pre-co
400
401
 
401
402
  - work items — `take <ids...> [--feature <id>]`, `item new [id] --title <text> --type <type>`, `submit`, `close`, `verdict <id> keep|tune|kill`, `decide <id> go|no|wontfix|known|close|continue|kill`, `block`, `unblock`, `drop`, `done`, `where`, `item amend <id> [--text <blocks>] [--add <lines>] [--title <text>] [--from <in-id>] [--dry-run --json]`
402
403
  - inbox and snapshot — `inbox [add <text> [--category <c>] [--detail <word>] | add --text-file <path|-> | category <in-id> | later <in-id> [--off] | categories | drop <in-id> | migrate]`, `live`, `live check`
403
- - runs and play — `context`, `plan check <id>`, `verify <id>`, `playtest`, `playtest session [--build]`, `audit`
404
+ - runs and play — `context`, `plan check <id>`, `verify <id>`, `playtest`, `playtest session`, `playtest status`, `audit`
404
405
  - project phase and board — `phase`, `phase next [--reason]`, `board [--json]` (everything a board shows, in one read)
405
406
  - branches — `worktree <id>`, `verify <id> --mark`, `integrate [<id>...]`: a run in its own worktree, the `GCF-Verified` trailer, the merge into main and the move; every committed move holds `.gcf-session/main.lock`
406
407
  - design and sources — `design check`, `design export`, `design import`, `design part`, `design save`, `design discard`, `design commit`, `design migrate`, `anchor`, `section`, `quotes`, `lint`
@@ -415,6 +416,8 @@ Every move of an item makes one commit `gcf(<move>): <id>` with every file it to
415
416
  **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`.
416
417
 
417
418
 
419
+ 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>`.
420
+
418
421
  ## Docs
419
422
 
420
423
  Full documentation lives in the [repository](https://github.com/VirtualMaestro/GCF): the [Usage Guide](https://github.com/VirtualMaestro/GCF/blob/main/docs/Usage-Guide.md) (RU) for day-to-day work, and [GCF-PRD](https://github.com/VirtualMaestro/GCF/blob/main/docs/GCF-PRD.md) for the spec — principles, data model, lifecycle, enforcement.
package/commands/gcf.js CHANGED
@@ -367,25 +367,24 @@ function registerAudit(gcf) {
367
367
  });
368
368
  }
369
369
 
370
- /** How the session's build went: built, no step, failed, or left to the human. */
371
- function buildText(b) {
372
- if (!b) return 'build it from this commit';
373
- if (!b.ok) return b.problems.join('; ');
370
+ /** An item's build on the sheet: its commit, what goes on, why it failed. */
371
+ function buildLine(b) {
372
+ if (!b) return [];
373
+ if (b.building) return [' build: being built'];
374
+ if (b.ok) return [` build: ${b.commit ?? 'no commit'}, ${b.source}, ${b.built_at}`];
374
375
 
375
- return b.skipped ? 'no build step (dod.build: none)' : 'built with dod.build';
376
+ return [` build failed: ${b.problem.split('\n')[0]}`];
376
377
  }
377
378
 
378
- /** The sheet's head: what was built, and why it may not be what main holds. */
379
+ /** The sheet's head: where main stands, and why the checkout may not be main. */
379
380
  function sessionHead(s) {
380
- const build = buildText(s.build);
381
-
382
381
  return [
383
- s.commit ? `build: ${s.branch} @ ${s.commit} — ${build}` : 'build: no commit to build yet',
382
+ s.commit ? `main: ${s.branch} @ ${s.commit}` : 'main: no commit yet',
384
383
  // Main by the remote's default when known, else any branch but detached or a worktree's.
385
384
  ...(s.branch === 'HEAD' || s.branch?.startsWith('work/') || (s.main && s.branch !== s.main)
386
- ? [`warning: ${s.branch} is not ${s.main ?? 'main'} — the session plays main`]
385
+ ? [`warning: ${s.branch} is not ${s.main ?? 'main'} — a click builds this checkout`]
387
386
  : []),
388
- ...(s.dirty ? ['warning: uncommitted changes — the build is not the commit'] : []),
387
+ ...(s.dirty ? ['warning: uncommitted changes — a click builds them too'] : []),
389
388
  ];
390
389
  }
391
390
 
@@ -425,7 +424,7 @@ export function sessionText(s) {
425
424
  '',
426
425
  `[ ] ${c.id} (${c.status}) [${c.system.join(',')}] ${c.title ?? c.intent ?? ''}`,
427
426
  );
428
- lines.push(` check: ${c.question}`);
427
+ lines.push(...buildLine(c.build), ` check: ${c.question}`);
429
428
  if (c.play_on?.length) lines.push(` play on: ${c.play_on.join('; ')}`);
430
429
  for (const r of c.reach) lines.push(` try: ${r}`);
431
430
  for (const f of c.feel) lines.push(` feel: ${f}`);
@@ -458,21 +457,128 @@ function registerPlaytest(gcf) {
458
457
  });
459
458
  playtest
460
459
  .command('session')
461
- .description('A playtest session: the build of main and the checklist, built from the items')
462
- .option('--build', 'run dod.build first')
460
+ .description('A playtest session: where main stands and the checklist, from the items')
463
461
  .option('--json', 'machine output')
464
462
  .action(async (o) => {
465
- const r = await (
466
- await lib('playtest-list')
467
- ).playtestSession(process.cwd(), { build: Boolean(o.build) });
463
+ const r = await (await lib('playtest-list')).playtestSession(process.cwd());
468
464
  // Commander gives a flag both levels define to the parent: `playtest session --json`.
469
465
  out(o.json || playtest.opts().json, r, sessionText);
470
- if (r.build && !r.build.ok) process.exitCode = 1;
466
+ });
467
+ registerPlay(playtest);
468
+ }
469
+
470
+ /** Whether a play command means the checkout: exactly one of a card's id and `--main`. */
471
+ function oneOf(id, main) {
472
+ if (Boolean(id) === Boolean(main)) throw new Error('name a card or --main, not both or neither');
473
+
474
+ return Boolean(main);
475
+ }
476
+
477
+ /** What `playtest start` says: the words to open it by, and what is left running. */
478
+ const startLine = (r) =>
479
+ r.state === 'running'
480
+ ? `playing ${r.id ?? 'main'} on ${r.target} (pid ${r.pid}): ${r.open}`
481
+ : `launched ${r.id ?? 'main'} on ${r.target}: ${r.open}`;
482
+
483
+ /** The player's line and the targets of `playtest status`. */
484
+ function statusText(s) {
485
+ if (!s) return 'how to play is not set up: ai-factory gcf playtest setup';
486
+ if (s.problem) return s.problem;
487
+
488
+ return [
489
+ s.running
490
+ ? `playing ${s.running.id ?? 'main'} on ${s.running.target}: ${s.running.open}`
491
+ : 'no player is running',
492
+ `targets: ${s.targets.map((t) => t.name).join(', ') || 'none'}`,
493
+ ].join('\n');
494
+ }
495
+
496
+ /** A card's build to play, or the checkout's (docs/Play-Setup-Plan.md). */
497
+ function registerPlayBuild(playtest, jsonOf) {
498
+ playtest
499
+ .command('build [id]')
500
+ .description("Build a card's game, or the checkout's (--main); one snapshot per code")
501
+ .option('--main', 'the checkout with its uncommitted edits, not a card')
502
+ .option('--fresh', 'build even when a snapshot of this code is there, and replace it')
503
+ .option('--from <worktree>', "the card's worktree, for a run whose code is not in main yet")
504
+ .option('--json', 'machine output')
505
+ .action(async (id, o) => {
506
+ const play = await lib('play');
507
+ const fresh = Boolean(o.fresh);
508
+ const main = oneOf(id, o.main);
509
+ if (main && o.from) throw new Error("--from names a card's worktree: not with --main");
510
+ const r = main
511
+ ? await play.buildMain(process.cwd(), { fresh })
512
+ : await play.buildItem(process.cwd(), id, { from: o.from ?? null, fresh });
513
+ const who = id ?? 'main';
514
+ out(jsonOf(o), r, (b) =>
515
+ b.ok
516
+ ? `built ${who} at ${b.commit?.slice(0, 7) ?? 'no commit'}, ${b.size} bytes` +
517
+ (b.dirtied.length ? `\nthe build changed: ${b.dirtied.join(', ')}` : '')
518
+ : `build of ${who} failed: ${b.problem}`,
519
+ );
520
+ if (!r.ok) process.exitCode = 1;
521
+ });
522
+ playtest
523
+ .command('start [id]')
524
+ .description("Start a card's snapshot, or the checkout's (--main), on a target: one player")
525
+ .option('--main', "the checkout's snapshot, not a card's")
526
+ .requiredOption('--target <name>', 'a target of play.targets')
527
+ .option('--json', 'machine output')
528
+ .action(async (id, o) => {
529
+ const main = oneOf(id, o.main);
530
+ const r = await (await lib('play')).startPlay(process.cwd(), main ? null : id, o.target);
531
+ out(jsonOf(o), r, startLine);
532
+ });
533
+ }
534
+
535
+ /** The player and the project's play: setup (docs/Play-Plan.md). */
536
+ function registerPlay(playtest) {
537
+ const jsonOf = (o) => o.json || playtest.opts().json;
538
+ registerPlayBuild(playtest, jsonOf);
539
+ playtest
540
+ .command('stop')
541
+ .description('Stop the running player')
542
+ .option('--json', 'machine output')
543
+ .action(async (o) => {
544
+ const r = await (await lib('play')).stopPlayLocked(process.cwd());
545
+ out(jsonOf(o), { stopped: r }, () =>
546
+ r ? `stopped ${r.id ?? 'main'}` : 'no player is running',
547
+ );
548
+ });
549
+ playtest
550
+ .command('status')
551
+ .description('The targets and the running player; what no card needs is cleared on the way')
552
+ .option('--json', 'machine output')
553
+ .action(async (o) => {
554
+ out(jsonOf(o), await (await lib('play')).playStatus(process.cwd()), statusText);
555
+ });
556
+ playtest
557
+ .command('setup')
558
+ .description("How the project builds and starts its game (play: in config.yml; the operator's)")
559
+ .option('--build <cmd>', 'the command that builds the game')
560
+ .option('--output <folder>', 'where it builds to: inside the project, ignored by git')
561
+ .option('--target <name>', 'the target the next three options set')
562
+ .option('--start <cmd>', 'starts the game: {dir} the snapshot, {port} a free port, {lan}')
563
+ .option('--open <text>', 'what to open: a URL or words, with the same placeholders')
564
+ .option('--stop <cmd>', 'runs after the player stops')
565
+ .option('--remove-target <name>', 'take a target away')
566
+ .option('--no-commit', 'leave the change uncommitted')
567
+ .action(async (o) => {
568
+ await operatorOnly('playtest setup');
569
+ const r = await (await lib('play')).setupPlay(process.cwd(), { ...o, open: o.open });
570
+ console.log(`play: ${r.play.build} into ${r.play.output}${shortHash(r.hash)}`);
471
571
  });
472
572
  }
473
573
 
474
574
  const shortHash = (h) => (h ? ` (${h.slice(0, 7)})` : '');
475
575
  const removalLine = (r) => (r.removal ? `\nremoval item: gcf/work/${r.removal}.md` : '');
576
+ /** What a verdict or a drop could not delete of the card's build. */
577
+ const leftLine = (r) =>
578
+ [r.build_left ?? []]
579
+ .flat()
580
+ .map((l) => `\n${l}`)
581
+ .join('');
476
582
 
477
583
  /** `--remove` / `--no-remove` / neither (the move's default) for a move that may bury code. */
478
584
  const removeOptions = (cmd) =>
@@ -516,7 +622,7 @@ function registerVerdict(gcf) {
516
622
  playedOn: opts.playedOn,
517
623
  commit: opts.commit,
518
624
  });
519
- console.log(`keep ${r.milestone} → ${r.ids.join(', ')}${shortHash(r.hash)}`);
625
+ console.log(`keep ${r.milestone} → ${r.ids.join(', ')}${shortHash(r.hash)}${leftLine(r)}`);
520
626
 
521
627
  return;
522
628
  }
@@ -531,7 +637,8 @@ function registerVerdict(gcf) {
531
637
  });
532
638
  console.log(
533
639
  `${res.verdict} ${res.id} → ${res.systems.join(',')}${shortHash(res.hash)}` +
534
- removalLine(res),
640
+ removalLine(res) +
641
+ leftLine(res),
535
642
  );
536
643
  });
537
644
  }
@@ -1019,7 +1126,7 @@ function registerMoves(gcf) {
1019
1126
  : await (
1020
1127
  await ops()
1021
1128
  ).dropUnit(process.cwd(), id, { reason: o.reason, tags, commit: o.commit });
1022
- console.log(`dropped ${r.id}${shortHash(r.hash)}${removalLine(r)}`);
1129
+ console.log(`dropped ${r.id}${shortHash(r.hash)}${removalLine(r)}${leftLine(r)}`);
1023
1130
  });
1024
1131
  }
1025
1132
 
@@ -1702,9 +1809,9 @@ function registerLive(gcf) {
1702
1809
  }
1703
1810
 
1704
1811
  function registerPlan(gcf) {
1705
- gcf
1706
- .command('plan')
1707
- .description('The plan of a work item')
1812
+ const plan = gcf.command('plan').description('The plan of a work item');
1813
+ registerPlanPasses(plan);
1814
+ plan
1708
1815
  .command('check <id>')
1709
1816
  .description(
1710
1817
  'Deterministic plan check: it exists, has task checkboxes, readset in budget; ' +
@@ -1733,6 +1840,77 @@ function registerPlan(gcf) {
1733
1840
  });
1734
1841
  }
1735
1842
 
1843
+ /**
1844
+ * The improve passes of a plan and their stop (Hold-Plan d12, d16): a pass is recorded in the
1845
+ * plan, the verdict decides; a stall blocks the card for the operator's more or accept.
1846
+ */
1847
+ function registerPlanPasses(plan) {
1848
+ plan
1849
+ .command('pass <id>')
1850
+ .description(
1851
+ "Record an improve pass in the plan's ## Passes: its blocking and polish findings; " +
1852
+ 'answer the verdict: continue, converged or stalled',
1853
+ )
1854
+ .requiredOption('--blocking <n>', 'findings that block the plan')
1855
+ .requiredOption('--polish <n>', 'findings that only polish it')
1856
+ .option('--by <reviewer>', 'the pass was made by another reviewer (codex)')
1857
+ .option('--json', 'machine output')
1858
+ .action(async (id, o) => {
1859
+ await touchSession(id);
1860
+ const r = await (
1861
+ await lib('plan-check')
1862
+ ).recordPass(process.cwd(), id, {
1863
+ blocking: Number(o.blocking),
1864
+ polish: Number(o.polish),
1865
+ by: o.by,
1866
+ });
1867
+ out(o.json, r, (x) => `pass ${x.pass}: ${x.verdict} (${x.passes.join(', ')})`);
1868
+ });
1869
+ plan
1870
+ .command('stall <id>')
1871
+ .description(
1872
+ 'Planning does not converge: block the card with its passes (commit gcf(plan_stall))',
1873
+ )
1874
+ .requiredOption('--passes <list>', 'the blocking findings of each pass, comma-separated')
1875
+ .option('--reason <text>', 'what keeps it from converging')
1876
+ .action(async (id, o) => {
1877
+ const passes = splitList(o.passes).map(Number);
1878
+ const r = await (
1879
+ await lib('work-ops')
1880
+ ).stallItem(process.cwd(), id, {
1881
+ passes,
1882
+ reason: o.reason,
1883
+ });
1884
+ console.log(`${r.id} → blocked: planning does not converge · ${r.stall.passes.join(', ')}`);
1885
+ });
1886
+ registerStallAnswers(plan);
1887
+ }
1888
+
1889
+ /** The operator's two answers to a planning stall (Hold-Plan d16). */
1890
+ function registerStallAnswers(plan) {
1891
+ plan
1892
+ .command('more <id>')
1893
+ .description("The operator's answer to a stall: N more passes, back to ready")
1894
+ .requiredOption('--passes <n>', 'how many more passes')
1895
+ .action(async (id, o) => {
1896
+ await operatorOnly('plan more');
1897
+ const r = await (
1898
+ await lib('work-ops')
1899
+ ).answerStall(process.cwd(), id, {
1900
+ more: Number(o.passes),
1901
+ });
1902
+ console.log(`${r.id} → ready: ${r.stall.more} more pass(es) past plan_passes`);
1903
+ });
1904
+ plan
1905
+ .command('accept <id>')
1906
+ .description("The operator's answer to a stall: implement the plan as it is, back to ready")
1907
+ .action(async (id) => {
1908
+ await operatorOnly('plan accept');
1909
+ const r = await (await lib('work-ops')).answerStall(process.cwd(), id, { accept: true });
1910
+ console.log(`${r.id} → ready: the plan goes to implementation as it is`);
1911
+ });
1912
+ }
1913
+
1736
1914
  function registerVerify(gcf) {
1737
1915
  gcf
1738
1916
  .command('verify <id>')
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.24.0",
4
+ "version": "0.26.0",
5
5
  "description": "Game Context Framework for AI Factory",
6
6
  "skills": [
7
7
  "skills/gcf-init",
@@ -187,12 +187,16 @@ export const DENY_GROUPS = [
187
187
  'ai-factory gcf verdict*',
188
188
  'ai-factory gcf question answer*',
189
189
  'ai-factory gcf unblock*',
190
+ // The operator's answers to planning that does not converge (Hold-Plan d16).
191
+ 'ai-factory gcf plan more*',
192
+ 'ai-factory gcf plan accept*',
190
193
  'ai-factory gcf item gates*',
191
194
  'ai-factory gcf item amend*',
192
195
  'ai-factory gcf phase next*',
193
196
  'ai-factory gcf pillar*',
194
197
  'ai-factory gcf permissions*',
195
198
  'ai-factory gcf config set*',
199
+ 'ai-factory gcf playtest setup*',
196
200
  'ai-factory gcf hooks-install*',
197
201
  // A human's hand edits under gcf/: their unfinished work, not the agent's to keep or erase.
198
202
  'ai-factory gcf edits commit*',
@@ -205,11 +209,26 @@ export const DENY_GROUPS = [
205
209
  // The autopilot's card session: an agent starts none.
206
210
  'ai-factory gcf-harness card*',
207
211
  'ai-factory gcf-harness stop*',
212
+ // The operator's Hold of an item or the project (Hold-Plan d6): an agent holds nothing.
213
+ 'ai-factory gcf-harness hold*',
208
214
  // The operator's chat input: an agent answering its own question would be no answer.
209
215
  'ai-factory gcf-harness chat*',
210
216
  'ai-factory extension*',
211
217
  ),
212
218
  },
219
+ {
220
+ id: 'run-play',
221
+ label: "a run's agent building or starting the game: the harness builds it at the run's end",
222
+ on: true,
223
+ // A build in a run would take its unfinished work as a card's. The project chat's agent builds
224
+ // on the human's ask (docs/Play-Setup-Plan.md d32): its thread leaves these rules out.
225
+ run_only: true,
226
+ rules: shell(
227
+ 'ai-factory gcf playtest build*',
228
+ 'ai-factory gcf playtest start*',
229
+ 'ai-factory gcf playtest stop*',
230
+ ),
231
+ },
213
232
  {
214
233
  id: 'guards',
215
234
  label:
@@ -225,6 +244,10 @@ export const DENY_GROUPS = [
225
244
  // The project chat's threads: their records, input and settings are the center's.
226
245
  '.gcf-session/chats/**',
227
246
  '.gcf-session/handoff.json',
247
+ // A card's build to play and the record of its player: only `gcf playtest` writes them.
248
+ '.gcf-session/builds/**',
249
+ '.gcf-session/snaps/**',
250
+ '.gcf-session/play.json',
228
251
  ),
229
252
  },
230
253
  {
@@ -334,11 +357,14 @@ export function agentOf(config) {
334
357
  const allowed = rules(agent, 'allow').map(parseRule);
335
358
  const groups = DENY_GROUPS.map((g) => ({ id: g.id, label: g.label, on: chosen[g.id] ?? g.on }));
336
359
  // A group's rule names its group: a refusal in a chat says which group to turn off.
360
+ const own = extra.map(parseRule);
361
+ // A rule the operator also wrote is theirs for every agent: no `run_only` lets a thread past it.
362
+ const runOnly = (g, r) => g.run_only && !own.some((x) => sameRule(x, r));
337
363
  const denied = [
338
364
  ...DENY_GROUPS.filter((g, i) => groups[i].on).flatMap((g) =>
339
- g.rules.map((r) => ({ ...r, group: g.id })),
365
+ g.rules.map((r) => ({ ...r, group: g.id, ...(runOnly(g, r) ? { run_only: true } : {}) })),
340
366
  ),
341
- ...extra.map(parseRule),
367
+ ...own,
342
368
  ].filter((r, i, all) => all.findIndex((x) => sameRule(x, r)) === i);
343
369
 
344
370
  return {
package/lib/board.js CHANGED
@@ -27,6 +27,7 @@ import { designCheck, designUnits } from './design-check.js';
27
27
  import { designState } from './design-parts.js';
28
28
  import { gatePolicy } from './gates.js';
29
29
  import { milestoneState } from './milestone-state.js';
30
+ import { buildOf, linksOf, playFacts } from './play.js';
30
31
 
31
32
  // The version of the JSON below (Methodology §11): a board refuses one it does not know. Bump it
32
33
  // when a field changes meaning or goes away; a new field does not bump it.
@@ -224,6 +225,8 @@ const SCALARS = [
224
225
  'run_mode',
225
226
  'skip_gates',
226
227
  'gate_why',
228
+ // Planning that does not converge (Hold-Plan d16): the blocking counts and the answer.
229
+ 'stall',
227
230
  ];
228
231
 
229
232
  /**
@@ -289,7 +292,9 @@ function runningKind(projectDir, id) {
289
292
  * agent's run to an item that waits for one and has no green verify yet. A feature runs through
290
293
  * its children: the run gate refuses it.
291
294
  */
292
- function offered(c, { running, verified, harness }) {
295
+ function offered(c, { running, verified, harness, building }) {
296
+ // A build of what waits for its verdict: the verdict does not wait for it.
297
+ if (building && c.data.status !== RUNS_FROM) return movesOf(c.data);
293
298
  if (running) return [];
294
299
  const runs = harness && c.data.status === RUNS_FROM && !verified && c.data.type !== 'feature';
295
300
 
@@ -316,7 +321,8 @@ async function attachmentsOf(projectDir, id) {
316
321
  }
317
322
 
318
323
  /** One item of the board. */
319
- async function itemOf(projectDir, c, { verified, shelved, ledger, harness, config }) {
324
+ async function itemOf(projectDir, c, { verified, shelved, ledger, harness, config, links }) {
325
+ const build = buildOf(projectDir, String(c.data.id), c.data.status, links);
320
326
  const id = String(c.data.id);
321
327
  // A trailer counts only while the item waits on main for its integrate.
322
328
  const ready = c.data.status === 'ready' && verified.has(id);
@@ -354,27 +360,31 @@ async function itemOf(projectDir, c, { verified, shelved, ledger, harness, confi
354
360
  ...(shelved.has(id) ? { shelved: shelved.get(id) } : {}),
355
361
  waits_for: waitsOf(c, running, ledger),
356
362
  needs: needsOf(ledger, c.data.depends ?? []),
357
- moves: offered(c, { running, verified: ready, harness }),
363
+ moves: offered(c, {
364
+ running,
365
+ verified: ready,
366
+ harness,
367
+ building: Boolean(build?.building),
368
+ }),
358
369
  file: `gcf/work/${c.name}`,
359
370
  ...(await attachmentsOf(projectDir, id)),
360
371
  log: logOf(projectDir, id),
372
+ // Its build to play (docs/Play-Setup-Plan.md), null while it has none.
373
+ build,
361
374
  // Filled by board() from the inbox.
362
375
  lessons: 0,
363
376
  ...(await progress(projectDir, c)),
364
377
  };
365
378
  }
366
379
 
367
- export async function board(projectDir) {
368
- const root = path.join(path.resolve(projectDir), 'gcf');
369
- const ledger = await buildLedger(projectDir);
380
+ /** The board's items in run order, each with the time its wait began. */
381
+ async function itemsOf(projectDir, { ledger, harness, config }) {
370
382
  const verified = verifiedOf(projectDir);
371
383
  const shelved = shelvedCards(projectDir);
372
- const { extensions, error: extensionsError } = await extensionsOf(projectDir);
373
- const harness = hasHarness(extensions);
374
- const config = await readConfig(root);
384
+ const links = linksOf(projectDir);
375
385
  const items = [];
376
386
  for (const c of ledger.items)
377
- items.push(await itemOf(projectDir, c, { verified, shelved, ledger, harness, config }));
387
+ items.push(await itemOf(projectDir, c, { verified, shelved, ledger, harness, config, links }));
378
388
  inRunOrder(items);
379
389
  // When the wait began: the time of the commit `since` names (Board-PRD §13).
380
390
  const times = commitTimes(
@@ -382,6 +392,17 @@ export async function board(projectDir) {
382
392
  items.map((i) => i.since),
383
393
  );
384
394
  for (const i of items) i.since_at = times.get(i.since) ?? null;
395
+
396
+ return items;
397
+ }
398
+
399
+ export async function board(projectDir) {
400
+ const root = path.join(path.resolve(projectDir), 'gcf');
401
+ const ledger = await buildLedger(projectDir);
402
+ const { extensions, error: extensionsError } = await extensionsOf(projectDir);
403
+ const harness = hasHarness(extensions);
404
+ const config = await readConfig(root);
405
+ const items = await itemsOf(projectDir, { ledger, harness, config });
385
406
  const inbox = await listInbox(root);
386
407
  // Where agents struggle: the lessons in the inbox each item's sessions left. A request or a
387
408
  // finding about the item names it too: it is no lesson.
@@ -415,6 +436,10 @@ export async function board(projectDir) {
415
436
  },
416
437
  // A run's chat with the operator (`chat:` in config.yml): what it asks, how long it waits.
417
438
  chat: config.chat,
439
+ // The plan's outside reviewer (`plan_review:`, Hold-Plan d17): null when not set.
440
+ plan_review: config.plan_review ?? null,
441
+ // How the game is played: the project's targets and the running player; null when not set up.
442
+ play: playFacts(projectDir, config),
418
443
  phase: await phaseOf(projectDir),
419
444
  extensions,
420
445
  extensions_error: extensionsError,
package/lib/config-set.js CHANGED
@@ -106,6 +106,31 @@ export const SETTINGS = [
106
106
  presets: 'effort',
107
107
  label: 'the effort an item or a chat thread without its own runs with (not set: High)',
108
108
  },
109
+ // The plan's outside reviewer (Hold-Plan d17): a read-only audit pass, Claude's when it fails.
110
+ {
111
+ key: 'plan_review.agent',
112
+ kind: 'word',
113
+ label:
114
+ 'the outside reviewer of a plan that keeps finding blocking issues ' +
115
+ '(not set: codex; none: off)',
116
+ },
117
+ {
118
+ key: 'plan_review.model',
119
+ kind: 'word',
120
+ label: 'the model of the plan review (not set: gpt-6-astra)',
121
+ },
122
+ {
123
+ key: 'plan_review.effort',
124
+ kind: 'word',
125
+ label: 'the effort of the plan review (not set: medium)',
126
+ },
127
+ {
128
+ key: 'plan_review.at',
129
+ kind: 'number',
130
+ label:
131
+ 'the improve pass the outside reviewer makes, when the one before found blocking ' +
132
+ 'issues (not set: 3)',
133
+ },
109
134
  {
110
135
  key: 'chat.ask',
111
136
  kind: 'mode',
@@ -224,6 +249,10 @@ const GROUPS = [
224
249
  'agent.model',
225
250
  'agent.effort',
226
251
  'plan_passes',
252
+ 'plan_review.agent',
253
+ 'plan_review.model',
254
+ 'plan_review.effort',
255
+ 'plan_review.at',
227
256
  'dod_attempts',
228
257
  ],
229
258
  ],