gcf-aif-ext 0.27.1 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -345,7 +345,9 @@ The run layer of the methodology. Update both extensions together — `gcf-harne
345
345
  - `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.
346
346
  - 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`.
347
347
  - `gcf playtest session` — where main stands and a checklist per item: its build, what to check, how to get there, what to feel.
348
- - `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. On Windows the project's commands (`play:`, `dod.*`) run with Git's `bin` first in PATH, so `bash` is Git's, not System32's WSL launcher. The deny group `run-play` keeps a run's agent from building; a chat thread may build on the human's ask.
348
+ - `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>.<build>.<profile>.json` or the checkout's `snaps/main.<build>.<profile>.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. On Windows the project's commands (`play:`, `dod.*`) run with Git's `bin` first in PATH, so `bash` is Git's, not System32's WSL launcher. The deny group `run-play` keeps a run's agent from building; a chat thread may build on the human's ask.
349
+ - `gcf playtest build <id> --wait|--queue`, `start <id> --target <t> [--device <id>] --wait|--queue`, `cancel <ticket>`, `devices <target>` — a build while a run works in the checkout waits on a ticket `.gcf-session/runs/.build-<n>.json` instead of a refusal; a main run lets it in between its cards by `.gcf-session/.main-run.yield`; `--queue` starts its own waiter and prints `{ticket}`; `cancel` takes a waiting ticket out or stops a build. `play.builds` names the project's builds, each with one command or `{debug, release}` and its `plays_on` rows; `--of <build>` and `--profile release` pick one (else the card's build: `play.auto_build` when its `play_on` names it or none, else the first it names, in debug); a card whose code has left HEAD builds in `.gcf-session/buildtree` at its own commit; `setup --of <build> [--profile release] --build <cmd>`, `--auto-build`, `--remove-build`, a target's `--target-build`; a target names its `build`, the rows it serves (`for`), its `devices` script and `launches`
350
+ - `gcf play-notes <id> [--template]`, `gcf item show <id>` — the agent's `## Play notes` in a card's plan, and the handoff the core reads from it and the card: outcome, main question, Play by platform, what changed, what to try, what waits; also `items[].handoff` of `gcf board --json`
349
351
  - `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`.
350
352
  - `gcf board [--json]` — everything a board shows in one read.
351
353
 
@@ -408,7 +410,7 @@ Removal leaves `gcf/` and `cnlp.config.json` in place. It also leaves the pre-co
408
410
 
409
411
  - 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]`
410
412
  - 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`
411
- - runs and play — `context`, `plan check <id>`, `verify <id>`, `playtest`, `playtest session`, `playtest status`, `audit`
413
+ - runs and play — `context`, `plan check <id>`, `verify <id>`, `playtest`, `playtest session`, `playtest status`, `playtest devices`, `play-notes`, `item show`, `audit`
412
414
  - project phase and board — `phase`, `phase next [--reason]`, `board [--json]` (everything a board shows, in one read)
413
415
  - 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`
414
416
  - design and sources — `design check`, `design export`, `design import`, `design part`, `design save`, `design discard`, `design commit`, `design migrate`, `anchor`, `section`, `quotes`, `lint`
package/commands/gcf.js CHANGED
@@ -6,6 +6,7 @@ import { existsSync, readFileSync } from 'node:fs';
6
6
  import { spawnSync } from 'node:child_process';
7
7
  import path from 'node:path';
8
8
  import { fileURLToPath } from 'node:url';
9
+ import YAML from 'yaml';
9
10
 
10
11
  const EXT_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
11
12
  /** The commit a switch kept of what a card had staged apart from the disk. */
@@ -81,6 +82,15 @@ const ASSUME =
81
82
  '"<question> = <value>" (repeatable)';
82
83
  const repeated = (v, p) => [...p, v];
83
84
 
85
+ /** A row given on the command line: a YAML flow map, `{ device: phone, os: android }`. */
86
+ function flowMap(text) {
87
+ const v = YAML.parse(String(text).trim().startsWith('{') ? text : `{ ${text} }`);
88
+ if (typeof v !== 'object' || v === null || Array.isArray(v))
89
+ throw new Error(`not a row of fields: ${text}`);
90
+
91
+ return v;
92
+ }
93
+
84
94
  /** A session's own command on its item keeps the item's running mark fresh. */
85
95
  const touchSession = async (id) => (await lib('session-mark')).touchSession(process.cwd(), id);
86
96
 
@@ -367,13 +377,15 @@ function registerAudit(gcf) {
367
377
  });
368
378
  }
369
379
 
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}`];
380
+ /** An item's builds on the sheet: each one's commit, what goes on, why it failed. */
381
+ function buildLines(builds) {
382
+ return (builds ?? []).map((b) => {
383
+ const which = `${b.build} ${b.profile}`;
384
+ if (b.building) return ` build ${which}: being built`;
385
+ if (b.ok) return ` build ${which}: ${b.commit ?? 'no commit'}, ${b.source}, ${b.built_at}`;
375
386
 
376
- return [` build failed: ${b.problem.split('\n')[0]}`];
387
+ return ` build ${which} failed: ${b.problem.split('\n')[0]}`;
388
+ });
377
389
  }
