audit-tools 0.28.0

package/dist/remediate/dispatch/amendmentClaim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"amendmentClaim.js","sourceRoot":"","sources":["../../../src/remediate/dispatch/amendmentClaim.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAA2B,EAC3B,MAAc,EACd,cAAwB;IAKxB,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,WAAW,GAA0D,EAAE,CAAC;IAE9E,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAClC,MAAM,OAAO,GAAG,QAAQ,CAAC,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAEtD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnB,SAAS;QACX,CAAC;QAED,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;YACxB,MAAM,aAAa,GAAG,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC;YAChE,MAAM,KAAK,GAAyB,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;YAC9E,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;YAC1C,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,IAAI,CAAC,SAAS,CAAC;gBACb,KAAK,EAAE,MAAM;gBACb,KAAK,EAAE,uBAAuB;gBAC9B,OAAO,EAAE,MAAM;gBACf,IAAI;gBACJ,OAAO,EAAE,OAAO;gBAChB,aAAa;gBACb,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aAC7B,CAAC,GAAG,IAAI,CACV,CAAC;YACF,SAAS;QACX,CAAC;QAED,YAAY;QACZ,MAAM,eAAe,GAAG,QAAQ,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC;QACtE,MAAM,KAAK,GAAyB,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;QACpF,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1C,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,IAAI,CAAC,SAAS,CAAC;YACb,KAAK,EAAE,MAAM;YACb,KAAK,EAAE,uBAAuB;YAC9B,OAAO,EAAE,MAAM;YACf,IAAI;YACJ,OAAO,EAAE,WAAW;YACpB,eAAe;YACf,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SAC7B,CAAC,GAAG,IAAI,CACV,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;AAClC,CAAC"}

package/dist/remediate/dispatch/ownershipRegistry.d.ts

@@ -0,0 +1,97 @@
+/**
+ * OwnershipRegistry — tracks which DAG node owns which file paths (write-scope
+ * declared in its contract). Used by the rolling-dispatch loop to gate
+ * amendment claims: a worker that discovers a necessary edit outside its declared
+ * contract scope may unilaterally extend write-scope ONLY into unowned files.
+ *
+ * Atomicity: claim registration is a synchronous in-memory CAS within a
+ * single-threaded orchestrator (no TOCTOU). The registry is checkpointed to
+ * `dispatch/ownership-registry.json` after each mutation so it survives a restart.
+ * Stale in-flight claims (node ID not in the current implementation DAG) are
+ * purged on load.
+ */
+export interface OwnershipRegistryJson {
+    /** nodeId → set of paths from that node's original contract scope */
+    contractScopes: Record<string, string[]>;
+    /** nodeId → set of in-flight amendment claims (dispatched but not yet merged) */
+    amendmentClaims: Record<string, string[]>;
+}
+/**
+ * OwnershipRegistry tracks write-scope ownership per DAG node.
+ *
+ * Initialization:
+ *   const registry = new OwnershipRegistry(checkpointPath);
+ *   registry.initialize(dagNodes);   // call once before dispatching
+ *
+ * Per-node lifecycle:
+ *   const claim = registry.claimAmendment(nodeId, path);
+ *   // on merge or triage:
+ *   registry.releaseAmendments(nodeId);
+ */
+export declare class OwnershipRegistry {
+    /** nodeId → paths from the node's original contract scope */
+    private contractScopes;
+    /**
+     * path → nodeId: which live parallel sibling (dispatched, not yet merged) has
+     * claimed this path via an amendment.
+     */
+    private amendmentClaims;
+    /** Optional path for checkpoint persistence. When provided, every mutation
+     * atomically writes the registry state to this path. */
+    private checkpointPath;
+    constructor(checkpointPath?: string);
+    /**
+     * Initialize the registry from the implementation DAG nodes. Each node's
+     * `affected_files` (or `write_paths`) constitutes its contract scope.
+     * Call once before any node is dispatched.
+     */
+    initialize(nodes: Array<{
+        node_id: string;
+        affected_files?: string[];
+        write_paths?: string[];
+    }>): void;
+    /**
+     * Attempt to claim `path` for `nodeId` as an amendment (write outside the
+     * node's original contract scope).
+     *
+     * Returns:
+     *  - `'granted'`    — path was unowned and uncontended; claim is recorded.
+     *  - `'owned'`      — path is in another node's contract scope; routes to seam protocol.
+     *  - `'contended'`  — path has been claimed by a live parallel sibling; routes to seam protocol.
+     */
+    claimAmendment(nodeId: string, path: string): "granted" | "owned" | "contended";
+    /**
+     * Release all amendment claims for `nodeId`. Call when a node finishes
+     * (merge or triage). Makes the previously claimed files available again.
+     */
+    releaseAmendments(nodeId: string): void;
+    /**
+     * Returns the union of the node's original contract `affected_files` and its
+     * granted amendment claims — used to re-derive the write-scope for verification
+     * and blast-radius attribution.
+     */
+    getScope(nodeId: string): string[];
+    /**
+     * Return the node ID that owns this path via contract scope, or undefined if
+     * the path is unowned.
+     */
+    contractOwner(path: string): string | undefined;
+    /**
+     * Return the node ID that has an in-flight amendment claim for this path, or
+     * undefined if uncontended.
+     */
+    amendmentClaimant(path: string): string | undefined;
+    /** Serialize to a plain JSON-safe object. */
+    serialize(): OwnershipRegistryJson;
+    /**
+     * Restore an OwnershipRegistry from a serialized JSON object.
+     * `knownNodeIds` is the set of node IDs in the current implementation DAG;
+     * any in-flight amendment claim for a node NOT in this set is purged (stale).
+     */
+    static fromJson(json: OwnershipRegistryJson, knownNodeIds: Set<string>, checkpointPath?: string): OwnershipRegistry;
+    /** Write checkpoint synchronously after each mutation. */
+    private _persist;
+    /** Load from a checkpoint file; returns undefined if the file doesn't exist or can't be parsed. */
+    static loadFromCheckpoint(checkpointPath: string, knownNodeIds: Set<string>): OwnershipRegistry | undefined;
+}
+//# sourceMappingURL=ownershipRegistry.d.ts.map

