gstack/bin/gstack-review-dispatch

#!/usr/bin/env -S bun --no-env-file --config=/dev/null
/**
 * gstack-review-dispatch — /ship's reviewers get their briefs byte for byte and the parent changes
 * nothing they return (GSTA-167 no-loss gate; docs/review-policy.md#verbatim-dispatch).
 *
 *   gstack-review-dispatch render --role <role> [--name <n>] --out <dir> [slots]   write the brief, print its sha256
 *   gstack-review-dispatch sent --ledger <f> --role <role> [--name <n>] --sent <file>  the prompt actually passed; mismatch fails
 *   gstack-review-dispatch collect --ledger <f> --role <role> [--name <n>] --output <file> --merged <file>
 *   gstack-review-dispatch judge --ledger <f> --merged <file> --judged <file>        no drop, no downgrade
 *   gstack-review-dispatch verify --ledger <f> [--targeted-out <file>]               replay every hash and the judgment
 *   gstack-review-dispatch pass --base <b> --out <dir> --pass <id> [-- plan flags]  the pass's staged manifest
 *   gstack-review-dispatch show|stage|chunk|mark --manifest <f> ...                  one manifest step
 *   gstack-review-dispatch program [--ledger <f>]                                    the checked-in Capy pass program
 *
 * Logic: lib/review-brief.ts (rendering from the sections), lib/review-ledger.ts (ledger, collect, judge, verify),
 * lib/review-pass.ts (the staged manifest) and lib/capy-review-pass.js (the Capy program that runs it).
 */
import { spawnSync } from 'node:child_process';
import * as fs from 'node:fs';
import * as path from 'node:path';
import { EXIT, exitTableHelp } from '../lib/headless-artifacts';
import { BRIEF_ROLES, BriefError, briefFile, promptHash, renderBrief, sectionTexts, type BriefRole, type Slots } from '../lib/review-brief';
import { collect, readJsonl, readLedger, readerKey, recordJudgment, recordSent, appendEvent, verify, type JudgedLine, type MergedLine, type VerifyRow } from '../lib/review-ledger';
import { buildManifest, chunkCount, chunkOf, manifestPath, markReader, readManifest, renderStage, writeManifest, STAGES, type Extra, type Manifest, type PassReader, type ReaderState, type Stage } from '../lib/review-pass';
import type { Dispatch } from '../lib/review-depth';
import { runScriptSync } from '../lib/script-invocation';
import { TARGETED_RULES, parseClassList, targetedBriefSha, targetedPatchId } from '../lib/review-targeted';
import { resolveBaseBranch } from '../lib/ship-policy';

