@bongos/core 1.17.0

package/tests/gate_approvals.mjs

@@ -0,0 +1,451 @@
+// tests/gate_approvals.mjs
+//
+// Coverage for Archon gate-surface PR approval from the hall (task 1179, ADR 0058
+// amendment) — the path that lets an Archon clear a gate-review-blocked PR from the
+// builders' hall instead of leaving a GitHub review.
+//
+// Three layers, all with NO live DB / server / network:
+//   1. src/bongos/github-push.js helpers — listOpenPullRequests / getPullRequestFiles /
+//      setGateOwnerApproved / recheckPullRequest, through the injectable
+//      fetchImpl / repoInfo / token seams.
+//   2. The route handlers — GET /gate-approvals (filters to gate-review-red PRs and
+//      reuses the REAL classifyChanges to render why) + POST /gate-approvals/:pr/
+//      approve (sets the trustless gate-owner-approved status + re-runs the check),
+//      exercised by stubbing the github-push module the router holds.
+//   3. Structural gating — both routes are requireBuilder + classify to archon under
+//      the route-rank auditor (a silent downgrade of the approve route would let any
+//      builder clear the hard floor).
+//
+// Run:  node tests/gate_approvals.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+
+const gp = require('../modules/lifecycle/github-push.js');
+const auth = require('../src/bongos/auth.js');
+const buildGateApprovalsRouter = require('../modules/lifecycle/routes/gate-approvals.js');
+const { checkRouteRanks } = require('../src/bongos/route-rank-check.js');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+
+let pass = 0, fail = 0;
+const t = async (name, fn) => {
+  try { await fn(); pass++; console.log(`PASS  ${name}`); }
+  catch (e) { fail++; console.log(`FAIL  ${name}\n      ${e.stack || e.message}`); }
+};
+
+const REPO = { owner: 'someowner', repo: 'somerepo', branch: 'main' };
+const SHA = 'a'.repeat(40);
+function jsonRes(status, body) {
+  return { ok: status >= 200 && status < 300, status, json: async () => body, text: async () => JSON.stringify(body) };
+}
+
+// Call the FINAL handler of a route (after the auth middleware) with a mock req/res.
+function routeHandler(router, method, routePath) {
+  const layer = router.stack.find((l) => l.route && l.route.path === routePath && l.route.methods[method]);
+  if (!layer) throw new Error(`route ${method} ${routePath} not registered`);
+  const stack = layer.route.stack;
+  return stack[stack.length - 1].handle;
+}
+function fakeRes() {
+  const res = { statusCode: 200, body: null };
+  res.status = (c) => { res.statusCode = c; return res; };
+  res.json = (b) => { res.body = b; return res; };
+  attachFail({}, res, () => {}); // install res.fail() as the router does (task 1991)
+  return res;
+}
+const ARCHON = { id: 1, rank: 'archon', github_login: 'lars589' };
+
+// Snapshot/restore the github-push functions a route test stubs, so layers don't bleed.
+function withStubs(stubs, fn) {
+  const keys = Object.keys(stubs);
+  const saved = keys.map((k) => [k, gp[k]]);
+  for (const k of keys) gp[k] = stubs[k];
+  return (async () => { try { return await fn(); } finally { for (const [k, v] of saved) gp[k] = v; } })();
+}
+
+// A PR node as listOpenPullRequests returns it (already flattened).
+function pr(over = {}) {
+  return {
+    number: 201, title: 'task 1163: x', url: 'http://gh/pr/201', is_draft: false,
+    head_ref: 'claude/x', head_sha: SHA, author: 'someone', body: '', review_decision: null,
+    rollup_state: 'FAILURE',
+    checks: [{ name: 'gate-review', conclusion: 'FAILURE', status: 'COMPLETED', url: 'http://ci' }],
+    ...over,
+  };
+}
+const gateCheck = (conclusion, status = 'COMPLETED') => ({ name: 'gate-review', conclusion, status, url: 'http://ci' });
+
+// ===========================================================================
+// Layer 1 — github-push helpers (injected seams)
+// ===========================================================================
+
+await t('listOpenPullRequests: maps GraphQL nodes → number/head_sha/author/flattened checks', async () => {
+  const fetchImpl = async (_url, opts) => {
+    assert.ok(/pullRequests\(states:OPEN/.test(JSON.parse(opts.body).query), 'queries OPEN PRs');
+    return jsonRes(200, { data: { repository: { pullRequests: { nodes: [{
+      number: 7, title: 'task 9: t', url: 'http://gh/pr/7', isDraft: false, headRefName: 'claude/y',
+      bodyText: 'body', author: { login: 'dev1' }, reviewDecision: 'REVIEW_REQUIRED',
+      commits: { nodes: [{ commit: { oid: SHA, statusCheckRollup: { state: 'FAILURE', contexts: { nodes: [
+        { __typename: 'CheckRun', name: 'gate-review', conclusion: 'FAILURE', status: 'COMPLETED', detailsUrl: 'http://ci' },
+        { __typename: 'StatusContext', context: 'gate-author-trust', state: 'SUCCESS', targetUrl: '' },
+      ] } } } }] },
+    }] } } } });
+  };
+  const out = await gp.listOpenPullRequests({ token: 'T', repoInfo: REPO, fetchImpl });
+  assert.equal(out.length, 1);
+  assert.equal(out[0].number, 7);
+  assert.equal(out[0].head_sha, SHA);
+  assert.equal(out[0].author, 'dev1');
+  assert.equal(out[0].checks.find((c) => c.name === 'gate-review').conclusion, 'FAILURE');
+  assert.equal(out[0].checks.find((c) => c.name === 'gate-author-trust').conclusion, 'SUCCESS');
+});
+
+await t('listOpenPullRequests: tolerates a PARTIAL FORBIDDEN (App lacks Checks:read) — uses data, flags partialErrors', async () => {
+  // GitHub returns `data` (PR list intact) ALONGSIDE an errors[] when statusCheckRollup.contexts
+  // is FORBIDDEN. The old code did `if (out.errors) throw` and 502'd; it must now use the data.
+  const fetchImpl = async () => jsonRes(200, {
+    data: { repository: { pullRequests: { nodes: [{
+      number: 167, title: 'task 1234: x', url: 'http://gh/pr/167', isDraft: false, headRefName: 'claude/z',
+      bodyText: 'b', author: { login: 'dev2' }, reviewDecision: null,
+      // REAL shape: the FORBIDDEN nulls the individual CheckRun ELEMENTS inside the array
+      // (a null hole) — NOT the whole `nodes` list. Readable StatusContexts survive.
+      commits: { nodes: [{ commit: { oid: SHA, statusCheckRollup: { state: 'FAILURE', contexts: { nodes: [
+        null, // the gate-review CheckRun, FORBIDDEN without Checks:read
+        { __typename: 'StatusContext', context: 'gate-author-trust', state: 'SUCCESS', targetUrl: '' },
+      ] } } } }] },
+    }] } } },
+    errors: [{ type: 'FORBIDDEN', path: ['repository', 'pullRequests', 'nodes', 0, 'commits', 'nodes', 0, 'commit', 'statusCheckRollup', 'contexts', 'nodes', 0] }],
+  });
+  const out = await gp.listOpenPullRequests({ token: 'T', repoInfo: REPO, fetchImpl });
+  assert.equal(out.length, 1, 'PR list is still returned despite the partial error');
+  assert.equal(out[0].number, 167);
+  assert.equal(out[0].head_sha, SHA, 'head sha — all the approve path actually needs — survives');
+  // The null CheckRun hole is filtered out (would otherwise crash on c.__typename); the
+  // readable StatusContext survives, so gate-author-trust / gate-owner-approved still show.
+  assert.deepEqual(out[0].checks.map((c) => c.name), ['gate-author-trust'], 'null CheckRun dropped, StatusContext kept');
+  assert.deepEqual(out.partialErrors, ['FORBIDDEN'], 'reduced fidelity is signalled, not silent');
+});
+
+await t('listOpenPullRequests: a TOP-LEVEL GraphQL failure (no data) still throws GRAPHQL_FAILED with detail', async () => {
+  const fetchImpl = async () => jsonRes(200, { data: null, errors: [{ type: 'FORBIDDEN', message: 'bad creds' }] });
+  await assert.rejects(
+    () => gp.listOpenPullRequests({ token: 'T', repoInfo: REPO, fetchImpl }),
+    (e) => e.code === 'GRAPHQL_FAILED' && /FORBIDDEN/.test(e.detail || '')
+  );
+});
+
+await t('getMergeState: a partial FORBIDDEN on the rollup still yields mergeable/merge_state (merge driver survives)', async () => {
+  const fetchImpl = async () => jsonRes(200, {
+    data: { repository: { pullRequests: { nodes: [{
+      number: 167, id: 'PR_x', state: 'OPEN', merged: false, mergeable: 'MERGEABLE', reviewDecision: null,
+      mergeStateStatus: 'CLEAN',
+      // null CheckRun hole (FORBIDDEN) alongside a readable StatusContext.
+      commits: { nodes: [{ commit: { oid: SHA, statusCheckRollup: { state: 'FAILURE', contexts: { nodes: [
+        null, { __typename: 'StatusContext', context: 'gate-author-trust', state: 'SUCCESS' },
+      ] } } } }] },
+    }] } } },
+    errors: [{ type: 'FORBIDDEN', path: ['repository', 'pullRequests', 'nodes', 0, 'commits', 'nodes', 0, 'commit', 'statusCheckRollup', 'contexts', 'nodes', 0] }],
+  });
+  const s = await gp.getMergeState({ branch: 'claude/z' }, { token: 'T', repoInfo: REPO, fetchImpl });
+  assert.equal(s.mergeable, 'MERGEABLE');
+  assert.equal(s.merge_state, 'CLEAN', 'the gate signal mergeIfGreen depends on is intact');
+  assert.deepEqual(s.checks.map((c) => c.name), ['gate-author-trust'], 'null hole filtered; readable status kept');
+});
+
+await t('getPullRequestFiles: maps REST files → {path,deleted,status}; reflects deletions', async () => {
+  const fetchImpl = async (url) => {
+    assert.ok(/\/pulls\/201\/files/.test(url));
+    return jsonRes(200, [
+      { filename: 'src/bongos/route-rank-check.js', status: 'modified', additions: 3, deletions: 1 },
+      { filename: 'old.js', status: 'removed', additions: 0, deletions: 9 },
+    ]);
+  };
+  const files = await gp.getPullRequestFiles({ number: 201 }, { token: 'T', repoInfo: REPO, fetchImpl });
+  assert.equal(files.length, 2);
+  assert.equal(files[0].path, 'src/bongos/route-rank-check.js');
+  assert.equal(files[0].deleted, false);
+  assert.equal(files[1].deleted, true, 'status removed → deleted');
+});
+
+await t('getPullRequestFiles: rejects a non-positive PR number before any fetch', async () => {
+  await assert.rejects(
+    () => gp.getPullRequestFiles({ number: 0 }, { token: 'T', repoInfo: REPO, fetchImpl: async () => { throw new Error('no fetch'); } }),
+    (e) => e.code === 'BAD_PR'
+  );
+});
+
+await t('setGateOwnerApproved: POSTs a gate-owner-approved success status on the sha', async () => {
+  let captured = null;
+  const fetchImpl = async (url, opts) => { captured = { url, body: JSON.parse(opts.body) }; return { ok: true }; };
+  const ok = await gp.setGateOwnerApproved({ sha: SHA, login: 'lars589' }, { token: 'T', repoInfo: REPO, fetchImpl });
+  assert.equal(ok, true);
+  assert.ok(captured.url.endsWith(`/statuses/${SHA}`), captured.url);
+  assert.equal(captured.body.context, gp.GATE_OWNER_APPROVED_CONTEXT);
+  assert.equal(captured.body.context, 'gate-owner-approved');
+  assert.equal(captured.body.state, 'success');
+  assert.ok(/lars589/.test(captured.body.description), 'records who approved');
+});
+
+await t('recheckPullRequest: PATCHes state=closed then state=open, then re-arms auto-merge', async () => {
+  const calls = [];
+  const fetchImpl = async (url, opts) => {
+    const method = (opts && opts.method) || 'GET';
+    if (method === 'PATCH') { calls.push(JSON.parse(opts.body).state); return jsonRes(200, { node_id: 'N1', state: JSON.parse(opts.body).state }); }
+    if (url === 'https://api.github.com/graphql') { calls.push('automerge'); return jsonRes(200, { data: { enablePullRequestAutoMerge: {} } }); }
+    throw new Error('unexpected ' + url + ' ' + method);
+  };
+  const r = await gp.recheckPullRequest({ number: 201 }, { token: 'T', repoInfo: REPO, fetchImpl, reopenDelayMs: 0 });
+  assert.deepEqual(calls, ['closed', 'open', 'automerge'], 'close → reopen → re-arm auto-merge, in order');
+  assert.equal(r.reopened, true);
+  assert.equal(r.auto_merge, true);
+});
+
+await t('recheckPullRequest: waits between close and reopen so GitHub fires a distinct reopened event (task 1241)', async () => {
+  // Regression for task 1241: a close+reopen issued ~1s apart is coalesced by GitHub
+  // into no net change and dispatches no `pull_request: reopened` event, so the
+  // gate-review run never re-fires. recheckPullRequest must sleep BETWEEN the close
+  // PATCH and the reopen PATCH (deps.reopenDelayMs, default 4s in prod) so the reopen
+  // lands as a distinct state transition. We assert the delay elapses strictly between
+  // the two PATCHes and not before the close / after the reopen.
+  const events = [];
+  const delayMs = 30;
+  const fetchImpl = async (url, opts) => {
+    const method = (opts && opts.method) || 'GET';
+    if (method === 'PATCH') { events.push('patch:' + JSON.parse(opts.body).state); return jsonRes(200, { node_id: 'N1', state: JSON.parse(opts.body).state }); }
+    if (url === 'https://api.github.com/graphql') { events.push('automerge'); return jsonRes(200, { data: { enablePullRequestAutoMerge: {} } }); }
+    throw new Error('unexpected ' + url + ' ' + method);
+  };
+  const t0 = Date.now();
+  await gp.recheckPullRequest({ number: 202 }, { token: 'T', repoInfo: REPO, fetchImpl, reopenDelayMs: delayMs });
+  const elapsed = Date.now() - t0;
+  assert.deepEqual(events, ['patch:closed', 'patch:open', 'automerge'], 'close then (after a wait) reopen then re-arm');
+  assert.ok(elapsed >= delayMs, `total elapsed (${elapsed}ms) must be at least the configured reopen delay (${delayMs}ms)`);
+});
+
+// ===========================================================================
+// Layer 2 — GET /gate-approvals handler logic (stub the github-push module)
+// ===========================================================================
+
+await t('GET /gate-approvals: lists ONLY gate-review-red PRs, with real classifier verdict + reasons', async () => {
+  const prs = [
+    pr({ number: 201, title: 'task 1163: harbor', checks: [gateCheck('FAILURE')] }),       // escalate (route-rank-check)
+    pr({ number: 202, checks: [gateCheck('SUCCESS')] }),                                     // green → excluded
+    pr({ number: 203, is_draft: true, checks: [gateCheck('FAILURE')] }),                     // draft → excluded
+    pr({ number: 204, checks: [gateCheck(null, 'IN_PROGRESS')] }),                           // still checking
+    pr({ number: 205, title: 'task 50: mig', checks: [gateCheck('FAILURE')] }),              // needs_trust (migration)
+    pr({ number: 206, checks: [] }),                                                         // no gate-review → excluded
+  ];
+  const filesByPr = {
+    201: [{ path: 'src/bongos/route-rank-check.js', status: 'modified' }],
+    205: [{ path: 'migrations/200_x.sql', status: 'added' }],
+  };
+  await withStubs({
+    isConfigured: () => true,
+    listOpenPullRequests: async () => prs,
+    getPullRequestFiles: async ({ number }) => filesByPr[number] || [],
+  }, async () => {
+    const handler = routeHandler(buildGateApprovalsRouter(), 'get', '/gate-approvals');
+    const res = fakeRes();
+    await handler({ builder: ARCHON, params: {}, body: {} }, res);
+    assert.equal(res.statusCode, 200);
+    const nums = res.body.awaiting.map((a) => a.number).sort();
+    assert.deepEqual(nums, [201, 205], 'only the two completed-FAILURE non-draft gate PRs');
+    assert.equal(res.body.checking, 1, 'the in-progress PR is counted as checking');
+    const a201 = res.body.awaiting.find((a) => a.number === 201);
+    assert.equal(a201.verdict, 'escalate');
+    assert.equal(a201.task, 1163, 'task id parsed from the title');
+    assert.ok(a201.reasons.some((r) => r.hard_floor === true), 'route-rank-check flagged as hard floor');
+    const a205 = res.body.awaiting.find((a) => a.number === 205);
+    assert.equal(a205.verdict, 'needs_trust');
+    assert.ok(a205.reasons.length >= 1 && a205.reasons.every((r) => r.hard_floor === false));
+  });
+});
+
+await t('GET /gate-approvals: marks already_approved when a gate-owner-approved status is present', async () => {
+  await withStubs({
+    isConfigured: () => true,
+    listOpenPullRequests: async () => [pr({
+      number: 210,
+      checks: [gateCheck('FAILURE'), { name: 'gate-owner-approved', conclusion: 'SUCCESS', status: 'COMPLETED' }],
+    })],
+    getPullRequestFiles: async () => [{ path: 'src/bongos/route-rank-check.js', status: 'modified' }],
+  }, async () => {
+    const handler = routeHandler(buildGateApprovalsRouter(), 'get', '/gate-approvals');
+    const res = fakeRes();
+    await handler({ builder: ARCHON, params: {}, body: {} }, res);
+    assert.equal(res.body.awaiting[0].already_approved, true);
+  });
+});
+
+await t('GET /gate-approvals: 503 when no GitHub credential is configured', async () => {
+  await withStubs({ isConfigured: () => false }, async () => {
+    const handler = routeHandler(buildGateApprovalsRouter(), 'get', '/gate-approvals');
+    const res = fakeRes();
+    await handler({ builder: ARCHON, params: {}, body: {} }, res);
+    assert.equal(res.statusCode, 503);
+    assert.equal(res.body.error.code, 'publish_unconfigured');
+  });
+});
+
+await t('GET /gate-approvals: surfaces checks_readable=false + a note when the check rollup is unreadable', async () => {
+  // listOpenPullRequests returned PRs but flagged a partial error → checks unreadable.
+  const prs = [pr({ number: 167, checks: [] })];
+  prs.partialErrors = ['FORBIDDEN'];
+  await withStubs({
+    isConfigured: () => true,
+    listOpenPullRequests: async () => prs,
+    getPullRequestFiles: async () => [],
+  }, async () => {
+    const handler = routeHandler(buildGateApprovalsRouter(), 'get', '/gate-approvals');
+    const res = fakeRes();
+    await handler({ builder: ARCHON, params: {}, body: {} }, res);
+    assert.equal(res.statusCode, 200);
+    assert.equal(res.body.checks_readable, false);
+    assert.ok(/Checks:read/.test(res.body.note), 'tells the operator exactly what to grant');
+    assert.equal(res.body.count, 0, 'no PRs are listed as awaiting when checks are unreadable (honest empty)');
+  });
+});
+
+// ===========================================================================
+// Layer 2 — POST /gate-approvals/:pr/approve handler logic
+// ===========================================================================
+
+await t('POST approve: sets the owner-approval status on the head sha + re-runs the check', async () => {
+  let approved = null, rechecked = null;
+  await withStubs({
+    isConfigured: () => true,
+    listOpenPullRequests: async () => [pr({ number: 201, head_sha: SHA, checks: [gateCheck('FAILURE')] })],
+    setGateOwnerApproved: async ({ sha, login }) => { approved = { sha, login }; return true; },
+    recheckPullRequest: async ({ number }) => { rechecked = number; return { reopened: true, auto_merge: true }; },
+  }, async () => {
+    const handler = routeHandler(buildGateApprovalsRouter(), 'post', '/gate-approvals/:pr/approve');
+    const res = fakeRes();
+    await handler({ builder: ARCHON, params: { pr: '201' }, body: {} }, res);
+    assert.equal(res.statusCode, 200);
+    assert.equal(res.body.ok, true);
+    assert.equal(res.body.status_set, true);
+    assert.deepEqual(approved, { sha: SHA, login: 'lars589' }, 'approval is sha-pinned to head + records the Archon');
+    assert.equal(rechecked, 201, 'the gate check is re-run for the PR');
+  });
+});
+
+await t('POST approve: still works when checks are unreadable (no gate-review check visible) — sets status + reopens', async () => {
+  // App lacks Checks:read → listOpenPullRequests returns the PR but with empty checks. The
+  // approve path must not depend on reading the gate-review conclusion: it resolves head_sha,
+  // sets the owner-approval status, and reopens. (This is the reported-bug path post-fix.)
+  let approved = null, rechecked = null;
+  await withStubs({
+    isConfigured: () => true,
+    listOpenPullRequests: async () => [pr({ number: 167, head_sha: SHA, checks: [] })],
+    setGateOwnerApproved: async ({ sha, login }) => { approved = { sha, login }; return true; },
+    recheckPullRequest: async ({ number }) => { rechecked = number; return { reopened: true, auto_merge: true }; },
+  }, async () => {
+    const handler = routeHandler(buildGateApprovalsRouter(), 'post', '/gate-approvals/:pr/approve');
+    const res = fakeRes();
+    await handler({ builder: ARCHON, params: { pr: '167' }, body: {} }, res);
+    assert.equal(res.statusCode, 200);
+    assert.equal(res.body.status_set, true);
+    assert.deepEqual(approved, { sha: SHA, login: 'lars589' });
+    assert.equal(rechecked, 167);
+  });
+});
+
+await t('POST approve: a green gate-review is a no-op (already_clear; no status set)', async () => {
+  let approvedCalled = false;
+  await withStubs({
+    isConfigured: () => true,
+    listOpenPullRequests: async () => [pr({ number: 201, checks: [gateCheck('SUCCESS')] })],
+    setGateOwnerApproved: async () => { approvedCalled = true; return true; },
+    recheckPullRequest: async () => ({ reopened: true }),
+  }, async () => {
+    const handler = routeHandler(buildGateApprovalsRouter(), 'post', '/gate-approvals/:pr/approve');
+    const res = fakeRes();
+    await handler({ builder: ARCHON, params: { pr: '201' }, body: {} }, res);
+    assert.equal(res.body.already_clear, true);
+    assert.equal(approvedCalled, false, 'must not set an approval status when nothing is blocked');
+  });
+});
+
+await t('POST approve: 404 when the PR is not open', async () => {
+  await withStubs({
+    isConfigured: () => true,
+    listOpenPullRequests: async () => [],
+  }, async () => {
+    const handler = routeHandler(buildGateApprovalsRouter(), 'post', '/gate-approvals/:pr/approve');
+    const res = fakeRes();
+    await handler({ builder: ARCHON, params: { pr: '999' }, body: {} }, res);
+    assert.equal(res.statusCode, 404);
+    assert.equal(res.body.error.code, 'pr_not_open');
+  });
+});
+
+await t('POST approve: 500 (not 502) when the status write fails — Cloudflare masks an origin 502', async () => {
+  await withStubs({
+    isConfigured: () => true,
+    listOpenPullRequests: async () => [pr({ number: 201, checks: [gateCheck('FAILURE')] })],
+    setGateOwnerApproved: async () => false,
+  }, async () => {
+    const handler = routeHandler(buildGateApprovalsRouter(), 'post', '/gate-approvals/:pr/approve');
+    const res = fakeRes();
+    await handler({ builder: ARCHON, params: { pr: '201' }, body: {} }, res);
+    assert.equal(res.statusCode, 500, 'never a bare 502 — Cloudflare would replace its body');
+    assert.equal(res.body.error.code, 'status_set_failed');
+  });
+});
+
+await t('POST approve: a thrown github-push error becomes a structured 500 with detail (never a bare 502)', async () => {
+  await withStubs({
+    isConfigured: () => true,
+    listOpenPullRequests: async () => { throw Object.assign(new Error('GRAPHQL_FAILED'), { code: 'GRAPHQL_FAILED', detail: '[{"type":"FORBIDDEN"}]' }); },
+  }, async () => {
+    const handler = routeHandler(buildGateApprovalsRouter(), 'post', '/gate-approvals/:pr/approve');
+    const res = fakeRes();
+    await handler({ builder: ARCHON, params: { pr: '201' }, body: {} }, res);
+    assert.equal(res.statusCode, 500, 'a failed upstream read is a 500, not a Cloudflare-masked 502');
+    assert.equal(res.body.error.code, 'gate_approve_failed');
+    assert.equal(res.body.error.message, 'GRAPHQL_FAILED');
+    assert.ok(/FORBIDDEN/.test(res.body.error.details.detail), 'the GraphQL detail is surfaced loudly, not swallowed');
+  });
+});
+
+await t('POST approve: a non-positive :pr is rejected 400 before any GitHub call', async () => {
+  await withStubs({
+    isConfigured: () => { throw new Error('should not reach isConfigured'); },
+  }, async () => {
+    const handler = routeHandler(buildGateApprovalsRouter(), 'post', '/gate-approvals/:pr/approve');
+    const res = fakeRes();
+    await handler({ builder: ARCHON, params: { pr: 'abc' }, body: {} }, res);
+    assert.equal(res.statusCode, 400);
+    assert.equal(res.body.error.code, 'bad_pr');
+  });
+});
+
+// ===========================================================================
+// Layer 3 — structural gating: requireBuilder present + archon under the auditor
+// ===========================================================================
+
+await t('both routes are requireBuilder-gated and registered', async () => {
+  const router = buildGateApprovalsRouter();
+  for (const [method, p] of [['get', '/gate-approvals'], ['post', '/gate-approvals/:pr/approve']]) {
+    const layer = router.stack.find((l) => l.route && l.route.path === p && l.route.methods[method]);
+    assert.ok(layer, `${method.toUpperCase()} ${p} registered`);
+    const handles = layer.route.stack.map((s) => s.handle);
+    assert.ok(handles.includes(auth.requireBuilder), `${p} must be requireBuilder-gated`);
+    assert.ok(!handles.includes(auth.allowBoxScope), `${p} must NOT carry allowBoxScope`);
+  }
+});
+
+await t('route-rank auditor: both gate-approval routes classify to archon with no findings', async () => {
+  const res = checkRouteRanks();
+  const mine = res.routes.filter((r) => r.route.includes('gate-approvals'));
+  assert.equal(mine.length, 2, 'both routes seen by the auditor');
+  for (const r of mine) assert.equal(r.rank, 'archon', `${r.key} must classify archon`);
+  const myFindings = res.findings.filter((f) => (f.route || '').includes('gate-approvals'));
+  assert.deepEqual(myFindings, [], 'no auditor findings on the gate-approval routes');
+});
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail === 0 ? 0 : 1);

