@bongos/core 1.19.579 → 1.19.581

package/scripts/gds/start.js

@@ -156,7 +156,7 @@ function quietStatusLine(header) {
   if (ideas != null) parts.push(`${ideas} idea${ideas === 1 ? '' : 's'} in inbox`);
   if (blockers != null) parts.push(`${blockers} open blocker${blockers === 1 ? '' : 's'}`);
   if (parts.length === 0) return null;
-  return `_${parts.join('  ·  ')}_`;
+  return surface.em(parts.join('  ·  '));
 }
 
 // Calibrated estimate, compact: ~8m / ~2h / ~1.5h.
@@ -201,6 +201,7 @@ function whatItIs(t) {
 // The claimable table — # / Version / Type / Reward / Est. / What it is.
 // Ids are emitted as hall links (renders as a clean #N) — a bare "#NNN" in a
 // relayed chat message autolinks to GitHub and 404s (CLAUDE.md ref rule).
+const surface = require('./surface');
 const HALL_TASK = `${hallBase()}#/task/`;
 function claimableTable(rows, rewardFromServer) {
   // On a cost-plus-only instance the Reward column is an advertised estimate that
@@ -208,15 +209,18 @@ function claimableTable(rows, rewardFromServer) {
   // and footnote what IS paid below the table (task 1002469).
   const perTask = rewardPolicy(rewardFromServer).perTaskCredit;
   const rewardHead = perTask ? 'Reward' : 'Reward (est.)';
-  const out = [
-    `| # | Version | Type | ${rewardHead} | Est. | What it is |`,
-    '|---|---|---|---|---|---|',
-  ];
-  for (const t of rows) {
-    out.push(`| [#${t.id}](${HALL_TASK}${t.id}) | ${cell(t.version_id || '?')} | ${cell(disciplineLabel(t) || '—')} | ${t.credits_reward ?? 0}c | ${estimateShort(t)} | ${cell(whatItIs(t))} |`);
-  }
+  const headers = ['#', 'Version', 'Type', rewardHead, 'Est.', 'What it is'];
+  const body = rows.map((t) => [
+    surface.taskRef(t.id, HALL_TASK),
+    cell(t.version_id || '?'),
+    cell(disciplineLabel(t) || '—'),
+    `${t.credits_reward ?? 0}c`,
+    estimateShort(t),
+    cell(whatItIs(t)),
+  ]);
+  const out = [surface.table(headers, body)];
   const cpNote = costPlusOnlyNote(rewardFromServer);
-  if (cpNote) out.push('', `_${cpNote}_`);
+  if (cpNote) out.push('', surface.em(cpNote));
   return out.join('\n');
 }
 
@@ -268,7 +272,8 @@ function rebaseWarningModel(needsRebaseTasks) {
 function rebaseWarningMarkdown(needsRebaseTasks) {
   const w = rebaseWarningModel(needsRebaseTasks);
   if (!w) return null;
-  return `⚠️ **Rebase owed — your queue is GATED.** ${w.count} ${w.noun} can't land and block new claims until you rebase + re-ship (or \`/builder-release\`) ${w.pronoun}: ${w.refs}.`;
+  return `⚠️ ${surface.strong('Rebase owed — your queue is GATED.')} ${w.count} ${w.noun} can't land and block new claims`
+    + ` until you rebase + re-ship (or ${surface.code(surface.action('release'))}) ${w.pronoun}: ${w.refs}.`;
 }
 
 // The widget warning block (Tabler alert icon, danger-tinted), or '' when none.
@@ -302,6 +307,9 @@ const CARD_DIRECTIVE = {
   markdown: '[otb-card] stdout is the finished /builder-start card (markdown). Output it verbatim as your reply, then stop — no rebuilt table, recommendation, nudge, or recap.',
 };
 function emitCardDirective(form) {
+  // Addressed to the model, not the reader. A terminal user has no card to relay and no
+  // show_widget to call, so this line is pure confusion there (task 1003680).
+  if (surface.isTerminal()) return;
   process.stderr.write(CARD_DIRECTIVE[form] + '\n');
 }
 
@@ -550,20 +558,20 @@ function isLocalOrigin(origin) {
 // ships inside the PRIVATE @bongos/core package) even exists.
 function instanceNotRunningCard({ origin, depsMissing } = {}) {
   const out = [];
-  out.push(`**builder-start — this instance isn't reachable yet**`);
+  out.push(surface.strong("builder-start — this instance isn't reachable yet"));
   out.push('');
 
   if (!isLocalOrigin(origin)) {
-    out.push(`I couldn't reach \`${origin}\`. That instance is **hosted** — it isn't this machine's server to start, so there's nothing to bring up here.`);
+    out.push(`I couldn't reach ${surface.code(origin)}. That instance is ${surface.strong('hosted')} — it isn't this machine's server to start, so there's nothing to bring up here.`);
     out.push('');
-    out.push(`1. **The board is a website, and it needs nothing installed** — open ${origin}/builders to see and claim work right now.`);
+    out.push(`1. ${surface.strong('The board is a website, and it needs nothing installed')} — open ${origin}/builders to see and claim work right now.`);
     out.push(`2. If that doesn't load either, the instance itself is down: \`curl -sI ${origin}/healthz\` says whether it's answering.`);
-    out.push(`3. Once it answers, re-run \`/builder-start\`.`);
+    out.push(`3. Once it answers, re-run ${surface.code(surface.action('start'))}.`);
     out.push('');
-    out.push(`**Don't run \`bongos dev\` for this.** It stands up a *separate local* instance with its own empty database — it cannot show you this board, and it would hide the outage behind an empty one.`);
+    out.push(`${surface.strong(`Don't run ${surface.code('bongos dev')} for this.`)} It stands up a separate local instance with its own empty database — it cannot show you this board, and it would hide the outage behind an empty one.`);
     if (depsMissing) {
       out.push('');
-      out.push(`(The \`bongos\` CLI isn't installed here. It's optional — the website above is the same board. \`@bongos/core\` is a **private** package, so installing it needs an \`NPM_TOKEN\`; a 404 without one is expected, not a missing version.)`);
+      out.push(`(The ${surface.code('bongos')} CLI isn't installed here. It's optional — the website above is the same board. ${surface.code('@bongos/core')} is a ${surface.strong('private')} package, so installing it needs an ${surface.code('NPM_TOKEN')}; a 404 without one is expected, not a missing version.)`);
     }
     return out.join('\n');
   }
@@ -575,7 +583,7 @@ function instanceNotRunningCard({ origin, depsMissing } = {}) {
     out.push(`${n++}. \`npm install\` — installs the toolchain first (the \`bongos\` CLI ships inside \`@bongos/core\`, so nothing else runs until this does).`);
   }
   out.push(`${n++}. \`bongos dev\` — one command: starts Postgres, builds the tables, runs the server, and signs you in.`);
-  out.push(`${n++}. Re-run \`/builder-start\`.`);
+  out.push(`${n++}. Re-run ${surface.code(surface.action('start'))}.`);
   out.push('');
   out.push(`Meant to work on a *different* instance that's already running? Sign in to it with \`bongos login <url>\` first.`);
   return out.join('\n');
@@ -800,7 +808,7 @@ async function main() {
       ? b.preferred_disciplines.join(' + ')
       : 'all disciplines';
     const credits = Number(b.total_credits || 0).toLocaleString();
-    console.log(`**builder-start** · ${b.github_login} (${rankLabel}) · ${credits} credits · ${discLabel}`);
+    console.log(`${surface.strong('builder-start')} · ${b.github_login} (${rankLabel}) · ${credits} credits · ${discLabel}`);
     const sk = me.data.streak;
     if (sk && Number(sk.current) > 0) {
       console.log(`🔥 ${sk.current}-day streak${Number(sk.longest) > Number(sk.current) ? ` · longest ${sk.longest}` : ''}`);
@@ -847,16 +855,18 @@ async function main() {
   // not block — feedback_parallel_sessions). Ids are hall links (ref rule).
   if (me.ok) {
     const myClaims = me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : []);
-    const heldActions = (id) => `    → ship: \`/builder-ship ${id}\`  ·  release: \`/builder-release ${id}\`  ·  open: [#${id}](${HALL_TASK}${id})`;
+    const heldActions = (id) => `    → ship: ${surface.code(surface.action('ship', id))}`
+      + `  ·  release: ${surface.code(surface.action('release', id))}`
+      + `  ·  open: ${surface.taskRef(id, HALL_TASK)}`;
     if (myClaims.length === 1) {
       const c = myClaims[0];
-      console.log(`You're holding [#${c.task_id}](${HALL_TASK}${c.task_id}) — ${clip(c.title, 56)}`);
+      console.log(`You're holding ${surface.taskRef(c.task_id, HALL_TASK)} — ${clip(c.title, 56)}`);
       console.log(heldActions(c.task_id));
       console.log('');
     } else if (myClaims.length > 1) {
       console.log(`You're holding ${myClaims.length} claims (parallel sessions OK):`);
       for (const c of myClaims) {
-        console.log(`  [#${c.task_id}](${HALL_TASK}${c.task_id}) — ${clip(c.title, 50)}`);
+        console.log(`  ${surface.taskRef(c.task_id, HALL_TASK)} — ${clip(c.title, 50)}`);
         console.log(heldActions(c.task_id));
       }
       console.log('');
@@ -869,7 +879,7 @@ async function main() {
     console.log(
       `🚦 ${s.versionId} looks ready to close ` +
       `(${s.criteriaSatisfied}/${s.criteriaTotal} criteria, ${s.percentComplete}% weighted; ` +
-      `${s.tasksShipped} shipped, ${s.tasksCarryOver} carry-over). Run /builder-version-close ${s.versionId}.`
+      `${s.tasksShipped} shipped, ${s.tasksCarryOver} carry-over). Run ${surface.action('version-close', s.versionId)}.`
     );
     console.log('');
   }
@@ -882,7 +892,7 @@ async function main() {
     fit && `fit=${fit}`,
   ].filter(Boolean);
   const filterNote = filterBits.length ? ` (${filterBits.join(', ')})` : '';
-  console.log(`**Claim one to start** — ${filtered.length} ready for you right now${matched}${filterNote}:`);
+  console.log(`${surface.strong('Claim one to start')} — ${filtered.length} ready for you right now${matched}${filterNote}:`);
   console.log('');
   if (claimable.length) {
     const cardRows = claimable.slice(0, CARD_ROWS);
@@ -890,10 +900,13 @@ async function main() {
     const moreN = filtered.length - cardRows.length;
     if (moreN > 0) {
       console.log('');
-      console.log(`_…and ${moreN} more — say "show all", or run with --limit 30._`);
+      console.log(surface.em(`…and ${moreN} more — say "show all", or run with --limit 30.`));
     }
   } else {
-    console.log("_Nothing claimable right now — everything is in flight, blocked, or shipped. Run /blocker-review to see what's stuck._");
+    console.log(surface.em(
+      "Nothing claimable right now — everything is in flight, blocked, or shipped."
+      + (surface.isTerminal() ? '' : " Run /blocker-review to see what's stuck.")
+    ));
   }
 
   // Cross-discipline pointer (one line) — only when preference-routed.
@@ -908,7 +921,7 @@ async function main() {
 
   // ---------- next ----------
   console.log('');
-  console.log('→ **Tell me a number** to claim it.');
+  console.log(`→ ${surface.isTerminal() ? `Claim one with ${surface.code('bongos claim <id>')} in a checkout` : `${surface.strong('Tell me a number')} to claim it`}.`);
   if (full) {
     console.log('');
     console.log('Commands:');

package/scripts/gds/surface.js

@@ -0,0 +1,89 @@
+// scripts/gds/surface.js — who is reading this output: an agent, or a person in a terminal?
+// (task 1003680, follow-up to ADR 0258.)
+//
+// WHY THIS EXISTS
+// The CLI's cards were written for exactly one reader: a Claude Code session. They carry
+// `[otb-card]` directives addressed to the model, `/builder-ship N` slash commands, and markdown
+// link syntax — all correct in a chat feed, all wrong in a terminal. That stayed invisible while
+// the CLI lived inside the private core, because the only way to run it was from a session.
+// `@cloudbongos/cli` (ADR 0258) put the same output in front of newcomers on a bare laptop, where
+// the first thing they read is an instruction written to somebody else and a command that does
+// not exist.
+//
+// HOW THE SURFACE IS DECIDED — and why not isTTY
+// AGENT is the default, so nothing about the Claude Code path changes unless something opts out.
+// The opt-out is `BONGOS_SURFACE=terminal`, set by the `bongos` DISPATCHER (bin/bongos.js, and the
+// generated one in the public package) when it spawns a verb. The skills and the card-delivery
+// hook run `node scripts/gds/<verb>.js` DIRECTLY, never through the dispatcher, so they keep the
+// agent shape byte-for-byte.
+//
+// `process.stdout.isTTY` would get this exactly backwards: a Claude Code session's stdout is not a
+// TTY either, so TTY-sniffing would classify every agent run as a terminal and break the card
+// contract the skills depend on. The signal has to be an explicit statement of intent, not a guess.
+
+'use strict';
+
+const AGENT = 'agent';
+const TERMINAL = 'terminal';
+
+// Which reader is this output for? Pure: takes the env, returns a string.
+function resolveSurface(env = process.env) {
+  const raw = String((env && env.BONGOS_SURFACE) || '').trim().toLowerCase();
+  return raw === TERMINAL ? TERMINAL : AGENT;
+}
+
+function isTerminal(env = process.env) {
+  return resolveSurface(env) === TERMINAL;
+}
+
+// A task reference. Agents get a hall link because a bare `#NNN` autolinks to GitHub issues and
+// 404s (the CLAUDE.md ref rule); a terminal reader gets the plain id and the URL beside it, since
+// `[#123](https://…)` is just noise on a console.
+function taskRef(id, url, env = process.env) {
+  return isTerminal(env) ? `#${id}` : `[#${id}](${url}${id})`;
+}
+
+// An action the reader can actually run. In a session that is the slash command; in a terminal it
+// is the `bongos` verb. `/builder-ship 123` does not exist outside Claude Code.
+function action(verb, arg, env = process.env) {
+  const tail = arg == null ? '' : ` ${arg}`;
+  return isTerminal(env) ? `bongos ${verb}${tail}` : `/builder-${verb}${tail}`;
+}
+
+// Markdown emphasis is decoration in a feed and literal asterisks on a console.
+function strong(s, env = process.env) {
+  return isTerminal(env) ? String(s) : `**${s}**`;
+}
+function em(s, env = process.env) {
+  return isTerminal(env) ? String(s) : `_${s}_`;
+}
+function code(s, env = process.env) {
+  return isTerminal(env) ? String(s) : `\`${s}\``;
+}
+
+// A table. Agents get GitHub-flavoured markdown (the feed renders it); a terminal gets columns
+// padded to width with a rule under the header, which is what a console can actually align.
+function table(headers, rows, env = process.env) {
+  if (!isTerminal(env)) {
+    return [
+      `| ${headers.join(' | ')} |`,
+      `|${headers.map(() => '---').join('|')}|`,
+      ...rows.map((r) => `| ${r.join(' | ')} |`),
+    ].join('\n');
+  }
+  const widths = headers.map((h, i) => Math.max(
+    String(h).length,
+    ...rows.map((r) => String(r[i] == null ? '' : r[i]).length),
+  ));
+  const line = (cells) => cells
+    .map((c, i) => String(c == null ? '' : c).padEnd(widths[i]))
+    .join('  ')
+    .replace(/\s+$/, '');
+  return [
+    line(headers),
+    widths.map((w) => '─'.repeat(w)).join('  '),
+    ...rows.map(line),
+  ].join('\n');
+}
+
+module.exports = { AGENT, TERMINAL, resolveSurface, isTerminal, taskRef, action, strong, em, code, table };

package/src/bongos/auth-admission.js

@@ -394,9 +394,70 @@ async function safeSyncRankRole(builder) {
 }
 
 
+// readApplicantProfileFromHub(githubId) — the reviewer queue's LIVE read of one
+// applicant's profile view from the hub (privacy spec D7, task 1002972). The
+// project side of POST /sso/applicant-profile.
+//
+// WHY IT LIVES IN THE KERNEL AND NOT IN THE onboarding MODULE THAT USES IT. The
+// call is authenticated with this instance's HUB CLIENT SECRET, and
+// loadIdpConfig is deliberately not on the doorway — putting it there would hand
+// every module the credential that speaks for this whole project. So the secret
+// stays in core beside the two other hub calls that hold it
+// (reportMembershipCheckIn, reportActivityRollup) and the module reaches a
+// NARROW port instead: one github_id in, one already-bounded view out.
+//
+// RESOLVED FRESH ON EVERY CALL — no cache, no memo, no store. That is D7's
+// "evaluated LIVE at review time, never a snapshot" (spec C2), and the reason a
+// hub outage answers null rather than a stale-but-helpful last-known value: an
+// applicant who hid their stats an hour ago must not have them rendered from
+// this instance's memory. The hub already sends Cache-Control: no-store; this
+// end simply keeps nothing.
+//
+// FAILS SOFT TO null, ALWAYS. A self-hosted instance with no hub (idp unset), a
+// hub that is down, a 404 for an applicant this project has no echo for, a
+// non-JSON body — every one of them is the same null, and the queue renders "no
+// record" beside a row that still shows its login, note and vouch pill. A
+// reviewer losing the profile block is a degraded queue; a queue that fails to
+// load because the hub is slow is a broken one, and admission does not depend on
+// any of this (ADR 0016).
+//
+// BOUNDED IN TIME, which is what makes the paragraph above true rather than
+// aspirational (task 1003681, grader finding). This is the only hub call that
+// FANS OUT: the other two fire at most once per sign-in or per ship, while this
+// one runs up to MAX_LIVE_PROFILE_READS (25) times concurrently inside the
+// Promise.all that GET /access-requests awaits. Unbounded, one unresponsive hub
+// holds the whole reviewer queue open for as long as the socket lives — the
+// exact "broken one" this comment disclaims. The timeout converts that into the
+// null this function already promises on every other failure.
+const APPLICANT_PROFILE_TIMEOUT_MS = 5000;
+
+async function readApplicantProfileFromHub(githubId) {
+  const idp = loadIdpConfig();
+  if (!idp || githubId == null) return null;
+  try {
+    const r = await fetch(`${idp.origin}/api/gds/sso/applicant-profile`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': userAgent() },
+      signal: AbortSignal.timeout(APPLICANT_PROFILE_TIMEOUT_MS),
+      body: JSON.stringify({
+        client_id: idp.clientId,
+        client_secret: idp.clientSecret,
+        github_id: githubId,
+      }),
+    });
+    if (!r.ok) return null;
+    const body = await r.json().catch(() => null);
+    return (body && body.profile) || null;
+  } catch (err) {
+    log.info('[auth] hub applicant-profile read failed (non-blocking):', err.message);
+    return null;
+  }
+}
+
 module.exports = {
   firstAdminLogin,
   firstTimeAdmissionBlocked,
+  readApplicantProfileFromHub,
   // Re-exported, not defined here (task 1003579 moved it to project-door.js with
   // the two knobs it composes against). auth.js, the doorway's api.joinabilityMode
   // and four test files import it by this path, and the read-back it answers —

package/src/bongos/auth.js

@@ -55,7 +55,7 @@ const ic = require('../instance-config');
 const { branding, userAgent } = require('../branding');
 
 const { SCOPE, authConfigured, grantedScopeCoversRepos, idpConfigured, idpEnabled, loadIdpConfig, scopeForWebFlow } = require('./auth-config.js');
-const { firstAdminLogin, firstTimeAdmissionBlocked, joinabilityMode, maybeSeatFirstAdmin, membershipKind, openEnrollmentEnabled, webAdmissionStatus } = require('./auth-admission.js');
+const { firstAdminLogin, firstTimeAdmissionBlocked, joinabilityMode, maybeSeatFirstAdmin, membershipKind, openEnrollmentEnabled, readApplicantProfileFromHub, webAdmissionStatus } = require('./auth-admission.js');
 const { buildAuthorizeUrl, completeWebFlow, pollDeviceFlow, startDeviceFlow } = require('./auth-github.js');
 const { buildIdpAuthorizeUrl, completeDeviceExchange, completeIdpFlow, idpAuthorizeUrl, loadHubPublicKey, logoutTokenJtiSeenAndRecord, verifyHubAssertion, verifyHubLogoutToken } = require('./auth-idp.js');
 const { addDiscordGuildMember, buildDiscordAuthorizeUrl, discordAuthorizeUrl, discordBotConfigured, discordConfigured, exchangeDiscordCode, fetchDiscordUser, isValidDiscordUserId, loadDiscordBotToken, loadDiscordCreds, removeDiscordGuildMember } = require('./auth-discord.js');
@@ -787,6 +787,7 @@ module.exports = {
   idpConfigured,
   openEnrollmentEnabled,
   joinabilityMode,
+  readApplicantProfileFromHub,
   firstTimeAdmissionBlocked,
   webAdmissionStatus,
   firstAdminLogin,

package/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // 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.579'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.581'; // 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');
@@ -273,6 +273,16 @@ 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),
+  // 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
+  //     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. A module passes one github_id and gets one
+  //     already-bounded view (or null) — it can neither widen the request nor
+  //     re-address it. Fails soft to null on every error, so a hub outage costs
+  //     the profile block and never the queue.
+  get readApplicantProfileFromHub() { return require('./bongos/auth').readApplicantProfileFromHub; },
   // userAgent — the instance's HTTP User-Agent string (branding-derived). The
   // carved lifecycle module's github-push.js stamps every GitHub API request with
   // it instead of reaching into src/branding.js directly (BV1.R86).

package/tests/adr_renumber_integrity.mjs

@@ -0,0 +1,84 @@
+// tests/adr_renumber_integrity.mjs — a renumbered ADR must move ALL of itself
+// (task 1003681, from a grader finding).
+//
+// Renumbering an ADR is not one edit, it is four, and `fitness.js` only checks
+// two of them (numbers are unique, and the index has one row per file). This
+// pins the other two, plus the class of stale reference that caused the finding.
+//
+// THE INCIDENT. Task 1002972's branch authored ADR 0241 while main landed a
+// DIFFERENT 0241; the collision failed fitness and stranded the PR for four
+// days. Renumbering the never-landed one to 0260 moved its filename, its
+// heading and its index row's link — but left its own session log still saying
+// "ADR 0241" in prose, twice. Because 0241 is a REAL, DIFFERENT, ALREADY-LANDED
+// ADR, that is worse than a dangling link: a reader follows it and arrives,
+// with no error, at the wrong decision. `docs-entropy.js` cannot see this — it
+// resolves LINKS, and these were bare prose references to a number that does
+// resolve, just to something else.
+//
+// What each check would have caught:
+//   • heading vs filename — a rename that forgot the `# ADR NNNN` line
+//   • index row number vs its own link target — a row renumbered IN PLACE
+//     (which is also how the row ended up sorted between 0240 and 0241)
+//   • the session log's references — the finding itself, as a regression pin
+//
+// Run:  node --test --test-reporter=tap tests/adr_renumber_integrity.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const ADR_DIR = path.join(ROOT, 'docs', 'adr');
+
+const adrFiles = fs
+  .readdirSync(ADR_DIR)
+  .filter((f) => f.endsWith('.md') && /^\d{4}-/.test(f))
+  .sort();
+
+test('every ADR file’s heading carries its own number — a rename must move the heading too', () => {
+  assert.ok(adrFiles.length > 200, 'the ADR corpus should be substantial; a tiny count means the glob broke');
+  const wrong = [];
+  for (const f of adrFiles) {
+    const fileNum = /^(\d{4})-/.exec(f)[1];
+    const first = fs.readFileSync(path.join(ADR_DIR, f), 'utf8').split(/\r?\n/)[0];
+    // both conventions ship in this corpus: "# ADR 0259 — …" and "# 0001 — …"
+    const heading = /^#\s*(?:ADR\s*)?(\d{4})\b/.exec(first);
+    if (!heading) { wrong.push(`${f} :: heading carries no number (${first.slice(0, 60)})`); continue; }
+    if (heading[1] !== fileNum) wrong.push(`${f} :: heading says ${heading[1]}`);
+  }
+  assert.deepEqual(wrong, [], 'an ADR whose heading and filename disagree is a half-finished renumber');
+});
+
+test('every index row’s number matches the file it links — a row renumbered in place is caught here', () => {
+  const readme = fs.readFileSync(path.join(ADR_DIR, 'README.md'), 'utf8');
+  const rows = readme.split(/\r?\n/).filter((l) => /^\|\s*\d{4}\s*\|/.test(l));
+  assert.ok(rows.length > 200, 'the index should carry a row per ADR');
+  const wrong = [];
+  for (const row of rows) {
+    const rowNum = /^\|\s*(\d{4})\s*\|/.exec(row)[1];
+    // A row's summary CITES many other ADRs, so the first `](NNNN-….md)` is
+    // usually a citation. The row's OWN target is the one closing its
+    // `[**Title**](…)` cell — i.e. the last link before the trailing category
+    // cell. Matching the first one instead reports ~60 false mismatches.
+    const link = /\]\((\d{4})-[^)]*\.md\)\s*\|[^|]*\|\s*$/.exec(row);
+    if (!link) continue; // a handful of legacy rows link elsewhere or not at all
+    if (link[1] !== rowNum) wrong.push(`row ${rowNum} links ${link[1]}-…`);
+  }
+  assert.deepEqual(wrong, [], 'a row whose number and link disagree sends every citation to the wrong ADR');
+});
+
+test('the ADR that was renumbered out of a collision leaves no reference to its old number (task 1003681)', () => {
+  // The regression itself. 0241 is a real, different, landed ADR — so a stale
+  // reference here resolves silently to the wrong decision rather than 404ing,
+  // which is exactly why no link checker flagged it.
+  const log = path.join(ROOT, 'docs', 'session-logs', '2026-09-03-goal-1000045-applicant-profile-d7.md');
+  const src = fs.readFileSync(log, 'utf8');
+  assert.doesNotMatch(src, /ADR 0241\b/, 'this task’s ADR moved to 0260; 0241 now names the artist-gate decision');
+  assert.match(src, /ADR 0260\b/, 'the log must cite the decision it actually produced');
+  assert.ok(
+    fs.existsSync(path.join(ADR_DIR, '0260-the-application-is-the-consent-and-the-echo-is-the-gate.md')),
+    'and that ADR must exist under the number the log now cites',
+  );
+});