Skip to main content
Architecture 2.0 Level 0 first
Start with the core artifact

Draft one design-loop card

Name the decision, bound the design space, and make the claim you intend to test visible. Add audit, replay, and independent review only when the corresponding records exist.

Draft Level 0 in 30 minutes

Level 0 records context and boundaries. It is a useful planning artifact, but it does not yet contain the records required for a Level 1 audit.

  1. 5 minutes

    Choose one decision

    Write one bounded architecture decision or experiment. Avoid goals such as “improve the system” that do not identify what could advance next.

  2. 10 minutes

    State intent and task

    Name the objective, constraints, non-goals, and bounded task. Put a paper's exact claim and non-claim under intent.claim_boundary. It is a view of intent, not a thirteenth field.

  3. 10 minutes

    Draw the design-space boundary

    List legal choices, invalid choices, and work deferred to a later turn. A reviewer should be able to tell where this loop must stop.

  4. 5 minutes

    Validate Level 0 structure

    Run the validator from a repository clone and fix every reported path.

    .venv-card/bin/python cli/arch2.py validate card my-card.yaml

Progress with existing evidence

The four examples follow one unchanged accelerator-array case. Each level preserves the earlier context and adds the records needed for a stronger conformance claim. Do not invent evidence to raise the level.

Draft Level 0, context Intent, task, and legal, invalid, and deferred design choices Add records Level 1, auditable card Representation, environment, actor map, feedback budget, evidence, and failed-run or rejected-alternative entries Bind replay Level 2, replay bindings present Stable IDs, workload and seed, tool version, parameter digest, and replay source Add a gate Level 3, independence and decision fields present Claimed independent rejection authority, commitment boundary, and named accountable owner

Practice in the real labs

The cumulative cards above are small synthetic schema and replay fixtures. They isolate the contract, but they do not replace empirical lab work with tool-produced evidence.

Simulator-backed Run the Architecture 2.0 labs Generate evidence, inspect raw outputs, preserve failed runs and rejected alternatives, and submit a reviewable runnable receipt Synthesis Study the Chapter 8 lighthouse example Follow the constructed worked example that connects the complete loop

The fixture progression and the real labs serve different teaching roles. Neither replaces Chapter 8's constructed lighthouse example.

Keep three axes separate

A higher card level does not automatically mean higher-fidelity evidence or permission to make a larger commitment.

Contract Conformance Which required record structures are present. Levels 0 to 3 and the schema validator measure this axis.
Measurement Evidence fidelity How closely the workload, tool, and observations represent the target system. A Level 3 card can still contain proxy evidence.
Decision Commitment What next action a human authorizes and how reversible it is. Stronger commitments require stronger evidence, not merely more card fields.

Disclosure and autonomy are separate review constraints too. Evidence may be confidential yet independently reviewable, and a loop documented by a Level 3 card may still grant the method very little autonomy.

Set up the validator once

The isolated environment installs only the card validator. It does not install the book, PDF, plotting, or notebook toolchain.

git clone https://github.com/harvard-edge/arch2.git
cd arch2
python3 -m venv .venv-card
.venv-card/bin/python -m pip install --upgrade pip==26.1.2
.venv-card/bin/python -m pip install -r requirements-card.txt
.venv-card/bin/python cli/arch2.py validate card my-card.yaml

The validator rejects unsupported schema versions, unknown fields, missing level requirements, and a dependent Level 3 rejection gate. See local project setup for the complete development environment.

Working artifacts

The schema defines conformance. The rubric and evidence review determine whether the card deserves trust.

Contract JSON Schema v1.1 Machine-readable field and conformance rules Review One-page Markdown form A human-readable card for paper and project review Compatibility Version policy Extension, compatibility, and change rules Replay Evidence packet instructions Render and verify the Level 2 and Level 3 example evidence

Instructor exercise

Pairs can complete a Level 0 paper-to-loop draft in one 30-minute block.

  1. Choose, 5 minutes. Select one paper with a concrete architecture result and name the next decision its result could support.
  2. Bound, 10 minutes. Write the objective, constraints, non-goals, task, claim, and non-claim.
  3. Separate, 10 minutes. List legal, invalid, and deferred design choices without reading the other pair's card.
  4. Challenge, 5 minutes. Exchange cards and identify one hidden assumption or ambiguous boundary.

For a follow-on audit exercise, give students an existing evidence packet and ask them to build Level 1. Do not ask them to fabricate evidence or failed alternatives from a paper that does not report them.