Make convergence clustering threshold configurable via --threshold (#100)

analyzeConvergence now accepts a threshold parameter (default 0.3).
New --threshold CLI flag passes through RunOptions. Test verifies
different thresholds produce different clustering results.

Generated by thinktank Opus (5 agents, 76% consensus, all pass).

Closes #65

Co-authored-by: unknown <that-github-user@github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

src/cli.ts

@@ -29,6 +29,7 @@ program
   .option("--timeout <seconds>", "Timeout per agent in seconds", "300")
   .option("--model <model>", "Claude model to use", "sonnet")
   .option("-r, --runner <name>", "AI coding tool to use (default: claude-code)")
+  .option("--threshold <number>", "Convergence clustering similarity threshold (0.0-1.0)", "0.3")
   .option("--verbose", "Show detailed output from each agent")
   .action(async (promptArg: string | undefined, opts) => {
     const prompt = resolvePrompt(promptArg, opts.file);
@@ -51,6 +52,12 @@ program
       process.exit(1);
     }
 
+    const threshold = parseFloat(opts.threshold);
+    if (Number.isNaN(threshold) || threshold < 0 || threshold > 1) {
+      console.error("Error: --threshold must be a number between 0.0 and 1.0");
+      process.exit(1);
+    }
+
     const knownModels = ["sonnet", "opus", "haiku"];
     if (!knownModels.includes(opts.model) && !opts.model.startsWith("claude-")) {
       console.warn(
@@ -65,6 +72,7 @@ program
       testTimeout,
       timeout,
       model: opts.model,
+      threshold,
       runner: opts.runner,
       verbose: opts.verbose ?? false,
     });

src/commands/run.test.ts

@@ -10,6 +10,7 @@ function makeOpts(overrides: Partial<RunOptions> = {}): RunOptions {
     testTimeout: 120,
     timeout: 300,
     model: "sonnet",
+    threshold: 0.3,
     verbose: false,
     ...overrides,
   };

src/commands/run.ts

@@ -126,7 +126,7 @@ export async function run(opts: RunOptions): Promise<void> {
   }
 
   // Phase 4: Convergence analysis
-  const convergence = analyzeConvergence(agents);
+  const convergence = analyzeConvergence(agents, opts.threshold);
 
   // Phase 5: Recommendation
   const { recommended, scores } = recommend(agents, testResults, convergence);

src/scoring/convergence.test.ts

@@ -76,6 +76,28 @@ describe("analyzeConvergence", () => {
     assert.deepEqual(groups[0]!.agents.sort(), [1, 2]);
   });
 
+  it("produces different clusters with different thresholds", () => {
+    // Agent 1 and 2 have similar (but not identical) diffs; agent 3 is different
+    const agents = [
+      makeAgent({ id: 1, diff: DIFF_A, filesChanged: ["a.ts"] }),
+      makeAgent({ id: 2, diff: DIFF_A_VARIANT, filesChanged: ["a.ts"] }),
+      makeAgent({ id: 3, diff: DIFF_B, filesChanged: ["b.ts"] }),
+    ];
+
+    // Low threshold: agents 1 and 2 cluster together (Jaccard similarity = 0.5 >= 0.3)
+    const lowGroups = analyzeConvergence(agents, 0.3);
+    const groupWith1And2 = lowGroups.find((g) => g.agents.includes(1) && g.agents.includes(2));
+    assert.ok(groupWith1And2, "At threshold 0.3, agents 1 and 2 should cluster together");
+
+    // Very high threshold: nothing clusters (similarity < 1.0 for non-identical diffs)
+    const highGroups = analyzeConvergence(agents, 1.0);
+    // Each agent should be in its own group since no pair has perfect similarity
+    assert.ok(
+      highGroups.length > lowGroups.length,
+      `Higher threshold should produce more groups (got ${highGroups.length} vs ${lowGroups.length})`,
+    );
+  });
+
   it("labels strong consensus correctly", () => {
     const agents = [
       makeAgent({ id: 1, diff: DIFF_A }),

src/scoring/convergence.ts

@@ -9,7 +9,7 @@ import { pairwiseSimilarity } from "./diff-parser.js";
  * Agents are clustered by diff similarity using single-linkage clustering
  * with a 0.5 similarity threshold.
  */
-export function analyzeConvergence(agents: AgentResult[]): ConvergenceGroup[] {
+export function analyzeConvergence(agents: AgentResult[], threshold = 0.3): ConvergenceGroup[] {
   const completed = agents.filter((a) => a.status === "success" && a.diff.length > 0);
 
   if (completed.length === 0) return [];
@@ -18,11 +18,10 @@ export function analyzeConvergence(agents: AgentResult[]): ConvergenceGroup[] {
   const similarities = pairwiseSimilarity(completed.map((a) => ({ id: a.id, diff: a.diff })));
 
   // Single-linkage clustering: merge agents with similarity >= threshold
-  const SIMILARITY_THRESHOLD = 0.3;
   const clusters = clusterAgents(
     completed.map((a) => a.id),
     similarities,
-    SIMILARITY_THRESHOLD,
+    threshold,
   );
 
   // Convert clusters to convergence groups

src/types.ts

@@ -5,6 +5,7 @@ export interface RunOptions {
   testTimeout: number;
   timeout: number;
   model: string;
+  threshold: number;
   verbose: boolean;
   runner?: string;
 }