gcf-harness-aif-ext 0.30.0 → 0.31.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.31.0 needs gcf-aif-ext 0.32 (docs/Fallback-Fidelity-Plan.md): update both together with gcf-board 0.32.0 (`gcf board --json` is `schema: 6`), then run `ai-factory gcf init`. `run_mode` is `main` by default now; set `run_mode: worktree` to keep parallel runs. Without `--mode` an item runs where the core says (`runs_in`): its own `run_mode`, else where its kept session ran (the record `<id>.agent.json` now carries `mode`; `--fresh` drops the session, not that place), else `worktree` while its worktree copy or `work/<id>` branch lives, else the project's. A review row that cannot make its pass (codex-review `failed`, `skipped` for no Codex, the Agent tool's refusal, a subagent with no answer or at its usage limit) gives way to the next of its `fallback`, then to the session's own model; the pass records `--by <who> --for <the row>`. A subagent's usage limit no longer stops the session (bundled gcf-session).
47
+
46
48
  0.25.1 changes nothing but the peer range: it runs with `gcf-aif-ext` 0.26 and 0.27.
47
49
 
48
50
  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`.
@@ -131,7 +133,7 @@ Updating keeps the hook entry valid — it points into the extension's install d
131
133
  - `/gcf-run` writes a plan task's code through aif-implement, so the plan ticks show the item's progress, and answers aif-implement's questions itself: no commit, stash or merge.
132
134
 
133
135
  0.8.0, to update together with core 0.7.0:
134
- - `run_mode: main` in `gcf/config.yml` (or `run --mode main`): items run one after another in the main checkout, for an agent that works through an editor bound to the project folder. The item carries the core's session mark (`gcf claim`), not a run lock, so the agent records its own move; one run works the checkout at a time (`.gcf-session/runs/.main-run.lock`).
136
+ - `run_mode: main` in `gcf/config.yml` (or `run --mode main`; the default since 0.31.0): items run one after another in the main checkout, for an agent that works through an editor bound to the project folder. The item carries the core's session mark (`gcf claim`), not a run lock, so the agent records its own move; one run works the checkout at a time (`.gcf-session/runs/.main-run.lock`).
135
137
  - `gcf-harness next [N] --json`: the ready items that can run together now, by priority; each is taken while the batch with it passes the gate.
136
138
  - `gcf-harness stop <id>`: stops the session that works the item (its run lock names it); the run records no result for it and goes on with the rest. The item stays ready and its work is kept. Known limit: the session is killed at once, so a `gcf` move it was in the middle of may leave `.gcf-session/main.lock` behind (taken over once its pid is gone).
137
139
  - A run on main refreshes its item's mark every 5 minutes while the mark is its own, and the readset-guard hook refreshes live marks on each read: a long build without a gcf command does not expire it.
@@ -160,7 +162,7 @@ Removal does not touch `.claude/settings.json`: delete the entries whose command
160
162
 
161
163
  **`ai-factory gcf-harness gate <item-id…>`** — the `/gcf-run` gate as code (`--each`: each item alone, see 0.14.0 above). It reads one `gcf audit --json` report and exits 1 with a one-line reason when the items may not go: a core older than 0.4.0, a `schema:` other than 1 in `gcf/config.yml`, an id with no work item, a feature (run its children; the feature closes when they are finished), an item that is not `ready`, an unplayed dependency, no WIP room for the batch (items awaiting a verdict + the batch's `gate: verdict` items over `wip_built_limit`), or two items of the batch touching the same system unless both say `parallel: ok`. The tune limit is not a gate rule: `verdict tune` itself refuses at the limit, and an item tuned up to it still gets its last build. The skill runs it and stops on a non-zero exit — no model compares the numbers.
162
164
 
163
- **`ai-factory gcf-harness run <item-id…> [--agent "<cmd>"]`** — runs a batch at once, each item in its own worktree (`gcf worktree <id>`) with its own agent session: `claude -p --output-format stream-json --verbose "/gcf-run <id> --worktree"` by default, or the command in `--agent` / `GCF_RUN_AGENT`. The sessions run unattended, so set the agent's permissions for print mode first. A session ends with a commit and `gcf verify <id> --mark` (the `GCF-Verified` trailer); a question for the human goes into `.gcf-session/outcome.json` in its worktree, and `run` records the block on main. Then `gcf integrate` merges the verified branches and records each move, and `run` prints the playtest session. Its first step, like `/gcf-run`'s, integrates the verified branches a dead run left. A session that ended with no result leaves its item `ready`; the next `run` resumes its worktree and the agent's own session (`--resume <session_id>`, kept in `.gcf-session/runs/<id>.agent.json`), in either run mode; `--fresh` starts a new session instead. A session cut off by Claude's usage limit reports `paused (usage limit, resets 3am (…))` and `limit_resets`. Logs: `.gcf-session/runs/<id>.log`, written as the session works: a `start:` line, then one stamped line per agent message, tool call (`tool: Edit <file>`, `tool: Bash <command>`) and failed tool result, and at the end the agent's final text and `done in 34m, 212 turns, $3.41 (…tokens)`; stderr goes in as it is, and a non-Claude `--agent` keeps its own lines. With `--json`, each item carries the session's `cost_usd`, `tokens`, `turns` and `duration_ms` when the agent reported them, what it ran on (`model`, `effort`; null: the agent's own) and `log: {from, to}`, the bytes of its log this run wrote. `--model <m>` and `--effort <e>` set the model and effort of every item for this run only, over the item's own `model:` and `effort:` (`default` or none: the item's); the item file is not changed. A run sets `GCF_MOVE_BY=run` for its core calls and every agent it starts, in either mode, so the core's moves name the run as their maker. One run drives an item at a time (`.gcf-session/runs/<id>.lock`), and a resumed worktree first gets main merged in, so the answer from an `unblock` reaches the session. A worktree sees only what is committed: keep `.ai-factory.json`, the installed extensions with their `node_modules` (a `node_modules/` line in `.gitignore` drops the core's `yaml` and `cnlp-kit`, and `ai-factory gcf` fails in the worktree) and `.claude/` (skills, the readset-guard hook) in git, or the session has no `/gcf-run` and no `ai-factory gcf`. On Windows a project in a deep folder needs `git config core.longpaths true`, or `git worktree add` fails on `Filename too long`.
165
+ **`ai-factory gcf-harness run <item-id…> [--agent "<cmd>"]`** — runs a batch; under `run_mode: worktree` (or `--mode worktree`, or for a card whose worktree copy lives) at once, each item in its own worktree (`gcf worktree <id>`) with its own agent session: `claude -p --output-format stream-json --verbose "/gcf-run <id> --worktree"` by default, or the command in `--agent` / `GCF_RUN_AGENT`. The sessions run unattended, so set the agent's permissions for print mode first. A session ends with a commit and `gcf verify <id> --mark` (the `GCF-Verified` trailer); a question for the human goes into `.gcf-session/outcome.json` in its worktree, and `run` records the block on main. Then `gcf integrate` merges the verified branches and records each move, and `run` prints the playtest session. Its first step, like `/gcf-run`'s, integrates the verified branches a dead run left. A session that ended with no result leaves its item `ready`; the next `run` resumes its worktree and the agent's own session (`--resume <session_id>`, kept in `.gcf-session/runs/<id>.agent.json`), in either run mode; `--fresh` starts a new session instead. A session cut off by Claude's usage limit reports `paused (usage limit, resets 3am (…))` and `limit_resets`. Logs: `.gcf-session/runs/<id>.log`, written as the session works: a `start:` line, then one stamped line per agent message, tool call (`tool: Edit <file>`, `tool: Bash <command>`) and failed tool result, and at the end the agent's final text and `done in 34m, 212 turns, $3.41 (…tokens)`; stderr goes in as it is, and a non-Claude `--agent` keeps its own lines. With `--json`, each item carries the session's `cost_usd`, `tokens`, `turns` and `duration_ms` when the agent reported them, what it ran on (`model`, `effort`; null: the agent's own) and `log: {from, to}`, the bytes of its log this run wrote. `--model <m>` and `--effort <e>` set the model and effort of every item for this run only, over the item's own `model:` and `effort:` (`default` or none: the item's); the item file is not changed. A run sets `GCF_MOVE_BY=run` for its core calls and every agent it starts, in either mode, so the core's moves name the run as their maker. One run drives an item at a time (`.gcf-session/runs/<id>.lock`), and a resumed worktree first gets main merged in, so the answer from an `unblock` reaches the session. A worktree sees only what is committed: keep `.ai-factory.json`, the installed extensions with their `node_modules` (a `node_modules/` line in `.gitignore` drops the core's `yaml` and `cnlp-kit`, and `ai-factory gcf` fails in the worktree) and `.claude/` (skills, the readset-guard hook) in git, or the session has no `/gcf-run` and no `ai-factory gcf`. On Windows a project in a deep folder needs `git config core.longpaths true`, or `git worktree add` fails on `Filename too long`.
164
166
 
165
167
  **`ai-factory gcf-harness metrics [--since <date>] [--json]`** — the run metrics of Harness-PRD §11 from `gcf/.metrics`: how many item runs reached `submit` or `close` (a run the usage limit paused or a session cut short does not count as finished), the block reasons, what the runs cost (dollars, minutes, turns, handoffs, code written outside aif-implement), the plan checks per item (the improve passes), the DoD attempts per item and the checks that failed them, and the guard firings by hook and by item. The logs: `run-log.csv` (one line per item of each `run`: `at, item, mode, result, reason, cost_usd, input, output, cache_read, turns, duration_ms, handoffs, process, run_id, started, model, effort, log_from, log_to`; `result` is `submit`, `close`, `block`, `error`, `conflict`, `skipped`, `paused` for the usage limit, `no-result` for a session cut short, `not-started`; `run_id` is `<started>-<pid>` of the run; `model` and `effort` what the item ran on, empty for the agent's own; `log_from`, `log_to` the bytes of `.gcf-session/runs/<id>.log` this run wrote; older lines end at `process`), `guard-log.csv` (each denial of readset-guard and implement-guard, by hook: `readset`, `implement`, or `verify` for a move past the verify gate), and the core's `plan-log.csv` and `verify-log.csv`. A worktree session's lines go to the main checkout's logs; the next `gcf integrate` commits them.
166
168
 
@@ -2,8 +2,10 @@
2
2
  // pass by the Codex CLI, read-only, when row k of `review.plan|code` is Codex's. Codex runs in its
3
3
  // read-only sandbox: the audit holds by the sandbox, not by trust. The row's model is a family
4
4
  // (`sol`), made the newest listed slug of the catalog, or a full slug as it is. Its answer is
5
- // findings as JSON; with no Codex, or when it fails, the session's own subagent makes the pass
6
- // (SKILL.md, steps 8-11 and 14-16).
5
+ // findings as JSON. With no Codex, or when it fails (its usage limit comes as a non-zero exit),
6
+ // the answer carries the row's `fallback` from `gcf review row` (Fallback-Fidelity-Plan d2): a
7
+ // subagent of a model of its size makes the pass, the list over, the session's own (`by self`).
8
+ // A row that is not Codex's is skipped with no fallback: its subagent makes it (SKILL.md).
7
9
  import { spawnSync } from 'node:child_process';
8
10
  import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
9
11
  import os from 'node:os';
@@ -51,7 +53,8 @@ export function reviewPrompt({ id, kind, plan, diff }) {
51
53
 
52
54
  /**
53
55
  * Run the pass: `{findings, by}`, `{skipped: why}` (the row is not Codex's, no Codex) or
54
- * `{failed: why}`. `row` is `gcf review row`'s answer; `codex` the command (a test's fake).
56
+ * `{failed: why}`; no Codex and a failure add the row's `fallback`. `row` is `gcf review row`'s
57
+ * answer; `codex` the command (a test's fake).
55
58
  * @param {string} projectDir
56
59
  * @param {{row: any, codex?: string[], timeoutMs?: number}} o
57
60
  */
@@ -59,17 +62,21 @@ export function codexReview(projectDir, o) {
59
62
  const { row } = o;
60
63
  if (row.row?.agent !== 'codex')
61
64
  return { skipped: `pass ${row.pass} is ${row.by ?? 'no row'}'s: a subagent makes it` };
