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.
@@ -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
@@ -41,6 +41,7 @@ import { cycleMessage, dependsGraph, gameMilestones, pathTo } from './design-che
41
41
  import { refuseByPhase } from './phase.js';
42
42
  import { locked, runHolder } from './main-lock.js';
43
43
  import { dropAgentSession, ownsMark, releaseSession, sessionActive } from './session-mark.js';
44
+ import { clearCard, inSwitch, isShelved, leaveFolder, wholeOnShelf } from './shelf.js';
44
45
  import { dropStamp, unverifiedProblem } from './verify-stamp.js';
45
46
  import { planTicks } from './plan-check.js';
46
47
  import {
@@ -55,6 +56,7 @@ import {
55
56
  import { verdictDeferred } from './gates.js';
56
57
  import { appendQuestions, questionsFile } from './questions.js';
57
58
  import { refusal } from './refusal.js';
59
+ import { releaseBuild } from './play.js';
58
60
 
59
61
  /**
60
62
  * Options of a committed move; each move reads the ones it needs.
@@ -213,6 +215,7 @@ async function begin(projectDir, id, move, refuse = refuseRunning) {
213
215
  refuse(projectDir, id);
214
216
  const files = [item.file];
215
217
  const steps = [];
218
+ const after = [];
216
219
  const liveOps = [];
217
220
 
218
221
  return {
@@ -220,6 +223,7 @@ async function begin(projectDir, id, move, refuse = refuseRunning) {
220
223
  root,
221
224
  ledger,
222
225
  item,
226
+ ran: after,
223
227
  /** @type {Set<string>} ids leaving systems/ in this move */
224
228
  leaving: new Set(),
225
229
  /** @type {Set<string>} every item the move touches, for its commit's GCF-Items */
@@ -229,6 +233,8 @@ async function begin(projectDir, id, move, refuse = refuseRunning) {
229
233
  inputs: [item.file],
230
234
  touch: (...f) => files.push(...f.filter((x) => !files.includes(x))),
231
235
  step: (fn) => steps.push(fn),
236
+ /** After the commit: refs that hold work go only once the move stands. */
237
+ after: (fn) => after.push(fn),
232
238
  live: (fn) => {
233
239
  if (!files.includes(liveFile(root))) files.push(liveFile(root));
234
240
  liveOps.push(fn);
@@ -262,10 +268,41 @@ async function finish(m, key, tail, commit) {
262
268
  releaseSession(m.projectDir, String(m.item.data.id));
263
269
  dropAgentSession(m.projectDir, String(m.item.data.id));
264
270
  dropStamp(m.projectDir, String(m.item.data.id));
271
+ // A caller that commits later cleans up after it: a refused commit rolls the files back, and
272
+ // refs gone by then would not come back.
273
+ if (commit === false) return hash;
274
+ // Its work is committed: what still lies loose is no longer the card's to carry.
275
+ if (move === 'submit' || move === 'close') leaveFolder(m.projectDir, String(m.item.data.id));
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));
265
280
 
266
281
  return hash;
267
282
  }
268
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
+
287
+ /** A card's work waits on its branch: it has to come back before it can be judged. */
288
+ function needInFolder(m, item = m.item) {
289
+ const id = String(item.data.id);
290
+ if (!isShelved(m.projectDir, id)) return;
291
+ const reason = `its work is shelved on work/${id}: run it, or gcf claim ${id}, to bring it back`;
292
+ throw refusal('shelve', { reason }, `${id}: ${reason}`);
293
+ }
294
+
295
+ /**
296
+ * A card that ends while a switch moves its work: the switch would finish after, and leave its
297
+ * branch and refs for no card at all, with nothing to take them away.
298
+ */
299
+ function needNoSwitch(m, item) {
300
+ const id = String(item.data.id);
301
+ if (!inSwitch(m.projectDir, id)) return;
302
+ const reason = `a switch of its work has not finished: gcf claim ${id} finishes it`;
303
+ throw refusal('shelve', { reason }, `${id}: ${reason}`);
304
+ }
305
+
269
306
  /**
270
307
  * `close` and `submit` from a command (Methodology §6): the code as it is now needs a green
271
308
  * `gcf verify`, unless the operator says why not (`unverified`, written into the move's
@@ -459,6 +496,9 @@ const detailOf = (item, archived) =>
459
496
  */
460
497
  function endToHistory(m, item, event, { applyLive = true } = {}) {
461
498
  const id = String(item.data.id);
499
+ // Accepted with its work on a branch, the branch would go and the work with it.
500
+ needInFolder(m, item);
501
+ needNoSwitch(m, item);
462
502
  if (item.data.type === 'release') recordRelease(m, item);
463
503
  m.touch(path.join(m.root, 'history.md'));
464
504
  m.step(() => recordLine(m.root, id, event));
@@ -470,6 +510,7 @@ function endToHistory(m, item, event, { applyLive = true } = {}) {
470
510
 
471
511
  dropKnownIssue(m, id);
472
512
  m.step(() => unlink(item.file));
513
+ m.after(() => clearCard(m.projectDir, id));
473
514
  }
474
515
 
475
516
  /**
@@ -551,6 +592,7 @@ function endToGraveyard(
551
592
  const id = String(item.data.id);
552
593
  const why = String(reason ?? '').trim();
553
594
  if (!why) throw new Error(`${id}: the graveyard keeps a reason — give one`);
595
+ needNoSwitch(m, item);
554
596
  m.touch(path.join(m.root, 'graveyard.md'), item.file);
555
597
  // A feature's kill takes its live children down in the same commit.
556
598
  m.items.add(id);
@@ -562,6 +604,7 @@ function endToGraveyard(
562
604
  if (!quiet) parentWaits(m, item);
563
605
  const removed = removal ? removalItem(m, item, why) : null;
564
606
  m.step(() => unlink(item.file));
607
+ m.after(() => clearCard(m.projectDir, id));
565
608
 
566
609
  return removed;
567
610
  }
@@ -572,19 +615,29 @@ function endToGraveyard(
572
615
  * code was committed. `--no-remove` overrides it.
573
616
  */
574
617
  const IN_MAIN = ['awaiting-verdict', 'awaiting-decision', 'unplayed', 'blocked', 'parked'];
575
- const codeInMain = (item) =>
618
+ const codeInMain = (projectDir, item) =>
576
619
  item.data.type !== 'spike' &&
577
- (IN_MAIN.includes(item.data.status) || (item.data.tune_count ?? 0) > 0);
620
+ (IN_MAIN.includes(item.data.status) || (item.data.tune_count ?? 0) > 0) &&
621
+ !shelvedWhole(projectDir, item);
622
+
623
+ /**
624
+ * A card whose code never reached main: all of it sits on its shelf, and goes with it. Only a
625
+ * shelve says so: a tuned card's earlier build is on main.
626
+ */
627
+ const shelvedWhole = (projectDir, item) =>
628
+ !(item.data.tune_count > 0) && wholeOnShelf(projectDir, String(item.data.id));
578
629
 
579
630
  /**
580
631
  * A feature's own status says nothing about its code: it is in main when a child ended
581
632
  * accepted, or a live child's code is.
582
633
  */
583
- const featureShipped = (ledger, feature) =>
634
+ const featureShipped = (projectDir, ledger, feature) =>
584
635
  (feature.data.children ?? []).some((c) => {
585
636
  const child = ledger.item(c);
586
637
 
587
- return child ? codeInMain(child) : ledger.where(c).terminal.some((t) => t !== 'killed');
638
+ return child
639
+ ? codeInMain(projectDir, child)
640
+ : ledger.where(c).terminal.some((t) => t !== 'killed');
588
641
  });
589
642
 
590
643
  function refuseOpenDepends(m, move, opts = {}) {
@@ -663,6 +716,7 @@ async function submitItemUnlocked(projectDir, id, opts = {}) {
663
716
  const changes = playChanges(m.item);
664
717
  // Unplayed needs its dependencies played, as a close does: not one still waiting (§4.1).
665
718
  refuseOpenDepends(m, 'submit', { waiting: !deferred || changes.length > 0 });
719
+ needInFolder(m);
666
720
  needTicked(m, opts);
667
721
  needVerified(m, opts);
668
722
  assumeInto(m, opts.assume);
@@ -754,6 +808,7 @@ async function closeItemUnlocked(projectDir, id, opts = {}) {
754
808
  throw new Error(`${id} has gate ${m.item.data.gate}: submit it, the operator closes it`);
755
809
  // A4: it will wait for a verdict, so a dependency waiting for its own is no bar.
756
810
  refuseOpenDepends(m, 'close', { waiting: changes.length > 0 });
811
+ needInFolder(m);
757
812
  needTicked(m, opts);
758
813
  needVerified(m, opts);
759
814
  if (changes.length) awaitVerdict(m, `modifies ${changes.join(', ')}`);
@@ -821,7 +876,7 @@ async function tune(m, note) {
821
876
  if (item.data.status === 'unplayed') unplay(m, item);
822
877
  const body = note ? await upsertItemNote(item, 'tuning', note) : item.body;
823
878
  const data = {
824
- ...without(item.data, 'frozen'),
879
+ ...newCycle(without(item.data, 'frozen')),
825
880
  status: 'ready',
826
881
  tune_count: tunes + 1,
827
882
  since: null,
@@ -829,6 +884,15 @@ async function tune(m, note) {
829
884
  m.step(() => writeItem(item, data, body));
830
885
  }
831
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
+
832
896
  /** keep | tune | kill on an item waiting for its verdict or unplayed (Methodology §5.4).
833
897
  * @param {MoveOpts} [opts]
834
898
  */
@@ -846,7 +910,7 @@ async function verdictItemUnlocked(projectDir, id, verdict, opts = {}) {
846
910
  const tail = `${verdict} ${id} → ${systems.join(',')}${played}`;
847
911
  const hash = await finish(m, `verdict:${verdict}`, tail, commit);
848
912
 
849
- return { verdict, id, systems, hash, removal };
913
+ return { verdict, id, systems, hash, removal, ...buildLeft(m) };
850
914
  }
851
915
 
852
916
  // What a milestone's keep may write: gcf/ as the gate reads it (no .metrics, which audit and
@@ -969,8 +1033,10 @@ async function keepMilestoneUnlocked(projectDir, name, opts = {}) {
969
1033
  const files = changedIn(projectDir).map((c) => path.join(projectDir, c.file));
970
1034
  const message = `gcf(verdict): keep ${name} → ${order.join(', ')}${played}`;
971
1035
  const hash = commitPaths(projectDir, message, files, { key: 'verdict:keep', items: order });
1036
+ for (const id of order) clearCard(projectDir, id);
1037
+ const left = order.map((id) => releaseBuild(projectDir, id)).filter(Boolean);
972
1038
 
973
- return { milestone: name, ids: order, hash };
1039
+ return { milestone: name, ids: order, hash, ...(left.length ? { build_left: left } : {}) };
974
1040
  } catch (e) {
975
1041
  // Nothing kept: what the keep wrote back to HEAD (staged or not); the pack's own files keep
976
1042
  // the operator's edits on disk and in the index as they were.
@@ -993,7 +1059,7 @@ async function keepMilestoneUnlocked(projectDir, name, opts = {}) {
993
1059
  /** decide kill: the live children go down with the feature, without removal items of their own. */
994
1060
  function killFeature(m, { reason, remove }) {
995
1061
  const { item, ledger } = m;
996
- const shipped = featureShipped(ledger, item);
1062
+ const shipped = featureShipped(m.projectDir, ledger, item);
997
1063
  const children = (item.data.children ?? []).map((c) => ledger.item(c)).filter(Boolean);
998
1064
  // A child's file goes with the feature: an agent working it would lose it mid-run.
999
1065
  // No session kills its own item through its feature: the claimed child counts as running too.
@@ -1021,12 +1087,16 @@ function park(m) {
1021
1087
  const DECIDE = {
1022
1088
  go: (m) => endToHistory(m, m.item, 'decided') ?? null,
1023
1089
  no: (m, o) =>
1024
- endToGraveyard(m, m.item, { reason: o.reason, removal: o.remove ?? codeInMain(m.item) }),
1090
+ endToGraveyard(m, m.item, {
1091
+ reason: o.reason,
1092
+ removal: o.remove ?? codeInMain(m.projectDir, m.item),
1093
+ }),
1025
1094
  // A bug not to be fixed has fix code in main only when a started fix got blocked.
1026
1095
  wontfix: (m, o) =>
1027
1096
  endToGraveyard(m, m.item, {
1028
1097
  reason: o.reason,
1029
- removal: o.remove ?? m.item.data.status === 'blocked',
1098
+ removal:
1099
+ o.remove ?? (m.item.data.status === 'blocked' && !shelvedWhole(m.projectDir, m.item)),
1030
1100
  }),
1031
1101
  known: park,
1032
1102
  close: (m) => closeFeature(m) ?? null,
@@ -1101,7 +1171,7 @@ async function unblockItemUnlocked(projectDir, id, opts = {}) {
1101
1171
  const childDied = / child \S+ died/.test(String(m.item.data.blocked ?? ''));
1102
1172
  const waits = m.item.data.type === 'feature' && childDied;
1103
1173
  const data = {
1104
- ...without(m.item.data, 'blocked'),
1174
+ ...newCycle(without(m.item.data, 'blocked')),
1105
1175
  status: waits ? 'awaiting-decision' : 'ready',
1106
1176
  since: waits ? headHash(projectDir) : null,
1107
1177
  };
@@ -1230,12 +1300,66 @@ async function amendItemUnlocked(projectDir, id, opts = {}) {
1230
1300
  if (dryRun) return { id, base: amendBase(m.item), title, text: amendableText(body), changes };
1231
1301
  refuseAmendPointless(m.item, { asked, base: opts.base, changes, entry });
1232
1302
  if (entry) carryEntry(m, entry, commit);
1233
- const data = asked.title ? { ...m.item.data, title } : m.item.data;
1303
+ const data = newCycle(asked.title ? { ...m.item.data, title } : m.item.data);
1234
1304
  m.step(() => writeItem(m.item, data, body));
1235
1305
 
1236
1306
  return { id, changes, hash: await finish(m, 'amend', id, commit) };
1237
1307
  }
1238
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
+
1239
1363
  /** What a fix asks for, trimmed: a blank field is none, an over-long or broken one refused. */
1240
1364
  function amendAsked(opts) {
1241
1365
  const [text, add, title, from] = [opts.text, opts.add, opts.title, opts.from].map((v) =>
@@ -1294,10 +1418,14 @@ async function dropItemUnlocked(projectDir, id, opts = {}) {
1294
1418
  if (m.item.data.type === 'feature' && (m.item.data.children ?? []).some((c) => m.ledger.item(c)))
1295
1419
  throw new Error(`${id} still has live children: drop them first, or decide kill ${id}`);
1296
1420
  const shipped =
1297
- m.item.data.type === 'feature' ? featureShipped(m.ledger, m.item) : codeInMain(m.item);
1421
+ m.item.data.type === 'feature'
1422
+ ? featureShipped(projectDir, m.ledger, m.item)
1423
+ : codeInMain(projectDir, m.item);
1298
1424
  const removal = endToGraveyard(m, m.item, { reason, tags, removal: remove ?? shipped });
1299
1425
 
1300
- 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) };
1301
1429
  }
1302
1430
 
1303
1431
  /** The version and channel of a new item: well-formed, and only on a release. */
@@ -1854,6 +1982,12 @@ export const decideItem = (projectDir, id, choice, opts = {}) =>
1854
1982
  /** @type {typeof blockItemUnlocked} */
1855
1983
  export const blockItem = (projectDir, id, opts = {}) =>
1856
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));
1857
1991
  /** @type {typeof unblockItemUnlocked} */
1858
1992
  export const unblockItem = (projectDir, id, opts = {}) =>
1859
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.23.0",
3
+ "version": "0.25.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
@@ -23,7 +23,7 @@ preconditions:
23
23
  - with YOLO a framework move that changes the project runs without a card too: a move with a `propose_` tool stays a proposal, and any other move is one the human asked for
24
24
 
25
25
  forbidden_behaviors:
26
- - do not make the human's moves: `verdict`, `decide`, `question answer`, `unblock`, `item amend`, `phase next`, `pillar`, `permissions`, `config set`, `hooks-install`, `edits commit`, `edits discard`; the rules refuse them to any agent
26
+ - do not make the human's moves: `verdict`, `decide`, `question answer`, `unblock`, `item amend`, `phase next`, `pillar`, `permissions`, `config set`, `hooks-install`, `edits commit`, `edits discard`, `changes commit`; the rules refuse them
27
27
  - do not put a decision about a live item into the inbox or a new item: a run reads neither, and it blocks on what its card does not say; the decision goes into the card with `propose_amend`
28
28
  - do not add a line to `notes:` that contradicts a slot of the card: replace the slot through `text`, as only the slots reach the documents of the systems
29
29
  - do not run a verdict, a decision, an unblock or an answer: propose it to the human with its `propose_` tool
@@ -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,7 @@ 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; `build_left` in its report names a build a held file kept, and a later `ai-factory gcf playtest status` removes it
24
25
  - 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
26
 
26
27
  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,9 @@ 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; that build stays apart in `.gcf-session/builds/<id>/`, and later work does not touch it
44
+ - the board's Play button starts that build on a target of `play:`, and the card's verdict stops it and removes the build; `ai-factory gcf playtest status` names the targets and the running player
45
+ - how the game builds and starts is the human's: `ai-factory gcf playtest setup`; in the project chat propose it with `propose_play_setup`, and the button with `propose_play`
40
46
  - 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
47
  - `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
48
  - 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,10 +52,17 @@ gcf_work:
46
52
  - 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
53
  - 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
54
  - 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
55
+ - `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
56
+ - 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
57
  - 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
58
  - 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
59
  - 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
52
60
  - where an item's runs go, the project folder or a worktree, is the human's choice: `ai-factory gcf item mode <id> --run main|worktree|default` over the project's `run_mode`, never a hand edit; set it only when the human asks
61
+ - in the project folder, the next item's `ai-factory gcf claim` moves a stopped item's unfinished work to branch `work/<id>`, and that item's own claim brings it back
62
+ - a branch `work/<id>` whose last commit says `GCF-Shelved: <id>` holds unfinished work: do not merge it
63
+ - a shelve keeps the files as they stand on disk; staged text that differed from them is in `refs/gcf/staged/<id>`, and the claim's output names the commit
64
+ - do not run `git stash` or `git reset` over a stopped item's files in the folder: the core loses track of its work
65
+ - the core refuses `close` and `submit` on a shelved item until a run brings its work back; `drop` drops the work too
53
66
  - before starting a run, `ai-factory gcf-harness gate --each <ids...> --json` says what the run gate refuses each item alone for now (it exits 0); `gate <ids...>` still gates a batch as a whole (exit 1)
54
67
  - a session stops after `session_timeout_min` of `gcf/config.yml`, its item stays ready
55
68
  - ready items run in `priority:` order, lower first: rank a set of items with `ai-factory gcf prioritize <id> <id> …`
@@ -60,7 +73,7 @@ gcf_work:
60
73
  - write the body of an item that is not a design unit in `language.artifacts` of `.ai-factory/config.yaml`
61
74
  - 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
62
75
  - an answer that moves into a unit's slot goes there in English
63
- - 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`)
76
+ - 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`)
64
77
  - 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`
65
78
  - 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
66
79
  - a new name saved with `design save` renames the id in every file that cites it
@@ -84,6 +97,7 @@ gcf_work:
84
97
  - `item amend` refused for a live run ends with `gcf-refusal: {"code":"running"}`, and refused for a card changed since its preview with `gcf-refusal: {"code":"stale"}`
85
98
  - a move the commit gate refuses ends its error with `gcf-refusal: {"code":"gate","problems":[…]}`: git holds no commit of it; fix what it names, then make the move again
86
99
  - `ai-factory gcf changes [--worktree <id>]` lists what is uncommitted in the checkout or an item's worktree, `gcf changes diff --path <path>` shows one text file's diff
100
+ - `gcf changes commit` is the human's Commit on the board, never the agent's; asked to commit loose work, read each diff and commit with git what belongs to the project
87
101
  - `no_diff` in `gcf/config.yml` is the project's list of files shown without a diff
88
102
  - a chat thread bound to an item reads the item's file, its plan, its run's log and run chat first (the paths its context names), answers the question, and only then proposes a move
89
103
 
@@ -91,7 +105,8 @@ gcf_forbidden:
91
105
  - 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
92
106
  - 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`
93
107
  - 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
94
- - 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`
108
+ - 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`
109
+ - do not build the game to play nor start a player yourself: the harness builds it, the human's Play button starts it, and `dod.build` only checks the code
95
110
  - do not answer a `TBD` of a design unit yourself: ask the human and offer your draft as the proposed answer
96
111
  - do not run `ai-factory gcf phase next`: the phase moves on the human's word only
97
112
  - 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}