gcf-harness-aif-ext 0.22.0 → 0.23.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.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
+
46
48
  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.
47
49
 
48
50
  0.5.1 is a fix release. During a run, `gcf/config.yml` is always readable, and a Grep inside `gcf/` reads only readset files. An import breaks a `depends:` cycle the pair checks closed and asks a D1 about it. It cuts a section longer than a segment at paragraphs, and lens and pair prompts carry a window around the quote. `/gcf-run` checks the plan against each pillar's invariant and asks each pillar's review question over the diff. Use it with core 0.4.1, which brings the parent feature into the readset.
@@ -50,20 +50,35 @@ function itemProblem(id, item, report) {
50
50
  return `${id}: its feature ${parent.id} awaits a decision — decide it first`;
51
51
  }
52
52
 
53
- // A dependency inside the same batch lands here too: the dependent waits for it.
54
- const open = report.open_depends.find((o) => o.id === id);
55
- if (open) {
56
- return (
57
- `${id} depends on unplayed ${open.depends.join(', ')} — playtest them first; ` +
58
- 'a killed one never plays: take it out of depends, or drop'
59
- );
60
- }
61
-
62
53
  // The tune limit is held by `verdict tune` itself: an item tuned up to the limit is still
63
54
  // built once more, and refusing that run would leave it stuck in ready.
64
55
  return null;
65
56
  }
66
57
 
58
+ const THEN = {
59
+ ready: 'run it first',
60
+ blocked: 'unblock it first',
61
+ 'awaiting-decision': 'decide it first',
62
+ };
63
+
64
+ /** What an item waits for, each dependency by what it takes: a card not built has no playtest. */
65
+ function waitWords(id, depends, byId) {
66
+ const each = depends.map((d) => {
67
+ const item = byId.get(d);
68
+ if (!item)
69
+ return (
70
+ `${d}, which has no work item: card it, or take it out of depends ` +
71
+ `(a killed one never plays: take it out, or drop ${id})`
72
+ );
73
+ if (item.type === 'feature') return `${d}, a feature: its children finish first`;
74
+ if (item.running) return `${d}, which is running: it ends first`;
75
+
76
+ return `${d}, which is ${item.status}: ${THEN[item.status] ?? 'it ends first'}`;
77
+ });
78
+
79
+ return `${id} waits for ${each.join('; ')}`;
80
+ }
81
+
67
82
  /**
68
83
  * Why the batch as a whole may not go, or null. `elsewhere` are the items other runs drive now:
69
84
  * a board starts one run per click, so each run sees the others only through their locks.
@@ -100,7 +115,11 @@ function batchProblem(items, wip, elsewhere = []) {
100
115
  return null;
101
116
  }
102
117
 
103
- const verdict = (reason) => ({ pass: !reason, reason: reason ?? '' });
118
+ const verdict = (reason, waits) => ({
119
+ pass: !reason,
120
+ reason: reason ?? '',
121
+ ...(waits && { waits }),
122
+ });
104
123
 
105
124
  const rank = (i) => i.priority ?? Number.MAX_SAFE_INTEGER;
106
125
 
@@ -215,6 +234,10 @@ export function gate(report, ids) {
215
234
  for (const id of ids) {
216
235
  const problem = itemProblem(id, byId.get(id), report);
217
236
  if (problem) return verdict(problem);
237
+ // A dependency inside the same batch lands here too: the dependent waits for it. `waits`: no
238
+ // failure, a queue keeps the item for when it is done.
239
+ const open = report.open_depends.find((o) => o.id === id);
240
+ if (open) return verdict(waitWords(id, open.depends, byId), { id, depends: open.depends });
218
241
  }
219
242
 
220
243
  return verdict(
@@ -461,8 +484,12 @@ function printEach({ items, dirty }) {
461
484
 
462
485
  function runGate(ids, opts) {
463
486
  if (opts.each) {
464
- const dirty = loosePaths(process.cwd());
465
- const result = { ...gateEach(auditReport(), [...new Set(ids)]), ...(dirty && { dirty }) };
487
+ const report = auditReport();
488
+ // A card's work in the folder is no human's: the next claim shelves it (lib/shelf.js).
489
+ const own = report.main_work?.paths;
490
+ const loose = loosePaths(process.cwd(), { files: Boolean(own) });
491
+ const dirty = own ? loose?.filter((p) => !own.includes(p)) : loose;
492
+ const result = { ...gateEach(report, [...new Set(ids)]), ...(dirty && { dirty }) };
466
493
  if (opts.json) console.log(JSON.stringify(result));
467
494
  else printEach(result);
468
495
 
@@ -710,7 +737,13 @@ export function stopRun(projectDir, id, core = cliCore(projectDir)) {
710
737
  * lessons its sessions left in the inbox.
711
738
  */
