@bongos/core 1.19.715 → 1.19.725

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.725'; // 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
@@ -394,6 +427,13 @@ module.exports = {
   //     directly. Resolved lazily so requiring the doorway never forces a config
   //     read at module-load (BV1.R81 / ADR 0093 §1).
   enabledDisciplines: (...a) => require('./modules').enabledDisciplines(...a),
+  //     isModuleEnabled(name) — is THIS module on for this instance? A module needs
+  //     it when its own behaviour depends on ANOTHER module being present: onboarding
+  //     posts a Discord approve/decline control whose 👍 is only ever applied by the
+  //     `discord` module's reaction handler, so with discord off the control is a lie
+  //     and must not be posted at all. Throws on an unknown name (a typo is a bug, not
+  //     a silent false). Lazy, like its sibling above.
+  isModuleEnabled: (...a) => require('./modules').isModuleEnabled(...a),
 
   // --- the seam registry — how modules cooperate without importing each other.
   //     Three primitives: PORTS (one required provider), EVENTS (many optional

package/tests/adopt_preflight.mjs

@@ -101,5 +101,77 @@ t('preflightAdopt: a clean repo → no blocking; every category reports', () =>
   } finally { rmSync(dir, { recursive: true, force: true }); }
 });
 
+// ---- ignored-incoming: the check that was missing (task 1003400) ----------
+//
+// The failure it exists to stop: adopt onto a repo whose .gitignore already carries
+// `.claude/`. The skills/hooks/settings are written to disk, `git add` drops them, the
+// commit looks clean, and every clone of that repo is missing its /builder-* commands
+// with nothing anywhere saying why.
+
+t('checkIgnoredIncoming: an ignored incoming file BLOCKS and names the rule to change', () => {
+  const f = pf.checkIgnoredIncoming([{ path: '.claude/skills', rule: '.gitignore:7:.claude/' }]);
+  assert.equal(f.length, 1);
+  assert.equal(f[0].severity, pf.SEV.BLOCK, 'silent data loss at git add is not a warning');
+  assert.match(f[0].message, /\.claude\/skills/, 'names the swallowed path');
+  assert.match(f[0].message, /\.gitignore:7/, 'names the exact rule line so the owner need not hunt');
+});
+
+t('checkIgnoredIncoming: nothing ignored → INFO, not blocking', () => {
+  const f = pf.checkIgnoredIncoming([]);
+  assert.equal(f[0].severity, pf.SEV.INFO);
+  assert.equal(f.filter((x) => x.severity === pf.SEV.BLOCK).length, 0);
+});
+
+t('checkIgnoredIncoming: probe could not run → INFO that says so, never a false all-clear', () => {
+  const f = pf.checkIgnoredIncoming([], { checked: false });
+  assert.equal(f[0].severity, pf.SEV.INFO);
+  assert.match(f[0].message, /could not run/, 'unknown must not be reported as clean');
+});
+
+t('probeIgnoredIncoming: parses git check-ignore -v into path + rule', () => {
+  const execFileSync = () => '.gitignore:7:.claude/\t.claude/skills\n.gitignore:7:.claude/\t.claude/hooks\n';
+  const { ignored, checked } = pf.probeIgnoredIncoming({ dir: '/x', execFileSync });
+  assert.equal(checked, true);
+  assert.deepEqual(ignored, [
+    { path: '.claude/skills', rule: '.gitignore:7:.claude/' },
+    { path: '.claude/hooks', rule: '.gitignore:7:.claude/' },
+  ]);
+});
+
+t('probeIgnoredIncoming: git exit 1 means NOTHING ignored — a real answer, not a failure', () => {
+  const execFileSync = () => { const e = new Error('exit 1'); e.status = 1; throw e; };
+  assert.deepEqual(pf.probeIgnoredIncoming({ dir: '/x', execFileSync }), { ignored: [], checked: true });
+});
+
+t('probeIgnoredIncoming: no git / not a repo → checked:false, distinct from "clean"', () => {
+  const execFileSync = () => { const e = new Error('not a git repository'); e.status = 128; throw e; };
+  assert.deepEqual(pf.probeIgnoredIncoming({ dir: '/x', execFileSync }), { ignored: [], checked: false });
+});
+
+t('probeIgnoredIncoming: strips our trailing dir slashes before handing paths to git', () => {
+  let input = null;
+  const execFileSync = (_cmd, _args, opts) => { input = opts.input; return ''; };
+  pf.probeIgnoredIncoming({ dir: '/x', incoming: ['.claude/hooks/', 'package.json'], execFileSync });
+  assert.equal(input, '.claude/hooks\npackage.json', 'git check-ignore wants plain pathnames');
+});
+
+t('preflightAdopt (end to end): mercury\'s .gitignore would have BLOCKED the adopt', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'pf-ignored-'));
+  try {
+    // The exact rule that swallowed the methodology surface on the real repo.
+    writeFileSync(join(dir, '.gitignore'), '.env\nvenv/\n\n#claude code\n.claude/\n');
+    const report = pf.preflightAdopt({
+      dir,
+      stack: { migrationsDirs: [], topLevelDirs: [], ci: [] },
+      // Stand in for git so the case is hermetic (no repo needed in tmp).
+      execFileSync: () => '.gitignore:5:.claude/\t.claude/settings.json\n.gitignore:5:.claude/\t.claude/skills\n',
+    });
+    assert.ok(report.hasBlocking, 'adopt must stop rather than produce a silently broken instance');
+    const found = cats(report.findings, 'ignored-incoming');
+    assert.equal(found.length, 1);
+    assert.equal(found[0].severity, pf.SEV.BLOCK);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
 console.log(`\nadopt_preflight: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

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');
+});