@bongos/core 1.17.0

package/src/bongos/route-rank-check.js

@@ -0,0 +1,420 @@
+// Deterministic route-rank invariant check (MAS — #475 / C7).
+//
+// Moved into the grader from the retired rank-check-audit nightly cron. It now
+// runs on every ship (the grader gate) and mid-flight (conductor-dispatch
+// reuses the same machinery) — strictly more often than a nightly cron, and
+// in-context, which is the whole point of C7's "a periodic auditor confirms no
+// privileged route is missing a rank check."
+//
+// It asserts the invariant DIRECTLY — every route declared in src/bongos/routes/
+// must classify to a KNOWN rank — instead of diffing against a frozen snapshot
+// (the old canonical-routes.json approach, which cried false drift whenever the
+// route set legitimately grew). Classification is STRUCTURAL: a route is gated
+// when its middleware chain carries requireRank/requireBuilder, OR it bears an
+// explicit `rank:` annotation. So an intentionally-public route is fine — it
+// just has to SAY so. A route the parser cannot classify ('unknown') means the
+// system can't verify it's protected, which is a finding:
+//   - write method (POST/PUT/PATCH/DELETE) → 'blocker' → hard FAIL on its own.
+//   - read method (GET) → 'major' → 'concerns'; the Hacker adjudicates intent.
+//
+// The deterministic check owns "is there a gate at all"; the Hacker (fed these
+// findings as input) owns "is the gate level correct / intentional."
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveCoreRoot } = require('../instance-config');
+
+const ROUTES_DIR = path.resolve(__dirname, 'routes');
+// Modules contribute routes too (ADR 0083 / BV1.R44): modules/<key>/routes/*.js.
+// modules/ ships WITH the core package (ADR 0108 §1); resolveCoreRoot() returns
+// the repo root today, so this is byte-identical. modules/ is absent until the
+// first module is moved in (BV1.R43+) → discovery is a no-op until then.
+const MODULES_DIR = path.join(resolveCoreRoot(), 'modules');
+// A changed-file path that warrants running the pre-pass: a core route file OR a
+// module route file (so adding/editing a module route also triggers the pre-pass).
+const ROUTE_FILE_RE = /^(?:src\/bongos\/routes\/|modules\/[^/]+\/routes\/).+\.js$/;
+// 'bfg-principal' is stricter than any human rank: the BFG service-principal
+// identity gate (auth.requireBfgPrincipal, ADR 0026 §6C) — NOT a rank. Listed
+// here so the cross-builder memory WRITE route classifies to a known, gated
+// rank (and a future edit that drops the principal gate is mechanically visible
+// to this auditor, not only to the bfg_write unit test).
+const KNOWN_RANKS = new Set(['public', 'any-builder', 'metic+archon', 'archon', 'bfg-principal']);
+const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+const SPECIALTY = 'deterministic: every src/bongos/routes/ route must classify to a known rank (ADR 0016)';
+
+// Expected-rank allowlist for KNOWN privileged routes (#999, red-team residual).
+// The base invariant above only checks a route classifies to SOME known rank —
+// so an accidental DOWNGRADE (an Archon-only route silently dropped to
+// requireBuilder) still classifies as a *known* rank ('any-builder') and passes
+// silently. This pins the exact expected rank for the routes whose downgrade
+// would be a real authority breach (rank/status mutation, session revocation,
+// the forensic audit log, the BFG cross-builder memory write, the Archon
+// override-decide path). If the live route classifies to anything OTHER than
+// the value here, the auditor emits a 'blocker' finding (hard FAIL) — a
+// deterministic alarm rather than a passing test.
+//
+// Smallest-useful scope (deliberately a curated allowlist, NOT every archon
+// route): keys are `METHOD route` exactly as classifyText emits them. Adding a
+// new privileged route here is the cost of admission to deterministic
+// downgrade-protection; routes not listed still get the base "must classify"
+// check. A key present here that no longer exists in the route set is itself a
+// finding (a privileged route was removed/renamed without updating this pin).
+const EXPECTED_RANKS = {
+  // builder authority — rank + lifecycle status mutation
+  'PATCH /builders/:id/rank': 'archon',
+  'PATCH /builders/:id/status': 'archon',
+  // session revocation (kill another builder's / all sessions)
+  'POST /auth/revoke': 'archon',
+  'POST /auth/revoke-all': 'archon',
+  // forensic surfaces
+  'GET /audit-log': 'archon',
+  'GET /builders/roster': 'archon',
+  // deliberately any-builder (task 1877) — the invite-picker roster (Goals
+  // invite control, task 1762) needs every active builder's identity, not just
+  // /leaderboard's top-100-by-credits window. Pinned so an accidental
+  // requireRank upgrade later would silently break the invite dropdown instead
+  // of failing loud.
+  'GET /builders/directory': 'any-builder',
+  // (the lifecycle fleet pins — task authoring/promotion/abandonment, override
+  //  adjudication, polymorphic dependency edges, goal tier + ask-to-widen,
+  //  criterion confirmation, and gate-approvals — moved to MODULE_EXPECTED_RANKS
+  //  ['lifecycle'] below in BV1.R86. They live in the lifecycle module now
+  //  (modules/lifecycle/routes/…), so they're verified only when that module is in
+  //  scope, not unconditionally from this core list — the pins follow the routes,
+  //  the dev-box precedent.)
+  // (dev-box fleet pins likewise live in MODULE_EXPECTED_RANKS below — BV1.R43.)
+  // security engagement docs — exploit-detail report store (task 991). Pinned
+  // because a silent downgrade here leaks the attacker cookbook below the
+  // Archon line. (security-the-PROPERTY stays kernel — routes/security.js.)
+  'GET /security/docs': 'archon',
+  'GET /security/docs/:slug': 'archon',
+  'POST /security/docs': 'archon',
+};
+
+// Module-scoped privileged-rank pins: a privileged route that lives in a FEATURE
+// MODULE (modules/<key>/routes/…), pinned like EXPECTED_RANKS but verified ONLY
+// when that module is in scope (its routes were discovered in this scan). So an
+// instance that doesn't ship the module — or a hermetic test isolating a
+// different module — never trips a false "vanished" alarm, while a real rank
+// downgrade or a removal IS still caught wherever the module is present. (dev-box's
+// box-fleet routes moved here from EXPECTED_RANKS in BV1.R43 / task 1412 — the pins
+// follow the routes; the intent is unchanged: closing/blocking another builder's
+// paid infra, and reading the fleet/cost roster, stay archon-only.)
+const MODULE_EXPECTED_RANKS = {
+  'dev-box': {
+    'GET /boxes': 'archon',
+    'GET /boxes/cost-ledger': 'archon',
+    'POST /boxes/:builderId/close': 'archon',
+    'PATCH /boxes/:builderId/block': 'archon',
+  },
+  // The lifecycle module's privileged routes (carved BV1.R86 — the pins follow the
+  // routes from EXPECTED_RANKS). Verified only when the lifecycle module is in scope.
+  lifecycle: {
+    // task authoring / promotion / abandonment. Create + promote re-ranked
+    // Archon→Metic+ (ADR 0090): a Metic who can triage ideas may also seed + shape
+    // tasks. Abandon (terminal scope removal) stays Archon.
+    'POST /tasks': 'metic+archon',
+    'POST /tasks/:id/promote': 'metic+archon',
+    'POST /tasks/:id/abandon': 'archon',
+    // override-request adjudication (lands credit + ship attribution).
+    'GET /override-requests': 'archon',
+    'POST /override-requests/:id/decide': 'archon',
+    // polymorphic dependency edges (ADR 0086 §5) — authoring a cross-tier
+    // dependency reshapes execution order + feeds the claim gate; both pinned.
+    'POST /dependencies': 'archon',
+    'DELETE /dependencies': 'archon',
+    // goal tier (ADR 0086 §3) — CREATE Metic+ (Archon for a protected-module scope,
+    // enforced in-handler); member admission is the protected-scope approval grant.
+    'POST /goals': 'metic+archon',
+    // member invite (task 1762) — DELIBERATELY 'any-builder': widened from
+    // Archon-only so a goal's own owner/manager can invite without an Archon in
+    // the loop (mirrors authorizeGoalManagement, like the owner/manager routes
+    // below). The wall is in-handler (owner | manager | Archon), with a protected-
+    // scope goal staying Archon-only (actor AND Metic+ target) inside the handler.
+    'POST /goals/:id/members': 'any-builder',
+    // per-version priority reorder (task 1760) — an owner decision, Archon-only;
+    // never self-granted by a goal's own member/manager authority.
+    'POST /goals/reorder': 'archon',
+    // ask-to-widen (ADR 0086 §4) — widening a goal's scope_modules; never self-granted.
+    'POST /goals/:id/scope': 'metic+archon',
+    // goal lifecycle disposition (ADR 0086 §6) — a rank drop here would let any
+    // builder archive/resurrect a shared workspace out from under its members.
+    'POST /goals/:id/archive': 'metic+archon',
+    'POST /goals/:id/reopen': 'metic+archon',
+    // The bounded task-authoring KEYSTONE + self-service membership (ADR 0086 §3,
+    // BV1.R60/R61). These are DELIBERATELY 'any-builder': the wall is the IN-HANDLER
+    // scope/protected/rank-floor gate (authorizeGoalTaskCreate + goal-scope-check),
+    // NOT a route-rank middleware — that is the whole maneuverability grant. Pinning
+    // them makes a drift a red build in the direction the base "unknown-write"
+    // invariant misses: an accidental requireRank that would silently LOCK sub-Metics
+    // OUT of the grant, or any re-gating of the authenticated contract. (Removing the
+    // gate entirely still trips the base ungated-write blocker on its own.)
+    'POST /goals/:id/tasks': 'any-builder',
+    'POST /goals/:id/join': 'any-builder',
+    'POST /goals/:id/leave': 'any-builder',
+    // goal owner/manager self-management (task 1735) — like the authoring
+    // keystone above, DELIBERATELY 'any-builder': the wall is the in-handler
+    // (owner | manager | Archon) gate + the atomic owner-demotion guard in the
+    // UPDATE, not a rank middleware. Transfer is (owner | Archon) in-handler,
+    // with a Metic+ floor on the new owner. Pinning catches both an accidental
+    // requireRank re-gate and a gate removal.
+    'PATCH /goals/:id/members/:builderId': 'any-builder',
+    'POST /goals/:id/transfer': 'any-builder',
+    // conflict resolution (task 1736) — same shape: the wall is the in-handler
+    // (owner | manager | Archon) gate + per-action goal containment.
+    'POST /goals/:id/conflicts/resolve': 'any-builder',
+    // private goals: visibility + the invite/join-request queue (task 1952 /
+    // ADR 0112) — all DELIBERATELY 'any-builder', the walls are in-handler:
+    //   visibility + invite + request-respond → owner|manager|Archon
+    //     (authorizeGoalManagement); invitation-respond → the invited builder
+    //     only (authorizeInvitationResponse); request-create → any builder for a
+    //     private/protected goal (authorizeCreateJoinRequest); inbox → own-scoped.
+    // Pinning catches an accidental requireRank re-gate that would lock builders
+    // out of asking/accepting, and any gate removal.
+    'GET /goals/inbox': 'any-builder',
+    'PATCH /goals/:id/visibility': 'any-builder',
+    'POST /goals/:id/requests': 'any-builder',
+    'POST /goals/:id/requests/:reqId/respond': 'any-builder',
+    'POST /goals/:id/invitations': 'any-builder',
+    'POST /goals/:id/invitations/:reqId/respond': 'any-builder',
+    // criterion confirmation + goal auto-achieve (ADR 0086 §6) — the planner's close loop.
+    'POST /done-when/:criterionId/satisfy': 'metic+archon',
+    // runtime criterion create (ADR 0105 gap fix, task 1874) — scope-truth write, Archon-only.
+    'POST /versions/:id/done-when': 'archon',
+    // gate-surface PR approval from the hall (task 1179, ADR 0058 amendment) — the
+    // approve route clears the gate-review hard floor; the list route exposes gate internals.
+    'GET /gate-approvals': 'archon',
+    'POST /gate-approvals/:pr/approve': 'archon',
+  },
+};
+
+// Classify one route's rank from the source lines and the declaration index.
+//   1. The middleware chain on the declaration line + next 20 lines (captures
+//      multi-line declarations) — requireRank/requireBuilder is authoritative.
+//   2. Otherwise a `rank:` annotation anywhere in the CONTIGUOUS comment block
+//      immediately above the declaration. Scanning the whole block (not a fixed
+//      5-line window) is the fix for routes like GET /public/repo-info, whose
+//      annotation sits atop a 6-line comment — just out of the old window.
+//   3. Neither → 'unknown'. An annotation whose value isn't a known rank (typo)
+//      is likewise 'unknown' — that surfaces the typo rather than trusting it.
+function classifyRank(lines, i) {
+  const window = lines.slice(i, i + 20).join('\n');
+  // Only the route's own MIDDLEWARE LIST decides its rank — not its handler body.
+  // The middleware are the args before the handler function; the handler opens
+  // with an arrow-and-brace (`=> {`). Truncating there keeps multi-line-declaration
+  // support (middleware can span several lines, all before the handler) while
+  // preventing a nested lower-rank guard call *inside* the handler body from
+  // falsely downgrading the route's recorded rank. Matching `=> {` specifically
+  // (not any `=>`) avoids cutting at an inline-arrow middleware like
+  // `rateLimit({ key: (req) => req.ip })`. If there's no `=> {` in the window
+  // (e.g. a `function` handler), fall back to the full window — prior behaviour.
+  const handlerAt = window.search(/=>\s*\{/);
+  const tail = handlerAt === -1 ? window : window.slice(0, handlerAt);
+  // Accept BOTH prefixes: core routes gate via `auth.requireRank(...)`; a module
+  // route reaches the SAME guards through the published doorway as `api.requireRank(...)`
+  // (src/module-api re-exports requireRank/requireBuilder/requireBfgPrincipal). Without
+  // the `api.` arm a correctly-gated module write route would mis-classify as 'unknown'
+  // → a false blocker, and the moved dev-box routes (BV1.R43/M07) would never pass.
+  if (/(?:auth|api)\.requireRank\(\s*['"]xenos['"]/.test(tail)) return 'any-builder';
+  if (/(?:auth|api)\.requireRank\(\s*['"]metic['"]\s*,\s*['"]archon['"]\s*\)/.test(tail)) return 'metic+archon';
+  if (/(?:auth|api)\.requireRank\(\s*['"]archon['"]\s*\)/.test(tail)) return 'archon';
+  // Matched BEFORE the requireBuilder branch in THIS classifier's if-chain (not
+  // a statement about middleware execution order — the actual route chain runs
+  // requireBuilder → requireBfgPrincipal). The BFG write route carries both;
+  // requireBuilder authenticates, requireBfgPrincipal narrows to the one service
+  // principal, and the principal gate is the load-bearing one we want recorded.
+  if (/(?:auth|api)\.requireBfgPrincipal/.test(tail)) return 'bfg-principal';
+  if (/(?:auth|api)\.requireBuilder/.test(tail)) return 'any-builder';
+
+  for (let j = i - 1; j >= 0; j--) {
+    const line = lines[j];
+    const isComment = /^\s*\/\//.test(line);
+    const isBlank = line.trim() === '';
+    if (!isComment && !isBlank) break; // hit code — stop before the prior route
+    if (isComment) {
+      // token shape covers public | archon | any-builder | metic+archon and
+      // stops at the first space / em-dash so trailing prose isn't captured.
+      const c = /\brank:\s*([a-z]+(?:[+-][a-z]+)*)/i.exec(line);
+      if (c) {
+        const v = c[1].toLowerCase();
+        return KNOWN_RANKS.has(v) ? v : 'unknown';
+      }
+    }
+  }
+  return 'unknown';
+}
+
+// Parse route declarations + ranks from a route file's source text. Pure
+// (no fs) so it's trivially testable. Returns [{ method, route, key, rank }].
+function classifyText(text) {
+  const lines = String(text).split('\n');
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^\s*router\.(get|post|patch|put|delete)\s*\(\s*['"]([^'"]+)['"]/.exec(lines[i]);
+    if (!m) continue;
+    const method = m[1].toUpperCase();
+    const route = m[2];
+    out.push({ method, route, key: `${method} ${route}`, rank: classifyRank(lines, i) });
+  }
+  return out;
+}
+
+// Discover every route file the invariant must cover: the core router files
+// (src/bongos/routes/*.js) PLUS each module's contributed routes (modules/*/routes/*.js,
+// ADR 0083 / BV1.R44). Stable order (core first, then modules by key). modules/ is
+// absent until a module is moved in → modules contribute nothing and the result
+// equals the core-only set (byte-identical). Pure-ish (fs reads, no app state).
+function discoverRouteFiles({ routesDir = ROUTES_DIR, modulesDir = MODULES_DIR } = {}) {
+  const out = [];
+  for (const f of fs.readdirSync(routesDir).filter((f) => f.endsWith('.js')).sort()) {
+    out.push({ abs: path.join(routesDir, f), rel: `src/bongos/routes/${f}` });
+  }
+  let moduleKeys = [];
+  try {
+    moduleKeys = fs.readdirSync(modulesDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory()).map((d) => d.name).sort();
+  } catch (e) { if (e.code !== 'ENOENT') throw e; } // no modules/ dir → nothing to add
+  for (const key of moduleKeys) {
+    const rdir = path.join(modulesDir, key, 'routes');
+    let files;
+    try { files = fs.readdirSync(rdir).filter((f) => f.endsWith('.js')).sort(); }
+    catch (e) { if (e.code === 'ENOENT') continue; throw e; } // a module without a routes/ dir
+    for (const f of files) out.push({ abs: path.join(rdir, f), rel: `modules/${key}/routes/${f}` });
+  }
+  return out;
+}
+
+// Walk every route file (core + modules) and assert the invariant. Returns:
+//   { ok, hardFail, routeCount, routes[], findings[] }
+// findings[]: { severity, file, route, method, rank, summary }
+function checkRouteRanks({ routesDir = ROUTES_DIR, modulesDir } = {}) {
+  // modulesDir DERIVES from routesDir by default so a grader pointed at a worktree's
+  // routes scans THAT tree's modules (routes -> gds -> src -> root -> modules); a
+  // caller (or a hermetic test) may pass modulesDir explicitly to override.
+  if (modulesDir === undefined) modulesDir = path.resolve(routesDir, '..', '..', '..', 'modules');
+  const routes = [];
+  for (const { abs, rel } of discoverRouteFiles({ routesDir, modulesDir })) {
+    for (const r of classifyText(fs.readFileSync(abs, 'utf8'))) {
+      routes.push({ ...r, file: rel });
+    }
+  }
+
+  const findings = [];
+  for (const r of routes) {
+    if (r.rank !== 'unknown') continue;
+    const isWrite = WRITE_METHODS.has(r.method);
+    findings.push({
+      severity: isWrite ? 'blocker' : 'major',
+      file: r.file,
+      route: r.key,
+      method: r.method,
+      rank: r.rank,
+      summary: `${r.key} (${r.file}) has no detectable rank gate — neither a requireRank/requireBuilder middleware nor a \`rank:\` annotation. `
+        + (isWrite
+          ? 'A write route with no verifiable gate is a hard fail (ADR 0016): add the middleware or, if it is genuinely public, a `rank: public` annotation.'
+          : 'Confirm it is intentionally public and add a `rank: public` annotation so the gate is verifiable.'),
+    });
+  }
+
+  // #999 — EXACT-rank pin on known privileged routes. A downgrade (e.g. an
+  // archon route silently dropped to any-builder) trips a 'blocker' here even
+  // though the route still classifies to a *known* rank, which the loop above
+  // alone would wave through.
+  const byKey = new Map();
+  for (const r of routes) {
+    // First declaration wins (Express routes are first-match); a duplicate key
+    // is unusual but we pin against the one a request would actually hit.
+    if (!byKey.has(r.key)) byKey.set(r.key, r);
+  }
+  // The pins to verify = the always-on core pins + each IN-SCOPE module's pins. A
+  // module is in scope when at least one of its route files was discovered in this
+  // scan (modules/<key>/…); pins for an out-of-scope module are skipped so a
+  // not-shipped optional module never trips a false "vanished" finding (BV1.R43).
+  const scopedModules = new Set();
+  for (const r of routes) {
+    const mm = /^modules\/([^/]+)\//.exec(r.file || '');
+    if (mm) scopedModules.add(mm[1]);
+  }
+  const effectivePins = { ...EXPECTED_RANKS };
+  for (const [mod, pins] of Object.entries(MODULE_EXPECTED_RANKS)) {
+    if (scopedModules.has(mod)) Object.assign(effectivePins, pins);
+  }
+  for (const [key, expected] of Object.entries(effectivePins)) {
+    const r = byKey.get(key);
+    if (!r) {
+      findings.push({
+        severity: 'blocker',
+        file: '(route-rank-check EXPECTED_RANKS)',
+        route: key,
+        method: key.split(' ')[0],
+        rank: '(missing)',
+        summary: `Privileged route ${key} is pinned to expect rank '${expected}' but is no longer present under src/bongos/routes/. `
+          + 'If it was intentionally removed/renamed, drop or update its entry in EXPECTED_RANKS; otherwise a protected route vanished.',
+      });
+      continue;
+    }
+    if (r.rank !== expected) {
+      findings.push({
+        severity: 'blocker',
+        file: r.file,
+        route: r.key,
+        method: r.method,
+        rank: r.rank,
+        summary: `Privileged route ${r.key} (${r.file}) classifies as '${r.rank}' but is pinned to '${expected}'. `
+          + 'This is a rank DOWNGRADE/CHANGE on a route that guards authority (ADR 0016). '
+          + 'If the change is intentional, update EXPECTED_RANKS in route-rank-check.js in the same commit; otherwise restore the gate.',
+      });
+    }
+  }
+
+  return {
+    ok: findings.length === 0,
+    hardFail: findings.some((f) => f.severity === 'blocker'),
+    routeCount: routes.length,
+    routes,
+    findings,
+  };
+}
+
+// Shape the check as a panel WorkerResult so aggregatePanel's existing
+// any-fail / any-concerns gate handles it with NO gate-logic change. Empty
+// scores → contributes nothing to the score medians; confidence=1 because a
+// deterministic check is certain.
+function toWorkerResult(result) {
+  const blockers = result.findings.filter((f) => f.severity === 'blocker').length;
+  const verdict = result.hardFail ? 'fail' : (result.findings.length > 0 ? 'concerns' : 'pass');
+  const header = verdict === 'fail'
+    ? `Route-Rank — FAIL (${blockers} ungated write route(s) of ${result.routeCount} routes)`
+    : verdict === 'concerns'
+      ? `Route-Rank — CONCERNS (${result.findings.length} unclassified read route(s) of ${result.routeCount}; the Hacker adjudicates intent)`
+      : `Route-Rank — PASS (all ${result.routeCount} routes classify to a known rank)`;
+  const body = result.findings.map((f) => `  [${f.severity}] ${f.route} — ${f.summary}`).join('\n');
+  return {
+    kind: 'route-rank',
+    name: 'Route-Rank Check',
+    specialty: SPECIALTY,
+    verdict,
+    scores: {},
+    issues: result.findings.map((f) => ({ severity: f.severity, file: f.file, summary: f.summary })),
+    notes_md: body ? `${header}\n${body}` : header,
+    confidence: 1,
+    model: 'deterministic',
+    run_ms: 0,
+    error: null,
+  };
+}
+
+module.exports = {
+  ROUTE_FILE_RE,
+  MODULES_DIR,
+  KNOWN_RANKS,
+  WRITE_METHODS,
+  EXPECTED_RANKS,
+  MODULE_EXPECTED_RANKS,
+  SPECIALTY,
+  classifyRank,
+  classifyText,
+  discoverRouteFiles,
+  checkRouteRanks,
+  toWorkerResult,
+};

package/src/bongos/routes/CLAUDE.md

@@ -0,0 +1,43 @@
+# src/bongos/routes/ — GDS HTTP surface (agent notes)
+
+> Nested CLAUDE.md — loads on demand when you work here. Root [CLAUDE.md](../../../CLAUDE.md) is the index. See [ADR 0061](../../../docs/adr/<redacted>.md) for why these exist.
+
+**Purpose.** Express route handlers for the GDS API, all mounted under `/api/gds/*` in the same Node process as the game server. One file per resource group; each exports a `buildXRouter()` factory that returns its own `express.Router()`. The thin mounter is [`../routes.js`](../routes.js) — adding a feature = new file here + one `router.use(buildXRouter())` line there (kept conflict-free across parallel branches). `routes.js` also wires the global 64 KB JSON parser (skipped for `/memory/sync`, `/sessions`, `/tasks/:id/publish-branch` — they mount their own larger parser), the audit-log finish hook, and the rate limiter — all BEFORE the feature routers.
+
+**Conventions (read before adding a route).**
+- Auth/rank: middleware from [`../auth.js`](../auth.js) — `auth.requireBuilder` (valid session) then `auth.requireRank('metic','archon')` / `auth.requireRank('archon')`. **The server enforces rank per-request, no caching** ([ADR 0016](../../../docs/adr/<redacted>.md)). A `// rank:` comment sits above most handlers — it feeds the **generated** OpenAPI spec + [`docs/api-reference.md`](../../../docs/api-reference.md) (via `scripts/gds/gen-api-docs.js`; do NOT hand-maintain a mirror — it regenerates on ship, task 1918/[ADR 0109](../../../docs/adr/<redacted>.md)). `auth.allowBoxScope` opens a route to the deny-by-default box token (box.js bootstrap only).
+- Public surface: `public.js` + `analytics.js` are unauthenticated read-only (status page reads cross-origin) — wrap with `corsPublicGet(scope)` from `_helpers.js`; no secrets.
+- Validation: [`_helpers.js`](./_helpers.js) — `validateOrRespond(req,res,schema)` (opt-in, never rejects extras, structured 400), `LIMITS` (TITLE/DESCRIPTION/NOTES caps), `parseId`, `asyncHandler(tag, fn)`.
+- GitHub-rendered output only: the PR title/body built in `tasks.js` de-hashes bare `#NNN` (so it doesn't 404-autolink to GitHub issues) via the local `deHashRefs` helper — which mirrors ship.js's `sanitizeGitHubRefs` (not requirable here). Mirror `deHashRefs`; don't hand-roll. DB-row prose (tasks/inbox/memory) is stored as-is — sanitization happens only at the GitHub boundary.
+
+**Route groups.**
+- Work-tracking: `tasks.js`, `claims.js`, `versions.js`, `done-when.js` — the task lifecycle, claims, versions, done-when criteria.
+- Auth/identity: `auth.js`, `me.js`, `sessions.js` — Device/web/app-pair flows, self profile/prefs, session digests. (Admission gating — `access-requests.js` — carved to [`modules/onboarding/`](../../../modules/onboarding/CLAUDE.md) at R81; the loader mounts it.)
+- Builder ops: `builders.js`, `cost.js`, `leaderboard.js`, `memory.js`, `learnings.js` — builder records/budget, cost log, rankings, BFG-scoped memory, learnings.
+- Dev-box: `box.js` — provision/wake/close, SSH keys, terminal/sandbox tunnels, server-mediated branch publish.
+- Social/data: `discord.js`, `inbox.js`, `blockers.js`, `analytics.js`, `audit-log.js` — idea inbox, blockers, Discord link, analytics, Archon audit trail.
+- GDS-V4 / security: `search.js` (recall), `gate-approvals.js` (Archon gate PRs), `security.js` (red-team reports + Archon-served docs).
+- Util: `healthz.js`, `public.js`, `optimizer.js`, `bug-attachments.js`.
+
+**Gotchas / invariants.**
+- `tasks.js` (~79 KB), `box.js`, `auth.js`, `memory.js` are large — grep `router.(get|post|...)(` for the route, don't read end-to-end.
+- Rank gates are load-bearing (trust boundary). Default a write to `requireRank('archon')` unless it's deliberately broader; never loosen one without the permissions doc + an ADR.
+- Mount order: `public.js` is mounted LAST in routes.js; keep new files' prefixes from shadowing it.
+
+<!-- BEGIN GENERATED REPO-MAP (scripts/gds/gen-repo-map.js — do not hand-edit) -->
+**Symbol skeleton (generated from the code — do not hand-edit; refresh: `node scripts/gds/gen-repo-map.js`).** Exported signatures, most-referenced first. The interpretive notes above are hand-written; this factual list is regenerated on deploy so it can't drift ([ADR 0063](../../../docs/adr/<redacted>.md)).
+
+- `_helpers.js` — `validateOrRespond(req, res, schema, opts = {})`, `parseId(req, res, { param = 'id', code = 'bad_id', positiveInt = false } = {})`, `LIMITS`, `validate(body, schema, { strict = false, query = false } = {})`, `asyncHandler(tag, handler, { message = true, errorCode = 'server_error' } = {})`, `publicOrigin(req)`, `pageMeta(limit, offset, total)`, `parsePagination(req, { defaultLimit = PAGINATION.DEFAULT_LIMIT, maxLimit = PAGINATION.MAX_LIMIT } = {})`, `corsPublicGet(scope)`, `parseCookie(req, name)` _(+2 more)_
+- `auth.js` — `renderAuthErrorPage(heading, detail, opts = {})`, `sessionCookieDomainOpts(req)`, `safeReturnTo(raw)`, `reqHost(req)`
+- `backup.js` — `latestDump()`
+- `builders.js` — `boxHasEverConnected(builderId)`, `discordIsLinked(builderId)`, `displayRank(rank)`, `<redacted>({ displayName, direction, newRank })`, `fireDiscordBroadcast(text)`
+- `instance.js` — `MANIFEST_SCHEMA`, `buildInstanceManifest({)`, `AUTH_METHODS`
+- `live.js` — `buildLiveRouter()`, `frameEvent(event, data)`, `MAX_CONN_PER_IP`, `streamLive(req, res, deps = {})`
+- `llm-cache.js` — `badKey(res)`, `knownTaskType(t)`, `clampedCost(raw)`
+- `me.js` — `boxHasEverConnected(builderId)`, `artSharedKeyConfigured()`, `discordIsLinked(builderId)`
+- `modules.js` — `listModules()`
+- `public.js` — `projectPublicTask(task)`, `projectPublicBlocker(blocker)`, `projectPublicIdea(idea)`, `recentShippedWindow(rawDays)`
+- `security.js` — `adrPath()`, `readFullAdr()`
+<!-- END GENERATED REPO-MAP -->
+
+**See also.** [ADR 0016](../../../docs/adr/<redacted>.md) (trust boundary), [`docs/api-reference.md`](../../../docs/api-reference.md) (generated per-endpoint reference; `/docs` renders it), [`docs/canonical-permissions.md`](../../../docs/canonical-permissions.md) (rank ladder), [`../routes.js`](../routes.js) (mounter), [`../auth.js`](../auth.js).