peaks-loop 4.0.54 → 4.1.1

package/dist/services/codegraph/codegraph-autorefresh.js

@@ -55,7 +55,7 @@
 // build), not `init`.
 import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { CODEGRAPH_DIR_NAME, CODEGRAPH_MARKER_NAME, createCodegraphInvocation, executeCodegraphInvocation, isCodegraphInitialized, } from './codegraph-service.js';
+import { CODEGRAPH_DIR_NAME, CODEGRAPH_MARKER_NAME, createCodegraphInvocation, executeCodegraphInvocation, isCodegraphInitialized } from './codegraph-service.js';
 import { repairCodegraphExcludeFromProject } from './codegraph-exclude-repair.js';
 /**
  * The operator-facing line for a refresh that did not happen, or `null` when
@@ -115,6 +115,50 @@ function firstMeaningfulLine(text) {
     const first = trimmed.split(/\r?\n/)[0];
     return first !== undefined ? first.slice(0, 200) : 'no upstream output';
 }
+/**
+ * Self-heal a `.codegraph/` dir that exists without a `codegraph.db`
+ * (extracted verbatim from `refreshCodegraphAfterSlice` to clear the
+ * `max-lines-per-function` arm; behavior unchanged). Returns a terminal
+ * result when the refresh must stop, `null` when the caller may proceed
+ * to the index step.
+ */
+async function selfHealUninitializedCodegraph(projectRoot, runner) {
+    // A `.codegraph/` dir without a `codegraph.db` is uninitialized:
+    //   - NOT peaks-loop-managed → foreign schema, never touch it.
+    //   - peaks-loop-managed → the dangling state left by the pre-fix
+    //     rid-CG-001 auto-stake (marker stamped, no upstream init). Run
+    //     init (fast, offline-safe — no full index) so the subsequent
+    //     index has a schema to write into.
+    if (!isCodegraphInitialized(projectRoot)) {
+        if (!isCodegraphPeaksLoopManaged(projectRoot)) {
+            return {
+                refreshed: false,
+                reason: 'no-codegraph-dir',
+                note: `auto codegraph refresh skipped: ${CODEGRAPH_DIR_NAME}/ exists without a codegraph.db and is not peaks-loop-managed. Run \`peaks codegraph init\` once to enable post-slice auto-refresh.`
+            };
+        }
+        const initResult = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'init', project: projectRoot }), runner);
+        if (initResult.exitCode !== 0) {
+            return {
+                refreshed: false,
+                reason: 'index-failed',
+                note: `auto codegraph refresh self-heal init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}. ${REFRESH_REMEDY}`
+            };
+        }
+        // That init just wrote upstream's 99-rule default `exclude`
+        // template, some of which block tracked source files — the same
+        // self-heal the CLI's `peaks codegraph init` performs, via the
+        // same shared helper. Skipped, this path would stamp the
+        // peaks-loop marker over an incomplete index that no later
+        // `init` (it would no-op) could ever repair.
+        //
+        // Never throws (the helper catches everything), and
+        // `reindex: false` because the index call below covers the
+        // recovered files.
+        await repairCodegraphExcludeFromProject(projectRoot, runner, { reindex: false });
+    }
+    return null;
+}
 /**
  * Run a best-effort `codegraph index` refresh for `projectRoot` after a
  * slice-complete boundary. NEVER throws — every failure path returns a
@@ -128,51 +172,24 @@ export async function refreshCodegraphAfterSlice(projectRoot, runner) {
         return {
             refreshed: false,
             reason: 'no-codegraph-dir',
-            note: `auto codegraph refresh skipped: no ${CODEGRAPH_DIR_NAME} directory at ${join(projectRoot, CODEGRAPH_DIR_NAME)}. Run \`peaks codegraph init\` once to enable post-slice auto-refresh.`,
+            note: `auto codegraph refresh skipped: no ${CODEGRAPH_DIR_NAME} directory at ${join(projectRoot, CODEGRAPH_DIR_NAME)}. Run \`peaks codegraph init\` once to enable post-slice auto-refresh.`
         };
     }
     try {
-        // A `.codegraph/` dir without a `codegraph.db` is uninitialized:
-        //   - NOT peaks-loop-managed → foreign schema, never touch it.
-        //   - peaks-loop-managed → the dangling state left by the pre-fix
-        //     rid-CG-001 auto-stake (marker stamped, no upstream init). Run
-        //     init (fast, offline-safe — no full index) so the subsequent
-        //     index has a schema to write into.
-        if (!isCodegraphInitialized(projectRoot)) {
-            if (!isCodegraphPeaksLoopManaged(projectRoot)) {
-                return {
-                    refreshed: false,
-                    reason: 'no-codegraph-dir',
-                    note: `auto codegraph refresh skipped: ${CODEGRAPH_DIR_NAME}/ exists without a codegraph.db and is not peaks-loop-managed. Run \`peaks codegraph init\` once to enable post-slice auto-refresh.`,
-                };
-            }
-            const initResult = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'init', project: projectRoot }), runner);
-            if (initResult.exitCode !== 0) {
-                return {
-                    refreshed: false,
-                    reason: 'index-failed',
-                    note: `auto codegraph refresh self-heal init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}. ${REFRESH_REMEDY}`,
-                };
-            }
-            // That init just wrote upstream's 99-rule default `exclude`
-            // template, some of which block tracked source files — the same
-            // self-heal the CLI's `peaks codegraph init` performs, via the
-            // same shared helper. Skipped, this path would stamp the
-            // peaks-loop marker over an incomplete index that no later
-            // `init` (it would no-op) could ever repair.
-            //
-            // Never throws (the helper catches everything), and
-            // `reindex: false` because the index call below covers the
-            // recovered files.
-            await repairCodegraphExcludeFromProject(projectRoot, runner, { reindex: false });
-        }
-        const invocation = createCodegraphInvocation({ subcommand: 'index', project: projectRoot, quiet: true });
+        const selfHeal = await selfHealUninitializedCodegraph(projectRoot, runner);
+        if (selfHeal !== null)
+            return selfHeal;
+        const invocation = createCodegraphInvocation({
+            subcommand: 'index',
+            project: projectRoot,
+            quiet: true
+        });
         const result = await executeCodegraphInvocation(invocation, runner);
         if (result.exitCode !== 0) {
             return {
                 refreshed: false,
                 reason: 'index-failed',
-                note: `auto codegraph refresh failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}. ${REFRESH_REMEDY}`,
+                note: `auto codegraph refresh failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}. ${REFRESH_REMEDY}`
             };
         }
         return { refreshed: true };
@@ -181,7 +198,7 @@ export async function refreshCodegraphAfterSlice(projectRoot, runner) {
         return {
             refreshed: false,
             reason: 'unavailable',
-            note: `auto codegraph refresh unavailable: ${errorMessage(error)}. ${REFRESH_REMEDY}`,
+            note: `auto codegraph refresh unavailable: ${errorMessage(error)}. ${REFRESH_REMEDY}`
         };
     }
 }

package/dist/services/codegraph/codegraph-config-repair-writer.js

@@ -314,7 +314,10 @@ export function applyCodegraphConfigRepair(projectRoot, repair) {
     // is how a wrong `include` would survive a repair that reported success.
     const include = record.include === undefined ? [] : assertStringArray(record.include, 'include', configPath);
     const excludePlan = repairCodegraphExclude({ exclude, rulesToRemove: repair.rulesToRemove });
-    const includePlan = repairCodegraphInclude({ include, patternsToAdd: repair.includePatternsToAdd });
+    const includePlan = repairCodegraphInclude({
+        include,
+        patternsToAdd: repair.includePatternsToAdd
+    });
     if (!excludePlan.changed && !includePlan.changed) {
         return {
             applied: false,

package/dist/services/codegraph/codegraph-exclude-integrity.js

@@ -84,7 +84,10 @@ export function inspectCodegraphExcludeIntegrity(projectRoot, inputs = {}) {
         excludedTrackedCount: result.excludedTrackedCount,
         violations: result.violations,
         rulesToRemove: result.rulesToRemove,
-        ruleImpacts: result.rulesToRemove.map((rule) => ({ rule, blockedCount: blockedCounts.get(rule) ?? 0 }))
+        ruleImpacts: result.rulesToRemove.map((rule) => ({
+            rule,
+            blockedCount: blockedCounts.get(rule) ?? 0
+        }))
     };
 }
 /**

package/dist/services/codegraph/codegraph-exclude-repair.js

@@ -210,8 +210,7 @@ export async function repairCodegraphExcludeFromProject(projectRoot, runner, opt
     // pass runs only on the one run per project that actually widens
     // `include`, where a repair is about to spend seconds rebuilding an index.
     const includeFilesRecovered = includePlan.changed
-        ? includeAdmittedAfter -
-            filterAdmittedTrackedFiles(trackedFiles, config.include).length
+        ? includeAdmittedAfter - filterAdmittedTrackedFiles(trackedFiles, config.include).length
         : 0;
     const nothingToRepair = includePlan.addedPatterns.length === 0 && reconcile.rulesToRemove.length === 0;
     const unchanged = {

package/dist/services/codegraph/codegraph-index-integrity.js

@@ -135,7 +135,7 @@ export const CODEGRAPH_REPAIR_INDEX_COMMAND = 'peaks codegraph repair-index --pr
 export const CODEGRAPH_INDEX_STRICT_ENV_VAR = 'PEAKS_CODEGRAPH_INDEX_STRICT';
 /** True when the project opted in to blocking index-gap verdicts. */
 export function isCodegraphIndexStrictMode(env = process.env) {
-    return env[CODEGRAPH_INDEX_STRICT_ENV_VAR] === '1' || env[CODEGRAPH_INDEX_STRICT_ENV_VAR] === 'true';
+    return (env[CODEGRAPH_INDEX_STRICT_ENV_VAR] === '1' || env[CODEGRAPH_INDEX_STRICT_ENV_VAR] === 'true');
 }
 /**
  * Fold the inspected report (null when there is no index to inspect) and

package/dist/services/codegraph/codegraph-preflight-service.d.ts

@@ -1,30 +1,7 @@
 import { type CodegraphProcessRunner } from './codegraph-service.js';
-export type CodegraphPreflightResult = {
-    available: true;
-    block: string;
-    fileCount: number;
-    truncated: boolean;
-} | {
-    available: false;
-    note: string;
-};
-/** Cap for the directory histogram in the rendered structure block. */
-export declare const CODEGRAPH_STRUCTURE_MAX_DIRS = 40;
-/** Cap for bare root files listed in the rendered structure block. */
-export declare const CODEGRAPH_STRUCTURE_MAX_ROOT_FILES = 12;
-export interface CodegraphStructureFileEntry {
-    readonly path: string;
-}
-export interface CodegraphStructureRenderOptions {
-    readonly maxDirs?: number;
-    readonly maxRootFiles?: number;
-}
-export interface CodegraphStructureSummary {
-    /** Full `## Codegraph structure` markdown block, ending on its own paragraph. */
-    block: string;
-    total: number;
-    truncated: boolean;
-}
+import { type CodegraphPreflightResult, type CodegraphStructureFileEntry, type CodegraphStructureRenderOptions, type CodegraphStructureSummary } from './codegraph-preflight-structure.js';
+export { CODEGRAPH_STRUCTURE_MAX_DIRS, CODEGRAPH_STRUCTURE_MAX_ROOT_FILES } from './codegraph-preflight-structure.js';
+export type { CodegraphPreflightResult, CodegraphStructureFileEntry, CodegraphStructureRenderOptions, CodegraphStructureSummary } from './codegraph-preflight-structure.js';
 /**
  * Pure renderer: turn the codegraph `files --json` payload into a bounded
  * `## Codegraph structure` block. Files are aggregated into a directory

package/dist/services/codegraph/codegraph-preflight-service.js

@@ -31,17 +31,11 @@
 //   - CODEGRAPH_STRUCTURE_MAX_DIRS        = 40  directory rows
 //   - CODEGRAPH_STRUCTURE_MAX_ROOT_FILES  = 12  bare root files
 import { mkdirSync } from 'node:fs';
-import { CODEGRAPH_DIR_NAME, createCodegraphInvocation, defaultCodegraphInitGuard, executeCodegraphInvocation, isCodegraphInitialized, writeCodegraphMarker, } from './codegraph-service.js';
+import { CODEGRAPH_DIR_NAME, createCodegraphInvocation, defaultCodegraphInitGuard, executeCodegraphInvocation, isCodegraphInitialized, writeCodegraphMarker } from './codegraph-service.js';
 import { defaultCodegraphProcessRunner } from './codegraph-process-runner.js';
 import { repairCodegraphExcludeFromProject } from './codegraph-exclude-repair.js';
-/** Cap for the directory histogram in the rendered structure block. */
-export const CODEGRAPH_STRUCTURE_MAX_DIRS = 40;
-/** Cap for bare root files listed in the rendered structure block. */
-export const CODEGRAPH_STRUCTURE_MAX_ROOT_FILES = 12;
-/** Strip a leading `./` (upstream codegraph paths may carry it). */
-function normalizeCodegraphPath(path) {
-    return path.startsWith('./') ? path.slice(2) : path;
-}
+import { CODEGRAPH_STRUCTURE_MAX_DIRS, CODEGRAPH_STRUCTURE_MAX_ROOT_FILES, normalizeCodegraphPath, parseFilesPayload } from './codegraph-preflight-structure.js';
+export { CODEGRAPH_STRUCTURE_MAX_DIRS, CODEGRAPH_STRUCTURE_MAX_ROOT_FILES } from './codegraph-preflight-structure.js';
 /**
  * Pure renderer: turn the codegraph `files --json` payload into a bounded
  * `## Codegraph structure` block. Files are aggregated into a directory
@@ -69,8 +63,7 @@ export function renderCodegraphStructureBlock(files, options = {}) {
         const dir = raw.slice(0, slash);
         dirCounts.set(dir, (dirCounts.get(dir) ?? 0) + 1);
     }
-    const sortedDirs = [...dirCounts.entries()]
-        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    const sortedDirs = [...dirCounts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
     const shownDirs = sortedDirs.slice(0, maxDirs);
     const truncatedDirs = sortedDirs.length > maxDirs;
     const sortedRoot = [...rootFiles].sort((a, b) => a.localeCompare(b));
@@ -102,28 +95,14 @@ function firstMeaningfulLine(text) {
     const first = trimmed.split(/\r?\n/)[0];
     return first !== undefined ? first.slice(0, 200) : 'no upstream output';
 }
-function parseFilesPayload(stdout) {
-    try {
-        const parsed = JSON.parse(stdout);
-        if (Array.isArray(parsed)) {
-            const entries = parsed
-                .filter((entry) => typeof entry === 'object' && entry !== null && 'path' in entry)
-                .map((entry) => ({ path: typeof entry.path === 'string' ? entry.path : '' }))
-                .filter((entry) => entry.path.length > 0);
-            return { ok: true, entries };
-        }
-        // JSON but not an array — not the shape we expect.
-        return { ok: false, entries: [] };
-    }
-    catch {
-        // Not JSON at all — e.g. the upstream text path ("No files indexed…").
-        return { ok: false, entries: [] };
-    }
-}
 async function readStructure(projectRoot, runner) {
     let result;
     try {
-        const invocation = createCodegraphInvocation({ subcommand: 'files', project: projectRoot, json: true });
+        const invocation = createCodegraphInvocation({
+            subcommand: 'files',
+            project: projectRoot,
+            json: true
+        });
         result = await executeCodegraphInvocation(invocation, runner);
     }
     catch (error) {
@@ -132,20 +111,20 @@ async function readStructure(projectRoot, runner) {
     if (result.exitCode !== 0) {
         return {
             available: false,
-            note: `codegraph files failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}`,
+            note: `codegraph files failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}`
         };
     }
     const { ok, entries } = parseFilesPayload(result.stdout);
     if (!ok) {
         return {
             available: false,
-            note: 'codegraph files returned no parseable structure — run `peaks codegraph index` before dispatch for symbol-accurate structure.',
+            note: 'codegraph files returned no parseable structure — run `peaks codegraph index` before dispatch for symbol-accurate structure.'
         };
     }
     if (entries.length === 0) {
         return {
             available: false,
-            note: 'codegraph index has no files — run `peaks codegraph index` before dispatch for symbol-accurate structure.',
+            note: 'codegraph index has no files — run `peaks codegraph index` before dispatch for symbol-accurate structure.'
         };
     }
     const summary = renderCodegraphStructureBlock(entries);
@@ -153,7 +132,7 @@ async function readStructure(projectRoot, runner) {
         available: true,
         block: summary.block,
         fileCount: summary.total,
-        truncated: summary.truncated,
+        truncated: summary.truncated
     };
 }
 /**
@@ -181,7 +160,7 @@ export async function buildCodegraphPreflightBlock(projectRoot, runner) {
     if (guard.status === 'conflict-foreign-schema') {
         return {
             available: false,
-            note: `codegraph unavailable: ${CODEGRAPH_DIR_NAME}/ exists with a non-peaks-loop schema and was not touched. Move or rename the foreign directory, then re-run \`peaks codegraph init\` to enable pre-dispatch structure reads.`,
+            note: `codegraph unavailable: ${CODEGRAPH_DIR_NAME}/ exists with a non-peaks-loop schema and was not touched. Move or rename the foreign directory, then re-run \`peaks codegraph init\` to enable pre-dispatch structure reads.`
         };
     }
     // 'fresh' (no dir) OR a dangling peaks-loop dir (marker present, no
@@ -196,7 +175,7 @@ export async function buildCodegraphPreflightBlock(projectRoot, runner) {
             if (initResult.exitCode !== 0) {
                 return {
                     available: false,
-                    note: `codegraph init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}`,
+                    note: `codegraph init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}`
                 };
             }
             try {
@@ -230,7 +209,7 @@ export async function buildCodegraphPreflightBlock(projectRoot, runner) {
             if (indexResult.exitCode !== 0) {
                 return {
                     available: false,
-                    note: `codegraph index failed (exit ${String(indexResult.exitCode)}): ${firstMeaningfulLine(indexResult.stderr || indexResult.stdout)}`,
+                    note: `codegraph index failed (exit ${String(indexResult.exitCode)}): ${firstMeaningfulLine(indexResult.stderr || indexResult.stdout)}`
                 };
             }
         }

package/dist/services/codegraph/codegraph-preflight-structure.d.ts

@@ -0,0 +1,32 @@
+export type CodegraphPreflightResult = {
+    available: true;
+    block: string;
+    fileCount: number;
+    truncated: boolean;
+} | {
+    available: false;
+    note: string;
+};
+/** Cap for the directory histogram in the rendered structure block. */
+export declare const CODEGRAPH_STRUCTURE_MAX_DIRS = 40;
+/** Cap for bare root files listed in the rendered structure block. */
+export declare const CODEGRAPH_STRUCTURE_MAX_ROOT_FILES = 12;
+export interface CodegraphStructureFileEntry {
+    readonly path: string;
+}
+export interface CodegraphStructureRenderOptions {
+    readonly maxDirs?: number;
+    readonly maxRootFiles?: number;
+}
+export interface CodegraphStructureSummary {
+    /** Full `## Codegraph structure` markdown block, ending on its own paragraph. */
+    block: string;
+    total: number;
+    truncated: boolean;
+}
+/** Strip a leading `./` (upstream codegraph paths may carry it). */
+export declare function normalizeCodegraphPath(path: string): string;
+export declare function parseFilesPayload(stdout: string): {
+    ok: boolean;
+    entries: CodegraphStructureFileEntry[];
+};

