@bongos/core 1.19.715 → 1.19.724

package/src/bongos/artist-gate.js

@@ -0,0 +1,204 @@
+'use strict';
+
+// src/bongos/artist-gate.js — the artist gate: what an unresolved artist review
+// holds, and what releases it (ADR 0241, task 1003575).
+//
+// WHAT IT ANSWERS: "an artist review task is open — does anything stop?" One
+// value, read from one place, so the cascade that FILES those reviews and the
+// deploy that they HOLD cannot disagree about the project's own policy:
+//
+//   off        no artist review tasks are filed at all; nothing is held
+//   advisory   reviews are filed; nothing is held
+//   strict     reviews are filed, and an unresolved one holds the DEPLOY
+//
+// THE TWO THINGS THAT MAKE THIS ADMISSIBLE, both from ADR 0241 and neither
+// optional — a gate that loses either one is the gate ADR 0162 retired:
+//
+//  1. IT READS A STATE, NEVER A VERDICT. The blocking condition is "is there an
+//     unresolved artist review attached to this work?", never "did the artist
+//     approve it?". An artist saying the copy is bad stops nothing by itself, and
+//     an artist saying it is fine releases nothing by itself; what moves is the
+//     review task's STATUS, by the ordinary means (shipped, or dismissed in
+//     triage). That is what keeps the gate rank-consistent and machine-checkable
+//     instead of pinned to one person being available.
+//
+//  2. IT HOLDS THE DEPLOY, NOT THE SHIP. A builder's work still grades, merges,
+//     credits and lands on CI alone. Nothing here may ever reach the ship or land
+//     path — the wave-4 strand class that forced ADR 0162 is exactly what that
+//     separation prevents. The only thing this can delay is a pin move, which is
+//     already deliberate, already owner-initiated, and reversible by doing it
+//     later.
+//
+// PURE HALF / READ HALF. Everything below `unresolvedArtistReviews` is pure — a
+// list of task-shaped objects in, a verdict out — so the halt matrix tests with no
+// pack, no env and no database. Only `artistGateMode` touches the branding pack,
+// and it defers that require to call time for the same reason project-door.js
+// does.
+
+const log = require('./logger').logger.child({ src: 'artist-gate' });
+
+// The three levels, ORDERED loosest → strictest (ADR 0241 §2's table).
+const ARTIST_GATE_LEVELS = Object.freeze(['off', 'advisory', 'strict']);
+
+// A task status is RESOLVED when the work it asks for is done or the board has
+// decided it will not be — 'shipped' and 'abandoned' are the two ways a task
+// leaves the board, and 'abandoned' is what triage's dismiss writes. Everything
+// else (backlog, ready, active, completed, confirmed) is an open request, which
+// is the state ADR 0241 §1 says the gate reads. A row merged into another is
+// resolved too: its successor carries the work.
+const RESOLVED_REVIEW_STATUSES = Object.freeze(['shipped', 'abandoned']);
+
+// The (source, source_ref-prefix) pair every cascade-filed artist review carries.
+// Mirrored from modules/lifecycle/cascade.js rather than imported: core must not
+// reach into a module (the fitness boundary), and a review's identity on the wire
+// is a two-field fact, not a behaviour. The cascade's own test pins the spelling.
+const ARTIST_REVIEW_SOURCE = 'cascade';
+const ARTIST_REVIEW_REF_PREFIX = 'cascade-artist-review-on-ship-';
+
+// ---------------------------------------------------------------------------
+// The pure half
+// ---------------------------------------------------------------------------
+
+// Is this task row a cascade-filed artist review? PURE and total.
+function isArtistReview(task) {
+  if (!task) return false;
+  return String(task.source || '') === ARTIST_REVIEW_SOURCE
+    && String(task.source_ref || '').startsWith(ARTIST_REVIEW_REF_PREFIX);
+}
+
+// Is this review still an open request? PURE and total. A merged row counts as
+// resolved even at an open status — the merge moved the work, and holding a
+// deploy on a row nobody will ever action again is the stall this gate must not
+// have.
+function isReviewResolved(task) {
+  if (!task) return true;
+  if (task.merged_into_task_id != null) return true;
+  return RESOLVED_REVIEW_STATUSES.includes(String(task.status || ''));
+}
+
+// The reviews that actually HOLD, out of every review row handed in. PURE.
+//
+// Two filters, and the second is ADR 0241 §5 — tightening is not retroactive. A
+// project that raises its gate to 'strict' must not inherit a backlog of reviews
+// for work nobody remembers, so a review filed BEFORE the raise never holds. An
+// absent or unparseable `since` means no cutoff, which is the right answer for a
+// project that has been strict since it stood up (the default) — it is not a
+// licence to ignore reviews, so it must not read as one.
+//
+// A review with no readable created_at is KEPT: the cutoff exists to spare a
+// project work it never chose, not to let an unreadable row slip the gate.
+function unresolvedArtistReviews(tasks, { since = null } = {}) {
+  const cutoff = since ? Date.parse(since) : NaN;
+  const list = Array.isArray(tasks) ? tasks : [];
+  return list.filter((t) => {
+    if (!isArtistReview(t) || isReviewResolved(t)) return false;
+    if (Number.isNaN(cutoff)) return true;
+    const filed = Date.parse(t.created_at);
+    if (Number.isNaN(filed)) return true;
+    return filed >= cutoff;
+  });
+}
+
+// Does the gate hold, and if so WHAT holds it and WHICH control releases it?
+// Returns null when nothing is held, else a halt-shaped object. PURE.
+//
+// The sentence is the point, not decoration. ADR 0241 §4's second guard is
+// explicit: the refusal must name what holds the deploy and which control
+// releases it, in one line, because ADR 0162's incident was made worse by a
+// blocked state that did not explain itself. So the detail names the review ids
+// AND both real ways out — resolve them, or the project OWNER releases past with
+// an override-request (rationale required, audit-logged; a self-release is
+// permitted and recorded as such, ADR 0241 §3).
+//
+// Keep this sentence TRUE to the mechanism, not merely to the ADR's prose. The
+// first cut of this gate described an escape hatch the code did not wire, which
+// is worse than no sentence: a refusal that names a control nobody can actually
+// use is a stall with extra steps. The release lives in
+// modules/lifecycle/db-overrides.js (the gate-release class) and the gate reads
+// it through db-tasks.listOpenArtistReviews — change one, re-read the other two.
+// `truncated` says the caller's read hit its scan cap, so `reviews` is a floor
+// rather than the whole queue. It cannot change the VERDICT — every row handed in
+// is a holder, so one is enough — only the count, which is then reported as a
+// floor ("200+") instead of a number the sentence cannot stand behind.
+function artistGateHalt({ mode, reviews = [], truncated = false } = {}) {
+  if (mode !== 'strict') return null;
+  const open = Array.isArray(reviews) ? reviews : [];
+  if (!open.length) return null;
+  // Named as `task N`, never a bare `#N`: this sentence is copied into chat, commit
+  // messages and session logs, where a bare hash autolinks to a GitHub issue that
+  // does not exist (the kernel's linkify rule).
+  const ids = open.slice(0, 5).map((t) => String(t.id));
+  const more = open.length - ids.length;
+  const named = ids.map((id) => `task ${id}`).join(', ');
+  return {
+    code: 'ARTIST_REVIEW_UNRESOLVED',
+    message: `${open.length}${truncated ? '+' : ''} unresolved artist review${open.length === 1 && !truncated ? '' : 's'} hold this deploy — the project runs artist_gate 'strict'`,
+    detail: `Held by ${named}${more > 0 ? ` and ${more} more` : ''}. `
+      + 'Two ways out, both ordinary: resolve or dismiss those reviews on the board, '
+      + 'or release one — POST /tasks/:id/override-request with a rationale, then the PROJECT OWNER '
+      + 'approves it at POST /override-requests/:id/decide (owner only, not an Archon; a self-release '
+      + 'is allowed and is audit-logged as a self-override). A released review stays open on the board; '
+      + "what it stops doing is holding the pin. Setting this project's artist_gate to 'advisory' "
+      + 'stops reviews holding deploys at all.',
+    reviewIds: open.map((t) => String(t.id)),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The read half
+// ---------------------------------------------------------------------------
+
+// artistGateMode — this project's stored artist strictness, and ONLY that. The
+// one reader for the knob, so the cascade, the deploy gate and any surface that
+// reports the policy cannot disagree about what the owner set.
+//
+// An unreadable pack, or a value this core cannot read, resolves to 'strict'. That
+// is fail-closed in the direction ADR 0241 §4 already chose as the DEFAULT, so an
+// instance whose pack went missing behaves like a fresh one rather than silently
+// dropping a policy the owner set — and 'strict' holds only a pin, which the owner
+// can always release. `read` is injectable for the unit tests only (the pack is
+// memoized for the process lifetime, which is why applying a change restarts the
+// instance).
+let warnedUnknownArtistGate = false;
+function artistGateMode(read) {
+  const readPack = read || require('../branding').branding; // eslint-disable-line global-require
+  let v;
+  try { v = readPack().project?.artistGate; } catch (err) {
+    log.error('[artist-gate] branding pack unreadable — treating the project as strict:', err.message);
+    return 'strict';
+  }
+  if (ARTIST_GATE_LEVELS.includes(v)) return v;
+  // Absent is the honest case for a self-hosted instance that has never been
+  // pushed a setting, and for the neutral pack before a value was written. It
+  // takes the default rather than a warning.
+  if (v === undefined || v === null || v === '') return 'strict';
+  if (!warnedUnknownArtistGate) {
+    warnedUnknownArtistGate = true;
+    log.error(`[artist-gate] unrecognised artistGate ${JSON.stringify(v)} — treating the project as strict`);
+  }
+  return 'strict';
+}
+
+// The moment this project's gate was last RAISED to 'strict', or null. Written by
+// the platform when the owner tightens the setting (provisioning.artistGateStamp)
+// and carried in on <PREFIX>_ARTIST_GATE_SINCE. null = no cutoff (ADR 0241 §5).
+function artistGateSince(read) {
+  const readPack = read || require('../branding').branding; // eslint-disable-line global-require
+  let v;
+  try { v = readPack().project?.artistGateSince; } catch { return null; }
+  if (typeof v !== 'string' || !v) return null;
+  return Number.isNaN(Date.parse(v)) ? null : v;
+}
+
+module.exports = {
+  ARTIST_GATE_LEVELS,
+  RESOLVED_REVIEW_STATUSES,
+  ARTIST_REVIEW_SOURCE,
+  ARTIST_REVIEW_REF_PREFIX,
+  isArtistReview,
+  isReviewResolved,
+  unresolvedArtistReviews,
+  artistGateHalt,
+  artistGateMode,
+  artistGateSince,
+};

package/src/branding.js

@@ -69,6 +69,14 @@ const ENV_OVERRIDES = [
   // view | apply | full. The ceiling on the visibility axis that JOINABILITY may
   // only narrow; composed into one door by src/bongos/project-door.js.
   ['JOIN_GRANT', ['project', 'joinGrant']],
+  // The artist gate (ADR 0241, task 1003575) — off | advisory | strict. `off`
+  // generates no artist review tasks; `strict` lets an unresolved one hold this
+  // instance's DEPLOY (never a builder's ship). Its companion stamp says when the
+  // gate was last raised, so the hold is not retroactive (ADR 0241 §5); empty is
+  // skipped by the loop below, which reads as "no cutoff" — correct for a project
+  // that has been strict since it stood up.
+  ['ARTIST_GATE', ['project', 'artistGate']],
+  ['ARTIST_GATE_SINCE', ['project', 'artistGateSince']],
 ];
 
 const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
@@ -250,6 +258,13 @@ function clientBranding(b = branding()) {
       // stranger's client should be able to say what THIS door does before knocking.
       // `full` = this axis narrows nothing, so an un-pushed instance is unchanged.
       joinGrant: b.project?.joinGrant || 'full',
+      // The artist gate (ADR 0241, task 1003575). Public for the read-back reason
+      // its neighbours are: a manage page has to be able to tell a SAVED setting
+      // from a LIVE one, and this instance's own manifest is the only honest
+      // answer to "what did it restart with?". The fallback is the platform
+      // DEFAULT, which for this one key is 'strict' rather than today's behaviour
+      // — the owner's ruling, ADR 0241 §4.
+      artistGate: b.project?.artistGate || 'strict',
     },
   };
 }

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.715'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.724'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');
@@ -164,6 +164,13 @@ module.exports = {
   //     db.js into the bounded src/bongos/db-kernel.js, which this surface resolves
   //     through — so loading a kernel accessor no longer drags in the monolith.
   getBuilderById: (...a) => require('./bongos/db-kernel').getBuilderById(...a),
+  // getFoundingBuilder — the instance's PROJECT OWNER: its first admitted human
+  //     builder (task 1002739). Kernel identity like getBuilderById beside it, and
+  //     published because ADR 0241 §3 gives the artist gate's one escape hatch to
+  //     "the project owner only — not the builder, not any Metic+, not the artist",
+  //     which a module cannot enforce without being able to ask who that is. It is
+  //     a READ of an existing row; it grants nothing by itself.
+  getFoundingBuilder: (...a) => require('./bongos/db-kernel').getFoundingBuilder(...a),
   insertAuditLog: (...a) => require('./bongos/db-kernel').insertAuditLog(...a),
   get LIVE_RANK_LADDER() { return require('./bongos/db-kernel').LIVE_RANK_LADDER; },
   // The ladder as the canonical 1-based rank → tier map (BV1.R108) — modules
@@ -303,6 +310,32 @@ module.exports = {
   //     the other two had closed. Optional `{ publishable }` for a caller that
   //     holds a publish verdict — see src/bongos/project-door.js.
   projectJoinDoor: (opts) => require('./bongos/project-door').effectiveJoinDoor(opts),
+  // artistGate — the project's artist strictness and the pure verdict helpers
+  //     that read it (ADR 0241, task 1003575): 'off' | 'advisory' | 'strict'.
+  //     `off` is what tells the lifecycle cascade not to file artist reviews at
+  //     all, and `strict` is what lets an unresolved one hold a DEPLOY (never a
+  //     ship). Published as the whole small surface rather than one call because
+  //     two different modules ask two different questions of it — "should I file
+  //     this?" and "does anything hold?" — and both must resolve the knob through
+  //     this one reader, never from branding().project directly: the fail-closed
+  //     default and the non-retroactivity cutoff live in there.
+  //     The members are named ONE BY ONE rather than re-exported wholesale: a
+  //     `return require(…)` would publish whatever that file happens to export
+  //     next, which is how a doorway stops being a contract.
+  get artistGate() {
+    const g = require('./bongos/artist-gate'); // eslint-disable-line global-require
+    return Object.freeze({
+      ARTIST_REVIEW_SOURCE: g.ARTIST_REVIEW_SOURCE,
+      ARTIST_REVIEW_REF_PREFIX: g.ARTIST_REVIEW_REF_PREFIX,
+      RESOLVED_REVIEW_STATUSES: g.RESOLVED_REVIEW_STATUSES,
+      isArtistReview: g.isArtistReview,
+      isReviewResolved: g.isReviewResolved,
+      unresolvedArtistReviews: g.unresolvedArtistReviews,
+      artistGateHalt: g.artistGateHalt,
+      artistGateMode: g.artistGateMode,
+      artistGateSince: g.artistGateSince,
+    });
+  },
   // readApplicantProfileFromHub(githubId) — the reviewer queue's LIVE per-render
   //     read of one applicant's hub profile view (privacy spec D7, task
   //     1002972). Published as a NARROW port on purpose: the underlying call is

package/tests/api_path_404.mjs

@@ -144,5 +144,33 @@ t('rebaseRequiredHint: says waiting is correct when CI is merely backed up', ()
   assert.match(rebaseRequiredHint([{ id: 7 }]), /waiting is correct/);
 });
 
+// task 1002788 — the menu must not name the move that deadlocks the reader.
+//
+// This hint fires on a branch that is ALREADY PUBLISHED, and server-mediated
+// publish is append-only by deliberate design (github-push.js: "Refuse
+// non-fast-forward implicitly (no --force, ever)"). The old wording — "rebase
+// the branch and re-ship" — rewrites history the server already holds, so every
+// later publish is rejected non-fast-forward and the builder is left gated from
+// new claims AND unable to land the one they hold. Reproduced end-to-end on task
+// 1002485. ship-land.js's recovery text already says "Do NOT reset or re-rebase";
+// this is the same advice given BEFORE the deadlock rather than after it.
+t('rebaseRequiredHint: prescribes MERGE, and never instructs a rebase', () => {
+  const hint = rebaseRequiredHint([{ id: 7 }]);
+  assert.ok(hint.includes('git merge origin/main'),
+    'must name the fast-forward-safe command, not just forbid the other one');
+  // Narrow on purpose: bans INSTRUCTING a rebase, not the word — "never rebase"
+  // is the sentence that carries the lesson and must keep working.
+  for (const re of [/\brebase\s*\+\s*re-ship\b/i, /\brebase (the|its|your) branch\b/i, /\brebases it\b/i]) {
+    assert.ok(!re.test(hint), `must not instruct a rebase (matched ${re}): ${hint}`);
+  }
+  assert.match(hint, /never rebase/i, 'and must say why, so the next reader does not re-add it');
+});
+
+t('rebaseRequiredHint: still leads with /strand-fix — merge is the manual fallback, not the first offer', () => {
+  const hint = rebaseRequiredHint([{ id: 7 }]);
+  assert.ok(hint.indexOf('/strand-fix') < hint.indexOf('git merge origin/main'),
+    'the command that works on any machine must still come first (task 1003768)');
+});
+
 console.log(`\napi_path_404: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/artist_gate.mjs

@@ -0,0 +1,234 @@
+// tests/artist_gate.mjs
+//
+// The artist gate (ADR 0241, task 1003575) — src/bongos/artist-gate.js.
+//
+// WHAT IS ACTUALLY WORTH PINNING HERE is not that the filter filters. It is the
+// four properties ADR 0241 spends its whole argument on, each of which is a way
+// this gate could quietly become the gate ADR 0162 retired:
+//
+//   1. IT READS A STATE, NEVER A VERDICT. Nothing here may consult who reviewed,
+//      what they thought, or whether they approved — only whether the review task
+//      is still open. A verdict-reading gate is pinned to a person and stalls when
+//      that person is away.
+//   2. IT NEVER HOLDS ANYTHING BUT AT 'strict'. `off` and `advisory` must be
+//      incapable of producing a halt, however many reviews are open.
+//   3. TIGHTENING IS NOT RETROACTIVE (§5). A review filed before the gate was
+//      raised must not hold, or raising the setting means inheriting a backlog for
+//      work nobody remembers — which is what makes a setting frightening to raise.
+//   4. THE REFUSAL EXPLAINS ITSELF (§4). It names what holds the deploy and which
+//      control releases it. ADR 0162's incident was made worse by a blocked state
+//      that did not say either.
+//
+// Pure: the module's read half is injectable, so nothing here needs a branding
+// pack, an env or a database.
+//
+// Run:  node --test tests/artist_gate.mjs
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+// Static named imports, not createRequire: the same shape tests/project_join_door.mjs
+// uses on the sibling kernel classifier. It reads better, and it is also what lets the
+// dead-code ratchet SEE these exports being exercised — a createRequire call is opaque
+// to it, so a fully-tested module reads as ten unused exports.
+import {
+  ARTIST_GATE_LEVELS,
+  RESOLVED_REVIEW_STATUSES,
+  ARTIST_REVIEW_SOURCE,
+  ARTIST_REVIEW_REF_PREFIX,
+  isArtistReview,
+  isReviewResolved,
+  unresolvedArtistReviews,
+  artistGateHalt,
+  artistGateMode,
+  artistGateSince,
+} from '../src/bongos/artist-gate.js';
+
+const gate = {
+  ARTIST_GATE_LEVELS,
+  RESOLVED_REVIEW_STATUSES,
+  ARTIST_REVIEW_SOURCE,
+  ARTIST_REVIEW_REF_PREFIX,
+  isArtistReview,
+  isReviewResolved,
+  unresolvedArtistReviews,
+  artistGateHalt,
+  artistGateMode,
+  artistGateSince,
+};
+
+// A cascade-filed artist review row, as the board holds it.
+const review = (over = {}) => ({
+  id: '9001',
+  title: 'Artist review: the copy and visuals that shipped in task 7001',
+  status: 'backlog',
+  source: 'cascade',
+  source_ref: 'cascade-artist-review-on-ship-7001',
+  created_at: '2026-09-10T00:00:00.000Z',
+  merged_into_task_id: null,
+  ...over,
+});
+
+// A pack reader, as branding().project would answer.
+const pack = (project) => () => ({ project });
+
+// ---------------------------------------------------------------------------
+// What counts as a review at all
+// ---------------------------------------------------------------------------
+
+test('only a CASCADE-filed artist review counts — a hand-filed task with a similar title does not', () => {
+  assert.equal(gate.isArtistReview(review()), true);
+  // Same source, different rule: another cascade must never hold a deploy this
+  // gate was not given authority over.
+  assert.equal(gate.isArtistReview(review({ source_ref: 'cascade-some-other-rule-7001' })), false);
+  // Same ref shape, not the cascade's source.
+  assert.equal(gate.isArtistReview(review({ source: 'manual' })), false);
+  assert.equal(gate.isArtistReview({ title: 'Artist review: please look at this' }), false);
+  assert.equal(gate.isArtistReview(null), false);
+});
+
+test('RESOLVED is a status, never a judgement — the two ways a task leaves the board, plus a merge', () => {
+  assert.equal(gate.isReviewResolved(review({ status: 'shipped' })), true);
+  assert.equal(gate.isReviewResolved(review({ status: 'abandoned' })), true, "triage's dismiss");
+  // A row merged into another is resolved even at an open status: its successor
+  // carries the work, and holding a deploy on a row nobody will action again is
+  // exactly the indefinite stall this gate must not have.
+  assert.equal(gate.isReviewResolved(review({ status: 'backlog', merged_into_task_id: '9100' })), true);
+  for (const status of ['backlog', 'ready', 'active', 'completed', 'confirmed']) {
+    assert.equal(gate.isReviewResolved(review({ status })), false, status);
+  }
+  assert.equal(gate.isReviewResolved(null), true, 'nothing is not an open request');
+});
+
+// ---------------------------------------------------------------------------
+// §5 — tightening is not retroactive
+// ---------------------------------------------------------------------------
+
+test('a review filed BEFORE the gate was raised does not hold; one filed after does', () => {
+  const older = review({ id: '9001', created_at: '2026-09-01T00:00:00.000Z' });
+  const newer = review({ id: '9002', created_at: '2026-09-12T00:00:00.000Z' });
+  const held = gate.unresolvedArtistReviews([older, newer], { since: '2026-09-10T00:00:00.000Z' });
+  assert.deepEqual(held.map((t) => t.id), ['9002']);
+});
+
+test('no cutoff means every open review counts — absent must not read as a licence to ignore', () => {
+  const rows = [review({ id: '9001' }), review({ id: '9002', created_at: '2020-01-01T00:00:00.000Z' })];
+  assert.equal(gate.unresolvedArtistReviews(rows, {}).length, 2);
+  assert.equal(gate.unresolvedArtistReviews(rows, { since: null }).length, 2);
+  assert.equal(gate.unresolvedArtistReviews(rows, { since: 'not a date' }).length, 2, 'junk is no cutoff, not no gate');
+});
+
+test('a review with an unreadable filing date is KEPT — the cutoff spares work, it does not excuse it', () => {
+  const held = gate.unresolvedArtistReviews([review({ created_at: null })], { since: '2026-09-10T00:00:00.000Z' });
+  assert.equal(held.length, 1);
+});
+
+test('resolved reviews are filtered out before the cutoff is even consulted', () => {
+  const rows = [review({ id: '9001', status: 'shipped' }), review({ id: '9002', status: 'abandoned' })];
+  assert.deepEqual(gate.unresolvedArtistReviews(rows, {}), []);
+});
+
+// ---------------------------------------------------------------------------
+// §2 / §4 — what holds, and what the refusal says
+// ---------------------------------------------------------------------------
+
+test("only 'strict' can hold — off and advisory are incapable of it, however many are open", () => {
+  const open = [review({ id: '9001' }), review({ id: '9002' })];
+  assert.equal(gate.artistGateHalt({ mode: 'off', reviews: open }), null);
+  assert.equal(gate.artistGateHalt({ mode: 'advisory', reviews: open }), null);
+  assert.ok(gate.artistGateHalt({ mode: 'strict', reviews: open }));
+});
+
+test("'strict' with nothing open holds nothing — the gate reads state, so no state is no hold", () => {
+  assert.equal(gate.artistGateHalt({ mode: 'strict', reviews: [] }), null);
+  assert.equal(gate.artistGateHalt({ mode: 'strict' }), null);
+});
+
+test('the refusal names WHAT holds the deploy and WHICH control releases it', () => {
+  const halt = gate.artistGateHalt({ mode: 'strict', reviews: [review({ id: '9001' }), review({ id: '9002' })] });
+  assert.equal(halt.code, 'ARTIST_REVIEW_UNRESOLVED');
+  assert.match(halt.message, /2 unresolved artist reviews/);
+  assert.match(halt.message, /strict/, 'and why it is holding at all');
+  // The two real ways out, and neither is "wait for someone".
+  assert.match(halt.detail, /task 9001, task 9002/);
+  assert.match(halt.detail, /resolve or dismiss/i);
+  assert.match(halt.detail, /override-request/);
+  assert.match(halt.detail, /OWNER/, 'the escape hatch is the owner, not any Metic+ (ADR 0241 §3)');
+  assert.match(halt.detail, /advisory/, 'and the setting that stops this happening again');
+  assert.deepEqual(halt.reviewIds, ['9001', '9002']);
+});
+
+test('the refusal never writes a bare #id — that autolinks to a GitHub issue that does not exist', () => {
+  const halt = gate.artistGateHalt({ mode: 'strict', reviews: [review()] });
+  assert.doesNotMatch(`${halt.message} ${halt.detail}`, /#\d/);
+});
+
+test('a TRUNCATED read reports a floor, and truncation can never change the verdict', () => {
+  const many = Array.from({ length: 3 }, (_, i) => review({ id: String(9000 + i) }));
+  const halt = artistGateHalt({ mode: 'strict', reviews: many, truncated: true });
+  assert.match(halt.message, /^3\+ unresolved artist reviews/, 'a floor, not a count it cannot stand behind');
+  // The verdict is identical either way: every row handed in is a holder, so one
+  // is enough and a capped read still holds.
+  assert.equal(artistGateHalt({ mode: 'strict', reviews: many }).code, halt.code);
+  // A single truncated row is still plural — "1+ review" would read as exactly one.
+  assert.match(artistGateHalt({ mode: 'strict', reviews: [review()], truncated: true }).message, /^1\+ unresolved artist reviews/);
+  assert.match(artistGateHalt({ mode: 'strict', reviews: [review()] }).message, /^1 unresolved artist review /);
+  // And truncation cannot manufacture a hold out of nothing.
+  assert.equal(artistGateHalt({ mode: 'strict', reviews: [], truncated: true }), null);
+});
+
+test('a long queue is summarised rather than dumped — five named, the rest counted', () => {
+  const many = Array.from({ length: 9 }, (_, i) => review({ id: String(9000 + i) }));
+  const halt = gate.artistGateHalt({ mode: 'strict', reviews: many });
+  assert.match(halt.detail, /and 4 more/);
+  assert.equal(halt.reviewIds.length, 9, 'but the machine-readable list is complete');
+});
+
+// ---------------------------------------------------------------------------
+// The reader — fail-closed in the direction the default already points
+// ---------------------------------------------------------------------------
+
+test('the level is read from the pack, and only the three declared levels are accepted', () => {
+  assert.equal(gate.artistGateMode(pack({ artistGate: 'off' })), 'off');
+  assert.equal(gate.artistGateMode(pack({ artistGate: 'advisory' })), 'advisory');
+  assert.equal(gate.artistGateMode(pack({ artistGate: 'strict' })), 'strict');
+});
+
+test("an absent, unreadable or unrecognised level resolves to 'strict' — the platform default", () => {
+  // Absent is the honest case for a self-hosted instance nobody ever pushed a
+  // setting to; it takes the default rather than dropping the policy.
+  assert.equal(gate.artistGateMode(pack({})), 'strict');
+  assert.equal(gate.artistGateMode(pack({ artistGate: '' })), 'strict');
+  // A value this core cannot read is a policy it does not know — and the safe
+  // direction here is the strict one, because strict only ever delays a pin move.
+  assert.equal(gate.artistGateMode(pack({ artistGate: 'Strict' })), 'strict');
+  assert.equal(gate.artistGateMode(pack({ artistGate: 'sort-of' })), 'strict');
+  assert.equal(gate.artistGateMode(() => { throw new Error('no pack'); }), 'strict');
+});
+
+test('the cutoff is read from the pack too, and junk reads as no cutoff', () => {
+  assert.equal(gate.artistGateSince(pack({ artistGateSince: '2026-09-10T00:00:00.000Z' })), '2026-09-10T00:00:00.000Z');
+  assert.equal(gate.artistGateSince(pack({ artistGateSince: '' })), null, 'the empty env value the transport always writes');
+  assert.equal(gate.artistGateSince(pack({ artistGateSince: 'whenever' })), null);
+  assert.equal(gate.artistGateSince(pack({})), null);
+  assert.equal(gate.artistGateSince(() => { throw new Error('no pack'); }), null);
+});
+
+// ---------------------------------------------------------------------------
+// The property the whole ADR turns on
+// ---------------------------------------------------------------------------
+
+test('NOTHING in the gate reads a verdict — only source, ref, status, merge and date', () => {
+  // A row carrying every judgement-shaped field the board could hand it must
+  // behave identically to one carrying none: if this ever fails, the gate has
+  // started reading an opinion and ADR 0162's objection applies again.
+  const opinionated = review({
+    grade: 'fail', verdict: 'rejected', approved_by: null, review_outcome: 'needs-work', artist_says: 'this is slop',
+  });
+  assert.deepEqual(
+    gate.unresolvedArtistReviews([opinionated], {}).map((t) => t.id),
+    gate.unresolvedArtistReviews([review()], {}).map((t) => t.id)
+  );
+  const a = gate.artistGateHalt({ mode: 'strict', reviews: [opinionated] });
+  const b = gate.artistGateHalt({ mode: 'strict', reviews: [review()] });
+  assert.deepEqual(a, b, 'an approving artist releases nothing; a disapproving one holds nothing extra');
+});