@bongos/core 1.19.714 → 1.19.724

package/tests/main_worktree_busy_reason.mjs

@@ -0,0 +1,167 @@
+// tests/main_worktree_busy_reason.mjs
+//
+// task 1002871 — every bail that touches the shared main checkout must identify
+// the OCCUPANT, not just the symptom.
+//
+// THE INCIDENT (idea 1000604, 2026-07-28). A shared main checkout sat parked on
+// `task-1002503-backfill-recovery` with 2 unpushed commits and 4 modified
+// generated files, and blocked the auto-merge leg for NINE confirmed tasks. Most
+// of that idea was fixed: ship-merge.js now detects a main checkout on a feature
+// branch, names it, and states the cure.
+//
+// What was NOT fixed is the exact shape of the incident. mainWorktreeBusy() runs
+// FIRST, and only ever said 'a merge is already in progress' or 'the working tree
+// is dirty or has unmerged files'. A checkout that is BOTH parked AND dirty — the
+// 2026-07-28 state precisely — short-circuits there, so the named-branch
+// diagnostic was reachable only when the tree was clean: the one case where
+// nobody needs telling twice.
+//
+// The decision is pure now so the exact string is pinned rather than eyeballed.
+// This is the ship hot path and the string IS the deliverable.
+//
+// Run:  node tests/main_worktree_busy_reason.mjs
+
+import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { describeMainWorktreeBusy } = require(path.join(ROOT, 'scripts', 'gds', 'ship-regen.js'));
+const { parkedMainCheckoutWarning } = require(path.join(ROOT, 'scripts', 'gds', 'worktree-claim-guard.js'));
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// --- describeMainWorktreeBusy ------------------------------------------------
+
+t('a clean main checkout on main is not busy', () => {
+  assert.equal(describeMainWorktreeBusy({ mergeInProgress: false, dirty: false, branch: 'main' }), null);
+});
+
+t('THE INCIDENT: dirty AND parked on a feature branch names the branch', () => {
+  const reason = describeMainWorktreeBusy({
+    mergeInProgress: false, dirty: true, branch: 'task-1002503-backfill-recovery',
+  });
+  assert.match(reason, /dirty or has unmerged files/, 'keeps the original symptom');
+  assert.match(reason, /task-1002503-backfill-recovery/, 'and NAMES the squatting branch — the whole point');
+  assert.match(reason, /not `main`/, 'and says what it should have been');
+});
+
+t('a merge in progress on a feature branch also names it', () => {
+  const reason = describeMainWorktreeBusy({ mergeInProgress: true, dirty: true, branch: 'task-999' });
+  assert.match(reason, /merge is already in progress/);
+  assert.match(reason, /task-999/, 'the branch is named on this arm too, not just the dirty one');
+});
+
+t('merge-in-progress wins over dirty — one reason, the most specific', () => {
+  const reason = describeMainWorktreeBusy({ mergeInProgress: true, dirty: true, branch: 'main' });
+  assert.match(reason, /merge is already in progress/);
+  assert.ok(!/dirty/.test(reason), 'must not concatenate both symptoms into one run-on reason');
+});
+
+t('on `main` itself the branch is NOT named — that line would be pure noise', () => {
+  const reason = describeMainWorktreeBusy({ mergeInProgress: false, dirty: true, branch: 'main' });
+  assert.equal(reason, 'the working tree is dirty or has unmerged files',
+    'saying "(on main, not main)" in every bail trains the reader to skip the line');
+});
+
+t('an unreadable branch degrades to the old wording rather than inventing one', () => {
+  for (const branch of [null, undefined, '', 'HEAD']) {
+    const reason = describeMainWorktreeBusy({ mergeInProgress: false, dirty: true, branch });
+    assert.equal(reason, 'the working tree is dirty or has unmerged files',
+      `branch=${JSON.stringify(branch)} must not produce a half-formed name`);
+  }
+});
+
+t('a non-default defaultBranch is honoured', () => {
+  assert.equal(describeMainWorktreeBusy({ dirty: true, branch: 'trunk', defaultBranch: 'trunk' }),
+    'the working tree is dirty or has unmerged files', 'the repo default is not hardcoded to main');
+  assert.match(describeMainWorktreeBusy({ dirty: true, branch: 'main', defaultBranch: 'trunk' }),
+    /on `main`, not `trunk`/);
+});
+
+t('no facts at all is a quiet null, never a throw', () => {
+  assert.equal(describeMainWorktreeBusy(), null);
+  assert.equal(describeMainWorktreeBusy({}), null);
+});
+
+// --- parkedMainCheckoutWarning (the release.js half) -------------------------
+
+t('release warning is silent when the main checkout is on main', () => {
+  assert.deepEqual(parkedMainCheckoutWarning({ branch: 'main' }), []);
+  assert.deepEqual(parkedMainCheckoutWarning({ branch: null }), [], 'an unreadable branch says nothing');
+  assert.deepEqual(parkedMainCheckoutWarning({}), []);
+});
+
+t('release warning names the parked branch, the cost, and the cure', () => {
+  const out = parkedMainCheckoutWarning({ branch: 'task-1002503-backfill-recovery' }).join('\n');
+  assert.match(out, /task-1002503-backfill-recovery/, 'names the occupant');
+  assert.match(out, /nowhere to merge INTO/, 'states the cost, not just the fact');
+  assert.match(out, /someone else/, 'and that the cost lands on other builders too');
+  assert.match(out, /checkout main/, 'and gives the cure');
+});
+
+t('release warning NEVER offers to restore the tree — on EITHER branch of the message', () => {
+  // Both arms, deliberately. A probe that made only the clean-tree line offer a
+  // restore kept this test green when it checked the dirty arm alone: the
+  // "we will not touch it" promise has two renderings and both must keep it.
+  for (const dirty of [true, false]) {
+    const out = parkedMainCheckoutWarning({ branch: 'task-42', dirty }).join('\n');
+    assert.match(out, /nothing here will touch it/i,
+      `dirty=${dirty}: switching the tree back would be a destructive guess — the branch may hold real work`);
+    assert.ok(!/\brestore it\b/i.test(out),
+      `dirty=${dirty}: must not offer to restore the tree on the builder's behalf`);
+  }
+  const dirtyOut = parkedMainCheckoutWarning({ branch: 'task-42', dirty: true }).join('\n');
+  assert.match(dirtyOut, /uncommitted changes/i, 'and when it IS dirty, say so — that is why we do not touch it');
+});
+
+// --- the probes that gather the facts must not build shell strings -----------
+//
+// Caught by the grader on this task: the first cut ran
+// `git -C "${root}" rev-parse …` through execSync, which spawns a shell. A
+// resolved filesystem path is NOT trusted input — a directory containing a quote,
+// backtick or `$()` breaks the quoting and executes as shell. The repo's
+// established pattern passes the directory to child_process instead of
+// interpolating it into a command string, and release.js now goes further and
+// uses an argv array with no shell at all.
+t('release.js never interpolates a path into a git command string', () => {
+  const raw = readFileSync(path.join(ROOT, 'scripts', 'gds', 'release.js'), 'utf8');
+  // Strip comments first: the file DESCRIBES the unsafe form on purpose, to stop
+  // the next reader reintroducing it. Scanning prose as if it were code is how a
+  // guard reds on its own documentation — which this one did, first run.
+  const src = raw.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+  assert.ok(!/git\s+-C\s+["'`]?\$\{/.test(src),
+    'a `git -C "${path}"` command string is shell-interpolated — pass the directory to child_process instead');
+  assert.ok(!/execSync\s*\(\s*[`'"]git /.test(src),
+    'a git command built as a shell string re-opens the injection this test exists to close');
+  assert.match(src, /execFileSync\('git', args/,
+    'git must be invoked with an argv array, which never reaches a shell');
+  assert.match(src, /cwd,/, 'and the directory must travel as cwd, not inside the command');
+  // The stripper must not have eaten the file: a guard over an empty string
+  // passes every negative assertion above and proves nothing.
+  assert.ok(src.length > 500, `comment-stripping left only ${src.length} chars — the scan is reading nothing`);
+});
+
+t('release.js imports nothing outside the published CLI package', () => {
+  const src = readFileSync(path.join(ROOT, 'scripts', 'gds', 'release.js'), 'utf8');
+  const manifest = readFileSync(path.join(ROOT, 'scripts', 'gds', 'build-cli-package.js'), 'utf8');
+  const locals = [...src.matchAll(/require\('\.\/([A-Za-z0-9._-]+)'\)/g)].map((m) => m[1]);
+  assert.ok(locals.length > 0, 'no local requires found — this guard is reading the wrong shape');
+  for (const name of locals) {
+    const file = name.endsWith('.js') ? name : `${name}.js`;
+    assert.ok(manifest.includes(`scripts/gds/${file}`),
+      `release.js requires ./${name}, which is not in the CLI package FILES list — `
+      + '`bongos release` would crash at require time in the published package (it did once already)');
+  }
+});
+
+console.log(`\nmain_worktree_busy_reason: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/membership_kind_lockstep.mjs

@@ -35,9 +35,13 @@ import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import fs from 'node:fs';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { authSource } from './helpers.mjs';
 
+const require = createRequire(import.meta.url);
+const lint = require('../scripts/gds/lint-migrations.js');
+
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
 
@@ -111,3 +115,87 @@ test('the sender writes BOTH spellings, computing the kind once (the cross-versi
   assert.equal((body.match(/membershipKind\(\{ githubLogin \}\)/g) || []).length, 1,
     'the kind is computed ONCE per check-in, not per field');
 });
+
+// ── THE CONTRACT PHASE — the test of the shim's own removal (task 1003089) ─────
+//
+// ADR 0174's Lineage lesson: a time-boxed shim outlives its release unless its
+// removal ships with the test that says it is gone. core_240 closed the GOAL
+// membership window — the trigger, the function and `goal_members.role` are all
+// dropped, and `membership_kind` carries NOT NULL + DEFAULT itself rather than
+// resting on a trigger surviving.
+//
+// The PROJECT membership half (platform_identity_010) is deliberately NOT here:
+// it is still inside its cross-version federation window, its contract phase is
+// task 1003092, and the expand-phase block above is what still guards it. Do not
+// merge the two — the whole point of the pair is that they close on different
+// schedules.
+const CONTRACT = 'migrations/core_240_goal_members_drop_legacy_role.sql';
+
+test('core_240: the contract phase drops the trigger, the function AND the column', () => {
+  const sql = read(CONTRACT);
+  assert.match(sql, /DROP TRIGGER IF EXISTS goal_members_membership_kind_lockstep ON goal_members/);
+  assert.match(sql, /DROP FUNCTION IF EXISTS goal_members_membership_kind_lockstep\(\)/,
+    'the FUNCTION outlives the trigger unless it is dropped by name — dropping only the trigger '
+    + 'leaves a dangling plpgsql body naming a column that no longer exists');
+  assert.match(sql, /ALTER TABLE goal_members\s+DROP COLUMN IF EXISTS role/);
+  assert.match(sql, /ALTER COLUMN membership_kind SET NOT NULL/,
+    'the guarantee core_220 deferred to step 2 arrives here, or the column never gets one');
+  assert.match(sql, /ALTER COLUMN membership_kind SET DEFAULT 'member'/,
+    'safe only NOW: a default while the legacy column was still written is the task-1003093 bug');
+});
+
+test('core_240: the forward-unsafe pragma is present, and its FIRST line carries the reason', () => {
+  const scan = lint.scanMigrationSql(read(CONTRACT));
+  assert.deepEqual([...scan.unsafe].sort(), ['drop-column', 'set-not-null'],
+    'the linter must still SEE both operations — an acknowledged migration is not an exempt one');
+  assert.ok(scan.acknowledged,
+    'a drop-column with no pragma reds tests/migrations_forward_safe.mjs, which is the point');
+  // ACK_RE captures a SINGLE line, so a reason spread over a paragraph records
+  // nothing in the lint output. The release a rollback could restore is the one
+  // fact that makes the drop safe, so it belongs on that line.
+  assert.match(scan.ackReason, /1\.19\.238/,
+    'the pragma must name the release that stopped reading the column, not merely assert safety');
+});
+
+test('the FRESH-INSTALL seed writes the new name — the writer that is not application code', () => {
+  // The last writer of `goal_members.role` was a MODULE migration, not a query:
+  // lifecycle_001_goal_first_leads.sql named it in the INSERT list AND the
+  // ON CONFLICT arm. Module migrations run AFTER the core ones on every fresh
+  // install, so a stale name here survives the DROP invisibly on an existing
+  // instance (already in schema_migrations, never re-run) and breaks
+  // `cloudbongos init` for every new one. Zero rows on a fresh DB does not save
+  // it: a missing column is a plan-time error, not a row-time one.
+  const code = lint.stripSqlComments(read('modules/lifecycle/migrations/lifecycle_001_goal_first_leads.sql'));
+  assert.match(code, /INSERT INTO goal_members \(goal_id, builder_id, membership_kind\)/);
+  assert.match(code, /DO UPDATE SET membership_kind = 'lead'/,
+    'the ON CONFLICT arm names the column too — renaming only the INSERT list still fails to plan');
+  assert.ok(!/\brole\b/.test(code),
+    'no statement in the fresh-install seed may name the dropped column');
+});
+
+test('no migration outside the three that own its lifecycle still names goal_members.role', () => {
+  // Comments are stripped first: the history is allowed to DISCUSS the old column,
+  // and this rule is about statements. The three exemptions are the migrations that
+  // created the column, expanded away from it, and dropped it.
+  const OWNS_ITS_LIFECYCLE = new Set([
+    '160_goal_tier.sql',                          // created it
+    'core_220_goal_members_membership_kind.sql',  // expand: read it to backfill; the trigger kept it in step
+    'core_240_goal_members_drop_legacy_role.sql', // contract: dropped it
+  ]);
+  const dirs = [path.join(ROOT, 'migrations')];
+  for (const d of fs.readdirSync(path.join(ROOT, 'modules'), { withFileTypes: true })) {
+    if (!d.isDirectory()) continue;
+    const md = path.join(ROOT, 'modules', d.name, 'migrations');
+    if (fs.existsSync(md)) dirs.push(md);
+  }
+  const offenders = [];
+  for (const dir of dirs) {
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.sql') || OWNS_ITS_LIFECYCLE.has(f)) continue;
+      const code = lint.stripSqlComments(fs.readFileSync(path.join(dir, f), 'utf8'));
+      if (/goal_members/.test(code) && /\brole\b/.test(code)) offenders.push(f);
+    }
+  }
+  assert.deepEqual(offenders, [],
+    `these migrations touch goal_members and still name the dropped column: ${offenders.join(', ')}`);
+});

package/tests/mirror_redact.mjs

@@ -161,6 +161,20 @@ t('findSecretLeak detects a secret shape, clean text passes', () => {
   assert.equal(findSecretLeak('token ghp_' + 'a'.repeat(36)), true);
   assert.equal(findSecretLeak('just ordinary prose here'), false);
 });
+// Regression (task 1003873). findSecretLeak is a DIFFERENTIAL audit — it re-scrubs and asks
+// "did anything change?" — so it must run with the same options as the scrub it is auditing.
+// Given none, it re-redacts the long ADR filename that task 1002460's allowlist deliberately
+// spared, mistakes its own disagreement for a leak, and (the gate being fail-closed) reports
+// a phantom secret in every published doc.
+t('findSecretLeak forwards scrub options, so it can audit a scrub that used them', () => {
+  const name = '0281-differential-audit-allowlist-symmetry.md';
+  const doc = `see docs/adr/${name} for the rationale`;
+  const knownDocNames = new Set([name]);
+  assert.equal(findSecretLeak(doc), true, 'without the allowlist the filename reads as a secret');
+  assert.equal(findSecretLeak(doc, [], { knownDocNames }), false, 'with it, a file is a file');
+  // …and the allowlist is not a smuggling channel: a real shape beside it still trips.
+  assert.equal(findSecretLeak(`ghp_${'a'.repeat(36)} in docs/adr/${name}`, [], { knownDocNames }), true);
+});
 
 // ── vanilla instance (empty branding) — IP floor still works, no token/owner rules ────
 t('empty branding derives no tokens/owners but the IP floor still redacts', () => {

package/tests/module_api.mjs

@@ -23,6 +23,11 @@ const PUBLISHED_SURFACE = [
   'requireBuilder', 'requireRank', 'rankMeetsThreshold', 'requireBfgPrincipal', 'allowBoxScope', 'resolveSession',
   'requirePermission', // BV1.R105: the authority-atom gate module routes migrate onto (1.19.0; ADR 0151)
   'pool', 'getPool', 'instanceDbName', 'withTx', 'getBuilderById',
+  // added by task 1003575 (ADR 0241 §3): the instance's PROJECT OWNER — its first
+  // admitted human builder. Kernel identity like getBuilderById beside it, and
+  // published because the artist gate's one escape hatch is the owner's alone, and
+  // a module cannot enforce that without being able to ask who the owner is.
+  'getFoundingBuilder',
   'secretBox', // Gemini-key storage relocated to modules/art-pipeline + its 'art.getBuilderGeminiKeyRow' port (ADR 0102)
   'grantedScopeCoversRepos', // the create-route credential preflight's scope read (task 1002909); kernel (auth-config.js), unlike db/github-repos which the module reaches via `pool` + its own client
   'accountExistenceReadRateLimit', // task 1003339 (ADR 0209): the shared per-IP budget both account-existence probes spend from — one instance, not a factory, so the budget is genuinely shared
@@ -40,6 +45,7 @@ const PUBLISHED_SURFACE = [
   'resolveRotDays', 'projectSettings', // added by task 1003279 (ADR 0232; goal 1000072): the ROT timer + the live knob store behind it. A DIFFERENT question from the stale-claim timer above — days not hours, DB not env, work nobody picked up rather than a builder who went quiet, and it only ever ASKS a human where that one ACTS. Both ride the doorway so no module hardcodes either.
   'joinabilityMode', // added by task 1003044 (ADR 0194; the carrier after 1.19.374): the project's membership door, one reader for the sign-in gate AND the onboarding module's public POST
   'projectJoinDoor', // added by task 1002331 (ADR 0182 D6 / ADR 0247): the COMPOSED join/apply door — visibility × join grant × joinability, one answer, so a module reading a single knob cannot re-open a door the other two closed
+  'artistGate', // added by task 1003575 (ADR 0241): the artist gate — off | advisory | strict, plus the pure verdict helpers over it. Two modules ask it two different questions ("file this review?" and "does an open one hold the deploy?") and both must resolve the knob through this one reader, never branding().project
   'readApplicantProfileFromHub', // added by task 1002972 (privacy spec D7): the reviewer queue's LIVE per-render read of one applicant's hub profile view. NARROW by design — the underlying call is authenticated with this instance's hub client secret, and loadIdpConfig stays OFF the doorway so no module ever holds the credential that speaks for the whole project
   'enabledDisciplines', // BV1.R81: instance offered-disciplines (1.9.0; onboarding restock backstop)
   'registerProvider', 'hasProvider', 'resolve', 'resolveOptional', 'listPorts', 'verifyPortsSatisfied',

package/tests/provision_settings_apply.mjs

@@ -61,6 +61,8 @@ ${NEUTRAL_PREFIX}_PLATFORM_VISIBILITY=public
 ${NEUTRAL_PREFIX}_JOINABILITY=apply
 ${NEUTRAL_PREFIX}_VISIBILITY=public
 ${NEUTRAL_PREFIX}_JOIN_GRANT=full
+${NEUTRAL_PREFIX}_ARTIST_GATE=strict
+${NEUTRAL_PREFIX}_ARTIST_GATE_SINCE=
 `;
 
 t('replaces an existing KEY= line where it stands; every other line survives byte-for-byte', () => {
@@ -113,7 +115,13 @@ t('is PURE: same input, same output; empty body yields just the lines', () => {
 t('settingsEnvVarsFor: the runner pushes the SAME pair webEnvBody writes at standup, under the pack prefix', () => {
   const inst = { slug: 'spike', port: 3010, db_name: 'spike', hosting_shape: 'standalone', target_ref: 'jaxri/spike', settings: { platform_visibility: 'gated' } };
   const vars = P.settingsEnvVarsFor(inst);
-  assert.deepEqual(vars, { [`${NEUTRAL_PREFIX}_PLATFORM_VISIBILITY`]: 'gated', [`${NEUTRAL_PREFIX}_JOINABILITY`]: 'apply', [`${NEUTRAL_PREFIX}_VISIBILITY`]: 'public', [`${NEUTRAL_PREFIX}_JOIN_GRANT`]: 'full' });
+  assert.deepEqual(vars, {
+    [`${NEUTRAL_PREFIX}_PLATFORM_VISIBILITY`]: 'gated', [`${NEUTRAL_PREFIX}_JOINABILITY`]: 'apply',
+    [`${NEUTRAL_PREFIX}_VISIBILITY`]: 'public', [`${NEUTRAL_PREFIX}_JOIN_GRANT`]: 'full',
+    // the artist gate + its non-retroactivity stamp (task 1003575, ADR 0241) ride
+    // the same transport; the stamp is empty until the gate is actually RAISED
+    [`${NEUTRAL_PREFIX}_ARTIST_GATE`]: 'strict', [`${NEUTRAL_PREFIX}_ARTIST_GATE_SINCE`]: '',
+  });
   const body = P.webEnvBody(inst, {});
   for (const [k, v] of Object.entries(vars)) assert.match(body, new RegExp(`^${k}=${v}$`, 'm'), `${k} at standup`);
 });
@@ -124,10 +132,10 @@ const GATED = { settings: { platform_visibility: 'gated', joinability: 'invite_o
 const manifestWith = (project) => JSON.stringify({ schema: 'instance-manifest/v1', brand: project === undefined ? {} : { project } });
 
 t('true when every pushed key matches brand.project (camelCase, the ENV_OVERRIDES targets)', () => {
-  assert.equal(P.settingsConsumed(manifestWith({ platformVisibility: 'gated', joinability: 'invite_only', visibility: 'public', joinGrant: 'full' }), GATED), true);
+  assert.equal(P.settingsConsumed(manifestWith({ platformVisibility: 'gated', joinability: 'invite_only', visibility: 'public', joinGrant: 'full', artistGate: 'strict' }), GATED), true);
 });
 t('false when the instance still reports a different value', () => {
-  assert.equal(P.settingsConsumed(manifestWith({ platformVisibility: 'public', joinability: 'invite_only', visibility: 'public', joinGrant: 'full' }), GATED), false);
+  assert.equal(P.settingsConsumed(manifestWith({ platformVisibility: 'public', joinability: 'invite_only', visibility: 'public', joinGrant: 'full', artistGate: 'strict' }), GATED), false);
   assert.equal(P.settingsConsumed(manifestWith({ joinability: 'invite_only' }), GATED), false, 'a missing key is a mismatch, not a pass');
 });
 t('null (unknown) when the manifest carries no project block — a core that predates task 1003139 — or does not parse', () => {
@@ -145,7 +153,7 @@ t('instanceManifestCmd asks the instance on loopback, like healthzCmd', () => {
 function recorder({ apply = false, envBody = LIVE_ENV, readFails = false, healthzFails = false, privileged = false,
   manifest = 'match', restartThrows = false, writeThrows = false } = {}) {
   const cmds = [], writes = [], events = [], probes = [], cleared = [], logs = [];
-  const manifestOut = manifest === 'match' ? manifestWith({ platformVisibility: 'gated', joinability: 'invite_only', visibility: 'public', joinGrant: 'full' })
+  const manifestOut = manifest === 'match' ? manifestWith({ platformVisibility: 'gated', joinability: 'invite_only', visibility: 'public', joinGrant: 'full', artistGate: 'strict' })
     : manifest === 'mismatch' ? manifestWith({ platformVisibility: 'public', joinability: 'apply', visibility: 'public' })
     : manifest === 'none' ? manifestWith(undefined) : 'nope';
   const exec = (cmd, opts = {}) => {
@@ -214,7 +222,7 @@ await ta('dry-run PLANS the patch: reads nothing real, writes NOTHING (no synthe
   assert.equal(r.ok, true);
   assert.equal(r.healthy, null, 'nothing ran, nothing observed');
   assert.equal(writes.length, 0, 'a dry-run must not plan a two-line overwrite of web.env');
-  assert.ok(logs.some((l) => /would patch .*_PLATFORM_VISIBILITY, .*_JOINABILITY, .*_VISIBILITY, .*_JOIN_GRANT in \/etc\/spike\/web\.env in place/.test(l)), logs.join('\n'));
+  assert.ok(logs.some((l) => /would patch .*_PLATFORM_VISIBILITY, .*_JOINABILITY, .*_VISIBILITY, .*_JOIN_GRANT, .*_ARTIST_GATE, .*_ARTIST_GATE_SINCE in \/etc\/spike\/web\.env in place/.test(l)), logs.join('\n'));
   assert.ok(cmds.some((c) => /restart spike/.test(c)), 'the restart is still in the plan');
   assert.ok(logs.some((l) => /dry-run — nothing ran/.test(l)), 'the closing line does not claim a restart happened');
 });

package/tests/provisioning_settings.mjs

@@ -164,7 +164,7 @@ await ta('owner reads DEFAULTS (public / apply) on a row with empty settings —
   reset();
   const r = await get('/provisioning/instances/18/settings');
   assert.equal(r.status, 200, r.raw);
-  assert.deepEqual(r.body.settings, { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full' });
+  assert.deepEqual(r.body.settings, { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full', artist_gate: 'strict' });
   // the planet rides beside the settings (task 1003347): no default — null = the platform's own pick
   assert.deepEqual(r.body.planet, { planet_template: null, planet_accent: null, card_backdrop: null });
   assert.deepEqual(r.body.options, {
@@ -175,6 +175,10 @@ await ta('owner reads DEFAULTS (public / apply) on a row with empty settings —
     // what a PUBLIC join grants (task 1002331, ADR 0247) — the fourth policy
     // axis, offered to the form the same way
     join_grant: ['view', 'apply', 'full'],
+    // the artist gate (task 1003575, ADR 0241) — the fifth policy axis. It is
+    // offered to the form like the rest; what makes it different is only its
+    // default, which is the owner's ruling rather than today's behaviour.
+    artist_gate: ['off', 'advisory', 'strict'],
     planet_template: [...provisioning.PLANET_TEMPLATES], planet_accent: ['sea', 'terracotta', 'gold-soft', 'sun-lit', 'accent'],
     // the card's backdrop (task 1003352) is the same kind of key: platform-drawn,
     // closed list, no default, no push — so it rides the same vocab
@@ -187,14 +191,14 @@ await ta('a stored planet reads back; a name that left the vocabulary reads null
   const r = await get('/provisioning/instances/18/settings');
   assert.equal(r.status, 200, r.raw);
   assert.deepEqual(r.body.planet, { planet_template: 'bead-obsidian-tint', planet_accent: null, card_backdrop: null });
-  assert.deepEqual(r.body.settings, { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full' }, 'the planet is not a setting: the policy read is untouched');
+  assert.deepEqual(r.body.settings, { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full', artist_gate: 'strict' }, 'the planet is not a setting: the policy read is untouched');
 });
 
 await ta('stored keys overlay the defaults', async () => {
   reset({ inst: { owner_builder_id: 7, slug: 'spike', status: 'active', settings: { joinability: 'invite_only' } } });
   const r = await get('/provisioning/instances/18/settings');
   assert.equal(r.status, 200, r.raw);
-  assert.deepEqual(r.body.settings, { platform_visibility: 'public', joinability: 'invite_only', visibility: 'public', join_grant: 'full' });
+  assert.deepEqual(r.body.settings, { platform_visibility: 'public', joinability: 'invite_only', visibility: 'public', join_grant: 'full', artist_gate: 'strict' });
 });
 
 await ta('ANOTHER builder\'s GET → 404 (no existence leak)', async () => {
@@ -222,7 +226,7 @@ await ta('owner changes one key — merged, returned effective, audited api:self
   reset();
   const r = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
   assert.equal(r.status, 200, r.raw);
-  assert.deepEqual(r.body.saved, { platform_visibility: 'public', joinability: 'open', visibility: 'public', join_grant: 'full' }, 'the SAVED value — the response never claims the instance runs it (task 1003140)');
+  assert.deepEqual(r.body.saved, { platform_visibility: 'public', joinability: 'open', visibility: 'public', join_grant: 'full', artist_gate: 'strict' }, 'the SAVED value — the response never claims the instance runs it (task 1003140)');
   assert.equal(r.body.push.queued, true, 'an active co-tenant gets the live push (task 1003140)');
   assert.deepEqual(updateCalls, [{ id: 18, patch: { joinability: 'open' } }], 'exactly the sent key, nothing else');
   assert.equal(events.length, 1);
@@ -235,7 +239,7 @@ await ta('owner changes both keys in one call', async () => {
   reset();
   const r = await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated', joinability: 'invite_only' });
   assert.equal(r.status, 200, r.raw);
-  assert.deepEqual(r.body.saved, { platform_visibility: 'gated', joinability: 'invite_only', visibility: 'public', join_grant: 'full' });
+  assert.deepEqual(r.body.saved, { platform_visibility: 'gated', joinability: 'invite_only', visibility: 'public', join_grant: 'full', artist_gate: 'strict' });
 });
 
 await ta('the OWN-SCOPE WALL: another builder\'s PATCH → 404 and the write path is never reached', async () => {
@@ -274,7 +278,7 @@ await ta('the owner sets the door to stealth — stored, echoed effective, audit
   reset();
   const r = await patch('/provisioning/instances/18/settings', { visibility: 'stealth' });
   assert.equal(r.status, 200, r.raw);
-  assert.deepEqual(r.body.saved, { platform_visibility: 'public', joinability: 'apply', visibility: 'stealth', join_grant: 'full' });
+  assert.deepEqual(r.body.saved, { platform_visibility: 'public', joinability: 'apply', visibility: 'stealth', join_grant: 'full', artist_gate: 'strict' });
   assert.deepEqual(updateCalls, [{ id: 18, patch: { visibility: 'stealth' } }], 'exactly the sent key, nothing else');
   assert.equal(events[0].actor, 'api:self');
   assert.match(events[0].detail, /visibility=stealth/);
@@ -334,7 +338,7 @@ await ta('the owner picks a planet: saved, echoed as `planet`, audited — and N
   const r = await patch('/provisioning/instances/18/settings', { planet_template: 'bead-obsidian-tint', planet_accent: 'sea' });
   assert.equal(r.status, 200, r.raw);
   assert.deepEqual(r.body.planet, { planet_template: 'bead-obsidian-tint', planet_accent: 'sea', card_backdrop: null });
-  assert.deepEqual(r.body.saved, { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full' }, 'the policy half is untouched');
+  assert.deepEqual(r.body.saved, { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full', artist_gate: 'strict' }, 'the policy half is untouched');
   assert.deepEqual(updateCalls, [{ id: 18, patch: { planet_template: 'bead-obsidian-tint', planet_accent: 'sea' } }]);
   assert.equal(r.body.push.queued, false);
   assert.equal(r.body.push.restart, false, 'an active co-tenant would get a push for a POLICY change — never for the planet');

package/tests/provisioning_settings_apply.mjs

@@ -225,7 +225,7 @@ await ta('ACTIVE standalone: the row is written FIRST, then a settings-apply int
   reset();
   const r = await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated' });
   assert.equal(r.status, 200, r.raw);
-  assert.deepEqual(r.body.saved, { platform_visibility: 'gated', joinability: 'apply', visibility: 'public', join_grant: 'full' }, 'the SAVED (requested) value — never `settings`, which a form would render as live');
+  assert.deepEqual(r.body.saved, { platform_visibility: 'gated', joinability: 'apply', visibility: 'public', join_grant: 'full', artist_gate: 'strict' }, 'the SAVED (requested) value — never `settings`, which a form would render as live');
   assert.equal(r.body.settings, undefined);
   assert.deepEqual(updateCalls.map((c) => c.patch), [{ platform_visibility: 'gated' }]);
   assert.equal(updateCalls[0].enqueuedSoFar, 0, 'the runner reads the row — the write must precede the intent');
@@ -274,7 +274,7 @@ await ta('an enqueue that THROWS still answers 200 "saved" — never a 500 that
   enqueueThrows = new Error('db down');
   const r = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
   assert.equal(r.status, 200, r.raw);
-  assert.deepEqual(r.body.saved, { platform_visibility: 'public', joinability: 'open', visibility: 'public', join_grant: 'full' });
+  assert.deepEqual(r.body.saved, { platform_visibility: 'public', joinability: 'open', visibility: 'public', join_grant: 'full', artist_gate: 'strict' });
   assert.equal(updateCalls.length, 1, 'the write landed');
   receiptShape(r.body.push, { queued: false, restart: true, reachable: true });
   assert.match(r.body.push.message, /Saved, but the restart could not be queued/);
@@ -287,7 +287,7 @@ await ta('same values as already stored → no write, no event, no intent, "No c
   reset({ inst: { ...ACTIVE, settings: { platform_visibility: 'gated', joinability: 'open' } } });
   const r = await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated', joinability: 'open' });
   assert.equal(r.status, 200, r.raw);
-  assert.deepEqual(r.body.saved, { platform_visibility: 'gated', joinability: 'open', visibility: 'public', join_grant: 'full' });
+  assert.deepEqual(r.body.saved, { platform_visibility: 'gated', joinability: 'open', visibility: 'public', join_grant: 'full', artist_gate: 'strict' });
   assert.equal(updateCalls.length, 0, 'nothing written (no updated_at reshuffle)');
   assert.equal(events.length, 0, 'no "settings changed" event for a change that is not one');
   assert.equal(enqueueCalls.length, 0, 'a whole-form save must not bounce a live project');
@@ -404,7 +404,7 @@ await ta('save A queues → save B 409s while A RUNS → A settles → the UNCHA
   assert.equal(enqueueCalls.length, enqueuedBefore + 1, 'exactly one new intent');
   assert.equal(updateCalls.length, writesBefore, 'nothing re-written — the value was already stored in step 2');
   assert.deepEqual(owedCalls[owedCalls.length - 1], { id: 18, owed: false }, 'and the debt is settled');
-  assert.deepEqual(r.body.saved, { platform_visibility: 'gated', joinability: 'open', visibility: 'public', join_grant: 'full' },
+  assert.deepEqual(r.body.saved, { platform_visibility: 'gated', joinability: 'open', visibility: 'public', join_grant: 'full', artist_gate: 'strict' },
     'the value that finally ships is the one the owner saved');
 });
 

package/tests/provisioning_settings_env.mjs

@@ -59,8 +59,17 @@ t('a row with NO stored settings emits today\'s behavior EXPLICITLY, never nothi
   assert.equal(v.CLOUDBONGOS_VISIBILITY, 'public');
   // what a public join grants rides it too (task 1002331, ADR 0182 D6)
   assert.equal(v.CLOUDBONGOS_JOIN_GRANT, 'full');
+  // The artist gate is the one key whose default is NOT today's behaviour — it is
+  // the owner's ruling (ADR 0241 §4), and it is safe as a default because strict
+  // holds only a pin move, never a builder's ship.
+  assert.equal(v.CLOUDBONGOS_ARTIST_GATE, 'strict');
+  // Its companion stamp is emitted EMPTY rather than omitted: an absent variable is
+  // a policy the instance would have to infer, and empty already means "no cutoff".
+  assert.equal(v.CLOUDBONGOS_ARTIST_GATE_SINCE, '', 'present and empty — never absent');
+  assert.ok(linesOf(provisioning.settingsEnvLines({}, 'X')).some((l) => l === 'X_ARTIST_GATE_SINCE='));
   assert.equal(linesOf(provisioning.settingsEnvLines({}, 'X')).length,
-    Object.keys(provisioning.SETTINGS_VOCAB).length, 'every policy key always present');
+    Object.keys(provisioning.SETTINGS_VOCAB).length + Object.keys(provisioning.SETTINGS_COMPANION_ENV).length,
+    'every policy key and every declared companion always present');
 });
 
 t('an off-vocabulary stored value falls back to the default, never reaches the instance', () => {
@@ -82,10 +91,14 @@ t('the planet never rides the env transport (task 1003347): it is the platform\'
   assert.doesNotMatch(provisioning.settingsEnvLines({ settings: { planet_template: 'bead-obsidian-tint' } }, 'CB'), /planet|PLANET/);
 });
 
-t('every emitted key is in SETTINGS_VOCAB — the two lists cannot drift', () => {
+t('every emitted key is a vocabulary key or a DECLARED companion — the lists cannot drift', () => {
   const keys = linesOf(provisioning.settingsEnvLines({}, 'X')).map((l) => l.split('=')[0].replace(/^X_/, '').toLowerCase());
-  assert.deepEqual(keys.sort(), Object.keys(provisioning.SETTINGS_VOCAB).sort(),
-    'a key added to the vocabulary must be carried, or the instance never learns it');
+  const expected = [
+    ...Object.keys(provisioning.SETTINGS_VOCAB),
+    ...Object.keys(provisioning.SETTINGS_COMPANION_ENV).map((k) => k.toLowerCase()),
+  ];
+  assert.deepEqual(keys.sort(), expected.sort(),
+    'a key added to the vocabulary must be carried, or the instance never learns it — and an env var the instance reads must be a DECLARED companion, never an ad-hoc extra');
 });
 
 console.log('\nThe generated file tells the truth about what it is:');
@@ -99,11 +112,50 @@ t('it names the live push by the intent the runner actually dispatches (task 100
 });
 
 t('settingsEnvVars is the single source both legs derive from — same keys, same values as the lines', () => {
-  const row = { settings: { platform_visibility: 'gated', joinability: 'open', visibility: 'stealth', join_grant: 'view' } };
+  const row = { settings: { platform_visibility: 'gated', joinability: 'open', visibility: 'stealth', join_grant: 'view', artist_gate: 'advisory' } };
   const vars = provisioning.settingsEnvVars(row, 'CLOUDBONGOS');
-  assert.deepEqual(vars, { CLOUDBONGOS_PLATFORM_VISIBILITY: 'gated', CLOUDBONGOS_JOINABILITY: 'open', CLOUDBONGOS_VISIBILITY: 'stealth', CLOUDBONGOS_JOIN_GRANT: 'view' });
+  assert.deepEqual(vars, {
+    CLOUDBONGOS_PLATFORM_VISIBILITY: 'gated', CLOUDBONGOS_JOINABILITY: 'open', CLOUDBONGOS_VISIBILITY: 'stealth',
+    CLOUDBONGOS_JOIN_GRANT: 'view', CLOUDBONGOS_ARTIST_GATE: 'advisory', CLOUDBONGOS_ARTIST_GATE_SINCE: '',
+  });
+  // varsOf splits on '=', so an empty value reads as '' on both sides — the point
+  // of the comparison is that the standup lines carry exactly the same key set.
   assert.deepEqual(varsOf(provisioning.settingsEnvLines(row, 'CLOUDBONGOS')), vars, 'the standup lines ARE the vars');
-  assert.deepEqual(provisioning.settingsEnvVars({}, 'X'), { X_PLATFORM_VISIBILITY: 'public', X_JOINABILITY: 'apply', X_VISIBILITY: 'public', X_JOIN_GRANT: 'full' }, 'defaults, explicitly');
+  assert.deepEqual(provisioning.settingsEnvVars({}, 'X'), {
+    X_PLATFORM_VISIBILITY: 'public', X_JOINABILITY: 'apply', X_VISIBILITY: 'public', X_JOIN_GRANT: 'full',
+    X_ARTIST_GATE: 'strict', X_ARTIST_GATE_SINCE: '',
+  }, 'defaults, explicitly');
+});
+
+console.log('\nThe artist gate rides the same transport (ADR 0241, task 1003575):');
+
+t('the stamp is carried only when the gate was actually RAISED, and it is the row\'s own value', () => {
+  const stamped = { settings: { artist_gate: 'strict', artist_gate_strict_since: '2026-09-13T00:00:00.000Z' } };
+  assert.equal(provisioning.settingsEnvVars(stamped, 'X').X_ARTIST_GATE_SINCE, '2026-09-13T00:00:00.000Z');
+  // An unparseable stamp is NOT transmitted as a date nobody can read: it reads as
+  // absent, which is the safe direction — no cutoff, so every open review counts.
+  assert.equal(provisioning.settingsEnvVars({ settings: { artist_gate_strict_since: 'whenever' } }, 'X').X_ARTIST_GATE_SINCE, '');
+});
+
+t('artistGateStamp writes the cutoff on a RAISE only — no other save may move it (ADR 0241 §5)', () => {
+  const now = new Date('2026-09-13T12:00:00.000Z');
+  const key = provisioning.ARTIST_GATE_STRICT_SINCE_KEY;
+  // advisory → strict is the tightening the stamp exists for.
+  assert.deepEqual(provisioning.artistGateStamp({ settings: { artist_gate: 'advisory' } }, { artist_gate: 'strict' }, now),
+    { [key]: '2026-09-13T12:00:00.000Z' });
+  // A row with NO stored gate is already 'strict' by default — re-sending 'strict'
+  // is not a raise, and stamping it would silently un-hold reviews already held.
+  assert.deepEqual(provisioning.artistGateStamp({}, { artist_gate: 'strict' }, now), {});
+  // Lowering, and any save that does not touch the gate at all, move nothing.
+  assert.deepEqual(provisioning.artistGateStamp({ settings: { artist_gate: 'strict' } }, { artist_gate: 'off' }, now), {});
+  assert.deepEqual(provisioning.artistGateStamp({ settings: { artist_gate: 'advisory' } }, { joinability: 'open' }, now), {});
+});
+
+t('the stamp can neither leak as a setting nor be written by a client patch', () => {
+  const row = { settings: { artist_gate: 'strict', artist_gate_strict_since: '2026-09-13T00:00:00.000Z' } };
+  assert.ok(!(provisioning.ARTIST_GATE_STRICT_SINCE_KEY in provisioning.SETTINGS_VOCAB));
+  assert.ok(!(provisioning.ARTIST_GATE_STRICT_SINCE_KEY in provisioning.PLANET_VOCAB));
+  assert.ok(!(provisioning.ARTIST_GATE_STRICT_SINCE_KEY in provisioning.effectiveSettings(row)));
 });
 
 console.log('\nwebEnvBody — the settings ride the real per-instance env file:');

package/tests/public_mirror_export.mjs

@@ -103,6 +103,18 @@ t('redactBlob SCRUBS a secret shape from a text blob (handled, not leaked)', ()
   assert.ok(!r.buf.toString('utf8').includes('AKIAABCDEFGHIJKLMNOP'), 'the secret must be scrubbed from the published text');
   assert.equal(r.secret, false, 'a scrubbed text secret is handled, so it is not a residual leak');
 });
+// Regression (task 1003873). The secret verdict audits THIS call's own scrub, so it has to
+// share the scrub's knownDocNames allowlist. When it did not, the audit re-redacted the ADR
+// filename the scrub had just spared, read the difference as a leak, and failed the packager
+// closed on every doc in the tree — the publish lane stayed red for seven core releases.
+t('redactBlob reports no secret for an allowlisted doc filename (the gate agrees with its own scrub)', () => {
+  const name = '0281-differential-audit-allowlist-symmetry.md';
+  const knownDocNames = new Set([name]);
+  const r = redactBlob({ buf: Buffer.from(`see [ADR 0281](docs/adr/${name}) for why`), rules, sensitiveLiterals, envSecrets: [], knownDocNames });
+  assert.ok(r.buf.toString('utf8').includes(name), 'the allowlisted filename must survive the scrub');
+  assert.equal(r.secret, false, 'and must not then be reported as a residual secret');
+  assert.deepEqual(r.leaks, []);
+});
 t('redactBlob FAILS CLOSED on a secret inside a BINARY blob (cannot safely rewrite it)', () => {
   const bin = Buffer.concat([Buffer.from('BIN\x00'), Buffer.from('AKIA' + 'ABCDEFGHIJKLMNOP')]);
   const r = redactBlob({ buf: bin, rules, sensitiveLiterals, envSecrets: [] });