llmnav 0.7.4 → 0.9.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ The npm package follows Semantic Versioning. The `llmnav/N` source protocol is v
 
 ## [Unreleased]
 
+## [0.9.0] — 2026-08-15
+
+### Added
+
+* Added `llmnav explain <file>` and `explainProjectFile` to report one file's navigation cards, module coverage, audit score evidence, reviewed disposition, and bounded next action without modifying source.
+
+## [0.8.0] — 2026-08-15
+
+### Added
+
+* Added exact-path audit dispositions with mandatory review reasons, deterministic suppression, and stale-decision reporting so intentional non-cards do not reappear without becoming hidden permanent ignores.
+
 ## [0.7.4] — 2026-08-14
 
 ### Fixed

package/README.md

@@ -47,7 +47,7 @@ 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.
+Before writing cards, run `npx llmnav audit`. It ranks likely architectural boundaries and explains each score. Use `npx llmnav explain <file>` when you need to know why one file is carded, covered by another module card, ranked as a candidate, suppressed by a reviewed disposition, or omitted from the candidate list. Neither command edits source. Review the evidence: a high score is a reason to inspect a file, not permission to generate semantic meaning automatically. For a reviewed false positive or implementation detail, add its exact path and a concrete reason to `audit.dispositions`; stale decisions remain visible instead of becoming permanent hidden ignores.
 
 ## Add the first card
 
@@ -172,6 +172,7 @@ Line-comment cards require an explicit terminator and work with `//`, `#`, and `
 | --- | --- |
 | `llmnav init` | Create configuration, registry, schemas, agent instructions, and the initial cache |
 | `llmnav audit` | Rank unannotated architectural boundary candidates, with compact or file-backed output |
+| `llmnav explain` | Explain one file's card coverage, audit score, disposition, and recommended next action |
 | `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 |
@@ -253,7 +254,7 @@ Do not annotate trivial getters, generated files, obvious wrappers, every test f
 
 ## Current implementation boundary
 
-Version 0.6 adds a deterministic coverage audit that prioritizes root and nested-package entrypoints, structural boundaries, persistent artifact filename protocols, versioned schema literals, Rust/Tauri runtime signals, TypeScript Tauri invoke adapters, and high fan-in modules. It suppresses declaration files, dependency caches, test support code, simple barrels, and low-fan-in broad utilities. It suggests narrow coverage rules but never writes cards or invents semantic roles. Use `llmnav audit --summary --json` for a compact automation result or `llmnav audit --json --output .llmnav/audit.json` to keep the full candidate report out of captured stdout.
+The deterministic coverage audit prioritizes root and nested-package entrypoints, structural boundaries, persistent artifact filename protocols, versioned schema literals, Rust/Tauri runtime signals, TypeScript Tauri invoke adapters, and high fan-in modules. It suppresses declaration files, dependency caches, test support code, simple barrels, and low-fan-in broad utilities. It suggests narrow coverage rules but never writes cards or invents semantic roles. Exact reviewed dispositions suppress known non-boundaries while stale dispositions expose obsolete decisions. Use `llmnav audit --summary --json` for a compact automation result or `llmnav audit --json --output .llmnav/audit.json` to keep the full candidate report out of captured stdout.
 
 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.
 
@@ -294,7 +295,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.7 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.8 CLI. The source format remains `llmnav/1`; npm package changes and source-grammar changes are versioned independently.
 
 ## License
 

package/docs/agent-integration.md

@@ -49,7 +49,7 @@ The generated instruction tells an agent to:
 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.
+When a host supports structured tool calls, `llmnav tools --json` returns five stable provider-neutral definitions in fixed order: `llmnav_query`, `llmnav_show`, `llmnav_context`, `llmnav_check`, and `llmnav_explain`. The new definition is appended so the existing stable tool prefix keeps its order. The schemas reject unknown fields and omit the repository root so the trusted host binds scope outside model-generated input.
 
 The protocol does not order an agent to trust a card over source code. It uses the card to choose what source to inspect.
 
@@ -99,7 +99,7 @@ Suggested contract:
 ```json
 {
   "schemaVersion": 1,
-  "operations": ["llmnav_query", "llmnav_show", "llmnav_context", "llmnav_check"]
+  "operations": ["llmnav_query", "llmnav_show", "llmnav_context", "llmnav_check", "llmnav_explain"]
 }
 ```
 

