specpi 0.10.0 → 0.11.2

package/NPM_RELEASE.md

@@ -1,110 +1,110 @@
-# npm Release Runbook
-
-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.
-
-## One-time npm setup
-
-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.
-
-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`, and `site/wiki/index.html` to the same version.
-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
-   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
-   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:
-
-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.
-
-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.
-
-## Automated publication
-
-Publishing the GitHub Release starts `.github/workflows/npm-publish.yml`.
-
-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.
-
-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.
-
-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
-```
-
-Remove managed resources before removing the CLI:
-
-```bash
-specpi uninstall
-npm uninstall --global specpi
-```
-
-Private wishlist, journal, experiment, and patch state survives managed uninstall unless explicitly removed.
-
-## Failure policy
-
-Before publication, stop and fix any failed gate without changing npm.
-
-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.
-
-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.
+# npm Release Runbook
+
+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.
+
+## One-time npm setup
+
+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.
+
+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`, and `site/wiki/index.html` to the same version.
+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
+   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
+   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:
+
+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.
+
+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.
+
+## Automated publication
+
+Publishing the GitHub Release starts `.github/workflows/npm-publish.yml`.
+
+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.
+
+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.
+
+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
+```
+
+Remove managed resources before removing the CLI:
+
+```bash
+specpi uninstall
+npm uninstall --global specpi
+```
+
+Private wishlist, journal, experiment, and patch state survives managed uninstall unless explicitly removed.
+
+## Failure policy
+
+Before publication, stop and fix any failed gate without changing npm.
+
+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.
+
+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.

package/README.md

