mercury-fix-loop

Mercury Fix Loop

Runs the fixer→judge cycle until all targeted findings are resolved or max iterations reached.

Inputs (from mercury-audit or direct invocation)

• project_dir — absolute path to the project
• branch — git branch created by mercury-audit (or create one now if missing)
• findings — list of finding objects to fix (JSON array, subset of the full report)
• manifest_path — path to mercury_<label>_manifest.json
• goal — user's stated goal if this was a specialized audit (may be null)

Step 0 — NAMS: Record audit session start

Call NAMS to create/update the audit entity:

memory_add_entity({
  name: "<project_label> Mercury Audit <YYYY-MM-DD>",
  type: "AuditSession",
  properties: {
    project_dir, branch, goal, finding_count, timestamp
  }
})

Also add an opening message to NAMS:

memory_add_messages([{
  role: "system",
  content: "Mercury audit started on <project> branch <branch>. <N> findings targeted. Goal: <goal or 'standard'>."
}])

Step 1 — Triage findings into work queue

Sort findings by priority:

1. blocks_goal: true + critical/high first
2. critical (no blocks_goal)
3. high
4. medium (only if explicitly included)

Assign each finding an ID: F-001, F-002, etc. Track state: open | in_progress | fixed_pending_review | approved | rejected

Print the queue:

Fix queue (<N> findings):
F-001 [critical] SECURITY  src/trader.py::execute_order  — <issue>  🎯 blocks goal
F-002 [high]     CORRECTNESS  src/risk.py::check_limits — <issue>
...

Step 2 — Fixer pass

For each finding in the queue (work through them in order):

2a. Set finding to in_progress.

2b. Spawn the mercury-fixer agent with:

Finding ID: <F-xxx>
Severity: <sev>
Category: <category>
File: <file>
Symbol: <symbol>
Issue: <issue>
Why: <why>
Suggested fix: <fix from report>
Goal context: <goal or null>
Project dir: <project_dir>

2c. Fixer agent returns: { fixed: bool, files_changed: [...], diff_summary: str, notes: str }

2d. If fixed: false, mark as rejected with fixer's notes and move on.

Step 3 — Judge review (code-auditor as judge)

For each finding the fixer reports as fixed:

3a. Spawn the code-auditor agent in JUDGE mode with:

MODE: JUDGE
Finding ID: <F-xxx>
Original finding: <full finding JSON>
Files changed: <list>
Diff summary: <fixer's diff summary>
Goal context: <goal or null>
Project dir: <project_dir>
Branch: <branch>

Your job: Determine if this fix is CORRECT, COMPLETE, and introduces NO regressions.
Read the changed files. Check the fix addresses the root cause, not just the symptom.
If the goal is specified, confirm the fix moves closer to the goal.

3b. Judge returns one of:

• APPROVED — finding closed ✅
• REJECTED: <specific reason> — finding goes back to fixer for another pass
• PARTIAL: <what's good, what's missing> — fixer gets targeted follow-up

3c. On REJECTED/PARTIAL: increment retry count. If retry >= 3, escalate to user.

Step 4 — Loop

Repeat Steps 2–3 until:

• All findings are approved → success
• Max iterations (5 per finding) reached → escalate to user with status
• User interrupts

Step 5 — Git commit approved fixes

After each judge APPROVED:

cd "<project_dir>"
git add -p   # stage only changed files
git commit -m "fix(mercury): <F-xxx> <category> — <issue one-liner>

Finding: <F-xxx>
Severity: <sev>
Approved-by: code-auditor (judge)
Audit-branch: <branch>"

Step 6 — Final report

When the loop completes, print:

## Fix Loop Complete — <project> | <branch>

| ID    | Sev      | 🎯 | Status   | File | Fix summary |
|-------|----------|----|----------|------|-------------|
| F-001 | critical | ✅ | APPROVED | ...  | ...         |
| F-002 | high     |    | APPROVED | ...  | ...         |
| F-003 | high     |    | ESCALATED| ...  | max retries |

Approved: N  |  Escalated: N  |  Skipped: N

Next suggested audit: run /mercury-audit again on <branch> to verify clean slate.

Step 7 — NAMS: Record completion

memory_add_messages([{
  role: "assistant",
  content: "Mercury fix loop complete on <project>. <N> findings approved, <N> escalated. Branch: <branch>. Goal: <goal>. Key fixes: <summary>."
}])

memory_add_entity({
  name: "<project_label> Mercury Audit <date>",
  type: "AuditSession",
  properties: { status: "complete", approved_count, escalated_count, branch }
})

Escalation protocol

If a finding hits max retries, surface it to the user with:

• The original finding
• All fixer attempts (diffs)
• All judge rejections with reasons
• A recommendation: "This likely needs architectural change, not a local fix."