Preview 0.33

F04: Fix a bug with a regression test

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.

Why

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

Expected result

Academy switches this clone to academy/F04-fix-with-evidence/ATTEMPT_NUMBER.

If that does not happen

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.

Evidence

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.

Why

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

Expected result

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 that does not happen

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.

Evidence

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.

Why

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

Expected result

Git prints nothing and the existing service tests pass.

If that does not happen

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.

Evidence

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.

Why

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.

Expected result

The focused regression fails for missing validation; production code is still unchanged.

If that does not happen

If the command blocks, preserve its finding. Do not bypass the lane or edit workshop_queue/service.py from a terminal.

Evidence

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

Why

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.

Expected result

Only tests/test_service.py changes, and the focused regression fails because claim_ticket does not raise ValueError.

If that does not happen

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.

Evidence

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.

Why

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

Expected result

The test fails because ValueError was not raised for a claimant label containing a control character.

If that does not happen

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.

Evidence

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.

Why

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

Expected result

Only tests/test_service.py is modified, with no whitespace error and no workshop_queue/service.py change.

If that does not happen

If another path changed, do not stage. Preserve the attempt and ask the agent to remove the unrelated change before the repair.

Evidence

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

Why

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.

Expected result

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 that does not happen

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.

Evidence

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.

Why

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

Expected result

The named regression passes and the service suite passes, including its ordinary claimant behavior.

If that does not happen

If either command fails, preserve the output and ask the agent to revise only workshop_queue/service.py. Keep the regression unchanged.

Evidence

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.

Why

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

Expected result

Only the test and service differ from Prepare, apart from at most one queued fix work item on the board.

If that does not happen

If another path changed, do not stage. Preserve the attempt and remove only the unintended uncommitted scope before requesting review.

Evidence

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.

Why

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

Expected result

The index contains the regression and minimal repair, plus the task board only when it holds this repair's queued fix work item.

If that does not happen

If another path is staged, unstage only that path and inspect the whole worktree again. Do not commit until the staged list is exact.

Evidence

One green commit retains the final test and repair.

Review the green fix

Review both staged paths and actual check results before committing.

Why

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.

Expected result

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 that does not happen

If the report names a changed test, another path, or an unreachable guard, do not approve. Preserve the attempt and correct only that defect.

Evidence

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.

Why

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

Expected result

One green learner commit contains both lesson paths, plus this repair's queued fix work item if codeArbiter recorded one.

If that does not happen

If the gate blocks, preserve the finding. Keep the passing test and repair together; resolve the named gate before committing.

Evidence

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.

Why

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

Expected result

The commit contains exactly the regression and service repair, plus at most one queued fix work item on the board.

If that does not happen

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.

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.

Why

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

Expected result

Check prints checkpoint F04-fix-with-evidence: passed; progress: .academy/progress.json.

If that does not happen

If Check fails, preserve the exact history and read its named predicate. Use Reset for a new numbered attempt instead of rewriting committed evidence.

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.

Why

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

Expected result

Academy archives the prior attempt and switches to the next academy/F04-fix-with-evidence/ATTEMPT_NUMBER branch.

If that does not happen

If Reset stops, preserve its message and current branch. Never force-reset or delete the prior attempt.

Evidence

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.

Why

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

Expected result

Git switches to main and leaves academy/F04-fix-with-evidence/ATTEMPT_NUMBER reachable.

If that does not happen

If Git refuses because work is uncommitted, stop and preserve it. Do not force the switch.

Evidence

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.

Next step

Continue with P01-feature-through-plan.

Recovery guidance