U04: Initialize a greenfield and a brownfield project

Know before you begin

U04 is a guided Preview 0.30 lesson. It prepares two separate child repositories beneath the Academy attempt root. The Academy root controls the attempt and stores the final binding report; it is not a CodeArbiter project for this lesson.

You · Active CodeArbiter harness · All operating systems

Confirm that this is the Academy attempt root. U04 creates two child repositories under .academy/workspaces/; do not initialize CodeArbiter in the Academy root.

Why

It distinguishes the controller repository from the two child repositories before any tool writes state.

Expected result

You know the Academy root controls the attempt and the two child paths are .academy/workspaces/U04-greenfield and .academy/workspaces/U04-brownfield. Next safe step: prepare attempt.

If that does not happen

If you have already initialized CodeArbiter in the Academy root, preserve the status and stop; do not delete or rewrite a repository to hide the mistake.

Evidence

Preserve the Academy-root path and the two child paths; no child repository exists yet.

What you will prove

U04 keeps the Academy root as the attempt controller and final-report repository. Do not initialize a child project in the Academy root. Host-native commands act on the folder visible in that host. A terminal cd does not switch it, and neither native-terminal nor CodeArbiter commands use !.

Greenfield will use ca-init, then ca-decompose, which generates the three exact reconciliation inputs under .codearbiter/plans/. After learner review, greenfield alone will use ca-reconcile, then ca-adr drafts the learner-attributed decision for the learner to review and explicitly accept. Reconciliation does not author ADRs or advance their status. Brownfield will use ca-init, then ca-create-context; the accepted walkthrough must use ca-create-context on the brownfield and must not use ca-decompose on the brownfield. The real brownfield route does not create the three ca-reconcile plan inputs, so this lesson does not invent them or run brownfield reconciliation.

Each child follows the same repository boundary: inspect generated changes, explicitly stage only those changes, review the cached diff, run host-native ca-commit while visibly rooted at that child, and prove clean status. An unresolved [CONFIRM-NN] stops the attempt.

Prepare safely

Prepare creates the greenfield and brownfield child repositories and switches the Academy repository to the dedicated attempt branch. Do not make either child yourself.

From the clean Academy root, run installed Academy Prepare. Native commands never begin with !.

Why

Prepare is the only supported way to create the bounded attempt and its two clean child repositories.

You · Native terminal · Windows

$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.30\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path prepare U04-initialize-projects

You · Native terminal · macOS

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" prepare U04-initialize-projects

You · Native terminal · Linux

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" prepare U04-initialize-projects

Expected result

Prepare switches to academy/U04-initialize-projects/<attempt> and creates clean .academy/workspaces/U04-greenfield and .academy/workspaces/U04-brownfield child repositories. Next safe step: inspect root.

If that does not happen

If Prepare reports an occupied child target or another setup error, preserve its output and correct that named boundary; do not create, delete, or initialize a child path by hand.

Evidence

Preserve Prepare output, the attempt branch, and empty status from both prepared child repositories.

Inspect the two prepared child repositories. Do not initialize the Academy root.

Why

It proves the prepared paths are separate children rather than accidental work in the Academy root.

You · Native terminal · Windows

Get-ChildItem .academy\workspaces\U04-greenfield, .academy\workspaces\U04-brownfield

You · Native terminal · macOS

ls -la .academy/workspaces/U04-greenfield .academy/workspaces/U04-brownfield

You · Native terminal · Linux

ls -la .academy/workspaces/U04-greenfield .academy/workspaces/U04-brownfield

Expected result

The listing shows separate U04-greenfield and U04-brownfield directories under .academy/workspaces; neither is the Academy root. Next safe step: inspect greenfield.

If that does not happen

If either child is missing, duplicated, or outside .academy/workspaces, stop and preserve the listing plus all three repository statuses; do not initialize a substitute directory by hand.

Evidence

Preserve the two-path listing and the empty prepared-child statuses so the later report remains bound to the intended repositories.

Practice

Complete and commit greenfield before opening brownfield:

You · Active CodeArbiter harness · All operating systems

Use Open Folder or the workspace switcher to visibly root the host at .academy/workspaces/U04-greenfield. A terminal cd does not change the host root.

Why

The visible host root prevents a greenfield command from being sent to the parent or the brownfield child.

Expected result

The host visibly names .academy/workspaces/U04-greenfield as its project root; merely changing a terminal directory is not sufficient. Next safe step: run greenfield init.

