@pilotspace/add 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# 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.2.0] — 2026-06-10
+
+The decision-arc release: the method now narrates the build as one continuous
+arc of decisions, and the loop reaches past a single milestone — graduating a
+prototype to production, gating milestones on their own goal, and running tasks
+in parallel waves. All additive; no breaking changes (SemVer MINOR).
+
+### Added
+- **The decision arc** — every human-gate report opens by naming where you are
+  on the arc (intent → cases → contract → tests → build → verify → observe), and
+  the book + GLOSSARY describe it as the spine of the method. The one human
+  approval is always placed on the arc, never floating.
+- **Graduation to production** — `add.py graduate` plus a graduate-guide and a
+  `→production` stage guard turn the mvp→production transition into an
+  analytics-driven, criteria-gated step instead of a label flip: a
+  graduation-report surfaces the evidence and a stage-goal-criteria cue tells you
+  when the prototype has earned the next stage.
+- **Goal-gated milestones & the dynamic task loop** — an explicit project GOAL
+  now rides on `status`/`guide`, a milestone completes only when every success
+  criterion is met, and a recorded `done → phase` reopen-transition lets a closed
+  task legitimately re-open without losing its history.
+- **verify-deepen** — the verify phase gained a deep-check rubric
+  (wiring · dead-code · semantic) so verification probes intent, not just a green
+  suite.
+- **Parallel waves** — `WAVE.md`, the wave ledger that is the resume point for
+  parallel task execution; `status` surfaces a live wave so a multi-task wave can
+  pause and resume cleanly.
+- **The flag-first freeze guard** — declaring a contract freeze is now
+  fail-closed: an `unflagged_freeze` is refused at `advance` time and flagged by
+  `add.py audit`, so a freeze can never be recorded without its explicit marker.
+- **Foundations & Lineage chapter** — the book gained an annotated Foundations
+  chapter with author-year citations and a references appendix, tracing the
+  method's lineage.
+
+### Changed
+- Engine prose now speaks one ubiquitous language — `add.py` output uses
+  consistent domain terms (scope level, decision point, retrospective, …).
+- `add.py compact` keeps the active state lean by compacting heavy archive
+  history, with the bundled engine frozen in lockstep.
+
+## [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

@@ -8,114 +8,228 @@ 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.
+ADD is **AI-first**: you talk to the agent and it drives the method. Reading this
+guide top to bottom, you will type exactly **one shell command — the install**.
+After that, everything happens in conversation (`/add` is how you start it, not
+a terminal command): the agent's hands are the CLI, and the same CLI is your
+escape hatch whenever you want to take the wheel (it's all in the appendix at
+the end).
 
 ---
 
-## The fast path — talk to the agent
+## 0 · Prerequisites
+
+- **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 in the appendix differ.
+
+---
 
-After installing (step 1 below), the whole on-ramp is one move:
+## 1 · Install — the one command you type
+
+From your project root, pick **one** path — both produce the same install:
+
+**Option A — npm (Node.js ≥ 18):**
+
+```bash
+npx @pilotspace/add init
+```
+
+**Option B — pip (Python 3.10+):**
+
+```bash
+pip install pilotspace-add
+pilotspace-add init
+```
+
+No flags needed — the agent infers your project's name from the folder and starts
+at the `prototype` stage. (Prefer to choose up front? Both installers take
+`--name "My App" --stage prototype|poc|mvp|production`; the stage can also be
+changed later — see the appendix.)
+
+Either one creates `.add/` (your runtime), drops the `add` skill into
+`.claude/skills/add/`, and bundles the book into `.add/docs/`. It deliberately
+does **not** initialise the project — that's the agent's first move, so nothing
+gets decided without you in the loop.
+
+**When the install finishes: open Claude Code and type `/add`.** That's the
+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`.
+
+---
+
+## 2 · Your first feature — talk to the agent
+
+In Claude Code, the whole onboarding 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:
+From there the agent runs the **onboarding** for you:
 
-1. **Orient** — it reads `add.py status` (the resume point), never re-reading your repo.
+1. **Orient** — it reads the project state (the resume point), never re-reading
+   your repo. On a fresh install it initialises the project itself and drafts
+   the foundation for your sign-off (the **baseline approval** — the one signature the
+   installer's closing message points at).
 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.*
+3. **Specification bundle** — for each task it drafts Spec + Scenarios + Contract + Tests
+   as one bundle, led by its lowest-confidence points. *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.
+contract → review the result.** Everything between is the agent. For the
+transfer-money feature above, that's four short conversations — and zero typed
+commands.
 
-> New term: **On-ramp** — the install→first-milestone path. See `docs/appendix-c-glossary.md`.
+> New term: **Onboarding** — the install→first-milestone path. See `.add/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.
+## 3 · What just happened (and your override)
 
