@bongos/core 1.19.332 → 1.19.333

package/modules/lifecycle/routes/tasks.js

@@ -41,191 +41,8 @@ const PUBLISH_BUNDLE_MAX_BYTES = 20 * 1024 * 1024; // 20 MB decoded bundle
 // 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;
-
-// task 1002648 (idea 1000642): compounds where the keyword is qualified by a
-// NON-database noun are refactor/API language, not schema work, and are blanked
-// before the keyword test. Two families surfaced in the wild: "gate/route/code
-// migration" (code-migration phrasing) and "request/PATCH/:NNN schema"
-// (API-shape phrasing — the task-1002614 false positive, which reserved
-// migration 213 for zero schema change). Bare "migration"/"schema" and every
-// DB-shaped compound ("schema migration", "DB schema") still flag.
-const NON_DB_COMPOUND_RE = new RegExp(
-  [
-    /\b(?:gate|route|code)s?[-\s]+migrations?\b/.source,
-    /\bmigrations?\s+of\s+(?:gate|route|code)s?\b/.source,
-    /\b(?:request|response|body|validation|patch|post|put|delete|json|openapi|api|error)[-\s]+schemas?\b/.source,
-    /:\d+[-\s]+schemas?\b/.source,
-  ].join('|'),
-  'gi'
-);
-
-function detectsMigration(...texts) {
-  return texts.some(
-    (t) => typeof t === 'string' && MIGRATION_KEYWORD_RE.test(t.replace(NON_DB_COMPOUND_RE, ' '))
-  );
-}
-
-// ---- peer votes (V3.R25 #245) ---------------------------------------------
-// The peer-vote SQL lives here (inline, via the route module's `pool`) rather
-// than in db.js on purpose: it's a self-contained feature, declared in this
-// task's touches[] (migrations/, this file, modules/hall-ui/), and keeping it
-// out of the large shared db.js avoids a parallel-safety conflict on that file.
-// Same deliberate-locality call as the MIGRATION_KEYWORD_RE mirror above.
-
-// VOTABLE_TASK_STATUSES — a task is votable once it's verified work the project
-// keeps (confirmed = past the grader, not yet paid; or shipped = deployed + paid);
-// backlog/ready/completed are not. Imported above from ../task-classifier (D1).
-
-// #853 (ADR 0041): temporary, default-OFF global grader bypass. When the env
-// GRADER_BYPASS_ENABLED is exactly '1', the subagent quality grader is treated
-// as unavailable and any builder may land work via /tasks/:id/confirm (normally
-// archon-only). Read live on each request — flipping the env (+ redeploy) is the
-// on/off switch; no caching, so turning it off re-arms the trust boundary at
-// once. Exported so /me can surface the same flag to ship.js.
-function graderBypassEnabled() {
-  return process.env.GRADER_BYPASS_ENABLED === '1';
-}
-
-// SECURITY (#871): claim-ownership gate for the lifecycle-advancing routes
-// (/grade, /confirm, /ship). These are requireBuilder-only (the grade is meant
-// to be an objective subagent output; the supervisor hot path must not need an
-// Archon), which — combined with applyGrade/confirmTask crediting work — let any
-// authenticated builder act on ANOTHER builder's task:
-//   * /grade  (requireBuilder, no rank gate): a builder could POST a fabricated
-//     passing grade on someone else's `completed` task. Pre-#871 applyGrade then
-//     credited the CALLER → cross-builder credit theft + ship-attribution hijack
-//     + a full bypass of the quality grader.
-//   * /confirm: archon-only normally, but the GRADER_BYPASS killswitch (ON
-//     during the grader outage) relaxes it to ANY builder, so anyone could
-//     force-confirm anyone's `completed` work past the (absent) grader.
-//   * /ship: any-builder supervisor hot path (so /merge-mode can land the queue).
-//
-// Allow when: the caller is an Archon (full authority / --regrade); OR — for
-// /ship only (allowSupervisor) — the caller is Metic, the trusted rank that runs
-// /merge-mode to sweep the confirmed queue across builders; OR the caller is the
-// task's most-recent claim holder (the builder who did the work).
-//
-// A NEVER-CLAIMED task (degenerate state, e.g. status set directly via SQL) is
-// NOT an open door: the Archon and supervisor early-returns above already cover
-// the legitimate actors who land such a task. By the time we read the claim
-// holder, the caller is necessarily a non-Archon (and not a supervisor Metic) —
-// so a missing claim must FAIL CLOSED with the same 403, not silently ALLOW.
-// (L2 residual, red-team 2026-06-12: combined with the GRADER_BYPASS relaxation
-// on /confirm, the old "no claim → ALLOW" let any builder confirm a claimless
-// `completed` task and have the credit fall to themselves.) An Archon (or the
-// /merge-mode supervisor) can still land a claimless task — they pass above.
-// Returns true if allowed; otherwise writes a 403 and returns false.
-async function gateTaskOwnership(req, res, taskId, { allowSupervisor = false } = {}) {
-  const rank = req.builder && req.builder.rank;
-  if (rank === 'archon') return true;
-  if (allowSupervisor && rank === 'metic') return true;
-  const holder = await db.getLastClaimHolder(taskId);
-  if (holder && String(holder.builder_id) === String(req.builder.id)) return true;
-  // task 1002614 (map N-2): a mistyped id used to earn the same not_your_task
-  // 403 as someone else's work — a misattribution that sent builders debugging
-  // ownership. An ABSENT task is the clean 404 an Archon already saw (they pass
-  // above and hit the handler's own lookup). A never-claimed task that EXISTS
-  // still fails closed with the 403 below (the L2 credit-theft block).
-  if (!holder && !(await db.getTask(taskId))) {
-    res.fail('task_not_found', 404);
-    return false;
-  }
-  res.fail('not_your_task', { status: 403, message: 'Only the task\'s claim holder (or an Archon) may grade/confirm/ship it.' });
-  return false;
-}
-
-// task 1053 (F): a verification task — one whose deliverable IS a verification
-// (e.g. a hardware-verify run). Confirming one requires an explicit attestation
-// that the verify actually passed, so a hardware-verify can't be confirmed on a
-// passing code-grade before the verify was even performed (the #1027 trap).
-// Keyed on the explicit kind (set by the planner), NOT a title regex — a task
-// ABOUT verify work would false-positive on text. Pure + exported for tests.
-function isVerifyTask(task) {
-  return !!task && task.kind === 'verify';
-}
-
-// task 1139 / 1169 (ADR 0058): the trustless server rank-attestation behind the
-// gate-review CI check. Only the SERVER can set it — it holds the authenticated
-// builder's server-resolved rank AND the App/PAT credential — so CI can trust it
-// where a PR-author-controlled signal (a PR title) would be spoofable. A Metic+
-// author's gate-author-trust=success clears a NEEDS_TRUST gate surface with no
-// owner click; below Metic gets no attestation (the gate escalates → owner review).
-//
-// rankAttestsGateTrust is the PURE rank decision (no network) — exported for tests.
-function rankAttestsGateTrust(rank) {
-  const { tierOf, MIN_TIER } = api.permissionPathCheck;
-  const tier = tierOf(rank);
-  return tier != null && tier >= MIN_TIER;
-}
-
-// postGateAuthorTrust — set (or skip) the gate-author-trust commit status for an
-// author's rank on a pushed SHA. Shared by the server-mediated publish path
-// (POST /tasks/:id/publish-branch) and the laptop ci-land path's attest endpoint
-// (POST /tasks/:id/attest-gate). Best-effort + never throws: a failed/skipped
-// status post leaves the PR un-attested, which ESCALATES (the safe direction — no
-// rank bypass without a real server signal). Returns { attested, reason } for UX.
-async function postGateAuthorTrust({ rank, sha, taskId }) {
-  if (!rankAttestsGateTrust(rank)) return { attested: false, reason: 'rank_below_metic' };
-  try {
-    const ok = await githubPush.setCommitStatus({
-      sha,
-      state: 'success',
-      context: 'gate-author-trust',
-      description: `Metic+ author (${rank}) — task ${taskId}`,
-    });
-    return { attested: !!ok, reason: ok ? null : 'status_post_failed' };
-  } catch (_) {
-    return { attested: false, reason: 'status_post_failed' };
-  }
-}
-
-async function peerVoteNet(taskId) {
-  const { rows } = await pool.query(
-    `SELECT COALESCE(SUM(vote), 0)::int AS net, COUNT(*)::int AS total
-       FROM peer_votes WHERE target_task_id = $1`,
-    [taskId]
-  );
-  return { net: rows[0].net, total: rows[0].total };
-}
-
-// #514: bad_kind responses carried a `valid` array but no human-readable line,
-// so a caller (or CLI that only prints .message) couldn't tell at a glance what
-// went wrong — the #506 session burned a turn guessing kind=chore. Add a
-// .message that spells out the allowed values while keeping the valid[] array.
-function badKind(res) {
-  const valid = Array.from(VALID_KINDS);
-  return res.fail('bad_kind', { status: 400, message: `kind must be one of: ${valid.join(', ')}`, details: { valid } });
-}
-
+const { MIGRATION_KEYWORD_RE, VALID_FITS, badKind, deHashRefs, detectsMigration, gateTaskOwnership, graderBypassEnabled, isVerifyTask, peerVoteNet, postGateAuthorTrust, rankAttestsGateTrust } = require('./task-route-helpers.js');
+const registerTaskWriteRoutes = require('./task-write-routes.js'); // task 1003206 — POST /tasks + PATCH /tasks/:id
 module.exports = function buildTasksRouter() {
   const router = express.Router();
 
@@ -549,517 +366,7 @@ module.exports = function buildTasksRouter() {
     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.requirePermission('task.create'), async (req, res) => {
-    if (validateOrRespond(req, res, {
-      version_id: { required: true, type: 'string', maxLength: 64 },
-      title: { required: true, type: 'string', maxLength: LIMITS.TITLE, minLength: 1 },
-      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 }, // AGENT-minutes — see est-advisory.js (task 1003148)
-      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).
-      // task 2165 — the task landed under a goal but the caller linked no
-      // criterion → SUGGEST the most likely done-when criterion(s) for the author
-      // to confirm (they link via POST /tasks/:id/criteria). Advisory only, never
-      // auto-linked ("suggest, human picks"). Best-effort: a suggestion hiccup
-      // must not fail an otherwise-successful create. The general catch-all goal
-      // usually has no criteria, so this is naturally empty there.
-      let suggested_criteria = [];
-      if (criteria.length === 0 && task.goal_id != null) {
-        try {
-          const goalCriteria = await db.listCriteriaForGoal(task.goal_id);
-          suggested_criteria = suggestCriteria(
-            goalCriteria,
-            { title: body.title, description: body.description },
-            { limit: 3 }
-          );
-        } catch (e) {
-          console.error('[gds] POST /tasks suggest-criteria (non-blocking)', e && e.message);
-        }
-      }
-      // task 1002539 — the orphan-task advisory (the /goal-create auto-pickup
-      // hook). Nothing 4xxs when a task has no goal, so surface it here instead of
-      // blocking. Non-blocking by construction — see goal-advisory.js.
-      const goal_advisory = await buildGoalAdvisory({ db, versionId: body.version_id, task });
-      res.status(201).json({
-        task,
-        credits_reward: task.credits_reward,
-        needs_migration: needsMigration,
-        criteria,
-        suggested_criteria,
-        goal_advisory, est_advisory: await require('../est-advisory').buildEstAdvisory({ db, task }), // task 1003148
-      });
-    } 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.requirePermission('task.edit'), 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 },
-      needs_migration: { type: 'boolean' },              // task 1002648 — correct the create-time heuristic's flag (the claim-time allocator keys off it)
-      // task 1002647 (map s4.3): the task body is a load-bearing builder prompt
-      // and was settable only at create — no route edited it at any rank. Now
-      // editable under this route's task.edit permission. minLength 1: a body
-      // can be rewritten, never blanked (and null is refused by the type check).
-      // Each edit's new body lands in audit_log via the write-audit middleware.
-      description: { type: 'string', minLength: 1, maxLength: LIMITS.DESCRIPTION },
-      // task 1002614 (map D-18): DECLARED so strict-mode admits the request far
-      // enough to reach the deliberate status_not_patchable hint below (#514) —
-      // the hint had been unreachable dead code behind unknown_field since the
-      // R11 strict-validation sweep landed after it.
-      status: {},
-    })) 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 hasNeedsMigration = Object.prototype.hasOwnProperty.call(body, 'needs_migration');
-    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');
-    const hasDescription = Object.prototype.hasOwnProperty.call(body, 'description');
-    // #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 && !hasNeedsMigration && !hasRequiresRank && !hasModuleKey && !hasGoalId && !hasDescription) {
-      return res.fail('no_supported_fields', { status: 400, message: 'PATCH /tasks/:id supports parent_task_id, kind, discipline, description, parallel_safe, security_sensitive, automation_tag, needs_migration, requires_rank, module_key, goal_id, and newcomer_friendly (alias: xenos_claimable). ' + STATUS_HINT });
-    }
-    // ---- task 1002609 (G-22): settle EVERY gate and validation before the ----
-    // ---- FIRST write. The previous shape validated-and-wrote per field in ----
-    // sequence, so a body mixing a valid early field with a refused later one
-    // committed the early write and then 403/400'd — state changed on a request
-    // the caller was told was refused (a Metic sending { parallel_safe,
-    // security_sensitive } had parallel_safe committed before rank_forbidden).
-    // Authorization, type/enum checks, and the goal existence/version reads all
-    // run here; writes begin only after the last validation `return`.
-    // (Documented residual: parent_task_id validates inside hierarchy.attachParent
-    // at the end — its checks are atomic with its OWN write, but a refusal there
-    // still lands after the field writes below. No authorization gate is
-    // involved in that path; the handler's only rank gate is hoisted here.)
-    if (hasParallelSafe && 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' });
-    }
-    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' });
-      }
-    }
-    const VALID_AUTOMATION_TAGS = new Set(['overnight-safe', 'live-only', 'needs-input']);
-    if (hasAutomationTag) {
-      const tag = body.automation_tag;
-      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) } });
-      }
-    }
-    if (hasModuleKey) {
-      // BV1.R53 (task 1422): assign or clear the module affinity label. null clears.
-      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 null to clear. Valid keys: ${moduleKeys().join(', ')}.`, details: { valid: moduleKeys() } });
-      }
-    }
-    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.` });
-        }
-      } 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.
-      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 } });
-      }
-    }
-    if (hasKind && !VALID_KINDS.has(body.kind)) {
-      return badKind(res);
-    }
-    if (hasDiscipline && !VALID_DISCIPLINES.has(body.discipline)) {
-      return res.fail('bad_discipline', 400, { valid: Array.from(VALID_DISCIPLINES) });
-    }
-    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` });
-      }
-    }
-    // ---- all gates passed: apply the writes. Order preserved from the old ----
-    // shape — requires_rank still runs AFTER security_sensitive so a
-    // same-request flag flip is already reflected in the derived floor.
-    let updated = null;
-    if (hasParallelSafe) {
-      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) {
-      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) {
-      try {
-        updated = await db.updateTaskAutomationTag(id, body.automation_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 (hasNeedsMigration) {
-      try {
-        updated = await db.updateTaskNeedsMigration(id, body.needs_migration);
-        if (!updated) return res.fail('task_not_found', 404);
-      } catch (err) {
-        console.error('[gds] PATCH /tasks/:id needs_migration', err);
-        return res.fail('patch_failed', { status: 500, message: 'internal error' });
-      }
-    }
-    if (hasModuleKey) {
-      try {
-        updated = await db.updateTaskModuleKey(id, body.module_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 (hasDescription) {
-      try {
-        updated = await db.updateTaskDescription(id, body.description);
-        if (!updated) return res.fail('task_not_found', 404);
-      } catch (err) {
-        console.error('[gds] PATCH /tasks/:id description', err);
-        return res.fail('patch_failed', { status: 500, message: 'internal error' });
-      }
-    }
-    if (hasGoalId) {
-      try {
-        updated = await db.updateTaskGoal(id, body.goal_id);
-        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) {
-      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) {
-      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) {
-      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) {
-      const incoming = hasNewcomerFriendly ? body.newcomer_friendly : body.xenos_claimable;
-      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' });
-    }
-  });
+  registerTaskWriteRoutes(router); // POST /tasks + PATCH /tasks/:id (task 1003206)
 
   // rank: metic+archon — backlog→ready promotion; scope mutation; ADR 0090 (was archon).
   //