gcf-aif-ext 0.24.0 → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,9 +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, readConfig, firstBullet } from './gcf-paths.js';
6
+ import { listItems, scalarOf, firstBullet } from './gcf-paths.js';
7
+ import { buildOf, linksOf } from './play.js';
7
8
  import { recordsOf } from './verdict-fs.js';
8
- import { runDod } from './verify.js';
9
9
 
10
10
  const ENVELOPE = /^\S+\.\.\S+ /;
11
11
 
@@ -50,11 +50,12 @@ export async function platformsOf(root) {
50
50
 
51
51
  /**
52
52
  * Playtest list (Methodology §5.3): every item waiting for its verdict, and every unplayed one,
53
- * with the question the play must answer, its milestone and where to play it (`play_on`, else
54
- * every line of `platforms`).
53
+ * 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.
55
55
  */
56
56
  export async function playtestList(root) {
57
57
  const platforms = await platformsOf(root);
58
+ const links = linksOf(path.dirname(root));
58
59
 
59
60
  return (await listItems(root))
60
61
  .filter((c) => ['awaiting-verdict', 'unplayed'].includes(c.data.status))
@@ -65,6 +66,7 @@ export async function playtestList(root) {
65
66
  system: c.data.system ?? [],
66
67
  milestone: c.data.milestone ?? null,
67
68
  play_on: c.data.play_on ?? platforms,
69
+ build: buildOf(path.dirname(root), String(c.data.id), c.data.status, links),
68
70
  question: scalarOf(c.body, 'miss_criterion') || '(miss_criterion is empty)',
69
71
  reach: recordsOf(c.body, 'behavior')
70
72
  .map((r) => r.input)
@@ -94,14 +96,11 @@ const git = (projectDir, args) => {
94
96
  };
95
97
 
96
98
  /**
97
- * `playtest session` (Methodology §5.3): one build of main and the checklist of everything that
99
+ * `playtest session` (Methodology §5.3): where main stands and the checklist of everything that
98
100
  * waits for play, grouped by subsystem — built from the items on every call, no file of its own.
99
- * `build` runs the project's `dod.build` first.
101
+ * Each item names its own build (lib/play.js).
100
102
  */
101
- export async function playtestSession(
102
- projectDir,
103
- { build = false, stdio = ['ignore', 2, 2] } = {},
104
- ) {
103
+ export async function playtestSession(projectDir) {
105
104
  const root = path.join(path.resolve(projectDir), 'gcf');
106
105
  const milestones = (await gameMilestones(root)) ?? [];
107
106
  // Milestones in game.md's order, then the items with none (or one game.md no longer has).
@@ -132,7 +131,6 @@ export async function playtestSession(
132
131
  commit: git(projectDir, ['rev-parse', '--short', 'HEAD']),
133
132
  // No commit (no repository, or none yet): the build is unknown, not clean.
134
133
  dirty: dirty === null ? null : Boolean(dirty),
135
- build: /** @type {Awaited<ReturnType<typeof runDod>> | null} */ (null),
136
134
  // Each milestone with something to play: its goal, the question its play answers, and how
137
135
  // much of it is still being built or blocked.
138
136
  milestones: milestones
@@ -152,7 +150,6 @@ export async function playtestSession(
152
150
  items,
153
151
  decisions: await decisionList(root),
154
152
  };
155
- if (build) session.build = await runDod(projectDir, await readConfig(root), 'build', stdio);
156
153
 
157
154
  return session;
158
155
  }
package/lib/safe-path.js CHANGED
@@ -32,7 +32,7 @@ const BUSY = new Set(['EPERM', 'EACCES', 'EBUSY']);
32
32
  // The board's writeAtomicSync budget: a scan of a fresh file often outlasts 200 ms.
33
33
  const RENAME_TRIES = 10;
34
34
 
35
- async function renameRetrying(from, to) {
35
+ export async function renameRetrying(from, to) {
36
36
  for (let attempt = 1; ; attempt++) {
37
37
  try {
38
38
  return await rename(from, to);
@@ -40,6 +40,10 @@ const FROM = {
40
40
  gates: STORED,
41
41
  // Nor a fix of its text; only an unplayed body is frozen (§5.4).
42
42
  amend: STORED.filter((s) => s !== 'unplayed'),
43
+ // Planning that does not converge (Hold-Plan d16): the run stalls it, the operator decides.
44
+ plan_stall: ['ready'],
45
+ plan_more: ['blocked'],
46
+ plan_accept: ['blocked'],
43
47
  };
44
48
 
45
49
  /** Every move an item may be offered, in the board's order. */
@@ -62,10 +66,13 @@ export const decisionFits = (choice, type) =>
62
66
  (!BUG_ONLY.includes(choice) || type === 'bug');
63
67
 
64
68
  /** Whether a move fits the item beyond its status: its gate for submit and close, its type. */
65
- function fits(move, { type, gate }) {
69
+ function fits(move, { type, gate, stall }) {
66
70
  const [cmd, arg] = move.split(':');
67
71
  if (cmd === 'submit') return gate !== 'auto';
68
72
  if (cmd === 'close') return gate === 'auto';
73
+ // The run's stall is no move a board offers; the operator's answers only to a stall.
74
+ if (cmd === 'plan_stall') return false;
75
+ if (cmd === 'plan_more' || cmd === 'plan_accept') return Boolean(stall);
69
76
 
70
77
  return cmd !== 'decide' || decisionFits(arg, type);
71
78
  }
@@ -68,6 +68,8 @@ const FIELDS = [
68
68
  'priority',
69
69
  'plan',
70
70
  'tune_count',
71
+ 'plan_cycle',
72
+ 'stall',
71
73
  'severity',
72
74
  'blocked',
73
75
  'since',
@@ -120,6 +122,28 @@ function changeProblem(c) {
120
122
  }
121
123
 
122
124
  /** A live: delta (Methodology §8): `{none: <why>}` or `{changes: [{id, change, summary}]}`. */
125
+ /**
126
+ * What is wrong with an item's `stall:` (Hold-Plan d16), or null: `{passes, reason?, more?,
127
+ * accepted?}`, the blocking counts of each pass, the operator's extra passes or their yes.
128
+ */
129
+ function stallProblem(v) {
130
+ const count = (n) => Number.isInteger(n) && n >= 0;
131
+ const keys = { passes: (x) => Array.isArray(x) && x.every(count) };
132
+ const optional = {
133
+ reason: (x) => typeof x === 'string',
134
+ more: (x) => count(x) && x >= 1,
135
+ accepted: (x) => x === true,
136
+ };
137
+ const ok =
138
+ v !== null &&
139
+ typeof v === 'object' &&
140
+ !Array.isArray(v) &&
141
+ keys.passes(v.passes) &&
142
+ Object.entries(v).every(([k, x]) => k === 'passes' || optional[k]?.(x));
143
+
144
+ return ok ? null : 'stall must be {passes: [counts], reason?, more?: n >= 1, accepted?: true}';
145
+ }
146
+
123
147
  export function liveProblem(v) {
124
148
  if (v === null || v === undefined) return null;
125
149
  if (typeof v !== 'object' || Array.isArray(v)) return LIVE_SHAPE;
@@ -169,6 +193,8 @@ const RULES = {
169
193
  'priority must be a rank, an integer >= 1 (lower runs sooner), or null',
170
194
  plan: (v) => nullable(isText)(v) || 'plan must be a path or null',
171
195
  tune_count: (v) => (Number.isInteger(v) && v >= 0) || 'tune_count must be an integer >= 0',
196
+ plan_cycle: (v) => (Number.isInteger(v) && v >= 1) || 'plan_cycle must be an integer >= 1',
197
+ stall: (v) => stallProblem(v) ?? true,
172
198
  severity: (v) =>
173
199
  nullable((x) => SEVERITIES.includes(x))(v) || `severity must be ${SEVERITIES.join(' | ')}`,
174
200
  blocked: (v) => nullable(isText)(v) || 'blocked must be text or null',
package/lib/verify.js CHANGED
@@ -51,7 +51,7 @@ const signal = (p, sig) => {
51
51
  * shortcut: a grandchild whose parent exited before the walk is init's and is not found; a
52
52
  * process group of its own per command would catch it, at the cost of the harness's group kill.
53
53
  */
54
- function killTree(pid) {
54
+ export function killTree(pid) {
55
55
  if (process.platform === 'win32') {
56
56
  spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
57
57
 
@@ -81,7 +81,7 @@ function stopChildren(doomed) {
81
81
  * Run `cmd` in a shell; past `ms` (0: never) it is killed with its whole tree. `exit`, not
82
82
  * `close`: a helper the command left running may hold the inherited stdio open.
83
83
  */
84
- function runCommand(cmd, cwd, stdio, ms) {
84
+ export function runCommand(cmd, cwd, stdio, ms) {
85
85
  return new Promise((resolve) => {
86
86
  const child = spawn(cmd, { cwd, shell: true, stdio });
87
87
  let timedOut = false;
@@ -118,7 +118,7 @@ export async function runDod(projectDir, config, key, stdio) {
118
118
  // stdin is closed; a command that never ends (a hung engine, a watch mode) meets the timeout.
119
119
  const minutes = config.dod_timeout_min ?? 0;
120
120
  const problem = failureOf(
121
- key,
121
+ `dod.${key}`,
122
122
  cmd,
123
123
  minutes,
124
124
  await runCommand(cmd, projectDir, stdio, minutes * 60000),
@@ -127,14 +127,14 @@ export async function runDod(projectDir, config, key, stdio) {
127
127
  return { name: key, ok: !problem, problems: problem ? [problem] : [] };
128
128
  }
129
129
 
130
- /** Why a finished DoD command failed, or null when it passed. */
131
- function failureOf(key, cmd, minutes, res) {
130
+ /** Why a finished command of the project's failed, or null when it passed. */
131
+ export function failureOf(name, cmd, minutes, res) {
132
132
  if (res.timedOut)
133
- return `dod.${key} timed out after ${minutes} min (dod_timeout_min), killed: ${cmd}`;
133
+ return `${name} timed out after ${minutes} min (dod_timeout_min), killed: ${cmd}`;
134
134
  if (res.status === 0) return null;
135
135
  const why = res.error ? res.error.message : `exit ${res.status ?? res.signal}`;
136
136
 
137
- return `dod.${key} failed (${why}): ${cmd}`;
137
+ return `${name} failed (${why}): ${cmd}`;
138
138
  }
139
139
 
140
140
  /**
package/lib/work-ops.js CHANGED
@@ -56,6 +56,7 @@ import {
56
56
  import { verdictDeferred } from './gates.js';
57
57
  import { appendQuestions, questionsFile } from './questions.js';
58
58
  import { refusal } from './refusal.js';
59
+ import { releaseBuild } from './play.js';
59
60
 
60
61
  /**
61
62
  * Options of a committed move; each move reads the ones it needs.
@@ -273,10 +274,16 @@ async function finish(m, key, tail, commit) {
273
274
  // Its work is committed: what still lies loose is no longer the card's to carry.
274
275
  if (move === 'submit' || move === 'close') leaveFolder(m.projectDir, String(m.item.data.id));
275
276
  for (const fn of m.ran) fn();
277
+ // Its play has ended: the player stops and the snapshot goes. It never undoes the move.
278
+ if (move === 'verdict' || move === 'drop')
279
+ m.buildLeft = releaseBuild(m.projectDir, String(m.item.data.id));
276
280
 
277
281
  return hash;
278
282
  }
279
283
 
284
+ /** A snapshot its move could not delete: the report names it, a later sweep repeats it. */
285
+ const buildLeft = (m) => (m.buildLeft ? { build_left: m.buildLeft } : {});
286
+
280
287
  /** A card's work waits on its branch: it has to come back before it can be judged. */
281
288
  function needInFolder(m, item = m.item) {
282
289
  const id = String(item.data.id);
@@ -869,7 +876,7 @@ async function tune(m, note) {
869
876
  if (item.data.status === 'unplayed') unplay(m, item);
870
877
  const body = note ? await upsertItemNote(item, 'tuning', note) : item.body;
871
878
  const data = {
872
- ...without(item.data, 'frozen'),
879
+ ...newCycle(without(item.data, 'frozen')),
873
880
  status: 'ready',
874
881
  tune_count: tunes + 1,
875
882
  since: null,
@@ -877,6 +884,15 @@ async function tune(m, note) {
877
884
  m.step(() => writeItem(item, data, body));
878
885
  }
879
886
 
887
+ /**
888
+ * The card back to planning (Hold-Plan d12): a new planning cycle, so the passes before it no
889
+ * longer count, and the operator's answer to an old stall goes with them.
890
+ */
891
+ const newCycle = (data) => ({
892
+ ...without(data, 'stall'),
893
+ plan_cycle: Number(data.plan_cycle ?? 0) + 1,
894
+ });
895
+
880
896
  /** keep | tune | kill on an item waiting for its verdict or unplayed (Methodology §5.4).
881
897
  * @param {MoveOpts} [opts]
882
898
  */
@@ -894,7 +910,7 @@ async function verdictItemUnlocked(projectDir, id, verdict, opts = {}) {
894
910
  const tail = `${verdict} ${id} → ${systems.join(',')}${played}`;
895
911
  const hash = await finish(m, `verdict:${verdict}`, tail, commit);
896
912
 
897
- return { verdict, id, systems, hash, removal };
913
+ return { verdict, id, systems, hash, removal, ...buildLeft(m) };
898
914
  }
899
915
 
900
916
  // What a milestone's keep may write: gcf/ as the gate reads it (no .metrics, which audit and
@@ -1018,8 +1034,9 @@ async function keepMilestoneUnlocked(projectDir, name, opts = {}) {
1018
1034
  const message = `gcf(verdict): keep ${name} → ${order.join(', ')}${played}`;
1019
1035
  const hash = commitPaths(projectDir, message, files, { key: 'verdict:keep', items: order });
1020
1036
  for (const id of order) clearCard(projectDir, id);
1037
+ const left = order.map((id) => releaseBuild(projectDir, id)).filter(Boolean);
1021
1038
 
1022
- return { milestone: name, ids: order, hash };
1039
+ return { milestone: name, ids: order, hash, ...(left.length ? { build_left: left } : {}) };
1023
1040
  } catch (e) {
1024
1041
  // Nothing kept: what the keep wrote back to HEAD (staged or not); the pack's own files keep
1025
1042
  // the operator's edits on disk and in the index as they were.
@@ -1154,7 +1171,7 @@ async function unblockItemUnlocked(projectDir, id, opts = {}) {
1154
1171
  const childDied = / child \S+ died/.test(String(m.item.data.blocked ?? ''));
1155
1172
  const waits = m.item.data.type === 'feature' && childDied;
1156
1173
  const data = {
1157
- ...without(m.item.data, 'blocked'),
1174
+ ...newCycle(without(m.item.data, 'blocked')),
1158
1175
  status: waits ? 'awaiting-decision' : 'ready',
1159
1176
  since: waits ? headHash(projectDir) : null,
1160
1177
  };
@@ -1283,12 +1300,66 @@ async function amendItemUnlocked(projectDir, id, opts = {}) {
1283
1300
  if (dryRun) return { id, base: amendBase(m.item), title, text: amendableText(body), changes };
1284
1301
  refuseAmendPointless(m.item, { asked, base: opts.base, changes, entry });
1285
1302
  if (entry) carryEntry(m, entry, commit);
1286
- const data = asked.title ? { ...m.item.data, title } : m.item.data;
1303
+ const data = newCycle(asked.title ? { ...m.item.data, title } : m.item.data);
1287
1304
  m.step(() => writeItem(m.item, data, body));
1288
1305
 
1289
1306
  return { id, changes, hash: await finish(m, 'amend', id, commit) };
1290
1307
  }
1291
1308
 
1309
+ /**
1310
+ * The run's stop of planning that does not converge (Hold-Plan d16): blocked, with the blocking
1311
+ * counts of its passes kept in `stall`, for the operator's "more passes" or "implement as is".
1312
+ * @param {string} projectDir
1313
+ * @param {string} id
1314
+ * @param {{passes: number[], reason?: string, commit?: boolean}} opts
1315
+ */
1316
+ async function stallItemUnlocked(projectDir, id, { passes, reason = '', commit = true }) {
1317
+ if (
1318
+ !Array.isArray(passes) ||
1319
+ !passes.length ||
1320
+ !passes.every((n) => Number.isInteger(n) && n >= 0)
1321
+ )
1322
+ throw new Error('--passes is the blocking count of each pass, e.g. 7,3,2,1');
1323
+ const m = await begin(projectDir, id, 'plan_stall');
1324
+ const why = String(reason).trim();
1325
+ // The operator's extra passes of this cycle stay: a second stall counts past them (review 3).
1326
+ const more = m.item.data.stall?.more;
1327
+ const stall = { passes, ...(why ? { reason: why } : {}), ...(more ? { more } : {}) };
1328
+ const blocked = `planning does not converge · ${passes.join(', ')}${why ? `: ${why}` : ''}`;
1329
+ const data = { ...m.item.data, status: 'blocked', blocked, since: headHash(projectDir), stall };
1330
+ m.step(() => writeItem(m.item, data));
1331
+
1332
+ return { id, stall, hash: await finish(m, 'plan_stall', id, commit) };
1333
+ }
1334
+
1335
+ /**
1336
+ * The operator's answer to a stall (Hold-Plan d16): `more` passes past the limit, or `accept`
1337
+ * the plan as it is; the card goes back to ready, its stall kept with the answer.
1338
+ * @param {string} projectDir
1339
+ * @param {string} id
1340
+ * @param {{more?: number, accept?: boolean, commit?: boolean}} opts
1341
+ */
1342
+ async function answerStallUnlocked(projectDir, id, { more, accept = false, commit = true }) {
1343
+ const move = accept ? 'plan_accept' : 'plan_more';
1344
+ if (!accept && !(Number.isInteger(more) && more >= 1))
1345
+ throw new Error('more passes: a number, 1 or more');
1346
+ const m = await begin(projectDir, id, move);
1347
+ const stall = m.item.data.stall;
1348
+ if (!stall) throw new Error(`${id} is not stalled in planning: nothing to answer`);
1349
+ const answered = accept
1350
+ ? { ...stall, accepted: true }
1351
+ : { ...stall, more: Number(stall.more ?? 0) + more };
1352
+ const data = {
1353
+ ...without(m.item.data, 'blocked'),
1354
+ status: 'ready',
1355
+ since: null,
1356
+ stall: answered,
1357
+ };
1358
+ m.step(() => writeItem(m.item, data));
1359
+
1360
+ return { id, stall: answered, hash: await finish(m, move, id, commit) };
1361
+ }
1362
+
1292
1363
  /** What a fix asks for, trimmed: a blank field is none, an over-long or broken one refused. */
1293
1364
  function amendAsked(opts) {
1294
1365
  const [text, add, title, from] = [opts.text, opts.add, opts.title, opts.from].map((v) =>
@@ -1352,7 +1423,9 @@ async function dropItemUnlocked(projectDir, id, opts = {}) {
1352
1423
  : codeInMain(projectDir, m.item);
1353
1424
  const removal = endToGraveyard(m, m.item, { reason, tags, removal: remove ?? shipped });
1354
1425
 
1355
- return { id, hash: await finish(m, 'drop', id, commit), removal };
1426
+ const hash = await finish(m, 'drop', id, commit);
1427
+
1428
+ return { id, hash, removal, ...buildLeft(m) };
1356
1429
  }
1357
1430
 
1358
1431
  /** The version and channel of a new item: well-formed, and only on a release. */
@@ -1909,6 +1982,12 @@ export const decideItem = (projectDir, id, choice, opts = {}) =>
1909
1982
  /** @type {typeof blockItemUnlocked} */
1910
1983
  export const blockItem = (projectDir, id, opts = {}) =>
1911
1984
  locked(projectDir, opts.commit ?? true, () => blockItemUnlocked(projectDir, id, opts));
1985
+ /** @type {typeof stallItemUnlocked} */
1986
+ export const stallItem = (projectDir, id, opts) =>
1987
+ locked(projectDir, opts.commit ?? true, () => stallItemUnlocked(projectDir, id, opts));
1988
+ /** @type {typeof answerStallUnlocked} */
1989
+ export const answerStall = (projectDir, id, opts) =>
1990
+ locked(projectDir, opts.commit ?? true, () => answerStallUnlocked(projectDir, id, opts));
1912
1991
  /** @type {typeof unblockItemUnlocked} */
1913
1992
  export const unblockItem = (projectDir, id, opts = {}) =>
1914
1993
  locked(projectDir, opts.commit ?? true, () => unblockItemUnlocked(projectDir, id, opts));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-aif-ext",
3
- "version": "0.24.0",
3
+ "version": "0.26.0",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -55,6 +55,18 @@
55
55
  "parallel": { "enum": ["ok", "serial"] },
56
56
  "plan": { "$ref": "#/definitions/textOrNull" },
57
57
  "tune_count": { "type": "integer", "minimum": 0 },
58
+ "plan_cycle": { "type": "integer", "minimum": 1 },
59
+ "stall": {
60
+ "type": "object",
61
+ "additionalProperties": false,
62
+ "required": ["passes"],
63
+ "properties": {
64
+ "passes": { "type": "array", "items": { "type": "integer", "minimum": 0 } },
65
+ "reason": { "type": "string" },
66
+ "more": { "type": "integer", "minimum": 1 },
67
+ "accepted": { "const": true }
68
+ }
69
+ },
58
70
  "severity": {
59
71
  "anyOf": [{ "type": "null" }, { "enum": ["critical", "high", "medium", "low"] }]
60
72
  },
@@ -35,7 +35,8 @@ workflow:
35
35
  9. draft `PILLARS.md` by the interview in the `gcf-init` skill, steps 4..8, and do not restate that interview here
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
- 12. state the next step: an old design document goes through `/gcf-ingest` into `gcf/design/`, new work starts at `/gcf-card`
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
40
 
40
41
  invocation:
41
42
  - run once, when a project that already has code adopts GCF
@@ -14,7 +14,7 @@ purpose:
14
14
 
15
15
  inputs:
16
16
  - the human's messages, one turn each
17
- - the thread's context file when the thread is bound to an item: the paths of the item's file, its plan, its run's log and run chat, its commits
17
+ - the thread's context file when the thread is bound to an item: the paths of the item's file, its plan, its run's log and run chat, its commits, its build to play
18
18
 
19
19
  preconditions:
20
20
  - `gcf/` exists and `ai-factory gcf board --json` runs
@@ -38,6 +38,7 @@ forbidden_behaviors:
38
38
  - do not answer from memory what a file says: read the file, then answer
39
39
  - do not ask again for a move the human refused: say what it would have done and leave it
40
40
  - do not read the board's own folder: it holds the human's token
41
+ - do not ask the human to build or start the game by hand, and do not say another agent did the work: the context file says whether a build exists and what opens it
41
42
 
42
43
  workflow:
43
44
  1. read `gcf/INDEX.md`, then run `ai-factory gcf board --json` for the phase, the items by status and the inbox
@@ -52,8 +53,10 @@ workflow:
52
53
  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
53
54
  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
54
55
  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
55
- 13. another move the human asks for: run its `ai-factory gcf` command; the human approves it on the card, or refuses it
56
- 14. say in one line what changed, or that nothing did
56
+ 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
57
+ 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
58
+ 15. another move the human asks for: run its `ai-factory gcf` command; the human approves it on the card, or refuses it
59
+ 16. say in one line what changed, or that nothing did
57
60
 
58
61
  invocation:
59
62
  - run at the start of a project chat thread the board opens, and when the user types `/gcf-chat`
@@ -21,6 +21,10 @@ forbidden_behaviors:
21
21
  - do not run `keep` when the human has not answered the item's miss_criterion question
22
22
  - do not hold a keep for a play condition: the human decides where to play; remind once of a line of `platforms` not played, then take the answer
23
23
  - do not edit systems docs, `LIVE.md`, history or graveyard by hand: the commands own them
24
+ - do not stop the player or delete the card's build: the verdict does both, and a build other cards on the same code hold stays for them
25
+ - `build_left` in the verdict's report names a build a held file kept; a later `ai-factory gcf playtest status` removes it
26
+ - do not answer that the human cannot play for want of a build: the card's Play button builds it first
27
+ - when the human asks for a build, run `ai-factory gcf playtest build <id>`, or `--main` for the checkout as it is
24
28
  - a tune note triage left in the inbox for the item goes into `--note`; after the verdict run `ai-factory gcf inbox drop <in-id>`, not before
25
29
 
26
30
  workflow:
@@ -18,6 +18,9 @@ gcf_work:
18
18
  - before planning an item, run `ai-factory gcf context <id>` and read only the files it lists under `gcf/`
19
19
  - an item's plan is in the plan form: blocks `context:`, `decisions:` (records `id`, `pick`, `why`), `tasks:` (`- [ ] t1 <action> (d1)`), `pillar_check:`, `verification:`, one idea a line
20
20
  - `ai-factory gcf plan check <id>` lists the plan's form problems as `format:` lines: fix them, they never block
21
+ - record each improve pass of a plan with `ai-factory gcf plan pass <id> --blocking <n> --polish <m> --json`; its verdict decides: continue, converged or stalled
22
+ - a `stalled` verdict: `ai-factory gcf plan stall <id> --passes <counts>` blocks the card; `gcf plan more` and `gcf plan accept` answer it, and they are the human's
23
+ - a harness run plans in one session and implements in a fresh one (`GCF_RUN_PHASE`); in your own terminal stop after planning unless the human asked for `--through`
21
24
  - drive a ready item with the gcf-run skill when the project has gcf-harness-aif-ext and the agent is Claude Code (a batch at once: `ai-factory gcf-harness run <ids...>`), otherwise with aif-plan and aif-implement
22
25
  - answer a question about how the runs go (the share that reached their move, cost, plan checks, DoD attempts, guard firings) with `ai-factory gcf-harness metrics`
23
26
  - answer a question about past runs (an item's results, what it ran on, its cost, the part of its log a run wrote) with `ai-factory gcf-harness runs [--item <id>] --json`
@@ -37,6 +40,14 @@ gcf_work:
37
40
  - `ai-factory gcf design check` names each hit of an avoided word in design and items as M4, `npx --yes cnlp-kit check` the rest
38
41
  - an `avoid:` lists only a word wrong in every document: a word with another use stays out, a phrase ("tile hand") beats a bare word
39
42
  - the human plays from `ai-factory gcf playtest session`; each free note from that play goes to `ai-factory gcf inbox add --category playtest "<note>"`, in the human's words
43
+ - 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
+ - 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
+ - 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
47
+ - 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
+ - do not ask the human for the build or start commands: the project holds them
49
+ - 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
50
+ - do not answer that the game cannot be built: offer the card's button with `propose_play`, or the checkout's with `propose_play_main`
40
51
  - a release item carries `version:` and `channel:` (`item new --title "<title>" --type release --release <v> --channel <c>`): its end writes the `release:` block of `gcf/LIVE.md`
41
52
  - `item new` and `take` refuse a type the current phase does not take: run `ai-factory gcf phase` and bring the refusal to the human
42
53
  - 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)
@@ -46,6 +57,8 @@ gcf_work:
46
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
47
58
  - 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
48
59
  - 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
+ - `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
61
+ - the queue and the autopilot stand at the quota's reserve (`quota_reserve_pct` of `~/.gcf/settings.json`); the human's own Run does not
49
62
  - an item the human wants run on a given model or effort gets `item new --title "<title>" --model <m> --effort <e>`: the harness run passes both to the agent
50
63
  - an existing item changes with `ai-factory gcf item agent <id> --model <m> --effort <e>` (`default` takes one off), never a hand edit; its next run takes them
51
64
  - an item without its own runs on the project's `agent.model` and `agent.effort` of `gcf/config.yml`, a setting of the human, and without those on opus, effort high
@@ -65,7 +78,7 @@ gcf_work:
65
78
  - write the body of an item that is not a design unit in `language.artifacts` of `.ai-factory/config.yaml`
66
79
  - write in English whatever lands in a checked document: `gcf/design/`, `gcf/systems/`, `GLOSSARY.md`, `gcf/PILLARS.md`, `gcf/LIVE.md`, the body of a design unit's item but its `tuning:` and `notes:`, an item's `live:` summary
67
80
  - an answer that moves into a unit's slot goes there in English
68
- - do not translate keys, statuses, ids, commands, `TBD`, `answer: q-NNN`, `## Handoff`, a `quote:` (it is verbatim from the GDD) or the fixed start of a block reason (`needs permission:`, `plan did not converge:`, `waits for`)
81
+ - do not translate keys, statuses, ids, commands, `TBD`, `answer: q-NNN`, `## Handoff`, a `quote:` (it is verbatim from the GDD) or the fixed start of a block reason (`needs permission:`, `planning does not converge`, `waits for`)
69
82
  - a D1 record that carries the human's `answer:` goes into the slot of each unit it blocks, with `answer: q-NNN`, and then leaves `gcf/open-questions.md`
70
83
  - a pillar changes only on the human's word; its short `name:` is what the human knows it by, and its id comes from the name
71
84
  - a new name saved with `design save` renames the id in every file that cites it
@@ -97,7 +110,9 @@ gcf_forbidden:
97
110
  - do not edit `status:`, `frozen:`, `gcf/LIVE.md`, `gcf/history.md`, `gcf/graveyard.md`, `gcf/inbox/` or `gcf/INDEX.md` by hand: the commands own them
98
111
  - do not give a verdict: `verdict` belongs to the human, through the gcf-verdict skill; nor a decision, but `go` or `no` of the spike you drive when the gates say `decision: agent`
99
112
  - the core refuses the human's moves to a harness run and a board chat: bring the move to the human, or block the item with the question
100
- - those moves are `verdict`, `decide`, `drop` of a work item, `unblock`, `item amend`, `question answer`, `config set`, `permissions`, `phase next`, `pillar`, `hooks-install`, `edits commit`, `edits discard`, `changes commit`
113
+ - those moves are `verdict`, `decide`, `drop` of a work item, `unblock`, `item amend`, `question answer`, `config set`, `playtest setup`, `permissions`, `phase next`, `pillar`, `hooks-install`, `edits commit`, `edits discard`, `changes commit`
114
+ - a run's agent does not build the game to play nor start a player: the harness builds it at the run's end, and `dod.build` only checks the code
115
+ - in the project chat, when the human asks for a build, run `ai-factory gcf playtest build <id>` or `ai-factory gcf playtest build --main` yourself
101
116
  - do not answer a `TBD` of a design unit yourself: ask the human and offer your draft as the proposed answer
102
117
  - do not run `ai-factory gcf phase next`: the phase moves on the human's word only
103
118
  - do not change what agent runs may do: `ai-factory gcf permissions`, its deny groups and the board's YOLO belong to the human
@@ -25,6 +25,14 @@ auto_compact_pct: 0
25
25
  # chat:
26
26
  # ask: d1
27
27
  # answer_timeout_min: 15
28
+ # The plan's improve passes (Hold-Plan d17): when a pass still finds blocking issues, pass `at`
29
+ # goes to an outside reviewer, read-only (Codex CLI); without it, or when it fails, Claude makes
30
+ # the pass. Uncomment to change (agent: none turns it off):
31
+ # plan_review:
32
+ # agent: codex
33
+ # model: gpt-6-astra
34
+ # effort: medium
35
+ # at: 3
28
36
  # Lessons (Methodology §5.2.2): at the end of each session on an item its agent says what got in
29
37
  # its way, into the inbox. `ai-factory gcf lessons prompt <id>` prints the questions. Uncomment to
30
38
  # turn them off, to ask what the project's template should learn, or to add questions:
@@ -45,3 +53,14 @@ auto_compact_pct: 0
45
53
  dod:
46
54
  test:
47
55
  build:
56
+ # How to build and start the game to play a finished card (ai-factory gcf playtest setup): a build
57
+ # a card keeps for itself until its verdict. `output` is git-ignored, inside the project; `{dir}`
58
+ # is that card's build, `{port}` a free port, `{lan}` this machine's address.
59
+ # A name with a space in it: "{dir}/My Game.exe".
60
+ # play:
61
+ # build: <the command that builds the game>
62
+ # output: <the folder it builds into>
63
+ # targets:
64
+ # browser:
65
+ # start: <a command that serves {dir} on {port}>
66
+ # open: http://localhost:{port}