llmnav 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ The npm package follows Semantic Versioning. The `llmnav/N` source protocol is v
 
 ## [Unreleased]
 
+## [0.6.0] — 2026-08-10
+
+### Added
+
+* Added semantic boundaries for configuration, source discovery and formatting, project scanning, declaration extraction, diagnostics, ID lifecycle, and the public protocol specification, with targeted coverage and retrieval regression queries.
+* Added a deterministic, read-only `audit` command and public API that ranks likely missing module boundaries, explains every signal, suggests narrow coverage rules, and supports opt-in CI thresholds.
+* Added generated agent guidance and an `llmnav:audit` package script so new repositories review coverage after initialization and structural changes.
+
+### Fixed
+
+* Suppressed declaration files and reduced false positives from tests, fixtures, benchmarks, broad utilities, and re-export barrels.
+
 ## [0.5.2] — 2026-08-09
 
 ### Fixed

package/README.md

@@ -6,7 +6,7 @@ It adds compact, stable metadata to a small number of architectural and behavior
 
 LLMNav is not a documentation generator, an embedding database, or a reason to annotate every function. It is a zero-runtime-dependency Node.js CLI and ESM library for reducing broad repository scans, irrelevant context, stale hand-written links, repeated card tokenization, and avoidable cache invalidation.
 
-## What v0.5 provides
+## What v0.6 provides
 
 * The backward-compatible `llmnav/1` source comment specification
 * A parser and data-loss-resistant canonical formatter
@@ -31,6 +31,7 @@ LLMNav is not a documentation generator, an embedding database, or a reason to a
 * Multilingual alias routing and CJK n-gram retrieval
 * Search regression tests with Recall@1, Recall@5, and MRR
 * Managed instructions for AGENTS.md, Claude Code, GitHub Copilot, and Cursor
+* A deterministic, read-only annotation coverage audit with explicit CI thresholds
 * Linux and Windows CI gates plus npm pack installation smoke tests
 
 The package supports Node.js 22 or newer, uses ESM, performs no network requests, and has no runtime dependencies.
@@ -44,6 +45,8 @@ npx llmnav init --agents all --package-scripts
 
 Initialization is explicit. LLMNav never edits a consumer repository from an npm `postinstall` script. Use `--agents none` when only the machine-readable control directory is desired.
 
+Before writing cards, run `npx llmnav audit`. It ranks likely architectural boundaries and explains each score. The command never edits source and remains advisory unless `--fail-on high`, `medium`, or `low` is selected. Review the candidates: a high score is evidence to inspect a file, not permission to generate semantic meaning automatically.
+
 ## Add the first card
 
 ```ts
@@ -166,6 +169,7 @@ Line-comment cards require an explicit terminator and work with `//`, `#`, and `
 | Command | Purpose |
 | --- | --- |
 | `llmnav init` | Create configuration, registry, schemas, agent instructions, and the initial cache |
+| `llmnav audit` | Rank unannotated architectural boundary candidates without modifying source |
 | `llmnav check` | Validate cards, relations, coverage rules, and registry state |
 | `llmnav format` | Rewrite safe cards into canonical order and spacing |
 | `llmnav generate` | Incrementally compile and transactionally commit generated artifacts |
@@ -246,7 +250,7 @@ Do not annotate trivial getters, generated files, obvious wrappers, every test f
 
 ## Current implementation boundary
 
-Version 0.5 adds stable provider-neutral agent tools, trusted-root operation dispatch, explicit prompt-prefix cache partitions, deterministic editor diagnostics, a VS Code task integration, and a runnable typed host example to the repository graph and incremental navigation layers.
+Version 0.6 adds a deterministic coverage audit that prioritizes public entrypoints, structural boundaries, and high fan-in modules while suppressing declaration files, test support code, simple barrels, and broad utilities. It suggests narrow coverage rules but never writes cards or invents semantic roles.
 
 LLMNav does not discover sibling repositories automatically and does not ship an MCP server, embedding database, hosted service, SCIP generator, or complete language-aware call graph. External tools may export the documented compact graph-input schema. Generated structure never writes derived edges into source cards.
 
@@ -287,7 +291,7 @@ The project uses the Node.js standard library and built-in test runner. There is
 
 ## Status
 
-LLMNav is an experimental protocol and a usable v0.5 CLI. The source format remains `llmnav/1`; npm package changes and source-grammar changes are versioned independently.
+LLMNav is an experimental protocol and a usable v0.6 CLI. The source format remains `llmnav/1`; npm package changes and source-grammar changes are versioned independently.
 
 ## License
 

package/ROADMAP.md

@@ -62,6 +62,17 @@ Implemented:
 * editor integrations and diagnostics
 * provider-neutral integration examples
 
+## 0.6 — annotation coverage audit
+
+Implemented:
+
+* deterministic read-only discovery of unannotated architectural boundary candidates
+* explainable priority signals for package entrypoints, public APIs, structural boundaries, fan-in, exports, and source size
+* false-positive penalties for declaration files, test support code, broad utilities, and re-export barrels
+* opt-in `--fail-on high|medium|low` CI enforcement
+* path-specific coverage-rule suggestions without automatic source annotation
+* audit guidance in generated agent instructions and package scripts
+
 ## 1.0 criteria
 
 The source grammar and generated formats will be declared stable only after use across multiple TypeScript, Go, Rust, Python, and mixed-language repositories. A 1.0 release requires migration tooling, documented compatibility guarantees, benchmark fixtures with published methodology, sustained Windows and Linux verification, and no unresolved high-severity parser or transaction ambiguity.

package/docs/agent-integration.md

