From audit JSON to self‑contained repair branch in one step

Audits that stop at a report

You run a repository audit. The tool emits a JSON file that lists missing licences, duplicated imports, and functions that never return a value. The file lands in the inbox. Nobody touches it. The audit cost is recorded, but the repository keeps its technical debt.

The failure mode is clear: audit automation ends with a static report. The next step – repair – is manual, error‑prone, and often abandoned. Teams treat the audit as a compliance checkbox rather than a catalyst for improvement.

From JSON to a repair branch in a single script

The missing link is a deterministic transformation that consumes the audit JSON and produces a self‑contained repair branch. The steps are:

1. Load the JSON.
2. For each issue, select a pre‑written fix template that matches the issue type.
3. Apply the template to the affected file, producing a diff.
4. Create a new Git branch, commit the diffs, and open a PR.

A minimal Node script that does this with the typed TypeScript client looks like this:

import { Repo, PullRequest } from '@shpbl/sdk';
import audit from './audit.json';

async function main() {
  const repo = new Repo('git@github.com:org/project.git');
  const branch = await repo.createBranch('audit‑repair');

  for (const issue of audit.issues) {
    const fix = selectFix(issue);               // returns a string patch
    await repo.applyPatch(branch, issue.file, fix);
  }

  const pr = await PullRequest.open({
    title: 'Automated repair from audit',
    head: branch,
    base: 'main',
    body: 'This PR applies fixes generated from the latest audit run.'
  });

  console.log(`PR created: ${pr.url}`);
}
main();

selectFix is a simple lookup table that maps an issue code to a code snippet. The table lives in the same repository, so the whole process is repeatable and version‑controlled. No AI model is consulted; the transformation is computed rather than generated.

Running the script turns a static JSON file into a fully fledged repair branch ready for review. The cost of the audit is now a tangible asset: a PR that can be merged.

Verifying the fix with the certification harness

Before the PR is merged, the SHPBL certification harness should exercise the changes. The harness runs the artifact against its contract and returns one of four verdicts:

• CERTIFIED – the fix is proven correct.
• PROVISIONAL – the fix runs reproducibly, but correctness is not yet asserted.
• INCONCLUSIVE – the harness could not exercise the contract; the limit is in the harness, not the fix.
• FAILED – the fix broke the contract.

Integrating the harness into the script is straightforward:

import { Harness } from '@shpbl/sdk';

async function verify(branch: string) {
  const result = await Harness.run(branch);
  if (result.verdict !== 'CERTIFIED') {
    throw new Error(`Cannot merge: ${result.verdict}`);
  }
}

Only when the harness returns CERTIFIED does the automation proceed to auto‑merge. This guard prevents the loop from introducing regressions while still eliminating the manual bottleneck.

How SHPBL closes the loop

SHPBL provides the same four access doors – MCP chatbot, HTTP API, typed SDK, and offline files – to run the audit, generate the repair branch, and invoke the certification harness. The library is model‑independent; every step is computed from the input JSON and the fix templates you supply. A Build Intent gate validates the proposal, resolves licensing, and returns a terminal state before any write occurs. You can try the workflow on a repository for free via the repository evaluation lane, then scale with the Practitioner tier if you need the full gauntlet. The method is described in detail on the SH​PBL home page. (≈140 words)

Monday’s concrete step

1. Run your favourite audit tool and save the JSON output.
2. Clone the SHPBL SDK, add a simple fix‑template table, and run the script above.
3. Let the harness verify the branch. If it returns CERTIFIED, merge the PR.

You will have turned an audit cost into a merged repair branch in a single afternoon. The repository’s technical debt shrinks, and the audit becomes an asset rather than a line‑item.