gcf-aif-ext 0.27.0 → 0.28.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.
@@ -3,8 +3,9 @@ import { existsSync } from 'node:fs';
3
3
  import { readFile } from 'node:fs/promises';
4
4
  import path from 'node:path';
5
5
  import { gameMilestones } from './design-check.js';
6
- import { listItems, scalarOf, firstBullet } from './gcf-paths.js';
7
- import { buildOf, linksOf } from './play.js';
6
+ import { listItems, readConfig, scalarOf, firstBullet } from './gcf-paths.js';
7
+ import { buildOf, linksOf, playOf } from './play.js';
8
+ import { handoffOf } from './handoff.js';
8
9
  import { recordsOf } from './verdict-fs.js';
9
10
 
10
11
  const ENVELOPE = /^\S+\.\.\S+ /;
@@ -48,14 +49,28 @@ export async function platformsOf(root) {
48
49
  return existsSync(file) ? bulletsOf(await readFile(file, 'utf8'), 'platforms') : [];
49
50
  }
50
51
 
52
+ /** The build names of `play:`, or null with none (or a broken one: its own command says so). */
53
+ async function buildNames(root) {
54
+ try {
55
+ const play = playOf(await readConfig(root));
56
+
57
+ return play ? Object.keys(play.builds) : null;
58
+ } catch {
59
+ return null;
60
+ }
61
+ }
62
+
51
63
  /**
52
64
  * Playtest list (Methodology §5.3): every item waiting for its verdict, and every unplayed one,
53
65
  * with the question the play must answer, its milestone, where to play it (`play_on`, else every
54
- * line of `platforms`) and its build (lib/play.js), null while it has none.
66
+ * build of `play.builds`, else every line of `platforms`) and its build (lib/play.js), null while
67
+ * it has none.
55
68
  */
56
69
  export async function playtestList(root) {
57
70
  const platforms = await platformsOf(root);
58
71
  const links = linksOf(path.dirname(root));
72
+ // No play_on: every build of the project (docs/Handoff-Plan.md d8); no play: the old lines.
73
+ const builds = await buildNames(root);
59
74
 
60
75
  return (await listItems(root))
61
76
  .filter((c) => ['awaiting-verdict', 'unplayed'].includes(c.data.status))
@@ -65,7 +80,7 @@ export async function playtestList(root) {
65
80
  status: c.data.status,
66
81
  system: c.data.system ?? [],
67
82
  milestone: c.data.milestone ?? null,
68
- play_on: c.data.play_on ?? platforms,
83
+ play_on: c.data.play_on ?? builds ?? platforms,
69
84
  build: buildOf(path.dirname(root), String(c.data.id), c.data.status, links),
70
85
  question: scalarOf(c.body, 'miss_criterion') || '(miss_criterion is empty)',
71
86
  reach: recordsOf(c.body, 'behavior')
@@ -147,7 +162,10 @@ export async function playtestSession(projectDir) {
147
162
  };
148
163
  }),
149
164
  platforms: await platformsOf(root),
150
- items,
165
+ // Each waiting card with its handoff (docs/Handoff-Plan.md d4); an unplayed one has none.
166
+ items: await Promise.all(
167
+ items.map(async (i) => ({ ...i, handoff: await handoffOf(projectDir, i.id) })),
168
+ ),
151
169
  decisions: await decisionList(root),
152
170
  };
153
171
 
