specpi 0.20.1 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.21.0 - 2026-09-14
+
+This release resets SpecPi's base and removes previously shipped harness features. Both retained Pi extensions ship as part of SpecPi 0.21.0. SpecPi Chat 0.7.1 remains the separately packaged VS Code frontend and is aligned with the new base.
+
+- Reduce SpecPi to `/scope` and the human-selected harness improvement loop, including its local evidence, contracts, verification, retirement, and reopen behavior.
+- Remove SpecPi's custom delegation, Command Guard, background tasks, browser and structural tools, extra workflow commands, file review UI, themes, and shell profiles.
+- Replace the old showcase site with a short installation and package guide. Keep existing documentation URLs working and provide a direct download for Chat 0.7.1.
+- Update the VS Code frontend for the upstream package base: pi-subagents activity and result cards, visible package messages, Permission System settings and approval dialogs, and existing usage/status reporting. Preserve the chat UI, attachments, history, and separate VSIX packaging.
+- Establish the new default base through eight pinned upstream Pi packages: pi-web-access 0.29.0, betterwright 2.8.1, pi-subagents 0.67.0, pi-lens 4.1.6, pi-background-tasks 2.5.0, pi-goal-x 0.31.2, @sreetej510/pi-usage 0.10.0, and @gotgenes/pi-permission-system 32.0.2. Keep the first-party surface limited to scope and the improvement loop.
+- Install and update the base with Pi's package installer, preserve unrelated settings and resource filters, and restore unchanged owned package entries on uninstall. Document upstream script/download rollback limits, BetterWright's separate browser setup, and Pi 0.84.4 compatibility. Keep an explicit core-only skip option and isolated real-package validation.
+- Save exact npm dependency versions during package acquisition and verify installed versions before completing the transaction, preventing later package installs from advancing an earlier pin.
+- Keep explicit, backed-up installation and removal. Updates retire old managed resources, restore owned settings, remove shell marker blocks, and preserve retired runtime bytes and modified resources in local backups. Restart Pi after updating to unload retired extensions.
+
 ## 0.20.1 - 2026-09-10
 
 - Enable `structural_search` by default on fresh installs and updates without a saved choice. Persist enablement transactionally and preserve explicit opt-outs; disable with `specpi update --structural-search=off`, then restart Pi.

package/NPM_RELEASE.md

@@ -4,22 +4,23 @@ Publishing, tags, deprecation, ownership changes and GitHub Releases require exp
 
 ## Prepare
 
-1. Choose an unused version; update `package.json`, dated `CHANGELOG.md` entry, README and site. Preserve historical changelog entries.
-2. Chat has an independent version: if changed, align `vscode/package.json`, its changelog, guides and VSIX filenames. Run its check, render, isolated VSIX and package scripts. The VSIX is not in the npm tarball; building does not authorize Marketplace publication.
-3. Validate:
+1. Choose an unused version; update `package.json`, the dated `CHANGELOG.md` entry, README, and the website. Check Chat's version and VSIX download links. Preserve historical changelog entries.
+2. Validate:
 
    ```sh
    npm install --ignore-scripts --omit=peer --no-package-lock
    npm run check
    npm run check:pi-package
+   npm run check:base
+   npm run check:site
    npm publish --dry-run --ignore-scripts --provenance=false
    npm pack --dry-run --json
    git diff --check
    ```
 
-   Browser changes also require their opt-in browser gates. Installer/Pi lifecycle tests must use disposable state, never a live profile. Local dry runs disable provenance because they lack GitHub OIDC.
-4. Review the diff, exact package manifest and artifact; obtain fresh read-only review for lifecycle, permissions and packaging changes.
-5. After approval, merge to `main`, then create the matching `v<version>` tag and GitHub Release. Approve the protected `npm` environment promptly: Pages may already advertise the version. If publication cannot complete, revert the release merge and use a new version for the next attempt.
+   Installer/Pi lifecycle tests must use disposable state, never a live profile. `check:base` requires network access and verifies the real eight-package base with isolated home/configuration paths. Review all default version changes, upstream lifecycle scripts, compatibility, and notices in `THIRD_PARTY.md`. Local dry runs disable provenance because they lack GitHub OIDC.
+3. Review the diff, exact package manifest and artifact; obtain fresh read-only review for lifecycle, permissions and packaging changes.
+4. After approval and passing PR checks, merge to `main`, then create the matching `v<version>` tag at the merge commit. Build Chat's VSIX with `npm --prefix vscode run package` and attach it to the GitHub Release. Publish the release to start the npm workflow and approve the protected `npm` environment if it requests review. Verify the website deployment and download links. If publication cannot complete, revert the release merge and use a new version for the next attempt.
 
 ## Protected publication
 

