@pilotspace/add 1.0.0

package/GETTING-STARTED.md

@@ -0,0 +1,238 @@
+# Getting started with ADD — your first feature in ~10 minutes
+
+This is a runnable walkthrough. Follow it top to bottom and you'll take one real
+feature — *transfer money between a user's own accounts* (the book's worked
+example) — from nothing to a verified, passing result, using the ADD method.
+
+You'll learn the whole loop by doing it once:
+
+> **Specify → Scenarios → Contract → Tests → Build → Verify → Observe**
+
+ADD is **AI-first**: you talk to the agent and it drives the method — you don't
+hand-type the commands. The commands below are the agent's hands (and your escape
+hatch); the rest of this guide shows both so you can see what the agent does.
+
+---
+
+## The fast path — talk to the agent
+
+After installing (step 1 below), the whole on-ramp is one move:
+
+```
+in Claude Code:  /add
+you:             "I want to let users transfer money between their own accounts."
+```
+
+From there the agent runs the **on-ramp** for you:
+
+1. **Orient** — it reads `add.py status` (the resume point), never re-reading your repo.
+2. **Intake** — it sizes your request into versioned scope and proposes a **milestone**
+   (goal · scope · breadth-first tasks · exit criteria). *You confirm the shape.*
+3. **One-approval front** — for each task it drafts Spec + Scenarios + Contract + Tests
+   as one bundle. *You give one approval at the frozen contract.*
+4. **Self-driving run** — build→verify runs to green; a security finding always stops
+   back to you.
+
+So a milestone-sized feature is: **describe it → confirm the milestone → approve each
+contract → review the result.** Everything between is the agent.
+
+> New term: **On-ramp** — the install→first-milestone path. See `docs/appendix-c-glossary.md`.
+
+---
+
+## 0 · Prerequisites
+
+- **Node.js ≥ 16** (to install) and **Python 3.12+** (the tool is stdlib-only).
+- A project folder. It can be empty or an existing repo.
+
+---
+
+## 1 · Install
+
+From your project root:
+
+```bash
+npx @pilotspace/add init --name "My App" --stage prototype
+```
+
+This creates `.add/` (your runtime), drops the `add` skill into
+`.claude/skills/add/`, and bundles the book into `.add/docs/`. Pick the stage that
+matches your intent — `prototype`, `poc`, `mvp`, or `production`. You can change it
+later with `python3 .add/tooling/add.py stage mvp`.
+
+> Why stages exist: the steps never change, only how *deeply* you run them.
+> See `.add/docs/10-setup-and-stages.md`.
+
+---
+
+## 2 · Orient — the command you'll use most
+
+```bash
+python3 .add/tooling/add.py status
+```
+
+`add.py status` is your home base. It reads `.add/state.json` and tells you the
+project stage, the active task, and which phase you're in. **Start every session
+with it** — that's how ADD resumes work without re-reading your whole repo.
+
+> Tip: shorten typing with an alias — `alias add="python3 .add/tooling/add.py"` —
+> then you can run `add status`, `add advance`, etc. The rest of this guide writes
+> the full `python3 .add/tooling/add.py ...` form so copy-paste always works.
+
+And when you're mid-task and unsure what the current phase needs, ask:
+
+```bash
+python3 .add/tooling/add.py guide
+```
+
+`status` tells you *where* you are; `guide` tells you *what to do next* — the active
+task's phase, the one concrete next action, the chapter to read, and the exact command
+to run once that phase is done.
+
+---
+
+## 3 · Start your first feature
+
+```bash
+python3 .add/tooling/add.py new-task transfer --title "Transfer money between my accounts"
+```
+
+This scaffolds `.add/tasks/transfer/TASK.md` — **one file holding all seven phase
+sections** — plus empty `tests/` and `src/` folders, and makes it the active task
+at phase `specify`.
+
+Open `.add/tasks/transfer/TASK.md` in your editor. You'll fill it top to bottom.
+
+---
+
+## Under the hood — the seven phases by hand (escape hatch)
+
+Everything above is what the agent drives for you through the one-approval front. This
+section is the **escape hatch**: the same seven phases run by hand, so you can see what
+each one produces and step in manually whenever you want to. You never *have* to type
+these — they are the agent's hands, and yours when you take the wheel.
+
+The rhythm is always: **fill the section → run `python3 .add/tooling/add.py advance`.**
+The tool keeps the `phase:` marker at the top of TASK.md in sync.
+
+### Phase 1 — Specify (`docs/03-step-1-specify.md`)
+
+Write the rules in **§1**. State what it *must* do, what it must *reject* (each
+with a named error code), and what's true after success:
+
+```
+Must:
+  - move an amount from one of my accounts to another of mine
+  - amount > 0 ; source ≠ destination ; source has enough balance
+After:
+  - source balance -= amount, destination balance += amount
+Reject:
+  - amount <= 0           -> "amount_invalid"
+  - source == destination -> "same_account"
+  - balance < amount      -> "insufficient_funds"
+  - account not mine      -> "forbidden"
+```
+
+Confirm every assumption (no FX, no daily limit in v1). Then:
+
+```bash
+python3 .add/tooling/add.py advance
+```
+
+### Phase 2 — Scenarios (`docs/04-step-2-scenarios.md`)
+
+In **§2**, turn each rule into a Given/When/Then. For every rejection, assert what
+must stay **unchanged**:
+
+```gherkin
+Scenario: insufficient funds
+  Given A has 20, mine
+  When I transfer 50 from A to B
+  Then it is rejected "insufficient_funds"
+  And no balance changes
+```
+
+Then `python3 .add/tooling/add.py advance`.
+
+### Phase 3 — Contract (`docs/05-step-3-contract.md`)
+
+In **§3**, fix the external shape and **freeze** it (`Status: FROZEN @ v1`):
+
+```
+POST /transfers  body: { fromAccountId, toAccountId, amount }
+  200 -> { transferId, fromBalance, toBalance }
+  400 -> { error: "amount_invalid" | "same_account" | "insufficient_funds" }
+  403 -> { error: "forbidden" }
+```
+
+A frozen contract is the seam that makes the AI build safe. Then advance.
+
+### Phase 4 — Tests, red first (`docs/06-step-4-tests.md`)
+
+Write one test per scenario into `.add/tasks/transfer/tests/`, then **run them and
+confirm they FAIL** — there's no code yet. A test that passes now is testing
+nothing. This is red/green TDD: red before green. Then advance.
+
+### Phase 5 — Build (`docs/07-step-5-build.md`)
+
+Now let the AI write code into `.add/tasks/transfer/src/` until **every test
+passes** — without changing any test or the frozen contract. Honor the safety rule
+(here: debit + credit in one atomic transaction). Then advance.
+
+### Phase 6 — Verify (`docs/08-step-6-verify.md`)
+
+In **§6**, confirm the evidence (all green, nothing weakened) and check what tests
+miss: concurrency, security, architecture. Record the gate — and close the task:
+
+```bash
+python3 .add/tooling/add.py gate PASS
+```
+
+`gate PASS` marks the task `done`. (Use `gate HARD-STOP` to send it back to Build,
+or `gate RISK-ACCEPTED` for a signed, non-security waiver.)
+
+### Phase 7 — Observe (`docs/09-the-loop.md`)
+
+In **§7**, note what to watch in production and the next spec delta. Every learning
+becomes the next `new-task`. The flow is a loop, not a finish line.
+
+---
+
+## 5 · Self-check
+
+Confirm your project is internally consistent at any time:
+
+```bash
+python3 .add/tooling/add.py check
+```
+
+It verifies state is valid, every task has its TASK.md, and markers match. Exit
+code 0 means healthy — handy as a CI gate.
+
+---
+
+## 6 · Resume next session
+
+Close your laptop, come back tomorrow, run:
+
+```bash
+python3 .add/tooling/add.py status
+```
+
+It tells you exactly where you left off and what to do next. No context rot — the
+state lives on disk, not in a chat window.
+
+---
+
+## 7 · Where to read more
+
+You just ran the method; now read *why* it's shaped this way:
+
+- The shift & principles — `.add/docs/00-introduction.md`, `.add/docs/01-principles.md`
+- The flow end to end — `.add/docs/02-the-flow.md`
+- Each step in depth — `.add/docs/03..09`
+- Operating it on a team — `.add/docs/11-governance.md`, `.add/docs/12-roles.md`
+- A fully worked example — `.add/docs/appendix-d-worked-example.md`
+
+The rule to remember: **build the right thing (direction), prove it's right
+(verification), and let the AI do the building in between.**

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Tin Dang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# ADD — AI-Driven Development
+
+> A minimal, state-tracked Claude Code skill for building software when the AI
+> writes the code and **you** own the two things it cannot do alone: decide *what*
+> to build, and *verify* it is correct.
+
+ADD is the **orchestration engine** of the AIDD method. It sits on top of a
+context foundation (DDD → SDD → UDD) and runs as a red/green TDD ↔ AI-build loop.
+The full reasoning — *why* every rule exists — is the AIDD book bundled in
+[`docs/`](./docs/README.md). Read it once; keep it open beside you.
+
+```
+  Foundation (context):  DDD  ·  SDD  ·  UDD
+  Engine (this skill):   TDD  ⇄  ADD
+  Flow per feature:  Specify → Scenarios → Contract → Tests → Build → Verify → Observe ↻
+```
+
+## Why ADD (and why it is minimal)
+
+Heavy doc-first methods burn your time writing documents and lose the thread
+across sessions (context rot). ADD fixes both:
+
+- **One file per feature.** Spec, scenarios, contract, test-plan, and gate record
+  all live inline in a single `TASK.md`. No sprawling doc tree.
+- **State on disk, not in chat.** A Python tool tracks where you are in
+  `.add/state.json`, so a fresh session resumes with one command instead of
+  re-reading the repo.
+- **Progressive disclosure.** The skill loads only the guide for the phase you are
+  in — the context window stays lean.
+
+## Install
+
+Pick your ecosystem — both install the same skill, tooling, and book:
+
+```bash
+# Node / npm
+npx @pilotspace/add init --name "My App" --stage prototype
+```
+
+```bash
+# Python / pip
+pip install add-method
+add-method init --name "My App" --stage prototype
+```
+
+**New here?** Follow the [10-minute Quickstart](./GETTING-STARTED.md) — it walks
+your first feature end to end.
+
+This installs:
+
+| Path | What |
+|------|------|
+| `.claude/skills/add/` | the `add` skill Claude loads (thin router + per-phase guides) |
+| `.add/tooling/add.py` | scaffolder + state tracker (Python, stdlib only) |
+| `.add/docs/` | the AIDD book — the trust layer |
+| `.add/state.json` | where the project is |
+| `.add/CONVENTIONS.md`, `GLOSSARY.md`, `MODEL_REGISTRY.md`, `dependencies.allowlist` | survivor-layer files |
+
+## Use it
+
+ADD is AI-first: you talk to the agent; it drives the method. In Claude Code, run
+**`/add`** and say what you want to build:
+
+> `/add` — *"I want to let users transfer money between their own accounts."*
+
+The agent orients from `state.json`, **sizes your request into a milestone** (you
+confirm the shape), then drafts each feature's **one-approval front** — Spec +
+Scenarios + Contract + Tests as one bundle — and you give **one approval at the
+frozen contract**. A self-driving build→verify run takes it to green; security
+findings always stop back to you.
+
+Under the hood the agent runs the CLI as its hands — and you can hand-drive it too:
+
+```bash
+python3 .add/tooling/add.py status      # where am I? (resume point)
+```
+
+## The non-negotiables
+
+1. **Direction before speed** — no Build until spec, scenarios, contract, and *red*
+   tests exist.
+2. **Trust evidence, not inspection** — a feature is trusted because its tests pass
+   and the blind spots (concurrency, security, architecture) were checked.
+3. **Never weaken a test or edit a frozen contract** to make the build pass.
+4. **No silent skips** — every Verify records `PASS`, `RISK-ACCEPTED`, or
+   `HARD-STOP`. Security findings are always `HARD-STOP`.
+5. **Ask, don't guess.**
+
+## The artifacts survive; the code is disposable
+
+The durable asset is the decisions — spec, scenarios, contract, tests. The code is
+one implementation that satisfies them and can be regenerated. If the thing you'd
+be upset to lose is "the code," you're still working the old way.
+
+## Read the method
+
+Start at [`docs/README.md`](./docs/README.md) — Foundations → the six steps →
+operating it across a team → templates, prompts, and a full worked example.
+
+## Develop
+
+```bash
+npm test     # runs the Python tests for the tooling (red/green)
+```
+
+License: MIT.

