gcf-aif-ext 0.23.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
@@ -50,6 +50,14 @@ 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.24.0
54
+
55
+ - A card's unfinished work in main mode goes to its branch when another card claims the folder (Methodology §7, [Shelve-Plan](https://github.com/VirtualMaestro/GCF/blob/main/docs/Shelve-Plan.md)). `gcf claim` pins a baseline at `refs/gcf/main-work`; the next card's claim moves what the card changed since to `work/<id>` as a commit with `GCF-Shelved: <id>`, untouched files keep their mtime, and no hook runs. Its own claim brings the work back by a three-way merge: conflicts stay as markers in the file, for the agent. A journal, `refs/gcf/main-switch`, makes every step recoverable.
56
+ - `gcf claim --json` gives `{shelved, returned, moved, conflicts}`; a claim that cannot move the folder refuses with `gcf-refusal: {"code":"shelve","reason":…}`.
57
+ - `close` and `submit` refuse a shelved card. `drop`, `decide no` and a feature's kill delete its branch; no `remove-<id>` when `GCF-Whole: yes` says none of its code reached main and `tune_count` is 0.
58
+ - `gcf audit --json` carries `main_work: {id, paths}` while a baseline stands; `gcf board --json` carries `items[].shelved: {files, commits}`.
59
+ - Needs git 2.40; an older git, a project inside a bigger repository or a linked worktree record nothing and stop a batch as before.
60
+
53
61
  ### 0.23.0
54
62
 
55
63
  - `gcf item amend <id>` fixes a live card's text from every stored status but `unplayed`, the status unchanged: `--text` (`--text-file`) replaces the blocks it names, a key alone takes one out; `--add` adds to `notes:`; `--title`; `--from <in-id>` takes an inbox entry in the same commit, its pictures one by one. `provenance:` and `tuning:` cannot be named; a unit's block must be in its profile. `--dry-run --json` writes nothing and gives `{base, title, text, changes}`; `--base <hash>` refuses a card changed since (`gcf-refusal: {"code":"stale"}`). The operator's: a run and a thread are refused, the deny group `human-moves` holds it, and a chat agent proposes it (`propose_amend`). Refused during this card's run or session (`{"code":"running"}`). Findings on the new text come from the pre-commit gate, with its rollback. The domain's `preview` and `hint` tell a board.
@@ -329,7 +337,8 @@ The run layer of the methodology. Update both extensions together — `gcf-harne
329
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.
330
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.
331
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`.
332
- - `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.
333
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`.
334
343
  - `gcf board [--json]` — everything a board shows in one read.
335
344
 
@@ -392,7 +401,7 @@ Removal leaves `gcf/` and `cnlp.config.json` in place. It also leaves the pre-co
392
401
 
393
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]`
394
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`
395
- - 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`
396
405
  - project phase and board — `phase`, `phase next [--reason]`, `board [--json]` (everything a board shows, in one read)
397
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`
398
407
  - design and sources — `design check`, `design export`, `design import`, `design part`, `design save`, `design discard`, `design commit`, `design migrate`, `anchor`, `section`, `quotes`, `lint`