@@ -44,8 +44,10 @@ The generated instruction tells an agent to:
 5. Keep IDs stable across moves and renames.
 6. Update semantic fields only when meaning changes.
 7. Never hand-maintain call, import, reference, implementation, export, or override relations.
-8. Run format, check, and generation after semantic changes.
-9. Fall back to broad search when no credible card is returned.
+8. Run `llmnav audit` after initialization and structural boundary changes, review high and medium candidates, and never annotate automatically.
+9. Encode accepted boundaries in narrow coverage rules and retrieval queries.
+10. Run format, check, and generation after semantic changes.
+11. Fall back to broad search when no credible card is returned.
 
 When a host supports structured tool calls, `llmnav tools --json` returns four stable provider-neutral definitions in fixed order: `llmnav_query`, `llmnav_show`, `llmnav_context`, and `llmnav_check`. The schemas reject unknown fields and omit the repository root so the trusted host binds scope outside model-generated input.
 
@@ -112,3 +114,5 @@ An agent should not stop when a repository is partially annotated.
 When `query` returns no credible result, the correct fallback is normal symbol search, grep, or language-server navigation. After completing the task, the agent may propose a new card only when the missed boundary satisfies the repository's annotation policy.
 
 Search failure alone is not permission to annotate every function sharing a keyword.
+
+Audit priority is also not permission to invent a card. It is a deterministic prompt to inspect likely boundaries; durable ownership and invariants still come from the current source and repository contracts.

package/docs/api.md

@@ -62,6 +62,21 @@ Stat hints are an optimization, not deterministic output. The returned `fileStat
 
 Attached symbol declarations expose generated `language`, `exported`, `visibility`, optional Go `receiver`, `endOffset`, and declaration `bodyHash` fields. Indexed cards also expose sorted route, event, schema, migration, and command `boundaries` with confidence and evidence.
 
+## Audit annotation coverage
+
+```js
+import { auditHasFindings, auditProject } from "llmnav";
+
+const result = await auditProject(process.cwd());
+for (const candidate of result.candidates) {
+  console.log(candidate.priority, candidate.path, candidate.reasons);
+}
+
+if (auditHasFindings(result, "high")) process.exitCode = 1;
+```
+
+`auditProject` is read-only and returns schemaVersion 1 data with repository-relative paths and deterministic ordering. Candidate signals are structural heuristics, not generated semantic meaning. Consumers should review high and medium candidates before adding a card and should never turn the suggested coverage rule into automatic source annotation.
+
 ## Generate incrementally and transactionally
 
 ```js

package/docs/architecture.md