package/bin/cli.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * @pilotspace/add installer.
+ *
+ *   npx @pilotspace/add init [targetDir] [--force] [--stage <stage>] [--name <name>]
+ *
+ * Installs the ADD skill + tooling + book into a target project:
+ *   <target>/.claude/skills/add/   (the skill Claude loads)
+ *   <target>/.add/tooling/         (add.py scaffolder + state tracker)
+ *   <target>/.add/docs/            (the AIDD book — the trust layer)
+ * Then runs `add.py init` to create .add/state.json and survivor files.
+ *
+ * Zero npm dependencies. Designed for failure: verifies sources, never clobbers
+ * an existing state.json, and degrades gracefully if python3 is absent.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const PKG_ROOT = path.resolve(__dirname, "..");
+
+function log(msg) { process.stdout.write(msg + "\n"); }
+function warn(msg) { process.stderr.write("warn: " + msg + "\n"); }
+function fail(msg) { process.stderr.write("error: " + msg + "\n"); process.exit(1); }
+
+function parseArgs(argv) {
+  const args = { _: [], force: false, stage: "prototype", name: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--force") args.force = true;
+    else if (a === "--stage") args.stage = argv[++i];
+    else if (a === "--name") args.name = argv[++i];
+    else if (a.startsWith("--")) warn("ignoring unknown flag " + a);
+    else args._.push(a);
+  }
+  return args;
+}
+
+function copyDir(src, dest, { skipIfExists } = {}) {
+  if (!fs.existsSync(src)) fail("missing packaged source: " + src);
+  if (skipIfExists && fs.existsSync(dest)) {
+    warn(dest + " exists — leaving it untouched");
+    return;
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.cpSync(src, dest, { recursive: true });
+}
+
+function hasPython() {
+  for (const py of ["python3", "python"]) {
+    const r = spawnSync(py, ["--version"], { stdio: "ignore" });
+    if (r.status === 0) return py;
+  }
+  return null;
+}
+
+function cmdInit(args) {
+  const target = path.resolve(args._[0] || ".");
+  if (!fs.existsSync(target)) fail("target directory does not exist: " + target);
+  log("Installing ADD into " + target);
+
+  // 1. skill -> .claude/skills/add
+  copyDir(
+    path.join(PKG_ROOT, "skill", "add"),
+    path.join(target, ".claude", "skills", "add"),
+    { skipIfExists: !args.force }
+  );
+  log("  ✓ skill      -> .claude/skills/add/");
+
+  // 2. tooling -> .add/tooling  (exclude tests from the installed copy)
+  const toolingDest = path.join(target, ".add", "tooling");
+  copyDir(path.join(PKG_ROOT, "tooling"), toolingDest, { skipIfExists: false });
+  // installed copy is runtime-only: drop ALL test files and any compiled cache
+  // (glob test_*.py — not just test_add.py — so no test leaks into installs)
+  fs.rmSync(path.join(toolingDest, "__pycache__"), { recursive: true, force: true });
+  for (const entry of fs.readdirSync(toolingDest)) {
+    if (/^test_.*\.py$/.test(entry)) {
+      fs.rmSync(path.join(toolingDest, entry), { force: true });
+    }
+  }
+  log("  ✓ tooling    -> .add/tooling/add.py (+ templates)");
+
+  // 3. docs (the book / trust layer) -> .add/docs
+  copyDir(path.join(PKG_ROOT, "docs"), path.join(target, ".add", "docs"),
+    { skipIfExists: false });
+  log("  ✓ trust docs -> .add/docs/ (the AIDD book)");
+
+  // 4. run add.py init (idempotent — add.py refuses to clobber state.json)
+  const py = hasPython();
+  const addPy = path.join(toolingDest, "add.py");
+  if (!py) {
+    warn("python3 not found — skipping `add.py init`.");
+    log("\nFinish setup manually once Python is available:");
+    log("  python3 .add/tooling/add.py init" +
+        (args.name ? ` --name "${args.name}"` : "") + ` --stage ${args.stage}`);
+    return;
+  }
+  const initArgs = [addPy, "init", "--dir", target, "--stage", args.stage];
+  if (args.name) initArgs.push("--name", args.name);
+  if (args.force) initArgs.push("--force");
+  const r = spawnSync(py, initArgs, { stdio: "inherit" });
+  if (r.status !== 0 && r.status !== null) {
+    warn("`add.py init` exited non-zero (state may already exist). Run `add.py status` to check.");
+  }
+
+  log("\nDone. In Claude Code, the `add` skill is now installed.");
+  log("Next:  open Claude Code, run `/add`, and say what you want to build —");
+  log("       the agent sizes it into a milestone and drives the build with you.");
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0] && !argv[0].startsWith("--") ? argv.shift() : "init";
+  const args = parseArgs(argv);
+  switch (cmd) {
+    case "init":
+      cmdInit(args);
+      break;
+    case "help":
+    case "--help":
+      log("usage: npx @pilotspace/add init [targetDir] [--force] [--stage <s>] [--name <n>]");
+      break;
+    default:
+      fail("unknown command '" + cmd + "'. Try: npx @pilotspace/add init");
+  }
+}
+
+main();