@@ -407,6 +416,8 @@ Every move of an item makes one commit `gcf(<move>): <id>` with every file it to
407
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`.
408
417
 
409
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
+
410
421
  ## Docs
411
422
 
412
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
@@ -8,6 +8,10 @@ import path from 'node:path';
8
8
  import { fileURLToPath } from 'node:url';
9
9
 
10
10
  const EXT_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
11
+ /** The commit a switch kept of what a card had staged apart from the disk. */
12
+ const stagedLine = (r) =>
13
+ r.staged ? [`what ${r.id} had staged apart from the disk: commit ${r.staged}`] : [];
14
+
11
15
  const lib = (name) => import(new URL(`../lib/${name}.js`, import.meta.url).href);
12
16
 
13
17
  // Must stay byte-identical to the comment line inside the shim below: hooks-install
@@ -87,11 +91,37 @@ function registerSession(gcf) {
87
91
  'An agent session starts working the item on main: the board shows it running until a ' +
88
92
  'move ends it, release, or 2 hours without a gcf command on it',
89
93
  )
90
- .action(async (id) => {
94
+ .option('--json', 'machine output: what moved in the folder')
95
+ .action(async (id, o) => {
91
96
  const { buildLedger } = await lib('ledger');
92
97
  if (!(await buildLedger(process.cwd())).item(id)) throw new Error(`${id} is not a work item`);
93
- await (await lib('session-mark')).claimSession(process.cwd(), id);
94
- console.log(`claimed ${id}`);
98
+ const moved = await (await lib('session-mark')).claimSession(process.cwd(), id);
99
+ out(o.json, moved, (m) =>
100
+ [
101
+ `claimed ${id}`,
102
+ ...(m.shelved
103
+ ? [
104
+ `shelved ${m.shelved.id}: ${m.shelved.files} file(s) went to ${m.shelved.branch}`,
105
+ ...stagedLine(m.shelved),
106
+ ]
107
+ : []),
108
+ ...(m.returned
109
+ ? [
110
+ `returned ${m.returned.id}: ${m.returned.files} file(s), ` +
111
+ `main moved ${m.moved} commit(s)`,
112
+ ...stagedLine(m.returned),
113
+ ...(m.returned.branch_moved
114
+ ? [`work/${m.returned.id} moved on and stays: its new commits are not here`]
115
+ : []),
116
+ ]
117
+ : []),
118
+ ...m.conflicts.map((c) =>
119
+ c.kept_main
120
+ ? `conflict ${c.path}: kept main's, the card's copy is in commit ${m.returned.copy}`
121
+ : `conflict ${c.path}: resolve its markers first, or block`,
122
+ ),
123
+ ].join('\n'),
124
+ );
95
125
  });
96
126
  gcf
97
127
  .command('release <id>')
@@ -337,25 +367,24 @@ function registerAudit(gcf) {
337
367
  });
338
368
  }
339
369
 
340
- /** How the session's build went: built, no step, failed, or left to the human. */
341
- function buildText(b) {
342
- if (!b) return 'build it from this commit';
343
- 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}`];
344
375
 
345
- return b.skipped ? 'no build step (dod.build: none)' : 'built with dod.build';
376
+ return [` build failed: ${b.problem.split('\n')[0]}`];
346
377
  }
347
378
 
348
- /** 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. */
349
380
  function sessionHead(s) {
350
- const build = buildText(s.build);
351
-
352
381
  return [
353
- 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',
354
383
  // Main by the remote's default when known, else any branch but detached or a worktree's.
355
384
  ...(s.branch === 'HEAD' || s.branch?.startsWith('work/') || (s.main && s.branch !== s.main)
356
- ? [`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`]
357
386
  : []),
358
- ...(s.dirty ? ['warning: uncommitted changes — the build is not the commit'] : []),
387
+ ...(s.dirty ? ['warning: uncommitted changes — a click builds them too'] : []),
359
388
  ];
360
389
  }
361
390
 
@@ -395,7 +424,7 @@ export function sessionText(s) {
395
424
  '',
396
425
  `[ ] ${c.id} (${c.status}) [${c.system.join(',')}] ${c.title ?? c.intent ?? ''}`,
397
426
  );
398
- lines.push(` check: ${c.question}`);
427
+ lines.push(...buildLine(c.build), ` check: ${c.question}`);
399
428
  if (c.play_on?.length) lines.push(` play on: ${c.play_on.join('; ')}`);
400
429
  for (const r of c.reach) lines.push(` try: ${r}`);
401
430
  for (const f of c.feel) lines.push(` feel: ${f}`);
@@ -428,21 +457,103 @@ function registerPlaytest(gcf) {
428
457
  });
429
458
  playtest
430
459
  .command('session')
431
- .description('A playtest session: the build of main and the checklist, built from the items')
432
- .option('--build', 'run dod.build first')
460
+ .description('A playtest session: where main stands and the checklist, from the items')
433
461
  .option('--json', 'machine output')
