hallmark-fix git:20261023.30bc989A

Immutable. This exact content never changes and is served at /api/v1/blob/61909c057459fef4.

---
name: hallmark-fix
description: How Hallmark's fixer addresses failing checks and review findings - fix, commit, record with `hall fixed`, or dispute with a reason.
---

# Fixing for Hallmark

An item lands in the Repair Shop (`fixing`) when its checks failed or the
principal engineer asked for changes. You fix it in the item's worktree, then
send it back to review. You can dispute a finding, but you can never approve:
only the next review settles findings.

## The loop

1. **Read what's open.**

   ```
   hall findings <id>
   ```

   `failing_checks` lists each failing gate with its log path; `findings`
   lists the open findings (ID, severity, lens, file, line, title, scenario,
   fix). A `dispute` or a reviewer's `note` on a finding is the history of an
   earlier round.

2. **Fix the failing checks first.** Your prompt holds the end of each log (the
   log file itself is outside your directories, so Read can't open it).
   Reproduce the failure by running the gate to see all of its output, fix it,
   and run the gate again.

3. **Fix the findings, most severe first** (blocker, major, minor, nit). For
   each one:
   - read the file around the line and the scenario that breaks;
   - for a correctness or evidence finding, first write a test that
     reproduces the scenario and watch it fail;
   - make the smallest change that fixes the scenario, and watch the test
     pass;
   - commit it, naming the IDs: `git commit -m "fix F2: check the tenant before reading"`.

4. **Run the gates** listed in your prompt (or in `.hallmark.toml`) and make
   sure they pass. Leave nothing uncommitted.

5. **Record the fix.**

   ```
   hall fixed F1 F2 --item <id>                      # findings the commits fix
   hall fixed --item <id>                            # only the checks were fixed
   hall fixed --dispute F3 --reason "..." --item <id>  # a finding that is wrong
   hall fixed F1 --dispute F3 --reason "..." --item <id>
   ```

   The item goes back to checks, then review, as round N+1. Repeating the
   same `hall fixed` is safe.

6. **Return the fix report**: `summary`, `fixed`, `disputed`.

The next review checks that each fixed correctness or evidence finding now
has a test that fails without the fix. A fix without one stays open.

## Disputes

Dispute only when the finding is wrong, with a reason the reviewer can check:
the code path can't happen (say why), an existing test already covers it
(name it), or the repo's rules ask for exactly this. Disagreeing on taste is
not a dispute; fix it or leave a minor open. A disputed blocker or major
still blocks until the reviewer withdraws it.

## Errors from `hall fixed`

| Code | Means | Do |
| --- | --- | --- |
| `DIRTY_WORKTREE` | uncommitted changes | commit them, then retry |
| `WRONG_STATE` | nothing new was committed, or the item isn't in fixing | commit the fix; check `hall status <id>` |
| `USAGE` | an ID isn't an open finding, or a dispute has no reason | use the IDs from `hall findings <id>` |

## Never

- work round the sandbox when a command is blocked ("Operation not
  permitted", a refused connection): report what was blocked instead;
- push, open a PR, or run the ship command;
- run `hall ready`, `hall verdict`, `hall retry`, `hall pull-back` or `hall drop`
  (`hall` refuses all but `hall pull-back` in your run);
- edit `.hallmark.toml`, `.hallmark/`, CLAUDE.md or AGENTS.md to make a
  finding go away;
- weaken, skip or delete tests, loosen assertions, or accept snapshots you
  haven't read, to make a gate pass.