@pilotspace/add 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to the ADD method (`@pilotspace/add` on npm,
+`pilotspace-add` on PyPI) are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/); versions follow semver.
+
+## [1.1.0] — 2026-06-05
+
+Production-ready enforcement: the gates are now verified by machinery distinct
+from the agent, and any AI agent can follow the method through the CLI alone.
+
+### Added
+- **`add.py audit [--json]`** — judgment-free, read-only verification that
+  human seams left well-formed records: a named human at every contract freeze,
+  exactly one gate outcome per done task, a human reviewer wherever the
+  security line carries a `NOTE`/`⚠` marker, no waivers on security. Exit 0
+  clean / exit 1 with `{task, code, detail}` findings.
+- **Seam audit in CI** — a `seam-audit` job (this repo) plus a copy-paste
+  workflow for consumer projects (GETTING-STARTED "Enforce the seams in CI"):
+  a malformed seam record fails CI on a machine the agent does not control
+  (*never self-gate*, enforced).
+- **The mechanized high-risk guard** — declare `risk: high` in a TASK.md
+  header and the engine refuses to complete the task (`PASS`/`RISK-ACCEPTED`)
+  until the dial is lowered to `autonomy: conservative`; error and audit
+  finding `unguarded_high_risk_auto`. Judging *what* is high-risk stays human;
+  the declared combination is enforced. `HARD-STOP` is never blocked.
+- **Agent portability** — `add.py guide` now names the exact phase-guide file
+  to read (`guide  : .claude/skills/add/phases/<n>-<phase>.md`, never a dead
+  pointer; additive `"guide"` key in `--json`), and the AGENTS.md/CLAUDE.md
+  block routes any agent — Claude, Cursor, Copilot, Codex — through the CLI
+  alone.
+- **The freeze review checklist** — six ⚠-first lines inside the contract
+  phase guide that aim the human's one approval (intent · cases · shape ·
+  risk declaration · tests), never a second gate.
+
+### Changed
+- GitHub Actions bumped off the deprecated Node-20 runtimes
+  (checkout v5, setup-python v6, setup-node v5).
+- GETTING-STARTED: CI enforcement section + `guide  :` orientation.
+
+## [1.0.0] — 2026-06-04
+
+First public release: the seven-phase flow (specify → scenarios → contract →
+tests → build → verify → observe) driven by one `TASK.md` per task, the
+`add.py` state tracker (init · status · guide · report · check · gates ·
+milestones · competency deltas · fold), the `add` skill for Claude Code, and
+the full method book (`.add/docs/`). Installable via
+`npx @pilotspace/add init` or `pip install pilotspace-add`.

package/GETTING-STARTED.md

@@ -42,20 +42,35 @@ contract → review the result.** Everything between is the agent.
 
 ## 0 · Prerequisites
 
-- **Node.js ≥ 16** (to install) and **Python 3.12+** (the tool is stdlib-only).
+- **Python 3.10+** — required; the tool itself is stdlib-only (no pip dependencies).
+- **One installer**, whichever you already have: **Node.js ≥ 18** (for `npx`) *or*
+  **pip** (Python). Both install the exact same `.add/` runtime.
 - A project folder. It can be empty or an existing repo.
 
+> **Windows:** use `py` wherever this guide writes `python3` (the Python launcher on
+> Windows) — e.g. `py .add\tooling\add.py status`. Both installers handle the install
+> step for you; only the by-hand `add.py` commands below differ.
+
 ---
 
 ## 1 · Install
 
-From your project root:
+From your project root, pick **one** path — both produce the same install:
+
+**Option A — npm (Node.js ≥ 18):**
 
 ```bash
 npx @pilotspace/add init --name "My App" --stage prototype
 ```
 
