crucible-mcp 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

crucible/cli.py

@@ -1,10 +1,14 @@
 """crucible CLI."""
 
+from __future__ import annotations
+
 import argparse
 import shutil
 import sys
 from pathlib import Path
 
+from crucible.enforcement.models import ComplianceConfig
+
 # Skills directories
 SKILLS_BUNDLED = Path(__file__).parent / "skills"
 SKILLS_USER = Path.home() / ".claude" / "crucible" / "skills"
@@ -408,6 +412,12 @@ def _load_review_config(repo_path: str | None = None) -> dict:
           backend: high
         include_context: false
         skip_tools: []
+        enforcement:
+          compliance:
+            enabled: true
+            model: sonnet
+            token_budget: 10000
+            overflow_behavior: warn
     """
     import yaml
 
@@ -423,31 +433,236 @@ def _load_review_config(repo_path: str | None = None) -> dict:
         try:
             with open(config_project) as f:
                 config_data = yaml.safe_load(f) or {}
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"Warning: Could not load {config_project}: {e}", file=sys.stderr)
 
     # Fall back to user-level
     if not config_data and config_user.exists():
         try:
             with open(config_user) as f:
                 config_data = yaml.safe_load(f) or {}
-        except Exception:
-            pass
+        except Exception as e:
+            print(f"Warning: Could not load {config_user}: {e}", file=sys.stderr)
 
     return config_data
 
 
+def _build_compliance_config(
+    config: dict,
+    cli_token_budget: int | None = None,
+    cli_model: str | None = None,
+    cli_no_compliance: bool = False,
+) -> ComplianceConfig:
+    """Build compliance config from config file and CLI overrides.
+
+    Args:
+        config: Loaded config dict
+        cli_token_budget: CLI --token-budget override
+        cli_model: CLI --compliance-model override
+        cli_no_compliance: CLI --no-compliance flag
+
+    Returns:
+        ComplianceConfig instance
+    """
+    from crucible.enforcement.models import ComplianceConfig, OverflowBehavior
+
+    # Get enforcement.compliance section from config
+    enforcement_config = config.get("enforcement", {})
+    compliance_section = enforcement_config.get("compliance", {})
+
+    # Build config with defaults
+    enabled = not cli_no_compliance and compliance_section.get("enabled", True)
+    model = cli_model or compliance_section.get("model", "sonnet")
+    token_budget = cli_token_budget if cli_token_budget is not None else compliance_section.get("token_budget", 10000)
+
+    # Parse overflow behavior
+    overflow_str = compliance_section.get("overflow_behavior", "warn")
+    try:
+        overflow_behavior = OverflowBehavior(overflow_str.lower())
+    except ValueError:
+        overflow_behavior = OverflowBehavior.WARN
+
+    # Parse priority order
+    priority_order = compliance_section.get("priority_order", ["critical", "high", "medium", "low"])
+    if isinstance(priority_order, list):
+        priority_order = tuple(priority_order)
+    else:
+        priority_order = ("critical", "high", "medium", "low")
+
+    return ComplianceConfig(
+        enabled=enabled,
+        model=model,
+        token_budget=token_budget,
+        priority_order=priority_order,
+        overflow_behavior=overflow_behavior,
+    )
+
+
+def _cmd_review_no_git(args: argparse.Namespace, path: str) -> int:
+    """Run static analysis on a path without git awareness."""
+    import json as json_mod
+    from pathlib import Path
+
+    from crucible.models import Domain, Severity, ToolFinding
+    from crucible.review.core import (
+        compute_severity_counts,
+        deduplicate_findings,
+        detect_domain_for_file,
+        get_tools_for_domain,
+        run_static_analysis,
+    )
+
+    path_obj = Path(path)
+    if not path_obj.exists():
+        print(f"Error: {path} does not exist")
+        return 1
+
+    # Load config from current directory or user level
+    config = _load_review_config(".")
+
+    # Parse severity threshold
+    severity_order = ["critical", "high", "medium", "low", "info"]
+    severity_map = {
+        "critical": Severity.CRITICAL,
+        "high": Severity.HIGH,
+        "medium": Severity.MEDIUM,
+        "low": Severity.LOW,
+        "info": Severity.INFO,
+    }
+    default_threshold_str = args.fail_on or config.get("fail_on")
+    default_threshold: Severity | None = None
+    if default_threshold_str:
+        default_threshold = severity_map.get(default_threshold_str.lower())
+
+    skip_tools = set(config.get("skip_tools", []))
+
+    # Collect files to analyze
+    files_to_analyze: list[str] = []
+    if path_obj.is_file():
+        files_to_analyze = [str(path_obj)]
+    else:
+        # Recursively find files, respecting common ignores
+        ignore_dirs = {".git", "__pycache__", "node_modules", ".venv", "venv", "build", "dist"}
+        for file_path in path_obj.rglob("*"):
+            if file_path.is_file():
+                # Skip ignored directories
+                if any(ignored in file_path.parts for ignored in ignore_dirs):
+                    continue
+                files_to_analyze.append(str(file_path))
+
+    if not files_to_analyze:
+        print("No files to analyze.")
+        return 0
+
+    if not args.quiet and not args.json:
+        print(f"Reviewing {len(files_to_analyze)} file(s) (no git)...")
+
+    # Run analysis
+    all_findings: list[ToolFinding] = []
+    tool_errors: list[str] = []
+    domains_detected: set[Domain] = set()
+    all_domain_tags: set[str] = set()
+
+    for file_path in files_to_analyze:
+        domain, domain_tags = detect_domain_for_file(file_path)
+        domains_detected.add(domain)
+        all_domain_tags.update(domain_tags)
+
+        tools = get_tools_for_domain(domain, domain_tags)
+        tools = [t for t in tools if t not in skip_tools]
+
+        findings, errors = run_static_analysis(file_path, domain, domain_tags, tools)
+        all_findings.extend(findings)
+        tool_errors.extend(errors)
+
+    # Deduplicate
+    all_findings = deduplicate_findings(all_findings)
+
+    # Compute severity summary
+    severity_counts = compute_severity_counts(all_findings)
+
+    # Determine pass/fail
+    passed = True
+    if default_threshold:
+        threshold_idx = severity_order.index(default_threshold.value)
+        for sev in severity_order[: threshold_idx + 1]:
+            if severity_counts.get(sev, 0) > 0:
+                passed = False
+                break
+
+    # Output
+    if args.json:
+        output = {
+            "mode": "no-git",
+            "files_analyzed": len(files_to_analyze),
+            "domains_detected": [d.value for d in domains_detected],
+            "findings": [
+                {
+                    "tool": f.tool,
+                    "rule": f.rule,
+                    "severity": f.severity.value,
+                    "message": f.message,
+                    "location": f.location,
+                    "suggestion": f.suggestion,
+                }
+                for f in all_findings
+            ],
+            "severity_counts": severity_counts,
+            "passed": passed,
+            "threshold": default_threshold.value if default_threshold else None,
+            "errors": tool_errors,
+        }
+        print(json_mod.dumps(output, indent=2))
+    else:
+        # Text output
+        if all_findings:
+            print(f"\nFound {len(all_findings)} issue(s):\n")
+            for f in all_findings:
+                sev_icon = {"critical": "🔴", "high": "🟠", "medium": "🟡", "low": "🔵", "info": "⚪"}.get(
+                    f.severity.value, "⚪"
+                )
+                print(f"{sev_icon} [{f.severity.value.upper()}] {f.location}")
+                print(f"   {f.tool}/{f.rule}: {f.message}")
+                if f.suggestion:
+                    print(f"   💡 {f.suggestion}")
+                print()
+        else:
+            print("\n✅ No issues found.")
+
+        # Summary
+        if severity_counts:
+            counts_str = ", ".join(f"{k}: {v}" for k, v in severity_counts.items() if v > 0)
+            print(f"Summary: {counts_str}")
+
+        if tool_errors and not args.quiet:
+            print(f"\n⚠️  {len(tool_errors)} tool error(s)")
+            for err in tool_errors[:5]:
+                print(f"   - {err}")
+
+    return 0 if passed else 1
+
+
 def cmd_review(args: argparse.Namespace) -> int:
-    """Run code review on git changes."""
+    """Run code review on git changes or a path directly."""
     import json as json_mod
 
     from crucible.models import Domain, Severity, ToolFinding
-    from crucible.tools.delegation import (
-        delegate_bandit,
-        delegate_ruff,
-        delegate_semgrep,
-        delegate_slither,
+    from crucible.review.core import (
+        compute_severity_counts,
+        deduplicate_findings,
+        detect_domain_for_file,
+        filter_findings_to_changes,
+        get_tools_for_domain,
+        run_static_analysis,
     )
+
+    path = args.path or "."
+
+    # Handle --no-git mode: simple static analysis without git awareness
+    if getattr(args, "no_git", False):
+        return _cmd_review_no_git(args, path)
+
+    # Git-aware review mode
     from crucible.tools.git import (
         get_branch_diff,
         get_recent_commits,
@@ -457,98 +672,12 @@ def cmd_review(args: argparse.Namespace) -> int:
         is_git_repo,
     )
 
-    # Helper functions (inline to avoid circular imports)
-    def get_semgrep_config(domain: Domain) -> str:
-        if domain == Domain.SMART_CONTRACT:
-            return "p/smart-contracts"
-        elif domain == Domain.BACKEND:
-            return "p/python"
-        elif domain == Domain.FRONTEND:
-            return "p/typescript"
-        return "auto"
-
-    def detect_domain(filename: str) -> tuple[Domain, list[str]]:
-        """Detect domain from file extension."""
-        ext = Path(filename).suffix.lower()
-        if ext == ".sol":
-            return Domain.SMART_CONTRACT, ["solidity", "smart_contract", "web3"]
-        elif ext in (".py", ".pyw"):
-            return Domain.BACKEND, ["python", "backend"]
-        elif ext in (".ts", ".tsx", ".js", ".jsx"):
-            return Domain.FRONTEND, ["typescript", "frontend", "javascript"]
-        elif ext == ".rs":
-            return Domain.BACKEND, ["rust", "backend"]
-        elif ext == ".go":
-            return Domain.BACKEND, ["go", "backend"]
-        return Domain.UNKNOWN, []
-
-    def get_changed_files(changes: list) -> list[str]:
-        """Get list of changed files (excluding deleted)."""
-        return [c.path for c in changes if c.status != "D"]
-
-    def parse_location_line(location: str) -> int | None:
-        """Extract line number from location string like 'file.py:10'."""
-        if ":" in location:
-            try:
-                return int(location.split(":")[1].split(":")[0])
-            except (ValueError, IndexError):
-                return None
-        return None
-
-    def filter_findings_to_changes(
-        findings: list[ToolFinding],
-        changes: list,
-        include_context: bool = False,
-    ) -> list[ToolFinding]:
-        """Filter findings to only those in changed lines."""
-        # Build a lookup of file -> changed line ranges
-        changed_ranges: dict[str, list[tuple[int, int]]] = {}
-        for change in changes:
-            if change.status == "D":
-                continue  # Skip deleted files
-            ranges = [(r.start, r.end) for r in change.added_lines]
-            changed_ranges[change.path] = ranges
-
-        context_lines = 5 if include_context else 0
-        filtered: list[ToolFinding] = []
-
-        for finding in findings:
-            # Parse location: "path:line" or "path:line:col"
-            parts = finding.location.split(":")
-            if len(parts) < 2:
-                continue
-
-            file_path = parts[0]
-            try:
-                line_num = int(parts[1])
-            except ValueError:
-                continue
-
-            # Check if file is in changes
-            # Handle both absolute and relative paths
-            matching_file = None
-            for changed_file in changed_ranges:
-                if file_path.endswith(changed_file) or changed_file.endswith(file_path):
-                    matching_file = changed_file
-                    break
-
-            if not matching_file:
-                continue
-
-            # Check if line is in changed ranges (with context)
-            for start, end in changed_ranges[matching_file]:
-                if start - context_lines <= line_num <= end + context_lines:
-                    filtered.append(finding)
-                    break
-
-        return filtered
-
-    path = args.path or "."
     mode = args.mode
 
     # Validate git repo
     if not is_git_repo(path):
-        print(f"Error: {path} is not a git repository")
+        print(f"Error: {path} is not inside a git repository")
+        print("Hint: Use --no-git to review files without git awareness")
         return 1
 
     root_result = get_repo_root(path)
@@ -638,7 +767,7 @@ def cmd_review(args: argparse.Namespace) -> int:
             print("No changes found.")
         return 0
 
-    changed_files = get_changed_files(context.changes)
+    changed_files = [c.path for c in context.changes if c.status != "D"]
     if not changed_files:
         print("No files to analyze (only deletions).")
         return 0
@@ -656,77 +785,24 @@ def cmd_review(args: argparse.Namespace) -> int:
 
     for file_path in changed_files:
         full_path = f"{repo_path}/{file_path}"
-        domain, domain_tags = detect_domain(file_path)
+        domain, domain_tags = detect_domain_for_file(file_path)
         domains_detected.add(domain)
         all_domain_tags.update(domain_tags)
 
-        # Select tools based on domain
-        if domain == Domain.SMART_CONTRACT:
-            tools = ["slither", "semgrep"]
-        elif domain == Domain.BACKEND and "python" in domain_tags:
-            tools = ["ruff", "bandit", "semgrep"]
-        elif domain == Domain.FRONTEND:
-            tools = ["semgrep"]
-        else:
-            tools = ["semgrep"]
-
-        # Apply skip_tools from config
+        # Get tools for this domain, applying skip_tools from config
+        tools = get_tools_for_domain(domain, domain_tags)
         tools = [t for t in tools if t not in skip_tools]
 
-        # Run tools
-        if "semgrep" in tools:
-            semgrep_config = get_semgrep_config(domain)
-            result = delegate_semgrep(full_path, semgrep_config)
-            if result.is_ok:
-                all_findings.extend(result.value)
-            elif result.is_err:
-                tool_errors.append(f"semgrep ({file_path}): {result.error}")
-
-        if "ruff" in tools:
-            result = delegate_ruff(full_path)
-            if result.is_ok:
-                all_findings.extend(result.value)
-            elif result.is_err:
-                tool_errors.append(f"ruff ({file_path}): {result.error}")
-
-        if "slither" in tools:
-            result = delegate_slither(full_path)
-            if result.is_ok:
-                all_findings.extend(result.value)
-            elif result.is_err:
-                tool_errors.append(f"slither ({file_path}): {result.error}")
-
-        if "bandit" in tools:
-            result = delegate_bandit(full_path)
-            if result.is_ok:
-                all_findings.extend(result.value)
-            elif result.is_err:
-                tool_errors.append(f"bandit ({file_path}): {result.error}")
-
-    # Filter findings to changed lines
+        # Run static analysis
+        findings, errors = run_static_analysis(full_path, domain, domain_tags, tools)
+        all_findings.extend(findings)
+        for err in errors:
+            tool_errors.append(f"{err} ({file_path})")
+
+    # Filter findings to changed lines and deduplicate
     filtered_findings = filter_findings_to_changes(
-        all_findings, context.changes, args.include_context
+        all_findings, context, args.include_context
     )
-
-    # Deduplicate findings
-    def deduplicate_findings(findings: list[ToolFinding]) -> list[ToolFinding]:
-        """Deduplicate findings by location and message."""
-        seen: dict[tuple[str, str], ToolFinding] = {}
-        severity_order = [Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM, Severity.LOW, Severity.INFO]
-
-        for f in findings:
-            norm_msg = f.message.lower().strip()
-            key = (f.location, norm_msg)
-
-            if key not in seen:
-                seen[key] = f
-            else:
-                existing = seen[key]
-                if severity_order.index(f.severity) < severity_order.index(existing.severity):
-                    seen[key] = f
-
-        return list(seen.values())
-
     filtered_findings = deduplicate_findings(filtered_findings)
 
     # Match skills and load knowledge based on detected domains
@@ -760,11 +836,30 @@ def cmd_review(args: argparse.Namespace) -> int:
         if result.is_ok:
             knowledge_content[filename] = result.value
 
+    # Run enforcement assertions (pattern + LLM)
+    from crucible.review.core import run_enforcement
+
+    compliance_config = _build_compliance_config(
+        config,
+        cli_token_budget=getattr(args, "token_budget", None),
+        cli_model=getattr(args, "compliance_model", None),
+        cli_no_compliance=getattr(args, "no_compliance", False),
+    )
+
+    enforcement_findings, enforcement_errors, assertions_checked, assertions_skipped, budget_state = (
+        run_enforcement(
+            repo_path,
+            changed_files=changed_files,
+            repo_root=repo_path,
+            compliance_config=compliance_config,
+        )
+    )
+
+    # Add enforcement errors to tool errors
+    tool_errors.extend(enforcement_errors)
+
     # Compute severity summary
-    severity_counts: dict[str, int] = {}
-    for f in filtered_findings:
-        sev = f.severity.value
-        severity_counts[sev] = severity_counts.get(sev, 0) + 1
+    severity_counts = compute_severity_counts(filtered_findings)
 
     # Determine pass/fail using per-domain thresholds
     # Use the strictest applicable threshold
@@ -813,6 +908,22 @@ def cmd_review(args: argparse.Namespace) -> int:
                 }
                 for f in filtered_findings
             ],
+            "enforcement": {
+                "findings": [
+                    {
+                        "assertion_id": f.assertion_id,
+                        "severity": f.severity,
+                        "message": f.message,
+                        "location": f.location,
+                        "source": f.source,
+                        "suppressed": f.suppressed,
+                    }
+                    for f in enforcement_findings
+                ],
+                "assertions_checked": assertions_checked,
+                "assertions_skipped": assertions_skipped,
+                "llm_tokens_used": budget_state.tokens_used if budget_state else 0,
+            },
             "severity_counts": severity_counts,
             "threshold": threshold_used,
             "errors": tool_errors,
@@ -955,6 +1066,28 @@ def cmd_review(args: argparse.Namespace) -> int:
         else:
             print("\nNo issues found in changed code.")
 
+        # Enforcement assertions
+        if enforcement_findings:
+            active_enforcement = [f for f in enforcement_findings if not f.suppressed]
+            suppressed_enforcement = [f for f in enforcement_findings if f.suppressed]
+
+            if active_enforcement:
+                print(f"\nEnforcement Assertions ({len(active_enforcement)}):")
+                for f in active_enforcement:
+                    sev_upper = f.severity.upper()
+                    source_label = "[LLM]" if f.source == "llm" else "[PATTERN]"
+                    print(f"  [{sev_upper}] {source_label} {f.assertion_id}: {f.location}")
+                    print(f"    {f.message}")
+                    print()
+
+            if suppressed_enforcement:
+                print(f"  Suppressed: {len(suppressed_enforcement)}")
+
+        if assertions_checked > 0:
+            print(f"\nAssertions: {assertions_checked} checked, {assertions_skipped} skipped")
+            if budget_state and budget_state.tokens_used > 0:
+                print(f"  LLM tokens used: {budget_state.tokens_used}")
+
         if effective_threshold:
             status = "PASSED" if passed else "FAILED"
             print(f"\n{'='*60}")
@@ -964,6 +1097,281 @@ def cmd_review(args: argparse.Namespace) -> int:
     return 0 if passed else 1
 
 
+# --- Assertions commands ---
+
+# Assertions directories
+ASSERTIONS_BUNDLED = Path(__file__).parent / "enforcement" / "bundled"
+ASSERTIONS_USER = Path.home() / ".claude" / "crucible" / "assertions"
+ASSERTIONS_PROJECT = Path(".crucible") / "assertions"
+
+
+def cmd_assertions_validate(args: argparse.Namespace) -> int:
+    """Validate assertion files."""
+    from crucible.enforcement.assertions import (
+        clear_assertion_cache,
+        get_all_assertion_files,
+        load_assertion_file,
+    )
+
+    clear_assertion_cache()
+
+    files = get_all_assertion_files()
+    if not files:
+        print("No assertion files found.")
+        print("\nCreate assertion files in:")
+        print(f"  Project: {ASSERTIONS_PROJECT}/")
+        print(f"  User:    {ASSERTIONS_USER}/")
+        return 0
+
+    valid_count = 0
+    error_count = 0
+
+    for filename in sorted(files):
+        result = load_assertion_file(filename)
+        if result.is_ok:
+            assertion_count = len(result.value.assertions)
+            print(f"  ✓ {filename}: {assertion_count} assertion(s) valid")
+            valid_count += 1
+        else:
+            print(f"  ✗ {filename}: {result.error}")
+            error_count += 1
+
+    print()
+    if error_count == 0:
+        print(f"All {valid_count} file(s) valid.")
+        return 0
+    else:
+        print(f"{error_count} file(s) with errors, {valid_count} valid.")
+        return 1
+
+
+def cmd_assertions_list(args: argparse.Namespace) -> int:
+    """List available assertion files."""
+    print("Bundled assertions:")
+    if ASSERTIONS_BUNDLED.exists():
+        found = False
+        for file_path in sorted(ASSERTIONS_BUNDLED.iterdir()):
+            if file_path.is_file() and file_path.suffix in (".yaml", ".yml"):
+                print(f"  - {file_path.name}")
+                found = True
+        if not found:
+            print("  (none)")
+    else:
+        print("  (none)")
+
+    print("\nUser assertions (~/.claude/crucible/assertions/):")
+    if ASSERTIONS_USER.exists():
+        found = False
+        for file_path in sorted(ASSERTIONS_USER.iterdir()):
+            if file_path.is_file() and file_path.suffix in (".yaml", ".yml"):
+                print(f"  - {file_path.name}")
+                found = True
+        if not found:
+            print("  (none)")
+    else:
+        print("  (none)")
+
+    print("\nProject assertions (.crucible/assertions/):")
+    if ASSERTIONS_PROJECT.exists():
+        found = False
+        for file_path in sorted(ASSERTIONS_PROJECT.iterdir()):
+            if file_path.is_file() and file_path.suffix in (".yaml", ".yml"):
+                print(f"  - {file_path.name}")
+                found = True
+        if not found:
+            print("  (none)")
+    else:
+        print("  (none)")
+
+    return 0
+
+
+def cmd_assertions_test(args: argparse.Namespace) -> int:
+    """Test assertions against a file or directory."""
+    import os
+
+    from crucible.enforcement.assertions import load_assertions
+    from crucible.enforcement.patterns import run_pattern_assertions
+
+    target_path = Path(args.file)
+    if not target_path.exists():
+        print(f"Error: Path '{target_path}' not found")
+        return 1
+
+    assertions, errors = load_assertions()
+
+    if errors:
+        print("Assertion loading errors:")
+        for error in errors:
+            print(f"  - {error}")
+        print()
+
+    if not assertions:
+        print("No assertions loaded.")
+        return 0
+
+    # Collect files to test
+    files_to_test: list[tuple[str, str]] = []  # (display_path, content)
+
+    if target_path.is_file():
+        try:
+            content = target_path.read_text()
+            files_to_test.append((str(target_path), content))
+        except UnicodeDecodeError:
+            print(f"Error: Cannot read '{target_path}' (binary file?)")
+            return 1
+    else:
+        # Directory mode
+        for root, _, files in os.walk(target_path):
+            for fname in files:
+                fpath = Path(root) / fname
+                rel_path = fpath.relative_to(target_path)
+                try:
+                    content = fpath.read_text()
+                    files_to_test.append((str(rel_path), content))
+                except (UnicodeDecodeError, OSError):
+                    pass  # Skip binary/unreadable files
+
+    # Run assertions on all files
+    all_findings = []
+    checked = 0
+    skipped = 0
+
+    for display_path, content in files_to_test:
+        findings, c, s = run_pattern_assertions(display_path, content, assertions)
+        all_findings.extend(findings)
+        checked = max(checked, c)
+        skipped = max(skipped, s)
+
+    # Separate suppressed and active findings
+    active = [f for f in all_findings if not f.suppressed]
+    suppressed = [f for f in all_findings if f.suppressed]
+
+    print(f"Testing {target_path}")
+    print(f"  Files scanned: {len(files_to_test)}")
+    print(f"  Assertions checked: {checked}")
+    print(f"  Assertions skipped (LLM): {skipped}")
+    print()
+
+    if active:
+        print(f"Findings ({len(active)}):")
+        for f in active:
+            sev = f.severity.upper()
+            print(f"  [{sev}] {f.assertion_id}: {f.location}")
+            print(f"    {f.message}")
+            if f.match_text:
+                print(f"    Matched: {f.match_text!r}")
+            print()
+
+    if suppressed:
+        print(f"Suppressed ({len(suppressed)}):")
+        for f in suppressed:
+            reason = f" -- {f.suppression_reason}" if f.suppression_reason else ""
+            print(f"  {f.assertion_id}: {f.location}{reason}")
+
+    if not active and not suppressed:
+        print("No matches found.")
+
+    return 0
+
+
+def cmd_assertions_explain(args: argparse.Namespace) -> int:
+    """Explain what a rule does."""
+    from crucible.enforcement.assertions import load_assertions
+
+    rule_id = args.rule.lower()
+    assertions, errors = load_assertions()
+
+    for assertion in assertions:
+        if assertion.id.lower() == rule_id:
+            print(f"Rule: {assertion.id}")
+            print(f"Type: {assertion.type.value}")
+            if assertion.pattern:
+                print(f"Pattern: {assertion.pattern}")
+            print(f"Message: {assertion.message}")
+            print(f"Severity: {assertion.severity}")
+            print(f"Priority: {assertion.priority.value}")
+            if assertion.languages:
+                print(f"Languages: {', '.join(assertion.languages)}")
+            if assertion.applicability:
+                if assertion.applicability.glob:
+                    print(f"Applies to: {assertion.applicability.glob}")
+                if assertion.applicability.exclude:
+                    print(f"Excludes: {', '.join(assertion.applicability.exclude)}")
+            if assertion.compliance:
+                print(f"Compliance: {assertion.compliance}")
+            return 0
+
+    print(f"Rule '{rule_id}' not found.")
+    print("\nAvailable rules:")
+    for a in assertions[:10]:
+        print(f"  - {a.id}")
+    if len(assertions) > 10:
+        print(f"  ... and {len(assertions) - 10} more")
+    return 1
+
+
+def cmd_assertions_debug(args: argparse.Namespace) -> int:
+    """Debug applicability for a rule and file."""
+    from crucible.enforcement.assertions import load_assertions
+    from crucible.enforcement.patterns import matches_glob, matches_language
+
+    rule_id = args.rule.lower()
+    file_path = args.file
+
+    assertions, errors = load_assertions()
+
+    for assertion in assertions:
+        if assertion.id.lower() == rule_id:
+            print(f"Applicability check for '{assertion.id}':")
+            print()
+
+            # Language check
+            if assertion.languages:
+                lang_match = matches_language(file_path, assertion.languages)
+                lang_status = "MATCH" if lang_match else "NO MATCH"
+                print(f"  Languages: {', '.join(assertion.languages)}")
+                print(f"    File: {file_path} → {lang_status}")
+            else:
+                print("  Languages: (any)")
+
+            # Glob check
+            if assertion.applicability:
+                if assertion.applicability.glob:
+                    glob_match = matches_glob(
+                        file_path,
+                        assertion.applicability.glob,
+                        assertion.applicability.exclude,
+                    )
+                    glob_status = "MATCH" if glob_match else "NO MATCH"
+                    print(f"  Glob: {assertion.applicability.glob}")
+                    if assertion.applicability.exclude:
+                        print(f"  Exclude: {', '.join(assertion.applicability.exclude)}")
+                    print(f"    File: {file_path} → {glob_status}")
+                else:
+                    print("  Glob: (any)")
+            else:
+                print("  Applicability: (none)")
+
+            # Overall result
+            print()
+            lang_ok = matches_language(file_path, assertion.languages)
+            glob_ok = True
+            if assertion.applicability and assertion.applicability.glob:
+                glob_ok = matches_glob(
+                    file_path,
+                    assertion.applicability.glob,
+                    assertion.applicability.exclude,
+                )
+            overall = lang_ok and glob_ok
+            result = "APPLICABLE" if overall else "NOT APPLICABLE"
+            print(f"  Result: {result}")
+            return 0
+
+    print(f"Rule '{rule_id}' not found.")
+    return 1
+
+
 # --- Hooks commands ---
 
 PRECOMMIT_HOOK_SCRIPT = """\