If that does not happen

If the host still shows the Academy root or U04-brownfield, do not invoke CodeArbiter; reopen U04-greenfield with Open Folder or the workspace switcher first.

Evidence

Preserve the host's visible root label or breadcrumb naming U04-greenfield; Check can verify repository bytes later, but cannot prove which folder the host displayed.

Only while visibly rooted at .academy/workspaces/U04-greenfield, run ca-init; a terminal cd does not change the host root.

Why

Initialization belongs in the greenfield child so its governance state starts from the real plugin entry point.

Your agent · Claude Code harness · All operating systems

/ca:init

Your agent · Codex harness · All operating systems

$ca-init

Your agent · Pi harness · All operating systems

/ca-init

Your agent · Pi harness · All operating systems

/skill:ca-init

Expected result

ca-init scaffolds an uncommitted .codearbiter directory inside U04-greenfield only; the Academy root and brownfield remain untouched. Next safe step: run greenfield decompose.

If that does not happen

If ca-init ran against another visible root, stop and preserve its output and every affected git status; do not commit or conceal the misplaced initialization.

Evidence

Preserve ca-init output and U04-greenfield git status showing the new .codearbiter paths before decomposition.

Only while visibly rooted at .academy/workspaces/U04-greenfield, run ca-decompose; a terminal cd does not change the host root.

Why

Decomposition creates the greenfield planning artifacts that reconciliation will evaluate.

Your agent · Claude Code harness · All operating systems

/ca:decompose

Your agent · Codex harness · All operating systems

$ca-decompose

Your agent · Pi harness · All operating systems

/ca-decompose

Your agent · Pi harness · All operating systems

/skill:ca-decompose

Expected result

U04-greenfield now contains .codearbiter/plans/01-architecture-breakdown.md, .codearbiter/plans/02-phased-build-plan.md, and .codearbiter/plans/03-task-backlog.md. Next safe step: read greenfield plans.

If that does not happen

If ca-decompose stops for input or any named plan is missing, preserve the transcript and partial files; continue the decompose interview in U04-greenfield instead of inventing a plan or switching repositories.

Evidence

Preserve the ca-decompose transcript and all three generated plan files; Check later reads these exact committed paths.

Read .academy/workspaces/U04-greenfield/.codearbiter/plans/01-architecture-breakdown.md, .academy/workspaces/U04-greenfield/.codearbiter/plans/02-phased-build-plan.md, and .academy/workspaces/U04-greenfield/.codearbiter/plans/03-task-backlog.md.

Why

Reading all three plans makes the later reconciliation a deliberate decision rather than an opaque command.

You · Native terminal · Windows

Get-Content .academy\workspaces\U04-greenfield\.codearbiter\plans\01-architecture-breakdown.md, .academy\workspaces\U04-greenfield\.codearbiter\plans\02-phased-build-plan.md, .academy\workspaces\U04-greenfield\.codearbiter\plans\03-task-backlog.md

You · Native terminal · macOS

cat .academy/workspaces/U04-greenfield/.codearbiter/plans/01-architecture-breakdown.md .academy/workspaces/U04-greenfield/.codearbiter/plans/02-phased-build-plan.md .academy/workspaces/U04-greenfield/.codearbiter/plans/03-task-backlog.md

You · Native terminal · Linux

cat .academy/workspaces/U04-greenfield/.codearbiter/plans/01-architecture-breakdown.md .academy/workspaces/U04-greenfield/.codearbiter/plans/02-phased-build-plan.md .academy/workspaces/U04-greenfield/.codearbiter/plans/03-task-backlog.md

Expected result

All three plan files are readable and distinguish architecture, phased delivery, and task backlog decisions that must be settled before reconciliation. Next safe step: choose greenfield reconciliation.

If that does not happen

If a file cannot be read or contains incomplete generated content, stop and return to ca-decompose in the visibly rooted greenfield host; do not repair generated structure from the Academy root.

Evidence

Preserve the three plan contents and a short list of every [CONFIRM-NN] or design choice that needs a learner decision.

You · Active CodeArbiter harness · All operating systems

Review the three greenfield plan inputs, resolve decisions or stop on [CONFIRM-NN], then use Open Folder or the workspace switcher to visibly return to .academy/workspaces/U04-greenfield. A terminal cd does not change the host root.

Why

Reconciliation must use learner-resolved decisions and stop on unresolved confirmation markers.

