@bongos/core 1.17.0

package/scripts/gds/learning-capture.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// Capture a learning — durable storage in the GDS DB (Phase 2b: the DB is
+// now the only canonical home for short-form learnings; long-form recipes
+// live under docs/recipes/).
+//
+// Usage:
+//   node scripts/gds/learning-capture.js \
+//     --tags "caddy,cloudflare" \
+//     --title "Origin cert needs *.amazonprimea.com SAN" \
+//     --body-file path/to/body.md
+//
+// Body source (in priority order): --body-file PATH > --body "text" > stdin.
+// Related files: --files "infra/Caddyfile,..." > auto-detected `git diff --name-only HEAD`.
+// Idempotency: --source / --source-ref pair acts as soft-key (server skips on duplicate).
+
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+
+const { cliClient, requireSession, arg } = require('./cli-lib');
+
+
+function csv(v) {
+  if (!v) return [];
+  return String(v).split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+async function readStdin() {
+  return new Promise((resolve, reject) => {
+    if (process.stdin.isTTY) return resolve('');
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => (data += chunk));
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+function autoDetectFiles() {
+  try {
+    const out = execSync('git diff --name-only HEAD', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out.split('\n').map((s) => s.trim()).filter(Boolean);
+  } catch (_) {
+    return [];
+  }
+}
+
+
+(async () => {
+  await requireSession();
+  const args = process.argv.slice(2);
+
+  const title = arg('--title', args);
+  const tags = csv(arg('--tags', args));
+  const bodyFile = arg('--body-file', args);
+  const bodyInline = arg('--body', args);
+  const filesArg = arg('--files', args);
+  const source = arg('--source', args);
+  const sourceRef = arg('--source-ref', args);
+  const taskIdStr = arg('--task-id', args);
+  const taskId = taskIdStr ? Number(taskIdStr) : null;
+  const dryRun = args.includes('--dry-run');
+
+  if (!title || tags.length === 0) {
+    console.error('usage: node scripts/gds/learning-capture.js --tags "a,b" --title "..." (--body-file PATH | --body "..." | stdin) [--files "f,g"] [--source manual] [--source-ref id] [--task-id N] [--dry-run]');
+    process.exit(2);
+  }
+
+  let body;
+  if (bodyFile) {
+    try {
+      body = await fsp.readFile(bodyFile, 'utf8');
+    } catch (err) {
+      console.error(`failed to read --body-file ${bodyFile}: ${err.message}`);
+      process.exit(2);
+    }
+  } else if (bodyInline) {
+    body = bodyInline;
+  } else {
+    body = await readStdin();
+  }
+  if (!body || !body.trim()) {
+    console.error('body is empty (provide via --body-file PATH, --body "...", or piped stdin)');
+    process.exit(2);
+  }
+
+  const relatedFiles = filesArg ? csv(filesArg) : autoDetectFiles();
+
+  // Find current builder login so the file footer says who captured.
+  let capturedByLogin = null;
+  try {
+    const api = await cliClient();
+    const me = await api.me.getMe();
+    if (me.ok) capturedByLogin = me.data?.builder?.github_login ?? null;
+  } catch (_) {}
+
+  if (dryRun) {
+    console.log('=== DRY RUN ===');
+    console.log('POST /api/gds/learnings:');
+    console.log(JSON.stringify({
+      title, body_md: body, tags, related_files: relatedFiles, source, source_ref: sourceRef, task_id: taskId,
+    }, null, 2));
+    process.exit(0);
+  }
+
+  const api = await cliClient();
+  const r = await api.learnings.postLearnings({
+    body: {
+      title,
+      body_md: body,
+      tags,
+      related_files: relatedFiles,
+      source,
+      source_ref: sourceRef,
+      task_id: taskId,
+    },
+  });
+
+  if (r.status === 200 && r.data?.skipped) {
+    console.log(`Skipped: duplicate (source=${source}, source_ref=${sourceRef}) already captured.`);
+    return;
+  }
+  if (r.status !== 201) {
+    console.error(`capture failed (${r.status}):`, r.data);
+    process.exit(1);
+  }
+
+  const { learning } = r.data;
+  console.log(`Captured learning #${learning.id}: ${learning.title}`);
+  console.log(`Tags: ${learning.tags.join(', ')}`);
+  if (learning.related_files?.length) {
+    console.log(`Related files: ${learning.related_files.join(', ')}`);
+  }
+  console.log('Stored in GDS DB. Query with: node scripts/gds/learning-list.js (TBD) or GET /api/gds/learnings');
+  // Phase 2b — the per-tag markdown append was removed. The DB is now the
+  // canonical store for short-form learnings; long-form operational recipes
+  // live separately under docs/recipes/.
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});

package/scripts/gds/lib.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# scripts/gds/lib.sh — shared helpers for the GDS shell smoke scripts.
+# SOURCED, never executed:  source "$(dirname "$0")/lib.sh"
+#
+# Holds ONLY the pieces that were byte-identical across smoke-batch-claim.sh,
+# smoke-claim-consistency.sh, and smoke-write.sh: the GDS API base-URL default
+# (a literal that had drifted) and the CLI session-token resolution.
+#
+# Deliberately NOT here:
+#   - the per-script curl `call()` wrapper — the two contracts differ in
+#     load-bearing ways (smoke-batch-claim echoes "PAYLOAD\nCODE" and never exits
+#     non-zero so its caller can read CODE/PAYLOAD; smoke-write/-consistency echo
+#     the payload and `return 1` on a non-2xx so `set -e` aborts). Merging them
+#     would break one or the other, so each script keeps its own.
+#   - smoke-dependencies.sh / portability-smoke-memory.sh, whose token + base-URL
+#     handling intentionally differs (macOS-only path / env-first token / no PMS
+#     fallback / skip-on-missing) — left as-is to preserve that drift.
+
+# The GDS API host. One home for the default that had drifted across the smoke
+# scripts; still overridable via GDS_API_BASE / (legacy) PMS_API_BASE.
+gds_api_base() {
+  printf '%s' "${GDS_API_BASE:-${PMS_API_BASE:-https://amazonprimea.com}}"
+}
+
+# Resolve the CLI session token: prefer ~/.config/otb/gds-session.json, fall back
+# to the legacy pms-session.json. Echoes the token on success. On a missing file
+# or empty token it prints a FAIL line to stderr and returns 2 — callers run
+#   TOKEN="$(gds_resolve_token)" || exit $?
+# so the failure propagates out of the command substitution.
+gds_resolve_token() {
+  local sf="${HOME}/.config/otb/gds-session.json"
+  [[ -f "$sf" ]] || sf="${HOME}/.config/otb/pms-session.json"
+  if [[ ! -f "$sf" ]]; then
+    echo "FAIL: no session at $sf. Run setup first." >&2
+    return 2
+  fi
+  local tok
+  tok=$(python3 -c "import json; print(json.load(open('$sf'))['token'])")
+  if [[ -z "$tok" ]]; then
+    echo "FAIL: no token in $sf" >&2
+    return 2
+  fi
+  printf '%s' "$tok"
+}

package/scripts/gds/linkify-refs.js

@@ -0,0 +1,473 @@
+#!/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/gds/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');
+
+const RESOLVER_BASE = 'https://amazonprimea.com/builders#/task/';
+const RESOLVER_BASE_IDEA = 'https://amazonprimea.com/builders#/idea/';
+const RESOLVER_BASE_BLOCKER = 'https://amazonprimea.com/builders#/blocker/';
+// API_BASE comes from cli-lib (the single source). 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.
+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);
+    }
+  };
+  for (const root of ['CLAUDE.md', 'README.md', 'docs']) walk(root);
+  return out.filter((rel) =>
+    !/GENERATED FILE/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;
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// An existing markdown link of the exact TASK form this script writes:
+// [#N](task-resolver/N). Used only to undo PAST task-resolver mis-links of
+// entity/idea/blocker refs; the idea/blocker resolver links are left alone.
+const RESOLVER_LINK_RE = new RegExp(`\\[#(\\d{1,5})\\]\\(${escapeRe(RESOLVER_BASE)}(\\d{1,5})\\)`, '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 = /#(\d{1,5})/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 && !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 = /`#(\d{1,5})`/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/gds/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,
+};