specpi 0.16.0 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.17.1 - 2026-09-07
+
+- Reduce the npm package by shipping only runtime scripts; remove obsolete plans, research documents and unused assets, and shorten operational guides.
+- Use structured wishlist candidates directly instead of parsing generated Markdown. Human selection and proof-gated retirement remain unchanged.
+- Remove obsolete tests, editorial assertions and duplicate CI execution while retaining supported safety coverage. SpecPi Chat 0.3.7 separately removes unused standalone conversation paths.
+
+## 0.17.0 - 2026-09-06
+
+- Let delegation workers correct ordinary source-tool arguments and malformed/truncated reports in the same child session, preserving previously read passages and spending the original budgets. Keep source changes, revocations, unavailable tools, and exhausted budgets terminal. Remove the delegation-specific 8,192-token cap in favor of Pi's provider/model settings; scale SDK response acceptance with `/delegate budget` (1 MiB by default).
+- Replace generic delegation worker failures with safe diagnostics for source tools, provider requests, stream/context/response limits, output-token truncation, and final JSON/schema/evidence validation. Preserve the original tool failure through SDK cancellation, disclose report constraints in the worker prompt, and cover low-usage failures with controller and native Pi regressions.
+- Raise default delegation budgets to 96 source calls/512 KiB and 32 model turns per job, with 32 batches/256 model turns per Pi process. Add human-only, persisted `/delegate budget <multiplier>` (1–64, default 8), scaling counts and context together while preserving spent usage, deadlines, and concurrency. Keep handoff and response sizes independently bounded.
+- Count only delivered source JSON, report the specific exhausted allowance, and reject spent-budget follow-ups before starting a child. Tell workers their remaining allowance and verify substantial reading plus passage-preserving follow-up with offline regressions.
+- Preserve safe delegation snapshot rejection reasons and identify the selected-source position so failed reviews are diagnosable in SpecPi Chat and terminal Pi. Redact raw filesystem errors and verify that rejected snapshots start no worker or inference.
+- Replace delegation's private-topic keyword filter with known private namespaces and credential-store formats. Allow ordinary authentication, credential, session, and history source files/directories in all supported text formats, including `src/lib/security/credential-url.ts` and `credentials.ts`. Protect configured Pi storage and its canonical aliases; retain selected-file scope, containment, link, text, size, and freshness checks.
+
 ## 0.16.0 - 2026-09-05
 
 - Enable experimental read-only delegation by default at the first session start of each Pi process, including TUI, RPC, print and JSON modes. Startup preflights the host without launching workers or model inference; selective review/scout admission, Guard checks, source restrictions and resource ceilings remain unchanged.

package/NPM_RELEASE.md

@@ -1,114 +1,46 @@
-# npm Release Runbook
+# npm release
 
-This runbook is for SpecPi maintainers. Publishing, changing dist-tags, deprecating versions, and changing package ownership are remote operations and require an explicit human decision.
+Publishing, tags, deprecation, ownership changes and GitHub Releases require explicit human approval. Publication is a post-merge operation: never publish from an unmerged commit. npm versions are immutable.
 
-## One-time npm setup
+## Prepare
 
-1. Sign in to the intended npm owner account and enable two-factor authentication and recovery access.
-2. Confirm that the unscoped `specpi` name is available immediately before the first release.
-3. Create a protected GitHub environment named `npm` with required reviewer approval.
-4. Configure npm trusted publishing for `TannerMidd/SpecPi` and `.github/workflows/npm-publish.yml`.
-5. Do not configure a long-lived `NPM_TOKEN` when trusted publishing is available.
+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:
 