Expected result

Each plan decision has an explicit learner answer, no unresolved [CONFIRM-NN] remains, and the host is visibly rooted at U04-greenfield. Next safe step: run greenfield reconcile.

If that does not happen

If any decision is unclear or [CONFIRM-NN] remains, stop before ca-reconcile; preserve the question and answer it explicitly in the greenfield conversation.

Evidence

Preserve the learner-attributed decisions and the resolved three plan files; this is judgment evidence that Check cannot infer from command invocation alone.

Only after the three plans and learner decisions exist, while visibly rooted at .academy/workspaces/U04-greenfield, run ca-reconcile; a terminal cd does not change the host root.

Why

Running reconcile only after its inputs exist keeps the plan-to-decision flow truthful.

Your agent · Claude Code harness · All operating systems

/ca:reconcile

Your agent · Codex harness · All operating systems

$ca-reconcile

Your agent · Pi harness · All operating systems

/ca-reconcile

Your agent · Pi harness · All operating systems

/skill:ca-reconcile

Expected result

ca-reconcile records the reviewed greenfield governance with no unresolved [CONFIRM-NN]. Next safe step: record greenfield ADR.

If that does not happen

If reconciliation reports an unresolved variance or confirmation, preserve the transcript and stop; return to the named greenfield decision instead of staging partial governance.

Evidence

Preserve ca-reconcile output and the final plan and governance files that will be reviewed in the unstaged diff.

While visibly rooted at .academy/workspaces/U04-greenfield, state the exact learner-selected greenfield decision and explicit learner attribution, then invoke ca-adr. The host assigns the number and writes the proposed ADR; do not ask ca-reconcile to author it.

Why

ca-adr, not ca-reconcile, owns an accepted Architecture Decision Record and requires explicit learner attribution.

Your agent · Claude Code harness · All operating systems

/ca:adr Use local storage for U04 greenfield state

Your agent · Codex harness · All operating systems

$ca-adr Use local storage for U04 greenfield state

Your agent · Pi harness · All operating systems

/ca-adr Use local storage for U04 greenfield state

Your agent · Pi harness · All operating systems

/skill:ca-adr Use local storage for U04 greenfield state

Expected result

ca-adr writes the next numbered proposed greenfield ADR under .codearbiter/decisions/ with the learner-attributed decision. Next safe step: accept greenfield ADR.

If that does not happen

If the decision or attribution is not exact, stop before accepting the ADR. Correct the learner decision in the greenfield conversation; do not ask ca-reconcile to create or revise the ADR.

Evidence

Preserve the proposed ADR path and learner-attributed decision with the reconciled plan and governance files.

You · Active CodeArbiter harness · All operating systems

Review the proposed greenfield ADR in the active ca-adr conversation. Only after confirming its decision and attribution, explicitly accept that ADR; the host must not advance its status on its own.

Why

ADR status transitions are an explicit learner decision, not an automatic result of reconciliation or drafting.

Expected result

The reviewed learner-attributed ADR is accepted under .codearbiter/decisions/. Next safe step: inspect greenfield changes.

If that does not happen

If the ADR title, decision, or attribution is wrong, leave it proposed and correct it with the learner before accepting. Do not silently edit or auto-advance its status.

Evidence

The accepted ADR path, status, decision, and explicit learner attribution.

Inspect greenfield status and unstaged governance diff before staging.

Why

An unstaged inspection lets the learner see exactly what the greenfield plugin flow produced.

You · Native terminal · Windows

git -C .academy\workspaces\U04-greenfield status --short
git -C .academy\workspaces\U04-greenfield diff -- .codearbiter .gitignore

You · Native terminal · macOS

git -C .academy/workspaces/U04-greenfield status --short
git -C .academy/workspaces/U04-greenfield diff -- .codearbiter .gitignore

You · Native terminal · Linux

git -C .academy/workspaces/U04-greenfield status --short
git -C .academy/workspaces/U04-greenfield diff -- .codearbiter .gitignore

Expected result

Greenfield status and the unstaged diff show only the intended .codearbiter governance and generated .gitignore change; nothing is staged yet. Next safe step: stage greenfield changes.

If that does not happen

If status names unrelated or unexpected paths, preserve the full status and diff and stop; identify their owner before altering, staging, or discarding them.

Evidence

Preserve the pre-stage status and full .codearbiter/.gitignore diff as the review record for the greenfield commit boundary.