434
462
  .action(async (o) => {
435
- const r = await (
436
- await lib('playtest-list')
437
- ).playtestSession(process.cwd(), { build: Boolean(o.build) });
463
+ const r = await (await lib('playtest-list')).playtestSession(process.cwd());
438
464
  // Commander gives a flag both levels define to the parent: `playtest session --json`.
439
465
  out(o.json || playtest.opts().json, r, sessionText);
440
- 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)}`);
441
546
  });
442
547
  }
443
548
 
444
549
  const shortHash = (h) => (h ? ` (${h.slice(0, 7)})` : '');
445
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('');
446
557
 
447
558
  /** `--remove` / `--no-remove` / neither (the move's default) for a move that may bury code. */
448
559
  const removeOptions = (cmd) =>
@@ -486,7 +597,7 @@ function registerVerdict(gcf) {
486
597
  playedOn: opts.playedOn,
487
598
  commit: opts.commit,
488
599
  });
489
- 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)}`);
490
601
 
491
602
  return;
492
603
  }
@@ -501,7 +612,8 @@ function registerVerdict(gcf) {
501
612
  });
502
613
  console.log(
503
614
  `${res.verdict} ${res.id} → ${res.systems.join(',')}${shortHash(res.hash)}` +
504
- removalLine(res),
615
+ removalLine(res) +
616
+ leftLine(res),
505
617
  );
506
618
  });
507
619
  }
@@ -803,7 +915,7 @@ function registerChanges(gcf) {
803
915
  const allOf = (o, cmd) => cmd?.optsWithGlobals?.() ?? o;
804
916
  const group = gcf
805
917
  .command('changes')
806
- .description("What is not committed in the main checkout or a run's worktree: read only")
918
+ .description("What is not committed in the main checkout or a run's worktree")
807
919
  .allowExcessArguments(false)
808
920
  .option('--worktree <id>', TREE)
809
921
  .option('--json', '{tree, base, count, files, trees, more, watch}')
@@ -860,6 +972,27 @@ function registerChanges(gcf) {
860
972
  ).changeFile(process.cwd(), o.path, o.side, { worktree: o.worktree });
861
973
  out(true, r);
862
974
  });
975
+ registerChangesCommit(group, allOf);
976
+ }
977
+
978
+ function registerChangesCommit(group, allOf) {
979
+ group
980
+ .command('commit')
981
+ .description(
982
+ "Commit these files of the main checkout with this message: the board's Commit, the " +
983
+ "operator's move",
984
+ )
985
+ .requiredOption('--fields-file <path>', '{message, paths} as JSON, - for stdin')
986
+ .option('--json', '{hash, subject, files}')
987
+ .action(async (own, cmd) => {
988
+ const o = allOf(own, cmd);
989
+ if (o.worktree) throw new Error('changes commit: a run commits its own work in a worktree');
990
+ await operatorOnly('changes commit');
991
+ const r = await (
992
+ await lib('commit-files')
993
+ ).commitFiles(process.cwd(), fieldsOf(o.fieldsFile));
994
+ out(o.json, r, (x) => `committed ${x.files} file${x.files === 1 ? '' : 's'} ${x.hash}`);
995
+ });
863
996
  }
864
997
 
865
998
  function registerMigrate(design) {
@@ -968,7 +1101,7 @@ function registerMoves(gcf) {
968
1101
  : await (
969
1102
  await ops()
970
1103
  ).dropUnit(process.cwd(), id, { reason: o.reason, tags, commit: o.commit });
971
- console.log(`dropped ${r.id}${shortHash(r.hash)}${removalLine(r)}`);
1104
+ console.log(`dropped ${r.id}${shortHash(r.hash)}${removalLine(r)}${leftLine(r)}`);
972
1105
  });
973
1106
  }
974
1107
 
@@ -1651,9 +1784,9 @@ function registerLive(gcf) {
1651
1784
  }
1652
1785
 
1653
1786
  function registerPlan(gcf) {
1654
- gcf
1655
- .command('plan')
1656
- .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
1657
1790
  .command('check <id>')
1658
1791
  .description(
1659
1792
  'Deterministic plan check: it exists, has task checkboxes, readset in budget; ' +
@@ -1682,6 +1815,77 @@ function registerPlan(gcf) {
1682
1815
  });
1683
1816
  }