-This creates `.add/` (your runtime), drops the `add` skill into
+**Option B — pip (Python 3.10+):**
+
+```bash
+pip install pilotspace-add
+pilotspace-add init --name "My App" --stage prototype
+```
+
+Either one 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`.
@@ -87,7 +102,9 @@ 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.
+to run once that phase is done. Its `guide  :` line names the phase-guide file to
+read for the current phase (`.claude/skills/add/phases/…` — plain markdown), which is
+how **any** agent — Claude, Cursor, Copilot, Codex — follows ADD through the CLI alone.
 
 ---
 
@@ -211,6 +228,51 @@ code 0 means healthy — handy as a CI gate.
 
 ---
 
+## Enforce the seams in CI
+
+`add.py audit` re-verifies every recorded human gate on your board — a named
+human at each contract freeze, exactly one gate outcome per done task, a human
+reviewer wherever the security line carries a note. It exits non-zero naming
+the task and the finding, which makes it a CI gate: enforcement runs on a
+machine the agent does not control, so the agent can never stamp its own work
+green (*never self-gate*).
+
+Drop this workflow into `.github/workflows/seam-audit.yml`:
+
+```yaml
+name: seam-audit
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  seam-audit:
+    name: Seam audit (recorded human gates)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Audit recorded human seams
+        run: python3 .add/tooling/add.py audit
+```
+
+The command is the same one you can run locally — the installer already placed
+`add.py` at `.add/tooling/add.py`, and the audit is read-only (it never edits
+your board). A red `seam-audit` job means a seam record is malformed or a
+security note was left to the auto-gate; fix the record (or escalate the gate
+to a human), never the auditor.
+
+---
+
 ## 6 · Resume next session
 
 Close your laptop, come back tomorrow, run:

package/README.md

@@ -39,8 +39,8 @@ npx @pilotspace/add init --name "My App" --stage prototype
 
 ```bash
 # Python / pip
