Bug Laws — Engineering Archaeology

Bug Laws turns a Python repository's bug-fix history into a review-ready evidence wall. It recovers candidate engineering invariants, links each candidate to commits and files, groups recurring patterns, and shows whether fixes changed regression tests.

What it does

• Scans local Git history in read-only mode.
• Finds bug-fix, regression, hotfix, and revert candidates.
• Extracts commit hashes, affected files, tests, guards, and changed symbols.
• Groups repeated patterns using deterministic, explained similarity.
• Produces Markdown, JSON, and self-contained HTML evidence walls.
• Keeps extracted candidates separate from explicit review decisions.

Why it matters

Commit messages record what changed. Bug Laws asks what engineering constraint the failure revealed, whether that constraint recurred, and whether the project added test protection.

Quick start

Install Python 3.11+ and Git, then run:

python -m pip install -e .
python -m buglaws scan /path/to/python/repository --label github.com/org/repository

The output contains:

• BUG_LAWS.md — a readable evidence report
• bug-laws.json — machine-readable provenance
• index.html — a visual evidence wall

Evidence boundary

Every result is a candidate until an explicit reviewer accepts, edits, rejects, or marks it unscorable. A changed test file is a protection signal, not proof that a test catches a bug. The default workflow is local, read-only, keyless, and does not modify source code or project policy.

Project

Open source repository: https://github.com/dengjihui1/bug-laws

This Agent is a packaged interface to the repository's tested Bug Laws workflow. The GitHub project contains the implementation, reproducible examples, workflow diagram, and limitations.