@pilotspace/add 1.16.1 → 2.0.0

package/CHANGELOG.md

@@ -4,6 +4,233 @@ 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.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
+a form the engine presents at that moment, cutting per-task ceremony without
+moving the safety floor), **persona-domain-fit** (a new milestone or task
+whose domain no existing persona covers gets a concrete draft-one nudge),
+**dynamic-personas** (a drafted persona carries `flow:` routing to its agent
+surface, at teacher-grade depth and load cost), and **self-improving-loop**
+(the observe→deltas→fold→compact loop surfaces its own accumulation instead of
+rotting silently) — plus twelve loose tasks. New engine verbs are additive; no
+gate weakened, nothing removed or renamed.
+
+### Added
+- **`add.py gate --explain [slug]`** — a read-only dry-run of the verify gate:
+  prints phase · autonomy · risk · sensitivity · advisor lines and one
+  `path: AUTO | HUMAN | RELAX | REFUSED (reason)` verdict, always ending with
+  the security floor (a security finding is always HARD-STOP). Writes nothing.
+- **`add.py advance --to <phase>`** — fast-forwards a drafted bundle's
+  bookkeeping crossings in one call, stopping hard at `tests` (the freeze gate,
+  tamper tripwire and scope snapshot are never skipped).
+- **`add.py re-cross`** — records a human-approved post-freeze re-cross
+  (`--by` required): re-runs the full tests→build gate stack to legally
+  re-snapshot after an approved test addition, never bypassing the freeze.
+- **`add.py worktree-prep <slug>`** — mechanizes the spawn-isolation recipe:
+  cuts a git worktree at HEAD, materializes the gitignored `.add/tooling` +
+  `.add/docs` a tracked-only checkout lacks, and echoes the fork base for the
+  WAVE.md ledger. Workspace-only; state.json is never written.
+- **Verify-record rollup** — `add.py audit` folds its four §6 shape lints into
+  one `verify_record_incomplete` line per task.
+- **Delta verbs reach archived tasks** — `drop-delta` / `carry-delta` /
+  `reopen-delta` now operate on a light-archived task's on-disk TASK.md
+  (explicit slug only, `(archived — on-disk record)` marker, state untouched).
+- **Batched intake + batched gates** — intake.md and report-template.md
+  document one report + one confirm for N same-gate items (per-item
+  lowest-confidence flags; any item holdable by name). Presentation only.
+- **Domain test forms** — 4-tests.md states that a test is any
+  machine-checkable assertion (metric threshold · reconciliation query ·
+  plan-diff · rendered-screen diff), red-first holding for each.
+- **Persona domain-fit nudge** — a milestone/task whose domain no existing
+  persona covers is nudged toward drafting a fitting one; TASK templates now
+  require a named persona and carry a domain-strategy hint.
+- **Fast-lane ground anchor** — the `--fast` template's §0 gains the
+  `Ground SHA:` drift anchor, so a fast task can clear the stale-line-ref WARN.
+- **Persona `flow:` routing** — a persona's `flow:` frontmatter (design | build
+  | advisor) is now read, not just written: the 4 flow-routed roster agents,
+  `design.md`'s evidence checklist, and `advisor.md`'s spawn block all select
+  a persona flow-first; add-persona drafts the current schema (`flow:` /
+  `source:` / `## Abilities`) and returns `flow` in its verdict.
+- **Persona load performance** — every seeded persona gains `## Abilities`
+  (orient-command-led) and `## Anti-patterns`; selection is frontmatter-first
+  (name · vibe · flow, then one body — not the whole roster); add-persona
+  routes the teacher library by division directory, never its catalog README.
+- **Fold grows the current persona schema** — `add.py fold` routes a
+  `persona:<slug> · anti-pattern|ability` lesson into those sections too (was
+  limited to `critical-rule`/`success-metric`), so the persona learning loop
+  can grow the sections that shape agent behavior.
+- **Loop-surfacing status cues** — `add.py status` names the carried
+  spec-delta backlog and the un-compacted foundation tail (last-rolled vs.
+  current `foundation-version`) once either passes a noticeable size;
+  `release-report` lists the carried total. Additive; a clean project's
+  output is unchanged.
+- **`skill/add/self-improve.md`** — one map of how ADD improves itself: the
+  four self-improving artifacts (foundation · personas · `SOUL.md` · next
+  scope), routed across the 5 domains, fed by all 8 steps.
+
+### Changed
+- **Sequential+auto is the default run mode** — parallel streams stay a
+  deliberate, persisted opt-in.
+- **Leaner TASK.md template** — instructional comment bloat trimmed 16%
+  (comments −27%); every machine-parsed marker untouched.
+- **Leaner guides** — run.md's specification-bundle section is a pointer at
+  its one home (`phases/3-contract.md`); the ⚠ flag grammar now lives in
+  exactly one guide.
+- **Waiver field census is case-insensitive** — `audit` recognizes
+  `Owner:/Ticket:/Expires:` as written by the signed records; the
+  missing-field refusal is unchanged.
+
+### Fixed
+- The CI-observed reclaim-ticket race in `_update_lock` (+ its JS/npm
+  heartbeat twin), orphaned reclaim-ticket sweep, the prune-data/update-global
+  lock race, the ADR harvester's multi-line field capture, and the
+  strip-scaffold backtick-comment over-strip.
+
 ## [1.16.1] — 2026-07-04
 
 Patch: two loose, additive persona-loop improvements found while dogfooding

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