specpi 0.20.1 → 0.21.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.21.1 - 2026-09-14
+
+- Restore the website's original typography, colors, Chat preview, theme switcher, and improvement diagram while keeping the new package base.
+- Bring back the README's logo, product preview, badges, and navigation, and make detailed command instructions collapsible.
+- Give npm's registry processing up to five minutes to finish before the publication readback check fails. Version 0.21.0 published correctly but became available after the previous one-minute check expired.
+
+## 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,27 +4,30 @@ 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
 
 `.github/workflows/npm-publish.yml` builds one immutable, checksummed candidate; validates that same tarball on Ubuntu, Windows and macOS; then publishes through approved GitHub OIDC with provenance. Stable releases use `latest`, prereleases `next`. Runs are serialized, existing versions are rejected and the candidate must advance its dist-tag. Registry readback must match version, integrity, dist-tag and attestation.
 
+Registry processing can take several minutes after npm accepts a publication. The workflow polls for up to five minutes. If that readback times out, inspect the registry and verify the published artifact before taking further action; do not rerun publication for a version that already exists.
+
 After publication, install the registry artifact into disposable state and exercise plan/install/doctor/uninstall. Check package-page links/images, license, provenance and dist-tag before announcing.
 
 ## First publication only

package/README.md

@@ -1,46 +1,42 @@
 <p align="center">
-  <img src="site/logo.svg" width="104" alt="SpecPi logo">
+  <img src="https://tannermidd.github.io/SpecPi/logo.svg" width="88" alt="SpecPi logo">
 </p>
 
 <h1 align="center">SpecPi</h1>
 
+<p align="center">Pi, beside your code.<br>Scope your work. Choose what improves. Keep your own Pi setup.</p>
+
 <p align="center">
-  A small toolkit for the <a href="https://pi.dev/">Pi coding agent</a>.
+  <a href="https://www.npmjs.com/package/specpi"><img src="https://img.shields.io/npm/v/specpi?style=flat-square&amp;color=084bdb" alt="npm version"></a>
+  <a href="https://github.com/TannerMidd/SpecPi/actions/workflows/ci.yml"><img src="https://github.com/TannerMidd/SpecPi/actions/workflows/ci.yml/badge.svg?branch=main" alt="Build status"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-084bdb?style=flat-square" alt="MIT license"></a>
 </p>
 
 <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>
+  <a href="#install">Install</a> · <a href="https://tannermidd.github.io/SpecPi/">Website</a> · <a href="https://tannermidd.github.io/SpecPi/wiki/">Documentation</a> · <a href="#vs-code">VS Code</a> · <a href="https://github.com/TannerMidd/SpecPi/releases">Releases</a>
 </p>
 
-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.
-
-<details>
-<summary>Watch the showcase · 51 seconds</summary>
-
-<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">
+<p align="center">
+  <a href="https://tannermidd.github.io/SpecPi/#vscode-chat">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://tannermidd.github.io/SpecPi/media/specpi-chat.png">
+      <img src="https://tannermidd.github.io/SpecPi/media/specpi-chat-light.png" width="1100" alt="SpecPi Chat beside a file in VS Code, discussing a focused code change with a file attached.">
+    </picture>
   </a>
 </p>
+<p align="center"><sub>SpecPi Chat · Example workspace</sub></p>
 
-</details>
-
-## What it adds
+SpecPi is a small base for the [Pi coding agent](https://pi.dev/). Its own extensions provide **scope control** and a **harness improvement loop**. Eight upstream packages handle the supporting tools, and **SpecPi Chat 0.7.1** brings them into VS Code.
 
-- **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.
+| Keep the work focused | Improve what gets in the way | Work beside your code |
+| --- | --- | --- |
+| Declare files and directories with `/scope`. Review drift as the task progresses. | Record recurring problems locally. Choose a change through `/harness-improvement` and verify it. | Chat, attach files, follow subagents, review approvals, and inspect changes in VS Code. |
 
-Problem collection is off by default. Its records stay on your machine. Pi connects to your chosen model provider.
+> **Moving from 0.20 or earlier?** The 0.21 base removes the old custom tools, extra commands, themes, and shell profiles. Read [updating and removal](#update-and-remove) before switching.
 
 ## Install
 
-Requires **Node.js 22.19+**, **npm**, and **Git**. SpecPi needs **Pi 0.84.4+**; the installer can add it if missing.
+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
@@ -49,26 +45,106 @@ specpi install
 specpi doctor
 ```
 
-Preview the changes, confirm the install, then check the setup. Restart Pi when finished.
+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.
+
+<details>
+<summary>Source checkouts, alternate Pi paths, and core-only installs</summary>
+
+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
+
+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.
+
+| 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 |
+
+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.
+
+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.
 
-To pin this release, use `npm install --global specpi@0.20.1`.
+Download the [0.7.1 VSIX](https://github.com/TannerMidd/SpecPi/releases/download/v0.21.1/specpi-chat-0.7.1.vsix), then run **Extensions: Install from VSIX…** in VS Code. Install/update SpecPi separately, then restart Pi in Chat to reload its extensions.
 
-Delegation is enabled at startup. Use `/delegate off` to turn it off.
+[Download Chat](https://github.com/TannerMidd/SpecPi/releases/download/v0.21.1/specpi-chat-0.7.1.vsix) · [Chat guide](https://github.com/TannerMidd/SpecPi/blob/main/vscode/GUIDE.md) · [Build from source](https://github.com/TannerMidd/SpecPi/blob/main/vscode/DEVELOPMENT.md)
 
-[Setup, updates & removal](https://tannermidd.github.io/SpecPi/wiki/#getting-started) · [Delegation settings](docs/delegation/README.md)
+## Scope
 
-## SpecPi Chat for VS Code
+Declare the files and directories a task should touch with `/scope set`, then use `/scope status` to review drift.
 
-Chat beside your code, attach files, and switch conversations.
+<details>
+<summary>Scope commands</summary>
+
+- `/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.
+
+</details>
+
+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
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://tannermidd.github.io/SpecPi/media/improvement-workflow-dark.svg">
+  <img src="https://tannermidd.github.io/SpecPi/media/improvement-workflow.svg" width="1200" alt="Observe a recurring gap, select one change, modify the harness, test it, retire with evidence, and review later outcomes.">
+</picture>
+
+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
 
-[**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.
+```sh
+npm install --global specpi@latest
+specpi plan
+specpi update
+specpi doctor
+specpi uninstall
+```
 
-In VS Code, find **SpecPi Chat** by **tannermidd** in Extensions and install it. Open **SpecPi** in the Activity Bar, then **Connect Pi**.
+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.
 
-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.
+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.
+
+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.
+
+## Development
+
+```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.