const HELP = `gstack-review-dispatch — verbatim reviewer briefs and loss-free collection for /ship

  render --role <role> [--name <n>] --out <dir> [--ledger <f>] [slots]
      roles: ${BRIEF_ROLES.join(', ')}
      slots: --diff-base <sha> (every role but fix-check)  --exclude '<DIFF_CMD tail>'  --stack <s>  --test-fw <s>
             --learnings-file <f>  --checklist <path> (default <root>/review/specialists/<name>.md; red-team.md for red-team)
             --checklists <a,b> (specialist-batched: the plan's checklists= names, or paths)  --findings-file <f> --specialists <n> (red-team)
             --fix-list <f> --hunks <f> --tests <f> [--callers <f>] (fix-check)
             --classes <money,gate,auth,secret> (targeted: the plan's TARGETED classes; the brief is review/specialists/targeted.md;
             --diff-base must be the merge base with --base, default origin/HEAD's branch, on every pass)
      writes <out>/<role>[-<name>].prompt.md, records it in the ledger (default <out>/review-ledger.jsonl) and prints
      BRIEF: reader=<role/name> sha256=<h> bytes=<n> file=<path>. Pass that file's content as the reader's prompt, unchanged.
  sent --ledger <f> --role <role> [--name <n>] --sent <file>
      the exact prompt a dispatch passed: BRIEF_SENT: … match, or BRIEF_MISMATCH: … (exit 1; the pass is not reviewed)
  collect --ledger <f> --role <role> [--name <n>] --output <file> --merged <merged.jsonl>
      the reader's raw output: hashes it and appends each finding to merged.jsonl with its label as written
  judge --ledger <f> --merged <merged.jsonl> --judged <judged.jsonl>
      judged lines {"id","severity","reason"?,"duplicate_of"?}: every merged id kept at its severity or above (a
      duplicate folds into one at least as severe); added and promoted findings need a reason. JUDGMENT: ok …, or
      JUDGMENT_REJECTED: dropped=… downgraded=… (exit 1)
  verify --ledger <f> [--targeted-out <file>]
      BRIEF, OUTPUT and JUDGE rows from the ledger alone, then VERIFY: clean (exit 0), VERIFY: dirty (exit 1) or
      VERIFY: no brief records (exit 3: this run's ledger kept no prompts). A ledger with a targeted brief also prints
      TARGETED_RECORD: and --targeted-out writes it as the JSON gstack-ship-receipt write --review-targeted reads
  pass --base <ref> --out <dir> --pass <id> [--ledger <f>] [--diff-base <sha>] [--learnings-file <f>] [--extras <json>]
       [--checklist-root <dir>] [-- <gstack-review-plan flags>]
      runs gstack-review-plan and writes <out>/pass-manifest.json: stage first (audit readers marked first in --extras),
      specialists (with the other --extras readers), red-team, voices (Step 11). Renders first and specialists now; prints
      the plan, MANIFEST: and one READER: line per reader. A plan whose NEXT is not full or scoped prints PASS: none.
      An existing manifest for the same --pass is reused (resumed). --extras: [{"name","prompt_file","first"?,"model"?}]
  show --manifest <f>                         MANIFEST_JSON: <the manifest on one line>
  stage --manifest <f> --stage <first|specialists|red-team|voices>
      renders a stage; the Red Team only after every earlier reader is collected, its findings file being the
      specialists' merged.jsonl lines byte for byte
  chunk --manifest <f> --reader <r> --index <i>
      BRIEF_CHUNK: reader=… index=i of=n sha256=…, then one JSON string line of at most 65,536 brief characters
  mark --manifest <f> --reader <r> --state <intent|created|queued|collected|failed> [--path <p>] [--output <f>] [--error <e>]
  mark --manifest <f> --before <tokens>,<credits>
  mark --manifest <f> --log-start <key> --token <t>   records a review-log start token once, so a rerun starts only what is missing
      reader states move forward only; intent is recorded before the subagent is created, its path right after
  program [--ledger <f>]
      PROGRAM: v<n> sha256=… bytes=…, then lib/capy-review-pass.js as one JSON string line (see the gstack Capy skill)
${exitTableHelp()}`;

const args = process.argv.slice(2);
const flag = (n: string) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : undefined; };
const readFile = (f: string | undefined, what: string) => {
  if (!f) return undefined;
  try { return fs.readFileSync(f, 'utf8'); } catch { throw new BriefError(`cannot read ${what} file ${f}`); }
};
const ROOT = path.resolve(import.meta.dir, '..');

