U03: Refactor, chore, and local release evidence
Choose the commands you use
Operating system
CodeArbiter host
This guided lesson prepares a sealed local release exercise in your fork. It creates no remote tag, GitHub Release, or publication claim.
Know before you begin
Read the boundary before running anything. U03 proves a local refactor, a docs chore, and the local release artifacts that the real CodeArbiter release lane creates.
Read the local evidence boundary
You · Active CodeArbiter harness · All operating systems
This prepared lesson is limited to an exact refactor of workshop_queue/store.py, a later docs-only README.md commit, the generated CHANGELOG.md release commit, an unchanged pre-existing tests/test_store.py, a clean worktree, and the declared annotated academy-v0.0.1 tag at the attempt head. Do not substitute your own scope, target, or release metadata.
A narrow contract makes the difference between repository evidence and a broader release claim visible.
You can name the exact local boundaries that Check can evaluate after Prepare.
If the boundary is unclear, stop before Prepare and reread this card. Next safe step: prepare the sealed U03 attempt.
Check can observe repository bytes, commit topology, the declared release target, generated CHANGELOG section, a clean worktree, and a local tag. It does not prove behavioral parity, human approval, CodeArbiter command execution, tag push, or publication.
What you will prove
The contract is deliberately narrow. Check can observe a sealed refactor of workshop_queue/store.py, a later docs-only README.md commit, the generated CHANGELOG.md release commit, unchanged pre-existing tests/test_store.py, a clean worktree, and local annotated academy-v0.0.1 at the attempt head. Its tag body reproduces the generated 0.0.1 changelog section followed by the matching Released-at date.
It does not prove behavioral parity, human approval, CodeArbiter command execution, tag push, or publication.
Prepare safely
Start from a clean Academy clone root. Prepare creates the sealed branch and brief. Do not make U03 files by hand.
Prepare the sealed U03 attempt
At the clean Academy clone root, run Prepare in a native terminal. Native-terminal commands go directly into that terminal and never begin with !.
Prepare creates the attempt branch and freezes the brief before learner work begins.
You · Native terminal · Windows
$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.30\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path prepare U03-refactor-chore-releaseYou · Native terminal · macOS
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" prepare U03-refactor-chore-releaseYou · Native terminal · Linux
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" prepare U03-refactor-chore-releasePrepare creates academy/U03-refactor-chore-release/1 with the sealed brief and declared release target, then reports its prepared commit.
If Prepare refuses or reports a dirty repository, preserve existing work and make the clone clean before retrying. Next safe step: inspect the prepared branch and brief.
Preserve the printed attempt branch and prepared commit. They bind all later Check evidence.
Confirm the prepared attempt is clean
Inspect the worktree from the same native terminal after Prepare. These commands are direct terminal commands and never begin with !.
The sealed attempt must begin clean before the learner invokes any host workflow.
You · Native terminal · Windows
git status --shortYou · Native terminal · macOS
git status --shortYou · Native terminal · Linux
git status --shortThe active branch is academy/U03-refactor-chore-release/1 and git status is empty after Prepare.
If the branch or status is wrong, stop and use Academy Reset only after preserving any unrelated work. Next safe step: review the sealed brief.
Preserve the branch name and clean status before beginning the refactor lane.
Practice
The following cards operate on the prepared attempt. The sealed brief supplies the exact approved values. The website remains the teaching surface; commands appear only in their action cards.
Review the sealed brief before work begins
Open the prepared sealed brief at training_scenarios/U03-refactor-chore-release.json using one command surface below. Read refactor.scope, chore.approved_readme_fact, release.target, release.changelog, and release.tag. Those exact values bound the refactor, README chore, and local release. Do not invent a generic command argument or a release claim.
The prepared scenario file is the authoritative sealed brief that supplies the scope the lesson and Check can evaluate.
You · Native terminal · Windows
Get-Content training_scenarios/U03-refactor-chore-release.jsonYou · Native terminal · macOS
cat training_scenarios/U03-refactor-chore-release.jsonYou · Native terminal · Linux
cat training_scenarios/U03-refactor-chore-release.jsonYou · Codex harness · Windows
! Get-Content training_scenarios/U03-refactor-chore-release.jsonYou · Claude Code harness · All operating systems
! cat training_scenarios/U03-refactor-chore-release.jsonThe prepared attempt shows the exact refactor scope, approved README fact, local release target, CHANGELOG.md path, and academy-v0.0.1 tag before you invoke the refactor route.
If any required value is absent or ambiguous, stop the attempt and preserve the condition for its author. Do not guess. Next safe step: invoke the refactor route only after the brief is clear.
Reading a brief does not authenticate a human approval or an executed host command.
Start the host-native refactor route
Invoke the host-native refactor route. Supply the exact sealed scope when the host asks for it. This is a CodeArbiter command, never a ! terminal passthrough command.
The refactor route should be bounded by the sealed U03 surface before the learner examines a change.
Your agent · Claude Code harness · All operating systems
/ca:refactorYour agent · Codex harness · All operating systems
$ca-refactorYour agent · Pi harness · All operating systems
/ca-refactorYour agent · Pi harness · All operating systems
/skill:ca-refactorThe host gathers the sealed scope before producing a proposed refactor boundary.
If the host requests a value that the sealed brief does not provide, stop. Do not supply a made-up scope. Next safe step: inspect the proposed refactor diff.
This lesson does not treat the command text as proof of behavioral parity or CodeArbiter command execution.
Inspect the proposed refactor boundary
Inspect the proposed diff in a native terminal. These commands are direct terminal commands and never begin with !.
The learner sees the exact implementation path before staging it.
You · Native terminal · Windows
git diff -- workshop_queue/store.py
git diff -- tests/test_store.pyYou · Native terminal · macOS
git diff -- workshop_queue/store.py
git diff -- tests/test_store.pyYou · Native terminal · Linux
git diff -- workshop_queue/store.py
git diff -- tests/test_store.pyYou can inspect the proposed store.py delta and confirm that tests/test_store.py has no diff.
If a pre-existing test changes or another path is involved, stop the refactor boundary instead of staging it. Next safe step: review the bounded diff.
A diff shows local bytes. It does not prove behavioral parity.
Decide whether the refactor boundary is acceptable
You · Active CodeArbiter harness · All operating systems
Decide whether the proposed change is limited to the sealed refactor boundary and leaves tests/test_store.py unchanged. Do not ask the agent to widen the task or assert that a review proves parity.
A learner decision remains separate from repository evidence.
You either stop the refactor boundary or can name the exact file that may be staged.
If the boundary is unclear, return to the sealed brief and preserve the proposed diff. Do not stage it. Next safe step: stage only store.py after accepting the boundary.
No file or log can prove that this learner review occurred.
Stage only the sealed refactor file
Only after accepting the refactor boundary, stage workshop_queue/store.py in a native terminal. Native-terminal commands never begin with !.
The staged path list makes the first commit boundary explicit.
You · Native terminal · Windows
git add -- workshop_queue/store.py
git diff --cached --name-onlyYou · Native terminal · macOS
git add -- workshop_queue/store.py
git diff --cached --name-onlyYou · Native terminal · Linux
git add -- workshop_queue/store.py
git diff --cached --name-onlyThe staged boundary names only workshop_queue/store.py.
If another path is staged, unstage only the unexpected path and inspect again. Do not reset or rewrite the attempt. Next safe step: invoke the commit gate.
The staged list is a local scope check, not proof that a refactor is behaviorally equivalent.
Commit the accepted refactor boundary
After the learner reviews the staged boundary, invoke the host-native commit gate. It is a CodeArbiter command, never a ! terminal passthrough command.
Check expects the refactor commit before the docs-only commit.
Your agent · Claude Code harness · All operating systems
/ca:commitYour agent · Codex harness · All operating systems
$ca-commitYour agent · Pi harness · All operating systems
/ca-commitYour agent · Pi harness · All operating systems
/skill:ca-commitThe attempt has one committed refactor boundary before the later docs-only work.
If the gate reports a finding, preserve it and correct only the stated boundary. The next dry run has one documented unpublished-HEAD recovery for its release-footer blocker; do not otherwise rewrite the attempt. Next safe step: run the local release dry run.
A commit can show ordered paths and bytes. It does not prove a human approval or a successful host conversation.
The bare commit gate does not take a fabricated footer argument. Before the docs chore, the real release dry run either diagnoses a missing footer without writing release artifacts or recognizes that the commit already has the approved footer. Only the documented missing-footer result permits the narrow HEAD-only amend; otherwise skip that card. It is never a reason to rewrite public history.
Ask the release lane to diagnose the local commit log
Before any docs chore, invoke the host-native release dry run for the declared target. The real lane either reports its read-only missing-CHANGELOG-footer block, or recognizes that the bare refactor already has the approved footer. It writes no CHANGELOG, tag, or commit in either case.
The release lane, not invented commit arguments, identifies the missing release metadata.
Your agent · Claude Code harness · All operating systems
/ca:release --dry-run academy-private-trainingYour agent · Codex harness · All operating systems
$ca-release --dry-run academy-private-trainingYour agent · Pi harness · All operating systems
/ca-release --dry-run academy-private-trainingYour agent · Pi harness · All operating systems
/skill:ca-release --dry-run academy-private-trainingThe dry run either blocks on the missing CHANGELOG footer or reports that HEAD already has the approved footer; both outcomes leave the worktree, commit count, CHANGELOG.md, and tags unchanged.
If the dry run reports a different blocker, preserve its text and stop; do not guess a repair. Next safe step: review whether the documented footer block appeared or the approved footer was already present.
The dry-run output is advisory. Check can later observe only the amended local commit message and release artifacts.
Inspect the documented release blocker
You · Active CodeArbiter harness · All operating systems
Confirm that the dry run either named the missing CHANGELOG footer on the just-created refactor commit or showed that exact approved footer already exists, and that it produced no release write. Do not treat another failure as permission to edit history.
The narrowly documented repair applies only to this precise unpublished-HEAD failure.
You can distinguish the expected missing-footer block, an already-complete approved footer, and an unrelated release failure.
If the approved footer already exists, skip the amend and continue to the docs chore. If the message does not name the footer, stop and preserve the output for diagnosis. Next safe step: amend only after the documented footer block, otherwise start the docs chore.
The learner's interpretation is not authenticated by Check.
Approve the sealed factual release footer
You · Active CodeArbiter harness · All operating systems
Review and explicitly approve this factual footer for the sealed refactor: `CHANGELOG: Preserve ticket-read behavior while clarifying its boundary.` This approval is limited to the unpublished HEAD refactor and does not authorize a remote rewrite, tag change, push, or publication.
The learner supplies the release summary that the bare commit gate could not know at commit time.
You either stop, or approve this one footer for the sealed local refactor only.
If the footer is not accurate, stop instead of substituting a different release claim. Next safe step: amend only after approving the exact footer.
Check cannot prove the approval; it can only inspect the later local message.
Amend the unpublished HEAD refactor with the approved footer
Only after the dry run reports the missing-footer block, and only while the sealed refactor is the unpublished HEAD before any later commit, tag, or push, amend its message in a native terminal with the approved footer. Each command verifies that HEAD is not already contained in origin/main before it amends. This is the release lane's documented HEAD-only recovery; never use it to rewrite public history or teach rebase.
The recovery repairs exactly the release metadata that the dry run diagnosed without adding a fourth learner commit.
You · Native terminal · Windows
git log -1 --format=%B
git merge-base --is-ancestor HEAD origin/main
$contained = $LASTEXITCODE
if ($contained -eq 0) { Write-Error "STOP: HEAD is already contained in origin/main"; exit 1 }
if ($contained -ne 1) { exit $contained }
git commit --amend -m "refactor: clarify store boundary" -m "Preserve behavior while clarifying the ticket-read boundary." -m "CHANGELOG: Preserve ticket-read behavior while clarifying its boundary."
git status --shortYou · Native terminal · macOS
git log -1 --format=%B
git merge-base --is-ancestor HEAD origin/main
contained=$?
if [ "$contained" -eq 0 ]; then echo "STOP: HEAD is already contained in origin/main" >&2; exit 1; fi
if [ "$contained" -ne 1 ]; then exit "$contained"; fi
git commit --amend -m "refactor: clarify store boundary" -m "Preserve behavior while clarifying the ticket-read boundary." -m "CHANGELOG: Preserve ticket-read behavior while clarifying its boundary."
git status --shortYou · Native terminal · Linux
git log -1 --format=%B
git merge-base --is-ancestor HEAD origin/main
contained=$?
if [ "$contained" -eq 0 ]; then echo "STOP: HEAD is already contained in origin/main" >&2; exit 1; fi
if [ "$contained" -ne 1 ]; then exit "$contained"; fi
git commit --amend -m "refactor: clarify store boundary" -m "Preserve behavior while clarifying the ticket-read boundary." -m "CHANGELOG: Preserve ticket-read behavior while clarifying its boundary."
git status --shortThe same local refactor boundary remains HEAD with its approved CHANGELOG footer; no new commit, tag, push, or publication occurs.
If the refactor is no longer the unpublished HEAD, stop. Do not rebase, force-push, rewrite a tag, or edit public history; use Academy Reset for a fresh sealed attempt. Next safe step: verify the amended local message.
Check can read the final local commit message and path topology, not prove this command was used.
Verify the amended local refactor boundary
In a native terminal, verify the amended HEAD message and its one-file boundary before starting the docs chore. These direct terminal commands never begin with !.
A local read shows whether the narrow repair still names a refactor and changes only the sealed code path.
You · Native terminal · Windows
git log -1 --format=%B
git diff --name-only HEAD^ HEAD
git status --shortYou · Native terminal · macOS
git log -1 --format=%B
git diff --name-only HEAD^ HEAD
git status --shortYou · Native terminal · Linux
git log -1 --format=%B
git diff --name-only HEAD^ HEAD
git status --shortHEAD is a refactor message with the approved footer, changes only workshop_queue/store.py, and leaves the worktree clean.
If the message or path boundary differs, stop before the docs chore and use Academy Reset rather than editing later history. Next safe step: start the docs chore only after this local check matches.
This terminal output is local inspection, not proof of an approved host interaction.
Start the host-native docs chore route
Invoke the host-native docs chore route. Supply the exact approved README fact from the sealed brief when the host asks. This is a CodeArbiter command, never a ! terminal passthrough command.
The second change is a docs-only boundary, not a disguised implementation change.
Your agent · Claude Code harness · All operating systems
/ca:chore docsYour agent · Codex harness · All operating systems
$ca-chore docsYour agent · Pi harness · All operating systems
/ca-chore docsYour agent · Pi harness · All operating systems
/skill:ca-chore docsThe host gathers the exact approved README fact before proposing a docs-only delta.
If the host proposes code, test, or release-metadata changes, stop the chore boundary instead of staging it. Next safe step: inspect the README diff.
This lesson does not treat the command text as proof of a valid docs-only decision.
Inspect the proposed docs-only boundary
Inspect the proposed README delta in a native terminal. These commands are direct terminal commands and never begin with !.
The learner can reject scope creep before the second commit exists.
You · Native terminal · Windows
git diff -- README.md
git status --shortYou · Native terminal · macOS
git diff -- README.md
git status --shortYou · Native terminal · Linux
git diff -- README.md
git status --shortYou can inspect the README.md delta and identify any path outside the docs-only boundary.
If any non-README.md path is present, stop and return to the sealed brief. Do not stage the chore. Next safe step: review the docs-only boundary.
A worktree inspection reports local state only.
Decide whether the docs-only boundary is acceptable
You · Active CodeArbiter harness · All operating systems
Decide whether the README.md delta states only the prepared approved fact. The learner makes this decision. Do not use a generated report as a substitute for it.
A distinct review prevents the later docs commit from inheriting the refactor's authorization.
You either stop the docs boundary or can name README.md as the only file that may be staged.
If the intended fact is not exact, preserve the diff and ask the agent to revise only that draft. Next safe step: stage README.md after accepting the boundary.
No artifact can prove that the learner accepted the docs-only boundary.
Stage only the approved README change
Only after accepting the docs-only boundary, stage README.md in a native terminal. Native-terminal commands never begin with !.
The second staged path list keeps the chore distinct from the refactor commit.
You · Native terminal · Windows
git add -- README.md
git diff --cached --name-onlyYou · Native terminal · macOS
git add -- README.md
git diff --cached --name-onlyYou · Native terminal · Linux
git add -- README.md
git diff --cached --name-onlyThe staged boundary names only README.md.
If another path is staged, unstage only the unexpected path and inspect again. Do not reset or rewrite the attempt. Next safe step: invoke the commit gate.
The staged list can show an exact local path boundary, not an approval.
Commit the accepted docs-only boundary
After the learner reviews the staged README boundary, invoke the host-native commit gate. It is a CodeArbiter command, never a ! terminal passthrough command.
Check expects the docs-only commit after the refactor commit.
Your agent · Claude Code harness · All operating systems
/ca:commitYour agent · Codex harness · All operating systems
$ca-commitYour agent · Pi harness · All operating systems
/ca-commitYour agent · Pi harness · All operating systems
/skill:ca-commitThe attempt has its docs-only commit after the sealed refactor commit.
If the gate blocks, preserve the finding and correct only the named README boundary. Do not rewrite either commit. Next safe step: invoke the declared release route.
A commit can show ordered repository paths. It does not prove a human approval or a host command execution.
Start the host-native release route
Invoke the host-native release route. Supply the exact declared target academy-private-training. It first presents the derived 0.0.1 patch release for learner confirmation; only after that confirmation may it write and commit CHANGELOG.md and compose an annotated local tag. This is a CodeArbiter command, never a ! terminal passthrough command. Do not invent a target and do not authorize a tag push or publication.
The route is a local evidence step in this lesson, not a promise of published software.
Your agent · Claude Code harness · All operating systems
/ca:release academy-private-trainingYour agent · Codex harness · All operating systems
$ca-release academy-private-trainingYour agent · Pi harness · All operating systems
/ca-release academy-private-trainingYour agent · Pi harness · All operating systems
/skill:ca-release academy-private-trainingAfter the learner confirms the derived version, the route commits the generated CHANGELOG.md section and composes annotated academy-v0.0.1. It does not push the tag or publish a release.
If the target is absent or the route reports a blocker, preserve that result and stop. Do not manufacture release metadata. Next safe step: review the local tag boundary.
The local changelog commit and tag are observable release artifacts; they do not prove a remote tag, GitHub Release, or publication.
Review the local tag boundary
You · Active CodeArbiter harness · All operating systems
Review the declared target and confirm that the required local release evidence is the generated CHANGELOG.md commit followed by annotated academy-v0.0.1 at the attempt head. Its body must reproduce the generated 0.0.1 changelog section followed by its matching Released-at date. Do not claim that a tag proves publication, a pushed reference, or a release record.
The local tag has a narrow evidentiary meaning.
You can either stop for a missing boundary or proceed to inspect the declared local tag.
If the tag name, object type, or target is not exact, preserve the state and stop. Do not retag over the attempt. Next safe step: inspect the local tag bytes.
Review is a learner action. The repository cannot prove it happened.
Inspect the declared annotated tag at HEAD
Inspect academy-v0.0.1 and CHANGELOG.md in a native terminal. Confirm the tag is annotated at HEAD and that its body reproduces the generated 0.0.1 changelog section followed by a matching Released-at date. Native-terminal commands never begin with !.
The learner verifies that the local tag is annotated, has Check's exact canonical body including one terminal newline, and points to the current attempt head.
You · Native terminal · Windows
git cat-file -t academy-v0.0.1
git tag --points-at HEAD
git show --no-patch --format=%B academy-v0.0.1
Get-Content CHANGELOG.mdYou · Native terminal · macOS
git cat-file -t academy-v0.0.1
git tag --points-at HEAD
git show --no-patch --format=%B academy-v0.0.1
cat CHANGELOG.mdYou · Native terminal · Linux
git cat-file -t academy-v0.0.1
git tag --points-at HEAD
git show --no-patch --format=%B academy-v0.0.1
cat CHANGELOG.mdThe inspection reports a tag object, academy-v0.0.1 at HEAD, and a tag body whose generated release section exactly matches CHANGELOG.md before its matching Released-at date.
If the object is lightweight, the tag is absent, its generated section or Released-at date differs from CHANGELOG.md, or it does not point at HEAD, stop the attempt without moving the tag. Next safe step: run Academy Check when the local evidence is exact.
This local check does not prove a remote tag, a GitHub Release, or publication.
Recognize success
Success is limited to the observed local boundary: three ordered commits (refactor, docs chore, generated changelog), the named paths, an unchanged pre-existing test file, a clean worktree, and an annotated academy-v0.0.1 tag at the attempt head. The tag body must reproduce the generated changelog section and matching Released-at date exactly. It is not a claim about a remote tag, a release page, or published software.
Check
Academy Check validates this local contract. It does not prove a remote tag, a GitHub Release, or command execution.
Check the completed U03 evidence
Run Check in a native terminal. Native-terminal commands never begin with !.
Check evaluates the prepared attempt's bounded local evidence.
You · Native terminal · Windows
$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.30\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path check U03-refactor-chore-releaseYou · Native terminal · macOS
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" check U03-refactor-chore-releaseYou · Native terminal · Linux
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" check U03-refactor-chore-releaseAcademy Check reports U03 passed after it verifies the three commits, declared target, generated changelog, annotated tag, and clean worktree.
If Check fails, preserve the failure and correct only the named local boundary. Do not add a remote tag or release record. Next safe step: rerun Check after the stated correction.
The Check result proves only the evaluated local repository facts, not a remote tag, GitHub Release, or publication.
Recover or continue
Do not destroy a failed attempt to make it look clean. Preserve the state and use Academy Reset so it archives the attempt before restoring the sealed state.
Reset a failed U03 attempt safely
Run Reset in a native terminal. Native-terminal commands never begin with !.
Reset archives an attempt before restoring the prepared state instead of erasing learner evidence.
You · Native terminal · Windows
$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.30\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path reset U03-refactor-chore-releaseYou · Native terminal · macOS
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" reset U03-refactor-chore-releaseYou · Native terminal · Linux
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" reset U03-refactor-chore-releaseAcademy Reset archives the failed U03 attempt and restores the sealed prepared state without rewriting history in place.
If Reset refuses, preserve the reported state and do not delete commits or tags by hand. Next safe step: resolve the stated reset boundary or return to Check.
Preserve the archive reference and the restored prepared branch if recovery is needed.
Understand the mechanism
The guide and its action manifest are one shared renderer contract. Every command card names who acts and where. Native terminal commands never use !. CodeArbiter commands use the selected host directly. Check can compare repository state, but it cannot infer a learner's judgment or an external release event.