package/tests/gate_review.mjs

@@ -0,0 +1,152 @@
+// tests/gate_review.mjs
+//
+// Unit tests for the automatic gate-surface gatekeeper classifier (ADR 0058,
+// task 1139). classifyChanges is PURE (diff-as-data in, verdict out) so the whole
+// policy — including every red-team evasion the design workflow surfaced — is a
+// regression case here. DB-free / network-free → runs in the unit gate.
+//
+// Verdicts: pass (auto-merge) | needs_trust (Metic+ auto / else escalate) | escalate
+// (hard floor — rank-independent, always pings the owner).
+//
+// Run:  node tests/gate_review.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const gk = require('../scripts/gds/gate-review.js');
+const permPath = require('../src/bongos/permission-path-check.js');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL ${name}\n     ${e.message}`); }
+}
+
+// Build a classifyChanges call from a compact spec.
+//   files: [{path, mode?, deleted?}]   blobs: { 'base:path':..., 'head:path':... }
+function classify(files, blobs = {}, diffBytes = 0) {
+  const blobAt = (which, p) => (Object.prototype.hasOwnProperty.call(blobs, `${which}:${p}`) ? blobs[`${which}:${p}`] : null);
+  return gk.classifyChanges({ files: files.map((f) => ({ mode: '100644', deleted: false, ...f })), blobAt, diffBytes });
+}
+const verdictOf = (...a) => classify(...a).verdict;
+
+// --- PASS: no gate surface / pure-narrowing AUTO -------------------------------------
+test('no gate surface (game/art/docs) → pass', () => {
+  assert.equal(verdictOf([{ path: 'public/game/main.js' }, { path: 'docs/foo.md' }, { path: 'art/x.png' }]), 'pass');
+});
+test('adding a new test file → pass', () => {
+  assert.equal(verdictOf([{ path: 'tests/new_thing.mjs' }], { 'head:tests/new_thing.mjs': 'test(...)' }), 'pass');
+});
+test('run-unit-tests.js REMOVING from INTEGRATION (un-mute) → pass (AUTO)', () => {
+  const base = `const INTEGRATION = new Set(['a','b']);\nconst KNOWN_FAILING = new Set(['x']);\nconst Z=1;`;
+  const head = `const INTEGRATION = new Set(['a']);\nconst KNOWN_FAILING = new Set(['x']);\nconst Z=1;`;
+  const r = classify([{ path: 'scripts/gds/run-unit-tests.js' }], { 'base:scripts/gds/run-unit-tests.js': base, 'head:scripts/gds/run-unit-tests.js': head });
+  assert.equal(r.verdict, 'pass');
+  assert.deepEqual(r.autoPassed, ['scripts/gds/run-unit-tests.js']);
+});
+test('secrets-allowlist.txt REMOVING a line (narrow) → pass (AUTO)', () => {
+  const r = classify([{ path: '.husky/secrets-allowlist.txt' }], { 'base:.husky/secrets-allowlist.txt': 'aaa\nbbb\n', 'head:.husky/secrets-allowlist.txt': 'aaa\n' });
+  assert.equal(r.verdict, 'pass');
+});
+
+// --- NEEDS_TRUST: sensitive-but-routine (rank-trustable) -----------------------------
+test('new migration → needs_trust', () => assert.equal(verdictOf([{ path: 'migrations/120_thing.sql' }]), 'needs_trust'));
+test('package.json bump → needs_trust', () => assert.equal(verdictOf([{ path: 'package.json' }]), 'needs_trust'));
+test('a route file → needs_trust', () => assert.equal(verdictOf([{ path: 'src/bongos/routes/tasks.js' }]), 'needs_trust'));
+test('server.js → needs_trust', () => assert.equal(verdictOf([{ path: 'server.js' }]), 'needs_trust'));
+test('ship.js → needs_trust', () => assert.equal(verdictOf([{ path: 'scripts/gds/ship.js' }]), 'needs_trust'));
+test('db.js change OUTSIDE the rank-tier region → needs_trust', () => {
+  const base = `const REQUIRES_RANK_TIER = { foo: 1 };\nfunction q(){ return 1 }`;
+  const head = `const REQUIRES_RANK_TIER = { foo: 1 };\nfunction q(){ return 2 }`;
+  assert.equal(verdictOf([{ path: 'src/bongos/db.js' }], { 'base:src/bongos/db.js': base, 'head:src/bongos/db.js': head }), 'needs_trust');
+});
+test('deleting a test file → needs_trust', () => assert.equal(verdictOf([{ path: 'tests/route_rank.mjs', deleted: true }]), 'needs_trust'));
+test('shrinking a test file → needs_trust', () => {
+  assert.equal(verdictOf([{ path: 'tests/route_rank.mjs' }], { 'base:tests/route_rank.mjs': 'x'.repeat(500), 'head:tests/route_rank.mjs': 'x'.repeat(50) }), 'needs_trust');
+});
+
+// --- ESCALATE: HARD FLOOR (rank-independent) -----------------------------------------
+for (const p of [
+  'scripts/gds/gate-review.js', 'src/bongos/permission-path-check.js', 'src/bongos/auth.js',
+  'src/bongos/route-rank-check.js', 'modules/grading/grader.js', 'modules/grading/grader-workers/narc.js',
+  'scripts/gds/main-audit.js', 'scripts/migrate.sh', 'scripts/deploy/deploy-prod.sh',
+  'config/deploy.json', 'infra/branch-protection.json', '.github/workflows/gate-review.yml',
+  'CODEOWNERS', '.husky/pre-push', '.claude/hooks/stop-sound.js', '.claude/settings.json',
+]) {
+  test(`hard floor: ${p} → escalate`, () => assert.equal(verdictOf([{ path: p }]), 'escalate'));
+}
+test('db.js with the rank-tier region CHANGED → escalate', () => {
+  const base = `const REQUIRES_RANK_TIER = { foo: 1 };\nfunction q(){}`;
+  const head = `const REQUIRES_RANK_TIER = { foo: 4, bar: 1 };\nfunction q(){}`;
+  assert.equal(verdictOf([{ path: 'src/bongos/db.js' }], { 'base:src/bongos/db.js': base, 'head:src/bongos/db.js': head }), 'escalate');
+});
+
+// --- ESCALATE: red-team evasions -----------------------------------------------------
+test('Hole(mute): run-unit-tests.js ADDING to KNOWN_FAILING → escalate (AUTO cert fails → floor)', () => {
+  const base = `const INTEGRATION = new Set(['a']);\nconst KNOWN_FAILING = new Set(['x']);`;
+  const head = `const INTEGRATION = new Set(['a']);\nconst KNOWN_FAILING = new Set(['x','grader_panel']);`;
+  assert.equal(verdictOf([{ path: 'scripts/gds/run-unit-tests.js' }], { 'base:scripts/gds/run-unit-tests.js': base, 'head:scripts/gds/run-unit-tests.js': head }), 'escalate');
+});
+test('Hole(mute): run-unit-tests.js non-set code changed → escalate', () => {
+  const base = `const INTEGRATION = new Set(['a']);\nconst KNOWN_FAILING = new Set([]);\nconst TIMEOUT=90000;`;
+  const head = `const INTEGRATION = new Set(['a']);\nconst KNOWN_FAILING = new Set([]);\nconst TIMEOUT=1;`;
+  assert.equal(verdictOf([{ path: 'scripts/gds/run-unit-tests.js' }], { 'base:scripts/gds/run-unit-tests.js': base, 'head:scripts/gds/run-unit-tests.js': head }), 'escalate');
+});
+test('Hole(allowlist): secrets-allowlist.txt ADDING a broadening line → escalate', () => {
+  assert.equal(verdictOf([{ path: '.husky/secrets-allowlist.txt' }], { 'base:.husky/secrets-allowlist.txt': 'aaa\n', 'head:.husky/secrets-allowlist.txt': 'aaa\nLEAKED_KEY=.*\n' }), 'escalate');
+});
+test('Hole8: a symlink in the diff → escalate (alias evasion)', () => {
+  assert.equal(verdictOf([{ path: 'src/bongos/routes/x.js', mode: '120000' }]), 'escalate');
+});
+test('Hole6/8: a non-ASCII/homoglyph path → escalate', () => {
+  assert.equal(verdictOf([{ path: 'src/bongos/аuth.js' /* cyrillic a */ }]), 'escalate');
+});
+test('Hole10: oversize diff → escalate', () => {
+  assert.equal(verdictOf([{ path: 'public/game/main.js' }], {}, 9 * 1024 * 1024), 'escalate');
+});
+test('Hole2: editing gate-review.yml (self-neuter) → escalate', () => {
+  assert.equal(verdictOf([{ path: '.github/workflows/gate-review.yml' }]), 'escalate');
+});
+test('Hole4: adding a new middleware + editing routes.js → escalate (auth.js floor) / needs_trust (routes)', () => {
+  // routes.js is needs_trust; but pairing with a hard-floor file makes the PR escalate.
+  assert.equal(verdictOf([{ path: 'src/bongos/routes.js' }, { path: 'src/bongos/auth.js' }]), 'escalate');
+});
+
+// --- DRIFT GUARD: no PROTECTED_GLOBS entry is silently un-routed (never pass) ---------
+test('drift guard: every PROTECTED_GLOBS entry routes to escalate or needs_trust (never pass)', () => {
+  for (const glob of permPath.PROTECTED_GLOBS) {
+    // Synthesize a representative path under each glob.
+    const sample = glob.endsWith('/') ? `${glob}__sample__.js` : glob;
+    // db.js needs blobs to classify; give it a no-op (region unchanged) → needs_trust (still not pass).
+    const blobs = sample === 'src/bongos/db.js'
+      ? { 'base:src/bongos/db.js': 'const REQUIRES_RANK_TIER = {};\nx', 'head:src/bongos/db.js': 'const REQUIRES_RANK_TIER = {};\ny' }
+      : {};
+    const v = verdictOf([{ path: sample }], blobs);
+    assert.notEqual(v, 'pass', `PROTECTED glob ${glob} (sample ${sample}) classified as PASS — gate-surface leak`);
+  }
+});
+test('drift guard: every HARD_FLOOR glob is also covered by PROTECTED_GLOBS (sub-Metic floor protects the gate machinery)', () => {
+  for (const g of gk.HARD_FLOOR_GLOBS) {
+    // a floor glob must be matched by SOME protected glob (subtree-aware): a file under it is protected.
+    const sample = g.endsWith('/') ? `${g}__s__` : g;
+    assert.equal(permPath.matchProtected([sample]).length > 0, true, `hard-floor ${g} is not in PROTECTED_GLOBS`);
+  }
+});
+
+// --- resolveAction: rank clears needs_trust; ONLY an owner review clears the hard floor (task 1142) ---
+const RA = (verdict, trusted, ownerApproved) => gk.resolveAction({ verdict, trusted, ownerApproved });
+test('resolveAction: pass → pass regardless of trust', () => {
+  assert.equal(RA('pass', false, false), 'pass');
+});
+test('resolveAction: needs_trust + Metic+ attestation → pass', () => assert.equal(RA('needs_trust', true, false), 'pass'));
+test('resolveAction: needs_trust + untrusted + no approval → block', () => assert.equal(RA('needs_trust', false, false), 'block'));
+test('resolveAction: needs_trust + owner approval (untrusted) → pass', () => assert.equal(RA('needs_trust', false, true), 'pass'));
+test('resolveAction: escalate + trusted but NOT owner-approved → block (rank never clears the hard floor)', () => {
+  assert.equal(RA('escalate', true, false), 'block');
+});
+test('resolveAction: escalate + owner approval → pass (only the owner clears the floor)', () => assert.equal(RA('escalate', false, true), 'pass'));
+test('resolveAction: escalate + nothing → block', () => assert.equal(RA('escalate', false, false), 'block'));
+
+console.log(`\ngate-review (task 1139) tests: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);