package/dist/services/codegraph/codegraph-preflight-structure.js

@@ -0,0 +1,33 @@
+// src/services/codegraph/codegraph-preflight-structure.ts
+//
+// The declaration + payload-parsing surface of the pre-dispatch codegraph
+// preflight (`codegraph-preflight-service.ts`), extracted so the service
+// module stays under the repo file-size cap. `codegraph-preflight-service.ts`
+// imports these and re-exports the public ones, so importers keep resolving
+// every name from the original path.
+/** Cap for the directory histogram in the rendered structure block. */
+export const CODEGRAPH_STRUCTURE_MAX_DIRS = 40;
+/** Cap for bare root files listed in the rendered structure block. */
+export const CODEGRAPH_STRUCTURE_MAX_ROOT_FILES = 12;
+/** Strip a leading `./` (upstream codegraph paths may carry it). */
+export function normalizeCodegraphPath(path) {
+    return path.startsWith('./') ? path.slice(2) : path;
+}
+export function parseFilesPayload(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        if (Array.isArray(parsed)) {
+            const entries = parsed
+                .filter((entry) => typeof entry === 'object' && entry !== null && 'path' in entry)
+                .map((entry) => ({ path: typeof entry.path === 'string' ? entry.path : '' }))
+                .filter((entry) => entry.path.length > 0);
+            return { ok: true, entries };
+        }
+        // JSON but not an array — not the shape we expect.
+        return { ok: false, entries: [] };
+    }
+    catch {
+        // Not JSON at all — e.g. the upstream text path ("No files indexed…").
+        return { ok: false, entries: [] };
+    }
+}

