/** * GSTA-167 PR 3a: a handoff child reads only its segment's sections. On #34 * and #36 the Steps 7-11.5 child booted at 1.29M by reading the whole ship * skill, preamble.md and docs/ship-budget.md before its first step; the brief * now names ship/SKILL.md's step list, the segment's sections and * budget-handoff.md, and nothing else. Variant E (replay 5): Steps 7-8 stay * with the parent, so the review child (Steps 9-11.5) reads review-army.md and * adversarial.md, and the record the driver keeps carries the six headings. */ import { afterEach, describe, expect, test } from 'bun:test'; import * as fs from 'node:fs'; import { RECORD_HEADINGS, segmentSections } from '../lib/ship-handoff'; import { budgetHarness, type Harness } from './helpers/ship-budget-harness'; const ROOT = `${import.meta.dir}/..`; const harnesses: Harness[] = []; const fresh = () => { const h = budgetHarness(); harnesses.push(h); return h; }; afterEach(() => { while (harnesses.length) harnesses.pop()!.cleanup(); }); function briefFor(from: string, to: string): string { const h = fresh(); const s = h.sb(['start', '--record', h.record(), '--token-cap', '400M', '--reading', '98000']); expect(s.code, s.out + s.err).toBe(0); const ho = h.sb(['handoff', '--run', h.field(s.out, 'BUDGET_RUN', 'id'), '--from', from, '--to', to, '--base', 'origin/main', '--reading', '1000000']); expect(ho.code, ho.out + ho.err).toBe(0); return fs.readFileSync(ho.out.match(/^HANDOFF: (\S+) /m)![1]!, 'utf8'); } const readSection = (text: string) => text.slice(text.indexOf('## Read'), text.indexOf('\n## ', text.indexOf('## Read') + 1)); describe('the handoff brief names only the segment\'s sections', () => { test('Steps 9-11.5: the step list plus review-army and adversarial only', () => { const read = readSection(briefFor('9', '11.5')); expect(read).toContain("ship/SKILL.md's step list"); for (const s of ['review-army.md', 'adversarial.md', 'budget-handoff.md']) expect(read).toContain(s); for (const s of ['test-coverage.md', 'plan-completion.md', 'changelog.md', 'documentation.md', 'pr-body.md', 'capy-pr.md', 'tests.md']) expect(read).not.toContain(s); expect(read).toMatch(/Never read ship\/sections\/preamble\.md in full or docs\/ship-budget\.md/); }); test('Steps 12-22: the step list plus changelog, documentation, pr-body and capy-pr', () => { const read = readSection(briefFor('12', '22')); for (const s of ['changelog.md', 'documentation.md', 'pr-body.md', 'capy-pr.md', 'budget-handoff.md']) expect(read).toContain(s); for (const s of ['test-coverage.md', 'plan-completion.md', 'review-army.md', 'adversarial.md']) expect(read).not.toContain(s); expect(read).toMatch(/Never read ship\/sections\/preamble\.md in full or docs\/ship-budget\.md/); }); test('a grandchild segment names only the sections of its own steps', () => { expect(segmentSections('9', '11.5')).toEqual(['review-army', 'adversarial']); expect(segmentSections('19', '22')).toEqual(['pr-body', 'capy-pr']); expect(segmentSections('1', '22')).toEqual(['tests', 'greptile-early', 'test-coverage', 'plan-completion', 'review-army', 'adversarial', 'changelog', 'documentation', 'pr-body', 'capy-pr']); }); // Value: protects=a handoff child reads exact line ranges: never ship/SKILL.md's preamble, the section index or another segment's steps, and every review section whole, so its reviewer briefs are the section's own text; fails_when=the brief names files without ranges, a range starts at line 1 of SKILL.md, a review section is cut, or a gate heading falls outside the ranges; // why_new=the tests above check file names only; seam=none; no_claim=that a child obeys the ranges test('the brief prints READ: ranges per file that skip the preamble, keep every gate heading and read each review section whole', () => { const ranges = (text: string) => Object.fromEntries([...text.matchAll(/^READ: (\S+?):([\d,-]+)$/gm)].map(m => [m[1]!, m[2]!.split(',').map(r => r.split('-').map(Number) as [number, number])])); const lineOf = (file: string, heading: string) => fs.readFileSync(`${ROOT}/${file}`, 'utf8').split('\n').findIndex(l => l.startsWith(heading)) + 1; const inside = (rs: [number, number][], n: number) => n > 0 && rs.some(([a, b]) => a <= n && n <= b); const total = (file: string) => fs.readFileSync(`${ROOT}/${file}`, 'utf8').replace(/\n$/, '').split('\n').length; const seg = briefFor('9', '11.5'); expect(seg).toMatch(/Read only the `READ:` ranges below/); const r = ranges(seg); const skill = r['ship/SKILL.md']!; expect(skill[0]![0]).toBe(lineOf('ship/SKILL.md', '# Ship:')); for (const h of ['## Step 11.5:', '## Important Rules', '### Ship control flow']) expect(inside(skill, lineOf('ship/SKILL.md', h)), h).toBe(true); for (const h of ['## Preamble (run first)', '## Section index', '## Step 3:', '## Step 7:', '## Step 8:', '## Step 12:']) expect(inside(skill, lineOf('ship/SKILL.md', h)), h).toBe(false); for (const s of ['review-army', 'adversarial', 'budget-handoff']) expect(r[`ship/sections/${s}.md`]).toEqual([[1, total(`ship/sections/${s}.md`)]]); for (const s of ['test-coverage', 'plan-completion']) expect(r[`ship/sections/${s}.md`]).toBeUndefined(); expect(Object.keys(r).filter(k => k.includes('audit-') || k.includes('changelog'))).toEqual([]); const late = ranges(briefFor('12', '22'))['ship/SKILL.md']!; for (const h of ['## Step 12:', '## Step 14.5:', '## Step 17:', '## Step 22:', '## Important Rules']) expect(inside(late, lineOf('ship/SKILL.md', h)), h).toBe(true); for (const h of ['## Step 3:', '## Step 11.5:']) expect(inside(late, lineOf('ship/SKILL.md', h)), h).toBe(false); }); // Value: protects=a segment ending at Step 22 is returned at Step 22, so the parent's reconcile reads it complete; fails_when=the brief leaves the return step to the child's reading of "Steps 1-21" (GSTA-167: --to 21 on a 12-22 handoff reconciled child=incomplete and stopped the parent); // why_new=no test follows a brief through return and reconcile at Step 22; seam=none; no_claim=what the child did between verify and return test('a Steps 12-22 brief names Step 22 as the last step and its return command; following it reconciles complete', () => { const h = fresh(); const s = h.sb(['start', '--record', h.record(), '--token-cap', '400M', '--reading', '98000']); const run = h.field(s.out, 'BUDGET_RUN', 'id'); const ho = h.sb(['handoff', '--run', run, '--from', '12', '--to', '22', '--base', 'origin/main', '--reading', '1000000']); expect(ho.code, ho.out + ho.err).toBe(0); const file = ho.out.match(/^HANDOFF: (\S+) /m)![1]!; const text = fs.readFileSync(file, 'utf8'); expect(text).toContain('Your last step is Step 22'); expect(text).toContain('gstack-ship-budget return --run --to 22'); const v = h.sb(['verify-handoff', '--in', file, '--reading', '1100000']); expect(v.code, v.out + v.err).toBe(0); const child = h.field(v.out, 'BUDGET_RUN', 'id'); const ret = h.sb(['return', '--run', child, '--to', '22', '--reading', '2000000']); expect(ret.code, ret.out + ret.err).toBe(0); const rec = h.sb(['reconcile', '--run', run, '--return', ho.out.match(/^RETURN_FILE: (\S+)$/m)![1]!, '--reading', '2100000']); expect(rec.out).toContain('child=complete'); expect(rec.code, rec.out).toBe(0); }); test('every section the brief can name is a registered ship section', () => { const manifest = JSON.parse(fs.readFileSync(`${import.meta.dir}/../ship/sections/manifest.json`, 'utf8')); const ids = new Set(manifest.sections.map((s: any) => s.id)); for (const id of segmentSections('1', '22')) expect(ids.has(id)).toBe(true); }); // Value: protects=the record ship/DRIVER.md tells the parent to keep is one gstack-ship-budget handoff accepts: the driver names each of the six headings with the phase that writes it, and a record holding them hands Steps 9-11.5 off while one missing a heading is refused by name; fails_when=the driver drops or renames a heading the handoff requires (GSTA-167 replay 5: "record ... lacks headings: Release, Decisions, Reviews, Checks, Documentation, Next steps"), or the refusal stops naming the missing heading; // why_new=the harness record above is hand-written, never the driver's; seam=none; no_claim=that the parent writes each heading on time test('the driver names each record heading with its phase, and a record built from it hands Steps 9-11.5 off', () => { const driver = fs.readFileSync(`${ROOT}/ship/DRIVER.md`, 'utf8'); const named = [...driver.matchAll(/\*\*([A-Z][a-z]+(?: steps)?)\*\*\s+\((?:Phases? [\d-]+|Step [\d.]+|any\s+phase|every phase)/g)].map(m => m[1]); expect(new Set(named)).toEqual(new Set(RECORD_HEADINGS)); expect(driver).toContain('write its six headings at Phase 1'); const h = fresh(); const record = (headings: readonly string[]) => { const file = h.record(`driver-${headings.length}.md`); fs.writeFileSync(file, ['# /ship invocation record', '', ...headings.flatMap(x => [`## ${x}`, x === 'Checks' ? '- Coverage: 89% value-weighted; Scope Check: CLEAN' : '', ''])].join('\n')); return file; }; const handoff = (file: string) => { const s = h.sb(['start', '--record', file, '--token-cap', '400M', '--reading', '98000']); expect(s.code, s.out + s.err).toBe(0); return h.sb(['handoff', '--run', h.field(s.out, 'BUDGET_RUN', 'id'), '--from', '9', '--to', '11.5', '--base', 'origin/main', '--reading', '1000000']); }; const ok = handoff(record(RECORD_HEADINGS)); expect(ok.code, ok.out + ok.err).toBe(0); const read = readSection(fs.readFileSync(ok.out.match(/^HANDOFF: (\S+) /m)![1]!, 'utf8')); expect(read).toContain('review-army.md, adversarial.md, budget-handoff.md'); const refused = handoff(record(RECORD_HEADINGS.filter(x => x !== 'Next steps'))); expect(refused.code).toBe(2); expect(refused.err).toContain('lacks headings: Next steps'); }); });