gcf-aif-ext 0.24.0 → 0.25.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>]`, `start <id> --target <name>`, `stop`, `status`, `setup` — a card's own build under `.gcf-session/builds/<id>/` and its player, from `play:` in `gcf/config.yml`; a verdict stops the player and removes the build.
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,103 @@ 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
+ /** What `playtest start` says: the words to open it by, and what is left running. */
471
+ const startLine = (r) =>
472
+ r.state === 'running'
473
+ ? `playing ${r.id} on ${r.target} (pid ${r.pid}): ${r.open}`
474
+ : `launched ${r.id} on ${r.target}: ${r.open}`;
475
+
476
+ /** The player's line and the targets of `playtest status`. */
477
+ function statusText(s) {
478
+ if (!s) return 'how to play is not set up: ai-factory gcf playtest setup';
479
+ if (s.problem) return s.problem;
480
+
481
+ return [
482
+ s.running
483
+ ? `playing ${s.running.id} on ${s.running.target}: ${s.running.open}`
484
+ : 'no player is running',
485
+ `targets: ${s.targets.map((t) => t.name).join(', ') || 'none'}`,
486
+ ].join('\n');
487
+ }
488
+
489
+ /** A card's build to play and its player (docs/Play-Plan.md). */
490
+ function registerPlay(playtest) {
491
+ const jsonOf = (o) => o.json || playtest.opts().json;
492
+ playtest
493
+ .command('build <id>')
494
+ .description("Build the game into the card's own snapshot; the old one stays if this fails")
495
+ .option('--from <worktree>', "the card's worktree, for a run whose code is not in main yet")
496
+ .option('--json', 'machine output')
497
+ .action(async (id, o) => {
498
+ const r = await (await lib('play')).buildItem(process.cwd(), id, { from: o.from ?? null });
499
+ out(jsonOf(o), r, (b) =>
500
+ b.ok
501
+ ? `built ${id} at ${b.commit ?? 'no commit'}, ${b.size} bytes` +
502
+ (b.dirtied.length ? `\nthe build changed: ${b.dirtied.join(', ')}` : '')
503
+ : `build of ${id} failed: ${b.problem}`,
504
+ );
505
+ if (!r.ok) process.exitCode = 1;
506
+ });
507
+ playtest
508
+ .command('start <id>')
509
+ .description("Start the card's snapshot on a target: one player per project")
510
+ .requiredOption('--target <name>', 'a target of play.targets')
511
+ .option('--json', 'machine output')
512
+ .action(async (id, o) => {
513
+ const r = await (await lib('play')).startPlay(process.cwd(), id, o.target);
514
+ out(jsonOf(o), r, startLine);
515
+ });
516
+ playtest
517
+ .command('stop')
518
+ .description('Stop the running player')
519
+ .option('--json', 'machine output')
520
+ .action(async (o) => {
521
+ const r = await (await lib('play')).stopPlayLocked(process.cwd());
522
+ out(jsonOf(o), { stopped: r }, () => (r ? `stopped ${r.id}` : 'no player is running'));
523
+ });
524
+ playtest
525
+ .command('status')
526
+ .description('The targets and the running player; what no card needs is cleared on the way')
527
+ .option('--json', 'machine output')
528
+ .action(async (o) => {
529
+ out(jsonOf(o), await (await lib('play')).playStatus(process.cwd()), statusText);
530
+ });
531
+ playtest
532
+ .command('setup')
533
+ .description("How the project builds and starts its game (play: in config.yml; the operator's)")
534
+ .option('--build <cmd>', 'the command that builds the game')
535
+ .option('--output <folder>', 'where it builds to: inside the project, ignored by git')
536
+ .option('--target <name>', 'the target the next three options set')
537
+ .option('--start <cmd>', 'starts the game: {dir} the snapshot, {port} a free port, {lan}')
538
+ .option('--open <text>', 'what to open: a URL or words, with the same placeholders')
539
+ .option('--stop <cmd>', 'runs after the player stops')
540
+ .option('--remove-target <name>', 'take a target away')
541
+ .option('--no-commit', 'leave the change uncommitted')
542
+ .action(async (o) => {
543
+ await operatorOnly('playtest setup');
544
+ const r = await (await lib('play')).setupPlay(process.cwd(), { ...o, open: o.open });
545
+ console.log(`play: ${r.play.build} into ${r.play.output}${shortHash(r.hash)}`);
471
546
  });
472
547
  }
473
548
 
474
549
  const shortHash = (h) => (h ? ` (${h.slice(0, 7)})` : '');
475
550
  const removalLine = (r) => (r.removal ? `\nremoval item: gcf/work/${r.removal}.md` : '');
551
+ /** What a verdict or a drop could not delete of the card's build. */
552
+ const leftLine = (r) =>
553
+ [r.build_left ?? []]
554
+ .flat()
555
+ .map((l) => `\n${l}`)
556
+ .join('');
476
557
 
477
558
  /** `--remove` / `--no-remove` / neither (the move's default) for a move that may bury code. */
478
559
  const removeOptions = (cmd) =>
@@ -516,7 +597,7 @@ function registerVerdict(gcf) {
516
597
  playedOn: opts.playedOn,
517
598
  commit: opts.commit,
518
599
  });
519
- console.log(`keep ${r.milestone} → ${r.ids.join(', ')}${shortHash(r.hash)}`);
600
+ console.log(`keep ${r.milestone} → ${r.ids.join(', ')}${shortHash(r.hash)}${leftLine(r)}`);
520
601
 
521
602
  return;
522
603
  }
@@ -531,7 +612,8 @@ function registerVerdict(gcf) {
531
612
  });
532
613
  console.log(
533
614
  `${res.verdict} ${res.id} → ${res.systems.join(',')}${shortHash(res.hash)}` +
534
- removalLine(res),
615
+ removalLine(res) +
616
+ leftLine(res),
535
617
  );
536
618
  });
537
619
  }
@@ -1019,7 +1101,7 @@ function registerMoves(gcf) {
1019
1101
  : await (
1020
1102
  await ops()
1021
1103
  ).dropUnit(process.cwd(), id, { reason: o.reason, tags, commit: o.commit });
1022
- console.log(`dropped ${r.id}${shortHash(r.hash)}${removalLine(r)}`);
1104
+ console.log(`dropped ${r.id}${shortHash(r.hash)}${removalLine(r)}${leftLine(r)}`);
1023
1105
  });
1024
1106
  }
1025
1107
 
@@ -1702,9 +1784,9 @@ function registerLive(gcf) {
1702
1784
  }
1703
1785
 
1704
1786
  function registerPlan(gcf) {
1705
- gcf
1706
- .command('plan')
1707
- .description('The plan of a work item')
1787
+ const plan = gcf.command('plan').description('The plan of a work item');
1788
+ registerPlanPasses(plan);
1789
+ plan
1708
1790
  .command('check <id>')
1709
1791
  .description(
1710
1792
  'Deterministic plan check: it exists, has task checkboxes, readset in budget; ' +
@@ -1733,6 +1815,77 @@ function registerPlan(gcf) {
1733
1815
  });
1734
1816
  }
1735
1817
 
1818
+ /**
1819
+ * The improve passes of a plan and their stop (Hold-Plan d12, d16): a pass is recorded in the
1820
+ * plan, the verdict decides; a stall blocks the card for the operator's more or accept.
1821
+ */
1822
+ function registerPlanPasses(plan) {
1823
+ plan
1824
+ .command('pass <id>')
1825
+ .description(
1826
+ "Record an improve pass in the plan's ## Passes: its blocking and polish findings; " +
1827
+ 'answer the verdict: continue, converged or stalled',
1828
+ )
1829
+ .requiredOption('--blocking <n>', 'findings that block the plan')
1830
+ .requiredOption('--polish <n>', 'findings that only polish it')
1831
+ .option('--by <reviewer>', 'the pass was made by another reviewer (codex)')
1832
+ .option('--json', 'machine output')
1833
+ .action(async (id, o) => {
1834
+ await touchSession(id);
1835
+ const r = await (
1836
+ await lib('plan-check')
1837
+ ).recordPass(process.cwd(), id, {
1838
+ blocking: Number(o.blocking),
1839
+ polish: Number(o.polish),
1840
+ by: o.by,
1841
+ });
1842
+ out(o.json, r, (x) => `pass ${x.pass}: ${x.verdict} (${x.passes.join(', ')})`);
1843
+ });
1844
+ plan
1845
+ .command('stall <id>')
1846
+ .description(
1847
+ 'Planning does not converge: block the card with its passes (commit gcf(plan_stall))',
1848
+ )
1849
+ .requiredOption('--passes <list>', 'the blocking findings of each pass, comma-separated')
1850
+ .option('--reason <text>', 'what keeps it from converging')
1851
+ .action(async (id, o) => {
1852
+ const passes = splitList(o.passes).map(Number);
1853
+ const r = await (
1854
+ await lib('work-ops')
1855
+ ).stallItem(process.cwd(), id, {
1856
+ passes,
1857
+ reason: o.reason,
1858
+ });
1859
+ console.log(`${r.id} → blocked: planning does not converge · ${r.stall.passes.join(', ')}`);
1860
+ });
1861
+ registerStallAnswers(plan);
1862
+ }
1863
+
1864
+ /** The operator's two answers to a planning stall (Hold-Plan d16). */
1865
+ function registerStallAnswers(plan) {
1866
+ plan
1867
+ .command('more <id>')
1868
+ .description("The operator's answer to a stall: N more passes, back to ready")
1869
+ .requiredOption('--passes <n>', 'how many more passes')
1870
+ .action(async (id, o) => {
1871
+ await operatorOnly('plan more');
1872
+ const r = await (
1873
+ await lib('work-ops')
1874
+ ).answerStall(process.cwd(), id, {
1875
+ more: Number(o.passes),
1876
+ });
1877
+ console.log(`${r.id} → ready: ${r.stall.more} more pass(es) past plan_passes`);
1878
+ });
1879
+ plan
1880
+ .command('accept <id>')
1881
+ .description("The operator's answer to a stall: implement the plan as it is, back to ready")
1882
+ .action(async (id) => {
1883
+ await operatorOnly('plan accept');
1884
+ const r = await (await lib('work-ops')).answerStall(process.cwd(), id, { accept: true });
1885
+ console.log(`${r.id} → ready: the plan goes to implementation as it is`);
1886
+ });
1887
+ }
1888
+
1736
1889
  function registerVerify(gcf) {
1737
1890
  gcf
1738
1891
  .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.25.0",
5
5
  "description": "Game Context Framework for AI Factory",
6
6
  "skills": [
7
7
  "skills/gcf-init",
@@ -187,12 +187,20 @@ 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*',
200
+ // A build by an agent would take its unfinished work as a card's; a run's goes by the harness.
201
+ 'ai-factory gcf playtest build*',
202
+ 'ai-factory gcf playtest start*',
203
+ 'ai-factory gcf playtest stop*',
196
204
  'ai-factory gcf hooks-install*',
197
205
  // A human's hand edits under gcf/: their unfinished work, not the agent's to keep or erase.
198
206
  'ai-factory gcf edits commit*',
@@ -205,6 +213,8 @@ export const DENY_GROUPS = [
205
213
  // The autopilot's card session: an agent starts none.
206
214
  'ai-factory gcf-harness card*',
207
215
  'ai-factory gcf-harness stop*',
216
+ // The operator's Hold of an item or the project (Hold-Plan d6): an agent holds nothing.
217
+ 'ai-factory gcf-harness hold*',
208
218
  // The operator's chat input: an agent answering its own question would be no answer.
209
219
  'ai-factory gcf-harness chat*',
210
220
  'ai-factory extension*',
@@ -225,6 +235,9 @@ export const DENY_GROUPS = [
225
235
  // The project chat's threads: their records, input and settings are the center's.
226
236
  '.gcf-session/chats/**',
227
237
  '.gcf-session/handoff.json',
238
+ // A card's build to play and the record of its player: only `gcf playtest` writes them.
239
+ '.gcf-session/builds/**',
240
+ '.gcf-session/play.json',
228
241
  ),
229
242
  },
230
243
  {
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, 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
 
@@ -354,10 +359,17 @@ async function itemOf(projectDir, c, { verified, shelved, ledger, harness, confi
354
359
  ...(shelved.has(id) ? { shelved: shelved.get(id) } : {}),
355
360
  waits_for: waitsOf(c, running, ledger),
356
361
  needs: needsOf(ledger, c.data.depends ?? []),
357
- moves: offered(c, { running, verified: ready, harness }),
362
+ moves: offered(c, {
363
+ running,
364
+ verified: ready,
365
+ harness,
366
+ building: Boolean(buildOf(projectDir, id, c.data.status)?.building),
367
+ }),
358
368
  file: `gcf/work/${c.name}`,
359
369
  ...(await attachmentsOf(projectDir, id)),
360
370
  log: logOf(projectDir, id),
371
+ // Its own build to play (docs/Play-Plan.md), null while it has none.
372
+ build: buildOf(projectDir, id, c.data.status),
361
373
  // Filled by board() from the inbox.
362
374
  lessons: 0,
363
375
  ...(await progress(projectDir, c)),
@@ -415,6 +427,10 @@ export async function board(projectDir) {
415
427
  },
416
428
  // A run's chat with the operator (`chat:` in config.yml): what it asks, how long it waits.
417
429
  chat: config.chat,
430
+ // The plan's outside reviewer (`plan_review:`, Hold-Plan d17): null when not set.
431
+ plan_review: config.plan_review ?? null,
432
+ // How the game is played: the project's targets and the running player; null when not set up.
433
+ play: playFacts(projectDir, config),
418
434
  phase: await phaseOf(projectDir),
419
435
  extensions,
420
436
  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
  ],
package/lib/domain.js CHANGED
@@ -212,6 +212,37 @@ const ITEM_SPECS = {
212
212
  },
213
213
  ],
214
214
  },
215
+ // Planning that does not converge (Hold-Plan d16): the run's stall, the operator's two answers.
216
+ plan_stall: {
217
+ label: 'planning stall',
218
+ help: "The run's stop: the plan's passes keep finding blocking issues past plan_passes",
219
+ args: ['gcf', 'plan', 'stall', '{id}'],
220
+ fields: [
221
+ { key: 'passes', label: 'Blocking findings of each pass', kind: 'text', required: true },
222
+ { key: 'reason', label: 'Reason', kind: 'longtext' },
223
+ ],
224
+ },
225
+ plan_more: {
226
+ label: 'more passes',
227
+ help: 'The plan improves N more passes, then the same check decides',
228
+ args: ['gcf', 'plan', 'more', '{id}'],
229
+ fields: [
230
+ {
231
+ key: 'passes',
232
+ label: 'More passes',
233
+ kind: 'choice',
234
+ required: true,
235
+ default: '2',
236
+ options: ['1', '2', '3', '5'].map((n) => ({ value: n, label: n })),
237
+ },
238
+ ],
239
+ },
240
+ plan_accept: {
241
+ label: 'implement as is',
242
+ help: 'The plan goes to implementation as it is, its open findings with it',
243
+ args: ['gcf', 'plan', 'accept', '{id}'],
244
+ fields: [],
245
+ },
215
246
  mode: {
216
247
  label: 'run mode',
217
248
  help: 'Where its runs go: the project folder or a worktree of their own; the next run takes it',
@@ -702,6 +733,28 @@ const BLOCK_SPECS = {
702
733
  args: ['gcf', 'inbox', 'later', '{id}', '--off', '--commit'],
703
734
  fields: [],
704
735
  },
736
+ // A chat's button to play: the board opens what it starts (docs/Play-Plan.md d17).
737
+ play: {
738
+ label: 'play',
739
+ help: "Start the card's own build on a target; its verdict stops it",
740
+ args: ['gcf', 'playtest', 'start', '{id}', '--json'],
741
+ fields: [text('target', 'Where to play', { required: true })],
742
+ propose: true,
743
+ },
744
+ 'play-setup': {
745
+ label: 'set up play',
746
+ help: 'How this project builds and starts its game: a card keeps its own build to play',
747
+ args: ['gcf', 'playtest', 'setup'],
748
+ fields: [
749
+ text('build', 'Build command'),
750
+ text('output', 'Folder it builds to: inside the project, ignored by git'),
751
+ text('target', 'Target name'),
752
+ text('start', 'Start command: {dir} the build, {port} a free port, {lan} this machine'),
753
+ text('open', 'What to open: a URL or words'),
754
+ text('stop', 'Command after the player stops'),
755
+ ],
756
+ propose: true,
757
+ },
705
758
  'question-answer': {
706
759
  label: 'answer',
707
760
  help: 'The answer goes into the record; the next agent on its units puts it in place',
@@ -900,6 +953,10 @@ const CHANGES = [
900
953
  'decide',
901
954
  'block',
902
955
  'unblock',
956
+ 'plan pass',
957
+ 'plan stall',
958
+ 'plan more',
959
+ 'plan accept',
903
960
  'inbox add',
904
961
  'inbox category',
905
962
  'inbox later',
@@ -913,6 +970,10 @@ const CHANGES = [
913
970
  'phase next',
914
971
  'hooks-install',
915
972
  'pillar',
973
+ 'playtest build',
974
+ 'playtest start',
975
+ 'playtest stop',
976
+ 'playtest setup',
916
977
  ];
917
978
 
918
979
  // The project chat of a GCF project (AD-5, AD-6): its skill, and the commands it asks for.
package/lib/integrate.js CHANGED
@@ -497,14 +497,20 @@ export async function integrate(projectDir, ids = []) {
497
497
  throw new Error(`integrate runs in the main checkout on its branch, not on ${branch}`);
498
498
  // The session of the item that run works now merges as before (gcf-run's step 1): it works the
499
499
  // checkout itself. A worktree session of the same harness inherits its owner, not that item.
500
- const main = runHolder(projectDir, MAIN_RUN);
501
- const own =
502
- process.env.GCF_RUN_OWNER === `run:${main}` &&
503
- Boolean(process.env.GCF_RUN_ITEM) &&
504
- process.env.GCF_RUN_ITEM === lockedItem(projectDir, MAIN_RUN);
505
- if (main && !own) throw new Error(`${MAIN_BUSY} (pid ${main}): integrate after it ends`);
500
+ const refuseBusy = () => {
501
+ const main = runHolder(projectDir, MAIN_RUN);
502
+ const own =
503
+ process.env.GCF_RUN_OWNER === `run:${main}` &&
504
+ Boolean(process.env.GCF_RUN_ITEM) &&
505
+ process.env.GCF_RUN_ITEM === lockedItem(projectDir, MAIN_RUN);
506
+ if (main && !own) throw new Error(`${MAIN_BUSY} (pid ${main}): integrate after it ends`);
507
+ };
508
+
509
+ refuseBusy();
506
510
 
507
511
  return withMainLock(projectDir, async () => {
512
+ // Again: the checkout may have been taken while this waited for the lock.
513
+ refuseBusy();
508
514
  // The run logs go in at every integrate, a main-mode run's first one too: nothing else
509
515
  // commits them there. Nothing to merge leaves the rest of main alone: a run's first
510
516
  // integrate must not refuse a dirty tree.
package/lib/main-lock.js CHANGED
@@ -31,6 +31,30 @@ export const alive = (pid) => {
31
31
  */
32
32
  export const MAIN_RUN = '.main-run';
33
33
 
34
+ /**
35
+ * Take the main checkout's run lock for work that is no run (a build by click): a main run refuses
36
+ * to start and `integrate` leaves its branches, as under a run. The second line is a token, no
37
+ * item: no card reads as run by it. The release, or null while a live run holds the checkout.
38
+ */
39
+ export async function claimMainRun(projectDir) {
40
+ const file = path.join(path.resolve(projectDir), '.gcf-session', 'runs', `${MAIN_RUN}.lock`);
41
+ await mkdir(path.dirname(file), { recursive: true });
42
+ const token = randomUUID();
43
+ for (let tries = 0; tries < 3; tries++) {
44
+ if (await take(file, token))
45
+ return async () => {
46
+ if ((await readFile(file, 'utf8').catch(() => '')).includes(token))
47
+ await unlink(file).catch(() => {});
48
+ };
49
+
50
+ const dead = await staleText(file);
51
+ if (dead === null) return null;
52
+ await clearStale(file, dead);
53
+ }
54
+
55
+ return null;
56
+ }
57
+
34
58
  /** The item a run lock names on its second line (a main run's: what it works now), or null. */
35
59
  export function lockedItem(projectDir, id) {
36
60
  try {