docbridge 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-10-08
+
+### Changed
+
+- A heading anchor keeps `_`, as GitHub's heading slugs do. Before, `_` became
+  `-`, so `### title_definitions` gave `#title-definitions`; it now gives
+  `#title_definitions`. A link written with the old `-` form now produces
+  `doc_anchor_not_found`; change it to match the heading, such as
+  `#title_definitions`.
+
+## [0.13.1] - 2026-10-06
+
+### Fixed
+
+- A worker that a scan started no longer outlives the CLI. On POSIX systems
+  each worker runs in its own process group, a time or output limit kills the
+  whole group, and `check`, `related`, `context`, and `graph` kill their
+  running workers when the CLI receives `SIGINT`, `SIGTERM`, or `SIGHUP`
+  during a scan, then end by that signal. Before, a worker that ran past the
+  CLI, or a process the worker started, could keep running.
+
 ## [0.13.0] - 2026-10-01
 
 ### Added
@@ -547,7 +568,9 @@ Initial release of the SpecLink CLI.
 - `speclink check` command with `--root`, `--json`, and `--audit` options.
 - `speclink --version` (alias `-v`) and `speclink --help` (alias `-h`).
 
-[Unreleased]: https://github.com/salan70/docbridge/compare/v0.13.0...HEAD
+[Unreleased]: https://github.com/salan70/docbridge/compare/v0.14.0...HEAD
+[0.14.0]: https://github.com/salan70/docbridge/releases/tag/v0.14.0
+[0.13.1]: https://github.com/salan70/docbridge/releases/tag/v0.13.1
 [0.13.0]: https://github.com/salan70/docbridge/releases/tag/v0.13.0
 [0.12.0]: https://github.com/salan70/docbridge/releases/tag/v0.12.0
 [0.11.0]: https://github.com/salan70/docbridge/releases/tag/v0.11.0

package/dist/bin/darwin-arm64/SHA256SUMS

@@ -1,4 +1,4 @@
-bb2e127396b445a443c6d9958430b9af7e992ecca54cac49ce8feb88c199f460  docbridge-swift-scanner
-32032f9e2c703f4ab4976361f15f723a58c675545edce90fdc673d3094fe154e  docbridge_dart_scanner
+2db42ddea8060f988cea4933696e73d652ae5b807a8e8ff00249375faf2b0be4  docbridge-swift-scanner
+f3da86ea5a0c1c92fa1e1f077251bec490e294d257b09cd03a46c8ce382aad19  docbridge_dart_scanner
 7fc3e6842b3e1bf425b8fd63e241eee7e64875f16be7ba8d1ae4a25baa7f2338  docbridge-rust-scanner
-1a7160cf70cb6ff1517d72685b6ecbfe1878ed1fed013fef706e5f2405ddbce0  docbridge-go-scanner
+1646b06856b0420acdcb82d1692b7afea83fe2b7666adeb6412c99782dfc8cae  docbridge-go-scanner

package/dist/bin/linux-x64/SHA256SUMS

@@ -1,4 +1,4 @@
-6e78c1c79c16572ed0759bfcf24ddd4cc77c7d1d699d19dc0279a9abca38d248  docbridge-swift-scanner
+0c023cfacede26a217a62420f9da1206b93c228122a3685469685a3db89f7735  docbridge-swift-scanner
 b75b14006ca792ed3ca8faf7ceee9e4d33c895f27dd416b640818cf8a4bdd9c8  docbridge_dart_scanner
 e0da7b8cc6ee23704f5fe8514cc309f0bb60380c77b55e3bc5ed113abd1f3478  docbridge-rust-scanner
-af845c263f65cc5db5beb01b4f4f7251ce449391986b4e288c03abfa04f7e708  docbridge-go-scanner
+5b8aee5b85a38679875c473b2dc32f021f022cba242785bb0fd94ee6fda0a6bf  docbridge-go-scanner

package/dist/bin/linux-x64/docbridge-swift-scanner

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/dist/bin/linux-x64/docbridge-swift-scanner
 size: 40932352 bytes
-sha256: 6e78c1c79c16572ed0759bfcf24ddd4cc77c7d1d699d19dc0279a9abca38d248
+sha256: 0c023cfacede26a217a62420f9da1206b93c228122a3685469685a3db89f7735

package/dist/index.js