package/docs/api.md

@@ -65,7 +65,7 @@ Attached symbol declarations expose generated `language`, `exported`, `visibilit
 ## Audit annotation coverage
 
 ```js
-import { auditHasFindings, auditProject } from "llmnav";
+import { auditHasFindings, auditProject, explainProjectFile } from "llmnav";
 
 const result = await auditProject(process.cwd());
 for (const candidate of result.candidates) {
@@ -73,9 +73,12 @@ for (const candidate of result.candidates) {
 }
 
 if (auditHasFindings(result, "high")) process.exitCode = 1;
+
+const explanation = await explainProjectFile(process.cwd(), "src/runtime.ts");
+console.log(explanation.status, explanation.candidate?.score, explanation.recommendation.action);
 ```
 
-`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.
+`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. Exact reviewed decisions from `audit.dispositions` are returned separately with `suppressed` or `stale` status; `auditHasFindings` considers only active candidates. `explainProjectFile` applies the same analysis to one path, preserving candidate score evidence and package-level coverage without mutating source. Consumers should review high and medium candidates before adding a card and should never turn a suggested coverage rule or recommendation into automatic source annotation.
 
 ## Generate incrementally and transactionally
 

package/docs/cli.md

@@ -39,7 +39,17 @@ Reads the selected source set and ranks files that lack file or module cards. Si
 
 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. `--summary` omits candidate details. `--output <path>` writes the selected report inside the repository and emits only a compact confirmation envelope to stdout; escaping paths and symbolic-link traversal are rejected. Suggestions require human or agent review: LLMNav cannot infer a durable role, ownership boundary, invariant, or semantic ID from structure alone.
+JSON output uses schemaVersion 1, repository-relative paths, deterministic ordering, explainable `reasons` and `signals`, and a path-specific `suggestedCoverageRule` for high and medium candidates. Reviewed `audit.dispositions` appear separately as `suppressed` or `stale`; only active candidates participate in `--fail-on`. Stale reasons are `file-not-scanned`, `already-carded`, or `not-a-candidate`. `--summary` omits candidate and disposition details but retains their counters. `--output <path>` writes the selected report inside the repository and emits only a compact confirmation envelope to stdout; escaping paths and symbolic-link traversal are rejected. Suggestions require human or agent review: LLMNav cannot infer a durable role, ownership boundary, invariant, or semantic ID from structure alone.
+
+## `llmnav explain`
+
+```sh
+llmnav explain <file> [--json]
+```
+
+Explains one repository-relative or repository-contained absolute file path without modifying the repository. The result distinguishes active candidates, reviewed suppressions, direct cards, package-level module coverage, files with no ranked audit signal, files excluded from the scanned source set, and stale dispositions. Candidate results retain the audit's representative path, priority, score, reasons, signals, and suggested coverage rule; this matters for Go packages, where the requested file and representative candidate can differ.
+
+The recommendation is deliberately bounded. It may ask for card review, disposition review, stale-disposition cleanup, or no action, but it never invents a semantic ID or writes a source comment. A file outside the repository or an invalid positional argument exits with status 2. A valid path that is not in the scanned source set returns its explanation and exits with status 1.
 
 ## `llmnav check`
 

package/docs/configuration.md

@@ -14,6 +14,9 @@
   "excludeDirectories": ["node_modules", "dist", "target"],
   "excludeFiles": ["*.generated.*", "*.gen.*"],
   "coverageRules": [],
+  "audit": {
+    "dispositions": []
+  },
   "graph": {
     "indexFiles": []
   },
@@ -90,6 +93,25 @@ A coverage rule checks files already selected by `sourceRoots` and extension fil
 
 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.
 
+## Audit dispositions
+
+When a candidate has been reviewed and intentionally does not need a semantic card, record that decision instead of repeatedly ignoring it:
+
+```json
+{
+  "audit": {
+    "dispositions": [
+      {
+        "path": "src/adapters/local-cache.ts",
+        "reason": "This private adapter mirrors its carded module contract and owns no durable policy."
+      }
+    ]
+  }
+}
+```
+
+Each disposition targets one exact normalized repository-relative path. Globs, trailing slashes, backslashes, duplicate paths, and reasons shorter than 12 characters are rejected. A matching candidate is omitted from the active queue and reported as `suppressed`. If the file disappears, gains card coverage, or stops qualifying as a candidate, the disposition is reported as `stale` with a machine-readable reason so obsolete decisions remain visible.
+
 ## 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/quickstart.md

@@ -23,7 +23,7 @@ Start with high and medium candidates. The audit explains whether a file is a pa
 
 In Go repositories, candidates represent packages. Full imports below a repository-contained `go.mod` contribute package fan-in, `cmd/*/main.go` is treated as a command entrypoint, and `_test.go` files do not create separate production candidates. Put one `module` card on a durable package representative; do not repeat the same package role on every Go 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.
+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`. If review confirms that a candidate owns no durable navigation responsibility, add its exact path and a concrete reason to `audit.dispositions`. Never use a glob to dismiss a directory. The audit suppresses the reviewed candidate but reports the entry as stale when the file or its classification changes. Use `npx llmnav audit --fail-on high` in CI only after the initial review.
 
 ## Annotate a module boundary
 

package/package.json

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

package/schema/config.schema.json

@@ -101,6 +101,34 @@
         }
       }
     },
+    "audit": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "dispositions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "path",
+              "reason"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "path": {
+                "type": "string",
+                "pattern": "^(?!/|[A-Za-z]:|.*(?:^|/)\\.\\.(?:/|$)|.*[\\\\*?\\[\\]{}])[^/]+(?:/[^/]+)*$"
+              },
+              "reason": {
+                "type": "string",
+                "minLength": 12,
+                "maxLength": 280
+              }
+            }
+          }
+        }
+      }
+    },
     "graph": {
       "type": "object",
       "additionalProperties": false,

package/src/agent-protocol.js

@@ -6,6 +6,7 @@ excludes=provider SDK transport|repository discovery|source mutation
 search=agent tool schema|provider neutral tools|tool dispatcher|agent operation protocol
 rel=workflow>llmnav.search.query
 rel=workflow>llmnav.rules.validate
+rel=workflow>llmnav.audit.coverage
 stability=contract
 */
 
@@ -14,6 +15,7 @@ import { scanProject } from "./project.js";
 import { buildContext, queryProject, showProjectCard } from "./search.js";
 import { countDiagnostics, validateProject } from "./validator.js";
 import { getAgentToolDefinitions } from "./agent-tools.js";
+import { explainProjectFile } from "./audit.js";
 
 export { AGENT_TOOL_SCHEMA_VERSION, getAgentToolDefinitions } from "./agent-tools.js";
 export const AGENT_OPERATION_SCHEMA_VERSION = 1;
@@ -25,6 +27,7 @@ const OPERATIONS = new Map([
   ["llmnav_show", "show"],
   ["llmnav_context", "context"],
   ["llmnav_check", "check"],
+  ["llmnav_explain", "explain"],
 ]);
 
 export async function executeAgentOperation(root, name, input = {}, options = {}) {
@@ -58,6 +61,9 @@ export async function executeAgentOperation(root, name, input = {}, options = {}
         ? options.session.context(input.id.trim(), contextOptions)
         : await buildContext(root, input.id.trim(), contextOptions));
     }
+    if (operation === "explain") {
+      return success(operation, await explainProjectFile(root, input.file.trim()));
+    }
     const project = await scanProject(root, { paths: input.paths ?? [] });
     const graphInputs = await loadGraphInputs(root, project.config);
     const diagnostics = [...validateProject(project), ...graphInputs.diagnostics].sort(compareDiagnostics);

package/src/agent-tools.js

@@ -32,6 +32,9 @@ const DEFINITIONS = [
       default: [],
     },
   }),