-pip install add-method
-add-method init --name "My App" --stage prototype
+pip install pilotspace-add
+pilotspace-add init --name "My App" --stage prototype
 ```
 
 **New here?** Follow the [10-minute Quickstart](./GETTING-STARTED.md) — it walks

package/bin/cli.js

@@ -10,15 +10,17 @@
  *   <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.
+ * It DROPS FILES ONLY — it does NOT run `add.py init`. Initialisation is deferred to
+ * the AI (via `/add`, which runs `init --await-lock` to arm the v12 lock-down gate) or
+ * to a CLI user. A pre-run plain init would grandfather-lock the gate before `/add` runs
+ * AND consume the brownfield signal in the terminal, where the AI never sees it.
  *
- * Zero npm dependencies. Designed for failure: verifies sources, never clobbers
- * an existing state.json, and degrades gracefully if python3 is absent.
+ * Zero npm dependencies, no Python needed at install time. Designed for failure:
+ * verifies sources exist before copying, never clobbers an existing skill.
  */
 
 const fs = require("fs");
 const path = require("path");
-const { spawnSync } = require("child_process");
 
 const PKG_ROOT = path.resolve(__dirname, "..");
 
@@ -39,24 +41,23 @@ function parseArgs(argv) {
   return args;
 }
 
-function copyDir(src, dest, { skipIfExists } = {}) {
+function copyDir(src, dest, { skipIfExists, cleanReplace } = {}) {
   if (!fs.existsSync(src)) fail("missing packaged source: " + src);
   if (skipIfExists && fs.existsSync(dest)) {
     warn(dest + " exists — leaving it untouched");
     return;
   }
+  // Clean replace: drop a stale dest before copying so a `--force` re-install can
+  // never leave orphaned files from a previous version behind. fs.cpSync merges
+  // (it never removes), so without this `--force` is a merge, not a replace. Mirrors
+  // _installer.py's `shutil.rmtree(skill_dest)` so npm and pip behave identically.
+  if (cleanReplace && fs.existsSync(dest)) {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
   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);
@@ -66,7 +67,7 @@ function cmdInit(args) {
   copyDir(
     path.join(PKG_ROOT, "skill", "add"),
     path.join(target, ".claude", "skills", "add"),
-    { skipIfExists: !args.force }
+    { skipIfExists: !args.force, cleanReplace: args.force }
   );
   log("  ✓ skill      -> .claude/skills/add/");
 
@@ -88,27 +89,18 @@ function cmdInit(args) {
     { 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.");
+  // NO step 4: the installer DROPS FILES ONLY. Initialisation is deferred to the AI
+  // (via `/add`) or a CLI user — a pre-run plain `add.py init` would grandfather-lock
+  // the v12 lock-down gate before `/add` runs (see file header). So no Python is run here.
+  log("\nDone. The `add` skill + tooling are installed (no project state yet — that's intentional).");
+  log("Next:  open Claude Code, run `/add`, and say what you want to build — the agent");
+  log("       sets up the foundation, sizes it into a milestone, and drives the build with you;");
+  log("       you sign off once, at the lock-down.");
+  log("");
+  log("Prefer the CLI / not using Claude Code? Initialise it yourself (this arms the lock-down):");
+  const launcher = process.platform === "win32" ? "py" : "python3";
+  log(`  ${launcher} .add/tooling/add.py init --await-lock --stage ${args.stage}` +
+      (args.name ? ` --name "${args.name}"` : ""));
 }
 
 function main() {

package/docs/02-the-flow.md

@@ -6,7 +6,7 @@
 
 ## The flow
 
-AIDD is one repeatable flow of six steps, followed by an observation loop. People perform the first four steps (with AI assistance), the AI performs the fifth (under direction), and people perform the sixth.
+AIDD is one repeatable flow of **seven steps**: six build the feature — Specify → Scenarios → Contract → Tests → Build → Verify — and the seventh, **Observe**, feeds what production teaches back into the next Specify. In the default flow the AI drafts the front (steps 1–4) and a person approves it **once**, at the contract freeze; the AI performs the Build; and Verify is resolved on evidence under `autonomy: auto`, with a person owning any residue. (See [11 Governance](./11-governance.md) for the autonomy dial and the one-approval seam.)
 
 ![The ADD flow — a solid forward spine Specify→Scenarios→Contract→Tests→Build→Verify→Observe, with dashed backward-correction arrows (any phase may return to an earlier one), a Tests⇄Build red/green engine, and Observe looping back to the next Specify](./add-flow.png)
 
@@ -47,6 +47,8 @@ flowchart LR
 
 The shape is deliberate: the human-led steps establish direction, a frozen contract forms the seam in the middle, and the AI-led build runs fast and safely on the far side because everything it needs is already fixed.
 
+> **What changed in v7 (the diagrams above show the structural spine, which is unchanged).** The *steps* and their order are exactly as drawn — only **who resolves them** moved. The AI now drafts the whole front (steps 1–4) and a person approves it **once**, at the contract freeze (not a sign-off at each step); and **Verify is auto-gated on evidence** under `autonomy: auto` (the default), escalating security — always a `HARD-STOP` — and other residue to a person. Lower the dial to `conservative` to keep a human at the Verify gate. See [11 Governance](./11-governance.md).
+
 ## Why the order is the order
 
 Each step produces exactly one artifact, and each artifact is the input to the next step. The order is not a preference; it is a dependency chain.
@@ -68,12 +70,13 @@ The flow runs in two directions under two rules that never conflict. **Backward
 
 | Step | Person's job | AI's job |
 |------|--------------|----------|
-| 1 Specify | decide and confirm the rules | draft; list assumptions to confirm |
-| 2 Scenarios | decide what "correct" looks like | draft scenarios |
-| 3 Contract | approve and freeze the shape | generate the contract and mocks |
-| 4 Tests | set the targets | generate failing tests |
+| 1 Specify | confirm the rules (part of the one approval) | draft; list assumptions to confirm |
+| 2 Scenarios | confirm what "correct" looks like (part of the one approval) | draft scenarios |
+| 3 Contract | **approve & freeze the whole bundle (§1–§4) once — the seam** | draft the contract and mocks |
+| 4 Tests | confirm the targets (part of the one approval) | draft the failing tests |
 | 5 Build | direct in small batches | implement until tests pass |
-| 6 Verify | confirm via evidence + judgment | (none — this is the human check) |
+| 6 Verify | own the residue (security · concurrency · architecture); approve when `conservative` | gather evidence; **auto-PASS on complete evidence** under `autonomy: auto` |
+| 7 Observe | read the signal; fold confirmed deltas into PROJECT.md | run behind a flag; emit competency deltas |
 
 ## What survives, and what is disposable
 

package/docs/04-step-2-scenarios.md

@@ -6,6 +6,8 @@
 > **Produces:** `features/<name>.feature`.
 > **Person's job:** decide what "correct" looks like in concrete situations. **AI's job:** draft the scenarios.
 
+> **Part of the one-approval front (v7).** In the default flow these scenarios are drafted by the AI alongside the spec, contract, and failing tests as **one bundle**, approved by a person **once**, at the contract freeze — not signed off step by step. This chapter is how to get the scenarios *right*; [05 Contract](./05-step-3-contract.md) is where the bundle is frozen. See [11 Governance](./11-governance.md).
+
 ---
 
 ## Why turn rules into scenarios

package/docs/05-step-3-contract.md

@@ -6,6 +6,8 @@
 > **Produces:** `contracts/<name>.md` (plus a mock and contract tests).
 > **Person's job:** approve and freeze the shape. **AI's job:** generate the first draft, the mock, and the contract tests.
 
+> **The one approval lands here (v7).** In the default flow the AI drafts the whole front — spec, scenarios, this contract, and the failing tests — as **one bundle**, and a person gives a **single approval at this freeze**. Freezing the contract is the one human gate of the front, not the third of three sign-offs; reject any part and the whole bundle returns to draft (backward correction, not failure). See [11 Governance](./11-governance.md).
+
 ---
 
 ## The seam of the whole method

package/docs/06-step-4-tests.md

@@ -6,6 +6,8 @@
 > **Produces:** a failing (red) automated test suite.
 > **Person's job:** set the targets and coverage. **AI's job:** generate the tests.
 
+> **Part of the one-approval front (v7).** In the default flow these tests are drafted by the AI as part of the front **bundle** (spec · scenarios · contract · tests) and approved by a person **once**, at the contract freeze — the tests are part of what that single approval covers. They still must be **red before the build**. See [11 Governance](./11-governance.md).
+
 ---
 
 ## Why tests come before code

package/docs/08-step-6-verify.md

@@ -4,7 +4,7 @@
 
 > **Purpose:** confirm the result is correct and safe to release.
 > **Produces:** a reviewed change with a recorded outcome, ready to release.
-> **Person's job:** this entire step. There is no AI role here — it is the human check.
+> **Who resolves it:** set per task by the `autonomy:` header. Under `autonomy: auto` (the default) the run resolves the gate on evidence; under `conservative`, or for any residue, it is the human's check. **Security always escalates to a human.**
 
 ---
 
@@ -14,6 +14,15 @@ The build produced passing tests. That is necessary but not sufficient. Verifica
 
 This needs care, because it is easy to misread. "Not by inspection" does not mean "do not look at the code." It means the *basis* of trust is the passing evidence plus a deliberate check of the specific things tests cannot easily catch — not a general impression that the code reads plausibly. Plausibility is exactly the trap: AI code is frequently plausible and wrong. So verification has two parts: confirm the evidence, then check the known blind spots.
 
+## Who resolves Verify — the evidence auto-gate
+
+Verify can be resolved two ways, set per task by the `autonomy:` header (see [governance](./11-governance.md) and the autonomy dial):
+
+- **Auto (the default).** When `autonomy: auto`, the run resolves the gate on **evidence** rather than waiting for a person — but only when *all* of these hold: every test green, coverage not decreased, no test weakened and no contract edited, the convergence loops dry, and **no residue** (security, concurrency, or architecture). It records `PASS` as *auto-resolved*, naming the run as the accountable owner — an explicit pass, not a skip. This is principle 7: a gate may be resolved by evidence when that evidence is sufficient and the result is logged.
+- **Human.** When `autonomy: conservative`, or whenever the run finds residue it cannot judge, the gate stops for a person; the two parts below are theirs.
+
+**Security is always a `HARD-STOP` and is never auto-passed, at any autonomy level.** The two parts that follow — confirm the evidence, then check the blind spots — are what *either* resolver works through; the only question is whether a person or the recorded run signs the outcome.
+
 ## Part one — confirm the evidence
 
 - [ ] All tests pass.
@@ -49,7 +58,7 @@ A security finding is always a `HARD-STOP`; it is never waved through with a wai
 - [ ] Concurrency/timing of the risky operation is safe.
 - [ ] No exposed secrets, injection openings, or unexpected dependencies.
 - [ ] Layering and dependencies follow `CONVENTIONS.md`.
-- [ ] A person has reviewed and approved the change.
+- [ ] The change is approved — by a person, **or** (under `autonomy: auto`, no residue) auto-resolved by the run as the recorded accountable owner.
 - [ ] An outcome is recorded (`PASS` / `RISK-ACCEPTED` / `HARD-STOP`).
 
 ## Common mistakes

package/docs/09-the-loop.md

@@ -33,6 +33,24 @@ Every defect, surprise, or new need is written up as a change to the specificati
 
 This is also where the AI returns to a useful role: summarizing telemetry, clustering errors into themes, and drafting the proposed spec delta for a person to review. But the production decisions — what to roll back, what to prioritize — remain human.
 
+## Competency deltas and the foundation fold
+
+A spec delta feeds the *next feature*. But a loop also teaches the **method itself** — that the domain model missed a boundary, that a whole class of scenario was never tested, that a build convention helped or hurt. AIDD captures those as **competency deltas**: a single tagged learning, written in the Observe step, marking which of the five competencies it sharpens.
+
+| tag | competency | a delta here means you learned something about… |
+|-----|------------|--------------------------------------------------|
+| `DDD` | Domain | the domain model — an entity, rule, or boundary the spec assumed wrong |
+| `SDD` | Spec | what the feature must do or reject — a missing or wrong requirement |
+| `UDD` | UI/UX | the user-facing shape — a flow, affordance, or wording that misled |
+| `TDD` | Test | how we prove correctness — a missing scenario, a flaky or hollow test |
+| `ADD` | AI/build | how the AI builds — a harness, prompt, or convention that helped or hurt |
+
+Each delta is one tagged entry — `- [COMPETENCY · status] the learning (evidence: a pointer)` — and the evidence is **required**: a failing scenario, a production signal, a review note. No evidence means it is an opinion, not a delta. The AI **emits** deltas as `open`; it never folds its own. Folding is judgment, and judgment is the human's — the same verify/observe seam that keeps the AI from grading its own work.
+
+**The fold.** At milestone close (or on demand, when open deltas pile up), a person runs the fold ritual: **gather** every `open` delta across the milestone's tasks, **group** them by competency, **propose** the exact foundation edit for each, **confirm** with the human one by one, then **write** — append-only — flipping each delta to `folded` (merged) or `rejected` (considered and deliberately not merged, left in place so the trail survives), and bumping the `foundation-version:` marker. `DDD`/`SDD`/`UDD` deltas fold into the matching section of `PROJECT.md`; `TDD`/`ADD` fold into `CONVENTIONS.md` (they sharpen the engine, not the product); and **every** fold also appends one row to `PROJECT.md` §Key Decisions — the universal, auditable record of what the foundation learned.
+
+**Tooling.** `add.py deltas` lists every open delta across the project (so nothing waiting to be folded is invisible); `add.py check` lints each delta's well-formedness — known competency tag, valid status, non-empty evidence. There is deliberately **no `add.py fold`**: the engine stays judgment-free, and the ritual lives with the human who owns it.
+
 ## Re-entrancy: the loop is the whole point
 
 Two principles converge here. *The flow is re-entrant* — any step can send you back to an earlier one — and *the flow is a loop* — production feeds the next specification. Together they mean the artifacts you built are never "finished"; they are living documents that the next cycle refines.

package/docs/10-setup-and-stages.md

@@ -6,26 +6,34 @@ This chapter covers two operational matters: what you set up once per project, a
 
 ---
 
-## One-time setup
+## Setup: the AI drafts, you lock down
 
-Before the first feature, establish the foundation the whole project depends on. Done once, it makes every later checkpoint enforceable automatically.
+Before the first feature, the project needs a foundation — but standing it up is no longer your chore. Point ADD at the repo and **the AI does the drafting**: it runs `init` itself, reads what is there, and fills the foundation the whole project depends on. Your single act is the **lock-down** — the one human gate that freezes it.
+
+**What the AI drafts.** From an existing codebase it works **silently** — the code answers the questions a setup interview would ask. On an empty repo it runs a short **four-lens interview** (domain · spec · users · decisions), then drafts. Either way it fills the survivor layer — the files that outlive all code — and drafts the first milestone's scope and the first task's candidate contract:
 
 | Item | File | Purpose |
 |------|------|---------|
-| Repository + pipeline | — | runs the gates on every change |
+| Foundation | `PROJECT.md` | domain · active spec · UI/UX · key decisions — the context every task reads first |
 | Conventions | `CONVENTIONS.md` | naming, layout, language, formatter — the survivor layer |
 | Model record | `MODEL_REGISTRY.md` | which AI model and version the project uses, for reproducibility and audit |
 | Dependency allow-list | `dependencies.allowlist` | the packages the AI may use; the pipeline rejects others |
 | Prompt playbook | `playbook/` | the six prompts from [Appendix B](./appendix-b-prompts.md) |
+| Repository + pipeline | — | runs the gates on every change |
+
+Every drafted decision is tagged **evidence-grounded** (read from the code) or **guessed** (thin or inferred) and listed least-sure-first in a `SETUP-REVIEW.md`, so the one signature you give is informed rather than a rubber stamp.
+
+**The lock-down.** The AI presents `SETUP-REVIEW.md`; you check the `guessed` rows; you **lock** — once. That single act freezes the foundation, the first scope, and the first contract together. It is the setup-altitude analog of the [contract freeze](./05-step-3-contract.md), and it doubles as the first task's contract approval — so there is no separate sign-off. Before the lock the engine lets the AI draft but refuses to cross into build; after it, the build opens.
 
 **Setup exit check**
 
+- [ ] Foundation + survivors drafted (brownfield: from the code, evidence-tagged; greenfield: from the interview, gaps flagged `guessed`).
+- [ ] `SETUP-REVIEW.md` lists every drafted decision least-sure-first.
+- [ ] The model is pinned; the allow-list exists and the pipeline fails on any package outside it.
 - [ ] The pipeline runs and is green on the empty skeleton.
-- [ ] The model is pinned.
-- [ ] The allow-list exists and the pipeline fails on any package outside it.
-- [ ] The playbook is present.
+- [ ] The human **locked down** — and only then did the first feature's build open.
 
-Do not start a feature until the pipeline is green. It is the thing that will enforce every later exit check without anyone having to remember to.
+Do not start a feature until the pipeline is green and the foundation is locked. The lock-down turns the AI's draft into committed direction; the pipeline enforces every later exit check without anyone having to remember to.
 
 ---
 
@@ -73,3 +81,24 @@ The durable thing is never the code:
 | MVP → Production | nothing | everything; the code is real and is hardened |
 
 The survivor layer thickens as you move right: a prototype leaves you a validated design; a proof of concept adds a proven approach and a contract; the MVP adds real, kept code. By production, you are hardening, not rebuilding.
+
+---
+
+## Parallel streams (opt-in)
+
+The default is one task at a time. But when a milestone holds several tasks whose dependencies are already `PASS` and a reviewer is ready, you may run them **concurrently** — one worker per ready task, each building behind its own frozen contract.
+
+**Be honest about the gain.** With one human reviewer you cannot beat `review_time × N_tasks`; the human-led seams are serial. So the win is **not throughput** — it is that the reviewer is *never blocked waiting on a build*. While a person reviews task A's front, the builds for B, C, and D run behind *their* frozen contracts. You hide build latency under human latency; do not promise more.
+
+**Two queues, no new state** — both read from `add.py status`:
+
+- **READY-QUEUE** — tasks in the active milestone where the phase is not `done` and every dependency already reads `gate=PASS`. These are the only tasks a worker may pick up; a task finishing `PASS` unblocks its dependents on the next `status`.
+- **REVIEW-QUEUE** — the irreducibly serial part: the **one-approval front** (contract freeze) and any **Verify escalation**. One human, one queue, presented one at a time — never a batch that invites a rubber stamp.
+
+**The autonomy dial is the throttle.** At `conservative`, both gates queue on the human (pure pipelining — builds overlap, nothing auto-resolves). At `auto` (the default), only the front seam and residue escalations queue; Verify auto-PASSes on evidence, so real concurrency follows. The floor never drops below **one human approval per task, at the contract seam**.
+
+**Design for failure (required).** Lease each task to its worker with a timeout — if a worker dies, release the claim back to READY rather than trusting partial work. A worker that hits a stop-and-escalate blocks only its own task; siblings keep running. And if several workers fail in one wave, trip a circuit-breaker and fall back to sequential — repeated failure means the scope was wrong, not the parallelism.
+
+**The hard boundary.** The orchestrator owns every shared write — `state.json`, `MILESTONE.md`, and each `add.py advance`/`gate` call (always with the explicit task slug). A worker owns only its own task directory and is isolated in a git worktree, so concurrent builds cannot collide. Merge is **serial**: bring worktrees back one at a time and run an **integration Verify** for the concurrency and architecture conflicts that two-green-in-isolation tasks can still produce — automation never auto-passes that step.
+
+The full, agent-agnostic worker contract (the prompt a worker runs) and the per-runner spawn adapter live in the skill's `streams.md`; this section is the *why* and the safety frame, not the operational recipe.

package/docs/13-adoption.md

@@ -10,7 +10,7 @@ How a team starts using AIDD, and how a new person becomes productive in it.
 
 Adopt the method on one real product, not as an all-at-once mandate.
 
-1. **Days 1–15 — Set the foundation.** Stand up the one-time setup on one pilot service: conventions, glossary, dependency allow-list, model record, and the prompt playbook ([Appendix B](./appendix-b-prompts.md)).
+1. **Days 1–15 — Lock the foundation.** On one pilot service, let the AI draft the foundation — conventions, glossary, dependency allow-list, model record — from the existing code (or the four-lens interview if greenfield), then **lock it down** with one signature. The prompt playbook is [Appendix B](./appendix-b-prompts.md).
 2. **Days 16–45 — One feature, end to end.** Run a single feature through the whole flow at the **Express** profile. Capture friction; tune the prompts' golden cases as you go.
 3. **Days 46–75 — Turn on the gates.** Wire the three reports and the gate-fail protocol into the pipeline; introduce the autonomy ladder at the generate-behind-gate level.
 4. **Days 76–90 — Promote.** Move the pilot to the **Standard** profile, draft the **Regulated** variant for any compliance-bound product, and publish the prompts as a shared, versioned playbook.
@@ -53,7 +53,7 @@ Switching tools changes the discovery convention and nothing structural.
 | Role | First-week task |
 |------|------------------|
 | Product / Domain | run the Specify prompt on a real input; produce a glossary you would defend |
-| Architect / Lead | stand up setup and freeze one contract; wire the architecture check into the pipeline |
+| Architect / Lead | review the AI's setup draft and lock it down (the first contract freezes with it); wire the architecture check into the pipeline |
 | Engineer (Senior) | run the Build prompt on one small task; produce a full evidence bundle |
 | Engineer (Junior) | take a handed-over spec; make a red test green without weakening it |
 | QA / Test | convert one rule into a scenario, then a failing test |

package/docs/14-foundation.md

@@ -74,7 +74,10 @@ one short section each, plus an append-only record of key decisions:
 Keep it to one screen. If a section wants to grow into a manual, that is a signal
 the detail belongs in a milestone or a contract, not the foundation. The foundation
 is the *thin, durable* context the engine reads first — not a place to relocate the
-work.
+work. And you do not hand-write it: at setup the AI **drafts** all four sections —
+silently from an existing codebase, or from a short four-lens interview on a
+greenfield repo — and a single human **lock-down** freezes that draft as committed
+direction (the setup-altitude analog of a contract freeze).
 
 ## How it feeds the engine — and takes feedback back
 
@@ -105,12 +108,17 @@ life of the product, owned above any single milestone.
 A milestone is a *version bump* to the foundation, not a fresh start: when it
 closes, fold what it validated into `PROJECT.md` (a decision, a settled domain
 term, a confirmed user journey) and open the next one against the same, now-richer,
-ground.
+ground. The fold is not informal: each loop emits **competency deltas** (tagged
+`DDD · SDD · UDD · TDD · ADD`) in its Observe step, and at milestone close a person
+gathers the open ones and folds them — append-only, with the `foundation-version:`
+bumped — into the foundation. See [09 · The loop](./09-the-loop.md#competency-deltas-and-the-foundation-fold)
+for the grammar, the ritual, and the tooling (`add.py deltas`, `add.py check`).
 
 ## In the tooling
 
-- `add.py init` scaffolds `PROJECT.md` as a survivor file — and, like every
-  survivor file, **never overwrites a hand-edited one**.
+- `add.py init` scaffolds `PROJECT.md` as a survivor file; the AI then drafts its
+  content and a single human **lock-down** (`add.py lock`) freezes it. Like every
+  survivor file, `init` **never overwrites a hand-edited one**.
 - `add.py status` shows a one-line pointer to the foundation, so a fresh session
   re-orients on context before code.
 - The guideline block written into `CLAUDE.md` / `AGENTS.md` tells any agent the

package/docs/appendix-f-requirements-matrix.md

@@ -12,7 +12,7 @@ This appendix maps every AIDD document to a three-level project hierarchy, so th
 |-------|-----------|--------------|-------|
 | **Project** | the whole product or engagement | the survivor layer — documents created once and kept for the life of the product | all milestones |
 | **Milestone** | a stage or release | one pass of the flow at a chosen depth: Prototype, POC, MVP, or Production-Ready; groups many tasks | many tasks |
-| **Task** | one feature through the flow | a single pass of Specify → … → Verify; the smallest unit with its own gate records | the six steps |
+| **Task** | one feature through the flow | a single pass of Specify → … → Verify → Observe; the smallest unit with its own gate records | the seven steps |
 
 A **project** sets up the survivor-layer documents once. A **milestone** is a depth-bounded goal that groups tasks and has its own entry and exit document gates. A **task** is one feature, and it produces the per-feature artifacts.
 
@@ -87,7 +87,7 @@ Which documents must exist, and at what depth, to **exit** each milestone. Depth
 
 ---
 
-## Matrix 3 — Documents required per task (the six steps)
+## Matrix 3 — Documents required per task (the seven steps)
 
 Every task, regardless of milestone, produces this artifact chain. The depth varies by milestone (Matrix 2); the *sequence and exit gate* do not.
 
@@ -98,9 +98,10 @@ Every task, regardless of milestone, produces this artifact chain. The depth var
 | 3 Contract | `contracts/<task>.md` | frozen + contract tests green | [05](./05-step-3-contract.md) |
 | 4 Tests | `tests/<task>_*` | one test per scenario, red first | [06](./06-step-4-tests.md) |
 | 5 Build | source code + evidence bundle | all tests green, nothing weakened | [07](./07-step-5-build.md) |
-| 6 Verify | gate outcome record | `PASS` / `RISK-ACCEPTED` / `HARD-STOP` | [08](./08-step-6-verify.md) |
+| 6 Verify | gate outcome record | `PASS` / `RISK-ACCEPTED` / `HARD-STOP` (auto-resolved on evidence under `autonomy: auto`; security always escalates) | [08](./08-step-6-verify.md) |
+| 7 Observe | `TASK.md` §7 OBSERVE block | released behind a flag; scenario-monitors live; spec delta + competency deltas captured | [09](./09-the-loop.md) |
 
-A task is **done** only when all six documents exist and the Verify record reads `PASS` (or a signed `RISK-ACCEPTED`). See the master shippable checklist in [Appendix E](./appendix-e-checklists.md).
+A task is **done** when the build's documents exist and the Verify record reads `PASS` (or a signed `RISK-ACCEPTED`); the seventh step — **Observe** (§7) — then runs in production and feeds the next loop's Specify. See the master shippable checklist in [Appendix E](./appendix-e-checklists.md).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "ADD (AI-Driven Development) — a minimal, state-tracked Claude Code skill that drives every feature through Specify → Scenarios → Contract → Tests → Build → Verify → Observe. Ships the AIDD book as its trust layer.",
   "bin": {
     "add": "bin/cli.js"
@@ -9,7 +9,8 @@
     "access": "public"
   },
   "scripts": {
-    "test": "python3 -m unittest discover -s tooling -p 'test_*.py'"
+    "test": "python3 -m unittest discover -s tooling -p 'test_*.py'",
+    "prepublishOnly": "python3 -m unittest discover -s tooling -p 'test_packaging.py'"
   },
   "files": [
     "bin/",
@@ -18,7 +19,8 @@
     "tooling/templates/",
     "docs/",
     "README.md",
-    "GETTING-STARTED.md"
+    "GETTING-STARTED.md",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "ai-driven-development",