@bongos/core 1.18.0 → 1.18.18

package/docs/adr/0151-governance-permissions-as-atom-ranks-as-roles.md

@@ -0,0 +1,229 @@
+# 0151 — Governance: permissions as the atom, ranks as seeded roles
+
+- **Status:** Accepted
+- **Date:** 2026-07-24
+- **Deciders:** Lars (owner / Archon), Claude
+- **Track:** `internal` (GDS / methodology — a Cloud Bongos platform capability)
+- **Task:** BV1.R90 ([#1001838](https://cloudbongos.com/builders#/task/1001838)) — the foundation of the BONGOS-V1 **Governance** goal ([#1000030](https://cloudbongos.com/builders#/goal/1000030)); settles the model in an ADR before any of R93–R114 build against it.
+- **Builds on:** [ADR 0016](<redacted>.md) (the server-enforced HTTP trust boundary — **preserved untouched**), [ADR 0043](<redacted>.md) (the out-of-band git/ssh substrate + protected-path rank floor), [ADR 0062](<redacted>.md) (core ↔ host split), [ADR 0083](<redacted>.md) (modules), [ADR 0084](<redacted>.md) (auto-derived per-task rank floor), [ADR 0086](<redacted>.md) (goal-scoped hierarchy + cross-tier edges), [ADR 0090](<redacted>.md) (Metic authoring powers), [ADR 0106](<redacted>.md) (ownership authority).
+- **Gates:** R91 (module key) · R93/R94 (tables + catalog code) · R95 (resolver) · R97 (`requirePermission`) · R98–R101 (principals / session-scopes / ownership / registry) · R96/R102 (core-host split) · R104–R109 (gate migration) · R110/R111/R113 (the tab) · R103/R112/R114 (proofs). This ADR is the decision those tasks implement.
+
+---
+
+## Context
+
+Authority in Cloud Bongos is a **single rank threshold** today. [ADR 0016](<redacted>.md) put authority in one DB column (`builders.rank`), checked server-side per request with no caching; [ADR 0018](<redacted>.md) / [ADR 0034](<redacted>.md) wired the four live ranks into the ordered tier `xenos (1) < thetes (2) < metic (3) < archon (4)`. Every privileged route calls `requireRank(...allowed)`, which admits a builder whose rank sits **at or above** the lowest-authority rank named (a threshold, [#591](https://cloudbongos.com/builders#/task/591)). That design is sound and is **not** being replaced — it is the substrate this ADR builds *on top of*.
+
+But a rank is an **all-or-nothing bundle**. There is no way to say "this builder may triage ideas but not author tasks," or to stand up a trusted reviewer who is not a full Metic, without inventing a new rank and threading it through a dozen-plus hand-copied tier maps (§Decision 2 counts 13). The owner wants a **Discord-style roles-and-permissions system**: configurable roles, assignable to builders, composed from granular permissions — where **permissions are the atomic primitive and ranks become seeded roles** — delivered with **zero day-one behavior change** and **without weakening the trust boundary** that is Cloud Bongos's one hard-to-copy moat ([ADR 0087](<redacted>.md): *compete on governance, not tooling*).
+
+The 2026-07-03 governance planning session ([goal 1000030](https://cloudbongos.com/builders#/goal/1000030)) locked the shape and seeded the R90–R114 task chain against six done-when criteria (C1–C6). This ADR records the decision so those tasks build against **one** settled model instead of re-litigating it fourteen times, and it enumerates the **full permission catalog** (the appendix) grounded in the 2026-07-24 authority sweep of every server-side gate in the tree.
+
+**What a rank threshold cannot express (the axes a role model must cover).** The sweep found four distinct *kinds* of authority already live in the code that a flat rank ladder flattens together:
+
+1. **Rank-derived power** — `requireRank('metic')` and friends. The bulk. Maps cleanly to roles.
+2. **Machine principals** — the BFG session-eval uploader and the Discord bot are gated on their **exact `system_role`** (`requireBfgPrincipal`, `requireDiscordBot` in `src/bongos/auth.js`), *not* rank: an Archon token is rejected because it carries `system_role = NULL`. A governance axis roles don't cover.
+3. **Session-scopes** — a dev-box token (`session.source = 'box'`) is **deny-by-default**: it may reach only the routes that opted in via `allowBoxScope`, *regardless of how senior its builder is*. Capability attached to the session, orthogonal to the builder's rank.
+4. **Ownership-scoped authority** — "act on **own** X" and "act on a goal you **own/manage**." Enforced today by in-handler pure gates (`authorizeMemberRoleChange`, [ADR 0106](<redacted>.md)) and by row-level ownership checks, not by `requireRank`.
+
+A model that claims to be "the complete authority model" (criterion C3) has to represent all four.
+
+---
+
+## Decision
+
+Six pillars, one per criterion.
+
+### 1. Permissions are the atom; ranks become seeded roles (C1)
+
+A **permission** is the atomic unit of authority — a stable string key (e.g. `idea.triage`, `task.create`, `builder.rank.set`) that maps to a real capability (a route, a claim rule, a page). Permissions are **defined in code, not UI-invented data**: because each key corresponds to an actual server capability, the catalog is a code constant that the resolver, the gates, and the tab all read from one place (R94). A permission that no route consumes does not exist.
+
+A **role** is a named, assignable bundle of permissions (`governance_roles` + `governance_role_permissions`). A **builder** holds zero or more roles (`governance_builder_roles`).
+
+The four live ranks become **four seeded roles** — `xenos`, `thetes`, `metic`, `archon` — whose grants reproduce today's rank thresholds **exactly** (the compat seed, below). `builders.rank` stays as the identity/graduation column it is today; the seed keeps each builder's role assignment in lock-step with their rank. Ranks do not disappear — they become the *default* roles a fresh instance ships, and the anchor the auto-graduation ([#692](https://cloudbongos.com/builders#/task/692)) and promotion ladder still move along.
+
+A per-request, **uncached** resolver `resolveBuilderPermissions(builderId)` returns a builder's **effective permission set** = the union of their roles' permissions, read fresh on every request (R95). This preserves ADR 0016's single most important property — **instant demotion, no stale-authority window** — because a role change, like a rank change today, takes effect on the builder's very next request. The resolver is exposed through a **kernel port** so core `auth` resolves permissions without importing the `governance` module (respecting the ADR 0083 core-never-imports-a-module boundary; the module registers the port, core calls it).
+
+A new middleware `requirePermission(...perms)` gates a route on the caller holding **all** of the named permissions (fail-closed: 403 on any missing). `requireRank` keeps working unchanged throughout the migration — the seeded rank-roles make `requireRank('metic')` and `requirePermission(<the metic-role's keys>)` equivalent — so gates migrate route-by-route with no flag day (R97).
+
+### 2. Every DB-resolvable authority gate reads permissions, not rank (C2)
+
+Once the primitive exists, the gates migrate off rank:
+
+- **Core routes** (`src/bongos/routes/`) and the **~60 module route gates** (`modules/*/routes/*`) move `requireRank(...)` → `requirePermission(<key>)` with the catalog key that names each route's capability, behavior verified identical against the parity intent (R104, R105).
+- **Claim eligibility** — today rank-driven (`xenosClaimAllowed` / the per-task `requires_rank` floor) — is re-expressed as permissions (`task.claim.newcomer` vs `task.claim.any`), with the per-task floor still honored and the abuse cases still blocked (R106).
+- **HTML page gates** (`requireArchonPage` / `requireNonXenosPage` / `requireBuilderPage`) and the **wandering-prefs rank-default/ceiling clamp** resolve via permissions / role metadata (R107).
+- The **duplicated rank-ladder / tier / order maps** collapse behind the resolver, with a fitness guard forbidding a new parallel map (R108). The 2026-07-24 sweep found **13 definition sites across 5 families** — `RANKS` (the full 16-value ladder, ×2 "twinned"), `LIVE_RANK_LADDER` (×2), `REQUIRES_RANK_TIER`/`RANK_TIER` (×3, one a deliberately-local copy in `permission-path-check.js`), `RANK_ORDER` (×4, one **0-indexed** while the tier maps are 1-indexed), and four one-off rank `Set`s — several commented as hand-kept copies. This is the exact drift class that *caused the Builder 25 incident* (a tier map that forgot `thetes` — [ADR 0043](<redacted>.md)); centralizing it is a security win, not just tidiness.
+- The **route-rank-check fitness gate** learns to read `requirePermission`, re-expresses its EXPECTED pins in permission terms, and still hard-fails the build on an ungated or under-gated write route (R109).
+
+### 3. The complete authority model — roles + principals + session-scopes + ownership-scoped permissions (C3)
+
+The model represents all four axes from §Context as **first-class types**, not as rank special-cases:
+
+- **Roles** — the rank-seeded and custom bundles of §1. The common case.
+- **Principals** (R98) — a **machine identity** is a first-class principal type, its capability keyed on `system_role` (the existing `bfg` / `discord_bot` gate), **provisioned out-of-band and never UI-grantable**. The resolver treats a principal's capability distinctly from a builder's roles; the governance tab *shows* principals but cannot *grant* to them. (A human token can never acquire a principal capability — that is the point of gating on exact identity.)
+- **Session-scopes** (R99) — a **session-scope** is a first-class capability the resolver honors: a box-scoped session's effective permissions are its **deny-by-default allow-list**, intersected with (never widening) its builder's role permissions — so a box session is limited even when its builder is an Archon. This models the current ad-hoc `allowBoxScope` flag explicitly.
+- **Ownership-scoped permissions** (R100) — "act on **own** X" is a **parameterized** permission distinct from the global grant: `box.manage.own` ≠ `box.manage.any`, `claim.act.own` ≠ `claim.act.any`, likewise own-memory / own-credential, and the goal owner/manager authority of [ADR 0106](<redacted>.md). A route requires the scoped form; the resolver + an ownership predicate (the in-handler pure-gate pattern) decide it against the target row. Existing own-scoped routes migrate to it.
+
+### 4. Policy owns / substrate enforces — the protected-surface registry + the system-permission wall (C6 / R101)
+
+This is the pillar that keeps configurability from becoming a foot-gun, and it has two halves.
+
+**The `system` flag.** Every permission in the catalog is flagged **`system: true`** (trust-boundary, **non-grantable**) or **`system: false`** (operational, grantable). A `system` permission — deploy, protected-path modification, rank-setting, version disposition, grade-bypass, cross-tier structural edges — **cannot be added to a custom role**; the governance API rejects the grant server-side and the tab renders it **LOCKED** (visible, so the model is legible; not togglable). `system: false` permissions are the ones an Archon may compose into custom roles freely. The rule for the flag: *a permission is `system` iff granting it to a non-Archon would breach the trust boundary or a scope/quality gate* (privilege management, scope disposition, quality-gate bypass, cross-tier structural edges, and everything the out-of-band substrate enforces).
+
+**The protected-surface registry.** Today's rank→surface map — `PROTECTED_GLOBS` + the per-tier `EXPECTED_RANKS` — is baked into code (`src/bongos/permission-path-check.js`). Governance takes ownership of it **as data**: which paths are protected, and at what floor, becomes a governance-owned registry. The **out-of-band substrate stays the enforcer** — the pre-push hook, the grader pre-pass, `main-audit.js`, `gate-review.js`, and the goal-scope check *read the registry* instead of a hardcoded list, but enforcement never moves into the app. The Metic floor and the `system`-permission mapping *flow from* the registry. The registry (R101) is also the moment to **close the [ADR 0087](<redacted>.md) §3 path-matching gap** the sweep confirmed: `permission-path-check.js`'s `normalize()` does backslash→slash + strip-`./` only — **no case-folding and no Unicode normalization** — so a case-varied or homoglyph path evades the protected-glob match (Linux-deployed, so latent today, but it is the Cursor-class `.cursorignore`/case-bypass CVE shape). The registry matcher should normalize (case-fold + Unicode NFC) and gate file **creation** as strictly as edits.
+
+The invariant this buys, stated as a testable promise (R112, R114): **the tab can re-map which surfaces are protected and at what floor (policy), but it cannot move enforcement into the request path (substrate).** An Archon can create a custom role and grant it every `system: false` permission in the catalog, assign it to a `xenos`, and that builder gains exactly those operational powers — **while a `system` permission the role "has" stays enforced by the substrate**: the deploy / protected-path / SSH attempt is still blocked, because [ADR 0043](<redacted>.md)'s layer-3 audit reads the real git history and the real registry, independent of anything the app grants. Config owns policy; the substrate owns enforcement; a forced grant cannot cross that line. (Note: `main` on this repo still has **no** GitHub branch protection — re-verified 2026-07-24, [ADR 0043](<redacted>.md) §"Branch-protection status" — so `main-audit.js` remains the *authoritative* substrate layer, not a redundant net. The registry does not change that; it only makes the protected list data instead of a constant.)
+
+### 5. Capability in core, settings per project (C4)
+
+Governance is a **core module** (`modules/governance/`, `default: true`) — a Cloud Bongos instance ships configurable roles the way it ships its status page. The *capability* (tables, resolver, catalog, gate, tab) lives in core; the *settings* (which roles exist, their starting grants) are **per-instance config**, mirroring the branding pattern:
+
+`config/governance.json` (instance) resolves over `config/governance.neutral.json` (neutral starter, ships with the core package) with an env override on top — the exact `env → instance → neutral` precedence of `src/branding.js` (`resolveBranding` / `deepMerge`) (R96). The neutral config seeds the four rank-role templates a fresh instance inherits; **live** role assignments live in the DB (`governance_builder_roles`, R93), never in config. A vanilla instance boots with sane default roles, no OTB-specific identity, and the trust boundary intact — proven by a vanilla-boot fitness check (R102).
+
+The tables are **module-owned, additive migrations** (`governance_roles`, `governance_role_permissions`, `governance_builder_roles`, all `governance_*`-namespaced per ADR 0083's module-migration rule), plus a `governance` scope-map key covering `modules/governance/**` + `config/governance*.json` (protected, since it overlaps the authz core — R91).
+
+### 6. The Archon Governance tab + the proofs (C5, C6)
+
+- **API** (R110): routes to list roles/permissions/assignments, create a role, toggle an **operational** permission on a role, and assign a role to a builder — all gated `governance.manage` (an Archon-seeded, itself-`system` permission), with `system` permissions **rejected as non-grantable server-side** and the routes pinned in route-rank-check.
+- **Page** (R111, R113): `modules/hall-ui/public/governance.{html,js}` renders the role list, a per-role permission grid (toggle operational perms; `system` perms render LOCKED), and assign-role-to-builder — Discord-style, theme-aware, behind an Archon nav entry + page gate (defense-in-depth on top of the API gate).
+- **Proofs**: a **parity test** (R103) enumerates every current builder + rank and asserts their resolved permission set grants **exactly** today's powers — no more, no less (red if the seed drifts). An **abuse-matrix test** (R112) asserts every attempt to grant a `system` permission to a custom role / low-trust builder is rejected, and the substrate still blocks the action even if a grant were forced. A **live demo** (R114) closes the goal: an Archon builds a custom role, assigns it, the builder performs the operational action — while a `system` permission stays walled.
+
+---
+
+## The compatibility seed (the "zero day-one change" guarantee)
+
+The seed is what makes the cut-over behavior-identical. Four rank-roles are seeded with **cumulative (nested-superset)** grants, and every existing builder is backfilled the role matching their current rank (R93):
+
+| Seeded role | Grants (cumulative — each ⊇ the one above) |
+|---|---|
+| **`xenos`** | own-work + public read: `task.claim.newcomer`, `task.ship`, `task.act.own`, `cost.log`, `learning.create`, `blocker.file`, `idea.file`, `box.manage.own`, `memory.manage.own`, `credential.manage.own`, `page.view.public` |
+| **`thetes`** | everything `xenos` has **+** `task.claim.any` (the whole general queue, still honoring each task's `requires_rank` floor), `page.view.builder` |
+| **`metic`** | everything `thetes` has **+** `me.wandering.set` (higher clamp) **+** the review/triage/authoring set: `idea.triage`, `blocker.review`, `task.{create,edit,promote,demote,vote}`, `task.dependency.manage`, `task.criterion.manage`, `criterion.satisfy`, `criterion.review`, `planning.run`, `priority.run`, `goal.create`, `goal.archive`, `goal.scope.widen`, `goal.manage.own`, `module.enable`, `module.submit`, `security.report.file`, `llm_cache.use`, `backup.manage`, `source.clone.local`, `box.source.full` |
+| **`archon`** | everything `metic` has **+** the **admin** operational set (`builder.status.set`, `builder.budget.set`, `task.abandon`, `criterion.unsatisfy`, `auth.session.revoke`, `access_request.review`, `security.report.adjudicate`, `provisioning.fleet.manage`, `box.fleet.manage`, `autonomy.precheck`, `discord.channels.manage`, `project.curate`, `override_request.decide`, `claim.release.any`, `idea.ratify`, `task.newcomer_restock`, `task.peer_votes.tally`, `goal.reorder`, `builder.roster.read`, `session.search`, `memory.read.any`, `audit_log.read`, `page.view.governance`) **+** the **`system`** set (`builder.rank.set`, `version.close`, `task.confirm.grade_bypass`, `dependency.cross_tier.manage`, `goal.scope.manage`, `governance.manage`, `gate_approval.decide`, `deploy.push_main`, `path.protected.modify`, `infra.ssh`). The `principal.*` permissions are **not** in any rank-role — they are held only by the machine-principal identities (`system_role='bfg'`/`'discord_bot'`), never by a human, not even an Archon (that is what gating on exact identity means). |
+
+**Why cumulative preserves the threshold.** Today `requireRank('metic')` admits metic **and** archon (threshold = at-or-above). Because the seeded `archon` role ⊇ `metic` role, the resolver's union preserves exactly that: both roles grant `idea.triage`, so `requirePermission('idea.triage')` admits both — identical to the old threshold. A builder in the compat seed holds exactly **one** rank-role, so their effective set = that role's set = exactly their rank's threshold powers today. The parity test (R103) is the mechanical proof.
+
+**One deliberate, fail-closed divergence.** The threshold check currently *also* admits the reserved-but-unwired ranks **above** archon (`olympian`…`demigod`) to `requireRank('archon')` gates. The seed maps **only the four live ranks** to roles; a reserved rank maps to **no role → no permissions → fail-closed**. No current builder holds a divine rank, so parity holds for the actual roster; but the model is stricter than today's *latent* threshold-admit-divine edge. This is intended (fail-closed beats fail-open for an unwired rank) and is called out for R103/R106 so the parity test asserts against the live roster, not the reserved enum.
+
+---
+
+## The permission catalog (appendix)
+
+Enumerated from the **2026-07-24 authority sweep** ([`docs/governance/<redacted>.md`](../governance/<redacted>.md) — 81 guarded routes + the ownership/page/substrate gates), grouped here by **capability** (one key may cover a set of sibling routes; the sweep doc holds the exhaustive 1:1 route→gate list R94 transcribes). `sys` = `system` flag (✔ = non-grantable, LOCKED in the tab). Ownership-scoped keys carry an `own`/`any` split. This catalog + the sweep doc are the single source R94 transcribes into `modules/governance/` code constants; R93 seeds roles against it.
+
+### System permissions (`system: true` — non-grantable; substrate- or Archon-enforced)
+
+`system` iff granting to a non-Archon would breach the trust boundary or a scope/quality gate — privilege management, scope disposition, quality-gate bypass, cross-tier structural edges, and everything the out-of-band substrate enforces.
+
+| Key | Guards (route / surface) | Enforced by | sys |
+|---|---|---|---|
+| `builder.rank.set` | `PATCH /builders/:id/rank` — the single rank writer; one-rung, upward | HTTP (`requireRank('archon')`) | ✔ |
+| `version.close` | version close disposition (never delegated below Archon — canonical) | HTTP | ✔ |
+| `task.confirm.grade_bypass` | `POST /tasks/:id/confirm` — ratify past a failed grade (env-relaxable; see note) | HTTP + grader | ✔ |
+| `dependency.cross_tier.manage` | `POST\|DELETE /dependencies` — cross-tier structural edges ([ADR 0086](<redacted>.md)) | HTTP | ✔ |
+| `goal.scope.manage` | cross-tier goal-scope edges + protected-scope admission ([ADR 0086](<redacted>.md)) | HTTP + goal-scope-check | ✔ |
+| `governance.manage` | the governance tab's write routes (roles/perms/assignments) — meta-escalation | HTTP (`requireRank('archon')`) | ✔ |
+| `gate_approval.decide` | `POST /gate-approvals/:pr/approve` — CI deploy-gate override | HTTP + gate-review substrate | ✔ |
+| `deploy.push_main` | `git push origin main` / the deploy | **substrate** (pre-push, main-audit, deploy gate) | ✔ |
+| `path.protected.modify` | modifying a `PROTECTED_GLOBS` path below the Metic floor | **substrate** (3 layers, [ADR 0043](<redacted>.md)) | ✔ |
+| `infra.ssh` | `ssh` to the droplet / operator surface | **substrate** (credential placement, not app) | ✔ |
+| `principal.bfg` | `/memory/bfg/*` — `requireBfgPrincipal` (exact `system_role='bfg'`) | HTTP (identity, not rank) | ✔ |
+| `principal.discord_bot` | Discord bot routes — `requireDiscordBot` (exact `system_role`; dormant) | HTTP (identity, not rank) | ✔ |
+
+The `system` set is deliberately **tight** — only gates whose delegation would *compromise the platform* (escalate rank, bypass the grader/deploy gate, touch protected paths/infra, or re-grant permissions). Every other authority — including many currently archon-gated **admin** ops (offboard, abandon, onboarding review, fleet teardown) — is **operational** and therefore *delegable*, which is the whole value of the model: an Archon can stand up a "moderator" or "onboarder" role without handing out deploy. (The exact system/operational line for a couple of scope-disposition ops is R94's to finalize; this ADR sets the rule and the default.)
+
+> **Env-relaxable exception (flagged for R94/R106):** `POST /tasks/:id/confirm` is archon-only *unless* `GRADER_BYPASS_ENABLED=1` (read live per request, [ADR 0041](<redacted>.md)), which relaxes the middleware to any-builder — then the handler re-narrows in-code via `gateTaskOwnership` (claim holder or Archon only). The permission model represents this as `task.confirm.grade_bypass` (system) with a documented env override on the *substrate* side; the grant is never widened by config, only by the operator env flag.
+
+### Operational permissions (`system: false` — grantable to custom roles)
+
+"Floor" = the rank that holds this permission *today* via the compat seed; it is the seed's job, not an intrinsic property — a custom role may be granted any of these regardless of floor.
+
+**Admin ops — floor `archon` today (delegable to a custom role; that is the point):**
+
+| Key | Guards (route / surface) |
+|---|---|
+| `builder.status.set` | `PATCH /builders/:id/status` — offboard / (de)activate |
+| `builder.budget.set` | `PATCH /builders/:id/budget` |
+| `task.abandon` | `POST /tasks/:id/abandon` — terminal scope removal |
+| `criterion.unsatisfy` | `POST /done-when/:id/unsatisfy` |
+| `auth.session.revoke` | `POST /auth/revoke`, `/auth/revoke-all` |
+| `access_request.review` | `GET/PATCH /access-requests/:id` — admit a builder |
+| `security.report.adjudicate` | `POST /security/reports/:id/{confirm,dispute,fix,link-fix}`, `/security/docs` CRUD |
+| `provisioning.fleet.manage` | `GET /provisioning/fleet[/cost-ledger]`, `POST …/force-teardown` |
+| `box.fleet.manage` | `GET /boxes[/cost-ledger]`, `POST /boxes/:b/close`, `PATCH …/block` |
+| `autonomy.precheck` | `GET /autonomy/precheck` — unsupervised-runner gate |
+| `discord.channels.manage` | `GET /discord/channels/plan`, `POST …/reconcile` |
+| `project.curate` | platform-identity: `POST /projects`, `/projects/invite`, `PATCH /projects/:id/featured`, `GET /scouting` |
+| `override_request.decide` | `GET /override-requests`, `POST …/:id/decide` |
+| `claim.release.any` | `POST /claims/:id/release-on-behalf` |
+| `idea.ratify` | `POST /inbox/:id/ratify` |
+| `task.newcomer_restock` | `POST /tasks/newcomer-restock` |
+| `task.peer_votes.tally` | `POST /tasks/peer-votes/tally` |
+| `goal.reorder` | `POST /goals/reorder` |
+| `builder.roster.read` | `GET /builders/roster`, `/grades/by-builder`, `/builders/:id/active-claims` |
+| `session.search` | `GET /sessions/search` |
+| `memory.read.any` | `GET /memory/builders/:id/file[s]` — cross-builder memory read (Archon) |
+| `audit_log.read` | `GET /audit-log` |
+
+**Working rank — floor `metic` today:**
+
+| Key | Guards (route / surface) |
+|---|---|
+| `idea.triage` | `PATCH /inbox/:id` |
+| `blocker.review` | `POST /blockers/:id/{resolve,link}` |
+| `task.create` / `task.edit` / `task.promote` / `task.demote` | `POST /tasks`, `PATCH /tasks/:id`, `/promote`, `/demote` ([ADR 0090](<redacted>.md)) |
+| `task.dependency.manage` / `task.criterion.manage` | `/tasks/:id/dependencies` + `/criteria` CRUD (same-tier) |
+| `task.vote` | `POST /tasks/:id/vote` |
+| `criterion.satisfy` / `criterion.review` | `POST /done-when/:id/satisfy`, `GET /done-when/pending-review` |
+| `criterion.create` | `POST /versions/:id/done-when` — floor `metic` but **qualified**: a non-Archon must name a `goal_id`, on a `building` version, in an `open` goal they own or manage ([ADR 0154](<redacted>.md)). A floor alone does not describe this permission. *(Was bundled into the `criterion.review` row above while the route was still Archon-only — a transcription slip against the sweep; see ADR 0154 §5.)* |
+| `planning.run` / `priority.run` | planning- / priority-session surface |
+| `goal.create` | `POST /goals` (protected scope → archon in-handler; [ADR 0086](<redacted>.md)) |
+| `goal.archive` | `POST /goals/:id/{archive,reopen}` |
+| `goal.scope.widen` | `POST /goals/:id/scope` (same-tier; cross-tier = `goal.scope.manage`, system) |
+| `module.enable` / `module.submit` | `POST /modules/:key/{enable,submit}`, `GET /modules/submissions` |
+| `security.report.file` | `POST /security/reports`, `GET /security/adr` |
+| `llm_cache.use` | `POST /llm-cache/{lookup,store}` |
+| `backup.manage` | `GET /backup/status`, `POST /backup/trigger` |
+| `source.clone.local` | Metic+ local clone / collaborator invite ([ADR 0035](<redacted>.md)) |
+| `box.source.full` | `GET /box/source-access` → `full` (vs `starter`); `boxScopeForRank` |
+
+**Ownership-scoped (`own` ≠ `any`) + baseline — floor `thetes` / `xenos` / any builder / `own`:**
+
+| Key | Guards (route / surface) | Floor |
+|---|---|---|
+| `goal.manage.own` | `PATCH /goals/:id/members/:b`, `POST /goals/:id/transfer` — owner/manager, in-handler ([ADR 0106](<redacted>.md)) | owner/manager |
+| `task.act.own` | act on **own** active claim (release, cost, notes) | own |
+| `box.manage.own` | own dev-box lifecycle | own |
+| `memory.manage.own` | own builder memory | own |
+| `credential.manage.own` | own API key / credential | own |
+| `me.wandering.set` | `PATCH /me/wandering` (clamped by `maxLevelForRank`) | own (rank-clamped) |
+| `task.claim.any` | claim the general queue (per-task floor still applies) | thetes |
+| `task.claim.newcomer` | claim a `newcomer_friendly` task (`xenosClaimAllowed`; xenos = one active claim) | xenos |
+| `task.ship` · `cost.log` · `learning.create` · `blocker.file` · `idea.file` | own-work write surfaces | any builder |
+| `page.view.public` | public read surfaces | any (incl. xenos) |
+| `page.view.builder` | authenticated hall pages (`requireNonXenosPage` / `requireBuilderPage`) | thetes+ |
+| `page.view.governance` | the Archon governance page (`requireArchonPage`; write = `governance.manage`) | archon |
+
+> **Sweep-completeness note.** These keys cover every authority **domain** the 2026-07-24 sweep found ([the sweep doc](../governance/<redacted>.md) holds the exhaustive 1:1 route list — 81 guarded routes). R94 (the code transcription) is where each remaining `requireRank` site is mapped 1:1 to a key and any residual gap is closed; the route-rank-check fitness gate (R109) is the mechanical backstop that no write route ends up keyless. Keys are stable strings; adding a permission is a catalog + migration change, never a UI action. **A permission's `system` flag, not its floor, decides grantability** — floors are seed data and move; the flag is the wall.
+
+---
+
+## Alternatives considered
+
+- **Keep ranks; add more of them.** Rejected. Every new rank threads through the 13 hand-copied tier/ladder maps (the exact drift that caused the Builder 25 incident) and still can't express "triage but not author," principals, session-scopes, or ownership. Ranks-as-roles subsumes ranks without losing them.
+- **Permissions replace ranks entirely (drop the rank column).** Rejected for the cut-over. `builders.rank` anchors auto-graduation, the promotion ladder, and the per-task `requires_rank` floor; ripping it out forfeits the zero-day-one-change guarantee. Ranks become *seeded roles* and the column stays as identity/graduation — a strangler, not a rewrite.
+- **Make every permission grantable (no `system` flag).** Rejected — it is the whole risk. A configurable role that could be granted `deploy` or `path.protected.modify` would let an Archon (or a compromised Archon token) hand the crown jewels to a `xenos`. The `system` flag + "substrate enforces" is what makes the tab safe; the abuse-matrix test (R112) exists to prove it.
+- **Enforce the protected-surface floor in the app (move the substrate in-process).** Rejected — it re-opens exactly the gap [ADR 0043](<redacted>.md) closed. Git/SSH sit *outside* the HTTP boundary; the authoritative audit must read real git history + real ranks/registry independent of the request path. Governance owns the *data* (policy); the out-of-band substrate stays the *enforcer*.
+- **Cache the resolved permission set per token/TTL.** Rejected, same reasoning as ADR 0016 rejected caching rank: a cache is a stale-authority window on a demotion. The resolver is per-request and uncached; the cost is one more query on a join we already do, bought for instant revocation.
+- **Store roles/permissions as free-form UI data.** Rejected. Permissions map to real routes, so the catalog is **code** — a permission no route consumes is meaningless. The UI assigns and toggles; it never invents a key.
+
+---
+
+## Consequences
+
+- **R91–R114 build against one settled model.** R93/R94 (tables + catalog code) transcribe this ADR's catalog and seed; R95–R97 build the resolver + gate; R98–R101 add the three non-role axes + the registry; R96/R102 do the core-host config split; R104–R109 migrate the gates and collapse the tier maps; R110/R111/R113 build the tab; R103/R112/R114 prove parity, the abuse matrix, and the live demo.
+- **ADR 0016 is preserved, not amended.** Authority still lives server-side, resolved fresh per request against the DB, with instant demotion. The unit of authority narrows from *rank* to *permission*; the enforcement property is unchanged. `requireRank` and `requirePermission` coexist during the migration via the seed.
+- **The trust boundary strengthens.** The 13 duplicated tier/ladder maps — a proven incident source — collapse to one resolver behind a fitness guard; the protected-surface list becomes auditable data with case/Unicode-normalized matching and a mechanical abuse-matrix proof; principals and session-scopes stop being ad-hoc special-cases and become modeled, testable types.
+- **Configurability is bounded by design.** An Archon can compose any `system: false` permission into a custom role, but the `system` set is non-grantable and substrate-enforced, so no configuration can hand out deploy / protected-path / rank-setting power. This is the C6 safety guarantee, proven not asserted.
+- **Zero day-one behavior change.** The compat seed reproduces every current builder's exact powers; the one divergence (unwired divine ranks fail closed instead of latently inheriting Archon) is a fail-closed improvement no live builder touches.
+- **Portable, and the moat.** Governance ships as a `default: true` core module with a neutral config every instance inherits; it is precisely the "governance / audit / org-memory" substrate [ADR 0087](<redacted>.md) named as the hard-to-copy asset. No new recurring cost — tables + code + a config file.

package/docs/adr/0152-landing-gate-served-by-the-core-app.md

@@ -0,0 +1,92 @@
+# 0152 — The landing gate is served by the core app, not by the front proxy
+
+- **Status:** Accepted
+- **Date:** 2026-07-27
+- **Deciders:** Lars (owner / Archon), Claude
+- **Track:** `internal` (platform serving / instance infra)
+- **Task:** <redacted> ([#1002411](https://example.com/builders#/task/1002411)) — the cutover step of the landing-migration chain L01→L07 under the **Project creation flow** goal ([#1000035](https://example.com/builders#/goal/1000035)).
+- **Builds on:** [ADR 0062](<redacted>.md) (core ↔ host split), [ADR 0108](<redacted>.md) (instance composition / pinned vendored core), [ADR 0111](<redacted>.md) (per-instance Caddy snippets), [ADR 0003](<redacted>.md) (origin certs).
+- **Supersedes in practice:** the "give the landing its own Caddy config + its own deploy script" plan that L05 was scoped around. See §Decision.
+
+---
+
+## Context
+
+The reference instance's landing page — the interactive orb "gate" — was historically **served off disk by the front proxy**. Caddy's apex block set `root * <checkout>/brand/cloud-bongos` and `file_server`'d `/`, `/gate/*` and `/world/*` straight out of a checkout of a *different* product repo (`example-owner/example`), while proxying every functional path to the platform app. The landing therefore had:
+
+- **two sources of truth** — the gate bundle lived in the other repo, and a copy of the serving rules lived in that repo's `infra/Caddyfile` and `scripts/deploy/deploy-cloudbongos.sh`;
+- **no deploy path of its own** — updating the landing meant pushing to the other repo and hand-running `git reset --hard origin/main` on the box;
+- **a cross-product coupling** the core could not express: a Cloud Bongos instance's front page was owned by an unrelated product's repository.
+
+L01 ([#1002407](https://example.com/builders#/task/1002407)) ported the verified gate bundle into the core as `public-landing/`, and L02 ([#1002408](https://example.com/builders#/task/1002408)) taught `src/platform-server.js` to serve it: `GET /` on the apex host 302-redirects to `/gate/`, `/gate` 301s to `/gate/`, `/gate/` serves the gate index raw, and the existing `express.static(public-landing)` already covers `/gate/*`, `/world/*` and `/assets/*`.
+
+Once L01+L02 shipped, **the app could already serve the entire landing on its own** — but the live box was still file-serving the other repo's copy, because nothing had flipped the proxy. L05 was scoped (before L01/L02 existed) as "give cloud-bongos (a) its own Caddy config and (b) its own deploy script, then cut the box over." By the time L05 came up, both halves of that plan had dissolved.
+
+## Decision
+
+**The core app owns the landing end to end. The front proxy does TLS, the staging lock, and `reverse_proxy` — nothing else.**
+
+Concretely, the apex and vanity-door site blocks drop `root` + `file_server` and proxy the landing paths to the app, exactly like every other path:
+
+```caddy
+example.com, www.example.com {
+	tls /etc/caddy/origin.crt /etc/caddy/origin.key
+	encode gzip zstd
+	import security_headers
+
+	# The landing surface. Identical to the catch-all except for the staging
+	# lock — so lifting the lock is a one-block delete, not a re-plumb.
+	@gate path / /gate /gate/* /world/*
+	handle @gate {
+		basic_auth {
+			# optional pre-launch lock; omit once the site is public
+		}
+		# Caddy runs `redir` BEFORE `basic_auth`, so "/" redirects first and the
+		# visitor meets the lock at /gate/. The app issues the same 302, so this
+		# line stays correct after the lock is removed.
+		redir / /gate/ 302
+		reverse_proxy 127.0.0.1:3000
+	}
+
+	handle {
+		reverse_proxy 127.0.0.1:3000
+	}
+}
+```
+
+Three consequences follow, and they are the actual decision:
+
+**1. There is no separate Caddy config to "give" the landing.** The block above is the *generic* instance block — the same pure-proxy shape `provision.js`'s `caddyBlock()` already writes for every provisioned instance ([ADR 0111](<redacted>.md) §4). The landing stopped being a special case in the proxy the moment the app could serve it. Host-specific values (hostnames, cert paths, whether a lock exists) stay on the host, per [ADR 0062](<redacted>.md) §7 — the core ships the *shape*, not an instance's hostnames.
+
+**2. There is no separate deploy script to write.** The landing ships **inside the pinned core package**, so it rides the instance's existing deploy: bump the core pin in the instance repo → the box's pull-deploy picks it up → the new landing is live. One artifact, one version number, one deploy path. A landing change is now a normal core change (edit `public-landing/`, ship, release), not an out-of-band push to a foreign repo.
+
+**3. The proxy keeps exactly three jobs on the landing surface:** terminate TLS, enforce any pre-launch `basic_auth` lock, and hide anything the bundle ships but should not expose (the gate's own `README.md` — an `@hidden` matcher for `*.md`/`*.json`/`*.py` and the brand-pipeline `proof`/`refs`/`references` paths). These are deployment-environment concerns, correctly the proxy's; everything else is the app's.
+
+## Consequences
+
+**Good**
+
+- **One source of truth.** The landing bundle exists once, in the core, versioned with everything else. The foreign-repo checkout becomes dead weight (retired by L06, [#1002412](https://example.com/builders#/task/1002412)).
+- **Portable.** Any instance that ships a `public-landing/gate/` gets the gate with a stock proxy block. L02 already guards this: the apex `/` → `/gate/` redirect only engages when the instance actually ships a gate, so a gate-less instance keeps its plain placeholder.
+- **Atomic + rollback-able.** The landing and the app that serves it move together on one pin. Rolling the core back rolls the landing back with it.
+- **Smaller proxy config.** No `root`, no `file_server`, no filesystem path in the site block — so a moved or re-cloned checkout can no longer silently change what the front page serves.
+
+**Costs / risks**
+
+- **The landing is now in the app's request path.** A dead app means a dead front page, where previously Caddy could still serve static files. Accepted: the front page's whole purpose is to reach the app (sign-in, project creation, the live featured-projects feed that fills the orbs), so a dead app already meant a useless landing.
+- **A landing tweak needs a core release.** Slower than pushing to a static checkout. That is the point — the landing is now under the same review and versioning as the rest of the platform.
+- **The `@hidden` guard is load-bearing and hand-maintained.** It is what keeps `gate/README.md` unreachable. If the landing bundle ever gains a file that should not be public, the matcher must keep up. Better long-term fix: don't ship non-public files in `public-landing/` at all.
+
+## Alternatives considered
+
+- **Keep file-serving, but from the core's `public-landing/` instead of the foreign checkout.** Would have removed the cross-repo coupling with a one-line `root` change. Rejected: it hardcodes a `node_modules/@bongos/core/...` path into the proxy config, which then breaks on any packaging-layout change, and it keeps the landing a special case in a config the core cannot ship.
+- **Write the landing its own Caddy config + deploy script, as originally scoped.** Rejected: it builds a second deploy path to maintain, for an artifact that already ships inside the core package and already has one.
+- **Serve the landing from a CDN / object store.** Rejected: the gate is not fully static — it calls the instance's own API for the featured-projects feed and the sign-in state — and it adds a service and a cost for a page the app can serve for free.
+
+## Verification
+
+The cutover was verified against the live reference instance:
+
+- Every landing path returns an identical status code before and after the flip, across the apex and both vanity doors — including the staging lock (`401` on `/gate/*`), the `@hidden` guard (`404` on `/gate/README.md`), and the proxied functional paths (`/healthz`, `/docs`, `/create`, the featured-projects feed).
+- The app's redirects are **relative** (`Location: /gate/`), so proxying them leaks no internal origin.
+- **Severance test:** with the foreign repo's landing folder moved aside entirely, the site continued to serve the byte-identical gate (same md5, same 34,366 bytes) and every asset, proving the dependency is genuinely cut rather than merely unused.

package/docs/adr/0152-metic-task-abandonment.md

@@ -0,0 +1,67 @@
+# 0152 — Metic gains task abandonment, paired with an un-abandon at the same rank
+
+- **Status:** Accepted
+- **Date:** 2026-07-27
+- **Deciders:** Lars (Archon), Claude
+
+**Builds on / amends:** [ADR 0090](<redacted>.md) (Metic task authoring — this ADR reverses one line of its "what stays Archon-only" list), [ADR 0016](<redacted>.md) (server-enforced rank boundary — unchanged), [ADR 0151](<redacted>.md) (permissions-as-atom — the `task.abandon` floor moves with the gate).
+
+**Track:** `internal` (GDS / methodology — a Cloud Bongos platform capability). Task [1002476](https://cloudbongos.com/builders#/task/1002476).
+
+---
+
+## Context
+
+[ADR 0090](<redacted>.md) moved task **authoring** down to the trusted working rank: a Metic can create a task, edit it, promote it backlog→ready, and wire its dependencies and criterion links. Its "what stays Archon-only" list kept one lifecycle transition behind: `POST /tasks/:id/abandon`, described there as "terminal scope removal — the inverse of promote; a destructive lifecycle kill."
+
+A year of using that split showed the asymmetry costs more than it protects. A Metic runs `/idea-triage`, decides which ideas become work, seeds the tasks, and shapes them — and then hits a wall on the one operation that cleans up after all of it. Duplicates they created, chores that a parallel session already shipped, and tasks their own re-scoping made moot all had to be handed back to the owner to retire. The Archon was not adjudicating anything in those hand-backs; they were doing janitorial work on a queue they had already delegated.
+
+Lars's directive (2026-07-27): **"Metics should also be able to abandon tasks."**
+
+### The real risk was not the grant — it was that abandon had no undo
+
+Abandoning is a one-way door *through the API*: `/promote` accepted only `backlog`/`blocked`, `PATCH /tasks/:id` refuses `status` outright ([#514](https://cloudbongos.com/builders#/task/514)), and nothing else writes `status='abandoned'` back to a live value. Restoring a wrongly-retired task meant hand-SQL on prod — an Archon-with-ssh operation.
+
+That was tolerable while abandon *was* Archon-only (the person who could break it could fix it). Handing the kill switch to Metic without an undo would not have removed the owner-cleanup burden; it would have swapped "please retire this" requests for "please un-retire this" requests, with a worse failure mode — a wrongly-abandoned task is invisible in every claimable list and every version rollup ([migration 017](../../migrations/<redacted>.sql) deliberately excludes abandoned from `version_progress`), so nobody notices the mistake until the work silently doesn't happen.
+
+## Decision
+
+**1. Re-rank the gate.** `POST /tasks/:id/abandon` moves from `requireRank('archon')` to `requireRank('metic', 'archon')` — the same threshold ADR 0090 gave create/edit/promote. A rank trusted to seed and shape work is trusted to retire it.
+
+**2. Add the undo at the same rank.** `POST /tasks/:id/promote` now also accepts `abandoned`, restoring the task to **`backlog`**:
+
+| Route | Was | Now |
+|---|---|---|
+| `POST /tasks/:id/abandon` | archon | **metic+** |
+| `POST /tasks/:id/promote` | backlog\|blocked → ready | **+ abandoned → backlog** (metic+, unchanged rank) |
+
+Restore lands in `backlog`, never straight to `ready`. The task was retired deliberately; bringing it back should re-enter it as un-workable and require a second, explicit promote to become claimable. The restore branch returns before the reward gate ([ADR 0096](<redacted>.md)) — that is a promote-to-*workable* concern, and `backlog` is the pre-workable state, the same reasoning `/demote` already uses.
+
+The backing `db.restoreTask` is the mirror of `db.abandonTask`: `SELECT … FOR UPDATE`, guard, single `UPDATE`, commit, with `TASK_NOT_FOUND` / `TASK_NOT_ABANDONED` as its refusals. It clears the `value_summary = 'Abandoned: <reason>'` stamp abandon writes — and *only* that stamp (`CASE WHEN value_summary LIKE 'Abandoned: %'`) — so a restored task never carries a retire note into a later ship card or `#ship-news` broadcast, while an unrelated summary survives.
+
+### What is unchanged
+
+- **The abandon guards.** A `shipped` task is still refused (immutable history — retiring it would corrupt the ledger and the version rollups); a task with an **active claim** is still refused (release it first, so an abandon can never race a ship in flight); an already-abandoned task is still an idempotent no-op.
+- **The audit trail.** Both the abandon and the restore are `POST`s through the writing middleware, so `audit_log` records who retired what, with the `reason`, and who brought it back.
+- **Everything else on ADR 0090's Archon-only list** — setting rank, closing versions, grader-bypass confirm, cross-tier `POST|DELETE /dependencies` and goal-scope edges, `done-when` unsatisfy, newcomer-restock, peer-vote tally, override adjudication. This ADR moves exactly one row.
+
+### Downgrade protection + the permission catalog
+
+- `EXPECTED_RANKS`'s lifecycle pin (`src/bongos/route-rank-check.js`, `MODULE_EXPECTED_RANKS.lifecycle`) moves to `metic+archon` in lockstep, so a *further* silent downgrade (to `any-builder`) is still a hard CI fail, and the route's `// rank:` annotation matches the middleware.
+- Under [ADR 0151](<redacted>.md) the `task.abandon` permission's `floor` moves `archon` → `metic`. Because `RANK_ROLE_SEED` is *derived* from floors, that one edit re-derives the seed; the live grant arrives as `modules/governance/migrations/<redacted>.sql`, since the compat seed (002) is run-once and editing it would leave every already-migrated database on the old grant. The floor change is purely **additive** (archon already holds the permission — the seeded roles are cumulative supersets), so nothing is revoked. `tests/governance_seed.mjs` was generalized to compare the **union** of all grant migrations against the catalog, and now fails loudly if a future migration ever *revokes*, which the union model could not represent.
+
+## Consequences
+
+- **The triage→author→retire loop closes for Metic.** The owner is out of the janitorial path for the queue they already delegated; the remaining owner-only lifecycle powers are ratification and scope-closing, which is where ADR 0090 wanted the line.
+- **A mis-retire is now self-service to fix, at the rank that caused it** — and, notably, this also removes an Archon-with-ssh chore that existed *before* this grant.
+- **Restore is deliberately not idempotent-friendly the way abandon is.** Calling `/promote` on a non-abandoned task still 409s `cannot_promote` with the current status; the restore path refuses rather than guessing. That keeps `/promote`'s contract honest — it is one route with two explicit source states, not a "make this task alive somehow" verb.
+- **Larger trusted surface, same shape as ADR 0090's.** A Metic can now retire any non-shipped, unclaimed task in any open version, with no per-version/per-module fence. That is the same accepted "tighten later" debt: if Metic authority is ever folded into the goal-scope model ([ADR 0086](<redacted>.md)), abandon travels with it.
+- **Trust boundary intact** ([ADR 0016](<redacted>.md)): enforcement stays server-side, per request, uncached. Editing a doc or `CLAUDE.md` grants nothing; `requireRank('metic','archon')` on the route is the authority.
+
+## Alternatives considered
+
+- **Re-rank abandon with no undo.** Rejected: it relocates the owner-cleanup burden instead of removing it, and the failure mode (a silently-invisible task) is worse than the one it fixes. The undo is ~40 lines including its guards.
+- **A dedicated `POST /tasks/:id/restore` route.** Rejected as surface for its own sake: `/promote` already *is* the "move this task toward workable" verb at exactly the right rank, and the restore is a third source state on it. A separate route would need its own gate, its own pin, its own catalog permission, and its own docs row — all to express the same transition.
+- **Restore straight to `ready`.** Rejected: it would make a two-keystroke mistake (abandon → restore) leave the task claimable again with no human re-read of *why* it was retired. Landing in `backlog` costs one deliberate extra call and puts the scope decision back in front of someone.
+- **Fence the grant (only tasks the Metic authored, or only non-`security_sensitive` ones).** Rejected as a rule builders have to learn for a threat that isn't real here: a Metic can already `PATCH` and re-scope any task, so "abandon only your own" fences nothing they couldn't achieve by editing. ADR 0090 made the same call for authoring.
+- **Promote the affected builders to Archon.** Rejected for the reason ADR 0090 gave: Archon also carries rank-setting, version-close, grader-bypass, and infra — far more than "clean up the task queue."

package/docs/adr/0153-sequential-chain-runner.md

@@ -0,0 +1,51 @@
+# ADR 0153 — Sequential chain execution: one kickoff walks a dependency chain
+
+- **Status:** accepted
+- **Date:** 2026-07-28
+- **Task:** 1002484
+- **Relates to:** [ADR 0015](<redacted>.md) (dependencies + auto-promotion), [ADR 0049](<redacted>.md) (the split parallel-safety contract), [ADR 0086](<redacted>.md) §5 (polymorphic dependency edges)
+
+## Context
+
+ADR 0015 made `dependencies[]` load-bearing: a task cannot be claimed until its predecessors ship, and shipping a task auto-promotes its now-unblocked dependents `backlog`→`ready` (the `promote_dependents_on_ship` trigger, migrations 020/163). That machinery works. What it does not do is **pick the newly-unblocked task up**.
+
+The result, measured on the live instance on 2026-07-28: **146 of 303 open tasks sit behind a predecessor, and only ~79 are `ready`** at any moment. A single planning seed like goal 1000045 fronts a 24-task chain worth 1,440 credits and ~62 hours. Working it meant 24 separate human kickoffs — each one a fresh session that had to re-derive what was now claimable.
+
+The only "sequential" affordance was `<redacted>` in `modules/hall-ui/public/work.js`: a clipboard template listing manually multi-selected tasks in topological order. Two problems. It is *text*, not execution. And the tasks a chain most needs to queue — the dependency-gated successors — are not selectable on the board at all, because they are still `backlog`.
+
+Two builders asked for this independently: idea 1000461 (jaxri — workflows that run tasks "in parallel or sequentially") and idea 1000398 (IAMMASTERQUA — chains as the claimable unit, priced by total chain value).
+
+## Decision
+
+Ship a **chain runner**: one kickoff walks a dependency chain end to end.
+
+**1. No schema change.** The ordering already exists in the polymorphic `dependencies` table, the `task_is_fully_unblocked` predicate, and the promote-on-ship trigger. `GET /tasks/:id` already returns `dependencies[]` and `dependents[]`. Adding a `queue`, `chain_id`, or `next_task` column would create a second, drift-prone source of truth for an order the graph already encodes. The runner derives the chain on demand and stays stateless.
+
+**2. No new claim guard.** One-active-claim-per-session is keyed on the *working tree* (`shouldRefuseSessionClaim`, `modules/lifecycle/routes/claims.js`), so ship-before-next-claim is already enforced — which is exactly the sequential shape. The chain therefore claims **one task at a time**, and a task is always fully `shipped` before the next is claimed. Batch-claiming a chain is not merely discouraged, it is impossible: successors fail `DEPS_NOT_SHIPPED` by construction, because their predecessor has not shipped yet. The ship *is* the thing that unblocks the next step.
+
+**3. Split deterministic plumbing from judgement.** `scripts/gds/sequence.js` resolves scope, orders it, and evaluates a halt matrix — all from facts on the task row, no model judgement. `.claude/skills/builder-sequence/SKILL.md` owns the loop and defers to `/builder-claim`, `/dev`, and `/builder-ship` for their existing mechanics. A halt is a named reason with a non-zero exit code, not a narrative.
+
+**4. Halt, do not skip** (owner decision, 2026-07-28). When the next task is something the runner should not decide alone, it **stops and reports**, leaving that task claimed. It does not ship a half-finished task, and it does not skip ahead to the next unblocked sibling.
+
+The halt matrix: `needs_migration`, `security_sensitive`, `protected_path` (touches[] ∩ `PROTECTED_GLOBS`), `rank_floor`, `thin_spec`, `judgement_kind` (`decision`/`spike`), `not_claimable`, `deps_unmet`, `in_flight`, `cycle`. The skill adds two it must detect itself: `ship_failed` and `scope_surprise`.
+
+## Why halt rather than skip
+
+Skipping looks like the higher-throughput option and is not. In a dependency graph, a skipped task is a *predecessor* — skipping it strands everything behind it, so the run continues while quietly guaranteeing that the rest of the chain cannot complete. The apparent progress is the dangerous part: a run that skipped three tasks and shipped nine reads as a success until someone asks why the chain never finished.
+
+Halting also makes unattended running safe, which is the whole point of one kickoff. The owner can start a chain and walk away knowing the failure mode is "stopped early with a reason", not "made twelve judgement calls you have not seen yet".
+
+## Consequences
+
+- A chain of N mechanical tasks now costs one kickoff instead of N.
+- Chains stop silently stranding: a halt names what a human must do, so the queue does not just quietly stop advancing.
+- The halt matrix is deliberately conservative. Tasks with thin specs will halt runs, which is a **feature** — it turns "the runner stopped" into pressure to write acceptance criteria at planning time.
+- `not_claimable` defers to the server's own claimable feed rather than re-deriving its filter client-side. If that endpoint is unreadable the runner stays quiet rather than halting on everything — an early bug where the envelope key was misread (`tasks` vs `claimable`) turned an empty result into a universal halt, and the null-vs-empty distinction is now covered by a test.
+- **Not built:** chains as a priced, claimable unit on the Tasks board (idea 1000398). The runner is the capability; surfacing chains with their total value is a separate, additive change.
+
+## Alternatives rejected
+
+- **A `chain_id` / queue table.** A second source of truth for an order the dependency graph already encodes, and one that drifts the moment an edge is added.
+- **Batch-claim the whole chain up front.** Impossible under the dep gate, and it would defeat the isolation that makes each ship safe.
+- **Let the runner use judgement and keep shipping** (the third option the owner was offered). Faster, but it moves review after the fact — the owner would be auditing decisions that had already landed.
+- **Extend `overnight-builder`.** That routine walks the claimable queue by priority across the whole backlog; this walks one bounded chain the user pointed at. Different scope, and the routine is instance-only (absent from the portable core).

package/docs/adr/0154-goal-owner-criterion-authoring.md

@@ -0,0 +1,86 @@
+# 0154 — A goal's done-when criteria are authored by that goal's owner or managers
+
+- **Status:** Accepted
+- **Date:** 2026-07-29
+- **Deciders:** Lars (owner / Archon), Claude
+
+**Builds on / amends:** [ADR 0086](<redacted>.md) (the goal tier — this ADR extends its owner/manager authority to the goal's criteria), [ADR 0090](<redacted>.md) (Metic task authoring), [ADR 0106](<redacted>.md) (owner vs manager), [ADR 0105](<redacted>.md) (why this route exists at all), [ADR 0016](<redacted>.md) (server-enforced rank boundary — unchanged), [ADR 0151](<redacted>.md) (permissions-as-atom — and see §5, which corrects one of its rows).
+
+**Track:** `internal` (GDS / methodology). Task [1002538](https://cloudbongos.com/builders#/task/1002538), under the **Builder experience** goal [1000025](https://cloudbongos.com/builders#/goal/1000025).
+
+---
+
+## Context
+
+The Metic planning loop is complete except in one place. A Metic may create a goal ([ADR 0086](<redacted>.md): `POST /goals` is `requireRank('metic','archon')`), author the tasks under it ([ADR 0090](<redacted>.md)), wire their dependencies and criterion links, and **confirm** a criterion when the work lands ([ADR 0086](<redacted>.md) §6 re-ranked `POST /done-when/:criterionId/satisfy` to Metic+ "so the planner — not only the Archon — closes the criterion/goal loop").
+
+But they could not **create** the criteria those tasks are measured against: `POST /versions/:id/done-when` was `requireRank('archon')`. So a Metic could stand up a goal, fill it with work, and close its criteria out — but had to ask an Archon to write them in the first place. That is the one Archon-shaped hole in an otherwise Metic-complete loop, and it is what blocked `/goal-create` ([1002540](https://cloudbongos.com/builders#/task/1002540)) from being a skill a Metic can actually run end to end.
+
+### Why the obvious fix — a flat re-rank — is wrong
+
+The tempting move is symmetry: a Metic may confirm a criterion, so let them create one. That argument does not survive contact with what a criterion *does*.
+
+**Creating an unsatisfied criterion is a backward ratchet, and there is no undo.** Every "is this done" aggregate counts unsatisfied rows:
+
+- `modules/lifecycle/version-close.js` gates on `criteria.satisfied === criteria.total`, counted **per version regardless of goal**. One unsatisfied row parks the version's close suggestion indefinitely — and that suggestion is served on the **unauthenticated** `GET /versions/close-suggestions`, so it is publicly visible.
+- `db.achieveGoalIfComplete` refuses while `unsatisfied > 0`, so the goal never auto-achieves, and `promote_dependents_on_goal_achieve` never releases the tasks waiting on it.
+
+That is operationally the same effect as `POST /done-when/:criterionId/unsatisfy` — which is Archon-only, and which `docs/governance/<redacted>.md` lists in the same Archon "Lifecycle disposition" line as this route. And there is **no DELETE route for a criterion**: descoping is direct SQL under a claim. A mistake is not correctable through the API by anyone.
+
+**The create path also had no ownership check whatsoever.** Its entire authorization surface was `requireBuilder` → `requireRank` → version exists → (if `goal_id` given) the goal belongs to that version. That last one is referential integrity, not authority. Every *other* goal-touching write in the module runs `authorizeGoalManagement` (owner | manager | Archon) or `authorizeGoalTaskCreate` (membership + scope wall). A flat re-rank would therefore have let any Metic attach a permanent, un-deletable criterion to **any goal on any version**, including goals they had never joined and private goals ([ADR 0112](<redacted>.md)) — published to the anonymous status feed.
+
+`docs/canonical-permissions.md` named "set version scope (`done-when`)" as Archon-exclusive. A flat re-rank contradicts that flatly; the decision below narrows it instead.
+
+## Decision
+
+**Authority over a goal's criteria follows goal ownership, not global rank.**
+
+`POST /versions/:id/done-when` becomes `requireRank('metic','archon')`, plus an **ordered, fail-closed in-handler wall** for any non-Archon:
+
+| Step | Refusal |
+|---|---|
+| a `goal_id` must be named | `403 goal_id_required` |
+| the caller must be the goal's **owner or a manager** | `400 bad_goal_id` — **masked**, see below |
+| the goal must be `open` | `409 goal_not_open` |
+| the version must be open (`planning` or `building`) | `409 version_closed` |
+
+An Archon short-circuits all four: version-level (goal-less) criteria, goals in any state, and versions in any state stay theirs.
+
+The authority predicate is `isGoalOwnerOrManager` — the **same** owner-or-manager test behind visibility changes, invitations, join-request responses, member roles and conflict resolution. It moved from `modules/lifecycle/routes/goals.js` to a module sibling, `modules/lifecycle/goal-authz.js`, so both routes share one definition of "who holds this goal"; `authorizeGoalManagement` is rebuilt on it and re-exported from `routes/goals.js`, so its existing DB-free tests are untouched. No route requires another route.
+
+### Authority is checked before state, and the refusal is masked
+
+Ordering matters here in a way it does not for the sibling goal routes. Those are reached by callers who already know the goal exists (they are looking at it); this one takes an arbitrary integer `goal_id` from any Metic.
+
+If the refusals were distinguishable — `400 bad_goal_id` (no such goal) vs `403 not_owner_or_manager` (exists, not yours) vs `409 goal_not_open` (exists, settled) — the route would be an **existence oracle**: a Metic could enumerate `goal_id`s and learn which exist on a version, including **private goals** ([ADR 0112](<redacted>.md)). That surface did not exist while the route was Archon-only, because an Archon can already read every goal. Re-ranking it creates the surface, so the re-rank has to close it.
+
+So the ownership test runs **ahead of** both state checks, and a caller who fails it gets byte-identical `400 bad_goal_id` to one naming a goal that does not exist — same code, same message, same envelope, rendered by the same `badGoalId()` helper the genuine-absence branch uses. Only someone who already holds the goal learns anything further about it. This mirrors the O1 no-leak ordering the goal abuse matrix already pins (`not_a_member` is returned before any scope hint).
+
+**What does not move.** `POST /done-when/:criterionId/unsatisfy` stays Archon — un-flipping a *confirmed* criterion rewrites shipped scope-truth, and keeping the backward ratchet at the top rank is the safety this grant is paired with. It was previously **unpinned** in `route-rank-check`; this ADR pins it at `archon` so a silent downgrade reds the build.
+
+### Why this is the right boundary
+
+Creating a criterion inside a goal you own is not scope-*truth* authorship in the sense the Archon gate was protecting — it is describing the finish line of a workspace you are already accountable for. The blast radius is bounded by something the actor already holds. Creating a criterion at the *version* level, or inside someone else's goal, still shapes the project's scope for other people, and that stays Archon.
+
+## Consequences
+
+- `/goal-create` becomes genuinely Metic-runnable: create the goal → write its criteria → seed its tasks, in one session, without an Archon in the loop.
+- A Metic can still park **their own** goal by adding a criterion they never satisfy. That is a self-inflicted wound inside their own workspace, visible in `/goal-review`, not an attack on anyone else's.
+- The proposal → ratify queue (`kind='criterion-proposal'` → `POST /inbox/:id/ratify`, Archon-only) remains the path for **version-level** criteria and for anyone who is not the goal's owner. It is no longer the only path for a goal owner describing their own goal. Note the direct path writes one row and awards no `proposal_ratified` karma and no `criterion_proposal_audit` provenance — proposals remain the richer, attributable route, and the one an Archon adjudicates.
+- Five generated artifacts regenerate (`docs/api/openapi.json`, `docs/api-reference.md`, `docs/routes-permissions.md`, `clients/bongos-client/*`), because the rank flows into the published contract via the `// rank:` annotation.
+
+## §5 — A correction to ADR 0151's catalog
+
+[ADR 0151](<redacted>.md)'s "floor `metic` today" table bundles three routes into one row:
+
+> `criterion.satisfy` / `criterion.review` | `POST /done-when/:id/satisfy`, `GET /done-when/pending-review`, `POST /versions/:id/done-when`
+
+Two of those were Metic; the third (`POST /versions/:id/done-when`) was **Archon** at the time that table was written. 0151's own cited source — the exhaustive `docs/governance/<redacted>.md` — lists it correctly under Archon. The bundled row was a transcription slip, and it was latent-dangerous: 0151's R94 compat seed grants "exactly today's powers," so seeding from that row would have handed the `metic` role an Archon route, and R103's parity test would either have gone red or, worse, ratified the escalation.
+
+This ADR makes the row's *outcome* correct but for a different reason, so the row is split anyway: `criterion.create` is its own atom, floor `metic`, **qualified by the goal-ownership wall above** — a floor alone does not describe this permission.
+
+## Alternatives considered
+
+- **Leave it Archon; use the proposal queue.** Rejected: it keeps the Archon in the loop for a Metic describing a goal they own, which is the janitorial-delegation problem [ADR 0152](<redacted>.md) already named. The queue survives for the cases that genuinely need adjudication.
+- **Flat re-rank to Metic+.** Rejected — §Context.
+- **Add a DELETE for criteria so the ratchet has an undo** (the [ADR 0152](<redacted>.md) "pair the grant with its inverse" pattern). Deferred, not rejected: it is the honest completion of "manage," and it would neutralise the no-undo objection directly. It is a new capability nobody has today — including Archons — and deleting a criterion with linked `task_criteria` rows needs its own cascade decision. Worth its own task.