+  tool("llmnav_explain", "Explain one file's card coverage, audit evidence, disposition, and recommended next action.", {
+    file: stringProperty("Repository-relative or repository-contained absolute file path."),
+  }, ["file"]),
 ];
 
 export function getAgentToolDefinitions() {

package/src/agents.js

@@ -30,7 +30,9 @@ 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 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. When a reviewed candidate has no durable navigation responsibility, record its exact path and a concrete reason in \`audit.dispositions\`; never use a glob or broad directory suppression.
+
+When deciding whether one specific file needs a card, run \`npm exec -- llmnav explain <file>\`. Use its coverage, score, and disposition evidence to guide review, but never turn its recommendation into automatic source annotation.
 
 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

@@ -1,9 +1,9 @@
 /* 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
+owns=annotation coverage audit|candidate prioritization|file explanation|coverage rule suggestions
 excludes=automatic source annotation|semantic role generation
-search=llmnav audit|missing module cards|coverage suggestions
+search=llmnav audit|missing module cards|explain missing annotation|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
@@ -17,6 +17,7 @@ import { compareText, readJsonSafe, toPosix } from "./util.js";
 
 export const AUDIT_SCHEMA_VERSION = 1;
 export const AUDIT_PRIORITIES = Object.freeze(["high", "medium", "low"]);
+export const FILE_EXPLANATION_SCHEMA_VERSION = 1;
 
 const SOURCE_EXTENSIONS = Object.freeze([
   ".astro", ".c", ".cc", ".cjs", ".cpp", ".cs", ".cts", ".dart", ".go", ".h", ".hpp", ".java",
@@ -28,6 +29,65 @@ const NON_PRODUCTION_PATH_PATTERN = /(?:^|\/)(?:__tests__|benchmarks?|fixtures?|
 const LARGE_SOURCE_BYTES = 12_000;
 
 export async function auditProject(root) {
+  return (await analyzeAuditProject(root)).result;
+}
+
+export async function explainProjectFile(root, inputPath) {
+  const file = normalizeExplanationPath(root, inputPath);
+  const analysis = await analyzeAuditProject(root);
+  const { project, fileByPath, candidates, result } = analysis;
+  const moduleKey = fileByPath.has(file) ? moduleKeyForFile(file) : null;
+  const navigationCards = project.records
+    .filter((record) => toPosix(record.relativePath) === file)
+    .map((record) => ({ id: record.card.id, scope: record.card.scope, path: file }))
+    .sort((left, right) => compareText(left.id, right.id));
+  const coverageCards = moduleKey === null ? [] : project.records
+    .filter((record) => {
+      const cardPath = toPosix(record.relativePath);
+      if (record.card.scope === "file") return cardPath === file;
+      return record.card.scope === "module" && moduleKeyForFile(cardPath) === moduleKey;
+    })
+    .map((record) => ({ id: record.card.id, scope: record.card.scope, path: toPosix(record.relativePath) }))
+    .sort((left, right) => compareText(left.id, right.id));
+  const candidate = moduleKey === null ? null : candidates.find((item) => moduleKeyForFile(item.path) === moduleKey) ?? null;
+  const dispositionPath = candidate?.path ?? file;
+  const disposition = result.dispositions.find((item) => item.path === dispositionPath) ??
+    result.dispositions.find((item) => item.path === file) ?? null;
+
+  if (disposition?.status === "stale") {
+    return buildFileExplanation(result.repositoryId, file, moduleKey, "stale-disposition", navigationCards, coverageCards, candidate, disposition, [
+      `stale-disposition:${disposition.staleReason}`,
+    ], "remove-or-review-disposition", "Remove or update the stale exact-path disposition after reviewing the current file state.");
+  }
+  if (!fileByPath.has(file)) {
+    return buildFileExplanation(result.repositoryId, file, null, "not-scanned", [], [], null, disposition, ["file-not-scanned"],
+      "check-scan-configuration", "Check that the file exists under a source root and is not excluded by extension, directory, or file rules.");
+  }
+  if (coverageCards.length > 0) {
+    const status = coverageCards.some((card) => card.path === file) ? "carded" : "covered";
+    return buildFileExplanation(result.repositoryId, file, moduleKey, status, navigationCards, coverageCards, null, disposition,
+      [status === "carded" ? "file-has-coverage-card" : "module-covered-by-card"],
+      "keep-current-coverage", "No additional file or module card is needed unless this file gains a separate durable responsibility.");
+  }
+  if (candidate && disposition?.status === "suppressed") {
+    return buildFileExplanation(result.repositoryId, file, moduleKey, "suppressed", navigationCards, coverageCards, candidate, disposition,
+      ["reviewed-exact-path-disposition", ...candidate.reasons], "keep-or-review-disposition",
+      "Keep the disposition while its reason remains true; remove it if the file gains a durable navigation responsibility.");
+  }
+  if (candidate) {
+    const action = candidate.priority === "low" ? "review-or-disposition" : "review-card";
+    const message = candidate.priority === "low"
+      ? "Review the low-priority signal, but do not add a card unless the file owns a durable navigation responsibility."
+      : "Review the candidate and either add one durable card with exact coverage or record an exact-path disposition with a concrete reason.";
+    return buildFileExplanation(result.repositoryId, file, moduleKey, "candidate", navigationCards, coverageCards, candidate, null,
+      candidate.reasons, action, message);
+  }
+  const reasons = /\.d\.[cm]?ts$/u.test(file) ? ["declaration-file"] : ["no-ranked-audit-signal"];
+  return buildFileExplanation(result.repositoryId, file, moduleKey, "not-candidate", navigationCards, coverageCards, null, disposition, reasons,
+    "no-card-needed", "Do not add a card solely for coverage; revisit only if the file gains a durable responsibility or stronger structural signals.");
+}
+
+async function analyzeAuditProject(root) {
   const project = await scanProject(root);
   const fileByPath = new Map(
     project.fileRecords.map((record) => [toPosix(record.relativePath), record]),
@@ -162,22 +222,82 @@ export async function auditProject(root) {
     priorityRank(left.priority) - priorityRank(right.priority) ||
     right.score - left.score ||
     compareText(left.path, right.path));
+  const candidateByPath = new Map(candidates.map((candidate) => [candidate.path, candidate]));
+  const dispositions = [...project.config.audit.dispositions]
+    .sort((left, right) => compareText(left.path, right.path))
+    .map((disposition) => {
+      const candidate = candidateByPath.get(disposition.path);
+      if (candidate) {
+        candidateByPath.delete(disposition.path);
+        return {
+          path: disposition.path,
+          reason: disposition.reason,
+          status: "suppressed",
+          priority: candidate.priority,
+          score: candidate.score,
+        };
+      }
+      return {
+        path: disposition.path,
+        reason: disposition.reason,
+        status: "stale",
+        staleReason: classifyStaleDisposition(disposition.path, fileByPath, exactCardPaths, coveredModules),
+      };
+    });
+  const activeCandidates = candidates.filter((candidate) => candidateByPath.has(candidate.path));
   const summary = {
     analyzedFiles: fileByPath.size,
     cardedFiles: cardedFilePaths.size,
     filesWithoutModuleCards: fileByPath.size - cardedFilePaths.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,
+    candidates: activeCandidates.length,
+    high: activeCandidates.filter((candidate) => candidate.priority === "high").length,
+    medium: activeCandidates.filter((candidate) => candidate.priority === "medium").length,
+    low: activeCandidates.filter((candidate) => candidate.priority === "low").length,
+    coverageSuggestions: activeCandidates.filter((candidate) => candidate.suggestedCoverageRule !== null).length,
+    suppressedCandidates: dispositions.filter((disposition) => disposition.status === "suppressed").length,
+    staleDispositions: dispositions.filter((disposition) => disposition.status === "stale").length,
   };
-  return {
+  const result = {
     schemaVersion: AUDIT_SCHEMA_VERSION,
     repositoryId: project.config.repositoryId,
     summary,
-    candidates,
+    candidates: activeCandidates,
+    dispositions,
   };
+  return { project, fileByPath, candidates, result };
+}
+
+function normalizeExplanationPath(root, inputPath) {
+  if (typeof inputPath !== "string" || inputPath.trim() === "") throw new TypeError("explain requires one file path.");
+  const rootPath = path.resolve(root);
+  const absolutePath = path.resolve(rootPath, inputPath);
+  const relativePath = path.relative(rootPath, absolutePath);
+  if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath)) {
+    throw new RangeError("explain path must name one file inside the repository root.");
+  }
+  return toPosix(relativePath);
+}
+
+function buildFileExplanation(repositoryId, file, moduleKey, status, navigationCards, coverageCards, candidate, disposition, reasons, action, message) {
+  return {
+    schemaVersion: FILE_EXPLANATION_SCHEMA_VERSION,
+    repositoryId,
+    path: file,
+    moduleKey,
+    status,
+    navigationCards,
+    coverageCards,
+    candidate,
+    disposition,
+    reasons,
+    recommendation: { action, message },
+  };
+}
+
+function classifyStaleDisposition(file, fileByPath, exactCardPaths, coveredModules) {
+  if (!fileByPath.has(file)) return "file-not-scanned";
+  if (exactCardPaths.has(file) || coveredModules.has(moduleKeyForFile(file))) return "already-carded";
+  return "not-a-candidate";
 }
 
 function groupFilesByModule(fileByPath) {

package/src/cli.js

@@ -38,7 +38,7 @@ 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";
+import { AUDIT_PRIORITIES, auditHasFindings, auditProject, explainProjectFile } from "./audit.js";
 import { migrateProject } from "./migration.js";
 
 const VALUE_OPTIONS = new Set(["--root", "--format", "--top", "--depth", "--budget", "--max-edges", "--agents", "--file", "--fail-on", "--output"]);
@@ -56,6 +56,7 @@ const COMMAND_OPTIONS = Object.freeze({
   doctor: new Set(["--root", "--json"]),
   migrate: new Set(["--check", "--write", "--root", "--json"]),
   audit: new Set(["--root", "--json", "--summary", "--fail-on", "--output"]),
+  explain: new Set(["--root", "--json"]),
   spec: new Set(["--root", "--json"]),
   tools: new Set(["--json"]),
   bundle: new Set(["--root", "--json"]),
@@ -106,6 +107,8 @@ export async function runCli(argv) {
       return runMigrate(root, args, json);
     case "audit":
       return runAudit(root, args, json);
+    case "explain":
+      return runExplain(root, args, json);
     case "spec":
       return runSpec(json);
     case "bundle":
@@ -349,17 +352,59 @@ async function runAudit(root, args, json) {
     const { summary } = result;
     console.log(
       `audit files=${summary.analyzedFiles} carded=${summary.cardedFiles} candidates=${summary.candidates} ` +
-      `high=${summary.high} medium=${summary.medium} low=${summary.low}`,
+      `high=${summary.high} medium=${summary.medium} low=${summary.low} ` +
+      `suppressed=${summary.suppressedCandidates} stale-dispositions=${summary.staleDispositions}`,
     );
     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.`);
