From audit report to merged repair branch in one step

Audits that stop at a PDF

The common audit workflow ends with a PDF. The report lists findings, severity, and location. Developers open the file, copy a line number, search the repo, and start a manual fix. The loop never closes. Time spent reading and triaging is dead weight. The codebase does not improve until someone remembers the report weeks later. The cost is hidden but real: stale findings, duplicated effort, and a false sense of compliance.

The repair branch that should follow the audit

A repair branch is the natural continuation of an audit. The audit already knows which files violate a rule and why. If the same data can be turned into a patch, the audit becomes a repair tool. The branch contains the exact change needed to satisfy the rule. Opening a pull request (PR) makes the change visible, reviewable, and mergeable. The repository gains a concrete improvement instead of a lingering PDF.

The difficulty lies in translating a rule violation into syntactically correct code. Some fixes are straightforward – replace a deprecated API call with its modern equivalent. Others need context – a refactor that touches several modules. An automated pipeline must therefore emit a self‑contained repair that compiles and passes the existing test suite. When the pipeline cannot guarantee correctness, it should still produce a provisional branch that a human can review.

Turning audit JSON into an automated PR

The audit engine we use exports a JSON payload. Each entry contains the file path, line range, rule identifier, and a short description. The repair pipeline consumes this payload and runs a series of steps:

1. Resolve the rule identifier to a repair template stored in the library.
2. Apply the template to the target file, preserving surrounding code.
3. Run the certification harness on the modified repository.
4. If the harness returns CERTIFIED or PROVISIONAL, create a new branch, commit the change, and open a PR via the HTTP API.

A minimal script looks like this:

audit-json ./audit/report.json \
  | shpbl-repair --template-dir ./templates \
  | shpbl-harness --run \
  | shpbl-pr --api https://api.shpbl.com --repo myorg/myrepo

The shpbl-repair step is model‑independent. It selects a pre‑written repair artifact from the catalog, inserts it into the source, and produces a diff. The shpbl-harness step executes the artifact against the repository’s test suite. The harness records a verdict – CERTIFIED, PROVISIONAL, INCONCLUSIVE, or FAILED – and includes that verdict in the PR description. Reviewers see exactly why the change was made and whether the harness could verify it.

Because the same library powers the MCP server, the plain HTTP API, and the typed TypeScript client (@shpbl/sdk), you can swap the command‑line for any integration point without changing behaviour. The offline edition can run the same steps from local files, useful for air‑gapped environments.

How SHPBL solves the end‑to‑end loop

SHPBL provides a model‑independent library of reusable repair artifacts. The library is accessed through four identical gates: an MCP server, a plain HTTP API, a typed TypeScript client, and an offline file‑based edition. Every artifact is exercised by a certification harness that records a verdict – CERTIFIED, PROVISIONAL, INCONCLUSIVE, or FAILED – before any PR is opened. The Build Intent gate validates licensing and invariants before any write occurs, so previewing a repair costs nothing. You can start with a free repository evaluation at /evaluation to see the audit‑to‑repair pipeline in action, then move to the Practitioner tier for the full gauntlet. The method is described in detail on the pillar post /blog/closing-the-loop-from-repository-audit-to-merged-repair.

A concrete step for Monday

Run the free evaluation on a repository you own. Export the audit as JSON. Feed that JSON to the SHPBL repair command shown above. Review the generated PR, merge it, and observe the repository change. The loop that used to end in a PDF now ends in a merged repair branch.