diff --git a/LifeOS/install/LIFEOS/TOOLS/ReferenceCheck.ts b/LifeOS/install/LIFEOS/TOOLS/ReferenceCheck.ts
index b515f7b4f0..3d8ce0b2d3 100755
--- a/LifeOS/install/LIFEOS/TOOLS/ReferenceCheck.ts
+++ b/LifeOS/install/LIFEOS/TOOLS/ReferenceCheck.ts
@@ -1,6 +1,6 @@
#!/usr/bin/env bun
/**
- * @version 1.7.0
+ * @version 1.8.0
* ReferenceCheck.ts — Full-surface reference validator for the LifeOS system.
*
* Walks every file under ~/.claude (excluding noise dirs), extracts every
@@ -24,6 +24,7 @@
* bun ReferenceCheck.ts --quiet # issues only
* bun ReferenceCheck.ts --changed # git-dirty files + dependents
* bun ReferenceCheck.ts --stale # include stale findings
+ * bun ReferenceCheck.ts --content # also check `path:line` — `snippet` citations by content (lib/CitationCheck.ts)
* bun ReferenceCheck.ts --orphans # include orphan findings
* bun ReferenceCheck.ts --root
# scan an install root other than ~/.claude (a staged release)
* bun ReferenceCheck.ts --shipped-paths # also resolve quoted install paths + spawn/dynamic-import specifiers
@@ -31,7 +32,7 @@
*
* Exit codes:
* 0 — no missing refs (stale/orphan do not fail)
- * 1 — missing refs found
+ * 1 — missing refs found (with --content, also rotten citations)
* 2 — scan error (unreadable root, etc)
*/
@@ -39,6 +40,7 @@ import { readFileSync, statSync, lstatSync, existsSync, readdirSync, realpathSyn
import { join, resolve, dirname, relative, extname, sep, basename } from 'path';
import { execFileSync } from 'child_process';
import { getClaudeDir } from './Paths';
+import { checkCitation, findCitations, isRotten, type CitationState } from './lib/CitationCheck';
// ── Arg parsing (manual, zero deps) ──
@@ -53,6 +55,9 @@ Flags:
--quiet Suppress OK lines; issues only
--changed Only scan git-dirty files + their dependents
--stale Include stale findings (ref mtime > referrer mtime)
+ --content Also check "path:line" — "snippet" citations in .md files by content:
+ ok, moved, ambiguous, changed, gone, dir, outside. Pointers with no
+ snippet are counted, not checked. Not narrowed by --changed.
--orphans Include orphan findings (file exists, nothing refs it)
--root Scan as the install root instead of ~/.claude (a staged release tree)
--shipped-paths
@@ -61,7 +66,7 @@ Flags:
dynamic import() specifiers — in code files too. The staged G7 lane.
--help This message
-Exit codes: 0 clean, 1 missing refs, 2 scan error`);
+Exit codes: 0 clean, 1 missing refs (or rotten citations under --content), 2 scan error`);
process.exit(0);
}
@@ -69,6 +74,8 @@ const jsonOutput = args.includes('--json');
const quiet = args.includes('--quiet');
const changedOnly = args.includes('--changed');
const includeStale = args.includes('--stale');
+// --content: the opt-in content check of `path:line` — `snippet` citations. public issue #2221, @drpaulobernardy
+const contentMode = args.includes('--content');
const includeOrphans = args.includes('--orphans');
// --shipped-paths / --root: the staged-install lane. G7 used to run only against
// the live tree, so a shipped file naming a path that the release scrub removes
@@ -807,7 +814,9 @@ const findings: Finding[] = [];
const referenced = new Set(); // absolute paths of files that are referenced
let scannedFiles = 0;
let scannedRefs = 0;
-const historicalSkipped: string[] = []; // files whose own frontmatter says `references: historical`
+const historicalSkipped: string[] = [];
+const citationResults: { file: string; line: number; cited: string; snippet: string; state: CitationState; foundAt?: number[] }[] = [];
+let citationsWithoutSnippet = 0; // files whose own frontmatter says `references: historical`
let allFiles: string[];
try {
@@ -842,6 +851,17 @@ for (const file of allFiles) {
historicalSkipped.push(relative(CLAUDE_DIR, file));
continue;
}
+ if (contentMode && file.endsWith('.md')) {
+ const found = findCitations(content);
+ citationsWithoutSnippet += found.withoutSnippet;
+ for (const c of found.citations) {
+ try {
+ citationResults.push({ file: relative(CLAUDE_DIR, file), line: c.line, cited: `${c.path}:${c.citedLine}`, snippet: c.snippet, ...checkCitation(CLAUDE_DIR, c.path, c.citedLine, c.snippet) });
+ } catch (e) {
+ scanFailed(`cannot check citation ${c.path}:${c.citedLine}`, file, e);
+ }
+ }
+ }
const refs = extractRefs(content, file);
if (refs.length > 0) fileRefs.set(file, refs);
for (const r of refs) {
@@ -998,6 +1018,15 @@ const elapsedMs = Date.now() - startedAt;
const missing = uniqueFindings.filter(f => f.type === 'missing');
const stale = uniqueFindings.filter(f => f.type === 'stale');
const orphan = uniqueFindings.filter(f => f.type === 'orphan');
+const movedCitations = citationResults.filter(c => c.state === 'moved');
+const rottenCitations = citationResults.filter(c => isRotten(c.state));
+const content = contentMode ? {
+ citations: citationResults.length,
+ ok: citationResults.filter(c => c.state === 'ok').length,
+ moved: movedCitations,
+ rotten: rottenCitations,
+ withoutSnippet: citationsWithoutSnippet,
+} : null;
const summary = {
scannedFiles,
@@ -1011,6 +1040,7 @@ const summary = {
stale: stale.length,
orphan: orphan.length,
},
+ ...(content ? { content } : {}),
};
if (jsonOutput) {
@@ -1039,7 +1069,18 @@ if (jsonOutput) {
`\nReferenceCheck: ${scannedFiles} files, ${scannedRefs} refs, ${missing.length} missing, ${stale.length} stale, ${orphan.length} orphan, ${historicalSkipped.length} historical (skipped by their own frontmatter) — ${elapsedMs}ms`
);
}
- if (uniqueFindings.length === 0 && !quiet) {
+ if (content && movedCitations.length > 0) {
+ console.error(`\n📍 MOVED CITATIONS (${movedCitations.length}) — the claim holds, the line number is old:`);
+ for (const c of movedCitations) console.error(` ${c.file}:${c.line} → ${c.cited} now at line ${c.foundAt![0]}`);
+ }
+ if (content && rottenCitations.length > 0) {
+ console.error(`\n❌ ROTTEN CITATIONS (${rottenCitations.length}) — re-read the cited code:`);
+ for (const c of rottenCitations) console.error(` ${c.file}:${c.line} → ${c.cited} (${c.state}${c.foundAt ? ` at lines ${c.foundAt.join(', ')}` : ''})`);
+ }
+ if (content && (!quiet || movedCitations.length + rottenCitations.length > 0)) {
+ console.error(`Citations: ${content.citations} checked, ${content.ok} ok, ${movedCitations.length} moved, ${rottenCitations.length} rotten; ${content.withoutSnippet} path:line without a snippet (not checked)`);
+ }
+ if (uniqueFindings.length === 0 && rottenCitations.length === 0 && !quiet) {
console.error('✅ All references valid.');
}
}
@@ -1051,4 +1092,4 @@ if (scanErrors.length > 0) {
if (scanErrors.length > 20) console.error(` … and ${scanErrors.length - 20} more`);
process.exit(2);
}
-process.exit(missing.length > 0 ? 1 : 0);
+process.exit(missing.length > 0 || rottenCitations.length > 0 ? 1 : 0);
diff --git a/LifeOS/install/LIFEOS/TOOLS/lib/CitationCheck.test.ts b/LifeOS/install/LIFEOS/TOOLS/lib/CitationCheck.test.ts
new file mode 100644
index 0000000000..6fc122ce07
--- /dev/null
+++ b/LifeOS/install/LIFEOS/TOOLS/lib/CitationCheck.test.ts
@@ -0,0 +1,116 @@
+// CitationCheck and ReferenceCheck --content (public issue #2221).
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { checkCitation, findCitations, isRotten } from "./CitationCheck";
+
+let root = "", outsideDir = "";
+beforeAll(() => {
+ root = mkdtempSync(join(tmpdir(), "citation-root-"));
+ outsideDir = mkdtempSync(join(tmpdir(), "citation-outside-"));
+ mkdirSync(join(root, "hooks"));
+ writeFileSync(join(root, "hooks/Foo.ts"), ["const a = 1;", "if (!session) return;", "log('x');", "log('x');", "use `tick` here"].join("\n"));
+ writeFileSync(join(outsideDir, "Secret.ts"), "if (!session) return;\n");
+ symlinkSync(join(outsideDir, "Secret.ts"), join(root, "hooks/Link.ts"));
+});
+afterAll(() => { rmSync(root, { recursive: true, force: true }); rmSync(outsideDir, { recursive: true, force: true }); });
+
+describe("checkCitation", () => {
+ test("ok: the cited line holds the snippet", () => {
+ expect(checkCitation(root, "hooks/Foo.ts", 2, "if (!session)")).toEqual({ state: "ok" });
+ });
+ test("moved: the snippet is on exactly one other line", () => {
+ expect(checkCitation(root, "hooks/Foo.ts", 1, "if (!session)")).toEqual({ state: "moved", foundAt: [2] });
+ });
+ test("ambiguous: the snippet is on several other lines", () => {
+ expect(checkCitation(root, "hooks/Foo.ts", 1, "log('x')")).toEqual({ state: "ambiguous", foundAt: [3, 4] });
+ });
+ test("changed: the snippet is nowhere in the file", () => {
+ expect(checkCitation(root, "hooks/Foo.ts", 2, "if (!user)")).toEqual({ state: "changed" });
+ });
+ test("gone: the file does not exist", () => {
+ expect(checkCitation(root, "hooks/Bar.ts", 2, "if (!session)")).toEqual({ state: "gone" });
+ });
+ test("dir: the path is a directory", () => {
+ expect(checkCitation(root, "hooks", 2, "if (!session)")).toEqual({ state: "dir" });
+ });
+ test("outside: a symlink or a ../ path that leaves the checked tree", () => {
+ expect(checkCitation(root, "hooks/Link.ts", 1, "if (!session)")).toEqual({ state: "outside" });
+ const rel = join("..", outsideDir.split("/").pop()!, "Secret.ts");
+ expect(checkCitation(root, rel, 1, "if (!session)")).toEqual({ state: "outside" });
+ expect(checkCitation(root, join(outsideDir, "Secret.ts"), 1, "if (!session)")).toEqual({ state: "outside" });
+ });
+ test("~/.claude/ reads as the checked root", () => {
+ expect(checkCitation(root, "~/.claude/hooks/Foo.ts", 2, "if (!session)")).toEqual({ state: "ok" });
+ });
+ test("only ok and moved are not rotten", () => {
+ expect(["ok", "moved", "ambiguous", "changed", "gone", "dir", "outside"].filter(s => !isRotten(s as any))).toEqual(["ok", "moved"]);
+ });
+});
+
+describe("findCitations", () => {
+ test("single and double backtick snippets, pointers without a snippet counted, fences skipped", () => {
+ const text = [
+ "See `hooks/Foo.ts:2` — `if (!session)` and `hooks/Foo.ts:5` — `` use `tick` here ``.",
+ "Also `hooks/Foo.ts:3` with no snippet, and `step:2`, which is not a path.",
+ "```",
+ "`hooks/Foo.ts:9` — `example only`",
+ "```",
+ ].join("\n");
+ const { citations, withoutSnippet } = findCitations(text);
+ expect(citations).toEqual([
+ { line: 1, path: "hooks/Foo.ts", citedLine: 2, snippet: "if (!session)" },
+ { line: 1, path: "hooks/Foo.ts", citedLine: 5, snippet: "use `tick` here" },
+ ]);
+ expect(withoutSnippet).toBe(1);
+ expect(checkCitation(root, "hooks/Foo.ts", 5, citations[1].snippet).state).toBe("ok");
+ });
+ test("tilde fences and a 4-backtick fence holding a 3-backtick example are skipped; text after the close is read", () => {
+ const text = [
+ "~~~markdown",
+ "`hooks/Foo.ts:9` — `inside tildes`",
+ "~~~",
+ "````markdown",
+ "```",
+ "inner example",
+ "```",
+ "`hooks/Foo.ts:9` — `between the fences`",
+ "````",
+ "```ts",
+ "~~~ does not close a backtick fence",
+ "`hooks/Foo.ts:9` — `after the tildes`",
+ "```",
+ "After: `hooks/Foo.ts:2` — `if (!session)`.",
+ ].join("\n");
+ expect(findCitations(text).citations).toEqual([{ line: 14, path: "hooks/Foo.ts", citedLine: 2, snippet: "if (!session)" }]);
+ });
+});
+
+describe("ReferenceCheck --content", () => {
+ const tool = join(import.meta.dir, "..", "ReferenceCheck.ts");
+ const run = (...args: string[]) => {
+ const p = Bun.spawnSync(["bun", tool, "--root", root, "--json", ...args], { stdout: "pipe", stderr: "pipe" });
+ return { code: p.exitCode, json: JSON.parse(p.stdout.toString()) };
+ };
+ beforeAll(() => {
+ writeFileSync(join(root, "NOTES.md"), "Holds: `hooks/Foo.ts:2` — `if (!session)`.\nMoved: `hooks/Foo.ts:1` — `if (!session)`.\nRotten: `hooks/Foo.ts:2` — `if (!user)`.\nBare: `hooks/Foo.ts:3`.\n");
+ });
+ test("the default run does not read citations and its output has no content key", () => {
+ const { code, json } = run();
+ expect(json.content).toBeUndefined();
+ expect(code).toBe(0);
+ });
+ test("--stale alone does not read citations either", () => {
+ expect(run("--stale").json.content).toBeUndefined();
+ });
+ test("--content reports moved and rotten citations, counts pointers without a snippet, and exits 1", () => {
+ const { code, json } = run("--content");
+ expect(json.content.citations).toBe(3);
+ expect(json.content.ok).toBe(1);
+ expect(json.content.moved.map((c: any) => [c.line, c.foundAt])).toEqual([[2, [2]]]);
+ expect(json.content.rotten.map((c: any) => [c.line, c.state])).toEqual([[3, "changed"]]);
+ expect(json.content.withoutSnippet).toBe(1);
+ expect(code).toBe(1);
+ });
+});
diff --git a/LifeOS/install/LIFEOS/TOOLS/lib/CitationCheck.ts b/LifeOS/install/LIFEOS/TOOLS/lib/CitationCheck.ts
new file mode 100644
index 0000000000..7d969e49f7
--- /dev/null
+++ b/LifeOS/install/LIFEOS/TOOLS/lib/CitationCheck.ts
@@ -0,0 +1,76 @@
+/**
+ * CitationCheck — checks a `path:line` — `snippet` citation by content, never by date (public issue #2221).
+ *
+ * A doc that says "see `hooks/Foo.hook.ts:128` — `if (!session)`" makes a claim about code. The snippet is what makes the
+ * claim checkable: with a line number alone, nothing tells "the code moved" from "the code is gone", and a file's mtime
+ * changes whenever anything in it is touched. The states:
+ * ok — line N contains the snippet.
+ * moved — it does not, but the snippet is on exactly one other line: the claim holds, only the number is old.
+ * ambiguous — the snippet is on several other lines: the citation cannot be re-pointed. → rotten
+ * changed — the snippet is nowhere in the file. → rotten
+ * gone — the cited path does not exist. → rotten
+ * dir — the cited path is a directory, which has no lines. → rotten
+ * outside — the cited path resolves (symlinks followed) outside the checked tree. → rotten
+ *
+ * It checks that the citation still points at the same code, not that the sentence next to it is true.
+ * The snippet convention is optional: a `path:line` pointer with no snippet is not checked here, only counted.
+ */
+
+import { readFileSync, realpathSync, statSync } from 'fs';
+import { isAbsolute, join, relative, sep } from 'path';
+
+export type CitationState = 'ok' | 'moved' | 'ambiguous' | 'changed' | 'gone' | 'dir' | 'outside';
+export interface CitationResult { state: CitationState; foundAt?: number[] }
+export const isRotten = (s: CitationState): boolean => s !== 'ok' && s !== 'moved';
+
+/** `path:line` — `snippet`, with the snippet in single backticks, or in double ones when it holds a backtick. */
+export const CITATION_RE = /`([^`\s]+?):(\d+)`\s*[—–-]\s*(?:``\s?(.+?)\s?``|`([^`]+)`)/g;
+/** A `path:line` pointer with no snippet after it. The path has a dot or a slash, so `step:2` is not one. */
+export const POINTER_RE = /`([^`\s]*[./][^`\s]*?):(\d+)`(?!\s*[—–-]\s*`)/g;
+
+/**
+ * The state of one citation. `path` is relative to `root`, absolute, or starts with `~/.claude/` (read as `root`).
+ * It resolves through `realpathSync` and must stay inside `root`. An unreadable root or file throws: a citation that
+ * could not be read is never reported as fine.
+ */
+export function checkCitation(root: string, path: string, line: number, snippet: string): CitationResult {
+ const rootReal = realpathSync(root);
+ const rel = path.startsWith('~/.claude/') ? path.slice('~/.claude/'.length) : path;
+ let real: string;
+ try {
+ real = realpathSync(isAbsolute(rel) ? rel : join(rootReal, rel));
+ } catch (e: any) {
+ if (e?.code === 'ENOENT' || e?.code === 'ENOTDIR') return { state: 'gone' };
+ throw e;
+ }
+ const inside = relative(rootReal, real);
+ if (inside === '..' || inside.startsWith('..' + sep) || isAbsolute(inside)) return { state: 'outside' };
+ if (statSync(real).isDirectory()) return { state: 'dir' };
+ const lines = readFileSync(real, 'utf-8').split('\n');
+ if (lines[line - 1]?.includes(snippet)) return { state: 'ok' };
+ const foundAt = lines.flatMap((l, i) => (l.includes(snippet) ? [i + 1] : []));
+ if (foundAt.length > 1) return { state: 'ambiguous', foundAt };
+ return foundAt.length === 1 ? { state: 'moved', foundAt } : { state: 'changed' };
+}
+
+export interface Citation { line: number; path: string; citedLine: number; snippet: string }
+
+/** The citations in a markdown text, and how many `path:line` pointers in it have no snippet. Fenced blocks are examples
+ * and are skipped. A fence is three or more backticks or tildes, as in CommonMark: it closes only on the same
+ * character, at least as long and with nothing after it, so a 4-backtick fence can hold a 3-backtick example. */
+export function findCitations(text: string): { citations: Citation[]; withoutSnippet: number } {
+ const citations: Citation[] = [];
+ let withoutSnippet = 0;
+ let fence: { char: string; size: number } | null = null;
+ text.split('\n').forEach((lineText, i) => {
+ const f = /^\s*(`{3,}|~{3,})(.*)$/.exec(lineText);
+ if (!fence && f && !(f[1][0] === '`' && f[2].includes('`'))) { fence = { char: f[1][0], size: f[1].length }; return; }
+ if (fence && f && f[1][0] === fence.char && f[1].length >= fence.size && !f[2].trim()) { fence = null; return; }
+ if (fence) return;
+ for (const m of lineText.matchAll(CITATION_RE)) {
+ citations.push({ line: i + 1, path: m[1], citedLine: Number(m[2]), snippet: (m[3] ?? m[4]) });
+ }
+ withoutSnippet += [...lineText.matchAll(POINTER_RE)].length;
+ });
+ return { citations, withoutSnippet };
+}