@bongos/core 1.19.715 → 1.19.724

package/modules/lifecycle/db-overrides.js

@@ -19,15 +19,66 @@ const { mostRecentClaimHolderId } = require('./db-shared.js');
 // believes the grader was wrong and asks an Archon to confirm anyway.
 
 
+// THE SECOND THING AN OVERRIDE REQUEST CAN BE (task 1003575, ADR 0241 §3).
+//
+// The original request is a GRADER BYPASS: a `completed` task whose ship the
+// subagent panel rejected, flipped to `confirmed` and paid. ADR 0241 needed an
+// escape hatch for a different refusal — a deploy held by an unresolved artist
+// review — and was explicit that it must be "the mechanism that already exists…
+// no new machinery, no second authority path". So it is the SAME table, the same
+// request flow and the same decide endpoint; only the target class and the effect
+// of an approval differ.
+//
+// A GATE RELEASE differs from a grader bypass in three ways, and each one is the
+// reason it could not simply reuse the existing path unchanged:
+//
+//   • Its target is NOT at 'completed'. An artist review sits at `backlog` and
+//     usually always will — ADR 0241 guard #4 calls "a strict project with no
+//     artist" the normal case for a new instance. The completed-only check below
+//     would have made the one documented escape hatch unusable for the exact
+//     scenario it was written for.
+//   • Approving it CONFIRMS NOTHING AND PAYS NOTHING. A released review is still
+//     an open request on the board; what the release buys is that it stops
+//     holding the pin. Flipping it to `confirmed` and crediting it would pay for
+//     work nobody did and erase the request.
+//   • Only the PROJECT OWNER may decide it (§3, owner ruling: not the builder,
+//     not any Metic+, not the artist) — a narrower gate than the Archon floor the
+//     grader bypass carries, enforced here rather than only at the route so no
+//     second caller can widen it.
+//
+// Whether a task is in this class is asked of core's ONE artist-gate reader, so
+// "is this an unresolved artist review" has the same answer here, at the deploy
+// gate and in the cascade that files them.
+function gateReleaseTarget(taskRow) {
+  const gate = api.artistGate;
+  return gate.isArtistReview(taskRow) && !gate.isReviewResolved(taskRow);
+}
+
+// WHO is asked "who owns this project?" — and the answer is the doorway unless we
+// are demonstrably in a test. Same NODE_ENV gate as the `deps.pool` seam below,
+// and for a sharper version of its reason (#538): this reader decides who may
+// release a deploy-blocking review, so a future caller that forwarded an options
+// object carrying a `getFoundingBuilder` key — a batch decide path, a CLI helper,
+// a careless refactor — would otherwise silently swap out the owner check in
+// production. Pure over its inputs, so the gate itself is unit-testable without a
+// database (which the decide path, holding a transaction, is not).
+function resolveOwnerReader(deps = {}, env = process.env) {
+  return (typeof deps.getFoundingBuilder === 'function' && env.NODE_ENV === 'test')
+    ? deps.getFoundingBuilder
+    : api.getFoundingBuilder;
+}
+
+const OVERRIDE_TASK_COLUMNS = 'id, status, source, source_ref, merged_into_task_id';
+
 async function createOverrideRequest({ taskId, requesterId, rationale }) {
   const { rows: taskRows } = await pool.query(
-    `SELECT id, status FROM tasks WHERE id = $1`,
+    `SELECT ${OVERRIDE_TASK_COLUMNS} FROM tasks WHERE id = $1`,
     [taskId]
   );
   if (taskRows.length === 0) {
     throw Object.assign(new Error('task not found'), { code: 'TASK_NOT_FOUND' });
   }
-  if (taskRows[0].status !== 'completed') {
+  if (taskRows[0].status !== 'completed' && !gateReleaseTarget(taskRows[0])) {
     throw Object.assign(new Error('task not in completed state'), {
       code: 'TASK_NOT_COMPLETED',
       currentStatus: taskRows[0].status,
@@ -83,6 +134,30 @@ async function decideOverrideRequest({ requestId, archonId, decision, note }, de
   // (same pattern as credit_grant.mjs). Production callers omit it → module pool.
   const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
   return withTx(async (client) => {
+    // Which KIND of override this is — decided from the target task, before the
+    // request row is touched, because the two classes differ in who may decide
+    // them and in what an approval does. See gateReleaseTarget above.
+    const { rows: targetRows } = await client.query(
+      `SELECT ${OVERRIDE_TASK_COLUMNS} FROM tasks
+         WHERE id = (SELECT task_id FROM task_override_requests WHERE id = $1)`,
+      [requestId]
+    );
+    const isGateRelease = targetRows.length > 0 && gateReleaseTarget(targetRows[0]);
+
+    // THE NARROWER GATE (ADR 0241 §3). The grader bypass admits any Archon; a
+    // gate release admits the PROJECT OWNER and nobody else — "not the builder,
+    // not any Metic+, and not the artist" is the owner's own wording, and the
+    // reason it is here rather than only at the route is that a second caller
+    // (a CLI, a future surface) would otherwise inherit the wider Archon floor.
+    if (isGateRelease) {
+      const owner = await resolveOwnerReader(deps)();
+      if (!owner || String(owner.id) !== String(archonId)) {
+        throw Object.assign(new Error('only the project owner may release an artist gate'), {
+          code: 'OVERRIDE_OWNER_ONLY',
+        });
+      }
+    }
+
     // RETURNING requested_by_builder_id so the approve path doesn't re-read the
     // row it just locked (#538): the work was the ORIGINAL REQUESTER's, and both
     // the credit AND the ship attribution must go to them.
@@ -102,7 +177,41 @@ async function decideOverrideRequest({ requestId, archonId, decision, note }, de
     const row = rows[0];
 
     let confirmResult = null;
-    if (decision === 'approve') {
+    let gateRelease = null;
+    if (decision === 'approve' && isGateRelease) {
+      // A RELEASE CONFIRMS NOTHING AND PAYS NOTHING. The approved request row IS
+      // the release — the deploy gate reads it and stops holding — and the review
+      // stays an ordinary open request on the board, because the work it asks for
+      // has not been done. Anything else here would pay for work nobody did.
+      //
+      // And it is NEVER QUIET (ADR 0241 §3). A self-release — the owner releasing
+      // a review filed against their own work, which on a solo instance is the
+      // normal case and is deliberately PERMITTED rather than impossible — is
+      // recorded as such, so the ledger shows who waved what through and why.
+      // The rationale already lives on the request row; this names the act.
+      const selfOverride = String(row.requested_by_builder_id) === String(archonId);
+      gateRelease = { taskId: String(row.task_id), selfOverride };
+      const writeAudit = deps.insertAuditLog || api.insertAuditLog;
+      // Best-effort: the release is durable in the request row, and losing the
+      // audit line must not roll back a decision the owner made. A failure here
+      // is loud in the logs rather than silent.
+      try {
+        await writeAudit({
+          builderId: archonId,
+          route: '/api/bongos/override-requests/:id/decide',
+          method: 'POST',
+          requestBodyRedacted: {
+            override_kind: 'artist_gate_release',
+            self_override: selfOverride,
+            task_id: String(row.task_id),
+            request_id: String(row.id),
+          },
+          responseStatus: 200,
+        });
+      } catch (e) {
+        api.logger('lifecycle').error(`[override] artist-gate release ${row.id}: audit write failed — ${e && e.message}`);
+      }
+    } else if (decision === 'approve') {
       // BOTH the credit AND the ship attribution (shipped_by, which drives the
       // builders' hall + peer-vote feed) go to the builder who actually DID the
       // work — the task's most-recent claim holder — never the approving Archon.
@@ -162,7 +271,7 @@ async function decideOverrideRequest({ requestId, archonId, decision, note }, de
       }
     }
 
-    return { request: row, confirmResult };
+    return { request: row, confirmResult, gateRelease };
   }, { pool: activePool });
 }
 
@@ -178,4 +287,8 @@ module.exports = {
   createOverrideRequest,
   decideOverrideRequest,
   listOverrideRequests,
+  // pure — exported so the release class and its authority seam can be asserted
+  // without a database (the decide path itself holds a transaction and cannot be)
+  gateReleaseTarget,
+  resolveOwnerReader,
 };

package/modules/lifecycle/db-tasks.js

@@ -1037,6 +1037,68 @@ async function updateTaskStatus(id, status) {
   await pool.query(`UPDATE tasks SET status = $2 WHERE id = $1`, [id, status]);
 }
 
+// The cascade-filed ARTIST REVIEW rows that are still open (ADR 0241, task
+// 1003575) — the state the deploy gate reads. Narrow projection on purpose: the
+// caller needs an id and a filing date to name what holds a deploy and to apply
+// the non-retroactivity cutoff, and nothing else belongs on that wire. The TITLE
+// is deliberately absent: it is builder-written text, nothing consumes it, and a
+// value that is safe as JSON today is an injection vector the first time a
+// surface renders it as HTML.
+//
+// THIS IS A PRE-FILTER, NOT THE RULE. The SQL narrows to "cascade artist reviews
+// that are not obviously finished"; the authoritative verdict — including ADR
+// 0241 §5's non-retroactivity cutoff — is src/bongos/artist-gate.js's pure
+// `unresolvedArtistReviews`, so the definition of "unresolved" lives in exactly
+// one place and a change to it cannot land in the JS and miss the SQL. The
+// pre-filter is deliberately the LOOSER of the two: a row it lets through is
+// re-judged, a row it drops is never seen again.
+//
+// The (source, source_ref) shape is the cascade's own (modules/lifecycle/
+// cascade.js `cascadeSourceRef`) and is passed IN rather than spelled here, so
+// this query cannot drift from the rule that files the rows.
+//
+// AN APPROVED OVERRIDE REQUEST IS A RELEASE (ADR 0241 §3, db-overrides.js): the
+// project owner has waved this review past, with a rationale and an audit line,
+// so it no longer holds a deploy. It is still an open request on the board — the
+// release buys the pin, not the work — which is why this is excluded HERE rather
+// than by changing the task's status.
+//
+// Indexed by `idx_tasks_source_ref` (core_240): without it this is a
+// sequential scan of `tasks` on a route any builder can call and every deploy
+// does call.
+//
+// THE CAP CANNOT WEAKEN THE GATE, and it is worth saying why rather than leaving
+// a reader to work it out. Every row this returns is a HOLDER — resolved and
+// released reviews are excluded in SQL — so a project with more open reviews than
+// the cap still gets a held verdict from the first one. What truncation can
+// affect is the COUNT in the refusal, so the caller is told when it happened
+// (`truncated`) and says "200+" rather than a number it cannot stand behind.
+// Oldest-first is the right order for the same reason: the cutoff is a date, so
+// the rows nearest the gate's own boundary are the ones kept.
+const ARTIST_REVIEW_SCAN_LIMIT = 200;
+
+async function listOpenArtistReviews({ source, refPrefix, resolvedStatuses = [], limit = ARTIST_REVIEW_SCAN_LIMIT } = {}) {
+  if (!source || !refPrefix) return { reviews: [], truncated: false };
+  const cap = Math.max(1, Math.min(1000, Number(limit) || ARTIST_REVIEW_SCAN_LIMIT));
+  const { rows } = await pool.query(
+    `SELECT id, status, source, source_ref, created_at, merged_into_task_id
+       FROM tasks t
+      WHERE t.source = $1
+        AND t.source_ref LIKE $2
+        AND t.merged_into_task_id IS NULL
+        AND NOT (t.status = ANY($3::text[]))
+        AND NOT EXISTS (
+              SELECT 1 FROM task_override_requests r
+               WHERE r.task_id = t.id AND r.status = 'approved')
+      ORDER BY t.created_at ASC
+      LIMIT $4`,
+    // cap + 1: one row past the cap is how "there are more" is learned without a
+    // second COUNT query that could disagree with the page it describes.
+    [source, `${refPrefix}%`, resolvedStatuses, cap + 1]
+  );
+  return { reviews: rows.slice(0, cap), truncated: rows.length > cap };
+}
+
 module.exports = {
   CREDITS_AWARDED_SUBQUERY,
   REWARD_SUGGESTION_CAP,
@@ -1047,6 +1109,7 @@ module.exports = {
   getTask,
   listActiveClaims,
   listClaimableTasks,
+  listOpenArtistReviews,
   listTasks,
   rankCrossDisciplineRecommendations,
   rewardGateAssignment,

package/modules/lifecycle/migrations/lifecycle_001_goal_first_leads.sql

@@ -1,7 +1,7 @@
 -- lifecycle_001_goal_first_leads.sql — backfill goal OWNERS into the member list
 -- (task 1735). The goal authority model: the OWNER is goals.created_by (fixed at
--- create, moved only by POST /goals/:id/transfer); goal_members.role 'lead' is
--- the MANAGER tier the hall renders. From now on db.createGoal inserts the
+-- create, moved only by POST /goals/:id/transfer); goal_members.membership_kind
+-- 'lead' is the MANAGER tier the hall renders. From now on db.createGoal inserts the
 -- creator's lead row atomically; this brings the goals created before that rule
 -- up to the same shape so owners appear in their own member lists.
 --
@@ -13,14 +13,22 @@
 -- Data-only (no schema change), idempotent (the upsert converges), and
 -- replay-safe on a fresh DB (zero goals → zero rows; no builder id is
 -- hard-coded — learning 1238).
+--
+-- THE COLUMN IS `membership_kind` (task 1003089, ADR 0177). This file wrote the
+-- legacy `role` until core_240 dropped it, and it is the reason that DROP was not
+-- a pure deletion: module migrations run AFTER the core ones on every fresh
+-- install, so a stale name here would have broken `cloudbongos init` for new
+-- instances while staying invisible on existing ones (already recorded in
+-- `schema_migrations`, so never re-run). Zero-row on a fresh DB, but a missing
+-- column is a plan-time error, not a row-time one.
 
 BEGIN;
 
-INSERT INTO goal_members (goal_id, builder_id, role)
+INSERT INTO goal_members (goal_id, builder_id, membership_kind)
 SELECT g.id, g.created_by, 'lead'
   FROM goals g
  WHERE g.created_by IS NOT NULL
-ON CONFLICT (goal_id, builder_id) DO UPDATE SET role = 'lead';
+ON CONFLICT (goal_id, builder_id) DO UPDATE SET membership_kind = 'lead';
 
 INSERT INTO schema_migrations (version) VALUES ('lifecycle_001_goal_first_leads')
   ON CONFLICT (version) DO NOTHING;

package/modules/lifecycle/module.json

@@ -25,7 +25,8 @@
       "visuals",
       "kickoff-seed",
       "rot",
-      "project-settings"
+      "project-settings",
+      "artist-gate"
     ],
     "pollers": [
       "publish-reconciler"

package/modules/lifecycle/pg-constraint-fail.js

@@ -0,0 +1,49 @@
+// modules/lifecycle/pg-constraint-fail.js — turn a Postgres CHECK violation into a
+// 400 that names the constraint, instead of an opaque 500 (task 1002845).
+//
+// WHY. A range the route validator accepts but the DB CHECK rejects is a
+// self-inflicted wound: the INSERT raises SQLSTATE 23514, the generic catch logs
+// it server-side and answers `create_failed` / "internal error", and the caller —
+// an agent, usually — has no idea which field was wrong. Idea 1000456 records
+// roughly four blind retries spent on exactly that during task 1604, and task
+// 1002845 measured it still happening: POST /tasks {manual_degree:0} → 500
+// "internal error".
+//
+// The first fix is always to make the validator match the DB so the INSERT never
+// sees a bad value (task 1233 did that for `priority`; task 1002845 for
+// `manual_degree`). This is the BACKSTOP for the next mismatch nobody has found
+// yet — it cannot know which field is at fault, but the constraint name says so.
+//
+// WHAT IS SAFE TO ECHO. `err.constraint` only — a schema identifier the operator
+// wrote, carrying no request or row data. NEVER `err.detail`: Postgres puts the
+// offending ROW VALUES in it ("Failing row contains (1, secret, ...)"), so echoing
+// it would leak other columns of the caller's own record into an error body, and
+// on a shared instance potentially values the caller never sent.
+
+'use strict';
+
+// Postgres SQLSTATE for a CHECK constraint violation.
+const CHECK_VIOLATION = '23514';
+
+// describeCheckViolation(err) → { code, status, message, details } | null
+//
+// Pure. Returns null for anything that is not a CHECK violation, so a caller can
+// use it as a guard and fall through to its existing generic handling.
+function describeCheckViolation(err) {
+  if (!err || err.code !== CHECK_VIOLATION) return null;
+  const constraint = typeof err.constraint === 'string' && err.constraint.trim()
+    ? err.constraint.trim()
+    : null;
+  return {
+    code: 'constraint_violation',
+    status: 400,
+    message: constraint
+      // Deliberately does not guess WHICH field: one CHECK can span several
+      // columns, and naming the wrong one is worse than naming none.
+      ? `a value in this request violates the database constraint "${constraint}" — check the field it guards against the accepted range`
+      : 'a value in this request violates a database constraint',
+    details: { constraint },
+  };
+}
+
+module.exports = { describeCheckViolation, CHECK_VIOLATION };

package/modules/lifecycle/routes/artist-gate.js

@@ -0,0 +1,101 @@
+'use strict';
+
+// modules/lifecycle/routes/artist-gate.js — the artist gate's STATE, in one read
+// (ADR 0241, task 1003575).
+//
+// WHY A ROUTE. The gate's two halves live on opposite sides of the wire. The
+// POLICY (`artist_gate`) is pushed into this instance's branding pack by the
+// platform and read by the core; the STATE it reads — which artist review tasks
+// are still open — is this instance's own board. The thing that has to consult
+// both is `scripts/gds/go-live.js`, the pin move, which runs from a core checkout
+// against a LIVE instance and can see neither from where it stands. So the
+// instance answers the question about itself, in one call, and the deploy script
+// decides what to do with the answer.
+//
+// IT DECIDES NOTHING AND HOLDS NOTHING. This route is a read: it reports the mode,
+// the open reviews and the halt sentence that would be shown. Nothing about a ship,
+// a land or a grade passes through here — ADR 0241's whole reconciliation with ADR
+// 0162 is that the artist's authority attaches to the DEPLOY, and a read surface
+// that could reach the ship path would smuggle that back in.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway
+// `../../../src/module-api` (which carries the one artist-gate reader); `../db` is
+// this module's own data layer.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const db = require('../db');
+
+const log = api.logger('lifecycle');
+
+module.exports = function buildArtistGateRouter() {
+  const router = express.Router();
+
+  // GET /artist-gate — this project's artist strictness and what it is holding.
+  //
+  // rank: any authenticated builder. The payload is ordinary board state — a
+  // policy value the instance already publishes as its own behaviour, and task
+  // ids/titles any builder can read on the hall — so a floor above requireBuilder
+  // would gate a fact the board already shows. Nothing here is writable.
+  //
+  // Response:
+  //   mode      'off' | 'advisory' | 'strict'  the project's setting as resolved
+  //   since     ISO string | null              when it was last RAISED to strict
+  //   holds     boolean                        does anything hold a deploy now?
+  //   truncated boolean                        `reviews` hit the scan cap — a floor
+  //   reviews   [{ id, created_at }]           the open reviews that count
+  //   halt      { code, message, detail } | null   the refusal, pre-composed
+  //
+  // `halt` is composed HERE rather than by the caller on purpose: ADR 0241 §4's
+  // second guard is that the refusal must name what holds the deploy and which
+  // control releases it, and a sentence assembled independently by each caller is
+  // a sentence that eventually says something different. One composer, one wording.
+  router.get('/artist-gate', api.requireBuilder, async (req, res) => {
+    try {
+      const gate = api.artistGate;
+      const mode = gate.artistGateMode();
+      const since = gate.artistGateSince();
+
+      // At 'off' no reviews are filed, so there is nothing to read and nothing to
+      // hold — answer without touching the database.
+      const scan = mode === 'off' ? { reviews: [], truncated: false } : await db.listOpenArtistReviews({
+        source: gate.ARTIST_REVIEW_SOURCE,
+        refPrefix: gate.ARTIST_REVIEW_REF_PREFIX,
+        resolvedStatuses: gate.RESOLVED_REVIEW_STATUSES,
+      });
+      const open = gate.unresolvedArtistReviews(scan.reviews, { since });
+      // `truncated` only survives if the cutoff did not itself empty the page:
+      // reporting "200+" over a list the non-retroactivity filter cut to three
+      // would be a worse lie than the number it replaced.
+      const truncated = scan.truncated && open.length === scan.reviews.length;
+      const halt = gate.artistGateHalt({ mode, reviews: open, truncated });
+
+      // A gate read is a policy comparison — a cached one is wrong the moment a
+      // review is dismissed (the project-settings / rot.js precedent).
+      res.set('Cache-Control', 'no-store');
+      res.json({
+        ok: true,
+        mode,
+        since,
+        holds: !!halt,
+        // A floor, not a census, when the scan hit its cap — said out loud so a
+        // caller never reads this list as "and that is all of them".
+        truncated,
+        // IDS AND DATES ONLY — deliberately no TITLE. A title is builder-written
+        // board text, and it was the only untrusted string this payload carried;
+        // nothing consumes it (go-live names ids, and a reader who wants the title
+        // has the board). Carrying it would have left a value that is safe as JSON
+        // today and becomes an injection vector the first time some surface renders
+        // it as HTML. Dropping it is the fix rather than escaping it, because an
+        // HTML-escaped value in a JSON API is wrong for every correct consumer.
+        reviews: open.map((t) => ({ id: String(t.id), created_at: t.created_at })),
+        halt,
+      });
+    } catch (err) {
+      log.error('[lifecycle] GET /artist-gate', err);
+      res.fail('artist_gate_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};

package/modules/lifecycle/routes/claims.js

@@ -85,9 +85,21 @@ function taskNotReadyHint(taskId, currentStatus) {
 // Ordering is the fix: the universally-available command leads, /merge-mode is
 // marked as needing a push credential rather than dropped (it is still the right
 // tool on a credentialed machine), and /builder-release stays as the give-up exit.
+//
+// AND THE VERB CHANGED (task 1002788). It used to say "rebase the branch and
+// re-ship", which is advice that can DEADLOCK the builder who follows it. The
+// branch is already published; server-mediated publish is append-only by
+// deliberate design (github-push.js: "Refuse non-fast-forward implicitly (no
+// --force, ever)"), so a rebase rewrites history the server already holds and
+// every subsequent publish is rejected non-fast-forward. The builder is then
+// gated from new claims AND unable to land the one they hold. Reproduced
+// end-to-end on task 1002485. `git merge origin/main` reaches the same
+// up-to-date branch and stays a fast-forward, which is why the recovery text in
+// ship-land.js already names merge and explicitly says "Do NOT reset or
+// re-rebase". This is the same advice, given BEFORE the deadlock instead of after.
 function rebaseRequiredHint(rebaseTasks) {
   const ids = (rebaseTasks || []).map((t) => `task ${t.id}`);
-  return `Your queue is gated: ${ids.length} confirmed task(s) await your rebase (${ids.join(', ') || 'unknown'}). Clear it with /strand-fix N (works on any machine), or rebase the branch and re-ship — /merge-mode only if this machine has a GitHub push credential. To give up on one instead, /builder-release it. If CI is simply backed up, waiting is correct: a task already landed clears the gate on its own.`;
+  return `Your queue is gated: ${ids.length} confirmed task(s) are waiting to land (${ids.join(', ') || 'unknown'}). Clear it with /strand-fix N (works on any machine), or bring the branch up to date with \`git merge origin/main\` and re-ship — MERGE, never rebase: server-mediated publish is append-only, and rewriting a published branch makes it un-pushable (task 1002788). /merge-mode only if this machine has a GitHub push credential. To give up on one instead, /builder-release it. If CI is simply backed up, waiting is correct: a task already landed clears the gate on its own.`;
 }
 
 // task 1642 (+ the worktree-keying fix) — the pure one-active-claim decision.

package/modules/lifecycle/routes/lifecycle.js

@@ -54,6 +54,12 @@ function registerSeams() {
     getTask: (id) => db.getTask(id),
     findTaskBySourceRef: (ref) => db.findTaskBySourceRef(ref),
     createTask: (spec) => db.createTask(spec),
+    // The project's artist gate (ADR 0241, task 1003575). Resolved through the
+    // doorway's one reader rather than from branding().project, so the level that
+    // decides whether a review is FILED and the level that decides whether one
+    // HOLDS a deploy can never be read differently. At 'off' the artist-review
+    // rule files nothing.
+    artistGateMode: () => api.artistGate.artistGateMode(),
     log: api.logger ? api.logger('lifecycle') : null,
   }));
 }

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

@@ -26,6 +26,7 @@ const { classifyTaskKind, VALID_KINDS, VALID_DISCIPLINES, VOTABLE_TASK_STATUSES,
 const { isModuleKey, moduleKeys } = api.moduleScopeMap;
 const { validateOrRespond, LIMITS, parseId } = api;
 const { badKind, detectsMigration } = require('./task-route-helpers.js');
+const { describeCheckViolation } = require('../pg-constraint-fail.js');
 const { goalNotOpenRefusal } = require('./goal-route-authz.js');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
 const log = api.logger('lifecycle');
@@ -275,6 +276,12 @@ module.exports = function registerTaskWriteRoutes(router) {
       });
     } catch (err) {
       log.error('[gds] POST /tasks', err);
+      // task 1002845: a CHECK violation is a CLIENT-correctable problem wearing a
+      // 500. Name the constraint so the next validator/DB range mismatch is
+      // self-diagnosing instead of costing another round of blind retries. The
+      // constraint name only — err.detail carries the failing row's values.
+      const cv = describeCheckViolation(err);
+      if (cv) return res.fail(cv.code, { status: cv.status, message: cv.message, details: cv.details });
       res.fail('create_failed', { status: 500, message: 'internal error' });
     }
   });

package/modules/lifecycle/routes/tasks.js

@@ -997,6 +997,12 @@ module.exports = function buildTasksRouter() {
   // asks an Archon to flip the task to confirmed anyway. Audit-logged via the
   // global write-audit middleware. Open requests surface in the Archon queue.
   // rank: any-builder — opens a request; the decision still rests with Archon.
+  //
+  // The SAME route also opens the artist gate's release (ADR 0241 §3, task
+  // 1003575): a request whose target is an unresolved artist review is admitted
+  // at ANY status, because such a review sits at `backlog` and a completed-only
+  // check would make the one documented escape hatch unusable for the exact case
+  // it was written for. Who may DECIDE it is narrower — see the decide route.
   router.post('/tasks/:id/override-request', auth.requireBuilder, async (req, res) => {
     const id = parseId(req, res, { code: 'bad_task_id' });
     if (id === null) return;
@@ -1328,6 +1334,14 @@ module.exports = function buildTasksRouter() {
   // updates; the task stays at completed and the builder must release or
   // re-ship after fixing whatever the grader caught.
   // rank: archon — grader-bypass authority; same gate as POST /tasks/:id/confirm.
+  //
+  // ONE EXCEPTION, and it is NARROWER than this gate rather than wider: a request
+  // whose target is an unresolved ARTIST REVIEW is a gate release (ADR 0241 §3,
+  // db-overrides.js), and only the PROJECT OWNER may decide it. That check lives
+  // in decideOverrideRequest, not here, so it cannot be bypassed by a second
+  // caller; this route only renders its refusal (403 override_owner_only).
+  // Approving one confirms nothing and pays nothing — it stops the review holding
+  // the DEPLOY and leaves it open on the board.
   router.post('/override-requests/:id/decide', auth.requireBuilder, auth.requirePermission('override_request.decide'), async (req, res) => {
     const id = parseId(req, res, { code: 'bad_request_id' });
     if (id === null) return;
@@ -1351,6 +1365,16 @@ module.exports = function buildTasksRouter() {
       if (err.code === 'REQUEST_NOT_OPEN') {
         return res.fail('request_not_open', 409);
       }
+      if (err.code === 'OVERRIDE_OWNER_ONLY') {
+        // The artist gate's release is narrower than this route's Archon floor
+        // (ADR 0241 §3): the PROJECT OWNER decides it, nobody else. 403 with the
+        // reason spelled out — an Archon refused here is not a bug, and a refusal
+        // that does not say which authority is missing sends them hunting.
+        return res.fail('override_owner_only', {
+          status: 403,
+          message: 'Releasing a deploy held by an artist review is the project owner\'s call alone — not an Archon\'s (ADR 0241). Resolve or dismiss the review instead, or ask the owner to decide this request.',
+        });
+      }
       if (err.code === 'OVERRIDE_NO_REQUESTER') {
         // Data-integrity guard (#538): an approved override with no requester to
         // credit. Should never happen (NOT NULL column); refuse rather than

package/modules/lifecycle/task-classifier.js

@@ -173,9 +173,18 @@ const VALID_DISCIPLINES = new Set(['engineer', 'artist', 'ideator', 'ui', 'uncla
 // `create_failed` constraint-violation message, and taught the context pack the
 // wrong range — task 1233.) `convention` is retained so the pack can surface the
 // human-facing "use P1–P5 tiers" label alongside the accepted range.
+// task 1002845: `manual_degree` had the SAME defect priority had, and is fixed the
+// same way — tighten the validator to the DB, never migrate the DB to the
+// validator. The CHECK is `manual_degree BETWEEN 1 AND 5`
+// (migrations/003_pms.sql, never widened since), so min:0 let a 0 pass the route
+// and then die in the INSERT as a 23514, which the generic catch answered as an
+// opaque 500 `create_failed` with the constraint name never reaching the caller.
+// Measured against the live API before the fix: POST /tasks {manual_degree:0}
+// → 500 "internal error". Idea 1000456 records roughly four blind retries spent
+// on this during task 1604.
 const TASK_FIELD_BOUNDS = {
   priority: { min: 1, max: 5, convention: { min: 1, max: 5, label: 'P1–P5 planning tiers' } },
-  manual_degree: { min: 0, max: 5 },
+  manual_degree: { min: 1, max: 5 },
 };
 
 // Task statuses that can receive peer-acclaim votes (a work must be at least

package/modules/lifecycle/tests/cascade.mjs

@@ -250,5 +250,48 @@ await test('the review inherits the shipped task goal and version, not goal 1000
   assert.equal(matched[0].spec.versionId, 'BONGOS-V1');
 });
 
+// --- the project's artist gate decides whether it is filed at all (ADR 0241) --
+
+await test("artist_gate 'off' files NO artist review — the one level at which the rule is silent", () => {
+  assert.equal(cascade.cascadesFor(shippedCopy(), cascade.CASCADES, { artistGate: 'off' }).matched.length, 0);
+  // The other two levels both FILE; what separates them is whether an open review
+  // holds a deploy, which is not this file's business at all.
+  assert.equal(cascade.cascadesFor(shippedCopy(), cascade.CASCADES, { artistGate: 'advisory' }).matched.length, 1);
+  assert.equal(cascade.cascadesFor(shippedCopy(), cascade.CASCADES, { artistGate: 'strict' }).matched.length, 1);
+});
+
+await test('an UNREAD policy files — silence is never read as an opt-out', () => {
+  // No context at all (an old caller), and an explicitly-undefined level (a reader
+  // that threw) must both behave like the gate's default, which is 'strict'.
+  assert.equal(cascade.cascadesFor(shippedCopy()).matched.length, 1);
+  assert.equal(cascade.cascadesFor(shippedCopy(), cascade.CASCADES, {}).matched.length, 1);
+  assert.equal(cascade.cascadesFor(shippedCopy(), cascade.CASCADES, { artistGate: undefined }).matched.length, 1);
+});
+
+await test('a gate reader that THROWS costs the run nothing — it is reported, and the review is still filed', async () => {
+  const created = [];
+  const report = await cascade.runCascadesForShip({ id: '7001' }, {
+    getTask: async () => shippedCopy(),
+    findTaskBySourceRef: async () => null,
+    createTask: async (spec) => { created.push(spec); return { id: '7002' }; },
+    artistGateMode: () => { throw new Error('pack unreadable'); },
+  });
+  assert.equal(created.length, 1, 'an unreadable policy must not silently behave like off');
+  assert.ok(report.errors.some((e) => /artistGateMode\(\) threw/.test(e)), 'and it says so');
+});
+
+await test("runCascadesForShip honours 'off' end to end — nothing is created, nothing errors", async () => {
+  let creates = 0;
+  const report = await cascade.runCascadesForShip({ id: '7001' }, {
+    getTask: async () => shippedCopy(),
+    findTaskBySourceRef: async () => null,
+    createTask: async () => { creates++; return { id: '7002' }; },
+    artistGateMode: () => 'off',
+  });
+  assert.equal(creates, 0);
+  assert.deepEqual(report.created, []);
+  assert.deepEqual(report.errors, [], 'a project that switched the gate off has no problem to report');
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);