After review, stage only greenfield generated governance changes.

Why

Selective staging keeps generated greenfield governance files separate from unrelated parent or child work.

You · Native terminal · Windows

git -C .academy\workspaces\U04-greenfield add -- .codearbiter .gitignore
git -C .academy\workspaces\U04-greenfield diff --cached --name-only

You · Native terminal · macOS

git -C .academy/workspaces/U04-greenfield add -- .codearbiter .gitignore
git -C .academy/workspaces/U04-greenfield diff --cached --name-only

You · Native terminal · Linux

git -C .academy/workspaces/U04-greenfield add -- .codearbiter .gitignore
git -C .academy/workspaces/U04-greenfield diff --cached --name-only

Expected result

Only reviewed U04-greenfield .codearbiter and .gitignore changes are staged, and diff --cached --name-only prints those exact paths. Next safe step: review greenfield commit boundary.

If that does not happen

If an unexpected path is staged, preserve the cached name list, unstage only that path, and return to the unstaged review; do not run ca-commit with a mixed boundary.

Evidence

Preserve the cached name list proving the greenfield index contains only generated governance and its .gitignore boundary.

Review the full cached diff, then use Open Folder or the workspace switcher to keep the host visibly rooted at .academy/workspaces/U04-greenfield.

Why

Cached-diff review proves the exact greenfield commit boundary before the commit gate runs.

You · Native terminal · Windows

git -C .academy\workspaces\U04-greenfield diff --cached --check
git -C .academy\workspaces\U04-greenfield diff --cached

You · Native terminal · macOS

git -C .academy/workspaces/U04-greenfield diff --cached --check
git -C .academy/workspaces/U04-greenfield diff --cached

You · Native terminal · Linux

git -C .academy/workspaces/U04-greenfield diff --cached --check
git -C .academy/workspaces/U04-greenfield diff --cached

Expected result

diff --cached --check reports no whitespace errors, and the full cached diff is the exact greenfield governance the learner intends to commit. Next safe step: run greenfield commit gate.

If that does not happen

If the cached check reports an error or the diff contains an unapproved change, preserve the output and stop; correct and restage the greenfield file before requesting ca-commit.

Evidence

Preserve the clean cached-check output and reviewed cached diff; together they define the exact bytes offered to the greenfield commit gate.

Only after learner review while visibly rooted at .academy/workspaces/U04-greenfield, run ca-commit; a terminal cd does not change the host root.

Why

The child-local commit gate records the reviewed greenfield governance change in its own history.

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

ca-commit creates a new child commit in U04-greenfield containing the reviewed staged governance and does not commit either the parent or brownfield. Next safe step: confirm greenfield clean.

If that does not happen

If the gate stops or requests remediation, preserve its findings and the staged diff; remediate in U04-greenfield and rerun ca-commit instead of bypassing the gate or using raw git commit.

Evidence

Preserve the successful ca-commit transcript and resulting greenfield commit hash; the later binding must use this committed HEAD.

After greenfield ca-commit succeeds, confirm its status is empty.

Why

A clean greenfield status is required before its committed facts can bind the parent report.

You · Native terminal · Windows

git -C .academy\workspaces\U04-greenfield status --short

You · Native terminal · macOS

git -C .academy/workspaces/U04-greenfield status --short

You · Native terminal · Linux

git -C .academy/workspaces/U04-greenfield status --short

Expected result

git status --short prints nothing, so the U04-greenfield working tree is clean after its new child commit. Next safe step: inspect brownfield.

If that does not happen

If any greenfield path is printed, preserve the status and stop before opening brownfield; return to the greenfield review or commit gate that left it dirty.

Evidence

Preserve the empty status output and the committed HEAD from the preceding gate; the parent report binds that committed HEAD, tree, and context.

Then create and commit the real brownfield context without synthetic plan documents:

You · Active CodeArbiter harness · All operating systems

After greenfield is committed and clean, use Open Folder or the workspace switcher to visibly root the host at .academy/workspaces/U04-brownfield. A terminal cd does not change the host root.

Why

Switching deliberately to brownfield keeps its existing-source workflow distinct from greenfield decomposition.

Expected result

The greenfield remains committed and clean while the host visibly names .academy/workspaces/U04-brownfield as its new project root. Next safe step: run brownfield init.

If that does not happen

