P03 - Record an accepted ADR
Choose the commands you use
Operating system
CodeArbiter host
Know before you begin
P03 is a public guided and runnable lesson in this preview. It uses the shared Markdown-plus-action-manifest renderer and the installed Academy Prepare, Check, and Reset commands. The immutable scenario, checkpoint, and action contract ID stay P03-record-an-adr.
Keep a native terminal at the clone root and one CodeArbiter harness at the same clone. Native terminal commands never begin with !; host-native CodeArbiter commands and harness requests never begin with ! either.
Academy accepts a prepared author name only when it has 1–80 Unicode scalar values. It captures %an, never echo a rejected name, and keeps no learner email. No learner email is retained, rendered, or required. The prepared decision log is an append-only byte prefix.
What you will prove
You will record ADR-0004 for the Workshop Queue summary-format boundary. The learner chooses and approves the ADR/log boundary. The agent may analyze and draft, but it cannot choose, replace, or broaden the decision.
The two allowed learner choices are stable text and structured JSON. The committed evidence is an accepted .codearbiter/decisions/0004-academy-lab.md and a matching append to .codearbiter/decisions/decision-log.md; ADR-0003 remains untouched. The permitted history is one commit or two linear commits, with the ADR before the log when split.
Prepare safely
Read the learner-owned decision boundary
Use the selected harness to establish the boundary before any drafting: the learner chooses and approves the ADR and decision-log boundary; the agent may analyze and draft but may not make that decision.
The exercise records a real architectural choice without assigning decision authority to the agent.
You · Claude Code harness · All operating systems
Read the P03 decision boundary. I choose and approve the ADR/log boundary; do not choose it for me.You · Codex harness · All operating systems
Read the P03 decision boundary. I choose and approve the ADR/log boundary; do not choose it for me.You · Pi harness · All operating systems
Read the P03 decision boundary. I choose and approve the ADR/log boundary; do not choose it for me.The learner and agent share the boundary: analysis and drafting can be delegated, but the decision and approval remain learner-owned.
If the agent selects an alternative or commits before learner approval, preserve the attempt and reset rather than treating that action as learner evidence.
Check can inspect the resulting artifacts but cannot authenticate who chose or approved them.
Keep prepared identity private
Use the selected harness to keep identity within Academy's prepared boundary. Academy records the display-safe Git author name from %an; do not paste an email address or a rejected name into the ADR, log, or chat.
The lesson needs attributable committed evidence without retaining unnecessary personal data.
You · Claude Code harness · All operating systems
Keep the prepared author identity private. Do not request, display, or record an email address.You · Codex harness · All operating systems
Keep the prepared author identity private. Do not request, display, or record an email address.You · Pi harness · All operating systems
Keep the prepared author identity private. Do not request, display, or record an email address.The ADR and log use only the prepared display-safe name, while no learner email is retained or rendered.
If the prepared name is rejected, preserve the error and retry through Academy; never echo the rejected value as evidence.
Check reads committed author metadata and artifact attribution, not a learner-supplied identity transcript.
Prepare the numbered P03 attempt
P03 is public, guided, and runnable in this preview. In a native terminal outside the checkout, replace every literal <learner-repository> in the selected command with the absolute path to the fork clone you used for P01. It is a placeholder, not a directory you can paste literally. Run the installed Academy Prepare command; do not substitute source checkout behavior.
Prepare establishes the verifier-owned attempt baseline and branch before the learner creates evidence.
You · Native terminal · Windows
$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.30\Scripts\arbiter-academy.exe"
& $academy --repository (Resolve-Path -LiteralPath '<learner-repository>').Path prepare P03-record-an-adrYou · Native terminal · macOS
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$(cd '<learner-repository>' && pwd)" prepare P03-record-an-adrYou · Native terminal · Linux
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$(cd '<learner-repository>' && pwd)" prepare P03-record-an-adrAcademy prints the prepared attempt branch and baseline without changing the decision artifacts yet.
If P03 is not guided in the installed release or Prepare fails, preserve the message and do not invent an attempt number or branch.
The prepared baseline lets Check compare the final committed ADR and append-only log state.
Do not invent an attempt number, branch, or source-checkout substitute; use the installed Academy action.
Practice the decision
Inspect the occupied decision context
In a native terminal at the prepared clone root, inspect ADR-0003 and the current decision log before drafting ADR-0004. Native terminal commands never begin with !.
The existing record establishes the occupied number and the byte prefix that P03 must preserve.
You · Native terminal · Windows
Get-Content .codearbiter\decisions\0003-local-verifier-trust-boundary.md
Get-Content .codearbiter\decisions\decision-log.mdYou · Native terminal · macOS
sed -n '1,240p' .codearbiter/decisions/0003-local-verifier-trust-boundary.md
sed -n '1,240p' .codearbiter/decisions/decision-log.mdYou · Native terminal · Linux
sed -n '1,240p' .codearbiter/decisions/0003-local-verifier-trust-boundary.md
sed -n '1,240p' .codearbiter/decisions/decision-log.mdADR-0003 remains occupied and the learner can identify the current log as the append-only prefix.
If either artifact is missing or unexpectedly edited, stop and reset to a prepared baseline; do not recreate governance history by hand.
The later log must retain the prepared decision-log bytes as its prefix.
Request analysis, then make the exact choice
Ask the agent to analyze the two alternatives and wait. The learner chooses and approves the ADR/log boundary; the agent may analyze and draft but may not select, replace, or broaden the choice.
A comparison can make consequences legible without making an architecture decision on the learner's behalf.
You · Claude Code harness · All operating systems
Compare stable text and structured JSON for Workshop Queue summaries across compatibility, automation, schema evolution, and local-first consequences. Do not choose, draft, append, stage, or commit. Wait for my exact choice.You · Claude Code harness · All operating systems
Use stable text for Workshop Queue summaries.You · Claude Code harness · All operating systems
Use structured JSON for Workshop Queue summaries.You · Codex harness · All operating systems
Compare stable text and structured JSON for Workshop Queue summaries across compatibility, automation, schema evolution, and local-first consequences. Do not choose, draft, append, stage, or commit. Wait for my exact choice.You · Codex harness · All operating systems
Use stable text for Workshop Queue summaries.You · Codex harness · All operating systems
Use structured JSON for Workshop Queue summaries.You · Pi harness · All operating systems
Compare stable text and structured JSON for Workshop Queue summaries across compatibility, automation, schema evolution, and local-first consequences. Do not choose, draft, append, stage, or commit. Wait for my exact choice.You · Pi harness · All operating systems
Use stable text for Workshop Queue summaries.You · Pi harness · All operating systems
Use structured JSON for Workshop Queue summaries.The agent presents analysis, and the learner supplies one of the two exact choice statements before any ADR or log draft exists.
If the agent chooses or writes before the learner sends one exact choice, preserve the attempt and reset instead of treating agent direction as learner evidence.
The committed decision can match the selected statement, but Check cannot prove who sent it or why.
Read the analysis, select one exact learner choice, then explicitly approve the ADR/log draft before the agent runs the ADR command. Review the draft against that choice, then explicitly approve its committed form before the agent runs the commit gate.
Run the host-native ADR command after learner approval
After the learner sends one exact choice and explicitly approves drafting the ADR/log boundary, invoke the selected host-native ADR command. The agent drafts the record; it does not decide for the learner.
The shared CodeArbiter ADR lane creates a structured record while preserving learner authority over the content.
Your agent · Claude Code harness · All operating systems
/ca:adr "Choose the Workshop Queue summary-format boundary"Your agent · Codex harness · All operating systems
$ca-adr "Choose the Workshop Queue summary-format boundary"Your agent · Pi harness · All operating systems
/ca-adr "Choose the Workshop Queue summary-format boundary"Your agent · Pi harness · All operating systems
/skill:ca-adr "Choose the Workshop Queue summary-format boundary"The agent drafts ADR-0004 and its matching log entry for the learner-approved boundary.
If the command cannot preserve the learner-owned choice or writes a different boundary, stop and reset; do not hand-edit around the ADR lane.
The host command is a drafting route, not proof that the learner approved the content.
Run the host-native commit gate after approval
After the learner reviews and explicitly approves the ADR/log content, invoke the selected host-native commit gate. Do not use a raw git commit as a substitute.
The shared commit gate records the approved evidence through the supported host workflow.
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-commitOne commit or two linear commits record only the approved ADR/log evidence, with ADR before log when split.
If the gate blocks or the staged boundary includes another path, preserve the finding and reset; do not amend or force a commit.
Git can show the resulting commit range and changed paths, but not the learner's approval process.
Recognize success
Confirm native evidence at the clone root
In a native terminal at the clone root, inspect the clean worktree, the latest one or two commits, and the ADR/log paths. Native terminal commands never begin with !.
Native Git evidence makes the narrow committed boundary visible before Check reconstructs it.
You · Native terminal · Windows
git status --short
git log --format='%h %ad %an %s' --date=short -2
git diff --name-only HEAD~2..HEAD
git diff --check HEAD~2..HEADYou · Native terminal · macOS
git status --short
git log --format='%h %ad %an %s' --date=short -2
git diff --name-only HEAD~2..HEAD
git diff --check HEAD~2..HEADYou · Native terminal · Linux
git status --short
git log --format='%h %ad %an %s' --date=short -2
git diff --name-only HEAD~2..HEAD
git diff --check HEAD~2..HEADThe worktree is clean and the visible range contains only the ADR and decision-log paths in the permitted ordering.
If another path, a merge, an uncommitted change, or reversed ADR/log order appears, preserve the evidence and reset; do not rewrite the attempt.
The native output exposes the same narrow final-state facts that Check can validate.
Success is an accepted ADR-0004 and matching decision-log append on the prepared branch. The record carries the learner-approved choice, attribution, alternatives, consequences, and risks; the worktree is clean.
Check
Run installed Academy Check
P03 is public in this preview. Run the installed Academy Check command from a native terminal.
Check evaluates the committed evidence against the immutable P03 checkpoint rather than trusting a transcript.
You · Native terminal · Windows
$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.30\Scripts\arbiter-academy.exe"
& $academy --repository (Resolve-Path -LiteralPath '<learner-repository>').Path check P03-record-an-adrYou · Native terminal · macOS
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$(cd '<learner-repository>' && pwd)" check P03-record-an-adrYou · Native terminal · Linux
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$(cd '<learner-repository>' && pwd)" check P03-record-an-adrCheck reports whether the prepared evidence satisfies the immutable P03 checkpoint.
If Check fails, preserve the predicate output and reset instead of amending, rebasing, or fabricating history.
Check evaluates final committed artifacts and Git state, not a claimed live process.
Check proves only final-state evidence: a clean worktree; 1–2 linear commits; only ADR/log paths; ADR before log if split; commit date/name; artifact format/choice; and the append-only log prefix. It cannot prove human acceptance, host command use, reasoning quality, chronology, or independent review.
Recover or continue
If evidence is wrong or Check names a failed predicate, preserve the attempt. Do not amend, rebase, overwrite ADR-0003, rewrite the log prefix, or manufacture a generic governance event.
Preserve the failed attempt and reset
P03 Reset is public in this preview. Run the installed Academy command from a native terminal only after preserving the failed evidence.
Reset protects the failed attempt as evidence before restoring a new prepared baseline.
You · Native terminal · Windows
$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.30\Scripts\arbiter-academy.exe"
& $academy --repository (Resolve-Path -LiteralPath '<learner-repository>').Path reset P03-record-an-adrYou · Native terminal · macOS
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$(cd '<learner-repository>' && pwd)" reset P03-record-an-adrYou · Native terminal · Linux
academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$(cd '<learner-repository>' && pwd)" reset P03-record-an-adrAcademy archives the failed attempt and restores a fresh prepared baseline.
If Reset is unavailable or fails, preserve the current attempt and do not delete the ADR, rewrite the log, or discard Git evidence.
The archived attempt retains the evidence that explains why its checkpoint did not pass.
Continue to P04, the next public guided Academy lesson in this preview.
Hint 1
Read ADR-0003 before drafting. Its occupied number and verifier-trust boundary explain why this exercise allocates ADR-0004.
Hint 2
The record needs consequences: explain what callers, automation, compatibility, and future schema evolution gain or lose under the learner-approved choice.
Hint 3
Check reconstructs committed facts. It can reject mismatched or rewritten artifacts, but it cannot recover deliberation or prove human approval.
Understand the mechanism
An ADR makes a consequential choice durable: context explains why it matters, alternatives preserve the trade-off, the decision records the approved boundary, and consequences guide future maintainers. The append-only log makes that lifecycle discoverable; Check reconstructs the committed boundary from Git rather than trusting a transcript.