Preview 0.33

P03 - Record an accepted ADR

Know before you begin

Record a decision that future contributors will need to understand: whether Workshop Queue summaries favor stable text or structured JSON. Explain the trade-off and retain who actually chose it.

Use this lesson to record an actual architectural choice with its reason, alternatives, and attribution. Prepare gives you a bounded scenario to discuss before recording the decision.

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. Commit the ADR and log first (together, or ADR before log when split). The ADR owner then appends a source-bound acceptance to .codearbiter/decisions/adr-lifecycle.jsonl in a separate final commit. That record binds the exact source commit and sealed obligations. Keep the existing ledger prefix unchanged.

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.

Why

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.

Expected result

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

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.

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.

Why

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.

Expected result

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

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.

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.

Why

Prepare establishes the verifier-owned attempt baseline and branch before the learner creates evidence.

You · Native terminal · Windows

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

You · Native terminal · macOS

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

You · Native terminal · Linux

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

Expected result

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

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.

Evidence

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

Why

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

You · Native terminal · macOS

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

You · Native terminal · Linux

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

Expected result

ADR-0003 remains occupied and the learner can identify the current log as the append-only 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.

Evidence

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.

Why

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.

Expected result

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

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.

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.

Why

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" Use the unused stem 0004-academy-lab for this exercise. Record only my confirmed decision; when I authorize acceptance, complete the current Accepted/Planned lifecycle, including sealed obligations and the separate source-bound ledger commit.

Your agent · Codex harness · All operating systems

$ca-adr "Choose the Workshop Queue summary-format boundary" Use the unused stem 0004-academy-lab for this exercise. Record only my confirmed decision; when I authorize acceptance, complete the current Accepted/Planned lifecycle, including sealed obligations and the separate source-bound ledger commit.

Your agent · Pi harness · All operating systems

/ca-adr "Choose the Workshop Queue summary-format boundary" Use the unused stem 0004-academy-lab for this exercise. Record only my confirmed decision; when I authorize acceptance, complete the current Accepted/Planned lifecycle, including sealed obligations and the separate source-bound ledger commit.

Your agent · Pi harness · All operating systems

/skill:ca-adr "Choose the Workshop Queue summary-format boundary" Use the unused stem 0004-academy-lab for this exercise. Record only my confirmed decision; when I authorize acceptance, complete the current Accepted/Planned lifecycle, including sealed obligations and the separate source-bound ledger commit.

Expected result

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

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.

Evidence

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

Complete and inspect the acceptance binding

If the ADR workflow has already committed the source and acceptance binding, inspect that result. Otherwise resume its unfinished commit steps under the same authorization; do not make a redundant commit.

Why

The shared commit gate records the approved evidence through the supported host workflow.

Your agent · Claude Code harness · All operating systems

Complete the current ADR acceptance workflow for 0004-academy-lab. Commit the accepted ADR and decision-log append through the commit gate first. Bind the exact committed ADR bytes and independently reviewed sealed obligations in adr-lifecycle.jsonl, then commit that append separately. Preserve existing ledger bytes. If already complete, inspect both commits without repeating them. Accepted/Planned does not mean implemented or verified.

Your agent · Codex harness · All operating systems

Complete the current ADR acceptance workflow for 0004-academy-lab. Commit the accepted ADR and decision-log append through the commit gate first. Bind the exact committed ADR bytes and independently reviewed sealed obligations in adr-lifecycle.jsonl, then commit that append separately. Preserve existing ledger bytes. If already complete, inspect both commits without repeating them. Accepted/Planned does not mean implemented or verified.

Your agent · Pi harness · All operating systems

Complete the current ADR acceptance workflow for 0004-academy-lab. Commit the accepted ADR and decision-log append through the commit gate first. Bind the exact committed ADR bytes and independently reviewed sealed obligations in adr-lifecycle.jsonl, then commit that append separately. Preserve existing ledger bytes. If already complete, inspect both commits without repeating them. Accepted/Planned does not mean implemented or verified.

Your agent · Pi harness · All operating systems