package/dist/services/codegraph/codegraph-process-runner.js

@@ -3,7 +3,18 @@ import { join } from 'node:path';
 const CODEGRAPH_PROCESS_TIMEOUT_MS = 600_000;
 const CODEGRAPH_OUTPUT_LIMIT_BYTES = 10 * 1024 * 1024;
 function createCodegraphEnvironment(sourceEnv = process.env) {
-    const preservedKeys = ['PATH', 'Path', 'HOME', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'TEMP', 'TMP', 'SystemRoot', 'WINDIR'];
+    const preservedKeys = [
+        'PATH',
+        'Path',
+        'HOME',
+        'USERPROFILE',
+        'APPDATA',
+        'LOCALAPPDATA',
+        'TEMP',
+        'TMP',
+        'SystemRoot',
+        'WINDIR'
+    ];
     const environment = {};
     for (const key of preservedKeys) {
         const value = sourceEnv[key];

package/dist/services/codegraph/codegraph-service.js

@@ -9,7 +9,15 @@ const CODEGRAPH_PACKAGE_VERSION = '0.7.10';
 const CODEGRAPH_EXECUTABLE = process.execPath;
 const CODEGRAPH_BINARY_PATH = resolveCodegraphBinaryPath();
 const POSITIONAL_ARGUMENT_PREFIX = '-';
-const ALLOWED_SUBCOMMANDS = ['status', 'init', 'index', 'query', 'files', 'context', 'affected'];
+const ALLOWED_SUBCOMMANDS = [
+    'status',
+    'init',
+    'index',
+    'query',
+    'files',
+    'context',
+    'affected'
+];
 const NUMERIC_FLAG_NAMES = ['limit', 'maxDepth'];
 const COMMON_OPTION_KEYS = ['subcommand', 'project'];
 const ALLOWED_OPTIONS_BY_SUBCOMMAND = {

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;