function render(): number {
  const role = flag('--role') as BriefRole | undefined;
  const out = flag('--out');
  if (!role || !BRIEF_ROLES.includes(role) || !out) { process.stderr.write(`gstack-review-dispatch render: needs --role <${BRIEF_ROLES.join('|')}> and --out <dir>\n`); return EXIT.usage; }
  const name = flag('--name');
  const diffBase = flag('--diff-base');
  const checklist = flag('--checklist') ?? (role === 'red-team' ? path.join(ROOT, 'review/specialists/red-team.md') : role === 'targeted' ? path.join(ROOT, 'review/specialists/targeted.md') : role === 'specialist' && name ? path.join(ROOT, 'review/specialists', `${name}.md`) : undefined);
  if (checklist && (role === 'specialist' || role === 'red-team' || role === 'targeted') && !fs.existsSync(checklist)) throw new BriefError(`checklist not found: ${checklist}`);
  const brief = role === 'targeted' ? readFile(checklist, 'targeted brief') : undefined;
  if (role === 'targeted') {
    const base = resolveBaseBranch(process.cwd(), flag('--base'));
    const mb = [`origin/${base}`, base].map(ref => spawnSync('git', ['merge-base', ref, 'HEAD'], { encoding: 'utf8', timeout: 30_000 })).find(r => r.status === 0)?.stdout.trim();
    const full = diffBase ? spawnSync('git', ['rev-parse', '--verify', '--quiet', `${diffBase}^{commit}`], { encoding: 'utf8', timeout: 30_000 }).stdout?.trim() : undefined;
    if (!full || full !== mb) throw new BriefError(`the targeted reader reads the whole diff on every pass: --diff-base must be the merge base with ${base} (${mb ?? 'unresolved'}), got ${diffBase ?? 'none'}`);
  }
  const checklists = flag('--checklists')?.split(',').map(s => s.trim()).filter(Boolean).map(c => (c.includes('/') ? c : path.join(ROOT, 'review/specialists', `${c}.md`)));
  for (const c of checklists ?? []) if (!fs.existsSync(c)) throw new BriefError(`checklist not found: ${c}`);
  let diff: string | undefined;
  if (role === 'outside-voice' && diffBase) {
    const r = spawnSync('git', ['-c', 'core.quotePath=false', 'diff', '--no-color', '--no-ext-diff', diffBase], { encoding: 'utf8', timeout: 60_000, maxBuffer: 256 * 1024 * 1024 });
    if (r.status !== 0) throw new BriefError(`git diff ${diffBase} failed: ${(r.stderr ?? '').trim().split('\n')[0]}`);
    diff = r.stdout;
  }
  const slots: Slots = {
    name, diff_base: diffBase, exclude: flag('--exclude'), stack: flag('--stack'), test_fw: flag('--test-fw'),
    learnings: readFile(flag('--learnings-file'), 'learnings'), checklist, checklists: checklists?.join(','),
    findings: readFile(flag('--findings-file'), 'findings'), specialists: flag('--specialists'), diff,
    classes: flag('--classes'), brief,
    fix_list: readFile(flag('--fix-list'), 'fix list'), hunks: readFile(flag('--hunks'), 'hunks'), tests: readFile(flag('--tests'), 'tests'), callers: readFile(flag('--callers'), 'callers'),
  };
  const text = renderBrief(role, slots, sectionTexts(ROOT));
  fs.mkdirSync(out, { recursive: true, mode: 0o700 });
  const file = path.join(path.resolve(out), briefFile(role, name));
  fs.writeFileSync(file, text, { mode: 0o600 });
  const ledger = flag('--ledger') ?? path.join(out, 'review-ledger.jsonl');
  const sha = promptHash(text);
  const targeted = brief === undefined ? {} : { classes: parseClassList(flag('--classes')!), rules: TARGETED_RULES, brief_sha: targetedBriefSha(checklist), diff_base: diffBase ?? null, patch_id: diffBase ? targetedPatchId(process.cwd(), diffBase) : 'none' };
  appendEvent(ledger, { event: 'rendered', reader: readerKey(role, name), role, name: name ?? null, file, sha256: sha, bytes: Buffer.byteLength(text), ...targeted });
  process.stdout.write(`BRIEF: reader=${readerKey(role, name)} sha256=${sha} bytes=${Buffer.byteLength(text)} file=${file}\n`);
  return EXIT.ok;
}

const PROGRAM_FILE = path.join(ROOT, 'lib', 'capy-review-pass.js');
const PROGRAM_VERSION = 1;
const git = (a: string[]) => { const r = spawnSync('git', a, { encoding: 'utf8', timeout: 60_000, maxBuffer: 256 * 1024 * 1024 }); return r.status === 0 ? r.stdout : null; };
const readerLine = (m: Manifest, r: PassReader) => `READER: ${r.reader} stage=${r.stage} state=${r.state} title="${r.title}"${r.sha256 ? ` sha256=${r.sha256} bytes=${r.bytes} chunks=${r.chunks}` : ''}${r.path ? ` path=${r.path}` : ''}`;
const branchDiff = (base: string) => {
  const d = git(['-c', 'core.quotePath=false', 'diff', '--no-color', '--no-ext-diff', base]);
  if (d === null) throw new BriefError(`git diff ${base} failed`);
  return d;
};