-If npm requires an initial interactive publication before a trusted publisher can be attached, validate the release artifact through every gate below. A local interactive npm session cannot issue GitHub's OIDC provenance, while this package requests provenance by default. For this one bootstrap exception only, publish the exact reviewed tarball with 2FA and an explicit override:
-
-```bash
-npm publish --ignore-scripts --access public --provenance=false ./specpi-<version>.tgz
-```
-
-Verify the registry bytes and metadata immediately, then configure trusted publishing before any later release. Do not publish a GitHub Release for that same bootstrap version: the release workflow deliberately rejects versions that already exist. Keep the reviewed source tag as its immutable source reference. All later versions use the protected OIDC workflow and provenance.
-
-## Prepare a release
-
-1. Select a version that has never appeared on npm. npm versions are immutable.
-2. Update `package.json`, `CHANGELOG.md`, `README.md`, `site/index.html`, `site/wiki/index.html`, `site/single-agent/index.html`, and the delegation guide to the same version. Keep historical changelog entries intact and remove stale unreleased-status wording.
-   If Chat changes are included, increment its independent version in `vscode/package.json` and `vscode/CHANGELOG.md`, and align the VSIX filenames and feature descriptions in the root README, extension README, and Pages guides. Build it with `npm --prefix vscode run package`, run `npm --prefix vscode run test:render` and the isolated `npm --prefix vscode run test:vsix`, and inspect the VSIX allowlist. The editor extension is not part of the npm tarball; creating this local artifact does not publish it or authorize a Marketplace release.
-
-3. For a stable release, add a dated changelog heading. Use a prerelease version when the package should not receive the `latest` dist-tag.
-4. Install the pinned development tools without lifecycle scripts or peers:
-
-   ```bash
+   ```sh
    npm install --ignore-scripts --omit=peer --no-package-lock
-   ```
-
-5. Run the complete repository and package gates:
-
-   ```bash
    npm run check
    npm run check:pi-package
    npm publish --dry-run --ignore-scripts --provenance=false
