Phase 4: Pre-commit hook integration for suggest engine

[Kadajett]

Context

Part of the --suggest recommendations engine (see #135). Depends on #137, #138, #140.

What to Build

1. --precommit flag and changed-file scoping

Add --precommit flag to CLI. When active:

• Detect staged files via git diff --cached --name-only
• Scope SuggestEngine to only those files + their direct callers/callees in the call graph (for context)
• Output in a pre-commit-friendly format (exit code 0 for pass, 1 for fail)

// src/suggest/precommit.rs
pub fn run_precommit(config: &SuggestConfig, cache: &CacheDir) -> Result<PrecommitResult> {
    let changed_files = git_staged_files()?;
    let scope = SuggestScope::Files(changed_files);
    // ... evaluate with scope, apply precommit config
}

pub struct PrecommitResult {
    pub recommendations: Vec<Recommendation>,
    pub should_block: bool,  // based on config thresholds
    pub exit_code: i32,
}

2. Pre-commit config in .semfora/suggest.yaml

precommit:
  enabled: true
  mode: warn              # warn (exit 0) | fail (exit 1 if threshold exceeded)
  fail_threshold: 3       # block if > N suggestions
  groups:                  # per-group override
    dead-code: fail        # always block on dead code
    naming: warn           # just warn on naming
    complexity: fail

3. Hook installation helpers

• semfora suggest --install-hook — writes to .git/hooks/pre-commit (or appends if exists)
• semfora suggest --install-hook --husky — writes to .husky/pre-commit
• Provide .pre-commit-hooks.yaml for the pre-commit framework:

- id: semfora-suggest
  name: semfora code suggestions
  entry: semfora-engine suggest --precommit
  language: system
  types: [file]
  pass_filenames: false

4. Performance

• Only load symbols for changed files (use CacheDir symbol lookup by file path)
• Expand scope to include 1-hop callers/callees for context-aware rules
• Target: <500ms for typical commits (1-10 files)

Acceptance Criteria

• semfora suggest --precommit runs only on staged files
• Exit code reflects config (0 for warn, 1 for fail when threshold exceeded)
• --install-hook creates working git hooks
• .pre-commit-hooks.yaml provided for pre-commit framework
• Performance: <500ms on 10-file commits
• Per-group warn/fail configuration works
• Integration test simulating a pre-commit run

References

• Architecture: Research: Recommendations Engine Architecture (--suggest system) #135
• Config system: Phase 2: Suggest configuration system (.semfora/suggest.yaml) #140
• Git integration: src/git/mod.rs