function pass(): number {
  const base = flag('--base'), out = flag('--out'), id = flag('--pass');
  if (!base || !out || !id || !/^[a-z0-9-]+$/.test(id)) { process.stderr.write('gstack-review-dispatch pass: needs --base <ref>, --out <dir> and --pass <id> (lowercase letters, digits, dashes)\n'); return EXIT.usage; }
  const file = manifestPath(out);
  if (fs.existsSync(file)) {
    const m = readManifest(file);
    if (m.pass !== id) throw new BriefError(`${file} belongs to pass ${m.pass}, not ${id}`);
    process.stdout.write([...m.plan_lines, `MANIFEST: file=${file} pass=${m.pass} readers=${m.readers.length} resumed`, ...m.readers.map(r => readerLine(m, r))].join('\n') + '\n');
    return EXIT.ok;
  }
  const planArgs = args.includes('--') ? args.slice(args.indexOf('--') + 1) : [];
  const plan = (json: boolean) => runScriptSync(path.join(ROOT, 'bin', 'gstack-review-plan'), ['--base', base, ...planArgs, ...(json ? ['--json'] : [])], { encoding: 'utf8', timeout: 180_000, maxBuffer: 64 * 1024 * 1024 });
  const text = plan(false);
  if (text.status !== 0) { process.stdout.write(text.stdout ?? ''); process.stderr.write(text.stderr ?? ''); return EXIT.fail; }
  const j = plan(true);
  if (j.status !== 0) { process.stderr.write(j.stderr ?? ''); return EXIT.fail; }
  const p = JSON.parse(j.stdout) as { next: { step: string }; dispatches: Dispatch[]; targeted?: { classes: string[] } };
  const planLines = text.stdout.trimEnd().split('\n');
  const step = p.next.step;
  if (step !== 'full' && step !== 'scoped') { process.stdout.write([...planLines, `PASS: none next=${step} (no reviewer pass; follow NEXT)`].join('\n') + '\n'); return EXIT.ok; }
  const diffBase = flag('--diff-base') ?? git(['merge-base', base, 'HEAD'])?.trim();
  if (!diffBase) throw new BriefError(`no merge base between ${base} and HEAD`);
  const root = git(['rev-parse', '--show-toplevel'])?.trim() ?? process.cwd();
  const extrasFile = flag('--extras');
  const extras = extrasFile ? JSON.parse(readFile(extrasFile, 'extras')!) as Extra[] : [];
  const m = buildManifest({ pass: id, out, ledger: flag('--ledger') ?? path.join(out, 'review-ledger.jsonl'), base, diffBase, root, checklistRoot: flag('--checklist-root') ?? ROOT,
    dispatches: p.dispatches, next: step, planLines, learnings: readFile(flag('--learnings-file'), 'learnings') ?? null, extras,
    targetedClasses: p.targeted?.classes, mergeBase: git(['merge-base', base, 'HEAD'])?.trim() });
  fs.mkdirSync(m.out, { recursive: true, mode: 0o700 });
  const t = sectionTexts(ROOT);
  renderStage(m, 'first', t, branchDiff);
  renderStage(m, 'specialists', t, branchDiff);
  writeManifest(file, m);
  const count = (s: string) => m.readers.filter(r => r.stage === s).length;
  process.stdout.write([...planLines, `MANIFEST: file=${file} pass=${id} readers=${m.readers.length} first=${count('first')} specialists=${count('specialists')} red-team=${count('red-team')} voices=${count('voices')}`, ...m.readers.map(r => readerLine(m, r))].join('\n') + '\n');
  return EXIT.ok;
}

