@pilotspace/add 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,47 @@ 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.3.0] — 2026-06-13
+
+The render-ready-foundation release: a UI project now gets a lintable design
+foundation the AI drafts from, a build's declared scope is enforced as a gate,
+every command names who drives the next step, and the new update command
+refreshes an installed project in place. All additive; no breaking changes
+(SemVer MINOR).
+
+### Added
+- **Render-ready UDD foundation** — a `DESIGN.md` prose front-door plus a JSON
+  foundation (3-layer design tokens · a component catalog · flat prototype
+  content trees) the AI drafts UI from, wired into 0-setup. `add.py check` now
+  lints the named set under `.add/design/`, going red with a named code on any
+  layer, catalog, tree, or cross-file token-resolution violation — and staying
+  silent when a project has no design set, so non-UI projects are unaffected.
+  A `udd-tokens.md` + `udd-catalog.md` pair documents the compact-DTCG dialect
+  and the json-render render recipe.
+- **The scope gate** — a task's `§5 Scope (may touch)` declaration is frozen
+  into a snapshot at tests→build and enforced at the gate: an out-of-scope touch
+  heals the task back to BUILD for an honest redo (counting against a per-task
+  cap), while erased gate evidence fails closed. Scope creep can no longer ride a
+  green suite into a merge.
+- **Engine next-step footer + the driver marker** — every completing command now
+  prints exactly one engine-sourced `next:` line, and names who owns it:
+  `[you drive]` when the AI proceeds, `[human gate]` at a decision point. The
+  driver marker resolves from one place (autonomy × phase), so the next step and
+  its owner are never ambiguous across a session.
+- **The `update` command** — `npx @pilotspace/add update` (and the
+  `pilotspace-add update` command on PyPI) re-materializes the managed layer
+  (skill · tooling · docs) to the installed package version without a re-install.
+  It never touches your work — `state.json`, `PROJECT.md`, milestones, tasks, and
+  archive are preserved (state is backed up first regardless) — is idempotent via
+  a `.add-version` stamp, and offers `--check` to report version drift without
+  writing.
+
+### Changed
+- The foundation self-improved across these milestones: closing
+  `udd-design-foundation` folded its OBSERVE backlog into the versioned
+  CONVENTIONS/PROJECT foundation (foundation-version 29), sharpening the
+  contract-completeness, adversarial-refute, and engine-pin conventions.
+
 ## [1.2.0] — 2026-06-10
 
 The decision-arc release: the method now narrates the build as one continuous

package/GETTING-STARTED.md

@@ -63,6 +63,28 @@ handoff — from here on it's conversation, not terminal commands.
 > Why stages exist: the steps never change, only how *deeply* you run them.
 > See `.add/docs/10-setup-and-stages.md`.
 
+### Updating to a newer ADD — no re-install
+
+When a new ADD version ships, refresh a project in two steps: bump the package
+(your package manager), then re-materialize it into the project with `update`:
+
+```bash
+# npm — one shot (npx fetches latest, then re-materializes into this project):
+npx @pilotspace/add@latest update
+
+# pip — one shot via pipx (the npx analog: fetch latest + run):
+pipx run pilotspace-add update
+
+# …or plain pip, in two steps:
+pip install -U pilotspace-add && pilotspace-add update
+```
+
+`update` clean-replaces the managed layer (`skill` · `.add/tooling` · `.add/docs`)
+and **never touches your work** — `state.json`, `PROJECT.md`, milestones, tasks and
+archive are left exactly as they were (it backs `state.json` up first regardless). It
+is idempotent (same version twice is a no-op) and writes a `.add/.add-version` stamp.
+Run `… update --check` to see whether a project is behind the installed package.
+
 ---
 
 ## 2 · Your first feature — talk to the agent

package/bin/cli.js

