Separate analyzer workspace from target repo

The analyzer was previously installing its bundled judge subagent inside
the target repo's .claude/ and writing reports + cache there too. This
mixed the analyzer's tooling with the target's project configuration and
left behind artifacts (.ai-dev-effectiveness-cache/, effectiveness-report.html,
the judge agent itself) in any repo it touched.

New flow:

  mkdir ~/dev-effectiveness && cd ~/dev-effectiveness
  ai-dev-effectiveness init-judge        # installs ./.claude/agents/effort-judge.md
  ai-dev-effectiveness analyze /some/target-repo --judge claude-cli
  # → reports + cache go to ./target-repo/
  # → target repo is read-only

Implementation:

- analyze() takes new `workspace` and `out_dir` kwargs. Agent path and
  judge cache dir are resolved as absolute paths inside the workspace
  (overriding any YAML setting) so the target repo is guaranteed read-only.
- AnalysisResult exposes `.workspace` and `.out_dir`; `.default_out_path(fmt)`
  returns the per-target output location.
- Judge subprocess CWD remains the target (so Read/Grep/git show operate
  on target content) but the agent definition comes from the analyzer
  workspace via absolute --agent path.
- New `ai_dev_effectiveness.ast_index` module: when `ast-index` is on
  PATH, runs `ast-index build` against the target before the judge
  starts. Best-effort; never fails the analysis. Disable with --no-ast-index
  or AI_DEV_EFFECTIVENESS_NO_AST_INDEX=1.
- CLI:
  * `analyze TARGET` — TARGET defaults to '.', out goes to $PWD/<basename>/
    when target != $PWD, else to $PWD (legacy single-repo mode).
  * `init-judge [WORKSPACE]` — WORKSPACE defaults to '.', help text
    explicitly says "NOT one of your project repos".
  * New flags: --workspace, --out-dir, --no-ast-index.
- Tests: added test_workspace_target_separation (verifies nothing lands
  in target) and test_target_equals_workspace_keeps_legacy_layout.
- README + case-study README rewritten around the new flow with a
  workspace-layout diagram.

Verified end-to-end on the HockeyBot worktree:
- Workspace at /tmp/ade-workspace/.claude/
- Output at /tmp/ade-workspace/musing-haslett-b9b799/
- Cache at /tmp/ade-workspace/musing-haslett-b9b799/.ai-dev-effectiveness-cache/
- Target /Users/denn/hockeybot_ws/.claude/worktrees/musing-haslett-b9b799/
  contains zero analyzer artifacts.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: denn-gubsky

README.md

@@ -8,12 +8,19 @@
 
 ```bash
 pipx install git+https://github.com/denn-gubsky/ai-dev-effectiveness
-cd /path/to/your/repo
-ai-dev-effectiveness analyze .
-open effectiveness-report.html
+
+# Pick a folder you'll run analyses from. NOT one of your project repos.
+mkdir -p ~/dev-effectiveness && cd ~/dev-effectiveness
+
+# Once: install the bundled judge subagent into THIS workspace.
+ai-dev-effectiveness init-judge
+
+# Now analyze any repo you want. Reports go to ./<target_basename>/.
+ai-dev-effectiveness analyze /path/to/your/repo
+open ./your-repo/effectiveness-report.html
 ```
 
-That's it. Zero config required for the first run — the tool auto-detects domains from your top-level dirs, classifies commits by language, and identifies AI co-authors from a built-in registry covering Claude (Opus/Sonnet/Haiku), GitHub Copilot, Cursor, Codex, Aider, Cody, Continue, Windsurf, Codeium, Tabnine, and Devin.
+The analyzer **never writes inside the target repo** — the bundled subagent, the judgment cache, and all reports live in your local workspace. Each target gets its own subfolder so you can compare repos side by side.
 
 ## What it measures
 