@@ -175581,7 +175581,7 @@ import { join as join15, resolve as resolve5 } from "node:path";
 // package.json
 var package_default = {
   name: "docbridge",
-  version: "0.13.0",
+  version: "0.14.0",
   description: "A CLI that links Markdown specifications and code declarations. Runs on Node.js and Bun.",
   keywords: [
     "bun",
@@ -176065,10 +176065,6 @@ function validateCodeEntry(language, value, diagnostics) {
 }
 function validateVisibilityOptions(language, values, target, diagnostics) {
   const allowed = LANGUAGE_VISIBILITY[language];
-  if (allowed.length === 0) {
-    diagnostics.push(configDiagnostic2("config_invalid_value", `${target}.visibility`, `\`${target}.visibility\` is not supported for ${language}.`));
-    return;
-  }
   for (const value of values) {
     if (!allowed.includes(value)) {
       diagnostics.push(configDiagnostic2("config_invalid_value", `${target}.visibility`, `Unsupported ${language} visibility: ${value}. Supported values: ${allowed.join(", ")}.`));
@@ -177601,24 +177597,13 @@ function manifestLink(source, target, entry, side) {
 }
 
 // src/shared/cancelable.ts
-function deferred() {
-  let settle;
-  const promise = new Promise((resolve2, reject) => {
-    settle = { resolve: resolve2, reject };
-  });
-  return {
-    promise,
-    resolve: (value) => settle?.resolve(value),
-    reject: (error) => settle?.reject(error)
-  };
-}
 function settledCancelable(value) {
   return { promise: Promise.resolve(value), cancel: () => {
     return;
   } };
 }
 function mapCancelable(task, map) {
-  const mapped = deferred();
+  const mapped = Promise.withResolvers();
   let cancelled = false;
   task.promise.then((value) => {
     if (cancelled) {
@@ -177644,7 +177629,7 @@ function isAbortError(error) {
   return error instanceof Error && error.name === "AbortError";
 }
 function cancelableSequence(body) {
-  const outcome = deferred();
+  const outcome = Promise.withResolvers();
   let cancelled = false;
   let running;
   const step = async (next) => {
@@ -177779,9 +177764,6 @@ function duplicateLinkDiagnostic(source, target, location, range) {
 // src/scan/code/typescript.ts
 var typeScriptAdapter = {
   language: "typescript",
-  scanFile(filePath, content, options) {
-    return scanTypeScript(filePath, content, options);
-  },
   scanFiles(files, options) {
     return files.map(({ filePath, content }) => scanTypeScript(filePath, content, options));
   }
@@ -178250,12 +178232,9 @@ function firstToken(text) {
 import { accessSync as accessSync2, constants as constants2, existsSync as existsSync3, realpathSync as realpathSync2, statSync as statSync2 } from "node:fs";
 import { extname, isAbsolute as isAbsolute2, join as join7, resolve as resolve2 } from "node:path";
 
-// src/scan/code/worker/runtime-probe.ts
-import { spawnSync as spawnSync2 } from "node:child_process";
-
 // src/scan/code/worker/scanner-worker.ts
 var import__2020 = __toESM(require_2020(), 1);
-import { spawn, spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join as join4 } from "node:path";
@@ -178454,14 +178433,12 @@ var scanner_worker_schema_default = {
 // src/scan/code/worker/scanner-worker.ts
 var WORKER_OUTPUT_LIMIT_BYTES = 1024 * 1024 * 1024;
 var KILLED_WORKER_GRACE_MS = 500;
-function createLazyWorkerResponseValidator(compile) {
-  let validator;
-  return () => {
-    validator ??= compile();
-    return validator;
-  };
+var liveWorkers = new Map;
+var compiledResponseValidator;
+function responseValidator() {
+  compiledResponseValidator ??= compileWorkerResponseValidator();
+  return compiledResponseValidator;
 }
-var responseValidator = createLazyWorkerResponseValidator(compileWorkerResponseValidator);
 function compileWorkerResponseValidator() {
   const ajv = new import__2020.default({ allErrors: true, strict: true });
   ajv.addSchema(common_output_schema_default);
@@ -178472,13 +178449,10 @@ function compileWorkerResponseValidator() {
   });
 }
 function invokeScannerWorker(request, command, run = runScannerWorkerProcess, stripEnv = []) {
-  return interpretWorkerProcess(request, command, run(processInput(request, command, stripEnv)));
-}
-function invokeScannerWorkerAsync(request, command, runAsync = runScannerWorkerProcessAsync, stripEnv = []) {
-  const run = runAsync(processInput(request, command, stripEnv));
+  const task = run(processInput(request, command, stripEnv));
   return {
-    promise: run.promise.then((processResult) => interpretWorkerProcess(request, command, processResult)),
-    cancel: () => run.cancel()
+    promise: task.promise.then((processResult) => interpretWorkerProcess(request, command, processResult)),
+    cancel: () => task.cancel()
   };
 }
 function processInput(request, command, stripEnv) {
@@ -178554,37 +178528,7 @@ function workerTimeoutMs(fileCount) {
   return 30000 + 1000 * fileCount;
 }
 function runScannerWorkerProcess(input) {
-  const maxOutputBytes = input.maxOutputBytes ?? WORKER_OUTPUT_LIMIT_BYTES;
-  try {
-    const [executable = "", ...args] = input.command;
-    const result = spawnSync(executable, args, {
-      env: workerProcessEnv(input.stripEnv),
-      input: input.stdin,
-      encoding: "utf8",
-      maxBuffer: maxOutputBytes,
-      killSignal: "SIGKILL",
-      ...input.timeoutMs === undefined ? {} : { timeout: input.timeoutMs }
-    });
-    return syncWorkerProcessResult(result, input.timeoutMs, maxOutputBytes);
-  } catch (error) {
-    return { ok: false, kind: "start", error, stderr: "" };
-  }
-}
-function syncWorkerProcessResult(result, timeoutMs, maxOutputBytes) {
-  const stderr = result.stderr ?? "";
-  if (result.error !== undefined) {
-    return syncSpawnFailure(result.error, workerStarted(result), timeoutMs, maxOutputBytes, stderr);
-  }
-  if (Buffer.byteLength(result.stdout ?? "") + Buffer.byteLength(stderr) > maxOutputBytes) {
-    return { ok: false, kind: "execution", error: outputLimitError(maxOutputBytes), stderr };
-  }
-  if (typeof result.status !== "number") {
-    return { ok: false, kind: "execution", error: signalError(result.signal), stderr };
-  }
-  return { ok: true, exitCode: result.status, stdout: result.stdout ?? "", stderr };
-}
-function runScannerWorkerProcessAsync(input) {
-  const run = deferred();
+  const run = Promise.withResolvers();
   let settled = false;
   let timer;
   let grace;
@@ -178593,6 +178537,9 @@ function runScannerWorkerProcessAsync(input) {
       return;
     }
     settled = true;
+    if (child !== undefined) {
+      liveWorkers.delete(child);
+    }
     clearTimeout(timer);
     clearTimeout(grace);
     complete();
@@ -178601,24 +178548,34 @@ function runScannerWorkerProcessAsync(input) {
   let child;
   try {
     const [executable = "", ...args] = input.command;
-    child = spawn(executable, args, { env: workerProcessEnv(input.stripEnv), detached: ownGroup });
+    child = spawn(executable, args, {
+      env: workerProcessEnv(input.stripEnv),
+      detached: ownGroup,
+      windowsHide: true
+    });
   } catch (error) {
     settle(() => run.resolve({ ok: false, kind: "start", error, stderr: "" }));
     return { promise: run.promise, cancel: () => {
       return;
     } };
   }
+  liveWorkers.set(child, ownGroup);
   const maxOutputBytes = input.maxOutputBytes ?? WORKER_OUTPUT_LIMIT_BYTES;
   const budget = { bytes: 0, limit: maxOutputBytes };
   const stdout = new OutputCollector(budget);
   const stderr = new OutputCollector(budget);
   let failure;
-  const kill = (reason) => {
+  let cause;
+  let exited = false;
+  const kill = (reason, why) => {
     failure ??= reason;
-    killWorker(child, ownGroup);
+    cause ??= why;
+    if (!exited) {
+      killWorker(child, ownGroup);
+    }
     grace ??= setTimeout(() => {
       closeStreams(child);
-      settle(() => run.resolve(closedProcessResult(null, null, failure, stdout, stderr)));
+      settle(() => run.resolve(closedProcessResult(null, null, failure, cause, stdout, stderr)));
     }, KILLED_WORKER_GRACE_MS);
   };
   let spawned = false;
@@ -178634,30 +178591,36 @@ function runScannerWorkerProcessAsync(input) {
   });
   child.stdout.on("data", (chunk) => {
     if (!stdout.add(chunk)) {
-      kill(outputLimitError(maxOutputBytes));
+      kill(outputLimitError(maxOutputBytes), { type: "output-limit" });
     }
   });
   child.stderr.on("data", (chunk) => {
     if (!stderr.add(chunk)) {
-      kill(outputLimitError(maxOutputBytes));
+      kill(outputLimitError(maxOutputBytes), { type: "output-limit" });
     }
   });
   child.stdin.on("error", () => {
     return;
   });
+  child.on("exit", () => {
+    exited = true;
+    liveWorkers.delete(child);
+  });
   child.on("close", (code, signal) => {
-    settle(() => run.resolve(closedProcessResult(code, signal, failure, stdout, stderr)));
+    settle(() => run.resolve(closedProcessResult(code, signal, failure, cause, stdout, stderr)));
   });
   child.stdin.end(input.stdin);
   const { timeoutMs } = input;
   if (timeoutMs !== undefined) {
-    timer = setTimeout(() => kill(timeoutError(timeoutMs)), timeoutMs);
+    timer = setTimeout(() => kill(timeoutError(timeoutMs), { type: "timeout" }), timeoutMs);
   }
   return {
     promise: run.promise,
     cancel() {
       settle(() => {
-        killWorker(child, ownGroup);
+        if (!exited) {
+          killWorker(child, ownGroup);
+        }
         closeStreams(child);
         run.reject(abortError());
       });
@@ -178697,39 +178660,36 @@ class OutputCollector {
     return Buffer.concat(this.chunks).toString("utf8");
   }
 }
-function closedProcessResult(code, signal, failure, stdout, stderr) {
+function closedProcessResult(code, signal, failure, cause, stdout, stderr) {
   if (failure !== undefined) {
-    return { ok: false, kind: "execution", error: failure, stderr: stderr.text() };
+    return {
+      ok: false,
+      kind: "execution",
+      error: failure,
+      ...cause === undefined ? {} : { cause },
+      stderr: stderr.text()
+    };
   }
   if (code === null) {
-    return { ok: false, kind: "execution", error: signalError(signal), stderr: stderr.text() };
+    return {
+      ok: false,
+      kind: "execution",
+      error: signalError(signal),
+      cause: { type: "signal", signal: signal ?? "unknown" },
+      stderr: stderr.text()
+    };
   }
   return { ok: true, exitCode: code, stdout: stdout.text(), stderr: stderr.text() };
 }
-function workerStarted(result) {
-  return typeof result.status === "number" || typeof result.signal === "string" || typeof result.pid === "number" && result.pid > 0;
-}
-function syncSpawnFailure(error, started, timeoutMs, maxOutputBytes, stderr) {
-  const code = error.code;
-  if (code === "ETIMEDOUT") {
-    return { ok: false, kind: "execution", error: timeoutError(timeoutMs ?? 0), stderr };
-  }
-  if (code === "ENOBUFS") {
-    return { ok: false, kind: "execution", error: outputLimitError(maxOutputBytes), stderr };
-  }
-  return { ok: false, kind: started ? "execution" : "start", error, stderr };
-}
 function signalError(signal) {
   const name = signal ?? "unknown";
-  return Object.assign(new Error(`worker terminated by signal ${name}`), { signal: name });
+  return new Error(`worker terminated by signal ${name}`);
 }
 function timeoutError(timeoutMs) {
-  return Object.assign(new Error(`worker timed out after ${timeoutMs} ms`), {
-    code: "ETIMEDOUT"
-  });
+  return new Error(`worker timed out after ${timeoutMs} ms`);
 }
 function outputLimitError(maxOutputBytes) {
-  return Object.assign(new Error(`worker wrote more than ${maxOutputBytes} bytes to stdout and stderr together`), { code: "ENOBUFS" });
+  return new Error(`worker wrote more than ${maxOutputBytes} bytes to stdout and stderr together`);
 }
 function validateWorkerResponse(value, request) {
   const validator = responseValidator();
@@ -178757,18 +178717,7 @@ function formatSchemaError(errors) {
   return `worker response does not match scanner-worker.schema.json at ${path}: ${error.message ?? "invalid value"}`;
 }
 function responseFilesMatchRequest(responseFiles, requestFiles) {
-  if (responseFiles.length !== requestFiles.length) {
-    return false;
-  }
-  return responseFiles.every((file, index) => {
-    if (!isRecord(file)) {
-      return false;
-    }
-    return file.filePath === requestFiles[index]?.filePath;
-  });
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+  return responseFiles.length === requestFiles.length && responseFiles.every((file, index) => file.filePath === requestFiles[index]?.filePath);
 }
 function scannerUnavailableDiagnostic(language, error, executable) {
   const label = languageLabel(language);
@@ -178807,20 +178756,17 @@ function scannerFailedDiagnostic(language, reason) {
 function languageLabel(language) {
   return language.charAt(0).toUpperCase() + language.slice(1);
 }
+function killRunningWorkers() {
+  for (const [child, ownGroup] of liveWorkers) {
+    killWorker(child, ownGroup);
+  }
+}
 
 // src/scan/code/worker/runtime-probe.ts
 var PROBE_TIMEOUT_MS = 1e4;
 var PROBE_MAX_OUTPUT_BYTES = 64 * 1024;
-function probeRuntime(command, stripEnv, spawn2 = spawnRuntimeProbe) {
-  const [executable = "", ...args] = command;
-  return classifyProbe(spawn2(executable, [...args, "--probe"], {
-    env: workerProcessEnv(stripEnv),
-    timeout: PROBE_TIMEOUT_MS,
-    maxBuffer: PROBE_MAX_OUTPUT_BYTES
-  }));
-}
-function probeRuntimeAsync(command, stripEnv, runAsync = runScannerWorkerProcessAsync) {
-  const run = runAsync({
+function probeRuntime(command, stripEnv, run = runScannerWorkerProcess) {
+  const task = run({
     command: [...command, "--probe"],
     stdin: "",
     stripEnv,
@@ -178828,49 +178774,34 @@ function probeRuntimeAsync(command, stripEnv, runAsync = runScannerWorkerProcess
     maxOutputBytes: PROBE_MAX_OUTPUT_BYTES
   });
   return {
-    promise: run.promise.then((result) => classifyProbe(spawnResultOf(result))),
-    cancel: () => run.cancel()
+    promise: task.promise.then(classifyProbe),
+    cancel: () => task.cancel()
   };
 }
-function spawnResultOf(result) {
-  if (result.ok) {
-    return { status: result.exitCode, signal: null, stdout: result.stdout, stderr: result.stderr };
-  }
-  const error = result.error instanceof Error ? result.error : new Error(reasonOf(result.error));
-  const { signal } = error;
-  if (typeof signal === "string") {
-    return { status: null, signal, stdout: "", stderr: result.stderr };
-  }
-  return { status: null, signal: null, stdout: "", stderr: result.stderr, error };
-}
 function classifyProbe(result) {
-  if (result.error !== undefined) {
-    return classifySpawnError(result.error);
-  }
-  if (result.status === null) {
-    return { kind: "failed", reason: `probe terminated by signal ${result.signal ?? "unknown"}` };
-  }
-  if (result.status !== 0) {
-    const detail = firstLine(result.stderr);
-    return {
-      kind: "failed",
-      reason: `probe exited with status ${result.status}${detail === "" ? "" : `: ${detail}`}`
-    };
-  }
-  return parseProbeOutput(result.stdout);
-}
-function classifySpawnError(error) {
-  const code = error.code;
-  if (code === "ETIMEDOUT") {
-    return { kind: "failed", reason: `probe did not finish within ${PROBE_TIMEOUT_MS / 1000} s` };
+  if (result.ok) {
+    if (result.exitCode !== 0) {
+      const detail = firstLine(result.stderr);
+      return {
+        kind: "failed",
+        reason: `probe exited with status ${result.exitCode}${detail === "" ? "" : `: ${detail}`}`
+      };
+    }
+    return parseProbeOutput(result.stdout);
   }
-  if (code === "ENOBUFS") {
-    return {
-      kind: "failed",
-      reason: `probe printed more than ${PROBE_MAX_OUTPUT_BYTES / 1024} KiB`
-    };
+  switch (result.cause?.type) {
+    case "timeout":
+      return { kind: "failed", reason: `probe did not finish within ${PROBE_TIMEOUT_MS / 1000} s` };
+    case "output-limit":
+      return {
+        kind: "failed",
+        reason: `probe printed more than ${PROBE_MAX_OUTPUT_BYTES / 1024} KiB`
+      };
+    case "signal":
+      return { kind: "failed", reason: `probe terminated by signal ${result.cause.signal}` };
+    default:
+      return { kind: "unstartable", reason: reasonOf(result.error) };
   }
-  return { kind: "unstartable", reason: reasonOf(error) };
 }
 function parseProbeOutput(stdout) {
   const text = stdout.trim();
@@ -178880,7 +178811,7 @@ function parseProbeOutput(stdout) {
   } catch {
     return malformed(text);
   }
-  if (!isRecord2(value)) {
+  if (!isRecord(value)) {
     return malformed(text);
   }
   if (value.ok === true && typeof value.runtime === "string" && typeof value.version === "string") {
@@ -178898,40 +178829,9 @@ function malformed(text) {
 function firstLine(text) {
   return text.trim().split(/\r?\n/u)[0] ?? "";
 }
-function isRecord2(value) {
+function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function spawnRuntimeProbe(executable, args, options) {
-  try {
-    const result = spawnSync2(executable, args, {
-      env: options.env,
-      timeout: options.timeout,
-      killSignal: "SIGKILL",
-      maxBuffer: options.maxBuffer,
-      input: "",
-      encoding: "utf8",
-      windowsHide: true
-    });
-    const stdout = result.stdout ?? "";
-    const stderr = result.stderr ?? "";
-    const error = result.error === undefined && Buffer.byteLength(stdout) + Buffer.byteLength(stderr) > options.maxBuffer ? Object.assign(new Error("probe output exceeded maxBuffer"), { code: "ENOBUFS" }) : result.error;
-    return {
-      status: result.status,
-      signal: result.signal,
-      stdout,
-      stderr,
-      ...error === undefined ? {} : { error }
-    };
-  } catch (error) {
-    return {
-      status: null,
-      signal: null,
-      stdout: "",
-      stderr: "",
-      error: error instanceof Error ? error : new Error(String(error))
-    };
-  }
-}
 
 // src/scan/code/worker/scanner-executable.ts
 import { accessSync, chmodSync, constants, existsSync as existsSync2, statSync } from "node:fs";
@@ -179143,22 +179043,12 @@ function rememberProbe(key, generation, outcome) {
 function resolveRuntimeWorkerCommand(language, options) {
   const env = options.env ?? process.env;
   const probe = options.probe ?? probeRuntime;
-  const steps = resolutionSteps(language, options, env);
-  let step = steps.next();
-  while (step.done !== true) {
-    step = steps.next(cachedProbe(step.value, env, probe));
-  }
-  return step.value;
-}
-function resolveRuntimeWorkerCommandAsync(language, options) {
-  const env = options.env ?? process.env;
-  const probeAsync = options.probeAsync ?? probeRuntimeAsync;
   return cancelableSequence(async (run) => {
     const steps = resolutionSteps(language, options, env);
     let step = steps.next();
     while (step.done !== true) {
       const request = step.value;
-      step = steps.next(await run(() => cachedProbeAsync(request, env, probeAsync)));
+      step = steps.next(await run(() => cachedProbe(request, env, probe)));
     }
     return step.value;
   });
@@ -179266,24 +179156,13 @@ function isExecutableFile(path, platform) {
   }
 }
 function cachedProbe({ command, stripEnv }, env, probe) {
-  const key = probeCacheKey(command, env);
-  const cached = probeCache.get(key);
-  if (cached !== undefined) {
-    return cached;
-  }
-  const generation = probeCacheGeneration;
-  const outcome = probe(command, stripEnv);
-  rememberProbe(key, generation, outcome);
-  return outcome;
-}
-function cachedProbeAsync({ command, stripEnv }, env, probeAsync) {
   const key = probeCacheKey(command, env);
   const cached = probeCache.get(key);
   if (cached !== undefined) {
     return settledCancelable(cached);
   }
   const generation = probeCacheGeneration;
-  return mapCancelable(probeAsync(command, stripEnv), (outcome) => {
+  return mapCancelable(probe(command, stripEnv), (outcome) => {
     rememberProbe(key, generation, outcome);
     return outcome;
   });
@@ -179339,16 +179218,12 @@ function failure(spec, language, code, reason) {
 
 // src/scan/code/dispatch.ts
 function createScannerWorkerAdapter(language, command, adapterOptions = {}) {
-  const { commandAsync } = adapterOptions;
-  const bound = (context) => boundWorkerAdapter(language, workerCommand(command(context)), adapterOptions).adapter;
-  const prepare = (context) => mapCancelable(commandAsync?.(context) ?? settledCancelable(command(context)), (value) => boundWorkerAdapter(language, workerCommand(value), adapterOptions));
+  const resolve3 = (context) => typeof command === "function" ? settledCancelable(command(context)) : command.commandAsync(context);
+  const prepare = (context) => mapCancelable(resolve3(context), (value) => boundWorkerAdapter(language, workerCommand(value), adapterOptions));
   const scanBatchAsync = (files, options, context) => {
     if (files.length === 0) {
       return settledCancelable([]);
     }
-    if (commandAsync === undefined) {
-      return bound(context).scanFilesAsync(files, options, context);
-    }
     return cancelableSequence(async (step) => {
       const { adapter } = await step(() => prepare(context));
       return step(() => adapter.scanFilesAsync(files, options, context));
@@ -179356,8 +179231,6 @@ function createScannerWorkerAdapter(language, command, adapterOptions = {}) {
   };
   return {
     language,
-    scanFile: (filePath, content, options, context) => bound(context).scanFile(filePath, content, options, context),
-    scanFiles: (files, options, context) => files.length === 0 ? [] : bound(context).scanFiles(files, options, context),
     scanFilesAsync: scanBatchAsync,
     prepare
   };
@@ -179367,20 +179240,6 @@ function boundWorkerAdapter(language, resolved, adapterOptions) {
   const runtime = resolved.ok ? resolved.runtime : [];
   const adapter = {
     language,
-    scanFile(filePath, content, options, context) {
-      const [scan] = adapter.scanFiles([{ filePath, content }], options, context);
-      return scan ?? emptyScan(language, filePath);
-    },
-    scanFiles(files, options, context) {
-      if (files.length === 0) {
-        return [];
-      }
-      if (!resolved.ok) {
-        return failedBatch(language, files, resolved.diagnostic);
-      }
-      const result = invokeScannerWorker(workerRequest(language, files, options, context, adapterOptions), resolved.command, adapterOptions.run, resolved.stripEnv);
-      return result.ok ? result.codeFiles : failedBatch(language, files, result.diagnostic);
-    },
     scanFilesAsync(files, options, context) {
       if (files.length === 0) {
         return settledCancelable([]);
@@ -179388,36 +179247,28 @@ function boundWorkerAdapter(language, resolved, adapterOptions) {
       if (!resolved.ok) {
         return settledCancelable(failedBatch(language, files, resolved.diagnostic));
       }
-      const task = invokeScannerWorkerAsync(workerRequest(language, files, options, context, adapterOptions), resolved.command, adapterOptions.runAsync, resolved.stripEnv);
+      const task = invokeScannerWorker(workerRequest(language, files, options, context, adapterOptions), resolved.command, adapterOptions.run, resolved.stripEnv);
       return mapCancelable(task, (result) => result.ok ? result.codeFiles : failedBatch(language, files, result.diagnostic));
     },
     prepare: () => settledCancelable({ argv, runtime, adapter })
   };
   return { argv, runtime, adapter };
 }
-function scanCodeFiles(projectRoot, files, codeInclude, read, options = {}) {
-  const plan = planCodeScan(files, codeInclude, read, options.onContent);
-  const context = scanContext(projectRoot, options);
-  for (const batch of plan.batches) {
-    const adapter = options.adapters?.[batch.language] ?? builtInAdapters[batch.language];
-    fillBatch(plan, batch, adapter.scanFiles(batch.files, batch.options, context));
-  }
-  return assemblePlan(plan);
-}
 function scanContext(projectRoot, options) {
   return options.scanners === undefined ? { projectRoot } : { projectRoot, scanners: options.scanners };
 }
-function scanCodeFilesAsync(projectRoot, files, codeInclude, read, options = {}) {
+function scanCodeFiles(projectRoot, files, codeInclude, read, options = {}) {
   const plan = planCodeScan(files, codeInclude, read, options.onContent);
   const context = scanContext(projectRoot, options);
   return cancelableSequence(async (step) => {
     const cache = new Map;
     for (const batch of plan.batches) {
       const base = options.adapters?.[batch.language] ?? builtInAdapters[batch.language];
-      const prepare = base.prepare?.bind(base);
-      const { argv, runtime, adapter } = prepare === undefined ? { argv: [], adapter: base } : await step(() => prepare(context));
-      const keys = batch.files.map((file) => codeScanCacheKey(batch.language, file.filePath, file.content, batch.options, argv, runtime));
-      const cached = keys.map((key) => options.cache?.get(key));
+      const { argv, runtime, adapter } = "scanFilesAsync" in base ? await step(() => base.prepare(context)) : { argv: [], adapter: base };
+      const keys = options.cache === undefined ? [] : batch.files.map((file) => codeScanCacheKey(batch.language, file.filePath, file.content, batch.options, argv, runtime));
+      const cached = options.cache === undefined ? batch.files.map(() => {
+        return;
+      }) : keys.map((key) => options.cache?.get(key));
       const missing = batch.files.filter((_, index) => cached[index] === undefined);
       const scanned = missing.length === 0 ? [] : await step(() => scanFilesAsync(adapter, missing, batch.options, context));
       let next = 0;
@@ -179425,7 +179276,7 @@ function scanCodeFilesAsync(projectRoot, files, codeInclude, read, options = {})
       fillBatch(plan, batch, results);
       results.forEach((scan, index) => {
         const key = keys[index];
-        if (scan !== undefined && key !== undefined && isReusableScan(scan)) {
+        if (options.cache !== undefined && scan !== undefined && key !== undefined && isReusableScan(scan)) {
           cache.set(key, scan);
         }
       });
@@ -179434,7 +179285,7 @@ function scanCodeFilesAsync(projectRoot, files, codeInclude, read, options = {})
   });
 }
 function scanFilesAsync(adapter, files, options, context) {
-  return adapter.scanFilesAsync?.(files, options, context) ?? settledCancelable(adapter.scanFiles(files, options, context));
+  return "scanFilesAsync" in adapter ? adapter.scanFilesAsync(files, options, context) : settledCancelable(adapter.scanFiles(files, options, context));
 }
 var builtInAdapters = {
   typescript: typeScriptAdapter,
@@ -179452,7 +179303,9 @@ function runtimeWorkerAdapter(language) {
     const command = scanners?.[language]?.command;
     return command === undefined ? { projectRoot } : { projectRoot, command };
   };
-  return createScannerWorkerAdapter(language, (context) => resolveRuntimeWorkerCommand(language, resolution(context)), { commandAsync: (context) => resolveRuntimeWorkerCommandAsync(language, resolution(context)) });
+  return createScannerWorkerAdapter(language, {
+    commandAsync: (context) => resolveRuntimeWorkerCommand(language, resolution(context))
+  });
 }
 function planCodeScan(files, codeInclude, read, onContent) {
   const slots = [];
@@ -179631,7 +179484,7 @@ function stripClosingHashes(text) {
 }
 function toAnchor(headingText) {
   const lowered = headingText.toLowerCase();
-  const replaced = lowered.replace(/[^\p{L}\p{N}]+/gu, "-");
+  const replaced = lowered.replace(/[^\p{L}\p{N}_]+/gu, "-");
   return replaced.replace(/^-+/, "").replace(/-+$/, "");
 }
 function matchCodeComment(line, filePath, lineNumber) {
@@ -179773,37 +179626,28 @@ function flushDanglingWith(pending, diagnostics, message) {
 // src/query/project-scan.ts
 function scanProject(options) {
   const loaded = loadProjectScan(options, options.keepContent === true);
-  if (!loaded.ok) {
-    return loaded;
-  }
-  const { inputs } = loaded;
-  const codeScan = scanCodeFiles(options.projectRoot, inputs.codeFiles, inputs.config.include.code, inputs.readFile, codeScanOptions(inputs, options));
-  const docReads = readDocFiles(inputs, options);
-  return { ok: true, scan: finishProjectScan(inputs, codeScan, docReads, options.buildGraph) };
-}
-function scanProjectAsync(options) {
-  const loaded = loadProjectScan(options, true);
   if (!loaded.ok) {
     return cancelableSequence(async () => loaded);
   }
   const { inputs } = loaded;
-  const fingerprint = JSON.stringify(inputs.config);
-  const sameConfiguration = options.cache.fingerprint === fingerprint;
-  if (!sameConfiguration && options.cache.fingerprint !== "") {
+  const previousCache = options.cache;
+  const fingerprint = previousCache === undefined ? undefined : JSON.stringify(inputs.config);
+  const sameConfiguration = previousCache !== undefined && previousCache.fingerprint === fingerprint;
+  if (previousCache !== undefined && !sameConfiguration && previousCache.fingerprint !== "") {
     options.onConfigurationChange?.();
   }
-  const codeScan = scanCodeFilesAsync(options.projectRoot, inputs.codeFiles, inputs.config.include.code, inputs.readFile, {
+  const codeScan = scanCodeFiles(options.projectRoot, inputs.codeFiles, inputs.config.include.code, inputs.readFile, {
     ...codeScanOptions(inputs, options),
-    ...sameConfiguration ? { cache: options.cache.entries } : {}
+    ...previousCache === undefined ? {} : { cache: sameConfiguration ? previousCache.entries : new Map }
   });
   const docReads = readDocFiles(inputs, options);
   return cancelableSequence(async (step) => {
     const { cache, ...code } = await step(codeScan);
-    const scan = finishProjectScan(inputs, code, docReads, true);
+    const scan = finishProjectScan(inputs, code, docReads, options.buildGraph);
     return {
       ok: true,
       scan,
-      cache: { fingerprint, entries: cache }
+      cache: { fingerprint: fingerprint ?? "", entries: cache }
     };
   });
 }
@@ -179908,19 +179752,12 @@ class Project {
     this.overlay.delete(relPath);
     this.overlayRevision += 1;
   }
-  resolve() {
-    const outcome = scanProject({
-      ...this.scanSources(this.overlay),
-      buildGraph: true,
-      keepContent: true
-    });
-    this.current = resolvedState(outcome);
-    return this.current;
-  }
   resolveAsync() {
     const revision = this.overlayRevision;
-    const scan = scanProjectAsync({
+    const scan = scanProject({
       ...this.scanSources(new Map(this.overlay)),
+      buildGraph: true,
+      keepContent: true,
       cache: this.cache,
       onConfigurationChange: clearRuntimeProbeCache
     });
@@ -180419,12 +180256,12 @@ function fullChangeText(changes) {
 }
 
 // src/query/check.ts
-function check(options) {
+async function check(options) {
   const audit = options.audit ?? false;
-  const outcome = scanProject({
+  const outcome = await scanProject({
     projectRoot: options.projectRoot,
     ...options.adapters === undefined ? {} : { adapters: options.adapters }
-  });
+  }).promise;
   if (!outcome.ok) {
     const sorted = sortDiagnostics(outcome.diagnostics);
     return { diagnostics: sorted, summary: summarizeDiagnostics(sorted) };
@@ -180498,8 +180335,8 @@ function collectGateViolations(result) {
   }
   return violations;
 }
-function related(options) {
-  const outcome = scanProject({ projectRoot: options.projectRoot, buildGraph: true });
+async function related(options) {
+  const outcome = await scanProject({ projectRoot: options.projectRoot, buildGraph: true }).promise;
   if (!outcome.ok) {
     return { ok: false, diagnostics: outcome.diagnostics };
   }
@@ -180557,12 +180394,12 @@ function computeContext(graph, contentByFile, inputFiles) {
     summary: { inputFiles: inputSet.size, contexts: contexts.length }
   };
 }
-function context(options) {
-  const outcome = scanProject({
+async function context(options) {
+  const outcome = await scanProject({
     projectRoot: options.projectRoot,
     buildGraph: true,
     keepContent: true
-  });
+  }).promise;
   if (!outcome.ok) {
     return { ok: false, diagnostics: outcome.diagnostics };
   }
@@ -180636,12 +180473,12 @@ function compareBlocks(left, right) {
 }
 
 // src/query/graph-output.ts
-function graph(options) {
-  const outcome = scanProject({
+async function graph(options) {
+  const outcome = await scanProject({
     projectRoot: options.projectRoot,
     buildGraph: true,
     keepContent: true
-  });
+  }).promise;
   if (!outcome.ok) {
     return { ok: false, diagnostics: outcome.diagnostics };
   }
@@ -181136,13 +180973,6 @@ class CliError extends Error {
   }
 }
 
-class InitCliError extends CliError {
-  constructor(message, guidance) {
-    super(message, guidance);
-    this.name = "InitCliError";
-  }
-}
-
 class DiagnosticOutputError extends Error {
   constructor(message) {
     super(message);
@@ -182101,7 +181931,6 @@ function readFileOrUndefined(path) {
 }
 
 // src/setup/init-plan.ts
-var CONFIG_FILE_NAME2 = "docbridge.config.json";
 var INIT_SKILL_NAMES = ["docbridge"];
 var LEGACY_SKILL_NAMES = [
   "docbridge-adopt",
@@ -182269,7 +182098,7 @@ function planConfigOperations(input) {
   return [
     {
       action,
-      path: CONFIG_FILE_NAME2,
+      path: CONFIG_FILE_NAME,
       content,
       reason: "Create docbridge.config.json from discovered scope."
     }
@@ -182421,7 +182250,7 @@ function resolveInitWithAgentTarget(discovery, options) {
   return { target: discovery.agent.defaultTarget, error: undefined };
 }
 function readExistingConfig(projectRoot) {
-  const configPath = join12(projectRoot, CONFIG_FILE_NAME2);
+  const configPath = join12(projectRoot, CONFIG_FILE_NAME);
   let rawText;
   try {
     rawText = readFileSync7(configPath, "utf8");
@@ -182499,7 +182328,7 @@ function parseInitOptions(args, command) {
     if (arg === "--root") {
       const root = args[index + 1];
       if (root === undefined) {
-        throw new InitCliError("--root requires a path.", rootPathGuidance(command));
+        throw new CliError("--root requires a path.", rootPathGuidance(command));
       }
       options.root = root;
       index += 1;
@@ -182508,22 +182337,22 @@ function parseInitOptions(args, command) {
     if (arg === "--agent-target") {
       const target = args[index + 1];
       if (target === undefined) {
-        throw new InitCliError("--agent-target requires a value.", agentTargetGuidance(command));
+        throw new CliError("--agent-target requires a value.", agentTargetGuidance(command));
       }
       if (!AGENT_TARGETS.has(target)) {
-        throw new InitCliError(`Unknown agent target: ${target}. Supported values: codex, claude, both${command === "init" ? ", none" : ""}.`, agentTargetGuidance(command));
+        throw new CliError(`Unknown agent target: ${target}. Supported values: codex, claude, both${command === "init" ? ", none" : ""}.`, agentTargetGuidance(command));
       }
       if (command === "init-with-agent" && target === "none") {
-        throw new InitCliError("init-with-agent requires an agent target other than none.", agentTargetGuidance(command));
+        throw new CliError("init-with-agent requires an agent target other than none.", agentTargetGuidance(command));
       }
       options.agentTarget = target;
       index += 1;
       continue;
     }
     if (arg.startsWith("--")) {
-      throw new InitCliError(`Unknown option: ${arg}`, commandHelpGuidance(command));
+      throw new CliError(`Unknown option: ${arg}`, commandHelpGuidance(command));
     }
-    throw new InitCliError(`Unexpected argument: ${arg}`, commandHelpGuidance(command));
+    throw new CliError(`Unexpected argument: ${arg}`, commandHelpGuidance(command));
   }
   return options;
 }
@@ -182610,19 +182439,19 @@ function resolveConfirmedScope(input) {
     };
   }
   if (!input.prompts.isInteractive) {
-    throw new InitCliError("Interactive setup requires a TTY. Re-run with --yes for non-interactive mode.");
+    throw new CliError("Interactive setup requires a TTY. Re-run with --yes for non-interactive mode.");
   }
   if (input.discovery.docs.ambiguous) {
     const choices = input.discovery.docs.candidates.map((candidate) => candidate.pattern);
     if (choices.length === 0) {
-      throw new InitCliError("Docs scope is ambiguous and no candidates were detected. Create docbridge.config.json manually.");
+      throw new CliError("Docs scope is ambiguous and no candidates were detected. Create docbridge.config.json manually.");
     }
     const docsPattern2 = input.prompts.select("Choose docs scope:", choices, choices[0] ?? "");
     const languages2 = selectLanguages(input.discovery.code.languages, input.prompts);
     return { docsPattern: docsPattern2, languages: languages2 };
   }
   if (input.discovery.docs.recommended === undefined) {
-    throw new InitCliError("Docs scope could not be determined.");
+    throw new CliError("Docs scope could not be determined.");
   }
   let docsPattern = input.discovery.docs.recommended.pattern;
   if (!input.prompts.confirm(`Use docs scope ${docsPattern}?`, true)) {
@@ -182656,7 +182485,7 @@ function selectLanguages(languages, prompts) {
     }
   }
   if (selected.length === 0) {
-    throw new InitCliError("At least one supported code language must remain in scope.");
+    throw new CliError("At least one supported code language must remain in scope.");
   }
   return selected;
 }
@@ -182686,10 +182515,10 @@ function resolveProjectRoot(root, command) {
   try {
     stats = statSync4(projectRoot);
   } catch {
-    throw new InitCliError(`Root path does not exist: ${root}`, rootPathGuidance(command));
+    throw new CliError(`Root path does not exist: ${root}`, rootPathGuidance(command));
   }
   if (!stats.isDirectory()) {
-    throw new InitCliError(`Root path is not a directory: ${root}`, rootPathGuidance(command));
+    throw new CliError(`Root path is not a directory: ${root}`, rootPathGuidance(command));
   }
   return projectRoot;
 }
@@ -182965,8 +182794,7 @@ function planUpgrade(input) {
     pending,
     messages,
     nextSteps: buildNextSteps({ mode, cli, options: input.options, pending }),
-    requiresConfirmation: mode === "apply" && !input.options.dryRun && !input.options.yes && operations.some((operation) => operation.action === "overwrite" || operation.action === "remove"),
-    exitCode: 0
+    requiresConfirmation: mode === "apply" && !input.options.dryRun && !input.options.yes && operations.some((operation) => operation.action === "overwrite" || operation.action === "remove")
   };
 }
 function planOperations(input) {
@@ -183149,7 +182977,7 @@ function runUpgrade(options, io, initRuntime, runtime) {
   });
   if (plan.mode === "check" || options.dryRun) {
     io.stdout(formatUpgradePlan(plan));
-    return plan.exitCode;
+    return 0;
   }
   return applyUpgrade(projectRoot, packageRoot, plan, io, initRuntime);
 }
@@ -183167,7 +182995,7 @@ function applyUpgrade(projectRoot, packageRoot, plan, io, initRuntime) {
     applySkillOperation(projectRoot, packageRoot, operation);
   }
   io.stdout(formatUpgradePlan(plan));
-  return plan.exitCode;
+  return 0;
 }
 function parseAgentTarget(value) {
   if (value === undefined) {
@@ -183192,6 +183020,31 @@ function resolveProjectRoot2(root) {
   return projectRoot;
 }
 
+// src/cli/worker-signals.ts
+async function killingWorkersOnSignal(scan) {
+  const signals = process.platform === "win32" ? ["SIGINT", "SIGTERM"] : ["SIGINT", "SIGTERM", "SIGHUP"];
+  const handlers = new Map;
+  const remove = () => {
+    for (const [signal, handler] of handlers) {
+      process.off(signal, handler);
+    }
+  };
+  for (const signal of signals) {
+    const handler = () => {
+      killRunningWorkers();
+      remove();
+      process.kill(process.pid, signal);
+    };
+    handlers.set(signal, handler);
+    process.on(signal, handler);
+  }
+  try {
+    return await scan();
+  } finally {
+    remove();
+  }
+}
+
 // src/cli/index.ts
 var VERSION = package_default.version;
 function parseCheckOptions(args) {
@@ -183219,9 +183072,9 @@ function resolveProjectRoot3(root, command) {
   }
   return projectRoot;
 }
-function runCheck(options, io) {
+async function runCheck(options, io) {
   const projectRoot = resolveProjectRoot3(options.root, "check");
-  const result = check({ projectRoot, audit: options.audit });
+  const result = await killingWorkersOnSignal(() => check({ projectRoot, audit: options.audit }));
   if (options.json) {
     io.stdout(`${JSON.stringify(result, null, 2)}
 `);
@@ -183242,7 +183095,7 @@ See \`docbridge docs show troubleshooting\` for diagnostic codes and fixes.
   }
   return result.summary.errors > 0 ? 1 : 0;
 }
-function runFileCommand(command, options, io, execute, render) {
+async function runFileCommand(command, options, io, execute, render) {
   const projectRoot = resolveProjectRoot3(options.root, command);
   const inputFiles = [...options.files];
   if (options.stdin) {
@@ -183250,7 +183103,7 @@ function runFileCommand(command, options, io, execute, render) {
     inputFiles.push(...readStdin().split(`
 `));
   }
-  const outcome = execute(projectRoot, inputFiles);
+  const outcome = await killingWorkersOnSignal(async () => execute(projectRoot, inputFiles));
   if (!outcome.ok) {
     throw new DiagnosticOutputError(outcome.diagnostics.map(formatDiagnostic).join(`
 `));
@@ -183271,7 +183124,7 @@ function writeStructuredResult(result, options) {
 `);
   }
 }
-function runRelated(options, io) {
+async function runRelated(options, io) {
   if (!options.stdin && options.files.length === 0) {
     throw new CliError("No input files were provided.", missingInputGuidance("related"));
   }
@@ -183300,7 +183153,7 @@ function runRelated(options, io) {
     return 0;
   });
 }
-function runContext(options, io) {
+async function runContext(options, io) {
   if (!options.stdin && options.files.length === 0) {
     throw new CliError("No input files were provided.", missingInputGuidance("context"));
   }
@@ -183314,7 +183167,7 @@ function runContext(options, io) {
     return 0;
   });
 }
-function runGraph(options, io) {
+async function runGraph(options, io) {
   return runFileCommand("graph", options, io, (projectRoot, inputFiles) => graph({ projectRoot, inputFiles, includeContent: options.includeContent }), (result, projectRoot, inputFiles) => {
     const normalizedInputFiles = normalizeChangedPaths(projectRoot, inputFiles);
     writeStructuredResult(result, {
@@ -183368,7 +183221,7 @@ var COMMAND_HANDLERS = {
     return 0;
   }
 };
-function run(argv, io = {
+async function run(argv, io = {
   stdout: (text) => process.stdout.write(text),
   stderr: (text) => process.stderr.write(text)
 }, initRuntime = { prompts: createDefaultPrompts() }, cliRuntime = {}) {
@@ -183390,7 +183243,7 @@ function run(argv, io = {
       return 0;
     }
     if (isSubcommand(command)) {
-      const exitCode = COMMAND_HANDLERS[command](rest, io, initRuntime, cliRuntime);
+      const exitCode = await COMMAND_HANDLERS[command](rest, io, initRuntime, cliRuntime);
       writeUpdateNotice(argv, io, initRuntime, cliRuntime);
       return exitCode;
     }
@@ -183455,7 +183308,7 @@ if (__require.main == __require.module) {
   const argv = process.argv.slice(2);
   const isTty = process.stderr.isTTY === true;
   const latest = await resolveLatestForInvocation(argv, process.env, isTty);
-  process.exitCode = run(argv, {
+  process.exitCode = await run(argv, {
     stdout: (text) => process.stdout.write(text),
     stderr: (text) => process.stderr.write(text)
   }, { prompts: createDefaultPrompts() }, { ...latest !== undefined ? { latest } : {}, env: process.env, isTty });

package/docs/README.md

@@ -63,7 +63,7 @@ with the specification for the interface whose exact contract you need:
 - [Commit messages](contributing/commits.md)
 - [Pull requests](contributing/pull-requests.md)
 - [Releasing](contributing/releasing.md)
-- [Self-audit baseline](contributing/self-audit.md)
+- [Self-audit](contributing/self-audit.md)
 
 ## Historical records
 

package/docs/user/linking.md

@@ -255,8 +255,9 @@ Use the scanner-produced canonical symbol ID exactly.
 ## Heading anchors and reciprocity
 
 DocBridge creates anchors from ATX headings only. It lowercases the heading,
-collapses runs of whitespace and punctuation to `-`, preserves Unicode letters
-and numbers, and removes leading and trailing hyphens. `## Login Spec (v2)` is
+collapses runs of whitespace and punctuation other than `_` to `-`, keeps `_`
+as GitHub's heading slugs do, preserves Unicode letters and numbers, and removes
+leading and trailing hyphens. `## Login Spec (v2)` is
 `#login-spec-v2`.
 
 Empty headings have no anchor; a `@code` annotation attached to an empty

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docbridge",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "A CLI that links Markdown specifications and code declarations. Runs on Node.js and Bun.",
   "keywords": [
     "bun",