If greenfield is dirty or the host displays any root other than U04-brownfield, stop; preserve both statuses and switch folders visibly before invoking CodeArbiter.

Evidence

Preserve the clean greenfield status and the host's visible U04-brownfield root label so the route transition is auditable.

Only while visibly rooted at .academy/workspaces/U04-brownfield, run ca-init; a terminal cd does not change the host root.

Why

Brownfield initialization starts governance in the existing child, never in the Academy root.

Your agent · Claude Code harness · All operating systems

/ca:init

Your agent · Codex harness · All operating systems

$ca-init

Your agent · Pi harness · All operating systems

/ca-init

Your agent · Pi harness · All operating systems

/skill:ca-init

Expected result

ca-init scaffolds an uncommitted .codearbiter directory inside U04-brownfield only while preserving its existing source files. Next safe step: run brownfield create context.

If that does not happen

If ca-init targets another root or changes existing brownfield source, stop and preserve the transcript and status; do not commit, reset, or mask those changes.

Evidence

Preserve ca-init output and brownfield status showing new governance beside, not replacing, the prepared source.

Only while visibly rooted at .academy/workspaces/U04-brownfield, run ca-create-context; a terminal cd does not change the host root. Keep this route bound to existing source and do not use ca-decompose on the brownfield. ca-create-context does not create the three ca-reconcile plan inputs.

Why

Create-context is the genuine brownfield route and does not invent greenfield plan artifacts.

Your agent · Claude Code harness · All operating systems

/ca:create-context

Your agent · Codex harness · All operating systems

$ca-create-context

Your agent · Pi harness · All operating systems

/ca-create-context

Your agent · Pi harness · All operating systems

/skill:ca-create-context

Expected result

ca-create-context derives brownfield governance from existing source, including .codearbiter/CONTEXT.md, and creates none of the three greenfield reconciliation plan files. Next safe step: inspect brownfield changes.

If that does not happen

If the host proposes ca-decompose, synthetic reconciliation plans, or context unrelated to the existing source, stop and preserve the transcript; rerun ca-create-context only from the visible brownfield root.

Evidence

Preserve the ca-create-context transcript, generated root governance paths, and absence of .codearbiter/plans/01-architecture-breakdown.md, 02-phased-build-plan.md, and 03-task-backlog.md.

Inspect brownfield status and unstaged governance diff before staging.

Why

Inspecting the brownfield diff exposes the exact context artifacts before they become committed evidence.

You · Native terminal · Windows

git -C .academy\workspaces\U04-brownfield status --short
git -C .academy\workspaces\U04-brownfield diff -- .codearbiter

You · Native terminal · macOS

git -C .academy/workspaces/U04-brownfield status --short
git -C .academy/workspaces/U04-brownfield diff -- .codearbiter

You · Native terminal · Linux

git -C .academy/workspaces/U04-brownfield status --short
git -C .academy/workspaces/U04-brownfield diff -- .codearbiter

Expected result

Brownfield status and the unstaged diff show only intended .codearbiter context derived from the prepared source; existing source is unchanged and nothing is staged yet. Next safe step: stage brownfield changes.

If that does not happen

If status names source edits, reconciliation plans, or unrelated paths, preserve the full status and diff and stop; do not stage or discard them as generated context.

Evidence

Preserve the pre-stage brownfield status and full .codearbiter diff as the review record for the context-creation boundary.

After review, stage only brownfield generated governance changes.

Why

Selective staging confines the brownfield commit to generated governance state.

You · Native terminal · Windows

git -C .academy\workspaces\U04-brownfield add -- .codearbiter
git -C .academy\workspaces\U04-brownfield diff --cached --name-only

You · Native terminal · macOS

git -C .academy/workspaces/U04-brownfield add -- .codearbiter
git -C .academy/workspaces/U04-brownfield diff --cached --name-only

You · Native terminal · Linux

git -C .academy/workspaces/U04-brownfield add -- .codearbiter
git -C .academy/workspaces/U04-brownfield diff --cached --name-only

Expected result

Only reviewed U04-brownfield .codearbiter changes are staged, and diff --cached --name-only prints those exact governance paths. Next safe step: review brownfield commit boundary.

If that does not happen

If an existing source file or any unexpected path is staged, preserve the cached name list, unstage only that path, and return to the brownfield unstaged review.

Evidence

Preserve the cached name list proving the brownfield index contains only context-creation governance.

