audit-tools 0.41.1 → 0.42.1

package/dist/shared/decompose/contentCoherence.d.ts

@@ -15,6 +15,39 @@ export declare const CONTENT_COHERENCE_SCORES: Readonly<{
     readonly shared_unit: 80;
 }>;
 export declare const CONTENT_COHERENCE_THRESHOLD = 60;
+/**
+ * Which pairs may join at all — the ONE policy axis of the shared core, never a
+ * fork. Both draws run the identical scan, union-find, and canonical ordering;
+ * they differ only in this predicate and in {@link ContentCoherencePolicy.refineAtModularityPeak}.
+ *
+ * - `weighted_score_threshold` — a pair joins when its summed evidence weight
+ *   reaches {@link CONTENT_COHERENCE_THRESHOLD}. Disjunctive: four of the six
+ *   classes clear 60 alone.
+ * - `shared_file_and_same_lens` — a pair joins only when it shares a FILE **and**
+ *   a lens. Measured on the promoted 2026-08-18 run (3,230 findings): the
+ *   threshold rule left 99.97% of findings in a single component, and no
+ *   class-COUNT variant fixed it, because `shared_unit`/`same_lens`/`same_directory`
+ *   are near-vacuous partitions at audit scale. The conjunction bounds by
+ *   STRUCTURE, not density — `same_lens` is a hard partition no edge may cross.
+ */
+export type ContentCoherenceEligibility = "weighted_score_threshold" | "shared_file_and_same_lens";
+/** The per-draw policy. Every difference between the draws lands here. */
+export interface ContentCoherencePolicy {
+    readonly eligibility: ContentCoherenceEligibility;
+    /**
+     * Refine each eligible-edge component at its modularity peak (below), so a
+     * loose component splits at its own data-derived thin seam while a true clique
+     * survives whole. No budget, ceiling, or size target participates.
+     */
+    readonly refineAtModularityPeak: boolean;
+}
+/**
+ * The audit TASK draw. Unmeasured for collapse — its eligibility is deliberately
+ * left as-is until it is measured on its own lap (`docs/backlog/open-bugs.md`).
+ */
+export declare const TASK_DRAW_COHERENCE_POLICY: ContentCoherencePolicy;
+/** The FINDINGS draw (work blocks + the findings deliverable). Owner cut, 2026-08-19. */
+export declare const FINDINGS_DRAW_COHERENCE_POLICY: ContentCoherencePolicy;
 export type ContentCoherenceEvidence = {
     -readonly [Kind in keyof typeof CONTENT_COHERENCE_SCORES]: boolean;
 };
@@ -43,52 +76,10 @@ export interface NormalizedContentCoherenceItem {
     tags: string[];
     critical_flow_ids?: string[];
 }
-export interface ContentCoherencePairScore {
-    left: string;
-    right: string;
-    evidence: ContentCoherenceEvidence;
-    score: number;
-    eligible: boolean;
-}
-export interface ContentCoherenceCandidate {
-    left: string;
-    right: string;
-    score: number;
-}
-export interface ContentCoherenceMergeTraceEntry extends ContentCoherenceCandidate {
-    decision: "merge" | "already_connected";
-    root: string;
-}
 export interface ContentCoherenceTrace {
     normalized_items: NormalizedContentCoherenceItem[];
-    pair_scores: ContentCoherencePairScore[];
-    eligible_candidates: ContentCoherenceCandidate[];
-    merge_trace: ContentCoherenceMergeTraceEntry[];
-    merge_decisions: Array<ContentCoherenceMergeTraceEntry["decision"]>;
     components: string[][];
 }
