@bongos/core 1.19.158 → 1.19.159

package/modules/governance/catalog.js

@@ -9,14 +9,23 @@
 // docs/governance/authority-sweep-2026-07-24.md.
 //
 // Two orthogonal axes per permission:
-//   • system  — true  = trust-boundary, NON-GRANTABLE. The governance API (R110)
-//               rejects adding it to a CUSTOM role and the tab renders it LOCKED;
-//               it is deploy/protected-path/rank-set/version-close/grade-bypass/
-//               cross-tier/principal power, enforced by the out-of-band substrate
-//               (ADR 0043) or reserved to Archon. The built-in `archon` rank-role
-//               legitimately HOLDS the archon-floored system perms — "non-grantable"
-//               constrains custom roles, not the seed.
+//   • system  — true  = trust-boundary. The governance API (R110) rejects adding it
+//               to a CUSTOM role and the tab renders it LOCKED there; it is deploy/
+//               protected-path/rank-set/version-close/grade-bypass/cross-tier/
+//               principal power, enforced by the out-of-band substrate (ADR 0043)
+//               or reserved to Archon. The built-in `archon` rank-role legitimately
+//               HOLDS the archon-floored system perms.
 //             — false = operational, freely composable into a custom role.
+//             `system` is NOT the whole grantability answer any more — see the
+//             `substrate` axis below and `isGrantableTo()`, which is per-ROLE.
+//   • substrate — true = this key's authority is enforced OUTSIDE the app, by the
+//               pre-push hook / main-audit / the rank floor the git and ssh layers
+//               read (ADR 0043). A grant row for one is INERT: no route consumes it
+//               through requirePermission, so granting it would be a toggle that
+//               looks like it worked and changes nothing. Therefore non-grantable to
+//               EVERY role, seeded rank-roles included — the one wall ADR 0172's
+//               widening deliberately did not move, because moving it would make the
+//               tab lie rather than delegate. Implies system:true + floor 'archon'.
 //   • floor   — the rank that holds this permission TODAY via the compat seed
 //               ('xenos' < 'thetes' < 'metic' < 'archon'), or null for a machine
 //               PRINCIPAL permission held by NO rank-role (gated on exact