Review the full cached diff, then use Open Folder or the workspace switcher to keep the host visibly rooted at .academy/workspaces/U04-brownfield.

Why

Cached-diff review catches an incorrect brownfield boundary before a durable child commit.

You · Native terminal · Windows

git -C .academy\workspaces\U04-brownfield diff --cached --check
git -C .academy\workspaces\U04-brownfield diff --cached

You · Native terminal · macOS

git -C .academy/workspaces/U04-brownfield diff --cached --check
git -C .academy/workspaces/U04-brownfield diff --cached

You · Native terminal · Linux

git -C .academy/workspaces/U04-brownfield diff --cached --check
git -C .academy/workspaces/U04-brownfield diff --cached

Expected result

diff --cached --check reports no whitespace errors, and the full cached diff is the exact brownfield governance the learner intends to commit. Next safe step: run brownfield commit gate.

If that does not happen

If the cached check reports an error or the diff contains source edits, plans, or another unapproved change, preserve the output and stop; correct the brownfield index before ca-commit.

Evidence

Preserve the clean cached-check output and reviewed cached diff; together they define the exact bytes offered to the brownfield commit gate.

Only after learner review while visibly rooted at .academy/workspaces/U04-brownfield, run ca-commit; a terminal cd does not change the host root.

Why

The brownfield child must pass its own commit gate so its history is independently verifiable.

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

ca-commit creates a new child commit in U04-brownfield containing the reviewed staged context and does not commit either the parent or greenfield. Next safe step: confirm brownfield clean.

If that does not happen

If the gate stops or requests remediation, preserve its findings and the staged diff; remediate in U04-brownfield and rerun ca-commit instead of bypassing it or using raw git commit.

Evidence

Preserve the successful ca-commit transcript and resulting brownfield commit hash; the later binding must use this committed HEAD.

After brownfield ca-commit succeeds, confirm its status is empty.

Why

A clean brownfield status proves no uncommitted state is hidden behind the parent binding.

You · Native terminal · Windows

git -C .academy\workspaces\U04-brownfield status --short

You · Native terminal · macOS

git -C .academy/workspaces/U04-brownfield status --short

You · Native terminal · Linux

git -C .academy/workspaces/U04-brownfield status --short

Expected result

git status --short prints nothing, so the U04-brownfield working tree is clean after its new child commit. Next safe step: inspect project evidence.

If that does not happen

If any brownfield path is printed, preserve the status and stop before binding; return to the brownfield review or commit gate that left it dirty.

Evidence

Preserve the empty status output and the committed HEAD from the preceding gate; the parent report binds that committed HEAD, tree, and context.

Only after both child commits are clean may the Academy parent bind them. The canonical writer derives the report from committed child state, so no learner or agent has to guess headings, labels, field order, or terminal newline.

Only after both child ca-commit gates succeed and both statuses are empty, inspect committed heads, trees, context digests, and statuses.

Why

The parent report may bind only committed child heads and trees, so inspect those immutable facts first.

You · Native terminal · Windows

git -C .academy\workspaces\U04-greenfield status --short
git -C .academy\workspaces\U04-brownfield status --short
git -C .academy\workspaces\U04-greenfield rev-parse HEAD HEAD^{tree}
git -C .academy\workspaces\U04-brownfield rev-parse HEAD HEAD^{tree}
(Get-FileHash .academy\workspaces\U04-greenfield\.codearbiter\CONTEXT.md -Algorithm SHA256).Hash.ToLowerInvariant()
(Get-FileHash .academy\workspaces\U04-brownfield\.codearbiter\CONTEXT.md -Algorithm SHA256).Hash.ToLowerInvariant()

You · Native terminal · macOS

git -C .academy/workspaces/U04-greenfield status --short
git -C .academy/workspaces/U04-brownfield status --short
git -C .academy/workspaces/U04-greenfield rev-parse HEAD 'HEAD^{tree}'
git -C .academy/workspaces/U04-brownfield rev-parse HEAD 'HEAD^{tree}'
shasum -a 256 .academy/workspaces/U04-greenfield/.codearbiter/CONTEXT.md .academy/workspaces/U04-brownfield/.codearbiter/CONTEXT.md

You · Native terminal · Linux