@@ -989,7 +1397,7 @@ def cmd_hooks_install(args: argparse.Namespace) -> int:
 
     path = args.path or "."
     if not is_git_repo(path):
-        print(f"Error: {path} is not a git repository")
+        print(f"Error: {path} is not inside a git repository")
         return 1
 
     root_result = get_repo_root(path)
@@ -1035,7 +1443,7 @@ def cmd_hooks_uninstall(args: argparse.Namespace) -> int:
 
     path = args.path or "."
     if not is_git_repo(path):
-        print(f"Error: {path} is not a git repository")
+        print(f"Error: {path} is not inside a git repository")
         return 1
 
     root_result = get_repo_root(path)
@@ -1068,7 +1476,7 @@ def cmd_hooks_status(args: argparse.Namespace) -> int:
 
     path = args.path or "."
     if not is_git_repo(path):
-        print(f"Error: {path} is not a git repository")
+        print(f"Error: {path} is not inside a git repository")
         return 1
 
     root_result = get_repo_root(path)
@@ -1333,6 +1741,104 @@ def cmd_ci_generate(args: argparse.Namespace) -> int:
     return 0
 
 
+# --- Config commands ---
+
+CONFIG_DIR = Path.home() / ".config" / "crucible"
+SECRETS_FILE = CONFIG_DIR / "secrets.yaml"
+
+
+def cmd_config_set_api_key(args: argparse.Namespace) -> int:
+    """Set Anthropic API key for LLM compliance assertions."""
+    import getpass
+
+    import yaml
+
+    print("Set Anthropic API key for LLM compliance assertions.")
+    print("This will be stored in ~/.config/crucible/secrets.yaml")
+    print()
+
+    # Prompt for key (hidden input)
+    api_key = getpass.getpass("Enter API key (input hidden): ")
+
+    if not api_key:
+        print("No key provided, aborting.")
+        return 1
+
+    if not api_key.startswith("sk-ant-"):
+        print("Warning: Key doesn't start with 'sk-ant-', are you sure this is correct?")
+        confirm = input("Continue? [y/N]: ")
+        if confirm.lower() != "y":
+            print("Aborted.")
+            return 1
+
+    # Create config directory
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Load existing config or create new
+    existing_config: dict = {}
+    if SECRETS_FILE.exists():
+        try:
+            with open(SECRETS_FILE) as f:
+                existing_config = yaml.safe_load(f) or {}
+        except Exception as e:
+            print(f"Warning: Could not read existing {SECRETS_FILE}: {e}", file=sys.stderr)
+
+    # Update config
+    existing_config["anthropic_api_key"] = api_key
+
+    # Write with restrictive permissions
+    SECRETS_FILE.write_text(yaml.dump(existing_config, default_flow_style=False))
+    SECRETS_FILE.chmod(0o600)
+
+    print(f"API key saved to {SECRETS_FILE}")
+    print("Permissions set to 600 (owner read/write only)")
+    return 0
+
+
+def cmd_config_show(args: argparse.Namespace) -> int:
+    """Show current configuration."""
+    import os
+
+    import yaml
+
+    print("Crucible Configuration")
+    print("=" * 40)
+
+    # Check env var
+    env_key = os.environ.get("ANTHROPIC_API_KEY")
+    if env_key:
+        print(f"ANTHROPIC_API_KEY (env): {env_key[:10]}...{env_key[-4:]}")
+    else:
+        print("ANTHROPIC_API_KEY (env): not set")
+
+    # Check config file
+    if SECRETS_FILE.exists():
+        try:
+            with open(SECRETS_FILE) as f:
+                data = yaml.safe_load(f) or {}
+            file_key = data.get("anthropic_api_key")
+            if file_key:
+                print(f"anthropic_api_key (file): {file_key[:10]}...{file_key[-4:]}")
+            else:
+                print("anthropic_api_key (file): not set")
+            print(f"Config file: {SECRETS_FILE}")
+        except Exception as e:
+            print(f"Config file error: {e}")
+    else:
+        print(f"Config file: {SECRETS_FILE} (not found)")
+
+    # Show which would be used
+    print()
+    if env_key:
+        print("Active: environment variable (takes precedence)")
+    elif SECRETS_FILE.exists():
+        print("Active: config file")
+    else:
+        print("Active: none (LLM assertions will fail)")
+
+    return 0
+
+
 # --- Main ---
 
 
