@pilotspace/add 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,87 @@ 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
+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

package/GETTING-STARTED.md

@@ -8,35 +8,12 @@ You'll learn the whole loop by doing it once:
 
 > **Specify → Scenarios → Contract → Tests → Build → Verify → Observe**
 
-ADD is **AI-first**: you talk to the agent and it drives the method — you don't
-hand-type the commands. The commands below are the agent's hands (and your escape
-hatch); the rest of this guide shows both so you can see what the agent does.
-
----
-
-## The fast path — talk to the agent
-
-After installing (step 1 below), the whole on-ramp is one move:
-
-```
-in Claude Code:  /add
-you:             "I want to let users transfer money between their own accounts."
-```
-
-From there the agent runs the **on-ramp** for you:
-
-1. **Orient** — it reads `add.py status` (the resume point), never re-reading your repo.
-2. **Intake** — it sizes your request into versioned scope and proposes a **milestone**
-   (goal · scope · breadth-first tasks · exit criteria). *You confirm the shape.*
-3. **One-approval front** — for each task it drafts Spec + Scenarios + Contract + Tests
-   as one bundle. *You give one approval at the frozen contract.*
-4. **Self-driving run** — build→verify runs to green; a security finding always stops
-   back to you.
-
-So a milestone-sized feature is: **describe it → confirm the milestone → approve each
-contract → review the result.** Everything between is the agent.
-
-> New term: **On-ramp** — the install→first-milestone path. See `docs/appendix-c-glossary.md`.
+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).
 
 ---
 
@@ -49,90 +26,232 @@ contract → review the result.** Everything between is the agent.
 
 > **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.
+> step for you; only the by-hand `add.py` commands in the appendix differ.
 
 ---
 
-## 1 · Install
+## 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 --name "My App" --stage prototype
+npx @pilotspace/add init
 ```
 
 **Option B — pip (Python 3.10+):**
 
 ```bash
 pip install pilotspace-add
-pilotspace-add init --name "My App" --stage prototype
+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/`. 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`.
+`.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`.
 
+### 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 · Orient — the command you'll use most
+## 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 **onboarding** for you:
+
+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. **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. For the
+transfer-money feature above, that's four short conversations — and zero typed
+commands.
+
+> New term: **Onboarding** — the install→first-milestone path. See `.add/docs/appendix-c-glossary.md`.
+
+---
+
+## 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.
+
+If you ever want to see that state yourself — or take over entirely — the same
+CLI is yours:
 
 ```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.
+`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.
 
 > 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.
+> 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.
+
+---
+
+## Resume next session
 
-And when you're mid-task and unsure what the current phase needs, ask:
+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 guide
+python3 .add/tooling/add.py status
 ```
 
-`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. 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.
-
 ---
 
-## 3 · Start your first feature
+## Self-check
+
+Confirm your project is internally consistent at any time:
 
 ```bash
-python3 .add/tooling/add.py new-task transfer --title "Transfer money between my accounts"
+python3 .add/tooling/add.py check
 ```
 
-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`.
+It verifies state is valid, every task has its TASK.md, and markers match. Exit
+code 0 means healthy — handy as a CI gate.
+
+---
+
+## Enforce the decision points 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: Decision-point audit (recorded human gates)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
 
-Open `.add/tasks/transfer/TASK.md` in your editor. You'll fill it top to bottom.
+      - 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:
@@ -156,7 +275,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**:
@@ -171,7 +290,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`):
 
@@ -182,21 +301,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:
@@ -208,91 +327,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.
-
----
-
-## 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:
-
-```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 pilotspace-add
-pilotspace-add init --name "My App" --stage prototype
+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`.