package/docs/00-introduction.md

@@ -0,0 +1,46 @@
+# 00 · The shift: why AIDD exists
+
+[Contents](./README.md) · Next: [01 Core principles →](./01-principles.md)
+
+---
+
+## Code became cheap
+
+For the whole history of software, writing code was the slow, expensive, central act. Methodologies — waterfall, agile, and the rest — were arrangements for managing that expensive act: how to plan it, divide it, review it, and ship it.
+
+AI changed the cost. An agent can now produce a working module in the time it takes to describe it. The marginal cost of *writing* a piece of code, and of *re-writing* it, has fallen close to zero.
+
+When the cost of one activity collapses, value moves to whatever is still scarce. Three things remain scarce:
+
+1. **Validated decisions** — knowing what should be built, and being right about it.
+2. **Stable contracts** — the agreed interfaces and data shapes that everything else depends on.
+3. **Verification capacity** — the rate at which people can confirm that what was produced is actually correct.
+
+AIDD is a development method organized around protecting those three things, because they are now where the difficulty lives.
+
+## The failure mode AIDD prevents
+
+The naïve way to use an AI agent is to describe a feature in a sentence and accept whatever it returns. This works for a throwaway script and fails for real software, for one reason: **an AI agent is fast in whatever direction it is pointed.**
+
+If the direction is vague, the agent does not slow down and ask. It produces a confident, plausible, complete-looking result that is subtly wrong — built on an assumption you never made, missing an edge case you never stated. Because it looks finished, the error survives a quick read and surfaces later, when it is expensive to fix.
+
+Speed in the wrong direction is not progress; it is faster waste. The entire purpose of AIDD is to fix the direction *before* turning on the speed.
+
+## Where value moves — and what that means for you
+
+If writing code is no longer the scarce skill, then a software person's value is no longer "can write code." It is two new things:
+
+- **Direction** — turning a fuzzy need into an unambiguous, buildable definition.
+- **Verification** — establishing, through evidence, that the result is correct and safe.
+
+This is not a smaller job than coding; it is a harder one. It is the part of engineering that was always the real work, now made explicit because the typing has been automated away.
+
+## What this book gives you
+
+The rest of the book is the practical consequence of the shift:
+
+- A **flow** (Part II) that front-loads direction and back-loads AI execution, with verification built in.
+- An **operating manual** (Part III) for running that flow across stages, roles, and risk levels.
+- **Reference material** (Part IV) — templates, prompts, and a fully worked example — so the method is concrete from day one.
+
+> **The thesis in one line.** Build the right thing (direction), prove it is right (verification), and let the AI do the building in between.