65
+ // From here the row cannot make its pass but by a stand-in: the core's `fallback`, in order
66
+ // (Fallback-Fidelity-Plan d2); an older core gives none, and the session's own subagent goes.
67
+ const standIns = Array.isArray(row.fallback) ? { fallback: row.fallback } : {};
62
68
  const cmd = o.codex
63
69
  ? { exe: o.codex[0], pre: o.codex.slice(1), shell: false }
64
70
  : { exe: 'codex', pre: [], shell: process.platform === 'win32' };
65
- if (!codexInstalled(cmd)) return { skipped: 'no codex in PATH' };
71
+ if (!codexInstalled(cmd)) return { skipped: 'no codex in PATH', ...standIns };
66
72
  // The catalog is read once a while for the project's runs (t2 d4).
67
73
  const cache = path.join(projectDir, '.gcf-session', 'codex-models.json');
68
74
  const slug = slugOf(codexModels({ cache, cmd }), row.row.model);
69
- if (!slug) return { failed: `Codex lists no model of ${row.row.model}` };
75
+ if (!slug) return { failed: `Codex lists no model of ${row.row.model}`, ...standIns };
70
76
  const { effort } = row.row;
77
+ const done = run(projectDir, cmd, { ...o, slug, effort });
71
78
 
72
- return { ...run(projectDir, cmd, { ...o, slug, effort }), by: `codex:${slug}:${effort}` };
79
+ return { ...done, by: `codex:${slug}:${effort}`, ...(done.failed ? standIns : {}) };
73
80
  }