package/README.md

@@ -1,74 +1,103 @@
-<p align="center">
-  <img src="site/logo.svg" width="104" alt="SpecPi logo">
-</p>
+# SpecPi
 
-<h1 align="center">SpecPi</h1>
+A small base for the [Pi coding agent](https://pi.dev/). Set the scope of a task, notice recurring problems, and choose what to improve. Eight upstream packages provide the supporting tools.
 
-<p align="center">
-  A small toolkit for the <a href="https://pi.dev/">Pi coding agent</a>.
-</p>
+**0.21.0 resets the base.** SpecPi's own Pi extensions now provide only `/scope` and the harness improvement loop. Custom tools, extra workflow commands, themes, and shell profiles have been removed. **SpecPi Chat 0.7.1** remains the VS Code frontend. Read [the release notes](CHANGELOG.md) and the migration instructions below before updating.
 
-<p align="center">
-  <a href="#install">Install</a>
-  · <a href="https://tannermidd.github.io/SpecPi/">Website</a>
-  · <a href="https://tannermidd.github.io/SpecPi/wiki/">Documentation</a>
-</p>
+[Website](https://tannermidd.github.io/SpecPi/) · [Download Chat](https://github.com/TannerMidd/SpecPi/releases/download/v0.21.0/specpi-chat-0.7.1.vsix) · [Releases](https://github.com/TannerMidd/SpecPi/releases)
 
-SpecPi extends Pi with chat, review tools, and focused delegation. Its principles are simple: you choose the improvements, changes stay small and reversible, improvement records stay local, and checks matter more than an agent's claims.
+## Install
+
+Requires Node.js 22.19+, Git, npm, and an existing Pi installation on PATH. The complete base is tested with Pi **0.84.4**; `pi-goal-x` currently declares Pi `>=0.83.0 <0.85.0` compatibility.
+
+```sh
+npm install --global specpi@latest
+specpi plan
+specpi install
+specpi doctor
+```
 
-<details>
-<summary>Watch the showcase · 51 seconds</summary>
+Inspect the plan, confirm the install, then restart Pi. SpecPi installs two first-party extensions, the improvement skill, a marked working agreement, and the packages below using `pi install`. Provider and model settings are preserved. There are no additional SpecPi extensions, themes, shell profiles, tool wrappers, or browser bootstrap scripts.
 
-<p>
-  <a href="https://tannermidd.github.io/SpecPi/#showcase">
-    <img src="https://tannermidd.github.io/SpecPi/media/showcase-poster.jpg" width="560" alt="Play the SpecPi showcase">
-  </a>
-</p>
+For this checkout, run `node scripts/specpi.mjs` in place of `specpi`. `PI_CODING_AGENT_DIR` selects an alternate destination; `SPECPI_PI` selects a Pi CLI path. `specpi install --skip-package-install` installs only the first-party core for offline use and testing. A plain `pi install npm:specpi` loads only the packaged first-party resources; use the SpecPi installer above for the complete base, and avoid installing the same first-party resources both ways.
 
-</details>
+## Default packages
 
-## What it adds
+These are installed on every normal install and update. Exact versions live in [`templates/settings.json`](templates/settings.json); SpecPi merges only the package entries, preserving unrelated configuration and existing resource filters.
 
-- **Focused delegation.** One agent makes changes. Up to two read-only subagents help investigate and review. [Research and design](https://tannermidd.github.io/SpecPi/single-agent/)
-- **Background tasks.** Start an approved dev server, test suite, or watch build, inspect bounded output, and stop it without blocking other work.
-- **Review as you work.** Track changed files, inspect diffs, check pages in a browser, and review risky commands.
-- **Structural search.** Bounded ast-grep patterns over selected code are enabled by default. Disable with `specpi update --structural-search=off`; on unsupported native hosts, pass `--structural-search=off` during installation too. [Usage and limits](docs/structural-search.md)
-- **Accessibility checks.** Scan the current browser state for automated WCAG and optional best-practice findings. [Browser verification](docs/browser-testing.md)
-- **Improvements you choose.** Record recurring problems, select one with `/harness-improvement`, and test the change before calling it done.
+| Package | Pinned version | Purpose |
+| --- | --- | --- |
+| [pi-web-access](https://github.com/nicobailon/pi-web-access) | 0.29.0 | Web search and page retrieval |
+| [betterwright](https://github.com/BetterWright/betterwright) | 2.8.1 | Browser automation |
+| [pi-subagents](https://github.com/nicobailon/pi-subagents) | 0.67.0 | Subagents and delegation |
+| [pi-lens](https://github.com/apmantza/pi-lens) | 4.1.6 | Language diagnostics, navigation, and structural tools |
+| [pi-background-tasks](https://github.com/ismailsaleekh/pi-background-tasks) | 2.5.0 | Durable background tasks |
+| [pi-goal-x](https://github.com/tmonk/pi-goal-x) | 0.31.2 | Persistent goals and progress |
+| [@sreetej510/pi-usage](https://github.com/Sreetej510/pi-extensions/tree/main/extensions/pi-usage) | 0.10.0 | Provider usage reporting |
+| [@gotgenes/pi-permission-system](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system) | 32.0.2 | Tool permission policies |
 
-Problem collection is off by default. Its records stay on your machine. Pi connects to your chosen model provider.
+The effective commands are `pi install npm:<package>@<version>` for each row, including the scoped names. These packages supply their own extensions, tools, skills, and prompts according to their upstream defaults. SpecPi does not add a second implementation or configure their policies.
 
-## Install
+SpecPi requests exact npm dependency saves for these installs and verifies installed versions before completing the transaction. This keeps later package installs from advancing an earlier pin through npm's default version ranges.
+
+BetterWright's browser is a separate upstream setup step: install Bun 1.4+ and run `bunx betterwright@2.8.1 setup` before using browser tools. See [BetterWright setup](https://github.com/BetterWright/betterwright/blob/main/SETUP.md). The default package installation does not install Bun or download its browser. Provider credentials, web-service configuration, language servers, and permission rules remain governed by each package's documentation. Package installation and extension loading do not prove that every external service or tool is ready.
+
+## VS Code
+
+[SpecPi Chat](https://github.com/TannerMidd/SpecPi/blob/main/vscode/README.md) provides the chat sidebar, file and image attachments, conversation history, tool output, package commands, and approval dialogs. Version **0.7.1** adds the new package base's visible messages, a Permission System settings button, and pi-subagents activity and result cards. The VSIX remains separate from the npm harness package.
+
+Download the [0.7.1 VSIX](https://github.com/TannerMidd/SpecPi/releases/download/v0.21.0/specpi-chat-0.7.1.vsix), then run **Extensions: Install from VSIX…** in VS Code. To build from source, run `npm --prefix vscode run package`; the file is written to `.specpi-test/vscode/specpi-chat-0.7.1.vsix`. See the [Chat guide](https://github.com/TannerMidd/SpecPi/blob/main/vscode/GUIDE.md) for package support and terminal-only controls. Install/update SpecPi separately, then restart Pi in Chat to reload its extensions.
 
-Requires **Node.js 22.19+**, **npm**, and **Git**. SpecPi needs **Pi 0.84.4+**; the installer can add it if missing.
+## Scope
+
+- `/scope set`: declare project-relative files or directories, one per line.
+- `/scope status`: review declared paths, pending drift, and snapshot uncertainty.
+- `/scope add <path>` or `/scope remove <path>`: change the declared scope.
+- `/scope accept <path>`: acknowledge a finding without adding that path to scope.
+- `/scope recheck`: deliberately refresh the baseline after an uncertain snapshot.
+- `/scope clear`: turn monitoring off.
+- `/scope task`: import the active improvement contract's paths explicitly.
+
+Interactive writes and edits outside scope ask before proceeding. In headless mode they are recorded as pending. Other tools are checked afterward against bounded Git snapshots. Scope is a drift monitor, not a sandbox: shell commands and custom tools can already have changed files when drift is reported. State follows the current Pi session branch.
+
+## Harness improvement loop
+
+1. Enable local observations with `/wishlist on`; collection is off by default. `/wishlist off` stops it.
+2. Review recurring gaps with `/wishlist` and select one through `/harness-improvement` in a complete SpecPi source checkout.
+3. Follow the `specpi-improve` skill: record a bounded contract, implement the smallest sufficient change, and gather direct acceptance evidence.
+4. `finish_harness_improvement` verifies the selected contract, source changes, repository checks, and registered capability validators before retirement.
+5. Review the journal with `/wishlist history <gap-id>`. A regression returns the item for human selection; it never authorizes an automatic fix.
+
+Observations are leads, not permission. Records stay local, use sanitized summaries and salted identifiers, and are never uploaded automatically. Pi still sends model requests to your selected provider. `/wishlist outcome <gap-id>` records the human's assessment of a local retirement.
+
+## Update and remove
 
 ```sh
 npm install --global specpi@latest
 specpi plan
-specpi install
+specpi update
 specpi doctor
+specpi uninstall
 ```
 
-Preview the changes, confirm the install, then check the setup. Restart Pi when finished.
+Install, update, and uninstall require confirmation; `--yes` supplies it for automation. Modified retained resources require `update --force`. Managed configuration and resources are backed up and checksum-tracked. `update --skip-package-install` preserves an existing base without invoking Pi's package installer. Normal updates reapply the reviewed pins.
 
-To pin this release, use `npm install --global specpi@0.20.1`.
+Updating from the larger harness retires its recorded extra resources, restores legacy settings that still match ownership records, removes its shell marker block, and installs the new package base. Modified retired files and old runtime directories are preserved under `<agent-dir>/specpi/backups/`. Restart Pi to unload the old extensions. Unrelated configuration and local improvement evidence remain intact.
 
-Delegation is enabled at startup. Use `/delegate off` to turn it off.
+Uninstall restores package entries that still match SpecPi's recorded changes and preserves subsequent user edits. Downloaded packages, npm caches, upstream configuration, and private evidence remain on disk. A failed install rolls back SpecPi-managed files and configuration; package downloads and upstream install-script effects cannot be rolled back. `doctor` checks the core, package settings, and installed top-level package versions without activating upstream tools.
 
-[Setup, updates & removal](https://tannermidd.github.io/SpecPi/wiki/#getting-started) · [Delegation settings](docs/delegation/README.md)
+## Development
 
-## SpecPi Chat for VS Code
-
-Chat beside your code, attach files, and switch conversations.
-
-[**Install from Marketplace**](https://marketplace.visualstudio.com/items?itemName=tannermidd.specpi-chat) · Requires VS Code 1.96+, Node.js 22.19+, and Pi 0.84.4+. SpecPi is optional.
-
-In VS Code, find **SpecPi Chat** by **tannermidd** in Extensions and install it. Open **SpecPi** in the Activity Bar, then **Connect Pi**.
-
-Chat 0.4.4 shows a compact delegation strip only while workers run or settle, and opens workspace image links in the image viewer. SpecPi 0.19.1 fixes delegation when switching GitHub Copilot models in the same chat, including Luna → Opus → Luna. Update the harness and use **Restart Pi** to load the fix; this patch does not require a Chat update. Later model switches do not require a restart. New Chat sessions start with Guard off; use `/guard guard` or `/guard strict` to enable it.
+```sh
+npm install --ignore-scripts --omit=peer --no-package-lock
+node --test tests/workflow-controls.test.mjs tests/workflow-controls-extension.test.mjs
+npm run check
+npm run check:pi-package
+npm run check:base
+```
 
-## Go further
+Installer tests use disposable Pi directories. `check:base` requires network access, installs the real eight packages in isolated state, loads them together through Pi 0.84.4, verifies Chat RPC startup and explicit permission replies, and checks removal. It does not send model requests or run browser tasks. Never test against a live Pi installation. Publication remains explicit and uses the [release procedure](NPM_RELEASE.md).
 
-[Commands](https://tannermidd.github.io/SpecPi/wiki/#reference) · [Chat help](https://github.com/TannerMidd/SpecPi/blob/main/vscode/README.md) · [Development](https://tannermidd.github.io/SpecPi/wiki/#development) · [Security](SECURITY_MODEL.md) · [Release notes](CHANGELOG.md)
+The website is static HTML and CSS in `site/`. After installing the pinned Playwright browser with `npx --no-install playwright install chromium`, run `npm run check:site` to check versions, links, and desktop, tablet, and mobile layouts. GitHub Pages deploys it from `main` after those checks pass.
 
-[MIT License](LICENSE)
+[Security model](SECURITY_MODEL.md) · [Third-party components](THIRD_PARTY.md) · [Release notes](CHANGELOG.md) · [MIT License](LICENSE)

package/SECURITY.md

@@ -6,6 +6,6 @@ Report vulnerabilities privately through [GitHub Security Advisories](https://gi
 
 Responses and fixes are best-effort, without a guaranteed timeline or bug bounty. Coordinate disclosure with the maintainer. Updates appear in [advisories](https://github.com/TannerMidd/SpecPi/security/advisories) and [release notes](CHANGELOG.md).
 
-Reports covering SpecPi's installer, extensions, Chat, website, automation, or dependency integration are welcome. Upstream-only problems may be redirected to the responsible project.
+Reports covering SpecPi's installer, scope monitor, improvement loop, or dependency integration are welcome. Upstream-only problems may be redirected to the responsible project.
 
 See [SECURITY_MODEL.md](SECURITY_MODEL.md) for trust boundaries and [THIRD_PARTY.md](THIRD_PARTY.md) for dependencies and licenses. SpecPi is not an OS sandbox; use least privilege and containers or VMs for hostile code.