@pilotspace/add 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -4,6 +4,97 @@ 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.7.0] — 2026-06-18
+
+The installer & onboarding release: standing up — or repairing — ADD is now one
+guided installer that adapts to the terminal and the agent, and the method's own
+build loop gained recorded delta resolution, guided choices at every human gate,
+and a milestone-close ship review. All additive; no breaking changes (SemVer MINOR).
+
+### Added
+- **Guided, agent-aware, self-healing installer (`installer-experience`)** — `npx
+  @pilotspace/add` (and `pilotspace-add`) now runs an interactive `@clack/prompts`
+  onramp in a real terminal and degrades to a byte-identical plain-text flow in
+  CI / non-TTY (the pip twin matches, on the stdlib). It **detects the active agent**
+  (Claude Code · Claude app/cowork · Codex · OpenCode · generic) and writes that
+  agent's integration file (`CLAUDE.md` / `AGENTS.md`) as a marker-delimited pointer,
+  then prints that agent's exact next step. `init` **and** `update` now **heal/reconcile**
+  a partial `.add/` — restoring missing managed assets and refreshing stale ones
+  **without touching** `state.json` / `PROJECT.md` / milestones / tasks.
+- **Global install (`--global`)** — install the engine + book + skill once into a
+  shared ADD home (`ADD_HOME` → `XDG_DATA_HOME/add` → `~/.add`) and reuse it across
+  projects; `update --global` refreshes the home and propagates to every registered
+  project. The home mirrors the bundled layer; the registry is a flat, atomically
+  written `registry.json`, and a corrupt registry fails loud (read-before-write,
+  zero-mutation abort).
+- **Global data (`--global-data`)** — opt-in (implies `--global`): a one-way snapshot
+  of a project's **user-data** under `<home>/data/<key>` keyed by project path, so the
+  shared home remembers each opting project. The per-project, git-tracked default is
+  byte-unchanged; without the flag, data stays local.
+- **Claude Code plugin distribution** — ADD is now installable straight from a
+  marketplace, with no npm or pip step: `/plugin marketplace add pilotspace/ADD`
+  then `/plugin install add@add-method`. A repo-root `.claude-plugin/marketplace.json`
+  lists the `add` plugin, which bundles the skill, the engine, and the AIDD book; on
+  first run the skill materializes the engine and book INTO the project
+  (`cli.js init --no-skill`) so every agent and a human at the shell get a
+  self-contained result identical to an npm/pip install. The skill stays in the plugin
+  (no duplicate); boundaries are disclosed in the README and guarded by
+  `tooling/test_plugin_manifest.py`.
+- **Recorded delta resolution (`delta-resolution`)** — both delta types now resolve
+  explicitly: SPEC deltas get a `seed` / `drop` lifecycle and competency deltas
+  consolidate into the foundation via **`add.py fold`** (transcription-only, human-
+  authorized). `add.py check` stays green only when deltas are well-formed.
+- **Guided-choice prompts (`decision-suggestions`)** — every human gate (intake ·
+  bundle approval · verify · milestone close · release) renders a recommended pick
+  plus 1–3 described alternatives. Presentation-only — the engine is untouched.
+- **Milestone-close ship review (`ship-review`)** — closing a milestone now records a
+  cross-task ship review (ship-by-domain · per-task evidence · goal-met map) that the
+  existing engine gate reads, plus AI-defined release-step hints that feed `release.md`.
+
+### Notes
+- The `udd-design-loop` work (the `design.md` UDD loop + the wireframe/HTML-mock
+  recipe, described narratively under [1.5.0]) is attributed to this cut in the
+  `RELEASES.md` ledger — its first explicit ledger accounting.
+- **The engine records; the human ships.** `add.py release` recorded the `RELEASES.md`
+  row and this changelog lineage; it never bumps a version source, tags, or publishes.
+  The human-gated `git tag v1.7.0` triggers the npm / PyPI publish.
+
+## [1.6.0] — 2026-06-16
+
+The releasing release: shipping a versioned cut is now a first-class **5th ADD
+scope level**, not an ad-hoc ritual. The AI gathers the inventory and drafts
+evidence-backed notes, the engine records the cut behind a security-hard-stop
+readiness floor, and the human owns the tag and publish. All additive; no
+breaking changes (SemVer MINOR).
+
+### Added
+- **The RELEASE scope level (`release.md`)** — the on-demand guide for the 7-step
+  flow `cue → gather → draft notes → readiness floor → human confirms → cut → watch`,
+  orthogonal to stage: bundle one or more closed milestones into a versioned,
+  watched cut. Cross-referenced from `SKILL.md`.
+- **`add.py release-report`** — a read-only gather of the five record-sets (closed
+  milestones · their consolidated deltas · riding `RISK-ACCEPTED` waivers · open
+  security `HARD-STOP` · scenarios → monitors), with `--json`, plus the
+  `→ releasable: N milestone(s)` status cue.
+- **`add.py release <version>`** — a guarded, record-only cut: it prepends the
+  `CHANGELOG.md` block, appends an append-only `RELEASES.md` ledger row
+  (newest-first), and attributes the bundled milestones — behind a four-code
+  readiness floor (`release_security_open` · `release_tests_red` ·
+  `release_no_closed_milestone` · `release_undisclosed_waiver`). The security stop
+  is **un-forceable**: `--force` can override the other three, never that one.
+- **`RELEASES.md`** — the append-only release ledger (date · version · milestones ·
+  waivers · evidence); membership is the attribution source, so the cue never has
+  to read a compacted milestone file.
+- **Book chapter 16 (`16-releasing.md`)** + five glossary entries (Release · Release
+  scope level · Readiness floor · RELEASES.md ledger · Hotfix release) + the
+  `test_release_docs_accord` guard that keeps the book in accord with `release.md`.
+
+### Notes
+- **The engine records; the human ships.** `add.py release` writes the changelog +
+  ledger + attribution; it never bumps a version source, tags, publishes, or
+  deploys. The outward act stays human-owned and tool-agnostic — exactly the
+  human-gated `git tag` that cut this very release.
+
 ## [1.5.0] — 2026-06-16
 
 The UDD design-loop release: defining the design *before* the code is now a