package/dist/remediate/dispatch/ownershipRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownershipRegistry.d.ts","sourceRoot":"","sources":["../../../src/remediate/dispatch/ownershipRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACzC,iFAAiF;IACjF,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAiB;IAC5B,6DAA6D;IAC7D,OAAO,CAAC,cAAc,CAAuC;IAE7D;;;OAGG;IACH,OAAO,CAAC,eAAe,CAAkC;IAEzD;4DACwD;IACxD,OAAO,CAAC,cAAc,CAAqB;gBAE/B,cAAc,CAAC,EAAE,MAAM;IAInC;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,GAAG,IAAI;IAUtG;;;;;;;;OAQG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW;IAoB/E;;;OAGG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAavC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAWlC;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAO/C;;;OAGG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAInD,6CAA6C;IAC7C,SAAS,IAAI,qBAAqB;IAkBlC;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CACb,IAAI,EAAE,qBAAqB,EAC3B,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,EACzB,cAAc,CAAC,EAAE,MAAM,GACtB,iBAAiB;IAqBpB,0DAA0D;IAC1D,OAAO,CAAC,QAAQ;IAqBhB,mGAAmG;IACnG,MAAM,CAAC,kBAAkB,CACvB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,GACxB,iBAAiB,GAAG,SAAS;CAuBjC"}

package/dist/remediate/dispatch/ownershipRegistry.js

