mapify-cli 3.22.0__py3-none-any.whl → 3.23.0__py3-none-any.whl

mapify_cli/__init__.py

@@ -23,8 +23,9 @@ Or install globally:
     mapify check
 """
 
-__version__ = "3.22.0"
+__version__ = "3.23.0"
 
+import json
 import os
 import subprocess
 import sys
@@ -173,6 +174,20 @@ governance_app = typer.Typer(
 
 app.add_typer(governance_app, name="governance")
 
+preset_app = typer.Typer(
+    name="preset",
+    help="Manage MAP workflow customization presets.",
+)
+
+app.add_typer(preset_app, name="preset")
+
+prompt_profile_app = typer.Typer(
+    name="prompt-profile",
+    help="Manage MAP prompt profiles — versioned, eval-gated prompt lifecycle.",
+)
+
+app.add_typer(prompt_profile_app, name="prompt-profile")
+
 
 def version_callback(value: bool):
     """Callback to show version and exit."""
@@ -1762,6 +1777,557 @@ def uninstall(
         console.print("[dim]Nothing to do.[/dim]")
 
 
+# ---------------------------------------------------------------------------
+# Preset management commands (#291)
+# ---------------------------------------------------------------------------
+
+_PRESET_MANIFEST_KEYS = ("id", "title", "version")
+
+
+def _presets_dir(project_dir: Path) -> Path:
+    return project_dir / ".map" / "presets"
+
+
+def _read_preset_manifest(preset_path: Path) -> dict[str, Any] | None:
+    manifest_path = preset_path / "manifest.json"
+    if not manifest_path.is_file():
+        return None
+    try:
+        return json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+@preset_app.command("list")
+def preset_list(
+    project_path: Optional[Path] = typer.Argument(
+        None,
+        help="Project root directory (defaults to current directory).",
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """List installed MAP presets in a project's .map/presets/ directory."""
+    target = project_path or Path.cwd()
+    presets_root = _presets_dir(target)
+
+    if not presets_root.is_dir():
+        if output_json:
+            typer.echo(json.dumps({"presets": []}))
+        else:
+            console.print("[dim]No presets installed. Use 'mapify preset add --from <path>' to install one.[/dim]")
+        return
+
+    presets: list[dict[str, Any]] = []
+    for entry in sorted(presets_root.iterdir()):
+        if not entry.is_dir():
+            continue
+        manifest = _read_preset_manifest(entry)
+        if manifest is None:
+            presets.append({"id": entry.name, "title": entry.name, "version": "?", "description": "(no manifest)"})
+        else:
+            presets.append({
+                "id": manifest.get("id", entry.name),
+                "title": manifest.get("title", entry.name),
+                "version": manifest.get("version", "?"),
+                "description": manifest.get("description", ""),
+            })
+
+    if output_json:
+        typer.echo(json.dumps({"presets": presets}))
+        return
+
+    if not presets:
+        console.print("[dim]No presets installed. Use 'mapify preset add --from <path>' to install one.[/dim]")
+        return
+
+    table = Table(title="Installed MAP Presets", show_header=True, header_style="bold cyan")
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("Title")
+    table.add_column("Version", style="dim")
+    table.add_column("Description", style="dim")
+    for p in presets:
+        table.add_row(p["id"], p["title"], p["version"], p.get("description", ""))
+    console.print(table)
+
+
+@preset_app.command("add")
+def preset_add(
+    from_path: Path = typer.Option(
+        ...,
+        "--from",
+        help="Path to a preset directory containing manifest.json.",
+        show_default=False,
+    ),
+    project_path: Optional[Path] = typer.Argument(
+        None,
+        help="Project root directory (defaults to current directory).",
+    ),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite if already installed."),
+) -> None:
+    """Install a MAP preset from a local directory into .map/presets/.
+
+    The source directory must contain a manifest.json with at least: id, title, version.
+    """
+    if not from_path.is_dir():
+        console.print(f"[red]Error:[/red] '{from_path}' is not a directory.")
+        raise typer.Exit(1)
+
+    manifest = _read_preset_manifest(from_path)
+    if manifest is None:
+        console.print(
+            f"[red]Error:[/red] No valid manifest.json found in '{from_path}'.\n"
+            "A preset directory must contain manifest.json with 'id', 'title', and 'version' keys."
+        )
+        raise typer.Exit(1)
+
+    missing = [k for k in _PRESET_MANIFEST_KEYS if k not in manifest]
+    if missing:
+        console.print(
+            f"[red]Error:[/red] manifest.json is missing required keys: {', '.join(missing)}"
+        )
+        raise typer.Exit(1)
+
+    preset_id: str = manifest["id"]
+    if not preset_id or "/" in preset_id or "\\" in preset_id or ".." in preset_id:
+        console.print(
+            f"[red]Error:[/red] Invalid preset id '{preset_id}' — must be a plain name (no path separators)."
+        )
+        raise typer.Exit(1)
+
+    target = project_path or Path.cwd()
+    dest = _presets_dir(target) / preset_id
+
+    if dest.exists() and not force:
+        console.print(
+            f"[yellow]Preset '{preset_id}' is already installed.[/yellow] "
+            "Use --force to overwrite."
+        )
+        raise typer.Exit(1)
+
+    if dest.exists():
+        shutil.rmtree(dest)
+
+    shutil.copytree(str(from_path), str(dest))
+    console.print(
+        f"[green]Preset '{preset_id}'[/green] ({manifest.get('title', preset_id)} "
+        f"v{manifest.get('version', '?')}) installed to {dest}."
+    )
+
+
+def _preset_state_path(preset_dir: Path) -> Path:
+    return preset_dir / ".state.json"
+
+
+def _read_preset_state(preset_dir: Path) -> dict[str, Any]:
+    path = _preset_state_path(preset_dir)
+    if not path.is_file():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _write_preset_state(preset_dir: Path, state: dict[str, Any]) -> None:
+    _preset_state_path(preset_dir).write_text(json.dumps(state, indent=2), encoding="utf-8")
+
+
+def _is_preset_enabled(preset_dir: Path) -> bool:
+    return _read_preset_state(preset_dir).get("enabled", True)
+
+
+def _resolve_installed_preset(presets_root: Path, preset_id: str) -> Path | None:
+    candidate = presets_root / preset_id
+    return candidate if candidate.is_dir() else None
+
+
+@preset_app.command("remove")
+def preset_remove(
+    preset_id: str = typer.Argument(..., help="ID of the preset to remove."),
+    project_path: Optional[Path] = typer.Argument(
+        None,
+        help="Project root directory (defaults to current directory).",
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+) -> None:
+    """Remove an installed MAP preset from .map/presets/."""
+    target = project_path or Path.cwd()
+    preset_dir = _resolve_installed_preset(_presets_dir(target), preset_id)
+    if preset_dir is None:
+        console.print(f"[red]Error:[/red] Preset '{preset_id}' is not installed.")
+        raise typer.Exit(1)
+
+    if not yes:
+        confirm = typer.confirm(f"Remove preset '{preset_id}'?", default=False)
+        if not confirm:
+            console.print("[dim]Aborted.[/dim]")
+            raise typer.Exit(0)
+
+    shutil.rmtree(preset_dir)
+    console.print(f"[green]Preset '{preset_id}' removed.[/green]")
+
+
+@preset_app.command("enable")
+def preset_enable(
+    preset_id: str = typer.Argument(..., help="ID of the preset to enable."),
+    project_path: Optional[Path] = typer.Argument(
+        None,
+        help="Project root directory (defaults to current directory).",
+    ),
+) -> None:
+    """Enable a disabled MAP preset."""
+    target = project_path or Path.cwd()
+    preset_dir = _resolve_installed_preset(_presets_dir(target), preset_id)
+    if preset_dir is None:
+        console.print(f"[red]Error:[/red] Preset '{preset_id}' is not installed.")
+        raise typer.Exit(1)
+
+    state = _read_preset_state(preset_dir)
+    state["enabled"] = True
+    _write_preset_state(preset_dir, state)
+    console.print(f"[green]Preset '{preset_id}' enabled.[/green]")
+
+
+@preset_app.command("disable")
+def preset_disable(
+    preset_id: str = typer.Argument(..., help="ID of the preset to disable."),
+    project_path: Optional[Path] = typer.Argument(
+        None,
+        help="Project root directory (defaults to current directory).",
+    ),
+) -> None:
+    """Disable a MAP preset without uninstalling it."""
+    target = project_path or Path.cwd()
+    preset_dir = _resolve_installed_preset(_presets_dir(target), preset_id)
+    if preset_dir is None:
+        console.print(f"[red]Error:[/red] Preset '{preset_id}' is not installed.")
+        raise typer.Exit(1)
+
+    state = _read_preset_state(preset_dir)
+    state["enabled"] = False
+    _write_preset_state(preset_dir, state)
+    console.print(f"[yellow]Preset '{preset_id}' disabled.[/yellow]")
+
+
+@preset_app.command("resolve")
+def preset_resolve(
+    template_name: str = typer.Argument(..., help="Template name to resolve (e.g. 'map-efficient.md')."),
+    project_path: Optional[Path] = typer.Argument(
+        None,
+        help="Project root directory (defaults to current directory).",
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Show which preset layers contribute to a template in resolution order.
+
+    Resolution order (highest priority first): project overrides → enabled presets → core templates.
+    """
+    target = project_path or Path.cwd()
+    presets_root = _presets_dir(target)
+
+    layers: list[dict[str, Any]] = []
+
+    # Tier 1: project overrides
+    project_override = target / ".map" / "overrides" / template_name
+    if project_override.is_file():
+        layers.append({"tier": "project-override", "path": str(project_override), "enabled": True})
+
+    # Tier 2: installed presets (sorted alphabetically for determinism)
+    if presets_root.is_dir():
+        for entry in sorted(presets_root.iterdir()):
+            if not entry.is_dir():
+                continue
+            enabled = _is_preset_enabled(entry)
+            template_path = entry / "templates" / template_name
+            if template_path.is_file():
+                manifest = _read_preset_manifest(entry)
+                strategy = (manifest or {}).get("strategies", {}).get(template_name, "append")
+                layers.append({
+                    "tier": "preset",
+                    "preset_id": entry.name,
+                    "path": str(template_path),
+                    "strategy": strategy,
+                    "enabled": enabled,
+                })
+
+    # Tier 3: core template (shipped by mapify)
+    try:
+        core_path = get_templates_dir() / template_name
+        if core_path.is_file():
+            layers.append({"tier": "core", "path": str(core_path), "enabled": True})
+    except Exception:
+        pass
+
+    if output_json:
+        typer.echo(json.dumps({"template": template_name, "layers": layers}))
+        return
+
+    if not layers:
+        console.print(f"[dim]No layers found for template '{template_name}'.[/dim]")
+        return
+
+    console.print(f"[bold]Resolution layers for:[/bold] [cyan]{template_name}[/cyan]")
+    for i, layer in enumerate(layers, 1):
+        tier = layer["tier"]
+        enabled_str = "" if layer.get("enabled", True) else " [dim](disabled)[/dim]"
+        strategy_str = f" strategy=[cyan]{layer['strategy']}[/cyan]" if "strategy" in layer else ""
+        preset_str = f" preset=[cyan]{layer['preset_id']}[/cyan]" if "preset_id" in layer else ""
+        console.print(f"  {i}. tier={tier}{preset_str}{strategy_str}{enabled_str} → {layer['path']}")
+
+
+# ---------------------------------------------------------------------------
+# Preset composition helpers (Slice 3)
+# ---------------------------------------------------------------------------
+
+_COMPOSITION_STRATEGIES = frozenset({"replace", "prepend", "append", "wrap"})
+_WRAP_PLACEHOLDER = "{CORE_TEMPLATE}"
+
+
+def _preset_priority(preset_dir: Path) -> int:
+    state = _read_preset_state(preset_dir)
+    return int(state.get("priority", 50))
+
+
+def _compose_template(core_content: str, layer_content: str, strategy: str) -> str:
+    """Apply a composition strategy to produce the final template content."""
+    if strategy == "replace":
+        return layer_content
+    if strategy == "prepend":
+        return layer_content + "\n" + core_content
+    if strategy == "append":
+        return core_content + "\n" + layer_content
+    if strategy == "wrap":
+        if _WRAP_PLACEHOLDER in layer_content:
+            return layer_content.replace(_WRAP_PLACEHOLDER, core_content)
+        return layer_content + "\n" + core_content
+    return core_content
+
+
+def _build_resolution_order(presets_root: Path, template_name: str) -> list[dict[str, Any]]:
+    """Return enabled preset layers for a template, sorted by priority descending."""
+    layers: list[dict[str, Any]] = []
+    if not presets_root.is_dir():
+        return layers
+    for entry in presets_root.iterdir():
+        if not entry.is_dir() or not _is_preset_enabled(entry):
+            continue
+        template_path = entry / "templates" / template_name
+        if not template_path.is_file():
+            continue
+        manifest = _read_preset_manifest(entry)
+        strategy = (manifest or {}).get("strategies", {}).get(template_name, "append")
+        layers.append({
+            "preset_id": entry.name,
+            "path": template_path,
+            "strategy": strategy,
+            "priority": _preset_priority(entry),
+        })
+    layers.sort(key=lambda x: x["priority"], reverse=True)
+    return layers
+
+
+@preset_app.command("render")
+def preset_render(
+    template_name: str = typer.Argument(..., help="Template name to render (e.g. 'map-efficient.md')."),
+    project_path: Optional[Path] = typer.Argument(
+        None,
+        help="Project root directory (defaults to current directory).",
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Output rendered content as JSON."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Print composed content without writing to disk."),
+) -> None:
+    """Compose a template by layering enabled presets over the core template.
+
+    Strategies (applied highest-priority first):
+      replace — preset content replaces the core entirely
+      prepend — preset content is inserted above the core
+      append  — preset content is inserted below the core
+      wrap    — preset content wraps the core via {CORE_TEMPLATE} placeholder
+    """
+    target = project_path or Path.cwd()
+    presets_root = _presets_dir(target)
+
+    # Start from project override if present, else core template
+    project_override = target / ".map" / "overrides" / template_name
+    if project_override.is_file():
+        composed = project_override.read_text(encoding="utf-8")
+        source = f"project-override:{project_override}"
+    else:
+        try:
+            core_path = get_templates_dir() / template_name
+            if core_path.is_file():
+                composed = core_path.read_text(encoding="utf-8")
+                source = f"core:{core_path}"
+            else:
+                composed = ""
+                source = "core:(not found)"
+        except Exception:
+            composed = ""
+            source = "core:(error)"
+
+    layers = _build_resolution_order(presets_root, template_name)
+    applied: list[str] = []
+    for layer in layers:
+        layer_content = Path(layer["path"]).read_text(encoding="utf-8")
+        strategy: str = layer["strategy"]
+        if strategy not in _COMPOSITION_STRATEGIES:
+            strategy = "append"
+        composed = _compose_template(composed, layer_content, strategy)
+        applied.append(f"{layer['preset_id']}({strategy})")
+
+    if output_json:
+        typer.echo(json.dumps({
+            "template": template_name,
+            "source": source,
+            "applied_layers": applied,
+            "content": composed,
+        }))
+        return
+
+    if dry_run or True:
+        console.print(f"[bold]Composed:[/bold] [cyan]{template_name}[/cyan]")
+        if applied:
+            console.print(f"[dim]Layers applied:[/dim] {' → '.join(applied)}")
+        else:
+            console.print("[dim]No preset layers matched; showing core/override content.[/dim]")
+        console.print()
+        console.print(composed)
+
+
+@preset_app.command("set-priority")
+def preset_set_priority(
+    preset_id: str = typer.Argument(..., help="ID of the preset to reprioritize."),
+    priority: int = typer.Argument(..., help="Priority value (higher = applied first). Default: 50."),
+    project_path: Optional[Path] = typer.Argument(
+        None,
+        help="Project root directory (defaults to current directory).",
+    ),
+) -> None:
+    """Set the composition priority of an installed preset.
+
+    Higher priority presets are applied first in the composition stack.
+    When two presets target the same template, the one with higher priority
+    has its strategy applied first, then lower-priority presets layer on top.
+    """
+    target = project_path or Path.cwd()
+    preset_dir = _resolve_installed_preset(_presets_dir(target), preset_id)
+    if preset_dir is None:
+        console.print(f"[red]Error:[/red] Preset '{preset_id}' is not installed.")
+        raise typer.Exit(1)
+
+    state = _read_preset_state(preset_dir)
+    state["priority"] = priority
+    _write_preset_state(preset_dir, state)
+    console.print(f"[green]Preset '{preset_id}'[/green] priority set to {priority}.")
+
+
+# Prompt profile commands
+
+_PROFILE_MANIFEST_KEYS = ("id", "title", "version")
+
+
+def _prompt_profiles_dir(project_dir: Path) -> Path:
+    return project_dir / ".map" / "prompt-profiles"
+
+
+def _read_profile_manifest(profile_path: Path) -> dict[str, Any] | None:
+    manifest_path = profile_path / "manifest.json"
+    if not manifest_path.is_file():
+        return None
+    try:
+        return json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _read_active_profile(profiles_root: Path) -> str | None:
+    """Return the active profile id from active.json, or None."""
+    active_path = profiles_root / "active.json"
+    if not active_path.is_file():
+        return None
+    try:
+        data = json.loads(active_path.read_text(encoding="utf-8"))
+        return data.get("active") or None
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+@prompt_profile_app.command("list")
+def prompt_profile_list(
+    project_path: Path = typer.Option(
+        Path("."),
+        "--project-path",
+        "-p",
+        help="Root of the target project (where .map/ lives).",
+        resolve_path=True,
+    ),
+    output_json: bool = typer.Option(False, "--json", help="Emit JSON instead of a table."),
+) -> None:
+    """List installed MAP prompt profiles in a project's .map/prompt-profiles/ directory."""
+    from rich.table import Table
+
+    profiles_root = _prompt_profiles_dir(project_path)
+    active_id = _read_active_profile(profiles_root)
+
+    profiles: list[dict[str, Any]] = []
+
+    if profiles_root.is_dir():
+        for entry in sorted(profiles_root.iterdir()):
+            if not entry.is_dir():
+                continue
+            manifest = _read_profile_manifest(entry)
+            if manifest is None:
+                continue
+            missing = [k for k in _PROFILE_MANIFEST_KEYS if k not in manifest]
+            if missing:
+                continue
+            profiles.append({
+                "id": manifest["id"],
+                "title": manifest["title"],
+                "version": manifest["version"],
+                "description": manifest.get("description", ""),
+                "targets": manifest.get("targets", []),
+                "active": manifest["id"] == active_id,
+            })
+
+    if output_json:
+        console.print_json(json.dumps({"profiles": profiles, "active": active_id}))
+        return
+
+    if not profiles:
+        console.print("No prompt profiles found in .map/prompt-profiles/.")
+        console.print(
+            "Create a profile at .map/prompt-profiles/<id>/manifest.json "
+            "with required keys: id, title, version."
+        )
+        return
+
+    table = Table(title="Prompt Profiles", box=None, show_header=True, header_style="bold")
+    table.add_column("ID", style="cyan")
+    table.add_column("Title")
+    table.add_column("Version")
+    table.add_column("Status")
+    table.add_column("Description")
+
+    for profile in profiles:
+        status = "active" if profile["active"] else "installed"
+        table.add_row(
+            profile["id"],
+            profile["title"],
+            profile["version"],
+            status,
+            profile["description"] or "",
+        )
+
+    console.print(table)
+
+    if active_id and not any(p["id"] == active_id for p in profiles):
+        console.print(
+            f"[yellow]Warning:[/yellow] active profile '{active_id}' not found in "
+            f".map/prompt-profiles/. The active.json pointer may be stale."
+        )
+
+
 # Research localization eval commands
 
 
@@ -2422,6 +2988,222 @@ def skill_eval_view(
         _open_best_effort(html)
 
 
+# ---------------------------------------------------------------------------
+# skill-eval trajectory (issue #351: AgentLens-style outcome eval)
+# ---------------------------------------------------------------------------
+
+
+@skill_eval_app.command("trajectory")
+def skill_eval_trajectory(
+    skill: str = typer.Argument(
+        ..., help="Skill under evaluation, e.g. map-task"
+    ),
+    fixture: Optional[Path] = typer.Option(
+        None,
+        "--fixture",
+        help="Path to a whole-skill fixture directory (manifest.json + repo/).",
+    ),
+    runs: int = typer.Option(
+        3,
+        "--runs",
+        min=1,
+        help="Repeated runs per fixture (default 3) for variance / flaky detection.",
+    ),
+    variant: str = typer.Option(
+        "good",
+        "--variant",
+        help="Seed variant: 'good' (baseline) or 'bad' (degrade seeded copy).",
+    ),
+    degrade: str = typer.Option(
+        "body", "--degrade", help="What the 'bad' variant degrades: body|actor|monitor."
+    ),
+    timeout: float = typer.Option(
+        3600.0, "--timeout", help="Per-run claude -p timeout (seconds)."
+    ),
+    judge_timeout: float = typer.Option(
+        360.0, "--judge-timeout", help="Per-run batched judge claude -p timeout."
+    ),
+    no_judge: bool = typer.Option(
+        False,
+        "--no-judge",
+        help="Skip the LLM judge (deterministic components only). Cheapest.",
+    ),
+    anchor: Optional[str] = typer.Option(
+        None,
+        "--anchor",
+        help="Compare against a prior run: path to a .jsonl, or 'latest'.",
+    ),
+    out: Optional[Path] = typer.Option(
+        None, "--out", help="Output .jsonl path (default .map/eval-runs/trajectory/...)."
+    ),
+    resume: bool = typer.Option(
+        False, "--resume", help="Resume the latest run, skipping present run_ids."
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Validate fixture + print planned runs; spend nothing, no dispatcher.",
+    ),
+    open_html: bool = typer.Option(
+        False, "--open", help="Open the side-by-side report in the default browser."
+    ),
+) -> None:
+    """Run a trajectory-level outcome eval over a full skill run (issue #351).
+
+    Seeds an isolated project, executes the whole skill body, scores six
+    component metrics (formal/end_result/tool_use deterministic +
+    instruction_compliance/pitfalls/reporting_trust from one batched judge
+    call), aggregates repeated runs (median/variance/hard-pass/flaky), and
+    optionally renders a candidate-vs-anchor side-by-side regression report.
+
+    Exit codes:
+      0 - Success (or dry-run completed)
+      1 - Runtime error (claude not found, or unexpected failure)
+      2 - Validation error (missing --fixture or malformed fixture)
+    """
+    from datetime import timezone
+
+    import mapify_cli.skills_eval.trajectory.judge as _judge
+    import mapify_cli.skills_eval.trajectory.runner as _trunner
+    from mapify_cli.skills_eval.trajectory.dispatcher import (
+        ClaudeTrajectoryDispatcher,
+    )
+    from mapify_cli.skills_eval.trajectory.report import (
+        build_report,
+        render_comparison_to_path,
+    )
+    from mapify_cli.skills_eval.trajectory.repeated import aggregate_repeated
+
+    # SC-2: --fixture is required.
+    if fixture is None:
+        console.print("[bold red]Error:[/bold red] provide --fixture PATH")
+        raise typer.Exit(2)
+    if not fixture.is_dir():
+        console.print(f"[bold red]Error:[/bold red] fixture dir not found: {fixture}")
+        raise typer.Exit(2)
+
+    # Validate the manifest BEFORE dry-run and before any dispatcher.
+    try:
+        manifest = _trunner.load_fixture_manifest(fixture)
+    except ValueError as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise typer.Exit(2)
+
+    root = Path.cwd()
+    run_ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+
+    if out is not None:
+        out_path = out
+    elif resume:
+        latest = _trunner.latest_run_path(root, skill)
+        out_path = latest if latest is not None else _trunner.default_run_path(
+            root, skill, run_ts
+        )
+    else:
+        out_path = _trunner.default_run_path(root, skill, run_ts)
+
+    # Dry-run: zero quota, NO dispatcher, NO claude required.
+    if dry_run:
+        planned = 1 * runs
+        console.print(
+            f"[bold]Dry-run:[/bold] fixture=[bold]{manifest['fixture']}[/bold] "
+            f"skill=[bold]{skill}[/bold] variant=[cyan]{variant}[/cyan] "
+            f"runs=[cyan]{planned}[/cyan] judge=[cyan]{'off' if no_judge else 'on'}[/cyan] "
+            f"— spends 0 quota"
+        )
+        raise typer.Exit(0)
+
+    # HC-6: require claude BEFORE any invocation (real run or judge).
+    if shutil.which("claude") is None:
+        console.print(
+            "[bold red]Error:[/bold red] requires-cmd: claude — "
+            "install the claude CLI and ensure it is on PATH"
+        )
+        raise typer.Exit(1)
+
+    dispatcher: object = ClaudeTrajectoryDispatcher()
+    judge_runner = None if no_judge else _judge.ClaudeJudgeRunner()
+
+    _trunner.run_matrix(
+        fixture_dirs=[fixture],
+        repo_root=root,
+        dispatcher=dispatcher,  # type: ignore[arg-type]
+        runs=runs,
+        out_path=out_path,
+        ts=run_ts,
+        judge_runner=judge_runner,
+        judge_timeout=judge_timeout,
+        run_timeout=timeout,
+        variant=variant,
+        degrade=degrade,
+        resume=resume,
+    )
+
+    records = _trunner.read_records(out_path)
+    agg = aggregate_repeated(records)
+    fa = agg.fixture(str(manifest["fixture"]))
+    median_str = (
+        f"{fa.composite_median:.3f}" if fa else "n/a"
+    )
+    hp_str = (
+        f"{fa.hard_pass_count}/{fa.n}" if fa else "n/a"
+    )
+    flaky_str = (
+        f" flaky=[cyan]{'; '.join(fa.flaky_reasons)}[/cyan]"
+        if fa and fa.flaky
+        else ""
+    )
+    console.print(
+        f"\n[bold]Trajectory eval complete:[/bold] skill=[bold]{skill}[/bold] "
+        f"fixture=[bold]{manifest['fixture']}[/bold] "
+        f"composite_median=[cyan]{median_str}[/cyan] "
+        f"hard_pass=[cyan]{hp_str}[/cyan]{flaky_str}"
+    )
+    console.print(f"  records: [cyan]{out_path}[/cyan]")
+
+    # Side-by-side regression report against an anchor run.
+    if anchor is not None:
+        anchor_path = _resolve_anchor(anchor, root, skill)
+        if anchor_path is None or not anchor_path.is_file():
+            console.print(
+                f"[bold red]Error:[/bold red] anchor run not found: {anchor}"
+            )
+            raise typer.Exit(1)
+        anchor_records = _trunner.read_records(anchor_path)
+        report = build_report(
+            records,
+            anchor_records,
+            candidate_path=str(out_path),
+            anchor_path=str(anchor_path),
+        )
+        html_path = out_path.with_suffix(".html")
+        render_comparison_to_path(report, html_path)
+        reg = report.n_regressions
+        console.print(
+            f"  side-by-side: [cyan]{html_path}[/cyan] "
+            f"({reg} regression(s) vs anchor)"
+        )
+        if open_html:
+            _open_best_effort(html_path)
+
+    if dry_run is False and no_judge:
+        console.print("  [dim]judge skipped (--no-judge)[/dim]")
+
+
+def _resolve_anchor(anchor: str, root: Path, skill: str) -> Optional[Path]:
+    """Resolve ``--anchor`` to a .jsonl path ('latest' or an explicit path)."""
+    if anchor == "latest":
+        latest_dir = root / ".map" / "eval-runs" / "trajectory" / skill
+        candidates = sorted(latest_dir.glob("*.jsonl")) if latest_dir.is_dir() else []
+        # Exclude the candidate currently being written by picking the
+        # previous-to-last when two exist; callers pass 'latest' meaning the
+        # most recent PRIOR run.
+        return candidates[-2] if len(candidates) >= 2 else (
+            candidates[-1] if candidates else None
+        )
+    return Path(anchor)
+
+
 def main():
     app()