@bongos/core 1.18.18 → 1.19.2

package/docs/api/openapi.json

@@ -101,6 +101,10 @@
       "name": "goals",
       "description": "Endpoints under `/api/bongos/goals`."
     },
+    {
+      "name": "governance",
+      "description": "Endpoints under `/api/bongos/governance`."
+    },
     {
       "name": "grades",
       "description": "Endpoints under `/api/bongos/grades`."
@@ -206,9 +210,12 @@
           "access-requests"
         ],
         "summary": "GET /access-requests",
-        "description": "GET /access-requests?status=pending — Archon queue. Defaults to pending; pass ?status=invited|dismissed for the resolved history. rank: archon — the queue exposes would-be builders' usernames.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "description": "GET /access-requests?status=pending — Archon queue. Defaults to pending; pass ?status=invited|dismissed for the resolved history. rank: archon — the queue exposes would-be builders' usernames.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `access_request.review` (all required).",
         "x-rank": "archon",
         "x-source": "modules/onboarding/routes/access-requests.js",
+        "x-permissions": [
+          "access_request.review"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -309,9 +316,12 @@
           "access-requests"
         ],
         "summary": "PATCH /access-requests/:id",
-        "description": "PATCH /access-requests/:id — Archon resolves a request. body: { status: 'invited' | 'dismissed' }. 'invited' = admitted to the hall (the only sign-in gate — no repo access needed); 'dismissed' = declined / spam / dup. The row stays as the audit trail either way. rank: archon — same gate as the rest of the roster management surface.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "description": "PATCH /access-requests/:id — Archon resolves a request. body: { status: 'invited' | 'dismissed' }. 'invited' = admitted to the hall (the only sign-in gate — no repo access needed); 'dismissed' = declined / spam / dup. The row stays as the audit trail either way. rank: archon — same gate as the rest of the roster management surface.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `access_request.review` (all required).",
         "x-rank": "archon",
         "x-source": "modules/onboarding/routes/access-requests.js",
+        "x-permissions": [
+          "access_request.review"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -455,9 +465,12 @@
           "audit-log"
         ],
         "summary": "GET /audit-log",
-        "description": "GET /api/gds/audit-log?limit=&offset=&builder_id=&method= Paginated, newest-first. Clamps: limit → 1..500, default 100 offset → >= 0, default 0 rank: archon — forensics surface; only the Archon should see who did what.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "GET /api/gds/audit-log?limit=&offset=&builder_id=&method= Paginated, newest-first. Clamps: limit → 1..500, default 100 offset → >= 0, default 0 rank: archon — forensics surface; only the Archon should see who did what. Gate: requirePermission('audit_log.read') — BV1.R104; the seeded rank-role makes the permission and the old rank floor identical (ADR 0151).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `audit_log.read` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/audit-log.js",
+        "x-permissions": [
+          "audit_log.read"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -958,9 +971,12 @@
           "auth"
         ],
         "summary": "POST /auth/revoke",