----
+Behind the conversation, the agent drove the CLI: it read the resume point, sized
+the milestone, froze the contract you approved, ran the tests red, built to green,
+and recorded the gate. The state lives on disk, not in the chat window.
 
-## 1 · Install
-
-From your project root:
+If you ever want to see that state yourself — or take over entirely — the same
+CLI is yours:
 
 ```bash
-npx @pilotspace/add init --name "My App" --stage prototype
+python3 .add/tooling/add.py status
 ```
 
-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`.
+`add.py status` is the resume point: project stage, active task, current phase.
+And `add.py guide` tells you what the current phase needs — its `guide  :` line
+names the exact phase-guide file to read (`.claude/skills/add/phases/…` — plain
+markdown), which is how **any** agent — Claude, Cursor, Copilot, Codex — follows
+ADD through the CLI alone.
 
-> Why stages exist: the steps never change, only how *deeply* you run them.
-> See `.add/docs/10-setup-and-stages.md`.
+> Tip: shorten typing with an alias — `alias add="python3 .add/tooling/add.py"` —
+> then you can run `add status`, `add guide`, etc. These are override and resume
+> surfaces, not steps you owe the method: the appendix walks the full by-hand path
+> whenever you want the wheel.
 
 ---
 
-## 2 · Orient — the command you'll use most
+## Resume next session
+
+Close your laptop, come back tomorrow, type `/add` again — the agent reorients
+itself from disk and continues exactly where you left off. No context rot.
+
+The same resume point is yours directly:
 
 ```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.
+## Self-check
 
-And when you're mid-task and unsure what the current phase needs, ask:
+Confirm your project is internally consistent at any time:
 
 ```bash
-python3 .add/tooling/add.py guide
+python3 .add/tooling/add.py check
 ```
 
-`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.
+It verifies state is valid, every task has its TASK.md, and markers match. Exit
+code 0 means healthy — handy as a CI gate.
 
 ---
 
-## 3 · Start your first feature
+## Enforce the decision points in CI
 
-```bash
-python3 .add/tooling/add.py new-task transfer --title "Transfer money between my accounts"
-```
+`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*).
 
-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`.
+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: Decision-point audit (recorded human gates)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
 
-Open `.add/tasks/transfer/TASK.md` in your editor. You'll fill it top to bottom.
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Audit recorded decision points
+        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 decision 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.
 
 ---
 
 ## 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
+Everything above is what the agent drives for you through the one-approval flow. This
+appendix 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`)
+### Before the phases — initialise and scaffold
+
+Starting cold? Install first as in §1 (`npx @pilotspace/add init`). Then
+initialise once and scaffold the task yourself (the agent normally does both):
+
+```bash
+python3 .add/tooling/add.py init
+python3 .add/tooling/add.py new-task transfer --title "Transfer money between my accounts"
+```
+
+> **Note:** the installer's closing hint shows `init --await-lock` — that form
+> arms the baseline-approval gate so a *human* signs the AI-drafted foundation before
+> any build. Plain `init` skips that gate, which is fine here: by hand, the
+> human IS the one driving every step.
+
+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 it in your editor; you'll fill it top to bottom.
+
+You can also change the project's depth at any time:
+
+```bash
+python3 .add/tooling/add.py stage mvp
+```
+
+### Phase 1 — Specify (`.add/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:
@@ -139,7 +253,7 @@ Confirm every assumption (no FX, no daily limit in v1). Then:
 python3 .add/tooling/add.py advance
 ```
 
-### Phase 2 — Scenarios (`docs/04-step-2-scenarios.md`)
+### Phase 2 — Scenarios (`.add/docs/04-step-2-scenarios.md`)
 
 In **§2**, turn each rule into a Given/When/Then. For every rejection, assert what
 must stay **unchanged**:
@@ -154,7 +268,7 @@ Scenario: insufficient funds
 
 Then `python3 .add/tooling/add.py advance`.
 
-### Phase 3 — Contract (`docs/05-step-3-contract.md`)
+### Phase 3 — Contract (`.add/docs/05-step-3-contract.md`)
 
 In **§3**, fix the external shape and **freeze** it (`Status: FROZEN @ v1`):
 
@@ -165,21 +279,21 @@ POST /transfers  body: { fromAccountId, toAccountId, amount }
   403 -> { error: "forbidden" }
 ```
 
