gcf-harness-aif-ext 0.22.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/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.
@@ -168,6 +170,12 @@ Removal does not touch `.claude/settings.json`: delete the entries whose command
168
170
 
169
171
  **implement-guard** — a `UserPromptSubmit` and `PreToolUse` hook (Skill, the write tools, Bash and PowerShell). A session that starts `/gcf-run` (typed, passed to `claude -p`, or invoked as a skill) gets a state in `.gcf-session/guard/<session_id>.json`; until it invokes the aif-implement skill, Edit, Write, MultiEdit and NotebookEdit are denied outside `gcf/`, `.ai-factory/`, `.gcf-session/` and markdown, and a markdown write that adds a `- [x]` tick is denied too. Any other session is never touched, and an error lets the call through. A `gcf submit` or `gcf close` with `--unverified` is refused in such a session, after its end move too (a close the core refused does not free it for a skip): only the human moves an item past the DoD gate, from a terminal of their own. Such a refusal is logged with the hook name `verify`. The move that ends the item (`gcf block`, `submit` or `close`, through Bash or PowerShell) lets the session go, so the operator's own edits after a blocked run are free again. A plugin's skill (`<plugin>:aif-implement`) counts too. Limits: the flag is per session, so in a batch the first item's aif-implement frees the rest; a write through Bash is not seen, by the run report either.
170
172
 