@@ -84,7 +93,12 @@ const RANK_ORDER = Object.freeze(['xenos', 'thetes', 'metic', 'archon']);
 // (the exhaustive 1:1 list lives in the authority sweep). Order: system first, then
 // operational by floor (archon → metic → thetes/own/any), matching the ADR appendix.
 const PERMISSIONS = [
-  // ── system: true — non-grantable (substrate- or Archon-enforced) ──────────────
+  // ── system: true — trust-boundary (substrate- or Archon-enforced) ─────────────
+  //
+  // The seven WITHOUT `substrate` are in-app Archon powers: a real route reads them
+  // through requirePermission, so granting one to a sub-Archon rank-role genuinely
+  // delegates it (ADR 0172, the owner's lever). The three WITH `substrate: true` are
+  // enforced out of band and can never be delegated by a row in this database.
   { key: 'builder.rank.set', system: true, floor: 'archon', guards: 'PATCH /builders/:id/rank — the single rank writer' },
   { key: 'version.close', system: true, floor: 'archon', guards: 'version close disposition (never delegated below Archon)' },
   { key: 'task.confirm.grade_bypass', system: true, floor: 'archon', guards: 'POST /tasks/:id/confirm — ratify past a failed grade (env-relaxable, ADR 0041)' },
@@ -92,9 +106,9 @@ const PERMISSIONS = [
   { key: 'goal.scope.manage', system: true, floor: 'archon', guards: 'cross-tier goal-scope edges + protected-scope admission (ADR 0086)' },
   { key: 'governance.manage', system: true, floor: 'archon', guards: 'the governance tab routes (roles/perms/assignments CRUD, reads included — R110) — meta-escalation' },
   { key: 'gate_approval.decide', system: true, floor: 'archon', guards: 'POST /gate-approvals/:pr/approve — CI deploy-gate override' },
-  { key: 'deploy.push_main', system: true, floor: 'archon', guards: 'git push origin main / the deploy — substrate-enforced (pre-push, main-audit)' },
-  { key: 'path.protected.modify', system: true, floor: 'archon', guards: 'modifying a PROTECTED_GLOBS path below the Metic floor — substrate (ADR 0043)' },
-  { key: 'infra.ssh', system: true, floor: 'archon', guards: 'ssh to the droplet / operator surface — substrate (credential placement)' },
+  { key: 'deploy.push_main', system: true, substrate: true, floor: 'archon', guards: 'git push origin main / the deploy — substrate-enforced (pre-push, main-audit)' },
+  { key: 'path.protected.modify', system: true, substrate: true, floor: 'archon', guards: 'modifying a PROTECTED_GLOBS path below the Metic floor — substrate (ADR 0043)' },
+  { key: 'infra.ssh', system: true, substrate: true, floor: 'archon', guards: 'ssh to the droplet / operator surface — substrate (credential placement)' },
   { key: 'principal.bfg', system: true, floor: null, principal: 'bfg', guards: '/memory/bfg/* — requireBfgPrincipal (exact system_role=bfg; NO rank-role holds it)' },
   { key: 'principal.discord_bot', system: true, floor: null, principal: 'discord_bot', guards: 'Discord bot routes — requireDiscordBot (exact system_role; dormant)' },
 
@@ -256,6 +270,23 @@ for (const p of PERMISSIONS) {
     if (!p.system) throw new Error(`governance catalog: ${p.key} is a principal permission and must be system:true (never grantable to a role)`);
     if (_byPrincipal.has(principal)) throw new Error(`governance catalog: duplicate principal identity "${principal}"`);
   }
+  // ── the SUBSTRATE axis (ADR 0172) ─────────────────────────────────────────
+  // A substrate key is enforced by the out-of-band layer (pre-push hook, main-audit,
+  // the rank floor git/ssh read), so no role row can confer it. Three shape rules,
+  // each closing a way the marker could quietly stop meaning that:
+  const substrate = p.substrate ?? false;
+  if (typeof substrate !== 'boolean') throw new Error(`governance catalog: ${p.key} has a non-boolean 'substrate'`);
+  if (substrate) {
+    // Substrate power is trust-boundary power by definition — a substrate key that
+    // was somehow operational would be freely grantable to a custom role.
+    if (!p.system) throw new Error(`governance catalog: ${p.key} is substrate-enforced and must be system:true`);
+    // A substrate key belongs to no machine identity: the two are different reasons
+    // a key is unreachable, and collapsing them would hide one behind the other.
+    if (principal !== null) throw new Error(`governance catalog: ${p.key} cannot be both substrate-enforced and a machine principal`);
+    // The out-of-band enforcers all compare against the top of the ladder. A lower
+    // floor would seed the key into a rank-role that the substrate then still denies.
+    if (p.floor !== 'archon') throw new Error(`governance catalog: ${p.key} is substrate-enforced and must floor at 'archon' (the substrate compares against the top of the ladder)`);
+  }
   // ── the OWNERSHIP axis (R100) ─────────────────────────────────────────────
   const scope = p.scope ?? null;
   const resource = p.resource ?? null;
@@ -283,7 +314,7 @@ for (const p of PERMISSIONS) {
   if (scope !== null && p.floor === null) {
     throw new Error(`governance catalog: ${p.key} is ownership-scoped but has no rank floor — the ownership axis narrows a ROLE permission, never an identity one`);
   }
-  const frozen = Object.freeze({ ...p, principal, scope, resource });
+  const frozen = Object.freeze({ ...p, principal, scope, resource, substrate });
   _byKey.set(p.key, frozen);
   if (principal !== null) _byPrincipal.set(principal, frozen);
   if (resource !== null) {
@@ -352,6 +383,8 @@ function isSystem(key) {
   return p ? p.system : null; // null = unknown key (caller fails closed)
 }
 // Grantable to a CUSTOM role = exists and not system. Unknown key → false (fail-closed).
+// This is the NARROW question — the custom-role wall, unchanged by ADR 0172 and
+// still what config.js strips against. For the per-role answer use isGrantableTo().
 function isGrantable(key) {
   const p = _byKey.get(key);
   return !!p && !p.system;
@@ -362,6 +395,49 @@ function systemKeys() {
 function grantableKeys() {
   return PERMISSIONS.filter((p) => !p.system).map((p) => p.key);
 }
+// Enforced outside the app (pre-push, main-audit, the rank floor git/ssh read).
+// Unknown key → false, but note the callers all pair it with a byKey() existence
+// check first — an unknown key is refused as unknown, never as "not substrate".
+function isSubstrate(key) {
+  const p = _byKey.get(key);
+  return !!p && p.substrate;
+}
+function substrateKeys() {
+  return PERMISSIONS.filter((p) => p.substrate).map((p) => p.key);
+}
+
+// ── grantability, per ROLE (ADR 0172) ──────────────────────────────────────────
+//
+// The owner's 2026-08-16 decision made the three sub-Archon RANK roles editable, so
+// "is this grantable" stopped being a property of the key alone. `role` is a
+// governance_roles row ({ is_system, seeded_rank }); the four answers:
+//
+//   • NEVER, to any role — a machine-principal key (held by an identity, not a role)
+//     and a SUBSTRATE key. The substrate three are inert as grant rows: no route
+//     consumes them through requirePermission, so a toggle for one would report
+//     success and delegate nothing. Refusing them keeps the tab honest.
+//   • the ARCHON rank-role — nothing. It is immutable and already holds everything,
+//     and that immutability is also the LOCKOUT GUARD: the only role carrying
+//     `governance.manage` by seed can never have it revoked, so no sequence of
+//     clicks in this tab can lock the owner out of the tab.
+//   • a SEEDED rank-role BELOW archon — everything else, the seven in-app Archon
+//     powers included. This is the delegation lever the owner asked for.
+//   • a CUSTOM role — operational only: the pre-existing R110 wall, deliberately NOT
+//     widened. A rank-role is the owner's own coarse ladder, moved by a rank write;
+//     a custom role is ad-hoc and assignable by anyone holding `governance.manage`,
+//     so widening it would hand the second group the first group's lever.
+//
+// Fail-closed on everything unrecognised: unknown key, missing role, or a system role
+// whose seeded_rank is not a real rank all answer false.
+function isGrantableTo(key, role) {
+  const p = _byKey.get(key);
+  if (!p || !role || typeof role !== 'object') return false;
+  if (p.principal !== null || p.substrate) return false;
+  if (role.is_system) {
+    return RANK_ORDER.includes(role.seeded_rank) && role.seeded_rank !== 'archon';
+  }
+  return !p.system;
+}
 
 // ── the principal axis (identity, not roles) ────────────────────────────────────
 // Reads only. Unknown/blank input fails closed to null/false — the same posture the
@@ -448,6 +524,9 @@ module.exports = {
   byKey,
   isSystem,
   isGrantable,
+  isGrantableTo,
+  isSubstrate,
+  substrateKeys,
   systemKeys,
   grantableKeys,
   seedForRank,

package/modules/governance/db.js

@@ -178,6 +178,35 @@ async function revokeRolePermission({ roleKey, permissionKey }) {
   return rowCount > 0;
 }
 
+// Replace a role's entire grant set in ONE transaction (ADR 0172's reset). The
+// delete+insert pair must be atomic: a crash between them would leave the role
+// holding NOTHING, and for a rank-role that is every builder at that rank losing
+// every permission until someone noticed. The caller supplies the keys (the route
+// derives them from catalog.seedForRank), so this stays a dumb write like its
+// neighbours — the authority decision is made against the catalog, in the route.
+async function resetRoleGrants({ roleKey, permissionKeys }) {
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+    await client.query(`DELETE FROM governance_role_permissions WHERE role_key = $1`, [roleKey]);
+    if (permissionKeys.length > 0) {
+      await client.query(
+        `INSERT INTO governance_role_permissions (role_key, permission_key)
+         SELECT $1, unnest($2::text[])
+         ON CONFLICT (role_key, permission_key) DO NOTHING`,
+        [roleKey, [...permissionKeys]],
+      );
+    }
+    await client.query('COMMIT');
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+  return permissionKeys.length;
+}
+
 async function listAssignments() {
   const { rows } = await pool.query(
     `SELECT br.builder_id, b.github_login, b.display_name, b.rank,
@@ -221,6 +250,7 @@ module.exports = {
   createRole,
   grantRolePermission,
   revokeRolePermission,
+  resetRoleGrants,
   listAssignments,
   assignRole,
   unassignRole,

package/modules/governance/routes/governance.js

@@ -108,14 +108,28 @@ function registerSeams() {
 // Every route — the three reads included — gates on the `governance.manage`
 // atom (system, floor archon): this surface EDITS the role/permission graph
 // itself, the meta-escalation the catalog flags non-grantable, and even listing
-// it exposes the full authority map. Two invariants are enforced HERE, against
-// the catalog, not in the db layer (governance_001's app-side-validation split):
-//   • a `system:true` permission is NON-GRANTABLE to a custom role (R94's wall —
-//     "The governance API (R110) rejects granting it");
-//   • the four seeded rank-roles are IMMUTABLE through this API: their grants
-//     derive from catalog floors (a change is a migration — R94) and their
-//     assignment derives from builders.rank via the R95b sync. A second writer
-//     for either would fork authority truth.
+// it exposes the full authority map. The invariants are enforced HERE, against
+// the catalog, not in the db layer (governance_001's app-side-validation split).
+//
+// ADR 0172 (owner decision, 2026-08-16) split what used to be ONE wall — "a seeded
+// rank-role is immutable" — into two, because grants and assignment are immutable
+// for different reasons and only one of those reasons still holds:
+//
+//   • GRANTS on the three sub-Archon rank-roles are now EDITABLE. Their rows were
+//     always ordinary `governance_role_permissions` rows (the governance_002 seed
+//     writes them); the old refusal was policy, not structure. What a rank means is
+//     now the owner's to set from the tab, and `catalog.isGrantableTo()` answers
+//     which keys per role. The ARCHON rank-role stays immutable — it holds
+//     everything, and its immutability is what makes lockout impossible.
+//   • ASSIGNMENT of every seeded rank-role is still refused, unchanged: it derives
+//     from `builders.rank` via the R95b sync, so a second writer here would fork
+//     authority truth and the sync would silently undo it on the next rank write.
+//     Changing who holds a rank-role is still `PATCH /builders/:id/rank`.
+//
+// The custom-role wall is unchanged: a `system:true` key stays non-grantable there
+// (R94's wall — "The governance API (R110) rejects granting it"), and the three
+// SUBSTRATE keys stay non-grantable to everything, rank-roles included, because a
+// grant row for one delegates nothing (ADR 0043 enforces them out of band).
 const { validateOrRespond, LIMITS, parseId } = api;
 const ROLE_KEY_RE = /^[a-z][a-z0-9-]*$/;
 const ROLE_KEY_MAX = 64;
@@ -136,21 +150,39 @@ module.exports = function buildGovernanceRouter() {
     return roleKey;
   }
 
-  // Load a role that this API may MUTATE: 404 on a missing role, refuse a seeded
-  // rank-role with the caller's `immutableCode`. Returns null after responding.
-  async function loadMutableRole(res, roleKey, immutableCode, reason) {
+  // Load a role whose GRANTS this API may edit (ADR 0172): 404 on a missing role,
+  // refuse only the Archon rank-role. Every other role — the three sub-Archon
+  // rank-roles and every custom one — is grant-editable; WHICH keys is then
+  // `catalog.isGrantableTo(key, role)`, per role. Returns null after responding.
+  async function loadGrantEditableRole(res, roleKey) {
+    const role = await db.getRoleByKey(roleKey);
+    if (!role) {
+      res.fail('role_not_found', 404, { role_key: roleKey });
+      return null;
+    }
+    if (role.is_system && role.seeded_rank === ARCHON) {
+      res.fail('archon_role_immutable', 403, { role_key: roleKey, reason: ARCHON_REASON });
+      return null;
+    }
+    return role;
+  }
+
+  // Load a role this API may ASSIGN. Unchanged from R110: every seeded rank-role is
+  // refused, because assignment derives from builders.rank via the R95b sync.
+  async function loadAssignableRole(res, roleKey) {
     const role = await db.getRoleByKey(roleKey);
     if (!role) {
       res.fail('role_not_found', 404, { role_key: roleKey });
       return null;
     }
     if (role.is_system) {
-      res.fail(immutableCode, 403, { role_key: roleKey, reason });
+      res.fail('seeded_role_assignment_forbidden', 403, { role_key: roleKey, reason: ASSIGN_REASON });
       return null;
     }
     return role;
   }
-  const GRANTS_REASON = 'a seeded rank-role\'s grants derive from catalog floors; changing one is a migration (R94), never an API write';
+  const ARCHON = 'archon';
+  const ARCHON_REASON = 'the Archon rank-role holds every permission and is immutable — it is the role that can never be locked out of this tab (ADR 0172)';
   const ASSIGN_REASON = 'a seeded rank-role is assigned by rank (R95b sync); change the builder\'s rank instead';
 
   // rank: perm governance.manage — the full role list with each role's grants.
@@ -165,12 +197,19 @@ module.exports = function buildGovernanceRouter() {
   });
 
   // rank: perm 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.
+  // from code (the catalog is CODE, not a table); no DB read. Principals are
+  // read-only by construction. Three flags the tab renders its locks from, and the
+  // tab must read all three rather than just `grantable`, because since ADR 0172
+  // grantability depends on WHICH role is selected:
+  //   • `grantable` — the CUSTOM-role answer (system:false). Unchanged meaning.
+  //   • `system`    — an in-app Archon power: locked on a custom role, togglable on
+  //                   a sub-Archon rank-role.
+  //   • `substrate` — locked EVERYWHERE, on every role, forever (ADR 0043).
   router.get('/governance/permissions', api.requireBuilder, api.requirePermission('governance.manage'), (req, res) => {
     const permissions = catalog.PERMISSIONS.map((p) => ({
       key: p.key,
       system: p.system,
+      substrate: p.substrate,
       floor: p.floor,
       guards: p.guards,
       scope: p.scope,
@@ -221,23 +260,31 @@ module.exports = function buildGovernanceRouter() {
     }
   });
 
-  // rank: perm 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.
+  // rank: perm governance.manage — grant one permission to a role (the toggle's ON
+  // half). The order of refusals is the authority order: role exists → role is not
+  // the Archon one → the key exists → the key is grantable TO THIS ROLE.
   router.put('/governance/roles/:roleKey/permissions/:permissionKey', api.requireBuilder, api.requirePermission('governance.manage'), async (req, res) => {
     const roleKey = roleKeyParam(req, res);
     if (roleKey === null) return;
     const permissionKey = req.params.permissionKey;
     try {
-      const role = await loadMutableRole(res, roleKey, 'seeded_role_immutable', GRANTS_REASON);
+      const role = await loadGrantEditableRole(res, roleKey);
       if (role === null) return;
       if (!catalog.byKey(permissionKey)) {
         return res.fail('unknown_permission', 400, { permission_key: permissionKey });
       }
-      if (!catalog.isGrantable(permissionKey)) {
+      if (!catalog.isGrantableTo(permissionKey, role)) {
         return res.fail('permission_not_grantable', 400, {
           permission_key: permissionKey,
-          reason: 'system (trust-boundary) permissions are non-grantable to a custom role (ADR 0151)',
+          role_key: roleKey,
+          // Name the ACTUAL wall. "Not grantable" now has three distinct causes and
+          // a caller that cannot tell them apart cannot tell a policy choice
+          // (widen the role) from a structural one (nothing will ever work).
+          reason: catalog.isSubstrate(permissionKey)
+            ? 'substrate-enforced (ADR 0043) — enforced outside the app by the pre-push hook / main-audit / the rank floor, so a grant row here would confer nothing. Non-grantable to EVERY role.'
+            : catalog.isPrincipalKey(permissionKey)
+              ? 'a machine-principal permission — held by an exact builders.system_role identity, never by a role (ADR 0151 §3)'
+              : 'a system (trust-boundary) permission is non-grantable to a CUSTOM role; only a sub-Archon rank-role may carry one (ADR 0172)',
         });
       }
       const granted = await db.grantRolePermission({ roleKey, permissionKey });
@@ -257,7 +304,7 @@ module.exports = function buildGovernanceRouter() {
     if (roleKey === null) return;
     const permissionKey = req.params.permissionKey;
     try {
-      const role = await loadMutableRole(res, roleKey, 'seeded_role_immutable', GRANTS_REASON);
+      const role = await loadGrantEditableRole(res, roleKey);
       if (role === null) return;
       const removed = await db.revokeRolePermission({ roleKey, permissionKey });
       res.json({ ok: true, role_key: roleKey, permission_key: permissionKey, removed });
@@ -267,6 +314,41 @@ module.exports = function buildGovernanceRouter() {
     }
   });
 
+  // rank: perm governance.manage — restore a SEEDED rank-role to its catalog
+  // default (ADR 0172). The counterweight to making the rank-roles editable: a
+  // rank's grant set is ~60 rows, so an owner who drifts one has no practical way
+  // back by clicking, and "what does Trusted mean by default" is a question only
+  // the catalog can answer. Restores catalog.seedForRank(role.seeded_rank) — the
+  // same derivation governance_002 seeded from, so the answer cannot drift from
+  // the floors even after later catalog edits.
+  //
+  // Deliberately NOT offered for a CUSTOM role: a custom role has no catalog
+  // default to return to (its "default" is the empty set it was created with), so
+  // the honest verb there is revoking the grants, which the toggle already does.
+  router.post('/governance/roles/:roleKey/reset', api.requireBuilder, api.requirePermission('governance.manage'), async (req, res) => {
+    const roleKey = roleKeyParam(req, res);
+    if (roleKey === null) return;
+    try {
+      const role = await loadGrantEditableRole(res, roleKey);
+      if (role === null) return;
+      if (!role.is_system || !catalog.RANK_ORDER.includes(role.seeded_rank)) {
+        return res.fail('role_has_no_default', 400, {
+          role_key: roleKey,
+          reason: 'only a seeded rank-role has a catalog default to reset to; revoke a custom role\'s grants instead',
+        });
+      }
+      // The seed is the floor derivation, which never contains a principal key and
+      // — below archon — never a system one. Filtering by isGrantableTo anyway keeps
+      // reset from being a back door that writes what the toggle refuses.
+      const keys = catalog.seedForRank(role.seeded_rank).filter((k) => catalog.isGrantableTo(k, role));
+      const count = await db.resetRoleGrants({ roleKey, permissionKeys: keys });
+      res.json({ ok: true, role_key: roleKey, seeded_rank: role.seeded_rank, permission_count: count });
+    } catch (err) {
+      console.error('[gds] POST /governance/roles/:roleKey/reset', err);
+      res.fail('reset_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // rank: perm 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).
@@ -280,7 +362,7 @@ module.exports = function buildGovernanceRouter() {
       return res.fail('bad_role_key', 400, { role_key: roleKey, expected: 'a kebab-case slug (^[a-z][a-z0-9-]*$)' });
     }
     try {
-      const role = await loadMutableRole(res, roleKey, 'seeded_role_assignment_forbidden', ASSIGN_REASON);
+      const role = await loadAssignableRole(res, roleKey);
       if (role === null) return;
       const assigned = await db.assignRole({
         builderId: req.body.builder_id,
@@ -305,7 +387,7 @@ module.exports = function buildGovernanceRouter() {
     const roleKey = roleKeyParam(req, res);
     if (roleKey === null) return;
     try {
-      const role = await loadMutableRole(res, roleKey, 'seeded_role_assignment_forbidden', ASSIGN_REASON);
+      const role = await loadAssignableRole(res, roleKey);
       if (role === null) return;
       const removed = await db.unassignRole({ builderId, roleKey });
       res.json({ ok: true, builder_id: builderId, role_key: roleKey, removed });

package/modules/hall-ui/public/governance.css

@@ -6,6 +6,9 @@
 .gov-h { color: var(--ink); font-size: 16px; font-weight: 600; margin: 22px 0 8px; }
 .gov-h--minor { font-size: 13px; margin: 18px 0 6px; }
 .gov-grid-note { color: var(--ink-soft); font-size: 12.5px; margin: 0 0 12px; }
+/* Holds the rank-role reset button. Empty for every other role, so it collapses
+   rather than reserving a gap — hence no margin on the empty box itself. */
+.gov-grid-actions:not(:empty) { margin: 0 0 14px; }
 .gov-sealed, .gov-empty { color: var(--ink-soft); padding: 16px 0; }
 
 /* Two columns on wide screens: role rail left, permission grid right. */

package/modules/hall-ui/public/governance.html

@@ -42,6 +42,7 @@
             <div class="gov-grid-col">
               <h2 class="gov-h" id="gov-grid-title">Permissions</h2>
               <p class="gov-grid-note" id="gov-grid-note"></p>
+              <div class="gov-grid-actions" id="gov-reset"></div>
               <div id="gov-grid"></div>
             </div>
           </div>

package/modules/hall-ui/public/governance.js

@@ -1,16 +1,24 @@
 // public-builders/governance.js — Governance (/builders/governance).
 //
 // The roles/permissions/assignments tab (BV1.R111, ADR 0151 §2) over the R110
-// CRUD routes. Discord-style: pick a role on the left, toggle its OPERATIONAL
-// permissions in the grid, assign custom roles to builders below. Two walls the
-// SERVER enforces and this page only renders honestly (ADR 0016 — nothing here
-// grants anything):
-//   • `system` (trust-boundary) permissions render LOCKED — visible, never
-//     togglable; the API refuses them as `permission_not_grantable`.
-//   • the four seeded rank-roles are read-only — their grants derive from
-//     catalog floors and their assignment from builders.rank (R95b), so both
-//     toggle + assign are disabled and the API refuses `seeded_role_immutable`
-//     / `seeded_role_assignment_forbidden`.
+// CRUD routes. Discord-style: pick a role on the left, toggle its permissions in
+// the grid, assign custom roles to builders below.
+//
+// Since ADR 0172 grantability depends on WHICH role is selected, so this page's
+// central job is rendering three different locks honestly. The SERVER enforces all
+// of them (ADR 0016 — nothing here grants anything; a disabled button is a
+// courtesy, `isGrantableTo` on the route is the wall):
+//   • SUBSTRATE permissions (deploy / protected paths / ssh) render LOCKED for
+//     every role, always. They are enforced outside the app (ADR 0043), so a grant
+//     row confers nothing — showing a working toggle would be the UI lying.
+//   • OWNER POWERS (the seven in-app `system` keys) render LOCKED on a custom role
+//     and TOGGLABLE on a sub-Archon rank-role. That asymmetry is the whole of the
+//     owner's 2026-08-16 decision, and the section header says so out loud.
+//   • the ARCHON rank-role is read-only in full: it holds everything, and its
+//     immutability is what makes it impossible to click your way into locking the
+//     owner out of this tab. The API refuses it as `archon_role_immutable`.
+// ASSIGNMENT of any rank-role is still refused (`seeded_role_assignment_forbidden`)
+// — you get a rank-role by holding the rank, so that dial is the rank itself.
 //
 // Like The Gate, this reads /api/bongos/me for a friendly Sealed notice —
 // DEFENCE IN DEPTH only. Every /governance/* endpoint (reads included) is ALSO
@@ -55,8 +63,9 @@
 
   // The R110 refusal codes, translated for the person clicking.
   const ERROR_COPY = {
-    permission_not_grantable: 'That is a trust-boundary permission — it can never be granted to a custom role.',
-    seeded_role_immutable: 'Rank roles are read-only: their permissions derive from the catalog, not from this page.',
+    permission_not_grantable: 'That permission can’t be granted to this role. (The server’s reply says which of the three walls applied.)',
+    archon_role_immutable: 'The Archon role is read-only — it holds every permission, which is what keeps you from locking yourself out of this page.',
+    role_has_no_default: 'Only a rank role has a catalog default to reset to. Revoke a custom role’s permissions individually instead.',
     seeded_role_assignment_forbidden: 'Rank roles are assigned by rank itself — change the builder’s rank instead.',
     role_exists: 'A role with that key already exists.',
     role_not_found: 'That role no longer exists — refreshing.',
@@ -83,9 +92,13 @@
     const list = document.getElementById('gov-role-list');
     list.innerHTML = '';
     for (const role of roles) {
-      const pill = role.is_system
-        ? `<span class="gov-pill gov-pill--seeded">rank role</span>`
-        : `<span class="gov-pill gov-pill--custom">custom</span>`;
+      // The Archon row is called out as read-only, because it is the one role in
+      // this list a click will not change and the reader should know before trying.
+      const pill = isArchonRole(role)
+        ? `<span class="gov-pill gov-pill--locked">rank role · read-only</span>`
+        : role.is_system
+          ? `<span class="gov-pill gov-pill--seeded">rank role</span>`
+          : `<span class="gov-pill gov-pill--custom">custom</span>`;
       const btn = document.createElement('button');
       btn.type = 'button';
       btn.className = 'gov-role';
@@ -100,20 +113,38 @@
 
   // ---- render: permission grid --------------------------------------------
 
+  // The client-side mirror of catalog.isGrantableTo(). It exists to render the
+  // right control, NEVER to decide authority — the route runs the real one and
+  // refuses regardless of what this returns. Kept in the same order as the server's
+  // so a future catalog change lands in one obvious place on each side.
+  const isArchonRole = (role) => !!role && role.is_system && role.seeded_rank === 'archon';
+  const isRankRole = (role) => !!role && role.is_system;
+  function grantableTo(p, role) {
+    if (!role || p.substrate) return false;
+    if (role.is_system) return role.seeded_rank !== 'archon';
+    return !!p.grantable;
+  }
+
   function permRow(p, role) {
     const held = !!role && (role.permissions || []).includes(p.key);
     const row = document.createElement('div');
     row.className = 'gov-perm';
 
+    // Why locked, in the words that tell the reader whether it is a policy they
+    // could change or a fact they cannot. Three causes, three sentences.
+    const lockReason = p.substrate
+      ? 'Enforced outside the app (the pre-push hook, the deploy audit, the server itself). Granting it here would change nothing, so it is locked for every role.'
+      : isArchonRole(role)
+        ? 'The Archon role holds everything and is read-only.'
+        : 'An owner-level permission. It can be handed to a rank role, but never to a custom one.';
+
     let control;
-    if (!p.grantable) {
-      // The R110 wall, rendered: visible, never togglable.
-      control = `<span class="gov-pill gov-pill--locked" title="Trust-boundary permission — non-grantable (ADR 0151)">locked</span>`;
-    } else if (!role) {
+    if (!role) {
       control = '';
-    } else if (role.is_system) {
-      // Seeded rank-role: show what it holds, allow nothing.
-      control = held ? `<span class="gov-held-note">held via rank</span>` : '';
+    } else if (!grantableTo(p, role)) {
+      control = `<span class="gov-pill gov-pill--locked" title="${escapeHtml(lockReason)}">locked</span>`;
+      // The Archon role is read-only rather than empty-handed, so say what it holds.
+      if (held && isArchonRole(role)) control = `<span class="gov-held-note">held</span>${control}`;
     } else {
       control = `<button type="button" class="gov-toggle" aria-pressed="${held ? 'true' : 'false'}" data-perm="${escapeHtml(p.key)}">${held ? 'granted' : 'grant'}</button>`;
     }
@@ -139,23 +170,71 @@
     return el;
   }
 
+  function gridNote(role) {
+    if (!role) return 'Pick a role to see and edit what it may do.';
+    if (isArchonRole(role)) {
+      return 'The Archon role holds every permission and is read-only — that is what makes it impossible to lock yourself out of this page. To give a power away, hand it to one of the ranks below instead.';
+    }
+    if (isRankRole(role)) {
+      return `Everything a ${role.label || role.role_key} can do, and yours to change — every builder at this rank is affected immediately. “Reset to default” puts it back to the shipped ladder.`;
+    }
+    return 'Toggle the everyday permissions this role carries. Owner powers can only go to a rank role, not to a custom one.';
+  }
+
   function renderGrid() {
     const grid = document.getElementById('gov-grid');
     const role = selectedRole();
     document.getElementById('gov-grid-title').textContent = role
       ? `Permissions — ${role.label || role.role_key}` : 'Permissions';
-    document.getElementById('gov-grid-note').textContent = !role
-      ? 'Pick a role to see and edit what it may do.'
-      : role.is_system
-        ? 'A rank role’s permissions derive from the catalog and cannot be edited here.'
-        : 'Toggle the everyday permissions this role carries. Locked rows are trust-boundary powers no custom role can ever hold.';
+    document.getElementById('gov-grid-note').textContent = gridNote(role);
+
+    // The reset escape hatch — only a rank role has a catalog default, and the
+    // Archon one never drifts from it, so it shows on exactly the three editable ones.
+    const resetBox = document.getElementById('gov-reset');
+    resetBox.innerHTML = '';
+    if (isRankRole(role) && !isArchonRole(role)) {
+      const btn = document.createElement('button');
+      btn.type = 'button';
+      btn.className = 'gov-btn gov-btn--ghost gov-btn--small';
+      btn.textContent = 'Reset to default';
+      btn.addEventListener('click', () => resetRole(role, btn));
+      resetBox.appendChild(btn);
+    }
 
     grid.innerHTML = '';
+    // Principals are rendered in their own section further down the page; a machine
+    // identity is not a row anyone can act on here.
     const humanPerms = permissions.filter((p) => !principals.some((pr) => pr.permission === p.key));
-    const locked = humanPerms.filter((p) => !p.grantable);
-    const operational = humanPerms.filter((p) => p.grantable);
-    grid.appendChild(section(`Trust boundary — locked (${locked.length})`, locked.map((p) => permRow(p, role))));
+    // Three groups, split by WHY a row is or isn't editable rather than by the old
+    // single `grantable` flag — which since ADR 0172 answers only the custom-role case.
+    const substrate = humanPerms.filter((p) => p.substrate);
+    const ownerPowers = humanPerms.filter((p) => p.system && !p.substrate);
+    const operational = humanPerms.filter((p) => !p.system);
+
+    const ownerHead = !role || isRankRole(role)
+      ? `Owner powers (${ownerPowers.length})`
+      : `Owner powers — locked for custom roles (${ownerPowers.length})`;
+
     grid.appendChild(section(`Operational (${operational.length})`, operational.map((p) => permRow(p, role))));
+    grid.appendChild(section(ownerHead, ownerPowers.map((p) => permRow(p, role))));
+    grid.appendChild(section(`Enforced outside the app — always locked (${substrate.length})`, substrate.map((p) => permRow(p, role))));
+  }
+
+  // Restore a rank role to the shipped ladder. Confirmed because it is the one
+  // action here that discards work in bulk — a drifted role can be ~60 rows.
+  async function resetRole(role, btn) {
+    const label = role.label || role.role_key;
+    if (!window.confirm(`Reset ${label} to its default permissions?\n\nEvery change you've made to this rank is discarded, and it takes effect for every builder at this rank on their next request.`)) return;
+    btn.disabled = true;
+    try {
+      const out = await sendJson('POST', `/governance/roles/${encodeURIComponent(role.role_key)}/reset`);
+      toast(`${label} reset to its default ${out.permission_count} permissions.`);
+      await reloadRoles();
+    } catch (err) {
+      if (err && err.kind === '401') return;
+      toast(`Could not reset: ${err.message || err}`);
+      btn.disabled = false;
+    }
   }
 
   async function toggleGrant(role, permissionKey, grant, btn) {
@@ -337,7 +416,7 @@
     const rank = (me && (me.builder || me).rank || '').toLowerCase();
     if (rank !== 'archon') { showSealed(); return; }
 
-    document.getElementById('gov-sub').textContent = 'Roles, permissions, and who holds them — the trust boundary stays locked.';
+    document.getElementById('gov-sub').textContent = 'Roles, permissions, and who holds them. Ranks below Archon are yours to shape; what the substrate enforces stays locked.';
     document.getElementById('gov-body').hidden = false;
     wireForms();
     try {