74
81
 
75
82
  /**
@@ -685,7 +685,10 @@ function registerCodexReview(harness) {
685
685
  )
686
686
  .requiredOption('--kind <kind>', 'plan or code')
687
687
  .requiredOption('--pass <k>', 'the pass number, 1 or more')
688
- .option('--json', 'machine output: {findings, by} | {skipped} | {failed, by?}')
688
+ .option(
689
+ '--json',
690
+ 'machine output: {findings, by} | {skipped, fallback?} | {failed, by?, fallback?}',
691
+ )
689
692
  .action((id, o) => {
690
693
  const r = /** @type {any} */ (codexReviewOf(process.cwd(), id, o));
691
694
  if (o.json) return console.log(JSON.stringify(r));
@@ -730,7 +733,12 @@ function registerRun(harness) {
730
733
  'stop a session that runs longer; its item stays ready (default: session_timeout_min of ' +
731
734
  `gcf/config.yml, else ${DEFAULT_TIMEOUT_MIN})`,
732
735
  )
733
- .option('--mode <mode>', 'worktree | main (default: run_mode of gcf/config.yml)')
736
+ .option(
737
+ '--mode <mode>',
738
+ "worktree | main (default: the core's runs_in: the item's own run_mode, else where its " +
739
+ 'kept session ran, else worktree while its live copy lives, else run_mode of ' +
740
+ 'gcf/config.yml)',
741
+ )
734
742
  .option('--fresh', 'start new agent sessions: an interrupted one is not resumed')
