@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/linkify-refs.js

@@ -0,0 +1,655 @@
+#!/usr/bin/env node
+// linkify-refs.js — rewrite bare "#NNN" GDS references in docs into explicit
+// markdown links to the Builders' Hall deep-link resolver, so they STOP
+// colliding with GitHub's built-in PR/issue autolinker when the docs are read
+// on github.com.
+//
+// THE PROBLEM. Our docs reference GDS ids as bare "#NNN". GitHub, viewing
+// markdown in the repo, auto-links every "#NNN" to PR/issue #NNN — a SEPARATE
+// number space from our task/idea/blocker ids. Early on task#≈PR# so it
+// coincidentally worked; they've since diverged, so "#170" now lands on an
+// unrelated PR (or a dead number). An explicit markdown link —
+// [#170](https://…/#/task/170) — suppresses GitHub's autolinker AND points at
+// the right record.
+//
+// THREE RESOLVABLE KINDS (#629). The hall resolves /#/task/N, /#/idea/N and
+// /#/blocker/N (DEEPLINK_RE in public-builders/builders.js), so this linkifier
+// classifies a ref by its surrounding noun and links it to the matching
+// resolver. A ref whose id is NOT in the matching public id set, and any other
+// entity that has no resolver (session/migration/report/learning/builder/…),
+// is NEUTRALIZED instead — wrapped in a code span (`#N`) that GitHub never
+// autolinks — so it can't 404 yet also can't mis-link.
+//
+// THE RISK. A WRONG rewrite (pointing a number at the wrong thing) just
+// recreates the complaint. So the classifier is deliberately conservative —
+// it links a "#NNN" ONLY when ALL of these hold:
+//   • NNN is a real id of the classified kind (fetched live from the public
+//     /api/bongos/public/ref-ids allow-list; PR-only numbers are therefore never
+//     touched, and an idea id is never linked as a task).
+//   • It is a bare reference — NOT a markdown heading anchor like
+//     `](#12-session-update-protocol)` (digits followed by `-`/word chars), and
+//     NOT already link text `[#170]` or a link target `](#170)`.
+//   • It is not inside an inline code span or a fenced code block (with the one
+//     exception of upgrading a prior `#N` idea/blocker NEUTRALIZATION — see
+//     upgradeLineCodeSpans).
+// Anything ambiguous is left bare/neutralized — a missed link is strictly safer
+// than a wrong one.
+//
+// USAGE
+//   node scripts/bongos/linkify-refs.js                 # dry-run on the default index docs
+//   node scripts/bongos/linkify-refs.js --apply         # write the changes
+//   node scripts/bongos/linkify-refs.js --check          # CI gate: non-zero exit if any bare/upgradeable ref remains
+//   node scripts/bongos/linkify-refs.js --apply docs/x.md CLAUDE.md   # explicit file set
+//   node scripts/bongos/linkify-refs.js --ids 1,2,3 ... # offline: supply the task-id set
+//
+// The core linkifyText() is a pure function (exported) so it can be unit-tested
+// without the API or the filesystem (see tests/linkify_refs.mjs).
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// The Builders' Hall deep-link resolver bases (task/idea/blocker), derived from the
+// instance's STABLE public hall — branding.domains.buildersOrigin, falling back to
+// publicOrigin. Deliberately NOT the env-overridable API_BASE: these bases get
+// WRITTEN INTO COMMITTED markdown, so a per-dev CLOUDBONGOS_API_BASE=localhost
+// override must never leak into a committed doc link (task 1002234; the committed-doc
+// twin of the task-1002233 printed-link fix, which purged the last hardcoded
+// `https://example.com`). When branding is unreadable the base is the
+// root-relative '/builders#/…' — never a hardcoded founder host. Reading branding is
+// a sync file read (no network), safe at module scope for this token-free CI gate.
+// A LOOPBACK origin is treated exactly like an unreadable one — root-relative,
+// never written out (task 1003542; the committed-doc half of task 1002975).
+//
+// The header above promises a per-dev localhost override "must never leak into a
+// committed doc link", and the API_BASE half of that holds. But the BRANDING half
+// did not: config/branding.neutral.json — the neutral core's own default, used by
+// every checkout with no instance branding — sets buildersOrigin to
+// http://localhost:3000. So `--apply` on a core checkout rewrote bare refs into
+// http://localhost:3000/builders#/task/N and committed them.
+//
+// That was survivable only while the gate was blind: it matched \d{1,5} and this
+// instance's ids are 7 digits, so --apply found nothing to rewrite. Widening the
+// width in this task ARMS it — the first honest run wanted to rewrite 33 refs
+// across 10 committed docs, ADRs included. Hence this guard lands with the widening
+// rather than after it.
+//
+// Root-relative is the right fallback, not a guess: it is what the catch below
+// already returns, and it resolves correctly on whatever host actually serves the
+// hall — which is more than a baked absolute origin can promise.
+function isLoopbackOrigin(origin) {
+  try {
+    // URL keeps an IPv6 literal in its brackets ('[::1]'), so strip them before
+    // comparing — a caught-by-its-own-test detail, not a hypothetical.
+    const host = new URL(origin).hostname.replace(/^\[|\]$/g, '');
+    return host === 'localhost' || host === '::1' || host === '0.0.0.0'
+      || host.endsWith('.localhost')
+      || /^127\./.test(host); // the whole 127.0.0.0/8 loopback block, not just .0.1
+  } catch (_) {
+    return false; // not a parseable absolute URL → not a loopback origin
+  }
+}
+
+function resolverHallRoot() {
+  try {
+    const d = (require('../../src/branding').branding().domains) || {};
+    const origin = (typeof d.buildersOrigin === 'string' && d.buildersOrigin.trim())
+      || (typeof d.publicOrigin === 'string' && d.publicOrigin.trim())
+      || '';
+    if (!origin || isLoopbackOrigin(origin)) return '/builders#';
+    return `${String(origin).replace(/\/+$/, '')}/builders#`;
+  } catch (_) {
+    return '/builders#';
+  }
+}
+const RESOLVER_HALL_ROOT = resolverHallRoot();
+const RESOLVER_BASE = `${RESOLVER_HALL_ROOT}/task/`;
+const RESOLVER_BASE_IDEA = `${RESOLVER_HALL_ROOT}/idea/`;
+const RESOLVER_BASE_BLOCKER = `${RESOLVER_HALL_ROOT}/blocker/`;
+// API_BASE (env → session → branding default) comes from cli-lib (the single
+// source) — used ONLY for the RUNTIME /public/ref-ids fetch below, never for the
+// committed link bases above. Safe for this token-free CI gate: cli-lib does no
+// eager session read or network at module scope.
+const { API_BASE } = require('./cli-lib');
+
+// Every hand-authored markdown file that a reader sees rendered on github.com:
+// the root CLAUDE.md/README.md plus all of docs/** (session-logs included). A
+// "GENERATED FILE" marker means the bare refs reappear on the next regen, so
+// the generator — not its output — is where those get fixed; skip them here.
+// PATHS COME BACK POSIX-STYLE, on every platform (task 1003935). path.join gives
+// OS-native separators, so on Windows this used to return 'docs\\adr\\0001-….md'.
+// Three things read these paths and only one of them tolerates that: fs accepts
+// either separator on Windows, but the --check report PRINTS them (so CI output
+// differed by platform for identical content) and the test that pins recursion
+// into docs/ compares against 'docs/' — which is how a permanently-red case hid
+// for months in a file no lane ran. Normalising here, at the one boundary that
+// produces them, is cheaper than teaching every consumer to be separator-aware.
+function discoverDocs() {
+  const out = [];
+  const walk = (rel) => {
+    const abs = path.resolve(process.cwd(), rel);
+    if (!fs.existsSync(abs)) return;
+    if (fs.statSync(abs).isDirectory()) {
+      for (const name of fs.readdirSync(abs).sort()) walk(path.join(rel, name));
+    } else if (rel.endsWith('.md')) {
+      out.push(rel.split(path.sep).join('/'));
+    }
+  };
+  for (const root of ['CLAUDE.md', 'README.md', 'docs']) walk(root);
+  // The skip marker matched only the literal "GENERATED FILE" — and NO generator in
+  // this repo writes that (task 1003542). gen-api-docs.js heads both of its outputs
+  // with "GENERATED by scripts/bongos/gen-api-docs.js", so docs/api-reference.md and
+  // docs/routes-permissions.md were being linkified despite the rule above: their
+  // rewrites survive exactly until the next regen, and meanwhile ship-check reports
+  // api-docs STALE. Two gates fighting over one file, each correctly.
+  //
+  // Latent until now for the same reason as the loopback leak: the matcher was too
+  // narrow to rewrite anything, so nothing was ever written into a generated file.
+  // Widening it in this task is what surfaced this.
+  //
+  // NOTE docs/copy-inventory.md heads with "**Generated** by" — bolded, so not
+  // contiguous and still unmatched here. Left alone deliberately: it carries no bare
+  // refs today, and inventing a looser pattern risks skipping a hand-authored doc
+  // that merely mentions being generated. Fix its marker at the generator if it ever
+  // grows one.
+  return out.filter((rel) =>
+    !/GENERATED (?:FILE|by)\b/i.test(fs.readFileSync(path.resolve(process.cwd(), rel), 'utf8').slice(0, 200))
+  );
+}
+
+// "#NNN" preceded by an IDEA / BLOCKER noun → that kind's resolver (#629). These
+// are checked before the generic ENTITY_RE so an idea/blocker ref links rather
+// than merely neutralizing.
+const IDEA_CTX_RE = /\b(idea_inbox|ideas?)[`'")\s(:]*$/i;
+const BLOCKER_CTX_RE = /\b(blockers?)[`'")\s(:]*$/i;
+// "#NNN" preceded by one of these nouns denotes a DIFFERENT entity that shares
+// the integer space with tasks but has NO resolver (a session ordinal, a
+// migration number, a security-report id, a learning, a builder, …). Those must
+// never be rewritten to a resolver URL — a wrong link is the exact bug we're
+// fixing. But leaving them BARE is also a bug: GitHub autolinks any bare "#NNN"
+// to its own PR/issue space, which 404s. So these are NEUTRALIZED — wrapped in a
+// code span (`#170`) GitHub never autolinks. ("task"/"tasks" is deliberately
+// NOT here: those ARE refs we want to linkify; idea/blocker are handled above.)
+// The trailing class tolerates a closing backtick / quote / opening paren /
+// colon so "`security_reports` (#2)" still classifies.
+const ENTITY_RE = /\b(idea_inbox|ideas?|blockers?|sessions?|migrations?|criteri(?:on|a)|(?:security[_ ]?)?reports?|learnings?|builders?|claims?|intents?|findings?|achievements?)[`'")\s(:]*$/i;
+// "#NNN" preceded by a GitHub-namespace noun (a PR ref) genuinely lives in
+// GitHub's number space — a bare "#NNN" there autolinks CORRECTLY, so it is
+// the one class we leave completely alone.
+const GITHUB_NS_RE = /\b(pull requests?|pull|prs?)[`'")\s(:]*$/i;
+// Pure list glue between two refs ("#1, #2" / "#1 and #2" / "#2–#11") — lets a
+// classification carry across a list or range so "blockers #1, #2" and
+// "reports #2–#11" treat BOTH ends the same way.
+const LIST_GLUE_RE = /^[\s,–—-]*(?:and|&|\+|or|to|through)?[\s,–—-]*$/i;
+
+// An existing markdown link of the TASK-resolver form this script writes:
+// [#N](…/builders#/task/N). Used only to undo PAST task-resolver mis-links of
+// entity/idea/blocker refs; the idea/blocker resolver links are left alone.
+// HOST-AGNOSTIC (task 1002234 part b): matches any http(s) host OR a root-relative
+// '/builders#/…', so the mislink-cleanup path still recognizes a link a PRIOR run
+// committed under a DIFFERENT host — the legacy `example.com` links, a
+// co-tenant's, or this instance's own — not only the current RESOLVER_BASE host.
+// How many digits a bare "#NNN" may carry — ONE source of truth, because the
+// width had drifted out of date in five places at once (task 1003542).
+//
+// It was {1,5}, a PRE-IMPORT id width. This instance renumbered imported tasks
+// +1,000,000, so every live id is SEVEN digits — and both enforcement points
+// silently stopped enforcing: `linkify-refs.js --check` (the CI gate) passed
+// trivially on a doc containing a bare #1003365, and .claude/hooks/stop-refcheck.js
+// fast-path-exited before it even fetched the allow-list. A guard that matches
+// nothing reports clean, which is indistinguishable from a guard that works.
+//
+// 7 keeps the property {1,5} was chosen for — not over-matching PR-shaped numbers.
+// GitHub PR numbers on this repo are 3 digits, well inside the old range, so the
+// bound was never what separated them; classifyKind's `PR #NNN` left-context test
+// is, and it is untouched here.
+//
+// Exported as the SOURCE STRING, not a RegExp: a /g/ regex carries lastIndex
+// between calls, so a shared instance would skip matches depending on who scanned
+// last. Each site builds its own.
+const REF_DIGITS = '\\d{1,7}';
+
+// ---- the ordinal-prose guard (task 1002975) --------------------------------
+//
+// THE BUG. With no context word, a bare `#N` was linkified on ID EXISTENCE ALONE:
+// the prose "side door #1" became a link to task 1, while its sibling "side door
+// #2" survived only because no id 2 exists. That is luck, not grammar, and task
+// 1002974 had to repair a committed doc because of it.
+//
+// THE RULE, AND WHY IT IS A WIDTH RULE. The originating row proposed "a preceding
+// bare noun without task/idea/blocker context words → leave alone". Measured
+// against the actual corpus, that is far too broad: running linkifyText over every
+// committed .md with a maximally permissive id set rewrites 231 context-less refs,
+// 77 of them preceded by a bare word — and 49 of those are GENUINE ("the #506",
+// "by #435", "under #436"). Skipping on the preceding noun alone would leave ~49
+// real refs bare, which is exactly the GitHub-mis-autolink harm this script exists
+// to prevent. So the noun test alone would have traded one defect for a worse one.
+//
+// What DOES separate them in the corpus is WIDTH. All 28 word-preceded refs of 1–2
+// digits are ordinal prose — "§Decision #4" (an ADR section, 13 of them), "limiter
+// #4", "limiter #5", "idea fixture #1", "fixture #4", "ask #1", "and #7", "with
+// #5" — and every word-preceded ref of 3+ digits is a real task. Ordinals in
+// English prose are small; the ids these docs cite are not. Hence: no context
+// word, AND a bare word immediately before, AND at most two digits.
+//
+// Both conjuncts are load-bearing. Drop the width and 49 real refs go bare; drop
+// the preceding-word test and "(#1)" or a line-leading "#7" — which the corpus
+// shows are ordinarily genuine — stop linking too.
+//
+// Known cost, accepted: "PMS-V2 #37" and "the #54" are legacy two-digit refs that
+// now stay bare. Two ambiguous links lost against ~26 false ones fixed, and a bare
+// "#37" with no entity word is ambiguous to a human reader as well.
+//
+// This lands in linkifyText rather than beside it because `.claude/hooks/
+// stop-refcheck.js` classifies by CALLING linkifyText — so the same prose stops
+// being flagged in chat by the same change, with no second copy of the rule.
+// The one context word the guard must stand down for. There is deliberately NO
+// task entry in classifyKind — "task #170" is handled by the DEFAULT path (no
+// kind, id exists → link), because a task is the thing this resolver is for. That
+// leaves "task #3" looking exactly like "limiter #4" to a width rule, and the
+// first cut of this guard ate it. Caught by its own test, which is why the test
+// exists. Not folded into ENTITY_RE: that set means "shares the integer space
+// with tasks but is NOT one", and adding `task` there would neutralize every
+// "task #N" into a code span.
+const TASK_CTX_RE = /\b(tasks?)[`'")\s(:]*$/i;
+// Words that INTRODUCE a reference rather than being the noun it counts. The row
+// asked for "a preceding bare NOUN", and these are not nouns: "see #2" is a real
+// ref and the Stop hook is right to block it in chat, which is how this omission
+// was caught — tests/stop_refcheck.mjs went red on exactly that string.
+//
+// Kept deliberately short, and checked against the corpus rather than guessed: the
+// 1–2 digit word-preceded refs in committed docs are preceded by pms-v2 · task ·
+// the · ask · and · decision · limiter · fixture · sr · with · fixing. None of
+// these six appears there, so exempting them re-breaks nothing that was measured.
+// Words like "the", "and", "with" and "of" are NOT here on purpose — they precede
+// ordinal phrases at least as often as references ("ask #1 and #7" means the
+// questions, not two tasks).
+const ORDINAL_EXEMPT_RE = /\b(see|from|per|via|in|at)[`'")\s(:]*$/i;
+const ORDINAL_MAX_DIGITS = 2;
+// A bare word (letters, then letters/digits/'/-) immediately before the '#',
+// separated by spaces or tabs or nothing at all. Anchored at the end of the left
+// context. The whitespace is OPTIONAL because the corpus contains "SR#11" — a
+// security-review finding number, unspaced and just as much a false positive as
+// the spaced ones. Widening it is safe precisely because the width conjunct is
+// what protects real refs: every word-adjacent ref of 3+ digits is untouched
+// either way, so this only ever admits more of the same two-digit class.
+const ORDINAL_PROSE_LEFT_RE = /[A-Za-z][A-Za-z0-9'-]*[ \t]*$/;
+
+const RESOLVER_LINK_RE = new RegExp(`\\[#(${REF_DIGITS})\\]\\((?:https?:\\/\\/[^/)\\s]+)?\\/builders#\\/task\\/(${REF_DIGITS})\\)`, 'g');
+
+// Classify a ref by its left context (+ list-glue carry). Returns one of
+// 'github' | 'idea' | 'blocker' | 'entity' | null (null = candidate task ref).
+function classifyKind(left, carried, prevKind) {
+  if (GITHUB_NS_RE.test(left)) return 'github';
+  if (IDEA_CTX_RE.test(left)) return 'idea';
+  if (BLOCKER_CTX_RE.test(left)) return 'blocker';
+  if (ENTITY_RE.test(left)) return 'entity';
+  if (carried) return prevKind;
+  return null;
+}
+
+// Accept a bare Set (legacy: task ids only) or {tasks, ideas, blockers}.
+function normalizeIdSets(ids) {
+  const toSet = (v) => (v instanceof Set ? v : new Set((v || []).map(Number).filter(Number.isInteger)));
+  if (ids instanceof Set) return { tasks: ids, ideas: new Set(), blockers: new Set() };
+  return { tasks: toSet(ids && ids.tasks), ideas: toSet(ids && ids.ideas), blockers: toSet(ids && ids.blockers) };
+}
+
+// Undo PAST mis-linkifications: an entity/idea/blocker-context ref that an
+// earlier, less careful run rewrote into a TASK link ("learning [#53](task/53)"
+// — wrong target). Such links become neutral code spans (Phase 2 then upgrades
+// idea/blocker ones to their proper resolver); a GitHub-namespace one (a PR ref
+// wrongly sent to the task resolver) goes back to bare so GitHub's own
+// autolinker works again. Same accumulating left-context + list-glue carry as
+// linkifySegment so ranges ("reports [#2](u)–[#11](u)") unwrap on both ends.
+function unlinkEntitySegment(segment, leftContext, stats) {
+  let out = '';
+  let last = 0;
+  let prevEnd = 0;
+  let hadPrev = false;
+  let prevKind = null; // 'entity' | 'idea' | 'blocker' | 'github' | null
+  let m;
+  RESOLVER_LINK_RE.lastIndex = 0;
+  while ((m = RESOLVER_LINK_RE.exec(segment)) !== null) {
+    if (m[1] !== m[2]) continue; // text/target number mismatch — not ours
+    const num = m[1];
+    const start = m.index;
+    const left = leftContext + out + segment.slice(last, start);
+    const gap = segment.slice(prevEnd, start);
+    const carried = hadPrev && prevKind && LIST_GLUE_RE.test(gap);
+    const kind = classifyKind(left, carried, prevKind);
+
+    prevEnd = start + m[0].length;
+    hadPrev = true;
+    prevKind = kind;
+    if (!kind) continue; // a genuine task link — leave it
+
+    out += segment.slice(last, start);
+    out += kind === 'github' ? `#${num}` : `\`#${num}\``;
+    last = prevEnd;
+    stats.unlinked = (stats.unlinked || 0) + 1;
+  }
+  out += segment.slice(last);
+  return out;
+}
+
+// Replace bare "#NNN" refs in a single non-code text segment. `leftContext` is
+// everything already emitted on this line (for left-context tests). `ids` is
+// {tasks, ideas, blockers} Sets. Returns the transformed segment; mutates `stats`.
+function linkifySegment(segment, ids, leftContext, stats) {
+  let out = '';
+  const re = new RegExp(`#(${REF_DIGITS})`, 'g');
+  let m;
+  let last = 0;
+  let prevEnd = 0;        // index in `segment` just past the previous match
+  let hadPrev = false;
+  let prevKind = null;    // carries across list glue
+  // Index ranges covered by the TEXT of a markdown link `[text](url)`. A "#NNN"
+  // inside link text is already part of a link; rewriting it nests one link
+  // inside another (`[task [#415](resolver)](url)`). prevChar==='[' only caught
+  // "#" right after the bracket — this catches it anywhere in the text.
+  const linkRanges = [];
+  { const lre = /\[([^\]]*)\]\([^)]*\)/g; let lm;
+    while ((lm = lre.exec(segment)) !== null) linkRanges.push([lm.index + 1, lm.index + 1 + lm[1].length]); }
+  while ((m = re.exec(segment)) !== null) {
+    const num = m[1];
+    const start = m.index;
+    const matchEnd = start + m[0].length;
+    const endChar = segment[matchEnd]; // char immediately after the digits
+    // Left context = the line so far + this segment up to the match.
+    const left = leftContext + segment.slice(0, start);
+    const prevChar = left.length ? left[left.length - 1] : '';
+    const gap = segment.slice(prevEnd, start);
+
+    // Classification = directly preceded by an entity / idea / blocker / GitHub
+    // noun, OR inherited across a pure list-glue gap.
+    const carried = hadPrev && prevKind && LIST_GLUE_RE.test(gap);
+    const kind = classifyKind(left, carried, prevKind);
+
+    // Positional skips first — these positions must never be rewritten in ANY
+    // direction (anchors, existing link text/targets).
+    let skipReason = null;
+    if (prevChar === '`' && endChar === '`') {
+      // Already a neutralized code-span ref (`#170`) — Phase 2 owns upgrading
+      // those; never wrap one again here.
+      skipReason = 'already-neutralized';
+    } else if (endChar === '-' || /[A-Za-z0-9_]/.test(endChar || '')) {
+      // `#12-session-update-protocol` (heading anchor) or `#170abc` — not a bare ref.
+      skipReason = 'anchor-or-slug';
+    } else if (prevChar === '[') {
+      // Already link text: `[#170](...)`.
+      skipReason = 'already-link-text';
+    } else if (linkRanges.some(([s, e]) => start >= s && start < e)) {
+      // Inside link text mid-string: `[task #170](url)` — would nest links.
+      skipReason = 'in-link-text';
+    } else if (/\]\($/.test(left)) {
+      // Link target: `](#170)`.
+      skipReason = 'link-target';
+    } else if (kind === 'github') {
+      // "PR #475" — genuinely GitHub's number space; the bare autolink is CORRECT.
+      skipReason = 'github-namespace';
+    } else if (!kind && !TASK_CTX_RE.test(left) && !ORDINAL_EXEMPT_RE.test(left)
+               && ORDINAL_PROSE_LEFT_RE.test(left) && num.length <= ORDINAL_MAX_DIGITS) {
+      // "side door #1", "limiter #4", "§Decision #4" — a noun followed by a small
+      // ordinal, not a ref. See ORDINAL_MAX_DIGITS for the corpus evidence.
+      skipReason = 'ordinal-prose';
+    } else if (!kind && !ids.tasks.has(Number(num))) {
+      // No context and not a known task id — too ambiguous to touch (a bare PR
+      // ref, a future task, a numeric color). Left bare.
+      skipReason = 'not-a-task';
+    }
+
+    // Advance list state for the NEXT match regardless of this one's outcome.
+    prevEnd = matchEnd;
+    hadPrev = true;
+    prevKind = kind;
+
+    if (skipReason) {
+      stats.skipped[skipReason] = (stats.skipped[skipReason] || 0) + 1;
+      continue; // leave the match untouched; regex keeps scanning after it
+    }
+
+    out += segment.slice(last, start);
+    if (kind === 'idea' || kind === 'blocker') {
+      // An idea/blocker ref: link to that resolver when the id is real, else
+      // neutralize (a stale/typo'd id bare would still autolink to a GitHub 404).
+      const set = kind === 'idea' ? ids.ideas : ids.blockers;
+      if (set.has(Number(num))) {
+        const base = kind === 'idea' ? RESOLVER_BASE_IDEA : RESOLVER_BASE_BLOCKER;
+        out += `[#${num}](${base}${num})`;
+        stats[kind === 'idea' ? 'linkified_idea' : 'linkified_blocker'] =
+          (stats[kind === 'idea' ? 'linkified_idea' : 'linkified_blocker'] || 0) + 1;
+      } else {
+        out += `\`#${num}\``;
+        stats.neutralized = (stats.neutralized || 0) + 1;
+      }
+    } else if (kind === 'entity') {
+      // A different entity's id with no resolver — neutralize.
+      out += `\`#${num}\``;
+      stats.neutralized = (stats.neutralized || 0) + 1;
+    } else {
+      // A task ref (validated above).
+      out += `[#${num}](${RESOLVER_BASE}${num})`;
+      stats.linkified += 1;
+    }
+    last = matchEnd;
+  }
+  out += segment.slice(last);
+  return out;
+}
+
+// Phase 2 (#629): upgrade a PRIOR idea/blocker NEUTRALIZATION (`#N`, emitted by
+// an earlier run before those resolvers existed) into a proper resolver link.
+// Operates on the rejoined line and matches ONLY the exact lone `#N` code-span
+// token, gated on (a) idea/blocker left-context (with list-glue carry) AND (b)
+// the id being in the matching public id set — so a legitimate code span like
+// "the `#197` marker" (no entity noun) and an other-entity neutralization
+// ("learning `#53`") are left untouched. Idempotent: once upgraded to a link
+// the `#N` code span is gone, so a second pass is a no-op.
+function upgradeLineCodeSpans(line, ids, stats) {
+  let out = '';
+  let last = 0;
+  let prevEnd = 0;
+  let hadPrev = false;
+  let prevKind = null; // only 'idea' | 'blocker' carry here
+  const re = new RegExp('`#(' + REF_DIGITS + ')`', 'g');
+  let m;
+  while ((m = re.exec(line)) !== null) {
+    const num = m[1];
+    const start = m.index;
+    const matchEnd = start + m[0].length;
+    const left = line.slice(0, start);
+    const gap = line.slice(prevEnd, start);
+    const carried = hadPrev && prevKind && LIST_GLUE_RE.test(gap);
+    let kind = null;
+    if (IDEA_CTX_RE.test(left)) kind = 'idea';
+    else if (BLOCKER_CTX_RE.test(left)) kind = 'blocker';
+    else if (carried) kind = prevKind;
+
+    prevEnd = matchEnd;
+    hadPrev = true;
+    prevKind = kind === 'idea' || kind === 'blocker' ? kind : null;
+
+    if (kind === 'idea' || kind === 'blocker') {
+      const set = kind === 'idea' ? ids.ideas : ids.blockers;
+      if (set.has(Number(num))) {
+        out += line.slice(last, start);
+        const base = kind === 'idea' ? RESOLVER_BASE_IDEA : RESOLVER_BASE_BLOCKER;
+        out += `[#${num}](${base}${num})`;
+        last = matchEnd;
+        stats.upgraded = (stats.upgraded || 0) + 1;
+      }
+      // valid-set miss → leave the code span as-is (correctly still neutralized)
+    }
+  }
+  out += line.slice(last);
+  return out;
+}
+
+// Pure: rewrite all eligible "#NNN" refs in `text`. `ids` is a Set of task ids
+// (legacy) or {tasks, ideas, blockers}. Skips fenced code blocks and inline code
+// spans (except the Phase-2 idea/blocker neutralization upgrade).
+function linkifyText(text, ids, stats) {
+  ids = normalizeIdSets(ids);
+  stats = stats || { linkified: 0, skipped: {} };
+  if (!stats.skipped) stats.skipped = {};
+  const lines = text.split('\n');
+  let inFence = false;
+  const result = lines.map((line) => {
+    const fenceToggle = /^\s*(```|~~~)/.test(line);
+    if (fenceToggle) {
+      inFence = !inFence;
+      return line; // the fence line itself is never transformed
+    }
+    if (inFence) return line;
+    // Phase 1. Split on inline code spans (single backtick). Even indices are
+    // outside code, odd indices are inside — only transform the outside segments.
+    const parts = line.split('`');
+    let leftContext = '';
+    for (let k = 0; k < parts.length; k++) {
+      if (k % 2 === 1) {
+        leftContext += '`' + parts[k]; // odd index = inside a code span; never transformed
+      } else {
+        // First undo past mis-linkifications (entity refs wrongly sent to the
+        // task resolver), then classify what's left.
+        const unlinked = unlinkEntitySegment(parts[k], leftContext, stats);
+        const transformed = linkifySegment(unlinked, ids, leftContext, stats);
+        leftContext += transformed;
+        parts[k] = transformed;
+      }
+    }
+    // Phase 2. Upgrade pre-existing idea/blocker `#N` neutralizations to links.
+    return upgradeLineCodeSpans(parts.join('`'), ids, stats);
+  });
+  return { text: result.join('\n'), stats };
+}
+
+// ---- CLI ----------------------------------------------------------------
+
+// Token-free: the public id allow-list, so this script (and the CI gate) work
+// with no builder session. Override the host with GDS_API_BASE for local dev.
+async function fetchRefIds() {
+  const res = await fetch(`${API_BASE}/api/bongos/public/ref-ids`);
+  if (!res.ok) throw new Error(`/public/ref-ids fetch failed (HTTP ${res.status})`);
+  const data = await res.json();
+  const toSet = (a) => new Set((a || []).map(Number).filter(Number.isInteger));
+  const tasks = toSet(data.tasks);
+  if (!tasks.size) throw new Error('no task ids returned from /public/ref-ids');
+  return { tasks, ideas: toSet(data.ideas), blockers: toSet(data.blockers) };
+}
+
+function unifiedish(file, before, after) {
+  // Print only the lines that changed, with a little context — enough for a
+  // human to eyeball without drowning in a full-file diff.
+  const a = before.split('\n');
+  const b = after.split('\n');
+  const out = [];
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      out.push(`  ${file}:${i + 1}`);
+      out.push(`    - ${a[i]}`);
+      out.push(`    + ${b[i]}`);
+    }
+  }
+  return out.join('\n');
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const apply = args.includes('--apply');
+  const check = args.includes('--check'); // CI gate: report + non-zero exit, no writes
+  const idsArgIdx = args.indexOf('--ids');
+  let ids;
+  const files = args.filter((a, i) => !a.startsWith('--') && !(idsArgIdx >= 0 && i === idsArgIdx + 1));
+  const targets = files.length ? files : discoverDocs();
+
+  if (idsArgIdx >= 0) {
+    const tasks = new Set(String(args[idsArgIdx + 1] || '').split(',').map((s) => Number(s.trim())).filter(Number.isInteger));
+    ids = { tasks, ideas: new Set(), blockers: new Set() };
+  } else {
+    try {
+      ids = await fetchRefIds();
+    } catch (err) {
+      // Fail OPEN on infra in --check: a network blip or a not-yet-deployed
+      // endpoint must never red-X an unrelated build. Real bare refs still get
+      // caught on the next run once the id list is reachable.
+      if (check) {
+        console.warn(`⚠ skipping check — id allow-list unavailable (${err.message}).`);
+        process.exit(0);
+      }
+      throw err;
+    }
+  }
+  const mode = check ? 'check (CI gate — non-zero exit if any bare/upgradeable ref remains)'
+    : apply ? 'apply (writing changes)'
+      : 'dry-run (no files written; pass --apply to write)';
+  console.log(`Linkify refs → task/idea/blocker resolvers  (${ids.tasks.size} task · ${ids.ideas.size} idea · ${ids.blockers.size} blocker ids · ${targets.length} docs)`);
+  console.log(`MODE: ${mode}\n`);
+
+  const totals = { linkified: 0, linkified_idea: 0, linkified_blocker: 0, neutralized: 0, unlinked: 0, upgraded: 0, skipped: {} };
+  const offenders = [];
+  for (const rel of targets) {
+    const abs = path.resolve(process.cwd(), rel);
+    if (!fs.existsSync(abs)) {
+      console.log(`  (skip — not found: ${rel})`);
+      continue;
+    }
+    const before = fs.readFileSync(abs, 'utf8');
+    const { text: after, stats } = linkifyText(before, ids);
+    totals.linkified += stats.linkified;
+    totals.linkified_idea += stats.linkified_idea || 0;
+    totals.linkified_blocker += stats.linkified_blocker || 0;
+    totals.neutralized += stats.neutralized || 0;
+    totals.unlinked += stats.unlinked || 0;
+    totals.upgraded += stats.upgraded || 0;
+    for (const [k, v] of Object.entries(stats.skipped)) totals.skipped[k] = (totals.skipped[k] || 0) + v;
+    if (after !== before) {
+      const changed = (stats.linkified || 0) + (stats.linkified_idea || 0) + (stats.linkified_blocker || 0) + (stats.upgraded || 0) + (stats.neutralized || 0) + (stats.unlinked || 0);
+      offenders.push({ rel, count: changed });
+      if (!check) {
+        console.log(`■ ${rel} — ${changed} change(s)`);
+        console.log(unifiedish(rel, before, after));
+        console.log('');
+      }
+      if (apply) fs.writeFileSync(abs, after);
+    }
+  }
+
+  console.log('— summary —');
+  console.log(`  docs needing rewrites: ${offenders.length}`);
+  console.log(`  task refs ${apply ? 'linkified' : 'pending'}: ${totals.linkified}`);
+  console.log(`  idea refs ${apply ? 'linkified' : 'pending'}: ${totals.linkified_idea}`);
+  console.log(`  blocker refs ${apply ? 'linkified' : 'pending'}: ${totals.linkified_blocker}`);
+  console.log(`  prior idea/blocker neutralizations ${apply ? 'upgraded' : 'to upgrade'}: ${totals.upgraded}`);
+  console.log(`  entity refs ${apply ? 'neutralized' : 'to neutralize'} (code-spanned): ${totals.neutralized}`);
+  console.log(`  past mis-links ${apply ? 'unwrapped' : 'to unwrap'}: ${totals.unlinked}`);
+  console.log(`  skipped: ${JSON.stringify(totals.skipped)}`);
+
+  if (check && offenders.length) {
+    console.error(`\n✖ ${offenders.length} doc(s) still have a bare/upgradeable "#NNN" that mis-renders on github.com:`);
+    for (const o of offenders) console.error(`    - ${o.rel} (${o.count})`);
+    console.error('\n  Fix locally: node scripts/bongos/linkify-refs.js --apply');
+    process.exit(1);
+  }
+  if (!apply && !check && offenders.length) console.log('\n  Re-run with --apply to write these changes.');
+}
+
+if (require.main === module) {
+  main().catch((e) => {
+    console.error('ERR', e.message);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  linkifyText, linkifySegment, unlinkEntitySegment, upgradeLineCodeSpans,
+  classifyKind, normalizeIdSets, discoverDocs,
+  RESOLVER_BASE, RESOLVER_BASE_IDEA, RESOLVER_BASE_BLOCKER,
+  // task 1003542: the bare-ref digit width, exported so the OTHER enforcement
+  // point (.claude/hooks/stop-refcheck.js) reads it here instead of keeping its
+  // own copy — the drift that let 7-digit ids past both guards at once.
+  REF_DIGITS,
+  // task 1003542: the loopback test behind the resolver base. Exported because
+  // RESOLVER_BASE is computed once at module load, so the DECISION is the only
+  // part a unit test can reach without re-requiring under a mocked branding.
+  isLoopbackOrigin,
+};