@bongos/core 1.18.19 → 1.19.2

package/modules/lifecycle/github-push.js

@@ -682,21 +682,48 @@ function landConfirmed(status) {
 // it must be an ancestor of main. NOTE claims.head_sha is the claim-TIME base — for a
 // task whose base is already on main (e.g. an R03 base) an ancestry check on it
 // false-positives — so we deliberately key on the published tip, never the base.
-// When no tip was recorded (a legacy row, or a publish in flight across the deploy
-// that introduced the column), fall back to verifying the matched PR references this
-// task id. Returns { proven, reason }. The compare call is the only network hop and
-// is injected-deps-pure for tests.
+//
+// task 1002615 (idea 1000613) — a land made OUT-OF-BAND must still prove. A squash-
+// or rebase-merge (e.g. the owner landing the PR through the GitHub web UI) REWRITES
+// the landed commit, so the recorded tip is never an ancestor of main even though the
+// work is live — the old early-return stranded exactly that shape, unpaid. When the
+// tip check misses, fall through to a second git-history proof: the matched PR is
+// MERGED, names THIS task, and its merge_commit_sha is contained in main (that sha is
+// the main-side commit under all three merge methods). Reference match PLUS ancestry
+// is strictly stronger than the legacy no-tip fallback, so it cannot widen the
+// branch-reuse false-ship this function guards.
+//
+// When no tip was recorded at all (a legacy row, or a publish in flight across the
+// deploy that introduced the column), fall back to the matched PR referencing this
+// task id — now requiring merged:true (task 1002615), because the reconciler consults
+// this proof while a PR is still in flight and an OPEN PR that merely references the
+// task must never count as a land. Returns { proven, reason }. The compare calls are
+// the only network hops and are injected-deps-pure for tests.
 async function landProvenForTask({ taskId, publishedSha, status }, deps = {}) {
-  if (publishedSha && SAFE_SHA_RE.test(String(publishedSha))) {
+  const hasTip = !!(publishedSha && SAFE_SHA_RE.test(String(publishedSha)));
+  if (hasTip) {
     const inMain = await isAncestorOfDefaultBranch({ sha: publishedSha }, deps);
-    return inMain
-      ? { proven: true, reason: `published tip ${publishedSha.slice(0, 8)} in main` }
-      : { proven: false, reason: `published tip ${publishedSha.slice(0, 8)} not in main (branch-reuse/stale PR)` };
+    if (inMain) return { proven: true, reason: `published tip ${publishedSha.slice(0, 8)} in main` };
+  }
+  if (status && status.merged === true && prReferencesTask(status, taskId)
+      && status.merge_sha && SAFE_SHA_RE.test(String(status.merge_sha))) {
+    let mergeInMain = false;
+    try {
+      mergeInMain = await isAncestorOfDefaultBranch({ sha: status.merge_sha }, deps);
+    } catch (_) {
+      /* transient compare miss → fall through; the next sweep retries */
+    }
+    if (mergeInMain) {
+      return { proven: true, reason: `merged PR for task ${taskId} — merge ${String(status.merge_sha).slice(0, 8)} in main (out-of-band/squash land)` };
+    }
+  }
+  if (hasTip) {
+    return { proven: false, reason: `published tip ${String(publishedSha).slice(0, 8)} not in main (branch-reuse/stale PR)` };
   }
-  if (prReferencesTask(status, taskId)) {
+  if (status && status.merged === true && prReferencesTask(status, taskId)) {
     return { proven: true, reason: `matched PR references task ${taskId} (no published tip recorded)` };
   }
-  return { proven: false, reason: `no published tip recorded and matched PR does not reference task ${taskId}` };
+  return { proven: false, reason: `no published tip recorded and no MERGED PR references task ${taskId}` };
 }
 
 // task 1313 — proof-of-land that does NOT depend on the PR/branch still existing.

package/modules/lifecycle/publish-reconciler.js

@@ -40,6 +40,34 @@
 // An 8-strand backlog (incl. a Xenos's onboarding ships that never counted) is what
 // surfaced this.
 //
+// task 1002615 (idea 1000613) — recognise a land made OUT-OF-BAND. Two residual
+// blind spots stranded a task whose work was verifiably on main: the sweep only
+// consulted the per-task land proof when the branch's PR reported fully landed
+// (prNotLanded suppressed it), and the proof itself gave up when the recorded
+// published tip wasn't an ancestor of main. A human landing the PR by hand is
+// completely normal — a web-UI squash/rebase REWRITES the landed sha (tip ancestry
+// can never pass), and a manual `git merge` straight to main leaves the PR open or
+// closed-unmerged (prNotLanded suppressed the proof forever). Both shapes left the
+// builder unpaid for landed work (the 2026-07-29 reproduction on task 1002525). Now
+// the proof answers from git history on main — tip ancestry, else the merged PR's
+// merge_commit_sha ancestry — the same authoritative-source principle as task 879
+// (git is the collision detector, not the bookkeeping). One deliberate exception:
+// a MERGED PR still mid-deploy keeps governing — on a deploy-enabled instance
+// 'shipped' means merged AND deployed, and the merge puts the tip in main minutes
+// before the deploy finishes.
+//
+// task 1002606 (finding P-3 — the DETECTION half; 1002615 fixed the cause half) —
+// a strand must reach its builder when it is DETECTED, not at the 30-minute stale
+// WARN. Two shapes are definitive the moment the sweep sees them: a hand-written
+// merge conflict (the ADR 0082 driver can never resolve it) and a PR closed
+// without merging (auto-merge is dead; the land proof already refused it).
+// Both now flag needs_rebase immediately — which surfaces in /builder-start's
+// rebase warning and gates the builder's new claims (ADR 0120 part 3) — and
+// every NEWLY-flagged strand additionally emits `task.strand-flagged` on the
+// kernel seam, giving strands the push channel that previously only
+// `task.shipped` had (the Discord module listens and posts a notice). Ambiguous
+// shapes (open PR, CI still running, no proof yet) keep the 30-min grace.
+//
 // Mirrors the in-process poller precedent (src/bongos/uptime-poller.js) and the
 // Discord reconcile timers (src/bongos/discord-bot.js): unref'd timers (never hold
 // the process open), best-effort (a GitHub/DB hiccup logs and waits for the next
@@ -145,7 +173,7 @@ async function runSweep(deps = {}) {
         `[publish-reconciler] WARN ${describeTarget({ configured: false, repo: resolveTarget(deps) })} — confirmed→shipped can NEVER land until a credential is set (GITHUB_APP_ID + GITHUB_APP_INSTALLATION_ID + GITHUB_APP_PRIVATE_KEY, or GITHUB_PUSH_TOKEN). Subsequent sweeps stay quiet until this changes.`
       );
     }
-    return { skipped: 'unconfigured', checked: 0, reconciled: 0, merged: 0, resolvedConflicts: 0, errors: 0 };
+    return { skipped: 'unconfigured', checked: 0, reconciled: 0, merged: 0, resolvedConflicts: 0, errors: 0, strandsFlagged: 0 };
   }
   warn.unconfigured = false; // re-arm: a later credential LOSS must warn again
 
@@ -154,7 +182,7 @@ async function runSweep(deps = {}) {
     rows = await db.listConfirmedTasksForReconcile({ limit: deps.limit || SWEEP_LIMIT });
   } catch (e) {
     errFn(`[publish-reconciler] could not list confirmed tasks: ${e && e.message}`);
-    return { skipped: 'list_failed', checked: 0, reconciled: 0, merged: 0, resolvedConflicts: 0, errors: 1 };
+    return { skipped: 'list_failed', checked: 0, reconciled: 0, merged: 0, resolvedConflicts: 0, errors: 1, strandsFlagged: 0 };
   }
 
   // Safety: a worktree_name can be reused across sequential (released) claims, so
@@ -175,9 +203,43 @@ async function runSweep(deps = {}) {
   let errors = 0;
   let unprovable = 0;   // confirmed tasks the sweep could not prove landed this pass
   let staleStrands = 0; // of those, the ones older than STALE_CONFIRMED_MS (WARN'd)
+  let strandsFlagged = 0; // task 1002606: needs_rebase flags NEWLY set this sweep (any site)
   const attempts = deps.healAttempts || healAttempts; // injectable for deterministic tests
   const branchesSeen = new Set();                     // to prune the attempts map post-sweep
   const nowMs = Date.now();
+
+  // task 1002606 — the ONE exit for every strand signal: flag needs_rebase
+  // (idempotent — a re-sweep is a no-op), WARN with the concrete cause, and on a
+  // NEW flag emit `task.strand-flagged` so a listening module (the Discord
+  // mirror) can push the strand to its builder the moment it is detected instead
+  // of leaving it to be found at the next session start. Best-effort on every
+  // leg — a DB or listener hiccup logs and never breaks the sweep.
+  const announceStrand = async (row, reason, describe) => {
+    let flagged = false;
+    try {
+      flagged = await db.flagTaskNeedsRebase(row.task_id, reason);
+    } catch (e) {
+      errFn(`[publish-reconciler] flagNeedsRebase task ${row.task_id} (non-blocking): ${e && e.message}`);
+    }
+    errFn(
+      `[publish-reconciler] STRAND task ${row.task_id}: ${describe}; ${flagged ? 'flagged needs_rebase for its builder' : 'needs_rebase already set'}`
+    );
+    if (flagged) {
+      strandsFlagged++;
+      try {
+        await emit('task.strand-flagged', {
+          id: row.task_id,
+          builder_id: row.builder_id,
+          title: row.title,
+          security_sensitive: row.security_sensitive,
+          reason,
+        });
+      } catch (e) {
+        errFn(`[publish-reconciler] strand broadcast for task ${row.task_id} (non-blocking): ${e && e.message}`);
+      }
+    }
+    return flagged;
+  };
   for (const r of rows) {
     const branch = r.worktree_name ? `claude/${r.worktree_name}` : null;
     if (branch) branchesSeen.add(branch);
@@ -192,9 +254,12 @@ async function runSweep(deps = {}) {
     let landed = false;
     let landNote = '';
     let branchStatus = null;
-    // task 1002472 — set when a PR exists but has not fully landed. Suppresses the
-    // land proof (an open PR must never ship) WITHOUT suppressing the observability
-    // below, which the old bare `continue` did.
+    // task 1002472 — set when a PR exists but has not fully landed. Classifies the
+    // unprovable reason for the observability below (which the old bare `continue`
+    // skipped). task 1002615: it no longer suppresses the land proof — the proof
+    // itself refuses an un-merged PR (its reference fallback requires merged:true),
+    // so an open PR still can't ship by reference, while a task whose WORK is
+    // already on main (out-of-band merge) can now prove it by ancestry.
     let prNotLanded = false;
 
     if (branchUsable) {
@@ -232,8 +297,16 @@ async function runSweep(deps = {}) {
                   `[publish-reconciler] task ${r.task_id} (${branch}) PR #${m.number} conflicted only on generated/index files — server-resolved + pushed; checks re-run, lands next sweep`
                 );
               } else if (rr && rr.skipped === 'unresolvable_conflict') {
-                logFn(
-                  `[publish-reconciler] task ${r.task_id} (${branch}) PR #${m.number} has a hand-written conflict (${(rr.conflicted || []).join(', ') || 'unknown'}) — left for a human`
+                // task 1002606 (P-3 detection): a hand-written conflict is DEFINITIVE —
+                // the driver can never resolve it and the PR sits red until a human
+                // acts — so the builder is told NOW, not at the 30-min stale WARN with
+                // a vague reason. The file list rides in the reason so /builder-start's
+                // rebase warning says WHERE to look.
+                const files = (rr.conflicted || []).slice(0, 5).join(',');
+                await announceStrand(
+                  r,
+                  `strand:unresolvable_conflict${files ? `:${files}` : ''}`,
+                  `PR #${m.number} (${branch}) has a hand-written conflict (${files || 'unknown files'}) only its builder can resolve`
                 );
               }
             } catch (e) {
@@ -263,13 +336,12 @@ async function runSweep(deps = {}) {
               // is exhausted and the PR is still red — a real check failure or a
               // hand-written conflict only the builder can resolve. Flag needs_rebase
               // so their queue is gated until they fix + re-land (or release it).
-              try {
-                if (await db.flagTaskNeedsRebase(r.task_id, `failing_check_capped:${m.reason}`)) {
-                  logFn(`[publish-reconciler] task ${r.task_id} flagged needs_rebase (regen-heal cap) — its builder must fix + re-land`);
-                }
-              } catch (e) {
-                errFn(`[publish-reconciler] flagNeedsRebase (cap) task ${r.task_id} (non-blocking): ${e && e.message}`);
-              }
+              // task 1002606: announceStrand also pushes task.strand-flagged.
+              await announceStrand(
+                r,
+                `failing_check_capped:${m.reason}`,
+                `PR #${m.number} (${branch}) still red after ${n} regen-heal attempt(s) (${m.reason}) — a real check failure or conflict only its builder can fix`
+              );
             } else {
               try {
                 const rr = await resolver.refreshStaleGenerated({ branch });
@@ -307,14 +379,24 @@ async function runSweep(deps = {}) {
       }
       if (!push.landConfirmed(status) && status && status.pr_state !== 'none') {
         // A PR exists but hasn't fully landed yet (open / merged-but-deploy-pending /
-        // blocked). Respect it — wait for the deploy — rather than risk shipping early.
+        // blocked). Respect the PR path — wait for the deploy — rather than merge-ship
+        // early on it.
         //
         // task 1002472: this used to be a bare `continue`, which jumped PAST the
         // unprovable counter, the STALE WARN and flagTaskNeedsRebase below — so this
         // strand shape was completely invisible (tasks 1002427/1002428 sat 50h at
-        // 'confirmed' reporting needs_rebase:false). Flag it instead and fall through
-        // to the observability block. The flag still suppresses the land proof, so an
-        // un-landed PR is no more shippable than it was.
+        // 'confirmed' reporting needs_rebase:false). Flag it instead and fall through.
+        //
+        // task 1002615: an UN-merged PR no longer suppresses the land proof — an
+        // out-of-band land (manual git merge to main with the PR left open or
+        // closed-unmerged) makes the PR report "not landed" while the WORK is on
+        // main, and suppressing the proof stranded exactly that shape, unpaid. The
+        // proof refuses reference-only claims on an un-merged PR, so a genuinely
+        // in-flight PR stays exactly as un-shippable as before. A MERGED PR still
+        // mid-deploy DOES keep governing (prMidDeploy below): on a deploy-enabled
+        // instance 'shipped' means merged AND deployed, and the merge puts the tip
+        // in main minutes before the deploy finishes — the tip proof must not
+        // short-circuit that window.
         prNotLanded = true;
       }
       branchStatus = status;
@@ -330,7 +412,11 @@ async function runSweep(deps = {}) {
     // references this task id. landProvenForTask still cures the task-1313 strand class
     // (PR deleted post-merge / no worktree_name / ambiguous branch) — now keyed on the
     // unambiguous published tip rather than the base.
-    if (!landed && !prNotLanded && typeof push.landProvenForTask === 'function') {
+    // task 1002615: only a MERGED PR that is still deploying suppresses the proof
+    // (the deploy gate governs); an un-merged PR — open, or closed without merging —
+    // cannot veto what git history on main already shows.
+    const prMidDeploy = prNotLanded && !!(branchStatus && branchStatus.merged === true);
+    if (!landed && !prMidDeploy && typeof push.landProvenForTask === 'function') {
       try {
         const proof = await push.landProvenForTask({
           taskId: r.task_id, publishedSha: r.published_head_sha, status: branchStatus,
@@ -355,9 +441,18 @@ async function runSweep(deps = {}) {
       // task 1002472: 'pr_not_landed' distinguishes "a PR exists and we are waiting on
       // it" from "we looked for proof and found none" — the two need different
       // remediation (wait/unblock the PR vs. push or rebase the branch).
-      const reason = prNotLanded
-        ? 'pr_not_landed'
-        : (!branch && !r.published_head_sha) ? 'no_branch_no_tip' : 'land_not_proven';
+      // task 1002606: 'pr_closed_unmerged' is carved out of it as DEFINITIVE — a PR
+      // closed without merging will never land on its own (auto-merge is dead and the
+      // land proof above already refused it), so it must not enjoy the 30-min grace
+      // that exists for CI legitimately still running. (A MERGED PR mid-deploy has
+      // merged=true and stays on the graced 'pr_not_landed' path.)
+      const prClosedUnmerged = prNotLanded && !!branchStatus &&
+        branchStatus.pr_state === 'closed' && branchStatus.merged !== true;
+      const reason = prClosedUnmerged
+        ? 'pr_closed_unmerged'
+        : prNotLanded
+          ? 'pr_not_landed'
+          : (!branch && !r.published_head_sha) ? 'no_branch_no_tip' : 'land_not_proven';
       const ageMs = r.confirmed_at ? (nowMs - new Date(r.confirmed_at).getTime()) : null;
       if (ageMs != null && ageMs > STALE_CONFIRMED_MS) {
         staleStrands++;
@@ -369,14 +464,16 @@ async function runSweep(deps = {}) {
         // NEW claims until they land or release it. Since the reward now lands only
         // on ship (part 1), they are motivated to clear it. NOTE it is no longer
         // "credited" — part 1 moved the payout from confirm to the land.
-        let flagged = false;
-        try {
-          flagged = await db.flagTaskNeedsRebase(r.task_id, `strand:${reason}`);
-        } catch (e) {
-          errFn(`[publish-reconciler] flagNeedsRebase (strand) task ${r.task_id} (non-blocking): ${e && e.message}`);
-        }
-        errFn(
-          `[publish-reconciler] STRAND task ${r.task_id}: confirmed ~${Math.round(ageMs / 3_600_000)}h ago, unprovable (${reason}) — no landed proof; ${flagged ? 'flagged needs_rebase for its builder' : 'needs_rebase already set'}`
+        await announceStrand(
+          r,
+          `strand:${reason}`,
+          `confirmed ~${Math.round(ageMs / 3_600_000)}h ago, unprovable (${reason}) — no landed proof`
+        );
+      } else if (prClosedUnmerged) {
+        await announceStrand(
+          r,
+          `strand:${reason}`,
+          `its PR was closed without merging — it will never land on its own`
         );
       }
       continue;
@@ -423,7 +520,7 @@ async function runSweep(deps = {}) {
       `[publish-reconciler] ${staleStrands} stale strand(s): confirmed >${Math.round(STALE_CONFIRMED_MS / 60_000)}min with no provable land — credited but unlanded; see STRAND lines above`
     );
   }
-  return { checked: rows.length, reconciled, merged, resolvedConflicts, refreshedStale, errors, unprovable, staleStrands };
+  return { checked: rows.length, reconciled, merged, resolvedConflicts, refreshedStale, errors, unprovable, staleStrands, strandsFlagged };
 }
 
 // task 1366 — server-side session-cost reconcile, piggybacked on the same 5-min

package/modules/lifecycle/routes/claims.js

@@ -37,7 +37,7 @@ function resolveCreatorSessionId(bindSession, sessionId) {
 function taskNotReadyHint(taskId, currentStatus) {
   const idNum = Number(taskId);
   return currentStatus === 'backlog'
-    ? `Task #${idNum} is in 'backlog' — promote it first: POST /api/bongos/tasks/${idNum}/promote (Archon), then claim.`
+    ? `Task #${idNum} is in 'backlog' — promote it first: POST /api/bongos/tasks/${idNum}/promote (Metic+), then claim.`
     : `Task #${idNum} is '${currentStatus}', not 'ready' — only 'ready' tasks are claimable (promote applies to 'backlog': POST /api/bongos/tasks/${idNum}/promote).`;
 }
 
@@ -259,6 +259,10 @@ module.exports = function buildClaimsRouter() {
           // tasks (already 'ready' at migration 177) are exempt and never reach here.
           err.code === 'REWARD_REQUIRED' ? 409 :
           err.code === 'ALREADY_CLAIMED' ? 409 :
+          // task 1002589: migration 180's per-session index tripped at the DB
+          // layer (claimTask maps the 23505 by err.constraint). Same 409 family
+          // as the route gate's session_already_has_active_claim above.
+          err.code === 'session_already_has_bound_claim' ? 409 :
           err.code === 'BUILDER_INACTIVE' ? 403 :
           // V3.R15 #239: rank_too_low_for_task is the canonical Xenos-gate code;
           // XENOS_RESTRICTED is the pre-rename alias still honored by callers
@@ -306,8 +310,10 @@ module.exports = function buildClaimsRouter() {
       // task 1802: omitting the flag (the real-CLI-session default) no longer
       // binds every row — db.claimTasksBatch only binds the FIRST inserted
       // claim to the caller's session and leaves the rest unbound, so a real
-      // session can batch-claim 2+ tasks without tripping
-      // uniq_active_claim_per_session (migration 180) on the 2nd+ INSERT. A
+      // session can batch-claim 2+ tasks without tripping the per-session
+      // backstop index on the 2nd+ INSERT (migration 180; re-keyed per
+      // (session, worktree) by core_204, where a prefix-less batch's NULL
+      // worktrees still fold into one group — first-row binding stays). A
       // single-task batch call is unaffected (first row IS the only row).
       bind_session: { type: 'boolean' },
     })) return;
@@ -502,7 +508,7 @@ module.exports = function buildClaimsRouter() {
   // grep can find every third-party release.
   router.post('/claims/:id/release-on-behalf',
     auth.requireBuilder,
-    auth.requireRank('archon'),
+    auth.requirePermission('claim.release.any'),
     async (req, res) => {
       if (validateOrRespond(req, res, {
         reason: { required: true, type: 'string', maxLength: LIMITS.NOTES },

package/modules/lifecycle/routes/dependencies.js

@@ -53,7 +53,7 @@ module.exports = function buildDependenciesRouter() {
 
   // POST /dependencies — create an edge "from is blocked until to is done".
   // rank: archon.
-  router.post('/dependencies', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+  router.post('/dependencies', auth.requireBuilder, auth.requirePermission('dependency.cross_tier.manage'), async (req, res) => {
     const edge = parseEdge(req, res);
     if (!edge) return;
     try {
@@ -66,7 +66,7 @@ module.exports = function buildDependenciesRouter() {
 
   // DELETE /dependencies — remove an edge (body carries the 4-tuple).
   // rank: archon.
-  router.delete('/dependencies', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+  router.delete('/dependencies', auth.requireBuilder, auth.requirePermission('dependency.cross_tier.manage'), async (req, res) => {
     const edge = parseEdge(req, res);
     if (!edge) return;
     try {

package/modules/lifecycle/routes/done-when.js

@@ -116,7 +116,7 @@ module.exports = function buildDoneWhenRouter() {
   //     bad_goal_id so the route is not an existence oracle (ADR 0112).
   // Pinned in route-rank-check.MODULE_EXPECTED_RANKS.
   // rank: metic+archon — criterion create, walled by goal ownership (ADR 0154).
-  router.post('/versions/:id/done-when', auth.requireBuilder, auth.requireRank('metic', 'archon'), asyncHandler('POST /versions/:id/done-when', async (req, res) => {
+  router.post('/versions/:id/done-when', auth.requireBuilder, auth.requirePermission('criterion.create'), asyncHandler('POST /versions/:id/done-when', async (req, res) => {
     const versionId = String(req.params.id || '').trim();
     if (!versionId) return res.fail('version_id_required', 400);
     if (validateOrRespond(req, res, {
@@ -176,7 +176,7 @@ module.exports = function buildDoneWhenRouter() {
   // match the satisfy route below — this is the planner's closing queue, not a
   // public surface.
   // rank: metic+archon — the planner review queue (mirrors the satisfy gate).
-  router.get('/done-when/pending-review', auth.requireBuilder, auth.requireRank('metic', 'archon'), asyncHandler('GET /done-when/pending-review', async (req, res) => {
+  router.get('/done-when/pending-review', auth.requireBuilder, auth.requirePermission('criterion.review'), asyncHandler('GET /done-when/pending-review', async (req, res) => {
     const versionId = String(req.query.version || '').trim() || null;
     const criteria = await doneWhen.listPendingReviewCriteria({ versionId });
     res.json({ criteria, count: criteria.length });
@@ -190,7 +190,7 @@ module.exports = function buildDoneWhenRouter() {
   // pinned in route-rank-check.MODULE_EXPECTED_RANKS.lifecycle so a further
   // downgrade is caught.
   // rank: metic+archon — criterion confirmation + goal auto-achieve (the closing loop).
-  router.post('/done-when/:criterionId/satisfy', auth.requireBuilder, auth.requireRank('metic', 'archon'), asyncHandler('POST /done-when/:criterionId/satisfy', async (req, res) => {
+  router.post('/done-when/:criterionId/satisfy', auth.requireBuilder, auth.requirePermission('criterion.satisfy'), asyncHandler('POST /done-when/:criterionId/satisfy', async (req, res) => {
     if (validateOrRespond(req, res, {
       satisfied_by_task_id: { type: 'integer', min: 1 },
     })) return;
@@ -213,7 +213,7 @@ module.exports = function buildDoneWhenRouter() {
 
   // Auth: flip a criterion back to unsatisfied (rare; for corrections).
   // rank: archon — un-flip a criterion; same gate as satisfy.
-  router.post('/done-when/:criterionId/unsatisfy', auth.requireBuilder, auth.requireRank('archon'), asyncHandler('POST /done-when/:criterionId/unsatisfy', async (req, res) => {
+  router.post('/done-when/:criterionId/unsatisfy', auth.requireBuilder, auth.requirePermission('criterion.unsatisfy'), asyncHandler('POST /done-when/:criterionId/unsatisfy', async (req, res) => {
     const id = parseId(req, res, { param: 'criterionId', code: 'bad_criterion_id' });
     if (id === null) return;
     const existing = await doneWhen.getCriterion(id);

package/modules/lifecycle/routes/gate-approvals.js

@@ -64,8 +64,14 @@ module.exports = function buildGateApprovalsRouter() {
   const router = express.Router();
 
   // GET /gate-approvals — open PRs awaiting owner approval (gate-review red), with the
-  // verdict + per-file reasons + changed files + diff link. rank: archon.
-  router.get('/gate-approvals', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+  // verdict + per-file reasons + changed files + diff link. rank: metic+archon.
+  // BV1.R105 left this on requireRank because `gate_approval.decide` was declared over
+  // the /approve WRITE only and no atom named the read. ADR 0157 extends the catalog
+  // with exactly that atom — `gate_approval.read`, floor metic — so the mapping is now
+  // one the catalog makes. The split is load-bearing, not cosmetic: `page.view.governance`
+  // opens /gate to Metic, and without a Metic-readable data endpoint that page would
+  // render nothing but a 403. Approving a held PR stays archon (`.decide`, system).
+  router.get('/gate-approvals', auth.requireBuilder, auth.requirePermission('gate_approval.read'), async (req, res) => {
     if (!githubPush.isConfigured()) {
       return res.fail('publish_unconfigured', { status: 503, message: 'No server GitHub credential configured — cannot read pull requests.' });
     }
@@ -130,7 +136,7 @@ module.exports = function buildGateApprovalsRouter() {
   // POST /gate-approvals/:pr/approve — record owner approval for a stuck gate PR and
   // re-run the gate-review check so it clears. rank: archon (clears the hard floor —
   // pinned in route-rank-check.EXPECTED_RANKS for downgrade protection).
-  router.post('/gate-approvals/:pr/approve', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+  router.post('/gate-approvals/:pr/approve', auth.requireBuilder, auth.requirePermission('gate_approval.decide'), async (req, res) => {
     const number = parseId(req, res, { param: 'pr', code: 'bad_pr', positiveInt: true });
     if (number == null) return;
     if (!githubPush.isConfigured()) {

package/modules/lifecycle/routes/goals.js

@@ -379,7 +379,7 @@ module.exports = function buildGoalsRouter() {
   // POST /goals — create a goal.
   // rank: metic+archon — a Metic or Archon may create a goal; creation of a goal
   // whose scope_modules includes a PROTECTED module is Archon-only (in-handler).
-  router.post('/goals', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+  router.post('/goals', auth.requireBuilder, auth.requirePermission('goal.create'), async (req, res) => {
     if (validateOrRespond(req, res, {
       version_id: { required: true, type: 'string', minLength: 1, maxLength: 64 },
       title: { required: true, type: 'string', minLength: 1, maxLength: LIMITS.TITLE },
@@ -457,7 +457,7 @@ module.exports = function buildGoalsRouter() {
   // Mounted BEFORE GET /goals/:id so 'reorder' is never captured as an id.
   // rank: archon — priority is an owner decision, never self-granted by a
   // goal's own member/manager (unlike the goal-authority routes above).
-  router.post('/goals/reorder', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+  router.post('/goals/reorder', auth.requireBuilder, auth.requirePermission('goal.reorder'), async (req, res) => {
     if (validateOrRespond(req, res, {
       version_id: { required: true, type: 'string', minLength: 1, maxLength: 64 },
       ordered_ids: { required: true, type: 'array', maxItems: 500, itemsType: 'integer' },
@@ -1232,7 +1232,7 @@ module.exports = function buildGoalsRouter() {
   // goals are re-openable (below). This is the lifecycle disposition the /goal-review
   // skill reaches for once a goal is achieved (ADR 0086 §6 / BV1.R64).
   // rank: metic+archon — a goal member (Metic+) or an Archon dispositions the goal.
-  router.post('/goals/:id/archive', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+  router.post('/goals/:id/archive', auth.requireBuilder, auth.requirePermission('goal.archive'), async (req, res) => {
     const id = parseId(req, res, { code: 'bad_goal_id' });
     if (id === null) return;
     try {
@@ -1255,7 +1255,7 @@ module.exports = function buildGoalsRouter() {
   // POST /goals/:id/reopen — bring an archived goal back to open (ADR 0086 §6 /
   // BV1.R64). Only archived → open; an already open/achieved goal is a 409.
   // rank: metic+archon — same gate as archive.
-  router.post('/goals/:id/reopen', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+  router.post('/goals/:id/reopen', auth.requireBuilder, auth.requirePermission('goal.archive'), async (req, res) => {
     const id = parseId(req, res, { code: 'bad_goal_id' });
     if (id === null) return;
     try {
@@ -1283,7 +1283,7 @@ module.exports = function buildGoalsRouter() {
   // ask a Metic+/Archon out-of-band, exactly as joining a protected goal works (R57).
   // The goal must be open. Body: { add: ["module-key", ...] }; idempotent (set-union).
   // rank: metic+archon — widens the module wall; pinned in route-rank-check.EXPECTED_RANKS.
-  router.post('/goals/:id/scope', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+  router.post('/goals/:id/scope', auth.requireBuilder, auth.requirePermission('goal.scope.widen'), async (req, res) => {
     const id = parseId(req, res, { code: 'bad_goal_id' });
     if (id === null) return;
     if (validateOrRespond(req, res, {

package/modules/lifecycle/routes/tasks.js

@@ -309,7 +309,7 @@ module.exports = function buildTasksRouter() {
   // BACKSTOP for the on-claim restock (the live mechanism is the post-claim hook
   // in routes/claims.js). Archon-gated like all task creation (ADR 0016). Must
   // be registered BEFORE GET /tasks/:id so ':id' doesn't swallow the literal.
-  router.post('/tasks/newcomer-restock', auth.requireBuilder, auth.requireRank('archon'), async (_req, res) => {
+  router.post('/tasks/newcomer-restock', auth.requireBuilder, auth.requirePermission('task.newcomer_restock'), async (_req, res) => {
     try {
       // The newcomer-chore restock carved into modules/onboarding/ (BV1.R81 / ADR
       // 0093 §1): resolve the `onboarding` kernel port — never a direct require.
@@ -368,7 +368,7 @@ module.exports = function buildTasksRouter() {
   //                                       { depends_on_task_ids: [N, ...] }
   // Returns 409 with code='cycle' if accepting would create a cycle.
   // rank: metic+archon — task-shaping; Metic may wire deps of a task it can author (ADR 0090).
-  router.post('/tasks/:id/dependencies', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+  router.post('/tasks/:id/dependencies', auth.requireBuilder, auth.requirePermission('task.dependency.manage'), async (req, res) => {
     if (validateOrRespond(req, res, {
       depends_on_task_ids: { type: 'array', maxItems: 200 },
       // depends_on_task_id can be a number or a string-coerced number — leave
@@ -412,7 +412,7 @@ module.exports = function buildTasksRouter() {
 
   // DELETE /tasks/:id/dependencies/:depId — removes the edge.
   // rank: metic+archon — removes a dep edge; task-shaping, Metic+ (ADR 0090).
-  router.delete('/tasks/:id/dependencies/:depId', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+  router.delete('/tasks/:id/dependencies/:depId', auth.requireBuilder, auth.requirePermission('task.dependency.manage'), async (req, res) => {
     const id = Number(req.params.id);
     const depId = Number(req.params.depId);
     if (!Number.isFinite(id) || !Number.isFinite(depId)) {
@@ -425,7 +425,7 @@ module.exports = function buildTasksRouter() {
   // PUT /tasks/:id/dependencies — replace the full dep set.
   //   body: { depends_on_task_ids: [N, ...] }
   // rank: metic+archon — replaces the full dep set; task-shaping, Metic+ (ADR 0090).
-  router.put('/tasks/:id/dependencies', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+  router.put('/tasks/:id/dependencies', auth.requireBuilder, auth.requirePermission('task.dependency.manage'), async (req, res) => {
     if (validateOrRespond(req, res, {
       depends_on_task_ids: { required: true, type: 'array', maxItems: 200 },
     })) return;
@@ -467,7 +467,7 @@ module.exports = function buildTasksRouter() {
   // POST /tasks/:id/criteria — body: { criterion_ids: [ref, ...] } OR
   //                                  { criterion_id: ref }. Metic+.
   // rank: metic+archon — links a task it can author to a criterion; mirrors POST deps (ADR 0090).
-  router.post('/tasks/:id/criteria', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+  router.post('/tasks/:id/criteria', auth.requireBuilder, auth.requirePermission('task.criterion.manage'), async (req, res) => {
     if (validateOrRespond(req, res, {
       criterion_ids: { type: 'array', maxItems: 100 },
       // criterion_id is the singular alt-form (a numeric id, "Cn" token, or slug)
@@ -509,7 +509,7 @@ module.exports = function buildTasksRouter() {
   // DELETE /tasks/:id/criteria/:criterionId — removes one link (criterionId is
   // the numeric done_when_criteria.id, mirroring DELETE deps/:depId).
   // rank: metic+archon — removes a criterion↔task edge; task-shaping, Metic+ (ADR 0090).
-  router.delete('/tasks/:id/criteria/:criterionId', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+  router.delete('/tasks/:id/criteria/:criterionId', auth.requireBuilder, auth.requirePermission('task.criterion.manage'), async (req, res) => {
     const id = Number(req.params.id);
     const criterionId = Number(req.params.criterionId);
     if (!Number.isFinite(id) || !Number.isFinite(criterionId)) {
@@ -525,7 +525,7 @@ module.exports = function buildTasksRouter() {
   // ADR 0018). A Xenos/Thetes still cannot author — they file ideas. Setting rank
   // and closing versions stay Archon. The every-route audit is task #231 (V3.R06).
   // rank: metic+archon — create work (plan/scope mutation); ADR 0090 (was ADR 0016/0018 archon).
-  router.post('/tasks', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+  router.post('/tasks', auth.requireBuilder, auth.requirePermission('task.create'), async (req, res) => {
     if (validateOrRespond(req, res, {
       version_id: { required: true, type: 'string', maxLength: 64 },
       title: { required: true, type: 'string', maxLength: LIMITS.TITLE, minLength: 1 },
@@ -747,7 +747,7 @@ module.exports = function buildTasksRouter() {
   // accepts true|false|null; newcomer_friendly is a boolean. Validation lives
   // in hierarchy.js for parent; the rest are validated inline.
   // rank: metic+archon — edit work (incl. newcomer_friendly flag); ADR 0090 (was ADR 0016 archon).
-  router.patch('/tasks/:id', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+  router.patch('/tasks/:id', auth.requireBuilder, auth.requirePermission('task.edit'), async (req, res) => {
     if (validateOrRespond(req, res, {
       kind: { type: 'string', maxLength: 64 },
       discipline: { type: 'string', maxLength: 64 },
@@ -977,7 +977,7 @@ module.exports = function buildTasksRouter() {
   // PATCH refuses `status` outright). A restore lands in **backlog**, never straight
   // to ready: the task was retired for a reason, so it re-enters as un-workable and
   // takes a second, deliberate promote to become claimable again.
-  router.post('/tasks/:id/promote', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+  router.post('/tasks/:id/promote', auth.requireBuilder, auth.requirePermission('task.promote'), async (req, res) => {
     const id = Number(req.params.id);
     const task = await db.getTask(id);
     if (!task) return res.fail('task_not_found', 404);
@@ -1020,7 +1020,7 @@ module.exports = function buildTasksRouter() {
   // task out from under its claim holder. No reward side-effects (the reward gate
   // is a promote-only concern; backlog is the pre-workable state).
   // rank: metic+archon — ready→backlog demotion; scope mutation; mirrors /promote (ADR 0090).
-  router.post('/tasks/:id/demote', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+  router.post('/tasks/:id/demote', auth.requireBuilder, auth.requirePermission('task.demote'), async (req, res) => {
     const id = Number(req.params.id);
     const task = await db.getTask(id);
     if (!task) return res.fail('task_not_found', 404);
@@ -1091,7 +1091,7 @@ module.exports = function buildTasksRouter() {
   // GRADER_BYPASS_ENABLED==='1'; archon-only otherwise).
   const confirmRankGate = (req, res, next) => {
     if (graderBypassEnabled()) return next();
-    return auth.requireRank('archon')(req, res, next);
+    return auth.requirePermission('task.confirm.grade_bypass')(req, res, next);
   };
   router.post('/tasks/:id/confirm', auth.requireBuilder, confirmRankGate, async (req, res) => {
     if (validateOrRespond(req, res, {
@@ -1148,7 +1148,7 @@ module.exports = function buildTasksRouter() {
   // triage they already delegated. Not one-way any more — /promote restores an
   // abandoned task to backlog at the same rank — and the guards below (shipped
   // refused, active claim refused) plus the audit_log entry are unchanged.
-  router.post('/tasks/:id/abandon', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+  router.post('/tasks/:id/abandon', auth.requireBuilder, auth.requirePermission('task.abandon'), async (req, res) => {
     if (validateOrRespond(req, res, {
       reason: { type: 'string' },  // free-text retire reason (sliced to 2000 below)
     })) return;
@@ -1228,7 +1228,7 @@ module.exports = function buildTasksRouter() {
   // reaches it via the doorway api.tallyPeerVotes — BV1.R83) share one code path
   // and can never diverge. This route keeps the Archon gate (the HTTP surface
   // stays Archon-only); the in-process timer has no requester to authorize.
-  router.post('/tasks/peer-votes/tally', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+  router.post('/tasks/peer-votes/tally', auth.requireBuilder, auth.requirePermission('task.peer_votes.tally'), async (req, res) => {
     try {
       const result = await db.tallyPeerVotes();
       res.json(result);
@@ -1244,7 +1244,7 @@ module.exports = function buildTasksRouter() {
   //   - 409 if the task isn't votable, or the vote was already folded into karma
   //   - vote: 0 clears (deletes the row, only while still untallied)
   // rank: metic+archon — a trusted-builder reputation action.
-  router.post('/tasks/:id/vote', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+  router.post('/tasks/:id/vote', auth.requireBuilder, auth.requirePermission('task.vote'), async (req, res) => {
     if (validateOrRespond(req, res, {
       vote: { required: true, type: 'integer', enum: [-1, 0, 1] },
     })) return;
@@ -1685,7 +1685,7 @@ module.exports = function buildTasksRouter() {
   // GET /override-requests?status=open — Archon queue. Status defaults to open;
   // pass ?status=approved or ?status=denied for the resolved history.
   // rank: archon — same gate as the audit log + Archon view.
-  router.get('/override-requests', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+  router.get('/override-requests', auth.requireBuilder, auth.requirePermission('override_request.decide'), async (req, res) => {
     const status = req.query.status || 'open';
     if (!['open', 'approved', 'denied'].includes(status)) {
       return res.fail('bad_status', 400);
@@ -1705,7 +1705,7 @@ module.exports = function buildTasksRouter() {
   // updates; the task stays at completed and the builder must release or
   // re-ship after fixing whatever the grader caught.
   // rank: archon — grader-bypass authority; same gate as POST /tasks/:id/confirm.
-  router.post('/override-requests/:id/decide', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+  router.post('/override-requests/:id/decide', auth.requireBuilder, auth.requirePermission('override_request.decide'), async (req, res) => {
     const id = parseId(req, res, { code: 'bad_request_id' });
     if (id === null) return;
     if (validateOrRespond(req, res, {