735
743
  .option(
736
744
  '--allow <rule>',
package/commands/run.js CHANGED
@@ -500,6 +500,8 @@ function recordFor(r) {
500
500
  ...((!r.handoffPending && !r.session_id) || r.held || r.phaseEnded ? { counted: true } : {}),
501
501
  ...whyHandedOver(r),
502
502
  ...(r.skipped ? { process: OUTSIDE_IMPLEMENT } : {}),
503
+ // Where it ran: its resume goes on there, whatever the default (Fallback-Fidelity-Plan d1).
504
+ mode: r.main ? 'main' : 'worktree',
503
505
  at: new Date().toISOString(),
504
506
  };
505
507
  }
@@ -983,7 +985,10 @@ async function itemJob(s, rec) {
983
985
  // Whole or not at all: the board reads it while the run waits (AD-34).
984
986
  persist: (state) => {
985
987
  persisted = true;
986
- writeAtomic(recordOf(logs, r.id), `${JSON.stringify(recordFor(state), null, 2)}\n`);
988
+ writeAtomic(
989
+ recordOf(logs, r.id),
990
+ `${JSON.stringify(recordFor({ ...state, main: r.main }), null, 2)}\n`,
991
+ );
987
992
  },
988
993
  quota,
989
994
  learned: launch?.learned,
@@ -2173,8 +2178,13 @@ function commandsOf(core, agent, board, override) {
2173
2178
  return { agentOf, agentFirst: (id) => commandOf(board, id) };
2174
2179
  }
2175
2180
 
2176
- /** Where an item's run goes: the run's mode, else the item's `run_mode`, else the project's. */
2177
- const modeOf = (mode, board, item) => mode ?? item?.run_mode ?? board.run_mode ?? 'worktree';
2181
+ /**
2182
+ * Where an item's run goes (Fallback-Fidelity-Plan d1): the run's mode, else the core's choice
2183
+ * (`runs_in`: its own `run_mode`, the mode its kept record names, worktree while its copy lives,
2184
+ * the project's), else, from an older core, its `run_mode` or the project's.
2185
+ */
2186
+ const modeOf = (mode, board, item) =>
2187
+ mode ?? item?.runs_in ?? item?.run_mode ?? board.run_mode ?? 'main';
2178
2188
 
2179
2189
  /**
2180
2190
  * Pick up orphans, gate the batch, run each item where it runs: the run's `mode`, else its own
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.30.0",
4
+ "version": "0.31.0",
5
5
  "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
6
6
  "skills": [
7
7
  "skills/gcf-run",
@@ -418,9 +418,13 @@ function contextOf(e) {
418
418
  return { context: tokens, ...(e.message.id ? { turn: String(e.message.id) } : {}) };
419
419
  }
420
420
 
421
- /** An assistant turn: its tool calls and its text, which may be the usage-limit message. */
421
+ /**
422
+ * An assistant turn: its tool calls and its text, which may be the usage-limit message. A
423
+ * subagent's limit is its own (Fallback-Fidelity-Plan d2): its reviewer gives way, the session
424
+ * goes on.
425
+ */
422
426
  function said(content, at, sub) {
423
- const texts = content.filter((b) => b.type === 'text').map((b) => b.text);
427
+ const texts = sub ? [] : content.filter((b) => b.type === 'text').map((b) => b.text);
424
428
 
425
429
  return {
426
430
  ...(texts.map((t) => limitIn(t)).find((l) => l.limit) ?? {}),
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-session",
3
- "version": "0.20.0",
3
+ "version": "0.21.0",
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.30.0",
3
+ "version": "0.31.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.31.0 <0.32.0"
31
+ "gcf-aif-ext": ">=0.32.0 <0.33.0"
32
32
  },
33
33
  "dependencies": {
34
34
  "gcf-session": "file:../gcf-session"
@@ -61,7 +61,14 @@ forbidden_behaviors:
61
61
  - who makes pass k of a review: `ai-factory gcf review row <id> --kind plan|code --pass <k> --json`; its `row` is `{agent, model, effort}`, its `by` the pass's `--by`, its `accepted` says the operator took the open findings as they are
62
62
  - a `claude` row: a fresh subagent with the row's `model` and `effort`; a plan pass has the description `gcf review plan`, a code review `gcf review`: the operator's chat shows the review by that name
63
63
  - a `codex` row: run `ai-factory gcf-harness codex-review <id> --kind plan|code --pass <k> --json` in the background; check each finding it returns against the code, apply the ones that hold, and record the pass with its `by`
64
- - `skipped` or `failed` from it, or a row the Agent tool refuses: make the pass with a subagent of your own model and record it with `--by self`
64
+ - a row cannot make its pass when codex-review answers `failed`, when it answers `skipped` for no codex in PATH, when the Agent tool refuses its subagent, or when its subagent ends with no answer or with a usage-limit line
65
+ - `skipped` because the row is not Codex's is no such case: its subagent makes the pass
66
+ - a row that cannot make its pass gives way to the next row of `fallback` (from `review row`, or from codex-review): a fresh subagent with that row's model and effort makes the whole pass anew
67
+ - drop the findings of the attempt that failed
68
+ - record a stand-in's pass with `--by claude:<model>:<effort> --for <the row>`
69
+ - the `fallback` list over: make the pass with a subagent of your own model and record it with `--by self --for <the row>`
70
+ - no `fallback` field at all: make the pass with a subagent of your own model and record it with `--by self` and no `--for`: an older core takes no `--for`
71
+ - do not repeat a subagent's usage-limit line in your own reply
65
72
  - no row (`rows` 0): no review of that kind; a plan converges at once, the code goes to its commit after a green DoD
66
73
  - the code reviewer reads the diff of `ai-factory gcf review row <id> --kind code --pass <k> --diff --json` (its `diff.file`) and only reads: it changes nothing
67
74
  - the verdict of `gcf plan pass`: `continue` is the next row's pass, `converged` ends the review, `stalled` is the stop of step 11 or of the code's stall