@@ -32,10 +32,11 @@ function parseArgs(argv) {
   // stage/name stay null unless EXPLICITLY passed — the engine's own `init`
   // defaults the stage and infers the name from the folder, so the manual-init
   // hint only echoes flags the user actually chose (shortest true command).
-  const args = { _: [], force: false, stage: null, name: null };
+  const args = { _: [], force: false, check: false, stage: null, name: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--force") args.force = true;
+    else if (a === "--check") args.check = true;
     else if (a === "--stage" || a === "--name") {
       const v = argv[++i];
       // fail loudly on a trailing/abutting flag — never silently drop a value
@@ -112,6 +113,82 @@ function cmdInit(args) {
       (args.name ? ` --name "${args.name}"` : ""));
 }
 
+// --- update: re-materialize the managed layer without a re-install -----------
+// The managed trees (ship-controlled). `update` clean-replaces each, so a file removed
+// upstream leaves no orphan — and never touches .add/state.json, PROJECT.md, milestones,
+// tasks, or archive (user data). Pure file-copy (npm <-> pip parity with _installer.py).
+const MANAGED = [
+  ["skill/add", [".claude", "skills", "add"], false],
+  ["tooling", [".add", "tooling"], true],
+  ["docs", [".add", "docs"], false],
+];
+const STAMP_FILE = ".add-version";
+
+function pkgVersion() {
+  try { return require(path.join(PKG_ROOT, "package.json")).version; }
+  catch (_e) { return "0.0.0"; }
+}
+
+function readStamp(addDir) {
+  const p = path.join(addDir, STAMP_FILE);
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch (_e) { return null; }
+}
+
+function writeStamp(addDir, version) {
+  fs.mkdirSync(addDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(addDir, STAMP_FILE),
+    JSON.stringify({ version: version, channel: "npm", installed_at: new Date().toISOString() }, null, 2) + "\n"
+  );
+}
+
+function cleanReplaceTree(src, dest, stripTests) {
+  if (!fs.existsSync(src)) fail("missing packaged source: " + src);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  if (fs.existsSync(dest)) fs.rmSync(dest, { recursive: true, force: true });
+  fs.cpSync(src, dest, { recursive: true });
+  if (stripTests) {
+    fs.rmSync(path.join(dest, "__pycache__"), { recursive: true, force: true });
+    for (const entry of fs.readdirSync(dest)) {
+      if (/^test_.*\.py$/.test(entry)) fs.rmSync(path.join(dest, entry), { force: true });
+    }
+  }
+}
+
+function cmdUpdate(args) {
+  const target = path.resolve(args._[0] || ".");
+  const addDir = path.join(target, ".add");
+  if (!fs.existsSync(path.join(addDir, "tooling")) && !fs.existsSync(path.join(addDir, "state.json"))) {
+    fail("no ADD project at " + target + " (.add/ not found) — run `init` first");
+  }
+  const version = pkgVersion();
+  const stamp = readStamp(addDir);
+  const cur = stamp && stamp.version ? stamp.version : null;
+
+  if (args.check) {
+    if (cur === version) log("ADD is current: project and package both at " + version + ".");
+    else if (cur === null) log("ADD project is unstamped; installed package is " + version + ". Run `update`.");
+    else log("ADD update available: project on " + cur + ", package is " + version + ". Run `update`.");
+    return;
+  }
+  if (cur === version && !args.force) {
+    log("ADD already at " + version + " — nothing to update (use --force to re-materialize).");
+    return;
+  }
+  // design-for-failure: back up state BEFORE touching anything.
+  const stateFile = path.join(addDir, "state.json");
+  if (fs.existsSync(stateFile)) {
+    fs.copyFileSync(stateFile, path.join(addDir, "pre-update-state.bak.json"));
+  }
+  for (const [sub, destParts, stripTests] of MANAGED) {
+    cleanReplaceTree(path.join(PKG_ROOT, sub), path.join(target, ...destParts), stripTests);
+  }
+  writeStamp(addDir, version);
+  log("ADD updated " + (cur || "(unstamped)") + " -> " + version +
+      " · skill · tooling · docs refreshed · your project state untouched.");
+}
+
 function main() {
   const argv = process.argv.slice(2);
   const cmd = argv[0] && !argv[0].startsWith("--") ? argv.shift() : "init";
@@ -120,9 +197,14 @@ function main() {
     case "init":
       cmdInit(args);
       break;
+    case "update":
+      cmdUpdate(args);
+      break;
     case "help":
     case "--help":
-      log("usage: npx @pilotspace/add init [targetDir] [--force] [--stage <s>] [--name <n>]");
+      log("usage: npx @pilotspace/add <init|update> [targetDir] [--force] [--check]");
+      log("  init    install the ADD skill + tooling + book into a project");
+      log("  update  re-materialize skill/tooling/docs to this package version (preserves your state)");
       break;
     default:
       fail("unknown command '" + cmd + "'. Try: npx @pilotspace/add init");

package/docs/02-the-flow.md

@@ -8,10 +8,13 @@
 
 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 specification bundle (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 level and the one-approval decision point.)
 
+**Before those seven steps comes a phase-0 preamble: `ground`.** Before it specifies anything, the AI gathers the real current codebase the task touches — the actual files, symbols, signatures, patterns, and conventions — into a lean §0 *grounding map*, surfacing the **anchors** the frozen contract will later cite. Ground is AI-owned and adds no new approval (the one approval stays at the contract freeze); it aims the specification bundle at reality instead of assumption, so the contract, tests, and build are grounded in the code as it actually is. The seven steps keep their numbering and brand — ground precedes them as step 0 (it is drawn as node 0 in the diagram below).
+
 ![The ADD flow — a solid primary flow 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)
 
 ```mermaid
 flowchart LR
+  S0["0 Ground<br/>the real codebase"] --> S1["1 Specify<br/>the rules"]
   S1["1 Specify<br/>the rules"] --> S2["2 Scenarios<br/>pass/fail cases"]
   S2 --> S3["3 Contract<br/>freeze the shape"]
   S3 --> S4["4 Tests<br/>failing-first (red)"]
@@ -27,7 +30,7 @@ flowchart LR
   classDef machine fill:#E6F1FB,stroke:#185FA5,color:#042C53;
   class S1,S2 human;
   class S3,S4 decision;
-  class S5,S6 machine;
+  class S0,S5,S6 machine;
 ```
 
 > **Solid arrows are the primary flow** — you never start a phase before its input exists (forward-skip forbidden). **Dashed arrows are backward correction** — any phase may return to an earlier one to repair its artifact (the long loop, Observe → Specify, is the same rule at milestone scale). The tight Tests ⇄ Build cycle is the per-feature red/green engine.

package/docs/03-step-1-specify.md

@@ -88,6 +88,8 @@ The defining instruction: *if a requirement is unclear, ask — do not resolve i
 - **Free-text errors.** Errors must be named codes, not sentences, so they can become scenarios and contract responses.
 - **Hidden assumptions.** If an assumption is not written down, it is not confirmed — it is a future bug with a delay timer.
 - **A flat list of "confirmed" assumptions.** Eight equal-looking ticks invite a reflex approval. Rank them; flag the one or two that are load-bearing. An unranked list hides the risk inside the noise.
+- **"Existing behavior" claims without a citation.** An assumption row that asserts "this is how X works today" is describing intent, not code. Any wiring claim or assumption that depends on the current state of an existing path must carry a grep/line citation (e.g. `file.rs:203`) — otherwise it is a future bug in disguise.
+- **Wiring claims that name a symbol, not a caller chain.** Verifying that a function exists is not the same as verifying it is reachable. A wiring claim is only valid when it names the production caller chain from an actual entry point — not just the symbol's location in a file. A function that nothing calls is dead, not wired.
 
 ## Exit check
 

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

@@ -60,6 +60,11 @@ The AI generates the test suite from the scenarios and contract. Your job is to
 - **A green suite before the build.** Means the tests are not actually exercising the missing feature — fix them now.
 - **Skipping the side-effect assertions.** Without `assert a.balance == 20` on the rejection path, a corrupting partial failure passes silently.
 - **No coverage target.** Without a recorded target, coverage can quietly erode during the build.
+- **`should_panic` as a red test.** Marking a test `#[should_panic(expected = "implement in green wave")]` (or the equivalent in any language) passes immediately and stays green while red — it is a lying red. Declare unimplemented paths with `todo!()` (or `unimplemented!()`) so the test actually fails. If a test is intentionally designed to flip from red to green during the build, say so with a comment: `// flip authorized at green wave`.
+- **Collateral tests named by category, not by exact name.** When a spec adds a slash command, a new CLI subcommand, or any other globally-enumerated thing, there is a fixed collateral set of tests that count or enumerate it (e.g. a command-registry count test, a help-text snapshot, an autocomplete positional assert). Pre-list these tests by their **exact test names** in §4 — not categories — so the build agent's edits to those "pre-existing" tests are expected and the count is right. Naming only the category means the agent finds the wrong test or misses one.
+- **Arithmetic not checked against frozen constants.** Before freezing, check that the red suite can reach green: a fixture with N bytes fails a hard-coded M-byte budget if N > M — the suite can never pass. Run the numbers before freeze, and add an additive override (e.g. `set_budget`) when the scenario implies a limit the production constant cannot satisfy in test.
+- **Non-hermetic tests that read real user state.** Tests that call a loader with `None` (defaulting to `~/.helios/settings.json` or the real home dir) become torn-read flakes under a parallel suite and assert nothing useful. Red tests that create or read production paths must redirect them to a temp dir; grep new tests for `home_dir`, `~/.config`, real-path defaults before freeze.
+- **Tests that share a per-machine singleton without isolation.** Background services (embedded servers, filesystem watchers) bind to fixed ports or paths. Tests that start such a service must tear it down, or they collide with a parallel run or an already-running dev instance. If the singleton cannot be isolated, gate those tests as serial (one thread, no parallel execution) and document it.
 
 ## Exit check
 
@@ -67,6 +72,9 @@ The AI generates the test suite from the scenarios and contract. Your job is to
 - [ ] The suite runs in the pipeline and is **red for the right reason**.
 - [ ] Tests assert observable behavior, not internals.
 - [ ] A coverage target is recorded.
+- [ ] No `should_panic` lying reds — unimplemented paths use `todo!()` or equivalent so they actually fail.
+- [ ] Collateral tests for globally-enumerated things (command counts, help snapshots) are listed by exact name.
+- [ ] Arithmetic checked: the red fixtures can reach green against the frozen constants.
 
 ## If the check fails
 

package/docs/07-step-5-build.md

@@ -78,3 +78,5 @@ The autonomy granted in this step should match the evidence and your review capa
 ## If the check fails
 
 If the AI weakened a test, reject and re-prompt. If it added an out-of-allow-list package, the pipeline blocks it; have the AI find an approved alternative or raise the package for human approval. If the batch is too large to review, ask the AI to split the work and resubmit. Only once the exit check passes does the change proceed to verification.
+
+And in the other direction: if the *verify* gate later finds a confirmed cheat — a tamper, or a build that gamed the green (overfit to the fixtures, vacuous asserts, stubbed-away logic) — the task returns *here* for an honest redo. That return is the **bounded self-heal loop** (see the run chapter): revert the tampered file or de-overfit the code, then advance again. It is capped — after the cap a confirmed cheat HARD-STOPs to the human rather than looping forever, and a gamed green is never auto-passed.

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

@@ -48,6 +48,14 @@ Two failures slip straight past green tests. The first is code that is never *wi
 
 This is *evidence*, not impression: a reference search showing where each new symbol is called, a scan confirming nothing new is orphaned, or — for prose — a note of exactly what was read and what it confirmed. An unfilled deep check is a **shallow verify**, not a pass. The engine cannot judge wiring, dead code, or whether prose was truly read; the resolver records the evidence, and a person (under `conservative`) or the recorded run (under `auto`) signs it.
 
+**The wiring trace is a named step, not a free-form note.** For every new hook, closure, or middleware registered in this task: trace from the process entry point to the call site and record it explicitly — symbol, file, line. A symbol that is only reachable via a test helper or `make_config` but not via the production entry point (e.g. `build_harness_with_dispatcher`, `interactive_mode`) is not wired. This is the third repeated class in production: "runtime-activation-order/silent-noop" — the code exists and the unit tests pass, but the feature is absent in the running program. The wiring trace is how you catch it before a user does.
+
+## Part four — was the green earned?
+
+Passing tests say the code satisfies the cases you wrote down. They do not say it earned that pass honestly — and the mechanical tamper tripwire (Step 6's floor) only catches an *edited* test or contract, not a build that gamed the *unchanged* suite. The same rubric the phase guide carries names what the tripwire cannot see:
+
+A green suite proves the tests pass — not that the build EARNED them. Three judgment cheats pass the unchanged suite without earning it: src overfit to the test fixtures (special-cased to the literal inputs, not the general behavior §1 asked for), vacuous asserts (tautological — green even against an empty implementation), and real logic stubbed away (the function returns a constant the tests happen to accept). These cheats are invisible to the mechanical tamper tripwire, which only sees edited files. Score them with an adversarial refute-read: an independent reviewer — a subagent under `autonomy: auto` is recommended, the engine never spawns one — prompted to argue the green was NOT earned from outside the build context. This is the verify-gate, whole-suite specialization of run.md's adversarial verify (see run.md), not a new discipline. A confirmed earned-green failure is HARD-STOP-class: never auto-passed, never RISK-ACCEPTED — but a first cheat is a chance to redo: a confirmed cheat (mechanical tamper or a reported earned-green failure) enters the bounded self-heal loop — it returns to build for an honest redo, and only after the loop's cap does it HARD-STOP to the human (the loop lives in run.md).
+
 ## Recording the outcome
 
 Every verification ends with exactly one recorded outcome, with an accountable owner — never a silent pass:
@@ -75,6 +83,9 @@ A security finding is always a `HARD-STOP`; it is never waved through with a wai
 - **Shipping on plausibility.** Reading the diff, finding it reasonable, and approving — without the evidence and the non-functional review — is the precise failure the method exists to prevent.
 - **Treating a security gap as acceptable risk.** It is a `HARD-STOP`, not a waiver.
 - **Skipping the concurrency check** because the tests are green. Tests rarely exercise simultaneity; this is a manual check by design.
+- **Trusting the green agent's self-reported test count.** A build agent running a filtered suite (e.g. `-E 'test(theme)'`) only sees tests inside the filter. Collateral failures outside the filter — a stale count in `all_commands_in_registry`, an e2e snapshot the agent did not touch — are invisible. The orchestrator's **full-suite rerun is load-bearing**; never skip it on the grounds that the scoped run was green.
+- **User-observable-only failures escalate to the human before exhausting discriminating probes.** When a symptom is only observable by a person (a TCC dialog, a visual flicker, an OS-level prompt), do not respond by running the suite again. Instead, design two or three targeted probes that let the user distinguish cause A from cause B in one interaction each. Three AskUser probes resolve what three blind reruns cannot.
+- **Background-process hangs misdiagnosed as test failures.** A test that never exits is not a failure in the test logic — it is a hang. The diagnosis recipe: background the test process, run `pgrep` to find it, use the platform profiler (`sample <pid>` on macOS, `perf` on Linux) to sample the stack, then `lsof -p <pid>` to see open files. Run an isolation experiment (suspect line on/off, 3×3) before reading any code. Entry-count caps do not bound wall time — a single huge directory or a blocking syscall inside a `spawn_blocking` call can hang indefinitely even when the entry cap is satisfied.
 
 ## If the check fails
 

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

@@ -109,7 +109,7 @@ The default is one task at a time. But when a milestone holds several tasks whos
 - **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 **bundle approval** (contract freeze) and any **Verify escalation**. One human, one queue, presented one at a time — never a batch that invites approval without reading.
 
-**The autonomy level is the throttle.** At `conservative`, both gates queue on the human (pure pipelining — builds overlap, nothing auto-resolves). At `auto` (the default), only the bundle-approval decision point 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 decision point**.
+**The autonomy level is the throttle** — an explicit, overridable per-task token on an ordered ladder `manual < conservative < auto`. At `manual`, the human owns every gate and nothing auto-resolves (the strict floor). At `conservative`, both gates queue on the human (pure pipelining — builds overlap, nothing auto-resolves). At `auto` (the seeded default), only the bundle-approval decision point 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 decision point**.
 
 **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.
 

package/docs/11-governance.md

@@ -21,6 +21,10 @@ The governing rule, restated from the principles: **operate only at the level yo
 
 The **per-scope default is auto-with-evidence behind a one-approval decision point**: the AI drafts the specification bundle, a human approves the frozen contract once, and the build auto-gates on evidence. You *lower* a scope toward draft-and-review or suggest wherever risk is high or evidence is thin — and a high-risk or method-defining scope is *always* lowered (it is never auto-run). The default sets where you start; review capacity and risk set where you stay.
 
+The engine expresses this per task as an explicit three-rung level — `autonomy: manual | conservative | auto`, an ordered ladder `manual < conservative < auto` declared in the `TASK.md` header and reviewed at the freeze. `auto` is auto-with-evidence behind the one approval (the seeded default); `conservative` is the deliberate lowering that keeps a person at the verify gate; `manual` is the strict floor where the human owns the gate and nothing auto-resolves. A high-risk or method-defining scope refuses an unguarded `auto` (`unguarded_high_risk_auto`) — it must be lowered to `conservative` or `manual`. The prose here and that engine token are one rule: prose ≡ enforcement.
+
+**Autonomy is earned by goal-clarity — the auto-ready goal.** The autonomy level decides *who* resolves Verify; an **auto-ready goal** decides whether a self-verifying run is even *meaningful*. A milestone goal is *auto-ready* when **every exit criterion cites a verifier** — `(verify: <test | command | metric>)` — so the engine can check the result against the goal without human judgment. `add.py check` raises a `goal_not_auto_ready` WARN (never red, the active milestone only) while the goal has criteria not all cited, and `status` surfaces a `goal-ready:` line every session, so the goal-clarity gap stays visible. The WARN *measures*, it never blocks: it changes neither the freeze gate nor the autonomy level — clarifying the goal is the prerequisite that *earns* trust, not a new gate (a zero-criteria goal reads not-auto-ready and is milestone-shaping's nudge, not this one's). The lint raises the floor — a citation slot per criterion — but cannot prove the citation is honest: a human can still write `(verify: it works)`, and closing that is a person's judgment, not the engine's.
+
 ## The gate-fail protocol and the three reports
 
 Every checkpoint produces three short reports — **Test** (does it pass?), **Quality** (is it well-made and conformant?), and **Risk** (what could go wrong, and who owns it?) — and resolves to exactly one outcome:

package/docs/appendix-c-glossary.md

@@ -24,6 +24,10 @@
 
 **Gate** — a checkpoint with an explicit pass/fail exit. Its outcome is `PASS`, `RISK-ACCEPTED`, or `HARD-STOP`.
 
+**Ground (phase-0 preamble)** — the per-task phase *before* Specify in which the AI gathers the real current codebase the task touches — files, symbols, signatures, patterns, conventions — into a lean **grounding map**, surfacing the **anchors** the frozen contract will cite. It is AI-owned and adds no approval (the one approval stays at the contract freeze); it precedes the seven steps as step 0 so the contract, tests, and build are grounded in the code as it actually is, not in assumption. Lives in the `add` skill's `phases/0-ground.md`.
+
+**Grounding map / anchors** — the §0 GROUND artifact: the real files, symbols, and conventions a task touches, plus the **anchors** — the symbols the frozen contract names. Task-specific delta only: it defers to `PROJECT.md` / `CONVENTIONS.md` for architecture and never re-runs the setup brownfield scan. `add.py status` / `check` surface whether the active task's contract is grounded (measure, never block — the contract-freeze checklist asks the human to confirm it).
+
 **`HARD-STOP`** — a gate outcome meaning work cannot proceed; triggered by any failing test or security finding.
 
 **Intake** — the step *before* a task: sizing a raw request into versioned scope by classifying it into one **request bucket**. The AI proposes `{bucket, rationale, command}`; the human confirms. Lives in the `add` skill's `intake.md` (the intake level, above the per-task flow).
@@ -70,7 +74,9 @@
 
 **Scope level** (formerly "altitude") — the granularity a decision lives at: intake level (request → versioned scope) · milestone level · setup/foundation level · task level. (A cross-stage decision lives one level out, at the **stage-graduation** loop — which `graduate.md` also numbers as a scope level; see **Stage graduation**.) One ⚠-assumption notation is shared across every scope level.
 
-**Autonomy level** (formerly "autonomy dial") — the per-task setting (`autonomy: auto | conservative`) choosing who resolves Verify; high-risk scope refuses an unguarded `auto`.
+**Autonomy level** (formerly "autonomy dial") — the explicit per-task setting (`autonomy: manual | conservative | auto`, an ordered ladder manual < conservative < auto) choosing who resolves Verify: `auto` auto-PASSes on complete evidence, `conservative` keeps a human at the gate, `manual` is the strict floor (the human owns the gate; nothing auto-resolves). A high-risk scope refuses an unguarded `auto` — it must be lowered to `manual` or `conservative`. New tasks seed a visible, overridable `autonomy: auto`; a live task with no level warns (`implicit_autonomy`), a token outside the set is rejected (`unknown_autonomy_level`).
+
+**Auto-ready goal** — a milestone goal whose every exit criterion **cites a verifier** (`(verify: <test|command|metric>)`), so the engine can self-verify the result against the goal without human judgment. It is the prerequisite by which **autonomy is earned by goal-clarity**: the **autonomy level** governs *who* resolves Verify, but a clarified, machine-checkable goal is what makes a self-verifying run meaningful. `add.py check` raises a `goal_not_auto_ready` **WARN** (never red) for the active milestone until it has an auto-ready goal (≥1 exit criterion and every one cited), and `status` surfaces it (`goal-ready: auto-ready ✓` / cited-of-total); a zero-criteria goal reads not-auto-ready and is milestone-shaping's nudge, not this warning's. The lint forces a citation *slot* per criterion — it raises the floor but **cannot prove the citation is real** (a human can write `(verify: it works)`): citation-theater is the accepted irreducible floor, and the freeze gate and autonomy behavior are unchanged by it.
 
 **Automated quality gate** (formerly "evidence auto-gate") — the Verify resolver under `autonomy: auto`: a run may auto-PASS on complete evidence, recorded as *auto-resolved*; a security finding always escalates (`HARD-STOP`).
 
@@ -103,6 +109,7 @@ This book uses plain step names. Teams connecting it to a larger formal standard
 | Plain step (this book) | Formal phase name |
 |------------------------|-------------------|
 | Project setup | Foundation |
+| Ground (preamble) | Codebase Discovery (the §0 grounding map) |
 | Specify | Domain Discovery + Spec Definition |
 | (design portion) | UX-Driven Design |
 | Scenarios | Behavior specification (Given/When/Then) |

package/docs/appendix-e-checklists.md

@@ -19,6 +19,7 @@ Every exit check in the book, collected for quick use. Print this page.
 - [ ] Every rejection has a named error code.
 - [ ] Success state-change described.
 - [ ] Assumptions ranked lowest-confidence first; the 1–2 most-likely-wrong ⚠-flagged with why + cost (or an honest "none material" that still names the single biggest risk).
+- [ ] "Existing behavior" assumptions carry grep/line citations; wiring claims name the production caller chain.
 
 ## Step 2 — Scenarios
 
@@ -40,6 +41,9 @@ Every exit check in the book, collected for quick use. Print this page.
 - [ ] Suite runs in the pipeline and is red for the right reason.
 - [ ] Tests assert behavior, not internals.
 - [ ] Coverage target recorded.
+- [ ] No `should_panic` lying reds — unimplemented paths use `todo!()` so they fail.
+- [ ] Collateral tests for globally-enumerated things listed by exact name.
+- [ ] Arithmetic checked: fixtures can reach green against frozen constants.
 
 ## Step 5 — Build
 
@@ -55,7 +59,10 @@ Every exit check in the book, collected for quick use. Print this page.
 - [ ] Concurrency/timing of the risky operation is safe.
 - [ ] No exposed secrets, injection, or unexpected dependencies.
 - [ ] Layering and dependencies follow `CONVENTIONS.md`.
-- [ ] A person reviewed and approved.
+- [ ] Deep check: wiring trace recorded (every new symbol reachable from production entry point) and no dead code introduced.
+- [ ] Was the green earned? Adversarial refute-read on the unchanged suite (no overfit, no vacuous asserts, no stubbed logic).
+- [ ] Full-suite rerun by orchestrator (not only the agent's scoped run).
+- [ ] A person reviewed and approved, **or** auto-resolved by the run (under `autonomy: auto`, no residue).
 - [ ] Outcome recorded (`PASS` / `RISK-ACCEPTED` / `HARD-STOP`).
 
 ## The loop
@@ -71,10 +78,15 @@ Every exit check in the book, collected for quick use. Print this page.
 A feature is shippable only when all are true:
 
 - [ ] Spec complete: behavior stated, rejections named, assumptions ranked lowest-confidence first with the biggest risk flagged.
+- [ ] Wiring and "existing behavior" assumptions carry grep/line citations; wiring claims name the production caller chain.
 - [ ] Every rule has a scenario.
 - [ ] Contract frozen; contract tests green.
-- [ ] A test per scenario; suite was red before the build.
+- [ ] A test per scenario; suite was red before the build (no `should_panic` lying reds).
+- [ ] Collateral tests listed by exact name; arithmetic checked against frozen constants.
 - [ ] All tests green; coverage held; tests and contract untouched by the AI.
+- [ ] Wiring trace recorded: every new symbol reachable from production entry point.
+- [ ] Adversarial refute-read confirms the green was earned (no overfit, no vacuous asserts, no stubbed logic).
+- [ ] Full-suite rerun by orchestrator; not just the agent's scoped run.
 - [ ] Concurrency, security, and architecture checked by a person.
 - [ ] Gate outcome recorded with an accountable owner.
 - [ ] Released behind a flag, with monitors in place.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.2.0",
+  "version": "1.3.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"

package/skill/add/SKILL.md

@@ -20,7 +20,7 @@ You are the orchestrator. ADD keeps the AI fast *and* safe by fixing direction
 the result through passing evidence rather than a plausible-looking diff.
 
 **One file = one task.** Each feature lives in a single `.add/tasks/<slug>/TASK.md`
-with seven sections. You fill them top to bottom; the Python tool tracks where
+with a §0 ground preamble and seven step sections. You fill them top to bottom; the Python tool tracks where
 you are so context never rots across sessions.
 
 ## Always start here (orient — do not skip)
@@ -61,6 +61,7 @@ Load the phase guide **only for the phase you are in** (progressive disclosure):
 | Phase | Guide | Produces (TASK.md section) | Who leads |
 |-------|-------|----------------------------|-----------|
 | setup | `phases/0-setup.md` | `.add/` + living docs + first §1–§3 + `SETUP-REVIEW.md` | AI drafts → **human locks** (the baseline approval) |
+| ground | `phases/0-ground.md` | §0 GROUND map (real files · symbols · the anchors §3 cites) | **AI** (the §0 preamble — no new gate) |
 | specify | `phases/1-specify.md` | §1 rules + ranked lowest-confidence flag | AI drafts (co-specify)† |
 | scenarios | `phases/2-scenarios.md` | §2 Given/When/Then | AI drafts† |
 | contract | `phases/3-contract.md` | §3 frozen shape | AI drafts → **human approves once** (the decision point)† |
@@ -73,7 +74,7 @@ Load the phase guide **only for the phase you are in** (progressive disclosure):
 contract freeze** (the decision point), presented lowest-confidence-first. See `run.md`.
 ‡ **Verify auto-gate (v6–v7).** Under `autonomy: auto` (the default) a run may auto-PASS on
 complete evidence — recorded as *auto-resolved*, an explicit PASS, not a skip. **Security always
-escalates** (HARD-STOP); so do concurrency / architecture residue and `conservative` autonomy.
+escalates** (HARD-STOP); so do concurrency / architecture residue and a lowered autonomy level (`conservative` / `manual`).
 See `run.md`.
 
 Whenever you present a decision point to the human in chat (intake · bundle approval · gate ·
@@ -90,7 +91,7 @@ gathers confirmed deltas into a versioned foundation — read `fold.md`.
 ## Beyond the bundle — load on demand
 
 Once **§3 CONTRACT is FROZEN**, the build→verify half is a dynamic, auto-gated run
-(`autonomy: auto` default, lowered to `conservative` for a human gate) — read `run.md`. To
+(`autonomy: auto` default, lowered to `conservative` or `manual` for a human gate) — read `run.md`. To
 pipeline several ready tasks behind their own frozen contracts, read `streams.md`.
 
 When a milestone's tasks are all done but its **goal** (the `MILESTONE.md` exit criteria) is not

package/skill/add/phases/0-ground.md

@@ -0,0 +1,66 @@
+# Phase 0 — Ground (the real codebase)
+
+Goal: before you specify anything, gather the REAL current working folder the task will
+touch — the actual files, symbols, signatures, docs, todos, config, data, patterns, and conventions — so the
+contract, tests, and build are grounded in what exists, not in what you assume.
+Fill **§0 GROUND** in TASK.md. Ground is a per-task preamble to the seven steps;
+it is **AI-owned** — no human gate here (the one approval stays at the §3 freeze).
+
+If you cannot name the files and symbols the task touches, you do not yet understand
+the work — gathering them IS the job, not a detour.
+
+## Gather (in TASK.md §0)
+
+- **Touches** — the real files · symbols · signatures the task will read or change,
+  named from the actual code (use your code-navigation tools — grep / symbol search,
+  never memory). Each as `path:symbol — what it is / how it is keyed`.
+- **Context (working folder)** — beyond code, the NON-code artifacts the task touches:
+  docs/textbase (README · `*.md` · design notes) · TODOs (`TODO.md` · `FIXME`/`TODO`/`HACK`
+  comments · task lists) · config/manifests (configs · `.env.example` · `pyproject`/`package`
+  · CI) · data/fixtures (samples · fixtures · schemas). Gather only the TASK-SPECIFIC
+  delta — never index the whole repo.
+- **Honors** — the patterns and conventions the work must respect, cited from
+  `PROJECT.md` / `CONVENTIONS.md`. Gather only the TASK-SPECIFIC delta — never
+  re-derive the architecture or re-run the setup brownfield scan.
+- **Anchors the contract cites** — the specific symbols §3 CONTRACT will name. The
+  contract may cite only anchors that appear here.
+
+**How — gather efficiently:** for the BROAD sweep, prefer a small-model subagent / fast
+index / skim (offload to a cheap context, return a compact map); then DEEPEN on what THIS
+task specifically needs — never lock a shallow first pass. A recommendation: the engine
+never spawns a subagent (tool-agnostic), so the orchestrating agent chooses.
+
+## Greenfield / first task
+
+The first task of a project runs ground too. When there is little or no code yet
+(greenfield), or you are mid-setup, your grounding IS the foundation docs / brownfield
+scan you just produced — point at them; do not re-scan. An honest "new module, no
+existing code; honors CONVENTIONS.md §X" is a complete grounding.
+
+## AI prompt
+
+<prompt>
+Role: an engineer who reads the real code before designing against it.
+Read first: PROJECT.md · CONVENTIONS.md · the actual files the task touches.
+Objective: fill §0 GROUND with the real files/symbols/signatures + the conventions to
+honor + the anchor points the contract will cite — gathered from the codebase, never assumed.
+Steps:
+  0. Sweep broad cheaply first — prefer a small-model subagent / fast index / skim — then deepen task-specifically.
+  1. Locate the files and symbols the task reads or changes (code tools, not memory).
+  2. Record their signatures / how they are keyed; cite the conventions to honor (task delta only).
+  3. Name the anchors §3 will cite.
+Never: invent a file, symbol, or signature you have not opened.
+</prompt>
+
+## Exit gate
+
+<exit_gate>
+- [ ] The real files/symbols the task touches are named (from the code, not assumed).
+- [ ] The conventions to honor are cited (task-delta only; no architecture re-scan).
+- [ ] The anchors §3 will cite are listed — §3 names only anchors that exist here.
+</exit_gate>
+
+## Next
+
+`python3 .add/tooling/add.py advance` → read `phases/1-specify.md`.
+Book: `docs/02-the-flow.md` (the flow; ground is the §0 preamble to the seven steps).

package/skill/add/phases/0-setup.md

@@ -53,7 +53,9 @@ tag thin or inferred answers `guessed`.
 
 1. **Fill the living documentation** (it outlives all code): `.add/PROJECT.md` (the foundation — Domain · Spec/active
    milestone · UI/UX · Key Decisions, one screen), `CONVENTIONS.md`, `GLOSSARY.md`, `MODEL_REGISTRY.md`,
-   `dependencies.allowlist`. Brownfield: from the code. Greenfield: from the interview, gaps flagged `guessed`.
+   `dependencies.allowlist`, and — for a UI project — `DESIGN.md` (the design source of truth: identity ·
+   principles · screens · the named-set foundation pointers + render recipe; delete it if there's no UI).
+   Brownfield: from the code. Greenfield: from the interview, gaps flagged `guessed`.
 2. **Size the first milestone** (read `scope.md`) and draft its `MILESTONE.md` — goal · scope · exit criteria
    · breadth-first tasks.
 3. **Create the first task and draft its candidate specification bundle.** `new-task` is allowed pre-lock:

package/skill/add/phases/1-specify.md

@@ -15,6 +15,11 @@ understand the feature — that is information, not an obstacle. Stop and ask.
 2. **Converge** — draft §1, then RANK where your confidence is lowest (below).
 3. **Validate** — present the ranked uncertainty first; the user confirms, corrects, or sends back.
 
+**Identity is direction, not default (UDD).** For UI/design work, identity values — the brand
+color, the core palette, the typeface — are human-owned. Surface them for discussion during
+Diverge; never assume a brand value. The UDD token dialect checks a token's *shape*; its *value*
+is the user's call (`udd-tokens.md`).
+
 ## Produce (in TASK.md §1)
 
 <output_format>

package/skill/add/phases/3-contract.md

@@ -22,10 +22,11 @@ whole bundle (§1–§4). Before asking for it, present the bundle **lowest-conf
 most likely wrong (`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`) — aim the human's
 eye before they freeze. Open that report with the ARC (goal · done · plan) per `report-template.md` so the
 human sees the goal this freeze serves and the plan beyond it, not just the bundle. See `run.md`.
+The approval also freezes the §5 Scope (may touch) + Strategy declarations — the bundle covers them.
 
 ## The freeze review checklist
 
-The human's one minute, aimed. Walk these six before saying yes:
+The human's one minute, aimed. Walk these seven before saying yes:
 
 - **⚠ flags first** — read the lowest-confidence flags; accept each knowing its cost if wrong.
   The engine refuses an unflagged freeze before build: a frozen §3 with no well-formed
@@ -34,6 +35,7 @@ The human's one minute, aimed. Walk these six before saying yes:
 - **Intent** — does §1 say what you actually want built (and is anything you expected missing)?
 - **Cases** — does every Must and Reject have an observable §2 scenario you care about?
 - **Shape** — glossary names, error codes, additive vs breaking: is THIS the shape to freeze?
+- **Grounded** — does §3 cite anchors that exist in the §0 GROUND map (real files/symbols), not invented ones? `status`/`check` surface this — measure, never block.
 - **Risk** — is this scope high-risk or method-defining? Then require
   `risk: high · autonomy: conservative` in the TASK.md header — the engine refuses an unguarded completion.
 - **Tests** — will §4 go red for the right reason, asserting behavior rather than internals?

package/skill/add/phases/5-build.md

@@ -10,6 +10,21 @@ Pick ONE task-sized slice, restate the tests it must satisfy, implement, run
 tests, iterate to green. Keep each batch small enough to review in full — you
 cannot move faster than you can verify.
 
+## Declaring the scope of impact (Scope + Strategy)
+
+§5 of TASK.md opens with two declarations, drafted WITH the specification bundle
+and frozen by the one §3 approval — never invented mid-build:
+
+- **Scope (may touch)** — the allowlist of every file the build may write
+  (backticked tokens; grammar in the template comment). During build, needing a
+  file outside the declared Scope is a **STOP → change request** back to Specify,
+  never improvisation.
+- **Strategy (ordered batches)** — the planned build order. Guidance, not
+  enforced: it aims the small-batches loop, it does not gate it.
+
+Deferral, named: the engine gate (touched ⊆ declared) lands in the
+`scope-gate-enforce` task — until it ships this section is prose discipline.
+
 ## The cardinal rule
 
 **Never weaken or delete a test to make it pass, and never edit the frozen
@@ -36,6 +51,7 @@ Never: change a test or the contract; use a package off the allow-list; or push
 - [ ] Coverage did not decrease.
 - [ ] No test and no contract modified by the AI.
 - [ ] No dependency outside the allow-list.
+- [ ] No file outside the declared §5 Scope was touched.
 - [ ] Change small enough to review in full.
 </exit_gate>
 
@@ -46,3 +62,9 @@ Book: `docs/07-step-5-build.md`.
 
 > Under `autonomy: auto` (the default) Build and Verify run together as one dynamic,
 > evidence-auto-gated run — not two manual stops. See `run.md`.
+>
+> **Honest redo.** If the verify gate finds a confirmed cheat (a tamper, or a reported
+> earned-green failure), the task returns HERE for an honest redo — revert the tampered
+> file or de-overfit src, then advance again. This is the bounded self-heal loop (`run.md`),
+> capped: after the cap a confirmed cheat HARD-STOPs to the human. Never weaken a test or
+> edit the frozen contract to pass.

package/skill/add/phases/6-verify.md

@@ -47,6 +47,22 @@ Record it in the §6 **Deep checks** block — where each new symbol is called (
 search), the dead-code scan result, or the prose you read in full and what it confirmed.
 An unfilled Deep checks block is a **shallow verify**, not a PASS.
 
+## Part four — was the green earned?
+
+A green suite proves the tests pass — not that the build EARNED them. Three judgment cheats
+pass the unchanged suite without earning it: src overfit to the test fixtures (special-cased
+to the literal inputs, not the general behavior §1 asked for), vacuous asserts (tautological —
+green even against an empty implementation), and real logic stubbed away (the function returns
+a constant the tests happen to accept). These cheats are invisible to the mechanical tamper
+tripwire, which only sees edited files. Score them with an adversarial refute-read: an
+independent reviewer — a subagent under `autonomy: auto` is recommended, the engine never
+spawns one — prompted to argue the green was NOT earned from outside the build context. This
+is the verify-gate, whole-suite specialization of run.md's adversarial verify (see run.md), not
+a new discipline. A confirmed earned-green failure is HARD-STOP-class: never auto-passed, never
+RISK-ACCEPTED — but a first cheat is a chance to redo: a confirmed cheat (mechanical tamper or a
+reported earned-green failure) enters the bounded self-heal loop — it returns to build for an honest
+redo, and only after the loop's cap does it HARD-STOP to the human (the loop lives in run.md).
+
 ## Record exactly one outcome (no silent pass)
 
 When you present this gate to the human, open with the ARC (goal · done · plan) per