@@ -36,7 +36,7 @@ Generated paths, signatures, callers, references, timestamps, and hashes are nev
 {
   "schemaVersion": 1,
   "specVersion": "1",
-  "generatedBy": "llmnav@0.5.2",
+  "generatedBy": "llmnav@0.6.0",
   "repositoryId": "example",
   "contractFingerprints": {
     "schemaVersion": 1,
@@ -68,6 +68,12 @@ Generated cards may contain a sorted `boundaries` array. LLMNav detects `route`,
 
 Generation compares the previous and current primary indexes to emit `affectedBoundaries`. The report preserves the card change and hash dimensions while adding module IDs, structural boundary records, outbound relation targets, and reverse semantic dependents. It is returned through the API and `generate --json`; it is not stored in source cards.
 
+## Annotation coverage audit
+
+The read-only audit combines package entrypoints, public re-export reachability, generated structural boundaries, import fan-in, exported declaration counts, and source size. It lowers the priority of broad utilities, declaration files, non-production support paths, and pure re-export barrels. Every candidate retains its score inputs and deterministic repository-relative path.
+
+This analyzer deliberately stops before semantic generation. Structure can identify a file worth inspecting, but it cannot safely invent a durable ID, role, ownership statement, invariant, risk, or relation. Accepted boundaries become explicit source cards, path-specific coverage rules, and retrieval regression queries through normal review.
+
 ## Deterministic inverted index
 
 `.llmnav/cache/search-index.json` schemaVersion 2 with `compact-v1` encoding stores a sorted card-ID table, normalized phrase documents, a sorted token dictionary, and posting lists.

package/docs/ci.md

@@ -2,10 +2,11 @@
 
 ## Consumer repository gates
 
-A practical LLMNav gate has four stages.
+A practical LLMNav gate has five stages after the repository has reviewed its initial audit baseline.
 
 ```sh
 npx llmnav format --check
+npx llmnav audit --fail-on high
 npx llmnav check --format github
 npx llmnav generate --full --check
 npx llmnav eval
@@ -13,6 +14,8 @@ npx llmnav eval
 
 `format --check` rejects non-canonical source-card serialization.
 
+`audit --fail-on high` rejects newly exposed high-priority unannotated boundaries. It does not modify source and should not be enabled until the initial candidate list has been reviewed. Medium and low candidates remain advisory by default to avoid turning heuristic scores into blanket annotation policy.
+
 `check` rejects invalid meaning, unresolved or retired semantic relations, malformed registry state, missing configured coverage, path escape, and declaration attachment failures.
 
 Use `npx llmnav check --format sarif > llmnav.sarif` when a code-scanning system accepts SARIF 2.1.0 rather than GitHub workflow annotations. SARIF output is deterministic for the same ordered diagnostics and uses repository-relative paths.
@@ -81,6 +84,7 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npx llmnav format --check
+      - run: npx llmnav audit --fail-on high
       - run: npx llmnav check --format github
       - run: npx llmnav generate --full --check
       - run: npx llmnav eval

package/docs/cli.md

@@ -25,10 +25,22 @@ Creates project configuration, schema, registry, lexicon, evaluation file, agent
 
 `--agents` accepts `agents`, `claude`, `copilot`, `cursor`, a comma-separated combination, `all`, or `none`. The default is `agents`.
 
-`--package-scripts` adds `llmnav:check`, `llmnav:format`, `llmnav:generate`, and `llmnav:eval` to an existing package.json.
+`--package-scripts` adds `llmnav:audit`, `llmnav:check`, `llmnav:format`, `llmnav:generate`, and `llmnav:eval` to an existing package.json. The audit script gates only high-priority candidates.
 
 `--force` refreshes configuration templates, schema, managed agent blocks, and `.llmnav/.gitignore`. It never resets semantic ID history, catalog order, aliases, evaluation cases, or source cards.
 
+## `llmnav audit`
+
+```sh
+llmnav audit [--fail-on none|high|medium|low] [--json]
+```
+
+Reads the selected source set and ranks files that lack file or module cards. Signals include package entrypoints, public re-exports, generated command/route/schema/migration/event boundaries, import fan-in, exported declarations, and source size. Declaration files are omitted; test support code, broad utilities, and pure re-export barrels receive penalties. Candidates whose penalties reduce their score to zero are omitted.
+
+The command never modifies source, configuration, registries, or generated caches. Its output is advisory and exits with status 0 by default. `--fail-on high` fails only for high candidates; `medium` fails for high or medium; `low` fails for any candidate. Invalid thresholds exit with status 2.
+
+JSON output uses schemaVersion 1, repository-relative paths, deterministic ordering, explainable `reasons` and `signals`, and a path-specific `suggestedCoverageRule` for high and medium candidates. Suggestions require human or agent review: LLMNav cannot infer a durable role, ownership boundary, invariant, or semantic ID from structure alone.
+
 ## `llmnav check`
 
 ```sh

package/docs/configuration.md

@@ -88,6 +88,8 @@ Coverage is opt-in and path-specific.
 
 A coverage rule checks files already selected by `sourceRoots` and extension filters. Its fields are closed and `requiredFields` must name valid LLMNav keys. It should target a real architectural boundary, never an entire source tree.
 
+Run `llmnav audit` to obtain path-specific candidate rules. A suggestion is not applied automatically and should be accepted only after the file's durable responsibility is confirmed. This separation prevents structural heuristics from creating vague or stale semantic cards.
+
 ## Lint profile
 
 Byte and field-count limits prevent semantic cards from becoming mini-documents. `maxSemanticRatio` produces a warning after the scanned source exceeds `minimumSourceBytesForRatio`.

package/docs/faq.md

@@ -8,9 +8,13 @@ No. That makes retrieval noisier and creates a second copy of the program in pro
 
 JSDoc and docstrings target generated human documentation and language tooling. They do not define durable semantic IDs, controlled effects and risks, append-only catalog order, relation validation, deterministic search artifacts, or search regression gates. They can coexist with LLMNav cards.
 
-## Does v0.5 change the `llmnav/1` syntax?
+## Does v0.6 change the `llmnav/1` syntax?
 
-No. The source grammar remains `llmnav/1`. v0.5 adds independently versioned agent-operation, prompt-bundle, and editor-diagnostic contracts beside the existing schemaVersion 1 `index.json`.
+No. The source grammar remains `llmnav/1`. v0.6 adds an independently versioned annotation-audit result beside the existing schemaVersion 1 `index.json` and v0.5 integration contracts.
+
+## Does `llmnav audit` write comments automatically?
+
+No. It produces an explainable review queue from structural evidence and never edits source. A candidate can still be intentionally cardless; only a reviewer can define its durable ID, ownership, exclusions, and invariants.
 
 ## Does every query still tokenize every card?
 
@@ -40,7 +44,7 @@ The files are deterministic agent context. Committing them makes drift reviewabl
 
 ## Does LLMNav execute project code?
 
-No. Version 0.5 reads text and configured repository-local JSON files, then writes generated artifacts or explicitly requested card formatting. Its tool dispatcher remains local and has no plugin loader, install hook, or network request.
+No. Version 0.6 reads text and configured repository-local JSON files, then writes generated artifacts or explicitly requested card formatting. The audit path is read-only. Its tool dispatcher remains local and has no plugin loader, install hook, or network request.
 
 ## Can cards be written in Korean?
 

package/docs/migration.md

@@ -7,7 +7,7 @@ No source-card migration is required. Keep every `llmnav/1` comment and the exis
 Upgrade and regenerate:
 
 ```sh
-npm install --save-dev llmnav@^0.5.2
+npm install --save-dev llmnav@^0.6.0
 npx llmnav init --agents all
 npx llmnav generate
 npx llmnav doctor

package/docs/publishing.md

@@ -61,8 +61,8 @@ npm publish --provenance=false --access public
 Automated publication:
 
 ```sh
-git tag v0.5.2
-git push origin v0.5.2
+git tag v0.6.0
+git push origin v0.6.0
 ```
 
 The release workflow rejects a tag that does not match `package.json`. If the exact version is already present in npm, the workflow succeeds only when the registry tarball integrity matches the tagged package; a mismatched package fails closed.

package/docs/quickstart.md

@@ -13,6 +13,16 @@ Review `.llmnav/config.json` before annotating code. The default scans the repos
 
 Source roots and evaluation files must remain inside the repository. The generated cache directory must remain below `.llmnav/`; parent traversal and symbolic-link control directories are rejected.
 
+## Audit before annotating
+
+```sh
+npx llmnav audit
+```
+
+Start with high and medium candidates. The audit explains whether a file is a package entrypoint, public API, generated structural boundary, or high fan-in module. It does not write source or invent card contents. Declaration files and common non-production or utility shapes are suppressed so the result is a review queue, not a demand to annotate every file.
+
+After accepting a candidate, write its durable meaning by inspecting the source, add a narrow `coverageRules` entry for that exact boundary, and add a real task-language query to `.llmnav/eval/queries.jsonl`. Use `npx llmnav audit --fail-on high` in CI only after the initial review.
+
 ## Annotate a module boundary
 
 Choose a boundary that an agent is likely to search for by behavior rather than by current symbol name.

package/examples/provider-neutral-host.mjs

@@ -1,3 +1,14 @@
+/* llmnav/1 module
+id=llmnav.agent.provider-neutral-host
+role=Demonstrate a provider-neutral host that binds one trusted repository root to reusable LLMNav tools and prompt partitions.
+owns=host-side root binding|project session lifecycle|prompt partition selection
+excludes=model provider client|authentication|model-selected repository roots
+search=provider neutral host|tool call adapter|project session example
+invariant=The host supplies the repository root; model-generated tool input cannot replace it.
+rel=workflow>llmnav.agent.protocol
+stability=contract
+*/
+
 import {
   executeAgentOperation,
   createProjectSession,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llmnav",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "A deterministic semantic navigation layer for LLM coding agents.",
   "type": "module",
   "bin": {

package/src/agents.js

@@ -30,6 +30,8 @@ Keep an existing LLMNav ID when a symbol or file is renamed or moved. Change \`r
 
 Do not add hand-maintained \`calls\`, \`imports\`, \`references\`, \`implements\`, \`exports\`, or \`overrides\` relations. Do not put paths, line numbers, commit hashes, timestamps, callers, or current signatures in LLMNav source comments.
 
+After initialization and whenever public entrypoints, commands, routes, schemas, migrations, or high fan-in modules change, run \`npm exec -- llmnav audit\`. Review high and medium candidates; never add cards automatically. Add a module card only after confirming a durable responsibility, then encode the accepted boundary in a path-specific \`coverageRules\` entry and add a representative retrieval query.
+
 After semantic changes, run \`npm exec -- llmnav format\`, \`npm exec -- llmnav check\`, and \`npm exec -- llmnav generate\`. Use broad text search only when LLMNav returns no credible candidate.
 ${END}`;
 

package/src/audit.js

@@ -0,0 +1,282 @@
+/* llmnav/1 module
+id=llmnav.audit.coverage
+role=Identify high-value source modules that lack semantic navigation boundaries without modifying source.
+owns=annotation coverage audit|candidate prioritization|coverage rule suggestions
+excludes=automatic source annotation|semantic role generation
+search=llmnav audit|missing module cards|coverage suggestions
+invariant=Audit output is deterministic, repository-relative, and advisory unless an explicit fail threshold is selected.
+rel=workflow>llmnav.project.scan
+stability=contract
+*/
+
+import path from "node:path";
+import { detectBoundaries } from "./boundaries.js";
+import { scanProject } from "./project.js";
+import { compareText, readJsonSafe, toPosix } from "./util.js";
+
+export const AUDIT_SCHEMA_VERSION = 1;
+export const AUDIT_PRIORITIES = Object.freeze(["high", "medium", "low"]);
+
+const SOURCE_EXTENSIONS = Object.freeze([
+  ".astro", ".c", ".cc", ".cjs", ".cpp", ".cs", ".cts", ".dart", ".go", ".h", ".hpp", ".java",
+  ".js", ".jsx", ".kt", ".kts", ".mjs", ".mts", ".php", ".py", ".rb", ".rs", ".svelte", ".swift",
+  ".ts", ".tsx", ".vue",
+]);
+const UTILITY_NAME_PATTERN = /^(?:common|helpers?|shared|utils?)$/u;
+const NON_PRODUCTION_PATH_PATTERN = /(?:^|\/)(?:__tests__|benchmarks?|fixtures?|tests?)(?:\/|$)|\.(?:spec|test)\.[^/]+$/u;
+const LARGE_SOURCE_BYTES = 12_000;
+
+export async function auditProject(root) {
+  const project = await scanProject(root);
+  const fileByPath = new Map(
+    project.fileRecords.map((record) => [toPosix(record.relativePath), record]),
+  );
+  const moduleCardPaths = new Set(
+    project.records
+      .filter((record) => record.card.scope === "file" || record.card.scope === "module")
+      .map((record) => toPosix(record.relativePath)),
+  );
+  const importsByPath = new Map();
+  const importedBy = new Map([...fileByPath.keys()].map((file) => [file, new Set()]));
+  for (const [file, record] of fileByPath) {
+    const resolved = record.imports
+      .map((specifier) => resolveLocalSpecifier(file, specifier, fileByPath))
+      .filter(Boolean);
+    const unique = [...new Set(resolved)].sort(compareText);
+    importsByPath.set(file, unique);
+    for (const target of unique) importedBy.get(target)?.add(file);
+  }
+
+  const packageJson = await readJsonSafe(path.join(root, "package.json"), {});
+  const entrypoints = collectPackageEntrypoints(packageJson, fileByPath);
+  const publicApiPaths = collectPublicApiPaths(entrypoints, fileByPath);
+  const candidates = [];
+
+  for (const [file, record] of [...fileByPath.entries()].sort(([left], [right]) => compareText(left, right))) {
+    if (moduleCardPaths.has(file)) continue;
+    if (/\.d\.[cm]?ts$/u.test(file)) continue;
+    const boundaries = detectBoundaries({
+      relativePath: file,
+      card: { effect: [], risk: [] },
+    }).map((boundary) => boundary.kind);
+    const exportedDeclarations = countExportedDeclarations(record.source ?? "", file);
+    const entrypoint = entrypoints.has(file);
+    const publicApi = publicApiPaths.has(file) && !entrypoint;
+    const importers = importedBy.get(file)?.size ?? 0;
+    const reexportBarrel = isReexportBarrel(record.source ?? "", file);
+    const basename = path.posix.basename(file, path.posix.extname(file)).toLowerCase();
+    const broadUtility = UTILITY_NAME_PATTERN.test(basename) ||
+      (exportedDeclarations >= 10 && !entrypoint && !publicApi && boundaries.length === 0);
+    const nonProduction = NON_PRODUCTION_PATH_PATTERN.test(file);
+    const largeSource = record.sourceBytes >= LARGE_SOURCE_BYTES;
+    const hasSignal = entrypoint || publicApi || boundaries.length > 0 || importers > 0 || exportedDeclarations > 0 || largeSource;
+    if (!hasSignal) continue;
+
+    let score = 0;
+    const reasons = ["missing-module-card"];
+    if (entrypoint) {
+      score += 50;
+      reasons.push("package-entrypoint");
+    }
+    if (publicApi) {
+      score += 45;
+      reasons.push("public-api-reexport");
+    }
+    for (const boundary of boundaries) {
+      score += boundary === "command" ? 40 : 30;
+      reasons.push(`${boundary}-boundary`);
+    }
+    if (importers > 0) {
+      score += Math.min(30, importers * 5);
+      reasons.push(`imported-by:${importers}`);
+    }
+    if (exportedDeclarations > 0) {
+      score += 10;
+      reasons.push(`exported-declarations:${exportedDeclarations}`);
+    }
+    if (largeSource) {
+      score += 10;
+      reasons.push("large-source");
+    }
+    if (broadUtility) {
+      score -= 30;
+      reasons.push("broad-utility-penalty");
+    }
+    if (nonProduction) {
+      score -= 40;
+      reasons.push("non-production-penalty");
+    }
+    if (reexportBarrel) {
+      score -= 60;
+      reasons.push("reexport-barrel-penalty");
+    }
+    score = Math.max(0, score);
+    if (score === 0) continue;
+    const priority = score >= 60 ? "high" : score >= 30 ? "medium" : "low";
+    candidates.push({
+      path: file,
+      priority,
+      score,
+      reasons,
+      signals: {
+        packageEntrypoint: entrypoint,
+        publicApi,
+        exportedDeclarations,
+        importedBy: importers,
+        boundaries,
+        largeSource,
+        broadUtility,
+        nonProduction,
+        reexportBarrel,
+      },
+      suggestedCoverageRule: priority === "low" ? null : buildCoverageSuggestion(file),
+    });
+  }
+
+  candidates.sort((left, right) =>
+    priorityRank(left.priority) - priorityRank(right.priority) ||
+    right.score - left.score ||
+    compareText(left.path, right.path));
+  const summary = {
+    analyzedFiles: fileByPath.size,
+    cardedFiles: moduleCardPaths.size,
+    filesWithoutModuleCards: fileByPath.size - moduleCardPaths.size,
+    candidates: candidates.length,
+    high: candidates.filter((candidate) => candidate.priority === "high").length,
+    medium: candidates.filter((candidate) => candidate.priority === "medium").length,
+    low: candidates.filter((candidate) => candidate.priority === "low").length,
+    coverageSuggestions: candidates.filter((candidate) => candidate.suggestedCoverageRule !== null).length,
+  };
+  return {
+    schemaVersion: AUDIT_SCHEMA_VERSION,
+    repositoryId: project.config.repositoryId,
+    summary,
+    candidates,
+  };
+}
+
+export function auditHasFindings(result, minimumPriority = "none") {
+  if (minimumPriority === "none") return false;
+  if (!AUDIT_PRIORITIES.includes(minimumPriority)) {
+    throw new TypeError(`Unknown audit priority: ${minimumPriority}.`);
+  }
+  const threshold = priorityRank(minimumPriority);
+  return result.candidates.some((candidate) => priorityRank(candidate.priority) <= threshold);
+}
+
+function buildCoverageSuggestion(file) {
+  const stem = path.posix.basename(file, path.posix.extname(file)).replace(/[^a-z0-9]+/giu, "-").toLowerCase();
+  return {
+    name: `${stem} module boundary`,
+    match: [file],
+    scope: "module",
+    requiredFields: ["owns", "search"],
+  };
+}
+
+function collectPackageEntrypoints(packageJson, fileByPath) {
+  const raw = [packageJson?.main, packageJson?.module, ...collectStringLeaves(packageJson?.bin), ...collectStringLeaves(packageJson?.exports)];
+  const entrypoints = new Set();
+  for (const value of raw) {
+    if (typeof value !== "string" || /\.d\.[cm]?ts$/u.test(value)) continue;
+    const normalized = normalizePackagePath(value);
+    if (!normalized) continue;
+    const resolved = resolveProjectPath(normalized, fileByPath);
+    if (resolved) entrypoints.add(resolved);
+  }
+  return entrypoints;
+}
+
+function collectStringLeaves(value, key = "") {
+  if (key === "types") return [];
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value)) return value.flatMap((item) => collectStringLeaves(item));
+  if (!value || typeof value !== "object") return [];
+  return Object.entries(value).flatMap(([childKey, child]) => collectStringLeaves(child, childKey));
+}
+
+function normalizePackagePath(value) {
+  const normalized = toPosix(value).replace(/^\.\//u, "");
+  if (!normalized || normalized.startsWith("/") || normalized.split("/").includes("..")) return null;
+  return path.posix.normalize(normalized);
+}
+
+function collectPublicApiPaths(entrypoints, fileByPath) {
+  const publicPaths = new Set(entrypoints);
+  const queue = [...entrypoints].sort(compareText);
+  for (let index = 0; index < queue.length; index += 1) {
+    const file = queue[index];
+    const source = fileByPath.get(file)?.source ?? "";
+    for (const specifier of extractReexportSpecifiers(source)) {
+      const target = resolveLocalSpecifier(file, specifier, fileByPath);
+      if (!target || publicPaths.has(target)) continue;
+      publicPaths.add(target);
+      queue.push(target);
+    }
+  }
+  return publicPaths;
+}
+
+function extractReexportSpecifiers(source) {
+  const values = [];
+  const pattern = /^\s*export\s+(?:\*(?:\s+as\s+[A-Za-z_$][\w$]*)?|\{[^}]*\})\s+from\s+["']([^"']+)["']\s*;?/gmu;
+  for (const match of source.matchAll(pattern)) values.push(match[1]);
+  return [...new Set(values)].sort(compareText);
+}
+
+function isReexportBarrel(source, file) {
+  if (!/\.[cm]?[jt]sx?$/u.test(file)) return false;
+  const reexports = extractReexportSpecifiers(source);
+  if (reexports.length === 0) return false;
+  const withoutReexports = source
+    .replace(/^\s*export\s+(?:\*(?:\s+as\s+[A-Za-z_$][\w$]*)?|\{[^}]*\})\s+from\s+["'][^"']+["']\s*;?/gmu, "")
+    .replace(/^\s*\/\/.*$/gmu, "")
+    .replace(/\/\*[\s\S]*?\*\//gu, "")
+    .trim();
+  return withoutReexports === "";
+}
+
+function resolveLocalSpecifier(fromFile, specifier, fileByPath) {
+  if (!specifier.startsWith(".")) return null;
+  const base = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), toPosix(specifier)));
+  if (base.startsWith("../") || base === "..") return null;
+  return resolveProjectPath(base, fileByPath);
+}
+
+function resolveProjectPath(candidate, fileByPath) {
+  const values = [candidate];
+  const extension = path.posix.extname(candidate);
+  if (extension) {
+    const stem = candidate.slice(0, -extension.length);
+    for (const nextExtension of SOURCE_EXTENSIONS) values.push(`${stem}${nextExtension}`);
+  } else {
+    for (const nextExtension of SOURCE_EXTENSIONS) {
+      values.push(`${candidate}${nextExtension}`);
+      values.push(`${candidate}/index${nextExtension}`);
+    }
+  }
+  return values.find((value) => fileByPath.has(value)) ?? null;
+}
+
+function countExportedDeclarations(source, file) {
+  const extension = path.posix.extname(file).toLowerCase();
+  if ([".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".mts", ".cts", ".svelte", ".astro", ".vue"].includes(extension)) {
+    const declarations = source.match(/^\s*export\s+(?:default\s+)?(?:declare\s+)?(?:async\s+)?(?:function|class|const|let|var|type|interface|enum)\b/gmu) ?? [];
+    const localLists = source.match(/^\s*export\s*\{[^}]*\}\s*;?$/gmu) ?? [];
+    const reexports = extractReexportSpecifiers(source).length;
+    return declarations.length + localLists.length + reexports;
+  }
+  if (extension === ".go") {
+    return [...source.matchAll(/^\s*(?:func\s+(?:\([^)]*\)\s*)?|type\s+|var\s+|const\s+)([A-Z][A-Za-z0-9_]*)\b/gmu)].length;
+  }
+  if (extension === ".rs") return [...source.matchAll(/^\s*pub(?:\([^)]*\))?\s+(?:async\s+)?(?:fn|struct|enum|trait|type|const|static|mod)\b/gmu)].length;
+  if (extension === ".py") return [...source.matchAll(/^\s*(?:async\s+def|def|class)\s+([A-Za-z][A-Za-z0-9_]*)\b/gmu)].filter((match) => !match[1].startsWith("_")).length;
+  return 0;
+}
+
+function priorityRank(priority) {
+  if (priority === "high") return 0;
+  if (priority === "medium") return 1;
+  if (priority === "low") return 2;
+  return 3;
+}

