@bongos/core 1.17.0

package/modules/lifecycle/routes/goals.js

@@ -0,0 +1,1419 @@
+// src/bongos/routes/goals.js — the Goal tier's HTTP surface (ADR 0086 §3, BV1.R57).
+//
+// A goal is a shared, module-scoped workspace (the `goals` + `goal_members`
+// tables from R56). This router lets a Metic+ create one, lets builders view and
+// join/leave them, and adds a `?goal_id=` filter to GET /tasks (in tasks.js).
+//
+// SCOPE WALL (ADR 0086 §3/§4). `scope_modules` is the wall, set at create time by
+// a trusted rank and never self-granted:
+//   - POST /goals is metic+archon, but ARCHON-ONLY when scope_modules names a
+//     `protected` module (module-scope-map.js, R54) — the protected core.
+//   - Joining a protected-scope goal is Archon-mediated: a non-Archon cannot
+//     self-join; an Archon admits them via POST /goals/:id/members, and only a
+//     Metic+ may be admitted. Per ADR 0086's Deferred section, a sub-Metic builder
+//     working INSIDE a protected-scope goal is held for the Phase-5 security-
+//     reviewed ADR — until then protected-scope goals require a Metic+ holder, and
+//     the self-service "request → approve" queue is not built here (it co-evolves
+//     with that ADR). Normal (non-protected) goals are open-join.
+//
+// The bounded task-authoring gate (POST /goals/:id/tasks) is R60, not here; this
+// router references no task-authoring grant. The grader/route-rank fitness check
+// pins these routes' ranks in route-rank-check.EXPECTED_RANKS.
+
+const express = require('express');
+// 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');
+const { classifyTaskKind, VALID_KINDS, VALID_DISCIPLINES, TASK_FIELD_BOUNDS } = require('../task-classifier');
+const { validateOrRespond, parseId, LIMITS } = api;
+const { isModuleKey, scopeIncludesProtected, moduleKeys } = api.moduleScopeMap;
+// goalScopeCheck — the PURE scope wall (BV1.R59 / ADR 0086 §3), reached through
+// the published doorway (a module never requires the core file directly — the
+// module-boundary fitness check would red the build). The create gate below calls
+// its check() VERBATIM; the two walls (scope-subset + protected-path) live there,
+// never re-implemented here.
+const goalScopeCheck = api.goalScopeCheck;
+// The pure conflict detector (task 1736) — a module sibling, like ../db.
+const goalConflicts = require('../goal-conflicts');
+
+const VALID_GOAL_STATUSES = ['open', 'achieved', 'archived'];
+const VALID_MEMBER_ROLES = ['lead', 'member'];
+const METIC_PLUS = ['metic', 'archon'];
+const RESOLVE_ACTIONS = ['sequence', 'flag_release', 'rescope'];
+// Private goals (task 1952 / ADR 0112): the visibility values, and the resolve
+// actions for each side of the membership-request queue.
+const VALID_VISIBILITIES = ['public', 'private'];
+const INVITE_RESPONSE_ACTIONS = ['accept', 'decline'];   // the invitee resolves their own invite
+const JOIN_REQUEST_RESPONSE_ACTIONS = ['approve', 'deny']; // an owner/manager/Archon resolves a request
+
+// Shared gate for the goal lifecycle + scope mutations (BV1.R64): the caller must
+// be a member of the goal, or an Archon (who may act on any goal). Returns true to
+// proceed; a false result means "not a member" → the route should 403. This is the
+// membership half of the wall; the protected-module rank check is enforced per-route
+// (scope is never self-granted).
+async function isMemberOrArchon(builder, goalId) {
+  if (builder.rank === 'archon') return true;
+  return db.isGoalMember({ goalId, builderId: builder.id });
+}
+
+// authorizeGoalTaskCreate — the ORDERED, FAIL-CLOSED authorization decision for
+// POST /goals/:id/tasks (BV1.R60 / ADR 0086 §3): the single point that lets a
+// lower-rank builder author their OWN work safely. PURE + exported (the
+// shouldRefuseSessionClaim precedent in claims.js) so every rejection is pinned
+// by a DB-free unit test AND reused by the BV1.R61 abuse matrix — no live route
+// or DB needed.
+//
+// The route fetches goal / version / membership, then calls this; it rejects on
+// the FIRST failure (fail-closed — a missing/ambiguous input denies):
+//   goal_not_found → goal_not_open → not_a_member → version_not_found →
+//   version_closed → (scope-subset + protected-path, via goalScopeCheck.check).
+// The scope+protected wall is goal-scope-check.check() VERBATIM (R59) — itself
+// ordered + fail-closed (empty-scope → empty-touches → unknown-scope →
+// scope-subset → protected-path) — never re-implemented here. `isMember` is the
+// resolved "member OR Archon" boolean the route computes (isMemberOrArchon).
+//
+// This is the CREATE-time filter: it sees only DECLARED touches[] (advisory — git
+// merge is the real collision detector, ADR 0049), so it is deliberately the FIRST
+// filter, NOT the last. The ship-time gates stay authoritative on the REAL diff
+// (grader permission/route-rank pre-passes + serverSideGuards, gate-review
+// ESCALATE floor, post-push main-audit — ADR 0086 §7). Returns { ok:true } or
+// { ok:false, status, body } (the exact HTTP status + JSON the route sends).
+function authorizeGoalTaskCreate({ goal, version, isMember, builderRank, touches }) {
+  if (!goal) {
+    return { ok: false, status: 404, body: { error: 'goal_not_found' } };
+  }
+  if (goal.status !== 'open') {
+    return { ok: false, status: 409, body: {
+      error: 'goal_not_open', status: goal.status,
+      message: 'Tasks can only be authored under an open goal.',
+    } };
+  }
+  if (!isMember) {
+    return { ok: false, status: 403, body: {
+      error: 'not_a_member',
+      message: 'Join the goal (or be an Archon) to author tasks within it.',
+    } };
+  }
+  if (!version) {
+    return { ok: false, status: 404, body: {
+      error: 'version_not_found',
+      message: `The goal's version '${goal.version_id}' no longer exists.`,
+    } };
+  }
+  if (version.status === 'shipped') {
+    return { ok: false, status: 409, body: {
+      error: 'version_closed',
+      message: `Version '${goal.version_id}' has shipped — it is closed history and cannot take new tasks.`,
+    } };
+  }
+  // The wall — scope-subset + protected-path in one pure call (R59). It bounds
+  // EVERYONE by the goal's modules (scope-subset), and additionally blocks a
+  // sub-Metic member from authoring into the protected core (protected-path),
+  // reusing the SINGLE protected roster (permission-path-check) — no drift.
+  const gate = goalScopeCheck.check(goal.scope_modules, touches, builderRank);
+  if (!gate.ok) {
+    return { ok: false, status: 403, body: {
+      error: gate.code, reason: gate.reason, details: gate.details,
+    } };
+  }
+  return { ok: true };
+}
+
+// The goal AUTHORITY MODEL (task 1735). Two layers, deliberately different kinds:
+//   - OWNER — goals.created_by, the fixed authority. Not a role row: it is set at
+//     create time (the creator) and moves only via the explicit transfer route.
+//     The owner holds every goal power.
+//   - MANAGER — the goal_members.role 'lead' value (the hall renders it
+//     "manager"). Owner-equivalent EXCEPT: a manager cannot DEMOTE a fellow
+//     manager (owner-only), and cannot transfer ownership.
+// A goal with created_by NULL (the migration-160 system defaults) has no owner;
+// Archons act as one — the archon arm of both gates below.
+function isGoalOwner(goal, builderId) {
+  return goal.created_by != null && String(goal.created_by) === String(builderId);
+}
+
+// authorizeMemberRoleChange — the ORDERED, FAIL-CLOSED authorization decision for
+// PATCH /goals/:id/members/:builderId (task 1735). Today the only role-assignment
+// path is the Archon admission route; this gate lets the goal's own authority
+// manage roles without an Archon in the loop:
+//   - the owner, a manager, or an Archon may promote member→lead(manager);
+//   - ONLY the owner (or an Archon) may demote lead(manager)→member;
+//   - the OWNER's row can never be demoted — owner authority is created_by, not
+//     the role value, so a demoted owner row would just lie to the member list.
+// PURE + exported (the authorizeGoalTaskCreate precedent above) so every
+// rejection is pinned by a DB-free unit test. The route fetches goal /
+// memberships, then calls this; it rejects on the FIRST failure (fail-closed —
+// a missing/ambiguous input denies):
+//   goal_not_found → goal_not_open → not_owner_or_manager → not_a_member
+//   (target) → no-op same-role → owner_only_demotion → owner_role_fixed.
+// Authority (not_owner_or_manager) is checked BEFORE the target lookup so an
+// unauthorized actor never learns who is or isn't a member (the O1 no-leak
+// ordering precedent in the abuse matrix). The DB helper (setGoalMemberRole)
+// re-asserts the owner-demotion guard atomically in the UPDATE itself — this
+// gate is the testable contract, the SQL guard is the backstop.
+// Returns { ok:true }, { ok:true, noop:true } (role already as requested), or
+// { ok:false, status, body } (the exact HTTP status + JSON the route sends).
+function authorizeMemberRoleChange({ goal, actorId, actorRank, actorMembership, targetMembership, targetId, role }) {
+  if (!goal) {
+    return { ok: false, status: 404, body: { error: 'goal_not_found' } };
+  }
+  if (goal.status !== 'open') {
+    return { ok: false, status: 409, body: {
+      error: 'goal_not_open', status: goal.status,
+      message: 'Member roles can only be changed on an open goal.',
+    } };
+  }
+  const actorIsOwner = isGoalOwner(goal, actorId);
+  const actorIsManager = !!actorMembership && actorMembership.role === 'lead';
+  if (actorRank !== 'archon' && !actorIsOwner && !actorIsManager) {
+    return { ok: false, status: 403, body: {
+      error: 'not_owner_or_manager',
+      message: 'Only this goal\'s owner or a manager (or an Archon) may change member roles.',
+    } };
+  }
+  if (!targetMembership) {
+    return { ok: false, status: 404, body: {
+      error: 'not_a_member',
+      message: 'That builder is not a member of this goal — admit them first.',
+    } };
+  }
+  if (targetMembership.role === role) {
+    return { ok: true, noop: true };
+  }
+  if (role === 'member') {
+    // A demotion. Managers promote; only the owner (or an Archon) demotes.
+    if (actorRank !== 'archon' && !actorIsOwner) {
+      return { ok: false, status: 403, body: {
+        error: 'owner_only_demotion',
+        message: 'Only the goal owner (or an Archon) may demote a manager.',
+      } };
+    }
+    if (isGoalOwner(goal, targetId)) {
+      return { ok: false, status: 409, body: {
+        error: 'owner_role_fixed',
+        message: 'The goal owner cannot be demoted — transfer ownership first.',
+      } };
+    }
+  }
+  return { ok: true };
+}
+
+// authorizeGoalManagement — the shared ORDERED, FAIL-CLOSED prefix for actions
+// a goal's own authority performs (task 1736: conflict resolution; the same
+// three steps open authorizeMemberRoleChange above): goal exists → goal open →
+// actor is owner|manager|Archon. Returns { ok:true } or { ok:false, status,
+// body }. PURE + exported, same precedent as its siblings.
+function authorizeGoalManagement({ goal, actorId, actorRank, actorMembership }) {
+  if (!goal) {
+    return { ok: false, status: 404, body: { error: 'goal_not_found' } };
+  }
+  if (goal.status !== 'open') {
+    return { ok: false, status: 409, body: {
+      error: 'goal_not_open', status: goal.status,
+      message: 'Only an open goal can be managed.',
+    } };
+  }
+  const actorIsOwner = isGoalOwner(goal, actorId);
+  const actorIsManager = !!actorMembership && actorMembership.role === 'lead';
+  if (actorRank !== 'archon' && !actorIsOwner && !actorIsManager) {
+    return { ok: false, status: 403, body: {
+      error: 'not_owner_or_manager',
+      message: 'Only this goal\'s owner or a manager (or an Archon) may do this.',
+    } };
+  }
+  return { ok: true };
+}
+
+// authorizeOwnershipTransfer — the ORDERED, FAIL-CLOSED decision for
+// POST /goals/:id/transfer (task 1735): the owner hands the goal to another
+// builder (the old owner keeps their manager row). Ownership is creator-
+// equivalent authority and goal CREATION is Metic+ — so the transfer target
+// must be Metic+ too (fail-closed; this also keeps the protected-scope
+// membership wall intact, since a protected-scope goal requires Metic+ members).
+// Ordering: goal_not_found → goal_not_open → not_owner → builder_not_found →
+// metic_required_for_ownership → no-op self-transfer.
+function authorizeOwnershipTransfer({ goal, actorId, actorRank, targetBuilder }) {
+  if (!goal) {
+    return { ok: false, status: 404, body: { error: 'goal_not_found' } };
+  }
+  if (goal.status !== 'open') {
+    return { ok: false, status: 409, body: {
+      error: 'goal_not_open', status: goal.status,
+      message: 'Ownership can only be transferred on an open goal.',
+    } };
+  }
+  if (actorRank !== 'archon' && !isGoalOwner(goal, actorId)) {
+    return { ok: false, status: 403, body: {
+      error: 'not_owner',
+      message: 'Only the goal owner (or an Archon) may transfer ownership.',
+    } };
+  }
+  if (!targetBuilder) {
+    return { ok: false, status: 404, body: { error: 'builder_not_found' } };
+  }
+  if (!METIC_PLUS.includes(targetBuilder.rank)) {
+    return { ok: false, status: 403, body: {
+      error: 'metic_required_for_ownership',
+      message: 'Goal ownership is creator-equivalent authority — the new owner must be Metic+.',
+    } };
+  }
+  if (isGoalOwner(goal, targetBuilder.id)) {
+    return { ok: true, noop: true };
+  }
+  return { ok: true };
+}
+
+// -------------------------------------------------------------------------
+// Private goals: the invite / join-request queue (task 1952 / ADR 0112). A
+// private goal is join-GATED (not hidden): a non-member can't self-join — they
+// are INVITED (a consented, pending row they accept) or REQUEST to join (an
+// owner/manager/Archon approves). Both directions live in goal_membership_requests
+// (kind='invite'|'request'); the resolve is atomic (db.resolveMembershipRequest
+// moves only from status='pending', so a re-submit can't double-add a member).
+// -------------------------------------------------------------------------
+
+// protectedScopeAdmissionBlock — the SINGLE protected-scope admission rule reused
+// by BOTH new admission paths (invite-create and join-request-approve) AND the
+// existing POST /goals/:id/members (whose inline checks this generalizes). A
+// protected-scope goal admits members only via an Archon, and only Metic+ builders
+// — sub-Metic membership inside protected scope is deferred to ADR 0086's Phase-5
+// ADR. Centralized so the protected wall can never drift between paths (the SEC
+// #863 single-roster lesson). Returns { status, body } to send, or null to proceed.
+function protectedScopeAdmissionBlock({ scopeProtected, actorRank, targetRank }) {
+  if (!scopeProtected) return null;
+  if (actorRank !== 'archon') {
+    return { status: 403, body: {
+      error: 'archon_required_for_protected_scope',
+      message: 'This goal is scoped to a protected module; only an Archon may admit members.',
+    } };
+  }
+  if (!METIC_PLUS.includes(targetRank)) {
+    return { status: 403, body: {
+      error: 'metic_required_for_protected_scope',
+      message: 'A protected-scope goal requires a Metic+ member; sub-Metic membership is deferred to the Phase-5 ADR.',
+    } };
+  }
+  return null;
+}
+
+// authorizeCreateJoinRequest — the ORDERED, FAIL-CLOSED gate for
+// POST /goals/:id/requests (task 1952): a builder asks to join. A request only
+// makes sense where self-join is gated — a PUBLIC, NON-protected goal is open-join,
+// so a request there is refused with a "just join" hint. Ordering:
+// goal_not_found → goal_not_open → already_a_member → goal_is_open (public+unprotected).
+// isMember is the caller's own membership; scopeProtected is scopeIncludesProtected(goal).
+// PURE + exported (the authorizeGoalTaskCreate precedent).
+function authorizeCreateJoinRequest({ goal, isMember, scopeProtected }) {
+  if (!goal) return { ok: false, status: 404, body: { error: 'goal_not_found' } };
+  if (goal.status !== 'open') {
+    return { ok: false, status: 409, body: {
+      error: 'goal_not_open', status: goal.status,
+      message: 'You can only request to join an open goal.',
+    } };
+  }
+  if (isMember) {
+    return { ok: false, status: 409, body: {
+      error: 'already_a_member', message: 'You are already a member of this goal.',
+    } };
+  }
+  if (goal.visibility !== 'private' && !scopeProtected) {
+    return { ok: false, status: 409, body: {
+      error: 'goal_is_open',
+      message: 'This goal is open — just join it (POST /goals/:id/join); no request needed.',
+    } };
+  }
+  return { ok: true };
+}
+
+// authorizeInvitationResponse — the ORDERED, FAIL-CLOSED gate for
+// POST /goals/:id/invitations/:reqId/respond (task 1952): ONLY the invited builder
+// may accept/decline their OWN pending invite. Containment first — the row must
+// belong to THIS goal and be an 'invite' — so the invitation route can never touch
+// a join-request row. Ordering: request_not_found → wrong_goal → not_an_invitation
+// → not_pending → not_your_invitation. PURE + exported.
+function authorizeInvitationResponse({ request, goalId, actorId }) {
+  if (!request) return { ok: false, status: 404, body: { error: 'request_not_found' } };
+  if (String(request.goal_id) !== String(goalId)) {
+    return { ok: false, status: 404, body: { error: 'request_not_found', message: 'No such invitation on this goal.' } };
+  }
+  if (request.kind !== 'invite') {
+    return { ok: false, status: 400, body: { error: 'not_an_invitation', message: 'That row is a join-request, not an invitation.' } };
+  }
+  if (request.status !== 'pending') {
+    return { ok: false, status: 409, body: { error: 'not_pending', status: request.status } };
+  }
+  if (String(request.builder_id) !== String(actorId)) {
+    return { ok: false, status: 403, body: {
+      error: 'not_your_invitation',
+      message: 'Only the invited builder may accept or decline this invitation.',
+    } };
+  }
+  return { ok: true };
+}
+
+// authorizeJoinRequestResponse — the gate for POST /goals/:id/requests/:reqId/respond
+// (task 1952): an owner|manager|Archon approves/denies a pending join-request. The
+// authority prefix is authorizeGoalManagement VERBATIM (goal exists/open + owner|
+// manager|Archon — checked BEFORE the request lookup so an unauthorized actor never
+// learns whether a request exists, the O1 no-leak ordering). Then request
+// containment + state: request_not_found → wrong_goal → not_a_join_request →
+// not_pending. PURE + exported.
+function authorizeJoinRequestResponse({ goal, actorId, actorRank, actorMembership, request, goalId }) {
+  const mgmt = authorizeGoalManagement({ goal, actorId, actorRank, actorMembership });
+  if (!mgmt.ok) return mgmt;
+  if (!request) return { ok: false, status: 404, body: { error: 'request_not_found' } };
+  if (String(request.goal_id) !== String(goalId)) {
+    return { ok: false, status: 404, body: { error: 'request_not_found', message: 'No such join-request on this goal.' } };
+  }
+  if (request.kind !== 'request') {
+    return { ok: false, status: 400, body: { error: 'not_a_join_request', message: 'That row is an invitation, not a join-request.' } };
+  }
+  if (request.status !== 'pending') {
+    return { ok: false, status: 409, body: { error: 'not_pending', status: request.status } };
+  }
+  return { ok: true };
+}
+
+module.exports = function buildGoalsRouter() {
+  const router = express.Router();
+
+  // POST /goals — create a goal.
+  // rank: metic+archon — a Metic or Archon may create a goal; creation of a goal
+  // whose scope_modules includes a PROTECTED module is Archon-only (in-handler).
+  router.post('/goals', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+    if (validateOrRespond(req, res, {
+      version_id: { required: true, type: 'string', minLength: 1, maxLength: 64 },
+      title: { required: true, type: 'string', minLength: 1, maxLength: LIMITS.TITLE },
+      description: { type: 'string', maxLength: LIMITS.DESCRIPTION },
+      scope_modules: { type: 'array', maxItems: 64, itemsType: 'string' },
+      succeeds_goal_id: { type: 'integer', min: 1 },
+    })) return;
+
+    const scopeModules = req.body.scope_modules || [];
+    // Fail closed on an unknown module key — the scope wall is meaningless if it
+    // can name a module that doesn't exist.
+    const unknown = scopeModules.filter((k) => !isModuleKey(k));
+    if (unknown.length) {
+      return res.fail('unknown_module', 400, { unknown, valid: moduleKeys() });
+    }
+    // The scope is set by a trusted rank at planning time; a protected-module
+    // scope can only be set by an Archon (ADR 0086 §3/§4).
+    if (scopeIncludesProtected(scopeModules) && req.builder.rank !== 'archon') {
+      return res.fail('archon_required_for_protected_scope', { status: 403, message: 'A goal scoped to a protected module can only be created by an Archon.' });
+    }
+
+    try {
+      const version = await db.getVersion(req.body.version_id);
+      if (!version) {
+        return res.fail('version_not_found', { status: 404, message: 'No such version.' });
+      }
+      // Rescope carry-forward (ADR 0086 §6 / BV1.R64): a new-version goal may declare
+      // the (achieved) goal it continues. Validate the predecessor exists BEFORE
+      // creating the successor, so a bad ref can't leave an orphan goal behind.
+      const succeedsId = req.body.succeeds_goal_id ?? null;
+      if (succeedsId != null) {
+        const predecessor = await db.getGoal(succeedsId);
+        if (!predecessor) {
+          return res.fail('predecessor_not_found', { status: 404, message: 'No such goal to carry forward.' });
+        }
+      }
+      const goal = await db.createGoal({
+        versionId: req.body.version_id,
+        title: req.body.title,
+        description: (req.body.description || '').trim() || null,
+        scopeModules,
+        createdBy: req.builder.id,
+      });
+      // Stamp the predecessor's succeeded_by pointer at the new goal (the lineage).
+      if (succeedsId != null) {
+        await db.setGoalSuccessor({ goalId: succeedsId, successorId: goal.id });
+      }
+      return res.status(201).json({ ok: true, goal, succeeds_goal_id: succeedsId });
+    } catch (err) {
+      console.error('[gds] POST /goals', err);
+      return res.fail('goal_create_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /goals?version=&status= — list goals (read).
+  // rank: any-builder — viewing the goal board.
+  router.get('/goals', auth.requireBuilder, async (req, res) => {
+    const { version, status } = req.query;
+    if (status && !VALID_GOAL_STATUSES.includes(status)) {
+      return res.fail('bad_status', 400, { valid: VALID_GOAL_STATUSES });
+    }
+    try {
+      const goals = await db.listGoals({ versionId: version || null, status: status || null });
+      return res.json({ goals });
+    } catch (err) {
+      console.error('[gds] GET /goals', err);
+      return res.fail('list_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /goals/reorder — Archon drag-to-reorder: set the priority order of
+  // every goal WITHIN one version (task 1760). ordered_ids must be exactly
+  // that version's goal ids, each once (db.reorderGoals fails closed
+  // otherwise) — a partial list can't silently orphan a goal's priority.
+  // Mounted BEFORE GET /goals/:id so 'reorder' is never captured as an id.
+  // rank: archon — priority is an owner decision, never self-granted by a
+  // goal's own member/manager (unlike the goal-authority routes above).
+  router.post('/goals/reorder', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    if (validateOrRespond(req, res, {
+      version_id: { required: true, type: 'string', minLength: 1, maxLength: 64 },
+      ordered_ids: { required: true, type: 'array', maxItems: 500, itemsType: 'integer' },
+    })) return;
+    const versionId = req.body.version_id;
+    const orderedIds = req.body.ordered_ids;
+    if (orderedIds.length === 0 || orderedIds.some((id) => !Number.isInteger(id) || id <= 0)) {
+      return res.fail('bad_ordered_ids', { status: 400, message: 'ordered_ids must be a non-empty list of positive integers.' });
+    }
+    try {
+      const version = await db.getVersion(versionId);
+      if (!version) return res.fail('version_not_found', 404);
+      const goals = await db.reorderGoals({ versionId, orderedIds });
+      return res.json({ ok: true, goals });
+    } catch (err) {
+      if (err && err.code === 'SET_MISMATCH') {
+        return res.fail('set_mismatch', { status: 400, message: err.message });
+      }
+      console.error('[gds] POST /goals/reorder', err);
+      return res.fail('reorder_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /goals/inbox — the caller's private-goals inbox (task 1952 / ADR 0112):
+  // { invitations: invites addressed to me (accept/decline); joinRequests: pending
+  // join-requests on goals I own or manage (approve/deny); myPendingRequests: my own
+  // outstanding requests }. Powers the home-page inbox widget (task 1954) + the
+  // goals page. Mounted BEFORE GET /goals/:id so the literal 'inbox' path is matched
+  // as its own route, not captured as an id (the /goals/reorder precedent).
+  // rank: any-builder — every builder reads their OWN inbox (db.listInboxFor scopes
+  // by req.builder.id; a builder can't read another's).
+  router.get('/goals/inbox', auth.requireBuilder, async (req, res) => {
+    try {
+      const inbox = await db.listInboxFor(req.builder.id);
+      return res.json(inbox);
+    } catch (err) {
+      console.error('[gds] GET /goals/inbox', err);
+      return res.fail('inbox_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /goals/:id — one goal with its members + linked criteria (read).
+  // rank: any-builder.
+  router.get('/goals/:id', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    try {
+      const goal = await db.getGoal(id);
+      if (!goal) return res.fail('goal_not_found', 404);
+      const [members, criteria, dependencies] = await Promise.all([
+        db.listGoalMembers(id),
+        db.listCriteriaForGoal(id),
+        db.getGoalDependencies(id),  // task 1761 — prerequisite goals + satisfied state
+      ]);
+      return res.json({ goal, members, criteria, dependencies });
+    } catch (err) {
+      console.error('[gds] GET /goals/:id', err);
+      return res.fail('fetch_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /goals/:id/join — join an open goal.
+  // rank: any-builder — open join for a NORMAL goal. A PROTECTED-scope goal is
+  // Archon-mediated: a non-Archon cannot self-join (an Archon admits them via
+  // POST /goals/:id/members). Sub-Metic membership inside protected scope is
+  // deferred to the Phase-5 ADR (ADR 0086 Deferred).
+  router.post('/goals/:id/join', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    try {
+      const goal = await db.getGoal(id);
+      if (!goal) return res.fail('goal_not_found', 404);
+      if (goal.status !== 'open') {
+        return res.fail('goal_not_open', 409, { status: goal.status });
+      }
+      if (scopeIncludesProtected(goal.scope_modules) && req.builder.rank !== 'archon') {
+        return res.fail('archon_approval_required', { status: 403, message: 'This goal is scoped to a protected module; an Archon must add you (POST /goals/:id/members).' });
+      }
+      // Private goals are join-GATED (task 1952 / ADR 0112): a non-member can't
+      // self-join — they request to join or wait for an invite. An existing member
+      // re-joining is a harmless upsert, and an Archon may still self-join anything.
+      if (goal.visibility === 'private' && req.builder.rank !== 'archon') {
+        const alreadyMember = await db.isGoalMember({ goalId: id, builderId: req.builder.id });
+        if (!alreadyMember) {
+          return res.fail('goal_private', { status: 409, message: 'This goal is private — request to join (POST /goals/:id/requests) or wait for an invitation.' });
+        }
+      }
+      const member = await db.addGoalMember({ goalId: id, builderId: req.builder.id, role: 'member' });
+      return res.status(201).json({ ok: true, member });
+    } catch (err) {
+      console.error('[gds] POST /goals/:id/join', err);
+      return res.fail('join_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /goals/:id/leave — leave a goal you're in.
+  // rank: any-builder.
+  router.post('/goals/:id/leave', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    try {
+      const { removed } = await db.removeGoalMember({ goalId: id, builderId: req.builder.id });
+      if (!removed) return res.fail('not_a_member', 409);
+      return res.json({ ok: true });
+    } catch (err) {
+      console.error('[gds] POST /goals/:id/leave', err);
+      return res.fail('leave_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH /goals/:id/visibility — make a goal public|private (task 1952 / ADR 0112).
+  // The owner, a manager, or an Archon (authorizeGoalManagement) flips it; a private
+  // goal is join-gated (see POST /goals/:id/join). 'public' is the default.
+  // rank: any-builder (requireBuilder) + the in-handler owner|manager|Archon gate.
+  // Pinned in route-rank-check.MODULE_EXPECTED_RANKS['lifecycle'].
+  router.patch('/goals/:id/visibility', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, { visibility: { required: true, type: 'string' } })) return;
+    const visibility = req.body.visibility;
+    if (!VALID_VISIBILITIES.includes(visibility)) {
+      return res.fail('bad_visibility', 400, { valid: VALID_VISIBILITIES });
+    }
+    try {
+      const goal = await db.getGoal(id);
+      const actorMembership = goal
+        ? await db.getGoalMember({ goalId: id, builderId: req.builder.id })
+        : null;
+      const decision = authorizeGoalManagement({
+        goal, actorId: req.builder.id, actorRank: req.builder.rank, actorMembership,
+      });
+      if (!decision.ok) return res.status(decision.status).json(decision.body);
+      const updated = await db.setGoalVisibility({ goalId: id, visibility });
+      return res.json({ ok: true, goal: updated });
+    } catch (err) {
+      console.error('[gds] PATCH /goals/:id/visibility', err);
+      return res.fail('visibility_update_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /goals/:id/requests — a builder asks to join a (private or protected)
+  // goal (task 1952 / ADR 0112). Refused on a public, non-protected goal (that's
+  // open-join — just POST /goals/:id/join). Creates a pending kind='request' the
+  // goal's owner/manager/Archon approves from their inbox. The pending-unique index
+  // (one open ask per goal+builder) surfaces as 409 request_pending.
+  // rank: any-builder (requireBuilder) + the in-handler authorizeCreateJoinRequest.
+  router.post('/goals/:id/requests', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, { note: { type: 'string', maxLength: LIMITS.NOTES } })) return;
+    try {
+      const goal = await db.getGoal(id);
+      const isMember = goal ? await db.isGoalMember({ goalId: id, builderId: req.builder.id }) : false;
+      const scopeProtected = goal ? scopeIncludesProtected(goal.scope_modules) : false;
+      const decision = authorizeCreateJoinRequest({ goal, isMember, scopeProtected });
+      if (!decision.ok) return res.status(decision.status).json(decision.body);
+      const request = await db.createMembershipRequest({
+        goalId: id, builderId: req.builder.id, kind: 'request',
+        createdBy: req.builder.id, note: (req.body.note || '').trim() || null,
+      });
+      return res.status(201).json({ ok: true, request });
+    } catch (err) {
+      if (err && err.code === 'PENDING_EXISTS') {
+        return res.fail('request_pending', { status: 409, message: 'You already have a pending request or invitation for this goal.' });
+      }
+      console.error('[gds] POST /goals/:id/requests', err);
+      return res.fail('request_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /goals/:id/requests/:reqId/respond { action: approve|deny } — an owner|
+  // manager|Archon resolves a pending join-request (task 1952). approve → the
+  // requester is added as a member; deny → the row is rejected (kept as the audit
+  // trail). The membership add is atomic with the resolve (resolveMembershipRequest
+  // moves only from status='pending'). A protected-scope goal still admits only
+  // Metic+ via an Archon — the same wall as invite + POST /members.
+  // rank: any-builder (requireBuilder) + the in-handler authorizeJoinRequestResponse.
+  router.post('/goals/:id/requests/:reqId/respond', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    const reqId = parseId(req, res, { param: 'reqId', code: 'bad_request_id', positiveInt: true });
+    if (reqId === null) return;
+    if (validateOrRespond(req, res, { action: { required: true, type: 'string' } })) return;
+    const action = req.body.action;
+    if (!JOIN_REQUEST_RESPONSE_ACTIONS.includes(action)) {
+      return res.fail('bad_action', 400, { valid: JOIN_REQUEST_RESPONSE_ACTIONS });
+    }
+    try {
+      const goal = await db.getGoal(id);
+      const [actorMembership, request] = goal
+        ? await Promise.all([
+            db.getGoalMember({ goalId: id, builderId: req.builder.id }),
+            db.getMembershipRequest(reqId),
+          ])
+        : [null, null];
+      const decision = authorizeJoinRequestResponse({
+        goal, actorId: req.builder.id, actorRank: req.builder.rank, actorMembership, request, goalId: id,
+      });
+      if (!decision.ok) return res.status(decision.status).json(decision.body);
+
+      if (action === 'deny') {
+        const resolved = await db.resolveMembershipRequest({ id: reqId, status: 'rejected', resolvedBy: req.builder.id });
+        if (!resolved) return res.fail('not_pending', { status: 409, message: 'The request changed underneath this response — re-read and retry.' });
+        return res.json({ ok: true, action, request: resolved });
+      }
+
+      // approve — the protected-scope admission wall, read against the goal's
+      // CURRENT scope (re-fetched here, not the top-of-handler read, so an Archon
+      // re-scope since then is seen — the invitation-accept path's pattern). The
+      // residual micro-race with a concurrent re-scope is defense-in-depth: ADR
+      // 0086 §7 makes the SHIP-TIME gates authoritative on the real diff, and this
+      // mirrors the POST /goals/:id/members admission path — a stale membership row
+      // never grants actual protected-code access.
+      const freshGoal = (await db.getGoal(id)) || goal;
+      if (scopeIncludesProtected(freshGoal.scope_modules)) {
+        const target = await api.getBuilderById(request.builder_id);
+        const block = protectedScopeAdmissionBlock({
+          scopeProtected: true, actorRank: req.builder.rank, targetRank: target && target.rank,
+        });
+        if (block) return res.status(block.status).json(block.body);
+      }
+      // Resolve + add atomically (one statement); the requester (request.builder_id)
+      // becomes the member. null = the request was resolved out from under us → 409.
+      const outcome = await db.acceptMembershipRequestAndAddMember({ id: reqId, resolvedBy: req.builder.id });
+      if (!outcome) return res.fail('not_pending', { status: 409, message: 'The request changed underneath this response — re-read and retry.' });
+      return res.json({ ok: true, action, request: outcome.request, member: outcome.member });
+    } catch (err) {
+      console.error('[gds] POST /goals/:id/requests/:reqId/respond', err);
+      return res.fail('request_respond_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /goals/:id/invitations { builder_id, note? } — an owner|manager|Archon
+  // invites a builder (task 1952). Creates a PENDING kind='invite' the invitee
+  // accepts from their inbox (a consented add — distinct from POST /goals/:id/members,
+  // the immediate force-add, kept as-is). Protected-scope invites keep the Archon-
+  // actor + Metic+-target wall (protectedScopeAdmissionBlock). 409 if the target is
+  // already a member or already has a pending row.
+  // rank: any-builder (requireBuilder) + the in-handler owner|manager|Archon gate.
+  router.post('/goals/:id/invitations', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      note: { type: 'string', maxLength: LIMITS.NOTES },
+      builder_id: {},  // number or numeric string (coerced below); untyped for strict-mode
+    })) return;
+    // builder_id accepts a JSON number OR a numeric string (the /members precedent —
+    // pg serializes bigint ids as strings, so a client echoing an id would fail an
+    // integer-typed validator).
+    const builderId = Number(req.body.builder_id);
+    if (!Number.isInteger(builderId) || builderId <= 0) {
+      return res.fail('bad_builder_id', { status: 400, message: 'builder_id must be a positive integer.' });
+    }
+    try {
+      const goal = await db.getGoal(id);
+      const actorMembership = goal
+        ? await db.getGoalMember({ goalId: id, builderId: req.builder.id })
+        : null;
+      const decision = authorizeGoalManagement({
+        goal, actorId: req.builder.id, actorRank: req.builder.rank, actorMembership,
+      });
+      if (!decision.ok) return res.status(decision.status).json(decision.body);
+      const target = await api.getBuilderById(builderId);
+      if (!target) return res.fail('builder_not_found', 404);
+      // Protected-scope wall against the goal's CURRENT scope (re-fetched, not the
+      // top-of-handler read — matches the respond paths). Residual re-scope race is
+      // defense-in-depth (ADR 0086 §7 — ship-time gates authoritative; mirrors
+      // POST /goals/:id/members).
+      const freshGoal = (await db.getGoal(id)) || goal;
+      const block = protectedScopeAdmissionBlock({
+        scopeProtected: scopeIncludesProtected(freshGoal.scope_modules),
+        actorRank: req.builder.rank, targetRank: target.rank,
+      });
+      if (block) return res.status(block.status).json(block.body);
+      if (await db.isGoalMember({ goalId: id, builderId })) {
+        return res.fail('already_a_member', { status: 409, message: 'That builder is already a member of this goal.' });
+      }
+      const request = await db.createMembershipRequest({
+        goalId: id, builderId, kind: 'invite',
+        createdBy: req.builder.id, note: (req.body.note || '').trim() || null,
+      });
+      return res.status(201).json({ ok: true, request });
+    } catch (err) {
+      if (err && err.code === 'PENDING_EXISTS') {
+        return res.fail('invite_pending', { status: 409, message: 'That builder already has a pending invitation or request for this goal.' });
+      }
+      console.error('[gds] POST /goals/:id/invitations', err);
+      return res.fail('invite_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /goals/:id/invitations/:reqId/respond { action: accept|decline } — ONLY the
+  // invited builder resolves their OWN pending invite (task 1952). accept → they're
+  // added as a member; decline → the row is rejected. A protected-scope goal still
+  // requires a Metic+ member, re-checked against the accepting builder's current rank
+  // (the goal could have been re-scoped after the invite).
+  // rank: any-builder (requireBuilder) + the in-handler authorizeInvitationResponse.
+  router.post('/goals/:id/invitations/:reqId/respond', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    const reqId = parseId(req, res, { param: 'reqId', code: 'bad_request_id', positiveInt: true });
+    if (reqId === null) return;
+    if (validateOrRespond(req, res, { action: { required: true, type: 'string' } })) return;
+    const action = req.body.action;
+    if (!INVITE_RESPONSE_ACTIONS.includes(action)) {
+      return res.fail('bad_action', 400, { valid: INVITE_RESPONSE_ACTIONS });
+    }
+    try {
+      const request = await db.getMembershipRequest(reqId);
+      const decision = authorizeInvitationResponse({ request, goalId: id, actorId: req.builder.id });
+      if (!decision.ok) return res.status(decision.status).json(decision.body);
+
+      if (action === 'decline') {
+        const resolved = await db.resolveMembershipRequest({ id: reqId, status: 'rejected', resolvedBy: req.builder.id });
+        if (!resolved) return res.fail('not_pending', { status: 409, message: 'The invitation changed underneath this response — re-read and retry.' });
+        return res.json({ ok: true, action, request: resolved });
+      }
+
+      // accept — re-assert the protected-scope Metic+ membership invariant against
+      // the accepting builder's CURRENT rank (the goal may have been re-scoped since
+      // the invite). The invitee is consenting, so the actor-is-Archon half of the
+      // admission rule does NOT apply here — only the Metic+ membership floor does.
+      const goal = await db.getGoal(id);
+      if (goal && scopeIncludesProtected(goal.scope_modules) && !METIC_PLUS.includes(req.builder.rank)) {
+        return res.fail('metic_required_for_protected_scope', { status: 403, message: 'This goal is scoped to a protected module and requires a Metic+ member.' });
+      }
+      // Resolve + add atomically (one statement) — never an 'accepted' invite
+      // with no membership (the task-1952 review fix).
+      const outcome = await db.acceptMembershipRequestAndAddMember({ id: reqId, resolvedBy: req.builder.id });
+      if (!outcome) return res.fail('not_pending', { status: 409, message: 'The invitation changed underneath this response — re-read and retry.' });
+      return res.json({ ok: true, action, request: outcome.request, member: outcome.member });
+    } catch (err) {
+      console.error('[gds] POST /goals/:id/invitations/:reqId/respond', err);
+      return res.fail('invitation_respond_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /goals/:id/members — the goal's own authority (owner | manager | Archon)
+  // invites a builder to the goal (task 1762: widened from Archon-only so a
+  // manager doesn't need an Archon in the loop for a normal goal). This stays the
+  // approval grant for a protected-scope goal, which a non-Archon cannot self-
+  // join AND a non-Archon cannot invite into (archon_required_for_protected_scope
+  // below) — protected-scope admission is deliberately Archon-mediated on BOTH
+  // sides of the grant. For a protected-scope goal the target must additionally
+  // be Metic+ (ADR 0086 Deferred: protected-scope goals require a Metic+ holder
+  // until the Phase-5 ADR).
+  // rank: any-builder (requireBuilder) + the in-handler (owner | manager |
+  // Archon) gate (authorizeGoalManagement) — like the sibling owner/manager
+  // routes, the wall is in-handler, NOT a rank middleware. Pinned in
+  // route-rank-check.EXPECTED_RANKS.
+  router.post('/goals/:id/members', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      role: { type: 'string' },
+      // builder_id accepts a JSON number OR a numeric string (coerced below);
+      // declared untyped so strict-mode accepts either form.
+      builder_id: {},
+    })) return;
+    // builder_id accepts a JSON number OR a numeric string: ids round-trip
+    // through JSON as strings (pg serializes bigint as a string), so a client
+    // echoing an id from a goal-members response would otherwise be rejected.
+    const builderId = Number(req.body.builder_id);
+    if (!Number.isInteger(builderId) || builderId <= 0) {
+      return res.fail('bad_builder_id', { status: 400, message: 'builder_id must be a positive integer.' });
+    }
+    const role = req.body.role || 'member';
+    if (!VALID_MEMBER_ROLES.includes(role)) {
+      return res.fail('bad_role', 400, { valid: VALID_MEMBER_ROLES });
+    }
+    try {
+      const goal = await db.getGoal(id);
+      const actorMembership = goal
+        ? await db.getGoalMember({ goalId: id, builderId: req.builder.id })
+        : null;
+      const decision = authorizeGoalManagement({
+        goal,
+        actorId: req.builder.id,
+        actorRank: req.builder.rank,
+        actorMembership,
+      });
+      if (!decision.ok) {
+        return res.status(decision.status).json(decision.body);
+      }
+      // Protected-scope admission is Archon-mediated on the ACTOR side too — a
+      // goal's own owner/manager cannot use this widened grant to route around
+      // the protected-module wall (ADR 0086 §3/§4; mirrors the join-route check).
+      if (scopeIncludesProtected(goal.scope_modules) && req.builder.rank !== 'archon') {
+        return res.fail('archon_required_for_protected_scope', { status: 403, message: 'This goal is scoped to a protected module; only an Archon may add members.' });
+      }
+      const target = await api.getBuilderById(builderId);
+      if (!target) return res.fail('builder_not_found', 404);
+      if (scopeIncludesProtected(goal.scope_modules) && !METIC_PLUS.includes(target.rank)) {
+        return res.fail('metic_required_for_protected_scope', { status: 403, message: 'A protected-scope goal requires a Metic+ member; sub-Metic membership is deferred to the Phase-5 ADR.' });
+      }
+      const member = await db.addGoalMember({ goalId: id, builderId, role });
+      return res.status(201).json({ ok: true, member });
+    } catch (err) {
+      console.error('[gds] POST /goals/:id/members', err);
+      return res.fail('add_member_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH /goals/:id/members/:builderId — role management by the goal's own
+  // authority (task 1735): the owner, a manager, or an Archon promotes
+  // member→lead(manager); ONLY the owner (or an Archon) demotes; the owner's
+  // row is never demotable. The decision is the pure ordered gate above
+  // (authorizeMemberRoleChange); the DB write re-asserts the owner-demotion
+  // guard atomically (setGoalMemberRole), so a race cannot demote an owner.
+  // rank: any-builder (requireBuilder) + the in-handler (owner | manager |
+  // Archon) gate — like the authoring keystone, the wall is in-handler, NOT a
+  // rank middleware. Pinned in route-rank-check.MODULE_EXPECTED_RANKS['lifecycle'].
+  router.patch('/goals/:id/members/:builderId', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    const builderId = parseId(req, res, { param: 'builderId', code: 'bad_builder_id', positiveInt: true });
+    if (builderId === null) return;
+    if (validateOrRespond(req, res, {
+      role: { required: true, type: 'string' },
+    })) return;
+    const role = req.body.role;
+    if (!VALID_MEMBER_ROLES.includes(role)) {
+      return res.fail('bad_role', 400, { valid: VALID_MEMBER_ROLES });
+    }
+    try {
+      const goal = await db.getGoal(id);
+      // The gate's reads — only taken when the goal exists (a 404 needs none).
+      const [actorMembership, targetMembership] = goal
+        ? await Promise.all([
+            db.getGoalMember({ goalId: id, builderId: req.builder.id }),
+            db.getGoalMember({ goalId: id, builderId }),
+          ])
+        : [null, null];
+      const decision = authorizeMemberRoleChange({
+        goal,
+        actorId: req.builder.id,
+        actorRank: req.builder.rank,
+        actorMembership,
+        targetMembership,
+        targetId: builderId,
+        role,
+      });
+      if (!decision.ok) {
+        return res.status(decision.status).json(decision.body);
+      }
+      if (decision.noop) {
+        return res.json({ ok: true, member: targetMembership, changed: false });
+      }
+      const member = await db.setGoalMemberRole({ goalId: id, builderId, role });
+      if (!member) {
+        // The atomic backstop fired: the membership vanished, or ownership
+        // moved onto the target between the gate's read and this write.
+        // Honest conflict, not silent success.
+        return res.fail('role_change_conflict', { status: 409, message: 'The goal membership changed underneath this request — re-read the goal and retry.' });
+      }
+      return res.json({ ok: true, member, changed: true });
+    } catch (err) {
+      console.error('[gds] PATCH /goals/:id/members/:builderId', err);
+      return res.fail('role_change_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /goals/:id/transfer — hand the goal to a new owner (task 1735). Owner
+  // (or Archon) only; the target must be Metic+ (ownership is creator-equivalent
+  // authority — see authorizeOwnershipTransfer). The DB move is atomic: created_by
+  // reassigns and the new owner's membership upserts to 'lead' in one statement;
+  // the OLD owner keeps their lead row — they drop to manager, not out.
+  // rank: any-builder (requireBuilder) + the in-handler (owner | Archon) gate.
+  // Pinned in route-rank-check.MODULE_EXPECTED_RANKS['lifecycle'].
+  router.post('/goals/:id/transfer', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      builder_id: {},  // new owner id — number or numeric string (coerced below)
+    })) return;
+    // builder_id accepts a JSON number OR a numeric string (the /members
+    // precedent — pg serializes bigint ids as strings).
+    const newOwnerId = Number(req.body && req.body.builder_id);
+    if (!Number.isInteger(newOwnerId) || newOwnerId <= 0) {
+      return res.fail('bad_builder_id', { status: 400, message: 'builder_id must be a positive integer.' });
+    }
+    try {
+      const goal = await db.getGoal(id);
+      const targetBuilder = goal ? await api.getBuilderById(newOwnerId) : null;
+      const decision = authorizeOwnershipTransfer({
+        goal,
+        actorId: req.builder.id,
+        actorRank: req.builder.rank,
+        targetBuilder,
+      });
+      if (!decision.ok) {
+        return res.status(decision.status).json(decision.body);
+      }
+      if (decision.noop) {
+        return res.json({ ok: true, goal, changed: false });
+      }
+      const updated = await db.transferGoalOwnership({ goalId: id, newOwnerId });
+      if (!updated) {
+        return res.fail('transfer_conflict', { status: 409, message: 'The goal changed underneath this request — re-read it and retry.' });
+      }
+      return res.json({ ok: true, goal: updated, changed: true });
+    } catch (err) {
+      console.error('[gds] POST /goals/:id/transfer', err);
+      return res.fail('transfer_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /goals/:id/conflicts — the server-side task-conflict view (task 1736).
+  // Replaces the hall Goals page's client-side exact-string approximation (the
+  // page feature-detects on 404): glob-aware touches[] intersection via the
+  // canonical path-match machinery, claim-aware severity, and cross-goal
+  // overlaps against other OPEN goals sharing scope_modules. Detection only —
+  // resolution is the POST below.
+  // rank: any-builder — a read; the same audience as GET /goals/:id.
+  router.get('/goals/:id/conflicts', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    try {
+      const goal = await db.getGoal(id);
+      if (!goal) return res.fail('goal_not_found', 404);
+      const goalTasks = await db.listTasks({ goalId: id });
+      // Sibling scope: other open goals sharing at least one scope module. A
+      // scopeless goal (the migration-160 defaults) shares territory with
+      // nobody by declaration — only its own tasks are compared.
+      const scope = goal.scope_modules || [];
+      let crossGoal = [];
+      if (scope.length) {
+        const openGoals = await db.listGoals({ status: 'open' });
+        const siblings = openGoals.filter((g) =>
+          String(g.id) !== String(goal.id)
+          && (g.scope_modules || []).some((m) => scope.includes(m)));
+        crossGoal = await Promise.all(siblings.map(async (g) => ({
+          goal: g,
+          tasks: await db.listTasks({ goalId: g.id }),
+        })));
+      }
+      const allIds = [...goalTasks, ...crossGoal.flatMap((c) => c.tasks)].map((t) => t.id);
+      const activeClaims = await db.listActiveClaimsForTasks(allIds);
+      const activeClaimTaskIds = new Set(activeClaims.map((c) => String(c.task_id)));
+      const conflicts = goalConflicts.computeGoalConflicts({ goalTasks, activeClaimTaskIds, crossGoal });
+      return res.json({
+        ok: true,
+        goal_id: Number(goal.id),
+        conflicts,
+        cross_goals_considered: crossGoal.map((c) => ({ id: Number(c.goal.id), title: c.goal.title })),
+      });
+    } catch (err) {
+      console.error('[gds] GET /goals/:id/conflicts', err);
+      return res.fail('conflicts_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /goals/:id/conflicts/resolve — the owner/manager resolution actions
+  // for a detected conflict (task 1736; authority model ADR 0106):
+  //   sequence     {first_task_id, then_task_id} — order the work: `then`
+  //                gains a dependency on `first` via the ADR 0015 edge CRUD
+  //                (cycle-checked), so the claim gate serializes them.
+  //   flag_release {task_id, note?} — soft-nudge the active claim holder to
+  //                wrap up/release; surfaces on their own /me claim reads.
+  //   rescope      {task_id, touches[]} — rewrite the DECLARED blast radius at
+  //                planning time (ADR 0049 advisory semantics). Refused while
+  //                the task holds an active claim — mid-claim touches rewriting
+  //                is the drift-expand task 879 removed; flag_release instead.
+  // All targets must belong to THIS goal (containment — the parent-attach
+  // precedent: a manager can't reshape another goal's tasks through this route).
+  // rank: any-builder (requireBuilder) + the in-handler (owner | manager |
+  // Archon) gate (authorizeGoalManagement). Pinned in
+  // route-rank-check.MODULE_EXPECTED_RANKS['lifecycle'].
+  router.post('/goals/:id/conflicts/resolve', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      action: { required: true, type: 'string' },
+      note: { type: 'string', maxLength: LIMITS.NOTES },
+      touches: { type: 'array', maxItems: 500, itemsType: 'string' },
+      // Task-id operands for the sequence/dedup actions (number or numeric
+      // string, resolved below) — declared so strict-mode accepts them.
+      first_task_id: {},
+      then_task_id: {},
+      task_id: {},
+    })) return;
+    const action = req.body.action;
+    if (!RESOLVE_ACTIONS.includes(action)) {
+      return res.fail('bad_action', 400, { valid: RESOLVE_ACTIONS });
+    }
+    try {
+      const goal = await db.getGoal(id);
+      const actorMembership = goal
+        ? await db.getGoalMember({ goalId: id, builderId: req.builder.id })
+        : null;
+      const decision = authorizeGoalManagement({
+        goal, actorId: req.builder.id, actorRank: req.builder.rank, actorMembership,
+      });
+      if (!decision.ok) {
+        return res.status(decision.status).json(decision.body);
+      }
+
+      // Containment: resolve a task id from the body and require it to live in
+      // THIS goal. Accepts a number or a numeric string (ids round-trip through
+      // JSON as strings — the /members precedent).
+      const goalTask = async (raw, field) => {
+        const tid = Number(raw);
+        if (!Number.isInteger(tid) || tid <= 0) {
+          return { err: { status: 400, body: { error: 'bad_task_id', field } } };
+        }
+        const task = await db.getTask(tid);
+        if (!task) {
+          return { err: { status: 404, body: { error: 'task_not_found', task_id: tid } } };
+        }
+        if (String(task.goal_id ?? '') !== String(goal.id)) {
+          return { err: { status: 400, body: {
+            error: 'task_outside_goal', task_id: tid,
+            message: 'Resolution actions apply only to this goal\'s own tasks.',
+          } } };
+        }
+        return { task };
+      };
+
+      if (action === 'sequence') {
+        const first = await goalTask(req.body.first_task_id, 'first_task_id');
+        if (first.err) return res.status(first.err.status).json(first.err.body);
+        const then = await goalTask(req.body.then_task_id, 'then_task_id');
+        if (then.err) return res.status(then.err.status).json(then.err.body);
+        try {
+          await db.addTaskDependency(then.task.id, first.task.id);
+        } 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 });
+          if (err && err.code === 'TASK_NOT_FOUND') return res.fail('task_not_found', 404);
+          throw err;
+        }
+        const dependencies = await db.getTaskDependencies(then.task.id);
+        return res.json({
+          ok: true, action,
+          first_task_id: Number(first.task.id), then_task_id: Number(then.task.id),
+          dependencies,
+        });
+      }
+
+      if (action === 'flag_release') {
+        const t = await goalTask(req.body.task_id, 'task_id');
+        if (t.err) return res.status(t.err.status).json(t.err.body);
+        const flagged = await db.requestClaimRelease({
+          taskId: t.task.id,
+          requestedBy: req.builder.id,
+          note: (req.body.note || '').trim() || null,
+        });
+        if (!flagged) {
+          return res.fail('no_active_claim', { status: 409, message: 'That task holds no active claim to flag.' });
+        }
+        return res.json({ ok: true, action, claim: flagged });
+      }
+
+      // action === 'rescope'
+      const t = await goalTask(req.body.task_id, 'task_id');
+      if (t.err) return res.status(t.err.status).json(t.err.body);
+      const touches = req.body.touches;
+      if (!Array.isArray(touches) || touches.length === 0) {
+        return res.fail('touches_required', { status: 400, message: 'rescope needs a non-empty touches[] — the declared blast radius.' });
+      }
+      // The SAME scope wall the R60 create-time gate runs (goal-scope-check
+      // VERBATIM): rescope is a second authoring surface for the touches field,
+      // so without this a member could author an in-scope task and then rewrite
+      // it out of the goal's territory (or at protected paths) past the wall.
+      // Bounds everyone (scope-subset), floors sub-Metic off protected paths.
+      const wall = goalScopeCheck.check(goal.scope_modules, touches, req.builder.rank);
+      if (!wall.ok) {
+        return res.fail(wall.code, 403, { reason: wall.reason, details: wall.details });
+      }
+      const active = await db.listActiveClaimsForTasks([t.task.id]);
+      if (active.length) {
+        return res.fail('task_claimed', { status: 409, message: 'That task has an active claim — ask the holder to wrap up (flag_release) instead of rescoping under them.' });
+      }
+      const updated = await db.rescopeTaskTouches({
+        taskId: t.task.id,
+        touches,
+        securitySensitive: t.task.security_sensitive === true,
+        currentRequiresRank: t.task.requires_rank ?? 'xenos',
+      });
+      if (!updated) {
+        return res.fail('rescope_conflict', { status: 409, message: 'The task changed underneath this request — re-read and retry.' });
+      }
+      return res.json({
+        ok: true, action,
+        task_id: Number(updated.id),
+        touches: updated.touches,
+        requires_rank: updated.requires_rank,
+      });
+    } catch (err) {
+      console.error('[gds] POST /goals/:id/conflicts/resolve', err);
+      return res.fail('conflict_resolve_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /goals/:id/archive — retire a goal (open|achieved → archived). Archived
+  // goals are re-openable (below). This is the lifecycle disposition the /goal-review
+  // skill reaches for once a goal is achieved (ADR 0086 §6 / BV1.R64).
+  // rank: metic+archon — a goal member (Metic+) or an Archon dispositions the goal.
+  router.post('/goals/:id/archive', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    try {
+      const goal = await db.getGoal(id);
+      if (!goal) return res.fail('goal_not_found', 404);
+      if (!(await isMemberOrArchon(req.builder, id))) {
+        return res.fail('not_a_member', { status: 403, message: 'Join the goal (or be an Archon) to disposition it.' });
+      }
+      if (goal.status === 'archived') {
+        return res.fail('already_archived', 409);
+      }
+      const updated = await db.setGoalStatus({ goalId: id, status: 'archived' });
+      return res.json({ ok: true, goal: updated });
+    } catch (err) {
+      console.error('[gds] POST /goals/:id/archive', err);
+      return res.fail('archive_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /goals/:id/reopen — bring an archived goal back to open (ADR 0086 §6 /
+  // BV1.R64). Only archived → open; an already open/achieved goal is a 409.
+  // rank: metic+archon — same gate as archive.
+  router.post('/goals/:id/reopen', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    try {
+      const goal = await db.getGoal(id);
+      if (!goal) return res.fail('goal_not_found', 404);
+      if (!(await isMemberOrArchon(req.builder, id))) {
+        return res.fail('not_a_member', { status: 403, message: 'Join the goal (or be an Archon) to reopen it.' });
+      }
+      if (goal.status !== 'archived') {
+        return res.fail('not_archived', 409, { status: goal.status });
+      }
+      const updated = await db.setGoalStatus({ goalId: id, status: 'open' });
+      return res.json({ ok: true, goal: updated });
+    } catch (err) {
+      console.error('[gds] POST /goals/:id/reopen', err);
+      return res.fail('reopen_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /goals/:id/scope — "ask to widen": add module(s) to a goal's scope_modules
+  // (ADR 0086 §4 / BV1.R64). Scope is NEVER self-granted, so this is the gated
+  // approve-and-apply: requireRank('metic','archon') + the caller must be a member
+  // (or Archon), and a PROTECTED module can only be added by an Archon (mirrors the
+  // POST /goals create gate). A sub-Metic member therefore cannot widen at all — they
+  // ask a Metic+/Archon out-of-band, exactly as joining a protected goal works (R57).
+  // The goal must be open. Body: { add: ["module-key", ...] }; idempotent (set-union).
+  // rank: metic+archon — widens the module wall; pinned in route-rank-check.EXPECTED_RANKS.
+  router.post('/goals/:id/scope', auth.requireBuilder, auth.requireRank('metic', 'archon'), async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      add: { required: true, type: 'array', maxItems: 64, itemsType: 'string' },
+    })) return;
+    const add = [...new Set(req.body.add)];
+    if (add.length === 0) {
+      return res.fail('empty_add', { status: 400, message: 'add must name at least one module.' });
+    }
+    const unknown = add.filter((k) => !isModuleKey(k));
+    if (unknown.length) {
+      return res.fail('unknown_module', 400, { unknown, valid: moduleKeys() });
+    }
+    // The wall: a protected module can only be added by an Archon — the scope is set
+    // by a trusted rank, never self-granted (ADR 0086 §4).
+    if (scopeIncludesProtected(add) && req.builder.rank !== 'archon') {
+      return res.fail('archon_required_for_protected_scope', { status: 403, message: 'Adding a protected module to a goal scope can only be done by an Archon.' });
+    }
+    try {
+      const goal = await db.getGoal(id);
+      if (!goal) return res.fail('goal_not_found', 404);
+      if (goal.status !== 'open') {
+        return res.fail('goal_not_open', 409, { status: goal.status });
+      }
+      if (!(await isMemberOrArchon(req.builder, id))) {
+        return res.fail('not_a_member', { status: 403, message: 'Join the goal (or be an Archon) to widen its scope.' });
+      }
+      const updated = await db.addGoalScopeModules({ goalId: id, modules: add });
+      return res.json({ ok: true, goal: updated });
+    } catch (err) {
+      console.error('[gds] POST /goals/:id/scope', err);
+      return res.fail('scope_widen_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /goals/:id/tasks — bounded task authoring within a goal's scope
+  // (BV1.R60 / ADR 0086 §3). THE ENFORCEMENT KEYSTONE of the goal-scoped work
+  // hierarchy: the one route that lets a member (even a sub-Metic one) author
+  // their OWN work — bounded by the goal's module wall, and never able to mint
+  // work they couldn't otherwise be trusted to claim.
+  //
+  // requireBuilder + the in-handler, ORDERED, FAIL-CLOSED gate
+  // (authorizeGoalTaskCreate above). On pass, db.createTask stamps goal_id with
+  // requires_rank AUTO-DERIVED (ADR 0084) — NEVER taken from client input: a
+  // protected/sensitive task auto-floors to Metic, so a sub-Metic author simply
+  // cannot claim it (there is no self-granted escape). The task's version is the
+  // GOAL's version (never client-supplied) and it is born 'ready' so the author
+  // can immediately claim + work it — the maneuverability grant (the scope wall +
+  // auto-rank-floor already bound WHAT they may create). One-level sub-tasks
+  // attach via hierarchy.attachParent (the depth-cap + version-match authority),
+  // constrained to the SAME goal.
+  //
+  // rank: any-builder (requireBuilder) + goal membership + the scope wall. Pinned
+  // in route-rank-check.EXPECTED_RANKS['lifecycle'] by BV1.R61.
+  router.post('/goals/:id/tasks', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_goal_id' });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      title: { required: true, type: 'string', minLength: 1, maxLength: LIMITS.TITLE },
+      description: { type: 'string', maxLength: LIMITS.DESCRIPTION },
+      // touches[] is REQUIRED — it is the blast radius the scope wall checks. A
+      // task with no declared touches can't be bounded to the goal, so the pure
+      // check() denies it too (empty_touches); requiring it gives a clean 400 up
+      // front rather than a 403.
+      touches: { required: true, type: 'array', maxItems: 500, itemsType: 'string' },
+      est_minutes: { type: 'integer', min: 0, max: 100000 },
+      priority: { type: 'integer', min: TASK_FIELD_BOUNDS.priority.min, max: TASK_FIELD_BOUNDS.priority.max },
+      kind: { type: 'string', maxLength: 64 },
+      discipline: { type: 'string', maxLength: 64 },
+      value_summary: { type: 'string', maxLength: LIMITS.VALUE_SUMMARY },
+      parent_task_id: { type: 'integer', min: 1 },
+      // Deliberately NOT read from the client (validateOrRespond ignores unknown
+      // fields, so any of these a client smuggles in are simply never used):
+      //   • version_id  — derived from the goal (a member can't author cross-version);
+      //   • requires_rank — AUTO-derived (ADR 0084); this is the self-raised-rank
+      //     escape the whole model exists to prevent, so the route never forwards it;
+      //   • status      — server-set to 'ready';
+      //   • security_sensitive / module_key — out of R60 scope.
+    })) return;
+
+    const body = req.body || {};
+    const touches = Array.isArray(body.touches) ? [...body.touches] : [];
+
+    try {
+      // Fetch the inputs the ordered gate consults. version is the GOAL's version
+      // (never client input). The couple of extra indexed reads on a reject path
+      // are immaterial and keep the whole decision in ONE testable place.
+      const goal = await db.getGoal(id);
+      const isMember = goal ? await isMemberOrArchon(req.builder, id) : false;
+      const version = goal ? await db.getVersion(goal.version_id) : null;
+
+      const decision = authorizeGoalTaskCreate({
+        goal, version, isMember, builderRank: req.builder.rank, touches,
+      });
+      if (!decision.ok) {
+        return res.status(decision.status).json(decision.body);
+      }
+
+      // One-level sub-task (optional). Validate the parent BEFORE creating
+      // anything, so a bad parent is a clean 4xx with no orphan task: it must
+      // exist, live in THIS goal (containment — a member can't graft work onto
+      // another goal's tree), and not itself be a sub-task (the depth cap; a fresh
+      // task can have no children, so that half is trivially met).
+      const parentTaskId = body.parent_task_id ?? null;
+      if (parentTaskId !== null) {
+        const parent = await db.getTask(parentTaskId);
+        if (!parent) {
+          return res.fail('parent_not_found', { status: 404, message: `No task #${parentTaskId} to attach under.` });
+        }
+        if (String(parent.goal_id ?? '') !== String(goal.id)) {
+          return res.fail('parent_outside_goal', { status: 400, message: `Parent task #${parentTaskId} is not part of this goal — a sub-task attaches to a parent within the same goal.` });
+        }
+        if (parent.parent_task_id !== null) {
+          return res.fail('parent_has_parent', { status: 409, message: `Task #${parentTaskId} is already a sub-task — the hierarchy is one level deep (ADR 0086 §2).` });
+        }
+      }
+
+      // Resolve kind/discipline like POST /tasks — a goal-authored task is a
+      // first-class task, so classify it for routing/reward. Caller wins if valid;
+      // otherwise the heuristic (confidence < 0.5 → 'unclassified' for triage).
+      let kind = body.kind;
+      if (kind && !VALID_KINDS.has(kind)) {
+        return res.fail('bad_kind', 400, { valid: Array.from(VALID_KINDS) });
+      }
+      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) });
+      }
+
+      // Create. version = the goal's (not client-supplied); status 'ready' so the
+      // author can claim it immediately; requiresRank OMITTED → auto-derived
+      // (ADR 0084), so a protected/sensitive task floors to Metic and a sub-Metic
+      // author cannot claim it. goal_id is stamped. credits_reward omitted →
+      // auto-assigned at creation (ADR 0096).
+      const task = await db.createTask({
+        versionId: goal.version_id,
+        title: body.title,
+        description: body.description || '',
+        status: 'ready',
+        touches,
+        estMinutes: body.est_minutes ?? null,
+        priority: body.priority ?? null,
+        valueSummary: body.value_summary ?? null,
+        kind,
+        discipline,
+        source: 'goal-authored',
+        goalId: goal.id,
+      });
+
+      // Attach the sub-task parent (validated above; attachParent re-checks the
+      // depth cap + version match atomically under row locks — the authority). A
+      // failure here is a rare race (parent gained a parent / was deleted between
+      // the pre-check and the attach): the task exists as a top-level goal task, so
+      // surface the attach failure honestly rather than pretend success.
+      let attachedParentId = null;
+      if (parentTaskId !== null) {
+        try {
+          const updated = await hierarchy.attachParent(task.id, parentTaskId);
+          attachedParentId = updated.parent_task_id != null ? Number(updated.parent_task_id) : null;
+        } catch (err) {
+          console.error('[gds] POST /goals/:id/tasks attachParent', err);
+          return res.fail('parent_attach_failed', { status: 409, message: `Task #${task.id} was created under the goal, but attaching it under parent #${parentTaskId} failed (${(err && err.code) || 'unknown'}).`, details: { code: err && err.code, task } });
+        }
+      }
+
+      return res.status(201).json({
+        ok: true,
+        task,
+        goal_id: goal.id,
+        parent_task_id: attachedParentId,
+        credits_reward: task.credits_reward,
+        requires_rank: task.requires_rank,
+      });
+    } catch (err) {
+      console.error('[gds] POST /goals/:id/tasks', err);
+      return res.fail('goal_task_create_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};
+
+// BV1.R60 / ADR 0086 §3: the pure ordered gate for POST /goals/:id/tasks —
+// exported for tests/goal_routes.mjs (DB-free) and the BV1.R61 abuse matrix, and
+// for reuse. The shouldRefuseSessionClaim (claims.js) precedent.
+module.exports.authorizeGoalTaskCreate = authorizeGoalTaskCreate;
+// task 1735: the pure ordered gates for PATCH /goals/:id/members/:builderId and
+// POST /goals/:id/transfer — exported for tests/goal_member_roles.mjs (DB-free),
+// same precedent.
+module.exports.authorizeMemberRoleChange = authorizeMemberRoleChange;
+module.exports.authorizeOwnershipTransfer = authorizeOwnershipTransfer;
+// task 1736: the shared management prefix gate (conflict resolution) —
+// exported for tests/goal_conflicts.mjs (DB-free), same precedent.
+module.exports.authorizeGoalManagement = authorizeGoalManagement;
+module.exports.RESOLVE_ACTIONS = RESOLVE_ACTIONS;
+// task 1952 / ADR 0112: the private-goal invite/join-request pure gates +
+// the shared protected-scope admission rule — exported for
+// tests/goal_membership_requests.mjs (DB-free), same precedent.
+module.exports.protectedScopeAdmissionBlock = protectedScopeAdmissionBlock;
+module.exports.authorizeCreateJoinRequest = authorizeCreateJoinRequest;
+module.exports.authorizeInvitationResponse = authorizeInvitationResponse;
+module.exports.authorizeJoinRequestResponse = authorizeJoinRequestResponse;