git:20261009.730e4ae to git:20261012.fe72dca

---

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.** Read the end of each log, reproduce the

failure by running the gate, 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;

- 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`.

## 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

- push, open a PR, or run the ship command;

- run `hall ready`, `hall verdict`, `hall pull-back` or `hall drop`;

- edit `.hallmark.toml`, `.hallmark/`, CLAUDE.md or AGENTS.md to make a

finding go away;