peaks-loop 4.1.0 → 4.1.2

package/dist/services/codegraph/codegraph-upstream-layout.js

@@ -0,0 +1,85 @@
+// src/services/codegraph/codegraph-upstream-layout.ts
+//
+// ONE answer to "where did the installed `@colbymchenry/codegraph` put its
+// files", for the four places peaks-loop reaches into the package.
+//
+// WHY THIS EXISTS (the 1.6.2 upgrade). Before it, one rule covered all four
+// sites: join `dist/…` onto whatever directory upstream's `package.json`
+// sits in. That rule is false from 1.6.x. The main package there is TYPE
+// DEFINITIONS ONLY — `find dist -name '*.js' | wc -l` is 0 — and the runtime
+// moved into a per-platform optionalDependency
+// (`@colbymchenry/codegraph-<platform>-<arch>`), whose own `lib/dist/` holds
+// the entry AND the modules. Every one of the four joins therefore resolved
+// to a path that does not exist, so the binary could not be spawned and the
+// two oracles could not be loaded.
+//
+// The fix is a PROBE, not a version check: the candidates are ordered
+// newest-layout-first (per-platform bundle, then the main package's own
+// `dist/`) and the first one whose `dist/bin/codegraph.js` actually exists
+// wins. So a 0.7.x install still resolves, a future release that moves the
+// files again is found without an edit here, and nothing is decided by a
+// version string that can drift from the filesystem.
+//
+// This module is separate from `codegraph-service.ts` rather than a few more
+// functions inside it, because that file sits under eslint's `max-lines` cap
+// and the resolver does not fit. It has no dependency on the service, so the
+// two oracles can import it without pulling in the service's session and
+// process-runner imports.
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+const CODEGRAPH_PACKAGE_NAME = '@colbymchenry/codegraph';
+/** The directory a 1.6.x per-platform bundle keeps its `dist/` under. */
+const CODEGRAPH_BUNDLE_LIB_DIR = 'lib';
+/**
+ * Directories a `dist/` might hang off, newest layout first.
+ *
+ * The platform bundle is resolved through a require anchored AT the main
+ * package's own `package.json`, never at this module: the bundle is a
+ * dependency OF the main package, so under pnpm's isolated layout it is
+ * linked into the MAIN package's `node_modules/` and is invisible to a
+ * require anchored here. A missing bundle (0.7.x, or a registry mirror that
+ * skipped the optionalDependency) is not an error — the main package's own
+ * `dist/` is the next candidate.
+ */
+function upstreamDistRoots(packageJsonPath) {
+    const bundlePackageName = `${CODEGRAPH_PACKAGE_NAME}-${process.platform}-${process.arch}`;
+    let bundleDir = null;
+    try {
+        const require = createRequire(packageJsonPath);
+        const bundlePackageJson = require.resolve(`${bundlePackageName}/package.json`);
+        bundleDir = dirname(bundlePackageJson);
+    }
+    catch {
+        // A missing bundle is an EXPECTED state, not a swallow: 0.7.x has none,
+        // and a registry mirror that did not mirror the optionalDependency
+        // leaves the install without one. It is reported by the assignment —
+        // the caller below then has exactly one candidate root instead of two.
+        bundleDir = null;
+    }
+    const roots = bundleDir === null ? [] : [join(bundleDir, CODEGRAPH_BUNDLE_LIB_DIR)];
+    roots.push(dirname(packageJsonPath));
+    return roots;
+}
+/**
+ * Resolve upstream's layout for one `package.json` path.
+ *
+ * `packageJsonPath` is a parameter rather than a lookup because the doctor's
+ * yarn-pnp fallback reaches the same package by a filesystem walk and needs
+ * the layout for THAT path, not for whatever `createRequire` finds.
+ */
+export function codegraphUpstreamLayoutFor(packageJsonPath) {
+    const distDirs = upstreamDistRoots(packageJsonPath).map((root) => join(root, 'dist'));
+    const probed = distDirs.find((dir) => existsSync(join(dir, 'bin', 'codegraph.js')));
+    const moduleDir = probed ?? distDirs[0] ?? '';
+    return {
+        binaryPath: moduleDir === '' ? '' : join(moduleDir, 'bin', 'codegraph.js'),
+        moduleDir
+    };
+}
+/** `codegraphUpstreamLayoutFor` for whichever install this process runs against. */
+export function resolveCodegraphUpstreamLayout() {
+    const require = createRequire(import.meta.url);
+    const packageJsonPath = require.resolve(`${CODEGRAPH_PACKAGE_NAME}/package.json`);
+    return codegraphUpstreamLayoutFor(packageJsonPath);
+}