-A frozen contract is the seam that makes the AI build safe. Then advance.
+A frozen contract is the decision point that makes the AI build safe. Then advance.
 
-### Phase 4 — Tests, red first (`docs/06-step-4-tests.md`)
+### Phase 4 — Tests, red first (`.add/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`)
+### Phase 5 — Build (`.add/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`)
+### Phase 6 — Verify (`.add/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:
@@ -191,46 +305,20 @@ 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`)
+### Phase 7 — Observe (`.add/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
+## 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`
+- Each step in depth — `.add/docs/03-step-1-specify.md` through `.add/docs/09-the-loop.md`
 - 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`
 

package/README.md

@@ -34,15 +34,18 @@ Pick your ecosystem — both install the same skill, tooling, and book:
 
 ```bash
 # Node / npm
-npx @pilotspace/add init --name "My App" --stage prototype
+npx @pilotspace/add init
 ```
 
 ```bash
 # Python / pip
-pip install add-method
-add-method init --name "My App" --stage prototype
+pip install pilotspace-add
+pilotspace-add init
 ```
 
+No flags needed — the project name is inferred from your folder and the stage
+defaults to `prototype` (pass `--name "My App" --stage mvp` to choose up front).
+
 **New here?** Follow the [10-minute Quickstart](./GETTING-STARTED.md) — it walks
 your first feature end to end.
 
@@ -52,9 +55,12 @@ This installs:
 |------|------|
 | `.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 |
+| `.add/docs/` | the AIDD book — the method rationale |
+
+Project state (`.add/state.json`) and the living-documentation files (`CONVENTIONS.md`,
+`GLOSSARY.md`, `MODEL_REGISTRY.md`, `dependencies.allowlist`) are *not* created
+here — the installer drops files only; initialisation is the agent's first move
+when you run `/add`.
 
 ## Use it
 
@@ -64,7 +70,7 @@ ADD is AI-first: you talk to the agent; it drives the method. In Claude Code, ru
 > `/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 +
+confirm the shape), then drafts each feature's **specification bundle** — 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.
@@ -80,7 +86,7 @@ python3 .add/tooling/add.py status      # where am I? (resume point)
 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.
+   and the non-functional risks (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`.

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, "..");
 
@@ -27,36 +29,43 @@ 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 };
+  // 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 };
   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 === "--stage" || a === "--name") {
+      const v = argv[++i];
+      // fail loudly on a trailing/abutting flag — never silently drop a value
+      // the user tried to pass (parity with the pip twin's argparse error)
+      if (v == null || v.startsWith("--")) fail(a + " requires a value");
+      if (a === "--stage") args.stage = v; else args.name = v;
+    }
     else if (a.startsWith("--")) warn("ignoring unknown flag " + a);
     else args._.push(a);
   }
   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 +75,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 +97,19 @@ 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` +
+      (args.stage ? ` --stage ${args.stage}` : "") +
+      (args.name ? ` --name "${args.name}"` : ""));
 }
 
 function main() {