gcf-harness-aif-ext 0.25.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.
package/README.md CHANGED
@@ -43,6 +43,8 @@ ai-factory extension update gcf-harness-aif-ext
43
43
 
44
44
  Updating keeps the hook entry valid — it points into the extension's install directory, which an update refreshes in place.
45
45
 
46
+ 0.25.1 changes nothing but the peer range: it runs with `gcf-aif-ext` 0.26 and 0.27.
47
+
46
48
  0.23.0 needs `gcf-aif-ext` 0.24: a main batch goes on past a card that left code, the next claim moving it to `work/<id>`. It still stops with `left` when no baseline stands or the shelve is refused. A returning card's first message says what came back and which conflicts to resolve first; `gate --each`'s `dirty` leaves out the paths of the card in the folder; a run's report names `shelved`, `returned` and `conflicts`.
47
49
 
48
50
  0.5.0 drives work items (`gcf/work/<id>.md`, schema 3) instead of cards and requires `gcf-aif-ext` 0.4.0 — update both together; against an older core the gate refuses with `gcf-aif-ext >= 0.4.0 is required`. A project still holding schema 2 cards in `gcf/cards/` re-creates them first (see the core's "Upgrading from 0.3.x"). What changes for you: `/gcf-run` takes ids of items in `ready`; it no longer stops at `built` but ends each item with `submit`, `close` or `block`; the plan is improved in passes until it converges; the WIP cap counts only items that end waiting for a verdict.
@@ -751,9 +751,29 @@ function chatAction(id, action, words, opts) {
751
751
  function lockOf(file) {
752
752
  try {
753
753
  const [run, item, session] = readFileSync(file, 'utf8').split('\n');
754
- if (!alive(Number(run))) return null;
754
+ if (!alive(Number(run))) return builderLock(file);
755
755
 
756
756
  return { run: Number(run), item: item || null, session: Number(session) || null };
757
+ } catch {
758
+ return builderLock(file);
759
+ }
760
+ }
761
+
762
+ /**
763
+ * The main checkout's lock while a build its run let in lives on (docs/Handoff-Plan.md d6): the
764
+ * builder holds it, even with its run dead. No card: a build works there.
765
+ */
766
+ function builderLock(file) {
767
+ if (path.basename(file) !== `${MAIN_RUN}.lock`) return null;
768
+ try {
769
+ const y = JSON.parse(
770
+ readFileSync(path.join(path.dirname(path.dirname(file)), `${MAIN_RUN}.yield`), 'utf8'),
771
+ );
772
+
773
+ // `builder: null` after a release reads as 0, which `kill(0, 0)` answers as alive.
774
+ const b = y.builder;
775
+
776
+ return Number.isInteger(b) && b > 0 && alive(b) ? { run: b, item: null, session: null } : null;
757
777
  } catch {
758
778
  return null;
759
779
  }
package/commands/run.js CHANGED
@@ -6,6 +6,7 @@ import { spawnSync } from 'node:child_process';
6
6
  import {
7
7
  existsSync,
8
8
  mkdirSync,
9
+ readdirSync,
9
10
  readFileSync,
10
11
  rmSync,
11
12
  statSync,
@@ -20,6 +21,7 @@ import {
20
21
  CHAT_TIMEOUT_MIN,
21
22
  SESSION_ID,
22
23
  adapterFor,
24
+ alive,
23
25
  chatIn,
24
26
  chatOut,
25
27
  claim,
@@ -1300,9 +1302,10 @@ async function runMain(projectDir, ids, releaseMain, ctx) {
1300
1302
  const items = [];
1301
1303
  try {
1302
1304
  for (const [n, id] of ids.entries()) {
1303
- const held = heldRest(ids, n, ctx);
1304
- if (held) {
1305
- items.push(...held);
1305
+ // Between its cards the run lets a build by click in (docs/Handoff-Plan.md d6).
1306
+ const rest = await yieldedRest(projectDir, ids, n, ctx);
1307
+ if (rest) {
1308
+ items.push(...rest);
1306
1309
  break;
1307
1310
  }
1308
1311
 
@@ -1458,7 +1461,8 @@ async function buildStep(ctx, id, { lock, from = null }) {
1458
1461
  const command = [
1459
1462
  ...coreCommand.map(word),
1460
1463
  ...['playtest', 'build', id, '--json'],
1461
- ...(from ? ['--from', word(from)] : []),
1464
+ // A worktree card's build waits for a build by click on a ticket (docs/Handoff-Plan.md d6).
1465
+ ...(from ? ['--from', word(from), '--wait'] : []),
1462
1466
  ].join(' ');
1463
1467
  const child = spawnAgent(command, projectDir, {});
1464
1468
  sessions.add(child);
@@ -1531,11 +1535,139 @@ function refusedShelve(dir, item) {
1531
1535
  };
1532
1536
  }
1533
1537
 
1538
+ /** The build tickets that wait (core lib/build-queue.js), in their order: their waiter lives. */
1539
+ export function buildTickets(logs) {
1540
+ if (!existsSync(logs)) return [];
1541
+ const tickets = [];
1542
+ for (const name of readdirSync(logs)) {
1543
+ if (!/^\.build-\d+\.json$/.test(name)) continue;
1544
+ try {
1545
+ const t = JSON.parse(readFileSync(path.join(logs, name), 'utf8'));
1546
+ if (Number.isInteger(t.n) && alive(Number(t.pid))) tickets.push(t);
1547
+ } catch {
1548
+ // Being written: the next look reads it.
1549
+ }
1550
+ }
1551
+
1552
+ return tickets.sort((a, b) => a.n - b.n);
1553
+ }
1554
+
1555
+ /** `.gcf-session/.main-run.yield`: whom a main run lets into its checkout between its cards. */
1556
+ export const yieldOf = (projectDir) => path.join(projectDir, '.gcf-session', `${MAIN_RUN}.yield`);
1557
+
1558
+ /**
1559
+ * Let the waiting builds in, one ticket at a time, before card `next` (docs/Handoff-Plan.md d6).
1560
+ * The lock names no card meanwhile; the yield is never withdrawn: the run waits until its ticket
1561
+ * is gone or its waiter dead. A Stop of the next card or the project's Hold cancels the ticket and
1562
+ * ends the run. Null to go on; else why the rest of the batch waits.
1563
+ */
1564
+ async function yieldToBuilds(projectDir, next, ctx) {
1565
+ const { logs, core } = ctx;
1566
+ if (!checkoutTicket(logs)) return null;
1567
+ const before = loosePaths(projectDir, { files: true }) ?? [];
1568
+ writeFileSync(path.join(logs, `${MAIN_RUN}.lock`), `${process.pid}\n\n`);
1569
+ try {
1570
+ for (let t = checkoutTicket(logs); t; t = checkoutTicket(logs)) {
1571
+ // Written once per ticket: a second write would erase the `builder` the waiter added.
1572
+ writeAtomic(yieldOf(projectDir), `${JSON.stringify({ run: process.pid, ticket: t.n })}\n`);
1573
+ const stop = await yieldUntil(t.n, next, ctx);
1574
+ if (stop) {
1575
+ await core(['playtest', 'cancel', String(t.n), '--json']);
1576
+ // A stop that takes long still holds the checkout: the yield stays while it lives.
1577
+ await yieldUntil(t.n, null, ctx);
1578
+
1579
+ return stop;
1580
+ }
1581
+ }
1582
+ } finally {
1583
+ await rm(yieldOf(projectDir), { force: true });
1584
+ }
1585
+
1586
+ const fresh = (loosePaths(projectDir, { files: true }) ?? []).filter((p) => !before.includes(p));
1587
+
1588
+ return fresh.length
1589
+ ? `a build by click changed ${fresh.slice(0, 3).join(', ')}: the rest of the batch waits for it`
1590
+ : null;
1591
+ }
1592
+
1593
+ /** The cards a Hold or a yield's stop leaves skipped, or null to go on. */
1594
+ async function yieldedRest(projectDir, ids, n, ctx) {
1595
+ const held = heldRest(ids, n, ctx);
1596
+ if (held) return held;
1597
+ const why = await yieldToBuilds(projectDir, ids[n], ctx);
1598
+
1599
+ return why ? ids.slice(n).map((id) => ({ id, result: 'skipped', reason: why })) : null;
1600
+ }
1601
+
1602
+ /**
1603
+ * The first ticket that needs the checkout: a worktree build (`from`) needs only its turn, and the
1604
+ * run does not wait for it.
1605
+ */
1606
+ const checkoutTicket = (logs) => buildTickets(logs).find((t) => !t.job?.from);
1607
+
1608
+ /**
1609
+ * Wait while ticket `n` lives, read again each time (its waiter takes it after the CLI that wrote
1610
+ * it ended), and while a builder the yield let in lives. The Stop of card `next` or a Hold of the
1611
+ * project says why not; `next` null: only wait.
1612
+ */
1613
+ async function yieldUntil(n, next, ctx) {
1614
+ const file = path.join(ctx.logs, `.build-${n}.json`);
1615
+ const dir = path.dirname(path.dirname(ctx.logs));
1616
+ const lives = () => {
1617
+ try {
1618
+ return alive(Number(JSON.parse(readFileSync(file, 'utf8')).pid));
1619
+ } catch {
1620
+ // Gone, or being written: a file being written is there, its waiter too.
1621
+ return existsSync(file);
1622
+ }
1623
+ };
1624
+
1625
+ while (lives() || builderLives(dir)) {
1626
+ if (next && existsSync(stopOf(ctx.logs, next)))
1627
+ return 'stopped while a build by click had its turn';
1628
+ if (next && projectHoldOf(ctx.logs, ctx)) return 'the project is held: it waits for Release';
1629
+ await new Promise((r) => setTimeout(r, 300));
1630
+ }
1631
+
1632
+ return null;
1633
+ }
1634
+
1635
+ /** Whether the builder of the yield lives: a pid of a process, not `null` read as 0. */
1636
+ function builderLives(projectDir) {
1637
+ try {
1638
+ const b = JSON.parse(readFileSync(yieldOf(projectDir), 'utf8')).builder;
1639
+
1640
+ return Number.isInteger(b) && b > 0 && alive(b);
1641
+ } catch {
1642
+ return false;
1643
+ }
1644
+ }
1645
+
1646
+ /**
1647
+ * The builder a yield let in, alive: it holds the checkout even when its run died. A yield whose
1648
+ * run and builder are both dead goes.
1649
+ */
1650
+ function yieldHeld(projectDir) {
1651
+ let y;
1652
+ try {
1653
+ y = JSON.parse(readFileSync(yieldOf(projectDir), 'utf8'));
1654
+ } catch {
1655
+ return false;
1656
+ }
1657
+
1658
+ if (Number.isInteger(y.builder) && y.builder > 0 && alive(y.builder)) return true;
1659
+ if (!alive(Number(y.run))) rmSync(yieldOf(projectDir), { force: true });
1660
+
1661
+ return false;
1662
+ }
1663
+
1534
1664
  /** The items a main run has yet to reach, one id a line. */
1535
1665
  export const queueOf = (logs) => path.join(logs, `${MAIN_RUN}.queue`);
1536
1666
 
1537
1667
  /** The main checkout for a main run, with its items queued; null while another run holds it. */
1538
1668
  async function holdMain(logs, ids) {
1669
+ // A build its dead run let in still works in the checkout (docs/Handoff-Plan.md d6).
1670
+ if (yieldHeld(path.dirname(path.dirname(logs)))) return null;
1539
1671
  const release = await claim(lockFile(logs, MAIN_RUN));
1540
1672
  // Whole or not at all: a gate reads it meanwhile. With no queue the checkout is not held:
1541
1673
  // another run's gate would see the items free.
@@ -1976,10 +2108,12 @@ export function runEndOf(i, projectDir, launch = null) {
1976
2108
  (word === 'skipped' ? 'skipped' : word === 'merged' ? 'submitted' : 'no-result'));
1977
2109
  const plan = launch?.planOf?.(i.id) ?? null;
1978
2110
  let unticked = null;
2111
+ let handoff = false;
1979
2112
  try {
1980
- if (plan)
1981
- unticked = (readFileSync(path.join(projectDir, plan), 'utf8').match(/^\s*- \[ \] /gm) ?? [])
1982
- .length;
2113
+ const text = plan ? readFileSync(path.join(projectDir, plan), 'utf8') : '';
2114
+ if (plan) unticked = (text.match(/^\s*- \[ \] /gm) ?? []).length;
2115
+ // The card's handoff to play is there to read (docs/Handoff-Plan.md d3): the board draws it.
2116
+ handoff = /^## Play notes[ \t]*\r?$/m.test(text);
1983
2117
  } catch {
1984
2118
  // Archived with its item: nothing left.
1985
2119
  }
@@ -2008,6 +2142,7 @@ export function runEndOf(i, projectDir, launch = null) {
2008
2142
  review: review ? (review.ok === false ? 'failed' : 'done') : null,
2009
2143
  // A branch that went in took its work along.
2010
2144
  left: outcome === 'submitted' ? null : leftIn(launch?.worktree, projectDir),
2145
+ handoff,
2011
2146
  };
2012
2147
  }
2013
2148
 
package/extension.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
3
3
  "name": "gcf-harness-aif-ext",
4
- "version": "0.25.0",
4
+ "version": "0.26.0",
5
5
  "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
6
6
  "skills": [
7
7
  "skills/gcf-run",
@@ -273,11 +273,26 @@ export function listThreads(dir) {
273
273
  /** Whether the main run's lock (`runs/<main>.lock`) names a live process. */
274
274
  function mainBusy(file) {
275
275
  if (!file) return false;
276
- try {
277
- return alive(Number(readFileSync(file, 'utf8').split('\n')[0]));
278
- } catch {
279
- return false;
280
- }
276
+ const pidIn = (f, read) => {
277
+ try {
278
+ // `builder: null` after a release would read as 0, which `kill(0, 0)` answers as alive.
279
+ const pid = Number(read(readFileSync(f, 'utf8')));
280
+
281
+ return Number.isInteger(pid) && pid > 0 && alive(pid);
282
+ } catch {
283
+ return false;
284
+ }
285
+ };
286
+
287
+ // The builder a main run's yield let in holds the checkout too, its run dead or not (core
288
+ // lib/build-queue.js): `.gcf-session/.main-run.yield` beside `runs/.main-run.lock`.
289
+ return (
290
+ pidIn(file, (t) => t.split('\n')[0]) ||
291
+ pidIn(
292
+ path.join(path.dirname(path.dirname(file)), '.main-run.yield'),
293
+ (t) => JSON.parse(t).builder,
294
+ )
295
+ );
281
296
  }
282
297
 
283
298
  const hashOf = (text) => createHash('sha256').update(text).digest('hex').slice(0, 16);
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-session",
3
- "version": "0.19.0",
3
+ "version": "0.19.1",
4
4
  "private": true,
5
5
  "description": "The session engine of GCF: one agent session and a run as a chain of them, the chat protocol, the provider adapters. Bundled by gcf-harness-aif-ext and gcf-board, never published.",
6
6
  "type": "module",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-harness-aif-ext",
3
- "version": "0.25.0",
3
+ "version": "0.26.0",
4
4
  "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -28,7 +28,7 @@
28
28
  "prepack": "node -e \"const p=require('./package.json'),e=require('./extension.json');if(p.version!==e.version)throw new Error('version mismatch: package.json '+p.version+' vs extension.json '+e.version);require('node:fs').statSync('node_modules/gcf-session/lib/index.js')\""
29
29
  },
30
30
  "peerDependencies": {
31
- "gcf-aif-ext": ">=0.26.0 <0.27.0"
31
+ "gcf-aif-ext": ">=0.28.0 <0.29.0"
32
32
  },
33
33
  "dependencies": {
34
34
  "gcf-session": "file:../gcf-session"
@@ -41,6 +41,10 @@ forbidden_behaviors:
41
41
  - with `--worktree`, a `--decide` decision and each `--assume` assumption go into the plan under `## Outcome` before the commit of step 24
42
42
  - its lines: `- decide: go|no`, `- reason: <why>`, one `- assume: <question> = <value>` each; the harness records them on main in the item's move
43
43
  - a plan that already holds a `## Outcome` from an earlier run gets this run's in its place, not a second one
44
+ - before the commit of step 16 a gate-verdict card's plan gets `## Play notes`, in main and in a worktree alike
45
+ - `## Play notes` starts from `ai-factory gcf play-notes <id> --template`
46
+ - under `### Question` go notes on the card's `miss_criterion`; under `### Try`, what to do in the game; under `### Rows`, a note per row the template lists; then `### Watch out`
47
+ - the player's fields say what is seen and what to do, in the player's words: hashes, checks, paths and commands go to `### Notes` alone
44
48
  - do not read a `gcf/` file outside the readset from `ai-factory gcf context`, but `gcf/INDEX.md` and `gcf/config.yml`
45
49
  - do not continue past a failed gate: report the one-line reason, delete `.gcf-session/readset.json`, and stop - a stop is a normal outcome
46
50
  - do not compare the audit numbers yourself: the gate command is the only judge of whether an item may go
@@ -109,14 +113,14 @@ workflow:
109
113
  16. after a review fix, run `ai-factory gcf verify <id>` again (a red run counts against `dod_attempts`); tick the plan tasks done outside aif-implement, the verify and the review; then commit the code, its plan and the `live:` delta via aif-commit
110
114
  17. gate `verdict` or `decision`: run `ai-factory gcf submit <id>`; gate `auto`: `ai-factory gcf close <id>` - a soft unit closes unplayed; the core defers what the gates defer; never pass `--unverified`, the human's call
111
115
  18. a dependency still waiting for its verdict refuses the close: run `ai-factory gcf block <id> --reason "waits for <dep>"`
112
- 19. close the run: delete `.gcf-session/readset.json`; report a row per plan pass: pass, blocking, polish, result; hand the human `ai-factory gcf playtest session` when the audit's `play_milestone` is set or an item waits for its verdict
116
+ 19. close the run: delete `.gcf-session/readset.json`; end with one line of text: what is done and what waits for the human; the board and `ai-factory gcf item show <id>` give the handoff, so no table of passes and no commands for the human
113
117
  20. after a tune verdict, an unblock or an amend, re-enter this pipeline at step 5: the gates re-run because the counters moved
114
118
  21. with `--worktree`: skip the integrate of step 1, steps 2-4 and the playtest of step 19, and change no `gcf/` file but the item's `live:`, a slot the human's word contradicts, and new inbox entries (`ai-factory gcf inbox add --category <c>`)
115
119
  22. with `--worktree`, every stop - a failed gate, an over budget readset, a failed plan check, a refused command, steps 12, 14, 18 - writes `{"block": "<reason>"}` to `.gcf-session/outcome.json` and ends the session
116
120
  23. with `--worktree`, run no `ai-factory gcf block`, `submit` or `close`: the core refuses them on a `work/` branch, and the harness records the move on main
117
121
  24. with `--worktree`, step 17 is: commit everything but `gcf/.metrics`, then run `ai-factory gcf verify <id> --mark`; the harness merges the branch
118
122
  25. with `--handoff`: run steps 1, 5 and 6, read the plan's `## Handoff`; `gcf plan check <id> --json` says `converged`: skip steps 7-11, go on at step 13; else go on with the passes after `## Passes`
119
- 26. with `--handoff`, take the review findings and the DoD diagnosis of `## Handoff` into steps 13-15, and delete the section before the commit of step 16
123
+ 26. with `--handoff`, take the review findings and the DoD diagnosis of `## Handoff` into steps 13-15, and delete that section alone before the commit of step 16: `## Play notes` and `## Outcome` stay
120
124
  27. without `--no-lessons` and without `--worktree`, end the run with the lessons: run `ai-factory gcf lessons prompt <id>` for each item of the run and do what it says
121
125
 
122
126
  invocation: