auditor-lambda 0.13.0 → 0.14.0

package/dist/coverage.d.ts

@@ -1,6 +1,6 @@
-import type { CoverageFileRecord, CoverageMatrix, FileCoverageRecord, Lens } from "./types.js";
+import type { ClassificationStatus, CoverageFileRecord, CoverageMatrix, FileCoverageRecord, Lens } from "./types.js";
 export declare function createCoverageMatrix(paths: string[]): CoverageMatrix;
-export declare function markExcludedPath(matrix: CoverageMatrix, path: string, classificationStatus: string): void;
+export declare function markExcludedPath(matrix: CoverageMatrix, path: string, classificationStatus: ClassificationStatus): void;
 export declare function applyUnitCoverage(matrix: CoverageMatrix, path: string, unitId: string, requiredLenses: Lens[]): void;
 export declare function applyFileCoverage(matrix: CoverageMatrix, fileCoverage: FileCoverageRecord[]): void;
 export declare function findUncoveredFiles(matrix: CoverageMatrix): CoverageFileRecord[];

package/dist/extractors/disposition.d.ts

@@ -1,9 +1,75 @@
+import type { SpawnSyncOptionsWithStringEncoding, SpawnSyncReturns } from "node:child_process";
 import type { RepoManifest } from "../types.js";
 import type { FileDisposition, FileDispositionStatus } from "@audit-tools/shared";
+/**
+ * Explicit out-of-scope reason for files excluded because the repository's own
+ * VCS ignore rules (.gitignore et al.) cover them.
+ */
+export declare const VCS_IGNORED_REASON = "vcs_ignored";
+/**
+ * At or below this many vcs-ignored files, the disposition carries one
+ * per-file record per ignored file. Above it, ignored files are aggregated by
+ * directory prefix so file_disposition.json stays bounded regardless of how
+ * many files the ignore rules cover.
+ */
+export declare const VCS_IGNORED_PER_FILE_LIMIT = 200;
+/**
+ * Guard threshold: when `git check-ignore` reports more than this share of all
+ * candidate files as ignored, the gitignore rule is skipped (guard branch
+ * `share_exceeded`) and only the existing targeted exclusions apply. A share
+ * of exactly 1.0 means the audit root itself is effectively ignored (guard
+ * branch `root_ignored`).
+ */
+export declare const VCS_IGNORED_MAX_SHARE = 0.9;
+export type VcsIgnoreGuardBranch = "root_ignored" | "share_exceeded";
+/** Bounded directory-prefix aggregate used above VCS_IGNORED_PER_FILE_LIMIT. */
+export interface VcsIgnoredAggregate {
+    /** Top-level directory prefix ("." for root-level files). */
+    prefix: string;
+    /** Number of vcs-ignored files under the prefix. */
+    count: number;
+    reason: typeof VCS_IGNORED_REASON;
+}
+/**
+ * Outcome record for the gitignore disposition rule, persisted alongside the
+ * per-file records so the scope pre-digest / intent checkpoint can surface
+ * skipped-rule and guard decisions.
+ */
+export interface VcsIgnoreSummary {
+    /** True when gitignore-based exclusions were applied to the disposition. */
+    applied: boolean;
+    /** Number of candidate files `git check-ignore` reported as ignored. */
+    ignored_count: number;
+    /** Why the gitignore rule was skipped (clean fallback or guard). */
+    skipped_reason?: string;
+    /** Which guard branch fired when a guard skipped the rule. */
+    guard_branch?: VcsIgnoreGuardBranch;
+    /** Directory-prefix aggregates emitted above VCS_IGNORED_PER_FILE_LIMIT. */
+    aggregates?: VcsIgnoredAggregate[];
+}
+/** FileDisposition enriched with the gitignore-rule outcome record. */
+export interface FileDispositionWithVcsIgnore extends FileDisposition {
+    vcs_ignore?: VcsIgnoreSummary;
+}
+/** Injection seam for the single batched `git check-ignore` spawn (tests). */
+export type CheckIgnoreSpawn = (command: string, args: readonly string[], options: SpawnSyncOptionsWithStringEncoding) => SpawnSyncReturns<string>;
+export interface BuildFileDispositionOptions {
+    /**
+     * Audit root. When provided (and a git work tree), enables the batched
+     * `git check-ignore --stdin` pass that classifies vcs-ignored files
+     * out of scope. Omit for the heuristics-only disposition.
+     */
+    root?: string;
+    /** Test seam: replacement for child_process.spawnSync. */
+    spawn?: CheckIgnoreSpawn;
+}
 /**
  * Applies shared path heuristics to mark files that should be excluded or
- * down-scoped before audit planning begins.
+ * down-scoped before audit planning begins. When `options.root` is provided,
+ * additionally classifies vcs-ignored files out of scope via one batched
+ * `git check-ignore --stdin` pass, with clean fallback to the heuristics-only
+ * disposition whenever git is unavailable or a safety guard fires.
  */
-export declare function buildFileDisposition(repoManifest: RepoManifest): FileDisposition;
+export declare function buildFileDisposition(repoManifest: RepoManifest, options?: BuildFileDispositionOptions): FileDispositionWithVcsIgnore;
 export declare function buildDispositionMap(disposition?: FileDisposition): Map<string, FileDispositionStatus>;
-export declare function isAuditExcludedStatus(status: FileDispositionStatus): boolean;
+export declare function isAuditExcludedStatus(status: FileDispositionStatus): status is Exclude<FileDispositionStatus, "included">;