173
+ ## Hold, the quota reserve, two phases
174
+
175
+ - `gcf-harness hold <id>` holds an item: its session hands over at its next call, its work waits `ready`, and your Run goes on from the plan. `hold --project` holds the queue and the autopilot (your own Run still goes); `hold --release [<id>]` lets go.
176
+ - Automation (`--wait-limit`, the autopilot's card sessions) keeps `quota_reserve_pct` of each usage window (`~/.gcf/settings.json`, 10): it waits for the 5-hour reset, and stops at the week's.
177
+ - Planning and implementation are two sessions: `GCF_RUN_PHASE` comes from `gcf plan check`; `aif-implement` goes only on a converged plan. `gcf-harness plan-review <id>` is an outside reviewer's read-only pass (Codex CLI, `plan_review:`).
178
+
171
179
  ## Docs
172
180
 
173
181
  [Harness-PRD](https://github.com/VirtualMaestro/GCF/blob/main/docs/Harness-PRD.md) is the spec: pipeline stages, gates, execution surfaces, the guard's contract.
@@ -175,3 +183,7 @@ Removal does not touch `.claude/settings.json`: delete the entries whose command
175
183
  ## License
176
184
 
177
185
  MIT
186
+
187
+ ## Playing a card
188
+
189
+ With `play:` in `gcf/config.yml`, a run builds a card that waits for its verdict at its end: in main mode before the next card starts, in worktree mode in its worktree before the merge. The build lands in `.gcf-session/builds/<id>/`. `stop <id>` ends it; a failed build is reported and stops nothing; a build that changes files git sees stops a main batch.
@@ -4,19 +4,31 @@
4
4
  // allows what a headless agent run needs (AGENT_ALLOW).
5
5
  // `ai-factory gcf-harness gate <ids…>` — the /gcf-run gate as code (Harness-PRD §4.3).
6
6
  import { readFile, writeFile, mkdir, appendFile } from 'node:fs/promises';
7
- import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
7
+ import {
8
+ existsSync,
9
+ mkdirSync,
10
+ readdirSync,
11
+ readFileSync,
12
+ realpathSync,
13
+ rmSync,
14
+ writeFileSync,
15
+ } from 'node:fs';
8
16
  import { spawnSync } from 'node:child_process';
9
17
  import path from 'node:path';
10
18
  import { fileURLToPath } from 'node:url';
11
19
  import { metricsCommand, runsCommand } from './metrics.js';
20
+ import { planReview } from './plan-review.js';
12
21
  import {
13
22
  run,
14
23
  card,
15
24
  closeFinishedFeatures,
16
25
  cliCore,
26
+ json,
17
27
  DEFAULT_AGENT,
18
28
  DEFAULT_TIMEOUT_MIN,
19
29
  MAIN_RUN,
30
+ PROJECT_HOLD,
31
+ holdMarkOf,
20
32
  loosePaths,
21
33
  queueOf,
22
34
  stopOf,
@@ -50,20 +62,35 @@ function itemProblem(id, item, report) {
50
62
  return `${id}: its feature ${parent.id} awaits a decision — decide it first`;
51
63
  }
52
64
 
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
65
  // The tune limit is held by `verdict tune` itself: an item tuned up to the limit is still
63
66
  // built once more, and refusing that run would leave it stuck in ready.
64
67
  return null;
65
68
  }
66
69
 
70
+ const THEN = {
71
+ ready: 'run it first',
72
+ blocked: 'unblock it first',
73
+ 'awaiting-decision': 'decide it first',
74
+ };
75
+
76
+ /** What an item waits for, each dependency by what it takes: a card not built has no playtest. */
77
+ function waitWords(id, depends, byId) {
78
+ const each = depends.map((d) => {
79
+ const item = byId.get(d);
80
+ if (!item)
81
+ return (
82
+ `${d}, which has no work item: card it, or take it out of depends ` +
83
+ `(a killed one never plays: take it out, or drop ${id})`
84
+ );
85
+ if (item.type === 'feature') return `${d}, a feature: its children finish first`;
86
+ if (item.running) return `${d}, which is running: it ends first`;
87
+
88
+ return `${d}, which is ${item.status}: ${THEN[item.status] ?? 'it ends first'}`;
89
+ });
90
+
91
+ return `${id} waits for ${each.join('; ')}`;
92
+ }
93
+
67
94
  /**
68
95
  * Why the batch as a whole may not go, or null. `elsewhere` are the items other runs drive now:
69
96
  * a board starts one run per click, so each run sees the others only through their locks.
@@ -100,7 +127,11 @@ function batchProblem(items, wip, elsewhere = []) {
100
127
  return null;
101
128
  }
102
129
 
103
- const verdict = (reason) => ({ pass: !reason, reason: reason ?? '' });
130
+ const verdict = (reason, waits) => ({
131
+ pass: !reason,
132
+ reason: reason ?? '',
133
+ ...(waits && { waits }),
134
+ });
104
135
 
105
136
  const rank = (i) => i.priority ?? Number.MAX_SAFE_INTEGER;
106
137
 
@@ -215,6 +246,10 @@ export function gate(report, ids) {
215
246
  for (const id of ids) {
216
247
  const problem = itemProblem(id, byId.get(id), report);
217
248
  if (problem) return verdict(problem);
249
+ // A dependency inside the same batch lands here too: the dependent waits for it. `waits`: no
250
+ // failure, a queue keeps the item for when it is done.
251
+ const open = report.open_depends.find((o) => o.id === id);
252
+ if (open) return verdict(waitWords(id, open.depends, byId), { id, depends: open.depends });
218
253
  }
219
254
 
220
255
  return verdict(
@@ -461,8 +496,12 @@ function printEach({ items, dirty }) {
461
496
 
462
497
  function runGate(ids, opts) {
463
498
  if (opts.each) {
464
- const dirty = loosePaths(process.cwd());
465
- const result = { ...gateEach(auditReport(), [...new Set(ids)]), ...(dirty && { dirty }) };
499
+ const report = auditReport();
500
+ // A card's work in the folder is no human's: the next claim shelves it (lib/shelf.js).
501
+ const own = report.main_work?.paths;
502
+ const loose = loosePaths(process.cwd(), { files: Boolean(own) });
503
+ const dirty = own ? loose?.filter((p) => !own.includes(p)) : loose;
504
+ const result = { ...gateEach(report, [...new Set(ids)]), ...(dirty && { dirty }) };
466
505
  if (opts.json) console.log(JSON.stringify(result));
467
506
  else printEach(result);
468
507
 
@@ -528,7 +567,13 @@ export function register(program) {
528
567
  .split(',')
529
568
  .map((x) => x.trim())
530
569
  .filter(Boolean);
531
- const plan = nextPlan(auditReport(), Math.max(1, Number(count ?? 1) || 1), skip);
570
+ const runs = runsDir(process.cwd());
571
+ // Held cards wait for the operator; a held project starts nothing by itself (d9).
572
+ skip.push(...heldIds(runs));
573
+ const held = o.plan && existsSync(path.join(runs, PROJECT_HOLD));
574
+ const plan = held
575
+ ? { ids: [], mode: null, units: [], stop: PROJECT_HELD }
576
+ : nextPlan(auditReport(), Math.max(1, Number(count ?? 1) || 1), skip);
532
577
  if (o.plan) return console.log(JSON.stringify({ ...plan, features }));
533
578
  const { ids } = plan;
534
579
  console.log(
@@ -547,9 +592,10 @@ export function register(program) {
547
592
  process.env.GCF_SESSION_AGENT ?? process.env.GCF_RUN_AGENT ?? DEFAULT_AGENT,
548
593
  )
549
594
  .option('--json', 'machine output: {units: [{id, result}]}')
595
+ .option('--wait-limit', "the autopilot's: wait for the limit's reset, keep the quota's reserve")
550
596
  .action(async (units, o) => {
551
597
  try {
552
- const r = await card(process.cwd(), units, { agent: o.agent });
598
+ const r = await card(process.cwd(), units, { agent: o.agent, waitLimit: o.waitLimit });
553
599
  if (o.json) console.log(JSON.stringify(r, null, 2));
554
600
  else for (const u of r.units) console.log(`${u.id}: ${u.result}`);
555
601
  if (r.error) {
@@ -578,9 +624,49 @@ export function register(program) {
578
624
  .command('stop <id>')
579
625
  .description('Stop the session that works an item; the run goes on, the item stays ready')
580
626
  .action((id) => console.log(stopRun(process.cwd(), id)));
627
+ registerHold(harness);
628
+ registerPlanReview(harness);
581
629
  registerChat(harness);
582
630
  }
583
631
 
632
+ /** `gcf-harness plan-review`: the outside reviewer's pass of a plan (Hold-Plan d17). */
633
+ function registerPlanReview(harness) {
634
+ harness
635
+ .command('plan-review <id>')
636
+ .description(
637
+ "An improve pass of the item's plan by an outside reviewer, read-only (plan_review: of " +
638
+ 'gcf/config.yml; Codex CLI): its findings, or skipped or failed with why',
639
+ )
640
+ .option('--json', 'machine output: {findings} | {skipped} | {failed}')
641
+ .action((id, o) => {
642
+ const r = reviewOf(process.cwd(), id);
643
+ if (o.json) return console.log(JSON.stringify(r));
644
+ if (r.findings)
645
+ for (const f of r.findings) console.log(`${f.severity}: ${f.where}: ${f.text}`);
646
+ else console.log(r.skipped ? `skipped: ${r.skipped}` : `failed: ${r.failed}`);
647
+ });
648
+ }
649
+
650
+ /** `gcf-harness hold`: the operator's Hold of an item or of the project (Hold-Plan d6). */
651
+ function registerHold(harness) {
652
+ harness
653
+ .command('hold [id]')
654
+ .description(
655
+ 'Hold an item: its session hands over at its next call and its work waits, ready; the ' +
656
+ "operator's Run of it releases it. --project holds the whole project's automation",
657
+ )
658
+ .option('--project', 'hold the project: no queued or autopilot session goes on')
659
+ .option('--release', 'release the hold of the item, or of the project without an id')
660
+ .action((id, o) => {
661
+ try {
662
+ console.log(holdCommand(process.cwd(), id, o));
663
+ } catch (e) {
664
+ console.error(`gcf-harness hold: ${e.message}`);
665
+ process.exitCode = 1;
666
+ }
667
+ });
668
+ }
669
+
584
670
  /** `gcf-harness run`: the items' agent sessions, each in its checkout. */
585
671
  function registerRun(harness) {
586
672
  harness
@@ -676,7 +762,7 @@ function lockOf(file) {
676
762
  /**
677
763
  * Stop the session that works `id`: the one its own lock names (worktree mode), or the main
678
764
  * checkout's run when that run works this very item (main mode). Only that session goes: the
679
- * run records it as stopped and goes on with the rest. The item stays ready and its work in
765
+ * run records it as stopped and goes on with the rest. The item stays where it is and its work in
680
766
  * progress is kept.
681
767
  */
682
768
  /**
@@ -689,6 +775,68 @@ export function itemLock(runs, id) {
689
775
  return lockOf(path.join(runs, `${id}.lock`)) ?? (main?.item === id ? main : null);
690
776
  }
691
777
 
778
+ /**
779
+ * The review of item `id`'s plan with the project's `plan_review:`; GCF_CODEX (a JSON list: the
780
+ * command and its first arguments) names another Codex, a test's fake.
781
+ */
782
+ function reviewOf(projectDir, id) {
783
+ const board = json(cliCore(projectDir)(['board', '--json']), 'board');
784
+ const item = board.items?.find((i) => i.id === id);
785
+ if (!item) return { failed: `${id} is not a work item of the board` };
786
+ const codex = process.env.GCF_CODEX ? JSON.parse(process.env.GCF_CODEX) : undefined;
787
+ const plan = item.plan_file ?? `.ai-factory/plans/${id}.md`;
788
+
789
+ return planReview(projectDir, { id, plan, config: board.plan_review ?? {}, codex });
790
+ }
791
+
792
+ /** The autopilot's stop while the project is held (Hold-Plan d9). */
793
+ const PROJECT_HELD = { kind: 'hold', text: 'the project is held: Release lets it go on' };
794
+
795
+ /** The folder of a project's run files: locks, marks, records. */
796
+ const runsDir = (projectDir) => path.join(path.resolve(projectDir), '.gcf-session', 'runs');
797
+
798
+ /** The items the operator holds now (`<id>.hold`). */
799
+ export function heldIds(runs) {
800
+ try {
801
+ return readdirSync(runs)
802
+ .filter((f) => f.endsWith('.hold') && f !== PROJECT_HOLD)
803
+ .map((f) => f.slice(0, -'.hold'.length));
804
+ } catch {
805
+ return [];
806
+ }
807
+ }
808
+
809
+ /** The refusal of `hold`'s arguments, if any. */
810
+ function holdArgs(id, project, release) {
811
+ if (id && !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(id))
812
+ throw new Error(`${id} is not an item id (a lowercase hyphen slug)`);
813
+ if (!id && !project && !release) throw new Error('name an item, or --project');
814
+ if (id && project) throw new Error('an item or --project, not both');
815
+ }
816
+
817
+ /**
818
+ * `gcf-harness hold`: the mark a run reads at its agent's next call, before each session and
819
+ * during a wait (Hold-Plan d6). It is a file, so it outlives the board and the run.
820
+ */
821
+ export function holdCommand(projectDir, id, { project = false, release = false } = {}) {
822
+ holdArgs(id, project, release);
823
+ const runs = runsDir(projectDir);
824
+ const mark = id ? holdMarkOf(runs, id) : path.join(runs, PROJECT_HOLD);
825
+ const what = id ?? 'the project';
826
+ if (release) {
827
+ rmSync(mark, { force: true });
828
+
829
+ return `released ${what}`;
830
+ }
831
+
832
+ mkdirSync(runs, { recursive: true });
833
+ writeFileSync(mark, `${new Date().toISOString()}\n`);
834
+
835
+ return id
836
+ ? `held ${id}: its session hands over at its next call; Run goes on from where it stopped`
837
+ : 'held the project: its sessions hand over, nothing queued or autopiloted starts';
838
+ }
839
+
692
840
  export function stopRun(projectDir, id, core = cliCore(projectDir)) {
693
841
  const runs = path.join(path.resolve(projectDir), '.gcf-session', 'runs');
694
842
  const lockFor = () => itemLock(runs, id);
@@ -702,7 +850,7 @@ export function stopRun(projectDir, id, core = cliCore(projectDir)) {
702
850
  if (session && alive(session)) killTree(session);
703
851
  core(['release', id]);
704
852
 
705
- return lock ? `stopped the run of ${id}; it stays ready` : `no run drives ${id}`;
853
+ return lock ? `stopped the run of ${id}; it stays where it is` : `no run drives ${id}`;
706
854
  }
707
855
 
708
856
  /**
@@ -710,7 +858,18 @@ export function stopRun(projectDir, id, core = cliCore(projectDir)) {
710
858
  * lessons its sessions left in the inbox.
711
859
  */
712
860
  export const itemLine = (i) =>
713
- [`${i.id}: ${i.result}`, i.reason ?? i.conflict ?? i.error ?? i.skipped, i.process]
861
+ [
862
+ `${i.id}: ${i.result}`,
863
+ i.reason ?? i.conflict ?? i.error ?? i.skipped,
864
+ i.process,
865
+ i.shelved && `${i.shelved.id}'s work went to ${i.shelved.branch}`,
866
+ i.returned && `its work came back with ${i.conflicts?.length ?? 0} conflict(s)`,
867
+ i.build &&
868
+ !i.build.ok &&
869
+ !i.build.moved_on &&
870
+ `no build to play: ${i.build.problem.split('\n')[0]}`,
871
+ i.build?.dirtied?.length && `its build changed ${i.build.dirtied.join(', ')}`,
872
+ ]
714
873
  .filter(Boolean)
715
874
  .join(' — ') + (i.lessons ? `, ${i.lessons} lesson${i.lessons > 1 ? 's' : ''}` : '');
716
875
 
@@ -89,22 +89,16 @@ const SKEW_MS = 2000;
89
89
  */
90
90
  export function milestones({ verifyLog, item, head = () => null, worktree = false } = {}) {
91
91
  const calls = new Map();
92
- const w = { checks: 0, planned: false };
93
- // A call the watch knows waits for its result; the first aif-implement is the plan's step.
92
+ const w = { checks: 0 };
93
+ // A call the watch knows waits for its result. The plan's step is the run's, at the end of its
94
+ // planning phase (Hold-Plan d18): aif-implement says nothing of how the plan converged.
94
95
  const called = (e) => {
95
96
  const step = stepOf(e);
96
97
  if (step?.step === 'move' && worktree) return [];
97
- if (step?.step !== 'plan') {
98
- if (step)
99
- calls.set(e.id, { ...step, at: Date.now(), head: step.step === 'commit' ? head() : null });
98
+ if (step && step.step !== 'plan')
99
+ calls.set(e.id, { ...step, at: Date.now(), head: step.step === 'commit' ? head() : null });
100
100
 
101
- return [];
102
- }
103
-
104
- const first = !w.planned;
105
- w.planned = true;
106
-
107
- return first ? [{ type: 'step', step: 'plan', passes: w.checks }] : [];
101
+ return [];
108
102
  };
109
103
 
110
104
  /** A step's `ok`: the DoD's row, a commit's new HEAD, else the tool's own result. */
@@ -134,10 +128,18 @@ export function milestones({ verifyLog, item, head = () => null, worktree = fals
134
128
  };
135
129
 
136
130
  return {
137
- // A session after an earlier run's handoff goes on from a plan that converged before it.
138
- skipPlan: () => {
139
- w.planned = true;
140
- },
131
+ // Kept for its callers: the plan's step comes from the phase's end now, not from a call.
132
+ skipPlan: () => {},
133
+ /**
134
+ * The end of the planning phase as a step (Hold-Plan d18): converged in K passes, or
135
+ * stalled, with each pass's blocking count.
136
+ */
137
+ phaseEnd: ({ passes, stalled = false }) => ({
138
+ type: 'step',
139
+ step: 'plan',
140
+ passes: passes.length,
141
+ ...(stalled ? { stalled: passes } : {}),
142
+ }),
141
143
  see(e) {
142
144
  // A subagent's calls (a reviewer running the tests) are its own, not the item's steps.
143
145
  if (!e || e.sub) return [];
@@ -0,0 +1,89 @@
1
+ // `gcf-harness plan-review <id>` (Hold-Plan d17): one improve pass of an item's plan by an outside
2
+ // reviewer, read-only. The Codex CLI runs in its read-only sandbox: the audit holds by the sandbox,
3
+ // not by trust. Its answer is findings as JSON; without Codex, or when it fails, the run's own
4
+ // agent makes the pass (SKILL.md, steps 8-11).
5
+ import { spawnSync } from 'node:child_process';
6
+ import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
7
+ import os from 'node:os';
8
+ import path from 'node:path';
9
+ import { fileURLToPath } from 'node:url';
10
+
11
+ const HERE = path.dirname(fileURLToPath(import.meta.url));
12
+ export const FINDINGS_SCHEMA = path.join(HERE, 'plan-review.schema.json');
13
+ export const REVIEW_TIMEOUT_MS = 25 * 60_000;
14
+ export const REVIEW_DEFAULTS = { agent: 'codex', model: 'gpt-6-astra', effort: 'medium', at: 3 };
15
+
16
+ /** The review's prompt: what to read and how to answer; the reviewer reads the files itself. */
17
+ export function reviewPrompt(id, plan) {
18
+ return [
19
+ `Audit the implementation plan of work item ${id}: ${plan}.`,
20
+ `Read the item gcf/work/${id}.md, the plan, and the code the plan names. Change nothing.`,
21
+ 'A finding is blocking when the plan, built as written, would be wrong, miss what the item',
22
+ 'asks, or break what the code already does; polish when it only reads better. Check each',
23
+ 'claim of the plan against the code. Answer with the findings only, as the schema says.',
24
+ ].join('\n');
25
+ }
26
+
27
+ /**
28
+ * Run the review: `{findings}`, `{skipped: why}` (no reviewer, none set) or `{failed: why}`.
29
+ * `codex` is the command to run (its executable and first arguments): a test's fake.
30
+ * @param {string} projectDir
31
+ * @param {{id: string, plan: string, config?: any, codex?: string[], timeoutMs?: number}} o
32
+ */
33
+ export function planReview(projectDir, o) {
34
+ const cfg = { ...REVIEW_DEFAULTS, ...(o.config ?? {}) };
35
+ const [exe, ...pre] = o.codex ?? ['codex'];
36
+ const shell = process.platform === 'win32' && !o.codex;
37
+ const skipped = reviewerMissing(cfg, exe, pre, shell);
38
+ if (skipped) return { skipped };
39
+ const dir = mkdtempSync(path.join(os.tmpdir(), 'gcf-review-'));
40
+ const out = path.join(dir, 'findings.json');
41
+ try {
42
+ const args = [
43
+ ...['exec', '-', '-s', 'read-only', '-m', cfg.model],
44
+ ...['-c', `model_reasoning_effort=${cfg.effort}`, '--ephemeral'],
45
+ ...['--output-schema', FINDINGS_SCHEMA, '-o', out],
46
+ ];
47
+ const res = spawnSync(exe, [...pre, ...args], {
48
+ cwd: projectDir,
49
+ input: reviewPrompt(o.id, o.plan),
50
+ encoding: 'utf8',
51
+ timeout: o.timeoutMs ?? REVIEW_TIMEOUT_MS,
52
+ shell,
53
+ });
54
+ if (res.error?.code === 'ETIMEDOUT') return { failed: 'the review timed out' };
55
+ // A flag the CLI no longer takes is named as it said it (Hold-Plan risk 11).
56
+ if (res.status !== 0)
57
+ return { failed: `codex exit ${res.status}: ${firstLine(res.stderr || res.stdout)}` };
58
+
59
+ return findingsOf(out);
60
+ } finally {
61
+ rmSync(dir, { recursive: true, force: true });
62
+ }
63
+ }
64
+
65
+ /** Why no review runs: no reviewer set, another than Codex, or no Codex to run; else null. */
66
+ function reviewerMissing(cfg, exe, pre, shell) {
67
+ if (cfg.agent === 'none') return 'plan_review.agent is none';
68
+ if (cfg.agent !== 'codex') return `no reviewer named ${cfg.agent}: only codex runs`;
69
+ const version = spawnSync(exe, [...pre, '--version'], { encoding: 'utf8', shell });
70
+
71
+ return version.error || version.status !== 0 ? 'no codex in PATH' : null;
72
+ }
73
+
74
+ const firstLine = (text) =>
75
+ String(text ?? '')
76
+ .trim()
77
+ .split(/\r?\n/)[0] || 'no output';
78
+
79
+ /** The findings the reviewer wrote, or why they cannot be read. */
80
+ function findingsOf(file) {
81
+ try {
82
+ const x = JSON.parse(readFileSync(file, 'utf8'));
83
+ if (!Array.isArray(x?.findings)) return { failed: 'the answer has no findings list' };
84
+
85
+ return { findings: x.findings };
86
+ } catch (e) {
87
+ return { failed: `the answer is not JSON: ${e.message}` };
88
+ }
89
+ }
@@ -0,0 +1,20 @@
1
+ {
2
+ "type": "object",
3
+ "additionalProperties": false,
4
+ "required": ["findings"],
5
+ "properties": {
6
+ "findings": {
7
+ "type": "array",
8
+ "items": {
9
+ "type": "object",
10
+ "additionalProperties": false,
11
+ "required": ["severity", "where", "text"],
12
+ "properties": {
13
+ "severity": { "enum": ["blocking", "polish"] },
14
+ "where": { "type": "string" },
15
+ "text": { "type": "string" }
16
+ }
17
+ }
18
+ }
19
+ }
20
+ }