Complete the current ADR acceptance workflow for 0004-academy-lab. Commit the accepted ADR and decision-log append through the commit gate first. Bind the exact committed ADR bytes and independently reviewed sealed obligations in adr-lifecycle.jsonl, then commit that append separately. Preserve existing ledger bytes. If already complete, inspect both commits without repeating them. Accepted/Planned does not mean implemented or verified.

Expected result

Two or three linear commits record the ADR/log evidence followed by a separate acceptance-ledger commit. When ADR and log are split, commit the ADR first.

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.

Evidence

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 two or three commits since Prepare. The command locates the latest P03 Prepare commit, then shows the full attempt range, including the separate acceptance-ledger append. Native terminal commands never begin with !.

Why

Native Git evidence makes the narrow committed boundary visible before Check reconstructs it.

You · Native terminal · Windows

git status --short
$preparedCommit = git log --format=%H --grep='^academy: prepare P03-record-an-adr attempt [0-9][0-9]*$' -1
if (-not $preparedCommit) { throw 'P03 Prepare commit not found' }
git log --format='%h %ad %an %s' --date=short "$preparedCommit..HEAD"
git diff --name-only "$preparedCommit..HEAD"
git diff --check "$preparedCommit..HEAD"

You · Native terminal · macOS

git status --short
prepared_commit=$(git log --format=%H --grep='^academy: prepare P03-record-an-adr attempt [0-9][0-9]*$' -1)
if [ -z "$prepared_commit" ]; then
  printf '%s\n' 'P03 Prepare commit not found' >&2
else
  git log --format='%h %ad %an %s' --date=short "$prepared_commit..HEAD"
  git diff --name-only "$prepared_commit..HEAD"
  git diff --check "$prepared_commit..HEAD"
fi

You · Native terminal · Linux

git status --short
prepared_commit=$(git log --format=%H --grep='^academy: prepare P03-record-an-adr attempt [0-9][0-9]*$' -1)
if [ -z "$prepared_commit" ]; then
  printf '%s\n' 'P03 Prepare commit not found' >&2
else
  git log --format='%h %ad %an %s' --date=short "$prepared_commit..HEAD"
  git diff --name-only "$prepared_commit..HEAD"
  git diff --check "$prepared_commit..HEAD"
fi

Expected result

The worktree is clean. Two or three linear commits change only .codearbiter/decisions/0004-academy-lab.md, .codearbiter/decisions/decision-log.md, and .codearbiter/decisions/adr-lifecycle.jsonl. The ledger-only commit is last; if ADR and log were split, ADR comes first.

If that does not happen

If a path outside those three appears, the ledger is missing or mixed into a source commit, or the range contains a merge or reversed ADR/log order, preserve the evidence and use Reset. The required ledger is part of this exercise. Resolve uncommitted work before Check.

Evidence

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

Success is an Accepted/Planned ADR-0004, matching decision-log append, and source-bound acceptance ledger 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.

Why

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.33\Scripts\arbiter-academy.exe"
& $academy --repository (Resolve-Path -LiteralPath '<learner-repository>').Path check P03-record-an-adr

You · Native terminal · macOS

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

You · Native terminal · Linux

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

Expected result

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

If that does not happen

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

Evidence

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

Check proves only final-state evidence: a clean worktree; 2–3 linear commits; only ADR, log, and acceptance-ledger 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.

Why

Reset protects the failed attempt as evidence before restoring a new prepared baseline.

You · Native terminal · Windows

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

You · Native terminal · macOS

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

You · Native terminal · Linux

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

Expected result

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

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.

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, alternatives, the approved decision, and consequences. The append-only log makes it discoverable, and Check rebuilds the committed boundary from Git instead of trusting a transcript. Record an Architecture Decision and ADRs and the Decision Log explain the lifecycle.

Use this in your own project. Keep ADRs for consequential choices. Let the workflow assign the number and preserve your attribution; never let an agent invent your acceptance.

Next step

Continue with P04-review-a-dependency.

Recovery guidance