gcf-aif-ext 0.23.0 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/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 {
@@ -213,6 +214,7 @@ async function begin(projectDir, id, move, refuse = refuseRunning) {
213
214
  refuse(projectDir, id);
214
215
  const files = [item.file];
215
216
  const steps = [];
217
+ const after = [];
216
218
  const liveOps = [];
217
219
 
218
220
  return {
@@ -220,6 +222,7 @@ async function begin(projectDir, id, move, refuse = refuseRunning) {
220
222
  root,
221
223
  ledger,
222
224
  item,
225
+ ran: after,
223
226
  /** @type {Set<string>} ids leaving systems/ in this move */
224
227
  leaving: new Set(),
225
228
  /** @type {Set<string>} every item the move touches, for its commit's GCF-Items */
@@ -229,6 +232,8 @@ async function begin(projectDir, id, move, refuse = refuseRunning) {
229
232
  inputs: [item.file],
230
233
  touch: (...f) => files.push(...f.filter((x) => !files.includes(x))),
231
234
  step: (fn) => steps.push(fn),
235
+ /** After the commit: refs that hold work go only once the move stands. */
236
+ after: (fn) => after.push(fn),
232
237
  live: (fn) => {
233
238
  if (!files.includes(liveFile(root))) files.push(liveFile(root));
234
239
  liveOps.push(fn);
@@ -262,10 +267,35 @@ async function finish(m, key, tail, commit) {
262
267
  releaseSession(m.projectDir, String(m.item.data.id));
263
268
  dropAgentSession(m.projectDir, String(m.item.data.id));
264
269
  dropStamp(m.projectDir, String(m.item.data.id));
270
+ // A caller that commits later cleans up after it: a refused commit rolls the files back, and
271
+ // refs gone by then would not come back.
272
+ if (commit === false) return hash;
273
+ // Its work is committed: what still lies loose is no longer the card's to carry.
274
+ if (move === 'submit' || move === 'close') leaveFolder(m.projectDir, String(m.item.data.id));
275
+ for (const fn of m.ran) fn();
265
276
 
266
277
  return hash;
267
278
  }
268
279
 
280
+ /** A card's work waits on its branch: it has to come back before it can be judged. */
281
+ function needInFolder(m, item = m.item) {
282
+ const id = String(item.data.id);
283
+ if (!isShelved(m.projectDir, id)) return;
284
+ const reason = `its work is shelved on work/${id}: run it, or gcf claim ${id}, to bring it back`;
285
+ throw refusal('shelve', { reason }, `${id}: ${reason}`);
286
+ }
287
+
288
+ /**
289
+ * A card that ends while a switch moves its work: the switch would finish after, and leave its
290
+ * branch and refs for no card at all, with nothing to take them away.
291
+ */
292
+ function needNoSwitch(m, item) {
293
+ const id = String(item.data.id);
294
+ if (!inSwitch(m.projectDir, id)) return;
295
+ const reason = `a switch of its work has not finished: gcf claim ${id} finishes it`;
296
+ throw refusal('shelve', { reason }, `${id}: ${reason}`);
297
+ }
298
+
269
299
  /**
270
300
  * `close` and `submit` from a command (Methodology §6): the code as it is now needs a green
271
301
  * `gcf verify`, unless the operator says why not (`unverified`, written into the move's
@@ -459,6 +489,9 @@ const detailOf = (item, archived) =>
459
489
  */
460
490
  function endToHistory(m, item, event, { applyLive = true } = {}) {
461
491
  const id = String(item.data.id);
492
+ // Accepted with its work on a branch, the branch would go and the work with it.
493
+ needInFolder(m, item);
494
+ needNoSwitch(m, item);
462
495
  if (item.data.type === 'release') recordRelease(m, item);
463
496
  m.touch(path.join(m.root, 'history.md'));
464
497
  m.step(() => recordLine(m.root, id, event));
@@ -470,6 +503,7 @@ function endToHistory(m, item, event, { applyLive = true } = {}) {
470
503
 
471
504
  dropKnownIssue(m, id);
472
505
  m.step(() => unlink(item.file));
506
+ m.after(() => clearCard(m.projectDir, id));
473
507
  }
474
508
 
475
509
  /**
@@ -551,6 +585,7 @@ function endToGraveyard(
551
585
  const id = String(item.data.id);
552
586
  const why = String(reason ?? '').trim();
553
587
  if (!why) throw new Error(`${id}: the graveyard keeps a reason — give one`);
588
+ needNoSwitch(m, item);
554
589
  m.touch(path.join(m.root, 'graveyard.md'), item.file);
555
590
  // A feature's kill takes its live children down in the same commit.
556
591
  m.items.add(id);
@@ -562,6 +597,7 @@ function endToGraveyard(
562
597
  if (!quiet) parentWaits(m, item);
563
598
  const removed = removal ? removalItem(m, item, why) : null;
564
599
  m.step(() => unlink(item.file));
600
+ m.after(() => clearCard(m.projectDir, id));
565
601
 
566
602
  return removed;
567
603
  }
@@ -572,19 +608,29 @@ function endToGraveyard(
572
608
  * code was committed. `--no-remove` overrides it.
573
609
  */
574
610
  const IN_MAIN = ['awaiting-verdict', 'awaiting-decision', 'unplayed', 'blocked', 'parked'];
575
- const codeInMain = (item) =>
611
+ const codeInMain = (projectDir, item) =>
576
612
  item.data.type !== 'spike' &&
577
- (IN_MAIN.includes(item.data.status) || (item.data.tune_count ?? 0) > 0);
613
+ (IN_MAIN.includes(item.data.status) || (item.data.tune_count ?? 0) > 0) &&
614
+ !shelvedWhole(projectDir, item);
615
+
616
+ /**
617
+ * A card whose code never reached main: all of it sits on its shelf, and goes with it. Only a
618
+ * shelve says so: a tuned card's earlier build is on main.
619
+ */
620
+ const shelvedWhole = (projectDir, item) =>
621
+ !(item.data.tune_count > 0) && wholeOnShelf(projectDir, String(item.data.id));
578
622
 
579
623
  /**
580
624
  * A feature's own status says nothing about its code: it is in main when a child ended
581
625
  * accepted, or a live child's code is.
582
626
  */
583
- const featureShipped = (ledger, feature) =>
627
+ const featureShipped = (projectDir, ledger, feature) =>
584
628
  (feature.data.children ?? []).some((c) => {
585
629
  const child = ledger.item(c);
586
630
 
587
- return child ? codeInMain(child) : ledger.where(c).terminal.some((t) => t !== 'killed');
631
+ return child
632
+ ? codeInMain(projectDir, child)
633
+ : ledger.where(c).terminal.some((t) => t !== 'killed');
588
634
  });
589
635
 
590
636
  function refuseOpenDepends(m, move, opts = {}) {
@@ -663,6 +709,7 @@ async function submitItemUnlocked(projectDir, id, opts = {}) {
663
709
  const changes = playChanges(m.item);
664
710
  // Unplayed needs its dependencies played, as a close does: not one still waiting (§4.1).
665
711
  refuseOpenDepends(m, 'submit', { waiting: !deferred || changes.length > 0 });
712
+ needInFolder(m);
666
713
  needTicked(m, opts);
667
714
  needVerified(m, opts);
668
715
  assumeInto(m, opts.assume);
@@ -754,6 +801,7 @@ async function closeItemUnlocked(projectDir, id, opts = {}) {
754
801
  throw new Error(`${id} has gate ${m.item.data.gate}: submit it, the operator closes it`);
755
802
  // A4: it will wait for a verdict, so a dependency waiting for its own is no bar.
756
803
  refuseOpenDepends(m, 'close', { waiting: changes.length > 0 });
804
+ needInFolder(m);
757
805
  needTicked(m, opts);
758
806
  needVerified(m, opts);
759
807
  if (changes.length) awaitVerdict(m, `modifies ${changes.join(', ')}`);
@@ -969,6 +1017,7 @@ async function keepMilestoneUnlocked(projectDir, name, opts = {}) {
969
1017
  const files = changedIn(projectDir).map((c) => path.join(projectDir, c.file));
970
1018
  const message = `gcf(verdict): keep ${name} → ${order.join(', ')}${played}`;
971
1019
  const hash = commitPaths(projectDir, message, files, { key: 'verdict:keep', items: order });
1020
+ for (const id of order) clearCard(projectDir, id);
972
1021
 
973
1022
  return { milestone: name, ids: order, hash };
974
1023
  } catch (e) {
@@ -993,7 +1042,7 @@ async function keepMilestoneUnlocked(projectDir, name, opts = {}) {
993
1042
  /** decide kill: the live children go down with the feature, without removal items of their own. */
994
1043
  function killFeature(m, { reason, remove }) {
995
1044
  const { item, ledger } = m;
996
- const shipped = featureShipped(ledger, item);
1045
+ const shipped = featureShipped(m.projectDir, ledger, item);
997
1046
  const children = (item.data.children ?? []).map((c) => ledger.item(c)).filter(Boolean);
998
1047
  // A child's file goes with the feature: an agent working it would lose it mid-run.
999
1048
  // No session kills its own item through its feature: the claimed child counts as running too.
@@ -1021,12 +1070,16 @@ function park(m) {
1021
1070
  const DECIDE = {
1022
1071
  go: (m) => endToHistory(m, m.item, 'decided') ?? null,
1023
1072
  no: (m, o) =>
1024
- endToGraveyard(m, m.item, { reason: o.reason, removal: o.remove ?? codeInMain(m.item) }),
1073
+ endToGraveyard(m, m.item, {
1074
+ reason: o.reason,
1075
+ removal: o.remove ?? codeInMain(m.projectDir, m.item),
1076
+ }),
1025
1077
  // A bug not to be fixed has fix code in main only when a started fix got blocked.
1026
1078
  wontfix: (m, o) =>
1027
1079
  endToGraveyard(m, m.item, {
1028
1080
  reason: o.reason,
1029
- removal: o.remove ?? m.item.data.status === 'blocked',
1081
+ removal:
1082
+ o.remove ?? (m.item.data.status === 'blocked' && !shelvedWhole(m.projectDir, m.item)),
1030
1083
  }),
1031
1084
  known: park,
1032
1085
  close: (m) => closeFeature(m) ?? null,
@@ -1294,7 +1347,9 @@ async function dropItemUnlocked(projectDir, id, opts = {}) {
1294
1347
  if (m.item.data.type === 'feature' && (m.item.data.children ?? []).some((c) => m.ledger.item(c)))
1295
1348
  throw new Error(`${id} still has live children: drop them first, or decide kill ${id}`);
1296
1349
  const shipped =
1297
- m.item.data.type === 'feature' ? featureShipped(m.ledger, m.item) : codeInMain(m.item);
1350
+ m.item.data.type === 'feature'
1351
+ ? featureShipped(projectDir, m.ledger, m.item)
1352
+ : codeInMain(projectDir, m.item);
1298
1353
  const removal = endToGraveyard(m, m.item, { reason, tags, removal: remove ?? shipped });
1299
1354
 
1300
1355
  return { id, hash: await finish(m, 'drop', id, commit), removal };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-aif-ext",
3
- "version": "0.23.0",
3
+ "version": "0.24.0",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -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
@@ -50,6 +50,11 @@ gcf_work:
50
50
  - 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
51
  - 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
52
  - 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
53
+ - 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
54
+ - a branch `work/<id>` whose last commit says `GCF-Shelved: <id>` holds unfinished work: do not merge it
55
+ - 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
56
+ - do not run `git stash` or `git reset` over a stopped item's files in the folder: the core loses track of its work
57
+ - the core refuses `close` and `submit` on a shelved item until a run brings its work back; `drop` drops the work too
53
58
  - 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
59
  - a session stops after `session_timeout_min` of `gcf/config.yml`, its item stays ready
55
60
  - ready items run in `priority:` order, lower first: rank a set of items with `ai-factory gcf prioritize <id> <id> …`
@@ -84,6 +89,7 @@ gcf_work:
84
89
  - `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
90
  - 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
91
  - `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
92
+ - `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
93
  - `no_diff` in `gcf/config.yml` is the project's list of files shown without a diff
88
94
  - 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
95
 
@@ -91,7 +97,7 @@ gcf_forbidden:
91
97
  - 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
98
  - 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
99
  - 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`
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`
95
101
  - do not answer a `TBD` of a design unit yourself: ask the human and offer your draft as the proposed answer
96
102
  - do not run `ai-factory gcf phase next`: the phase moves on the human's word only
97
103
  - do not change what agent runs may do: `ai-factory gcf permissions`, its deny groups and the board's YOLO belong to the human