@bongos/core 1.21.175 → 1.21.176

package/scripts/gds/linkify-refs.js

@@ -1,655 +1,7 @@
 #!/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/gds/linkify-refs.js                 # dry-run on the default index docs
-//   node scripts/gds/linkify-refs.js --apply         # write the changes
-//   node scripts/gds/linkify-refs.js --check          # CI gate: non-zero exit if any bare/upgradeable ref remains
-//   node scripts/gds/linkify-refs.js --apply docs/x.md CLAUDE.md   # explicit file set
-//   node scripts/gds/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/gds/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/gds/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,
-};
+// scripts/gds/linkify-refs.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/linkify-refs.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'linkify-refs.js');