hallmark-fix ยท diff
git:20261009.68b7e6b to git:20261009.730e4ae
68 added, 1 removed. Audit A to A.
---
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
- (Workstream C writes the fix loop.)
+ 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;
+ - make the smallest change that fixes the scenario, with a test when the
+ finding is about correctness or evidence;
+ - 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;
+ - weaken or delete tests to make a gate pass.