-export declare const ContentCoherenceEvidenceSchema: z.ZodObject<{
-    call_import_reference_adjacency: z.ZodBoolean;
-    same_directory: z.ZodBoolean;
-    shared_critical_flow: z.ZodBoolean;
-    shared_file: z.ZodBoolean;
-    shared_semantic_tag_or_same_lens: z.ZodBoolean;
-    shared_unit: z.ZodBoolean;
-}, "strict", z.ZodTypeAny, {
-    call_import_reference_adjacency: boolean;
-    same_directory: boolean;
-    shared_critical_flow: boolean;
-    shared_file: boolean;
-    shared_semantic_tag_or_same_lens: boolean;
-    shared_unit: boolean;
-}, {
-    call_import_reference_adjacency: boolean;
-    same_directory: boolean;
-    shared_critical_flow: boolean;
-    shared_file: boolean;
-    shared_semantic_tag_or_same_lens: boolean;
-    shared_unit: boolean;
-}>;
 export declare const NormalizedContentCoherenceItemSchema: z.ZodObject<{
     id: z.ZodString;
     file_paths: z.ZodArray<z.ZodString, "many">;
@@ -108,93 +99,6 @@ export declare const NormalizedContentCoherenceItemSchema: z.ZodObject<{
     tags: string[];
     critical_flow_ids?: string[] | undefined;
 }>;
-export declare const ContentCoherencePairScoreSchema: z.ZodObject<{
-    left: z.ZodString;
-    right: z.ZodString;
-    evidence: z.ZodObject<{
-        call_import_reference_adjacency: z.ZodBoolean;
-        same_directory: z.ZodBoolean;
-        shared_critical_flow: z.ZodBoolean;
-        shared_file: z.ZodBoolean;
-        shared_semantic_tag_or_same_lens: z.ZodBoolean;
-        shared_unit: z.ZodBoolean;
-    }, "strict", z.ZodTypeAny, {
-        call_import_reference_adjacency: boolean;
-        same_directory: boolean;
-        shared_critical_flow: boolean;
-        shared_file: boolean;
-        shared_semantic_tag_or_same_lens: boolean;
-        shared_unit: boolean;
-    }, {
-        call_import_reference_adjacency: boolean;
-        same_directory: boolean;
-        shared_critical_flow: boolean;
-        shared_file: boolean;
-        shared_semantic_tag_or_same_lens: boolean;
-        shared_unit: boolean;
-    }>;
-    score: z.ZodNumber;
-    eligible: z.ZodBoolean;
-}, "strict", z.ZodTypeAny, {
-    left: string;
-    right: string;
-    evidence: {
-        call_import_reference_adjacency: boolean;
-        same_directory: boolean;
-        shared_critical_flow: boolean;
-        shared_file: boolean;
-        shared_semantic_tag_or_same_lens: boolean;
-        shared_unit: boolean;
-    };
-    score: number;
-    eligible: boolean;
-}, {
-    left: string;
-    right: string;
-    evidence: {
-        call_import_reference_adjacency: boolean;
-        same_directory: boolean;
-        shared_critical_flow: boolean;
-        shared_file: boolean;
-        shared_semantic_tag_or_same_lens: boolean;
-        shared_unit: boolean;
-    };
-    score: number;
-    eligible: boolean;
-}>;
-export declare const ContentCoherenceCandidateSchema: z.ZodObject<{
-    left: z.ZodString;
-    right: z.ZodString;
-    score: z.ZodNumber;
-}, "strict", z.ZodTypeAny, {
-    left: string;
-    right: string;
-    score: number;
-}, {
-    left: string;
-    right: string;
-    score: number;
-}>;
-export declare const ContentCoherenceMergeTraceEntrySchema: z.ZodObject<{
-    left: z.ZodString;
-    right: z.ZodString;
-    score: z.ZodNumber;
-} & {
-    decision: z.ZodEnum<["merge", "already_connected"]>;
-    root: z.ZodString;
-}, "strict", z.ZodTypeAny, {
-    decision: "merge" | "already_connected";
-    left: string;
-    right: string;
-    score: number;
-    root: string;
-}, {
-    decision: "merge" | "already_connected";
-    left: string;
-    right: string;
-    score: number;
-    root: string;
-}>;
 export declare const ContentCoherenceTraceSchema: z.ZodObject<{
     normalized_items: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -215,94 +119,6 @@ export declare const ContentCoherenceTraceSchema: z.ZodObject<{
         tags: string[];
         critical_flow_ids?: string[] | undefined;
     }>, "many">;
-    pair_scores: z.ZodArray<z.ZodObject<{
-        left: z.ZodString;
-        right: z.ZodString;
-        evidence: z.ZodObject<{
-            call_import_reference_adjacency: z.ZodBoolean;
-            same_directory: z.ZodBoolean;
-            shared_critical_flow: z.ZodBoolean;
-            shared_file: z.ZodBoolean;
-            shared_semantic_tag_or_same_lens: z.ZodBoolean;
-            shared_unit: z.ZodBoolean;
-        }, "strict", z.ZodTypeAny, {
-            call_import_reference_adjacency: boolean;
-            same_directory: boolean;
-            shared_critical_flow: boolean;
-            shared_file: boolean;
-            shared_semantic_tag_or_same_lens: boolean;
-            shared_unit: boolean;
-        }, {
-            call_import_reference_adjacency: boolean;
-            same_directory: boolean;
-            shared_critical_flow: boolean;
-            shared_file: boolean;
-            shared_semantic_tag_or_same_lens: boolean;
-            shared_unit: boolean;
-        }>;
-        score: z.ZodNumber;
-        eligible: z.ZodBoolean;
-    }, "strict", z.ZodTypeAny, {
-        left: string;
-        right: string;
-        evidence: {
-            call_import_reference_adjacency: boolean;
-            same_directory: boolean;
-            shared_critical_flow: boolean;
-            shared_file: boolean;
-            shared_semantic_tag_or_same_lens: boolean;
-            shared_unit: boolean;
-        };
-        score: number;
-        eligible: boolean;
-    }, {
-        left: string;
-        right: string;
-        evidence: {
-            call_import_reference_adjacency: boolean;
-            same_directory: boolean;
-            shared_critical_flow: boolean;
-            shared_file: boolean;
-            shared_semantic_tag_or_same_lens: boolean;
-            shared_unit: boolean;
-        };
-        score: number;
-        eligible: boolean;
-    }>, "many">;
-    eligible_candidates: z.ZodArray<z.ZodObject<{
-        left: z.ZodString;
-        right: z.ZodString;
-        score: z.ZodNumber;
-    }, "strict", z.ZodTypeAny, {
-        left: string;
-        right: string;
-        score: number;
-    }, {
-        left: string;
-        right: string;
-        score: number;
-    }>, "many">;
-    merge_trace: z.ZodArray<z.ZodObject<{
-        left: z.ZodString;
-        right: z.ZodString;
-        score: z.ZodNumber;
-    } & {
-        decision: z.ZodEnum<["merge", "already_connected"]>;
-        root: z.ZodString;
-    }, "strict", z.ZodTypeAny, {
-        decision: "merge" | "already_connected";
-        left: string;
-        right: string;
-        score: number;
-        root: string;
-    }, {
-        decision: "merge" | "already_connected";
-        left: string;
-        right: string;
-        score: number;
-        root: string;
-    }>, "many">;
-    merge_decisions: z.ZodArray<z.ZodEnum<["merge", "already_connected"]>, "many">;
     components: z.ZodArray<z.ZodArray<z.ZodString, "many">, "many">;
 }, "strict", z.ZodTypeAny, {
     normalized_items: {
@@ -312,33 +128,6 @@ export declare const ContentCoherenceTraceSchema: z.ZodObject<{
         tags: string[];
         critical_flow_ids?: string[] | undefined;
     }[];
-    pair_scores: {
-        left: string;
-        right: string;
-        evidence: {
-            call_import_reference_adjacency: boolean;
-            same_directory: boolean;
-            shared_critical_flow: boolean;
-            shared_file: boolean;
-            shared_semantic_tag_or_same_lens: boolean;
-            shared_unit: boolean;
-        };
-        score: number;
-        eligible: boolean;
-    }[];
-    eligible_candidates: {
-        left: string;
-        right: string;
-        score: number;
-    }[];
-    merge_trace: {
-        decision: "merge" | "already_connected";
-        left: string;
-        right: string;
-        score: number;
-        root: string;
-    }[];
-    merge_decisions: ("merge" | "already_connected")[];
     components: string[][];
 }, {
     normalized_items: {
@@ -348,35 +137,16 @@ export declare const ContentCoherenceTraceSchema: z.ZodObject<{
         tags: string[];
         critical_flow_ids?: string[] | undefined;
     }[];
-    pair_scores: {
-        left: string;
-        right: string;
-        evidence: {
-            call_import_reference_adjacency: boolean;
-            same_directory: boolean;
-            shared_critical_flow: boolean;
-            shared_file: boolean;
-            shared_semantic_tag_or_same_lens: boolean;
-            shared_unit: boolean;
-        };
-        score: number;
-        eligible: boolean;
-    }[];
-    eligible_candidates: {
-        left: string;
-        right: string;
-        score: number;
-    }[];
-    merge_trace: {
-        decision: "merge" | "already_connected";
-        left: string;
-        right: string;
-        score: number;
-        root: string;
-    }[];
-    merge_decisions: ("merge" | "already_connected")[];
     components: string[][];
 }>;
-/** Build the complete canonical trace used by both audit and findings draws. */
-export declare function buildContentCoherenceTrace(input: ContentCoherenceInput | Record<string, unknown>): ContentCoherenceTrace;
+/**
+ * Build the complete canonical trace used by both audit and findings draws.
+ *
+ * `policy` is REQUIRED and has no default: a draw that forgot to declare its
+ * eligibility would otherwise silently inherit the other draw's, which is
+ * exactly the class of latent failure this project refuses to leave to a
+ * caller's memory. Pass {@link TASK_DRAW_COHERENCE_POLICY} or
+ * {@link FINDINGS_DRAW_COHERENCE_POLICY}.
+ */
+export declare function buildContentCoherenceTrace(input: ContentCoherenceInput | Record<string, unknown>, policy: ContentCoherencePolicy): ContentCoherenceTrace;
 //# sourceMappingURL=contentCoherence.d.ts.map

package/dist/shared/decompose/contentCoherence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contentCoherence.d.ts","sourceRoot":"","sources":["../../../src/shared/decompose/contentCoherence.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contentCoherence.d.ts","sourceRoot":"","sources":["../../../src/shared/decompose/contentCoherence.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,wBAAwB;;;;;;;EAO1B,CAAC;AAEZ,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,2BAA2B,GACnC,0BAA0B,GAC1B,2BAA2B,CAAC;AAEhC,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,2BAA2B,CAAC;IAClD;;;;OAIG;IACH,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;CAC1C;AAED;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,sBAGvC,CAAC;AAEH,yFAAyF;AACzF,eAAO,MAAM,8BAA8B,EAAE,sBAG3C,CAAC;AAiBH,MAAM,MAAM,wBAAwB,GAAG;IACrC,CAAC,UAAU,IAAI,IAAI,MAAM,OAAO,wBAAwB,GAAG,OAAO;CACnE,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACjD;AAED,MAAM,MAAM,gCAAgC,GACxC,aAAa,GACb,sBAAsB,GACtB,WAAW,GACX,eAAe,GACf,WAAW,GACX,WAAW,GACX,UAAU,CAAC;AAEf,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,gCAAgC,GAAG,MAAM,CAAC;CACjD;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACvC,aAAa,CAAC,EAAE,SAAS,4BAA4B,EAAE,CAAC;CACzD;AAED,MAAM,WAAW,8BAA8B;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAoBD,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,EAAE,8BAA8B,EAAE,CAAC;IACnD,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC;CACxB;AAED,eAAO,MAAM,oCAAoC;;;;;;;;;;;;;;;;;;EAQtC,CAAC;AAEZ,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAK7B,CAAC;AA4RZ;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtD,MAAM,EAAE,sBAAsB,GAC7B,qBAAqB,CAkGvB"}

package/dist/shared/decompose/contentCoherence.js

@@ -6,6 +6,7 @@
  * those components.
  */
 import { z } from "zod";
+import { louvain, modularityOf } from "./modularity.js";
 export const CONTENT_COHERENCE_SCORES = Object.freeze({
     call_import_reference_adjacency: 70,
     same_directory: 10,
@@ -15,16 +16,32 @@ export const CONTENT_COHERENCE_SCORES = Object.freeze({
     shared_unit: 80,
 });
 export const CONTENT_COHERENCE_THRESHOLD = 60;
-export const ContentCoherenceEvidenceSchema = z
-    .object({
-    call_import_reference_adjacency: z.boolean(),
-    same_directory: z.boolean(),
-    shared_critical_flow: z.boolean(),
-    shared_file: z.boolean(),
-    shared_semantic_tag_or_same_lens: z.boolean(),
-    shared_unit: z.boolean(),
-})
-    .strict();
+/**
+ * The audit TASK draw. Unmeasured for collapse — its eligibility is deliberately
+ * left as-is until it is measured on its own lap (`docs/backlog/open-bugs.md`).
+ */
+export const TASK_DRAW_COHERENCE_POLICY = Object.freeze({
+    eligibility: "weighted_score_threshold",
+    refineAtModularityPeak: false,
+});
+/** The FINDINGS draw (work blocks + the findings deliverable). Owner cut, 2026-08-19. */
+export const FINDINGS_DRAW_COHERENCE_POLICY = Object.freeze({
+    eligibility: "shared_file_and_same_lens",
+    refineAtModularityPeak: true,
+});
+/**
+ * The canonical modularity resolution (γ). NOT a tuned knob and never to become
+ * one: γ = 1 is the literature default, at which the trivial whole-component
+ * partition scores exactly 0, so "did the split beat keeping the component
+ * whole" is answered by the data alone.
+ */
+const MODULARITY_RESOLUTION = 1;
+/**
+ * Components at or below this size are handed back unrefined. A triviality
+ * guard, not a size budget: modularity over one, two, or three nodes describes
+ * noise rather than structure, and nothing downstream reads the number.
+ */
+const TRIVIAL_COMPONENT_SIZE = 3;
 export const NormalizedContentCoherenceItemSchema = z
     .object({
     id: z.string().min(1),
@@ -34,33 +51,9 @@ export const NormalizedContentCoherenceItemSchema = z
     critical_flow_ids: z.array(z.string()).optional(),
 })
     .strict();
-export const ContentCoherencePairScoreSchema = z
-    .object({
-    left: z.string(),
-    right: z.string(),
-    evidence: ContentCoherenceEvidenceSchema,
-    score: z.number().int(),
-    eligible: z.boolean(),
-})
-    .strict();
-export const ContentCoherenceCandidateSchema = z
-    .object({
-    left: z.string(),
-    right: z.string(),
-    score: z.number().int(),
-})
-    .strict();
-export const ContentCoherenceMergeTraceEntrySchema = ContentCoherenceCandidateSchema.extend({
-    decision: z.enum(["merge", "already_connected"]),
-    root: z.string(),
-}).strict();
 export const ContentCoherenceTraceSchema = z
     .object({
     normalized_items: z.array(NormalizedContentCoherenceItemSchema),
-    pair_scores: z.array(ContentCoherencePairScoreSchema),
-    eligible_candidates: z.array(ContentCoherenceCandidateSchema),
-    merge_trace: z.array(ContentCoherenceMergeTraceEntrySchema),
-    merge_decisions: z.array(z.enum(["merge", "already_connected"])),
     components: z.array(z.array(z.string())),
 })
     .strict();
@@ -201,6 +194,55 @@ function scoreEvidence(evidence) {
     }
     return score;
 }
+function isEligible(direct, score, policy) {
+    return policy.eligibility === "shared_file_and_same_lens"
+        ? direct.sharedFile && direct.sameLens
+        : score >= CONTENT_COHERENCE_THRESHOLD;
+}
+/**
+ * Split one eligible-edge component at its modularity PEAK, or hand it back
+ * whole. The component's own eligible pairs are the weighted graph (edge weight =
+ * the pair's evidence score), Louvain proposes a partition at the canonical γ,
+ * and the proposal is accepted only when it scores strictly above keeping the
+ * component whole. A component held together by one weak bridge splits there.
+ * Nothing in the decision is a constant of any denomination.
+ *
+ * What survives whole is a UNIFORM-weight clique: with every edge equal, any cut
+ * scores below the trivial partition, so it cannot be split. A clique whose
+ * weights DIFFER can still split — six findings on one file and one lens but two
+ * units weigh 220 within a unit and 140 across it, and that contrast alone beats
+ * the whole. That is intended (the halves are genuinely less coupled), and the
+ * shared file then surfaces as a seam between them rather than disappearing into
+ * one block. "A clique stays whole" without the uniform qualifier is an
+ * overclaim; the two cases are pinned separately in
+ * `tests/shared/content-coherence.test.ts`.
+ */
+function refineAtModularityPeak(members, candidates) {
+    if (members.length <= TRIVIAL_COMPONENT_SIZE)
+        return [[...members]];
+    const graph = {
+        nodes: [...members],
+        edges: candidates.map((candidate) => ({
+            a: candidate.left,
+            b: candidate.right,
+            weight: candidate.score,
+        })),
+    };
+    const proposed = louvain(graph, MODULARITY_RESOLUTION);
+    const whole = new Map(members.map((id) => [id, members[0] ?? id]));
+    if (modularityOf(graph, proposed, MODULARITY_RESOLUTION) <=
+        modularityOf(graph, whole, MODULARITY_RESOLUTION)) {
+        return [[...members]];
+    }
+    const communities = new Map();
+    for (const member of members) {
+        const community = proposed.get(member) ?? member;
+        const group = communities.get(community) ?? [];
+        group.push(member);
+        communities.set(community, group);
+    }
+    return [...communities.values()];
+}
 function findRoot(parent, id) {
     const lineage = [];
     let root = id;
@@ -212,37 +254,50 @@ function findRoot(parent, id) {
         parent.set(member, root);
     return root;
 }
-/** Build the complete canonical trace used by both audit and findings draws. */
-export function buildContentCoherenceTrace(input) {
+/**
+ * Build the complete canonical trace used by both audit and findings draws.
+ *
+ * `policy` is REQUIRED and has no default: a draw that forgot to declare its
+ * eligibility would otherwise silently inherit the other draw's, which is
+ * exactly the class of latent failure this project refuses to leave to a
+ * caller's memory. Pass {@link TASK_DRAW_COHERENCE_POLICY} or
+ * {@link FINDINGS_DRAW_COHERENCE_POLICY}.
+ */
+export function buildContentCoherenceTrace(input, policy) {
     if (!isRecord(input)) {
         throw new Error("Content-coherence input must be an object.");
     }
     const normalizedItems = normalizeItems(input.items);
     const itemIds = new Set(normalizedItems.map((item) => item.id));
     const relationshipEvidence = normalizeRelationshipEvidence(input.relationships, itemIds);
-    const pairScores = [];
+    // Only ELIGIBLE pairs are retained. The ineligible majority (82% of pairs on
+    // the 3,194-finding dogfood run) can affect nothing downstream — union-find
+    // consumes eligibility alone — so materializing the full O(N²) pair layer was
+    // pure cost. Scoring itself is unchanged; the sort comparator below is total
+    // over distinct (left,right) pairs, so filtering during the scan yields the
+    // byte-identical candidate order the filter-then-sort form produced.
+    const eligibleCandidates = [];
     for (let leftIndex = 0; leftIndex < normalizedItems.length; leftIndex += 1) {
         for (let rightIndex = leftIndex + 1; rightIndex < normalizedItems.length; rightIndex += 1) {
             const left = normalizedItems[leftIndex];
             const right = normalizedItems[rightIndex];
             const evidence = directEvidence(left, right);
+            // Captured BEFORE relationship evidence is folded in — the conjunctive
+            // policy must read only what the items themselves assert.
+            const direct = {
+                sharedFile: evidence.shared_file,
+                sameLens: evidence.shared_semantic_tag_or_same_lens,
+            };
             for (const kind of relationshipEvidence.get(pairKey(left.id, right.id)) ?? []) {
                 evidence[kind] = true;
             }
             const score = scoreEvidence(evidence);
-            pairScores.push({
-                left: left.id,
-                right: right.id,
-                evidence,
-                score,
-                eligible: score >= CONTENT_COHERENCE_THRESHOLD,
-            });
+            if (!isEligible(direct, score, policy))
+                continue;
+            eligibleCandidates.push({ left: left.id, right: right.id, score });
         }
     }
-    const eligibleCandidates = pairScores
-        .filter((pair) => pair.eligible)
-        .map(({ left, right, score }) => ({ left, right, score }))
-        .sort((left, right) => {
+    eligibleCandidates.sort((left, right) => {
         if (left.score !== right.score)
             return right.score - left.score;
         const leftDelta = compareCodeUnits(left.left, right.left);
@@ -251,22 +306,14 @@ export function buildContentCoherenceTrace(input) {
             : compareCodeUnits(left.right, right.right);
     });
     const parent = new Map(normalizedItems.map((item) => [item.id, item.id]));
-    const mergeTrace = [];
     for (const candidate of eligibleCandidates) {
         const leftRoot = findRoot(parent, candidate.left);
         const rightRoot = findRoot(parent, candidate.right);
-        if (leftRoot === rightRoot) {
-            mergeTrace.push({
-                ...candidate,
-                decision: "already_connected",
-                root: leftRoot,
-            });
+        if (leftRoot === rightRoot)
             continue;
-        }
         const root = compareCodeUnits(leftRoot, rightRoot) <= 0 ? leftRoot : rightRoot;
         const other = root === leftRoot ? rightRoot : leftRoot;
         parent.set(other, root);
-        mergeTrace.push({ ...candidate, decision: "merge", root });
     }
     const groups = new Map();
     for (const item of normalizedItems) {
@@ -275,15 +322,25 @@ export function buildContentCoherenceTrace(input) {
         members.push(item.id);
         groups.set(root, members);
     }
-    const components = [...groups.values()]
-        .map((members) => members.sort(compareCodeUnits))
+    // Bucket the eligible pairs by the component they ended up inside, so
+    // refinement reads each component's own weighted evidence graph once.
+    const candidatesByRoot = new Map();
+    if (policy.refineAtModularityPeak) {
+        for (const candidate of eligibleCandidates) {
+            const root = findRoot(parent, candidate.left);
+            const bucket = candidatesByRoot.get(root) ?? [];
+            bucket.push(candidate);
+            candidatesByRoot.set(root, bucket);
+        }
+    }
+    const merged = [...groups.entries()].map(([root, members]) => [root, members.sort(compareCodeUnits)]);
+    const components = (policy.refineAtModularityPeak
+        ? merged.flatMap(([root, members]) => refineAtModularityPeak(members, candidatesByRoot.get(root) ?? []))
+        : merged.map(([, members]) => members))
+        .map((members) => [...members].sort(compareCodeUnits))
         .sort((left, right) => compareCodeUnits(left[0] ?? "", right[0] ?? ""));
     return {
         normalized_items: normalizedItems,
-        pair_scores: pairScores,
-        eligible_candidates: eligibleCandidates,
-        merge_trace: mergeTrace,
-        merge_decisions: mergeTrace.map((entry) => entry.decision),
         components,
     };
 }