cctx-cli 1.7.0__tar.gz → 1.9.0__tar.gz

{cctx_cli-1.7.0 → cctx_cli-1.9.0}/CHANGELOG.md

@@ -2,6 +2,87 @@
 
 <!-- version list -->
 
+## v1.9.0 (2026-06-11)
+
+### Bug Fixes
+
+- Combine split import in test_efficacy (ruff I001)
+  ([#111](https://github.com/jacquardlabs/cctx/pull/111),
+  [`d40fe5b`](https://github.com/jacquardlabs/cctx/commit/d40fe5b15643546ef7d9dc75ffcf1b62d4ec051b))
+
+- Normalize Z-suffix UTC timestamps for Python 3.10 fromisoformat
+  ([#111](https://github.com/jacquardlabs/cctx/pull/111),
+  [`d40fe5b`](https://github.com/jacquardlabs/cctx/commit/d40fe5b15643546ef7d9dc75ffcf1b62d4ec051b))
+
+- Remove unused timezone import (ruff F401) ([#111](https://github.com/jacquardlabs/cctx/pull/111),
+  [`d40fe5b`](https://github.com/jacquardlabs/cctx/commit/d40fe5b15643546ef7d9dc75ffcf1b62d4ec051b))
+
+- Use %aI git format for Python 3.10 compat; guard total_after==0 signal
+  ([#111](https://github.com/jacquardlabs/cctx/pull/111),
+  [`d40fe5b`](https://github.com/jacquardlabs/cctx/commit/d40fe5b15643546ef7d9dc75ffcf1b62d4ec051b))
+
+### Documentation
+
+- Add managed_heading_dates to harvest.py module docstring
+  ([#111](https://github.com/jacquardlabs/cctx/pull/111),
+  [`d40fe5b`](https://github.com/jacquardlabs/cctx/commit/d40fe5b15643546ef7d9dc75ffcf1b62d4ec051b))
+
+### Features
+
+- EfficacyRow + EfficacyReport dataclasses (M17 #90)
+  ([#111](https://github.com/jacquardlabs/cctx/pull/111),
+  [`d40fe5b`](https://github.com/jacquardlabs/cctx/commit/d40fe5b15643546ef7d9dc75ffcf1b62d4ec051b))
+
+- Evidence.efficacy — before/after session bucketing (M17 #90)
+  ([#111](https://github.com/jacquardlabs/cctx/pull/111),
+  [`d40fe5b`](https://github.com/jacquardlabs/cctx/commit/d40fe5b15643546ef7d9dc75ffcf1b62d4ec051b))
+
+- Harvest --efficacy CLI flag (M17 #90) ([#111](https://github.com/jacquardlabs/cctx/pull/111),
+  [`d40fe5b`](https://github.com/jacquardlabs/cctx/commit/d40fe5b15643546ef7d9dc75ffcf1b62d4ec051b))
+
+- Managed_heading_dates — git-based patch introduction dates (M17 #90)
+  ([#111](https://github.com/jacquardlabs/cctx/pull/111),
+  [`d40fe5b`](https://github.com/jacquardlabs/cctx/commit/d40fe5b15643546ef7d9dc75ffcf1b62d4ec051b))
+
+- Patch efficacy report — harvest --efficacy (M17 #90)
+  ([#111](https://github.com/jacquardlabs/cctx/pull/111),
+  [`d40fe5b`](https://github.com/jacquardlabs/cctx/commit/d40fe5b15643546ef7d9dc75ffcf1b62d4ec051b))
+
+- Render_efficacy_report — efficacy table renderer (M17 #90)
+  ([#111](https://github.com/jacquardlabs/cctx/pull/111),
+  [`d40fe5b`](https://github.com/jacquardlabs/cctx/commit/d40fe5b15643546ef7d9dc75ffcf1b62d4ec051b))
+
+
+## v1.8.0 (2026-06-11)
+
+### Bug Fixes
+
+- Add _FANOUT_WASTE_DIFF template so MANAGED_HEADINGS stays in sync
+  ([#110](https://github.com/jacquardlabs/cctx/pull/110),
+  [`0123588`](https://github.com/jacquardlabs/cctx/commit/01235884bde2158307441c71f38d4cf96a2d8481))
+
+- Ruff lint — move imports to top, break long lines in test file
+  ([#110](https://github.com/jacquardlabs/cctx/pull/110),
+  [`0123588`](https://github.com/jacquardlabs/cctx/commit/01235884bde2158307441c71f38d4cf96a2d8481))
+
+### Features
+
+- Add FindingKind.FANOUT_WASTE + KIND_LABEL + MANAGED_HEADINGS
+  ([#110](https://github.com/jacquardlabs/cctx/pull/110),
+  [`0123588`](https://github.com/jacquardlabs/cctx/commit/01235884bde2158307441c71f38d4cf96a2d8481))
+
+- Fan-out waste classifier (M16 #89) ([#110](https://github.com/jacquardlabs/cctx/pull/110),
+  [`0123588`](https://github.com/jacquardlabs/cctx/commit/01235884bde2158307441c71f38d4cf96a2d8481))
+
+- Fan_out classifier — Signal A (overlap) + Signal B (retry)
+  ([#110](https://github.com/jacquardlabs/cctx/pull/110),
+  [`0123588`](https://github.com/jacquardlabs/cctx/commit/01235884bde2158307441c71f38d4cf96a2d8481))
+
+- Wire fan_out classifier into diagnostician, add _patch_fanout_costs
+  ([#110](https://github.com/jacquardlabs/cctx/pull/110),
+  [`0123588`](https://github.com/jacquardlabs/cctx/commit/01235884bde2158307441c71f38d4cf96a2d8481))
+
+
 ## v1.7.0 (2026-06-11)
 
 ### Bug Fixes

{cctx_cli-1.7.0 → cctx_cli-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctx-cli
-Version: 1.7.0
+Version: 1.9.0
 Summary: Diagnose Claude Code sessions — find what went wrong, what it cost, and what to add to CLAUDE.md
 Author: Jacquard Labs
 License-Expression: MIT

{cctx_cli-1.7.0 → cctx_cli-1.9.0}/cctx/__init__.py

@@ -1,3 +1,3 @@
 """cctx: profile, debug, and optimize Claude Code and Agent SDK sessions."""
 
-__version__ = "1.7.0"
+__version__ = "1.9.0"

{cctx_cli-1.7.0 → cctx_cli-1.9.0}/cctx/cli.py

@@ -32,6 +32,7 @@ from cctx.renderers.terminal import (
     render_aggregate,
     render_aggregate_drilldown,
     render_diagnosis,
+    render_efficacy_report,
     render_harvest_results,
     render_projects,
     render_sessions,
@@ -587,6 +588,13 @@ def trace(target: Path | None, latest: bool) -> None:
     help="With --emit: also mirror already-harvested cctx-managed sections "
          "from CLAUDE.md into the emit target.",
 )
+@click.option(
+    "--efficacy",
+    "efficacy_mode",
+    is_flag=True,
+    default=False,
+    help="Report whether applied patches reduced their target patterns (before vs. after).",
+)
 def harvest(
     target: Path,
     since: str | None,
@@ -597,6 +605,7 @@ def harvest(
     check_severity: str,
     emit_targets: tuple[str, ...],
     sync_mode: bool,
+    efficacy_mode: bool,
 ) -> None:
     """Apply autopsy patches to CLAUDE.md."""
     from cctx.harvest import (
@@ -610,6 +619,22 @@ def harvest(
     if sync_mode and not emit_targets:
         raise click.UsageError("--sync requires --emit.")
 
+    if efficacy_mode:
+        if target.is_file():
+            raise click.UsageError(
+                "--efficacy requires a project directory, not a .jsonl file."
+            )
+        resolved_dir = target_dir or Path.cwd()
+        from cctx.harvest import managed_heading_dates
+        from cctx.recommender.evidence import efficacy as _run_efficacy
+        start = datetime(2020, 1, 1, tzinfo=UTC)
+        end   = datetime(2035, 1, 1, tzinfo=UTC)
+        pairs = aggregate.run(target, start, end)
+        h_dates = managed_heading_dates(resolved_dir)
+        report  = _run_efficacy(pairs, h_dates)
+        render_efficacy_report(report, resolved_dir, target)
+        return
+
     if check_mode:
         from cctx.harvest import CheckSeverity
         resolved_dir = target_dir or Path.cwd()

{cctx_cli-1.7.0 → cctx_cli-1.9.0}/cctx/diagnostician/__init__.py

@@ -16,6 +16,7 @@ from typing import TYPE_CHECKING
 from cctx.diagnostician import inflection
 from cctx.diagnostician.patterns import (
     dead_end,
+    fan_out,
     retry_loop,
     scope_creep,
     stale_context,
@@ -41,6 +42,45 @@ def _patch_costs(findings: list[Finding], model: str | None) -> list[Finding]:
     return result
 
 
+def _patch_fanout_costs(
+    findings: list[Finding],
+    subagent_costs: list[SubagentAttribution],
+) -> list[Finding]:
+    """Fill cost_usd on FANOUT_WASTE findings from subagent attribution data.
+
+    For overlap findings: picks the cheaper of the two subagents as waste.
+    For retry findings: attributes the full cost of the failed subagent.
+    Populates evidence['subagent_session_ids'] so run()'s dedup pass works.
+    """
+    cost_map = {a.session_id: a.total_cost_usd for a in subagent_costs}
+    result: list[Finding] = []
+    for f in findings:
+        if f.kind is FindingKind.FANOUT_WASTE:
+            signal = f.evidence.get("signal")
+            if signal == "overlap":
+                pair = [sid for sid in f.evidence.get("overlap_pair", []) if sid is not None]
+                if pair:
+                    cheaper_cost, cheaper_sid = min(
+                        (cost_map.get(sid, 0.0), sid) for sid in pair
+                    )
+                    f = dataclasses.replace(
+                        f,
+                        cost_usd=round(cheaper_cost, 4),
+                        evidence={**f.evidence, "subagent_session_ids": [cheaper_sid]},
+                    )
+            elif signal == "retry":
+                failed_sid = f.evidence.get("failed_session_id")
+                if failed_sid is not None:
+                    cost = cost_map.get(failed_sid, 0.0)
+                    f = dataclasses.replace(
+                        f,
+                        cost_usd=round(cost, 4),
+                        evidence={**f.evidence, "subagent_session_ids": [failed_sid]},
+                    )
+        result.append(f)
+    return result
+
+
 def _compute_own_cost(trace: SessionTrace, model: str | None) -> float:
     """Parent-turns-only cost — does not recurse into subagents.
 
@@ -111,17 +151,32 @@ def run(trace: SessionTrace) -> Diagnosis:
         *stale_context.classify(trace),
         *tool_thrash.classify(trace),
         *dead_end.classify(trace),
+        *fan_out.classify(trace),
     ]
     findings.sort(key=lambda f: f.first_turn)
 
     inflection_turn = inflection.detect(findings)
     findings = _patch_costs(findings, trace.primary_model)
 
+    # Fan-out cost patching requires attributions first.
+    subagent_costs = _collect_attributions(trace)
+    findings = _patch_fanout_costs(findings, subagent_costs)
+
     total_cost = round(_compute_inclusive_cost(trace), 4)
-    waste_cost = sum(f.cost_usd for f in findings if f.cost_usd is not None)
-    waste_cost = min(waste_cost, total_cost)
 
-    subagent_costs = _collect_attributions(trace)
+    # Deduplicate fan-out waste: a subagent flagged by both overlap AND retry
+    # must not be double-counted. Collect unique wasted session IDs, sum once.
+    cost_map = {a.session_id: a.total_cost_usd for a in subagent_costs}
+    wasted_sids: set[str] = set()
+    for f in findings:
+        if f.kind is FindingKind.FANOUT_WASTE:
+            wasted_sids.update(f.evidence.get("subagent_session_ids", []))
+    fanout_waste = sum(cost_map.get(sid, 0.0) for sid in wasted_sids)
+    other_waste = sum(
+        f.cost_usd for f in findings
+        if f.cost_usd is not None and f.kind is not FindingKind.FANOUT_WASTE
+    )
+    waste_cost = min(other_waste + fanout_waste, total_cost)
 
     return Diagnosis(
         session_id=trace.session_id,

cctx_cli-1.9.0/cctx/diagnostician/patterns/fan_out.py

@@ -0,0 +1,175 @@
+"""Fan-out waste classifier.
+
+classify(trace) -> list[Finding]
+
+Signal A — OVERLAP: Two Agent calls with Jaccard >= 0.65 on word 3-grams,
+    both prompts >= 50 words.
+Signal B — RETRY: Agent ToolResult is_error=True followed by the next Agent
+    call with Jaccard >= 0.50 on word 3-grams, both prompts >= 30 words.
+
+Signal C (unused-result) is deferred — the 6-gram approach fires false
+positives on paraphrased references and is not ship-ready.
+
+cost_usd is set to None here; _patch_fanout_costs() in diagnostician/__init__.py
+fills it in from SubagentAttribution data after run() collects attributions.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from cctx.models import Confidence, Finding, FindingKind, Severity
+
+if TYPE_CHECKING:
+    from cctx.models import SessionTrace, ToolUse
+
+# ---------------------------------------------------------------------------
+# Thresholds — documented here, not tuned at runtime
+# ---------------------------------------------------------------------------
+
+OVERLAP_JACCARD: float = 0.65   # minimum Jaccard on word 3-grams for overlap
+OVERLAP_MIN_WORDS: int = 50     # both prompts must be this long
+
+RETRY_JACCARD: float = 0.50     # minimum Jaccard for failed-retry detection
+RETRY_MIN_WORDS: int = 30       # both prompts must be this long
+
+
+# ---------------------------------------------------------------------------
+# N-gram helpers
+# ---------------------------------------------------------------------------
+
+def _word_ngrams(text: str, n: int) -> set[tuple[str, ...]]:
+    words = text.lower().split()
+    if len(words) < n:
+        return set()
+    return {tuple(words[i : i + n]) for i in range(len(words) - n + 1)}
+
+
+def _jaccard(a: set, b: set) -> float:
+    if not a or not b:
+        return 0.0
+    return len(a & b) / len(a | b)
+
+
+def _get_prompt(tu: ToolUse) -> str:
+    return tu.tool_input.get("prompt") or tu.tool_input.get("description") or ""
+
+
+# ---------------------------------------------------------------------------
+# Signal A — Overlapping subagent prompts
+# ---------------------------------------------------------------------------
+
+def _signal_overlap(agent_calls: list[tuple[int, ToolUse]]) -> list[Finding]:
+    findings: list[Finding] = []
+    for i in range(len(agent_calls)):
+        turn_i, tu_i = agent_calls[i]
+        p_i = _get_prompt(tu_i)
+        words_i = p_i.split()
+        if len(words_i) < OVERLAP_MIN_WORDS:
+            continue
+        ng_i = _word_ngrams(p_i, 3)
+        for j in range(i + 1, len(agent_calls)):
+            turn_j, tu_j = agent_calls[j]
+            p_j = _get_prompt(tu_j)
+            words_j = p_j.split()
+            if len(words_j) < OVERLAP_MIN_WORDS:
+                continue
+            ng_j = _word_ngrams(p_j, 3)
+            score = _jaccard(ng_i, ng_j)
+            if score < OVERLAP_JACCARD:
+                continue
+            findings.append(Finding(
+                kind=FindingKind.FANOUT_WASTE,
+                severity=Severity.MEDIUM,
+                confidence=Confidence.MEDIUM,
+                first_turn=min(turn_i, turn_j),
+                last_turn=max(turn_i, turn_j),
+                evidence={
+                    "signal": "overlap",
+                    "overlap_pair": [tu_i.subagent_session_id, tu_j.subagent_session_id],
+                    "jaccard": round(score, 3),
+                    "prompt_a": p_i[:80],
+                    "prompt_b": p_j[:80],
+                    "subagent_session_ids": [],  # filled by _patch_fanout_costs
+                },
+                cost_usd=None,
+                summary=f"Overlapping subagent prompts (Jaccard {score:.2f})",
+            ))
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# Signal B — Failed subagent re-spawned with similar prompt
+# ---------------------------------------------------------------------------
+
+def _signal_retry(
+    agent_calls: list[tuple[int, ToolUse]],
+    result_map: dict[str, tuple[bool, str]],  # tool_use_id -> (is_error, content)
+) -> list[Finding]:
+    findings: list[Finding] = []
+    for k, (turn_k, tu_k) in enumerate(agent_calls):
+        is_error, _content = result_map.get(tu_k.tool_use_id, (False, ""))
+        if not is_error:
+            continue
+        # Only check the immediate next Agent call (by list order = turn order)
+        if k + 1 >= len(agent_calls):
+            continue
+        turn_next, tu_next = agent_calls[k + 1]
+        p_failed = _get_prompt(tu_k)
+        p_retry = _get_prompt(tu_next)
+        if len(p_failed.split()) < RETRY_MIN_WORDS or len(p_retry.split()) < RETRY_MIN_WORDS:
+            continue
+        score = _jaccard(_word_ngrams(p_failed, 3), _word_ngrams(p_retry, 3))
+        if score < RETRY_JACCARD:
+            continue
+        findings.append(Finding(
+            kind=FindingKind.FANOUT_WASTE,
+            severity=Severity.HIGH,
+            confidence=Confidence.HIGH,
+            first_turn=turn_k,
+            last_turn=turn_next,
+            evidence={
+                "signal": "retry",
+                "failed_session_id": tu_k.subagent_session_id,
+                "jaccard": round(score, 3),
+                "failed_prompt": p_failed[:80],
+                "retry_prompt": p_retry[:80],
+                "subagent_session_ids": [],  # filled by _patch_fanout_costs
+            },
+            cost_usd=None,
+            summary=f"Failed subagent re-spawned with similar prompt (Jaccard {score:.2f})",
+        ))
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+def _classify_impl(trace: SessionTrace) -> list[Finding]:
+    # Collect Agent ToolUse in turn order
+    agent_calls: list[tuple[int, ToolUse]] = []
+    result_map: dict[str, tuple[bool, str]] = {}
+
+    for turn in trace.turns:
+        for tu in turn.tool_uses:
+            if tu.tool_name == "Agent":
+                agent_calls.append((turn.turn_number, tu))
+        for tr in turn.tool_results:
+            if tr.tool_name == "Agent":
+                result_map[tr.tool_use_id] = (tr.is_error, tr.content)
+
+    if len(agent_calls) < 2:
+        return []
+
+    findings: list[Finding] = [
+        *_signal_overlap(agent_calls),
+        *_signal_retry(agent_calls, result_map),
+    ]
+    return findings
+
+
+def classify(trace: SessionTrace) -> list[Finding]:
+    try:
+        return _classify_impl(trace)
+    except Exception:
+        return []

{cctx_cli-1.7.0 → cctx_cli-1.9.0}/cctx/harvest.py

@@ -5,6 +5,7 @@ Public API:
     preview_patches(patches, target_dir) -> list[ApplyResult]
     apply_patches(patches, target_dir) -> list[ApplyResult]
     check_claude_md(target_dir) -> list[CheckFinding]
+    managed_heading_dates(target_dir) -> dict[str, datetime | None]
 
 Layering rules (MUST respect):
 - Does NOT import click, rich_click, or anthropic.
@@ -15,8 +16,10 @@ from __future__ import annotations
 
 import dataclasses
 import re
+import subprocess
 from collections import defaultdict
 from dataclasses import dataclass
+from datetime import datetime
 from enum import Enum
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -276,6 +279,38 @@ def apply_patches(patches: list[Patch], target_dir: Path) -> list[ApplyResult]:
     return [apply_patch(patch, target_dir) for patch in patches]
 
 
+def managed_heading_dates(target_dir: Path) -> dict[str, datetime | None]:
+    """Return the git introduction date for each MANAGED_HEADINGS heading.
+
+    For each heading, runs:
+        git log --reverse --format="%aI" -S"<heading>" -- CLAUDE.md
+
+    --reverse gives oldest-first; the first line is the introduction commit.
+    -S (pickaxe) fires when the occurrence count of the literal string changes.
+    Returns None for any heading not found in git history, or if git fails.
+    Never raises.
+    """
+    result: dict[str, datetime | None] = {}
+    for heading in MANAGED_HEADINGS.values():
+        try:
+            proc = subprocess.run(
+                ["git", "log", "--reverse", "--format=%aI", f"-S{heading}", "--", "CLAUDE.md"],
+                cwd=target_dir,
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            lines = proc.stdout.strip().splitlines()
+            if lines:
+                date_str = lines[0].replace("Z", "+00:00")
+                result[heading] = datetime.fromisoformat(date_str)
+            else:
+                result[heading] = None
+        except Exception:  # noqa: BLE001
+            result[heading] = None
+    return result
+
+
 # ---------------------------------------------------------------------------
 # harvest --check
 # ---------------------------------------------------------------------------

{cctx_cli-1.7.0 → cctx_cli-1.9.0}/cctx/models.py

@@ -172,6 +172,7 @@ class FindingKind(str, Enum):
     STALE_CONTEXT = "stale_context"
     TOOL_THRASH   = "tool_thrash"
     DEAD_END      = "dead_end"
+    FANOUT_WASTE  = "fanout_waste"
     PROJECT_PATTERN = "project_pattern"
 
 
@@ -181,6 +182,7 @@ KIND_LABEL: dict[FindingKind, str] = {
     FindingKind.STALE_CONTEXT: "STALE CONTEXT",
     FindingKind.TOOL_THRASH:   "TOOL THRASH",
     FindingKind.DEAD_END:      "DEAD END",
+    FindingKind.FANOUT_WASTE:  "FANOUT WASTE",
     FindingKind.PROJECT_PATTERN: "PROJECT PATTERN",
 }
 
@@ -194,6 +196,7 @@ MANAGED_HEADINGS: dict[FindingKind, str] = {
     FindingKind.STALE_CONTEXT: "## Context hygiene",
     FindingKind.TOOL_THRASH:   "## Tool-call discipline",
     FindingKind.DEAD_END:      "## Exploration discipline",
+    FindingKind.FANOUT_WASTE:  "## Fan-out discipline",
 }
 
 # Project-specific patterns use a heading that embeds tool+key, so the managed
@@ -294,6 +297,31 @@ class AggregateReport:
     project_patterns:       list[ProjectPattern] = field(default_factory=list)
 
 
+@dataclass
+class EfficacyRow:
+    """One row in a patch efficacy report — before/after session counts for a managed heading."""
+
+    heading: str                  # e.g. "## Retry discipline"
+    kind: FindingKind | None      # reverse lookup from MANAGED_HEADINGS; None = not found
+    applied_at: datetime | None   # first git commit that introduced this heading; None if unknown
+    sessions_before: int          # sessions with this kind's finding before applied_at
+    sessions_after: int           # sessions with this kind's finding from applied_at onward
+    total_before: int             # total sessions analysed before applied_at
+    total_after: int              # total sessions analysed from applied_at onward
+    weeks_before: float           # (applied_at - oldest_session_start).days / 7
+    weeks_after: float            # (newest_session_start - applied_at).days / 7
+
+
+@dataclass
+class EfficacyReport:
+    """Aggregated before/after report across all managed CLAUDE.md headings."""
+
+    rows: list[EfficacyRow]
+    total_sessions: int
+    oldest_session: datetime | None  # min start_time across all analysed sessions
+    newest_session: datetime | None  # max start_time across all analysed sessions
+
+
 # ---------------------------------------------------------------------------
 # Renderer helper
 # ---------------------------------------------------------------------------

{cctx_cli-1.7.0 → cctx_cli-1.9.0}/cctx/recommender/claude_md.py

@@ -57,6 +57,15 @@ _DEAD_END_DIFF = """\
 +approaches already ruled out, and pick a meaningfully different one. Sunk effort on a
 +failing approach is not a reason to continue it."""
 
+_FANOUT_WASTE_DIFF = """\
++## Fan-out discipline
++
++Before spawning multiple subagents in parallel, state what each one will return
++and verify the tasks don't overlap. After each subagent completes, confirm its
++result is actually consumed by the parent before spawning retries. Retry only
++after changing something meaningful about the task — identical re-spawns waste
++the full subagent cost with no new information."""
+
 _TEMPLATES: dict[FindingKind, tuple[str, str, str]] = {
     # kind → (description, diff_body, target_file)
     FindingKind.RETRY_LOOP:    ("Add retry discipline rule", _RETRY_LOOP_DIFF, "CLAUDE.md"),
@@ -64,6 +73,7 @@ _TEMPLATES: dict[FindingKind, tuple[str, str, str]] = {
     FindingKind.STALE_CONTEXT: ("Add context hygiene rule", _STALE_CONTEXT_DIFF, "CLAUDE.md"),
     FindingKind.TOOL_THRASH:   ("Add tool-call discipline rule", _TOOL_THRASH_DIFF, "CLAUDE.md"),
     FindingKind.DEAD_END:      ("Add exploration discipline rule", _DEAD_END_DIFF, "CLAUDE.md"),
+    FindingKind.FANOUT_WASTE:  ("Add fan-out discipline rule", _FANOUT_WASTE_DIFF, "CLAUDE.md"),
 }
 
 

cctx_cli-1.9.0/cctx/recommender/evidence.py

@@ -0,0 +1,129 @@
+"""Cross-session evidence accumulation.
+
+accumulate(diagnoses) -> dict[FindingKind, KindEvidence]
+
+Counts how many sessions triggered each finding kind and sums waste cost.
+Per the spec, session_count increments once per session per kind, regardless
+of how many findings of that kind appear in one session.
+Stores up to 3 example_summaries for the renderer.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from cctx.models import (
+    MANAGED_HEADINGS,  # noqa: E402 — after stdlib, isort groups together
+    Diagnosis,
+    EfficacyReport,
+    EfficacyRow,
+    FindingKind,
+    KindEvidence,
+    SessionTrace,
+)
+from cctx.recommender.claude_md import summarize
+
+if TYPE_CHECKING:
+    from cctx.models import Finding
+
+
+_HEADING_TO_KIND: dict[str, FindingKind] = {v: k for k, v in MANAGED_HEADINGS.items()}
+
+
+def _summarize_finding(finding: Finding) -> str:
+    return summarize(finding)
+
+
+def accumulate(diagnoses: list[Diagnosis]) -> dict[FindingKind, KindEvidence]:
+    result: dict[FindingKind, KindEvidence] = {}
+    for diagnosis in diagnoses:
+        # Track which kinds we've already counted for this session to ensure
+        # session_count increments once per session per kind, not per finding.
+        seen_kinds: set[FindingKind] = set()
+        for finding in diagnosis.findings:
+            if finding.kind not in result:
+                result[finding.kind] = KindEvidence(
+                    kind=finding.kind,
+                    session_count=0,
+                    total_waste_usd=0.0,
+                    example_summaries=[],
+                )
+            ev = result[finding.kind]
+            if finding.kind not in seen_kinds:
+                ev.session_count += 1
+                seen_kinds.add(finding.kind)
+            ev.total_waste_usd += finding.cost_usd or 0.0
+            if len(ev.example_summaries) < 3:
+                ev.example_summaries.append(_summarize_finding(finding))
+    return result
+
+
+def _session_matches(diag: Diagnosis, kind: FindingKind | None) -> bool:
+    if kind is None:
+        return False
+    return any(f.kind is kind for f in diag.findings)
+
+
+def efficacy(
+    pairs: list[tuple[Diagnosis, SessionTrace]],
+    heading_dates: dict[str, datetime | None],
+) -> EfficacyReport:
+    """Compute before/after session counts for each managed CLAUDE.md heading.
+
+    For each heading in heading_dates:
+      - Sessions with start_time < applied_at → "before" bucket.
+      - Sessions with start_time >= applied_at → "after" bucket.
+      - Sessions with start_time=None are skipped entirely.
+      - If applied_at is None: all sessions go into "after" (no baseline).
+    """
+    valid_pairs = [(d, t) for d, t in pairs if t.start_time is not None]
+
+    oldest = min((t.start_time for _, t in valid_pairs), default=None)
+    newest = max((t.start_time for _, t in valid_pairs), default=None)
+
+    rows: list[EfficacyRow] = []
+
+    for heading, applied_at in heading_dates.items():
+        kind = _HEADING_TO_KIND.get(heading)
+
+        before_pairs = []
+        after_pairs = []
+        for diag, trace in valid_pairs:
+            if applied_at is None or trace.start_time >= applied_at:
+                after_pairs.append((diag, trace))
+            else:
+                before_pairs.append((diag, trace))
+
+        sessions_before = sum(1 for d, _ in before_pairs if _session_matches(d, kind))
+        sessions_after  = sum(1 for d, _ in after_pairs  if _session_matches(d, kind))
+
+        if applied_at is not None and oldest is not None:
+            weeks_before = max((applied_at - oldest).days, 0) / 7
+        else:
+            weeks_before = 0.0
+
+        if applied_at is not None and newest is not None:
+            weeks_after = max((newest - applied_at).days, 0) / 7
+        elif newest is not None and oldest is not None:
+            weeks_after = max((newest - oldest).days, 0) / 7
+        else:
+            weeks_after = 0.0
+
+        rows.append(EfficacyRow(
+            heading=heading,
+            kind=kind,
+            applied_at=applied_at,
+            sessions_before=sessions_before,
+            sessions_after=sessions_after,
+            total_before=len(before_pairs),
+            total_after=len(after_pairs),
+            weeks_before=weeks_before,
+            weeks_after=weeks_after,
+        ))
+
+    return EfficacyReport(
+        rows=rows,
+        total_sessions=len(valid_pairs),
+        oldest_session=oldest,
+        newest_session=newest,
+    )