package/README.md

@@ -30,7 +30,7 @@ across sessions (context rot). ADD fixes both:
 
 ## Install
 
-Pick your ecosystem — both install the same skill, tooling, and book:
+Pick your ecosystem — all three install the same skill, tooling, and book:
 
 ```bash
 # Node / npm
@@ -43,6 +43,17 @@ pip install pilotspace-add
 pilotspace-add init
 ```
 
+```text
+# Claude Code plugin — no npm or pip needed
+/plugin marketplace add pilotspace/ADD
+/plugin install add@add-method
+```
+
+The plugin carries the engine and the book. On first `/add`, the skill materializes them
+into the project (`node "${CLAUDE_PLUGIN_ROOT}/bin/cli.js" init --no-skill`) and scaffolds
+`.add/` — a self-contained, portable result identical to the npm/pip flow. The skill stays
+in the plugin, so nothing is duplicated.
+
 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).
 
@@ -75,6 +86,28 @@ Project state (`.add/state.json`) and the living-documentation files (`CONVENTIO
 human-owned voice) are *not* created here — the installer drops files only;
 initialisation is the agent's first move when you run `/add`.
 
+## What this plugin does, writes, and runs (boundaries)
+
+ADD is a development methodology, so by design it works *inside your project* — here is
+exactly what that means, so there are no surprises:
+
+- **Runs only when you ask.** Nothing executes on install. The skill acts when you run
+  `/add` (or another agent follows the guideline block). It is user-initiated, every time.
+- **What it runs:** the bundled engine and bootstrapper only — `node bin/cli.js` and
+  `python3 .add/tooling/add.py`. No downloaded or remote code is executed; everything it
+  runs ships in the package.
+- **What it writes:** files under your project's `.add/` (state, milestones, tasks, the
+  book) and the managed guideline block in `CLAUDE.md` / `AGENTS.md`. On a plugin install
+  it also materializes the engine + book into `.add/` on first run. It writes nowhere
+  outside the project working directory; it never touches files above the project root.
+- **Network:** one optional, advisory update check. On `status` / `guide` the engine may
+  make a single HTTPS GET to `https://registry.npmjs.org/@pilotspace/add/latest` to see if
+  a newer version exists — at most once per 24h (cached in `.update-cache.json`), 1.5s
+  timeout, fail-open (offline ⇒ silent no-op). It only writes a one-line note to **stderr**
+  and never changes a command's output or exit code. Disable it entirely with
+  `ADD_NO_UPDATE_CHECK=1`. No other network access, no telemetry, no analytics.
+- **No secrets, no credentials, no privileged access.** Pure local file orchestration.
+
 ## Use it
 
 ADD is AI-first: you talk to the agent; it drives the method. In Claude Code, run