@@ -1483,7 +1989,24 @@ def main() -> int:
         help="Suppress progress messages"
     )
     review_parser.add_argument(
-        "path", nargs="?", default=".", help="Repository path"
+        "--token-budget", type=int,
+        help="Token budget for LLM compliance assertions (0 = unlimited)"
+    )
+    review_parser.add_argument(
+        "--compliance-model",
+        choices=["sonnet", "opus", "haiku"],
+        help="Model for LLM compliance assertions (default: sonnet)"
+    )
+    review_parser.add_argument(
+        "--no-compliance", action="store_true",
+        help="Disable LLM compliance assertions"
+    )
+    review_parser.add_argument(
+        "--no-git", action="store_true",
+        help="Review path directly without git awareness (static analysis only)"
+    )
+    review_parser.add_argument(
+        "path", nargs="?", default=".", help="Path to review (file or directory)"
     )
 
     # === pre-commit command (direct invocation) ===
@@ -1526,6 +2049,38 @@ def main() -> int:
         help="Project path (default: current directory)"
     )
 
+    # === assertions command ===
+    assertions_parser = subparsers.add_parser("assertions", help="Manage pattern assertions")
+    assertions_sub = assertions_parser.add_subparsers(dest="assertions_command")
+
+    # assertions validate
+    assertions_sub.add_parser("validate", help="Validate assertion files")
+
+    # assertions list
+    assertions_sub.add_parser("list", help="List assertion files from all sources")
+
+    # assertions test
+    assertions_test_parser = assertions_sub.add_parser(
+        "test",
+        help="Test assertions against a file"
+    )
+    assertions_test_parser.add_argument("file", help="File to test")
+
+    # assertions explain
+    assertions_explain_parser = assertions_sub.add_parser(
+        "explain",
+        help="Explain what a rule does"
+    )
+    assertions_explain_parser.add_argument("rule", help="Rule ID to explain")
+
+    # assertions debug
+    assertions_debug_parser = assertions_sub.add_parser(
+        "debug",
+        help="Debug applicability for a rule and file"
+    )
+    assertions_debug_parser.add_argument("--rule", "-r", required=True, help="Rule ID")
+    assertions_debug_parser.add_argument("--file", "-f", required=True, help="File to check")
+
     # === ci command ===
     ci_parser = subparsers.add_parser(
         "ci",
@@ -1549,6 +2104,22 @@ def main() -> int:
         help="Fail threshold for CI (default: high)"
     )
 
