From bad231f914224a3e55cbbed9789e9894b3c37b32 Mon Sep 17 00:00:00 2001 From: Heewon Oh Date: Sun, 15 Nov 2026 07:22:36 +0900 Subject: [PATCH] feat(factory): merge steward guard engine, dry-run only (AGT-4879) A pure decision over a PR snapshot with four fail-closed guards: required checks green on the head SHA, risk low, no open sibling PR touching the same files, reviewer approved and the run complete. Evidence recorded on another commit, missing or truncated counts as a failure. dryRun: false throws; there is no merge path. Each guard has a test that the PR it refuses is let through once that guard is removed. --- src/automation/mergeStewardGuards.test.ts | 222 ++++++++++++++++++ src/automation/mergeStewardGuards.ts | 265 ++++++++++++++++++++++ 2 files changed, 487 insertions(+) create mode 100644 src/automation/mergeStewardGuards.test.ts create mode 100644 src/automation/mergeStewardGuards.ts 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(' | ')}`; +}