1684
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
+
1685
1889
  function registerVerify(gcf) {
1686
1890
  gcf
1687
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.23.0",
4
+ "version": "0.25.0",
5
5
  "description": "Game Context Framework for AI Factory",
6
6
  "skills": [
7
7
  "skills/gcf-init",
@@ -187,22 +187,34 @@ 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*',
199
207
  'ai-factory gcf edits discard*',
208
+ // What goes into the operator's commit is theirs to say; an agent commits with git.
209
+ 'ai-factory gcf changes commit*',
200
210
  'ai-factory gcf-harness init*',
201
211
  // The space keeps `gcf-harness runs`, the history of past runs, a read the agent may make.
202
212
  'ai-factory gcf-harness run *',
203
213
  // The autopilot's card session: an agent starts none.
204
214
  'ai-factory gcf-harness card*',
205
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*',
206
218
  // The operator's chat input: an agent answering its own question would be no answer.
207
219
  'ai-factory gcf-harness chat*',
208
220
  'ai-factory extension*',
@@ -223,6 +235,9 @@ export const DENY_GROUPS = [
223
235
  // The project chat's threads: their records, input and settings are the center's.
224
236
  '.gcf-session/chats/**',
225
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',
226
241
  ),
227
242
  },
228
243
  {
package/lib/audit-core.js CHANGED
@@ -17,6 +17,7 @@ import { inboxProblems } from './inbox.js';
17
17
  import { inboxVocabulary } from './domain.js';
18
18
  import { gatePolicy, verdictDeferred } from './gates.js';
19
19
  import { milestoneState } from './milestone-state.js';
20
+ import { mainWork } from './shelf.js';
20
21
 
21
22
  function git(args, cwd) {
22
23
  // A blame of a long file overflows the 1 MiB default, and an overflow reads as a git failure.
@@ -57,6 +58,7 @@ function runningOf(projectDir, id) {
57
58
  * @property {Array<{id: string, tune_count: number, limit: number}>} tune_limit
58
59
  * @property {Array<{id: string, depends: string[]}>} open_depends
59
60
  * @property {{count: number, limit: number, over: boolean}} wip
61
+ * @property {{id: string, paths: string[]}} [main_work] the card in the folder (lib/shelf.js)
60
62
  * @property {{count: number, warn_after: number, over: boolean}} unplayed
61
63
  * @property {string[]} legacy_cards
62
64
  * @property {{tokens: number, budget: number, over: boolean, count: number, too_many: boolean}
@@ -143,6 +145,9 @@ export async function audit(projectDir) {
143
145
  deferred: verdictDeferred(config, c.data),
144
146
  ...runningOf(projectDir, String(c.data.id)),
145
147
  }));
148
+ // The card whose unfinished work lies in the folder (lib/shelf.js): the next claim shelves it.
149
+ const work = mainWork(projectDir);
150
+ if (work) report.main_work = work;
146
151
  const design = await designCheck(projectDir);
147
152
  checkItems(report, items, config, { projectDir, ledger });
148
153
  report.design = {
package/lib/board.js CHANGED
@@ -20,12 +20,14 @@ import { lessonRepeats } from './inbox-categories.js';
20
20
  import { openDepends } from './work-ops.js';
21
21
  import { listQuestions } from './questions.js';
22
22
  import { sessionActive } from './session-mark.js';
23
+ import { shelvedCards } from './shelf.js';
23
24
  import { agentOf } from './agent-permissions.js';
24
25
  import { projectSettings } from './config-set.js';
25
26
  import { designCheck, designUnits } from './design-check.js';
26
27
  import { designState } from './design-parts.js';
27
28
  import { gatePolicy } from './gates.js';
28
29
  import { milestoneState } from './milestone-state.js';
30
+ import { buildOf, playFacts } from './play.js';
29
31
 
30
32
  // The version of the JSON below (Methodology §11): a board refuses one it does not know. Bump it
31
33
  // when a field changes meaning or goes away; a new field does not bump it.
@@ -223,6 +225,8 @@ const SCALARS = [
223
225
  'run_mode',
224
226
  'skip_gates',
225
227
  'gate_why',
228
+ // Planning that does not converge (Hold-Plan d16): the blocking counts and the answer.
229
+ 'stall',
226
230
  ];
227
231
 
228
232
  /**
@@ -288,7 +292,9 @@ function runningKind(projectDir, id) {
288
292
  * agent's run to an item that waits for one and has no green verify yet. A feature runs through
289
293
  * its children: the run gate refuses it.
290
294
  */
291
- 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);
292
298
  if (running) return [];
293
299
  const runs = harness && c.data.status === RUNS_FROM && !verified && c.data.type !== 'feature';
294
300
 
@@ -315,7 +321,7 @@ async function attachmentsOf(projectDir, id) {
315
321
  }
316
322
 
317
323
  /** One item of the board. */
318
- async function itemOf(projectDir, c, { verified, ledger, harness, config }) {
324
+ async function itemOf(projectDir, c, { verified, shelved, ledger, harness, config }) {
319
325
  const id = String(c.data.id);
320
326
  // A trailer counts only while the item waits on main for its integrate.
321
327
  const ready = c.data.status === 'ready' && verified.has(id);
@@ -349,12 +355,21 @@ async function itemOf(projectDir, c, { verified, ledger, harness, config }) {
349
355
  resumable,
350
356
  resume,
351
357
  verified: ready,
358
+ // Its unfinished work waits on its branch (lib/shelf.js); a run brings it back.
359
+ ...(shelved.has(id) ? { shelved: shelved.get(id) } : {}),
352
360
  waits_for: waitsOf(c, running, ledger),
353
361
  needs: needsOf(ledger, c.data.depends ?? []),
354
- 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
+ }),
355
368
  file: `gcf/work/${c.name}`,
356
369
  ...(await attachmentsOf(projectDir, id)),
357
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),
358
373
  // Filled by board() from the inbox.
359
374
  lessons: 0,
360
375
  ...(await progress(projectDir, c)),
@@ -365,12 +380,13 @@ export async function board(projectDir) {
365
380
  const root = path.join(path.resolve(projectDir), 'gcf');
366
381
  const ledger = await buildLedger(projectDir);
367
382
  const verified = verifiedOf(projectDir);
383
+ const shelved = shelvedCards(projectDir);
368
384
  const { extensions, error: extensionsError } = await extensionsOf(projectDir);
369
385
  const harness = hasHarness(extensions);
370
386
  const config = await readConfig(root);
371
387
  const items = [];
372
388
  for (const c of ledger.items)
373
- items.push(await itemOf(projectDir, c, { verified, ledger, harness, config }));
389
+ items.push(await itemOf(projectDir, c, { verified, shelved, ledger, harness, config }));
374
390
  inRunOrder(items);
375
391
  // When the wait began: the time of the commit `since` names (Board-PRD §13).
376
392
  const times = commitTimes(
@@ -411,6 +427,10 @@ export async function board(projectDir) {
411
427
  },
412
428
  // A run's chat with the operator (`chat:` in config.yml): what it asks, how long it waits.
413
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),
414
434
  phase: await phaseOf(projectDir),
415
435
  extensions,
416
436
  extensions_error: extensionsError,
package/lib/changes.js CHANGED
@@ -514,6 +514,13 @@ export async function changesOf(projectDir, { worktree } = {}) {
514
514
  };
515
515
  }
516
516
 
517
+ /** The main checkout's rows as a commit reads them, past the list's limit: `xy` and `why` kept. */
518
+ export async function rowsToCommit(projectDir) {
519
+ const { tree, rows } = await readTree(projectDir);
520
+
521
+ return { base: tree.base, rows: (rows ?? []).map((r) => byDisk(tree.dir, r)) };
522
+ }
523
+
517
524
  /** The row of `p` with its view, or the refusal of a path the list does not hold. */
518
525
  async function rowOf(projectDir, p, worktree) {
519
526
  const { tree, rows, noDiff } = await readTree(projectDir, worktree);