@@ -208,7 +208,7 @@ const RULES = {
208
208
  skip_gates: (v) => typeof v === 'boolean' || 'skip_gates must be true or false',
209
209
  gate_why: (v) => nullable(isText)(v) || 'gate_why must be text or null',
210
210
  play_on: (v) =>
211
- (Array.isArray(v) && v.every(isText)) || 'play_on must list lines of platforms in game.md',
211
+ (Array.isArray(v) && v.every(isText)) || 'play_on must list names of play.builds',
212
212
  version: (v) =>
213
213
  nullable((x) => typeof x === 'string' && /^\S+$/.test(x))(v) ||
214
214
  'version must be one word of text (quote a number: "1.0")',
package/lib/verify.js CHANGED
@@ -81,10 +81,13 @@ function stopChildren(doomed) {
81
81
  /**
82
82
  * Run `cmd` in a shell; past `ms` (0: never) it is killed with its whole tree. `exit`, not
83
83
  * `close`: a helper the command left running may hold the inherited stdio open.
84
+ * @returns {Promise<{status?: number | null, signal?: string | null, error?: Error,
85
+ * timedOut: boolean}> & {child: import('node:child_process').ChildProcess}}
84
86
  */
85
87
  export function runCommand(cmd, cwd, stdio, ms) {
86
- return new Promise((resolve) => {
87
- const child = spawn(cmd, { cwd, shell: true, stdio, env: commandEnv() });
88
+ let child;
89
+ const done = new Promise((resolve) => {
90
+ child = spawn(cmd, { cwd, shell: true, stdio, env: commandEnv() });
88
91
  let timedOut = false;
89
92
  const timer =
90
93
  ms > 0
@@ -102,6 +105,9 @@ export function runCommand(cmd, cwd, stdio, ms) {
102
105
  resolve({ status, signal, timedOut });
103
106
  });
104
107
  });
108
+
109
+ // The process too: a stop by the operator kills its tree (lib/build-queue.js).
110
+ return Object.assign(done, { child });
105
111
  }
106
112
 
107
113
  /** Run a `dod.<key>` command in the project; `none` says the project has no such step. */
package/lib/work-ops.js CHANGED
@@ -57,6 +57,7 @@ import { verdictDeferred } from './gates.js';
57
57
  import { appendQuestions, questionsFile } from './questions.js';
58
58
  import { refusal } from './refusal.js';
59
59
  import { releaseBuild } from './play.js';
60
+ import { playNotesCheck, playNotesOf, withoutPlayNotes } from './play-notes.js';
60
61
 
61
62
  /**
62
63
  * Options of a committed move; each move reads the ones it needs.
@@ -476,6 +477,28 @@ function dropOutcomeOf(m) {
476
477
  });
477
478
  }
478
479
 
480
+ /**
481
+ * A move back to `ready` takes the plan's `## Play notes` (docs/Handoff-Plan.md d3): the next
482
+ * submit must not carry the old handoff. `integrate` leaves it: the card waits with it.
483
+ */
484
+ function dropPlayNotesOf(m) {
485
+ const rel = m.item.data.plan ?? `.ai-factory/plans/${m.item.data.id}.md`;
486
+ const file = resolveInside(m.projectDir, rel);
487
+ if (!existsSync(file) || !playNotesOf(readFileSync(file, 'utf8'))) return;
488
+ m.touch(file);
489
+ m.step(async () => {
490
+ if (!existsSync(file)) return;
491
+ const text = await readFile(file, 'utf8');
492
+ const out = withoutPlayNotes(text);
493
+ if (out !== text) await atomicWrite(file, out);
494
+ });
495
+ }
496
+
497
+ /** What the card's handoff lacks, for a submit that leaves it waiting for a verdict. */
498
+ async function playNotesWarnings(m, played = true) {
499
+ return played ? (await playNotesCheck(m.projectDir, m.item)).warnings : [];
500
+ }
501
+
479
502
  /** A delta whose changes name no refs points at where the item's detail now lives. */
480
503
  function withRefs(delta, refs) {
481
504
  if (!delta || 'none' in delta || !refs) return delta;
@@ -747,8 +770,15 @@ async function submitItemUnlocked(projectDir, id, opts = {}) {
747
770
 
748
771
  const status = verdict ? 'awaiting-verdict' : 'awaiting-decision';
749
772
  const tail = `${id}${why ? ` → ${status} (${why})` : ''}${unverifiedTail(opts)}`;
773
+ // Read before the move: a warning, never a refusal (d3); a decision has no play.
774
+ const warnings = await playNotesWarnings(m, verdict);
750
775
 
751
- return { id, status, hash: await finish(m, 'submit', tail, commit) };
776
+ return {
777
+ id,
778
+ status,
779
+ hash: await finish(m, 'submit', tail, commit),
780
+ play_notes_warnings: warnings,
781
+ };
752
782
  }
753
783
 
754
784
  /**
@@ -822,8 +852,10 @@ async function closeItemUnlocked(projectDir, id, opts = {}) {
822
852
  // The item waits now: the move is a submit's, as the integrator and the history read it.
823
853
  const why = `modifies ${changes.join(', ')}`;
824
854
  const tail = `${id} → awaiting-verdict (${why})${unverifiedTail(opts)}`;
855
+ const warnings = await playNotesWarnings(m);
856
+ const hash = await finish(m, 'submit', tail, commit);
825
857
 
826
- return { id, hash: await finish(m, 'submit', tail, commit), unplayed: false, awaits: why };
858
+ return { id, hash, unplayed: false, awaits: why, play_notes_warnings: warnings };
827
859
  }
828
860
 
829
861
  const tail = `${id}${unplayed ? ' → unplayed' : ''}${unverifiedTail(opts)}`;
@@ -882,6 +914,7 @@ async function tune(m, note) {
882
914
  since: null,
883
915
  };
884
916
  m.step(() => writeItem(item, data, body));
917
+ dropPlayNotesOf(m);
885
918
  }
886
919
 
887
920
  /**
@@ -1102,6 +1135,7 @@ const DECIDE = {
1102
1135
  close: (m) => closeFeature(m) ?? null,
1103
1136
  continue: (m) => {
1104
1137
  m.step(() => writeItem(m.item, { ...m.item.data, status: 'ready' }));
1138
+ dropPlayNotesOf(m);
1105
1139
 
1106
1140
  return null;
1107
1141
  },
@@ -1176,6 +1210,7 @@ async function unblockItemUnlocked(projectDir, id, opts = {}) {
1176
1210
  since: waits ? headHash(projectDir) : null,
1177
1211
  };
1178
1212
  m.step(() => writeItem(m.item, data, body));
1213
+ if (!waits) dropPlayNotesOf(m);
1179
1214
 
1180
1215
  return { id, hash: await finish(m, 'unblock', id, commit) };
1181
1216
  }
@@ -1302,6 +1337,7 @@ async function amendItemUnlocked(projectDir, id, opts = {}) {
1302
1337
  if (entry) carryEntry(m, entry, commit);
1303
1338
  const data = newCycle(asked.title ? { ...m.item.data, title } : m.item.data);
1304
1339
  m.step(() => writeItem(m.item, data, body));
1340
+ if (m.item.data.status === 'ready') dropPlayNotesOf(m);
1305
1341
 
1306
1342
  return { id, changes, hash: await finish(m, 'amend', id, commit) };
1307
1343
  }
@@ -1356,6 +1392,7 @@ async function answerStallUnlocked(projectDir, id, { more, accept = false, commi
1356
1392
  stall: answered,
1357
1393
  };
1358
1394
  m.step(() => writeItem(m.item, data));
1395
+ dropPlayNotesOf(m);
1359
1396
 
1360
1397
  return { id, stall: answered, hash: await finish(m, move, id, commit) };
1361
1398
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-aif-ext",
3
- "version": "0.27.0",
3
+ "version": "0.28.0",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -36,7 +36,9 @@ workflow:
36
36
  10. run `npx --yes cnlp-kit check` (it covers the systems docs and PILLARS of `cnlp.config.json` and `GLOSSARY.md`, not design units), then `ai-factory gcf lint` over each new systems doc, then `ai-factory gcf index`
37
37
  11. ask the human to run `ai-factory gcf hooks-install`; when it refuses over a foreign pre-commit, hand them the chain line it prints
38
38
  12. when the project says how its game builds and starts, ask the human to record it with `ai-factory gcf playtest setup`: an output folder git ignores, and a target per place to play
39
- 13. state the next step: an old design document goes through `/gcf-ingest` into `gcf/design/`, new work starts at `/gcf-card`
39
+ 13. with it, the rows the build plays on from the `platforms` of `gcf/game.md`: `--plays-on "{ device: phone, os: android, os_min: 10 }"`, one per row
40
+ 14. each target names the rows it serves (`--for`), its `--devices` script, and `--launches` when it installs and ends
41
+ 15. state the next step: an old design document goes through `/gcf-ingest` into `gcf/design/`, new work starts at `/gcf-card`
40
42
 
41
43
  invocation:
42
44
  - run once, when a project that already has code adopts GCF
@@ -37,6 +37,7 @@ outputs:
37
37
  - every item carries a `live:` delta before it ends: what it adds, modifies or removes in `gcf/LIVE.md`, or `none: <why>`
38
38
  - a mechanic or resource with a milestone carries `gate: auto`: it closes unplayed, and the human plays it with its milestone
39
39
  - `gate: verdict` on such an item carries `gate_why:`: the rest is built on its feel - input, controls, camera, the core verb
40
+ - give `gate: verdict` to a sizeable piece of work with something to try; a small card gets `gate: auto`, and the human plays it later with the next verdict card or its milestone
40
41
 
41
42
  workflow:
42
43
  1. for a free-text design idea: ask "into work now, or park it?"; `ai-factory gcf design save --kind unit --system <s> --type <t> --title "<title>" --fields-file -`, `{}` on stdin, writes it with `TBD` slots and prints its id; on "park" stop here
@@ -55,10 +55,13 @@ workflow:
55
55
  10. a move the human asks for, or one the talk shows is due, that has a `propose_<move>` tool: call it with the `id` of the item, inbox entry or question it acts on, and say why in one line; name an item by its title with the id in brackets
56
56
  11. a kill, a no or a wontfix: its reason is the human's words; the graveyard keeps it, and the move does not go without it
57
57
  12. an open D1 question the talk answers: call `propose_question_answer` with its id and the human's words, or your draft when the human asks for one
58
- 13. an item to play: say from the context file whether its build exists, of which commit, and where it plays; call `propose_play` with its `id` and a `target`: the human's click starts it and opens it, and the verdict stops it
59
- 14. the context file says no `play:` is set up and the project's `AGENTS.md` says how the game builds and starts: call `propose_play_setup` with those commands; say what is missing when it does not say
60
- 15. another move the human asks for: run its `ai-factory gcf` command; the human approves it on the card, or refuses it
61
- 16. say in one line what changed, or that nothing did
58
+ 13. an item to play: read its handoff (`ai-factory gcf item show <id>`, or `handoff` in the context file); say its main question, what to try, and which row of Play by platform is ready
59
+ 14. then call `propose_play` with its `id`, a `target` and, for a target with devices, the `device` id: the human's click starts it and opens it, and the verdict stops it
60
+ 15. the context file says no `play:` is set up and the project's `AGENTS.md` says how the game builds and starts: call `propose_play_setup` with those commands; say what is missing when it does not say
61
+ 16. a Set up pass over a `play:` with no `plays_on`: propose `play.builds` with rows from the `platforms` of `gcf/game.md`, and targets with `build`, `for`, `devices` and `launches`
62
+ 17. in that pass, turn each line of platforms in a card's `play_on` and `played_on` into the name of its build
63
+ 18. another move the human asks for: run its `ai-factory gcf` command; the human approves it on the card, or refuses it
64
+ 19. say in one line what changed, or that nothing did
62
65
 
63
66
  invocation:
64
67
  - run at the start of a project chat thread the board opens, and when the user types `/gcf-chat`
@@ -33,7 +33,7 @@ workflow:
33
33
  3. for `tune` at the tune limit (`tune_limit` in `gcf/config.yml`, 3 by default): the command refuses; the way out is a kill, and a redesigned envelope becomes a new item with `reopens: <id>`
34
34
  4. for `keep` of a design-unit item still awaiting its verdict: compress it first - the collapse copies lines verbatim, 1 line per behavior record, refusal and boundary
35
35
  5. for that keep: strip `contract:` down to paths and entry points and cut `intent:` to the line the subsystem's purpose still lacks; leave an unplayed item as it is - its close froze the body
36
- 6. run `ai-factory gcf verdict <id> <verdict> --note "<answer>"`, with `--played-on "<line>"` per line of `platforms` the human played on; a kill makes a removal item for code in main unless `--no-remove`
36
+ 6. run `ai-factory gcf verdict <id> <verdict> --note "<answer>"`, with `--played-on <build>` per build of `play.builds` the human played on; a kill makes a removal item for code in main unless `--no-remove`
37
37
  7. for a decision run `ai-factory gcf decide <id> <choice> --reason "<why>"`; `known` parks a bug and lists it in `gcf/LIVE.md` known issues
38
38
  8. for a feature whose child died, the human picks: `close` without the child, `continue` with a replacement, or `kill` with its live children
39
39
  9. for `keep` on an item touching 2 or more subsystems: read each updated systems doc and report a contradiction between constraints as a D1 question instead of finishing silently
@@ -31,6 +31,10 @@ gcf_work:
31
31
  - the second form: `live:` with `changes:`, a list of `{id: <capability slug>, change: added | modified | removed, summary: "<at most two sentences>"}` (a removed one needs no summary)
32
32
  - before `submit` or `close`, tick every task of the item's plan that is done, the verify and the review included: both refuse a plan with unticked tasks; `--unticked "<why>"` is the human's call, never the agent's
33
33
  - `submit` and `close` refuse code that changed since its last green `gcf verify`: run it again after any fix; `--unverified "<why>"` is the human's call, never the agent's
34
+ - before the commit that ends a gate-verdict item, write `## Play notes` into its plan from `ai-factory gcf play-notes <id> --template`, in main and in a worktree alike
35
+ - its sections: `### Question` (notes under the card's `miss_criterion`), `### Try`, `### Rows` (a line per row the template lists: `- <build> <device> [os]: <note>`), `### Watch out`, `### Notes`
36
+ - the fields for the player say what is seen and what to do in the game, never how to start it, no hashes, no paths, no commands: those go to `### Notes`
37
+ - `submit` names what the notes lack as warnings; a move back to `ready` takes them out of the plan
34
38
  - then end the work on the item with its command: `ai-factory gcf submit <id>` for gate verdict or decision, `ai-factory gcf close <id>` for gate auto
35
39
  - work that cannot go on: run `ai-factory gcf block <id> --reason "<why or the question>"`
36
40
  - in a worktree on branch `work/<id>` change no `gcf/` file but the item's `live:` and new inbox entries, commit all, then run `ai-factory gcf verify <id> --mark`: `ai-factory gcf integrate` in the main checkout merges it and records the move
@@ -43,7 +47,12 @@ gcf_work:
43
47
  - with `play:` in `gcf/config.yml` the harness builds a card that waits for its verdict at the end of its run, into `.gcf-session/snaps/`, where later work does not touch it
44
48
  - a build is one per code: cards on the same code share it, and a verdict removes it only when no other card holds it
45
49
  - the board's Play button builds the card when it has no build yet, then starts it on a target of `play:`; the card's verdict stops its player
46
- - Play main does the same for the checkout as it is, hand edits too; `ai-factory gcf playtest status` names the targets and the running player
50
+ - Play main does the same for the checkout as it is, hand edits too; `ai-factory gcf playtest status` names the targets, the running player and the build queue
51
+ - `ai-factory gcf item show <id>` prints a waiting card's handoff: its outcome, its main question, Play by platform, what changed, what to try, what waits for the human
52
+ - `play.builds` names the builds of the project, each with its command, its output and the rows it `plays_on` (`device`, `os`, `os_min`, `model`, `input`)
53
+ - a target names its `build`, the rows it serves (`for`), its `devices` script, and `launches: true` when it installs and ends
54
+ - `ai-factory gcf playtest devices <target>` lists the devices its script finds and why one does not fit; `playtest start <id> --target <t> --device <id>` plays on one
55
+ - a build while a run works in the checkout waits on a ticket: `playtest build <id> --wait` waits in its process, `--queue` prints `{ticket}` and ends; `ai-factory gcf playtest cancel <ticket>` takes it out or stops it
47
56
  - how the game builds and starts is the human's to accept: find it in the project (this file, its build and serve scripts) and propose it with `propose_play_setup`
48
57
  - do not ask the human for the build or start commands: the project holds them
49
58
  - a project with no command that builds into a folder git ignores, or none that starts it from there, gets a tech card from you that adds both and names them here
@@ -53,8 +62,9 @@ gcf_work:
53
62
  - an item's milestone (`item new --milestone <name>`) is a `name` of the `milestones` in `gcf/game.md`, as a unit's: `item new` refuses another; a new milestone is a change of the vision, for the human (the gcf-vision skill)
54
63
  - a milestone is a slice of the game the human plays as one, in `gcf/game.md`'s order
55
64
  - a mechanic or resource with a milestone gets `gate: auto` and closes unplayed, and the human plays it with the milestone
65
+ - give `gate: verdict` to a card with something to try, a sizeable piece of work; a small card gets `gate: auto`, and the human plays it later with others
56
66
  - a feature and a taken soft unit need a milestone while `gcf/game.md` lists milestones (`take --milestone <name>`)
57
- - the lines of `platforms` in `gcf/game.md` are where the human can play the game; an item may narrow them in `play_on:`; they are a hint for the human, never a condition of a move
67
+ - the lines of `platforms` in `gcf/game.md` are the game's intent in words; an item's `play_on:` and a verdict's `--played-on` name builds of `play.builds`; `ai-factory gcf audit` names one of no build
58
68
  - the stops that wait for the human are the `gates:` of `gcf/config.yml` (`milestone`, `verdict`, `decision`, `question`) and each card's `skip_gates:`, both the human's (`config set`, `item gates`); the core applies them itself
59
69
  - the board's autopilot starts the runs and the card sessions (`ai-factory gcf-harness card`) by itself and stops when a milestone is built for the human to play; an agent starts neither
60
70
  - `ai-factory gcf-harness hold <id>` and `hold --project` are the human's: a held session hands over at its next call, and an agent holds nothing