package/docs/01-principles.md

@@ -0,0 +1,71 @@
+# 01 · Core principles
+
+[← 00 The shift](./00-introduction.md) · [Contents](./README.md) · Next: [02 The flow →](./02-the-flow.md)
+
+Everything in this book follows from a small set of principles. If a practice ever seems arbitrary, trace it back to one of these.
+
+---
+
+## 1. Direction before speed
+
+An AI agent accelerates in whatever direction it is given. Therefore the direction must be fixed before the acceleration begins. In practice this means the early, human-led steps of the flow are not optional preamble — they are the steering, and the build step is the engine. You do not start the engine until the wheel is set.
+
+**Consequence:** the specification, scenarios, and contract come *before* any code, every time.
+
+## 2. Trust through evidence, not inspection
+
+AI output is often wrong in ways that read as correct. You cannot establish correctness by reading the code and judging it plausible. You establish it by defining, in advance, what "correct" means — as automated tests — and confirming the code satisfies them, then checking by hand only the narrow set of things tests cannot catch.
+
+**Consequence:** tests are written *before* the implementation, and a feature is trusted because its tests pass, not because someone reviewed it and liked it.
+
+## 3. The artifacts survive; the code is disposable
+
+The durable assets of a project are the decisions and agreements: the specification, the scenarios, the contract, the tests. The code is merely one implementation that satisfies them and can be regenerated at will. Protect the artifacts; treat the code as replaceable.
+
+**Consequence:** effort goes into keeping contracts and specs stable and clear, not into preserving particular code. Metrics that count code volume or reuse measure the wrong thing.
+
+## 4. The loop is re-entrant, not a waterfall
+
+The flow has an order, but it is not a one-way march. Any step may reveal a gap in an earlier one — and when it does, you return to that earlier step, fix the artifact, and come forward again. The specification is a living document, not a frozen contract signed once.
+
+**Consequence:** discovering a missing rule during the build is the method working, not failing. The only true one-way door is the frozen interface contract, and even that reopens through a deliberate change request.
+
+## 5. Trust is earned per scope, not granted globally
+
+How much you let the AI do is not a single switch. It is a setting that lives *per scope*, and it can differ from one part of the system to another. A well-tested, low-risk area may run at full autonomy while a new, high-risk one is held back.
+
+The *default starting point* is a deliberate choice. A team that has built up evidence and tooling may **start a scope at auto** — the AI drafts the front, a human approves the frozen contract once, and the build runs and auto-gates on evidence — and *lower to conservative* wherever risk is high. (An earlier formulation started every scope conservative and made autonomy the earned exception; it is the same dial either way — what differs is which end you default to.) Two things never move with the default, whichever way it points: the contract-freeze seam stays human (the AI never freezes the interface it then builds against), and a high-risk scope is always lowered, never auto-run.
+
+**Consequence:** autonomy is a per-scope setting you choose deliberately and can lower at any time; high-risk scope is held to a human gate regardless of the default (see [11 Governance](./11-governance.md)).
+
+## 6. You cannot move faster than you can verify
+
+When an agent produces more than the team can review, the excess is not speed — it is unreviewed risk accumulating. Verification capacity is the real ceiling on throughput.
+
+But *verification* is not the same as *human reading*. The ceiling is what you can trust to a recorded standard, and automated verification raises it: a passing test suite, a contract check, an adversarial verifier are all verification, and they scale in a way human review cannot. This is only principle 2 taken to its limit. What automation cannot cover is the residue principle 2 names — the narrow set tests miss: security, concurrency, and architecture. That residue stays at human speed. So the rule sharpens: you may move as fast as your *automated* verification carries you, and no faster on the part only a human can check.
+
+**Consequence:** if AI output outpaces verification, the correct response is to strengthen the automated checks or reduce the AI's autonomy — never to rush or skip. More autonomy is earned by more verification, not by a lower bar.
+
+## 7. No silent skips
+
+Every checkpoint resolves explicitly. A step is either passed, or passed with a recorded and signed acceptance of a known risk, or stopped. Nothing is quietly waved through.
+
+An *automated* pass is still an explicit pass, not a skip — provided it records an outcome and escalates what it cannot judge. A gate may be resolved by evidence rather than by a person when that evidence is sufficient and the result is logged to an accountable owner: a named run, against a recorded standard, is as accountable as a signature. The line between a pass and a skip is the recorded outcome, not who signed it. The exception is absolute: security always escalates to a human and is never auto-passed — a security finding is a hard stop, whatever the evidence says.
+
+**Consequence:** every gate produces a recorded outcome with an accountable owner — a person, or a named automated run — and security always stops for a person (see [11 Governance](./11-governance.md)).
+
+## 8. Tool-agnostic by construction
+
+The instructions you give the AI are plain text that reference files in the repository, not commands tied to one product. Enforcement of the gates lives in your build pipeline, not in the agent. This keeps the method portable: the agent is replaceable; the method is not.
+
+**Consequence:** the same project works whether the team uses one AI coding tool or another, and switching tools changes nothing structural.
+
+## 9. Two surfaces: the State you load, the Story you reference
+
+A method that fills the context window with its own documentation defeats itself — the agent rots before it reaches the work. So ADD keeps two doc surfaces and never loads both. The **State surface** is everything an agent loads to do the work each session: the `add` skill itself (its router `SKILL.md` and the one phase currently in play) together with the lean, current operational docs — `PROJECT.md` (the foundation), the active `MILESTONE.md`, the active `TASK.md`, and `state.json`. The **Story surface** is this book: the whole method, read once by a person to understand and trust ADD, and thereafter **never auto-loaded** into agent context — only referenced by a pointer. Depth lives on the Story surface; leanness is enforced on the State surface; they never compete for the same tokens.
+
+**Consequence:** the book can be as rich as trust requires without costing a single runtime token, while the loaded surface stays small enough never to rot. It is why the guideline block in `CLAUDE.md`/`AGENTS.md` *points* to `add.py status` and `PROJECT.md` rather than copying them.
+
+---
+
+> **The principles, compressed.** Steer before you accelerate. Trust evidence, not impressions. Keep the decisions, throw away the code. Loop freely, but never skip silently. Load the State; reference the Story. Grant the AI only as much autonomy as you can verify.