@bongos/core 1.19.331 → 1.19.333

package/modules/lifecycle/routes/goals.js

@@ -61,373 +61,7 @@ const JOIN_REQUEST_RESPONSE_ACTIONS = ['approve', 'deny']; // an owner/manager/A
 // proceed; a false result means "not a member" → the route should 403. This is the
 // membership half of the wall; the protected-module rank check is enforced per-route
 // (scope is never self-granted).
-async function isMemberOrArchon(builder, goalId) {
-  if (builder.rank === 'archon') return true;
-  return db.isGoalMember({ goalId, builderId: builder.id });
-}
-
-// authorizeGoalTaskCreate — the ORDERED, FAIL-CLOSED authorization decision for
-// POST /goals/:id/tasks (BV1.R60 / ADR 0086 §3): the single point that lets a
-// lower-rank builder author their OWN work safely. PURE + exported (the
-// shouldRefuseSessionClaim precedent in claims.js) so every rejection is pinned
-// by a DB-free unit test AND reused by the BV1.R61 abuse matrix — no live route
-// or DB needed.
-//
-// The route fetches goal / version / membership, then calls this; it rejects on
-// the FIRST failure (fail-closed — a missing/ambiguous input denies):
-//   goal_not_found → goal_not_open → not_a_member → version_not_found →
-//   version_closed → (scope-subset + protected-path, via goalScopeCheck.check).
-// The scope+protected wall is goal-scope-check.check() VERBATIM (R59) — itself
-// ordered + fail-closed (empty-scope → empty-touches → unknown-scope →
-// scope-subset → protected-path) — never re-implemented here. `isMember` is the
-// resolved "member OR Archon" boolean the route computes (isMemberOrArchon).
-//
-// This is the CREATE-time filter: it sees only DECLARED touches[] (advisory — git
-// merge is the real collision detector, ADR 0049), so it is deliberately the FIRST
-// filter, NOT the last. The ship-time gates stay authoritative on the REAL diff
-// (grader permission/route-rank pre-passes + serverSideGuards, gate-review
-// ESCALATE floor, post-push main-audit — ADR 0086 §7). Returns { ok:true } or
-// { ok:false, status, body } (the exact HTTP status + JSON the route sends).
-function authorizeGoalTaskCreate({ goal, version, isMember, builderRank, touches }) {
-  if (!goal) {
-    return { ok: false, status: 404, body: { error: 'goal_not_found' } };
-  }
-  if (goal.status !== 'open') {
-    return { ok: false, status: 409, body: {
-      error: 'goal_not_open', status: goal.status,
-      message: 'Tasks can only be authored under an open goal.',
-    } };
-  }
-  if (!isMember) {
-    return { ok: false, status: 403, body: {
-      error: 'not_a_member',
-      message: 'Join the goal (or be an Archon) to author tasks within it.',
-    } };
-  }
-  if (!version) {
-    return { ok: false, status: 404, body: {
-      error: 'version_not_found',
-      message: `The goal's version '${goal.version_id}' no longer exists.`,
-    } };
-  }
-  if (version.status === 'shipped') {
-    return { ok: false, status: 409, body: {
-      error: 'version_closed',
-      message: `Version '${goal.version_id}' has shipped — it is closed history and cannot take new tasks.`,
-    } };
-  }
-  // The wall — scope-subset + protected-path in one pure call (R59). It bounds
-  // EVERYONE by the goal's modules (scope-subset), and additionally blocks a
-  // sub-Metic member from authoring into the protected core (protected-path),
-  // reusing the SINGLE protected roster (permission-path-check) — no drift.
-  const gate = goalScopeCheck.check(goal.scope_modules, touches, builderRank);
-  if (!gate.ok) {
-    return { ok: false, status: 403, body: {
-      error: gate.code, reason: gate.reason, details: gate.details,
-    } };
-  }
-  return { ok: true };
-}
-
-// The goal AUTHORITY MODEL (owner vs manager) now lives in ../goal-authz.js —
-// isGoalOwner + authorizeGoalManagement are imported at the top of this file and
-// re-exported at the bottom (task 1002538 / ADR 0154).
-
-// authorizeMembershipKindChange — the ORDERED, FAIL-CLOSED authorization decision
-// for PATCH /goals/:id/members/:builderId (task 1735). Today the only assignment
-// path is the Archon admission route; this gate lets the goal's own authority
-// manage memberships without an Archon in the loop:
-//
-// THE FIELD IS `membership_kind` (task 1003013, ADR 0177): ADR 0174 reserves the
-// old word for the three crafts — Artist, Ideator, Builder — and a goal membership
-// is a per-goal position, neither a craft nor a rank.
-
-//   - the owner, a manager, or an Archon may promote member→lead(manager);
-//   - ONLY the owner (or an Archon) may demote lead(manager)→member;
-//   - the OWNER's row can never be demoted — owner authority is created_by, not
-//     the membership value, so a demoted owner row would just lie to the list.
-// PURE + exported (the authorizeGoalTaskCreate precedent above) so every
-// rejection is pinned by a DB-free unit test. The route fetches goal /
-// memberships, then calls this; it rejects on the FIRST failure (fail-closed —
-// a missing/ambiguous input denies):
-//   goal_not_found → goal_not_open → not_owner_or_manager → not_a_member
-//   (target) → no-op same-kind → owner_only_demotion → owner_membership_fixed.
-// Authority (not_owner_or_manager) is checked BEFORE the target lookup so an
-// unauthorized actor never learns who is or isn't a member (the O1 no-leak
-// ordering precedent in the abuse matrix). The DB helper (setGoalMembershipKind)
-// re-asserts the owner-demotion guard atomically in the UPDATE itself — this
-// gate is the testable contract, the SQL guard is the backstop.
-// Returns { ok:true }, { ok:true, noop:true } (already as requested), or
-// { ok:false, status, body } (the exact HTTP status + JSON the route sends).
-function authorizeMembershipKindChange({ goal, actorId, actorRank, actorMembership, targetMembership, targetId, membershipKind }) {
-  if (!goal) {
-    return { ok: false, status: 404, body: { error: 'goal_not_found' } };
-  }
-  if (goal.status !== 'open') {
-    return { ok: false, status: 409, body: {
-      error: 'goal_not_open', status: goal.status,
-      message: 'Memberships can only be changed on an open goal.',
-    } };
-  }
-  const actorIsOwner = isGoalOwner(goal, actorId);
-  const actorIsManager = !!actorMembership && actorMembership.membership_kind === 'lead';
-  if (actorRank !== 'archon' && !actorIsOwner && !actorIsManager) {
-    return { ok: false, status: 403, body: {
-      error: 'not_owner_or_manager',
-      message: 'Only this goal\'s owner or a manager (or an Archon) may change memberships.',
-    } };
-  }
-  if (!targetMembership) {
-    return { ok: false, status: 404, body: {
-      error: 'not_a_member',
-      message: 'That builder is not a member of this goal — admit them first.',
-    } };
-  }
-  if (targetMembership.membership_kind === membershipKind) {
-    return { ok: true, noop: true };
-  }
-  if (membershipKind === 'member') {
-    // A demotion. Managers promote; only the owner (or an Archon) demotes.
-    if (actorRank !== 'archon' && !actorIsOwner) {
-      return { ok: false, status: 403, body: {
-        error: 'owner_only_demotion',
-        message: 'Only the goal owner (or an Archon) may demote a manager.',
-      } };
-    }
-    if (isGoalOwner(goal, targetId)) {
-      return { ok: false, status: 409, body: {
-        error: 'owner_membership_fixed',
-        message: 'The goal owner cannot be demoted — transfer ownership first.',
-      } };
-    }
-  }
-  return { ok: true };
-}
-
-// authorizeOwnershipTransfer — the ORDERED, FAIL-CLOSED decision for
-// POST /goals/:id/transfer (task 1735): the owner hands the goal to another
-// builder (the old owner keeps their manager row). Ownership is creator-
-// equivalent authority and goal CREATION is Metic+ — so the transfer target
-// must be Metic+ too (fail-closed; this also keeps the protected-scope
-// membership wall intact, since a protected-scope goal requires Metic+ members).
-// Ordering: goal_not_found → goal_not_open → not_owner → builder_not_found →
-// metic_required_for_ownership → no-op self-transfer.
-function authorizeOwnershipTransfer({ goal, actorId, actorRank, targetBuilder }) {
-  if (!goal) {
-    return { ok: false, status: 404, body: { error: 'goal_not_found' } };
-  }
-  if (goal.status !== 'open') {
-    return { ok: false, status: 409, body: {
-      error: 'goal_not_open', status: goal.status,
-      message: 'Ownership can only be transferred on an open goal.',
-    } };
-  }
-  if (actorRank !== 'archon' && !isGoalOwner(goal, actorId)) {
-    return { ok: false, status: 403, body: {
-      error: 'not_owner',
-      message: 'Only the goal owner (or an Archon) may transfer ownership.',
-    } };
-  }
-  if (!targetBuilder) {
-    return { ok: false, status: 404, body: { error: 'builder_not_found' } };
-  }
-  if (!METIC_PLUS.includes(targetBuilder.rank)) {
-    return { ok: false, status: 403, body: {
-      error: 'metic_required_for_ownership',
-      message: 'Goal ownership is creator-equivalent authority — the new owner must be Metic+.',
-    } };
-  }
-  if (isGoalOwner(goal, targetBuilder.id)) {
-    return { ok: true, noop: true };
-  }
-  return { ok: true };
-}
-
-// -------------------------------------------------------------------------
-// Private goals: the invite / join-request queue (task 1952 / ADR 0112). A
-// private goal is join-GATED (not hidden): a non-member can't self-join — they
-// are INVITED (a consented, pending row they accept) or REQUEST to join (an
-// owner/manager/Archon approves). Both directions live in goal_membership_requests
-// (kind='invite'|'request'); the resolve is atomic (db.resolveMembershipRequest
-// moves only from status='pending', so a re-submit can't double-add a member).
-// -------------------------------------------------------------------------
-
-// protectedScopeAdmissionBlock — the SINGLE protected-scope admission rule reused
-// by BOTH new admission paths (invite-create and join-request-approve) AND the
-// existing POST /goals/:id/members (whose inline checks this generalizes). A
-// protected-scope goal admits members only via an Archon, and only Metic+ builders
-// — sub-Metic membership inside protected scope is deferred to ADR 0086's Phase-5
-// ADR. Centralized so the protected wall can never drift between paths (the SEC
-// #863 single-roster lesson). Returns { status, body } to send, or null to proceed.
-function protectedScopeAdmissionBlock({ scopeProtected, actorRank, targetRank }) {
-  if (!scopeProtected) return null;
-  if (actorRank !== 'archon') {
-    return { status: 403, body: {
-      error: 'archon_required_for_protected_scope',
-      message: 'This goal is scoped to a protected module; only an Archon may admit members.',
-    } };
-  }
-  if (!METIC_PLUS.includes(targetRank)) {
-    return { status: 403, body: {
-      error: 'metic_required_for_protected_scope',
-      message: 'A protected-scope goal requires a Metic+ member; sub-Metic membership is deferred to the Phase-5 ADR.',
-    } };
-  }
-  return null;
-}
-
-// authorizeCreateJoinRequest — the ORDERED, FAIL-CLOSED gate for
-// POST /goals/:id/requests (task 1952): a builder asks to join. A request only
-// makes sense where self-join is gated — a PUBLIC, NON-protected goal is open-join,
-// so a request there is refused with a "just join" hint. Ordering:
-// goal_not_found → goal_not_open → already_a_member → goal_is_open (public+unprotected).
-// isMember is the caller's own membership; scopeProtected is scopeIncludesProtected(goal).
-// PURE + exported (the authorizeGoalTaskCreate precedent).
-function authorizeCreateJoinRequest({ goal, isMember, scopeProtected }) {
-  if (!goal) return { ok: false, status: 404, body: { error: 'goal_not_found' } };
-  if (goal.status !== 'open') {
-    return { ok: false, status: 409, body: {
-      error: 'goal_not_open', status: goal.status,
-      message: 'You can only request to join an open goal.',
-    } };
-  }
-  if (isMember) {
-    return { ok: false, status: 409, body: {
-      error: 'already_a_member', message: 'You are already a member of this goal.',
-    } };
-  }
-  if (goal.visibility !== 'private' && !scopeProtected) {
-    return { ok: false, status: 409, body: {
-      error: 'goal_is_open',
-      message: 'This goal is open — just join it (POST /goals/:id/join); no request needed.',
-    } };
-  }
-  return { ok: true };
-}
-
-// authorizeInvitationResponse — the ORDERED, FAIL-CLOSED gate for
-// POST /goals/:id/invitations/:reqId/respond (task 1952): ONLY the invited builder
-// may accept/decline their OWN pending invite. Containment first — the row must
-// belong to THIS goal and be an 'invite' — so the invitation route can never touch
-// a join-request row. Ordering: request_not_found → wrong_goal → not_an_invitation
-// → not_pending → not_your_invitation. PURE + exported.
-function authorizeInvitationResponse({ request, goalId, actorId }) {
-  if (!request) return { ok: false, status: 404, body: { error: 'request_not_found' } };
-  if (String(request.goal_id) !== String(goalId)) {
-    return { ok: false, status: 404, body: { error: 'request_not_found', message: 'No such invitation on this goal.' } };
-  }
-  if (request.kind !== 'invite') {
-    return { ok: false, status: 400, body: { error: 'not_an_invitation', message: 'That row is a join-request, not an invitation.' } };
-  }
-  if (request.status !== 'pending') {
-    return { ok: false, status: 409, body: { error: 'not_pending', status: request.status } };
-  }
-  if (String(request.builder_id) !== String(actorId)) {
-    return { ok: false, status: 403, body: {
-      error: 'not_your_invitation',
-      message: 'Only the invited builder may accept or decline this invitation.',
-    } };
-  }
-  return { ok: true };
-}
-
-// authorizeInvitationAccept — the ORDERED, FAIL-CLOSED gate for the ACCEPT half of
-// POST /goals/:id/invitations/:reqId/respond, run against the GOAL after
-// authorizeInvitationResponse has cleared the request row (task 1002887).
-//
-// Accepting is an ADMISSION, so it needs the same goal-state floor every other
-// admission path already has: the create side requires an open goal
-// (authorizeGoalManagement) and the join-request approve side inherits that check
-// verbatim — only invitation-accept was missing it, so an invite issued while a
-// goal was open could still add a member AFTER the goal was achieved or archived.
-// DECLINE is deliberately NOT gated here: clearing a stale invitation out of your
-// inbox is cleanup, not admission (the route returns before calling this).
-// Ordering mirrors the sibling routes: goal_not_found → goal_not_open →
-// metic_required_for_protected_scope (the pre-existing protected-scope membership
-// floor, re-asserted against the ACCEPTING builder's current rank because the goal
-// may have been re-scoped since the invite; the actor-is-Archon half of
-// protectedScopeAdmissionBlock does not apply — the invitee is consenting).
-//
-// Unlike its {status, body} siblings this returns a res.fail SPEC ({ code, status,
-// message, details }) because the accept branch already answers through res.fail —
-// routing it through the envelope keeps the existing metic_required_for_protected_scope
-// response byte-identical while still being PURE + exported for DB-free tests.
-function authorizeInvitationAccept({ goal, scopeProtected, actorRank }) {
-  if (!goal) {
-    return { ok: false, code: 'goal_not_found', status: 404,
-      message: 'The goal behind this invitation no longer exists.' };
-  }
-  if (goal.status !== 'open') {
-    return { ok: false, code: 'goal_not_open', status: 409,
-      message: 'This goal is no longer open — an invitation can only be accepted while it is. You can still decline it.',
-      details: { status: goal.status } };
-  }
-  if (scopeProtected && !METIC_PLUS.includes(actorRank)) {
-    return { ok: false, code: 'metic_required_for_protected_scope', status: 403,
-      message: 'This goal is scoped to a protected module and requires a Metic+ member.' };
-  }
-  return { ok: true };
-}
-
-// authorizeJoinRequestResponse — the gate for POST /goals/:id/requests/:reqId/respond
-// (task 1952): an owner|manager|Archon approves/denies a pending join-request. The
-// authority prefix is authorizeGoalManagement VERBATIM (goal exists/open + owner|
-// manager|Archon — checked BEFORE the request lookup so an unauthorized actor never
-// learns whether a request exists, the O1 no-leak ordering). Then request
-// containment + state: request_not_found → wrong_goal → not_a_join_request →
-// not_pending. PURE + exported.
-function authorizeJoinRequestResponse({ goal, actorId, actorRank, actorMembership, request, goalId }) {
-  const mgmt = authorizeGoalManagement({ goal, actorId, actorRank, actorMembership });
-  if (!mgmt.ok) return mgmt;
-  if (!request) return { ok: false, status: 404, body: { error: 'request_not_found' } };
-  if (String(request.goal_id) !== String(goalId)) {
-    return { ok: false, status: 404, body: { error: 'request_not_found', message: 'No such join-request on this goal.' } };
-  }
-  if (request.kind !== 'request') {
-    return { ok: false, status: 400, body: { error: 'not_a_join_request', message: 'That row is an invitation, not a join-request.' } };
-  }
-  if (request.status !== 'pending') {
-    return { ok: false, status: 409, body: { error: 'not_pending', status: request.status } };
-  }
-  return { ok: true };
-}
-
-// authorizeWithdrawJoinRequest — the gate for POST /goals/:id/requests/:reqId/withdraw
-// (task 1953): ONLY the requester may withdraw their OWN pending join-request — a
-// symmetric mirror of authorizeInvitationResponse (the invitee resolves their own
-// invite; here the requester resolves their own request, self-served instead of
-// waiting on an owner/manager deny). Ordering: request_not_found → wrong_goal →
-// not_a_join_request → not_pending → not_your_request. PURE + exported.
-function authorizeWithdrawJoinRequest({ request, goalId, actorId }) {
-  if (!request) return { ok: false, status: 404, body: { error: 'request_not_found' } };
-  if (String(request.goal_id) !== String(goalId)) {
-    return { ok: false, status: 404, body: { error: 'request_not_found', message: 'No such request on this goal.' } };
-  }
-  if (request.kind !== 'request') {
-    return { ok: false, status: 400, body: { error: 'not_a_join_request', message: 'That row is an invitation, not a join-request.' } };
-  }
-  if (request.status !== 'pending') {
-    return { ok: false, status: 409, body: { error: 'not_pending', status: request.status } };
-  }
-  if (String(request.builder_id) !== String(actorId)) {
-    return { ok: false, status: 403, body: {
-      error: 'not_your_request',
-      message: 'Only the requester may withdraw their own join-request.',
-    } };
-  }
-  return { ok: true };
-}
-
-// decorateGoalScope — additive, derived scope_protected flag on goal payloads
-// (task 1002689). A protected-scope goal is join-gated like a private one
-// (Archon-mediated membership, ADR 0086 §3), but the hall cannot re-derive the
-// protected roster client-side (module-scope-map is server-only) — so the
-// list/detail reads carry the boolean and the UI renders the request-to-join
-// path instead of a dead-end Join button. Never persisted; a pure map.
-function decorateGoalScope(goal) {
-  return goal ? { ...goal, scope_protected: scopeIncludesProtected(goal.scope_modules) } : goal;
-}
-
+const { authorizeCreateJoinRequest, authorizeGoalTaskCreate, authorizeInvitationAccept, authorizeInvitationResponse, authorizeJoinRequestResponse, authorizeMembershipKindChange, authorizeOwnershipTransfer, authorizeWithdrawJoinRequest, decorateGoalScope, isMemberOrArchon, protectedScopeAdmissionBlock } = require('./goal-route-authz.js');
 module.exports = function buildGoalsRouter() {
   const router = express.Router();
 

package/modules/lifecycle/routes/task-route-helpers.js

@@ -0,0 +1,219 @@
+// modules/lifecycle/routes/task-route-helpers.js — the small predicates and
+// gates the task routes share: #NNN de-hashing, migration detection, the grader
+// bypass switch, task ownership, verify-task detection, gate-trust attestation
+// and the peer-vote net.
+//
+// Carved out of modules/lifecycle/routes/tasks.js by task 1003206 (goal 1000079,
+// the R03 de-monolith plan). Pulled out FIRST so the route groups that follow can
+// share them without either side requiring the other — the split has to stay a
+// DAG. A STRUCTURAL move: bodies unchanged, and tasks.js re-exports the ones its
+// tests import.
+
+'use strict';
+
+const path = require('node:path');
+const api = require('../../../src/module-api');
+const db = require('../db');
+const githubPush = require('../github-push');
+const { classifyTaskKind, VALID_KINDS, VALID_DISCIPLINES, VOTABLE_TASK_STATUSES, TASK_FIELD_BOUNDS } = require('../task-classifier');
+const { pool } = api;
+
+function deHashRefs(text) {
+  return String(text == null ? '' : text).replace(/#(\d{1,5})\b/g, 'task $1');
+}
+
+// tasks.discipline — orthogonal to kind. See migrations 014 + 086.
+// VALID_DISCIPLINES (engineer = builds code · artist = makes visual assets ·
+// ideator = thinks/writes/scopes · unclassified = un-triaged) is imported above
+// from ../task-classifier — the single source (D1).
+
+// ?fit= on /tasks/claimable — narrows to tasks the autonomous overnight
+// session-runner (#358) may pick up. See db.listClaimableTasks.
+const VALID_FITS = new Set(['autonomous', 'parallel']);
+
+// V3.R48 (#267): auto-detect schema-change tasks so the touches[] scanner
+// reserves a migration number even when the builder forgets to list
+// 'migrations/'. The keyword set is intentionally conservative — it matches
+// whole tokens ("migration"/"migrations", "schema") and the two SQL phrases
+// that almost always imply a migration, so unrelated words ("schematic",
+// "reschema", a button color) don't false-positive. Case-insensitive.
+//
+// Migration-keyword detection. POST /tasks uses this to set the
+// tasks.needs_migration boolean (migration 081, touches[] cleanup [1/8] /
+// task 876), which is what the claim-time allocator now keys off — replacing
+// the old "inject 'migrations/' into touches[]" sentinel. Conservative,
+// whole-token, case-insensitive. The former scripts/gds/capture.js mirror was
+// deleted with the same task: captured ideas have no touches[] and the server
+// re-detects on create, so the CLI copy earned its keep no longer.
+const MIGRATION_KEYWORD_RE =
+  /\bmigrations?\b|\bschema\b|\balter\s+table\b|\bcreate\s+table\b/i;
+
+// task 1002648 (idea 1000642): compounds where the keyword is qualified by a
+// NON-database noun are refactor/API language, not schema work, and are blanked
+// before the keyword test. Two families surfaced in the wild: "gate/route/code
+// migration" (code-migration phrasing) and "request/PATCH/:NNN schema"
+// (API-shape phrasing — the task-1002614 false positive, which reserved
+// migration 213 for zero schema change). Bare "migration"/"schema" and every
+// DB-shaped compound ("schema migration", "DB schema") still flag.
+const NON_DB_COMPOUND_RE = new RegExp(
+  [
+    /\b(?:gate|route|code)s?[-\s]+migrations?\b/.source,
+    /\bmigrations?\s+of\s+(?:gate|route|code)s?\b/.source,
+    /\b(?:request|response|body|validation|patch|post|put|delete|json|openapi|api|error)[-\s]+schemas?\b/.source,
+    /:\d+[-\s]+schemas?\b/.source,
+  ].join('|'),
+  'gi'
+);
+
+function detectsMigration(...texts) {
+  return texts.some(
+    (t) => typeof t === 'string' && MIGRATION_KEYWORD_RE.test(t.replace(NON_DB_COMPOUND_RE, ' '))
+  );
+}
+
+// ---- peer votes (V3.R25 #245) ---------------------------------------------
+// The peer-vote SQL lives here (inline, via the route module's `pool`) rather
+// than in db.js on purpose: it's a self-contained feature, declared in this
+// task's touches[] (migrations/, this file, modules/hall-ui/), and keeping it
+// out of the large shared db.js avoids a parallel-safety conflict on that file.
+// Same deliberate-locality call as the MIGRATION_KEYWORD_RE mirror above.
+
+// VOTABLE_TASK_STATUSES — a task is votable once it's verified work the project
+// keeps (confirmed = past the grader, not yet paid; or shipped = deployed + paid);
+// backlog/ready/completed are not. Imported above from ../task-classifier (D1).
+
+// #853 (ADR 0041): temporary, default-OFF global grader bypass. When the env
+// GRADER_BYPASS_ENABLED is exactly '1', the subagent quality grader is treated
+// as unavailable and any builder may land work via /tasks/:id/confirm (normally
+// archon-only). Read live on each request — flipping the env (+ redeploy) is the
+// on/off switch; no caching, so turning it off re-arms the trust boundary at
+// once. Exported so /me can surface the same flag to ship.js.
+function graderBypassEnabled() {
+  return process.env.GRADER_BYPASS_ENABLED === '1';
+}
+
+// SECURITY (#871): claim-ownership gate for the lifecycle-advancing routes
+// (/grade, /confirm, /ship). These are requireBuilder-only (the grade is meant
+// to be an objective subagent output; the supervisor hot path must not need an
+// Archon), which — combined with applyGrade/confirmTask crediting work — let any
+// authenticated builder act on ANOTHER builder's task:
+//   * /grade  (requireBuilder, no rank gate): a builder could POST a fabricated
+//     passing grade on someone else's `completed` task. Pre-#871 applyGrade then
+//     credited the CALLER → cross-builder credit theft + ship-attribution hijack
+//     + a full bypass of the quality grader.
+//   * /confirm: archon-only normally, but the GRADER_BYPASS killswitch (ON
+//     during the grader outage) relaxes it to ANY builder, so anyone could
+//     force-confirm anyone's `completed` work past the (absent) grader.
+//   * /ship: any-builder supervisor hot path (so /merge-mode can land the queue).
+//
+// Allow when: the caller is an Archon (full authority / --regrade); OR — for
+// /ship only (allowSupervisor) — the caller is Metic, the trusted rank that runs
+// /merge-mode to sweep the confirmed queue across builders; OR the caller is the
+// task's most-recent claim holder (the builder who did the work).
+//
+// A NEVER-CLAIMED task (degenerate state, e.g. status set directly via SQL) is
+// NOT an open door: the Archon and supervisor early-returns above already cover
+// the legitimate actors who land such a task. By the time we read the claim
+// holder, the caller is necessarily a non-Archon (and not a supervisor Metic) —
+// so a missing claim must FAIL CLOSED with the same 403, not silently ALLOW.
+// (L2 residual, red-team 2026-06-12: combined with the GRADER_BYPASS relaxation
+// on /confirm, the old "no claim → ALLOW" let any builder confirm a claimless
+// `completed` task and have the credit fall to themselves.) An Archon (or the
+// /merge-mode supervisor) can still land a claimless task — they pass above.
+// Returns true if allowed; otherwise writes a 403 and returns false.
+async function gateTaskOwnership(req, res, taskId, { allowSupervisor = false } = {}) {
+  const rank = req.builder && req.builder.rank;
+  if (rank === 'archon') return true;
+  if (allowSupervisor && rank === 'metic') return true;
+  const holder = await db.getLastClaimHolder(taskId);
+  if (holder && String(holder.builder_id) === String(req.builder.id)) return true;
+  // task 1002614 (map N-2): a mistyped id used to earn the same not_your_task
+  // 403 as someone else's work — a misattribution that sent builders debugging
+  // ownership. An ABSENT task is the clean 404 an Archon already saw (they pass
+  // above and hit the handler's own lookup). A never-claimed task that EXISTS
+  // still fails closed with the 403 below (the L2 credit-theft block).
+  if (!holder && !(await db.getTask(taskId))) {
+    res.fail('task_not_found', 404);
+    return false;
+  }
+  res.fail('not_your_task', { status: 403, message: 'Only the task\'s claim holder (or an Archon) may grade/confirm/ship it.' });
+  return false;
+}
+
+// task 1053 (F): a verification task — one whose deliverable IS a verification
+// (e.g. a hardware-verify run). Confirming one requires an explicit attestation
+// that the verify actually passed, so a hardware-verify can't be confirmed on a
+// passing code-grade before the verify was even performed (the #1027 trap).
+// Keyed on the explicit kind (set by the planner), NOT a title regex — a task
+// ABOUT verify work would false-positive on text. Pure + exported for tests.
+function isVerifyTask(task) {
+  return !!task && task.kind === 'verify';
+}
+
+// task 1139 / 1169 (ADR 0058): the trustless server rank-attestation behind the
+// gate-review CI check. Only the SERVER can set it — it holds the authenticated
+// builder's server-resolved rank AND the App/PAT credential — so CI can trust it
+// where a PR-author-controlled signal (a PR title) would be spoofable. A Metic+
+// author's gate-author-trust=success clears a NEEDS_TRUST gate surface with no
+// owner click; below Metic gets no attestation (the gate escalates → owner review).
+//
+// rankAttestsGateTrust is the PURE rank decision (no network) — exported for tests.
+function rankAttestsGateTrust(rank) {
+  const { tierOf, MIN_TIER } = api.permissionPathCheck;
+  const tier = tierOf(rank);
+  return tier != null && tier >= MIN_TIER;
+}
+
+// postGateAuthorTrust — set (or skip) the gate-author-trust commit status for an
+// author's rank on a pushed SHA. Shared by the server-mediated publish path
+// (POST /tasks/:id/publish-branch) and the laptop ci-land path's attest endpoint
+// (POST /tasks/:id/attest-gate). Best-effort + never throws: a failed/skipped
+// status post leaves the PR un-attested, which ESCALATES (the safe direction — no
+// rank bypass without a real server signal). Returns { attested, reason } for UX.
+async function postGateAuthorTrust({ rank, sha, taskId }) {
+  if (!rankAttestsGateTrust(rank)) return { attested: false, reason: 'rank_below_metic' };
+  try {
+    const ok = await githubPush.setCommitStatus({
+      sha,
+      state: 'success',
+      context: 'gate-author-trust',
+      description: `Metic+ author (${rank}) — task ${taskId}`,
+    });
+    return { attested: !!ok, reason: ok ? null : 'status_post_failed' };
+  } catch (_) {
+    return { attested: false, reason: 'status_post_failed' };
+  }
+}
+
+async function peerVoteNet(taskId) {
+  const { rows } = await pool.query(
+    `SELECT COALESCE(SUM(vote), 0)::int AS net, COUNT(*)::int AS total
+       FROM peer_votes WHERE target_task_id = $1`,
+    [taskId]
+  );
+  return { net: rows[0].net, total: rows[0].total };
+}
+
+// #514: bad_kind responses carried a `valid` array but no human-readable line,
+// so a caller (or CLI that only prints .message) couldn't tell at a glance what
+// went wrong — the #506 session burned a turn guessing kind=chore. Add a
+// .message that spells out the allowed values while keeping the valid[] array.
+function badKind(res) {
+  const valid = Array.from(VALID_KINDS);
+  return res.fail('bad_kind', { status: 400, message: `kind must be one of: ${valid.join(', ')}`, details: { valid } });
+}
+
+
+module.exports = {
+  MIGRATION_KEYWORD_RE,
+  VALID_FITS,
+  badKind,
+  deHashRefs,
+  detectsMigration,
+  gateTaskOwnership,
+  graderBypassEnabled,
+  isVerifyTask,
+  peerVoteNet,
+  postGateAuthorTrust,
+  rankAttestsGateTrust,
+};