Record an accepted ADR

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

1. 1

   You

   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.

   Why this matters: The exercise records a real architectural choice without assigning decision authority to the agent.

   Any OS · Claude Code

   Read the P03 decision boundary. I choose and approve the ADR/log boundary; do not choose it for me.

   Copy

   Any OS · Codex

   Read the P03 decision boundary. I choose and approve the ADR/log boundary; do not choose it for me.

   Copy

   Any OS · Pi

   Read the P03 decision boundary. I choose and approve the ADR/log boundary; do not choose it for me.

   Copy

   Expected result

   The learner and agent share the boundary: analysis and drafting can be delegated, but the decision and approval remain learner-owned.

   Evidence

   Check can inspect the resulting artifacts but cannot authenticate who chose or approved them.

   If that does not happen

   If the agent selects an alternative or commits before learner approval, preserve the attempt and reset rather than treating that action as learner evidence.

1. 2

   You

   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.

   Why this matters: The lesson needs attributable committed evidence without retaining unnecessary personal data.

   Any OS · Claude Code

   Keep the prepared author identity private. Do not request, display, or record an email address.

   Copy

   Any OS · Codex

   Keep the prepared author identity private. Do not request, display, or record an email address.

   Copy

   Any OS · Pi

   Keep the prepared author identity private. Do not request, display, or record an email address.

   Copy

   Expected result

   The ADR and log use only the prepared display-safe name, while no learner email is retained or rendered.

   Evidence

   Check reads committed author metadata and artifact attribution, not a learner-supplied identity transcript.

   If that does not happen

   If the prepared name is rejected, preserve the error and retry through Academy; never echo the rejected value as evidence.

1. 3

   You

   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.

   Why this matters: Prepare establishes the verifier-owned attempt baseline and branch before the learner creates evidence.

   Windows

   $academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.32\Scripts\arbiter-academy.exe"
   & $academy --repository (Resolve-Path -LiteralPath '<learner-repository>').Path prepare P03-record-an-adr

   Copy

   macOS

   academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.32/bin/arbiter-academy"
   "$academy" --repository "$(cd '<learner-repository>' && pwd)" prepare P03-record-an-adr

   Copy

   Linux

   academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.32/bin/arbiter-academy"
   "$academy" --repository "$(cd '<learner-repository>' && pwd)" prepare P03-record-an-adr

   Copy

   Expected result

   Academy prints the prepared attempt branch and baseline without changing the decision artifacts yet.

   Evidence

   The prepared baseline lets Check compare the final committed ADR and append-only log state.

   If that does not happen

   If P03 is not guided in the installed release or Prepare fails, preserve the message and do not invent an attempt number or branch.

Do not invent an attempt number, branch, or source-checkout substitute; use the installed Academy action.

Practice the decision

1. 4

   You

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

   Why this matters: The existing record establishes the occupied number and the byte prefix that P03 must preserve.

   Windows

   Get-Content .codearbiter\decisions\0003-local-verifier-trust-boundary.md
   Get-Content .codearbiter\decisions\decision-log.md

   Copy

   macOS

   sed -n '1,240p' .codearbiter/decisions/0003-local-verifier-trust-boundary.md
   sed -n '1,240p' .codearbiter/decisions/decision-log.md

   Copy

   Linux

   sed -n '1,240p' .codearbiter/decisions/0003-local-verifier-trust-boundary.md
   sed -n '1,240p' .codearbiter/decisions/decision-log.md

   Copy

   Expected result

   ADR-0003 remains occupied and the learner can identify the current log as the append-only prefix.

   Evidence

   The later log must retain the prepared decision-log bytes as its prefix.

   If that does not happen

   If either artifact is missing or unexpectedly edited, stop and reset to a prepared baseline; do not recreate governance history by hand.

1. 5

   You

   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.

   Why this matters: A comparison can make consequences legible without making an architecture decision on the learner's behalf.

   Any OS · Claude Code

   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.

   Copy

   Any OS · Claude Code

   Use stable text for Workshop Queue summaries.

   Copy

   Any OS · Claude Code

   Use structured JSON for Workshop Queue summaries.

   Copy

   Any OS · Codex

   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.

   Copy

   Any OS · Codex

   Use stable text for Workshop Queue summaries.

   Copy

   Any OS · Codex

   Use structured JSON for Workshop Queue summaries.

   Copy

   Any OS · Pi

   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.

   Copy

   Any OS · Pi

   Use stable text for Workshop Queue summaries.

   Copy

   Any OS · Pi

   Use structured JSON for Workshop Queue summaries.

   Copy

   Expected result

   The agent presents analysis, and the learner supplies one of the two exact choice statements before any ADR or log draft exists.

   Evidence

   The committed decision can match the selected statement, but Check cannot prove who sent it or why.

   If that does not happen

   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.

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.

