diff --git a/src/automation/mergeStewardGuards.test.ts b/src/automation/mergeStewardGuards.test.ts new file mode 100644 index 00000000..2c12826a --- /dev/null +++ b/src/automation/mergeStewardGuards.test.ts @@ -0,0 +1,222 @@ +// AGT-4879 — merge steward guard engine (dry-run). Each guard has a fixture that +// differs from an all-green baseline in exactly one respect: the full engine +// refuses it naming that guard, and the same engine minus that guard lets it +// through. That is the proof the guard is load-bearing. + +import { readFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; +import { describe, expect, it } from 'vitest'; +import { + STEWARD_GUARDS, + applyStewardGuards, + evaluateMergeSteward, + formatStewardDecision, + isDecisionCurrent, + type StewardGuardName, + type StewardSnapshot, +} from './mergeStewardGuards.js'; + +const HEAD = 'a'.repeat(40); +const OLD = 'b'.repeat(40); + +function baseline(overrides: Partial = {}): StewardSnapshot { + return { + prNumber: 101, + headSha: HEAD, + title: 'fix(api): handle empty payload (AX-1)', + files: ['src/api.ts', 'src/api.test.ts'], + complete: true, + requiredChecks: ['Tests', 'Lint'], + checks: [ + { name: 'Tests', conclusion: 'success', headSha: HEAD }, + { name: 'Lint', conclusion: 'success', headSha: HEAD }, + ], + risk: { level: 'low', headSha: HEAD }, + siblings: [{ number: 102, headRefName: 'swarm/AX-2-docs', files: ['docs/guide.md'], complete: true }], + review: { verdict: 'approve', headSha: HEAD }, + completeness: { verdict: 'complete', headSha: HEAD }, + ...overrides, + }; +} + +function without(name: StewardGuardName) { + return STEWARD_GUARDS.filter((g) => g.name !== name); +} + +function expectLoadBearing(name: StewardGuardName, snapshot: StewardSnapshot): void { + const full = evaluateMergeSteward(snapshot); + expect(full.mergeable).toBe(false); + expect(full.results.filter((r) => !r.pass).map((r) => r.guard)).toEqual([name]); + expect(applyStewardGuards(snapshot, without(name)).mergeable).toBe(true); +} + +describe('merge steward baseline', () => { + it('passes an all-green low-risk complete PR with no overlap', () => { + const decision = evaluateMergeSteward(baseline()); + expect(decision.mergeable).toBe(true); + expect(decision.dryRun).toBe(true); + expect(decision.headSha).toBe(HEAD); + expect(decision.results.map((r) => r.guard)).toEqual([ + 'required-checks', + 'risk', + 'sibling-overlap', + 'review-completeness', + ]); + }); + + it('runs all four guards', () => { + expect(STEWARD_GUARDS.map((g) => g.name)).toEqual([ + 'required-checks', + 'risk', + 'sibling-overlap', + 'review-completeness', + ]); + }); + + it('never approves with an empty guard list', () => { + expect(applyStewardGuards(baseline(), []).mergeable).toBe(false); + }); +}); + +describe('guard: required checks green on the head SHA', () => { + it('a failing required check is load-bearing', () => { + expectLoadBearing('required-checks', baseline({ + checks: [ + { name: 'Tests', conclusion: 'failure', headSha: HEAD }, + { name: 'Lint', conclusion: 'success', headSha: HEAD }, + ], + })); + }); + + it('refuses a pending or missing required check', () => { + expectLoadBearing('required-checks', baseline({ + checks: [{ name: 'Tests', conclusion: 'pending', headSha: HEAD }], + })); + }); + + it('refuses checks that went green only on an older commit', () => { + expectLoadBearing('required-checks', baseline({ + checks: [ + { name: 'Tests', conclusion: 'success', headSha: OLD }, + { name: 'Lint', conclusion: 'success', headSha: OLD }, + ], + })); + }); + + it('refuses when a re-run on the head failed after an earlier success', () => { + expectLoadBearing('required-checks', baseline({ + checks: [ + { name: 'Tests', conclusion: 'success', headSha: HEAD }, + { name: 'Tests', conclusion: 'failure', headSha: HEAD }, + { name: 'Lint', conclusion: 'success', headSha: HEAD }, + ], + })); + }); + + it('refuses an empty required-check set (AGT-4414)', () => { + const decision = evaluateMergeSteward(baseline({ requiredChecks: [], checks: [] })); + expect(decision.mergeable).toBe(false); + expect(decision.blockedBy[0]).toContain('no required checks'); + }); +}); + +describe('guard: risk is low', () => { + it('a medium-risk PR is load-bearing', () => { + expectLoadBearing('risk', baseline({ risk: { level: 'medium', headSha: HEAD } })); + }); + + it('refuses high, unknown and missing risk', () => { + expectLoadBearing('risk', baseline({ risk: { level: 'high', headSha: HEAD } })); + expectLoadBearing('risk', baseline({ risk: { level: null, headSha: HEAD } })); + expectLoadBearing('risk', baseline({ risk: null })); + }); + + it('refuses a low class computed on an older commit', () => { + expectLoadBearing('risk', baseline({ risk: { level: 'low', headSha: OLD } })); + }); +}); + +describe('guard: no open sibling PR touches the same files', () => { + it('an overlapping sibling is load-bearing', () => { + expectLoadBearing('sibling-overlap', baseline({ + siblings: [{ number: 103, headRefName: 'swarm/AX-3-api', files: ['src/api.ts'], complete: true }], + })); + }); + + it('refuses when a sibling\'s file list is unknown or truncated', () => { + expectLoadBearing('sibling-overlap', baseline({ + siblings: [{ number: 103, headRefName: 'swarm/AX-3', files: null, complete: false }], + })); + expectLoadBearing('sibling-overlap', baseline({ + siblings: [{ number: 103, headRefName: 'swarm/AX-3', files: ['docs/x.md'], complete: false }], + })); + }); + + it('refuses when this PR\'s own file list is unknown or truncated', () => { + expectLoadBearing('sibling-overlap', baseline({ files: null, complete: false })); + expectLoadBearing('sibling-overlap', baseline({ complete: false })); + }); + + it('counts a rename source listed by a sibling as overlap', () => { + // This PR renamed src/old.ts -> src/new.ts; the list carries both paths. + expectLoadBearing('sibling-overlap', baseline({ + files: ['src/old.ts', 'src/new.ts'], + siblings: [{ number: 104, headRefName: 'swarm/AX-4', files: ['src/old.ts'], complete: true }], + })); + }); + + it('ignores OpenSwarm bookkeeping that every worktree carries, and itself', () => { + const decision = evaluateMergeSteward(baseline({ + files: ['src/api.ts', '.openswarm-preserved'], + siblings: [ + { number: 105, headRefName: 'swarm/AX-5', files: ['.openswarm-preserved', 'docs/a.md'], complete: true }, + { number: 101, headRefName: 'swarm/AX-1', files: ['src/api.ts'], complete: true }, + ], + })); + expect(decision.mergeable).toBe(true); + }); +}); + +describe('guard: reviewer approved and the run is complete', () => { + it('a missing reviewer is load-bearing (fail-closed until AGT-4806 lands)', () => { + expectLoadBearing('review-completeness', baseline({ review: null })); + }); + + it('refuses a rejecting or stale review', () => { + expectLoadBearing('review-completeness', baseline({ review: { verdict: 'reject', headSha: HEAD } })); + expectLoadBearing('review-completeness', baseline({ review: { verdict: 'approve', headSha: OLD } })); + }); + + it('refuses a partial run, by verdict or by the [partial] title marker', () => { + expectLoadBearing('review-completeness', baseline({ completeness: { verdict: 'partial', headSha: HEAD } })); + expectLoadBearing('review-completeness', baseline({ completeness: null })); + expectLoadBearing('review-completeness', baseline({ completeness: { verdict: 'complete', headSha: OLD } })); + expectLoadBearing('review-completeness', baseline({ title: '[partial] fix(api): handle empty payload' })); + }); +}); + +describe('dry-run only', () => { + it('refuses dryRun: false instead of silently doing nothing', () => { + expect(() => evaluateMergeSteward(baseline(), { dryRun: false })).toThrow(/no merge path/); + }); + + it('a decision is valid only for the head it was computed on', () => { + const decision = evaluateMergeSteward(baseline()); + expect(isDecisionCurrent(decision, HEAD)).toBe(true); + expect(isDecisionCurrent(decision, OLD)).toBe(false); + }); + + it('records the verdict and reasons in one line', () => { + expect(formatStewardDecision(evaluateMergeSteward(baseline()))).toContain('would merge'); + const line = formatStewardDecision(evaluateMergeSteward(baseline({ risk: { level: 'high', headSha: HEAD } }))); + expect(line).toContain('would NOT merge'); + expect(line).toContain('risk: risk is high'); + }); + + it('has no code path that could merge: no process, network or GitHub client imports', () => { + const source = readFileSync(fileURLToPath(new URL('./mergeStewardGuards.ts', import.meta.url)), 'utf8'); + const imports = source.split('\n').filter((line) => /^\s*import\s/.test(line)); + expect(imports.every((line) => line.includes("'../agents/siblingWorkFormat.js'"))).toBe(true); + expect(source).not.toMatch(/child_process|execFile|spawn\(|fetch\(|octokit|gh pr merge|\/merge\b/i); + }); +}); diff --git a/src/automation/mergeStewardGuards.ts b/src/automation/mergeStewardGuards.ts new file mode 100644 index 00000000..9f7725d5 --- /dev/null +++ b/src/automation/mergeStewardGuards.ts @@ -0,0 +1,265 @@ +// Created: 2026-11-15 +// Purpose: merge steward guard engine, dry-run only — decides whether a factory PR may be merged and why (AGT-4879) +// Dependencies: ../agents/siblingWorkFormat (bookkeeping paths) +// Test Status: mergeStewardGuards.test.ts + +/** + * The merge steward is the only actor allowed to merge a factory PR (AGT-4803, + * after AGT-4414: an agent merged its own PR seven seconds after opening it). + * This module is the decision only. It never merges, never shells out and never + * talks to GitHub: it reads a snapshot gathered elsewhere and returns a verdict + * with reasons. `evaluateMergeSteward` refuses `dryRun: false` until a real merge + * path has its own review. + * + * Every guard is fail-closed. Evidence that is missing, unknown, truncated, or + * recorded on a commit other than the current head counts as a failure, so a + * stale snapshot can never approve a newer push. + */ + +import { isBookkeepingPath } from '../agents/siblingWorkFormat.js'; + +/** Local mirror of the publisher's class (AGT-4804); kept here so the engine does not depend on that PR. */ +export type StewardRiskLevel = 'low' | 'medium' | 'high'; + +export type CheckConclusion = 'success' | 'failure' | 'pending' | 'skipped' | 'cancelled' | 'neutral' | 'unknown'; + +export interface StewardCheck { + name: string; + conclusion: CheckConclusion; + /** Commit the check ran on. */ + headSha: string; +} + +/** + * One PR's changed paths. `files: null` or `complete: false` means the list could not be read + * in full. A rename must list both its old and its new path: a sibling editing the old path + * conflicts just as much. + */ +export interface StewardFileList { + files: readonly string[] | null; + /** False when the host truncated the list (e.g. paged API cut off). */ + complete: boolean; +} + +export interface StewardSiblingPr extends StewardFileList { + number: number; + headRefName: string; +} + +export interface StewardReview { + verdict: 'approve' | 'reject' | 'revise' | 'unknown'; + /** Commit the reviewer looked at. */ + headSha: string; +} + +export interface StewardCompleteness { + verdict: 'complete' | 'partial' | 'unknown'; + headSha: string; +} + +export interface StewardRisk { + level: StewardRiskLevel | null; + /** Commit whose final diff was classified. */ + headSha: string; +} + +export interface StewardSnapshot extends StewardFileList { + prNumber: number; + /** The PR's current head commit. All evidence must be for this SHA. */ + headSha: string; + title: string; + /** Names of the branch-protection required checks. Empty is not "nothing to wait for": it is refused. */ + requiredChecks: readonly string[]; + checks: readonly StewardCheck[]; + risk: StewardRisk | null; + /** Other open swarm PRs in the same repository. */ + siblings: readonly StewardSiblingPr[]; + review: StewardReview | null; + completeness: StewardCompleteness | null; +} + +export type StewardGuardName = 'required-checks' | 'risk' | 'sibling-overlap' | 'review-completeness'; + +export interface StewardGuardResult { + guard: StewardGuardName; + pass: boolean; + reason: string; +} + +export interface StewardGuard { + name: StewardGuardName; + check(snapshot: StewardSnapshot): StewardGuardResult; +} + +export interface StewardDecision { + prNumber: number; + /** The head the decision was computed for; a different head invalidates it. */ + headSha: string; + mergeable: boolean; + dryRun: true; + results: StewardGuardResult[]; + /** Reasons of the failing guards, in guard order. */ + blockedBy: string[]; +} + +const pass = (guard: StewardGuardName, reason: string): StewardGuardResult => ({ guard, pass: true, reason }); +const fail = (guard: StewardGuardName, reason: string): StewardGuardResult => ({ guard, pass: false, reason }); + +function short(sha: string): string { + return sha.slice(0, 12); +} + +const requiredChecksGuard: StewardGuard = { + name: 'required-checks', + check(s) { + const name = 'required-checks'; + if (s.requiredChecks.length === 0) { + return fail(name, 'no required checks are configured; an empty set proves nothing (AGT-4414)'); + } + const problems: string[] = []; + for (const required of s.requiredChecks) { + const runs = s.checks.filter((c) => c.name === required); + const onHead = runs.filter((c) => c.headSha === s.headSha); + if (onHead.length === 0) { + problems.push(runs.length > 0 ? `${required}: only ran on another commit` : `${required}: missing`); + continue; + } + // Any non-success run on the head (a re-run that failed, a pending one) blocks. + const bad = onHead.find((c) => c.conclusion !== 'success'); + if (bad) problems.push(`${required}: ${bad.conclusion}`); + } + return problems.length > 0 + ? fail(name, `required checks not green on ${short(s.headSha)}: ${problems.join('; ')}`) + : pass(name, `${s.requiredChecks.length} required check(s) green on ${short(s.headSha)}`); + }, +}; + +const riskGuard: StewardGuard = { + name: 'risk', + check(s) { + const name = 'risk'; + if (!s.risk || s.risk.level === null) return fail(name, 'risk class unknown'); + if (s.risk.headSha !== s.headSha) { + return fail(name, `risk was classified on ${short(s.risk.headSha)}, not the head ${short(s.headSha)}`); + } + if (s.risk.level !== 'low') return fail(name, `risk is ${s.risk.level}; only low merges without a person`); + return pass(name, 'risk is low'); + }, +}; + +function readableFiles(list: StewardFileList): string[] | null { + if (!list.complete || list.files === null) return null; + return list.files.filter((file) => !isBookkeepingPath(file)); +} + +const siblingOverlapGuard: StewardGuard = { + name: 'sibling-overlap', + check(s) { + const name = 'sibling-overlap'; + const own = readableFiles(s); + if (own === null) return fail(name, 'this PR\'s changed-file list is unknown or truncated'); + const ownSet = new Set(own); + const problems: string[] = []; + for (const sibling of s.siblings) { + if (sibling.number === s.prNumber) continue; + const theirs = readableFiles(sibling); + if (theirs === null) { + problems.push(`#${sibling.number} (${sibling.headRefName}): file list unknown or truncated`); + continue; + } + const shared = theirs.filter((file) => ownSet.has(file)); + if (shared.length > 0) { + const shown = shared.slice(0, 5).join(', '); + problems.push(`#${sibling.number} (${sibling.headRefName}) also touches ${shown}${shared.length > 5 ? ', …' : ''}`); + } + } + return problems.length > 0 + ? fail(name, `open sibling PRs overlap: ${problems.join('; ')}`) + : pass(name, `no open sibling PR touches the same files (${s.siblings.length} checked)`); + }, +}; + +const PARTIAL_MARKER = /\[partial\]/i; + +const reviewCompletenessGuard: StewardGuard = { + name: 'review-completeness', + check(s) { + const name = 'review-completeness'; + if (!s.review) return fail(name, 'no reviewer verdict recorded'); + if (s.review.headSha !== s.headSha) { + return fail(name, `review was for ${short(s.review.headSha)}, not the head ${short(s.headSha)}`); + } + if (s.review.verdict !== 'approve') return fail(name, `reviewer verdict is ${s.review.verdict}`); + if (PARTIAL_MARKER.test(s.title)) return fail(name, 'PR title is marked [partial]'); + if (!s.completeness) return fail(name, 'no completeness verdict recorded'); + if (s.completeness.headSha !== s.headSha) { + return fail(name, `completeness was judged on ${short(s.completeness.headSha)}, not the head ${short(s.headSha)}`); + } + if (s.completeness.verdict !== 'complete') return fail(name, `completeness verdict is ${s.completeness.verdict}`); + return pass(name, 'reviewer approved and the run is complete'); + }, +}; + +/** Every guard, in report order. The steward always runs all of them. */ +export const STEWARD_GUARDS: readonly StewardGuard[] = Object.freeze([ + requiredChecksGuard, + riskGuard, + siblingOverlapGuard, + reviewCompletenessGuard, +]); + +/** + * Apply a guard list to a snapshot. Exported for tests that prove each guard is + * load-bearing by removing it; production goes through `evaluateMergeSteward`, + * which always uses `STEWARD_GUARDS`. + */ +export function applyStewardGuards(snapshot: StewardSnapshot, guards: readonly StewardGuard[]): StewardDecision { + const results = guards.map((guard) => { + try { + return guard.check(snapshot); + } catch (err) { + return fail(guard.name, `guard threw: ${err instanceof Error ? err.message : String(err)}`); + } + }); + const failing = results.filter((r) => !r.pass); + return { + prNumber: snapshot.prNumber, + headSha: snapshot.headSha, + mergeable: guards.length > 0 && failing.length === 0, + dryRun: true, + results, + blockedBy: failing.map((r) => `${r.guard}: ${r.reason}`), + }; +} + +export interface EvaluateMergeStewardOptions { + /** Defaults to true. There is no merge path yet, so false is refused. */ + dryRun?: boolean; +} + +/** Decide whether the steward would merge this PR. Never merges. */ +export function evaluateMergeSteward( + snapshot: StewardSnapshot, + options: EvaluateMergeStewardOptions = {}, +): StewardDecision { + if (options.dryRun === false) { + throw new Error('merge steward: only --dry-run is implemented; there is no merge path (AGT-4879)'); + } + return applyStewardGuards(snapshot, STEWARD_GUARDS); +} + +/** + * A decision is only valid for the head it was computed on. A push after the + * snapshot makes every piece of evidence stale. + */ +export function isDecisionCurrent(decision: StewardDecision, currentHeadSha: string): boolean { + return decision.headSha === currentHeadSha; +} + +/** One log line per decision: the verdict and why. */ +export function formatStewardDecision(decision: StewardDecision): string { + const head = `[steward dry-run] PR #${decision.prNumber} @ ${short(decision.headSha)}: `; + return decision.mergeable + ? `${head}would merge — ${decision.results.map((r) => r.reason).join('; ')}` + : `${head}would NOT merge — ${decision.blockedBy.join(' | ')}`; +}