package/dist/extractors/disposition.js

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { isNodeModulesOrGit, isPackageManagerCachePath, isTmpPath, isBuildOutput, isVendorPath, isBinaryArtifact, isLicensePath, isLockfilePath, isLogPath, isDocPath, isGeneratedPath, isAuditArtifactPath, isAuditToolOutputArtifact, isGeneratedTestArtifactPath, isGeneratedInstallArtifactPath, isExamplesOrFixturesPath, normalizeExtractorPath, } from "./pathPatterns.js";
 function inferDisposition(path) {
     const normalized = normalizeExtractorPath(path);
@@ -87,13 +88,174 @@ function inferDisposition(path) {
         reason: "Default included source or config artifact.",
     };
 }
+/**
+ * Explicit out-of-scope reason for files excluded because the repository's own
+ * VCS ignore rules (.gitignore et al.) cover them.
+ */
+export const VCS_IGNORED_REASON = "vcs_ignored";
+/**
+ * At or below this many vcs-ignored files, the disposition carries one
+ * per-file record per ignored file. Above it, ignored files are aggregated by
+ * directory prefix so file_disposition.json stays bounded regardless of how
+ * many files the ignore rules cover.
+ */
+export const VCS_IGNORED_PER_FILE_LIMIT = 200;
+/**
+ * Guard threshold: when `git check-ignore` reports more than this share of all
+ * candidate files as ignored, the gitignore rule is skipped (guard branch
+ * `share_exceeded`) and only the existing targeted exclusions apply. A share
+ * of exactly 1.0 means the audit root itself is effectively ignored (guard
+ * branch `root_ignored`).
+ */
+export const VCS_IGNORED_MAX_SHARE = 0.9;
+function toPosixPath(path) {
+    return path.replace(/\\/g, "/");
+}
+/**
+ * Evaluates every candidate path through ONE batched
+ * `git check-ignore --stdin -z` invocation (never per-file). Exit-code
+ * contract: 0 = some paths ignored, 1 = none ignored (success, empty set),
+ * anything else (128 / git absent / not a work tree) = clean fallback —
+ * the caller keeps only the existing targeted exclusions. Never throws.
+ */
+function evaluateVcsIgnored(root, candidatePosixPaths, spawn) {
+    if (candidatePosixPaths.length === 0) {
+        return { ok: true, ignored: new Set() };
+    }
+    let result;
+    try {
+        result = spawn("git", ["check-ignore", "--stdin", "-z"], {
+            cwd: root,
+            input: candidatePosixPaths.map((path) => `${path}\0`).join(""),
+            encoding: "utf8",
+            maxBuffer: 256 * 1024 * 1024,
+            windowsHide: true,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, reason: `git check-ignore spawn failed: ${message}` };
+    }
+    if (result.error) {
+        const code = result.error.code;
+        return {
+            ok: false,
+            reason: code === "ENOENT"
+                ? "git executable not found (ENOENT)"
+                : `git check-ignore failed to start: ${result.error.message}`,
+        };
+    }
+    if (result.status === 0 || result.status === 1) {
+        // 0 = some paths ignored (stdout has the set); 1 = no paths ignored.
+        const ignored = new Set((result.stdout ?? "").split("\0").filter((path) => path.length > 0));
+        return { ok: true, ignored };
+    }
+    const stderrFirstLine = (result.stderr ?? "").trim().split(/\r?\n/, 1)[0] ?? "";
+    return {
+        ok: false,
+        reason: `git check-ignore exited ${result.status ?? "by signal"}` +
+            (stderrFirstLine ? `: ${stderrFirstLine}` : ""),
+    };
+}
+function topLevelPrefix(posixPath) {
+    const slash = posixPath.indexOf("/");
+    return slash === -1 ? "." : posixPath.slice(0, slash);
+}
+function aggregateByPrefix(posixPaths) {
+    const counts = new Map();
+    for (const path of posixPaths) {
+        const prefix = topLevelPrefix(path);
+        counts.set(prefix, (counts.get(prefix) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([prefix, count]) => ({ prefix, count, reason: VCS_IGNORED_REASON }));
+}
 /**
  * Applies shared path heuristics to mark files that should be excluded or
- * down-scoped before audit planning begins.
+ * down-scoped before audit planning begins. When `options.root` is provided,
+ * additionally classifies vcs-ignored files out of scope via one batched
+ * `git check-ignore --stdin` pass, with clean fallback to the heuristics-only
+ * disposition whenever git is unavailable or a safety guard fires.
  */
-export function buildFileDisposition(repoManifest) {
+export function buildFileDisposition(repoManifest, options = {}) {
+    const baseline = repoManifest.files.map((file) => inferDisposition(file.path));
+    if (!options.root) {
+        return { files: baseline };
+    }
+    const candidatePosix = repoManifest.files.map((file) => toPosixPath(file.path));
+    const evaluation = evaluateVcsIgnored(options.root, candidatePosix, options.spawn ?? spawnSync);
+    if (!evaluation.ok) {
+        // Clean fallback: keep the existing targeted exclusions only.
+        return {
+            files: baseline,
+            vcs_ignore: {
+                applied: false,
+                ignored_count: 0,
+                skipped_reason: `gitignore rule skipped: ${evaluation.reason}`,
+            },
+        };
+    }
+    const total = candidatePosix.length;
+    const ignoredCount = candidatePosix.filter((path) => evaluation.ignored.has(path)).length;
+    // Root-ignored guard: every candidate ignored means the audit root itself is
+    // (effectively) ignored — applying the rule would empty the audit scope.
+    if (total > 0 && ignoredCount === total) {
+        return {
+            files: baseline,
+            vcs_ignore: {
+                applied: false,
+                ignored_count: ignoredCount,
+                guard_branch: "root_ignored",
+                skipped_reason: "gitignore rule skipped: audit root itself is ignored (every candidate file matched ignore rules)",
+            },
+        };
+    }
+    // Share guard: an ignore rule that would exclude more than
+    // VCS_IGNORED_MAX_SHARE of candidates is more likely a mis-scope than a
+    // legitimate exclusion — skip it and surface the decision.
+    if (total > 0 && ignoredCount / total > VCS_IGNORED_MAX_SHARE) {
+        return {
+            files: baseline,
+            vcs_ignore: {
+                applied: false,
+                ignored_count: ignoredCount,
+                guard_branch: "share_exceeded",
+                skipped_reason: `gitignore rule skipped: ignored share ${(ignoredCount / total).toFixed(3)} ` +
+                    `exceeds VCS_IGNORED_MAX_SHARE (${VCS_IGNORED_MAX_SHARE})`,
+            },
+        };
+    }
+    // Existing targeted exclusions take precedence; the gitignore rule only
+    // re-classifies files the heuristics would otherwise include.
+    const newlyIgnoredPosix = [];
+    for (let i = 0; i < baseline.length; i++) {
+        if (baseline[i].status === "included" &&
+            evaluation.ignored.has(candidatePosix[i])) {
+            newlyIgnoredPosix.push(candidatePosix[i]);
+        }
+    }
+    if (newlyIgnoredPosix.length <= VCS_IGNORED_PER_FILE_LIMIT) {
+        const newlyIgnoredSet = new Set(newlyIgnoredPosix);
+        const files = baseline.map((item, i) => newlyIgnoredSet.has(candidatePosix[i]) && item.status === "included"
+            ? { path: item.path, status: "excluded", reason: VCS_IGNORED_REASON }
+            : item);
+        return {
+            files,
+            vcs_ignore: { applied: true, ignored_count: ignoredCount },
+        };
+    }
+    // Bounded representation: above the per-file limit, drop per-file records
+    // for vcs-ignored files and emit directory-prefix aggregates instead.
+    const newlyIgnoredSet = new Set(newlyIgnoredPosix);
+    const files = baseline.filter((item, i) => !(item.status === "included" && newlyIgnoredSet.has(candidatePosix[i])));
     return {
-        files: repoManifest.files.map((file) => inferDisposition(file.path)),
+        files,
+        vcs_ignore: {
+            applied: true,
+            ignored_count: ignoredCount,
+            aggregates: aggregateByPrefix(newlyIgnoredPosix),
+        },
     };
 }
 export function buildDispositionMap(disposition) {

package/dist/orchestrator/intakeExecutors.js

@@ -83,7 +83,7 @@ export async function runIntakeExecutor(bundle, root, artifactsDir) {
         ignore,
         hash_files: true,
     });
-    const disposition = buildFileDisposition(repoManifest);
+    const disposition = buildFileDisposition(repoManifest, { root });
     const auditableCount = disposition.files.filter((file) => !isAuditExcludedStatus(file.status)).length;
     if (auditableCount === 0) {
         throw new Error(`No auditable files found in ${root}. The repository may be empty, generated-only, documentation-only, or filtered by .auditorignore.`);

package/dist/orchestrator/structureExecutors.js

@@ -10,7 +10,8 @@ export async function runStructureExecutor(bundle, root) {
         throw new Error("Cannot run structure executor without repo_manifest");
     }
     const externalAnalyzerResults = bundle.external_analyzer_results;
-    const disposition = bundle.file_disposition ?? buildFileDisposition(bundle.repo_manifest);
+    const disposition = bundle.file_disposition ??
+        buildFileDisposition(bundle.repo_manifest, root ? { root } : {});
     const unitManifest = buildUnitManifest(bundle.repo_manifest, disposition);
     const graphBundle = root
         ? await buildGraphBundleFromFs(bundle.repo_manifest, root, disposition, {

package/dist/reporting/findingIdentity.d.ts

@@ -1,6 +1,53 @@
 import type { Finding } from "../types.js";
 /**
- * Re-key finalized findings with globally-unique, content-derived ids at the
+ * The stable semantic fields a finding's identity may be derived from.
+ *
+ * Volatile, content-derived values — unit ids, line numbers, pass
+ * ordinals/pass_id, timestamps — are deliberately absent from this shape so
+ * they can never reach the hash input at any ladder tier. The raw title is
+ * accepted but only ever influences identity after aggressive normalization
+ * (tier 3), and only when no stronger tier applies.
+ */
+export interface FindingIdentityFields {
+    /** Repo-relative primary file path of the structural anchor, if any. */
+    anchor_path?: string;
+    /** Symbol/scope identifier at the anchor (the anchor's unit/scope). */
+    anchor_symbol?: string;
+    /** Rule/category identifier. */
+    category?: string;
+    /** Lens — paired with category at tier 2 (the existing category convention). */
+    lens?: string;
+    /** Title; aggressively normalized before it can influence identity. */
+    title?: string;
+}
+/**
+ * The single, explicit, deterministic fallback ladder for finding identity.
+ * The same semantic finding always yields the same signature across passes
+ * and runs; the ladder consults stable semantic fields only:
+ *
+ * 1. **Structural anchor** — the repo-relative primary file path
+ *    (separator-normalized, case-folded) together with the anchor's
+ *    symbol/scope. The unit/scope is part of the hashed identity, so two
+ *    findings at the same path but different scopes get distinct ids.
+ * 2. **Rule/category** — when no structural anchor is available, the
+ *    rule/category identifier paired with the lens (the existing category
+ *    convention).
+ * 3. **Normalized title** — when neither anchor nor rule/category exists, an
+ *    aggressively normalized title (see {@link normalizeTitle}).
+ *
+ * Content-derived unit ids, line numbers, pass ordinals/pass_id, timestamps,
+ * and raw (unnormalized) titles are never part of the signature: they do not
+ * appear in {@link FindingIdentityFields}, so no tier can hash them.
+ *
+ * The signature is also independent of a finding's merged affected-file
+ * *list*: at most the single structural anchor (primary path + scope) can
+ * contribute, never the full file set, so a finding's identity stays put as
+ * mergeFindings() unions additional re-emitted files into it across passes
+ * and runs.
+ */
+export declare function findingIdentitySignature(fields: FindingIdentityFields): string;
+/**
+ * Re-key finalized findings with globally-unique, content-addressed ids at the
  * synthesis boundary.
  *
  * Worker packets assign locally-scoped ids (e.g. `MNT-001`) that collide across
@@ -9,10 +56,18 @@ import type { Finding } from "../types.js";
  * findings into one block), and `work_blocks.finding_ids` / theme `finding_ids` /
  * the remediator's per-finding addressing can no longer resolve a single finding.
  *
- * The id is `<LENS_PREFIX>-<sha256(content)[:8]>`, deterministic and stable so a
- * re-synthesis of the same findings produces the same ids. A vanishingly rare
- * hash collision between two *distinct* findings is broken deterministically with
- * a numeric suffix (findings arrive in mergeFindings()' stable order).
+ * The id is `<LENS_PREFIX>-<sha256(signature)[:8]>`, where the signature comes
+ * from the deterministic fallback ladder in {@link findingIdentitySignature} —
+ * stable semantic fields only, so the same semantic finding keeps the same id
+ * across passes and re-syntheses even when volatile fields (line numbers, pass
+ * ordinals, unit ids, timestamps, title phrasing) drift. By the time findings
+ * reach this function, mergeFindings() has already collapsed every re-emission
+ * of one file-independent identity (exact normalized lens|category|title) into
+ * a single multi-file finding, and the hash never covers the merged file list,
+ * so the id also stays stable as a finding's merged file set grows. Distinct
+ * findings that share a signature (e.g. two issues anchored at the same
+ * path + scope) are disambiguated deterministically with a numeric suffix
+ * (findings arrive in mergeFindings()' stable order).
  *
  * `related_findings`, when present, referenced the old colliding ids and cannot
  * be remapped unambiguously, so it is dropped rather than left dangling. (It is

package/dist/reporting/findingIdentity.js

@@ -15,26 +15,86 @@ const LENS_ID_PREFIX = {
     config_deployment: "CFG",
     observability: "OBS",
 };
+/** Separator-normalized (always `/`), case-folded, repo-relative path. */
+function normalizeAnchorPath(path) {
+    return (path ?? "")
+        .trim()
+        .replace(/\\/g, "/")
+        .replace(/^\.\//, "")
+        .toLowerCase();
+}
+/**
+ * Aggressively normalize a title so volatile content cannot influence
+ * identity: case-folded; embedded file paths (with optional `:line[:col]`
+ * suffixes) stripped; counts, line numbers, and all other numerals stripped;
+ * punctuation collapsed; whitespace collapsed to single spaces.
+ */
+function normalizeTitle(title) {
+    return (title ?? "")
+        .toLowerCase()
+        // File paths, optionally suffixed with :line or :line:col.
+        .replace(/[\w.~-]*[\\/][\w.\\/~-]*(:\d+(:\d+)?)?/g, " ")
+        // Counts, line numbers, and any other numerals.
+        .replace(/\d+/g, " ")
+        // Collapse punctuation, then whitespace.
+        .replace(/[^a-z\s]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
 /**
- * A stable signature of a finding's identity-bearing content. The same logical
- * finding yields the same signature across runs (so its id is reproducible),
- * while two distinct findings — which only coexist after surviving merge and
- * dedup with different content — yield different signatures.
+ * The single, explicit, deterministic fallback ladder for finding identity.
+ * The same semantic finding always yields the same signature across passes
+ * and runs; the ladder consults stable semantic fields only:
+ *
+ * 1. **Structural anchor** — the repo-relative primary file path
+ *    (separator-normalized, case-folded) together with the anchor's
+ *    symbol/scope. The unit/scope is part of the hashed identity, so two
+ *    findings at the same path but different scopes get distinct ids.
+ * 2. **Rule/category** — when no structural anchor is available, the
+ *    rule/category identifier paired with the lens (the existing category
+ *    convention).
+ * 3. **Normalized title** — when neither anchor nor rule/category exists, an
+ *    aggressively normalized title (see {@link normalizeTitle}).
+ *
+ * Content-derived unit ids, line numbers, pass ordinals/pass_id, timestamps,
+ * and raw (unnormalized) titles are never part of the signature: they do not
+ * appear in {@link FindingIdentityFields}, so no tier can hash them.
+ *
+ * The signature is also independent of a finding's merged affected-file
+ * *list*: at most the single structural anchor (primary path + scope) can
+ * contribute, never the full file set, so a finding's identity stays put as
+ * mergeFindings() unions additional re-emitted files into it across passes
+ * and runs.
  */
-function contentSignature(finding) {
-    const files = finding.affected_files
-        .map((file) => `${file.path}:${file.line_start ?? ""}:${file.line_end ?? ""}:${file.symbol ?? ""}`)
-        .sort()
-        .join(",");
-    return [
-        finding.lens.trim().toLowerCase(),
-        finding.category.trim().toLowerCase(),
-        finding.title.trim().toLowerCase(),
-        files,
-    ].join("|");
+export function findingIdentitySignature(fields) {
+    // Tier 1: structural anchor (path + symbol/scope).
+    const anchorPath = normalizeAnchorPath(fields.anchor_path);
+    if (anchorPath !== "") {
+        const scope = (fields.anchor_symbol ?? "").trim();
+        return `anchor|${anchorPath}|${scope}`;
+    }
+    // Tier 2: rule/category (+ lens, the existing category convention).
+    const category = (fields.category ?? "").trim().toLowerCase();
+    if (category !== "") {
+        const lens = (fields.lens ?? "").trim().toLowerCase();
+        return `rule|${lens}|${category}`;
+    }
+    // Tier 3: aggressively normalized title.
+    return `title|${normalizeTitle(fields.title)}`;
+}
+/** Extract only the stable identity-bearing fields from a finding. */
+function identityFields(finding) {
+    const anchor = finding.affected_files[0];
+    return {
+        anchor_path: anchor?.path,
+        anchor_symbol: anchor?.symbol,
+        category: finding.category,
+        lens: finding.lens,
+        title: finding.title,
+    };
 }
 /**
- * Re-key finalized findings with globally-unique, content-derived ids at the
+ * Re-key finalized findings with globally-unique, content-addressed ids at the
  * synthesis boundary.
  *
  * Worker packets assign locally-scoped ids (e.g. `MNT-001`) that collide across
@@ -43,10 +103,18 @@ function contentSignature(finding) {
  * findings into one block), and `work_blocks.finding_ids` / theme `finding_ids` /
  * the remediator's per-finding addressing can no longer resolve a single finding.
  *
- * The id is `<LENS_PREFIX>-<sha256(content)[:8]>`, deterministic and stable so a
- * re-synthesis of the same findings produces the same ids. A vanishingly rare
- * hash collision between two *distinct* findings is broken deterministically with
- * a numeric suffix (findings arrive in mergeFindings()' stable order).
+ * The id is `<LENS_PREFIX>-<sha256(signature)[:8]>`, where the signature comes
+ * from the deterministic fallback ladder in {@link findingIdentitySignature} —
+ * stable semantic fields only, so the same semantic finding keeps the same id
+ * across passes and re-syntheses even when volatile fields (line numbers, pass
+ * ordinals, unit ids, timestamps, title phrasing) drift. By the time findings
+ * reach this function, mergeFindings() has already collapsed every re-emission
+ * of one file-independent identity (exact normalized lens|category|title) into
+ * a single multi-file finding, and the hash never covers the merged file list,
+ * so the id also stays stable as a finding's merged file set grows. Distinct
+ * findings that share a signature (e.g. two issues anchored at the same
+ * path + scope) are disambiguated deterministically with a numeric suffix
+ * (findings arrive in mergeFindings()' stable order).
  *
  * `related_findings`, when present, referenced the old colliding ids and cannot
  * be remapped unambiguously, so it is dropped rather than left dangling. (It is
@@ -57,7 +125,7 @@ export function assignStableFindingIds(findings) {
     return findings.map((finding) => {
         const prefix = LENS_ID_PREFIX[finding.lens.trim().toLowerCase()] ?? "FND";
         const hash = createHash("sha256")
-            .update(contentSignature(finding))
+            .update(findingIdentitySignature(identityFields(finding)))
             .digest("hex")
             .slice(0, 8);
         let id = `${prefix}-${hash}`;

package/dist/reporting/mergeFindings.js

@@ -34,14 +34,22 @@ function filePathOverlap(a, b) {
 function primaryPath(finding) {
     return finding.affected_files[0]?.path ?? "";
 }
+/**
+ * File-independent finding identity. Re-emissions of the same logical finding
+ * (exact normalized lens + category + title) across files, units, and passes
+ * share one key, so the exact-key merge collapses them into a single finding
+ * whose affected_files / evidence are the union of every re-emission.
+ *
+ * Cross-file merging happens ONLY on this exact equality — the fuzzy
+ * (Jaccard-title) dedup passes below stay grouped by primary path, which is
+ * what guarantees that distinct problems in different units never collapse
+ * on mere similarity.
+ */
 function findingKey(finding) {
     return [
         normalizeText(finding.lens),
         normalizeText(finding.category),
         normalizeText(finding.title),
-        primaryPath(finding),
-        String(finding.affected_files[0]?.line_start ?? ""),
-        String(finding.affected_files[0]?.line_end ?? ""),
     ].join("|");
 }
 function runtimeSummary(report) {
@@ -213,6 +221,44 @@ function relevantExternalEvidence(finding, results) {
         .filter((item) => findingPaths.has(item.path))
         .map((item) => `external:${results.tool}:${item.path}:${item.summary}`);
 }
+/**
+ * Insert a finding into the identity-keyed map, or absorb it into the existing
+ * finding with the same identity: affected_files and evidence are unioned,
+ * severity / confidence escalate to the maximum rank seen, `systemic` ORs,
+ * impact / likelihood backfill, and the longest summary wins.
+ */
+function upsertFinding(merged, finding) {
+    const key = findingKey(finding);
+    const existing = merged.get(key);
+    if (!existing) {
+        merged.set(key, {
+            ...finding,
+            affected_files: [...finding.affected_files],
+            evidence: [...(finding.evidence ?? [])],
+        });
+        return;
+    }
+    if (severityRank(finding.severity) > severityRank(existing.severity)) {
+        existing.severity = finding.severity;
+    }
+    if (confidenceRank(finding.confidence) > confidenceRank(existing.confidence)) {
+        existing.confidence = finding.confidence;
+    }
+    existing.systemic = Boolean(existing.systemic || finding.systemic);
+    existing.impact = existing.impact ?? finding.impact;
+    existing.likelihood = existing.likelihood ?? finding.likelihood;
+    existing.summary =
+        existing.summary.length >= finding.summary.length
+            ? existing.summary
+            : finding.summary;
+    mergeAffectedFiles(existing, finding);
+    existing.evidence = [
+        ...new Set([
+            ...(existing.evidence ?? []),
+            ...(finding.evidence ?? []),
+        ]),
+    ];
+}
 export function mergeFindings(results, runtimeReport, externalAnalyzerResults, designAssessment) {
     const merged = new Map();
     const allDesignFindings = [
@@ -220,45 +266,11 @@ export function mergeFindings(results, runtimeReport, externalAnalyzerResults, d
         ...(designAssessment?.review_findings ?? []),
     ];
     for (const finding of allDesignFindings) {
-        const key = findingKey(finding);
-        merged.set(key, {
-            ...finding,
-            affected_files: [...finding.affected_files],
-            evidence: [...(finding.evidence ?? [])],
-        });
+        upsertFinding(merged, finding);
     }
     for (const result of results) {
         for (const finding of result.findings) {
-            const key = findingKey(finding);
-            const existing = merged.get(key);
-            if (!existing) {
-                merged.set(key, {
-                    ...finding,
-                    affected_files: [...finding.affected_files],
-                    evidence: [...(finding.evidence ?? [])],
-                });
-                continue;
-            }
-            if (severityRank(finding.severity) > severityRank(existing.severity)) {
-                existing.severity = finding.severity;
-            }
-            if (confidenceRank(finding.confidence) > confidenceRank(existing.confidence)) {
-                existing.confidence = finding.confidence;
-            }
-            existing.systemic = Boolean(existing.systemic || finding.systemic);
-            existing.impact = existing.impact ?? finding.impact;
-            existing.likelihood = existing.likelihood ?? finding.likelihood;
-            existing.summary =
-                existing.summary.length >= finding.summary.length
-                    ? existing.summary
-                    : finding.summary;
-            mergeAffectedFiles(existing, finding);
-            existing.evidence = [
-                ...new Set([
-                    ...(existing.evidence ?? []),
-                    ...(finding.evidence ?? []),
-                ]),
-            ];
+            upsertFinding(merged, finding);
         }
     }
     for (const finding of merged.values()) {

package/dist/reporting/synthesis.js

@@ -55,10 +55,15 @@ function formatCountList(summary) {
     return parts.length > 0 ? parts.join(", ") : "none";
 }
 export function buildAuditReportModel(params) {
-    // Re-key the finalized findings with globally-unique, content-derived ids
-    // before anything addresses them by id. buildWorkBlocks keys its union-find on
-    // finding.id, so the locally-scoped, collision-prone ids worker packets emit
-    // must be replaced here or unrelated findings fuse into one block.
+    // Re-key the finalized findings with globally-unique, content-addressed ids
+    // before anything addresses them by id. mergeFindings emits exactly one
+    // finding per file-independent identity (exact normalized lens|category|
+    // title) across files, units, and passes, and assignStableFindingIds hashes
+    // only stable identity signals — never line numbers, pass ids, or the merged
+    // file list — so the same logical finding keeps one id across passes and
+    // re-syntheses. buildWorkBlocks keys its union-find on finding.id, so the
+    // locally-scoped, collision-prone ids worker packets emit must be replaced
+    // here or unrelated findings fuse into one block.
     const findings = assignStableFindingIds(mergeFindings(params.results, params.runtimeValidationReport, params.externalAnalyzerResults, params.designAssessment));
     const workBlocks = buildWorkBlocks({
         findings,

package/dist/types.d.ts

@@ -57,10 +57,20 @@ export interface FileCoverageRecord {
     lens?: Lens;
     agent_role?: string;
 }
+/** Single source of truth for coverage-matrix classification statuses (mirrors
+ * the LENS_REGISTRY-derives-Lens pattern above). The value set is
+ * {unclassified, classified} plus the audit-excluded subset of
+ * FileDispositionStatus (excluded | generated | vendor | binary | doc_only)
+ * plus the scope/trivial-audit statuses written by scope.ts
+ * (out_of_scope_delta, out_of_scope_intent) and trivialAudit.ts
+ * (excluded_trivial). schemas/coverage_matrix.schema.json must list the same
+ * enum — tests/classification-status-drift.test.mjs enforces set equality. */
+export declare const CLASSIFICATION_STATUSES: readonly ["unclassified", "classified", "excluded", "generated", "vendor", "binary", "doc_only", "out_of_scope_delta", "excluded_trivial", "out_of_scope_intent"];
+export type ClassificationStatus = (typeof CLASSIFICATION_STATUSES)[number];
 export interface CoverageFileRecord {
     path: string;
     unit_ids: string[];
-    classification_status: string;
+    classification_status: ClassificationStatus;
     audit_status: string;
     required_lenses: Lens[];
     completed_lenses: Lens[];

package/dist/types.js

@@ -26,3 +26,23 @@ export const ENABLED_LENSES = LENS_REGISTRY
 export function isLens(value) {
     return (typeof value === "string" && ALL_LENSES.includes(value));
 }
+/** Single source of truth for coverage-matrix classification statuses (mirrors
+ * the LENS_REGISTRY-derives-Lens pattern above). The value set is
+ * {unclassified, classified} plus the audit-excluded subset of
+ * FileDispositionStatus (excluded | generated | vendor | binary | doc_only)
+ * plus the scope/trivial-audit statuses written by scope.ts
+ * (out_of_scope_delta, out_of_scope_intent) and trivialAudit.ts
+ * (excluded_trivial). schemas/coverage_matrix.schema.json must list the same
+ * enum — tests/classification-status-drift.test.mjs enforces set equality. */
+export const CLASSIFICATION_STATUSES = [
+    "unclassified",
+    "classified",
+    "excluded",
+    "generated",
+    "vendor",
+    "binary",
+    "doc_only",
+    "out_of_scope_delta",
+    "excluded_trivial",
+    "out_of_scope_intent",
+];

package/dist/validation/artifacts.js

@@ -107,8 +107,21 @@ export function validateArtifactBundle(bundle) {
     }
     if (bundle.repo_manifest && bundle.file_disposition) {
         const dispositionPaths = new Set(fileDispositionEntries.map((file) => file.path));
+        // Above VCS_IGNORED_PER_FILE_LIMIT the disposition drops per-file entries
+        // for vcs-ignored files and records directory-prefix aggregates instead;
+        // a path covered by an aggregate prefix is accounted for, not missing.
+        const aggregatePrefixes = new Set(asArray(bundle.file_disposition
+            ?.vcs_ignore?.aggregates).map((aggregate) => aggregate.prefix));
+        const coveredByAggregate = (path) => {
+            if (aggregatePrefixes.size === 0)
+                return false;
+            const posix = path.replace(/\\/g, "/");
+            const slash = posix.indexOf("/");
+            const prefix = slash === -1 ? "." : posix.slice(0, slash);
+            return aggregatePrefixes.has(prefix);
+        };
         for (const path of repoPaths) {
-            if (!dispositionPaths.has(path)) {
+            if (!dispositionPaths.has(path) && !coveredByAggregate(path)) {
                 pushIssue(issues, "file_disposition", `Missing disposition entry for ${path}`);
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",

package/schemas/coverage_matrix.schema.json

@@ -18,7 +18,7 @@
           },
           "classification_status": {
             "type": "string",
-            "enum": ["unclassified", "classified", "excluded", "generated", "vendor", "binary", "doc_only"]
+            "enum": ["unclassified", "classified", "excluded", "generated", "vendor", "binary", "doc_only", "out_of_scope_delta", "excluded_trivial", "out_of_scope_intent"]
           },
           "audit_status": {
             "type": "string",

package/scripts/postinstall.mjs

@@ -85,52 +85,35 @@ const OPENCODE_AUDIT_BASH_PERMISSION = {
   'rm *': 'deny',
 };
 
-function replaceBackslashes(value) {
-  return value.replace(/\\/g, '/');
-}
-
-function renderOpenCodeExternalDirectoryPermission() {
-  return { '*': 'allow' };
-}
-
 function objectValue(value) {
   return value && typeof value === 'object' && !Array.isArray(value)
     ? value
     : {};
 }
 
-function mergeOpenCodePermissionRule(existingRule, generatedRule, managedRules = {}) {
-  if (generatedRule && typeof generatedRule === 'object' && !Array.isArray(generatedRule)) {
-    const generatedObject = generatedRule;
-    const merged = {};
-    const existingObject =
-      existingRule && typeof existingRule === 'object' && !Array.isArray(existingRule)
-        ? existingRule
-        : {};
-
-    if (typeof existingRule === 'string') {
-      merged['*'] = existingRule;
-    } else {
-      merged['*'] = existingObject['*'] ?? generatedObject['*'] ?? 'ask';
-    }
-
-    for (const [key, value] of Object.entries(generatedObject)) {
-      if (key !== '*') merged[key] = value;
-    }
-    for (const [key, value] of Object.entries(existingObject)) {
-      if (key !== '*') merged[key] = value;
-    }
-    for (const [key, value] of Object.entries(managedRules)) {
-      merged[key] = value;
-    }
-
-    return merged;
+// The scoped OpenCode permission merge helpers are single-sourced in
+// @audit-tools/shared (global top-level scope vs. auditor agent scope).
+// Resolve them best-effort: on a fresh workspace checkout the shared dist may
+// not be built yet, in which case the OpenCode config deployment below is
+// skipped with a warning instead of failing the whole install.
+let sharedOpenCodePermissions = null;
+try {
+  const shared = await import('@audit-tools/shared');
+  if (
+    typeof shared.mergeOpenCodeAgentPermissionRule === 'function' &&
+    typeof shared.mergeOpenCodeGlobalPermissionRule === 'function' &&
+    typeof shared.migrateOpenCodeGlobalExternalDirectory === 'function'
+  ) {
+    sharedOpenCodePermissions = shared;
   }
-
-  return existingRule ?? generatedRule;
+} catch {
+  // Leave null; the OpenCode deployment step reports the skip.
 }
 
-function mergeOpenCodePermissionConfig(existingPermission, generatedPermission) {
+// Auditor agent scope: broad-allow-with-denylist, unchanged. Managed rules
+// (including the wildcard) always win at this scope.
+function mergeOpenCodeAgentPermissionConfig(existingPermission, generatedPermission) {
+  const { mergeOpenCodeAgentPermissionRule } = sharedOpenCodePermissions;
   if (!existingPermission || typeof existingPermission !== 'object' || Array.isArray(existingPermission)) {
     return generatedPermission;
   }
@@ -141,17 +124,17 @@ function mergeOpenCodePermissionConfig(existingPermission, generatedPermission)
     read: generatedPermission.read,
     glob: generatedPermission.glob,
     grep: generatedPermission.grep,
-    external_directory: mergeOpenCodePermissionRule(
+    external_directory: mergeOpenCodeAgentPermissionRule(
       existingPermission.external_directory,
       generatedPermission.external_directory,
       OPENCODE_AUDIT_EXTERNAL_DIRECTORY_PERMISSION,
     ),
-    edit: mergeOpenCodePermissionRule(
+    edit: mergeOpenCodeAgentPermissionRule(
       existingPermission.edit,
       generatedPermission.edit,
       OPENCODE_AUDIT_EDIT_PERMISSION,
     ),
-    bash: mergeOpenCodePermissionRule(
+    bash: mergeOpenCodeAgentPermissionRule(
       existingPermission.bash,
       generatedPermission.bash,
       OPENCODE_AUDIT_BASH_PERMISSION,
@@ -159,12 +142,52 @@ function mergeOpenCodePermissionConfig(existingPermission, generatedPermission)
   };
 }
 
+// Global top-level scope: never seeds bash['*']='allow' or
+// external_directory['*']='allow', keeps the denylist hygiene rules, and
+// migrates away previously deployed broad rules whose value exactly matches
+// the historically managed value ('allow'). Non-matching values are untouched.
+function mergeOpenCodeGlobalPermissionConfig(existingPermission, generatedPermission) {
+  const {
+    mergeOpenCodeAgentPermissionRule,
+    mergeOpenCodeGlobalPermissionRule,
+    migrateOpenCodeGlobalExternalDirectory,
+  } = sharedOpenCodePermissions;
+  const existing = objectValue(existingPermission);
+
+  const merged = {
+    ...generatedPermission,
+    ...existing,
+    read: generatedPermission.read,
+    glob: generatedPermission.glob,
+    grep: generatedPermission.grep,
+    edit: mergeOpenCodeAgentPermissionRule(
+      existing.edit,
+      generatedPermission.edit,
+      OPENCODE_AUDIT_EDIT_PERMISSION,
+    ),
+    bash: mergeOpenCodeGlobalPermissionRule(
+      existing.bash,
+      generatedPermission.bash,
+      OPENCODE_AUDIT_BASH_PERMISSION,
+    ),
+  };
+
+  const externalDirectory = migrateOpenCodeGlobalExternalDirectory(existing.external_directory);
+  if (externalDirectory === undefined) {
+    delete merged.external_directory;
+  } else {
+    merged.external_directory = externalDirectory;
+  }
+
+  return merged;
+}
+
 function renderOpenCodePermissionConfig() {
   return {
     read: 'allow',
     glob: 'allow',
     grep: 'allow',
-    external_directory: renderOpenCodeExternalDirectoryPermission(),
+    external_directory: { ...OPENCODE_AUDIT_EXTERNAL_DIRECTORY_PERMISSION },
     edit: { ...OPENCODE_AUDIT_EDIT_PERMISSION },
     bash: { ...OPENCODE_AUDIT_BASH_PERMISSION },
   };
@@ -190,10 +213,7 @@ function mergeOpenCodeGlobalConfig(existing) {
         subtask: false,
       },
     },
-    permission: {
-      ...mergeOpenCodePermissionConfig(parsed.permission, auditPermission),
-      external_directory: { '*': 'allow' },
-    },
+    permission: mergeOpenCodeGlobalPermissionConfig(parsed.permission, auditPermission),
     agent: {
       ...(parsed.agent && typeof parsed.agent === 'object' && !Array.isArray(parsed.agent)
         ? parsed.agent
@@ -202,7 +222,7 @@ function mergeOpenCodeGlobalConfig(existing) {
         ...existingAuditor,
         description: 'Read-heavy audit orchestration agent for the /audit-code workflow.',
         permission: {
-          ...mergeOpenCodePermissionConfig(existingAuditor.permission, auditPermission),
+          ...mergeOpenCodeAgentPermissionConfig(existingAuditor.permission, auditPermission),
           external_directory: { '*': 'allow' },
           'auditor_*': 'allow',
           question: 'allow',
@@ -288,6 +308,11 @@ for (const install of installs) {
 // Install OpenCode global command and MCP via merged config
 const opencodeGlobalConfig = join(homedir(), '.config', 'opencode', 'opencode.json');
 try {
+  if (!sharedOpenCodePermissions) {
+    throw new Error(
+      '@audit-tools/shared is unavailable (build the shared workspace first); skipping OpenCode config deployment',
+    );
+  }
   const action = installMergedJson(opencodeGlobalConfig, (existing) =>
     mergeOpenCodeGlobalConfig(existing),
   );