@@ -0,0 +1,217 @@
+/**
+ * OwnershipRegistry — tracks which DAG node owns which file paths (write-scope
+ * declared in its contract). Used by the rolling-dispatch loop to gate
+ * amendment claims: a worker that discovers a necessary edit outside its declared
+ * contract scope may unilaterally extend write-scope ONLY into unowned files.
+ *
+ * Atomicity: claim registration is a synchronous in-memory CAS within a
+ * single-threaded orchestrator (no TOCTOU). The registry is checkpointed to
+ * `dispatch/ownership-registry.json` after each mutation so it survives a restart.
+ * Stale in-flight claims (node ID not in the current implementation DAG) are
+ * purged on load.
+ */
+import { writeFileSync, readFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * OwnershipRegistry tracks write-scope ownership per DAG node.
+ *
+ * Initialization:
+ *   const registry = new OwnershipRegistry(checkpointPath);
+ *   registry.initialize(dagNodes);   // call once before dispatching
+ *
+ * Per-node lifecycle:
+ *   const claim = registry.claimAmendment(nodeId, path);
+ *   // on merge or triage:
+ *   registry.releaseAmendments(nodeId);
+ */
+export class OwnershipRegistry {
+    /** nodeId → paths from the node's original contract scope */
+    contractScopes = new Map();
+    /**
+     * path → nodeId: which live parallel sibling (dispatched, not yet merged) has
+     * claimed this path via an amendment.
+     */
+    amendmentClaims = new Map();
+    /** Optional path for checkpoint persistence. When provided, every mutation
+     * atomically writes the registry state to this path. */
+    checkpointPath;
+    constructor(checkpointPath) {
+        this.checkpointPath = checkpointPath;
+    }
+    /**
+     * Initialize the registry from the implementation DAG nodes. Each node's
+     * `affected_files` (or `write_paths`) constitutes its contract scope.
+     * Call once before any node is dispatched.
+     */
+    initialize(nodes) {
+        this.contractScopes.clear();
+        this.amendmentClaims.clear();
+        for (const node of nodes) {
+            const paths = node.affected_files ?? node.write_paths ?? [];
+            this.contractScopes.set(node.node_id, new Set(paths));
+        }
+        this._persist();
+    }
+    /**
+     * Attempt to claim `path` for `nodeId` as an amendment (write outside the
+     * node's original contract scope).
+     *
+     * Returns:
+     *  - `'granted'`    — path was unowned and uncontended; claim is recorded.
+     *  - `'owned'`      — path is in another node's contract scope; routes to seam protocol.
+     *  - `'contended'`  — path has been claimed by a live parallel sibling; routes to seam protocol.
+     */
+    claimAmendment(nodeId, path) {
+        // Check if path is in any OTHER node's contract scope.
+        for (const [scopeNodeId, scopePaths] of this.contractScopes) {
+            if (scopeNodeId !== nodeId && scopePaths.has(path)) {
+                return "owned";
+            }
+        }
+        // Check if path has already been amendment-claimed by a live parallel sibling.
+        const existingClaimant = this.amendmentClaims.get(path);
+        if (existingClaimant !== undefined && existingClaimant !== nodeId) {
+            return "contended";
+        }
+        // Grant: record the claim.
+        this.amendmentClaims.set(path, nodeId);
+        this._persist();
+        return "granted";
+    }
+    /**
+     * Release all amendment claims for `nodeId`. Call when a node finishes
+     * (merge or triage). Makes the previously claimed files available again.
+     */
+    releaseAmendments(nodeId) {
+        let changed = false;
+        for (const [path, claimant] of this.amendmentClaims) {
+            if (claimant === nodeId) {
+                this.amendmentClaims.delete(path);
+                changed = true;
+            }
+        }
+        if (changed) {
+            this._persist();
+        }
+    }
+    /**
+     * Returns the union of the node's original contract `affected_files` and its
+     * granted amendment claims — used to re-derive the write-scope for verification
+     * and blast-radius attribution.
+     */
+    getScope(nodeId) {
+        const contractPaths = this.contractScopes.get(nodeId) ?? new Set();
+        const amendmentPaths = [];
+        for (const [path, claimant] of this.amendmentClaims) {
+            if (claimant === nodeId) {
+                amendmentPaths.push(path);
+            }
+        }
+        return [...contractPaths, ...amendmentPaths];
+    }
+    /**
+     * Return the node ID that owns this path via contract scope, or undefined if
+     * the path is unowned.
+     */
+    contractOwner(path) {
+        for (const [nodeId, scopePaths] of this.contractScopes) {
+            if (scopePaths.has(path))
+                return nodeId;
+        }
+        return undefined;
+    }
+    /**
+     * Return the node ID that has an in-flight amendment claim for this path, or
+     * undefined if uncontended.
+     */
+    amendmentClaimant(path) {
+        return this.amendmentClaims.get(path);
+    }
+    /** Serialize to a plain JSON-safe object. */
+    serialize() {
+        const contractScopes = {};
+        for (const [nodeId, paths] of this.contractScopes) {
+            contractScopes[nodeId] = [...paths];
+        }
+        const amendmentClaims = {};
+        // Group by nodeId for storage: Record<nodeId, path[]>
+        const byNode = new Map();
+        for (const [path, nodeId] of this.amendmentClaims) {
+            if (!byNode.has(nodeId))
+                byNode.set(nodeId, []);
+            byNode.get(nodeId).push(path);
+        }
+        for (const [nodeId, paths] of byNode) {
+            amendmentClaims[nodeId] = paths;
+        }
+        return { contractScopes, amendmentClaims };
+    }
+    /**
+     * Restore an OwnershipRegistry from a serialized JSON object.
+     * `knownNodeIds` is the set of node IDs in the current implementation DAG;
+     * any in-flight amendment claim for a node NOT in this set is purged (stale).
+     */
+    static fromJson(json, knownNodeIds, checkpointPath) {
+        const registry = new OwnershipRegistry(checkpointPath);
+        for (const [nodeId, paths] of Object.entries(json.contractScopes)) {
+            registry.contractScopes.set(nodeId, new Set(paths));
+        }
+        // Restore amendment claims; purge stale ones whose node is no longer in DAG.
+        for (const [nodeId, paths] of Object.entries(json.amendmentClaims)) {
+            if (!knownNodeIds.has(nodeId)) {
+                // Stale node — drop all its amendment claims.
+                continue;
+            }
+            for (const path of paths) {
+                registry.amendmentClaims.set(path, nodeId);
+            }
+        }
+        return registry;
+    }
+    /** Write checkpoint synchronously after each mutation. */
+    _persist() {
+        if (!this.checkpointPath)
+            return;
+        const json = JSON.stringify(this.serialize(), null, 2) + "\n";
+        try {
+            mkdirSync(dirname(this.checkpointPath), { recursive: true });
+            writeFileSync(this.checkpointPath, json, "utf8");
+        }
+        catch (err) {
+            // Best-effort: a checkpoint write failure must not crash the orchestrator.
+            process.stderr.write(JSON.stringify({
+                level: "warn",
+                event: "ownership_registry_persist_failed",
+                path: this.checkpointPath,
+                code: err.code ?? null,
+                message: String(err),
+                ts: new Date().toISOString(),
+            }) + "\n");
+        }
+    }
+    /** Load from a checkpoint file; returns undefined if the file doesn't exist or can't be parsed. */
+    static loadFromCheckpoint(checkpointPath, knownNodeIds) {
+        let raw;
+        try {
+            raw = readFileSync(checkpointPath, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+        let json;
+        try {
+            json = JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+        if (typeof json !== "object" ||
+            json === null ||
+            !("contractScopes" in json) ||
+            !("amendmentClaims" in json)) {
+            return undefined;
+        }
+        return OwnershipRegistry.fromJson(json, knownNodeIds, checkpointPath);
+    }
+}
+//# sourceMappingURL=ownershipRegistry.js.map

package/dist/remediate/dispatch/ownershipRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownershipRegistry.js","sourceRoot":"","sources":["../../../src/remediate/dispatch/ownershipRegistry.ts"],"names":[],"mappings":"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"}

package/dist/remediate/findingFilter.d.ts

@@ -0,0 +1,42 @@
+import type { Finding, IntentCheckpoint } from "audit-tools/shared";
+import { type GroundExtractedFindingsOptions } from "./phases/grounding.js";
+/** Survivors plus every pre-planning disposition, in `buildCoverageLedger` shape. */
+export interface FindingFilterResult {
+    /** Findings that survive every filter — the set the preview shows and the pipeline acts on. */
+    survivors: Finding[];
+    /** Cross-lens dedup map: absorbed finding id → surviving canonical finding id. */
+    mergeMap: Map<string, string>;
+    /** Ids dropped for carrying no evidence. */
+    droppedNoEvidence: string[];
+    /** Ids dropped because every cited path was phantom, with the phantom paths. */
+    droppedPhantomPaths: Map<string, string[]>;
+    /** Phantom paths stripped from surviving findings (kept, not dropped). */
+    phantomPathsRemoved: Map<string, string[]>;
+    /** Ids dropped by the intent checkpoint (filters / excluded scope). */
+    droppedByCheckpoint: string[];
+}
+export interface RunFindingFilterPassOptions {
+    root: string;
+    /** Confirmed intent checkpoint; absent/draft/no-constraints keeps everything. */
+    checkpoint?: IntentCheckpoint;
+    /**
+     * Passed through to grounding: set false for findings grounded by construction
+     * (contract-pipeline obligation evidence) rather than by path citation. Path
+     * grounding still runs. Defaults to true (original audit findings cite paths).
+     */
+    evidenceGrounding?: boolean;
+    /** Optional one-shot repair for all-phantom findings (see groundExtractedFindings). */
+    repairZeroPathFindings?: GroundExtractedFindingsOptions["repairZeroPathFindings"];
+}
+/**
+ * Run the canonical pre-planning filter chain once, in the established order:
+ *   1. drop findings with no evidence,
+ *   2. cross-lens dedup (fold duplicates a different lens flagged independently),
+ *   3. phantom-path grounding (strip non-existent paths; drop all-phantom findings),
+ *   4. intent-checkpoint exclusion (severity/lens/package/theme/scope filters).
+ *
+ * Returns the survivors and the full disposition record. Operates on findings
+ * only — block pruning is the caller's job (prune to `survivors` once at the end).
+ */
+export declare function runFindingFilterPass(findings: Finding[], options: RunFindingFilterPassOptions): Promise<FindingFilterResult>;
+//# sourceMappingURL=findingFilter.d.ts.map

package/dist/remediate/findingFilter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findingFilter.d.ts","sourceRoot":"","sources":["../../src/remediate/findingFilter.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEpE,OAAO,EAEL,KAAK,8BAA8B,EACpC,MAAM,uBAAuB,CAAC;AAG/B,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC,+FAA+F;IAC/F,SAAS,EAAE,OAAO,EAAE,CAAC;IACrB,kFAAkF;IAClF,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,4CAA4C;IAC5C,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,gFAAgF;IAChF,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3C,0EAA0E;IAC1E,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3C,uEAAuE;IACvE,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uFAAuF;IACvF,sBAAsB,CAAC,EAAE,8BAA8B,CAAC,wBAAwB,CAAC,CAAC;CACnF;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,mBAAmB,CAAC,CAsC9B"}

package/dist/remediate/findingFilter.js

@@ -0,0 +1,62 @@
+// Single finding-filter pass (review-gate convergence, chunk A).
+//
+// The pre-planning filters — no-evidence drop, cross-lens dedup, phantom-path
+// grounding, intent-checkpoint exclusion — historically ran in two different
+// places with two different orderings: `runPlanPhase` (document/conversation
+// path) ran them inline up front, while the structured-audit/contract-pipeline
+// path ran dedup + grounding LATE, after the pipeline collapsed findings into DAG
+// nodes, and never applied the checkpoint at all. That split is why the review
+// preview could show findings that were about to be deduped/dropped.
+//
+// This is the ONE pass: run it once, on a finding set, BEFORE the review preview,
+// so the preview shows exactly the survivors and the dispositions feed the
+// coverage ledger verbatim. Its output shape is the `buildCoverageLedger`
+// disposition inputs (minus planId/items), so the ledger never has to recompute
+// any of it.
+//
+// Pure-ish: deterministic given the same findings + checkpoint + disk state; the
+// only IO is phantom-path existence checks (via groundExtractedFindings).
+import { deduplicateCrossLensFindings } from "./dedup/crossLensDedup.js";
+import { groundExtractedFindings, } from "./phases/grounding.js";
+import { filterFindingsByCheckpoint } from "./intent/checkpointFilter.js";
+/**
+ * Run the canonical pre-planning filter chain once, in the established order:
+ *   1. drop findings with no evidence,
+ *   2. cross-lens dedup (fold duplicates a different lens flagged independently),
+ *   3. phantom-path grounding (strip non-existent paths; drop all-phantom findings),
+ *   4. intent-checkpoint exclusion (severity/lens/package/theme/scope filters).
+ *
+ * Returns the survivors and the full disposition record. Operates on findings
+ * only — block pruning is the caller's job (prune to `survivors` once at the end).
+ */
+export async function runFindingFilterPass(findings, options) {
+    // 1. No-evidence drop.
+    const droppedNoEvidence = findings
+        .filter((f) => !Array.isArray(f.evidence) || f.evidence.length === 0)
+        .map((f) => f.id);
+    let kept = findings.filter((f) => Array.isArray(f.evidence) && f.evidence.length > 0);
+    // 2. Cross-lens dedup.
+    const dedup = deduplicateCrossLensFindings(kept);
+    kept = dedup.findings;
+    // 3. Phantom-path grounding.
+    const grounding = await groundExtractedFindings(kept, {
+        root: options.root,
+        evidenceGrounding: options.evidenceGrounding ?? true,
+        ...(options.repairZeroPathFindings
+            ? { repairZeroPathFindings: options.repairZeroPathFindings }
+            : {}),
+    });
+    kept = grounding.findings;
+    // 4. Intent-checkpoint exclusion.
+    const { kept: checkpointKept, droppedIds: droppedByCheckpoint } = filterFindingsByCheckpoint(kept, options.checkpoint);
+    kept = checkpointKept;
+    return {
+        survivors: kept,
+        mergeMap: dedup.mergeMap,
+        droppedNoEvidence,
+        droppedPhantomPaths: new Map(grounding.dropped.map((d) => [d.finding.id, d.phantomPaths])),
+        phantomPathsRemoved: grounding.phantomPathsByFinding,
+        droppedByCheckpoint,
+    };
+}
+//# sourceMappingURL=findingFilter.js.map

package/dist/remediate/findingFilter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findingFilter.js","sourceRoot":"","sources":["../../src/remediate/findingFilter.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,6EAA6E;AAC7E,+EAA+E;AAC/E,kFAAkF;AAClF,+EAA+E;AAC/E,qEAAqE;AACrE,EAAE;AACF,kFAAkF;AAClF,2EAA2E;AAC3E,0EAA0E;AAC1E,gFAAgF;AAChF,aAAa;AACb,EAAE;AACF,iFAAiF;AACjF,0EAA0E;AAG1E,OAAO,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EACL,uBAAuB,GAExB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAgC1E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,QAAmB,EACnB,OAAoC;IAEpC,uBAAuB;IACvB,MAAM,iBAAiB,GAAG,QAAQ;SAC/B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC;SACpE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpB,IAAI,IAAI,GAAG,QAAQ,CAAC,MAAM,CACxB,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAC1D,CAAC;IAEF,uBAAuB;IACvB,MAAM,KAAK,GAAG,4BAA4B,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC;IAEtB,6BAA6B;IAC7B,MAAM,SAAS,GAAG,MAAM,uBAAuB,CAAC,IAAI,EAAE;QACpD,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,IAAI,IAAI;QACpD,GAAG,CAAC,OAAO,CAAC,sBAAsB;YAChC,CAAC,CAAC,EAAE,sBAAsB,EAAE,OAAO,CAAC,sBAAsB,EAAE;YAC5D,CAAC,CAAC,EAAE,CAAC;KACR,CAAC,CAAC;IACH,IAAI,GAAG,SAAS,CAAC,QAAQ,CAAC;IAE1B,kCAAkC;IAClC,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,UAAU,EAAE,mBAAmB,EAAE,GAC7D,0BAA0B,CAAC,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IACvD,IAAI,GAAG,cAAc,CAAC;IAEtB,OAAO;QACL,SAAS,EAAE,IAAI;QACf,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,iBAAiB;QACjB,mBAAmB,EAAE,IAAI,GAAG,CAC1B,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,CAC7D;QACD,mBAAmB,EAAE,SAAS,CAAC,qBAAqB;QACpD,mBAAmB;KACpB,CAAC;AACJ,CAAC"}

package/dist/remediate/index.d.ts

@@ -0,0 +1,45 @@
+import { Command } from "commander";
+import { runCommand } from "./utils/commands.js";
+declare const program: Command;
+export { program };
+/**
+ * Parse argv through the program after normalizing the `=value` form of the
+ * tristate `--host-can-dispatch-subagents` boolean into commander's bare /
+ * negatable forms. Commander treats `--flag=value` on a value-less boolean as an
+ * unknown option, so `--host-can-dispatch-subagents=true|false` is rewritten to
+ * the bare flag / `--no-` flag here. This keeps the flag a true boolean (a bare
+ * flag never swallows the next token) while still accepting the `=false` spelling.
+ */
+export declare function parseProgram(argv: string[]): void;
+/**
+ * Rewrite `<flag>=true` → `<flag>` and `<flag>=false` → `--no-<flag>` so a
+ * value-less commander boolean can still be set false via the `=` spelling. A
+ * non-boolean `<flag>=<other>` value fails loudly rather than silently defaulting.
+ */
+export declare function normalizeBooleanFlagArgv(argv: string[], flag: string): string[];
+/**
+ * Single-step bootstrap writer for `intake/conversation-start.md`.
+ *
+ * Sole writer + idempotent-on-target (INV-CC-03): re-applying the identical
+ * guidance is a byte-identical no-op (the existing file is left untouched, never
+ * appended to), and a pre-existing file with DIFFERING content is never silently
+ * clobbered — that case fails loudly so host/conversation-authored guidance can't
+ * be lost. The guidance file's bytes are written verbatim.
+ */
+export declare function applyGuidanceFile(artifactsDir: string, guidanceFilePath: string): string;
+/**
+ * Resolve the remediation artifacts dir. An explicit `--artifacts-dir` is
+ * honored verbatim; the unchanged commander default (`.audit-tools/remediation`)
+ * rebases onto `--root` via the shared `remediationArtifactsDir()` helper, so
+ * `--root <X>` lands the default under `<X>/.audit-tools/remediation`. The
+ * `.audit-tools/...` join literal lives only in the shared path module.
+ */
+export declare function resolveArtifactsDirOption(root: string, artifactsDir: string): string;
+export declare function runValidateCommand(deps?: {
+    run?: typeof runCommand;
+    log?: (message: string) => void;
+    error?: (message: string) => void;
+}): number;
+export declare function installRepoAssets(root: string, quiet: boolean, log?: (msg: string) => void, homeDir?: string): void;
+export declare function ensureGlobalAssets(quiet: boolean, log?: (msg: string) => void, homeDir?: string, root?: string): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/remediate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/remediate/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAoDjD,QAAA,MAAM,OAAO,SAAgB,CAAC;AA2R9B,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAEjD;AAUD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAU/E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,GACvB,MAAM,CAuBR;AAYD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GACnB,MAAM,CAIR;AAED,wBAAgB,kBAAkB,CAChC,IAAI,GAAE;IACJ,GAAG,CAAC,EAAE,OAAO,UAAU,CAAC;IACxB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B,GACL,MAAM,CAcR;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAkB,EACxC,OAAO,SAAY,GAClB,IAAI,CAQN;AA4FD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAkB,EACxC,OAAO,SAAY,EACnB,IAAI,SAAgB,GACnB,IAAI,CA4EN"}