package/dist/services/comments/citation-rules.d.ts

@@ -0,0 +1,154 @@
+/**
+ * What makes a backtick span a claim about this repository's file tree.
+ *
+ * These are the candidate rules, shared by the two readers of the same judgement:
+ * the comment classifier (`comment-hygiene.ts`) and, by literal, the repository's
+ * citation guard (`tests/unit/standards/repo-citation-integrity.test.ts`).
+ * `tests/unit/comments/citation-parity.test.ts` pins that the two spellings agree —
+ * a shape rule restated in a second place and then drifting is the defect this
+ * repository keeps documenting for itself.
+ *
+ * The rules are exclusions, and every one of them exists because of a measured
+ * false positive rather than a taste for tidiness. See `isCitationCandidate`.
+ */
+/** Backtick span that has at least one `/` — a path citation, not a mention. */
+export declare const PATH_SHAPED: RegExp;
+/** First segments that make a span repo-relative rather than document-relative. */
+export declare const REPO_ANCHORS: RegExp;
+/** `path.ts:14-17` — strip before judging; the FILE must exist, the line may move. */
+export declare const LINE_SUFFIX: RegExp;
+/**
+ * Session-runtime dirs. A path starting with one of these is a runtime artifact
+ * written under `.peaks/_runtime/<sessionId>/` and abbreviated in prose; it is
+ * not a repo file, and reporting it as missing is how a guard starts being
+ * ignored. Same exemption list the citation guard carries.
+ */
+export declare const SESSION_WORKSPACE_DIRS: Set<string>;
+/** `<placeholder>`, an ellipsis, a glob segment — illustrative, not asserted. */
+export declare const SYNTHETIC_SEGMENT: RegExp;
+/**
+ * A segment that is exactly an ASCII ellipsis names a path *family*
+ * (`src/...`, `openspec/changes/...`), not a file. `SYNTHETIC_SEGMENT` above
+ * catches the Unicode `…` and the glob `*`; this catches `...`, which its
+ * character class admits.
+ */
+export declare const ELLIPSIS_SEGMENT: RegExp;
+export declare const BARE_TEST_FILENAME_SHAPE: RegExp;
+/**
+ * Runtime state the CLI writes into a project. In a checkout of THIS repository
+ * these are absent by design — they are produced in the consuming project at run
+ * time — so a comment naming them makes no claim about this tree.
+ */
+export declare const RUNTIME_STATE_PREFIXES: readonly [".peaks/_runtime/", ".peaks/cron/", ".peaks/cache/", ".peaks/_dogfood/", ".peaks/_sub_agents/"];
+/**
+ * A file sitting flat in a project's `.peaks/` root is state the CLI writes there
+ * at run time — `.peaks/fork-state.json`, `.peaks/polyrepo.json`,
+ * `.peaks/role-registry.json`, `.peaks/.gitignore`, `.peaks/smoke-paths.json`.
+ *
+ * What this repository's own `.peaks/` commits is directories (`standards/`,
+ * `docs/`, `lint/`, `memory/`) plus four flat files, every one of which is
+ * present, so a citation to a tracked flat file resolves and this rule never fires
+ * for it. The shape is trusted over an entry list because an entry list has to
+ * grow with every runtime file the CLI adds — and the cost is stated: a future flat
+ * `.peaks/<file>` that is committed and later deleted would be hidden here.
+ * Repository convention is that top-level `.peaks/` entries are session or decision
+ * state, and a citation of that shape describes the consuming project.
+ */
+export declare const RUNTIME_STATE_ROOT_FILE: RegExp;
+/** Stems that name a shape rather than a file (`src/services/x/y.ts`, `foo.ts`). */
+export declare const SYNTHETIC_STEMS: Set<string>;
+/**
+ * Text that introduces a path as a shape to copy into the consumer's own
+ * repository, rather than a claim that this tree contains it.
+ */
+export declare const ILLUSTRATION_CUE: RegExp;
+/**
+ * A sentence that reasons about what a path *would* do, rather than reporting
+ * that a file is there.
+ *
+ * Two measured shapes, both read from the whole line because the cue sits on
+ * either side of the span:
+ *
+ *   - a matching rule illustrated with made-up operands —
+ *     `E.g. \`src/services/login\` should match \`src/services/login/handler.ts\``.
+ *     Neither path is in any repository; the line is about the glob semantics.
+ *     The `ILLUSTRATION_CUE` above cannot reach the second operand, because the
+ *     cue must sit immediately before the span to fire, and here it does not.
+ *   - a deliberate counterexample — `Written into \`.peaks/.gitignore\` they
+ *     resolved to \`…\` and \`…\` — matching nothing, in every project`. The comment
+ *     names two paths precisely because they match nothing; reporting them as
+ *     missing files asks the reader to fix a bug the text is describing.
+ *
+ * The list is modal phrases only, and the boundary is load-bearing: the real
+ * finding at `src/services/workspace/claude-settings-template.ts:90` asserts that a
+ * handler "invokes the shipped script" by path, uses no modal, and stays reported —
+ * the script is not in the tree. Bare `resolves to` was tried and dropped from the
+ * list for the opposite reason: it also appears in live assertions about files that
+ * DO exist, and a cue that clears those is a cue that hides debt.
+ *
+ * (This rule's own header was reported by the scan it documents — the sentence
+ * above quoted the missing script's path verbatim, and quoting a dead path in prose
+ * about a dead path is still a dead path. Cited by file and line now.)
+ */
+export declare const HYPOTHETICAL_CUE: RegExp;
+/**
+ * Documented runtime paths that are legitimately absent from a checkout. Each
+ * entry needs a reason; an allowlist without one is how a guard dies.
+ */
+export declare const OPTIONAL_RUNTIME_PATHS: Set<string>;
+/** One path-shaped backtick span, with the offsets that bound it in its line. */
+export type Citation = {
+    readonly span: string;
+    /** Offset of the opening backtick. */
+    readonly from: number;
+    /** Offset just past the closing backtick. */
+    readonly to: number;
+};
+/** What the candidate rule needs beyond the span itself. */
+export type CitationContext = {
+    /** Repo-relative path of the citing file or document. */
+    readonly file: string;
+    /** True when a repo-relative path is a directory in the working tree. */
+    readonly dirExists: (relDir: string) => boolean;
+};
+/**
+ * The second resolution origin, made explicit: an unanchored span is a SIBLING
+ * reference, so its parent directory must exist next to the citing file — and only
+ * there.
+ *
+ * The repo root is deliberately not an origin for an unanchored span: writing a
+ * repo-root path is exactly what the anchors are for. The walk is narrower than the
+ * citation guard's every-ancestor version, and the reason is measured: with every
+ * ancestor tried, `hooks/hooks.json` cited from
+ * `src/services/doctor/doctor-service/checks/` was adopted by `src/services/hooks/`
+ * four levels up, and `memory/index.json` by `src/services/memory/` — 16 findings
+ * of paths inside installed packages and under
+ * `.peaks/_runtime/<sessionId>/`, reported as missing repository files. A
+ * sibling-only reading loses nothing real: a deleted file cited by the directory it
+ * lived in still has that parent dir, and is still reported.
+ */
+export declare function isFileRelative(citation: string, ctx: CitationContext): boolean;
+/**
+ * Is this span a claim about the working tree at all?
+ *
+ * These are the candidate exclusions the repository's citation guard applies to
+ * markdown and to `scripts/` comments, transplanted to source comments —
+ * deliberately the SAME rules, not a second definition of "citation". Porting them
+ * was the answer to a measurement: 188 findings for roughly 20 real dead
+ * references, because a comment that gives a shape as an example (`a/b`,
+ * `pages/api`), names a path inside an installed package (`hooks/hooks.json`), or
+ * documents runtime state the CLI writes in the user's project
+ * (`.peaks/cron/schedule.json`) all read as "missing file" to a probe that only
+ * knows `exists`.
+ *
+ * The direction to preserve is the guard's stated invariant: these must never hide
+ * an ANCHORED citation. A path beginning `src/`, `tests/`, `docs/`, `skills/`,
+ * `scripts/`, `packages/` or `.peaks/` claims a location in this repository, and
+ * nothing below lets it through unread.
+ *
+ * `namesNoDirectory` is set only by the bare-`*.test.ts`-filename reading, whose own
+ * pattern has already established the filename shape: a filename names no
+ * directory, so it cannot satisfy `PATH_SHAPED`, and it has no parent directory to
+ * read as a sibling.
+ */
+export declare function isCitationCandidate(citation: Citation, line: string, ctx: CitationContext, namesNoDirectory?: boolean): boolean;