+    # === config command ===
+    config_parser = subparsers.add_parser("config", help="Manage crucible configuration")
+    config_sub = config_parser.add_subparsers(dest="config_command")
+
+    # config set-api-key
+    config_sub.add_parser(
+        "set-api-key",
+        help="Set Anthropic API key for LLM compliance assertions"
+    )
+
+    # config show
+    config_sub.add_parser(
+        "show",
+        help="Show current configuration"
+    )
+
     args = parser.parse_args()
 
     if args.command == "init":
@@ -1593,10 +2164,32 @@ def main() -> int:
         else:
             hooks_parser.print_help()
             return 0
+    elif args.command == "assertions":
+        if args.assertions_command == "validate":
+            return cmd_assertions_validate(args)
+        elif args.assertions_command == "list":
+            return cmd_assertions_list(args)
+        elif args.assertions_command == "test":
+            return cmd_assertions_test(args)
+        elif args.assertions_command == "explain":
+            return cmd_assertions_explain(args)
+        elif args.assertions_command == "debug":
+            return cmd_assertions_debug(args)
+        else:
+            assertions_parser.print_help()
+            return 0
     elif args.command == "review":
         return cmd_review(args)
     elif args.command == "pre-commit":
         return cmd_precommit(args)
+    elif args.command == "config":
+        if args.config_command == "set-api-key":
+            return cmd_config_set_api_key(args)
+        elif args.config_command == "show":
+            return cmd_config_show(args)
+        else:
+            config_parser.print_help()
+            return 0
     else:
         # Default help
         print("crucible - Code review orchestration\n")
@@ -1619,9 +2212,16 @@ def main() -> int:
         print("  crucible hooks uninstall        Remove pre-commit hook")
         print("  crucible hooks status           Show hook installation status")
         print()
-        print("  crucible review                 Review git changes")
+        print("  crucible assertions list        List assertion files from all sources")
+        print("  crucible assertions validate    Validate assertion files")
+        print("  crucible assertions test <file> Test assertions against a file")
+        print("  crucible assertions explain <r> Explain what a rule does")
+        print("  crucible assertions debug       Debug applicability for a rule")
+        print()
+        print("  crucible review                 Review git changes or files")
         print("    --mode <mode>                 staged/unstaged/branch/commits (default: staged)")
         print("    --base <ref>                  Base branch or commit count")
+        print("    --no-git                      Review path without git (static analysis only)")
         print("    --fail-on <severity>          Fail threshold (critical/high/medium/low/info)")
         print("    --format <format>             Output format: text (default) or report (markdown)")
         print()