1. 6

   Your host

   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.

   Why this matters: The shared codeArbiter ADR lane creates a structured record while preserving learner authority over the content.

   Any OS · Claude Code

   /ca:adr "Choose the Workshop Queue summary-format boundary"

   Copy

   Any OS · Codex

   $ca-adr "Choose the Workshop Queue summary-format boundary"

   Copy

   Any OS · Pi

   /ca-adr "Choose the Workshop Queue summary-format boundary"

   Copy

   Any OS · Pi

   /skill:ca-adr "Choose the Workshop Queue summary-format boundary"

   Copy

   Expected result

   The agent drafts ADR-0004 and its matching log entry for the learner-approved boundary.

   Evidence

   The host command is a drafting route, not proof that the learner approved the content.

   If that does not happen

   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.

1. 7

   Your host

   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.

   Why this matters: The shared commit gate records the approved evidence through the supported host workflow.

   Any OS · Claude Code

   /ca:commit

   Copy

   Any OS · Codex

   $ca-commit

   Copy

   Any OS · Pi

   /ca-commit

   Copy

   Any OS · Pi

   /skill:ca-commit

   Copy

   Expected result

   One commit or two linear commits record only the approved ADR/log evidence, with ADR before log when split.

   Evidence

   Git can show the resulting commit range and changed paths, but not the learner's approval process.

   If that does not happen

   If the gate blocks or the staged boundary includes another path, preserve the finding and reset; do not amend or force a commit.

Recognize success

1. 8

   You

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

   Why this matters: Native Git evidence makes the narrow committed boundary visible before Check reconstructs it.

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

   Copy

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

   Copy

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

   Copy

   Expected result

   The worktree is clean and the visible range contains only the ADR and decision-log paths in the permitted ordering.

   Evidence

   The native output exposes the same narrow final-state facts that Check can validate.

   If that does not happen

   If another path, a merge, an uncommitted change, or reversed ADR/log order appears, preserve the evidence and reset; do not rewrite the attempt.

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

1. 9

   You

   Run installed Academy Check

   P03 is public in this preview. Run the installed Academy Check command from a native terminal.

   Why this matters: Check evaluates the committed evidence against the immutable P03 checkpoint rather than trusting a transcript.

   Windows

   $academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.32\Scripts\arbiter-academy.exe"
   & $academy --repository (Resolve-Path -LiteralPath '<learner-repository>').Path check P03-record-an-adr

   Copy

   macOS

   academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.32/bin/arbiter-academy"
   "$academy" --repository "$(cd '<learner-repository>' && pwd)" check P03-record-an-adr

   Copy

   Linux

   academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.32/bin/arbiter-academy"
   "$academy" --repository "$(cd '<learner-repository>' && pwd)" check P03-record-an-adr

   Copy

   Expected result

   Check reports whether the prepared evidence satisfies the immutable P03 checkpoint.

   Evidence

   Check evaluates final committed artifacts and Git state, not a claimed live process.

   If that does not happen

   If Check fails, preserve the predicate output and reset instead of amending, rebasing, or fabricating history.

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.

1. 10

   You

   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.

   Why this matters: Reset protects the failed attempt as evidence before restoring a new prepared baseline.

   Windows

   $academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.32\Scripts\arbiter-academy.exe"
   & $academy --repository (Resolve-Path -LiteralPath '<learner-repository>').Path reset P03-record-an-adr

   Copy

   macOS

   academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.32/bin/arbiter-academy"
   "$academy" --repository "$(cd '<learner-repository>' && pwd)" reset P03-record-an-adr

   Copy

   Linux

   academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.32/bin/arbiter-academy"
   "$academy" --repository "$(cd '<learner-repository>' && pwd)" reset P03-record-an-adr

   Copy

   Expected result

   Academy archives the failed attempt and restores a fresh prepared baseline.

   Evidence

   The archived attempt retains the evidence that explains why its checkpoint did not pass.

   If that does not happen

   If Reset is unavailable or fails, preserve the current attempt and do not delete the ADR, rewrite the log, or discard Git evidence.

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.