package/dist/services/comments/citation-rules.js

@@ -0,0 +1,241 @@
+/**
+ * What makes a backtick span a claim about this repository's file tree.
+ *
+ * These are the candidate rules, shared by the two readers of the same judgement:
+ * the comment classifier (`comment-hygiene.ts`) and, by literal, the repository's
+ * citation guard (`tests/unit/standards/repo-citation-integrity.test.ts`).
+ * `tests/unit/comments/citation-parity.test.ts` pins that the two spellings agree —
+ * a shape rule restated in a second place and then drifting is the defect this
+ * repository keeps documenting for itself.
+ *
+ * The rules are exclusions, and every one of them exists because of a measured
+ * false positive rather than a taste for tidiness. See `isCitationCandidate`.
+ */
+/** Backtick span that has at least one `/` — a path citation, not a mention. */
+export const PATH_SHAPED = /^[A-Za-z0-9_.@-]+(?:\/[A-Za-z0-9_.@-]+)+$/;
+/** First segments that make a span repo-relative rather than document-relative. */
+export const REPO_ANCHORS = /^(\.peaks|\.claude|\.github|src|tests|docs|scripts|skills|packages|bin|openspec|contracts)\//;
+/** `path.ts:14-17` — strip before judging; the FILE must exist, the line may move. */
+export const LINE_SUFFIX = /:\d+(?:-\d+)?$/;
+/**
+ * Session-runtime dirs. A path starting with one of these is a runtime artifact
+ * written under `.peaks/_runtime/<sessionId>/` and abbreviated in prose; it is
+ * not a repo file, and reporting it as missing is how a guard starts being
+ * ignored. Same exemption list the citation guard carries.
+ */
+export const SESSION_WORKSPACE_DIRS = new Set([
+    'prd',
+    'rd',
+    'qa',
+    'sc',
+    'txt',
+    'audit',
+    'ui',
+    'session',
+    'system'
+]);
+/** `<placeholder>`, an ellipsis, a glob segment — illustrative, not asserted. */
+export const SYNTHETIC_SEGMENT = /[<>*…]|etc\.$/;
+/**
+ * A segment that is exactly an ASCII ellipsis names a path *family*
+ * (`src/...`, `openspec/changes/...`), not a file. `SYNTHETIC_SEGMENT` above
+ * catches the Unicode `…` and the glob `*`; this catches `...`, which its
+ * character class admits.
+ */
+export const ELLIPSIS_SEGMENT = /(?:^|\/)\.\.\.(?:$|\/)/;
+/**
+ * The bare-`*.test.ts`-filename shape, written once. A filename carries no slash,
+ * so `PATH_SHAPED` cannot see it; this is the second shape a candidate claim can
+ * take, and the guard reads the same character classes.
+ */
+const BARE_FILENAME_NAME = String.raw `[A-Za-z0-9_][A-Za-z0-9_.-]*-[A-Za-z0-9_.-]*\.test\.ts`;
+export const BARE_TEST_FILENAME_SHAPE = new RegExp(`^${BARE_FILENAME_NAME}$`);
+/**
+ * Runtime state the CLI writes into a project. In a checkout of THIS repository
+ * these are absent by design — they are produced in the consuming project at run
+ * time — so a comment naming them makes no claim about this tree.
+ */
+export const RUNTIME_STATE_PREFIXES = [
+    '.peaks/_runtime/',
+    '.peaks/cron/',
+    '.peaks/cache/',
+    // Both are gitignored at the repository root and written per run: `_dogfood/` by
+    // the dogfood harness, `_sub_agents/` by `peaks sub-agent dispatch`.
+    '.peaks/_dogfood/',
+    '.peaks/_sub_agents/'
+];
+/**
+ * A file sitting flat in a project's `.peaks/` root is state the CLI writes there
+ * at run time — `.peaks/fork-state.json`, `.peaks/polyrepo.json`,
+ * `.peaks/role-registry.json`, `.peaks/.gitignore`, `.peaks/smoke-paths.json`.
+ *
+ * What this repository's own `.peaks/` commits is directories (`standards/`,
+ * `docs/`, `lint/`, `memory/`) plus four flat files, every one of which is
+ * present, so a citation to a tracked flat file resolves and this rule never fires
+ * for it. The shape is trusted over an entry list because an entry list has to
+ * grow with every runtime file the CLI adds — and the cost is stated: a future flat
+ * `.peaks/<file>` that is committed and later deleted would be hidden here.
+ * Repository convention is that top-level `.peaks/` entries are session or decision
+ * state, and a citation of that shape describes the consuming project.
+ */
+export const RUNTIME_STATE_ROOT_FILE = /^\.peaks\/[^/]+$/;
+/** Stems that name a shape rather than a file (`src/services/x/y.ts`, `foo.ts`). */
+export const SYNTHETIC_STEMS = new Set([
+    'x',
+    'y',
+    'z',
+    'foo',
+    'bar',
+    'baz',
+    'qux',
+    'example',
+    'sample',
+    'dummy',
+    'placeholder'
+]);
+/**
+ * Text that introduces a path as a shape to copy into the consumer's own
+ * repository, rather than a claim that this tree contains it.
+ */
+export const ILLUSTRATION_CUE = /(?:e\.g\.|i\.e\.|for example|such as|reference shape|Example:)\s*\(?\s*$/i;
+/**
+ * A sentence that reasons about what a path *would* do, rather than reporting
+ * that a file is there.
+ *
+ * Two measured shapes, both read from the whole line because the cue sits on
+ * either side of the span:
+ *
+ *   - a matching rule illustrated with made-up operands —
+ *     `E.g. \`src/services/login\` should match \`src/services/login/handler.ts\``.
+ *     Neither path is in any repository; the line is about the glob semantics.
+ *     The `ILLUSTRATION_CUE` above cannot reach the second operand, because the
+ *     cue must sit immediately before the span to fire, and here it does not.
+ *   - a deliberate counterexample — `Written into \`.peaks/.gitignore\` they
+ *     resolved to \`…\` and \`…\` — matching nothing, in every project`. The comment
+ *     names two paths precisely because they match nothing; reporting them as
+ *     missing files asks the reader to fix a bug the text is describing.
+ *
+ * The list is modal phrases only, and the boundary is load-bearing: the real
+ * finding at `src/services/workspace/claude-settings-template.ts:90` asserts that a
+ * handler "invokes the shipped script" by path, uses no modal, and stays reported —
+ * the script is not in the tree. Bare `resolves to` was tried and dropped from the
+ * list for the opposite reason: it also appears in live assertions about files that
+ * DO exist, and a cue that clears those is a cue that hides debt.
+ *
+ * (This rule's own header was reported by the scan it documents — the sentence
+ * above quoted the missing script's path verbatim, and quoting a dead path in prose
+ * about a dead path is still a dead path. Cited by file and line now.)
+ */
+export const HYPOTHETICAL_CUE = /\b(?:should match|would (?:match|resolve|be|land|fail)|matching nothing|matched nothing|resolved to|do(?:es)? not match|never matched|hypothetical|counterexample|in that case)\b/i;
+/**
+ * Documented runtime paths that are legitimately absent from a checkout. Each
+ * entry needs a reason; an allowlist without one is how a guard dies.
+ */
+export const OPTIONAL_RUNTIME_PATHS = new Set([
+    // Legacy fallback location of the active-skill marker; the canonical path is
+    // `.peaks/_runtime/active-skill.json`, so this dotfile is absent by design.
+    '.peaks/.active-skill.json',
+    // Legacy back-compat location of the session binding file, read by
+    // `peaks session` when the canonical `.peaks/_runtime/session.json` is gone.
+    '.peaks/.session.json'
+]);
+/**
+ * The second resolution origin, made explicit: an unanchored span is a SIBLING
+ * reference, so its parent directory must exist next to the citing file — and only
+ * there.
+ *
+ * The repo root is deliberately not an origin for an unanchored span: writing a
+ * repo-root path is exactly what the anchors are for. The walk is narrower than the
+ * citation guard's every-ancestor version, and the reason is measured: with every
+ * ancestor tried, `hooks/hooks.json` cited from
+ * `src/services/doctor/doctor-service/checks/` was adopted by `src/services/hooks/`
+ * four levels up, and `memory/index.json` by `src/services/memory/` — 16 findings
+ * of paths inside installed packages and under
+ * `.peaks/_runtime/<sessionId>/`, reported as missing repository files. A
+ * sibling-only reading loses nothing real: a deleted file cited by the directory it
+ * lived in still has that parent dir, and is still reported.
+ */
+export function isFileRelative(citation, ctx) {
+    const parent = citation.slice(0, citation.lastIndexOf('/'));
+    const cut = ctx.file.lastIndexOf('/');
+    if (cut === -1)
+        return false;
+    return ctx.dirExists(`${ctx.file.slice(0, cut)}/${parent}`);
+}
+/**
+ * Spans that name something outside this repository: a package, a GitHub Action,
+ * runtime state the CLI writes in the consuming project, a path *family*, or the
+ * `./` form a document uses for a project it is installed into.
+ */
+function namesSomethingElse(span) {
+    if (span.includes('@'))
+        return true; // npm package / GitHub-Action refs
+    if (RUNTIME_STATE_PREFIXES.some((prefix) => span.startsWith(prefix)))
+        return true;
+    if (RUNTIME_STATE_ROOT_FILE.test(span))
+        return true;
+    if (OPTIONAL_RUNTIME_PATHS.has(span))
+        return true;
+    if (ELLIPSIS_SEGMENT.test(span))
+        return true;
+    // A repo path in this tree is written from the repo root; `./x` is where the
+    // CONSUMING project must not put a file.
+    return span.startsWith('./');
+}
+/**
+ * Spans that are template text or an illustration rather than an assertion: wrapped
+ * in a `<…>` fill-in, introduced by an example cue, or built from stems that exist
+ * only to show a shape.
+ */
+function illustratesRatherThanAsserts(citation, line, span) {
+    const before = line.slice(0, citation.from);
+    const after = line.slice(citation.to);
+    // Inside a `<…>` fill-in the span is template text meant to be replaced.
+    if (before.lastIndexOf('<') > before.lastIndexOf('>') && after.includes('>'))
+        return true;
+    if (ILLUSTRATION_CUE.test(before))
+        return true;
+    const basename = span.slice(span.lastIndexOf('/') + 1);
+    const dot = basename.indexOf('.');
+    return SYNTHETIC_STEMS.has(dot === -1 ? basename : basename.slice(0, dot));
+}
+/**
+ * Is this span a claim about the working tree at all?
+ *
+ * These are the candidate exclusions the repository's citation guard applies to
+ * markdown and to `scripts/` comments, transplanted to source comments —
+ * deliberately the SAME rules, not a second definition of "citation". Porting them
+ * was the answer to a measurement: 188 findings for roughly 20 real dead
+ * references, because a comment that gives a shape as an example (`a/b`,
+ * `pages/api`), names a path inside an installed package (`hooks/hooks.json`), or
+ * documents runtime state the CLI writes in the user's project
+ * (`.peaks/cron/schedule.json`) all read as "missing file" to a probe that only
+ * knows `exists`.
+ *
+ * The direction to preserve is the guard's stated invariant: these must never hide
+ * an ANCHORED citation. A path beginning `src/`, `tests/`, `docs/`, `skills/`,
+ * `scripts/`, `packages/` or `.peaks/` claims a location in this repository, and
+ * nothing below lets it through unread.
+ *
+ * `namesNoDirectory` is set only by the bare-`*.test.ts`-filename reading, whose own
+ * pattern has already established the filename shape: a filename names no
+ * directory, so it cannot satisfy `PATH_SHAPED`, and it has no parent directory to
+ * read as a sibling.
+ */
+export function isCitationCandidate(citation, line, ctx, namesNoDirectory = false) {
+    const span = citation.span;
+    if (!(namesNoDirectory ? BARE_TEST_FILENAME_SHAPE.test(span) : PATH_SHAPED.test(span)))
+        return false;
+    if (namesSomethingElse(span))
+        return false;
+    if (illustratesRatherThanAsserts(citation, line, span))
+        return false;
+    // The line reasons about what a path would do; it does not claim one is there.
+    if (HYPOTHETICAL_CUE.test(line))
+        return false;
+    if (REPO_ANCHORS.test(span))
+        return true;
+    if (namesNoDirectory)
+        return true;
+    return isFileRelative(span, ctx);
+}

package/dist/services/comments/comment-audit.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Project-wide comment scan: what the classifier finds across the enforced scope.
+ *
+ * Scope follows the repository's existing lint boundary — `src` plus each
+ * workspace package's `src`, as `.husky/lint-scope.mjs` defines it — rather than
+ * a second definition of "product code" written here. Two names for one rule is
+ * the failure the parity test in `tests/unit/comments/citation-parity.test.ts`
+ * exists to prevent, and the parity that second name actually caused is pinned by
+ * `tests/unit/comments/comment-audit.test.ts`, which requires this walk to read the
+ * same number of files the artifact records the ratchet measuring.
+ *
+ * This is the read side only. Nothing here writes a file: the counts it produces
+ * are the numbers a ratchet would start from, and a ratchet seeded from a scan
+ * nobody has spot-checked is a gate that will be trained away the first time it
+ * refuses a legitimate change.
+ */
+import { type CommentFileSummary, type CommentFinding, type CommentFindingKind } from './comment-hygiene.js';
+/**
+ * Product-code directories, in report order: `src`, then every package under
+ * `packages/` that has a `src`.
+ *
+ * Derived from the rule rather than enumerated, because `.husky/lint-scope.mjs` says a
+ * new `packages/<anything>/src` joins the enforced scope BY EXISTING. The first version
+ * of this list spelled it `['src', 'packages/peaks-loop-mut/src']`, which was the second
+ * definition of "product code" this file's header claims not to be: the ratchet measures
+ * 953 files and the worklist read 926, so 14 gated narrative rows lived in three
+ * packages no `peaks comments audit` would show and no `prune` could clear.
+ */
+export declare function commentScanScope(projectRoot: string): string[];
+/**
+ * Every source file under one scope dir, repo-relative, sorted.
+ *
+ * The relative form is not cosmetic: `citationResolves` tries a citation with no
+ * repo anchor against the citing file's own directory and its ancestors, so an
+ * absolute path here turns every sibling reference into a false "missing file".
+ * `relative()` + separator normalisation is what keeps that resolution honest on
+ * a Windows host.
+ */
+export declare function scopeFiles(projectRoot: string, scopeDir: string): string[];
+export type CommentAuditResult = {
+    readonly scannedFiles: number;
+    /** Files the caller named. Equal to `scannedFiles` unless one was unreadable. */
+    readonly askedFiles: number;
+    readonly commentLines: number;
+    readonly deadReferences: number;
+    readonly narrative: number;
+    readonly files: readonly CommentFileSummary[];
+    readonly findings: readonly CommentFinding[];
+};
+export type CommentAuditOptions = {
+    readonly projectRoot: string;
+    /** Narrow to one category, the way the prune will be able to. */
+    readonly kind?: CommentFindingKind;
+    /** Cap the finding list; totals are never capped. */
+    readonly limit?: number;
+    /**
+     * Scan EXACTLY these repo-relative files instead of walking the scope dirs.
+     *
+     * A ratchet row must be measured over the population its callers agree to, and a
+     * walk is not a scope: the walk sees untracked files the index never heard of and
+     * misses tracked files the disk dropped, so a row measured over a walk can move
+     * while nobody edits source. `git ls-files` filtered by the published scope rule is
+     * that population — the same list the eslint, prettier and silent-warning legs
+     */
+    readonly files?: readonly string[];
+};
+/** Scan the enforced scope. Synchronous by design: it is a CLI read path. */
+export declare function auditComments(options: CommentAuditOptions): CommentAuditResult;

package/dist/services/comments/comment-audit.js

@@ -0,0 +1,121 @@
+/**
+ * Project-wide comment scan: what the classifier finds across the enforced scope.
+ *
+ * Scope follows the repository's existing lint boundary — `src` plus each
+ * workspace package's `src`, as `.husky/lint-scope.mjs` defines it — rather than
+ * a second definition of "product code" written here. Two names for one rule is
+ * the failure the parity test in `tests/unit/comments/citation-parity.test.ts`
+ * exists to prevent, and the parity that second name actually caused is pinned by
+ * `tests/unit/comments/comment-audit.test.ts`, which requires this walk to read the
+ * same number of files the artifact records the ratchet measuring.
+ *
+ * This is the read side only. Nothing here writes a file: the counts it produces
+ * are the numbers a ratchet would start from, and a ratchet seeded from a scan
+ * nobody has spot-checked is a gate that will be trained away the first time it
+ * refuses a legitimate change.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { scanComments, summarize } from './comment-hygiene.js';
+import { createFsProbe, createRepoProbe } from './repo-path-probe.js';
+/**
+ * Product-code directories, in report order: `src`, then every package under
+ * `packages/` that has a `src`.
+ *
+ * Derived from the rule rather than enumerated, because `.husky/lint-scope.mjs` says a
+ * new `packages/<anything>/src` joins the enforced scope BY EXISTING. The first version
+ * of this list spelled it `['src', 'packages/peaks-loop-mut/src']`, which was the second
+ * definition of "product code" this file's header claims not to be: the ratchet measures
+ * 953 files and the worklist read 926, so 14 gated narrative rows lived in three
+ * packages no `peaks comments audit` would show and no `prune` could clear.
+ */
+export function commentScanScope(projectRoot) {
+    const packagesDir = join(projectRoot, 'packages');
+    if (!existsSync(packagesDir))
+        return ['src'];
+    const names = readdirSync(packagesDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && existsSync(join(packagesDir, entry.name, 'src')))
+        .map((entry) => entry.name)
+        .sort();
+    return ['src', ...names.map((name) => join('packages', name, 'src'))];
+}
+const SOURCE_SUFFIXES = ['.ts', '.tsx', '.mts', '.cts'];
+function isSourceFile(name) {
+    return SOURCE_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+/**
+ * Every source file under one scope dir, repo-relative, sorted.
+ *
+ * The relative form is not cosmetic: `citationResolves` tries a citation with no
+ * repo anchor against the citing file's own directory and its ancestors, so an
+ * absolute path here turns every sibling reference into a false "missing file".
+ * `relative()` + separator normalisation is what keeps that resolution honest on
+ * a Windows host.
+ */
+export function scopeFiles(projectRoot, scopeDir) {
+    const root = resolve(projectRoot, scopeDir);
+    const base = resolve(projectRoot);
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    const walk = (absDir) => {
+        for (const entry of readdirSync(absDir, { withFileTypes: true })) {
+            const abs = join(absDir, entry.name);
+            if (entry.isDirectory()) {
+                walk(abs);
+            }
+            else if (isSourceFile(entry.name)) {
+                out.push(relative(base, abs).replace(/\\/g, '/'));
+            }
+        }
+    };
+    walk(root);
+    return out.sort();
+}
+function totalOf(files, key) {
+    return files.reduce((sum, file) => sum + file[key], 0);
+}
+/** Scan the enforced scope. Synchronous by design: it is a CLI read path. */
+export function auditComments(options) {
+    const { projectRoot } = options;
+    const exists = createRepoProbe(projectRoot);
+    const installed = createFsProbe(projectRoot);
+    const kinds = options.kind === undefined ? undefined : [options.kind];
+    const population = options.files ?? scopePopulation(projectRoot);
+    const findings = [];
+    const summaries = [];
+    // Files actually READ, not files handed in. A tracked path the disk no longer
+    // carries has to show up as `scanned < asked`, which is how a leg refuses instead
+    // of printing a count measured over a population nobody agreed to.
+    let scanned = 0;
+    for (const file of population) {
+        if (!existsSync(resolve(projectRoot, file)))
+            continue;
+        scanned += 1;
+        const source = readFileSync(resolve(projectRoot, file), 'utf8');
+        const input = { file, source };
+        const found = scanComments(input, {
+            exists,
+            installed,
+            ...(kinds === undefined ? {} : { kinds })
+        });
+        if (found.length === 0)
+            continue;
+        summaries.push(summarize(input, found));
+        findings.push(...found);
+    }
+    const capped = options.limit === undefined ? findings : findings.slice(0, options.limit);
+    return {
+        scannedFiles: scanned,
+        askedFiles: population.length,
+        commentLines: summaries.reduce((n, file) => n + file.commentLines, 0),
+        deadReferences: totalOf(summaries, 'deadReferences'),
+        narrative: totalOf(summaries, 'narrative'),
+        files: summaries.sort((a, b) => b.deadReferences + b.narrative - (a.deadReferences + a.narrative)),
+        findings: capped
+    };
+}
+/** The walked population, used only when a caller did not hand an explicit list. */
+function scopePopulation(projectRoot) {
+    return commentScanScope(projectRoot).flatMap((scopeDir) => scopeFiles(projectRoot, scopeDir));
+}