function passStep(cmd: string): number {
  const file = flag('--manifest');
  if (!file) { process.stderr.write(`gstack-review-dispatch ${cmd}: --manifest <file> is required\n`); return EXIT.usage; }
  const m = readManifest(file);
  if (cmd === 'show') { process.stdout.write(`MANIFEST_JSON: ${JSON.stringify(m)}\n`); return EXIT.ok; }
  if (cmd === 'stage') {
    const stage = flag('--stage') as Stage | undefined;
    if (!stage || !STAGES.includes(stage)) { process.stderr.write(`gstack-review-dispatch stage: --stage ${STAGES.join('|')}\n`); return EXIT.usage; }
    const done = renderStage(m, stage, sectionTexts(ROOT), branchDiff);
    writeManifest(file, m);
    process.stdout.write([`STAGE: ${stage} rendered=${done.length}`, ...done.map(r => readerLine(m, r))].join('\n') + '\n');
    return EXIT.ok;
  }
  if (cmd === 'chunk') {
    const r = m.readers.find(x => x.reader === flag('--reader'));
    if (!r?.file || !r.sha256) { process.stderr.write(`gstack-review-dispatch chunk: no rendered reader ${flag('--reader')}\n`); return EXIT.usage; }
    const text = readFile(r.file, 'brief')!;
    if (promptHash(text) !== r.sha256) throw new BriefError(`${r.reader}'s brief ${r.file} changed since it was rendered`);
    const index = Number(flag('--index') ?? '0');
    process.stdout.write(`BRIEF_CHUNK: reader=${r.reader} index=${index} of=${chunkCount(text)} sha256=${r.sha256}\n${JSON.stringify(chunkOf(text, index))}\n`);
    return EXIT.ok;
  }
  if (cmd === 'mark') {
    const logStart = flag('--log-start');
    if (logStart) {
      const token = flag('--token');
      if (!token) { process.stderr.write('gstack-review-dispatch mark: --log-start <key> --token <t>\n'); return EXIT.usage; }
      m.log_starts ??= {};
      m.log_starts[logStart] ??= token;
      writeManifest(file, m);
      process.stdout.write(`LOG_START: ${logStart} token=${m.log_starts[logStart]}\n`);
      return EXIT.ok;
    }
    const before = flag('--before');
    if (before) {
      const [tokens, credits] = before.split(',').map(Number);
      if (!Number.isFinite(tokens) || !Number.isFinite(credits)) { process.stderr.write('gstack-review-dispatch mark: --before <tokens>,<credits>\n'); return EXIT.usage; }
      m.before ??= { tokens: tokens!, credits: credits! };
      writeManifest(file, m);
      process.stdout.write(`BEFORE: tokens=${m.before.tokens} credits=${m.before.credits}\n`);
      return EXIT.ok;
    }
    const r = markReader(m, flag('--reader') ?? '', flag('--state') as ReaderState, { path: flag('--path'), output: flag('--output'), error: flag('--error') });
    writeManifest(file, m);
    process.stdout.write(readerLine(m, r) + '\n');
    return EXIT.ok;
  }
  return EXIT.usage;
}

function program(): number {
  const text = readFile(PROGRAM_FILE, 'pass program')!;
  const sha = promptHash(text);
  const ledger = flag('--ledger');
  if (ledger) appendEvent(ledger, { event: 'program', version: PROGRAM_VERSION, sha256: sha });
  process.stdout.write(`PROGRAM: v${PROGRAM_VERSION} sha256=${sha} bytes=${Buffer.byteLength(text)}\n${JSON.stringify(text)}\n`);
  return EXIT.ok;
}

/**
 * The receipt's review_targeted record from the newest targeted dispatch: done only when its brief was sent verbatim, its output
 * collected, and the committed diff it was rendered on is still the one at verify (targetedPatchId; uncommitted never proves it).
 */
function targetedRecord(ledger: string, rows: VerifyRow[]): { classes: string[]; rules: string; brief_sha: string; status: 'done' | 'failed'; findings: number; raised_by: string } | null {
  const events = readLedger(ledger);
  const render = events.filter(e => e.event === 'rendered' && e.reader === 'targeted').at(-1);
  if (!render) return null;
  const label = rows.filter(r => r.kind === 'BRIEF' && r.reader.split('@')[0] === 'targeted').at(-1)?.reader;
  const brief = rows.filter(r => r.kind === 'BRIEF' && r.reader === label).at(-1);
  const output = rows.filter(r => r.kind === 'OUTPUT' && r.reader === label).at(-1);
  const read = typeof render.patch_id === 'string' && !['uncommitted', 'none'].includes(render.patch_id) && typeof render.diff_base === 'string' && targetedPatchId(process.cwd(), render.diff_base) === render.patch_id;
  const done = brief?.status === 'MATCH' && output?.status === 'MATCH' && read;
  const ids = events.filter(e => e.event === 'output' && e.reader === 'targeted').at(-1)?.ids;
  return { classes: (render.classes as string[]) ?? [], rules: String(render.rules), brief_sha: String(render.brief_sha), status: done ? 'done' : 'failed', findings: done && Array.isArray(ids) ? ids.length : 0, raised_by: 'targeted' };
}

