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

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

@@ -2,6 +2,57 @@
 
 <!-- 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctx-cli
-Version: 1.8.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.8.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.8.0"
+__version__ = "1.9.0"

{cctx_cli-1.8.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.8.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.8.0 → cctx_cli-1.9.0}/cctx/models.py

@@ -297,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.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,
+    )

{cctx_cli-1.8.0 → cctx_cli-1.9.0}/cctx/renderers/terminal.py

@@ -5,6 +5,7 @@ render_aggregate(report, console=None) -> None
 render_harvest_results(results, dry_run=False, console=None) -> None
 render_projects(projects, live_statuses=None, console=None) -> None
 render_sessions(project, live_statuses=None, console=None) -> None
+render_efficacy_report(report, target_dir, project_dir, console=None) -> None
 
 Uses rich for formatting. Accepts an optional Console for testing.
 """
@@ -24,7 +25,7 @@ from cctx.models import KIND_LABEL, FindingKind, Severity
 
 if TYPE_CHECKING:
     from cctx.discovery import ProjectInfo
-    from cctx.models import AggregateReport, Diagnosis, SessionTrace
+    from cctx.models import AggregateReport, Diagnosis, EfficacyReport, EfficacyRow, SessionTrace
 
 _SEVERITY_STYLE = {
     Severity.HIGH:   "bold red",
@@ -39,6 +40,11 @@ def _default_console() -> Console:
     return Console()
 
 
+def _wide_console() -> Console:
+    """Console with fixed wide width to prevent table cell wrapping."""
+    return Console(width=200)
+
+
 def render_diagnosis(
     diagnosis: Diagnosis,
     *,
@@ -407,3 +413,89 @@ def render_sessions(
         Text("cctx autopsy <path>", style="bold") +
         Text("  to diagnose a session", style="dim")
     )
+
+
+def _efficacy_signal(row: EfficacyRow) -> str:
+    """Classify efficacy: ✓ effective | ↓ reduced | ✗ persisting | ? no baseline | ? not in git."""
+    if row.applied_at is None:
+        return "? not in git"
+    if row.sessions_before == 0:
+        return "? no baseline"
+    if row.total_after == 0:
+        return "? no post-patch data"
+    rate_before = row.sessions_before / max(row.weeks_before, 0.5)
+    rate_after  = row.sessions_after  / max(row.weeks_after,  0.5)
+    low = " (low sample)" if row.total_before < 3 or row.total_after < 3 else ""
+    if rate_after == 0 or rate_after < rate_before * 0.25:
+        return f"✓ effective{low}"
+    if rate_after < rate_before * 0.75:
+        return f"↓ reduced{low}"
+    return f"✗ persisting{low}"
+
+
+def render_efficacy_report(
+    report: EfficacyReport,
+    target_dir: Path,
+    project_dir: Path,
+    *,
+    console: Console | None = None,
+) -> None:
+    """Render patch efficacy table to terminal."""
+    con = console or _default_console()
+
+    if report.total_sessions == 0:
+        con.print(f"No sessions found in {project_dir}.")
+        return
+
+    if not report.rows:
+        con.print(f"No managed headings found in CLAUDE.md at {target_dir / 'CLAUDE.md'}.")
+        return
+
+    range_str = ""
+    if report.oldest_session and report.newest_session:
+        oldest = report.oldest_session.strftime("%Y-%m-%d")
+        newest = report.newest_session.strftime("%Y-%m-%d")
+        range_str = f"   Range: {oldest} — {newest}"
+    con.print(Rule("cctx harvest --efficacy"))
+    con.print(f"Sessions: {report.total_sessions}{range_str}")
+    con.print(f"CLAUDE.md: {target_dir / 'CLAUDE.md'}")
+    con.print()
+
+    _SIGNAL_STYLE = {
+        "✓": "bold green",
+        "↓": "bold yellow",
+        "✗": "bold red",
+        "?": "dim",
+    }
+
+    # Build table for heading + applied + before/after counts.
+    # Signal is printed as a separate styled line per row so it is never
+    # truncated or wrapped regardless of terminal width.
+    table = Table(show_header=True, header_style="bold", box=None, padding=(0, 1))
+    table.add_column("Heading", style="bold", no_wrap=True)
+    table.add_column("Applied", no_wrap=True)
+    table.add_column("Before", no_wrap=True)
+    table.add_column("After", no_wrap=True)
+
+    row_signals: list[tuple[str, str]] = []  # (signal_text, style)
+
+    for row in report.rows:
+        if row.applied_at is None:
+            applied_str = "(not in git)"
+            before_str = "—"
+        else:
+            applied_str = row.applied_at.strftime("%Y-%m-%d")
+            before_str = f"{row.sessions_before}/{row.total_before} sessions"
+        after_str = f"{row.sessions_after}/{row.total_after} sessions"
+        signal = _efficacy_signal(row)
+        first_char = signal[0] if signal else "?"
+        signal_style = _SIGNAL_STYLE.get(first_char, "")
+        table.add_row(row.heading, applied_str, before_str, after_str)
+        row_signals.append((signal, signal_style))
+
+    con.print(table)
+    con.print()
+    for (signal, style), row in zip(row_signals, report.rows, strict=True):
+        prefix = Text(f"  {row.heading}: ", style="dim")
+        signal_text = Text(signal, style=style)
+        con.print(prefix + signal_text, soft_wrap=True)

{cctx_cli-1.8.0 → cctx_cli-1.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cctx-cli"
-version = "1.8.0"
+version = "1.9.0"
 description = "Diagnose Claude Code sessions — find what went wrong, what it cost, and what to add to CLAUDE.md"
 readme = "README.md"
 requires-python = ">=3.10"