invar-tools 1.0.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

invar/shell/{cli.py → commands/guard.py}

@@ -27,7 +27,7 @@ from invar.core.rules import check_all_rules
 from invar.core.utils import get_exit_code
 from invar.shell.config import load_config
 from invar.shell.fs import scan_project
-from invar.shell.guard_output import output_agent, output_json, output_rich
+from invar.shell.guard_output import output_agent, output_rich
 
 app = typer.Typer(
     name="invar",
@@ -37,6 +37,8 @@ app = typer.Typer(
 console = Console()
 
 
+# @shell_orchestration: Statistics helper for CLI guard output
+# @shell_complexity: Iterates symbols checking kind and contracts (4 branches minimal)
 def _count_core_functions(file_info) -> tuple[int, int]:
     """Count functions and functions with contracts in a Core file (P24)."""
     from invar.core.models import SymbolKind
@@ -54,11 +56,19 @@ def _count_core_functions(file_info) -> tuple[int, int]:
     return (total, with_contracts)
 
 
+# @shell_complexity: Core orchestration - iterates files, handles failures, aggregates results
+# @shell_complexity: Core orchestration - iterates files, handles failures, aggregates results
 def _scan_and_check(
     path: Path, config: RuleConfig, only_files: set[Path] | None = None
 ) -> Result[GuardReport, str]:
     """Scan project files and check against rules."""
+    from invar.core.entry_points import extract_escape_hatches
+    from invar.core.review_trigger import check_duplicate_escape_reasons
+    from invar.core.shell_architecture import check_complexity_debt
+
     report = GuardReport(files_checked=0)
+    all_escapes: list[tuple[str, str, str]] = []  # DX-33: (file, rule, reason)
+
     for file_result in scan_project(path, only_files):
         if isinstance(file_result, Failure):
             console.print(f"[yellow]Warning:[/yellow] {file_result.failure()}")
@@ -70,43 +80,64 @@ def _scan_and_check(
         report.update_coverage(total, with_contracts)
         for violation in check_all_rules(file_info, config):
             report.add_violation(violation)
+        # DX-33: Collect escape hatches for cross-file analysis
+        if file_info.source:
+            for rule, reason in extract_escape_hatches(file_info.source):
+                all_escapes.append((file_info.path, rule, reason))
+
+    # DX-22: Check project-level complexity debt (Fix-or-Explain enforcement)
+    for debt_violation in check_complexity_debt(
+        report.violations, config.shell_complexity_debt_limit
+    ):
+        report.add_violation(debt_violation)
+
+    # DX-33: Check for duplicate escape reasons across files
+    for escape_violation in check_duplicate_escape_reasons(all_escapes):
+        report.add_violation(escape_violation)
+
     return Success(report)
 
 
+# @invar:allow entry_point_too_thick: Main CLI entry point, orchestrates all verification phases
 @app.command()
 def guard(
     path: Path = typer.Argument(
         Path(), help="Project root directory", exists=True, file_okay=False, dir_okay=True
     ),
     strict: bool = typer.Option(False, "--strict", help="Treat warnings as errors"),
+    changed: bool = typer.Option(
+        False, "--changed", help="Only check git-modified files"
+    ),
+    static: bool = typer.Option(
+        False, "--static", help="Static analysis only, skip all runtime tests"
+    ),
+    human: bool = typer.Option(
+        False, "--human", help="Force human-readable output (for testing/debugging)"
+    ),
+    # DX-26: Deprecated flags kept for backward compatibility
     no_strict_pure: bool = typer.Option(
-        False, "--no-strict-pure", help="Disable purity checks (internal imports, impure calls)"
+        False, "--no-strict-pure", hidden=True, help="[Deprecated] Disable purity checks"
     ),
     pedantic: bool = typer.Option(
-        False, "--pedantic", help="Show all violations including off-by-default rules"
+        False, "--pedantic", hidden=True, help="[Deprecated] Show off-by-default rules"
     ),
     explain: bool = typer.Option(
-        False, "--explain", help="Show detailed explanations and limitations"
-    ),
-    changed: bool = typer.Option(
-        False, "--changed", help="Only check git-modified files"
+        False, "--explain", hidden=True, help="[Deprecated] Show detailed explanations"
     ),
     agent: bool = typer.Option(
-        False, "--agent", help="Output JSON with fix instructions for agents"
+        False, "--agent", help="Force JSON output (for inspecting agent format)"
     ),
     json_output: bool = typer.Option(
-        False, "--json", help="Output as JSON (simple format, no fix instructions)"
+        False, "--json", hidden=True, help="[Deprecated] Use TTY auto-detection instead"
     ),
-    static: bool = typer.Option(
-        False, "--static", help="Static analysis only, skip all runtime tests"
+    coverage: bool = typer.Option(
+        False, "--coverage", help="DX-37: Collect branch coverage from doctest + hypothesis"
     ),
 ) -> None:
     """Check project against Invar architecture rules.
 
     Smart Guard: Runs static analysis + doctests + CrossHair + Hypothesis by default.
     Use --static for quick static-only checks (~0.5s vs ~5s full).
-
-    DX-19: Simplified to 2 levels (Zero decisions).
     """
     from invar.shell.guard_helpers import (
         collect_files_to_check,
@@ -150,58 +181,106 @@ def guard(
         raise typer.Exit(1)
     report = scan_result.unwrap()
 
-    # Determine output mode
-    use_agent_output, use_json_output = _determine_output_mode(
-        json_output, agent
-    )
+    # DX-26: Simplified output mode (TTY auto-detect + --human override)
+    use_agent_output = _determine_output_mode(human, agent, json_output)
 
     # DX-19: Simplified to 2 levels (STATIC or STANDARD)
     verification_level = VerificationLevel.STATIC if static else VerificationLevel.STANDARD
     level_name = "STATIC" if static else "STANDARD"
 
     # Show verification level (human mode)
-    if not use_agent_output and not use_json_output:
+    if not use_agent_output:
         _show_verification_level(verification_level)
 
     # Run verification phases
     static_exit_code = get_exit_code(report, strict)
     doctest_passed, doctest_output = True, ""
-    crosshair_passed, crosshair_output = True, {}
-    property_passed, property_output = True, {}
+    crosshair_passed: bool = True
+    crosshair_output: dict = {}
+    property_passed: bool = True
+    property_output: dict = {}
+    # DX-37: Coverage data from doctest + hypothesis phases
+    doctest_coverage: dict | None = None
+    property_coverage: dict | None = None
+
+    # DX-37: Check coverage availability if requested
+    if coverage:
+        from invar.shell.coverage import check_coverage_available
+        cov_check = check_coverage_available()
+        if isinstance(cov_check, Failure):
+            console.print(f"[yellow]Warning:[/yellow] {cov_check.failure()}")
+            coverage = False  # Disable coverage if not available
 
     # DX-19: STANDARD runs all verification phases
     if verification_level == VerificationLevel.STANDARD and static_exit_code == 0:
         checked_files = collect_files_to_check(path, checked_files)
 
-        # Phase 1: Doctests
-        doctest_passed, doctest_output = run_doctests_phase(checked_files, explain)
+        # Phase 1: Doctests (DX-37: with optional coverage)
+        doctest_passed, doctest_output, doctest_coverage = run_doctests_phase(
+            checked_files, explain, timeout=config.timeout_doctest,
+            collect_coverage=coverage,
+        )
 
         # Phase 2: CrossHair symbolic verification
+        # Note: CrossHair uses subprocess + symbolic execution, coverage not applicable
         crosshair_passed, crosshair_output = run_crosshair_phase(
             path, checked_files, doctest_passed, static_exit_code,
             changed_mode=changed,
+            timeout=config.timeout_crosshair,
+            per_condition_timeout=config.timeout_crosshair_per_condition,
         )
 
-        # Phase 3: Hypothesis property tests
-        property_passed, property_output = run_property_tests_phase(
-            checked_files, doctest_passed, static_exit_code
+        # Phase 3: Hypothesis property tests (DX-37: with optional coverage)
+        property_passed, property_output, property_coverage = run_property_tests_phase(
+            checked_files, doctest_passed, static_exit_code,
+            collect_coverage=coverage,
         )
-
-    # Output results
+    elif verification_level == VerificationLevel.STATIC:
+        # Static-only mode: explicitly mark verification as skipped
+        crosshair_output = {"status": "skipped", "reason": "static mode"}
+        property_output = {"status": "skipped", "reason": "static mode"}
+    elif static_exit_code != 0:
+        # Static failures: explicitly mark verification as skipped
+        crosshair_output = {"status": "skipped", "reason": "prior failures"}
+        property_output = {"status": "skipped", "reason": "prior failures"}
+
+    # DX-37: Merge coverage data from doctest + hypothesis
+    coverage_output: dict | None = None
+    if coverage and (doctest_coverage or property_coverage):
+        coverage_output = {
+            "enabled": True,
+            "phases_tracked": [],
+            "phases_excluded": ["crosshair"],  # CrossHair uses symbolic execution
+        }
+        if doctest_coverage and doctest_coverage.get("collected"):
+            coverage_output["phases_tracked"].append("doctest")
+        if property_coverage and property_coverage.get("collected"):
+            coverage_output["phases_tracked"].append("hypothesis")
+            if "overall_branch_coverage" in property_coverage:
+                coverage_output["overall_branch_coverage"] = property_coverage["overall_branch_coverage"]
+
+    # DX-26: Unified output (agent JSON or human Rich)
     if use_agent_output:
         output_agent(
-            report, doctest_passed, doctest_output, crosshair_output, level_name,
+            report, strict, doctest_passed, doctest_output, crosshair_output, level_name,
             property_output=property_output,
+            coverage_data=coverage_output,  # DX-37
         )
-    elif use_json_output:
-        output_json(report)
     else:
-        output_rich(report, config.strict_pure, changed, pedantic, explain)
+        output_rich(report, config.strict_pure, changed, pedantic, explain, static)
         output_verification_status(
             verification_level, static_exit_code, doctest_passed,
             doctest_output, crosshair_output, explain,
             property_output=property_output,
+            strict=strict,
         )
+        # DX-37: Show coverage info in human output
+        if coverage_output and coverage_output.get("phases_tracked"):
+            phases = coverage_output.get("phases_tracked", [])
+            overall = coverage_output.get("overall_branch_coverage", 0.0)
+            console.print(f"\n[bold]Coverage Analysis[/bold] ({' + '.join(phases)})")
+            console.print(f"  Overall branch coverage: {overall}%")
+            console.print("  [dim]Note: CrossHair uses symbolic execution; coverage not applicable.[/dim]")
 
     # Exit with combined status
     all_passed = doctest_passed and crosshair_passed and property_passed
@@ -209,13 +288,26 @@ def guard(
     raise typer.Exit(final_exit)
 
 
-def _determine_output_mode(json_output: bool, agent: bool) -> tuple[bool, bool]:
-    """Determine output mode based on flags and context."""
-    if json_output:
-        return False, True
-    if agent or _detect_agent_mode():
-        return True, False
-    return False, False
+# @shell_orchestration: Output mode decision helper for CLI
+def _determine_output_mode(human: bool, agent: bool = False, json_output: bool = False) -> bool:
+    """Determine if agent JSON output should be used (DX-26).
+
+    DX-26: TTY auto-detection with --human override.
+    - --human flag → human output (for testing/debugging)
+    - TTY (terminal) → human output
+    - Non-TTY (pipe/redirect) → agent JSON output
+    - Deprecated --agent/--json flags → still work for backward compat
+    """
+    # --human flag always forces human output
+    if human:
+        return False  # use_agent = False
+
+    # Deprecated flags (backward compat)
+    if json_output or agent:
+        return True  # use_agent = True
+
+    # TTY auto-detection
+    return _detect_agent_mode()  # Returns True if non-TTY
 
 
 def _show_verification_level(verification_level) -> None:
@@ -245,7 +337,7 @@ def map_command(
     json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
 ) -> None:
     """Generate symbol map with reference counts."""
-    from invar.shell.perception import run_map
+    from invar.shell.commands.perception import run_map
 
     # Phase 9 P11: Auto-detect agent mode
     use_json = json_output or _detect_agent_mode()
@@ -261,7 +353,7 @@ def sig_command(
     json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
 ) -> None:
     """Extract signatures from a file or symbol."""
-    from invar.shell.perception import run_sig
+    from invar.shell.commands.perception import run_sig
 
     # Phase 9 P11: Auto-detect agent mode
     use_json = json_output or _detect_agent_mode()
@@ -271,6 +363,7 @@ def sig_command(
         raise typer.Exit(1)
 
 
+# @invar:allow entry_point_too_thick: Rules display with filtering and dual output modes
 @app.command()
 def rules(
     json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
@@ -343,15 +436,30 @@ def rules(
         console.print(f"\n[dim]{len(rules_list)} rules total. Use --json for full details.[/dim]")
 
 
-# Import commands from separate modules to reduce file size
-from invar.shell.init_cmd import init
-from invar.shell.test_cmd import test, verify
-from invar.shell.update_cmd import update
+# DX-48b: Import commands from shell/commands/
+from invar.shell.commands.init import init
+from invar.shell.commands.mutate import mutate  # DX-28
+from invar.shell.commands.sync_self import sync_self  # DX-49
+from invar.shell.commands.test import test, verify
+from invar.shell.commands.update import update
 
 app.command()(init)
 app.command()(update)
 app.command()(test)
 app.command()(verify)
+app.command()(mutate)  # DX-28: Mutation testing
+
+# DX-56: Create dev subcommand group for developer commands
+dev_app = typer.Typer(
+    name="dev",
+    help="Developer commands for Invar project development",
+    add_completion=False,
+)
+dev_app.command("sync")(sync_self)  # DX-56: renamed from sync-self
+app.add_typer(dev_app)
+
+# DX-56: Keep sync-self as alias for backward compatibility (deprecated)
+app.command("sync-self", hidden=True)(sync_self)
 
 
 if __name__ == "__main__":

invar/shell/{init_cmd.py → commands/init.py}

@@ -3,6 +3,8 @@ Init command for Invar.
 
 Shell module: handles project initialization.
 DX-21B: Added --claude flag for Claude Code integration.
+DX-55: Unified idempotent init command with smart merge.
+DX-56: Uses unified template sync engine for file generation.
 """
 
 from __future__ import annotations
@@ -15,17 +17,23 @@ import typer
 from returns.result import Failure, Success
 from rich.console import Console
 
+from invar.core.sync_helpers import SyncConfig
+from invar.core.template_parser import ClaudeMdState
+from invar.shell.commands.merge import (
+    ProjectState,
+    detect_project_state,
+)
+from invar.shell.commands.template_sync import sync_templates
 from invar.shell.mcp_config import (
     detect_available_methods,
     generate_mcp_json,
     get_method_by_name,
     get_recommended_method,
 )
+from invar.shell.template_engine import generate_from_manifest
 from invar.shell.templates import (
     add_config,
     add_invar_reference,
-    copy_examples_directory,
-    copy_template,
     create_agent_config,
     create_directories,
     detect_agent_configs,
@@ -35,6 +43,7 @@ from invar.shell.templates import (
 console = Console()
 
 
+# @shell_complexity: Claude init with config file detection
 def run_claude_init(path: Path) -> bool:
     """
     Run 'claude /init' to generate intelligent CLAUDE.md.
@@ -95,16 +104,27 @@ def append_invar_reference_to_claude_md(path: Path) -> bool:
 
 ## Invar Protocol
 
-> **Protocol:** Follow [INVAR.md](./INVAR.md) for the Invar development methodology.
+> **Protocol:** Follow [INVAR.md](./INVAR.md) — includes Check-In, USBV workflow, and Task Completion.
+
+### Check-In
+
+Your first message MUST display:
+
+```
+✓ Check-In: [project] | [branch] | [clean/dirty]
+```
+
+Read `.invar/context.md` first. Do NOT run guard/map at Check-In.
 
-Your **first message** for any implementation task MUST include actual output from:
+### Final
 
-```bash
-invar guard --changed   # or: invar_guard(changed=true)
-invar map --top 10      # or: invar_map(top=10)
+Your last message MUST display:
+
+```
+✓ Final: guard PASS | 0 errors, 2 warnings
 ```
 
-**Use MCP tools if available**, otherwise use CLI commands.
+Execute `invar guard` and show this one-line summary.
 """
 
     claude_md.write_text(content + invar_reference)
@@ -112,6 +132,7 @@ invar map --top 10      # or: invar_map(top=10)
     return True
 
 
+# @shell_complexity: MCP config with method selection and validation
 def configure_mcp_with_method(
     path: Path, mcp_method: str | None
 ) -> None:
@@ -163,6 +184,7 @@ def show_available_mcp_methods() -> None:
         console.print(f"  {marker} {method.method.value}: {method.description}")
 
 
+# @shell_complexity: Project init with config detection and template setup
 def init(
     path: Path = typer.Argument(Path(), help="Project root directory"),
     claude: bool = typer.Option(
@@ -179,24 +201,107 @@ def init(
     hooks: bool = typer.Option(
         True, "--hooks/--no-hooks", help="Install pre-commit hooks (default: ON)"
     ),
+    skills: bool = typer.Option(
+        True, "--skills/--no-skills", help="Create .claude/skills/ (default: ON, use --no-skills for Cursor)"
+    ),
     yes: bool = typer.Option(
         False, "--yes", "-y", help="Accept defaults without prompting"
     ),
+    check: bool = typer.Option(
+        False, "--check", help="Preview changes without applying (DX-55)"
+    ),
+    force: bool = typer.Option(
+        False, "--force", help="Update even if already current (DX-55)"
+    ),
+    reset: bool = typer.Option(
+        False, "--reset", help="Dangerous: discard all user content (DX-55)"
+    ),
 ) -> None:
     """
-    Initialize Invar configuration in a project.
+    Initialize or update Invar configuration (idempotent).
+
+    DX-55: This command is idempotent - safe to run multiple times.
+    It detects current state and does the right thing:
+
+    \b
+    - New project: Full setup
+    - Existing project: Update managed regions, preserve user content
+    - Corrupted/overwritten: Smart recovery with content preservation
 
     Works with or without pyproject.toml:
-    - If pyproject.toml exists: adds [tool.invar.guard] section
+
+    \b
+    - If pyproject.toml exists: adds tool.invar section
     - Otherwise: creates invar.toml
 
-    Use --claude to run 'claude /init' first (recommended for Claude Code users).
+    Use --check to preview changes without applying.
+    Use --force to update even if already current.
+    Use --reset to discard all user content (dangerous).
+    Use --claude to run 'claude /init' first.
     Use --mcp-method to specify MCP execution method (uvx, command, python).
     Use --dirs to always create directories, --no-dirs to skip.
     Use --no-hooks to skip pre-commit hooks installation.
+    Use --no-skills to skip .claude/skills/ creation (for Cursor users).
     Use --yes to accept defaults without prompting.
     """
-    # DX-21B: Run claude /init if requested
+    from invar import __version__
+
+    # DX-55: Detect project state first
+    state = detect_project_state(path)
+
+    # --check mode: preview only
+    if check:
+        _show_check_preview(state, path, __version__)
+        return
+
+    # --reset mode: dangerous full reset
+    if reset:
+        if not yes and not typer.confirm(
+            "[red]This will DELETE all user customizations. Continue?[/red]",
+            default=False,
+        ):
+            console.print("[yellow]Cancelled[/yellow]")
+            return
+        # Fall through to full init with reset flag
+        state = ProjectState(
+            initialized=False,
+            claude_md_state=ClaudeMdState(state="absent"),
+            version="",
+            needs_update=True,
+        )
+
+    # DX-55: Handle based on detected state
+    action = state.action if not force else "update"
+
+    if action == "none" and not force:
+        # DX-55: Check for missing required files before declaring "no changes needed"
+        missing_files = []
+        if skills:
+            skill_files = [
+                ".claude/skills/develop/SKILL.md",
+                ".claude/skills/investigate/SKILL.md",
+                ".claude/skills/propose/SKILL.md",
+                ".claude/skills/review/SKILL.md",
+            ]
+            for skill_file in skill_files:
+                if not (path / skill_file).exists():
+                    missing_files.append(skill_file)
+
+        if not missing_files:
+            console.print(f"[green]✓[/green] Invar v{__version__} configured (no changes needed)")
+            console.print("[dim]Use --force to refresh managed regions[/dim]")
+            return
+        else:
+            # Recreate missing files
+            console.print(f"[yellow]Detected:[/yellow] {len(missing_files)} missing file(s)")
+            result = generate_from_manifest(path, syntax="cli", files_to_generate=missing_files)
+            if isinstance(result, Success):
+                for generated_file in result.unwrap():
+                    console.print(f"[green]Restored[/green] {generated_file}")
+            console.print(f"[green]✓[/green] Invar v{__version__} configured")
+            return
+
+    # DX-21B: Run claude /init if requested (before sync)
     if claude:
         claude_success = run_claude_init(path)
         if claude_success:
@@ -209,26 +314,49 @@ def init(
         raise typer.Exit(1)
     config_added = config_result.unwrap()
 
-    # Create INVAR.md (protocol)
-    result = copy_template("INVAR.md", path)
-    if isinstance(result, Success) and result.unwrap():
-        console.print("[green]Created[/green] INVAR.md (Invar Protocol)")
-
-    # Copy examples directory
-    copy_examples_directory(path, console)
-
-    # Create .invar directory structure
+    # DX-56: Use unified sync engine for file generation
+    console.print("\n[bold]Creating Invar files...[/bold]")
+
+    # Check for project-additions.md
+    has_project_additions = (path / ".invar" / "project-additions.md").exists()
+
+    # Build skip patterns for --no-skills
+    skip_patterns: list[str] = []
+    if not skills:
+        skip_patterns.append(".claude/skills/*")
+
+    sync_config = SyncConfig(
+        syntax="cli",
+        inject_project_additions=has_project_additions,
+        force=force,
+        check=False,  # Already handled above
+        reset=reset,
+        skip_patterns=skip_patterns,
+    )
+
+    # DX-56: Run unified sync engine (handles DX-55 state detection internally)
+    result = sync_templates(path, sync_config)
+    if isinstance(result, Failure):
+        console.print(f"[yellow]Warning:[/yellow] {result.failure()}")
+    else:
+        report = result.unwrap()
+        for file in report.created:
+            console.print(f"[green]Created[/green] {file}")
+        for file in report.updated:
+            console.print(f"[cyan]Updated[/cyan] {file}")
+        for error in report.errors:
+            console.print(f"[yellow]Warning:[/yellow] {error}")
+
+    # Create .invar directory structure (for proposals template - not in manifest)
     invar_dir = path / ".invar"
     if not invar_dir.exists():
         invar_dir.mkdir()
-        result = copy_template("context.md.template", invar_dir, "context.md")
-        if isinstance(result, Success) and result.unwrap():
-            console.print("[green]Created[/green] .invar/context.md (context management)")
 
     # Create proposals directory for protocol governance
     proposals_dir = invar_dir / "proposals"
     if not proposals_dir.exists():
         proposals_dir.mkdir()
+        from invar.shell.templates import copy_template
         result = copy_template("proposal.md.template", proposals_dir, "TEMPLATE.md")
         if isinstance(result, Success) and result.unwrap():
             console.print("[green]Created[/green] .invar/proposals/TEMPLATE.md")
@@ -281,9 +409,53 @@ def init(
     if not config_added and not (path / "INVAR.md").exists():
         console.print("[yellow]Invar already configured.[/yellow]")
 
-    # Summary
-    console.print("\n[bold green]Invar initialized successfully![/bold green]")
+    # DX-55: Summary based on action taken
+    if action == "full_init":
+        console.print(f"\n[bold green]✓ Initialized Invar v{__version__}[/bold green]")
+        console.print("[dim]Note: If you run 'claude /init' later, just run 'invar init' again.[/dim]")
+    elif action == "recover":
+        console.print(f"\n[bold green]✓ Recovered Invar v{__version__}[/bold green]")
+        console.print("[dim]Review the merged content in CLAUDE.md[/dim]")
+    elif action == "update" or force:
+        console.print(f"\n[bold green]✓ Updated Invar v{__version__}[/bold green]")
+        console.print("[dim]Refreshed managed regions, preserved user content[/dim]")
+    else:
+        console.print("\n[bold green]Invar initialized successfully![/bold green]")
+
     if claude:
         console.print("[dim]Next: Review CLAUDE.md and start coding with Claude Code[/dim]")
-    else:
-        console.print("[dim]Tip: Use --claude for Claude Code integration[/dim]")
+
+
+# @shell_complexity: Preview display requires multiple state-specific branches
+def _show_check_preview(state: ProjectState, path: Path, version: str) -> None:
+    """Show preview of what would change (--check mode)."""
+    console.print(f"\n[bold]Invar v{version} - Preview Mode[/bold]\n")
+
+    console.print(f"Project state: [cyan]{state.claude_md_state.state}[/cyan]")
+    console.print(f"Initialized: [cyan]{state.initialized}[/cyan]")
+    console.print(f"Current version: [cyan]{state.version or 'N/A'}[/cyan]")
+    console.print(f"Needs update: [cyan]{state.needs_update}[/cyan]")
+    console.print(f"Action: [cyan]{state.action}[/cyan]\n")
+
+    match state.action:
+        case "none":
+            console.print("[green]No changes needed[/green]")
+        case "full_init":
+            console.print("Would create:")
+            console.print("  - INVAR.md")
+            console.print("  - CLAUDE.md")
+            console.print("  - .invar/context.md")
+            console.print("  - .claude/skills/")
+            console.print("  - .pre-commit-config.yaml")
+        case "update":
+            console.print("Would update:")
+            console.print(f"  - CLAUDE.md (managed section v{state.version} → v{version})")
+            console.print("  - .claude/skills/* (refresh)")
+        case "recover":
+            console.print("[yellow]Would recover:[/yellow]")
+            console.print("  - CLAUDE.md (restore regions, preserve content)")
+        case "create":
+            console.print("Would create:")
+            console.print("  - CLAUDE.md")
+
+    console.print("\n[dim]Run 'invar init' to apply.[/dim]")