function main(): number {
  const cmd = args[0];
  if (!cmd || cmd === '--help' || cmd === '-h') { process.stdout.write(HELP + '\n'); return cmd ? EXIT.ok : EXIT.usage; }
  if (cmd === 'render') return render();
  if (cmd === 'pass') return pass();
  if (cmd === 'program') return program();
  if (['show', 'stage', 'chunk', 'mark'].includes(cmd)) return passStep(cmd);
  const ledger = flag('--ledger');
  if (!ledger) { process.stderr.write(`gstack-review-dispatch ${cmd}: --ledger <file> is required\n`); return EXIT.usage; }
  const reader = flag('--role') ? readerKey(flag('--role')!, flag('--name')) : '';
  if (cmd === 'sent') {
    const sent = readFile(flag('--sent'), 'sent prompt');
    if (!reader || sent === undefined) { process.stderr.write('gstack-review-dispatch sent: needs --role and --sent <file>\n'); return EXIT.usage; }
    const r = recordSent(ledger, reader, sent);
    process.stdout.write(r.ok ? `BRIEF_SENT: reader=${reader} sha256=${r.sent} match\n`
      : `BRIEF_MISMATCH: reader=${reader} rendered=${r.rendered ?? 'none'} sent=${r.sent} (dispatch the rendered file unchanged; this reader's review does not count)\n`);
    return r.ok ? EXIT.ok : EXIT.fail;
  }
  if (cmd === 'collect') {
    const outFile = flag('--output');
    const output = readFile(outFile, 'reader output');
    const merged = flag('--merged');
    if (!reader || output === undefined || !merged) { process.stderr.write('gstack-review-dispatch collect: needs --role, --output <file> and --merged <file>\n'); return EXIT.usage; }
    const r = collect(ledger, reader, output, merged, path.resolve(outFile!));
    process.stdout.write(`COLLECT: reader=${reader} findings=${r.lines.length} sha256=${r.sha} merged=${merged}\n`);
    return EXIT.ok;
  }
  if (cmd === 'judge') {
    const merged = flag('--merged');
    const judged = flag('--judged');
    if (!merged || !judged) { process.stderr.write('gstack-review-dispatch judge: needs --merged <file> and --judged <file>\n'); return EXIT.usage; }
    const r = recordJudgment(ledger, readJsonl<MergedLine>(merged), readJsonl<JudgedLine>(judged), judged, merged);
    process.stdout.write(r.ok ? `JUDGMENT: ok added=${r.added.length} promoted=${r.promoted.length} folded=${r.folded.length}\n`
      : `JUDGMENT_REJECTED: dropped=${JSON.stringify(r.dropped)} downgraded=${JSON.stringify(r.downgraded)} unexplained=${JSON.stringify(r.unexplained)} invalid=${JSON.stringify(r.invalid)} (lead judgment may add or promote a finding, never drop or downgrade one)\n`);
    return r.ok ? EXIT.ok : EXIT.fail;
  }
  if (cmd === 'verify') {
    const v = verify(ledger);
    for (const r of v.rows) process.stdout.write(`${r.kind} ${r.reader} ${r.status} ${r.detail}\n`);
    if (!v.briefs) { process.stdout.write('VERIFY: no brief records (this run\'s ledger kept no prompts; dispatched-vs-rendered cannot be checked)\n'); return EXIT.refused; }
    const record = targetedRecord(ledger, v.rows);
    if (record) {
      process.stdout.write(`TARGETED_RECORD: classes=${record.classes.join(',')} status=${record.status} findings=${record.findings} brief=${record.brief_sha.slice(0, 12)} rules=${record.rules}\n`);
      if (flag('--targeted-out')) fs.writeFileSync(flag('--targeted-out')!, JSON.stringify(record) + '\n');
    }
    process.stdout.write(`VERIFY: ${v.clean ? 'clean' : 'dirty'} briefs=${v.briefs} outputs=${v.rows.filter(r => r.kind === 'OUTPUT').length} voided=${v.voided}\n`);
    return v.clean ? EXIT.ok : EXIT.fail;
  }
  process.stderr.write(`gstack-review-dispatch: unknown command ${cmd}\n${HELP}\n`);
  return EXIT.usage;
}

try { process.exit(main()); } catch (e) {
  if (e instanceof BriefError) { process.stderr.write(`BRIEF_RENDER_FAILED: ${e.message}\n`); process.exit(EXIT.fail); }
  throw e;
}