feat(ship): batched specialists per shard, audit skip at zero code paths, gate-scan summary for the parent (GSTA-167)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
garrytanandcapy-ai[bot] committed 2026-10-29 21:39:03 +00:00
1 parent 1a558ded87
commit bde74d6f33
17 files changed
+334 -101

No files matched your search

+31 -18
View File
@@ -4,13 +4,13 @@
* their results (docs/review-policy.md#reviewer-packets).
*
* gstack-review-packet build --base <ref> --out-dir <dir> [--range <sha>] [--plan-file <path>] [--only a,b]
* [--findings <merged.jsonl>] [--fix-list <f> --tests <f> [--callers <f>]] [plan flags]
* [--findings <merged.jsonl>] [--fix-list <f> --tests <f> [--callers <f>]] [--fanout batched|parallel] [plan flags]
* gstack-review-packet build --audit test-coverage|plan-completion --base <ref> --out-dir <dir> [--plan-file <path>]
* [--context <file>] [--generation allowed|audit-only] [--passes-used <n>]
* [--context <file>] [--passes-used <n>]
* gstack-review-packet collect --dir <dir>
*
* build runs the plan gstack-review-plan prints (lib/review-plan-live.ts, same flags) and writes
* one packet per DISPATCH line; collect reads every packet's output file. Logic: lib/review-packet.ts,
* one packet per DISPATCH line, a pass's specialist lines packed into one batched packet; collect reads every packet's output file. Logic: lib/review-packet.ts,
* lib/review-packet-collect.ts.
*/
import * as fs from 'node:fs';
@@ -20,29 +20,33 @@ import { EXIT, exitTableHelp } from '../lib/headless-artifacts';
import { runScriptSync } from '../lib/script-invocation';
import { reviewPlanLine } from '../lib/review-depth';
import { flagReader, livePlan, parsePlanFlags, planPass, PLAN_FLAGS_HELP } from '../lib/review-plan-live';
import { AUDITS, auditDraft, draftFor, packetLine, PACKET_CAP_BYTES, readManifest, writeManifest, writePackets, type AuditName, type BuildContext, type PacketEntry } from '../lib/review-packet';
import { AUDITS, auditCodePaths, auditDraft, draftFor, packetLine, packSpecialists, PACKET_CAP_BYTES, PACKINGS, readManifest, SPECIALIST_PACKING, writeManifest, writePackets, type AuditName, type BuildContext, type PacketEntry, type Packing } from '../lib/review-packet';
import { collect } from '../lib/review-packet-collect';
const BIN = 'gstack-review-packet';
const HELP = `${BIN} — one packet file per /ship reviewer; collect reads their results (docs/review-policy.md#reviewer-packets)
build --base <ref> --out-dir <dir> write one packet per DISPATCH line of the plan gstack-review-plan prints
--fanout batched|parallel batched (default ${SPECIALIST_PACKING}): a pass's specialist lines are one packet
per shard inlining every checklist; parallel: one packet per specialist
--range <sha> the diff base from pass 2 on (RANGE_BASE; fix-check: PASS_HEAD); default the merge base
--plan-file <path> add at most 8 KB of the plan to each packet (the plan-completion audit gets it whole)
--only a,b only these reviewers (names or roles: adversarial, outside-voice, red-team, ...)
--findings <merged.jsonl> collect's merged findings: builds the red-team packet (deferred without it)
--fix-list <f> --tests <f> [--callers <f>] the fix-check packet's inputs (its hunks are the --range diff)
--audit test-coverage|plan-completion the Step 7/8 audit packet instead of the plan's reviewers
--context <file> --generation allowed|audit-only --passes-used <n> the audit's parent-supplied inputs
--audit test-coverage|plan-completion the Step 7/8 audit packet instead of the plan's reviewers; a diff with
no code path prints AUDIT_SKIPPED: test-coverage and builds nothing
--context <file> --passes-used <n> the audit's parent-supplied inputs (the coverage packet is audit-only)
plan flags (same as gstack-review-plan):
${PLAN_FLAGS_HELP}
collect --dir <dir> read every packet's output: one REVIEWER: line each, every CRITICAL on one
line, INFORMATIONAL counts; writes merged.jsonl and informational.md in <dir>
build prints PACKET: <role> <name> effort=<e> bytes=<n> tokens~=<n/4> file=<path> out=<path> per packet
(a reviewer past ${PACKET_CAP_BYTES} bytes is sharded by path as <name>.1ofK, never truncated) and
PACKETS: n=<k> total_bytes=<n> fingerprint=<plan fingerprint>. collect exits 3 with
REVIEW_COVERAGE_INCOMPLETE when any packet's output is missing or unusable.
(a reviewer past ${PACKET_CAP_BYTES} bytes is sharded by path as <name>.1ofK, never truncated),
PACKED: specialist batched checklists=<a,b> shards=<k> per batched reviewer, and PACKETS: n=<k> total_bytes=<n> fingerprint=<plan fingerprint>. collect exits 3 with
REVIEW_COVERAGE_INCOMPLETE when any packet's output is missing or unusable, or a batched packet's
COVERED: line leaves out a checklist it inlined.
${exitTableHelp()}`;
const args = process.argv.slice(2);
@@ -65,6 +69,8 @@ function build(): number {
if (has('--audit') && !AUDITS.includes(audit as AuditName)) return fail(`--audit must be ${AUDITS.join(' or ')}`);
const flags = parsePlanFlags(args, BIN);
if ('usage' in flags) return fail(flags.usage.replace(`${BIN}: `, ''));
const fanout = (flag('--fanout') ?? SPECIALIST_PACKING) as Packing;
if (!PACKINGS.includes(fanout)) return fail(`--fanout must be ${PACKINGS.join(' or ')}`);
const planText = readFlag('--plan-file');
if (planText === null) return fail(`--plan-file ${flag('--plan-file')} is not readable`);
const binDir = path.dirname(Bun.fileURLToPath(import.meta.url));
@@ -84,18 +90,23 @@ function build(): number {
const context = readFlag('--context');
if (context === null) return fail(`--context ${flag('--context')} is not readable`);
if (audit === 'plan-completion' && planText === undefined) return fail('--audit plan-completion needs --plan-file <the bound plan>');
let draft = auditDraft(audit, { ...ctx, ...(context ? { context } : {}) }, flags.base, live.auditEffort);
const gen = flag('--generation'), used = flag('--passes-used');
if (gen || used) draft = { ...draft, head: draft.head.map(s => s.replace('<allowed|audit-only>', gen ?? '<allowed|audit-only>').replace('passes used: <N>', `passes used: ${used ?? '<N>'}`)) };
entries = writePackets(draft, ctx);
const codePaths = audit === 'test-coverage' ? auditCodePaths(collected.paths, root) : null;
if (codePaths?.length === 0) {
const shown = collected.paths.slice(0, 5).join(',') + (collected.paths.length > 5 ? `,+${collected.paths.length - 5} more` : '');
out.push(`AUDIT_SKIPPED: test-coverage code_paths=0 (docs, data and tests only: ${shown || 'empty diff'}); no audit dispatched, the coverage gate records zero paths`);
} else {
let draft = auditDraft(audit, { ...ctx, ...(context ? { context } : {}) }, flags.base, live.auditEffort);
const used = flag('--passes-used');
if (used) draft = { ...draft, head: draft.head.map(s => s.replace('passes used: <N>', `passes used: ${used}`)) };
entries = writePackets(draft, ctx);
}
} else {
const only = list('--only');
const wanted = (role: string, key: string) => !only.length || only.includes(key) || only.includes(role);
const findingsText = readFlag('--findings');
if (findingsText === null) return fail(`--findings ${flag('--findings')} is not readable`);
for (const d of plan.dispatches) {
const key = d.name.split(' ')[0]!;
if (!wanted(d.role, key)) continue;
const selected = plan.dispatches.filter(d => wanted(d.role, d.name.split(' ')[0]!));
for (const d of fanout === 'batched' ? packSpecialists(selected) : selected) {
if (d.role === 'red-team' && findingsText === undefined) {
out.push(`PACKET_DEFERRED: red-team (after collect: build --only red-team --findings ${path.join(outDir, 'merged.jsonl')} with these flags)`);
entries.push({ role: 'red-team', name: 'red-team', reviewer: 'red-team', effort: d.effort, file: '', out: '', bytes: 0, checklists: ['red-team'], fixtures: 'summary', shard: null, deferred: true });
@@ -104,7 +115,7 @@ function build(): number {
let dctx = ctx;
if (d.role === 'red-team') {
const findings = findingsText!.split('\n').filter(Boolean).flatMap(l => { try { const f = JSON.parse(l); return [`[${f.severity}] ${f.path}${f.line ? `:${f.line}` : ''} (${(f.sources ?? [f.specialist]).join(' + ')}) ${String(f.summary).replace(/\s+/g, ' ')}`.slice(0, 300)]; } catch { return []; } });
const specialists = new Set((readManifest(absOut)?.packets ?? []).filter(p => p.role === 'specialist').map(p => p.reviewer)).size;
const specialists = new Set((readManifest(absOut)?.packets ?? []).filter(p => p.role === 'specialist').flatMap(p => p.checklists.filter(c => c !== 'red-team'))).size;
dctx = { ...ctx, findings, specialists };
}
if (d.role === 'fix-check') {
@@ -112,7 +123,9 @@ function build(): number {
if (!fixList || !tests || callers === null) return fail('the plan dispatches fix-check: pass readable --fix-list and --tests files (--callers optional)');
dctx = { ...ctx, fixCheck: { fixList, tests, callers: callers ?? '' } };
}
entries.push(...writePackets(draftFor(d, dctx), dctx));
const written = writePackets(draftFor(d, dctx), dctx);
if (d.checklists) out.push(`PACKED: specialist batched checklists=${d.checklists.join(',')} shards=${written.length}`);
entries.push(...written);
}
out.unshift(reviewPlanLine(plan, planPass(plan, flags.pass)));
}