+    for (const disposition of result.dispositions.filter((item) => item.status === "stale")) {
+      console.log(`stale ${disposition.path} ${disposition.staleReason}: ${disposition.reason}`);
+    }
     if (outputPath) console.log(`wrote ${relativePosix(root, outputPath)}`);
   }
   return auditHasFindings(result, failOn) ? 1 : 0;
 }
 
+async function runExplain(root, args, json) {
+  const files = getPositionals(args);
+  if (files.length !== 1) throw usageError("explain requires exactly one file path.");
+  let result;
+  try {
+    result = await explainProjectFile(root, files[0]);
+  } catch (error) {
+    if ((error instanceof TypeError || error instanceof RangeError) && /^explain (?:requires|path)/u.test(error.message)) {
+      throw usageError(error.message);
+    }
+    throw error;
+  }
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`file ${result.path}`);
+    console.log(`status ${result.status}`);
+    if (result.moduleKey) console.log(`module ${result.moduleKey}`);
+    for (const card of result.navigationCards) console.log(`card ${card.scope} @${card.id} ${card.path}`);
+    for (const card of result.coverageCards) {
+      if (!result.navigationCards.some((item) => item.id === card.id && item.path === card.path)) {
+        console.log(`coverage ${card.scope} @${card.id} ${card.path}`);
+      }
+    }
+    if (result.candidate) {
+      console.log(`candidate ${result.candidate.priority} ${result.candidate.path} score=${result.candidate.score}`);
+      console.log(`why ${result.candidate.reasons.join(",")}`);
+      const signals = Object.entries(result.candidate.signals)
+        .filter(([, value]) => Array.isArray(value) ? value.length > 0 : Boolean(value))
+        .map(([name, value]) => `${name}=${Array.isArray(value) ? value.join("|") : value}`);
+      if (signals.length > 0) console.log(`signals ${signals.join(",")}`);
+    }
+    if (result.disposition) console.log(`disposition ${result.disposition.status}: ${result.disposition.reason}`);
+    console.log(`next ${result.recommendation.action}: ${result.recommendation.message}`);
+  }
+  return result.status === "not-scanned" ? 1 : 0;
+}
+
 function runSpec(json) {
   const spec = {
     specVersion: SPEC_VERSION,
@@ -518,6 +563,7 @@ Usage
   llmnav doctor
   llmnav migrate [--check|--write]
   llmnav audit [--summary] [--output path] [--fail-on none|high|medium|low]
+  llmnav explain <file>
   llmnav spec
   llmnav tools [--json]
   llmnav bundle [--json]

package/src/config.js

@@ -30,7 +30,9 @@ const LINT_KEYS = new Set(Object.keys(DEFAULT_CONFIG.lint));
 const GENERATION_KEYS = new Set(Object.keys(DEFAULT_CONFIG.generation));
 const EVALUATION_KEYS = new Set(Object.keys(DEFAULT_CONFIG.evaluation));
 const GRAPH_KEYS = new Set(Object.keys(DEFAULT_CONFIG.graph));
+const AUDIT_KEYS = new Set(Object.keys(DEFAULT_CONFIG.audit));
 const COVERAGE_KEYS = new Set(["name", "match", "scope", "requiredFields"]);
+const AUDIT_DISPOSITION_KEYS = new Set(["path", "reason"]);
 
 export async function loadConfig(root) {
   const configPath = path.join(root, ".llmnav", "config.json");
@@ -72,6 +74,7 @@ export function validateConfig(config, configPath = ".llmnav/config.json") {
   validateStringArray(config.excludeDirectories, "excludeDirectories", problems, { unique: true });
   validateStringArray(config.excludeFiles, "excludeFiles", problems, { unique: true });
   validateCoverageRules(config.coverageRules, problems);
+  validateAudit(config.audit, problems);
   validateGraph(config.graph, problems);
 
   validateLint(config.lint, problems);
@@ -83,6 +86,44 @@ export function validateConfig(config, configPath = ".llmnav/config.json") {
   }
 }
 
+function validateAudit(audit, problems) {
+  if (!isObject(audit)) {
+    problems.push("audit must be an object");
+    return;
+  }
+  validateObjectKeys(audit, AUDIT_KEYS, "audit", problems);
+  if (!Array.isArray(audit.dispositions)) {
+    problems.push("audit.dispositions must be an array");
+    return;
+  }
+  const seenPaths = new Set();
+  for (const [index, disposition] of audit.dispositions.entries()) {
+    const name = `audit.dispositions[${index}]`;
+    if (!isObject(disposition)) {
+      problems.push(`${name} must be an object`);
+      continue;
+    }
+    validateObjectKeys(disposition, AUDIT_DISPOSITION_KEYS, name, problems);
+    const pathProblem = validateProjectRelativePath(disposition.path);
+    if (pathProblem) {
+      problems.push(`${name}.path ${pathProblem}`);
+    } else {
+      const normalizedPath = path.posix.normalize(disposition.path);
+      if (normalizedPath !== disposition.path || disposition.path.endsWith("/") || /[*?[\]{}]/u.test(disposition.path)) {
+        problems.push(`${name}.path must be one exact normalized repository-relative path without glob syntax`);
+      }
+      const comparisonPath = normalizedPath.normalize("NFKC").toLocaleLowerCase("en-US");
+      if (seenPaths.has(comparisonPath)) problems.push(`${name}.path duplicates an earlier disposition`);
+      seenPaths.add(comparisonPath);
+    }
+    if (typeof disposition.reason !== "string" || disposition.reason.trim().length < 12) {
+      problems.push(`${name}.reason must explain the review decision in at least 12 characters`);
+    } else if (disposition.reason.length > 280) {
+      problems.push(`${name}.reason must not exceed 280 characters`);
+    }
+  }
+}
+
 function validateGraph(graph, problems) {
   if (!isObject(graph)) {
     problems.push("graph must be an object");

package/src/index.d.ts

@@ -2,6 +2,8 @@ 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 type AuditDispositionStaleReason = "file-not-scanned" | "already-carded" | "not-a-candidate";
+export type FileExplanationStatus = "candidate" | "suppressed" | "carded" | "covered" | "not-candidate" | "not-scanned" | "stale-disposition";
 
 export interface LlmnavCard {
   scope: LlmnavScope;
@@ -108,8 +110,31 @@ export interface AuditResult {
     medium: number;
     low: number;
     coverageSuggestions: number;
+    suppressedCandidates: number;
+    staleDispositions: number;
   };
   candidates: AuditCandidate[];
+  dispositions: Array<
+    | { path: string; reason: string; status: "suppressed"; priority: AuditPriority; score: number }
+    | { path: string; reason: string; status: "stale"; staleReason: AuditDispositionStaleReason }
+  >;
+}
+
+export interface FileExplanationResult {
+  schemaVersion: 1;
+  repositoryId: string;
+  path: string;
+  moduleKey: string | null;
+  status: FileExplanationStatus;
+  navigationCards: Array<{ id: string; scope: LlmnavScope; path: string }>;
+  coverageCards: Array<{ id: string; scope: "file" | "module"; path: string }>;
+  candidate: AuditCandidate | null;
+  disposition: AuditResult["dispositions"][number] | null;
+  reasons: string[];
+  recommendation: {
+    action: "review-card" | "review-or-disposition" | "keep-or-review-disposition" | "keep-current-coverage" | "no-card-needed" | "check-scan-configuration" | "remove-or-review-disposition";
+    message: string;
+  };
 }
 
 export interface IndexedLocation {
@@ -247,6 +272,9 @@ export interface LlmnavConfig {
   excludeDirectories: string[];
   excludeFiles: string[];
   coverageRules: Array<Record<string, unknown>>;
+  audit: {
+    dispositions: Array<{ path: string; reason: string }>;
+  };
   graph: {
     indexFiles: string[];
   };
@@ -287,7 +315,7 @@ export interface LlmnavConfig {
 
 export interface AgentToolDefinition {
   schemaVersion: 1;
-  name: "llmnav_query" | "llmnav_show" | "llmnav_context" | "llmnav_check";
+  name: "llmnav_query" | "llmnav_show" | "llmnav_context" | "llmnav_check" | "llmnav_explain";
   description: string;
   inputSchema: {
     type: "object";
@@ -299,7 +327,7 @@ export interface AgentToolDefinition {
 
 export interface AgentOperationResult<T = unknown> {
   schemaVersion: 1;
-  operation: "query" | "show" | "context" | "check" | "unknown";
+  operation: "query" | "show" | "context" | "check" | "explain" | "unknown";
   ok: boolean;
   data: T | null;
   error: { code: string; message: string } | null;
@@ -611,6 +639,7 @@ export interface EvaluationResult {
 export const AGENT_PROTOCOL: string;
 export const AUDIT_PRIORITIES: readonly AuditPriority[];
 export const AUDIT_SCHEMA_VERSION: 1;
+export const FILE_EXPLANATION_SCHEMA_VERSION: 1;
 export const AGENT_OPERATION_SCHEMA_VERSION: 1;
 export const AGENT_TOOL_SCHEMA_VERSION: 1;
 export const BOUNDARY_KINDS: readonly DetectedBoundary["kind"][];
@@ -688,6 +717,7 @@ export function loadConfig(root: string): Promise<{ config: LlmnavConfig; config
 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 explainProjectFile(root: string, file: string): Promise<FileExplanationResult>;
 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,7 +14,14 @@ 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 {
+  AUDIT_PRIORITIES,
+  AUDIT_SCHEMA_VERSION,
+  FILE_EXPLANATION_SCHEMA_VERSION,
+  auditHasFindings,
+  auditProject,
+  explainProjectFile,
+} from "./audit.js";
 export { BOUNDARY_KINDS, detectBoundaries } from "./boundaries.js";
 export {
   diagnosticsToEditor,

package/src/spec.js

@@ -10,7 +10,7 @@ rel=workflow>llmnav.rules.validate
 stability=contract
 */
 
-export const PACKAGE_VERSION = "0.7.4";
+export const PACKAGE_VERSION = "0.9.0";
 export const SPEC_VERSION = "1";
 
 export const SCOPES = Object.freeze(["file", "module", "symbol"]);
@@ -208,6 +208,9 @@ export const DEFAULT_CONFIG = Object.freeze({
   excludeDirectories: [...DEFAULT_EXCLUDED_DIRECTORIES],
   excludeFiles: ["*.min.js", "*.bundle.js", "*.generated.*", "*.gen.*"],
   coverageRules: [],
+  audit: {
+    dispositions: [],
+  },
   graph: {
     indexFiles: [],
   },