@@ -1,155 +1,223 @@
-<p align="center">
-  <img src="site/logo.svg" width="104" alt="SpecPi logo">
-</p>
-
-<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>.
-</p>
-
-<p align="center">
-  <a href="https://tannermidd.github.io/SpecPi/"><strong>Overview</strong></a>
-  · <a href="https://tannermidd.github.io/SpecPi/wiki/">Wiki</a>
-  · <a href="#install">Install</a>
-  · <a href="SECURITY.md">Security</a>
-</p>
-
-## Purpose
-
-SpecPi records recurring capability gaps in local state and presents qualified items for review. Selecting an item with `/harness-improvement` authorizes one bounded change. Repository checks and capability-specific validators must pass before the item can retire.
-
-Collection is disabled until explicitly enabled. Reports are sanitized, bounded, deduplicated by task, and never uploaded.
-
-<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>
-
-## Improvement loop
-
-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 registry integration, runs `npm run check`, and runs the item's closed validator.
-6. **Retire:** A passing item leaves the queue. Its evidence, gates, changed files, and version remain in the local journal.
-7. **Review again:** Later evidence returns the item as `review-needed`. Implementation does not restart automatically.
-
-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.
-
-## Included capabilities
-
-| Capability | Interface | Behavior |
-| --- | --- | --- |
-| Spec execution | `/spec` | Replaces normal chrome with a technical run panel, seals live reasoning, holds streaming prose until complete, and keeps tools collapsed. |
-| File review | `/files` | Browses source, rendered Markdown, Git diffs, and bounded review comments. |
-| Scope monitoring | `/scope` | Declares expected paths and reports unacknowledged drift. |
-| Worktree experiments | `/experiment` | Creates detached worktrees with keep, binary patch export, and confirmed discard outcomes. |
-| Completion review | `/challenge` | Produces a structured readiness review with evidence, gaps, contradictions, and residual risk. |
-| Capability wishlist | `/wishlist` | Stores and curates privacy-minimized local gap reports. |
-| Improvement selection | `/harness-improvement` | Authorizes one qualified or review-needed item. |
-| Command guard | `/guard` | Denies confirmed host-wide destructive calls and requests approval for bounded risk classes. |
-| Browser QA | Browser tools | Opens an isolated Chromium context for rendered inspection and screenshots. |
-| Specification theme | `specpi-spec` | Applies the GitHub Pages design’s blueprint blue, technical greys, layered surfaces, and restrained semantic states across Pi. |
-| Installer lifecycle | `specpi` | Plans, installs, updates, verifies, and uninstalls managed state with backups and rollback. |
-
-`specpi-spec` is the default Pi theme. It carries the site’s clean specification direction through message surfaces, tools, Markdown, diffs, syntax highlighting, search, and the full thinking-level scale. 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.
-
-## Install
-
-Requirements:
-
-- Node.js 22.19 or newer
-- npm
-- Git
-- Pi 0.84.4 or newer. If Pi is absent, the confirmed install adds the reviewed pinned package.
-
-Install the CLI, inspect its non-mutating plan, and then confirm the managed installation:
-
-```bash
-npm install --global specpi@latest
-specpi plan
-specpi install
-specpi doctor
-```
-
-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.10.0
-npx --package specpi@0.10.0 specpi plan
-```
-
-For a source-audited installation, clone the exact release instead:
-
-```bash
-git clone --branch v0.10.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.
-
-`plan` does not mutate the system. Install, update, and uninstall require confirmation unless `--yes` is supplied. After installation, run `/reload` in Pi.
-
-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
-```
-
-Direct `pi install npm:specpi` loads the package's 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.
-
-## Command guard
-
-Every supported model-initiated Pi tool call is classified before execution. Select one mode at session start:
-
-- **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.
-
-## Work ownership
-
-SpecPi does not install subagent orchestration. Keep one writer per working directory. A parent agent determines what context a child receives and summarizes what returns, so either handoff can omit a material constraint. Parallel writers also introduce conflicting assumptions and increase review work.
-
-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.
-
-`/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.
-
-## Data and security boundaries
-
-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. Wishlist reports, improvement journals, experiment metadata, and exported patches remain in private local SpecPi state and can survive uninstall. Review local artifacts before sharing.
-
-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.
-
-## Development
-
-```bash
-npm install --ignore-scripts --omit=peer --no-package-lock
-npm run format
-npm run check
-```
-
-JavaScript and TypeScript use four-space indentation, explicit braced control flow, and one statement per line. The repository check enforces formatting, validates syntax, 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.
-
-MIT licensed.
+<p align="center">
+  <img src="site/logo.svg" width="104" alt="SpecPi logo">
+</p>
+
+<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>.
+</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="https://tannermidd.github.io/SpecPi/">Website</a>
+  · <a href="https://tannermidd.github.io/SpecPi/wiki/">Wiki</a>
+  · <a href="SECURITY.md">Security</a>
+</p>
+
+## Purpose
+
+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.
+
+This README documents `0.11.2`, including task cards, verification receipts, and human outcome assessments. See the [release notes](CHANGELOG.md#0112---2026-09-04) for the complete change list.
+
+## 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.
+
+Install the CLI, inspect its non-mutating plan, and confirm the managed installation:
+
+```bash
+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. After installation, run `/reload` in Pi.
+
+<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.11.2
+npx --package specpi@0.11.2 specpi plan
+```
+
+For a source-audited installation, clone the exact release:
+
+```bash
+git clone --branch v0.11.2 --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 | Open an isolated Chromium context for rendered inspection and 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 does not install subagent orchestration. Keep one writer per working directory. A parent agent determines what context a child receives and summarizes what returns, so either handoff can omit a material constraint. Parallel writers also introduce conflicting assumptions and increase review work.
+
+## Improvement loop
+
+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.
+
+<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
+
+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.
+
+**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.
+
+## Development
+
+```bash
+npm install --ignore-scripts --omit=peer --no-package-lock
+npm run format
+npm run check
+```
+
+JavaScript and TypeScript use four-space indentation, explicit braced control flow, and one statement per line. The repository check enforces formatting, validates syntax, 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.
+
+MIT licensed.