@@ -28,23 +35,48 @@ When all three agree within 2x, the multiplier is defensible. When they diverge,
 ## Optional: AI judge for diff-aware estimates
 
 ```bash
-ai-dev-effectiveness init-judge          # installs the bundled subagent into .claude/
-ai-dev-effectiveness analyze . --judge claude-cli
+cd ~/dev-effectiveness          # the workspace where init-judge ran
+ai-dev-effectiveness analyze /path/to/your/repo --judge claude-cli
+```
+
+The judge uses your existing Claude Code CLI session — no API key, no metered billing, no diffs leaving your machine. If you have [ast-index](https://github.com/asgardiandevs/ast-index) on your `PATH`, the analyzer runs `ast-index build` against the target before the judge starts so the bundled subagent can use `mcp__ast-index__*` tools for symbol-level lookups (much faster than grep-then-read for "find callers of this function").
+
+Other providers (opt-in): `--judge anthropic-api` (separate API key), `--judge openai`, `--judge ollama` (local model).
+
+Disable ast-index for a run: `--no-ast-index`.
+
+## Workspace layout
+
+```
+~/dev-effectiveness/                      # your analyzer workspace
+├── .claude/
+│   ├── agents/effort-judge.md           # ← installed by `init-judge`
+│   ├── skills/effort-estimation/SKILL.md
+│   └── settings.recommended.json
+├── ai_dev.yaml                          # optional: custom config (init-config)
+├── repo-a/                              # output for one analyzed target
+│   ├── effectiveness-report.html
+│   ├── effectiveness-report.json
+│   └── .ai-dev-effectiveness-cache/
+└── repo-b/                              # another target's outputs
+    └── ...
 ```
 
-The judge uses your existing Claude Code CLI session — no API key, no metered billing, no diffs leaving your machine. If you have [ast-index](https://github.com/defendend/Claude-ast-index-search) MCP configured, it's used for symbol-level lookups.
+Useful flags:
 
-Other providers: `--judge anthropic-api` (separate API key), `--judge openai`, `--judge ollama` (local model).
+- `--workspace PATH` — override the analyzer workspace (default: `$PWD`).
+- `--out-dir PATH` — override where this run's reports go.
+- `--judge-dry-run` — show what the judge would do (sample size, cost, paths) without invoking it.
 
 ## Case study
 
 [`examples/robotics-case-study/`](examples/robotics-case-study/) — anonymized analysis of a real 117K-LOC robotics project built by 1 dev + Claude over 10 months. Use it to see what a credible report looks like and to calibrate your own results.
 
 ## Customize
 
-- `ai-dev-effectiveness init-config` — drops `ai_dev.yaml` into your repo
-- Define your specialist roles, effort constants, agent signatures
-- See [`docs/REPRODUCTION_GUIDE.md`](docs/REPRODUCTION_GUIDE.md) and [`docs/config-reference.md`](docs/config-reference.md)
+- `ai-dev-effectiveness init-config` — drops `ai_dev.yaml` into your workspace.
+- Define your specialist roles, effort constants, agent signatures.
+- See [`docs/REPRODUCTION_GUIDE.md`](docs/REPRODUCTION_GUIDE.md) and [`docs/config-reference.md`](docs/config-reference.md).
 
 ## License
 

examples/robotics-case-study/README.md

@@ -74,10 +74,23 @@ The notebook walks through ten sections:
 
 ## Reproducing this on your own repo
 
-1. `pipx install git+https://github.com/denn-gubsky/ai-dev-effectiveness`
-2. `cd /path/to/your/repo`
-3. `ai-dev-effectiveness init-config && $EDITOR ai_dev.yaml` — edit the
-   `domains` and `roles` sections to match your project.
-4. `ai-dev-effectiveness analyze . --config ai_dev.yaml`
-5. Optionally: `ai-dev-effectiveness init-judge && ai-dev-effectiveness analyze . --config ai_dev.yaml --judge claude-cli`
-   to add the AI judge as a third estimator.
+```bash
+pipx install git+https://github.com/denn-gubsky/ai-dev-effectiveness
+
+# 1. Pick a workspace (NOT one of your project repos).
+mkdir -p ~/dev-effectiveness && cd ~/dev-effectiveness
+
+# 2. One-time: install the bundled judge subagent into the workspace.
+ai-dev-effectiveness init-judge
+
+# 3. Drop a config and edit the `domains` and `roles` sections to match
+#    your project. (Use this case study's ai_dev.yaml as a starting point.)
+ai-dev-effectiveness init-config && $EDITOR ai_dev.yaml
+
+# 4. Run the analysis. Reports land in ~/dev-effectiveness/<target_basename>/.
+ai-dev-effectiveness analyze /path/to/your/repo --config ai_dev.yaml \
+    --judge claude-cli
+```
+
+The analyzer is read-only with respect to your project — no `.claude/`, cache,
+or report files are ever created inside it.

src/ai_dev_effectiveness/__init__.py

@@ -17,6 +17,7 @@
 
 from . import (
     agent_detector,
+    ast_index,
     domain_classifier,
     effort_estimator,
     git_extractor,
@@ -46,6 +47,11 @@ class AnalysisResult:
     loc: pd.DataFrame
     metrics: _metrics.MetricsBundle
     figures: report_renderer.Figures
+    workspace: Path = Path(".")
+    out_dir: Path = Path(".")
+
+    def default_out_path(self, fmt: str) -> Path:
+        return self.out_dir / f"effectiveness-report.{fmt}"
 
     def to_html(self, path: str | Path | None = None) -> str:
         html = report_renderer.render_html(self.figures, self.config.project.name)
@@ -74,20 +80,38 @@ def to_json(self, path: str | Path | None = None) -> str:
 def analyze(
     repo: str | Path = ".",
     config: str | Path | Config | None = None,
+    workspace: str | Path | None = None,
+    out_dir: str | Path | None = None,
 ) -> AnalysisResult:
     """Run the full pipeline against `repo` and return an `AnalysisResult`.
 
     Args:
-        repo: path to a git repo. Walks up to find .git/.
+        repo: path to the target git repo. Walks up to find .git/. Read-only.
         config: path to ai_dev.yaml, an already-loaded Config, or None for defaults.
+        workspace: analyzer workspace where the bundled judge agent lives
+                   (`<workspace>/.claude/agents/effort-judge.md`). Defaults to cwd.
+        out_dir: where to write the report and cache. Defaults to:
+                   - `cwd` if the resolved target is the same as cwd, OR
+                   - `cwd/<basename(target)>` if the target is elsewhere.
+                 Either way, NOTHING is ever written to the target repo.
     """
     repo_path = _find_repo(Path(repo).resolve())
+    workspace_path = Path(workspace).resolve() if workspace else Path.cwd().resolve()
+    out_dir_path = _resolve_out_dir(out_dir, workspace_path, repo_path)
+    out_dir_path.mkdir(parents=True, exist_ok=True)
 
     if isinstance(config, Config):
         cfg = config
     else:
         cfg = _config.load(config) if config is not None else Config()
 
+    # Reroute judge artefacts to the analyzer workspace and the per-target
+    # output dir, regardless of what the YAML config said. This guarantees
+    # nothing lands inside the target repo.
+    cfg.judge.cache_dir = str(out_dir_path / ".ai-dev-effectiveness-cache")
+    cfg.judge.agent_path = str(workspace_path / ".claude/agents/effort-judge.md")
+    cfg.judge.skill_path = str(workspace_path / ".claude/skills/effort-estimation/SKILL.md")
+
     # 1. extract commits
     commits = git_extractor.extract_commits(repo_path)
     commits = git_extractor.add_week_columns(commits)
@@ -130,6 +154,11 @@ def analyze(
     # 7. optional AI judge — runs only if config.judge.enabled
     judge_summary_dict = None
     if cfg.judge.enabled:
+        # Best-effort: build the ast-index for the target so the bundled
+        # subagent can use mcp__ast-index__* tools for symbol-level lookups.
+        ok, msg = ast_index.build(repo_path)
+        print(f"  ast-index: {msg}", flush=True)
+
         judge_cfg = _judge.JudgeConfig(
             provider=cfg.judge.provider, model=cfg.judge.model,
             sample_size=cfg.judge.sample_size, judge_all=cfg.judge.judge_all,
@@ -163,6 +192,7 @@ def _progress(i, n, sha):
 
     return AnalysisResult(
         config=cfg, commits=commits, loc=loc_df, metrics=bundle, figures=figures,
+        workspace=workspace_path, out_dir=out_dir_path,
     )
 
 
@@ -175,6 +205,19 @@ def _find_repo(start: Path) -> Path:
     raise RuntimeError(f"No git repository found at or above {start}")
 
 
+def _resolve_out_dir(out_dir: str | Path | None, workspace: Path, target: Path) -> Path:
+    """Decide where to write reports and cache.
+
+    Default rule: workspace itself if target == workspace; else workspace/<basename(target)>.
+    Explicit `out_dir` always wins.
+    """
+    if out_dir is not None:
+        return Path(out_dir).resolve()
+    if target == workspace:
+        return workspace
+    return workspace / target.name
+
+
 def _project_months(commits: pd.DataFrame) -> float | None:
     if commits.empty:
         return None

src/ai_dev_effectiveness/ast_index.py

@@ -0,0 +1,55 @@
+"""Optional integration with ast-index (https://github.com/asgardiandevs/ast-index).
+
+When `ast-index` is on PATH, we run `ast-index build` against the target repo
+before invoking the judge. The bundled effort-judge subagent's tool allowlist
+includes `mcp__ast-index__*`, so the agent can do symbol-level lookups during
+its judgment if the user has the ast-index MCP server configured.
+
+This module is best-effort: every function returns gracefully when ast-index
+isn't installed or the build fails. The analysis pipeline never depends on it.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+
+def is_installed() -> bool:
+    """True iff `ast-index` is on PATH."""
+    return shutil.which("ast-index") is not None
+
+
+def build(target: Path, timeout_sec: int = 120) -> tuple[bool, str]:
+    """Run `ast-index build` in the target repo.
+
+    Args:
+        target: path to the repo to index. ast-index walks it itself.
+        timeout_sec: kill the build after this many seconds.
+
+    Returns:
+        (success, message) — `success` is False when ast-index isn't installed,
+        the build fails, or it times out. `message` is a short human-readable
+        status suitable for printing to the user.
+    """
+    import os
+    if os.environ.get("AI_DEV_EFFECTIVENESS_NO_AST_INDEX") == "1":
+        return (False, "ast-index disabled via AI_DEV_EFFECTIVENESS_NO_AST_INDEX=1.")
+    if not is_installed():
+        return (False, "ast-index not installed; skipping (install with `pipx install ast-index`).")
+
+    try:
+        proc = subprocess.run(
+            ["ast-index", "build"],
+            cwd=str(target),
+            capture_output=True, text=True,
+            timeout=timeout_sec, check=False,
+        )
+    except subprocess.TimeoutExpired:
+        return (False, f"ast-index build timed out after {timeout_sec}s.")
+    except OSError as e:
+        return (False, f"ast-index build failed to start: {e}")
+
+    if proc.returncode == 0:
+        return (True, "ast-index build OK")
+    return (False, f"ast-index build exited {proc.returncode}: {proc.stderr.strip()[:200]}")