712
739
  export const itemLine = (i) =>
713
- [`${i.id}: ${i.result}`, i.reason ?? i.conflict ?? i.error ?? i.skipped, i.process]
740
+ [
741
+ `${i.id}: ${i.result}`,
742
+ i.reason ?? i.conflict ?? i.error ?? i.skipped,
743
+ i.process,
744
+ i.shelved && `${i.shelved.id}'s work went to ${i.shelved.branch}`,
745
+ i.returned && `its work came back with ${i.conflicts?.length ?? 0} conflict(s)`,
746
+ ]
714
747
  .filter(Boolean)
715
748
  .join(' — ') + (i.lessons ? `, ${i.lessons} lesson${i.lessons > 1 ? 's' : ''}` : '');
716
749
 
package/commands/run.js CHANGED
@@ -482,16 +482,50 @@ const taskOf = (r, launch, after) => {
482
482
  * resume of the session its last run kept (the engine resumes it in the same directory, so the
483
483
  * agent finds it).
484
484
  */
485
- const promptOf = (r, launch) => (kind, caps, rec) => {
486
- const task = taskOf(r, launch, caps.after);
487
- if (kind === 'handoff') return `${task} --handoff`;
488
- if (kind !== 'resume') return task;
489
- // One plain line: the prompt goes into the shell command in double quotes.
490
- const ended = String(rec.ended).replace(/[^\w -]/g, '');
491
-
492
- return `Continue ${task}: the session was cut off (${ended}). Pick up where you stopped.`;
485
+ const promptOf = (r, launch) => {
486
+ // The first message only: a later session finds the files as this one left them.
487
+ let note = folderNote(r.folder);
488
+
489
+ return (kind, caps, rec) => {
490
+ const told = note;
491
+ note = '';
492
+ const task = taskOf(r, launch, caps.after);
493
+ if (kind === 'handoff') return `${task} --handoff${told}`;
494
+ if (kind !== 'resume') return `${task}${told}`;
495
+ // One plain line: the prompt goes into the shell command in double quotes.
496
+ const ended = String(rec.ended).replace(/[^\w -]/g, '');
497
+
498
+ const cut = `the session was cut off (${ended})`;
499
+
500
+ return `Continue ${task}: ${cut}. Pick up where you stopped.${told}`;
501
+ };
493
502
  };
494
503
 
504
+ /**
505
+ * What came back into the folder at the claim (`gcf claim --json`), for a session that may believe
506
+ * its files are as it left them; empty when nothing did. Plain words: see `promptOf`.
507
+ */
508
+ export function folderNote(folder) {
509
+ if (!folder?.returned) return '';
510
+ const names = (conflicts) =>
511
+ conflicts
512
+ .slice(0, 20)
513
+ .map((c) => c.path.replace(/[^\p{L}\p{N}_ ./-]/gu, ''))
514
+ .join(', ') + (conflicts.length > 20 ? ` and ${conflicts.length - 20} more` : '');
515
+ const marked = folder.conflicts.filter((c) => !c.kept_main);
516
+ const kept = folder.conflicts.filter((c) => c.kept_main);
517
+ const { id, files, copy, staged, branch_moved } = folder.returned;
518
+
519
+ return (
520
+ ` Your unfinished work came back into the folder: ${files} file(s), main moved ` +
521
+ `${folder.moved} commit(s) meanwhile.` +
522
+ (marked.length ? ` Conflict markers to resolve first, or block: ${names(marked)}.` : '') +
523
+ (kept.length ? ` Kept main's copy, yours is in commit ${copy}: ${names(kept)}.` : '') +
524
+ (staged ? ` What you had staged apart from the disk is in commit ${staged}.` : '') +
525
+ (branch_moved ? ` Branch work/${id} moved on and stays: its new commits are not here.` : '')
526
+ );
527
+ }
528
+
495
529
  /** The report note of an item whose session skipped gcf-run step 13. */
496
530
  export const OUTSIDE_IMPLEMENT = 'code written outside aif-implement';
497
531
  /** The report note of a main-mode item moved with `--unverified` (its commit says so). */
@@ -1004,8 +1038,10 @@ async function runMain(projectDir, ids, releaseMain, ctx) {
1004
1038
  };
1005
1039
 
1006
1040
  items.push(await mainItem(projectDir, id, { ...ctx, dequeue }));
1007
- await postEnd(ctx, items.at(-1));
1008
- const left = leftBehind(projectDir, items.at(-1), loose);
1041
+ if (!items.at(-1).shelve) await postEnd(ctx, items.at(-1));
1042
+ const left = items.at(-1).shelve
1043
+ ? refusedShelve(projectDir, items.at(-1))
1044
+ : leftBehind(projectDir, items.at(-1), loose);
1009
1045
  if (left) {
1010
1046
  items.at(-1).left = left.paths;
1011
1047
  items.push(
@@ -1026,12 +1062,13 @@ async function runMain(projectDir, ids, releaseMain, ctx) {
1026
1062
  * The checkout's uncommitted paths outside `gcf/` and `GLOSSARY.md`, untracked ones too (a new
1027
1063
  * folder as one): a main run's code lands among them, so the board warns before its click (Tails
1028
1064
  * "Первым" 6). The moves' own refusals guard `gcf/` and the glossary (core 0.21's gate scope).
1029
- * Null outside a git checkout.
1065
+ * Null outside a git checkout. `files`: a new folder as its files, to compare with a card's paths.
1030
1066
  */
1031
- export function loosePaths(dir) {
1067
+ export function loosePaths(dir, { files = false } = {}) {
1032
1068
  // No optional locks: a main run's agent may be committing in the same checkout.
1033
1069
  const args = [
1034
- ...['--no-optional-locks', 'status', '--porcelain', '-z', '--', '.'],
1070
+ ...['--no-optional-locks', 'status', '--porcelain', '-z', ...(files ? ['-uall'] : [])],
1071
+ ...['--', '.'],
1035
1072
  ...[':(exclude)gcf', ':(exclude)GLOSSARY.md'],
1036
1073
  ];
1037
1074
  const res = spawnSync('git', args, { cwd: dir, encoding: 'utf8' });
@@ -1055,10 +1092,11 @@ const COMMITTED = ['submit', 'close', 'decide', 'deferred'];
1055
1092
  * paths that were not loose before it (`loose`), and the next item would build on top of them. A
1056
1093
  * plan under `.ai-factory/` is no such work: a block at the plan's stage leaves one by design.
1057
1094
  * shortcut: a path already loose before it and changed again passes as a human's, as the status
1058
- * alone cannot tell them apart; comparing hashes would.
1095
+ * alone cannot tell them apart; comparing hashes would. A card the folder's baseline names goes
1096
+ * further: the next claim shelves its work (docs/Shelve-Plan.md d9).
1059
1097
  */
1060
1098
  function leftBehind(dir, item, loose) {
1061
- if (COMMITTED.includes(item.result) || !loose) return null;
1099
+ if (COMMITTED.includes(item.result) || !loose || folderHolds(dir, item.id)) return null;
1062
1100
  const fresh = (loosePaths(dir) ?? []).filter(
1063
1101
  (p) => !loose.includes(p) && !p.startsWith('.ai-factory/'),
1064
1102
  );
@@ -1071,6 +1109,27 @@ function leftBehind(dir, item, loose) {
1071
1109
  };
1072
1110
  }
1073
1111
 
1112
+ /** Whether the folder's baseline names card `id`: its loose work can be shelved. */
1113
+ function folderHolds(dir, id) {
1114
+ const r = spawnSync('git', ['log', '-1', '--format=%s', 'refs/gcf/main-work', '--'], {
1115
+ cwd: dir,
1116
+ encoding: 'utf8',
1117
+ });
1118
+
1119
+ return r.status === 0 && r.stdout.trim() === `gcf(main-work): ${id}`;
1120
+ }
1121
+
1122
+ /** The folder cannot change hands: this card and the rest wait, and a board's queue with them. */
1123
+ function refusedShelve(dir, item) {
1124
+ delete item.shelve;
1125
+ const paths = loosePaths(dir) ?? [];
1126
+
1127
+ return {
1128
+ paths: paths.length ? paths : [`work/${item.id}`],
1129
+ reason: `${item.id} did not start: ${item.reason}`,
1130
+ };
1131
+ }
1132
+
1074
1133
  /** The items a main run has yet to reach, one id a line. */
1075
1134
  export const queueOf = (logs) => path.join(logs, `${MAIN_RUN}.queue`);
1076
1135
 
@@ -1095,19 +1154,24 @@ async function mainItem(projectDir, id, ctx) {
1095
1154
  let r;
1096
1155
  let started = false;
1097
1156
  let marked = false;
1157
+ let folder = /** @type {any} */ (null);
1098
1158
  const head = headOf(projectDir);
1099
1159
  await rm(stopOf(logs, id), { force: true });
1100
1160
  // The checkout's lock names the item from now on: a stop before its session marks it.
1101
1161
  writeFileSync(path.join(logs, `${MAIN_RUN}.lock`), `${process.pid}\n${id}\n`);
1102
1162
  try {
1103
- const claimed = await core(['claim', id]);
1163
+ const claimed = await core(['claim', id, '--json']);
1104
1164
  if (!claimed.ok) {
1105
1165
  dequeue();
1106
- throw new Error((claimed.err || claimed.out).trim());
1166
+ const text = (claimed.err || claimed.out).trim();
1167
+ if (text.includes('gcf-refusal: {"code":"shelve"'))
1168
+ return { id, result: 'skipped', reason: text.split('\n')[0], shelve: true, started: false };
1169
+ throw new Error(text);
1107
1170
  }
1108
1171
 
1109
1172
  marked = true;
1110
1173
  dequeue();
1174
+ folder = json(claimed, 'claim');
1111
1175
  const none = async () => {};
1112
1176
 
1113
1177
  // The agent recorded the item's move: no fresh session takes it over.
@@ -1131,6 +1195,7 @@ async function mainItem(projectDir, id, ctx) {
1131
1195
  main: true,
1132
1196
  done,
1133
1197
  lessonsPrompt,
1198
+ folder,
1134
1199
  };
1135
1200
  started = true;
1136
1201
  r = await session(s, ctx);
@@ -1151,9 +1216,21 @@ async function mainItem(projectDir, id, ctx) {
1151
1216
  const note = started && movedUnverified(projectDir, id, head) ? UNVERIFIED_MOVE : null;
1152
1217
 
1153
1218
  // An item refused before its session spent nothing: the metrics keep it out of the share (§11).
1154
- return { ...item, ...r.cost, ...extras(r, note), ...(started ? {} : { started: false }) };
1219
+ return {
1220
+ ...item,
1221
+ ...r.cost,
1222
+ ...extras(r, note),
1223
+ ...(started ? {} : { started: false }),
1224
+ ...folderReport(folder),
1225
+ };
1155
1226
  }
1156
1227
 
1228
+ /** The report names what went where: a shelve must not read as lost work. */
1229
+ const folderReport = (folder) => ({
1230
+ ...(folder?.shelved ? { shelved: folder.shelved } : {}),
1231
+ ...(folder?.returned ? { returned: folder.returned, conflicts: folder.conflicts } : {}),
1232
+ });
1233
+
1157
1234
  /** The checkout's HEAD, or null before its first commit. */
1158
1235
  /** Whether main merged item `id`'s branch since `head`: the integrator's `gcf(integrate): <id>`. */
1159
1236
  function mergedSince(dir, id, head) {
@@ -1721,7 +1798,11 @@ async function runBatch(
1721
1798
 
1722
1799
  return { passed: verdict, claims: held };
1723
1800
  });
1724
- if (!passed.pass) return { orphans, gate: passed.reason, items: [] };
1801
+ if (!passed.pass) {
1802
+ const waits = passed.waits ? { waits: passed.waits } : {};
1803
+
1804
+ return { orphans, gate: passed.reason, ...waits, items: [] };
1805
+ }
1725
1806
 
1726
1807
  const { agentOf, agentFirst } = commandsOf(core, agent, board, override);
1727
1808
  const ctx = {
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.22.0",
4
+ "version": "0.23.0",
5
5
  "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
6
6
  "skills": [
7
7
  "skills/gcf-run",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-harness-aif-ext",
3
- "version": "0.22.0",
3
+ "version": "0.23.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.20.0 <0.24.0"
31
+ "gcf-aif-ext": ">=0.24.0 <0.25.0"
32
32
  },
33
33
  "dependencies": {
34
34
  "gcf-session": "file:../gcf-session"
@@ -11,6 +11,10 @@ purpose:
11
11
  - outside `--worktree`, mark each item running after its gate passes: `ai-factory gcf claim <id>`; a move clears the mark, and an item left without one gets `ai-factory gcf release <id>`
12
12
  - a claimed item takes only its session's moves: run `submit`, `close` and `block` on it with `--claimed`
13
13
  - a refused claim means another session works the item: report that item as taken and go on with the next; never `release` it, that is the human's call
14
+ - a claim refused with `gcf-refusal: {"code":"shelve",...}` means the folder cannot change hands: report the item as not started with its reason and stop the run; move no file by hand
15
+ - a claim moves files in the project folder: the unfinished work of the item that held it goes to branch `work/<other>`, and this item's own comes back
16
+ - a claim's `conflict <path>: resolve its markers` lines, or the words after the flags of the session's first message, come before everything else: resolve each marker and go on, or `block` and name the paths
17
+ - a claim's `conflict <path>: kept main's` line keeps main's file; the commit it names holds the item's copy, read it with `git show <commit>:<path>`
14
18
  - an item the audit lists `running_by: you` is held by this session or its harness run, and `unowned` by nobody: the claim passes; `session` or `run` is someone else's
15
19
 
16
20
  inputs:
@@ -83,7 +87,7 @@ workflow:
83
87
  2. for a unit still in `gcf/design/`: take it with the gcf-card skill first
84
88
  3. for a feature id: replace it with its `ready` children from the audit report's `items` (`parent` names the feature) that are not in `open_depends`; a feature in `awaiting-decision` starts none of them
85
89
  4. of those children, keep one per subsystem unless every child sharing it says `parallel: ok`; the rest wait for the next run; an empty list: report "nothing to run" and stop
86
- 5. gate: run `ai-factory gcf-harness gate <item-ids...>` over the whole batch; a non-zero exit is a failed gate, its stderr line is the reason
90
+ 5. gate: run `ai-factory gcf-harness gate <item-ids...>` over the whole batch; a non-zero exit is a failed gate, its stderr line is the reason; outside `--worktree`, then claim the item and take its conflict lines first
87
91
  6. readset: run `ai-factory gcf context <item-id> --json --readset`; it writes `.gcf-session/readset.json` for this session itself; `over_budget: true` stops the run with a D1 question naming the subsystem
88
92
  7. plan: run aif-plan full for the item into its `plan:` path, by default `.ai-factory/plans/<id>.md`, reading only the readset files; an existing plan (the item came back after a tune, an unblock, a continue or an amend) is kept, not rewritten
89
93
  8. improve the plan in passes, each pass a fresh subagent that reads only the plan and the readset and applies aif-improve without questions, writing each default it picks into the plan