llmnav 0.7.4 → 0.8.0

package/CHANGELOG.md

@@ -6,6 +6,12 @@ The npm package follows Semantic Versioning. The `llmnav/N` source protocol is v
 
 ## [Unreleased]
 
+## [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. 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. 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
 
@@ -253,7 +253,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 +294,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/api.md

@@ -75,7 +75,7 @@ for (const candidate of result.candidates) {
 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.
+`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. 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
 

package/docs/cli.md

@@ -39,7 +39,7 @@ 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 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.8.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/agents.js

@@ -30,7 +30,7 @@ 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.
 
 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

@@ -162,24 +162,56 @@ 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 {
     schemaVersion: AUDIT_SCHEMA_VERSION,
     repositoryId: project.config.repositoryId,
     summary,
-    candidates,
+    candidates: activeCandidates,
+    dispositions,
   };
 }
 
+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) {
   const output = new Map();
   for (const [file, record] of fileByPath) {

package/src/cli.js

@@ -349,12 +349,16 @@ 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;

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,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 type AuditDispositionStaleReason = "file-not-scanned" | "already-carded" | "not-a-candidate";
 
 export interface LlmnavCard {
   scope: LlmnavScope;
@@ -108,8 +109,14 @@ 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 IndexedLocation {
@@ -247,6 +254,9 @@ export interface LlmnavConfig {
   excludeDirectories: string[];
   excludeFiles: string[];
   coverageRules: Array<Record<string, unknown>>;
+  audit: {
+    dispositions: Array<{ path: string; reason: string }>;
+  };
   graph: {
     indexFiles: string[];
   };

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.8.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: [],
   },