git -C .academy/workspaces/U04-greenfield status --short
git -C .academy/workspaces/U04-brownfield status --short
git -C .academy/workspaces/U04-greenfield rev-parse HEAD 'HEAD^{tree}'
git -C .academy/workspaces/U04-brownfield rev-parse HEAD 'HEAD^{tree}'
sha256sum .academy/workspaces/U04-greenfield/.codearbiter/CONTEXT.md .academy/workspaces/U04-brownfield/.codearbiter/CONTEXT.md

Expected result

Both status commands print nothing, followed by each child's committed HEAD, committed tree, and context digest from .codearbiter/CONTEXT.md. Next safe step: write binding report.

If that does not happen

If either status is nonempty or any HEAD, tree, or digest is missing, preserve all output and return to that child; do not generate a parent report from partial or uncommitted state.

Evidence

Preserve the six binding values and both empty statuses exactly as printed; they are the source facts the canonical writer must bind.

After both children are committed and clean, run the supported canonical writer from the Academy root. Never hand-author verifier-sensitive report bytes.

Why

The supported writer derives canonical report bytes from live child repositories instead of trusting a hand-written claim.

You · Native terminal · Windows

$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.30\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path write-report U04-initialize-projects

You · Native terminal · macOS

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" write-report U04-initialize-projects

You · Native terminal · Linux

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" write-report U04-initialize-projects

Expected result

The writer creates .codearbiter/reports/academy/U04-initialization.md with canonical generated bytes bound to both clean committed children. Next safe step: inspect report.

If that does not happen

If the writer reports a dirty, uncommitted, or wrong-layout child, preserve the message and return only to that child; do not hand-author the report.

Evidence

Preserve the canonical report at its exact path plus each child's committed HEAD, committed tree, and context digest that it records.

Inspect the canonical parent report before staging.

Why

Inspecting the generated report verifies its binding facts before it enters the parent commit.

You · Native terminal · Windows

Get-Content .codearbiter\reports\academy\U04-initialization.md

You · Native terminal · macOS

cat .codearbiter/reports/academy/U04-initialization.md

You · Native terminal · Linux

cat .codearbiter/reports/academy/U04-initialization.md

Expected result

The report displays Greenfield, Brownfield, and Route evidence sections with the exact child paths, HEADs, trees, CONTEXT-SHA256 digests, and route artifacts. Next safe step: stage report.

If that does not happen

If a field is absent or differs from the inspected child evidence, preserve the report and child outputs, then rerun the canonical writer after fixing the child state; do not edit the report.

Evidence

Preserve the displayed canonical report and compare every binding field to the immediately preceding child evidence.

After review, stage only the canonical parent report.

Why

Staging only the canonical report prevents child content or unrelated parent files from entering the binding commit.

You · Native terminal · Windows

git add -- .codearbiter\reports\academy\U04-initialization.md
git diff --cached --name-only

You · Native terminal · macOS

git add -- .codearbiter/reports/academy/U04-initialization.md
git diff --cached --name-only

You · Native terminal · Linux

git add -- .codearbiter/reports/academy/U04-initialization.md
git diff --cached --name-only

Expected result

Only .codearbiter/reports/academy/U04-initialization.md is staged in the Academy parent, and diff --cached --name-only prints exactly that path. Next safe step: review commit boundary.

If that does not happen

If any other parent path is staged, preserve the cached list and unstage only the unexpected path; leave both child histories untouched.

Evidence

Preserve the one-line cached name list naming only .codearbiter/reports/academy/U04-initialization.md.

You · Active CodeArbiter harness · All operating systems

Confirm only the report is staged and both children are clean. Then use Open Folder or the workspace switcher to return to the Academy root.

Why

The parent cached diff must contain only the report while both child repositories remain clean.

Expected result

The parent index contains only U04-initialization.md, both child statuses remain empty, and the host visibly shows the Academy root. Next safe step: run commit gate.

If that does not happen

If another parent path is staged, either child is dirty, or the host shows a child root, stop; preserve the cached list and statuses and correct only that boundary before ca-commit.

Evidence

Preserve the single staged report path, both empty child statuses, and the visible Academy-root label presented to the parent commit gate.

Only at the visibly confirmed Academy root, run ca-commit; do not run it in either child.

Why

The Academy-root commit gate preserves the separation between parent evidence and child governance history.

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

ca-commit creates a new Academy-parent commit whose only changed path is .codearbiter/reports/academy/U04-initialization.md; child histories do not change. Next safe step: confirm clean.

If that does not happen

If the parent gate stops, preserve its findings and staged report; remediate from the Academy root and rerun ca-commit without recommitting either child.