-        "description": "POST /auth/revoke — V3.R38 / task 259. Archon-only. Kill a SINGLE session by its primary-key id. Used for surgical lockouts (e.g. a compromised CLI on a known builder's laptop) without disturbing that builder's other sessions. Body: { session_id: <bigint> }. Response: { ok, revoked: 0|1 }. rank: archon — kills an arbitrary session; can lock other builders out.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "description": "POST /auth/revoke — V3.R38 / task 259. Archon-only. Kill a SINGLE session by its primary-key id. Used for surgical lockouts (e.g. a compromised CLI on a known builder's laptop) without disturbing that builder's other sessions. Body: { session_id: <bigint> }. Response: { ok, revoked: 0|1 }. rank: archon — kills an arbitrary session; can lock other builders out. Gate: requirePermission('auth.session.revoke') — BV1.R104; the seeded rank-role makes the permission and the old rank floor identical (ADR 0151).\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `auth.session.revoke` (all required).",
         "x-rank": "archon",
         "x-source": "src/bongos/routes/auth.js",
+        "x-permissions": [
+          "auth.session.revoke"
+        ],
         "requestBody": {
           "required": false,
           "content": {
@@ -1007,9 +1023,12 @@
           "auth"
         ],
         "summary": "POST /auth/revoke-all",
-        "description": "POST /auth/revoke-all — V3.R38 / task 259. Archon-only. Kill EVERY active session for a given builder. Used at demotion (auto-called from setBuilderRank when newRank moves down the ladder — C7 rank-change-near- instant) and as a manual operator hammer. Body: { builder_id: <bigint> }. Response: { ok, revoked: <count> }. rank: archon — same authority as PATCH /builders/:id/rank.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "description": "POST /auth/revoke-all — V3.R38 / task 259. Archon-only. Kill EVERY active session for a given builder. Used at demotion (auto-called from setBuilderRank when newRank moves down the ladder — C7 rank-change-near- instant) and as a manual operator hammer. Body: { builder_id: <bigint> }. Response: { ok, revoked: <count> }. rank: archon — same authority as PATCH /builders/:id/rank. Gate: requirePermission('auth.session.revoke') — BV1.R104; the same atom /auth/revoke gates on (ADR 0151).\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `auth.session.revoke` (all required).",
         "x-rank": "archon",
         "x-source": "src/bongos/routes/auth.js",
+        "x-permissions": [
+          "auth.session.revoke"
+        ],
         "requestBody": {
           "required": false,
           "content": {
@@ -1126,9 +1145,12 @@
           "autonomy"
         ],
         "summary": "GET /autonomy/precheck",
-        "description": "**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `autonomy.precheck` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/autonomy/routes/autonomy.js",
+        "x-permissions": [
+          "autonomy.precheck"
+        ],
         "responses": {
           "200": {
             "description": "Success."
@@ -1157,9 +1179,12 @@
           "backup"
         ],
         "summary": "GET /backup/status",
-        "description": "any working builder may check or trigger a backup.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "any working builder may check or trigger a backup. Gate: requirePermission('backup.manage') — BV1.R104; the seeded rank-role makes the permission and the old rank floor identical (ADR 0151).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `backup.manage` (all required).",
         "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/backup.js",
+        "x-permissions": [
+          "backup.manage"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -1195,9 +1220,12 @@
           "backup"
         ],
         "summary": "POST /backup/trigger",
-        "description": "**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "kicks off a fresh dump; same gate as the status read. Gate: requirePermission('backup.manage') — BV1.R104.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `backup.manage` (all required).",
         "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/backup.js",
+        "x-permissions": [
+          "backup.manage"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -1360,9 +1388,12 @@
           "blockers"
         ],
         "summary": "POST /blockers/:id/link",
-        "description": "Link an existing blocker to a task (puts the task in 'blocked' status if it's currently 'backlog' or 'ready'). Metic+ (task 360 / ADR 0018) — same blocker-review grant as resolve above. rank: metic+archon — link a blocker to a task; same blocker-review grant as resolve.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "Link an existing blocker to a task. A task that is currently 'ready' is parked in 'blocked' so it stops advertising as claimable and the resolve-side trigger can release it; every other status is left alone (task 1002559 — see LINK_BLOCKABLE_STATUSES for why 'backlog' is excluded). Metic+ (task 360 / ADR 0018) — same blocker-review grant as resolve above. rank: metic+archon — link a blocker to a task; same blocker-review grant as resolve.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `blocker.review` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/ideas/routes/blockers.js",
+        "x-permissions": [
+          "blocker.review"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -1423,9 +1454,12 @@
           "blockers"
         ],
         "summary": "POST /blockers/:id/resolve",
-        "description": "Resolve. Auto-promotes any blocked tasks linked via task_blockers. Metic+ (task 360 / ADR 0018): blocker review is one of the operations C2 assigns to Metic, so this widened from archon-only to metic+archon when the three-rank model went live. Any builder can still FILE a blocker (POST /blockers above); a Xenos cannot resolve or link them. rank: metic+archon — blocker review (auto-promotes linked blocked tasks); criterion C2 / task 360 / ADR 0018.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "Resolve. Auto-promotes any blocked tasks linked via task_blockers. Metic+ (task 360 / ADR 0018): blocker review is one of the operations C2 assigns to Metic, so this widened from archon-only to metic+archon when the three-rank model went live. Any builder can still FILE a blocker (POST /blockers above); a Xenos cannot resolve or link them. rank: metic+archon — blocker review (auto-promotes linked blocked tasks); criterion C2 / task 360 / ADR 0018.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `blocker.review` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/ideas/routes/blockers.js",
+        "x-permissions": [
+          "blocker.review"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -2156,9 +2190,12 @@
           "boxes"
         ],
         "summary": "GET /boxes",
-        "description": "GET /boxes — full roster across all builders. rank: archon (exposes every builder's box + IP + cost; same gate as the rest of roster management).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "GET /boxes — full roster across all builders. rank: archon (exposes every builder's box + IP + cost; same gate as the rest of roster management).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `box.fleet.manage` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/dev-box/routes/box.js",
+        "x-permissions": [
+          "box.fleet.manage"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -2194,9 +2231,12 @@
           "boxes"
         ],
         "summary": "GET /boxes/cost-ledger",
-        "description": "GET /boxes/cost-ledger — the full per-builder container-cost ledger + totals (task 602). rank: archon — cost oversight across every builder without a DB query. Declared among the archon routes (archon-first) so the route-rank auditor's 20-line lookahead classifies it correctly.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "GET /boxes/cost-ledger — the full per-builder container-cost ledger + totals (task 602). rank: archon — cost oversight across every builder without a DB query. Declared among the archon routes (archon-first) so the route-rank auditor's 20-line lookahead classifies it correctly.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `box.fleet.manage` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/dev-box/routes/box.js",
+        "x-permissions": [
+          "box.fleet.manage"
+        ],
         "responses": {
           "200": {
             "description": "Success."
@@ -2225,9 +2265,12 @@
           "boxes"
         ],
         "summary": "PATCH /boxes/:builderId/block",
-        "description": "PATCH /boxes/:builderId/block — Archon bars (or un-bars) a builder from OPENING dev boxes (idea 257 / task 1163; migration 104). Body: { blocked: bool (required), reason?: string, // recorded on block; shown back to the builder close_current?: bool } // on block, ALSO deprovision a running box Block alone is \"no new opens\" (decideEnsureAction → BOX_PROVISION_BLOCKED); it does NOT touch a box that is already active. close_current adds the explicit teardown the owner asked be optional (\"options for both\"). rank: archon. Archon-first ordering (see above).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "PATCH /boxes/:builderId/block — Archon bars (or un-bars) a builder from OPENING dev boxes (idea 257 / task 1163; migration 104). Body: { blocked: bool (required), reason?: string, // recorded on block; shown back to the builder close_current?: bool } // on block, ALSO deprovision a running box Block alone is \"no new opens\" (decideEnsureAction → BOX_PROVISION_BLOCKED); it does NOT touch a box that is already active. close_current adds the explicit teardown the owner asked be optional (\"options for both\"). rank: archon. Archon-first ordering (see above).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `box.fleet.manage` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/dev-box/routes/box.js",
+        "x-permissions": [
+          "box.fleet.manage"
+        ],
         "parameters": [
           {
             "name": "builderId",
@@ -2288,9 +2331,12 @@
           "boxes"
         ],
         "summary": "POST /boxes/:builderId/close",
-        "description": "POST /boxes/:builderId/close — Archon force-closes ANY builder's box (idea 257 / task 1163). Trust-safe by the same mechanism as the builder's own POST /box/close: it ENQUEUES a 'deprovision' intent and the control-plane runner executes it, so the web tier never holds DO_API_TOKEN (ADR 0031 §9.4). rank: archon (acts on another builder's paid infrastructure). Declared among the archon routes (archon-first) so the route-rank auditor's 20-line lookahead classifies it correctly.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "POST /boxes/:builderId/close — Archon force-closes ANY builder's box (idea 257 / task 1163). Trust-safe by the same mechanism as the builder's own POST /box/close: it ENQUEUES a 'deprovision' intent and the control-plane runner executes it, so the web tier never holds DO_API_TOKEN (ADR 0031 §9.4). rank: archon (acts on another builder's paid infrastructure). Declared among the archon routes (archon-first) so the route-rank auditor's 20-line lookahead classifies it correctly.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `box.fleet.manage` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/dev-box/routes/box.js",
+        "x-permissions": [
+          "box.fleet.manage"
+        ],
         "parameters": [
           {
             "name": "builderId",
@@ -2461,9 +2507,12 @@
           "builders"
         ],
         "summary": "GET /builders/roster",
-        "description": "GET /builders/roster — V3.R14 (task 238) onboarding observability. Archon-only roster of every builder with their identity + onboarding signals + active-claim posture. Powers the management panel in the /builders hall so the Archon can promote / demote / release-stale-claim without dropping into psql. Optional query param: ?stale_hours=N (default 24). Defines what counts as \"stale\" for the per-row stale_claim flag — mirrors the threshold the stale-claim-release sweeper uses but exposed as a roster knob so the Archon can dial it in if needed. rank: archon — surfaces every builder's onboarding state.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "GET /builders/roster — V3.R14 (task 238) onboarding observability. Archon-only roster of every builder with their identity + onboarding signals + active-claim posture. Powers the management panel in the /builders hall so the Archon can promote / demote / release-stale-claim without dropping into psql. Optional query param: ?stale_hours=N (default 24). Defines what counts as \"stale\" for the per-row stale_claim flag — mirrors the threshold the stale-claim-release sweeper uses but exposed as a roster knob so the Archon can dial it in if needed. rank: archon — surfaces every builder's onboarding state. Gate: requirePermission('builder.roster.read') — BV1.R104; the same atom /grades/by-builder and /builders/:id/active-claims already gate on (ADR 0151).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `builder.roster.read` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/builders.js",
+        "x-permissions": [
+          "builder.roster.read"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -2499,9 +2548,12 @@
           "builders"
         ],
         "summary": "GET /builders/:id/active-claims",
-        "description": "GET /builders/:id/active-claims — V3.R14 (task 238). Archon-only detail view of a single builder's active claims, with the same stale_claim flag the roster computes. The roster only carries boolean \"has any stale claim?\"; this endpoint surfaces *which* claim is stale so the Archon can target the release. rank: archon — privileged read of another builder's work surface.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "GET /builders/:id/active-claims — V3.R14 (task 238). Archon-only detail view of a single builder's active claims, with the same stale_claim flag the roster computes. The roster only carries boolean \"has any stale claim?\"; this endpoint surfaces *which* claim is stale so the Archon can target the release. rank: archon — privileged read of another builder's work surface. NOT ownership-scoped. Gate: requirePermission('builder.roster.read') — BV1.R104.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `builder.roster.read` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/builders.js",
+        "x-permissions": [
+          "builder.roster.read"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -2551,9 +2603,12 @@
           "builders"
         ],
         "summary": "PATCH /builders/:id/budget",
-        "description": "PATCH /builders/:id/budget — set or clear a builder's monthly spend ceiling (V3.R84 task 302, criterion C3). Archon-only. Body: { monthly_budget_usd: <num> } sets the per-builder override — the manual emergency brake; a positive value engages the warn/over thresholds. { monthly_budget_usd: null } clears it: the builder becomes UNCAPPED (there is no default cap — ADR 0085). This is the \"budget per-builder configurable by Archon\" done-when. 404 if no such builder. rank: archon — changes another builder's cost ceiling.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "PATCH /builders/:id/budget — set or clear a builder's monthly spend ceiling (V3.R84 task 302, criterion C3). Archon-only. Body: { monthly_budget_usd: <num> } sets the per-builder override — the manual emergency brake; a positive value engages the warn/over thresholds. { monthly_budget_usd: null } clears it: the builder becomes UNCAPPED (there is no default cap — ADR 0085). This is the \"budget per-builder configurable by Archon\" done-when. 404 if no such builder. rank: archon — changes another builder's cost ceiling. NOT ownership-scoped: archon-only admin op. Gate: requirePermission('builder.budget.set') — BV1.R104; the seeded rank-role makes the permission and the old rank floor identical (ADR 0151).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `builder.budget.set` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/builders.js",
+        "x-permissions": [
+          "builder.budget.set"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -2698,9 +2753,12 @@
           "builders"
         ],
         "summary": "PATCH /builders/:id/rank",
-        "description": "sole chokepoint that mutates builders.rank; ADR 0016 §enforcement.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "description": "sole chokepoint that mutates builders.rank; ADR 0016 §enforcement. Gate: requirePermission('builder.rank.set') — BV1.R104; the seeded rank-role makes the permission and the old rank floor identical (ADR 0151). The atom is `system: true`, so no CUSTOM role may ever be granted it — only the seeded archon role holds it, which is exactly the meta-escalation wall ADR 0016 wants.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `builder.rank.set` (all required).",
         "x-rank": "archon",
         "x-source": "src/bongos/routes/builders.js",
+        "x-permissions": [
+          "builder.rank.set"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -2761,9 +2819,12 @@
           "builders"
         ],
         "summary": "PATCH /builders/:id/status",
-        "description": "PATCH /builders/:id/status — graceful exit + reactivation (V3.R88 task 307). Archon-only. { status: 'inactive', reason? } deactivates (releases active claims, seals their session_logs, rank → xenos, blocks new claims while preserving all credit/history); { status: 'active' } reactivates. Cannot change your own status (no last-Archon footgun — same guard as /rank). rank: archon — deactivation/reactivation; preserves credit history but blocks claims.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "description": "PATCH /builders/:id/status — graceful exit + reactivation (V3.R88 task 307). Archon-only. { status: 'inactive', reason? } deactivates (releases active claims, seals their session_logs, rank → xenos, blocks new claims while preserving all credit/history); { status: 'active' } reactivates. Cannot change your own status (no last-Archon footgun — same guard as /rank). rank: archon — deactivation/reactivation; preserves credit history but blocks claims. Gate: requirePermission('builder.status.set') — BV1.R104; the seeded rank-role makes the permission and the old rank floor identical (ADR 0151).\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `builder.status.set` (all required).",
         "x-rank": "archon",
         "x-source": "src/bongos/routes/builders.js",
+        "x-permissions": [
+          "builder.status.set"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -3006,9 +3067,12 @@
           "claims"
         ],
         "summary": "POST /claims/:id/release-on-behalf",
-        "description": "POST /claims/:id/release-on-behalf — V3.R14 (task 238). Archon-only escape hatch. The normal /claims/:id/resolve path only accepts the original claimant; this route lets the Archon release someone else's stuck claim (typically a stale one the sweeper has not picked up yet, or a deliberate intervention). Body: { reason: string }. The reason is required — every Archon intervention needs a paper trail. Capped at LIMITS.NOTES. The release sets outcome='abandoned' and returns the task to status='ready' (same as a normal abandon). No credits land. The session_logs row carries the original builder_id with notes_md tagged \"[archon-release]\" + the acting Archon's @login so an audit grep can find every third-party release.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "POST /claims/:id/release-on-behalf — V3.R14 (task 238). Archon-only escape hatch. The normal /claims/:id/resolve path only accepts the original claimant; this route lets the Archon release someone else's stuck claim (typically a stale one the sweeper has not picked up yet, or a deliberate intervention). Body: { reason: string }. The reason is required — every Archon intervention needs a paper trail. Capped at LIMITS.NOTES. The release sets outcome='abandoned' and returns the task to status='ready' (same as a normal abandon). No credits land. The session_logs row carries the original builder_id with notes_md tagged \"[archon-release]\" + the acting Archon's @login so an audit grep can find every third-party release.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `claim.release.any` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/claims.js",
+        "x-permissions": [
+          "claim.release.any"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -3167,9 +3231,12 @@
           "dependencies"
         ],
         "summary": "POST /dependencies",
-        "description": "POST /dependencies — create an edge \"from is blocked until to is done\". rank: archon.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "description": "POST /dependencies — create an edge \"from is blocked until to is done\". rank: archon.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `dependency.cross_tier.manage` (all required).",
         "x-rank": "archon",
         "x-source": "modules/lifecycle/routes/dependencies.js",
+        "x-permissions": [
+          "dependency.cross_tier.manage"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -3203,9 +3270,12 @@
           "dependencies"
         ],
         "summary": "DELETE /dependencies",
-        "description": "DELETE /dependencies — remove an edge (body carries the 4-tuple). rank: archon.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "description": "DELETE /dependencies — remove an edge (body carries the 4-tuple). rank: archon.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `dependency.cross_tier.manage` (all required).",
         "x-rank": "archon",
         "x-source": "modules/lifecycle/routes/dependencies.js",
+        "x-permissions": [
+          "dependency.cross_tier.manage"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -3241,9 +3311,12 @@
           "discord"
         ],
         "summary": "GET /discord/channels/plan",
-        "description": "GET /api/bongos/discord/channels/plan — dry run. Returns the ops the bot WOULD apply to make Discord match docs/discord/channels.json, plus warnings. No writes. 503 when the bot is disabled / not connected to a guild. rank: archon — channel administration command.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "GET /api/bongos/discord/channels/plan — dry run. Returns the ops the bot WOULD apply to make Discord match docs/discord/channels.json, plus warnings. No writes. 503 when the bot is disabled / not connected to a guild. rank: archon — channel administration command.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `discord.channels.manage` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/discord/routes/discord.js",
+        "x-permissions": [
+          "discord.channels.manage"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -3279,9 +3352,12 @@
           "discord"
         ],
         "summary": "POST /discord/channels/reconcile",
-        "description": "POST /api/bongos/discord/channels/reconcile — apply the config to Discord now. Best-effort; returns how many ops applied/failed. 503 when the bot is disabled / not connected. rank: archon — channel administration command.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "POST /api/bongos/discord/channels/reconcile — apply the config to Discord now. Best-effort; returns how many ops applied/failed. 503 when the bot is disabled / not connected. rank: archon — channel administration command.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `discord.channels.manage` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/discord/routes/discord.js",
+        "x-permissions": [
+          "discord.channels.manage"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -3317,9 +3393,12 @@
           "done-when"
         ],
         "summary": "GET /done-when/pending-review",
-        "description": "Auth (Metic+): the criterion review queue — every criterion auto-flagged \"met — pending review\" (≥1 linked task, all shipped, not yet confirmed), derived from task_criteria + ship status (ADR 0086 §6 / BV1.R63). Powers the /goal-review skill. Optional ?version= scopes to one version. Gated Metic+ to match the satisfy route below — this is the planner's closing queue, not a public surface. rank: metic+archon — the planner review queue (mirrors the satisfy gate).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "Auth (Metic+): the criterion review queue — every criterion auto-flagged \"met — pending review\" (≥1 linked task, all shipped, not yet confirmed), derived from task_criteria + ship status (ADR 0086 §6 / BV1.R63). Powers the /goal-review skill. Optional ?version= scopes to one version. Gated Metic+ to match the satisfy route below — this is the planner's closing queue, not a public surface. rank: metic+archon — the planner review queue (mirrors the satisfy gate).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `criterion.review` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/done-when.js",
+        "x-permissions": [
+          "criterion.review"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -3355,9 +3434,12 @@
           "done-when"
         ],
         "summary": "POST /done-when/:criterionId/satisfy",
-        "description": "Auth (Metic+): confirm a criterion — flip it to satisfied. Accepts optional satisfied_by_task_id so the UI can show which ship-task fulfilled it. When the criterion belongs to a goal and was its LAST unsatisfied one, the goal auto- flips open→achieved (ADR 0086 §6 / BV1.R63). Re-ranked Archon→Metic+ so the planner — not only the Archon — closes the criterion/goal loop; the route is pinned in route-rank-check.MODULE_EXPECTED_RANKS.lifecycle so a further downgrade is caught. rank: metic+archon — criterion confirmation + goal auto-achieve (the closing loop).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "Auth (Metic+): confirm a criterion — flip it to satisfied. Accepts optional satisfied_by_task_id so the UI can show which ship-task fulfilled it. When the criterion belongs to a goal and was its LAST unsatisfied one, the goal auto- flips open→achieved (ADR 0086 §6 / BV1.R63). Re-ranked Archon→Metic+ so the planner — not only the Archon — closes the criterion/goal loop; the route is pinned in route-rank-check.MODULE_EXPECTED_RANKS.lifecycle so a further downgrade is caught. rank: metic+archon — criterion confirmation + goal auto-achieve (the closing loop).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `criterion.satisfy` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/done-when.js",
+        "x-permissions": [
+          "criterion.satisfy"
+        ],
         "parameters": [
           {
             "name": "criterionId",
@@ -3418,9 +3500,12 @@
           "done-when"
         ],
         "summary": "POST /done-when/:criterionId/unsatisfy",
-        "description": "Auth: flip a criterion back to unsatisfied (rare; for corrections). rank: archon — un-flip a criterion; same gate as satisfy.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "Auth: flip a criterion back to unsatisfied (rare; for corrections). rank: archon — un-flip a criterion; same gate as satisfy.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `criterion.unsatisfy` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/done-when.js",
+        "x-permissions": [
+          "criterion.unsatisfy"
+        ],
         "parameters": [
           {
             "name": "criterionId",
@@ -3470,9 +3555,12 @@
           "gate-approvals"
         ],
         "summary": "GET /gate-approvals",
-        "description": "GET /gate-approvals — open PRs awaiting owner approval (gate-review red), with the verdict + per-file reasons + changed files + diff link. rank: archon.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "GET /gate-approvals — open PRs awaiting owner approval (gate-review red), with the verdict + per-file reasons + changed files + diff link. rank: metic+archon. BV1.R105 left this on requireRank because `gate_approval.decide` was declared over the /approve WRITE only and no atom named the read. ADR 0157 extends the catalog with exactly that atom — `gate_approval.read`, floor metic — so the mapping is now one the catalog makes. The split is load-bearing, not cosmetic: `page.view.governance` opens /gate to Metic, and without a Metic-readable data endpoint that page would render nothing but a 403. Approving a held PR stays archon (`.decide`, system).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `gate_approval.read` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/gate-approvals.js",
+        "x-permissions": [
+          "gate_approval.read"
+        ],
         "responses": {
           "200": {
             "description": "Success."
@@ -3501,9 +3589,12 @@
           "gate-approvals"
         ],
         "summary": "POST /gate-approvals/:pr/approve",
-        "description": "POST /gate-approvals/:pr/approve — record owner approval for a stuck gate PR and re-run the gate-review check so it clears. rank: archon (clears the hard floor — pinned in route-rank-check.EXPECTED_RANKS for downgrade protection).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "description": "POST /gate-approvals/:pr/approve — record owner approval for a stuck gate PR and re-run the gate-review check so it clears. rank: archon (clears the hard floor — pinned in route-rank-check.EXPECTED_RANKS for downgrade protection).\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `gate_approval.decide` (all required).",
         "x-rank": "archon",
         "x-source": "modules/lifecycle/routes/gate-approvals.js",
+        "x-permissions": [
+          "gate_approval.decide"
+        ],
         "parameters": [
           {
             "name": "pr",
@@ -3674,9 +3765,12 @@
           "goals"
         ],
         "summary": "POST /goals",
-        "description": "POST /goals — create a goal. rank: metic+archon — a Metic or Archon may create a goal; creation of a goal whose scope_modules includes a PROTECTED module is Archon-only (in-handler).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "POST /goals — create a goal. rank: metic+archon — a Metic or Archon may create a goal; creation of a goal whose scope_modules includes a PROTECTED module is Archon-only (in-handler).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `goal.create` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/goals.js",
+        "x-permissions": [
+          "goal.create"
+        ],
         "requestBody": {
           "required": true,
           "content": {
@@ -3754,9 +3848,12 @@
           "goals"
         ],
         "summary": "POST /goals/reorder",
-        "description": "POST /goals/reorder — Archon drag-to-reorder: set the priority order of every goal WITHIN one version (task 1760). ordered_ids must be exactly that version's goal ids, each once (db.reorderGoals fails closed otherwise) — a partial list can't silently orphan a goal's priority. Mounted BEFORE GET /goals/:id so 'reorder' is never captured as an id. rank: archon — priority is an owner decision, never self-granted by a goal's own member/manager (unlike the goal-authority routes above).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "POST /goals/reorder — Archon drag-to-reorder: set the priority order of every goal WITHIN one version (task 1760). ordered_ids must be exactly that version's goal ids, each once (db.reorderGoals fails closed otherwise) — a partial list can't silently orphan a goal's priority. Mounted BEFORE GET /goals/:id so 'reorder' is never captured as an id. rank: archon — priority is an owner decision, never self-granted by a goal's own member/manager (unlike the goal-authority routes above).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `goal.reorder` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/goals.js",
+        "x-permissions": [
+          "goal.reorder"
+        ],
         "requestBody": {
           "required": true,
           "content": {
@@ -3855,9 +3952,12 @@
           "goals"
         ],
         "summary": "POST /goals/:id/archive",
-        "description": "POST /goals/:id/archive — retire a goal (open|achieved → archived). Archived goals are re-openable (below). This is the lifecycle disposition the /goal-review skill reaches for once a goal is achieved (ADR 0086 §6 / BV1.R64). rank: metic+archon — a goal member (Metic+) or an Archon dispositions the goal.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "POST /goals/:id/archive — retire a goal (open|achieved → archived). Archived goals are re-openable (below). This is the lifecycle disposition the /goal-review skill reaches for once a goal is achieved (ADR 0086 §6 / BV1.R64). rank: metic+archon — a goal member (Metic+) or an Archon dispositions the goal.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `goal.archive` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/goals.js",
+        "x-permissions": [
+          "goal.archive"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -4396,9 +4496,12 @@
           "goals"
         ],
         "summary": "POST /goals/:id/reopen",
-        "description": "POST /goals/:id/reopen — bring an archived goal back to open (ADR 0086 §6 / BV1.R64). Only archived → open; an already open/achieved goal is a 409. rank: metic+archon — same gate as archive.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "POST /goals/:id/reopen — bring an archived goal back to open (ADR 0086 §6 / BV1.R64). Only archived → open; an already open/achieved goal is a 409. rank: metic+archon — same gate as archive.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `goal.archive` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/goals.js",
+        "x-permissions": [
+          "goal.archive"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -4694,9 +4797,12 @@
           "goals"
         ],
         "summary": "POST /goals/:id/scope",
-        "description": "POST /goals/:id/scope — \"ask to widen\": add module(s) to a goal's scope_modules (ADR 0086 §4 / BV1.R64). Scope is NEVER self-granted, so this is the gated approve-and-apply: requireRank('metic','archon') + the caller must be a member (or Archon), and a PROTECTED module can only be added by an Archon (mirrors the POST /goals create gate). A sub-Metic member therefore cannot widen at all — they ask a Metic+/Archon out-of-band, exactly as joining a protected goal works (R57). The goal must be open. Body: { add: [\"module-key\", ...] }; idempotent (set-union). rank: metic+archon — widens the module wall; pinned in route-rank-check.EXPECTED_RANKS.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "POST /goals/:id/scope — \"ask to widen\": add module(s) to a goal's scope_modules (ADR 0086 §4 / BV1.R64). Scope is NEVER self-granted, so this is the gated approve-and-apply: requireRank('metic','archon') + the caller must be a member (or Archon), and a PROTECTED module can only be added by an Archon (mirrors the POST /goals create gate). A sub-Metic member therefore cannot widen at all — they ask a Metic+/Archon out-of-band, exactly as joining a protected goal works (R57). The goal must be open. Body: { add: [\"module-key\", ...] }; idempotent (set-union). rank: metic+archon — widens the module wall; pinned in route-rank-check.EXPECTED_RANKS.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `goal.scope.widen` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/goals.js",
+        "x-permissions": [
+          "goal.scope.widen"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -4991,23 +5097,26 @@
         ]
       }
     },
-    "/grades/by-builder": {
+    "/governance/assignments": {
       "get": {
-        "operationId": "get_grades_by_builder",
+        "operationId": "get_governance_assignments",
         "tags": [
-          "grades"
+          "governance"
         ],
-        "summary": "GET /grades/by-builder",
-        "description": "GET /grades/by-builder?days=30 — per-builder grade breakdown (task 726). Archon-only monitoring read backing the MARKS section of the /watch page: who is passing/failing the grader, over a window. Aggregated from task_grades joined through tasks.shipped_by. Mirrors the rank gate on the roster + audit-log reads — it exposes cross-builder quality data, so it is the Ruling Hand's alone (the project-wide aggregate stays public via /public/grades; this per-builder split does not). rank: archon.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
+        "summary": "GET /governance/assignments",
+        "description": "governance.manage — every builder↔role assignment row.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `governance.manage` (all required).",
         "x-rank": "archon",
-        "x-source": "src/bongos/routes/builders.js",
+        "x-source": "modules/governance/routes/governance.js",
+        "x-permissions": [
+          "governance.manage"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetGradesByBuilderResponse"
+                  "$ref": "#/components/schemas/GetGovernanceAssignmentsResponse"
                 }
               }
             }
@@ -5027,53 +5136,176 @@
             "builderSession": []
           }
         ]
+      },
+      "post": {
+        "operationId": "post_governance_assignments",
+        "tags": [
+          "governance"
+        ],
+        "summary": "POST /governance/assignments",
+        "description": "governance.manage — assign a CUSTOM role to a builder. assigned_by is ALWAYS the session builder, never input (the audit trail's \"who did this\" must be the authenticated actor).\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `governance.manage` (all required).",
+        "x-rank": "archon",
+        "x-source": "modules/governance/routes/governance.js",
+        "x-permissions": [
+          "governance.manage"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostGovernanceAssignmentsRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
       }
     },
-    "/healthz": {
+    "/governance/assignments/{builderId}/{roleKey}": {
+      "delete": {
+        "operationId": "delete_governance_assignments_builderId_roleKey",
+        "tags": [
+          "governance"
+        ],
+        "summary": "DELETE /governance/assignments/:builderId/:roleKey",
+        "description": "governance.manage — remove a custom-role assignment. Idempotent: `removed` says whether a row went away.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `governance.manage` (all required).",
+        "x-rank": "archon",
+        "x-source": "modules/governance/routes/governance.js",
+        "x-permissions": [
+          "governance.manage"
+        ],
+        "parameters": [
+          {
+            "name": "builderId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `builderId`."
+          },
+          {
+            "name": "roleKey",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `roleKey`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DeleteGovernanceAssignmentsBuilderIdRoleKeyResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/governance/permissions": {
       "get": {
-        "operationId": "get_healthz",
+        "operationId": "get_governance_permissions",
         "tags": [
-          "healthz"
+          "governance"
+        ],
+        "summary": "GET /governance/permissions",
+        "description": "governance.manage — the permission catalog + principals, straight from code (the catalog is CODE, not a table); no DB read. `grantable` is the flag the tab renders LOCKED from; principals are read-only by construction.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `governance.manage` (all required).",
+        "x-rank": "archon",
+        "x-source": "modules/governance/routes/governance.js",
+        "x-permissions": [
+          "governance.manage"
         ],
-        "summary": "GET /healthz",
-        "description": "liveness probe; status.amazonprimea.com hits this anonymously.\n\n**Rank:** `public` — No authentication — any caller.",
-        "x-rank": "public",
-        "x-source": "src/bongos/routes/healthz.js",
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetHealthzResponse"
+                  "$ref": "#/components/schemas/GetGovernancePermissionsResponse"
                 }
               }
             }
           },
           "400": {
             "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
           }
         },
-        "security": []
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
       }
     },
-    "/inbox": {
+    "/governance/roles": {
       "get": {
-        "operationId": "get_inbox",
+        "operationId": "get_governance_roles",
         "tags": [
-          "inbox"
+          "governance"
+        ],
+        "summary": "GET /governance/roles",
+        "description": "governance.manage — the full role list with each role's grants.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `governance.manage` (all required).",
+        "x-rank": "archon",
+        "x-source": "modules/governance/routes/governance.js",
+        "x-permissions": [
+          "governance.manage"
         ],
-        "summary": "GET /inbox",
-        "description": "read open ideas; skill-friction rows filtered by viewer rank.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "modules/ideas/routes/inbox.js",
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetInboxResponse"
+                  "$ref": "#/components/schemas/GetGovernanceRolesResponse"
                 }
               }
             }
@@ -5095,20 +5327,23 @@
         ]
       },
       "post": {
-        "operationId": "post_inbox",
+        "operationId": "post_governance_roles",
         "tags": [
-          "inbox"
+          "governance"
+        ],
+        "summary": "POST /governance/roles",
+        "description": "governance.manage — create a CUSTOM role (is_system false, no seeded_rank — the seeded four exist only via governance_002). Grants are added one at a time via the toggle below, so creation carries none.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `governance.manage` (all required).",
+        "x-rank": "archon",
+        "x-source": "modules/governance/routes/governance.js",
+        "x-permissions": [
+          "governance.manage"
         ],
-        "summary": "POST /inbox",
-        "description": "for ordinary ideas; metic+ for kind='criterion-proposal'. Anyone can file a general contribution (the open-to-all path that idea-triage's \"Xenos can still file\" line guarantees). But kind= 'criterion-proposal' is the marker the /planning-session skill writes from Metic-mode, and a planning-session proposal reshapes the next version's scope-truth — that's a trusted-builder operation (V3.R87 / task 306). Gate it here so a Xenos can't slip a criterion proposal in via raw curl after the skill itself refuses to run for them.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "modules/ideas/routes/inbox.js",
         "requestBody": {
           "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/PostInboxRequest"
+                "$ref": "#/components/schemas/PostGovernanceRolesRequest"
               }
             }
           },
@@ -5120,7 +5355,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PostInboxResponse"
+                  "$ref": "#/components/schemas/PostGovernanceRolesResponse"
                 }
               }
             }
@@ -5142,25 +5377,37 @@
         ]
       }
     },
-    "/inbox/{id}": {
-      "get": {
-        "operationId": "get_inbox_id",
+    "/governance/roles/{roleKey}/permissions/{permissionKey}": {
+      "put": {
+        "operationId": "put_governance_roles_roleKey_permissions_permissionKey",
         "tags": [
-          "inbox"
+          "governance"
+        ],
+        "summary": "PUT /governance/roles/:roleKey/permissions/:permissionKey",
+        "description": "governance.manage — grant one OPERATIONAL permission to a custom role (the toggle's ON half). The order of refusals is the authority order: role exists → role is custom → the key exists → the key is grantable.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `governance.manage` (all required).",
+        "x-rank": "archon",
+        "x-source": "modules/governance/routes/governance.js",
+        "x-permissions": [
+          "governance.manage"
         ],
-        "summary": "GET /inbox/:id",
-        "description": "single idea read for the \"#NNN\" deep-link resolver (task 1047). Mirrors GET /blockers/:id. The hall resolves /#/idea/N by id, but the /inbox LIST returns only the open-first-50, so a closed/older idea ref would dead-end at a \"no such idea\" card. getIdea() reads any idea by id. Authed: a logged-out resolve hits the hall's softAuth \"sign in\" card, so no idea text is exposed publicly (the linked refs are public, the bodies aren't).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
-        "x-rank": "any-builder",
-        "x-source": "modules/ideas/routes/inbox.js",
         "parameters": [
           {
-            "name": "id",
+            "name": "roleKey",
             "in": "path",
             "required": true,
             "schema": {
               "type": "string"
             },
-            "description": "Path parameter `id`."
+            "description": "Path parameter `roleKey`."
+          },
+          {
+            "name": "permissionKey",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `permissionKey`."
           }
         ],
         "responses": {
@@ -5169,7 +5416,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetInboxIdResponse"
+                  "$ref": "#/components/schemas/PutGovernanceRolesRoleKeyPermissionsPermissionKeyResponse"
                 }
               }
             }
@@ -5193,50 +5440,321 @@
           }
         ]
       },
-      "patch": {
-        "operationId": "patch_inbox_id",
+      "delete": {
+        "operationId": "delete_governance_roles_roleKey_permissions_permissionKey",
         "tags": [
-          "inbox"
+          "governance"
+        ],
+        "summary": "DELETE /governance/roles/:roleKey/permissions/:permissionKey",
+        "description": "governance.manage — revoke a grant (the toggle's OFF half). Deliberately NOT validated against the catalog: a grant whose key the catalog since retired is exactly the row an Archon most needs to remove (the resolver already drops it — this is hygiene, not authority).\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `governance.manage` (all required).",
+        "x-rank": "archon",
+        "x-source": "modules/governance/routes/governance.js",
+        "x-permissions": [
+          "governance.manage"
         ],
-        "summary": "PATCH /inbox/:id",
-        "description": "Metic+ (task 360 / ADR 0018): idea triage (promote/discard/merge) shapes the backlog. Criterion C2 assigns triage to Metic, so this widened from archon-only to metic+archon when the three-rank model went live. Any builder can still FILE an idea (POST /inbox above); a Xenos cannot triage. rank: metic+archon — idea triage shapes the backlog; criterion C2 / task 360 / ADR 0018.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
-        "x-rank": "metic+archon",
-        "x-source": "modules/ideas/routes/inbox.js",
         "parameters": [
           {
-            "name": "id",
+            "name": "roleKey",
             "in": "path",
             "required": true,
             "schema": {
               "type": "string"
             },
-            "description": "Path parameter `id`."
+            "description": "Path parameter `roleKey`."
+          },
+          {
+            "name": "permissionKey",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `permissionKey`."
           }
         ],
-        "requestBody": {
-          "required": false,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/PatchInboxIdRequest"
-              }
-            }
-          },
-          "x-validated": true
-        },
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PatchInboxIdResponse"
+                  "$ref": "#/components/schemas/DeleteGovernanceRolesRoleKeyPermissionsPermissionKeyResponse"
                 }
               }
             }
           },
           "400": {
-            "$ref": "#/components/responses/ValidationFailed"
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/grades/by-builder": {
+      "get": {
+        "operationId": "get_grades_by_builder",
+        "tags": [
+          "grades"
+        ],
+        "summary": "GET /grades/by-builder",
+        "description": "GET /grades/by-builder?days=30 — per-builder grade breakdown (task 726). Archon-only monitoring read backing the MARKS section of the /watch page: who is passing/failing the grader, over a window. Aggregated from task_grades joined through tasks.shipped_by. Mirrors the rank gate on the roster + audit-log reads — it exposes cross-builder quality data, so it is the Ruling Hand's alone (the project-wide aggregate stays public via /public/grades; this per-builder split does not). rank: archon — NOT ownership-scoped: archon-only cross-builder read. Gate: requirePermission('builder.roster.read') — BV1.R104.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `builder.roster.read` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "src/bongos/routes/builders.js",
+        "x-permissions": [
+          "builder.roster.read"
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetGradesByBuilderResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/healthz": {
+      "get": {
+        "operationId": "get_healthz",
+        "tags": [
+          "healthz"
+        ],
+        "summary": "GET /healthz",
+        "description": "liveness probe; status.amazonprimea.com hits this anonymously.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "src/bongos/routes/healthz.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetHealthzResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
+    "/inbox": {
+      "get": {
+        "operationId": "get_inbox",
+        "tags": [
+          "inbox"
+        ],
+        "summary": "GET /inbox",
+        "description": "read open ideas; skill-friction rows filtered by viewer rank.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/ideas/routes/inbox.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetInboxResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "post": {
+        "operationId": "post_inbox",
+        "tags": [
+          "inbox"
+        ],
+        "summary": "POST /inbox",
+        "description": "for ordinary ideas; metic+ for kind='criterion-proposal'. Anyone can file a general contribution (the open-to-all path that idea-triage's \"Xenos can still file\" line guarantees). But kind= 'criterion-proposal' is the marker the /planning-session skill writes from Metic-mode, and a planning-session proposal reshapes the next version's scope-truth — that's a trusted-builder operation (V3.R87 / task 306). Gate it here so a Xenos can't slip a criterion proposal in via raw curl after the skill itself refuses to run for them.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/ideas/routes/inbox.js",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostInboxRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostInboxResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/inbox/{id}": {
+      "get": {
+        "operationId": "get_inbox_id",
+        "tags": [
+          "inbox"
+        ],
+        "summary": "GET /inbox/:id",
+        "description": "single idea read for the \"#NNN\" deep-link resolver (task 1047). Mirrors GET /blockers/:id. The hall resolves /#/idea/N by id, but the /inbox LIST returns only the open-first-50, so a closed/older idea ref would dead-end at a \"no such idea\" card. getIdea() reads any idea by id. Authed: a logged-out resolve hits the hall's softAuth \"sign in\" card, so no idea text is exposed publicly (the linked refs are public, the bodies aren't).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/ideas/routes/inbox.js",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetInboxIdResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "patch": {
+        "operationId": "patch_inbox_id",
+        "tags": [
+          "inbox"
+        ],
+        "summary": "PATCH /inbox/:id",
+        "description": "Metic+ (task 360 / ADR 0018): idea triage (promote/discard/merge) shapes the backlog. Criterion C2 assigns triage to Metic, so this widened from archon-only to metic+archon when the three-rank model went live. Any builder can still FILE an idea (POST /inbox above); a Xenos cannot triage. rank: metic+archon — idea triage shapes the backlog; criterion C2 / task 360 / ADR 0018.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `idea.triage` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/ideas/routes/inbox.js",
+        "x-permissions": [
+          "idea.triage"
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PatchInboxIdRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PatchInboxIdResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
@@ -5262,9 +5780,12 @@
           "inbox"
         ],
         "summary": "POST /inbox/:id/ratify",
-        "description": "V3.R31 (task 252) — Archon ratifies a criterion-proposal idea, atomically: - INSERT done_when_criteria row on the target version - UPDATE idea_inbox SET status='promoted', reviewed_at=now() - INSERT karma_log (delta=+3, reason='proposal_ratified') for proposer (V3.R28 / task 248 tuned the delta from +5 → +3; tunable.) - INSERT criterion_proposal_audit row capturing who/when/what Archon-only — done_when_criteria writes are scope-shaping (criterion C2 in canonical-permissions.md). The kind='criterion-proposal' POST is Metic+ (gated above), but the ratification is the Archon decision. Returns 400 if the source idea isn't kind='criterion-proposal' or its body_md isn't a parseable {target_version, criterion_md, sort_order_hint} JSON object. Returns 404 if the idea doesn't exist. Returns 409 if the idea is already promoted/discarded/merged (status != 'open'). All four writes happen in one transaction — partial failures roll back cleanly.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "V3.R31 (task 252) — Archon ratifies a criterion-proposal idea, atomically: - INSERT done_when_criteria row on the target version - UPDATE idea_inbox SET status='promoted', reviewed_at=now() - INSERT karma_log (delta=+3, reason='proposal_ratified') for proposer (V3.R28 / task 248 tuned the delta from +5 → +3; tunable.) - INSERT criterion_proposal_audit row capturing who/when/what Archon-only — done_when_criteria writes are scope-shaping (criterion C2 in canonical-permissions.md). The kind='criterion-proposal' POST is Metic+ (gated above), but the ratification is the Archon decision. Returns 400 if the source idea isn't kind='criterion-proposal' or its body_md isn't a parseable {target_version, criterion_md, sort_order_hint} JSON object. Returns 404 if the idea doesn't exist. Returns 409 if the idea is already promoted/discarded/merged (status != 'open'). All four writes happen in one transaction — partial failures roll back cleanly.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `idea.ratify` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/ideas/routes/inbox.js",
+        "x-permissions": [
+          "idea.ratify"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -5483,9 +6004,12 @@
           "llm-cache"
         ],
         "summary": "POST /llm-cache/lookup",
-        "description": "POST /llm-cache/lookup — hit/miss + atomic hit_count bump. Best-effort: any DB error inside lookup() already returns null → we report a miss. rank: metic — only the same trust tier that can store may read a stored result.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "POST /llm-cache/lookup — hit/miss + atomic hit_count bump. Best-effort: any DB error inside lookup() already returns null → we report a miss. rank: metic — only the same trust tier that can store may read a stored result. Gate: requirePermission('llm_cache.use') — BV1.R104; the seeded rank-role makes the permission and the old rank floor identical (ADR 0151).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `llm_cache.use` (all required).",
         "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/llm-cache.js",
+        "x-permissions": [
+          "llm_cache.use"
+        ],
         "requestBody": {
           "required": false,
           "content": {
@@ -5532,9 +6056,12 @@
           "llm-cache"
         ],
         "summary": "POST /llm-cache/store",
-        "description": "POST /llm-cache/store — upsert a freshly-produced result. rank: metic — a store seeds a result that a later run replays at $0 and trusts.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "POST /llm-cache/store — upsert a freshly-produced result. rank: metic — a store seeds a result that a later run replays at $0 and trusts. Gate: requirePermission('llm_cache.use') — BV1.R104.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `llm_cache.use` (all required).",
         "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/llm-cache.js",
+        "x-permissions": [
+          "llm_cache.use"
+        ],
         "requestBody": {
           "required": false,
           "content": {
@@ -6593,9 +7120,12 @@
           "memory"
         ],
         "summary": "GET /memory/builders/:builderId/file",
-        "description": "GET /memory/builders/:builderId/file?path=... — Archon reads ONE of ANOTHER builder's files (content included). Audit-logged. 404 if the target has no file at that path.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "GET /memory/builders/:builderId/file?path=... — Archon reads ONE of ANOTHER builder's files (content included). Audit-logged. 404 if the target has no file at that path.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `memory.read.any` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/memory/routes/memory.js",
+        "x-permissions": [
+          "memory.read.any"
+        ],
         "parameters": [
           {
             "name": "builderId",
@@ -6645,9 +7175,12 @@
           "memory"
         ],
         "summary": "GET /memory/builders/:builderId/files",
-        "description": "GET /memory/builders/:builderId/files — Archon lists ANOTHER builder's memory file metadata. Audit-logged.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "GET /memory/builders/:builderId/files — Archon lists ANOTHER builder's memory file metadata. Audit-logged.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `memory.read.any` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/memory/routes/memory.js",
+        "x-permissions": [
+          "memory.read.any"
+        ],
         "parameters": [
           {
             "name": "builderId",
@@ -6901,9 +7434,12 @@
           "modules"
         ],
         "summary": "GET /modules/submissions",
-        "description": "GET /api/gds/modules/submissions?status=&module_key= — the upstreaming review queue (task 1771 reads this). Metadata only — no file contents (a future GET .../:id can add a with-files fetch if the review UI needs it). rank: metic+archon — the review queue, same rank as filing into it.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "GET /api/gds/modules/submissions?status=&module_key= — the upstreaming review queue (task 1771 reads this). Metadata only — no file contents (a future GET .../:id can add a with-files fetch if the review UI needs it). rank: metic+archon — the review queue, same rank as filing into it. Gate: requirePermission('module.submit') — BV1.R104.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `module.submit` (all required).",
         "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/modules.js",
+        "x-permissions": [
+          "module.submit"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -6939,9 +7475,12 @@
           "modules"
         ],
         "summary": "POST /modules/:key/enable",
-        "description": "toggling a module changes running behavior for the whole instance, not just the caller.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "toggling a module changes running behavior for the whole instance, not just the caller. Gate: requirePermission('module.enable') — BV1.R104; the seeded rank-role makes the permission and the old rank floor identical (ADR 0151).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `module.enable` (all required).",
         "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/modules.js",
+        "x-permissions": [
+          "module.enable"
+        ],
         "parameters": [
           {
             "name": "key",
@@ -7002,9 +7541,12 @@
           "modules"
         ],
         "summary": "POST /modules/:key/submit",
-        "description": "POST /api/gds/modules/:key/submit — ADR 0107 §1 upstreaming submission. task 1770. Body: { signed_by?: \"Name <email>\" }. Re-runs the §4 AGPL/publish pre-check + requires a DCO-style sign-off against THIS box's OWN on-disk copy of modules/:key (the authoritative check — a local `bongos module check` pass on a builder's box is a courtesy, not proof, if the module's changes aren't committed + shipped + deployed here yet). signed_by records a NEW sign-off only if none is on file; an existing .upstream-signoff.json is reused as-is (not overwritten). rank: metic+archon — files into a shared review queue, not just a toggle for the caller.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "POST /api/gds/modules/:key/submit — ADR 0107 §1 upstreaming submission. task 1770. Body: { signed_by?: \"Name <email>\" }. Re-runs the §4 AGPL/publish pre-check + requires a DCO-style sign-off against THIS box's OWN on-disk copy of modules/:key (the authoritative check — a local `bongos module check` pass on a builder's box is a courtesy, not proof, if the module's changes aren't committed + shipped + deployed here yet). signed_by records a NEW sign-off only if none is on file; an existing .upstream-signoff.json is reused as-is (not overwritten). rank: metic+archon — files into a shared review queue, not just a toggle for the caller. Gate: requirePermission('module.submit') — BV1.R104.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `module.submit` (all required).",
         "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/modules.js",
+        "x-permissions": [
+          "module.submit"
+        ],
         "parameters": [
           {
             "name": "key",
@@ -7346,9 +7888,12 @@
           "override-requests"
         ],
         "summary": "GET /override-requests",
-        "description": "GET /override-requests?status=open — Archon queue. Status defaults to open; pass ?status=approved or ?status=denied for the resolved history. rank: archon — same gate as the audit log + Archon view.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "GET /override-requests?status=open — Archon queue. Status defaults to open; pass ?status=approved or ?status=denied for the resolved history. rank: archon — same gate as the audit log + Archon view.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `override_request.decide` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
+        "x-permissions": [
+          "override_request.decide"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -7384,9 +7929,12 @@
           "override-requests"
         ],
         "summary": "POST /override-requests/:id/decide",
-        "description": "POST /override-requests/:id/decide — body: { decision: 'approve'|'deny', note? } On approve, atomically flips the task completed→confirmed and awards the credits to the original requester (NOT the Archon). On deny, only the row updates; the task stays at completed and the builder must release or re-ship after fixing whatever the grader caught. rank: archon — grader-bypass authority; same gate as POST /tasks/:id/confirm.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "POST /override-requests/:id/decide — body: { decision: 'approve'|'deny', note? } On approve, atomically flips the task completed→confirmed and awards the credits to the original requester (NOT the Archon). On deny, only the row updates; the task stays at completed and the builder must release or re-ship after fixing whatever the grader caught. rank: archon — grader-bypass authority; same gate as POST /tasks/:id/confirm.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `override_request.decide` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
+        "x-permissions": [
+          "override_request.decide"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -7440,9 +7988,12 @@
           "projects"
         ],
         "summary": "GET /projects",
-        "description": "the full curation list (includes unfeatured + owner attribution).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "the full curation list (includes unfeatured + owner attribution). BV1.R105 left this on requireRank because `project.curate` was declared over the writes + GET /scouting, not over this read. ADR 0157 extends that atom's guards to name GET /projects and lowers its floor archon→metic, so the mapping now exists and the audience is the working rank.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `project.curate` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/platform-identity/routes/projects.js",
+        "x-permissions": [
+          "project.curate"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -7476,9 +8027,12 @@
           "projects"
         ],
         "summary": "POST /projects",
-        "description": "create / update a catalog entry (manual seed for hand-wired instances; federated projects auto-catalogue at registration).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "create / update a catalog entry (manual seed for hand-wired instances; federated projects auto-catalogue at registration).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `project.curate` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/platform-identity/routes/projects.js",
+        "x-permissions": [
+          "project.curate"
+        ],
         "requestBody": {
           "required": true,
           "content": {
@@ -7553,9 +8107,12 @@
           "projects"
         ],
         "summary": "POST /projects/invite",
-        "description": "invite a builder into a project (ADR 0141 §5, task #1002115). Pre-seeds a 'pending' membership the invitee accepts from My Projects. V1 invites by github_login and requires the invitee to already have a platform account (they build on some project); inviting someone entirely new to the platform (GitHub-id resolution) is a follow-up.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "invite a builder into a project (ADR 0141 §5, task #1002115). Pre-seeds a 'pending' membership the invitee accepts from My Projects. V1 invites by github_login and requires the invitee to already have a platform account (they build on some project); inviting someone entirely new to the platform (GitHub-id resolution) is a follow-up.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `project.curate` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/platform-identity/routes/projects.js",
+        "x-permissions": [
+          "project.curate"
+        ],
         "requestBody": {
           "required": true,
           "content": {
@@ -7595,9 +8152,12 @@
           "projects"
         ],
         "summary": "PATCH /projects/:id/featured",
-        "description": "the feature / unfeature control (the ADR 0141 §5 curation gate).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "the feature / unfeature control (the ADR 0141 §5 curation gate).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `project.curate` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/platform-identity/routes/projects.js",
+        "x-permissions": [
+          "project.curate"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -7658,9 +8218,12 @@
           "provisioning"
         ],
         "summary": "GET /provisioning/fleet",
-        "description": "GET /provisioning/fleet — the full instance roster across all owners. rank: archon (exposes every owner's instance + cost; the /boxes precedent).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "GET /provisioning/fleet — the full instance roster across all owners. rank: archon (exposes every owner's instance + cost; the /boxes precedent).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `provisioning.fleet.manage` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/provisioning/routes/provisioning.js",
+        "x-permissions": [
+          "provisioning.fleet.manage"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -7696,9 +8259,12 @@
           "provisioning"
         ],
         "summary": "GET /provisioning/fleet/cost-ledger",
-        "description": "GET /provisioning/fleet/cost-ledger — per-instance monthly estimate + total. rank: archon — cost oversight across the fleet (the /boxes/cost-ledger precedent). Declared among the archon routes (archon-first) for correct auditor classification.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "GET /provisioning/fleet/cost-ledger — per-instance monthly estimate + total. rank: archon — cost oversight across the fleet (the /boxes/cost-ledger precedent). Declared among the archon routes (archon-first) for correct auditor classification.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `provisioning.fleet.manage` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/provisioning/routes/provisioning.js",
+        "x-permissions": [
+          "provisioning.fleet.manage"
+        ],
         "responses": {
           "200": {
             "description": "Success."
@@ -7840,7 +8406,7 @@
           "provisioning"
         ],
         "summary": "POST /provisioning/instances",
-        "description": "POST /provisioning/instances — request a new instance. rank: any authenticated builder (own resource). ENQUEUES a 'provision' intent + records the request; the runner (task P3) does the real standup. Idempotent on slug for the SAME owner (re-request returns the existing row); a slug owned by ANOTHER builder → 409. Body: { slug (required), target_ref?, hosting_shape? (co-tenant|dedicated), domain?, tier? }.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "description": "POST /provisioning/instances — request a new instance. rank: any authenticated builder (own resource). ENQUEUES a 'provision' intent + records the request; the runner (task P3) does the real standup. Idempotent on slug for the SAME owner (re-request returns the existing row); a slug owned by ANOTHER builder → 409. Body: { slug (required), target_ref?, hosting_shape? (co-tenant|dedicated), domain?, tier?, onboard_mode? (greenfield|adopt) }. onboard_mode is LOAD-BEARING, not a label (task 1002562): the control-plane runner branches its repo scaffold on it. 'adopt' means target_ref is a repo the owner ALREADY has, so the runner must clone + layer onto its history instead of pushing a fresh tree at `main` (which an existing repo rejects as unrelated history). Absent → 'greenfield', the safe default.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
         "x-rank": "any-builder",
         "x-source": "modules/provisioning/routes/provisioning.js",
         "requestBody": {
@@ -7934,9 +8500,12 @@
           "provisioning"
         ],
         "summary": "POST /provisioning/instances/:id/force-teardown",
-        "description": "POST /provisioning/instances/:id/force-teardown — Archon tears down ANY instance. Trust-safe by the same mechanism as the owner's own teardown: it ENQUEUES a 'teardown' intent for the control-plane runner; the web tier never holds cloud tokens. rank: archon (acts on another owner's infrastructure). Declared among the archon routes (archon-first).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "POST /provisioning/instances/:id/force-teardown — Archon tears down ANY instance. Trust-safe by the same mechanism as the owner's own teardown: it ENQUEUES a 'teardown' intent for the control-plane runner; the web tier never holds cloud tokens. rank: archon (acts on another owner's infrastructure). Declared among the archon routes (archon-first).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `provisioning.fleet.manage` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/provisioning/routes/provisioning.js",
+        "x-permissions": [
+          "provisioning.fleet.manage"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -8661,9 +9230,12 @@
           "scouting"
         ],
         "summary": "GET /scouting",
-        "description": "the internal talent directory across every project. The Archon gate here is the load-bearing protection (\"NOT shown to builders\"): a non-Archon is 403'd before any cross-builder data is read.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "the internal talent directory across every project. The Archon gate here is the load-bearing protection (\"NOT shown to builders\"): a non-Archon is 403'd before any cross-builder data is read.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `project.curate` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/platform-identity/routes/scouting.js",
+        "x-permissions": [
+          "project.curate"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -8790,9 +9362,12 @@
           "security"
         ],
         "summary": "GET /security/adr",
-        "description": "GET /api/gds/security/adr Metic+ only. Returns the full security ADR as { adr_md, source, fetched_at } when the file is provisioned; otherwise 404 with a structured hint. The rank gate runs BEFORE the file-existence check so a Xenos sees 403 regardless of whether the document is provisioned — we don't want existence-or-not to leak below the rank line. rank: metic+archon — trust-tier access to the threat model + defenses inventory (ADR 0020).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "GET /api/gds/security/adr Metic+ only. Returns the full security ADR as { adr_md, source, fetched_at } when the file is provisioned; otherwise 404 with a structured hint. The rank gate runs BEFORE the file-existence check so a Xenos sees 403 regardless of whether the document is provisioned — we don't want existence-or-not to leak below the rank line. rank: metic+archon — trust-tier access to the threat model + defenses inventory (ADR 0020). Gate: requirePermission('security.report.file') — BV1.R104; the seeded rank-role makes the permission and the old rank floor identical (ADR 0151). NB the 403 code on this route is `permission_forbidden`, not `rank_forbidden` (ADR 0020 §\"A Xenos hitting the endpoint\" updated to match).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `security.report.file` (all required).",
         "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/security.js",
+        "x-permissions": [
+          "security.report.file"
+        ],
         "responses": {
           "200": {
             "description": "Success."
@@ -8821,9 +9396,12 @@
           "security"
         ],
         "summary": "GET /security/docs",
-        "description": "GET /api/gds/security/docs — list doc METADATA (no content). rank: archon — index of exploit-detail engagement reports.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "GET /api/gds/security/docs — list doc METADATA (no content). rank: archon — index of exploit-detail engagement reports. Gate: requirePermission('security.report.adjudicate') — BV1.R104.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `security.report.adjudicate` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/security.js",
+        "x-permissions": [
+          "security.report.adjudicate"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -8857,9 +9435,12 @@
           "security"
         ],
         "summary": "POST /security/docs",
-        "description": "POST /api/gds/security/docs — upsert a doc by slug. The director uploads each dated engagement report here after deploy. Body: { slug, title, content_md }. content_md uses a large explicit cap (full reports), NOT the small LIMITS.DESCRIPTION. Returns 201 + the row. rank: archon — writes exploit-detail report bodies.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "POST /api/gds/security/docs — upsert a doc by slug. The director uploads each dated engagement report here after deploy. Body: { slug, title, content_md }. content_md uses a large explicit cap (full reports), NOT the small LIMITS.DESCRIPTION. Returns 201 + the row. rank: archon — writes exploit-detail report bodies. Gate: requirePermission('security.report.adjudicate') — BV1.R104.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `security.report.adjudicate` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/security.js",
+        "x-permissions": [
+          "security.report.adjudicate"
+        ],
         "requestBody": {
           "required": true,
           "content": {
@@ -8906,9 +9487,12 @@
           "security"
         ],
         "summary": "GET /security/docs/:slug",
-        "description": "GET /api/gds/security/docs/:slug — one doc WITH content, or 404. rank: archon — reads the full exploit-detail report body.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "GET /api/gds/security/docs/:slug — one doc WITH content, or 404. rank: archon — reads the full exploit-detail report body. Gate: requirePermission('security.report.adjudicate') — BV1.R104.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `security.report.adjudicate` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "src/bongos/routes/security.js",
+        "x-permissions": [
+          "security.report.adjudicate"
+        ],
         "parameters": [
           {
             "name": "slug",
@@ -8958,9 +9542,12 @@
           "security"
         ],
         "summary": "GET /security/reports",
-        "description": "GET /api/bongos/security/reports?status=<status> Archon-only, newest-first. The Archon dashboard view fetches this on load + after each adjudication action. ?status= narrows to one lifecycle bucket (open / repro_attempted / confirmed / disputed / fixed / wontfix); omitted = all. rank: archon — adjudication surface; reading every builder's reports.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "GET /api/bongos/security/reports?status=<status> Archon-only, newest-first. The Archon dashboard view fetches this on load + after each adjudication action. ?status= narrows to one lifecycle bucket (open / repro_attempted / confirmed / disputed / fixed / wontfix); omitted = all. rank: metic+archon — adjudication surface; reading every builder's reports. BV1.R105 left this on requireRank because `security.report.adjudicate` was declared over the adjudication WRITES + /security/docs CRUD, not over this read. ADR 0157 extends that atom's guards to name GET /security/reports and lowers its floor archon→metic, so the mapping now exists and the audience is the working rank.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `security.report.adjudicate` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/security/routes/reports.js",
+        "x-permissions": [
+          "security.report.adjudicate"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -8994,9 +9581,12 @@
           "security"
         ],
         "summary": "POST /security/reports",
-        "description": "POST /api/bongos/security/reports — file a new vulnerability report. V3.R64 (task 283). Used by the /builder-redteam skill. Metic+ only — Xenos can't open the bounty surface (the rank gate keeps the noise-floor sane; a Xenos who finds a real flaw can flag it through normal channels). Body: { target, severity, title, description?, repro_steps_md? } Returns 201 + the inserted row (status='open' by default; the Archon view picks it up immediately). rank: metic+archon — bounty intake; Xenos kept out by design (V3.R63).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "POST /api/bongos/security/reports — file a new vulnerability report. V3.R64 (task 283). Used by the /builder-redteam skill. Metic+ only — Xenos can't open the bounty surface (the rank gate keeps the noise-floor sane; a Xenos who finds a real flaw can flag it through normal channels). Body: { target, severity, title, description?, repro_steps_md? } Returns 201 + the inserted row (status='open' by default; the Archon view picks it up immediately). rank: metic+archon — bounty intake; Xenos kept out by design (V3.R63).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `security.report.file` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/security/routes/reports.js",
+        "x-permissions": [
+          "security.report.file"
+        ],
         "requestBody": {
           "required": true,
           "content": {
@@ -9043,9 +9633,12 @@
           "security"
         ],
         "summary": "POST /security/reports/:id/confirm",
-        "description": "POST /api/bongos/security/reports/:id/confirm Body: { drachmae_awarded?: integer } — defaults to the severity tier bounty if omitted. Marks the report confirmed, stamps confirmed_at, and sets drachmae_awarded. rank: archon — confirms a payout-eligible report.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "POST /api/bongos/security/reports/:id/confirm Body: { drachmae_awarded?: integer } — defaults to the severity tier bounty if omitted. Marks the report confirmed, stamps confirmed_at, and sets drachmae_awarded. rank: archon — confirms a payout-eligible report.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `security.report.adjudicate` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/security/routes/reports.js",
+        "x-permissions": [
+          "security.report.adjudicate"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -9106,9 +9699,12 @@
           "security"
         ],
         "summary": "POST /security/reports/:id/dispute",
-        "description": "POST /api/bongos/security/reports/:id/dispute Marks the report disputed and clears drachmae_awarded. rank: archon — dispute adjudication.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "POST /api/bongos/security/reports/:id/dispute Marks the report disputed and clears drachmae_awarded. rank: archon — dispute adjudication.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `security.report.adjudicate` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/security/routes/reports.js",
+        "x-permissions": [
+          "security.report.adjudicate"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -9126,13 +9722,134 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PostSecurityReportsIdDisputeResponse"
+                  "$ref": "#/components/schemas/PostSecurityReportsIdDisputeResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/security/reports/{id}/fix": {
+      "post": {
+        "operationId": "post_security_reports_id_fix",
+        "tags": [
+          "security"
+        ],
+        "summary": "POST /security/reports/:id/fix",
+        "description": "POST /api/bongos/security/reports/:id/fix Marks the report fixed and stamps fixed_at. Does not change fix_task_id — link that separately via /link-fix. rank: archon — fix-confirmation adjudication.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `security.report.adjudicate` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/security/routes/reports.js",
+        "x-permissions": [
+          "security.report.adjudicate"
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostSecurityReportsIdFixResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/security/reports/{id}/link-fix": {
+      "post": {
+        "operationId": "post_security_reports_id_link_fix",
+        "tags": [
+          "security"
+        ],
+        "summary": "POST /security/reports/:id/link-fix",
+        "description": "POST /api/bongos/security/reports/:id/link-fix Body: { task_id: integer } — attaches a fix-task FK. Doesn't change status (a confirmed report can have a linked fix-task while still open work). 422 if the referenced task doesn't exist. rank: archon — linking a report to its fix-task in the queue.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `security.report.adjudicate` (all required).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/security/routes/reports.js",
+        "x-permissions": [
+          "security.report.adjudicate"
+        ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostSecurityReportsIdLinkFixRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostSecurityReportsIdLinkFixResponse"
                 }
               }
             }
           },
           "400": {
-            "$ref": "#/components/responses/BadRequest"
+            "$ref": "#/components/responses/ValidationFailed"
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
@@ -9151,34 +9868,23 @@
         ]
       }
     },
-    "/security/reports/{id}/fix": {
-      "post": {
-        "operationId": "post_security_reports_id_fix",
+    "/security/scans": {
+      "get": {
+        "operationId": "get_security_scans",
         "tags": [
           "security"
         ],
-        "summary": "POST /security/reports/:id/fix",
-        "description": "POST /api/bongos/security/reports/:id/fix Marks the report fixed and stamps fixed_at. Does not change fix_task_id — link that separately via /link-fix. rank: archon — fix-confirmation adjudication.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
-        "x-source": "modules/security/routes/reports.js",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Path parameter `id`."
-          }
-        ],
+        "summary": "GET /security/scans",
+        "description": "GET /api/bongos/security/scans?content_hash=<64 hex> \"Have these exact bytes been scanned before, and what did the scan say?\" Newest first. Rows carry structure only, so reading them can never expose the reader to the scanned artifact's content. rank: any-builder — deliberately open to every rank (see header).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/security/routes/scans.js",
         "responses": {
           "200": {
             "description": "Success.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PostSecurityReportsIdFixResponse"
+                  "$ref": "#/components/schemas/GetSecurityScansResponse"
                 }
               }
             }
@@ -9191,9 +9897,6 @@
           },
           "403": {
             "$ref": "#/components/responses/Forbidden"
-          },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
           }
         },
         "security": [
@@ -9201,35 +9904,22 @@
             "builderSession": []
           }
         ]
-      }
-    },
-    "/security/reports/{id}/link-fix": {
+      },
       "post": {
-        "operationId": "post_security_reports_id_link_fix",
+        "operationId": "post_security_scans",
         "tags": [
           "security"
         ],
-        "summary": "POST /security/reports/:id/link-fix",
-        "description": "POST /api/bongos/security/reports/:id/link-fix Body: { task_id: integer } — attaches a fix-task FK. Doesn't change status (a confirmed report can have a linked fix-task while still open work). 422 if the referenced task doesn't exist. rank: archon — linking a report to its fix-task in the queue.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
-        "x-source": "modules/security/routes/reports.js",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string"
-            },
-            "description": "Path parameter `id`."
-          }
-        ],
+        "summary": "POST /security/scans",
+        "description": "POST /api/bongos/security/scans — record one scan run. Body: structure only, never quoted target content — the deep checks (one-line claims, fence-marker rejection, scrubbing, verdict/completion coupling) live in scanStore.normalizeScanPayload; the schema here rejects unknown/typo'd top-level fields (strict default) and pins basic shapes. rank: metic+archon — a verdict-shaped write is a trust-shaped write.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "x-rank": "metic+archon",
+        "x-source": "modules/security/routes/scans.js",
         "requestBody": {
           "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/PostSecurityReportsIdLinkFixRequest"
+                "$ref": "#/components/schemas/PostSecurityScansRequest"
               }
             }
           },
@@ -9241,7 +9931,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PostSecurityReportsIdLinkFixResponse"
+                  "$ref": "#/components/schemas/PostSecurityScansResponse"
                 }
               }
             }
@@ -9254,9 +9944,6 @@
           },
           "403": {
             "$ref": "#/components/responses/Forbidden"
-          },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
           }
         },
         "security": [
@@ -9402,9 +10089,12 @@
           "sessions"
         ],
         "summary": "GET /sessions/search",
-        "description": "cross-builder corpus search (BFG-principal posture until 6C.1).\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "cross-builder corpus search (BFG-principal posture until 6C.1).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `session.search` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/sessions/routes/sessions.js",
+        "x-permissions": [
+          "session.search"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -9758,9 +10448,12 @@
           "tasks"
         ],
         "summary": "POST /tasks",
-        "description": "Task create/promote/edit (plan/scope mutation) is Metic+ as of ADR 0090 (owner decision 2026-06-26): a Metic who can run idea-triage may also seed + shape tasks. Was Archon-only (task task 106 / ADR 0016; three-rank model task 360 / ADR 0018). A Xenos/Thetes still cannot author — they file ideas. Setting rank and closing versions stay Archon. The every-route audit is task task 231 (V3.R06). rank: metic+archon — create work (plan/scope mutation); ADR 0090 (was ADR 0016/0018 archon).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "Task create/promote/edit (plan/scope mutation) is Metic+ as of ADR 0090 (owner decision 2026-06-26): a Metic who can run idea-triage may also seed + shape tasks. Was Archon-only (task task 106 / ADR 0016; three-rank model task 360 / ADR 0018). A Xenos/Thetes still cannot author — they file ideas. Setting rank and closing versions stay Archon. The every-route audit is task task 231 (V3.R06). rank: metic+archon — create work (plan/scope mutation); ADR 0090 (was ADR 0016/0018 archon).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `task.create` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
+        "x-permissions": [
+          "task.create"
+        ],
         "requestBody": {
           "required": true,
           "content": {
@@ -9876,9 +10569,12 @@
           "tasks"
         ],
         "summary": "POST /tasks/newcomer-restock",
-        "description": "POST /tasks/newcomer-restock (task 1168) — bring every evergreen newcomer chore's standing pool up to its configured floor. This is the SEED + manual BACKSTOP for the on-claim restock (the live mechanism is the post-claim hook in routes/claims.js). Archon-gated like all task creation (ADR 0016). Must be registered BEFORE GET /tasks/:id so ':id' doesn't swallow the literal.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "POST /tasks/newcomer-restock (task 1168) — bring every evergreen newcomer chore's standing pool up to its configured floor. This is the SEED + manual BACKSTOP for the on-claim restock (the live mechanism is the post-claim hook in routes/claims.js). Archon-gated like all task creation (ADR 0016). Must be registered BEFORE GET /tasks/:id so ':id' doesn't swallow the literal.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `task.newcomer_restock` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
+        "x-permissions": [
+          "task.newcomer_restock"
+        ],
         "responses": {
           "200": {
             "description": "Success.",
@@ -9952,9 +10648,12 @@
           "tasks"
         ],
         "summary": "POST /tasks/peer-votes/tally",
-        "description": "POST /tasks/peer-votes/tally — fold matured votes (≥7 days old, not yet counted) into karma_log, one net row per shipping builder, then mark them tallied. Idempotent + transactional. Driven by the weekly cron (.claude/scheduled-tasks/peer-vote-tally/). Archon-gated — it writes karma. rank: archon — writes karma_log on others' behalf; scope-shaping reputation. The tally transaction lives in db.tallyPeerVotes() (task 1382, ADR 0078 amendment) so this route AND the server-internal weekly timer (the carved autonomy module's poller, modules/autonomy/pollers/routine-timers.js, which reaches it via the doorway api.tallyPeerVotes — BV1.R83) share one code path and can never diverge. This route keeps the Archon gate (the HTTP surface stays Archon-only); the in-process timer has no requester to authorize.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "POST /tasks/peer-votes/tally — fold matured votes (≥7 days old, not yet counted) into karma_log, one net row per shipping builder, then mark them tallied. Idempotent + transactional. Driven by the weekly cron (.claude/scheduled-tasks/peer-vote-tally/). Archon-gated — it writes karma. rank: archon — writes karma_log on others' behalf; scope-shaping reputation. The tally transaction lives in db.tallyPeerVotes() (task 1382, ADR 0078 amendment) so this route AND the server-internal weekly timer (the carved autonomy module's poller, modules/autonomy/pollers/routine-timers.js, which reaches it via the doorway api.tallyPeerVotes — BV1.R83) share one code path and can never diverge. This route keeps the Archon gate (the HTTP surface stays Archon-only); the in-process timer has no requester to authorize.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `task.peer_votes.tally` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
+        "x-permissions": [
+          "task.peer_votes.tally"
+        ],
         "responses": {
           "200": {
             "description": "Success."
@@ -10026,9 +10725,12 @@
           "tasks"
         ],
         "summary": "PATCH /tasks/:id",
-        "description": "PATCH /tasks/:id — supports body.parent_task_id (V2 C2), body.kind (V2 B1), body.discipline (mig 014), body.parallel_safe (mig 028), and body.newcomer_friendly (task 360 / ADR 0018 + V3.R15 task 239 — body.touches was removed in touches[] cleanup [4/8] (task 879) along with the drift scanner — open a task to the Xenos sandbox; alias body.xenos_claimable accepted for pre-rename callers). Pass parent_task_id: null to detach; parallel_safe accepts true|false|null; newcomer_friendly is a boolean. Validation lives in hierarchy.js for parent; the rest are validated inline. rank: metic+archon — edit work (incl. newcomer_friendly flag); ADR 0090 (was ADR 0016 archon).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "PATCH /tasks/:id — supports body.parent_task_id (V2 C2), body.kind (V2 B1), body.discipline (mig 014), body.parallel_safe (mig 028), and body.newcomer_friendly (task 360 / ADR 0018 + V3.R15 task 239 — body.touches was removed in touches[] cleanup [4/8] (task 879) along with the drift scanner — open a task to the Xenos sandbox; alias body.xenos_claimable accepted for pre-rename callers). Pass parent_task_id: null to detach; parallel_safe accepts true|false|null; newcomer_friendly is a boolean. Validation lives in hierarchy.js for parent; the rest are validated inline. rank: metic+archon — edit work (incl. newcomer_friendly flag); ADR 0090 (was ADR 0016 archon).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `task.edit` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
+        "x-permissions": [
+          "task.edit"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -10082,9 +10784,12 @@
           "tasks"
         ],
         "summary": "POST /tasks/:id/abandon",
-        "description": "POST /tasks/:id/abandon — terminal \"retire this task\" transition (task 987). The lifecycle had promote/ship/confirm/resolve but no first-class way to KILL a task that is no longer relevant: the only paths to status='abandoned' were offboarding a builder or a raw SQL UPDATE, so stale/moot tasks lingered in 'ready' as claimable noise. Refuses on a shipped task (immutable history) and on a task with an active claim (release it first); idempotent on an already- abandoned task. The abandon + its `reason` land in audit_log via the writing middleware, so the ledger keeps a record of who retired what. rank: metic+archon — scope removal; the inverse of /promote, and re-ranked to match it (ADR 0152, was archon under ADR 0090). A Metic who may author, shape, and promote work may also retire it: leaving the kill switch an Archon rung higher than the create switch only forced the owner to clean up after the triage they already delegated. Not one-way any more — /promote restores an abandoned task to backlog at the same rank — and the guards below (shipped refused, active claim refused) plus the audit_log entry are unchanged.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "POST /tasks/:id/abandon — terminal \"retire this task\" transition (task 987). The lifecycle had promote/ship/confirm/resolve but no first-class way to KILL a task that is no longer relevant: the only paths to status='abandoned' were offboarding a builder or a raw SQL UPDATE, so stale/moot tasks lingered in 'ready' as claimable noise. Refuses on a shipped task (immutable history) and on a task with an active claim (release it first); idempotent on an already- abandoned task. The abandon + its `reason` land in audit_log via the writing middleware, so the ledger keeps a record of who retired what. rank: metic+archon — scope removal; the inverse of /promote, and re-ranked to match it (ADR 0152, was archon under ADR 0090). A Metic who may author, shape, and promote work may also retire it: leaving the kill switch an Archon rung higher than the create switch only forced the owner to clean up after the triage they already delegated. Not one-way any more — /promote restores an abandoned task to backlog at the same rank — and the guards below (shipped refused, active claim refused) plus the audit_log entry are unchanged.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `task.abandon` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
+        "x-permissions": [
+          "task.abandon"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -10307,9 +11012,12 @@
           "tasks"
         ],
         "summary": "POST /tasks/:id/criteria",
-        "description": "POST /tasks/:id/criteria — body: { criterion_ids: [ref, ...] } OR { criterion_id: ref }. Metic+. rank: metic+archon — links a task it can author to a criterion; mirrors POST deps (ADR 0090).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "POST /tasks/:id/criteria — body: { criterion_ids: [ref, ...] } OR { criterion_id: ref }. Metic+. rank: metic+archon — links a task it can author to a criterion; mirrors POST deps (ADR 0090).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `task.criterion.manage` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
+        "x-permissions": [
+          "task.criterion.manage"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -10370,9 +11078,12 @@
           "tasks"
         ],
         "summary": "DELETE /tasks/:id/criteria/:criterionId",
-        "description": "DELETE /tasks/:id/criteria/:criterionId — removes one link (criterionId is the numeric done_when_criteria.id, mirroring DELETE deps/:depId). rank: metic+archon — removes a criterion↔task edge; task-shaping, Metic+ (ADR 0090).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "DELETE /tasks/:id/criteria/:criterionId — removes one link (criterionId is the numeric done_when_criteria.id, mirroring DELETE deps/:depId). rank: metic+archon — removes a criterion↔task edge; task-shaping, Metic+ (ADR 0090).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `task.criterion.manage` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
+        "x-permissions": [
+          "task.criterion.manage"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -10431,9 +11142,12 @@
           "tasks"
         ],
         "summary": "POST /tasks/:id/demote",
-        "description": "POST /tasks/:id/demote — the strict inverse of /promote: flip a task ready→backlog and nothing else. Use case (task 1223): a dependency-gated task that was wrongly promoted to ready needs to go back to backlog without hand-SQL on prod. Mirrors /promote's auth (Metic+ — scope mutation, ADR 0090). Strictly ready→backlog: refuse any other current status (blocked, active, or any later lifecycle state). A claimed task is `active`, so this gate also refuses demoting work that's already in flight — demote is not a way to yank a task out from under its claim holder. No reward side-effects (the reward gate is a promote-only concern; backlog is the pre-workable state). rank: metic+archon — ready→backlog demotion; scope mutation; mirrors /promote (ADR 0090).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "POST /tasks/:id/demote — the strict inverse of /promote: flip a task ready→backlog and nothing else. Use case (task 1223): a dependency-gated task that was wrongly promoted to ready needs to go back to backlog without hand-SQL on prod. Mirrors /promote's auth (Metic+ — scope mutation, ADR 0090). Strictly ready→backlog: refuse any other current status (blocked, active, or any later lifecycle state). A claimed task is `active`, so this gate also refuses demoting work that's already in flight — demote is not a way to yank a task out from under its claim holder. No reward side-effects (the reward gate is a promote-only concern; backlog is the pre-workable state). rank: metic+archon — ready→backlog demotion; scope mutation; mirrors /promote (ADR 0090).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `task.demote` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
+        "x-permissions": [
+          "task.demote"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -10533,9 +11247,12 @@
           "tasks"
         ],
         "summary": "POST /tasks/:id/dependencies",
-        "description": "POST /tasks/:id/dependencies — body: { depends_on_task_id } OR { depends_on_task_ids: [N, ...] } Returns 409 with code='cycle' if accepting would create a cycle. rank: metic+archon — task-shaping; Metic may wire deps of a task it can author (ADR 0090).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "POST /tasks/:id/dependencies — body: { depends_on_task_id } OR { depends_on_task_ids: [N, ...] } Returns 409 with code='cycle' if accepting would create a cycle. rank: metic+archon — task-shaping; Metic may wire deps of a task it can author (ADR 0090).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `task.dependency.manage` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
+        "x-permissions": [
+          "task.dependency.manage"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -10594,9 +11311,12 @@
           "tasks"
         ],
         "summary": "PUT /tasks/:id/dependencies",
-        "description": "PUT /tasks/:id/dependencies — replace the full dep set. body: { depends_on_task_ids: [N, ...] } rank: metic+archon — replaces the full dep set; task-shaping, Metic+ (ADR 0090).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "PUT /tasks/:id/dependencies — replace the full dep set. body: { depends_on_task_ids: [N, ...] } rank: metic+archon — replaces the full dep set; task-shaping, Metic+ (ADR 0090).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `task.dependency.manage` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
+        "x-permissions": [
+          "task.dependency.manage"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -10657,9 +11377,12 @@
           "tasks"
         ],
         "summary": "DELETE /tasks/:id/dependencies/:depId",
-        "description": "DELETE /tasks/:id/dependencies/:depId — removes the edge. rank: metic+archon — removes a dep edge; task-shaping, Metic+ (ADR 0090).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "DELETE /tasks/:id/dependencies/:depId — removes the edge. rank: metic+archon — removes a dep edge; task-shaping, Metic+ (ADR 0090).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `task.dependency.manage` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
+        "x-permissions": [
+          "task.dependency.manage"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -10837,9 +11560,12 @@
           "tasks"
         ],
         "summary": "POST /tasks/:id/promote",
-        "description": "backlog→ready promotion; scope mutation; ADR 0090 (was archon). Also the UN-ABANDON path (ADR 0152): 'abandoned' → 'backlog'. When abandon moved down to Metic+ it needed an undo at the same rank, or a Metic's mis-retire would be unrecoverable without Archon SQL (no other route restores an abandoned task — PATCH refuses `status` outright). A restore lands in **backlog**, never straight to ready: the task was retired for a reason, so it re-enters as un-workable and takes a second, deliberate promote to become claimable again.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "backlog→ready promotion; scope mutation; ADR 0090 (was archon). Also the UN-ABANDON path (ADR 0152): 'abandoned' → 'backlog'. When abandon moved down to Metic+ it needed an undo at the same rank, or a Metic's mis-retire would be unrecoverable without Archon SQL (no other route restores an abandoned task — PATCH refuses `status` outright). A restore lands in **backlog**, never straight to ready: the task was retired for a reason, so it re-enters as un-workable and takes a second, deliberate promote to become claimable again.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `task.promote` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
+        "x-permissions": [
+          "task.promote"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -11042,9 +11768,12 @@
           "tasks"
         ],
         "summary": "POST /tasks/:id/vote",
-        "description": "POST /tasks/:id/vote { vote: 1 | -1 | 0 } — cast/change/clear a peer vote on a confirmed/shipped task. Metic+ only (Xenos read-only on the project). - 403 anti-self-vote if the caller shipped the task - 409 if the task isn't votable, or the vote was already folded into karma - vote: 0 clears (deletes the row, only while still untallied) rank: metic+archon — a trusted-builder reputation action.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "POST /tasks/:id/vote { vote: 1 | -1 | 0 } — cast/change/clear a peer vote on a confirmed/shipped task. Metic+ only (Xenos read-only on the project). - 403 anti-self-vote if the caller shipped the task - 409 if the task isn't votable, or the vote was already folded into karma - vote: 0 clears (deletes the row, only while still untallied) rank: metic+archon — a trusted-builder reputation action.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `task.vote` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/tasks.js",
+        "x-permissions": [
+          "task.vote"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -11131,9 +11860,12 @@
           "versions"
         ],
         "summary": "POST /versions",
-        "description": "POST /versions — create a version + its done-when criteria in one call. The seed primitive `bongos init` (task 1204 / R65) uses so a fresh instance needs no hand-written seed-*.js script. Archon-only: creating a version is a plan/scope mutation, same gate as POST /tasks (ADR 0016). rank: archon — creates a version + its done-when criteria.\n\n**Rank:** `archon` — Archon only (the single owner — ratification, infra, rank changes).",
-        "x-rank": "archon",
+        "description": "POST /versions — create a version + its done-when criteria in one call. The seed primitive `bongos init` (task 1204 / R65) uses so a fresh instance needs no hand-written seed-*.js script. Archon-only: creating a version is a plan/scope mutation, same gate as POST /tasks (ADR 0016). rank: archon — creates a version + its done-when criteria.\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `version.create` (all required).",
+        "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/versions.js",
+        "x-permissions": [
+          "version.create"
+        ],
         "requestBody": {
           "required": true,
           "content": {
@@ -11276,9 +12008,12 @@
           "versions"
         ],
         "summary": "POST /versions/:id/done-when",
-        "description": "Auth (Metic+, then the goal's own authority): create a done-when criterion at RUNTIME. ADR 0105 moved scope-truth seeds (versions/goals/criteria) out of the normal migration path, so a brand-new criterion on a RUNNING instance can no longer be added by a plain migration (migrations/instance/ applies only under the owner opt-in GDS_APPLY_INSTANCE_SEEDS=1, a DR step). This is the vector a planning session uses to add a criterion to a live version WITHOUT a droplet migrate. ADR 0154 — authority over a GOAL's criteria follows GOAL OWNERSHIP, not global rank. A Metic who may create the goal (POST /goals) and author the tasks under it (POST /tasks, ADR 0090) may now write the criteria those tasks gate — but only inside a goal they own or manage. Deliberately NOT a flat re-rank: - An unsatisfied criterion permanently blocks version close (version-close.js counts satisfied === total per VERSION, regardless of goal) and goal auto-achieve (db.achieveGoalIfComplete). There is NO delete route, so it cannot be undone via the API — the same backward ratchet as unsatisfy, which stays Archon. - So a non-Archon must name a goal_id (version-level criteria stay Archon), must be that goal's OWNER or MANAGER (isGoalOwnerOrManager — the same predicate behind visibility/invite/role management), and the goal must be open on a planning/building version. That bounds the blast radius to a workspace they already hold. An unauthorized caller is masked behind bad_goal_id so the route is not an existence oracle (ADR 0112). Pinned in route-rank-check.MODULE_EXPECTED_RANKS. rank: metic+archon — criterion create, walled by goal ownership (ADR 0154).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).",
+        "description": "Auth (Metic+, then the goal's own authority): create a done-when criterion at RUNTIME. ADR 0105 moved scope-truth seeds (versions/goals/criteria) out of the normal migration path, so a brand-new criterion on a RUNNING instance can no longer be added by a plain migration (migrations/instance/ applies only under the owner opt-in GDS_APPLY_INSTANCE_SEEDS=1, a DR step). This is the vector a planning session uses to add a criterion to a live version WITHOUT a droplet migrate. ADR 0154 — authority over a GOAL's criteria follows GOAL OWNERSHIP, not global rank. A Metic who may create the goal (POST /goals) and author the tasks under it (POST /tasks, ADR 0090) may now write the criteria those tasks gate — but only inside a goal they own or manage. Deliberately NOT a flat re-rank: - An unsatisfied criterion permanently blocks version close (version-close.js counts satisfied === total per VERSION, regardless of goal) and goal auto-achieve (db.achieveGoalIfComplete). There is NO delete route, so it cannot be undone via the API — the same backward ratchet as unsatisfy, which stays Archon. - So a non-Archon must name a goal_id (version-level criteria stay Archon), must be that goal's OWNER or MANAGER (isGoalOwnerOrManager — the same predicate behind visibility/invite/role management), and the goal must be open on a planning/building version. That bounds the blast radius to a workspace they already hold. An unauthorized caller is masked behind bad_goal_id so the route is not an existence oracle (ADR 0112). Pinned in route-rank-check.MODULE_EXPECTED_RANKS. rank: metic+archon — criterion create, walled by goal ownership (ADR 0154).\n\n**Rank:** `metic+archon` — Metic or Archon rank (review/triage powers).\n\n**Permissions:** `criterion.create` (all required).",
         "x-rank": "metic+archon",
         "x-source": "modules/lifecycle/routes/done-when.js",
+        "x-permissions": [
+          "criterion.create"
+        ],
         "parameters": [
           {
             "name": "id",
@@ -11423,6 +12158,40 @@
           "ok"
         ]
       },
+      "DeleteGovernanceAssignmentsBuilderIdRoleKeyResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "builder_id": {},
+          "role_key": {},
+          "removed": {}
+        },
+        "required": [
+          "ok",
+          "builder_id",
+          "role_key",
+          "removed"
+        ]
+      },
+      "DeleteGovernanceRolesRoleKeyPermissionsPermissionKeyResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "role_key": {},
+          "permission_key": {},
+          "removed": {}
+        },
+        "required": [
+          "ok",
+          "role_key",
+          "permission_key",
+          "removed"
+        ]
+      },
       "DeleteMemoryFileResponse": {
         "type": "object",
         "properties": {
@@ -11829,6 +12598,35 @@
           "goals"
         ]
       },
+      "GetGovernanceAssignmentsResponse": {
+        "type": "object",
+        "properties": {
+          "assignments": {}
+        },
+        "required": [
+          "assignments"
+        ]
+      },
+      "GetGovernancePermissionsResponse": {
+        "type": "object",
+        "properties": {
+          "permissions": {},
+          "principals": {}
+        },
+        "required": [
+          "permissions",
+          "principals"
+        ]
+      },
+      "GetGovernanceRolesResponse": {
+        "type": "object",
+        "properties": {
+          "roles": {}
+        },
+        "required": [
+          "roles"
+        ]
+      },
       "GetGradesByBuilderResponse": {
         "type": "object",
         "properties": {
@@ -12437,6 +13235,15 @@
           "statuses"
         ]
       },
+      "GetSecurityScansResponse": {
+        "type": "object",
+        "properties": {
+          "scans": {}
+        },
+        "required": [
+          "scans"
+        ]
+      },
       "GetSessionsIdResponse": {
         "type": "object",
         "properties": {
@@ -13272,10 +14079,12 @@
         "properties": {
           "ok": {
             "type": "boolean"
-          }
+          },
+          "blocked": {}
         },
         "required": [
-          "ok"
+          "ok",
+          "blocked"
         ]
       },
       "PostBlockersIdResolveRequest": {
@@ -14326,6 +15135,58 @@
           "succeeds_goal_id"
         ]
       },
+      "PostGovernanceAssignmentsRequest": {
+        "type": "object",
+        "properties": {
+          "builder_id": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "role_key": {
+            "type": "string",
+            "minLength": 2,
+            "maxLength": 64
+          }
+        },
+        "required": [
+          "builder_id",
+          "role_key"
+        ],
+        "additionalProperties": false
+      },
+      "PostGovernanceRolesRequest": {
+        "type": "object",
+        "properties": {
+          "role_key": {
+            "type": "string",
+            "minLength": 2,
+            "maxLength": 64
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 2000
+          }
+        },
+        "required": [
+          "role_key",
+          "label"
+        ],
+        "additionalProperties": false
+      },
+      "PostGovernanceRolesResponse": {
+        "type": "object",
+        "properties": {
+          "role": {}
+        },
+        "required": [
+          "role"
+        ]
+      },
       "PostInboxIdRatifyRequest": {
         "type": "object",
         "properties": {
@@ -14851,6 +15712,10 @@
           "tier": {
             "type": "string",
             "maxLength": 40
+          },
+          "onboard_mode": {
+            "type": "string",
+            "maxLength": 20
           }
         },
         "required": [
@@ -15035,6 +15900,96 @@
           "bounty_table"
         ]
       },
+      "PostSecurityScansRequest": {
+        "type": "object",
+        "properties": {
+          "target_url": {
+            "type": "string",
+            "minLength": 9,
+            "maxLength": 2048
+          },
+          "artifact_kind": {
+            "type": "string"
+          },
+          "resolved_sha": {
+            "type": "string",
+            "maxLength": 40
+          },
+          "content_hash": {
+            "type": "string",
+            "maxLength": 64
+          },
+          "file_count": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "total_bytes": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "tier": {
+            "type": "string"
+          },
+          "verdict": {
+            "type": "string"
+          },
+          "completion": {
+            "type": "string"
+          },
+          "abort_code": {
+            "type": "string",
+            "maxLength": 64
+          },
+          "findings_critical": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "findings_high": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "findings_medium": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "findings_low": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "findings_summary": {
+            "type": "array"
+          },
+          "action_taken": {
+            "type": "string"
+          },
+          "engine_version": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
+          }
+        },
+        "required": [
+          "target_url",
+          "artifact_kind",
+          "tier",
+          "completion",
+          "engine_version"
+        ],
+        "additionalProperties": false
+      },
+      "PostSecurityScansResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "scan": {}
+        },
+        "required": [
+          "ok",
+          "scan"
+        ]
+      },
       "PostSessionOptimizeRequest": {
         "type": "object",
         "properties": {
@@ -15703,6 +16658,10 @@
             "type": "string",
             "maxLength": 32
           },
+          "track": {
+            "type": "string",
+            "maxLength": 16
+          },
           "done_when": {
             "type": "string",
             "maxLength": 8000
@@ -15733,6 +16692,23 @@
           "criteria"
         ]
       },
+      "PutGovernanceRolesRoleKeyPermissionsPermissionKeyResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "role_key": {},
+          "permission_key": {},
+          "granted": {}
+        },
+        "required": [
+          "ok",
+          "role_key",
+          "permission_key",
+          "granted"
+        ]
+      },
       "PutTasksIdDependenciesRequest": {
         "type": "object",
         "properties": {
@@ -15884,9 +16860,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 258,
-  "x-schema-count": 288,
+  "x-endpoint-count": 268,
+  "x-schema-count": 300,
   "x-undocumented-bodies": 8,
-  "x-response-schemas": 194,
+  "x-response-schemas": 203,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }