Appendix A: Setup and Implementation Checklist

1. It defines the minimal setup you need to run the examples and build your own Software Development as Code (SDaC) loop.
2. It provides an implementation checklist (a dependency graph plus milestones).
3. It includes a concept map so you can skim the book without memorizing the canon.

Minimal toolchain

You can implement Software Development as Code (SDaC) in any stack. The patterns in this book assume you have a small deterministic substrate that can do three things reliably: version, run, and verify.

Minimum requirements:

• Version control (Git).
• A deterministic runner (Make, a task runner, or a CI job).
• A scripting/runtime layer for glue code (Python is used in many examples, but the point is “small and deterministic,” not “Python specifically”).
• A diff surface (unified diffs in Git are the simplest).
• A validator suite (linters, schema checks, and tests) that can return machine-readable failures.

Optional (useful for docs or manuscripts):

• A Markdown renderer to produce PDFs.

Runnability legend (how to read code blocks)

This book is published for web reading, so treat code blocks as patterns unless the text explicitly marks them as runnable.

This book mixes three kinds of snippets:

1. Runnable (companion repo): commands or file paths tied to github.com/kjwise/aoi_code. If you git clone that repo, you can run these examples as written.
2. Runnable (adapt): realistic configs and scripts that will run once you substitute your own paths, tool names, and CI environment. They are “copy, then specialize.”
3. Illustrative: pseudocode, sketches, and schemas that explain shape and contracts. They are not meant to run without surrounding implementation.

When provenance matters, the text calls out the source (companion repo, this repo, or “illustrative”). When it doesn’t, treat the snippet as a pattern template.

Quick sanity check (for any repo)

Before you build autonomy, verify you can deterministically reproduce reality:

1. Run git status; it should be clean.
2. Run a validator suite locally (lint/tests) and get a deterministic pass/fail.
3. Generate a diff and revert it cleanly.

If you cannot do those three things, your SDaC loop is likely to be “creative,” not reliable.

Git hooks (optional, recommended)

Git hooks are a cheap way to push Physics earlier: run deterministic checks before changes enter history.

If you want repo-local, versioned hooks, point Git at a hooks directory inside your repo (for example .githooks):

git config core.hooksPath .githooks
git config --get core.hooksPath

Some repos also provide a convenience target for this (for example make hooks-install).

If hooks are installed, core.hooksPath should print .githooks.

Implementation checklist

The goal is not to implement every chapter. The goal is to ship a small loop that is correct, auditable, and easy to extend.

For reusable copy/paste artifacts, use Appendix C as the canonical home: output-contract patterns, Mission templates, and the Day 2 hardening checklist live there.

The dependency graph

flowchart TD
  MVF["Ch 1:\nMinimum Viable Factory"] --> Sandwich["Ch 2:\nDeterministic Sandwich"]
  Sandwich --> Validators["Ch 3:\nDefine Good (Validators)"]
  Validators --> Drift["Ch 4:\nDrift Measurement"]
  Validators --> Ouroboros["Ch 5:\nOuroboros Protocol"]
  Ouroboros --> Slice["Ch 6:\nContext Slicing"]
  Slice --> Missions["Ch 7:\nMission Objects"]
  Missions --> MapUpdaters["Ch 8:\nMap-Updaters + CI Gate"]
  MapUpdaters --> Dream["Ch 9:\nScheduled Maintenance / Dream Daemon"]
  Validators --> Guardrails["Ch 10:\nImmutable Infrastructure"]
  Guardrails --> Refactor["Ch 11:\nAutomated Refactoring Under Guards"]
  Guardrails --> Policy["Ch 12:\nGovernance at Machine Speed"]
  Policy --> Reflect["Ch 13:\nHofstadter Bridge"]

Chapter 14 (“The Race to Reliable Autonomy”) is intentionally not a build dependency. Read it any time you want more pressure about why the bar is rising.

Weekend sprint (Part I): Build the first loop

Milestone 1: A loop you can run locally (Chapter 1)

Definition of done:

• One Effector that updates an artifact (docs, config, or code) from a Map input.
• One Validator that deterministically gates the result.
• One command that runs effector -> validator end-to-end and fails fast on violations.

Minimal scope recommendations:

• Prefer doc sync or config generation before code generation.
• Keep the “Map” small and explicit (one YAML/JSON file).

Milestone 2: Wrap the stochastic call (Chapter 2)

Definition of done:

• Prep layer produces a structured request from typed inputs (a template + a mapping function).
• Validation layer parses the output strictly and emits a machine-readable error on failure.
• The Effector refuses to write when validation fails.

Minimum set of error fields to collect (even if you only print them):

• file_path
• line_number (or “unknown” if your validator cannot localize yet)
• error_code (schema keyword, linter code, or tool name)
• message

Milestone 3: Make “good” executable (Chapter 3)

Definition of done:

• At least one hard validator that catches a real failure mode your team has seen.
• Your validator output is stable and readable (same format every run).
• You can demonstrate causality: break the rule, observe deterministic failure.

Weeks 1–2 (Part II): Understand why it works

Milestone 4: Measure drift (Chapter 4)

Definition of done:

• Run the same Mission Object 10 times.
• Track at least one drift metric:
  • Unique diffs (how many distinct outputs)
  • Failure rate (what percent violates validators)
  • Time-to-convergence (iterations until PASS)

Milestone 5: Build a loop that converges (Chapter 5)

Definition of done:

• A Write -> Judge -> Refine loop that terminates.
• The Judge returns structured diagnostics, not vague prose.
• You have circuit breakers (max iterations + wall-clock budget).

Milestone 6: Slice the graph, do not dump it (Chapter 6)

Definition of done:

• A repeatable way to build a context packet for a single task.
• The slice is small enough to fit comfortably in one model call.
• You can show one failure from a raw dump and one success from a slice.

Weeks 2–4 (Part III): Scale the loop into a system

Milestone 7: Intent as a typed object (Chapter 7)

Definition of done:

• Mission Objects are stored as data (JSON/YAML) rather than embedded strings.
• Mission Objects include constraints and a success condition.
• Failures route through a state machine: Revert, Iterate, or Update Environment.

Milestone 8: Keep the Map fresh (Chapter 8)

Definition of done:

• A Map-Updater that extracts a deterministic skeleton from the Terrain.
• A compare step that detects drift.
• A propose step that emits a unified diff (and nothing else).
• A CI gate that fails on drift and tells you how to repair it.

Milestone 9: The 90% maintenance system (Chapter 9)

Definition of done:

• Scheduled runs (nightly or weekly) that propose maintenance patches.
• Human approval before merge.
• A short “Dream Manifest” of what you measure and why (defects, flaky tests, complexity hotspots).

Ongoing (Part IV): Govern safe evolution

Milestone 10: Protected Infrastructure (Chapter 10)

Definition of done:

• Your system cannot modify the code that grades it (tests, validators, CI rules) without a human.
• Protected paths and review rules are enforced by the platform (CODEOWNERS / branch protection).
• A break-glass procedure exists and is rehearsed.

Milestone 11: Automated refactoring under guards (Chapter 11)

Definition of done:

• A small, metric-driven refactor loop with commit/revert rules.
• The Ratchet is explicit: quality metrics do not regress without an intentional waiver.

Milestone 12: Governance at machine speed (Chapter 12)

Definition of done:

• Clear policy for what can auto-merge vs what requires review.
• Blast radius boundaries are explicit and enforced.
• Audit artifacts are retained (logs, diffs, run metadata).

Part V: Reflections (destination + stakes)

Chapter 13 is the destination the rest of the book has been building toward. Most teams will cross that bridge one bounded surface at a time, not all at once.

Concept map (where terms live)

You don’t need to memorize the canon up front. The terms arrive in the order you need them.

Use this section like an index:

• If you’re impatient, ignore it and start with Part I.
• If you’re skimming, it tells you where to look when a term shows up.

Guided ascent (high level)

Where key concepts are introduced (chapter-level)

• Chapter 1: Map, Terrain, Ledger, Effector, Validator (Minimum Viable Factory (MVF) v0: a loop you can run).
• Chapter 2: The Deterministic Sandwich (Prep → Model → Validation).
• Chapter 3: Validators → Immune System (Physics you can enforce).
• Chapter 4: Stochastic Drift (measure it, budget it, reduce it).
• Chapter 5: The Ouroboros Protocol + Attractors + circuit breakers (debug convergence).
• Chapter 6: Context Architecture + Context Graph + Branching Factor + Skeleton-First Rule (slice deterministically).
• Chapters 7–9: Mission Objects, Map-Updaters, Dream (scale the loop into a system).
• Chapters 10–12: Immutable Infrastructure + governance at machine speed (protect graders and blast radius).
• Chapter 13: Hofstadter Bridge (destination: when the Map becomes enforceable, one bounded surface at a time).
• Chapter 14: The Race to Reliable Autonomy (stakes: why the bar is rising).
• Appendix D: glossary + translation guide.

Actionable: What you can do this week

1. Pick one artifact and one validator, and get a local end-to-end loop working.

2. Add structured error output to your Judge, even if it is only file_path + message at first.

3. Put one protected path in place (tests/validators/CI) and require human review for it.