package/src/cli.js

@@ -8,6 +8,7 @@ rel=workflow>llmnav.project.initialize
 rel=workflow>llmnav.rules.validate
 rel=workflow>llmnav.search.query
 rel=workflow>llmnav.eval.measure
+rel=workflow>llmnav.audit.coverage
 stability=architecture
 */
 
@@ -37,8 +38,9 @@ import { renderGraphNode } from "./graph.js";
 import { getAgentToolDefinitions } from "./agent-protocol.js";
 import { loadPromptPrefixBundle } from "./prompt-bundle.js";
 import { diagnosticsToEditor, getEditorIntegration } from "./editor.js";
+import { AUDIT_PRIORITIES, auditHasFindings, auditProject } from "./audit.js";
 
-const VALUE_OPTIONS = new Set(["--root", "--format", "--top", "--depth", "--budget", "--max-edges", "--agents", "--file"]);
+const VALUE_OPTIONS = new Set(["--root", "--format", "--top", "--depth", "--budget", "--max-edges", "--agents", "--file", "--fail-on"]);
 
 const COMMAND_OPTIONS = Object.freeze({
   init: new Set(["--agents", "--package-scripts", "--force", "--root", "--json"]),
@@ -51,6 +53,7 @@ const COMMAND_OPTIONS = Object.freeze({
   context: new Set(["--depth", "--budget", "--max-edges", "--root", "--json"]),
   eval: new Set(["--file", "--top", "--root", "--json"]),
   doctor: new Set(["--root", "--json"]),
+  audit: new Set(["--root", "--json", "--fail-on"]),
   spec: new Set(["--root", "--json"]),
   tools: new Set(["--json"]),
   bundle: new Set(["--root", "--json"]),
@@ -97,6 +100,8 @@ export async function runCli(argv) {
       return runEval(root, args, json);
     case "doctor":
       return runDoctor(root, json);
+    case "audit":
+      return runAudit(root, args, json);
     case "spec":
       return runSpec(json);
     case "bundle":
@@ -290,6 +295,29 @@ async function runDoctor(root, json) {
   return result.ok ? 0 : 1;
 }
 
+async function runAudit(root, args, json) {
+  const failOn = getOption(args, "--fail-on") ?? "none";
+  if (failOn !== "none" && !AUDIT_PRIORITIES.includes(failOn)) {
+    throw usageError(`audit --fail-on must be one of none, ${AUDIT_PRIORITIES.join(", ")}.`);
+  }
+  const result = await auditProject(root);
+  const report = { ...result, failOn };
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    const { summary } = result;
+    console.log(
+      `audit files=${summary.analyzedFiles} carded=${summary.cardedFiles} candidates=${summary.candidates} ` +
+      `high=${summary.high} medium=${summary.medium} low=${summary.low}`,
+    );
+    for (const candidate of result.candidates.filter((item) => item.priority !== "low")) {
+      console.log(`${candidate.priority} ${candidate.path} score=${candidate.score} ${candidate.reasons.join(",")}`);
+    }
+    if (summary.low > 0) console.log(`${summary.low} low-priority candidate(s) are available in --json output.`);
+  }
+  return auditHasFindings(result, failOn) ? 1 : 0;
+}
+
 function runSpec(json) {
   const spec = {
     specVersion: SPEC_VERSION,
@@ -446,6 +474,7 @@ Usage
   llmnav context <semantic-id> [--depth 1] [--budget 2500] [--max-edges 24]
   llmnav eval [--file path] [--top 5]
   llmnav doctor
+  llmnav audit [--fail-on none|high|medium|low]
   llmnav spec
   llmnav tools [--json]
   llmnav bundle [--json]

package/src/config.js

@@ -1,3 +1,14 @@
+/* llmnav/1 module
+id=llmnav.config.load
+role=Load, merge, and validate repository configuration before project operations observe it.
+owns=configuration loading|default merging|configuration schema validation
+excludes=source-card validation|schema file generation
+search=load llmnav config|configuration validation|coverage rules
+invariant=Unknown configuration keys and escaping project paths are rejected before use.
+rel=workflow>llmnav.rules.validate
+stability=contract
+*/
+
 import path from "node:path";
 import {
   ALLOWED_KEYS,

package/src/declaration.js

@@ -1,3 +1,14 @@
+/* llmnav/1 module
+id=llmnav.declaration.extract
+role=Attach symbol cards to language declarations and derive structural metadata without executing source.
+owns=declaration attachment|signature extraction|import extraction
+excludes=semantic card parsing|type-system resolution
+search=declaration extraction|symbol attachment|body hash
+invariant=String literals and comments do not create false declarations or imports.
+rel=workflow>llmnav.project.scan
+stability=architecture
+*/
+
 import path from "node:path";
 import { lineAtOffset, normalizeNewlines, sha256 } from "./util.js";
 

package/src/doctor.js

@@ -1,3 +1,14 @@
+/* llmnav/1 module
+id=llmnav.diagnostics.doctor
+role=Diagnose project configuration, generated cache integrity, and recoverable generation state.
+owns=project health checks|cache integrity checks|release readiness diagnostics
+excludes=source formatting|package publication
+search=llmnav doctor|project health|cache integrity
+invariant=Only interrupted generation recovery may mutate state; all other health checks are read-only.
+rel=workflow>llmnav.index.generate
+stability=contract
+*/
+
 import path from "node:path";
 import { loadConfig } from "./config.js";
 import { generateProject } from "./generator.js";

package/src/files.js

@@ -1,3 +1,14 @@
+/* llmnav/1 module
+id=llmnav.source.discover
+role=Locate ancestor LLMNav roots and collect project-contained source files without following symlinks.
+owns=project root discovery|source traversal|include and exclude filtering
+excludes=source parsing|generated artifact selection
+search=source discovery|project root|file traversal
+invariant=Selected source paths remain inside the repository and symbolic links are never traversed.
+rel=workflow>llmnav.project.scan
+stability=contract
+*/
+
 import { lstat, readdir, stat } from "node:fs/promises";
 import path from "node:path";
 import { compareText, matchesAnyGlob, relativePosix, toPosix } from "./util.js";

package/src/formatter.js

@@ -1,3 +1,14 @@
+/* llmnav/1 module
+id=llmnav.source.format
+role=Canonicalize LLMNav source blocks across selected files with atomic writes and check-only reporting.
+owns=source card formatting|format check mode|atomic source rewrite
+excludes=semantic validation|generated cache formatting
+search=llmnav format|canonical comments|source rewrite
+invariant=Check mode reports non-canonical files without writing source files.
+rel=workflow>llmnav.syntax.parse
+stability=contract
+*/
+
 import { readFile } from "node:fs/promises";
 import { loadConfig } from "./config.js";
 import { collectSourceFiles } from "./files.js";

package/src/index.d.ts

@@ -1,6 +1,7 @@
 export type LlmnavScope = "file" | "module" | "symbol";
 export type LlmnavStability = "architecture" | "contract" | "implementation";
 export type DiagnosticSeverity = "error" | "warning" | "info";
+export type AuditPriority = "high" | "medium" | "low";
 
 export interface LlmnavCard {
   scope: LlmnavScope;
@@ -71,6 +72,46 @@ export interface Diagnostic {
   column: number;
 }
 
+export interface AuditCandidate {
+  path: string;
+  priority: AuditPriority;
+  score: number;
+  reasons: string[];
+  signals: {
+    packageEntrypoint: boolean;
+    publicApi: boolean;
+    exportedDeclarations: number;
+    importedBy: number;
+    boundaries: DetectedBoundary["kind"][];
+    largeSource: boolean;
+    broadUtility: boolean;
+    nonProduction: boolean;
+    reexportBarrel: boolean;
+  };
+  suggestedCoverageRule: null | {
+    name: string;
+    match: [string];
+    scope: "module";
+    requiredFields: ["owns", "search"];
+  };
+}
+
+export interface AuditResult {
+  schemaVersion: 1;
+  repositoryId: string;
+  summary: {
+    analyzedFiles: number;
+    cardedFiles: number;
+    filesWithoutModuleCards: number;
+    candidates: number;
+    high: number;
+    medium: number;
+    low: number;
+    coverageSuggestions: number;
+  };
+  candidates: AuditCandidate[];
+}
+
 export interface IndexedLocation {
   path: string;
   startLine: number;
@@ -541,6 +582,8 @@ export interface EvaluationResult {
 }
 
 export const AGENT_PROTOCOL: string;
+export const AUDIT_PRIORITIES: readonly AuditPriority[];
+export const AUDIT_SCHEMA_VERSION: 1;
 export const AGENT_OPERATION_SCHEMA_VERSION: 1;
 export const AGENT_TOOL_SCHEMA_VERSION: 1;
 export const BOUNDARY_KINDS: readonly DetectedBoundary["kind"][];
@@ -615,6 +658,8 @@ export function describeAffectedBoundaries(changedCards: ChangedCardRecord[], co
 export function describeAffectedCatalogs(changedFiles: string[], cacheDirectory: string, config: LlmnavConfig, previousIndex: LlmnavIndex | null, currentIndex: LlmnavIndex): AffectedCatalogRecord[];
 export function loadConfig(root: string): Promise<{ config: LlmnavConfig; configPath: string }>;
 export function validateConfig(config: LlmnavConfig, configPath?: string): void;
+export function auditProject(root: string): Promise<AuditResult>;
+export function auditHasFindings(result: AuditResult, minimumPriority?: AuditPriority | "none"): boolean;
 export function findAttachedDeclaration(source: string, block: LlmnavBlock, filePath: string): Declaration | null;
 export function extractImports(source: string, filePath: string): string[];
 export function doctorProject(root: string): Promise<{ ok: boolean; checks: Array<{ name: string; ok: boolean; message: string }> }>;

package/src/index.js

@@ -14,6 +14,7 @@ export {
 } from "./prompt-bundle.js";
 export { compareCardIndexes, describeAffectedBoundaries, describeAffectedCatalogs } from "./changes.js";
 export { loadConfig, validateConfig } from "./config.js";
+export { AUDIT_PRIORITIES, AUDIT_SCHEMA_VERSION, auditHasFindings, auditProject } from "./audit.js";
 export { BOUNDARY_KINDS, detectBoundaries } from "./boundaries.js";
 export {
   diagnosticsToEditor,

package/src/initializer.js

@@ -121,6 +121,7 @@ async function addPackageScripts(root) {
   const parsed = JSON.parse(text);
   parsed.scripts ??= {};
   const desired = {
+    "llmnav:audit": "llmnav audit --fail-on high",
     "llmnav:check": "llmnav check",
     "llmnav:format": "llmnav format",
     "llmnav:generate": "llmnav generate",

package/src/project.js

@@ -1,3 +1,15 @@
+/* llmnav/1 module
+id=llmnav.project.scan
+role=Scan project sources into semantic card and file records with declarations, imports, and content hashes.
+owns=project scan|card record assembly|source metrics
+excludes=semantic validation|cache generation
+search=project scan|card records|source metadata
+invariant=Generated paths and structural metadata remain derived data and are never written into source cards.
+rel=workflow>llmnav.declaration.extract
+rel=workflow>llmnav.syntax.parse
+stability=architecture
+*/
+
 import { readFile } from "node:fs/promises";
 import { loadConfig } from "./config.js";
 import { findAttachedDeclaration, extractImports } from "./declaration.js";

package/src/registry.js

@@ -1,3 +1,14 @@
+/* llmnav/1 module
+id=llmnav.registry.ids
+role=Validate and evolve semantic ID lifecycle records across active, redirect, replaced, and retired states.
+owns=semantic ID registry|redirect resolution|replacement lifecycle
+excludes=source card parsing|search ranking
+search=semantic id registry|redirected id|retired id
+invariant=Registry resolution never silently chooses among multiple replacement targets.
+rel=workflow>llmnav.index.generate
+stability=contract
+*/
+
 import path from "node:path";
 import { ID_PATTERN } from "./spec.js";
 import { atomicWrite, parseJsonLines, readText } from "./util.js";

package/src/spec.js

@@ -1,4 +1,16 @@
-export const PACKAGE_VERSION = "0.5.2";
+/* llmnav/1 module
+id=llmnav.spec.contract
+role=Define the public LLMNav/1 vocabulary, limits, relation kinds, and default configuration.
+owns=protocol vocabulary|controlled field values|default configuration
+excludes=configuration overrides|source parsing
+search=llmnav specification|protocol constants|default config
+invariant=Public field, effect, risk, and relation vocabularies remain deterministic and versioned.
+rel=workflow>llmnav.config.load
+rel=workflow>llmnav.rules.validate
+stability=contract
+*/
+
+export const PACKAGE_VERSION = "0.6.0";
 export const SPEC_VERSION = "1";
 
 export const SCOPES = Object.freeze(["file", "module", "symbol"]);