+   npm pack --dry-run --json
    git diff --check
    ```
 
-   Dry runs explicitly disable provenance because local and validation contexts do not have GitHub OIDC; the protected publish job still requires provenance.
-
-6. Inspect the final diff and the JSON file manifest emitted by `npm pack --dry-run --json`.
-7. Obtain fresh read-only review of package metadata, installer behavior, workflow permissions, and the packed artifact.
-8. Commit the reviewed release, create the matching `v<version>` tag, and create a GitHub Release only after explicit approval.
-
-## Documentation and publication order
-
-Publication is a post-merge operation. npm versions are immutable, and the protected workflow must run from a reviewed release tag on `main`, so never publish from an unmerged commit: that would leave permanent public bytes whose source might never land.
-
-`README.md`, `site/index.html`, and `site/wiki/index.html` document both the canonical `npm install --global specpi@latest` route and a version-pinned example, while `.github/workflows/pages.yml` deploys the site on any push to `main` that touches `site/**`. The release merge therefore deploys install instructions for a version that is not yet on the registry, and the site advertises a command that resolves to `E404` until publication completes.
-
-Keep that window short and bounded:
+   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.
 
-1. Merge the reviewed release to `main`.
-2. Create the `v<version>` tag and GitHub Release immediately, and approve the `npm` environment without delay. For the one bootstrap version described above, publish the reviewed tarball interactively instead and create no GitHub Release.
-3. Wait for the publish job to verify registry version, integrity, dist-tag, and attestation state.
-4. Complete the registry smoke check below, then confirm the deployed site and announce the release.
+## Protected publication
 
-If publication cannot complete, revert the release merge on `main` so the site stops advertising an unavailable version, and restart from a new version rather than reusing the failed one.
+`.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.
 
-## Automated publication
+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.
 
-Publishing the GitHub Release starts `.github/workflows/npm-publish.yml`.
+## First publication only
 
-All three jobs pin npm 11.19.1, above npm's 11.5.1 trusted-publishing minimum, on Node.js 22.19.0 and GitHub-hosted runners.
+Enable npm 2FA/recovery, create a reviewer-protected GitHub `npm` environment and configure trusted publishing for `TannerMidd/SpecPi`, `.github/workflows/npm-publish.yml`. Do not add a long-lived npm token when OIDC is available.
 
-The build job checks tag, package version, changelog entry, and registry immutability, then creates and checksums one tarball before installing repository development tools. It stores that immutable candidate for seven days.
+If npm requires an initial interactive publication before attaching the trusted publisher, run every gate above, then publish the exact reviewed tarball with 2FA:
 
-The validation job runs as an Ubuntu, Windows, and macOS matrix. Every runner downloads and verifies the same candidate, exercises that exact tarball through the npm and native Pi package lifecycles, and runs an npm publish dry-run; Ubuntu also runs the full repository checks.
-
-The publish job requires approval in the `npm` environment. Publication runs are serialized, and every candidate must advance its existing dist-tag. The job downloads and verifies the same immutable candidate, publishes through GitHub OIDC with npm provenance, uses `next` for prereleases and `latest` for stable versions, and reads the registry back until version, integrity, dist-tag, and attestation state match.
-
-## Registry smoke check
-
-After publication, install from the registry into disposable state rather than reusing the local tarball:
-
-```bash
-npm install --global specpi@<version>
-specpi plan
-```
-
-Then complete one isolated install, doctor, and uninstall lifecycle before announcing the release. Verify the npm package page, README images, license, repository links, provenance, and dist-tag.
-
-## Update and uninstall contract
-
-Updating the npm CLI and managed SpecPi state are separate operations:
-
-```bash
-npm install --global specpi@latest
-specpi update
-specpi doctor
-```
-
-Restart Pi after updating managed resources so it loads the new delegation runtime.
-
-Remove managed resources before removing the CLI:
-
-```bash
-specpi uninstall
-npm uninstall --global specpi
+```sh
+npm publish --ignore-scripts --access public --provenance=false ./specpi-<version>.tgz
 ```
 
-Private wishlist, journal, experiment, and patch state survives managed uninstall unless explicitly removed.
-
-## Failure policy
+This one bootstrap exception lacks GitHub provenance. Verify registry bytes/metadata immediately and configure trusted publishing before subsequent releases. Do not publish a GitHub Release for that same bootstrap version: the workflow rejects existing versions. Keep its reviewed source tag.
 
-Before publication, stop and fix any failed gate without changing npm.
+## Recovery
 
-After publication, never attempt to replace a version with different bytes. Verify the defect from the registry artifact, deprecate the affected version when warranted, publish a corrected patch after all gates pass, and change a dist-tag only through an explicit reviewed operation. Use unpublish only when npm policy, legal requirements, or credential exposure makes it necessary.
+Stop before publication if any gate fails. After publication, never replace a version's bytes: verify the registry defect, deprecate when warranted, and ship a checked patch through an explicitly approved operation. Unpublish only when npm policy, legal requirements or credential exposure warrants it.
 
-If a publishing credential is exposed, revoke it, stop active workflows, inspect npm ownership and dist-tag history, follow the private security-reporting process, and rotate related credentials before resuming.
+For exposed credentials, revoke them, stop workflows, inspect ownership/dist-tag history, use the [private reporting channel](SECURITY.md), and rotate related credentials before resuming.

package/README.md

@@ -5,237 +5,67 @@
 <h1 align="center">SpecPi</h1>
 
 <p align="center">
-  A local, human-directed improvement harness for the
-  <a href="https://pi.dev/">Pi coding agent</a>.
+  A small toolkit for the <a href="https://pi.dev/">Pi coding agent</a>.
 </p>
 
 <p align="center">
-  <a href="#install"><strong>Install</strong></a>
-  · <a href="#included-capabilities">Capabilities</a>
-  · <a href="#improvement-loop">Improvement loop</a>
+  <a href="#install">Install</a>
   · <a href="https://tannermidd.github.io/SpecPi/">Website</a>
-  · <a href="https://tannermidd.github.io/SpecPi/wiki/">Wiki</a>
-  · <a href="SECURITY.md">Security</a>
+  · <a href="https://tannermidd.github.io/SpecPi/wiki/">Documentation</a>
 </p>
 
-## Purpose
+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.
 
-SpecPi adds task contracts, workflow controls, and a local improvement loop to Pi. It records recurring capability gaps and presents qualified items for human review. Selecting one exact item with `/harness-improvement` authorizes a bounded change; repository checks and capability-specific validators must pass before it can retire.
-
-Collection is disabled until explicitly enabled. Reports are sanitized, bounded, deduplicated by task, and never uploaded. Later evidence can reopen an item for review, but never restarts implementation automatically.
-
-Version `0.16.0` enables bounded read-only delegation by default at Pi startup. One agent still owns edits and verification; worker use remains selective. SpecPi Chat, browser checks, and the human-selected improvement workflow remain available. See the [release notes](CHANGELOG.md) for the change list.
-
-## SpecPi Chat for VS Code
-
-The `vscode/` source contains **SpecPi Chat 0.3.2**, a separately packaged native sidebar with streamed replies, tool results, file and image attachments, model/thinking controls, Pi approvals, and searchable workspace conversation history. Rename or archive chats, switch between independent live conversations, branch or edit an earlier prompt, search and export visible messages, inspect usage, and review changes through VS Code's native diff tools. Switching chats preserves background work, approvals, drafts, and attachments. Connected conversations share workspace files; use separate worktrees for isolated writers. Opening the sidebar does not start Pi.
+<details>
+<summary>Watch the showcase · 51 seconds</summary>
 
-From a repository checkout, build a local VSIX with `npm --prefix vscode run package`, then install `.specpi-test/vscode/specpi-chat-0.3.2.vsix` through **Extensions: Install from VSIX…**. See the [extension guide](https://github.com/TannerMidd/SpecPi/blob/main/vscode/README.md) for prerequisites, image/provider limits, commands, privacy, and testing. Pi owns provider authentication and tool execution. Stop and Disconnect affect the selected conversation only; branching does not undo code changes. The extension is separate from the SpecPi npm package and has not been published to a marketplace.
+<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>
 
-## Selective delegation
+</details>
 
-One agent owns edits and verifies results. Experimental delegation adds up to two read-only Pi workers: `review` checks a frozen artifact; `scout` answers a focused question using selected sources. Workers cannot write, run shell commands, browse the web, or delegate further.
+## What it adds
 
-Delegation is **on by default at Pi startup**, subject to compatibility, settings, and Guard checks. Startup does not launch workers or model inference. Use `/delegate status` to inspect work and limits, `/delegate off` to revoke it, and `/delegate on` to re-enable it. Off and safety revocations survive reloads and session switches; restarting Pi reapplies the on default. Research informed the design; SpecPi quality, speed, and cost gains remain unmeasured.
+- **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/)
+- **Review as you work.** Track changed files, inspect diffs, check pages in a browser, and review risky commands.
+- **Improvements you choose.** Record recurring problems, select one with `/harness-improvement`, and test the change before calling it done.
 
-See [setup and limits](docs/delegation/README.md) or [how the research shaped the architecture](https://tannermidd.github.io/SpecPi/single-agent/).
+Problem collection is off by default. Its records stay on your machine. Pi connects to your chosen model provider.
 
 ## Install
 
-Requires **Node.js 22.19+**, **npm**, **Git**, and **Pi 0.84.4+**. If Pi is absent, the confirmed install adds the reviewed pinned package.
+Requires **Node.js 22.19+**, **npm**, and **Git**. SpecPi needs **Pi 0.84.4+**; the installer can add it if missing.
 
-Install the CLI, inspect its non-mutating plan, and confirm the managed installation:
-
-```bash
+```sh
 npm install --global specpi@latest
 specpi plan
 specpi install
 specpi doctor
 ```
 
-`plan` does not mutate the system. Install, update, and uninstall require confirmation unless `--yes` is supplied. Restart Pi after installation or updating SpecPi to load the delegation runtime.
-
-<details>
-<summary><strong>Pin a release or install from audited source</strong></summary>
-
-Pin the reusable CLI when installing a reviewed release, or inspect its plan without retaining a global CLI installation:
-
-```bash
-npm install --global specpi@0.16.0
-npx --package specpi@0.16.0 specpi plan
-```
-
-For a source-audited installation, clone the exact release:
-
-```bash
-git clone --branch v0.16.0 --depth 1 https://github.com/TannerMidd/SpecPi.git
-cd SpecPi
-./specpi plan
-./specpi install
-./specpi doctor
-```
-
-On Windows source checkouts, use `.\specpi.cmd` in place of `./specpi`. The npm installation provides the `specpi` command on every supported platform.
-
-</details>
-
-<details>
-<summary><strong>Update or uninstall</strong></summary>
-
-Update the npm CLI and its managed installation as two explicit steps:
-
-```bash
-npm install --global specpi@latest
-specpi update
-specpi doctor
-```
-
-Uninstall managed SpecPi resources before removing the CLI. Private wishlist, journal, experiment, and patch state remains local unless explicitly removed:
-
-```bash
-specpi uninstall
-npm uninstall --global specpi
-```
-
-</details>
-
-Direct `pi install npm:specpi` loads extensions, skills, and themes only. It does not run the full installer or provide managed instructions, browser runtime dependencies, supporting Pi packages, optional tools, shell integration, backups, or ownership records.
-
-## Included capabilities
-
-### Define and review work
-
-| Interface     | Purpose                                                                                                                                         |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/task`       | Record the objective, fixed requirements, acceptance checks, expected paths, hypothesis, rollback, and non-goals on the current session branch. |
-| `/scope`      | Declare expected paths and report unacknowledged drift.                                                                                         |
-| `/files`      | Browse source, rendered Markdown, Git diffs, and bounded review comments.                                                                       |
-| `/experiment` | Create detached worktrees with keep, binary patch export, and confirmed discard outcomes.                                                       |
-| `/challenge`  | Review readiness through structured evidence, gaps, contradictions, and residual risk.                                                          |
-
-### Improve from evidence
-
-| Interface              | Purpose                                                                              |
-| ---------------------- | ------------------------------------------------------------------------------------ |
-| `/wishlist`            | Store and curate privacy-minimized local capability-gap reports.                     |
-| `/harness-improvement` | Select one qualified or review-needed item and authorize its bounded implementation. |
-
-### Work inside Pi
-
-| Interface           | Purpose                                                                                                                               |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `/spec`             | Replace normal chrome with a technical run panel, seal live reasoning, hold streaming prose until complete, and keep tools collapsed. |
-| `/guard`            | Deny confirmed host-wide destructive calls and request approval for bounded risk classes.                                             |
-| Browser tools       | Inspect isolated Chromium, diagnose errors, exercise keyboard/select/wait flows, and capture screenshots.                              |
-| `specpi-spec` theme | Bring blueprint blue, technical greys, layered surfaces, and restrained semantic states into Pi.                                      |
-| `specpi` CLI        | Plan, install, update, verify, and uninstall managed state with backups and rollback.                                                 |
-
-`specpi-spec` is the default Pi theme, carrying the site's specification design through message surfaces, tools, Markdown, diffs, syntax highlighting, search, and the full thinking-level scale. **Existing valid theme preferences survive installation and updates.** The original `tea-house` theme remains bundled and selectable from `/settings`.
-
-Capability registry entries include closed offline validators. Completion, `npm run check`, and `specpi doctor` run those validators.
-
-## How SpecPi fits
-
-SpecPi runs inside Pi through extensions, skills, settings, and themes. Pi supplies the agent runtime, tools, sessions, and model connections; SpecPi adds the working agreement, workflow controls, and local improvement loop.
-
-```mermaid
-flowchart TB
-    human["You · goals, selections, review"]
-    subgraph session["Pi session"]
-        specpi["SpecPi · contracts, guard, review, improvement"]
-        pi["Pi · agent loop, tools, sessions"]
-        specpi <-->|extension hooks| pi
-    end
-    human --> specpi
-    human --> pi
-    pi -->|model requests| provider["Selected model provider"]
-    pi -->|tools| project["Project files and commands"]
-    specpi -->|local records| evidence["Task cards, wishlist, verification receipts"]
-```
-
-## Work ownership
-
-### Task contracts and handoff
-
-Use `/task set` when a shared contract would improve continuity. Its card supplies fixed requirement IDs to `/challenge` and can seed an experiment's hypothesis and acceptance checks. `/spec` shows the active task. `/scope task` explicitly imports the card's expected paths; recording a card alone never widens scope. Human edits create a new card revision and invalidate a review of the earlier card.
-
-Use `/task clear` before recording an unrelated task. Within a session, repeated reports for the same capability share the card's task ID across agent runs and card revisions. Without a card, report grouping remains per run.
-
-`/task handoff` displays a review packet containing the original card, observed change information, the latest completion review, and unresolved facts. Inspect the packet before sharing it or opening a separate review session. It does not launch another agent or write an export.
-
-### Scope and completion
-
-`/scope set` declares expected paths. `/scope accept <path>` acknowledges one finding without widening the contract. `/scope add <path>` widens it. `/scope recheck` replaces an uncertain baseline.
-
-`/challenge` requires structured requirement evidence and checks for contradictions, false-positive validation, scope drift, missing runtime or visual checks, and residual risk. Its result supports human review and does not replace direct proof.
-
-### Isolated experiments
-
-Use `/experiment start` when an independent review or trial justifies a separate worktree. Open the reported path in another Pi session. SpecPi does not launch an agent, copy dirty base changes, commit, merge, or touch remotes.
-
-SpecPi's default workflow uses one writer per working directory. Its experimental delegation adds bounded read-only Pi sessions. SpecPi Chat also supports independent conversations that you start explicitly; connected chats can continue concurrently in the same workspace. They share workspace files rather than receiving separate worktrees. A parent determines what context a delegated child receives and verifies what returns, so either handoff can omit a material constraint. Parallel writers also introduce conflicting assumptions and increase review work.
+Preview the changes, confirm the install, then check the setup. Restart Pi when finished.
 
-## Improvement loop
+To pin this release, use `npm install --global specpi@0.17.1`.
 
-1. **Record:** A reusable capability gap is stored as a sanitized local report.
-2. **Qualify:** Recurrence, project reach, impact, and recency determine whether the item enters the review menu.
-3. **Select:** `/harness-improvement` authorizes one exact item.
-4. **Implement:** The `specpi-improve` skill makes the narrowest sufficient change and adds direct checks.
-5. **Verify:** The completion gate checks the selected task contract and registry integration, runs `npm run check` and the item's closed validators, and rejects evidence if the checked source changes.
-6. **Retire:** A passing item leaves the queue. Its model-reported evidence and executable verification receipt remain separately identified in the local journal.
-7. **Review again:** Later evidence returns the item as `review-needed`. Implementation does not restart automatically.
+Delegation is enabled at startup. Use `/delegate off` to turn it off.
 
-<details>
-<summary><strong>View the improvement loop</strong></summary>
-
-<p align="center">
-  <img src="site/self-improvement-loop-v2.svg" width="760" alt="SpecPi improvement loop: local friction becomes qualified evidence; a person chooses one change; verification failure keeps it selected; later evidence returns it to human review.">
-</p>
-
-</details>
-
-### Inspect the record
-
-Use `/wishlist status` for queue and loop-health totals. Use `/wishlist history [gap-id]` for retirement evidence, validators, changed files, reopen signals, and rollback context. `/wishlist` also supports duplicate cleanup, local issue drafts, archive, and reset operations.
-
-With collection enabled, `/wishlist outcome <gap-id>` records an explicit human assessment of the latest local retirement: helped, failed, not exercised, or reverted. Later assessments replace the earlier assessment in totals while history retains both. Failure is a reason to review; it never authorizes another implementation. Unused capabilities remain unassessed.
-
-## Command guard
+[Setup, updates & removal](https://tannermidd.github.io/SpecPi/wiki/#getting-started) · [Delegation settings](docs/delegation/README.md)
 
-Every supported model-initiated Pi tool call is classified before execution. Select one mode at session start:
-
-| Mode       | Behavior                                                                                                                |
-| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
-| **Guard**  | Denies confirmed host-wide catastrophe and guard tampering, asks before Git destroys work, and otherwise remains quiet. |
-| **Strict** | Adds approval requests for mutation, execution, sensitive reads, and network activity.                                  |
-| **Off**    | Requires confirmation and applies only to the current session.                                                          |
-
-Approvals apply to one exact call and one session. Only a structurally proven critical mutation locks the session. Parser uncertainty and invalid cleanup syntax are denied without locking later work.
-
-The guard covers the documented `bash`, `powershell`, `read`, `write`, and `edit` seams. Direct shell escapes, malicious extensions, unclassified custom tools, approved scripts, TOCTOU changes, and external processes remain outside its scope.
-
-## Data and security boundaries
-
-**Local state.** SpecPi does not persist command text or read Pi credentials, unrelated sessions, or history. Scope and challenge records are bounded entries in the current Pi session; task cards are bounded to the active session branch. Wishlist reports, improvement journals, experiment metadata, and exported patches remain in private local SpecPi state and can survive uninstall. Review local artifacts before sharing.
-
-**Verification receipts.** Improvement verification fingerprints supported source and validation inputs, records actual gate results, and detects changes between verification snapshots. Receipts retain hashes and runtime metadata, not source contents or raw command output. They describe what was checked; they are not cryptographic attestations or proof that a model's acceptance explanation is correct. Older journals remain readable and are identified as lacking a receipt.
-
-**Provider and network access.** Local SpecPi evidence does not make the whole agent offline. Pi sends model requests to the selected provider, browser pages and installed packages may contact the network, and Pi has separate telemetry and update-check settings. The installer explains these boundaries without changing those upstream preferences.
+## SpecPi Chat for VS Code
 
-**Host permissions.** Pi extensions run with the current user's permissions. Use OS permissions, a least-privilege account, a container, or a VM for hostile code or data. See [SECURITY_MODEL.md](SECURITY_MODEL.md) for the complete trust model and [SECURITY.md](SECURITY.md) for vulnerability reporting.
+Chat beside your code, attach files, and switch conversations.
 
-## Development
+[**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.
 
-```bash
-npm install --ignore-scripts --omit=peer --no-package-lock
-npm run format
-npm run check
-```
+In VS Code, find **SpecPi Chat** by **tannermidd** in Extensions and install it. Open **SpecPi** in the Activity Bar, then **Connect Pi**.
 
-JavaScript and TypeScript use four-space indentation, explicit braced control flow, and one statement per line. The repository check enforces formatting, validates syntax, strictly type-checks the browser extension, runs the Node test suite, executes registry-linked validators, and installs the exact npm tarball through an isolated lifecycle. Maintainers should follow [NPM_RELEASE.md](NPM_RELEASE.md) for release preparation and protected publication.
+Chat 0.3.7 includes **Restart Pi** in the Chat title bar and Command Palette to reconnect the selected conversation and reload its Pi extensions. Other conversations keep running.
 
-For application testing, use `browser_diagnostics` alongside rendered inspection, and `browser_press`, `browser_select_option`, and `browser_wait_for` for keyboard, native dropdown, and asynchronous flows. Diagnostics are bounded and best-effort sanitized, not guaranteed secret-free or proof of application health.
+## Go further
 
-Provision repository-local Chromium with `npm run setup:browser`, then run `npm run test:browser` and `npm run test:site:browser`. The required CI browser commands reject skipped coverage; Pages deployment waits for the same rendered check. See [browser testing](docs/browser-testing.md) for tool contracts, privacy limits, type-check scope, and the semantic-navigation assessment.
+[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)
 
-MIT licensed.
+[MIT License](LICENSE)

package/SECURITY.md

@@ -1,86 +1,11 @@
-# Security Policy
+# Security policy
 
-This policy explains which SpecPi releases receive security fixes, how to report a vulnerability, and the security responsibilities shared by SpecPi and its users. For architecture, trust boundaries, and component limitations, see [SECURITY_MODEL.md](SECURITY_MODEL.md). Exact third-party versions and licenses are listed in [THIRD_PARTY.md](THIRD_PARTY.md).
+Security fixes target the latest tagged SpecPi release. Older releases are unsupported unless an advisory says otherwise.
 
-## Supported versions
+Report vulnerabilities privately through [GitHub Security Advisories](https://github.com/TannerMidd/SpecPi/security/advisories/new). Include the affected version, platform, impact, and a minimal reproduction using synthetic data. Do not post exploit details publicly or include real credentials. If private reporting is unavailable, open an issue requesting restoration of the channel without disclosing the vulnerability.
 
-SpecPi provides security fixes for the latest tagged release only. Older releases are unsupported unless a published security advisory says otherwise. Before reporting, check whether the latest release already corrects the behavior; reports affecting the supported release remain welcome.
+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).
 
-| Release | Security support |
-| --- | --- |
-| Latest tagged release | Supported |
-| Older releases | Unsupported |
+Reports covering SpecPi's installer, extensions, Chat, website, automation, or dependency integration are welcome. Upstream-only problems may be redirected to the responsible project.
 
-## Report a vulnerability
-
-Report suspected vulnerabilities through [GitHub private vulnerability reporting](https://github.com/TannerMidd/SpecPi/security/advisories/new). SpecPi currently accepts private reports only through GitHub.
-
-Do not open a public issue, pull request, discussion, or other public report containing vulnerability or exploit details. A GitHub account is required. If private reporting is unexpectedly unavailable, open a public issue containing no vulnerability details and ask the maintainer to restore the private reporting channel before sharing the report.
-
-Include as much of the following as is safe and practical:
-
-- the affected SpecPi release or commit;
-- the affected installer command, extension, tool, workflow, or website component;
-- operating system and relevant configuration;
-- expected and observed behavior;
-- security impact and plausible attack scenario;
-- minimal reproduction steps or proof of concept;
-- known mitigations or workarounds;
-- whether the issue is already public or actively exploited;
-- preferred credit or anonymity.
-
-Do not include real credentials, personal data, production secrets, or destructive payloads when a minimized demonstration is sufficient.
-
-SpecPi handles reports on a best-effort basis. Maintainers will acknowledge, assess, and communicate as capacity permits, but the project does not promise fixed response or remediation times. Fix timing depends on impact, exploitability, complexity, upstream coordination, and release safety.
-
-Please keep the report private while impact, mitigations, a fix, and an advisory are coordinated. Disclosure timing will be discussed with the reporter and may be accelerated when details are already public or exploitation is active. SpecPi does not currently operate a bug bounty program.
-
-## Scope
-
-Reports are in scope when they concern SpecPi-owned behavior, including:
-
-- the plan, install, update, doctor, and uninstall lifecycle;
-- managed configuration, backups, checksums, rollback, and shell integration;
-- bundled extensions, skills, themes, browser integration, and local state;
-- Command Guard classification, enforcement, approval, or bypass behavior;
-- the GitHub Pages site and repository release or deployment workflows;
-- an upstream dependency when SpecPi's integration, configuration, or selected version creates or exposes the vulnerability.
-
-Pi, npm, Chromium, Playwright, DonSeTch, GitHub, and other third-party projects maintain their own security boundaries. Upstream-only vulnerabilities may be redirected to the responsible project. Reports remain relevant to SpecPi when its use of an upstream component creates a distinct risk or requires a SpecPi mitigation.
-
-A disagreement with an intentional, documented limitation is not by itself a vulnerability. Reports that show the implementation violating its stated boundary, silently weakening a protection, exposing protected data, or enabling a practical bypass are welcome.
-
-## Security updates
-
-When appropriate, SpecPi publishes security information through [GitHub Security Advisories](https://github.com/TannerMidd/SpecPi/security/advisories), tagged releases, and [CHANGELOG.md](CHANGELOG.md). An advisory should identify affected and fixed releases, impact, mitigations or workarounds, and upgrade guidance. A CVE may be requested when appropriate.
-
-## Secure installation and operation
-
-- Install a version-pinned npm release or clone and review the matching source tag. Verify npm provenance when relying on the registry artifact. Do not pipe remote installer content directly into a shell.
-- Installing the npm package adds the CLI only. Review `specpi plan` before installation or update, and use `--yes` only when every planned external installation is intended.
-- Treat `pi install npm:specpi` as limited resource-only mode, not as the managed installer with browser runtime, supporting packages, instructions, backups, and rollback ownership.
-- Run `specpi doctor` after installation and updates.
-- Run Pi and SpecPi with the least operating-system privilege practical. Use a container or VM for hostile repositories, code, or web content.
-- Protect Pi configuration and credentials with operating-system permissions. SpecPi is not a credential or process sandbox.
-- Use dedicated test accounts rather than personal authenticated browser sessions.
-- Inspect task cards, review packets, wishlist reports, issue drafts, screenshots, page text, downloads, console output, and visual baselines before sharing them.
-- Review optional and global package installations. Some external state and package caches survive rollback or uninstall.
-
-## Security boundaries at a glance
-
-| Area | SpecPi provides | SpecPi does not provide |
-| --- | --- | --- |
-| npm distribution | Reviewed file allow-list, no install lifecycle script, protected publishing, and requested provenance | Automatic execution of the managed SpecPi installer or proof that packaged code is safe |
-| Installer | Explicit plans and confirmation, bounded managed changes, backups, checksums, atomic promotion, and rollback | Rollback of every external package-manager side effect or cache |
-| Command Guard | Pre-execution defense in depth for documented model-tool seams | A general sandbox for direct user commands, arbitrary tools, scripts, extensions, or running processes |
-| Local improvement state | Explicit collection choice, bounded local records, sanitization, and no SpecPi upload | Guaranteed removal of every plain-language identity or automatic deletion on uninstall |
-| Task and verification records | Fixed task requirements, source-bound gate observations, and explicit human outcome feedback | Independent model judgment, cryptographic attestation, or automatic authority to expand a task |
-| Browser | A fresh Chromium context without the personal browser profile | Operating-system or network isolation from hostile web content |
-
-The authoritative assumptions, enforcement seams, residual risks, and component details are in [SECURITY_MODEL.md](SECURITY_MODEL.md).
-
-## Dependencies and supply chain
-
-SpecPi pins reviewed executable dependencies and uses a reviewed lockfile for its managed browser runtime. The npm release workflow validates one tarball, publishes those same bytes from a protected environment with GitHub OIDC, and requests npm provenance. Provenance links an artifact to its build workflow but does not prove the source or dependencies are safe. Pinning, lockfiles, and provenance improve accountability but are not complete reproducible-build guarantees. Installation still trusts the configured package registries, upstream publishers, downloaded browser distribution, GitHub Actions, and the invoking host.
-
-Some optional or bootstrap packages are installed globally and remain external system state. SpecPi uninstall does not remove them. See [THIRD_PARTY.md](THIRD_PARTY.md) for the canonical component and version inventory and [SECURITY_MODEL.md](SECURITY_MODEL.md) for acquisition and rollback boundaries.
+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.