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 +12 -0
- package/commands/harness.js +177 -18
- package/commands/milestones.js +18 -16
- package/commands/plan-review.js +89 -0
- package/commands/plan-review.schema.json +20 -0
- package/commands/run.js +581 -42
- package/extension.json +1 -1
- package/hooks/handoff-guard.js +16 -5
- package/hooks/implement-guard.js +55 -6
- package/node_modules/gcf-session/lib/chat.js +39 -5
- package/node_modules/gcf-session/lib/index.js +15 -0
- package/node_modules/gcf-session/lib/job.js +133 -34
- package/node_modules/gcf-session/lib/session.js +64 -10
- package/node_modules/gcf-session/lib/usage.js +288 -0
- package/node_modules/gcf-session/package.json +1 -1
- package/node_modules/gcf-session/types/index.d.ts +60 -2
- package/package.json +2 -2
- package/skills/gcf-run/SKILL.md +19 -7
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.
|
package/commands/harness.js
CHANGED
|
@@ -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 {
|
|
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) => ({
|
|
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
|
|
465
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
[
|
|
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
|
|
package/commands/milestones.js
CHANGED
|
@@ -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
|
|
93
|
-
// A call the watch knows waits for its result
|
|
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
|
|
98
|
-
|
|
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
|
-
|
|
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
|
-
//
|
|
138
|
-
skipPlan: () => {
|
|
139
|
-
|
|
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
|
+
}
|