@bongos/core 1.19.835 → 1.19.836

package/tests/plain_cards.mjs

@@ -0,0 +1,221 @@
+// tests/plain_cards.mjs — every failure a builder can be parked behind has a
+// plain-language card (task 1003989).
+//
+// WHY. The CLIs explain a refusal in engineer prose and the lifecycle skills said
+// "relay verbatim", so a non-technical builder met REBASE_REQUIRED or
+// strand:pr_not_landed raw, at exactly the moment they were stuck. The registry in
+// scripts/gds/plain-cards.js says the same thing in plain words. This file holds
+// three lines: a new failure code cannot ship without a card, a card cannot drift
+// back into jargon, and the deliberate restrictions stay marked as deliberate.
+//
+// Run:  node tests/plain_cards.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { CARDS, cardFor, plainCardLines, PLAIN_MARKER } from '../scripts/gds/plain-cards.js';
+import * as shipLand from '../scripts/gds/ship-land.js';
+
+const require = createRequire(import.meta.url);
+const { JARGON_TERMS } = require('../modules/sessions/accessibility.js');
+const { formatClaimFailure } = require('../scripts/gds/claim.js');
+const { formatGradeOutcome } = require('../scripts/gds/ship-grade-steps.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+const read = (rel) => fs.readFileSync(new URL(`../${rel}`, import.meta.url), 'utf8').replace(/\r\n/g, '\n');
+const missing = (codes) => [...new Set(codes)].filter((c) => !cardFor(c)).sort();
+
+// ── completeness: the codes are read out of the code that raises them ──────────
+
+test('every refusal claim.js renders has a card', () => {
+  const src = read('scripts/gds/claim.js');
+  const body = src.slice(src.indexOf('function claimFailureGuidance'), src.indexOf('function goalMembershipOfferPlan'));
+  const codes = [...body.matchAll(/code === '([A-Za-z_]+)'/g)].map((m) => m[1]);
+  assert.ok(codes.length >= 12, `expected the claim ladder, found ${codes.length}`);
+  assert.deepEqual(missing(codes), []);
+});
+
+test('every refusal the claim ladder can throw server-side has a card', () => {
+  const src = read('modules/lifecycle/db-claims.js');
+  const codes = [...src.matchAll(/\bcode: '([A-Za-z_]+)'/g), ...src.matchAll(/\.code = '([A-Za-z_]+)'/g)].map((m) => m[1]);
+  assert.ok(codes.includes('REBASE_REQUIRED'), 'the ladder was not found — has db-claims.js moved?');
+  assert.deepEqual(missing(codes), []);
+});
+
+test('every reason a confirmed task can be flagged with has a card', () => {
+  // The reconciler composes `strand:${reason}` at runtime, so read both halves: the
+  // literal tokens, and the four values the `reason` ternary can take.
+  const src = read('modules/lifecycle/publish-reconciler.js');
+  const ternary = src.slice(src.indexOf('const reason = prClosedUnmerged'));
+  const reasons = [...ternary.slice(0, ternary.indexOf(';')).matchAll(/'([a-z_]+)'/g)].map((m) => `strand:${m[1]}`);
+  const literals = [...src.matchAll(/strand:([a-z_]{3,})/g)].map((m) => `strand:${m[1]}`);
+  assert.equal(reasons.length, 4, `the reason ternary moved: ${reasons.join(',')}`);
+  assert.ok(literals.length >= 2, 'the conflict strand literals were not found');
+  assert.deepEqual(missing([...reasons, ...literals]), []);
+  assert.ok(cardFor('strand:unresolvable_conflict:docs/a.md,docs/b.md'), 'a reason carrying file names still resolves');
+});
+
+test('every reason an open pull request has not merged has a card', () => {
+  const src = read('modules/lifecycle/github-push.js');
+  const body = src.slice(src.indexOf('function mergeBlockReason'), src.indexOf('async function mergeIfGreen'));
+  const tokens = [...body.matchAll(/return [`']([a-z_]+)/g)].map((m) => m[1]);
+  assert.ok(tokens.includes('merge_conflict') && tokens.includes('failing_check_unreadable'), tokens.join(','));
+  assert.deepEqual(missing(tokens), []);
+  assert.ok(cardFor('failing_check:unit') && cardFor('non_required_check_failing:e2e'), 'named-check reasons resolve by prefix');
+});
+
+test('every push diagnosis and land bail has a card', () => {
+  const ids = [...shipLand.PUSH_DIAGNOSES.map((d) => d.id), 'unknown',
+    shipLand.LAND_BAIL_MAIN_CHECKOUT_ON_BRANCH, shipLand.LAND_BAIL_NO_TASK_BRANCH];
+  assert.deepEqual(missing(ids.map((id) => `ship:${id}`)), []);
+});
+
+// ── the words ─────────────────────────────────────────────────────────────────
+
+// Beyond the scorer's list: the git/GitHub nouns these particular failures are
+// made of, which is exactly what the card exists to keep out of the first line.
+const GIT_NOUNS = ['branch', 'pull request', 'commit', 'merge conflict', 'CI', 'SHA', 'diff', 'PAT', 'origin'];
+
+test('no card speaks in the vocabulary it exists to translate', () => {
+  const banned = [...JARGON_TERMS, ...GIT_NOUNS];
+  const hits = [];
+  for (const [code, card] of Object.entries(CARDS)) {
+    for (const field of ['happened', 'next', 'person']) {
+      for (const term of banned) {
+        const re = new RegExp(`(^|[^A-Za-z])${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([^A-Za-z]|$)`, /^[A-Z+-]+$/.test(term) ? '' : 'i');
+        if (re.test(card[field] || '')) hits.push(`${code}.${field}: "${term}"`);
+      }
+    }
+  }
+  assert.deepEqual(hits, []);
+});
+
+test('every card is complete, and short enough to be read', () => {
+  for (const [code, card] of Object.entries(CARDS)) {
+    assert.ok(card.happened && card.next, `${code} needs happened + next`);
+    assert.equal(typeof card.by_design, 'boolean', `${code}.by_design`);
+    assert.ok(card.person === null || typeof card.person === 'string', `${code}.person is null or who`);
+    for (const f of ['happened', 'next']) assert.ok(card[f].length <= 230, `${code}.${f} is ${card[f].length} chars`);
+  }
+});
+
+test('the restrictions that must never be worked around are marked by_design', () => {
+  for (const code of ['REBASE_REQUIRED', 'INSUFFICIENT_RANK', 'rank_too_low_for_task', 'session_already_has_active_claim',
+    'main_checkout_claim', 'ship:protected_branch', 'ship:auth', 'box_scope', 'no_push_credential', 'grade_refused_authorization']) {
+    assert.equal(cardFor(code)?.by_design, true, code);
+  }
+  assert.match(cardFor('no_push_credential').next, /never ask/i);
+});
+
+// ── the rendering, and the seams that print it ────────────────────────────────
+
+test('plainCardLines renders four labelled lines under the marker, and nothing for an unknown code', () => {
+  const lines = plainCardLines('ALREADY_CLAIMED');
+  assert.ok(lines[0].includes(PLAIN_MARKER));
+  assert.equal(lines.length, 5);
+  assert.deepEqual(plainCardLines('never_heard_of_it'), []);
+  assert.deepEqual(plainCardLines(undefined), []);
+});
+
+test('a card interpolates nothing — it is static text, so it adds no injection surface', () => {
+  for (const card of Object.values(CARDS)) assert.ok(!/\$\{|%s|<[a-z_]+>/.test(JSON.stringify(card)));
+});
+
+test('a refused claim prints the engineer text first and the card after it', () => {
+  const r = { status: 409, data: { error: { code: 'REBASE_REQUIRED', message: 'x', details: { rebaseTasks: [{ id: 7, reason: 'strand:pr_not_landed' }] } } } };
+  const { lines, exit } = formatClaimFailure(r, 42);
+  assert.equal(exit, 1);
+  assert.match(lines[0], /queue is gated/);
+  const at = lines.findIndex((l) => l.includes(PLAIN_MARKER));
+  assert.ok(at > 0, 'card follows the existing guidance');
+  assert.ok(lines.slice(at).join('\n').includes(CARDS.REBASE_REQUIRED.happened));
+  assert.ok(lines.join('\n').includes(CARDS['strand:pr_not_landed'].happened), 'the flagged reason is translated too');
+});
+
+test('an unmapped claim code still renders, just without a card', () => {
+  const { lines } = formatClaimFailure({ status: 500, data: { error: { code: 'SOMETHING_NEW', message: 'm' } } }, 1);
+  assert.ok(lines.length >= 1 && !lines.join('\n').includes(PLAIN_MARKER));
+});
+
+test('a grader outage and a failed grade each carry their own card', () => {
+  const outage = formatGradeOutcome({ passed: false, signals: { panel_outcome: 'unavailable' } }, 9);
+  assert.ok(outage.includes(CARDS.grade_unavailable.happened));
+  const fail = formatGradeOutcome({ passed: false, score: 4, threshold: 7, issues: [] }, 9);
+  assert.ok(fail.includes(CARDS.grade_failed.happened));
+  assert.ok(!formatGradeOutcome({ passed: true, score: 9, threshold: 7 }, 9).includes(PLAIN_MARKER), 'a pass needs no card');
+});
+
+test('a red pull request line is followed by its card', () => {
+  const lines = shipLand.redPrLines({ reason: 'failing_check_unreadable', checks_unreadable: true });
+  assert.ok(lines[0].includes('RED') && lines.join('\n').includes(CARDS.failing_check_unreadable.happened));
+  assert.deepEqual(shipLand.redPrLines({ reason: 'review_required' }), []);
+});
+
+test('a person at a terminal gets no card — it is written in the agent\'s voice', () => {
+  assert.deepEqual(plainCardLines('REBASE_REQUIRED', { BONGOS_SURFACE: 'terminal' }), []);
+  assert.equal(plainCardLines('REBASE_REQUIRED', {}).length, 5);
+});
+
+test('the sign-in printers, the release refusals and the claim guard each print their card', () => {
+  const wired = {
+    'scripts/gds/cli-lib.js': ['session_invalid', 'box_scope', 'no_session'],
+    'scripts/gds/release.js': ['no_active_claim', 'CLAIM_SESSION_MISMATCH'],
+    'scripts/gds/claim.js': ['main_checkout_claim'],
+    'scripts/gds/ship-land.js': ['land_pending', 'reconcile_blocked'],
+    'scripts/gds/push-path-brief.js': ['no_push_credential'],
+  };
+  for (const [file, codes] of Object.entries(wired)) {
+    const src = read(file);
+    for (const code of codes) {
+      assert.ok(src.includes(`plainCardLines('${code}')`), `${file} should print the ${code} card`);
+      assert.ok(cardFor(code), `${code} has no card`);
+    }
+  }
+});
+
+test('every way start.js can refuse or fail prints a card', () => {
+  const src = read('scripts/gds/start.js');
+  const codes = [...src.matchAll(/\.error === '([A-Za-z_]+)'/g)].map((m) => m[1]);
+  assert.ok(codes.includes('stage_required'), 'start.js no longer names its refusal — has the branch moved?');
+  assert.deepEqual(missing(codes), []);
+  for (const code of [...new Set(codes)]) assert.ok(src.includes(`plainCardLines('${code}')`), `start.js never prints the ${code} card`);
+  // The generic non-ok exit is the last way out; it must not be the one mute path.
+  const generic = src.slice(src.indexOf('if (!r.ok) {'));
+  assert.ok(generic.slice(0, generic.indexOf('process.exit(1)')).includes("plainCardLines('board_unavailable')"));
+});
+
+test('no card is an orphan — each is printed by name, or belongs to a family a seam prints by code', () => {
+  const scripts = fs.readdirSync(new URL('../scripts/gds/', import.meta.url)).filter((f) => f.endsWith('.js') && f !== 'plain-cards.js');
+  const printed = new Set();
+  for (const f of scripts) for (const m of read(`scripts/gds/${f}`).matchAll(/plainCardLines\('([^']+)'\)/g)) printed.add(m[1]);
+  // Families reach plainCardLines through a variable: the claim refusal code, the
+  // flagged strand reason, the merge reason on a red pull request, `ship:${d.id}`.
+  const claimSrc = read('scripts/gds/claim.js') + read('modules/lifecycle/db-claims.js') + read('modules/lifecycle/routes/claims.js') + read('modules/lifecycle/goal-authz.js');
+  const mergeSrc = read('modules/lifecycle/github-push.js');
+  const byFamily = (code) => code.startsWith('strand:') || code.startsWith('ship:')
+    || claimSrc.includes(`'${code}'`) || mergeSrc.includes(`'${code}'`) || mergeSrc.includes(`\`${code}:`);
+  const orphans = Object.keys(CARDS).filter((code) => !printed.has(code) && !byFamily(code));
+  assert.deepEqual(orphans, []);
+});
+
+test('the four lifecycle skills tell the agent how to use the card', () => {
+  for (const skill of ['builder-claim', 'builder-ship', 'builder-start', 'builder-release']) {
+    const md = read(`.claude/skills/${skill}/SKILL.md`);
+    assert.ok(md.includes(PLAIN_MARKER), `${skill} never mentions the ${PLAIN_MARKER} card`);
+    assert.match(md, /interaction profile/, `${skill} does not tie the card to the builder's profile`);
+  }
+  assert.match(read('.claude/skills/builder-claim/SKILL.md'), /never look for a way round it/);
+});
+
+test('the public CLI package ships the card file its scripts require', () => {
+  assert.ok(read('scripts/gds/build-cli-package.js').includes("'scripts/gds/plain-cards.js'"));
+});
+
+console.log(`\nplain cards (task 1003989) tests: ${passed} passed, ${failed} failed`);
+process.exitCode = failed > 0 ? 1 : 0;

package/tests/rebase_gate_unprovable.mjs

@@ -0,0 +1,134 @@
+// tests/rebase_gate_unprovable.mjs — a strand the builder CANNOT clear must stop
+// blocking their queue without stopping being reported (task 1003294).
+//
+// THE BUG. publish-reconciler proves a land by looking for a branch / published tip
+// in the CORE repo. A task that legitimately delivers into the INSTANCE repo (task
+// 1003253 — a real, complete, deployed commit on the instance host) can never be
+// proven here, so the sweep writes needs_rebase_reason='strand:no_branch_no_tip'.
+// ADR 0120 part 3 then refuses that builder EVERY new claim until they land or
+// release it — and they can do neither, because there is nothing in this repository
+// to land. The recorded remedy was a hand-run SQL UPDATE on the droplet.
+//
+// THE SHAPE OF THE FIX, and what these tests are really protecting: the gate and the
+// SURFACING were one function. "Stop blocking" must not become "stop telling them",
+// so the fix SPLITS them — gatingRebaseTasksForBuilder may release a strand past the
+// grace, needsRebaseTasksForBuilder keeps answering in full for me.js / the hall /
+// the CLI. Re-collapsing the two is the regression this file exists to catch.
+//
+// SQL SEMANTICS ARE NOT TESTED HERE — they need a real Postgres and live in
+// tests/claim_gate_rebase.mjs (INTEGRATION set). What is testable DB-free is the
+// wiring, the parameters, and the NULL-handling SHAPE of the predicate, and a
+// fail-open in that shape is the dangerous mistake, so it is asserted directly.
+//
+// Run:  node tests/rebase_gate_unprovable.mjs
+
+import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const { test, summary } = makeRunner();
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (rel) => readFileSync(path.join(REPO_ROOT, rel), 'utf8');
+
+const shipMod = require('../modules/lifecycle/db-ship.js');
+const CLAIMS = read('modules/lifecycle/db-claims.js');
+const SHIP = read('modules/lifecycle/db-ship.js');
+const RECON = read('modules/lifecycle/publish-reconciler.js');
+
+// A client that records what it was asked, so the query can be inspected without a DB.
+const spyClient = () => {
+  const seen = [];
+  return { seen, query: async (sql, params) => { seen.push({ sql, params }); return { rows: [] }; } };
+};
+
+await test('the CLAIM GATE asks the gating query, not the surfacing one', async () => {
+  assert.match(CLAIMS, /gatingRebaseTasksForBuilder\(builderId, client\)/,
+    'claimTask must consult the gating subset');
+  assert.doesNotMatch(CLAIMS, /needsRebaseTasksForBuilder\(/,
+    'the gate must NOT use the unfiltered surfacing query — that is the bug, restored');
+});
+
+await test('the SURFACING query still returns everything — no exclusion at all', () => {
+  const body = SHIP.slice(
+    SHIP.indexOf('async function needsRebaseTasksForBuilder'),
+    SHIP.indexOf('// The ship gate (task 1002483')
+  );
+  assert.ok(body.length > 0, 'needsRebaseTasksForBuilder must still exist');
+  assert.doesNotMatch(body, /interval '1 millisecond'/,
+    'the surfacing query must not inherit the gate grace — the builder still sees the strand');
+  assert.doesNotMatch(body, /no_branch_no_tip/,
+    'the surfacing query must not filter on the strand reason');
+});
+
+await test('the gating query is parameterised with the grace and the reason', async () => {
+  const c = spyClient();
+  await shipMod.gatingRebaseTasksForBuilder(4242, c);
+  assert.equal(c.seen.length, 1);
+  const { sql, params } = c.seen[0];
+  assert.equal(params[0], 4242, 'builder id');
+  assert.equal(params[1], shipMod.UNPROVABLE_GATE_GRACE_MS, 'the grace is passed, not inlined');
+  assert.equal(params[2], 'strand:no_branch_no_tip',
+    'the reason is passed in the SPELLING announceStrand stores (strand:<reason>)');
+  assert.match(sql, /needs_rebase = true AND status = 'confirmed' AND shipped_by = \$1/,
+    'it must still be the same set of owed rebases, only narrowed');
+});
+
+await test('an explicit grace overrides the default — the window is tunable', async () => {
+  const c = spyClient();
+  await shipMod.gatingRebaseTasksForBuilder(1, c, 5_000);
+  assert.equal(c.seen[0].params[1], 5_000);
+});
+
+await test('a negative or junk grace degrades to 0, never to a negative interval', async () => {
+  // A negative interval would make `needs_rebase_at < now() + X` true for FRESH
+  // strands — releasing the gate immediately, the exact inversion of the intent.
+  for (const bad of [-1, NaN, undefined, 'nonsense']) {
+    const c = spyClient();
+    await shipMod.gatingRebaseTasksForBuilder(1, c, bad);
+    assert.ok(c.seen[0].params[1] >= 0, `grace ${String(bad)} must not go negative`);
+  }
+});
+
+await test('the predicate is FAIL-CLOSED on NULLs — an unknown keeps the gate', () => {
+  const body = SHIP.slice(SHIP.indexOf('async function gatingRebaseTasksForBuilder'));
+  const q = body.slice(0, body.indexOf('return rows;'));
+  // A bare `needs_rebase_reason = $3` yields NULL for a NULL reason, and
+  // NOT(NULL AND true AND true) is NULL, which drops the row from the WHERE —
+  // releasing the gate for a row we know nothing about. COALESCE removes the NULL.
+  assert.match(q, /COALESCE\(needs_rebase_reason, ''\) = \$3/,
+    'the reason comparison must not be able to produce NULL');
+  assert.match(q, /needs_rebase_at IS NOT NULL/,
+    'a NULL timestamp must not participate in the age comparison');
+  assert.match(q, /AND NOT \(/, 'the exclusion is expressed as NOT over non-NULL operands');
+});
+
+await test('the reconciler ESCALATES past the grace instead of going quiet', () => {
+  assert.match(RECON, /UNPROVABLE_GATE_GRACE_MS/,
+    'the sweep must use the SAME constant as the gate, not a second number that can drift');
+  assert.match(RECON, /require\('\.\/db-ship\.js'\)/, 'imported rather than restated');
+  assert.match(RECON, /UNPROVABLE task \$\{r\.task_id\}/,
+    'an ungated strand must still be named on every sweep');
+  assert.match(RECON, /still confirmed and still unlanded/,
+    'the log must say this is not a resolution');
+});
+
+await test('releasing the gate does NOT clear the flag — the row stays owed', () => {
+  // The fix must not touch needs_rebase/needs_rebase_reason. If a future change
+  // "tidied up" by clearing the flag past the grace, the strand would vanish from
+  // every surfacing and the task would silently sit confirmed forever.
+  const body = SHIP.slice(SHIP.indexOf('async function gatingRebaseTasksForBuilder'));
+  const q = body.slice(0, body.indexOf('return rows;'));
+  assert.doesNotMatch(q, /UPDATE|SET /, 'the gating query must be a pure read');
+});
+
+await test('the grace is bounded and sane by default', () => {
+  assert.ok(shipMod.UNPROVABLE_GATE_GRACE_MS > 0, 'a zero default would never gate at all');
+  assert.ok(shipMod.UNPROVABLE_GATE_GRACE_MS >= 60 * 60_000,
+    'too short and case (a) — the builder who simply never pushed — escapes the gate that exists for them');
+});
+
+summary();