Evidence

Preserve the successful parent ca-commit transcript, new parent commit hash, and its one-path diff naming only the canonical U04 report.

Confirm parent, greenfield, and brownfield status are empty.

Why

Three clean statuses prove the complete evidence topology is settled before acceptance.

You · Native terminal · Windows

git status --short
git -C .academy\workspaces\U04-greenfield status --short
git -C .academy\workspaces\U04-brownfield status --short

You · Native terminal · macOS

git status --short
git -C .academy/workspaces/U04-greenfield status --short
git -C .academy/workspaces/U04-brownfield status --short

You · Native terminal · Linux

git status --short
git -C .academy/workspaces/U04-greenfield status --short
git -C .academy/workspaces/U04-brownfield status --short

Expected result

All three status commands print nothing: the Academy parent, U04-greenfield, and U04-brownfield working trees are clean. Next safe step: recognize the accepted result.

If that does not happen

If any command prints a path, preserve all three outputs and return only to the repository that is dirty; do not reset or rewrite either committed child history.

Evidence

Preserve the three empty status outputs and current parent and child HEADs as the final clean-state record.

Recognize success

At success, greenfield has committed initialized context, the exact three .codearbiter/plans/ artifacts, and at least one accepted ADR. Brownfield has committed initialized context from its existing source and does not contain a synthetic three-plan reconciliation set. Both child worktrees are clean before their heads, trees, and committed context digests are bound. The parent commit changes only .codearbiter/reports/academy/U04-initialization.md.

The U04 Check will prove these repository facts. It will not prove that a host command ran, that a learner made a good decision, or that anything was pushed or published.

Check

Check validates committed repository facts. It does not prove that a host command ran, that a learner made a good decision, or that anything was pushed or published.

From the clean Academy root, run installed Academy Check after committing the canonical parent report.

Why

Check validates durable child and parent facts, not an unobservable claim that a host command was invoked.

You · Native terminal · Windows

$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.30\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path check U04-initialize-projects

You · Native terminal · macOS

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" check U04-initialize-projects

You · Native terminal · Linux

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" check U04-initialize-projects

Expected result

Check prints checkpoint U04-initialize-projects: passed and records progress only after it sees the clean committed parent report and both committed child states. Next safe step: preserve the completed attempt.

If that does not happen

If Check names a child or parent fact that does not match, preserve its output and return only to that boundary; do not infer success from a command exit alone.

Evidence

Preserve Check output and the committed child HEADs, trees, context digests, and parent report it validated.

Recover or continue

U04 Reset deliberately refuses until Academy can archive both child histories. Preserve failures and return to the exact child whose review or commit gate stopped. Do not reset, rewrite, or delete child history to make status look clean.

If you need to recover, invoke installed Academy Reset only to read its preservation diagnostic. U04 Reset intentionally refuses until Academy can archive both child histories.

Why

Reset must refuse rather than discard child history until a supported archival path exists.

You · Native terminal · Windows

$academy = "$env:LOCALAPPDATA\ArbiterAcademy\preview-0.30\Scripts\arbiter-academy.exe"
& $academy --repository (Get-Location).Path reset U04-initialize-projects

You · Native terminal · macOS

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" reset U04-initialize-projects

You · Native terminal · Linux

academy="${XDG_DATA_HOME:-$HOME/.local/share}/arbiter-academy/preview-0.30/bin/arbiter-academy"
"$academy" --repository "$PWD" reset U04-initialize-projects

Expected result

Reset reports that it is unavailable until Academy can archive both child repository histories and leaves all three repositories unchanged. Next safe step: preserve state and correct the named child or parent boundary.

If that does not happen

Use the status, cached-diff, and commit cards for the named repository. Do not delete, reset, or rewrite either committed child history to make status look clean.

Evidence

Preserve the Reset diagnostic plus parent and child status before and after it; their equality proves no history was rewritten.

Understand the mechanism

The action manifest preserves actor, surface, timing, expected result, evidence, recovery, and next safe step. Its verifier reads real CodeArbiter layout from committed child heads: decompose plans live under .codearbiter/plans/; context-creation documents remain in their real root locations. The canonical writer and Check use the same byte renderer, so the report that you inspect is the report Check verifies.

U04: Initialize a greenfield and a brownfield project

Know before you begin

What you will prove

Prepare safely

Practice

Recognize success

Check

Recover or continue

Understand the mechanism

Next step