@bongos/core 1.17.0

package/modules/lifecycle/routes/tasks.js

@@ -0,0 +1,1703 @@
+const express = require('express');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+// Intra-module + the published doorway — a module never requires a core internal.
+const api = require('../../../src/module-api');
+const auth = api;
+const db = require('../db');
+const hierarchy = require('../hierarchy');
+// grading carved to modules/grading/ (BV1.R73 / ADR 0091 §4): the lifecycle no
+// longer imports the grader — it resolves the `grade` kernel PORT at grade time
+// (seams.resolveOptional('grade'), in POST /tasks/:id/grade below).
+const githubPush = require('../github-push');
+const seams = api;
+const { classifyTaskKind, VALID_KINDS, VALID_DISCIPLINES, VOTABLE_TASK_STATUSES, TASK_FIELD_BOUNDS } = require('../task-classifier');
+const { isModuleKey, moduleKeys } = api.moduleScopeMap;
+const { validateOrRespond, LIMITS, parseId } = api;
+// The onboarding state machine + the evergreen newcomer-chore restock carved into
+// modules/onboarding/ (BV1.R81 / ADR 0093 §1): GET /tasks/claimable marks
+// first_start and POST /tasks/newcomer-restock tops up the chore shelf — both
+// through the `onboarding` kernel port (seams.resolveOptional('onboarding')),
+// never a direct require of a module file.
+const { pool } = api;
+const { branding } = api;
+
+// ---- server-mediated branch publish (ADR 0055 / task 1025) -----------------
+// Body caps for POST /tasks/:id/publish-branch. The branch arrives as a base64
+// git bundle; base64 inflates ~33%, so the encoded string + JSON body limit sit
+// above the 20 MB decoded ceiling. The decoded bytes are re-checked in the
+// handler (the JSON `limit` only bounds the ENCODED payload — SR-17 posture).
+const PUBLISH_BODY_LIMIT = '32mb';
+const PUBLISH_BUNDLE_B64_MAX = 30 * 1024 * 1024;   // validator guard on the b64 string
+const PUBLISH_BUNDLE_MAX_BYTES = 20 * 1024 * 1024; // 20 MB decoded bundle
+
+// De-`#` text bound for a GitHub-rendered surface (PR title/body): a bare "#NNN"
+// autolinks to GitHub's own issue space (dead links for GDS task ids — task 916).
+// Mirrors ship.js sanitizeGitHubRefs (which lives in scripts/ and isn't requirable
+// here).
+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;
+
+function detectsMigration(...texts) {
+  return texts.some((t) => typeof t === 'string' && MIGRATION_KEYWORD_RE.test(t));
+}
+
+// ---- 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, credits landed; or shipped = deployed);
+// 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;
+  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 = function buildTasksRouter() {
+  const router = express.Router();
+
+  // rank: any-builder — reads (filtered task list); preserved per CRITICAL §4.
+  router.get('/tasks', auth.requireBuilder, async (req, res) => {
+    const { version, status, kind, discipline, goal_id } = req.query;
+    if (kind && !VALID_KINDS.has(kind)) {
+      return badKind(res);
+    }
+    if (discipline && !VALID_DISCIPLINES.has(discipline)) {
+      return res.fail('bad_discipline', 400, { valid: Array.from(VALID_DISCIPLINES) });
+    }
+    // ?goal_id= filters tasks to one goal (ADR 0086 §3 / BV1.R57). A non-numeric
+    // value is a 400 rather than a silently-ignored filter.
+    let goalId;
+    if (goal_id !== undefined) {
+      goalId = Number(goal_id);
+      if (!Number.isInteger(goalId) || goalId <= 0) {
+        return res.fail('bad_goal_id', { status: 400, message: 'goal_id must be a positive integer.' });
+      }
+    }
+    const tasks = await db.listTasks({ versionId: version, status, kind, discipline, goalId });
+    res.json({ tasks });
+  });
+
+  // NOTE: /tasks/claimable must come BEFORE /tasks/:id or Express will
+  // route 'claimable' to the :id param.
+  // rank: any-builder — claimable feed (read); preserved per CRITICAL §4 (supervisor hot path).
+  // #766: the primer-read onboarding gate that once sat here was removed — the
+  // Xenos path no longer requires reading the citizen's primer before surveying
+  // the works. Newcomers browse the claimable queue straight away; db.listClaimableTasks
+  // still filters Xenos to newcomer_friendly rows on its own.
+  router.get('/tasks/claimable',
+    auth.requireBuilder,
+    async (req, res) => {
+    const { version, discipline, fit } = req.query;
+    if (discipline && !VALID_DISCIPLINES.has(discipline)) {
+      return res.fail('bad_discipline', 400, { valid: Array.from(VALID_DISCIPLINES) });
+    }
+    if (fit && !VALID_FITS.has(fit)) {
+      return res.fail('bad_fit', 400, { valid: Array.from(VALID_FITS) });
+    }
+    const [claimable, active] = await Promise.all([
+      db.listClaimableTasks({
+        versionId: version || null,
+        builderId: req.builder.id,
+        discipline: discipline || null,
+        fit: fit || null,
+      }),
+      db.listActiveClaims(),
+    ]);
+    // V3.R75 (#294): tick the onboarding state machine for first_start. Fire
+    // and forget — the response should never wait on or fail because of the
+    // onboarding write. safeMarkStage swallows errors and handles the
+    // graduation broadcast. Through the `onboarding` kernel port (BV1.R81 / ADR
+    // 0093 §1); ?. degrades to a no-op when the module is off.
+    seams.resolveOptional('onboarding')?.safeMarkStage(pool, req.builder.id, 'first_start', req.builder);
+    res.json({ claimable, active_claims: active });
+  });
+
+  // GET /tasks/newcomer-floor — supply gauge for the newcomer queue (task 614).
+  // Per-discipline counts of newcomer_friendly tasks in the two unclaimed live
+  // statuses: `ready` (claimable now — what the floor is measured against, per
+  // the canonical query in task 614) and `backlog` (held / pending review —
+  // proposals an Archon hasn't promoted yet). The AI floor replenisher
+  // (scripts/gds/newcomer-floor.js) reads this to decide which disciplines are
+  // under-supplied, counting `ready + backlog` so a re-run never piles fresh
+  // proposals on top of ones already awaiting review (idempotency). The hall can
+  // also render it as a live gauge.
+  //
+  // Global across open versions on purpose — a Xenos can claim any
+  // newcomer_friendly ready task regardless of version, so the floor is a
+  // project-wide promise, not a per-version one. Read-only, any-builder; the
+  // inline SQL follows the same self-contained-feature-locality call as the
+  // peer-vote queries above (kept out of the shared db.js).
+  // MUST stay registered before '/tasks/:id' or Express routes the literal
+  // 'newcomer-floor' into the :id param (same ordering constraint as /claimable).
+  router.get('/tasks/newcomer-floor', auth.requireBuilder, async (_req, res) => {
+    try {
+      const { rows } = await pool.query(
+        `SELECT COALESCE(discipline, 'unclassified') AS discipline, status, COUNT(*)::int AS n
+           FROM tasks
+          WHERE newcomer_friendly = true AND status IN ('ready', 'backlog')
+          GROUP BY COALESCE(discipline, 'unclassified'), status`
+      );
+      const disciplines = {};
+      for (const d of VALID_DISCIPLINES) disciplines[d] = { ready: 0, backlog: 0 };
+      for (const r of rows) {
+        // discipline is COALESCE'd to a non-null string above; a value outside
+        // the known set (shouldn't happen) still gets a bucket rather than throwing.
+        if (!disciplines[r.discipline]) disciplines[r.discipline] = { ready: 0, backlog: 0 };
+        disciplines[r.discipline][r.status] = r.n;
+      }
+      res.json({ disciplines });
+    } catch (err) {
+      console.error('[gds] GET /tasks/newcomer-floor', err);
+      res.fail('newcomer_floor_failed', 500);
+    }
+  });
+
+  // POST /tasks/newcomer-restock (task 1168) — bring every evergreen newcomer
+  // chore's standing pool up to its configured floor. This is the SEED + manual
+  // BACKSTOP for the on-claim restock (the live mechanism is the post-claim hook
+  // in routes/claims.js). Archon-gated like all task creation (ADR 0016). Must
+  // be registered BEFORE GET /tasks/:id so ':id' doesn't swallow the literal.
+  router.post('/tasks/newcomer-restock', auth.requireBuilder, auth.requireRank('archon'), 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.
+      // Default-on (present in prod); a module-less instance has no chore shelf,
+      // so the backstop is a clean no-op (zero stamped).
+      const onboarding = seams.resolveOptional('onboarding');
+      const results = onboarding ? await onboarding.restockAll() : [];
+      const stamped = results.reduce((n, r) => n + (Array.isArray(r.stamped) ? r.stamped.length : 0), 0);
+      res.json({ ok: true, stamped, results });
+    } catch (err) {
+      console.error('[gds] POST /tasks/newcomer-restock', err);
+      res.fail('newcomer_restock_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: any-builder — single-task read; preserved per CRITICAL §4 (supervisor hot path).
+  router.get('/tasks/:id', auth.requireBuilder, async (req, res) => {
+    const id = Number(req.params.id);
+    const task = await db.getTask(id);
+    if (!task) return res.fail('task_not_found', 404);
+    // #678: the `--regrade` CLI needs the most recent claim holder to gate "you
+    // last held this claim, or you're Archon". It's opt-in via ?include=last_claim
+    // so this CRITICAL §4 supervisor hot path doesn't pay for an extra query on
+    // every read (grader quality finding). Additive sibling key when requested.
+    const includes = String(req.query.include || '').split(',');
+    const wantLastClaim = includes.includes('last_claim');
+    const wantGrade = includes.includes('grade');
+    const [dependencies, dependents, lastClaim, grade] = await Promise.all([
+      db.getTaskDependencies(id),
+      db.getTaskDependents(id),
+      wantLastClaim ? db.getLastClaimHolder(id) : Promise.resolve(null),
+      wantGrade ? db.getTaskGrade(id) : Promise.resolve(null),
+    ]);
+    const body = { task: { ...task, dependencies, dependents } };
+    if (wantLastClaim) body.last_claim = lastClaim;
+    if (wantGrade) body.grade = grade; // null when no grade exists yet
+    res.json(body);
+  });
+
+  // GET /tasks/:id/dependencies — same data, surfaced as its own resource.
+  // Returns { dependencies, dependents } — both arrays of task summaries.
+  // rank: any-builder — dep graph read; pure read, no mutation.
+  router.get('/tasks/:id/dependencies', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    const task = await db.getTask(id);
+    if (!task) return res.fail('task_not_found', 404);
+    const [dependencies, dependents] = await Promise.all([
+      db.getTaskDependencies(id),
+      db.getTaskDependents(id),
+    ]);
+    res.json({ dependencies, dependents });
+  });
+
+  // POST /tasks/:id/dependencies — body: { depends_on_task_id } OR
+  //                                       { depends_on_task_ids: [N, ...] }
+  // Returns 409 with code='cycle' if accepting would create a cycle.
+  // rank: metic+archon — task-shaping; Metic may wire deps of a task it can author (ADR 0090).
+  router.post('/tasks/:id/dependencies', auth.requireBuilder, auth.requireRank('metic', 'archon'), 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
+      // the strict integer check to the existing Number.isFinite guard below
+      // (declared untyped so strict-mode accepts the singular form too).
+      depends_on_task_id: {},
+    })) return;
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    const body = req.body || {};
+    let depIds = [];
+    if (Array.isArray(body.depends_on_task_ids)) {
+      depIds = body.depends_on_task_ids.map(Number).filter(Number.isFinite);
+    } else if (body.depends_on_task_id != null) {
+      depIds = [Number(body.depends_on_task_id)].filter(Number.isFinite);
+    }
+    if (depIds.length === 0) {
+      return res.fail('depends_on_task_id_required', 400);
+    }
+    const added = [];
+    for (const depId of depIds) {
+      try {
+        await db.addTaskDependency(id, depId);
+        added.push(depId);
+      } catch (err) {
+        if (err && err.code === 'SELF_DEP') {
+          return res.fail('self_dep', 400, { task_id: id });
+        }
+        if (err && err.code === 'TASK_NOT_FOUND') {
+          return res.fail('task_not_found', 404);
+        }
+        if (err && err.code === 'CYCLE') {
+          return res.fail('cycle', 409, { path: err.path });
+        }
+        throw err;
+      }
+    }
+    const dependencies = await db.getTaskDependencies(id);
+    res.json({ ok: true, added, dependencies });
+  });
+
+  // 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) => {
+    const id = Number(req.params.id);
+    const depId = Number(req.params.depId);
+    if (!Number.isFinite(id) || !Number.isFinite(depId)) {
+      return res.fail('bad_task_id', 400);
+    }
+    const removed = await db.removeTaskDependency(id, depId);
+    res.json({ ok: true, removed });
+  });
+
+  // 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) => {
+    if (validateOrRespond(req, res, {
+      depends_on_task_ids: { required: true, type: 'array', maxItems: 200 },
+    })) return;
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    const body = req.body || {};
+    if (!Array.isArray(body.depends_on_task_ids)) {
+      return res.fail('depends_on_task_ids_required', 400);
+    }
+    try {
+      const written = await db.setTaskDependencies(id, body.depends_on_task_ids);
+      const dependencies = await db.getTaskDependencies(id);
+      res.json({ ok: true, written, dependencies });
+    } catch (err) {
+      if (err && err.code === 'SELF_DEP') {
+        return res.fail('self_dep', 400);
+      }
+      if (err && err.code === 'CYCLE') {
+        return res.fail('cycle', 409, { path: err.path });
+      }
+      throw err;
+    }
+  });
+
+  // ---- task↔criterion links (task 438 / ADR 0025) — mirrors the dependency
+  // endpoints above. A criterion ref is a numeric done_when_criteria.id, a
+  // positional "Cn" token, or a criterion_id slug; the manage endpoints resolve
+  // it against the TASK's version so a cross-version link can't be formed.
+
+  // GET /tasks/:id/criteria — the criteria this task gates (with live "Cn" +
+  // source). Read-open like GET /tasks/:id/dependencies.
+  router.get('/tasks/:id/criteria', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    const criteria = await db.getTaskCriteria(id);
+    res.json({ criteria });
+  });
+
+  // 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) => {
+    if (validateOrRespond(req, res, {
+      criterion_ids: { type: 'array', maxItems: 100 },
+      // criterion_id is the singular alt-form (a numeric id, "Cn" token, or slug)
+      // — untyped so strict-mode accepts it alongside the array form.
+      criterion_id: {},
+    })) return;
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    const body = req.body || {};
+    let refs = [];
+    if (Array.isArray(body.criterion_ids)) refs = body.criterion_ids;
+    else if (body.criterion_id != null) refs = [body.criterion_id];
+    if (refs.length === 0) return res.fail('criterion_id_required', 400);
+
+    const task = await db.getTask(id);
+    if (!task) return res.fail('task_not_found', 404);
+    const { ids, unresolved } = await db.resolveCriterionIds(task.version_id, refs);
+    if (unresolved.length > 0) {
+      return res.fail('bad_criterion_ref', { status: 400, message: `These criterion refs don't match any criterion of version '${task.version_id}': ${unresolved.join(', ')}.`, details: { unresolved } });
+    }
+    const added = [];
+    for (const cid of ids) {
+      try {
+        await db.addTaskCriterion(id, cid, 'manual');
+        added.push(cid);
+      } catch (err) {
+        if (err && err.code === 'CRITERION_VERSION_MISMATCH') {
+          return res.fail('criterion_version_mismatch', 400);
+        }
+        if (err && err.code === 'CRITERION_NOT_FOUND') return res.fail('criterion_not_found', 404);
+        if (err && err.code === 'TASK_NOT_FOUND') return res.fail('task_not_found', 404);
+        throw err;
+      }
+    }
+    const criteria = await db.getTaskCriteria(id);
+    res.json({ ok: true, added, criteria });
+  });
+
+  // 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) => {
+    const id = Number(req.params.id);
+    const criterionId = Number(req.params.criterionId);
+    if (!Number.isFinite(id) || !Number.isFinite(criterionId)) {
+      return res.fail('bad_task_id', 400);
+    }
+    const removed = await db.removeTaskCriterion(id, criterionId);
+    res.json({ ok: true, removed });
+  });
+
+  // Task create/promote/edit (plan/scope mutation) is Metic+ as of ADR 0090
+  // (owner decision 2026-06-26): a Metic who can run idea-triage may also seed +
+  // shape tasks. Was Archon-only (task #106 / ADR 0016; three-rank model #360 /
+  // ADR 0018). A Xenos/Thetes still cannot author — they file ideas. Setting rank
+  // and closing versions stay Archon. The every-route audit is task #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) => {
+    if (validateOrRespond(req, res, {
+      version_id: { required: true, type: 'string', maxLength: 64 },
+      title: { required: true, type: 'string', maxLength: LIMITS.TITLE, minLength: 1 },
+      description: { type: 'string', maxLength: LIMITS.DESCRIPTION },
+      status: { type: 'string', maxLength: 32 },
+      touches: { type: 'array', maxItems: 500, itemsType: 'string' },
+      est_minutes: { type: 'integer', min: 0, max: 100000 },
+      est_cost_usd: { type: 'number', min: 0 },
+      manual_degree: { type: 'integer', min: TASK_FIELD_BOUNDS.manual_degree.min, max: TASK_FIELD_BOUNDS.manual_degree.max },
+      priority: { type: 'integer', min: TASK_FIELD_BOUNDS.priority.min, max: TASK_FIELD_BOUNDS.priority.max },
+      automation_tag: { type: 'string', maxLength: 64 },
+      credits_reward: { type: 'integer', min: 0, max: 1000000 },
+      source: { type: 'string', maxLength: LIMITS.SOURCE },
+      source_ref: { type: 'string', maxLength: LIMITS.SOURCE_REF },
+      value_summary: { type: 'string', maxLength: LIMITS.VALUE_SUMMARY },
+      kind: { type: 'string', maxLength: 64 },
+      discipline: { type: 'string', maxLength: 64 },
+      parallel_safe: {},  // accepts true/false/null — type checked below
+      newcomer_friendly: { type: 'boolean' },  // V3.R15 #239 — Xenos-claimable flag
+      security_sensitive: { type: 'boolean' },  // task 990 — Archon-only ship broadcast
+      requires_rank: { type: 'string', maxLength: 16 },  // task 1498 / ADR 0084 — per-task rank floor (auto-derived; explicit value can only raise it)
+      auto_detect_touches: { type: 'boolean' },
+      // task 438: link the new task to done-when criteria at creation time. Each
+      // element is a numeric done_when_criteria.id, a positional "Cn" token, or a
+      // criterion_id slug — resolved against this task's version below (ADR 0025).
+      criterion_ids: { type: 'array', maxItems: 100 },
+      // BV1.R53 (task 1422): module affinity label. Drives module-disjointness at
+      // claim time and diff⊆module drift detection at ship time.
+      module_key: { type: 'string', maxLength: 64 },
+      // Parent the new task under a specific goal at create (task 1763 added the
+      // PATCH-move vector; this is the create-time counterpart so a planning seed
+      // lands tasks under their goal, not the version's default catch-all).
+      // Validated to exist + belong to this version below.
+      goal_id: { type: 'integer', min: 1 },
+    })) return;
+    const body = req.body || {};
+    if (!body.version_id || !body.title) {
+      return res.fail('version_id_and_title_required', 400);
+    }
+    // task 975: a version is the ledger of one bounded chunk of work. Once it
+    // ships it is sealed history — its progress bar reads 100% and its scope
+    // is archived. Filing new work against it would reopen a closed book and
+    // (until the view fix above) silently drag the bar back below 100%. Reject
+    // creation against a missing or shipped version; the caller should target
+    // an open version or file the idea to idea_inbox for the next planning
+    // session. (POST /tasks is the only API create-vector — PATCH cannot
+    // re-bind version_id — so this is the complete guard.)
+    const targetVersion = await db.getVersion(body.version_id);
+    if (!targetVersion) {
+      return res.fail('version_not_found', { status: 404, message: `No version '${body.version_id}'. Create the task under an existing, open version.` });
+    }
+    // task 386 (idea #85): idempotency on (source, source_ref). A re-submitted
+    // create — a retried POST, a capture/promotion re-run — must resolve to the
+    // ORIGINAL task, not silently mint a duplicate (the #248-dup-of-#252 class of
+    // bug). Runs BEFORE the version-closed guard so re-POSTing the same ref after
+    // its task already shipped (version now closed) returns the existing row
+    // instead of a spurious 409. `source` defaults to 'manual' to match the
+    // createTask call below, so the lookup key is exactly what would be written.
+    const effectiveSource = body.source ?? 'manual';
+    if (body.source_ref) {
+      const existing = await db.findTaskBySourceRef({ source: effectiveSource, sourceRef: body.source_ref });
+      if (existing) {
+        const criteria = await db.getTaskCriteria(existing.id);
+        return res.status(200).json({
+          task: existing,
+          needs_migration: existing.needs_migration === true,
+          criteria,
+          idempotent: true,
+        });
+      }
+    }
+    if (targetVersion.status === 'shipped') {
+      return res.fail('version_closed', { status: 409, message: `Version '${body.version_id}' has shipped — it is closed history and cannot take new tasks. ` +
+          `Target an open version, or capture this in idea_inbox for the next planning session.` });
+    }
+    // task 438: resolve any criterion_ids BEFORE creating the task, so a bad ref
+    // is a clean 400 with nothing created. Scoped to this task's version, so "C8"
+    // is unambiguous and a numeric id from another version doesn't resolve.
+    let criterionIdsResolved = [];
+    if (Array.isArray(body.criterion_ids) && body.criterion_ids.length > 0) {
+      const { ids, unresolved } = await db.resolveCriterionIds(body.version_id, body.criterion_ids);
+      if (unresolved.length > 0) {
+        return res.fail('bad_criterion_ref', { status: 400, message: `These criterion refs don't match any criterion of version '${body.version_id}': ` +
+            `${unresolved.join(', ')}. Use a numeric done_when_criteria.id, a "Cn" position, or a criterion_id slug.`, details: { unresolved } });
+      }
+      criterionIdsResolved = ids;
+    }
+    // Resolve kind: caller wins if they specified a valid non-unclassified
+    // value; otherwise run the heuristic classifier on title+description.
+    // Confidence < 0.5 falls through to 'unclassified' for triage.
+    let kind = body.kind;
+    if (kind && !VALID_KINDS.has(kind)) {
+      return badKind(res);
+    }
+    if (!kind || kind === 'unclassified') {
+      const result = classifyTaskKind(body.title, body.description || '');
+      kind = result.confidence >= 0.5 ? result.kind : 'unclassified';
+    }
+    const discipline = body.discipline ?? 'unclassified';
+    if (!VALID_DISCIPLINES.has(discipline)) {
+      return res.fail('bad_discipline', 400, { valid: Array.from(VALID_DISCIPLINES) });
+    }
+    // task 1498 / ADR 0084: an explicit requires_rank must be a live rank. The
+    // floor auto-derives from touches + security_sensitive; createTask clamps
+    // any explicit value UP to that floor (never below), so this only rejects a
+    // malformed enum.
+    if (body.requires_rank != null) {
+      const LIVE_RANKS = new Set(db.LIVE_RANK_LADDER);
+      if (!LIVE_RANKS.has(body.requires_rank)) {
+        return res.fail('bad_requires_rank', { status: 400, message: `requires_rank must be one of ${db.LIVE_RANK_LADDER.join(' | ')}. The floor auto-derives from touches + security_sensitive; an explicit value can only raise it.`, details: { valid: db.LIVE_RANK_LADDER } });
+      }
+    }
+    // BV1.R53 (task 1422): validate module_key against MODULE_SCOPE_MAP.
+    if (body.module_key != null && !isModuleKey(body.module_key)) {
+      return res.fail('bad_module_key', { status: 400, message: `module_key must be one of the known module keys, or omitted. Valid keys: ${moduleKeys().join(', ')}.`, details: { valid: moduleKeys() } });
+    }
+    // V3.R48 (#267) → migration 081 (task 876): if the title/description reads
+    // like a schema change, flag tasks.needs_migration so the claim-time
+    // allocator reserves a migration number. This used to inject the literal
+    // 'migrations/' into touches[]; it now sets a dedicated boolean and leaves
+    // touches[] alone. Opt out with { auto_detect_touches: false }.
+    const touches = Array.isArray(body.touches) ? [...body.touches] : [];
+    const autoDetect = body.auto_detect_touches !== false;
+    const needsMigration = autoDetect && detectsMigration(body.title, body.description);
+    // Validate an explicit goal_id: it must exist AND belong to THIS version (a task
+    // can't be parented under another version's goal). Absent → the default-goal
+    // trigger files it under the version's catch-all goal, exactly as before.
+    if (body.goal_id != null) {
+      const goal = await db.getGoal(body.goal_id);
+      if (!goal || String(goal.version_id) !== String(body.version_id)) {
+        return res.fail('bad_goal_id', { status: 400, message: `goal_id ${body.goal_id} does not exist on version '${body.version_id}'.` });
+      }
+    }
+    try {
+      const task = await db.createTask({
+        versionId: body.version_id,
+        title: body.title,
+        description: body.description || '',
+        status: body.status || 'backlog',
+        touches,
+        estMinutes: body.est_minutes ?? null,
+        estCostUsd: body.est_cost_usd ?? null,
+        manualDegree: body.manual_degree ?? null,
+        priority: body.priority ?? null,
+        automationTag: body.automation_tag ?? null,
+        creditsReward: body.credits_reward ?? 0,
+        source: effectiveSource,
+        sourceRef: body.source_ref ?? null,
+        valueSummary: body.value_summary ?? null,
+        kind,
+        discipline,
+        parallelSafe: typeof body.parallel_safe === 'boolean' ? body.parallel_safe : null,
+        newcomerFriendly: body.newcomer_friendly === true,
+        securitySensitive: body.security_sensitive === true,
+        needsMigration,
+        requiresRank: body.requires_rank ?? null,
+        moduleKey: body.module_key ?? null,
+        goalId: body.goal_id ?? null,
+      });
+      // task 438: link resolved criteria (source='planning' — task-create is the
+      // planning vector). The ids were version-checked above, so this is a single
+      // idempotent batch insert; surface the linked criteria in the response so the
+      // caller (and planning-session) can confirm the task is attributed.
+      let criteria = [];
+      if (criterionIdsResolved.length > 0) {
+        await db.linkTaskCriteria(task.id, criterionIdsResolved, 'planning');
+        criteria = await db.getTaskCriteria(task.id);
+      }
+      // task 1677 / ADR 0096: surface the assigned credits_reward so the creator sees
+      // the drachmae value the task was born with — auto-assigned at creation when the
+      // caller supplied no positive value (0/absent flows into createTask as "unset").
+      // task 1957: credits_reward is an ESTIMATE, not a guaranteed payout. The hall
+      // renders it as "<Currency> Est." until the task settles (confirmed/shipped),
+      // then switches to the real ledger figure (credits_awarded from the task read).
+      res.status(201).json({
+        task,
+        credits_reward: task.credits_reward,
+        needs_migration: needsMigration,
+        criteria,
+      });
+    } catch (err) {
+      console.error('[gds] POST /tasks', err);
+      res.fail('create_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH /tasks/:id — supports body.parent_task_id (V2 C2), body.kind (V2 B1),
+  // body.discipline (mig 014), body.parallel_safe
+  // (mig 028), and body.newcomer_friendly (#360 / ADR 0018 + V3.R15 #239 —
+  // body.touches was removed in touches[] cleanup [4/8] (task 879) along with
+  // the drift scanner —
+  // open a task to the Xenos sandbox; alias body.xenos_claimable accepted for
+  // pre-rename callers). Pass parent_task_id: null to detach; parallel_safe
+  // accepts true|false|null; newcomer_friendly is a boolean. Validation lives
+  // in hierarchy.js for parent; the rest are validated inline.
+  // rank: metic+archon — edit work (incl. newcomer_friendly flag); ADR 0090 (was ADR 0016 archon).
+  router.patch('/tasks/:id', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+    if (validateOrRespond(req, res, {
+      kind: { type: 'string', maxLength: 64 },
+      discipline: { type: 'string', maxLength: 64 },
+      requires_rank: { type: 'string', maxLength: 16 },  // task 1498 / ADR 0084 — override the per-task rank floor (upward only)
+      module_key: { type: 'string', maxLength: 64 },     // BV1.R53 (task 1422) — module affinity label
+      goal_id: { type: 'integer', min: 1 },              // task 1763 — (re)assign the task's goal (must be in the task's version)
+      // touches[] cleanup [4/8] (task 879): touches is no longer PATCH-able —
+      // the drift scanner + mid-claim expansion were removed. The rest are
+      // checked inline below but must be DECLARED so strict-mode (R11/#1998)
+      // accepts them instead of rejecting them as unknown fields.
+      parent_task_id: {},                                // number id, or null to detach (hasOwnProperty-gated below)
+      parallel_safe: {},                                 // true/false/null — checked inline
+      newcomer_friendly: { type: 'boolean' },            // V3.R15 — Xenos-claimable flag
+      xenos_claimable: { type: 'boolean' },              // pre-rename alias for newcomer_friendly
+      security_sensitive: { type: 'boolean' },           // task 990 — Archon-only ship broadcast
+      automation_tag: { type: 'string', maxLength: 64 },
+    })) return;
+    const id = parseId(req, res, { code: 'bad_task_id', positiveInt: true });
+    if (id === null) return;
+    const body = req.body || {};
+    const hasParent = Object.prototype.hasOwnProperty.call(body, 'parent_task_id');
+    const hasKind = Object.prototype.hasOwnProperty.call(body, 'kind');
+    const hasDiscipline = Object.prototype.hasOwnProperty.call(body, 'discipline');
+    // V3.R15 #239: newcomer_friendly is the canonical name; xenos_claimable is
+    // the pre-rename alias and still accepted. Either presence triggers the
+    // same update path.
+    const hasNewcomerFriendly = Object.prototype.hasOwnProperty.call(body, 'newcomer_friendly');
+    const hasXenosClaimable = Object.prototype.hasOwnProperty.call(body, 'xenos_claimable');
+    const hasNewcomerOrXenos = hasNewcomerFriendly || hasXenosClaimable;
+    const hasParallelSafe = Object.prototype.hasOwnProperty.call(body, 'parallel_safe');
+    const hasSecuritySensitive = Object.prototype.hasOwnProperty.call(body, 'security_sensitive');
+    const hasAutomationTag = Object.prototype.hasOwnProperty.call(body, 'automation_tag');
+    const hasRequiresRank = Object.prototype.hasOwnProperty.call(body, 'requires_rank');
+    const hasModuleKey = Object.prototype.hasOwnProperty.call(body, 'module_key');
+    const hasGoalId = Object.prototype.hasOwnProperty.call(body, 'goal_id');
+    // #514: status is a lifecycle field, not a PATCH-able column — it moves only
+    // through the dedicated transition routes. The #506 session tried
+    // `PATCH status=ready`, got the generic no_supported_fields error, and had
+    // to go spelunking for the promote route. Detect status explicitly and point
+    // the caller straight at the right endpoint.
+    const STATUS_HINT =
+      'status is not editable via PATCH; use POST /tasks/:id/promote (backlog->ready), ' +
+      '/tasks/:id/confirm, /tasks/:id/ship, or /claims/:id/resolve to move a task through its lifecycle.';
+    if (Object.prototype.hasOwnProperty.call(body, 'status')) {
+      return res.fail('status_not_patchable', { status: 400, message: STATUS_HINT });
+    }
+    if (!hasParent && !hasKind && !hasDiscipline && !hasNewcomerOrXenos && !hasParallelSafe && !hasSecuritySensitive && !hasAutomationTag && !hasRequiresRank && !hasModuleKey && !hasGoalId) {
+      return res.fail('no_supported_fields', { status: 400, message: 'PATCH /tasks/:id supports parent_task_id, kind, discipline, parallel_safe, security_sensitive, automation_tag, requires_rank, module_key, goal_id, and newcomer_friendly (alias: xenos_claimable). ' + STATUS_HINT });
+    }
+    let updated = null;
+    if (hasParallelSafe) {
+      if (body.parallel_safe !== null && typeof body.parallel_safe !== 'boolean') {
+        return res.fail('bad_parallel_safe', { status: 400, message: 'parallel_safe must be true, false, or null' });
+      }
+      try {
+        updated = await db.updateTaskParallelSafe(id, body.parallel_safe);
+        if (!updated) return res.fail('task_not_found', 404);
+      } catch (err) {
+        console.error('[gds] PATCH /tasks/:id parallel_safe', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
+    if (hasSecuritySensitive) {
+      // task 990: explicit Archon-only-broadcast flag. Boolean only (no null) —
+      // it gates whether ship.js routes the broadcast to the Archon-only
+      // #security-ship-feed channel instead of the public feeds.
+      // ADR 0090: PATCH /tasks/:id opened to Metic+, but security_sensitive is a
+      // SECURITY control (broadcast suppression + it feeds the auto-derived rank
+      // floor, ADR 0084), not a planning field — so it stays Archon-only via this
+      // in-handler gate. A Metic editing any other field is unaffected; only a
+      // requires_rank-style escalation surface is withheld. (Setting it at create
+      // time is safe — a brand-new task has no existing sensitivity to clear.)
+      if (!auth.rankMeetsThreshold(req.builder.rank, ['archon'])) {
+        return res.fail('rank_forbidden', 403, { required: ['archon'], actual: req.builder.rank, reason: 'security_sensitive is an Archon-only security control (ADR 0090); a Metic may edit every other task field.' });
+      }
+      if (typeof body.security_sensitive !== 'boolean') {
+        return res.fail('bad_security_sensitive', { status: 400, message: 'security_sensitive must be a boolean' });
+      }
+      try {
+        updated = await db.updateTaskSecuritySensitive(id, body.security_sensitive);
+        if (!updated) return res.fail('task_not_found', 404);
+      } catch (err) {
+        console.error('[gds] PATCH /tasks/:id security_sensitive', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
+    if (hasAutomationTag) {
+      const tag = body.automation_tag;
+      const VALID_AUTOMATION_TAGS = new Set(['overnight-safe', 'live-only', 'needs-input']);
+      if (tag !== null && (typeof tag !== 'string' || !VALID_AUTOMATION_TAGS.has(tag))) {
+        return res.fail('bad_automation_tag', { status: 400, message: 'automation_tag must be one of overnight-safe | live-only | needs-input, or null to clear', details: { valid: Array.from(VALID_AUTOMATION_TAGS) } });
+      }
+      try {
+        updated = await db.updateTaskAutomationTag(id, tag);
+        if (!updated) return res.fail('task_not_found', 404);
+      } catch (err) {
+        console.error('[gds] PATCH /tasks/:id automation_tag', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
+    if (hasModuleKey) {
+      // BV1.R53 (task 1422): assign or clear the module affinity label. null clears.
+      const key = body.module_key;
+      if (key !== null && !isModuleKey(key)) {
+        return res.fail('bad_module_key', { status: 400, message: `module_key must be one of the known module keys, or null to clear. Valid keys: ${moduleKeys().join(', ')}.`, details: { valid: moduleKeys() } });
+      }
+      try {
+        updated = await db.updateTaskModuleKey(id, key ?? null);
+        if (!updated) return res.fail('task_not_found', 404);
+      } catch (err) {
+        console.error('[gds] PATCH /tasks/:id module_key', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
+    if (hasGoalId) {
+      // task 1763: (re)assign the task's goal — the documented "Archon/Metic
+      // mechanism" to set goal_id (this route is metic+archon). A task belongs to
+      // exactly one goal WITHIN its own version: both the per-version general goals
+      // and goal-authored tasks hold this, and the /status rollup walks
+      // version→goal→task, so a cross-version link would drop the task out of its
+      // version's rollup. Refuse that (409). goal_id is never cleared to null here
+      // (that reintroduces an orphan) — a positive integer is required.
+      const goalId = body.goal_id;
+      if (!Number.isInteger(goalId) || goalId <= 0) {
+        return res.fail('bad_goal_id', { status: 400, message: 'goal_id must be a positive integer — a task belongs to exactly one goal.' });
+      }
+      try {
+        const task = await db.getTask(id);
+        if (!task) return res.fail('task_not_found', 404);
+        const goal = await db.getGoal(goalId);
+        if (!goal) return res.fail('goal_not_found', { status: 404, message: `No goal #${goalId}.` });
+        if (String(goal.version_id) !== String(task.version_id)) {
+          return res.fail('goal_version_mismatch', { status: 409, message: `Goal #${goalId} is in version '${goal.version_id}' but task #${id} is in '${task.version_id}'. A task can only join a goal in its own version.` });
+        }
+        updated = await db.updateTaskGoal(id, goalId);
+        if (!updated) return res.fail('task_not_found', 404);
+      } catch (err) {
+        console.error('[gds] PATCH /tasks/:id goal_id', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
+    if (hasRequiresRank) {
+      // task 1498 / ADR 0084: the Archon override of the per-task rank floor.
+      // Validate the enum here; db.updateTaskRequiresRank clamps the value UP to
+      // the auto-derived floor (touches + security_sensitive), so a PATCH can
+      // only RAISE the gate — never open a sensitive task to a lower rank. Runs
+      // AFTER the security_sensitive block above, so a same-request flag flip is
+      // already reflected in the derived floor.
+      const LIVE_RANKS = new Set(db.LIVE_RANK_LADDER);
+      if (typeof body.requires_rank !== 'string' || !LIVE_RANKS.has(body.requires_rank)) {
+        return res.fail('bad_requires_rank', { status: 400, message: `requires_rank must be one of ${db.LIVE_RANK_LADDER.join(' | ')}. An override can only raise the floor; it is clamped up to the auto-derived minimum.`, details: { valid: db.LIVE_RANK_LADDER } });
+      }
+      try {
+        updated = await db.updateTaskRequiresRank(id, body.requires_rank);
+        if (!updated) return res.fail('task_not_found', 404);
+      } catch (err) {
+        console.error('[gds] PATCH /tasks/:id requires_rank', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
+    if (hasKind) {
+      if (!VALID_KINDS.has(body.kind)) {
+        return badKind(res);
+      }
+      try {
+        updated = await db.updateTaskKind(id, body.kind);
+        if (!updated) return res.fail('task_not_found', 404);
+      } catch (err) {
+        console.error('[gds] PATCH /tasks/:id kind', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
+    if (hasDiscipline) {
+      if (!VALID_DISCIPLINES.has(body.discipline)) {
+        return res.fail('bad_discipline', 400, { valid: Array.from(VALID_DISCIPLINES) });
+      }
+      try {
+        updated = await db.updateTaskDiscipline(id, body.discipline);
+        if (!updated) return res.fail('task_not_found', 404);
+      } catch (err) {
+        console.error('[gds] PATCH /tasks/:id discipline', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
+    if (hasNewcomerOrXenos) {
+      // V3.R15 #239: prefer newcomer_friendly (canonical); fall back to
+      // xenos_claimable (pre-rename alias). Both map to the same DB column.
+      const incoming = hasNewcomerFriendly ? body.newcomer_friendly : body.xenos_claimable;
+      if (typeof incoming !== 'boolean') {
+        const field = hasNewcomerFriendly ? 'newcomer_friendly' : 'xenos_claimable';
+        return res.fail(`bad_${field}`, { status: 400, message: `${field} must be a boolean` });
+      }
+      try {
+        updated = await db.updateTaskNewcomerFriendly(id, incoming);
+        if (!updated) return res.fail('task_not_found', 404);
+      } catch (err) {
+        console.error('[gds] PATCH /tasks/:id newcomer_friendly', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
+    if (!hasParent) return res.json({ task: updated });
+    try {
+      const task = await hierarchy.attachParent(id, body.parent_task_id);
+      res.json({ task });
+    } catch (err) {
+      if (err && err.code) {
+        const status =
+          err.code === 'TASK_NOT_FOUND'        ? 404 :
+          err.code === 'PARENT_NOT_FOUND'      ? 404 :
+          err.code === 'SELF_PARENT'           ? 409 :
+          err.code === 'VERSION_MISMATCH'      ? 409 :
+          err.code === 'PARENT_HAS_PARENT'     ? 409 :
+          err.code === 'TARGET_HAS_CHILDREN'   ? 409 :
+          500;
+        return res.fail(err.code, status, { ...err });
+      }
+      console.error('[gds] PATCH /tasks/:id', err);
+      res.fail('patch_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // rank: metic+archon — backlog→ready promotion; scope mutation; ADR 0090 (was archon).
+  router.post('/tasks/:id/promote', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+    const id = Number(req.params.id);
+    const task = await db.getTask(id);
+    if (!task) return res.fail('task_not_found', 404);
+    if (!['backlog', 'blocked'].includes(task.status)) {
+      return res.fail('cannot_promote', 409, { current_status: task.status });
+    }
+    // task 1670 / ADR 0096 + task 1673 amendment (2026-06-28): a task must never
+    // become workable paying 0 drachmae — but the gate AUTO-ASSIGNS rather than
+    // BLOCKS. If credits_reward is 0/NULL, assign the capped suggestion (from
+    // kind/est, cap 60) and PROCEED to promote. The promote is never refused for
+    // a missing reward. This reverses ADR 0023's strict author-set stance for the
+    // gate-time value only (capped + audited); explicit author-set values via
+    // PATCH /tasks/:id and the ungameable cost-plus session reward (ADR 0054)
+    // remain the primary drivers. AUDIT: setCreditsReward logs + the visible
+    // credits_reward change.
+    let assignedReward = null;
+    const rewardAssign = db.rewardGateAssignment(task);
+    if (rewardAssign) {
+      const updated = await db.setCreditsReward(id, rewardAssign.assign);
+      assignedReward = updated ? updated.credits_reward : rewardAssign.assign;
+    }
+    await db.updateTaskStatus(id, 'ready');
+    res.json({ ok: true, ...(assignedReward !== null ? { assigned_credits_reward: assignedReward } : {}) });
+  });
+
+  // POST /tasks/:id/demote — the strict inverse of /promote: flip a task
+  // ready→backlog and nothing else. Use case (task 1223): a dependency-gated task
+  // that was wrongly promoted to ready needs to go back to backlog without
+  // hand-SQL on prod. Mirrors /promote's auth (Metic+ — scope mutation, ADR 0090).
+  //
+  // Strictly ready→backlog: refuse any other current status (blocked, active, or
+  // any later lifecycle state). A claimed task is `active`, so this gate also
+  // refuses demoting work that's already in flight — demote is not a way to yank a
+  // task out from under its claim holder. No reward side-effects (the reward gate
+  // is a promote-only concern; backlog is the pre-workable state).
+  // rank: metic+archon — ready→backlog demotion; scope mutation; mirrors /promote (ADR 0090).
+  router.post('/tasks/:id/demote', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+    const id = Number(req.params.id);
+    const task = await db.getTask(id);
+    if (!task) return res.fail('task_not_found', 404);
+    if (task.status !== 'ready') {
+      return res.fail('cannot_demote', 409, { current_status: task.status });
+    }
+    await db.updateTaskStatus(id, 'backlog');
+    res.json({ ok: true });
+  });
+
+  // Phase 5 lifecycle transitions: completed → confirmed → shipped.
+  // /resolve handles active → completed (and the auto-completed-to-confirmed
+  // promotion when verification passes). These endpoints handle the manual
+  // overrides + the final merge step.
+
+  // confirmed → shipped. Called by /merge-mode (or the auto-merge chain in
+  // /builder-ship) once the branch is on main + deployed.
+  // rank: any-builder — confirmed→shipped on builder's own work; supervisor hot path
+  // (preserved per CRITICAL §4 — no requireRank).
+  router.post('/tasks/:id/ship', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    // SECURITY (#871): confirmed→shipped is an any-builder supervisor hot path so
+    // /merge-mode can sweep the queue — but a Xenos/Thetes should only flip their
+    // OWN confirmed task. allowSupervisor lets Metic+ (who run /merge-mode) ship
+    // across builders; the claim holder ships their own; everyone else is 403'd.
+    if (!(await gateTaskOwnership(req, res, id, { allowSupervisor: true }))) return;
+    try {
+      const task = await db.shipTask({ taskId: id, builderId: req.builder.id });
+      // task 1749: emit task.shipped on THIS entry point too, not just the
+      // publish-status reconcile-on-read path (line ~1545) + the reconciler
+      // sweep. A direct ship here (e.g. /merge-mode sweeping the confirmed
+      // queue) otherwise lands with no Discord broadcast. shipTask is the
+      // confirmed→shipped flip and throws TASK_NOT_CONFIRMED on a repeat, so
+      // whichever entry point wins the transition is the only one that reaches
+      // this line — the emit fires exactly ONCE per ship across all three
+      // paths. The server is thus the SINGLE ship broadcaster (the box/laptop
+      // local post in scripts/gds/ship.js was removed as a duplicate, task
+      // 1749). Best-effort: emitAsync isolates listener errors so a broadcast
+      // hiccup can never turn a successful ship into a 500.
+      try { await seams.emitAsync('task.shipped', task); } catch (_) { /* non-blocking */ }
+      res.json({ ok: true, task });
+    } catch (err) {
+      if (err.code === 'TASK_NOT_CONFIRMED') {
+        return res.fail('task_not_confirmed', 409);
+      }
+      console.error('[gds] POST /tasks/:id/ship', err);
+      res.fail('ship_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // completed → confirmed. Manual override for cases where automated
+  // verification at /resolve time was inconclusive but a human has since
+  // verified. Awards credits if not already credited (idempotent).
+  //
+  // Archon-only (#231): this bypasses the subagent quality grader, so it must
+  // not be self-serviceable by a builder pushing their own work past a failed
+  // grade. /ship and /grade below stay open — they're part of any builder's
+  // own ship flow (the grade is computed by an objective subagent).
+  //
+  // #853 (ADR 0041): a temporary, default-OFF env kill-switch
+  // GRADER_BYPASS_ENABLED relaxes this gate to any-builder during a grader
+  // OUTAGE (e.g. a provider 429), so every builder can land work without the
+  // subagent grader. When the env is unset/!=='1' the archon-only gate from
+  // #231 stays in force, preserving the ADR 0016 trust boundary by default.
+  // The relaxation is logged so the audit trail shows every bypass confirm.
+  // rank: archon — grader-bypass override (relaxed to any-builder only while
+  // GRADER_BYPASS_ENABLED==='1'; archon-only otherwise).
+  const confirmRankGate = (req, res, next) => {
+    if (graderBypassEnabled()) return next();
+    return auth.requireRank('archon')(req, res, next);
+  };
+  router.post('/tasks/:id/confirm', auth.requireBuilder, confirmRankGate, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      // { verified: true } attestation for verify-kind tasks (checked below);
+      // absent/any-shape otherwise. Untyped so the supervisor's `{}` and the
+      // `--verified` boolean both pass; strict rejects a typo'd extra field.
+      verified: {},
+    })) return;
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    // SECURITY (#871): the grader-bypass relaxation lets ANY builder reach this
+    // route during the outage. Confirm is meant to land a builder's OWN work past
+    // the (absent) grader — NOT to let anyone confirm anyone's task. Gate to the
+    // claim holder (or Archon). In the normal (non-bypass) path the route is
+    // already archon-only, and an Archon always passes this check.
+    if (!(await gateTaskOwnership(req, res, id))) return;
+    // task 1053 (F): a verification task must not be confirmed before the verify
+    // actually ran. A passing code-grade (or the skip-grade bypass) says nothing
+    // about whether the hardware-verify was performed — that gap let #1027 sit at
+    // 'confirmed' unverified. Require an explicit { verified: true } attestation.
+    // Defense-in-depth: /builder-ship passes it from the --verified flag.
+    const confirmTaskRow = await db.getTask(id);
+    if (isVerifyTask(confirmTaskRow) && req.body?.verified !== true) {
+      return res.fail('verify_attestation_required', { status: 409, message: `Task #${id} is a verification task (kind='verify') — confirm it only AFTER the verification ` +
+          `actually passed, with { "verified": true }. Re-run /builder-ship ${id} --verified once it has.` });
+    }
+    if (graderBypassEnabled()) {
+      console.log(`[gds] grader-bypass confirm: builder ${req.builder.id} (${req.builder.rank}) confirming task ${id} with GRADER_BYPASS_ENABLED on`);
+    }
+    try {
+      const result = await db.confirmTask({ taskId: id, builderId: req.builder.id });
+      res.json({ ok: true, ...result });
+    } catch (err) {
+      if (err.code === 'TASK_NOT_COMPLETED') {
+        return res.fail('task_not_completed', 409);
+      }
+      console.error('[gds] POST /tasks/:id/confirm', err);
+      res.fail('confirm_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /tasks/:id/abandon — terminal "retire this task" transition (task 987).
+  // The lifecycle had promote/ship/confirm/resolve but no first-class way to KILL
+  // a task that is no longer relevant: the only paths to status='abandoned' were
+  // offboarding a builder or a raw SQL UPDATE, so stale/moot tasks lingered in
+  // 'ready' as claimable noise. Refuses on a shipped task (immutable history) and
+  // on a task with an active claim (release it first); idempotent on an already-
+  // abandoned task. The abandon + its `reason` land in audit_log via the writing
+  // middleware, so the ledger keeps a record of who retired what.
+  // rank: archon — terminal lifecycle mutation / scope removal (ADR 0016). This
+  // is the inverse of /promote and belongs to the same archon-gated scope-control
+  // surface, never self-serviceable by a lower rank.
+  router.post('/tasks/:id/abandon', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    if (validateOrRespond(req, res, {
+      reason: { type: 'string' },  // free-text retire reason (sliced to 2000 below)
+    })) return;
+    const id = parseId(req, res, { code: 'bad_task_id', positiveInt: true });
+    if (id === null) return;
+    const reason = typeof req.body?.reason === 'string' ? req.body.reason.slice(0, 2000) : '';
+    try {
+      const result = await db.abandonTask({ taskId: id, reason });
+      res.json({ ok: true, ...result });
+    } catch (err) {
+      if (err.code === 'TASK_NOT_FOUND') return res.fail('task_not_found', 404);
+      if (err.code === 'CANNOT_ABANDON_SHIPPED') {
+        return res.fail('cannot_abandon_shipped', { status: 409, message: 'shipped tasks are immutable history' });
+      }
+      if (err.code === 'TASK_HAS_ACTIVE_CLAIM') {
+        return res.fail('task_has_active_claim', { status: 409, message: 'release the active claim before abandoning' });
+      }
+      console.error('[gds] POST /tasks/:id/abandon', err);
+      res.fail('abandon_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // ==== peer votes (V3.R25 #245) — criterion C2 karma signal sourcing =======
+  // These three sit BEFORE the generic /tasks/:id-shaped routes that take a
+  // numeric id, but Express keys on the literal path so /tasks/peer-votes/feed
+  // (3 segments, non-numeric) never collides with /tasks/:id (2 segments).
+
+  // GET /tasks/peer-votes/feed — recent confirmed/shipped work by OTHER
+  // builders, each with its net vote total and the caller's own current vote,
+  // so the hall can render a vote widget per row. Any builder may view; only
+  // Metic+ may actually vote (enforced on POST below). Excludes the caller's
+  // own ships (you can't vote on yourself).
+  // rank: any-builder — read of the votable feed.
+  router.get('/tasks/peer-votes/feed', auth.requireBuilder, async (req, res) => {
+    // R14 (#2001 / ADR 0119): shared helper; per-endpoint cap preserved (default 25, max 100).
+    const { limit } = api.parsePagination(req, { defaultLimit: 25, maxLimit: 100 });
+    try {
+      const { rows } = await pool.query(
+        `SELECT t.id, t.title, t.value_summary, t.version_id, t.status,
+                t.shipped_at, t.shipped_by,
+                b.github_login, b.display_name,
+                COALESCE(pv.net, 0)::int AS net_votes,
+                mine.vote                AS my_vote
+           FROM tasks t
+           LEFT JOIN builders b ON b.id = t.shipped_by
+           LEFT JOIN LATERAL (
+             SELECT SUM(vote) AS net
+               FROM peer_votes WHERE target_task_id = t.id
+           ) pv ON true
+           LEFT JOIN peer_votes mine
+             ON mine.target_task_id = t.id AND mine.voter_builder_id = $1
+          WHERE t.status IN ('confirmed', 'shipped')
+            AND t.shipped_by IS NOT NULL
+            AND t.shipped_by <> $1
+            AND t.title NOT LIKE '\\_\\_smoke\\_\\_%' ESCAPE '\\'
+          ORDER BY COALESCE(t.shipped_at, t.updated_at) DESC NULLS LAST
+          LIMIT $2`,
+        [req.builder.id, limit]
+      );
+      res.json({ tasks: rows, can_vote: ['metic', 'archon'].includes(req.builder.rank) });
+    } catch (err) {
+      // Log the detail server-side; don't return err.message — a raw Postgres
+      // error can leak schema internals (table/column/constraint names).
+      console.error('[gds] GET /tasks/peer-votes/feed', err);
+      res.fail('feed_failed', 500);
+    }
+  });
+
+  // POST /tasks/peer-votes/tally — fold matured votes (≥7 days old, not yet
+  // counted) into karma_log, one net row per shipping builder, then mark them
+  // tallied. Idempotent + transactional. Driven by the weekly cron
+  // (.claude/scheduled-tasks/peer-vote-tally/). Archon-gated — it writes karma.
+  // rank: archon — writes karma_log on others' behalf; scope-shaping reputation.
+  // The tally transaction lives in db.tallyPeerVotes() (task 1382, ADR 0078
+  // amendment) so this route AND the server-internal weekly timer (the carved
+  // autonomy module's poller, modules/autonomy/pollers/routine-timers.js, which
+  // reaches it via the doorway api.tallyPeerVotes — BV1.R83) share one code path
+  // and can never diverge. This route keeps the Archon gate (the HTTP surface
+  // stays Archon-only); the in-process timer has no requester to authorize.
+  router.post('/tasks/peer-votes/tally', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    try {
+      const result = await db.tallyPeerVotes();
+      res.json(result);
+    } catch (err) {
+      console.error('[gds] POST /tasks/peer-votes/tally', err);
+      res.fail('tally_failed', 500);
+    }
+  });
+
+  // POST /tasks/:id/vote { vote: 1 | -1 | 0 } — cast/change/clear a peer vote on
+  // a confirmed/shipped task. Metic+ only (Xenos read-only on the project).
+  //   - 403 anti-self-vote if the caller shipped the task
+  //   - 409 if the task isn't votable, or the vote was already folded into karma
+  //   - vote: 0 clears (deletes the row, only while still untallied)
+  // rank: metic+archon — a trusted-builder reputation action.
+  router.post('/tasks/:id/vote', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+    if (validateOrRespond(req, res, {
+      vote: { required: true, type: 'integer', enum: [-1, 0, 1] },
+    })) return;
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    const vote = req.body ? req.body.vote : undefined;
+    if (![-1, 0, 1].includes(vote)) {
+      return res.fail('bad_vote', 400, { detail: 'vote must be 1, -1, or 0 (clear)' });
+    }
+    try {
+      const { rows: taskRows } = await pool.query(
+        `SELECT id, status, shipped_by FROM tasks WHERE id = $1`,
+        [id]
+      );
+      if (!taskRows.length) return res.fail('task_not_found', 404);
+      const task = taskRows[0];
+      if (!VOTABLE_TASK_STATUSES.has(task.status)) {
+        return res.fail('task_not_votable', 409, { detail: 'only confirmed or shipped work can be voted on', status: task.status });
+      }
+      if (task.shipped_by == null) {
+        return res.fail('no_shipping_builder', 409, { detail: 'task has no shipped_by to credit' });
+      }
+      if (Number(task.shipped_by) === Number(req.builder.id)) {
+        return res.fail('self_vote_forbidden', 403, { detail: 'you cannot vote on your own work' });
+      }
+      // A vote already folded into karma is frozen. The freeze-check and the
+      // write are done in ONE statement so the weekly tally can't commit
+      // between a separate check and write (no TOCTOU): the conditional
+      // ON CONFLICT … WHERE tallied_at IS NULL only mutates an untallied row,
+      // and RETURNING tells us whether it took. Clearing keeps the same
+      // tallied_at IS NULL guard. (recorded_at is left untouched on change so
+      // the 7-day lag clock isn't reset.)
+      if (vote === 0) {
+        const del = await pool.query(
+          `DELETE FROM peer_votes WHERE voter_builder_id = $1 AND target_task_id = $2 AND tallied_at IS NULL RETURNING id`,
+          [req.builder.id, id]
+        );
+        // A 0-row delete is ambiguous: either there was no vote (harmless
+        // no-op) or the vote is frozen (tallied). Disambiguate so we don't tell
+        // the client "cleared" when a tallied vote actually survived — same
+        // freeze semantics as the cast path below.
+        if (del.rowCount === 0) {
+          const ex = await pool.query(
+            `SELECT 1 FROM peer_votes WHERE voter_builder_id = $1 AND target_task_id = $2`,
+            [req.builder.id, id]
+          );
+          if (ex.rowCount > 0) {
+            return res.fail('vote_already_counted', 409, { detail: 'this vote was folded into karma and can no longer be changed' });
+          }
+        }
+      } else {
+        const up = await pool.query(
+          `INSERT INTO peer_votes (voter_builder_id, target_task_id, vote)
+           VALUES ($1, $2, $3)
+           ON CONFLICT (voter_builder_id, target_task_id)
+           DO UPDATE SET vote = EXCLUDED.vote
+             WHERE peer_votes.tallied_at IS NULL
+           RETURNING id`,
+          [req.builder.id, id, vote]
+        );
+        // rowCount 0 ⟺ the conflicting row was already tallied (the WHERE
+        // filtered the update and the insert was a no-op on conflict).
+        if (up.rowCount === 0) {
+          return res.fail('vote_already_counted', 409, { detail: 'this vote was folded into karma and can no longer be changed' });
+        }
+      }
+      const { net, total } = await peerVoteNet(id);
+      res.json({ ok: true, task_id: id, my_vote: vote === 0 ? null : vote, net_votes: net, total_votes: total });
+    } catch (err) {
+      console.error('[gds] POST /tasks/:id/vote', err);
+      res.fail('vote_failed', 500);
+    }
+  });
+
+  // GDS-V3 task V3.R18 (#209). Subagent grader credits gate.
+  //
+  // ship.js (or any caller) spawns an Opus subagent against the diff + task
+  // description, then POSTs the subagent's JSON to this endpoint. The
+  // endpoint validates+scores the JSON, writes the task_grades row, and —
+  // if both functional_fidelity and code_quality clear threshold — promotes
+  // the task from completed→confirmed and awards credits.
+  //
+  // Request body:
+  //   {
+  //     subagent_output: <object or string — the subagent's JSON>,
+  //     signals?: <object — optional run metadata: model, run_ms, etc.>
+  //   }
+  //
+  // Failure modes (none of which throw — all return a graded row + 200):
+  //   - malformed subagent JSON         → passed=false, schema/parse_error in signals
+  //   - functional_fidelity < threshold → passed=false
+  //   - code_quality < threshold        → passed=false
+  //   - confidence < low-confidence cap → passed=false
+  // Any of these leaves the task at `completed`; builder can manual-confirm
+  // via POST /tasks/:id/confirm if they think the grade was wrong.
+  // rank: any-builder — grader writes a row + auto-promotes only if grade clears
+  // threshold; the grader subagent is the objectivity guarantee. Supervisor hot
+  // path (preserved per CRITICAL §4 — no requireRank).
+  router.post('/tasks/:id/grade', auth.requireBuilder, async (req, res) => {
+    // Permissive on subagent_output type — the grader handles both object AND
+    // JSON-string forms (see tests/grader.mjs "accepts JSON-string input").
+    // Only enforce presence + light shape on signals (extras pass through).
+    if (validateOrRespond(req, res, {
+      // subagent_output is an object OR a JSON string — the grader handles both
+      // (tests/grader.mjs); declared untyped so strict-mode accepts it (its deep
+      // shape is validated by the grader, and its presence by the guard below).
+      subagent_output: {},
+      signals: { type: 'object' },
+      // touches[] cleanup [3/8] (task 878): ship.js sends the real committed
+      // changed-files so the shipper badges key off the diff, not touches[].
+      committed_files: { type: 'array', maxItems: 5000, itemsType: 'string' },
+      diff_hash: { type: 'string', maxLength: 128 },
+    })) return;
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+
+    // SECURITY (#871): only the claim holder (or an Archon for --regrade) may
+    // grade — a builder must not be able to grade work they never claimed.
+    if (!(await gateTaskOwnership(req, res, id))) return;
+
+    const { subagent_output: subagentOutput, signals, committed_files: committedFiles, diff_hash: diffHash } = req.body || {};
+    if (subagentOutput == null) {
+      return res.fail('subagent_output_required', 400);
+    }
+
+    // grading carved to modules/grading/ (BV1.R73 / ADR 0091 §4): resolve the
+    // `grade` kernel PORT. resolveOptional (not resolve) so a grading-disabled
+    // instance returns a clean 503 rather than a thrown required-port error;
+    // on OTB grading is default-on, so this is byte-identical to the old import.
+    const grading = seams.resolveOptional('grade');
+    if (!grading) {
+      return res.fail('grading_unavailable', { status: 503, message: 'grading is disabled on this instance' });
+    }
+    const clientGrade = grading.validateAndScore(subagentOutput, signals || {});
+
+    // SR-9 / SR-18 (task 992): server-authoritative hardening. validateAndScore
+    // above computes `passed` from the CLIENT's submitted scores — the real
+    // adversarial panel + the deterministic pre-passes run client-side in
+    // ship.js and the server never re-runs them, so a builder could POST a
+    // forged {ff:10,cq:10,issues:[]} to self-pass. serverSideGuards re-runs the
+    // two DETERMINISTIC pre-passes here (route-rank against the server's own
+    // route files; permission-path against the caller's LIVE, authoritative
+    // rank — req.builder.rank, read fresh from the DB per request), rejects an
+    // implausible empty-issues PASS on a non-trivial diff, and neutralizes an
+    // obviously-forged net-negative credit signal (SR-18). It is DOWNGRADE-ONLY:
+    // it can flip a client PASS to a hard FAIL or manual-confirm, but never
+    // upgrades a fail and never relaxes the existing gate — so a legitimate
+    // honest grade (and the Archon / GRADER_BYPASS confirm path, which lands via
+    // /tasks/:id/confirm, NOT this route) is unaffected.
+    const gradeResult = grading.serverSideGuards(clientGrade, {
+      committedFiles: Array.isArray(committedFiles) ? committedFiles : null,
+      builderRank: req.builder && req.builder.rank, // SERVER-KNOWN authoritative rank
+      diffStats: (signals && signals.diff_stats) || null,
+    });
+
+    try {
+      const result = await db.applyGrade({
+        taskId: id,
+        builderId: req.builder.id,
+        gradeResult,
+        committedFiles: Array.isArray(committedFiles) ? committedFiles : null,
+        diffHash: typeof diffHash === 'string' && diffHash.length > 0 ? diffHash : null,
+      });
+      res.json({ ok: true, ...result, just_unlocked: result.justUnlocked ?? [] });
+    } catch (err) {
+      if (err.code === 'TASK_NOT_FOUND') return res.fail('task_not_found', 404);
+      if (err.code === 'TASK_NOT_GRADABLE') {
+        return res.fail('task_not_gradable', 409, { current_status: err.current_status });
+      }
+      console.error('[gds] POST /tasks/:id/grade', err);
+      res.fail('grade_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /tasks/:id/override-request — V3.R74 (#293). The rare path: a builder
+  // whose ship failed the subagent grader believes the grader was wrong and
+  // asks an Archon to flip the task to confirmed anyway. Audit-logged via the
+  // global write-audit middleware. Open requests surface in the Archon queue.
+  // rank: any-builder — opens a request; the decision still rests with Archon.
+  router.post('/tasks/:id/override-request', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      rationale: { required: true, type: 'string', minLength: 20, maxLength: 4000 },
+    })) return;
+    // SECURITY (SR-16 / #996 — mirrors the #871 gate on /grade, /confirm, /ship):
+    // only the task's most-recent claim holder (or an Archon) may file an
+    // override-request. Without this, a SECOND builder could open a request on
+    // another builder's `completed` task; on Archon approval that historically
+    // routed the credit + ship attribution toward the requester, so the gate is
+    // the front-line defence against cross-builder credit/attribution theft (the
+    // decideOverrideRequest attribution fix from #538 is the second layer). An
+    // Archon always passes; a never-claimed task falls back to ALLOW so a legit
+    // edge case is never wedged.
+    if (!(await gateTaskOwnership(req, res, id))) return;
+    try {
+      const row = await db.createOverrideRequest({
+        taskId: id,
+        requesterId: req.builder.id,
+        rationale: req.body.rationale.trim(),
+      });
+      res.status(201).json({ ok: true, request: row });
+    } catch (err) {
+      if (err.code === 'TASK_NOT_FOUND') return res.fail('task_not_found', 404);
+      if (err.code === 'TASK_NOT_COMPLETED') {
+        return res.fail('task_not_completed', 409, { current_status: err.currentStatus });
+      }
+      if (err.code === 'OPEN_REQUEST_EXISTS') {
+        return res.fail('open_request_exists', 409);
+      }
+      console.error('[gds] POST /tasks/:id/override-request', err);
+      res.fail('override_request_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // ==========================================================================
+  // Server-mediated branch publish (ADR 0055 / task 1025)
+  // --------------------------------------------------------------------------
+  // A builder on a cloud dev box has NO GitHub push credential (#919/ADR 0053
+  // box-scope + credential-less origin), so in `ci` deploy mode ship.js cannot
+  // `git push` + `gh pr create`. Instead the box uploads its branch as a THIN
+  // git bundle here; the server pushes it + opens the PR + enables auto-merge
+  // using its own push credential — a GitHub App installation token (preferred,
+  // task 1028) or the GITHUB_PUSH_TOKEN PAT fallback; single repo, Contents:write
+  // + PR:write + Actions:read — it CANNOT push to branch-protected main nor bypass
+  // required checks. The box holds NO github credential, so the #919 model is
+  // preserved.
+  //
+  // AUTH: requireBuilder + gateTaskOwnership, deliberately NOT allowBoxScope — a
+  // box-scoped session is 403'd here (it must `/builder-reauth` to a real cli
+  // session first). The grade already ran client-side against this exact HEAD
+  // (ship.js grades BEFORE this call), and the bundle-tip == claimed head_sha
+  // check below binds the pushed code to that graded sha.
+  const publishUpload = express.json({ limit: PUBLISH_BODY_LIMIT });
+  router.post('/tasks/:id/publish-branch', auth.requireBuilder, publishUpload, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      branch: { required: true, type: 'string', maxLength: 200, minLength: 1 },
+      head_sha: { required: true, type: 'string', maxLength: 64, minLength: 7 },
+      bundle_b64: { required: true, type: 'string', maxLength: PUBLISH_BUNDLE_B64_MAX },
+      value_summary: { type: 'string', maxLength: LIMITS.VALUE_SUMMARY },
+    })) return;
+    // SECURITY (#871 gate, same as /grade /confirm /ship): only the claim holder
+    // (or an Archon) may publish this task's branch.
+    if (!(await gateTaskOwnership(req, res, id))) return;
+    if (!githubPush.isConfigured()) {
+      return res.fail('push_unconfigured', { status: 503, message: 'Server-mediated push is not configured (no GitHub App nor GITHUB_PUSH_TOKEN on the server). ' +
+          'Ask the operator to provision it; meanwhile ship from a machine with its own git push credentials.' });
+    }
+    const { branch, head_sha: headSha, value_summary: valueSummary } = req.body;
+    if (!githubPush.isSafeBranch(branch)) return res.fail('bad_branch', 400);
+    if (!/^[0-9a-f]{7,64}$/.test(headSha)) return res.fail('bad_head_sha', 400);
+
+    // Decode + byte-bound the bundle. The JSON `limit` bounds the ENCODED payload;
+    // base64 inflates ~33%, so cap the DECODED bytes too (SR-17 disk-fill posture).
+    let bundleBuf;
+    try {
+      bundleBuf = Buffer.from(req.body.bundle_b64, 'base64');
+    } catch (_) {
+      return res.fail('bad_bundle_encoding', 400);
+    }
+    if (!bundleBuf.length) return res.fail('empty_bundle', 400);
+    if (bundleBuf.length > PUBLISH_BUNDLE_MAX_BYTES) {
+      return res.fail('bundle_too_large', 413, { max_bytes: PUBLISH_BUNDLE_MAX_BYTES });
+    }
+
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-publish-in-'));
+    const bundlePath = path.join(tmpDir, 'branch.bundle');
+    try {
+      fs.writeFileSync(bundlePath, bundleBuf);
+      const { head_sha: pushedSha } = await githubPush.pushBundle({ bundlePath, branch, headSha });
+      const title = `task ${id}: ${deHashRefs(valueSummary) || branch}`.slice(0, 240);
+      const body =
+        `Auto-opened by GDS server-mediated publish (ADR 0055) for task ${id}.\n\n` +
+        `${deHashRefs(valueSummary) || '(no value summary)'}\n\n` +
+        `Merging triggers .github/workflows/deploy-prod.yml -> ${branding().domains.publicOrigin}. ` +
+        `Auto-merge is enabled — GitHub lands it once the required checks pass.`;
+      const pr = await githubPush.openOrFindPullRequest({ branch, title, body });
+      const autoMerge = await githubPush.enableAutoMerge({ nodeId: pr.node_id });
+      // task 1139 (ADR 0058): attest the author's trust tier on the pushed sha so the
+      // gate-review check can auto-approve a Metic+ author's gate-surface PR with no
+      // owner click. Only the SERVER can set this (it holds req.builder's server-
+      // resolved rank + the App credential) — CI cannot forge it, and a PR-title rank
+      // lookup would be spoofable. Shared with POST /tasks/:id/attest-gate (the laptop
+      // ci-land path — task 1169). Best-effort: a failure leaves the PR un-attested,
+      // so it escalates (the safe direction).
+      await postGateAuthorTrust({ rank: req.builder.rank, sha: pushedSha, taskId: id });
+      // task 1547: persist the tip we ACTUALLY pushed so the confirmed->shipped
+      // reconcile proves THIS task's land from its own commit, not from a (reusable)
+      // branch name. Without it, a reused worktree branch can match an older task's
+      // already-merged PR and false-flip confirmed->shipped (the BV1.R04/R05 strand:
+      // branch claude/jovial-rosalind-84d6c3 had earlier been PR #386 / task 1297).
+      // Best-effort: a miss just falls the reconcile back to the PR-ref-this-task check.
+      try {
+        await db.setClaimPublishedSha({ taskId: id, builderId: req.builder.id, sha: pushedSha });
+      } catch (e) {
+        console.error('[gds] setClaimPublishedSha (non-blocking)', id, e && e.message);
+      }
+      return res.status(201).json({
+        ok: true, pr_url: pr.url, pr_number: pr.number, head_sha: pushedSha, auto_merge: autoMerge,
+      });
+    } catch (e) {
+      if (e.code === 'TIP_MISMATCH') {
+        return res.fail('tip_mismatch', { status: 400, message: `The uploaded bundle's tip (${String(e.tip || '').slice(0, 8)}) does not match the ` +
+            `claimed head_sha (${headSha.slice(0, 8)}). Commit your work and re-ship from a clean tree.` });
+      }
+      if (e.code === 'BAD_BRANCH') return res.fail('bad_branch', 400);
+      if (e.code === 'BAD_SHA') return res.fail('bad_head_sha', 400);
+      if (e.code === 'NO_REPO_INFO') return res.fail('no_repo_info', 500);
+      if (e.code === 'PUSH_UNCONFIGURED') return res.fail('push_unconfigured', 503);
+      if (e.code === 'PR_CREATE_FAILED') return res.fail('pr_create_failed', 502, { detail: e.detail });
+      // task 1547: GIT_FAILED now carries WHICH git step failed + the credential-
+      // scrubbed stderr (github-push.defaultExec). Log both so the next push outage
+      // is a one-line diagnosis, not a multi-hour opaque-`publish_failed` mystery
+      // (the BV1.R04/R05 incident: ~2h of bare GIT_FAILED with no cause). Return the
+      // step + a short scrubbed reason to the (ownership-gated) builder too.
+      console.error(
+        '[gds] POST /tasks/:id/publish-branch', e.code || e.message,
+        e.git_step ? `step=${e.git_step}` : '',
+        e.stderr ? `stderr=${e.stderr}` : ''
+      );
+      return res.fail('publish_failed', 500, { ...(e.git_step ? { step: e.git_step } : {}), ...(e.stderr ? { reason: String(e.stderr).slice(0, 200) } : {}) });
+    } finally {
+      try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) { /* best-effort */ }
+    }
+  });
+
+  // GET /tasks/:id/publish-status?branch=<branch> — poll the PR + prod-deploy
+  // state for a server-mediated publish so ship.js can confirm the land WITHOUT
+  // gh on the box. Ownership-gated like the POST. Derives state live from GitHub.
+  router.get('/tasks/:id/publish-status', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    if (!(await gateTaskOwnership(req, res, id))) return;
+    if (!githubPush.isConfigured()) return res.fail('push_unconfigured', 503);
+    const branch = req.query.branch;
+    if (!githubPush.isSafeBranch(branch)) return res.fail('bad_branch', 400);
+    try {
+      const status = await githubPush.getPublishStatus({ branch });
+      // task 1049 (B — server-side reconcile-on-read): when GitHub shows the PR
+      // MERGED and deploy-prod SUCCEEDED, finish the task right here so a
+      // confirmed-but-unshipped task never strands waiting on a human to re-poll
+      // (the #1027 retrospective: a successful publish left the task at confirmed
+      // forever). Idempotent + safe: db.shipTask is the exact flip POST /ship
+      // runs, throws TASK_NOT_CONFIRMED when the task isn't at 'confirmed'
+      // (already shipped, or never confirmed) — which we swallow. Same authority
+      // as /ship: this route is gateTaskOwnership-gated.
+      let reconciled = false;
+      let reconcile_blocked = null;
+      // task 1547: landConfirmed alone is NOT enough — getPublishStatus matches the
+      // most-recent PR for a branch NAME, and worktree branch names get reused, so a
+      // merged-but-OLDER PR can satisfy landConfirmed for a task whose own push never
+      // landed (the BV1.R04/R05 false-ship off PR #386 / task 1297). Require proof that
+      // THIS task's published tip is in main before flipping confirmed->shipped.
+      if (githubPush.landConfirmed(status)) {
+        const publishedSha = await db.getClaimPublishedSha(id);
+        const proof = await githubPush.landProvenForTask({ taskId: id, publishedSha, status });
+        if (!proof.proven) {
+          reconcile_blocked = proof.reason;
+          console.warn(`[gds] publish-status reconcile BLOCKED task ${id}: ${proof.reason}`);
+        }
+      }
+      if (githubPush.landConfirmed(status) && !reconcile_blocked) {
+        try {
+          const shipped = await db.shipTask({ taskId: id, builderId: req.builder.id });
+          reconciled = true;
+          // task 1045: the box that published can't post the Discord broadcast —
+          // it holds no webhook secret (ADR 0053 "box holds nothing"), so a box
+          // ship was silently skipping the public announcement. The server holds
+          // the secrets and just confirmed the deploy, so it fires the broadcast
+          // here — exactly ONCE, on the confirmed→shipped transition. shipTask
+          // throws TASK_NOT_CONFIRMED on a repeat poll, so this never re-posts.
+          // Best-effort: emit task.shipped; the discord module (if enabled) posts
+          // the #ship-news / #ship-feed broadcast on its listener. emitAsync
+          // isolates listener errors, so a broadcast hiccup can never turn a
+          // successful reconcile into a 502 (ADR 0083 / BV1.R47 — replaces the old
+          // direct require('../ship-broadcast') core→discord import).
+          await seams.emitAsync('task.shipped', shipped);
+        } catch (err) {
+          if (err.code !== 'TASK_NOT_CONFIRMED') throw err;
+        }
+      }
+      // task 1162: if GitHub still shows the PR open (not merged) and we didn't
+      // just ship, GitHub's auto-merge daemon may have stalled on an already-green
+      // PR (the PR #125 case: 7/7 checks green, CLEAN, never merged). NUDGE the
+      // merge server-side AND surface the real blocker, so a credential-less
+      // session reports the truth (pending/failing check, review required) instead
+      // of guessing a non-existent gate and asking the owner to click merge. This
+      // mirrors the reconcile-on-read precedent above (a GET that finishes the
+      // land); best-effort so a merge-driver miss never turns the poll into a 502.
+      let merge_driver = null;
+      if (!reconciled && !status.merged && status.pr_state === 'open') {
+        try {
+          merge_driver = await githubPush.mergeIfGreen({ branch });
+        } catch (e) {
+          console.error('[gds] publish-status merge-driver (non-blocking):', e && e.message);
+        }
+      }
+      return res.json({ ok: true, ...status, reconciled, reconcile_blocked, merge_driver });
+    } catch (e) {
+      if (e.code === 'NO_REPO_INFO') return res.fail('no_repo_info', 500);
+      console.error('[gds] GET /tasks/:id/publish-status', e.code || e.message);
+      return res.fail('status_failed', 502);
+    }
+  });
+
+  // POST /tasks/:id/attest-gate — body: { head_sha }. The LAPTOP ci-land analogue
+  // of the publish-branch attestation (task 1169). ship.js's local push path
+  // (pushVia 'local') pushes the branch + opens the PR with its OWN gh credential
+  // but CANNOT forge the trustless gate-author-trust commit status — only the server
+  // can (it holds req.builder's server-resolved rank). Without this, an ENFORCING
+  // ADR-0058 gate-review BLOCKS a Metic+ author's gate-surface PR shipped from a
+  // laptop and they can't self-approve their own PR (hit live on task 1162 / PR #131).
+  //
+  // AUTH mirrors publish-branch EXACTLY: requireBuilder + gateTaskOwnership, and
+  // deliberately NOT allowBoxScope (a box-scoped session 403s — it must reauth). The
+  // attestation power is bounded: gate-author-trust clears a NEEDS_TRUST surface for
+  // a Metic+ author only and NEVER the hard floor (which always needs an owner
+  // review), so a Metic+ vouching for their own task's head stays within their tier.
+  router.post('/tasks/:id/attest-gate', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_task_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      head_sha: { required: true, type: 'string', maxLength: 64, minLength: 7 },
+    })) return;
+    if (!(await gateTaskOwnership(req, res, id))) return;
+    const { head_sha: headSha } = req.body;
+    if (!/^[0-9a-f]{7,64}$/.test(headSha)) return res.fail('bad_head_sha', 400);
+    if (!githubPush.isConfigured()) {
+      return res.fail('push_unconfigured', { status: 503, message: 'No server push credential (GitHub App / GITHUB_PUSH_TOKEN) to post the gate attestation. ' +
+          'A gate-surface PR will need an owner review until the operator provisions it.' });
+    }
+    const { attested, reason } = await postGateAuthorTrust({ rank: req.builder.rank, sha: headSha, taskId: id });
+    return res.json({ ok: true, attested, reason });
+  });
+
+  // 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) => {
+    const status = req.query.status || 'open';
+    if (!['open', 'approved', 'denied'].includes(status)) {
+      return res.fail('bad_status', 400);
+    }
+    try {
+      const rows = await db.listOverrideRequests({ status });
+      res.json({ requests: rows });
+    } catch (err) {
+      console.error('[gds] GET /override-requests', err);
+      res.fail('list_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /override-requests/:id/decide — body: { decision: 'approve'|'deny', note? }
+  // On approve, atomically flips the task completed→confirmed and awards the
+  // credits to the original requester (NOT the Archon). On deny, only the row
+  // updates; the task stays at completed and the builder must release or
+  // re-ship after fixing whatever the grader caught.
+  // rank: archon — grader-bypass authority; same gate as POST /tasks/:id/confirm.
+  router.post('/override-requests/:id/decide', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_request_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      decision: { required: true, type: 'string' },
+      note: { type: 'string', maxLength: 4000 },
+    })) return;
+    const { decision, note } = req.body || {};
+    if (decision !== 'approve' && decision !== 'deny') {
+      return res.fail('bad_decision', { status: 400, message: "decision must be 'approve' or 'deny'" });
+    }
+    try {
+      const result = await db.decideOverrideRequest({
+        requestId: id,
+        archonId: req.builder.id,
+        decision,
+        note,
+      });
+      res.json({ ok: true, ...result });
+    } catch (err) {
+      if (err.code === 'REQUEST_NOT_OPEN') {
+        return res.fail('request_not_open', 409);
+      }
+      if (err.code === 'OVERRIDE_NO_REQUESTER') {
+        // Data-integrity guard (#538): an approved override with no requester to
+        // credit. Should never happen (NOT NULL column); refuse rather than
+        // misattribute. 409 — the request is left open for inspection.
+        return res.fail('override_no_requester', { status: 409, message: 'internal error' });
+      }
+      console.error('[gds] POST /override-requests/:id/decide', err);
+      res.fail('decide_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};
+
+// Exported for unit testing + so callers can reuse the exact detection logic.
+module.exports.detectsMigration = detectsMigration;
+module.exports.graderBypassEnabled = graderBypassEnabled;
+module.exports.MIGRATION_KEYWORD_RE = MIGRATION_KEYWORD_RE;
+// #871: exported so tests/task_ownership_gate.mjs can drive the claim-ownership
+// gate directly (with a stubbed db.getLastClaimHolder) — no server/DB needed.
+module.exports.gateTaskOwnership = gateTaskOwnership;
+// task 1053 (F): exported so the verify-attestation guard is unit-tested.
+module.exports.isVerifyTask = isVerifyTask;
+// task 1139 / 1169 (ADR 0058): exported so the pure rank-attestation decision
+// (Metic+ → gate-author-trust) is unit-tested without a server/DB/network.
+module.exports.rankAttestsGateTrust = rankAttestsGateTrust;