F04: Fix a bug with a regression test
Choose the commands you use
Operating system
codeArbiter host
Know before you begin
A bug fix should explain what failed and leave a test that catches it next time. Here you stop a ticket claimant from putting a newline, tab, or DEL character into a display name, while keeping an ordinary name such as Sam Allen valid.
Complete F02 first. F03 offers practice with task and commit boundaries. Start from clean main in your Academy clone. Keep your native terminal and selected codeArbiter harness at the same clone. Run Academy and shell commands in the terminal. Send agent requests in the harness. The cards label both.
What you will prove
Run the new regression before editing production code. RED means it fails because the service accepts an invalid name. GREEN means the same test passes after the fix. An import error is a setup problem, not RED evidence.
Commit only after the focused test and service suite pass. One final commit contains tests/test_service.py and workshop_queue/service.py. The current commit gate does not permit a failing-test commit.
Prepare safely
01Establish the baseline
Prepare a numbered fix attempt
From a clean main branch at your Academy clone root, run Prepare in a native terminal. The printed attempt number is evidence metadata, not text to type.
Prepare gives the intentionally defective service a separate, reviewable history.
You · Native terminal · Windows
$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.33\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path prepare F04-fix-with-evidence
You · Native terminal · macOS
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.33/bin/arbiter-academy"
"$academy" --repository "$PWD" prepare F04-fix-with-evidence
You · Native terminal · Linux
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.33/bin/arbiter-academy"
"$academy" --repository "$PWD" prepare F04-fix-with-evidence
Academy switches this clone to academy/F04-fix-with-evidence/ATTEMPT_NUMBER.
If Prepare stops, preserve its message and resolve only the named clean-worktree, branch, or prerequisite condition. Do not force-reset main or delete an earlier attempt.
The numbered branch preserves the defective starting point.
Read the defect and its boundary
Read the prepared service and test file before requesting a change. Identify claim_ticket as the live boundary and confirm that the regression name is not already present.
The lesson repairs one claimant-label rule, not the CLI, JSON storage, or a fictional copy of the service.
You · Native terminal · Windows
Get-Content -LiteralPath 'workshop_queue/service.py'; Get-Content -LiteralPath 'tests/test_service.py'
You · Native terminal · macOS
sed -n '1,240p' workshop_queue/service.py; sed -n '1,180p' tests/test_service.py
You · Native terminal · Linux
sed -n '1,240p' workshop_queue/service.py; sed -n '1,180p' tests/test_service.py
claim_ticket accepts a volunteer label without rejecting newline, tab, or DEL characters, and tests/test_service.py has no claimant-label control-character regression.
If either file differs from that prepared state, stop. Preserve the branch and use Reset for a new F04 attempt rather than adapting another lesson's state.
You identified the real production boundary and the missing executable regression.
Confirm the prepared baseline is clean
Run the service suite in a native terminal before adding the regression. The existing suite must be green and Git must print no paths.
A green prepared baseline lets the later red result identify the new regression instead of a pre-existing failure.
You · Native terminal · Windows
git status --short; python -m unittest tests.test_service -v
You · Native terminal · macOS
git status --short && python3 -m unittest tests.test_service -v
You · Native terminal · Linux
git status --short && python3 -m unittest tests.test_service -v
Git prints nothing and the existing service tests pass.
If Git prints a path or a baseline test fails, preserve the output. Do not add a regression until the prepared attempt is understood; use Reset if the attempt is not clean.
The red test will be attributable to the regression you request next.
Stay on the numbered branch printed by Prepare; do not edit main.
Practice
Request a pause at RED so you can inspect the failure yourself.
02Prove the defect is real
Open the governed fix lane
Enter the fix lane and explicitly request a pause after RED so you can inspect the failure. Ordinary fixes can continue under the original request.
The fix lane records the defect boundary and keeps the upcoming work under the repository's rules.
Your agent · Claude Code harness · All operating systems
/ca:fix "Reject control characters in a claimant label" For this lesson stop after the focused regression fails; wait for my repair request before editing production code or committing.
Your agent · Codex harness · All operating systems
$ca-fix "Reject control characters in a claimant label" For this lesson stop after the focused regression fails; wait for my repair request before editing production code or committing.
Your agent · Pi harness · All operating systems
/ca-fix "Reject control characters in a claimant label" For this lesson stop after the focused regression fails; wait for my repair request before editing production code or committing.
Your agent · Pi harness · All operating systems
/skill:ca-fix "Reject control characters in a claimant label" For this lesson stop after the focused regression fails; wait for my repair request before editing production code or committing.
The focused regression fails for missing validation; production code is still unchanged.
If the command blocks, preserve its finding. Do not bypass the lane or edit workshop_queue/service.py from a terminal.
The governed path names the production boundary before it changes.
Inspect and refine the existing regression
Paste this request into the selected harness and send it. It is an instruction to your agent, not a terminal command, so it never begins with !.
A focused failure must expose the defect before production code changes.
You · Claude Code harness · All operating systems
Inspect the regression already added by the fix lane. Refine it only if needed so there is exactly one direct unittest named test_claim_rejects_control_characters_in_volunteer_label in tests/test_service.py. Loop over Sam\nAdmin, Sam\tAdmin, and Sam\x7fAdmin; for each, use assertRaisesRegex(ValueError, a message containing control characters) around the real claim_ticket call. Then assign the real claim_ticket result for Sam Allen to a variable and assert its claimed_by is Sam Allen. Do not edit workshop_queue/service.py. Run only that test and stop after its semantic assertion failure.
You · Codex harness · All operating systems
Inspect the regression already added by the fix lane. Refine it only if needed so there is exactly one direct unittest named test_claim_rejects_control_characters_in_volunteer_label in tests/test_service.py. Loop over Sam\nAdmin, Sam\tAdmin, and Sam\x7fAdmin; for each, use assertRaisesRegex(ValueError, a message containing control characters) around the real claim_ticket call. Then assign the real claim_ticket result for Sam Allen to a variable and assert its claimed_by is Sam Allen. Do not edit workshop_queue/service.py. Run only that test and stop after its semantic assertion failure.
You · Pi harness · All operating systems
Inspect the regression already added by the fix lane. Refine it only if needed so there is exactly one direct unittest named test_claim_rejects_control_characters_in_volunteer_label in tests/test_service.py. Loop over Sam\nAdmin, Sam\tAdmin, and Sam\x7fAdmin; for each, use assertRaisesRegex(ValueError, a message containing control characters) around the real claim_ticket call. Then assign the real claim_ticket result for Sam Allen to a variable and assert its claimed_by is Sam Allen. Do not edit workshop_queue/service.py. Run only that test and stop after its semantic assertion failure.
Only tests/test_service.py changes, and the focused regression fails because claim_ticket does not raise ValueError.
If the result is an import, syntax, or unrelated failure, reject it as evidence and ask the agent to correct only the regression. If production code changes, do not stage it.
The same named test is executable proof of the original defect.
Observe the semantic red failure
Run the focused regression yourself in a native terminal. This command is expected to fail at this point; read the assertion before continuing.
A test that passes before the repair cannot prove the repair fixed the intended defect.
You · Native terminal · Windows
python -m unittest tests.test_service.TicketTransitionTests.test_claim_rejects_control_characters_in_volunteer_label -v
You · Native terminal · macOS
python3 -m unittest tests.test_service.TicketTransitionTests.test_claim_rejects_control_characters_in_volunteer_label -v
You · Native terminal · Linux
python3 -m unittest tests.test_service.TicketTransitionTests.test_claim_rejects_control_characters_in_volunteer_label -v
The test fails because ValueError was not raised for a claimant label containing a control character.
If the test passes, errors before reaching claim_ticket, or names a different failure, stop. Return to the regression request and preserve the current attempt.
You personally observed the red assertion against the prepared production code.
Inspect the test-only boundary
Inspect whole-worktree status and both relevant paths before staging. The service path must have no diff yet.
Inspect the uncommitted RED boundary before requesting the repair.
You · Native terminal · Windows
git status --short; git diff --check; git diff -- tests/test_service.py workshop_queue/service.py
You · Native terminal · macOS
git status --short && git diff --check && git diff -- tests/test_service.py workshop_queue/service.py
You · Native terminal · Linux
git status --short && git diff --check && git diff -- tests/test_service.py workshop_queue/service.py
Only tests/test_service.py is modified, with no whitespace error and no workshop_queue/service.py change.
If another path changed, do not stage. Preserve the attempt and ask the agent to remove the unrelated change before the repair.
The observed RED boundary is test-only; no commit is needed yet.
The assertion should reach the real claim_ticket function and fail because ValueError was not raised. Explain why the ordinary-name assertion matters: rejecting every name would also be a bug.
03Repair one live boundary
Request the minimal production repair
Paste this request into the selected harness and send it. It is a request to your agent, not a terminal command, so it never begins with !.
The repair must be a reachable claimant-label guard, not a broad rewrite or a disconnected test helper.
You · Claude Code harness · All operating systems
Add only the smallest reachable control-character validation at the existing claim_ticket volunteer-label boundary in workshop_queue/service.py. Reject characters below U+0020 and U+007F, preserve the existing regression unchanged, preserve valid Sam Allen behavior, add no dependency, and run the focused regression plus tests.test_service.
You · Codex harness · All operating systems
Add only the smallest reachable control-character validation at the existing claim_ticket volunteer-label boundary in workshop_queue/service.py. Reject characters below U+0020 and U+007F, preserve the existing regression unchanged, preserve valid Sam Allen behavior, add no dependency, and run the focused regression plus tests.test_service.
You · Pi harness · All operating systems
Add only the smallest reachable control-character validation at the existing claim_ticket volunteer-label boundary in workshop_queue/service.py. Reject characters below U+0020 and U+007F, preserve the existing regression unchanged, preserve valid Sam Allen behavior, add no dependency, and run the focused regression plus tests.test_service.
Only workshop_queue/service.py changes, apart from at most one queued fix work item that codeArbiter records for this repair in .codearbiter/open-tasks.md, and the existing regression is ready to turn green.
If the agent changes the test, adds a dependency, or edits another path, do not stage. Ask it to restore the test and reduce the repair to the claimant boundary.
The repair follows the observed failure and retains the same regression.
Prove the same test turns green
Run the named regression and then the complete service suite in a native terminal before staging the repair.
The same test must change from red to green, while an ordinary claimant remains valid.
You · Native terminal · Windows
python -m unittest tests.test_service.TicketTransitionTests.test_claim_rejects_control_characters_in_volunteer_label -v; python -m unittest tests.test_service -v
You · Native terminal · macOS
python3 -m unittest tests.test_service.TicketTransitionTests.test_claim_rejects_control_characters_in_volunteer_label -v && python3 -m unittest tests.test_service -v
You · Native terminal · Linux
python3 -m unittest tests.test_service.TicketTransitionTests.test_claim_rejects_control_characters_in_volunteer_label -v && python3 -m unittest tests.test_service -v
The named regression passes and the service suite passes, including its ordinary claimant behavior.
If either command fails, preserve the output and ask the agent to revise only workshop_queue/service.py. Keep the regression unchanged.
One named regression is red before the repair and green after it.
Inspect the test and repair
Inspect both paths. The regression must remain unchanged since you observed RED.
The checkpoint rejects extra paths and a regression that no longer checks the defect.
You · Native terminal · Windows
git status --short; git diff --check; git diff -- tests/test_service.py workshop_queue/service.py
You · Native terminal · macOS
git status --short && git diff --check && git diff -- tests/test_service.py workshop_queue/service.py
You · Native terminal · Linux
git status --short && git diff --check && git diff -- tests/test_service.py workshop_queue/service.py
Only the test and service differ from Prepare, apart from at most one queued fix work item on the board.
If another path changed, do not stage. Preserve the attempt and remove only the unintended uncommitted scope before requesting review.
The retained regression and reachable repair are reviewable together.
Stage the green test and repair together
After the focused test and service suite pass, stage the test and service paths. If the fix lane recorded its queued fix work item, the commands also stage the task board so the commit gate reviews that row with the repair.
The governed commit needs one visible test-and-service boundary with passing checks.
You · Native terminal · Windows
git add -- tests/test_service.py workshop_queue/service.py
git diff --quiet -- .codearbiter/open-tasks.md
if ($LASTEXITCODE -ne 0) { git add -- .codearbiter/open-tasks.md }
git diff --cached --stat
You · Native terminal · macOS
git add -- tests/test_service.py workshop_queue/service.py
git diff --quiet -- .codearbiter/open-tasks.md || git add -- .codearbiter/open-tasks.md
git diff --cached --stat
You · Native terminal · Linux
git add -- tests/test_service.py workshop_queue/service.py
git diff --quiet -- .codearbiter/open-tasks.md || git add -- .codearbiter/open-tasks.md
git diff --cached --stat
The index contains the regression and minimal repair, plus the task board only when it holds this repair's queued fix work item.
If another path is staged, unstage only that path and inspect the whole worktree again. Do not commit until the staged list is exact.
One green commit retains the final test and repair.
Review the green fix
Review both staged paths and actual check results before committing.
The learner approves the narrow repair after the regression and full service suite pass.
You · Claude Code harness · All operating systems
Show the staged paths and diff. Confirm the staged paths are tests/test_service.py and workshop_queue/service.py, plus .codearbiter/open-tasks.md only when its sole change is this repair's one queued fix work item, the regression is unchanged since RED, and the focused test and service suite pass. Do not commit until I request it.
You · Codex harness · All operating systems
Show the staged paths and diff. Confirm the staged paths are tests/test_service.py and workshop_queue/service.py, plus .codearbiter/open-tasks.md only when its sole change is this repair's one queued fix work item, the regression is unchanged since RED, and the focused test and service suite pass. Do not commit until I request it.
You · Pi harness · All operating systems
Show the staged paths and diff. Confirm the staged paths are tests/test_service.py and workshop_queue/service.py, plus .codearbiter/open-tasks.md only when its sole change is this repair's one queued fix work item, the regression is unchanged since RED, and the focused test and service suite pass. Do not commit until I request it.
The test and service paths are staged, with the task board only when it holds this repair's queued fix work item, and the checks passed.
If the report names a changed test, another path, or an unreachable guard, do not approve. Preserve the attempt and correct only that defect.
Review the observed RED result separately from the committed final source.
Commit the green fix
After reviewing both staged paths and passing checks, invoke the commit gate.
The governed commit preserves the regression and repair after they pass together.
Your agent · Claude Code harness · All operating systems
/ca:commit
Your agent · Codex harness · All operating systems
$ca-commit
Your agent · Pi harness · All operating systems
/ca-commit
Your agent · Pi harness · All operating systems
/skill:ca-commit
One green learner commit contains both lesson paths, plus this repair's queued fix work item if codeArbiter recorded one.
If the gate blocks, preserve the finding. Keep the passing test and repair together; resolve the named gate before committing.
The governed commit preserves the checked final change.
From codeArbiter 3.8, the fix lane records an authorized repair as one fix work item. On this practice board that is one queued row. Stage it with the repair so the commit gate reviews it in the same commit, and leave it queued; completing work items is outside this lesson.
Inspect the green commit
Confirm clean status and inspect the single learner commit after Prepare.
Check reconstructs this history from Git rather than trusting a transcript.
You · Native terminal · Windows
git status --short
git log -1 --oneline
git show --stat --oneline HEAD
You · Native terminal · macOS
git status --short
git log -1 --oneline
git show --stat --oneline HEAD
You · Native terminal · Linux
git status --short
git log -1 --oneline
git show --stat --oneline HEAD
The commit contains exactly the regression and service repair, plus at most one queued fix work item on the board.
If the history has another path, another commit, or dirty state, preserve it and use Reset for a numbered retry. Do not rebase, amend, or delete the failed evidence.
Git preserves the final change, not the order of earlier test commands.
Recognize success
One green learner commit follows Prepare and contains only the test and service repair. The regression rejects all three control characters and accepts Sam Allen. The short Git status prints nothing. Keep the observed RED and GREEN results in your session: the final commit cannot prove when a test ran.
Check
04Verify and preserve
Run the external Academy Check
Run Check from a native terminal. Academy reads the prepared baseline, commit order, retained source shapes, and clean current worktree without executing learner-authored code.
External verification makes the evidence independently reconstructable.
You · Native terminal · Windows
$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.33\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path check F04-fix-with-evidence
You · Native terminal · macOS
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.33/bin/arbiter-academy"
"$academy" --repository "$PWD" check F04-fix-with-evidence
You · Native terminal · Linux
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.33/bin/arbiter-academy"
"$academy" --repository "$PWD" check F04-fix-with-evidence
Check prints checkpoint F04-fix-with-evidence: passed; progress: .academy/progress.json.
If Check fails, preserve the exact history and read its named predicate. Use Reset for a new numbered attempt instead of rewriting committed evidence.
Only a passing external Check records F04 progress.
Check compares the prepared source, retained regression, reachable repair, and clean worktree. It does not execute learner-authored code or authenticate test chronology. Your actual test runs establish the behavior you observed.
Recover or continue
Preserve a failed attempt and read the named failure before changing anything.
Hint 1. Test claim_ticket, not a helper that production never calls.
Hint 2. Keep the regression unchanged during repair. Never weaken an assertion to get GREEN.
Hint 3. Keep unrelated paths out of the commit. Use Reset when the history needs a fresh numbered attempt.
Create a preserved numbered retry
Use this only after a failed Check or an irrecoverably wrong attempt. Run Reset in a native terminal at the Academy clone root.
Reset keeps the failed red-to-green history reachable and starts the same defect on the next unused branch number.
You · Native terminal · Windows
$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.33\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path reset F04-fix-with-evidence
You · Native terminal · macOS
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.33/bin/arbiter-academy"
"$academy" --repository "$PWD" reset F04-fix-with-evidence
You · Native terminal · Linux
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.33/bin/arbiter-academy"
"$academy" --repository "$PWD" reset F04-fix-with-evidence
Academy archives the prior attempt and switches to the next academy/F04-fix-with-evidence/ATTEMPT_NUMBER branch.
If Reset stops, preserve its message and current branch. Never force-reset or delete the prior attempt.
The failed attempt remains reachable while the retry starts clean.
Return to main after success
After Check passes, return to main in a native terminal without deleting the completed attempt branch.
The passing attempt remains available for a reviewer to inspect.
You · Native terminal · Windows
git switch main
You · Native terminal · macOS
git switch main
You · Native terminal · Linux
git switch main
Git switches to main and leaves academy/F04-fix-with-evidence/ATTEMPT_NUMBER reachable.
If Git refuses because work is uncommitted, stop and preserve it. Do not force the switch.
The completed evidence remains separated from main.
After a passing Check, continue to P01.
Understand the mechanism
Running a regression before a fix shows it detects the defect. Running it afterward checks the repair. A green commit retains both the protection and the implementation. Investigate and Fix a Defect and Test-First Evidence cover the full lane.
Use this in your own project. Describe the input, the actual result, and the expected result. Ask for a regression at the caller boundary.