378
390
 
379
391
  /** The sheet's head: where main stands, and why the checkout may not be main. */
@@ -388,8 +400,21 @@ function sessionHead(s) {
388
400
  ];
389
401
  }
390
402
 
403
+ /** One card of the sheet: its handoff when it has one (docs/Handoff-Plan.md d4), else the old. */
404
+ function itemLines(c, linesOf) {
405
+ if (c.handoff && linesOf) return linesOf(c.id, c.handoff).map((l) => ` ${l}`);
406
+
407
+ return [
408
+ ...buildLines(c.builds),
409
+ ` check: ${c.question}`,
410
+ ...(c.play_on?.length ? [` play on: ${c.play_on.join('; ')}`] : []),
411
+ ...c.reach.map((r) => ` try: ${r}`),
412
+ ...c.feel.map((f) => ` feel: ${f}`),
413
+ ];
414
+ }
415
+
391
416
  /** The session sheet: the build, then per item what to check and how to get there. */
392
- export function sessionText(s) {
417
+ export function sessionText(s, linesOf = null) {
393
418
  const lines = sessionHead(s);
394
419
  const decide = s.decisions.length
395
420
  ? [
@@ -424,10 +449,7 @@ export function sessionText(s) {
424
449
  '',
425
450
  `[ ] ${c.id} (${c.status}) [${c.system.join(',')}] ${c.title ?? c.intent ?? ''}`,
426
451
  );
427
- lines.push(...buildLine(c.build), ` check: ${c.question}`);
428
- if (c.play_on?.length) lines.push(` play on: ${c.play_on.join('; ')}`);
429
- for (const r of c.reach) lines.push(` try: ${r}`);
430
- for (const f of c.feel) lines.push(` feel: ${f}`);
452
+ lines.push(...itemLines(c, linesOf));
431
453
  }
432
454
 
433
455
  return [
@@ -462,7 +484,8 @@ function registerPlaytest(gcf) {
462
484
  .action(async (o) => {
463
485
  const r = await (await lib('playtest-list')).playtestSession(process.cwd());
464
486
  // Commander gives a flag both levels define to the parent: `playtest session --json`.
465
- out(o.json || playtest.opts().json, r, sessionText);
487
+ const { handoffLines } = await lib('handoff');
488
+ out(o.json || playtest.opts().json, r, (x) => sessionText(x, handoffLines));
466
489
  });
467
490
  registerPlay(playtest);
468
491
  }
@@ -480,6 +503,32 @@ const startLine = (r) =>
480
503
  ? `playing ${r.id ?? 'main'} on ${r.target} (pid ${r.pid}): ${r.open}`
481
504
  : `launched ${r.id ?? 'main'} on ${r.target}: ${r.open}`;
482
505
 
506
+ /** `playtest devices` as words: each device, whether it plays, and why not. */
507
+ function devicesText(r) {
508
+ if (r.problem) return [r.problem, r.tail].filter(Boolean).join('\n');
509
+ if (r.unavailable) return `${r.target}: ${r.unavailable}`;
510
+ if (!r.devices.length) return `${r.target}: no device found`;
511
+
512
+ return r.devices
513
+ .map((d) => {
514
+ const os = [d.os, d.os_version].filter(Boolean).join(' ');
515
+ const why = d.play ? 'ready' : (d.why ?? d.state);
516
+
517
+ return `${d.id ?? '?'} · ${d.name} · ${os || '?'} · ${why}`;
518
+ })
519
+ .join('\n');
520
+ }
521
+
522
+ /** A build ticket of the queue, as words. */
523
+ const ticketLine = (q) => {
524
+ const then = q.job.start ? ` then ${q.job.start.target}` : '';
525
+ const state = q.building ? 'building' : q.after ? `waits after ${q.after}` : 'waits';
526
+
527
+ const which = q.job.of ? ` ${q.job.of} ${q.job.profile ?? 'debug'}` : '';
528
+
529
+ return `ticket ${q.ticket}: ${q.job.build ?? 'main'}${which}${then}, ${state}`;
530
+ };
531
+
483
532
  /** The player's line and the targets of `playtest status`. */
484
533
  function statusText(s) {
485
534
  if (!s) return 'how to play is not set up: ai-factory gcf playtest setup';
@@ -490,6 +539,7 @@ function statusText(s) {
490
539
  ? `playing ${s.running.id ?? 'main'} on ${s.running.target}: ${s.running.open}`
491
540
  : 'no player is running',
492
541
  `targets: ${s.targets.map((t) => t.name).join(', ') || 'none'}`,
542
+ ...(s.queue ?? []).map(ticketLine),
493
543
  ].join('\n');
494
544
  }
495
545
 
@@ -501,16 +551,29 @@ function registerPlayBuild(playtest, jsonOf) {
501
551
  .option('--main', 'the checkout with its uncommitted edits, not a card')
502
552
  .option('--fresh', 'build even when a snapshot of this code is there, and replace it')
503
553
  .option('--from <worktree>', "the card's worktree, for a run whose code is not in main yet")
554
+ .option('--of <build>', "which build of play.builds: else the card's own, else auto_build")
555
+ .option('--profile <profile>', 'debug (the default) or release')
556
+ .option('--wait', 'a busy checkout is waited for on a ticket, in this process')
557
+ .option('--queue', 'a ticket and its own waiter: prints {ticket} and ends at once')
504
558
  .option('--json', 'machine output')
505
559
  .action(async (id, o) => {
506
560
  const play = await lib('play');
507
561
  const fresh = Boolean(o.fresh);
508
562
  const main = oneOf(id, o.main);
509
563
  if (main && o.from) throw new Error("--from names a card's worktree: not with --main");
564
+ const which = { of: o.of ?? null, profile: o.profile ?? null };
565
+ if (o.queue) {
566
+ const job = { build: main ? null : id, from: o.from ?? null, fresh, ...which };
567
+ const q = await play.queueJob(process.cwd(), job);
568
+
569
+ return out(jsonOf(o), q, (x) => `ticket ${x.ticket}: the build waits its turn`);
570
+ }
571
+
572
+ const wait = Boolean(o.wait);
510
573
  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';
574
+ ? await play.buildMain(process.cwd(), { fresh, wait, ...which })
575
+ : await play.buildItem(process.cwd(), id, { from: o.from ?? null, fresh, wait, ...which });
576
+ const who = `${id ?? 'main'} ${r.build} ${r.profile}`;
514
577
  out(jsonOf(o), r, (b) =>
515
578
  b.ok
516
579
  ? `built ${who} at ${b.commit?.slice(0, 7) ?? 'no commit'}, ${b.size} bytes` +
@@ -524,18 +587,58 @@ function registerPlayBuild(playtest, jsonOf) {
524
587
  .description("Start a card's snapshot, or the checkout's (--main), on a target: one player")
525
588
  .option('--main', "the checkout's snapshot, not a card's")
526
589
  .requiredOption('--target <name>', 'a target of play.targets')
590
+ .option('--device <id>', "a device of the target's devices answer: {device} in its commands")
591
+ .option('--profile <profile>', "the target's build in debug (the default) or release")
592
+ .option('--wait', 'no build yet: build it on a ticket first, then start (this process waits)')
593
+ .option('--queue', 'no build yet: a ticket and its own waiter; prints {ticket} at once')
527
594
  .option('--json', 'machine output')
528
595
  .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);
596
+ const play = await lib('play');
597
+ const who = oneOf(id, o.main) ? null : id;
598
+ const profile = o.profile ?? null;
599
+ if (o.queue && !(await play.hasBuildOf(process.cwd(), who, o.target, profile))) {
600
+ const start = { target: o.target, device: o.device ?? null, profile };
601
+ const q = await play.queueJob(process.cwd(), { build: who, start });
602
+
603
+ return out(jsonOf(o), q, (x) => `ticket ${x.ticket}: the build waits, the start after it`);
604
+ }
605
+
606
+ const how = { wait: Boolean(o.wait), device: o.device ?? null, profile };
607
+ const r = await play.startPlay(process.cwd(), who, o.target, how);
531
608
  out(jsonOf(o), r, startLine);
532
609
  });
533
610
  }
534
611
 
612
+ /** The build queue (docs/Handoff-Plan.md d6): a ticket cancelled; a target's devices (d5). */
613
+ function registerPlayQueue(playtest, jsonOf) {
614
+ playtest
615
+ .command('devices <target>')
616
+ .description("The devices a target's script finds, each under the plays_on row it fits")
617
+ .option('--json', 'machine output')
618
+ .action(async (target, o) => {
619
+ const r = await (await lib('devices')).devicesOf(process.cwd(), target);
620
+ out(jsonOf(o), r, devicesText);
621
+ if (r.problem) process.exitCode = 1;
622
+ });
623
+ playtest
624
+ .command('cancel <ticket>')
625
+ .description('Cancel a build ticket: a waiting one goes, a building one is stopped')
626
+ .option('--json', 'machine output')
627
+ .action(async (ticket, o) => {
628
+ const n = Number(ticket);
629
+ if (!Number.isInteger(n) || n < 1) throw new Error(`${ticket} is no ticket number`);
630
+ const r = await (await lib('build-queue')).cancelTicket(process.cwd(), n);
631
+ out(jsonOf(o), r, (x) =>
632
+ x.was === 'gone' ? `ticket ${n} is not in the queue` : `ticket ${n} cancelled (${x.was})`,
633
+ );
634
+ });
635
+ }
636
+
535
637
  /** The player and the project's play: setup (docs/Play-Plan.md). */
536
638
  function registerPlay(playtest) {
537
639
  const jsonOf = (o) => o.json || playtest.opts().json;
538
640
  registerPlayBuild(playtest, jsonOf);
641
+ registerPlayQueue(playtest, jsonOf);
539
642
  playtest
540
643
  .command('stop')
541
644
  .description('Stop the running player')
@@ -556,18 +659,37 @@ function registerPlay(playtest) {
556
659
  playtest
557
660
  .command('setup')
558
661
  .description("How the project builds and starts its game (play: in config.yml; the operator's)")
662
+ .option('--of <build>', 'the build the next options set (a new name adds one)')
559
663
  .option('--build <cmd>', 'the command that builds the game')
664
+ .option('--profile <profile>', 'whose command --build gives: debug or release')
560
665
  .option('--output <folder>', 'where it builds to: inside the project, ignored by git')
561
- .option('--target <name>', 'the target the next three options set')
666
+ .option('--auto-build <build>', "the build a run's card gets when its play_on names none")
667
+ .option('--remove-build <build>', 'take a build away')
668
+ .option('--target <name>', 'the target the next options set')
669
+ .option('--target-build <build>', 'the build the target plays')
562
670
  .option('--start <cmd>', 'starts the game: {dir} the snapshot, {port} a free port, {lan}')
563
671
  .option('--open <text>', 'what to open: a URL or words, with the same placeholders')
564
672
  .option('--stop <cmd>', 'runs after the player stops')
673
+ .option('--for <row>', 'the rows the target serves: "{ device: phone, os: android }"', flowMap)
674
+ .option('--devices <cmd>', 'lists the devices: a JSON line each (id, name, device, os, state)')
675
+ .option('--launches', 'the start installs and launches, then ends: wait for its exit')
676
+ .option('--no-launches', 'the start keeps running while the game plays')
677
+ .option(
678
+ '--plays-on <row>',
679
+ 'a row the build plays on: "{ device: phone, os: android, os_min: 10 }" (repeatable)',
680
+ (v, p) => [...(p ?? []), flowMap(v)],
681
+ undefined,
682
+ )
565
683
  .option('--remove-target <name>', 'take a target away')
566
684
  .option('--no-commit', 'leave the change uncommitted')
567
685
  .action(async (o) => {
568
686
  await operatorOnly('playtest setup');
569
687
  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)}`);
688
+ const builds = Object.entries(r.play.builds).map(
689
+ ([n, b]) => `${n} (${Object.keys(b.profiles).join(', ')}) into ${b.output}`,
690
+ );
691
+ console.log(`play: ${builds.join('; ')}${shortHash(r.hash)}`);
692
+ for (const w of r.play.warnings) console.log(`warning: ${w}`);
571
693
  });
572
694
  }
573
695
 
@@ -586,6 +708,23 @@ const removeOptions = (cmd) =>
586
708
  .option('--remove', 'also create a removal item: the code is in main')
587
709
  .option('--no-remove', 'no removal item: the code never reached main');
588
710
 
711
+ /** The agent's part of a card's handoff (docs/Handoff-Plan.md d3). */
712
+ function registerPlayNotes(gcf) {
713
+ gcf
714
+ .command('play-notes <id>')
715
+ .description("A card's ## Play notes: its template, or what its plan holds and lacks")
716
+ .option('--template', "print the section to fill, with the card's rows of play_on")
717
+ .option('--json', 'machine output')
718
+ .action(async (id, o) => {
719
+ const notes = await lib('play-notes');
720
+ if (o.template) return console.log(await notes.playNotesTemplate(process.cwd(), id));
721
+ const item = (await (await lib('ledger')).buildLedger(process.cwd())).item(id);
722
+ if (!item) throw new Error(`${id} is not on the board`);
723
+ const r = await notes.playNotesCheck(process.cwd(), item);
724
+ out(o.json, r, (x) => x.warnings.join('\n') || 'the play notes are whole');
725
+ });
726
+ }
727
+
589
728
  function registerVerdict(gcf) {
590
729
  removeOptions(
591
730
  gcf
@@ -602,7 +741,7 @@ function registerVerdict(gcf) {
602
741
  )
603
742
  .option(
604
743
  '--played-on <line>',
605
- 'where you played it, a line of platforms in game.md (repeatable; a note, not a must)',
744
+ 'where you played it, a build of play.builds (repeatable; a note, not a must)',
606
745
  repeated,
607
746
  [],
608
747
  )
@@ -1175,8 +1314,31 @@ function registerMoves(gcf) {
1175
1314
  });
1176
1315
  }
1177
1316
 
1317
+ /** A card and its handoff (docs/Handoff-Plan.md d4): `item <id>` would meet the subcommands. */
1318
+ function registerItemShow(item) {
1319
+ item
1320
+ .command('show <id>')
1321
+ .description('A card and its handoff to play: blocks 0-6, the technical one in a line')
1322
+ .option('--json', 'machine output')
1323
+ .action(async (id, o) => {
1324
+ const ledger = await (await lib('ledger')).buildLedger(process.cwd());
1325
+ const card = ledger.item(id);
1326
+ if (!card) throw new Error(`${id} is not on the board`);
1327
+ const { handoffLines, handoffOf } = await lib('handoff');
1328
+ const handoff = await handoffOf(process.cwd(), id, { ledger });
1329
+ const r = { id, title: card.data.title ?? null, status: card.data.status, handoff };
1330
+ out(o.json, r, (x) =>
1331
+ [
1332
+ `${x.id} (${x.status})${x.title ? ` ${x.title}` : ''}`,
1333
+ ...(x.handoff ? handoffLines(x.id, x.handoff) : ['it waits for nothing: no handoff']),
1334
+ ].join('\n'),
1335
+ );
1336
+ });
1337
+ }
1338
+
1178
1339
  function registerItem(gcf) {
1179
1340
  const item = gcf.command('item').description('Work items in gcf/work/ (Methodology §3)');
1341
+ registerItemShow(item);
1180
1342
  item
1181
1343
  .command('new [id]')
1182
1344
  .description(
@@ -1473,6 +1635,7 @@ function registerItemMoves(gcf) {
1473
1635
  claimedBy(o, id);
1474
1636
  const r = await (await ops()).submitItem(process.cwd(), id, verifiedMove(o));
1475
1637
  console.log(`${r.id} → ${r.status}${shortHash(r.hash)}`);
1638
+ notesWarned(r);
1476
1639
  });
1477
1640
  gcf
1478
1641
  .command('close <id>')
@@ -1494,9 +1657,15 @@ function registerItemMoves(gcf) {
1494
1657
  await ops()
1495
1658
  ).closeItem(process.cwd(), id, { ...verifiedMove(o), constraints: o.constraint });
1496
1659
  console.log(`closed ${r.id}${r.unplayed ? ' → unplayed' : ''}${shortHash(r.hash)}`);
1660
+ notesWarned(r);
1497
1661
  });
1498
1662
  }
1499
1663
 
1664
+ /** What the card's ## Play notes lack (docs/Handoff-Plan.md d3): a warning, never a refusal. */
1665
+ const notesWarned = (r) => {
1666
+ for (const w of r.play_notes_warnings ?? []) console.log(`play notes: ${w}`);
1667
+ };
1668
+
1500
1669
  function registerDecide(gcf) {
1501
1670
  const ops = () => lib('work-ops');
1502
1671
  removeOptions(
@@ -2310,6 +2479,7 @@ export function register(program) {
2310
2479
  registerAudit(gcf);
2311
2480
  registerPlaytest(gcf);
2312
2481
  registerVerdict(gcf);
2482
+ registerPlayNotes(gcf);
2313
2483
  registerAnchor(gcf);
2314
2484
  registerSection(gcf);
2315
2485
  registerQuotes(gcf);
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.27.1",
4
+ "version": "0.29.0",
5
5
  "description": "Game Context Framework for AI Factory",
6
6
  "skills": [
7
7
  "skills/gcf-init",
@@ -227,6 +227,7 @@ export const DENY_GROUPS = [
227
227
  'ai-factory gcf playtest build*',
228
228
  'ai-factory gcf playtest start*',
229
229
  'ai-factory gcf playtest stop*',
230
+ 'ai-factory gcf playtest cancel*',
230
231
  ),
231
232
  },
232
233
  {
package/lib/audit-core.js CHANGED
@@ -18,6 +18,8 @@ import { inboxVocabulary } from './domain.js';
18
18
  import { gatePolicy, verdictDeferred } from './gates.js';
19
19
  import { milestoneState } from './milestone-state.js';
20
20
  import { mainWork } from './shelf.js';
21
+ import { playOnIssues } from './play-on.js';
22
+ import { platformsOf } from './playtest-list.js';
21
23
 
22
24
  function git(args, cwd) {
23
25
  // A blame of a long file overflows the 1 MiB default, and an overflow reads as a git failure.
@@ -69,6 +71,7 @@ function runningOf(projectDir, id) {
69
71
  * @property {boolean} index_drift
70
72
  * @property {Array<{id: string, status: string}>} illegal_status
71
73
  * @property {Array<{id: string, commits: number | null, limit: number}>} stale_questions
74
+ * @property {{errors: string[], warnings: string[]}} play_on cards' build names (lib/play-on.js)
72
75
  * @property {number} [schema]
73
76
  * @property {Array<{id: string, type: string, gate: string, status: string, system: string[],
74
77
  * depends: string[], parent: string | null, tune_count: number, parallel: string,
@@ -122,10 +125,10 @@ export async function audit(projectDir) {
122
125
  illegal_status: [],
123
126
  stale_questions: staleQuestions(projectDir, root, config),
124
127
  inbox: await inboxProblems(root, inboxVocabulary()),
128
+ play_on: playOnIssues(items, config, await platformsOf(root)),
125
129
  };
126
130
  // The harness gate reads everything from this one report — it never parses gcf/ itself.
127
- report.schema = config.schema;
128
- report.gates = config.gates;
131
+ Object.assign(report, { schema: config.schema, gates: config.gates });
129
132
  report.items = items.map((c) => ({
130
133
  id: c.data.id,
131
134
  type: c.data.type,
@@ -395,9 +398,16 @@ const docAlerts = (report) => [
395
398
  Object.keys(report.linter).length && 'П2 linter findings in systems docs',
396
399
  report.index_drift && 'INDEX drift (regenerate)',
397
400
  report.design?.blocking && `${report.design.blocking} blocking design finding(s)`,
401
+ ...playOnAlerts(report.play_on),
398
402
  ...inboxAlerts(report.inbox),
399
403
  ];
400
404
 
405
+ /** A card's play_on and played_on name builds (docs/Handoff-Plan.md d8). */
406
+ const playOnAlerts = (p) => [
407
+ p.errors.length && `${p.errors.length} play_on name(s) of no build`,
408
+ p.warnings.length && `${p.warnings.length} play_on line(s) of platforms: name builds (Set up)`,
409
+ ];
410
+
401
411
  /** Alerts about gcf/inbox/: the old one-line file, files that are no entry, broken pictures. */
402
412
  const inboxAlerts = (i) => [
403
413
  i.legacy &&
package/lib/board.js CHANGED
@@ -27,11 +27,12 @@ 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
+ import { itemBuilds, linksOf, playFacts } from './play.js';
31
+ import { handoffOf } from './handoff.js';
31
32
 
32
33
  // The version of the JSON below (Methodology §11): a board refuses one it does not know. Bump it
33
34
  // when a field changes meaning or goes away; a new field does not bump it.
34
- export const BOARD_SCHEMA = 4;
35
+ export const BOARD_SCHEMA = 5;
35
36
 
36
37
  /**
37
38
  * Plan progress `{tasks, done}` from its checkboxes and the plan's project path, both null
@@ -321,8 +322,15 @@ async function attachmentsOf(projectDir, id) {
321
322
  }
322
323
 
323
324
  /** One item of the board. */
325
+ /** `handoff` of a card that waits; nothing for any other. */
326
+ async function handoffPart(projectDir, id, read) {
327
+ const handoff = await handoffOf(projectDir, id, read);
328
+
329
+ return handoff ? { handoff } : {};
330
+ }
331
+
324
332
  async function itemOf(projectDir, c, { verified, shelved, ledger, harness, config, links }) {
325
- const build = buildOf(projectDir, String(c.data.id), c.data.status, links);
333
+ const builds = itemBuilds(projectDir, String(c.data.id), c.data.status, links);
326
334
  const id = String(c.data.id);
327
335
  // A trailer counts only while the item waits on main for its integrate.
328
336
  const ready = c.data.status === 'ready' && verified.has(id);
@@ -364,13 +372,15 @@ async function itemOf(projectDir, c, { verified, shelved, ledger, harness, confi
364
372
  running,
365
373
  verified: ready,
366
374
  harness,
367
- building: Boolean(build?.building),
375
+ building: builds.some((b) => b.building),
368
376
  }),
369
377
  file: `gcf/work/${c.name}`,
370
378
  ...(await attachmentsOf(projectDir, id)),
371
379
  log: logOf(projectDir, id),
372
- // Its build to play (docs/Play-Setup-Plan.md), null while it has none.
373
- build,
380
+ // Its builds to play, one per build and profile it has (docs/Handoff-Plan.md t17, schema 5).
381
+ builds,
382
+ // What a card that waits hands to the operator (docs/Handoff-Plan.md d4): read from its plan.
383
+ ...(await handoffPart(projectDir, id, { ledger, config, links })),
374
384
  // Filled by board() from the inbox.
375
385
  lessons: 0,
376
386
  ...(await progress(projectDir, c)),