Documentationv1.4.0

History-Aware Escalation

Local, deterministic structural risk scoring and suggested remediation commands.

Zero-AI, 100% Deterministic Risk Scoring

gitresolve incorporates a local, dependency-free escalation layer. Before touching any conflict file, the engine mines repository Git history and inspects AST call trees to answer two questions:

  • Why did this conflict happen? (e.g. stale branch divergence, simultaneous edits by teammates).
  • What is the blast radius? (e.g. widely referenced symbols, un-modified coupled partner files, dependency cycles).

When structural risk exceeds policy thresholds, gitresolve escalates the block for human review with an informative 2-line explanation and a suggested command rendered from parameterized templates filled strictly from verified repository facts.

semantic.high_blast_radius

Blast Radius Analysis

Detects when a modified function or symbol is referenced by more than 10 other locations across the codebase.

semantic.missing_coupled_file

Missing Coupled Files

Detects when historical co-change strength >= 0.60 indicates a paired file should have been modified, but was not.

semantic.import_cycle

Import Cycle Detection

Evaluates Go package dependency graphs using Tarjan's SCC algorithm to flag conflicts sitting inside cyclic dependencies.

strategy.stale_branch_divergence

Stale Branch Divergence

Pre-flight check running before resolution to detect branches falling behind remote default branch with overlapping authors.

CLI Terminal Experience

Clean 2-line summary in default mode; comprehensive evidence audit in verbose mode.

1. Default View (Interactive Escalation)

bash
$gitresolve resolve
Warning: branch is 15 commits behind main — alice@example.com, bob@example.com authored changes touching files you also modified
suggested: git fetch && git rebase origin/main
Conflict in internal/payments/charge.go (lines 45-58):
reason: ProcessPayment is called from 14 other locations — escalating for manual review
suggested: go test ./... (run full suite before committing)
Select resolution [1: ours, 2: theirs, 3: manual, 4: abort]: _

2. Verbose Evidence View (--verbose / -v)

bash – verbose mode
$gitresolve resolve -v
Conflict in internal/payments/charge.go (lines 45-58):
reason: ProcessPayment is called from 14 other locations — escalating for manual review
suggested: go test ./... (run full suite before committing)
[verbose evidence]
AST / Conflict block diff:
--- ours ---
+ func ProcessPayment(amount int) error { ... }
--- theirs ---
- func ProcessPayment(amount int, currency string) error { ... }
Historical author contributions:
* alice@company.com (weight: 2.45, last touched: 2026-08-21)
* bob@company.com (weight: 1.10, last touched: 2026-08-15)
Historical file couplings:
* handlers/checkout.go (count: 18, strength: 0.90)
Decision log row:
reason_code: semantic.high_blast_radius | confidence: 0.20 | type: func_decl | severity: high

Namespaced Reason Codes

Stable reason codes written to the SQLite decision_logs table.

Reason CodeCategorySeverityTrigger Condition
semantic.high_blast_radiusSemanticHighCallee count > max_callers (default 10)
semantic.missing_coupled_fileSemanticMediumCo-change strength ≥ 0.60, partner file untouched
semantic.import_cycleSemanticHighFile package is member of a Tarjan SCC cycle
strategy.stale_branch_divergenceStrategyMediumBehind commits > max_divergence_commits
strategy.multi_author_conflictStrategyInfoConflicted sides have distinct historical contributors

Performance Guarantees

Graph build + rule evaluation is designed to add negligible overhead to the resolve pipeline.

Target Budget
< 200 ms

Upper bound ceiling for full graph build on large repositories.

Benchmark Result
~55 ms

Measured over 5,000 commits and 2,000 files in synthetic suite.

Incremental Sync
~10 ms

Cached commit SHAs in SQLite enable near-instant re-runs.