@pilotspace/add 1.17.0 → 2.1.0

package/CHANGELOG.md

@@ -4,6 +4,199 @@ 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.
 
+## [2.1.0] — 2026-07-22
+
+Minor: the two-agent roster matures and the persona author learns from real
+corpora; TDD flexes for non-coding tasks; every honest verify→build round
+becomes engine-visible; the dogfood foundation completes its 2.0 migration.
+
+- **two-agent roster** — `add` retires; **add-worker** runs every EXECUTION
+  beat (direction · build · verify · persona) and **add-advisor** is the
+  second mind serving EVERY beat (propose-plan · advise-midflight · refute)
+  with a per-beat calibration map. The worker gains a mid-flight **support
+  fan-out** for medium/large builds: non-overlapping §3-Scope slices,
+  worktree isolation per support worker, the lead serializes git and re-runs
+  the FULL suite on every return; the quality floor multiplies, never dilutes.
+- **persona-author skill** — the static `.add/personas/_template.md` retires
+  for a `persona-author` skill (contract · patterns · seeding references +
+  two worked examples). Patterns grow 9 → 11 from a deep diagnosis of 13
+  sample subagents and the 256-file teacher corpus: NEW *numbers-you'd-defend*
+  (a named budget beats an adjective; fake precision is worse than none) and
+  *per-flow stance* (what a lens LEADS with at build vs REFUSES at verify —
+  the verify stance carries a default NEEDS-WORK verdict); seeding gains
+  mine-the-gold / refuse-the-rot source guidance. All 6 live roster personas
+  folded to patterns-v11.
+- **flexible TDD** — §4 supports failing-first **acceptance checks** for
+  non-coding kinds (docs · release · infra): verifiable pass/fail evidence,
+  red before the artifact exists, green after — the red→green discipline
+  holds; only the must-be-executable-code requirement is lifted. Guide,
+  template, and book reframe; NO engine change (the kernel was already
+  tolerant); 21 non-coding prose-guard tests retired dogfooding the policy.
+- **round-visible runs** — every verify→build return trip is a recorded
+  **round**: `add.py phase build [--note "finding"]` and every non-exhausted
+  heal return increment an uncapped, observational `tasks[slug].rounds`
+  (count + timestamped history, notes verbatim); `status` names `round N`;
+  the route trace carries `"rounds"` beside `"heals"`. Heal stays the
+  cheat-classed, capped subset; rounds are the honest whole. `--note` off
+  the build target refuses (`phase_note_build_only`).
+- **foundation-split** — the dogfood board completes the 1.x→2.0 foundation
+  migration this package's own `migrate` verb leaves to judgment: PROJECT.md
+  322 → 63 lines (engine-read lines byte-identical), the pre-2.0 standing
+  picture folded into the five `.add/specs/` living specs with a per-bullet
+  fold ledger — the worked example external 2.0 upgraders can follow.
+- **SKILL.md command cookbook** — the skill router carries the common
+  call recipes so agents skip the `-h` round-trip; README copy tightened
+  (benefit-led highlights, honest tradeoffs, no dollar figures).
+
+Retired (no CLI/install surface change): the `add` roster agent (superseded
+by add-worker + add-advisor) and the static persona template (superseded by
+the persona-author skill; `init` now creates an empty personas dir and the
+hints point at the skill).
+
+## [2.0.0] — 2026-07-18
+
+Major: ADD 2.0 — a skill-led method on a thin state kernel. The skill drives
+the loop; `add.py` records state and guards the seams; **personas carry the
+playbooks** the platform pillars used to hard-code.
+
+- **engine-kernel-trim** — the verb surface collapses 54 → 31: the platform
+  pillars die as engine code (streams/waves/DAG orchestration · components/
+  federation · release/graduation engines · gate-audit machinery · fold/compact
+  consolidation · team verbs · the SPEC-delta trio · doctor/worktree-prep) and
+  their workflows live on as seed-persona playbooks. `add.py` shrinks
+  9,558 → 6,596 lines; the phase guides fold 17 → 12.
+- **PLAN.md** — the task doc is `PLAN.md` everywhere (was TASK.md; the
+  template is `PLAN.md.tmpl`), and the new one-shot **`add.py migrate`**
+  converts a 1.x board: renames live + archived task docs, seeds any missing
+  living spec, idempotent, refuses `migrate_conflict` before touching anything.
+- **5-DD living specs** — `.add/specs/` (domain · system · experience ·
+  quality · method) with **`add.py delta-append`** as the in-flight lesson
+  channel; the fold ceremony is gone.
+- **book-stops-shipping** — the AIDD book publishes at
+  https://pilotspace.github.io/ADD/ and never installs; engine chapter
+  pointers deep-link the site (`BOOK_URL`), installers drop the docs tree,
+  and a legacy `.add/docs/` from 1.x is user-space (never swept).
+- **phase-collapse-3** — the lifecycle is direction · build · verify: ONE
+  freeze approval crosses the whole Direction bundle; the 3-call walk
+  (`new-task` · `freeze --by --cross` · `gate PASS`) is the whole ceremony.
+- **persona routes + route scoreboard (GEPA)** — the persona proposes the
+  lane (`route:` header, ratified at freeze); every recorded gate appends a
+  route-outcome trace, and `add.py deltas` rolls the traces up per lane —
+  the evidence the PM persona reflects on GEPA-style, proposing route-rule
+  deltas the human folds into the persona file.
+
+Breaking (the 2.0 line): removed verbs refuse as unknown commands; task docs
+must be `PLAN.md` (`add.py migrate` is the paved path); the book no longer
+lands in `.add/docs/`; `TASK.fast.md.tmpl` is gone (one template, every lane).
+
+## [1.18.0] — 2026-07-14
+
+Minor: eleven milestones, expanded from the original July-7 two-milestone cut
+(unpublished — the 1.17.0-amend precedent) to attribute everything merged
+since. Headline: **six-phase-loop** — the lifecycle merges 8 phases into 6
+(specify absorbs scenarios; verify absorbs observe), phase guides disclose
+into the roster's bundle subagents, and the tick into build re-renders the
+frozen spec. Also: **expectations-first** (plan phase; ONE freeze),
+**plan-legibility**, **quality-floors**, **risk-proportional-ceremony**,
+**three-phase-flow**, **add-bench** + **add-bench-v2** (the trust benchmark
+that measured it all), **add-lean-loop**, plus the original
+**build-strategy-facets** and **delta-drain**. The ceremony-to-effort and
+call-floor features (compound ticks · scope echo · kickoff truth · skill
+orient split) ship here too; their milestones remain open on measurement
+criteria. Folded in after the July-14 cut: the **engine-minimalism /
+context-cost thread** — a progressive foundation read, a lean default `status`,
+and one fewer ceremony turn per crossing — measured by **token-anatomy** and
+**honest-fidelity-meter**. No gate weakened; a security finding still HARD-STOPs.
+
+### Changed (the headline)
+- **The loop is six phases**: `specify → plan → tests → build → verify → done`.
+  Scenarios live inside SPECIFY (§2 unchanged as a section); the observe duties
+  live inside VERIFY (§7 unchanged). Legacy phase tokens (`ground`, `contract`,
+  `scenarios`, `observe`) normalize on read — in-flight boards migrate loud and
+  safe; the skip grammar is retired (nothing is skippable; vestigial `skips:`
+  headers are noted at gate, never fatal) (six-phase-loop).
+- **Guides re-cut to 6 files**; delegating spawns a bundle agent that loads its
+  own phase guides — the orchestrator reads only SKILL.md; the inline lane stays
+  first-class (six-phase-loop).
+- The specification bundle approves at ONE freeze on the plan phase
+  (expectations-first); the freeze report renders the BUILD PLAN block and the
+  resolved scope echo (plan-legibility, ceremony-to-effort).
+
+### Added
+- **Build-entry spec echo** — the tests→build tick prints the §1 Must/Reject
+  rules + the frozen §3 contract head, so the builder starts from the spec on
+  the screen, not from memory; fail-open, both entry paths (six-phase-loop).
+- **Per-phase persona presets** — teacher-grade expert stances per owned phase
+  in the roster agents; project-persona routing stays first; a preset never
+  lowers a gate (six-phase-loop).
+- **Compound ticks** — `freeze --cross` lands in tests; `gate` records from
+  build (one call fewer per crossing); init prints the resume pointer
+  (call-floor).
+- **Quality floors** — spec-dialect warn at build entry · fast-lane
+  `Boundary:` freeze-refusal · §6 DIALECT check line (quality-floors).
+- **The trust benchmark** — arms × workload-milestones harness with
+  deterministic oracles, tamper/regression meters, and the
+  cost-per-trusted-feature verdict (add-bench, add-bench-v2).
+- **AI-plan-verify gate + phase bundles** (three-phase-flow) · message-layer
+  error ergonomics, −24% turns at equal rigor (risk-proportional-ceremony).
+
+### Added (from the original July-7 cut)
+- **Faceted §5 build strategy** — four domain-generic facet lines drafted at
+  the tests→build cross: `Approach` (domain strategy) · `Data strategy` ·
+  `Pattern` · `Optimization stance`; the fast lane collapses them to one line
+  (build-strategy-facets).
+- **per-facet ADR harvest** — each §5 facet lands in §7 Decisions (ADR) as its
+  own actor-tagged line at done (build-strategy-facets).
+- **compact-foundation `--propose`** — a read-only preview of the compaction a
+  run would take; inspect before any byte moves (delta-drain).
+- **`verify` flow value for personas** — personas route to the verify surface
+  directly; the streams.md worker-contract `<persona>` block names the flow
+  preference (delta-drain).
+- **persona roster line** — `status`/`check` render an engine-built roster with
+  flows, never hand-maintained (delta-drain).
+
+### Changed
+- §5 build strategy guidance, phase guides, and the TASK.md/TASK.fast.md
+  templates teach and carry the facet block (build-strategy-facets).
+
+### Fixed
+- **Installer data loss** — `.claude/agents` is a shared namespace: init/update
+  now land only ADD's own roster files per-file (atomic), removal is
+  explicit-tombstone-only — the user's own subagents survive every install and
+  update (loose task installer-shared-namespace-guard, PR #151).
+
+### Added (engine-minimalism — the context-cost thread)
+- **Progressive foundation read** — `status --foundation` prints a MAP (the preamble +
+  `invariants:` + Domain + Spec in full; every other section collapsed to its heading +
+  an on-demand `add.py status --foundation "<section>"` pull), so the cross-milestone
+  foundation that is re-read every turn is a slice, not the whole file; a named section
+  fleshes out on demand and `--all` restores the whole foundation (foundation-slice, −59%
+  on a 55KB foundation). Invariants never collapse — the contracts that bind every task
+  always survive the map.
+- **Lean default `status`** — bare `status` prints the resume essentials; five heavy
+  blocks gate behind `--all`; `status --brief` is the mid-task resume; `status --section
+  <n>` reads one TASK.md §body instead of the whole growing file (engine-minimalism).
+- **`--help` diet** — the top-level help drops from 121 lines to 19 (engine-minimalism).
+
+### Changed (engine-minimalism)
+- **One fewer ceremony turn per crossing** — a green build steers straight to `gate PASS`;
+  the redundant pre-gate `advance` is folded away (ceremony-turn-cut / advance-fold).
+- **Leaner per-turn engine output** — bare `status` stops restating the 'now' card in its
+  resume block; `new-task` teaches the full annotated recipe once per project, compact
+  thereafter; the skill re-orients from each verb's `next:` footer instead of re-running
+  `status` (engine-output-trim, status-brief-adoption, trust-the-footer).
+
+### Added (measurement — not shipped in the package)
+- **Token anatomy** attributes a benchmark run's cache-read cost by category; a
+  deterministic **`requirement_coverage`** meter replaces the artifact-blind spec-fidelity
+  judge (now a source-aware, non-gating annotation); scoring is hermetic per boot
+  (token-anatomy, honest-fidelity-meter). Dev harness under `benchmark/` — not in the
+  npm/PyPI tarball.
+
+### Disclosed waivers (non-security, signed)
+- `reclaim-ticket-race` — lock-reclaim TOCTOU flake; owner Tin Dang, expires 2026-08-04.
+- `js-reclaim-lock-heartbeat` — JS lock-heartbeat race; owner Tin Dang, expires 2026-08-04.
+
 ## [1.17.0] — 2026-07-06
 
 Minor: four milestones — **method-ergonomics** (every recurring gate rule becomes

package/GETTING-STARTED.md

@@ -53,7 +53,8 @@ at the `prototype` stage. (Prefer to choose up front? Both installers take
 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
+`.claude/skills/add/`. The book itself is published at
+https://pilotspace.github.io/ADD/ and never installs into the project. It deliberately
 does **not** initialise the project — that's the agent's first move, so nothing
 gets decided without you in the loop.
 
@@ -61,7 +62,7 @@ gets decided without you in the loop.
 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`.
+> See https://pilotspace.github.io/ADD/10-setup-and-stages/.
 
 ### Updating to a newer ADD — no re-install
 
@@ -79,7 +80,7 @@ pipx run pilotspace-add update
 pip install -U pilotspace-add && pilotspace-add update
 ```
 
-`update` clean-replaces the managed layer (`skill` · `.add/tooling` · `.add/docs`)
+`update` clean-replaces the managed layer (`skill` · `.add/tooling`)
 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.
@@ -115,7 +116,7 @@ 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`.
+> New term: **Onboarding** — the install→first-milestone path. See https://pilotspace.github.io/ADD/appendix-c-glossary/.
 
 ---
 
@@ -169,56 +170,11 @@ Confirm your project is internally consistent at any time:
 python3 .add/tooling/add.py check
 ```
 
-It verifies state is valid, every task has its TASK.md, and markers match. Exit
+It verifies state is valid, every task has its PLAN.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'
-
-      - 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 flow. This
@@ -227,7 +183,7 @@ each one produces and step in manually whenever you want to. You never *have* to
 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.
+The tool keeps the `phase:` marker at the top of PLAN.md in sync.
 
 ### Before the phases — initialise and scaffold
 
@@ -244,7 +200,7 @@ python3 .add/tooling/add.py new-task transfer --title "Transfer money between my
 > 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
+This scaffolds `.add/tasks/transfer/PLAN.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.
 
@@ -254,7 +210,7 @@ You can also change the project's depth at any time:
 python3 .add/tooling/add.py stage mvp
 ```
 
-### Phase 1 — Specify (`.add/docs/03-step-1-specify.md`)
+### Phase 1 — Specify (https://pilotspace.github.io/ADD/03-step-1-specify/)
 
 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:
@@ -278,7 +234,7 @@ Confirm every assumption (no FX, no daily limit in v1). Then:
 python3 .add/tooling/add.py advance
 ```
 
-### Phase 2 — Scenarios (`.add/docs/04-step-2-scenarios.md`)
+### Phase 2 — Scenarios (https://pilotspace.github.io/ADD/04-step-2-scenarios/)
 
 In **§2**, turn each rule into a Given/When/Then. For every rejection, assert what
 must stay **unchanged**:
@@ -293,7 +249,7 @@ Scenario: insufficient funds
 
 Then `python3 .add/tooling/add.py advance`.
 
-### Phase 3 — Contract (`.add/docs/05-step-3-contract.md`)
+### Phase 3 — Contract (https://pilotspace.github.io/ADD/05-step-3-plan/)
 
 In **§3**, fix the external shape and **freeze** it (`Status: FROZEN @ v1`):
 
@@ -306,19 +262,19 @@ POST /transfers  body: { fromAccountId, toAccountId, amount }
 
 A frozen contract is the decision point that makes the AI build safe. Then advance.
 
-### Phase 4 — Tests, red first (`.add/docs/06-step-4-tests.md`)
+### Phase 4 — Tests, red first (https://pilotspace.github.io/ADD/06-step-4-tests/)
 
 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 (`.add/docs/07-step-5-build.md`)
+### Phase 5 — Build (https://pilotspace.github.io/ADD/07-step-5-build/)
 
 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 (`.add/docs/08-step-6-verify.md`)
+### Phase 6 — Verify (https://pilotspace.github.io/ADD/08-step-6-verify/)
 
 In **§6**, confirm the evidence (all green, nothing weakened) and check what tests
 miss: concurrency, security, architecture. Record the gate — and close the task:
@@ -330,7 +286,7 @@ 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 (`.add/docs/09-the-loop.md`)
+### Phase 7 — Observe (https://pilotspace.github.io/ADD/09-the-loop/)
 
 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.
@@ -341,11 +297,11 @@ becomes the next `new-task`. The flow is a loop, not a finish line.
 
 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-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`
+- The shift & principles — https://pilotspace.github.io/ADD/00-introduction/, https://pilotspace.github.io/ADD/01-principles/
+- The flow end to end — https://pilotspace.github.io/ADD/02-the-flow/
+- Each step in depth — https://pilotspace.github.io/ADD/03-step-1-specify/ through https://pilotspace.github.io/ADD/09-the-loop/
+- Operating it on a team — https://pilotspace.github.io/ADD/11-governance/, https://pilotspace.github.io/ADD/12-roles/
+- A fully worked example — https://pilotspace.github.io/ADD/appendix-d-worked-example/
 - Building UI? The render-ready UDD foundation — `.add/DESIGN.md` is the prose
   front-door to a lintable design system (`.add/design/` tokens · catalog ·
   prototypes) the AI drafts from; `add.py check` lints it (delete `DESIGN.md` if