@bongos/core 1.19.332 → 1.19.333

package/modules/lifecycle/routes/task-write-routes.js

@@ -0,0 +1,542 @@
+// modules/lifecycle/routes/task-write-routes.js — POST /tasks and
+// PATCH /tasks/:id: the two heavyweight write handlers (creation with its goal
+// routing + classification, and the field-by-field edit gate).
+//
+// Carved out of modules/lifecycle/routes/tasks.js by task 1003206 (goal 1000079,
+// the R03 de-monolith plan) — together they were 510 of that router's lines.
+// A STRUCTURAL move: the handlers are unchanged and still register on the SAME
+// router instance, so the mounted paths, their order and their middleware are
+// exactly as before. tasks.js calls this during buildTasksRouter().
+//
+// Registrar shape (not a sub-router): Express matches in registration order and
+// '/tasks/:id' would shadow sibling literal paths if these were mounted
+// separately. Handing the same router to a register function keeps the order the
+// single file had.
+
+'use strict';
+
+const path = require('node:path');
+const api = require('../../../src/module-api');
+const auth = api;
+const db = require('../db');
+const hierarchy = require('../hierarchy');
+const { suggestCriteria } = require('../criterion-suggest');
+const { buildGoalAdvisory } = require('../goal-advisory');
+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;
+const { badKind, detectsMigration } = require('./task-route-helpers.js');
+
+module.exports = function registerTaskWriteRoutes(router) {
+  // 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' });
+    }
+  });
+};