specpi 0.10.0

package/CHANGELOG.md

@@ -0,0 +1,150 @@
+# Changelog
+
+## Unreleased
+
+## 0.10.0 - 2026-09-02
+
+- Add the public npm distribution contract for the `specpi` installer CLI, including global install, explicit managed install/update/uninstall steps, source-audited alternatives, and the limited resource-only boundary of direct `pi install npm:specpi` usage.
+- Validate the exact npm tarball in isolated state: enforce its public file allow-list and metadata, install it offline into a temporary global prefix without auto-installing Pi host peers, and run packed `plan`, `install`, `doctor`, `update`, and `uninstall` lifecycle checks while proving private evidence survives.
+- Declare every imported Pi core module as an optional host peer, ship the README logo, preserve an executable package bin, and add public/provenance publishing metadata without npm installation lifecycle scripts.
+- Add a release-only npm workflow that checks immutable tag/version/changelog alignment, rejects existing versions, preserves and checksums one validated tarball, separates protected publication from validation, publishes through GitHub OIDC with npm provenance, and verifies registry integrity, dist-tag, and attestation state.
+
+## 0.9.0 - 2026-09-01
+
+- Adopt the SpecPi identity across the package, executables, installer and private state, environment variables, managed markers, extensions and events, `/spec` mode, improvement skill, theme, tests, documentation, security policy, and GitHub Pages URLs.
+- Add the immersive `specpi-spec` Pi theme based on SpecPi’s clean GitHub Pages specification design, with layered technical surfaces and complete palettes for Markdown, tools, diffs, syntax, search, statuses, and thinking levels. Make it the default while retaining Tea House as an installed option.
+- Rebuild `/spec` as an immersive specification console: replace normal header and footer chrome, show indexed execution phases and scope state, seal reasoning traces, hold live response prose until completion, keep tool output collapsed, and suppress routine model narration while preserving the full transcript and restoring normal rendering when the mode exits.
+
+## 0.8.4 - 2026-09-01
+
+- Add opt-in workflow controls: `/scope` declares project-relative change boundaries and surfaces direct or observed drift without silently expanding scope; `/experiment` creates detached, private-state Git worktrees with complete patch export and explicitly confirmed discard; `/challenge` produces a structured adversarial readiness card whose deterministic gate rejects unresolved evidence.
+- Keep the new controls human-led and local: no child process or agent launch, automatic commit/merge/apply, remote operation, raw command log, unrelated session scan, or mandatory completion interception. Add branch-local scope/challenge state, a private recoverable experiment registry, direct closed validators, installer lifecycle coverage, and security-boundary documentation.
+- Separate `/scope accept` from `/scope add`: accepting acknowledges one observed finding and leaves the declared contract untouched, so a later change to the same path is reported again. Add `/scope recheck` to re-baseline the worktree and deliberately clear snapshot uncertainty, and report removals and no-op verbs explicitly.
+- Export experiment patches as the exact bytes Git produces. A text file that is not valid UTF-8 previously lost its original bytes on export and produced a patch that no longer applied.
+- Disclose ignored files in `/experiment status` and `/experiment close`. Ignored work is invisible to Git status and cannot travel in a patch, so a worktree holding only ignored work no longer looks empty at discard time.
+- Expire a completion challenge that the agent turn ends without answering, instead of leaving its "do not implement" instruction attached to every later turn.
+- Offer a working recovery action for an experiment directory Git no longer tracks: the record can be released while the files are left in place for the human.
+- Snapshot the worktree once per tool instead of twice, skip snapshots for read-only calls, and copy scope entries both when appending and when restoring them so a branch record cannot be rewritten by later mutation.
+- Record an expired challenge distinctly from a cleared one, so a challenge that goes unanswered no longer discards the last completed readiness card after a restart.
+- Report ignored paths from `/experiment status` with no ID, the form used from inside an experiment worktree.
+- Re-derive worktree presence inside the registry lock during `/experiment recover`, so a Git operation performed while a recovery prompt is open cannot drop a live record or adopt a replaced directory.
+- Measure experiment status and patch export from the recorded base commit instead of the worktree's current HEAD. Work committed inside an experiment previously reported as clean, exported to an empty patch, and could be discarded without the dirty-work confirmation.
+- Keep Git-reported paths canonical in workflow state and percent-escape controls only at presentation boundaries, so filenames containing `%`, newlines, Unicode separators, or directionality controls remain matchable without forging system guidance or UI text.
+- Resolve relative direct write and edit paths from the active session directory before comparing them with project-relative scope, so sessions opened below the Git root neither allow outside-scope mutations nor reject matching nested paths.
+- Claim a patch output exclusively instead of checking then renaming, so a destination created in the gap is never replaced without explicit overwrite approval.
+- Require a ready completion verdict to disclose residual risk when the change snapshot was indeterminate, instead of ignoring that signal.
+
+## 0.8.3 - 2026-09-01
+
+- Remove the `pi-subagents` package and SpecPi's native-subagent configuration, runtime integration, and installation defaults.
+- Make the workflow rationale explicit: automated parent/child handoffs can silently omit decisive context, while parallel writers fragment assumptions and ownership. Prefer deliberate context gathering, reviewable artifacts, explicit second-opinion sessions, and one writer per working directory or isolated worktree.
+- Split the public security policy from the technical security model. Document latest-release support, private vulnerability reporting, best-effort response expectations, reporting scope, secure operation, and supply-chain assumptions while keeping implementation boundaries in a shipped `SECURITY_MODEL.md`.
+
+## 0.8.2 - 2026-09-01
+
+- Keep command-guard denials fail-closed without making every uncertain or wrong-shell cleanup attempt strand the session: only structurally proven lock-worthy critical mutations latch `locked`, while parser fallback, shell-syntax mismatches, and refused reads remain non-latching denials.
+- Protect installed command-guard files as managed enforcement nodes rather than treating the whole command-guard directory as protected, allowing unrelated temporary descendants while preserving ancestor and canonical-path protection. Share the managed-file inventory with installer resources and checksums.
+- Classify cmd-style `rd`/`rmdir /s /q` sent directly to the Windows Bash tool as a corrective non-latching denial, and keep parser-fallback protected-path matching local to the destructive statement so unrelated scratch cleanup cannot inherit a critical result.
+
+## 0.8.1 - 2026-08-30
+
+- Ask for Guard approval before Git destroys work. Force pushes (`--force`, `-f`, `--force-with-lease`, `--force-if-includes`) and the wider destructive Git family — remote ref deletion, hard resets, cleans, branch and tag deletion, stash drops, discarding checkouts and restores, rebases, and history rewrites — now surface an approval in Guard instead of running silently, because they discard or rewrite work no local undo restores. Ordinary pushes, pulls, and fetches stay quiet in Guard; all of it still asks in Strict.
+
+## 0.8.0 - 2026-08-31
+
+- Parse Bash and cmd at the statement level instead of treating every word in command position as a program. Shell reserved words (`if`/`then`/`while`/`until`/`for`/`do`), the `!` negation prefix, and the `builtin`/`command`/`coproc`/`time` prefixes were taken as leaf executables, so in `if true; then rm -rf /; fi` the real command survived only as an argument list on a leaf named `then` and matched no rule at all. `trap 'rm -rf /' EXIT` now analyzes its handler string, and cmd `if` conditionals are unwrapped the way `for` already was.
+- Resolve the heredoc consumer instead of assuming `-c` makes the body inert. `bash -c 'sh' <<EOF … EOF` runs the body through the `sh` that `-c` launches, and `su root <<EOF` runs it as root, so both are code rather than data.
+- Thread the working directory through a command sequence. Relative targets always resolved against the session cwd regardless of what ran before them, so `cd / && rm -rf usr`, `Set-Location C:\ ; Remove-Item -Recurse -Force Windows`, `cd /d C:\ && rmdir /s /q Windows` and `env --chdir=/ rm -rf usr` were each reported as a determinate, clean delete inside the workspace. A directory change the analyzer cannot resolve now makes later targets uncertain instead of clean.
+- Protect the ancestors that contain enforcement state, not only the subtree itself. Deleting `<agent-dir>/extensions/command-guard` was denied while deleting `<agent-dir>/extensions` or the whole agent directory — a superset of the same tampering — was allowed. Destructive Git operations run inside protected or enforcement trees are classified with them.
+- Canonicalize the path spellings that reach the same target: Win32 trailing dots and spaces (`C:\Windows.`), `~` under PowerShell as well as Bash, the macOS firmlinked `/private/etc` and `/private/var` trees, and the Windows `EFI`/`Recovery` boot partitions.
+- Complete the decode-to-interpreter set (`base32`, `basenc`, `xxd`, `hexdump`, `od`) and the critical-process list (`svchost`, `services`, `smss`, `winlogon`, `launchd`), which previously closed only the base64 and `lsass`/`csrss` spellings of the same operation.
+- Stop an unavailable parser from downgrading a catastrophe into an approvable prompt. A helper timeout, a missing interpreter or a blown limit produced `ask`, so the case where the guard knows least was the case where it yielded most. The raw command text is now scanned for confirmed catastrophic operations before any approval is offered, including the payload of an inline-code flag such as `-Command` or `-c`, which is program text rather than data. The scan reads only what the shell would execute as syntax — quoted arguments stay inert and backslash is treated as an escape only where the shell treats it as one — so a command that merely prints a destructive-looking string is not mistaken for one.
+- Give the PowerShell parser helper the environment it needs to start. Spawned with only `SystemRoot`, `PATH` and `TEMP`, Windows PowerShell 5.1 hung indefinitely on a current Windows Server 2025 image — measured at five of five spawns killed at a 20-second bound with no output and no error — while the same spawn with `PSModulePath`, `APPDATA`, `LOCALAPPDATA` and `USERPROFILE` present completed in about 380 ms. PowerShell 7 was unaffected. Every 5.1 analysis in a session therefore waited out its full bound before falling back. The helper still runs on an allowlist that withholds tokens, keys and other credential-bearing variables.
+- Match endpoint-protection services as complete tokens rather than substrings. `security`, `firewall` and `sentinel` matched anywhere in the arguments, so ordinary units — `redis-sentinel`, `security-scanner.service`, an in-house `firewall-ui` — were critical denials that locked the session.
+- Identify credential paths by shape rather than by bare words that ordinary source trees use as directories. `credentials`, `token`, `secret` and `passwd` matched as standalone path segments, so every file under a monorepo's `packages/token/`, `src/secret/` or `app/credentials/` was a critical read denial.
+- Resolve the agent directory with the analyzed platform's path semantics rather than the host's, so cross-platform classification is deterministic instead of depending on how the host resolves a foreign path spelling.
+- Reformat all tracked JavaScript and TypeScript for readability with four-space indentation, explicit braced control flow, one statement per line, and consistent spacing around blocks and returns. Add pinned project-local Prettier and ESLint checks so future changes preserve the style.
+- Guide agents to prefer simple, explicit commands while Command Guard is active, reducing avoidable parser-uncertainty approvals without weakening or bypassing protection.
+- Add a first-party, session-scoped command guard with Guard, Strict, Off, and Locked states. Guard is a narrow catastrophe backstop: confirmed host-wide destruction and enforcement tampering are immutable denials, analysis uncertainty asks with UI and denies headlessly, and determinate non-catastrophic work runs without routine prompts. Strict retains broad approval behavior.
+- Add bounded shell-specific analyzers, native PowerShell AST parsing without evaluation, protected-path canonicalization, display redaction, deterministic policy smoke validation, and Linux/Windows regression coverage across PowerShell 5.1, PowerShell 7, cmd, and inert adversarial corpora.
+- Propagate protected modes to supported native subagents through the pinned public preflight contract, a managed child extension, and a reserved binding; preserve unrelated child extensions, block unverifiable launch forms, and exercise a real inert native-child process in CI.
+- Parse PowerShell with whichever installed host accepts the command text: PowerShell 7 grammar (`&&`, `??`, `?:`) is no longer denied as malformed when only Windows PowerShell 5.1 parses it, and either host alone is now sufficient. A rejection is authoritative only when every installed host rejects it, and a spawn failure can never escalate a syntax error into a critical denial.
+- Classify argv-prefix runners (`setsid`, `stdbuf`, `ionice`, `taskset`, `flock`, `systemd-run`, `unbuffer`, `runuser`, `setarch`, `xvfb-run`, `proxychains`), command-string runners (`su`, `runuser`, `script`, `watch`), awk shell escapes, and `osascript`/`tclsh`/`expect` inline code, so a critical payload cannot be laundered through an unlisted wrapper.
+- Treat a whitespace-bearing command token as unresolved rather than reducing it to its trailing path segment, and propagate an unresolved nested child up to the whole analysis so wrapped command strings cannot be reported as a clean parse.
+- Match every PowerShell parameter prefix, not only full spellings: `-enc` runs the same code as `-EncodedCommand`, so an abbreviated flag used to carry a base64 payload past the guard with no approval when the invocation arrived through the Bash or cmd parser. Bash- and cmd-hosted `powershell`/`pwsh` invocations now decode and classify their `-Command`/`-EncodedCommand` payload instead of seeing one opaque argument, including recursive `cmd /c powershell.exe` dispatch, and an absent PowerShell parser downgrades to an approval rather than locking the session over an interpreter the command could not have used.
+- Remove routine Guard approvals for determinate non-catastrophic work, including project or user-data deletion, force push, publication, installation, network transfer, process termination, service and registry changes, and out-of-workspace targets. Keep those broader prompts in Strict. Narrow Guard's protected mutation boundary to host-root/key system targets and, inside the installed agent, command-guard enforcement sources, `settings.json`, and `specpi/manifest.json`.
+- Identify Pi and SpecPi private state by location rather than by name. `specpi/manifest.json`, `specpi/backups`, `specpi/wishlist` and `extensions/command-guard` were matched as bare relative segments, so reviewing SpecPi's own repository denied a file read critically and locked the session, and `guard.self-tamper` fired on any mutation whose arguments merely contained "specpi" or "command-guard" — `mkdir specpi-experiment` was a critical denial. On POSIX the rule was an unanchored `/(?:specpi|pi).*(?:auth|session|…)/`, so everyday files such as `src/api/session.ts` and `lib/api/auth.py` ("pi" inside "api") were denied critically too. These now key on the resolved `PI_CODING_AGENT_DIR`; Guard protects only enforcement-critical installed state while Strict retains the wider private-path policy.
+- Stop latching the session lock when a *read* is refused. Blocking the read is the protection; locking additionally refused every later call — including read-only ones — until `/guard unlock`, so one blocked file ended the session. Critical mutation attempts still lock.
+- Stop treating a plain `find` as a deletion. `find` sits in the delete family for `-delete`/`-exec`, but `hasRecursiveFlag` matches any predicate containing an "r", so `find src -type f -print` was reported as "Recursive deletion needs approval", `find /etc -name '*.conf'` denied critically, and `find . -name specpi` tripped guard self-tamper. Mutating `find` now reaches `filesystem.find-mutation`, which was unreachable behind the delete-family branch, and `clearlyReadOnly` shares the same predicate list.
+- Classify complete environment enumeration however it is spelled (`printenv`, `declare -x`, `export -p`, `compgen -v`, bare `declare`) and recognize `/proc/<pid>/environ` and `/proc/<pid>/mem` shell reads. Strict asks about those findings; Guard does not claim comprehensive credential-read protection.
+- Protect macOS system roots (`/System`, `/Library`, `/Applications`, `/Users/<name>`, `/Volumes/<name>`, `/private/etc`, `/cores`) and `.bash_profile`/`.zshenv`/`.zlogin`, without capturing the firmlinked `/System/Volumes/Data` user tree.
+- Give approval prompts a human-scale bound and add **Allow exact call for session**. Reuse is limited to 128 in-memory SHA-256 fingerprints over complete tool input, cwd, mode, and policy version; calls are always reanalyzed first, critical denials cannot be overridden, and `/guard clear-approvals` clears the set.
+- Fail doctor on installed command-guard checksum drift, on a `pi-subagents` version that no longer matches the pinned native-child contract, and when no PowerShell parser host is available; add byte-for-byte installer/update rollback injection coverage.
+- Document the defense-in-depth boundary, including direct user commands, custom tools, approved scripts, trusted extensions/configuration, TOCTOU behavior, and the need for OS-level isolation with hostile code.
+
+## 0.7.0 - 2026-08-29
+
+- Make retirement durable: every capability now ships a closed validator from a reviewed catalog, `finish_harness_improvement` dispatches all linked validators generically and fails closed on unknown names, and `npm run check` plus `specpi doctor` continuously re-prove retired capabilities in temporary state.
+- Add the improvement journal: retirements persist bounded sanitized proof (acceptance evidence, gates, repo-relative changed files, SpecPi version) in the local decision log, `/wishlist history [id]` renders the harness's own changelog with rollback context, and the report's retired list shows verification dates and gates.
+- Add loop health metrics: deterministic retirements, reopen rate, open reviews, median time-to-retire, and qualification rate rendered in the report footer and summarized by `/wishlist status`.
+- Make reopens context-rich: reopen decisions link to the retirement they review, carry up to five sanitized post-retirement signals, and the `/harness-improvement` prompt includes the original proof and what changed since.
+- Extend repository checks to the wishlist extension and validator sources, ship the validator module through install/update/uninstall, and run completion validators from the source checkout under review; document the new local-only journal data classes in SECURITY.md and the `SpecPi-Gap:` commit trailer convention in the improvement skill.
+
+## 0.6.1 - 2026-08-29
+
+- Flush a prompt frame when extension dialogs mount so chained menus such as `/spec-subagents` do not remain invisible until the next keypress in regular TUI sessions, notably through Windows SSH terminals; require and bootstrap the reviewed Pi 0.84.4 baseline that provides prompt lifecycle events.
+- Fix provider-profile activation on model changes by prompting the user to run the documented `/reload` flow instead of calling command-only `ctx.reload()` from a lifecycle event context.
+- Redesign the README self-improvement diagram as a compact Tea House graphic and version its asset URL so GitHub and browser caches cannot retain the previous rendering.
+
+## 0.6.0 - 2026-08-29
+
+- Add exact-provider subagent profiles that restore automatically with a single bounded runtime reload, while keeping capacity global and unavailable saved models stale without replacement.
+- Add ephemeral provider leases so simultaneous different-provider Pi processes fail closed instead of racing the shared active settings mirror.
+- Preserve private provider profiles across update and uninstall; store no credentials, authentication data, prompts, sessions, history, or complete settings snapshots.
+- Replace the README's text loop with an accessible static Tea House SVG and update the showcase to explain saved provider restoration.
+
+## 0.5.0 - 2026-08-29
+
+- Automatically install pinned `@earendil-works/pi-coding-agent@0.84.3` through npm after confirmation when `pi` is absent; preserve the external installation on rollback and uninstall, with `--skip-package-install` as the opt-out.
+- Add `/spec-subagents` with confirmed capacity, builtin-role model, and thinking configuration using only the documented `pi-subagents` config surface.
+- Synchronize strict native subagent scope to the parent's exact Pi provider, filter model choices accordingly, flag stale role models after provider changes, and block unsafe project-scope tool launches.
+- Preserve user-tunable role and capacity leaves across update/uninstall while continuing to enforce security-owned settings; add bounded leaf backups, shared locking, atomic writes, rollback, doctor validation, and legacy whole-file config migration.
+- Add provider-safe delegation guidance to the working agreement, README, security documentation, and static showcase.
+
+## 0.4.0 - 2026-08-29
+
+- Replace the abstract cycle charts with an accessible interactive walkthrough that shows one gap moving through evidence, human choice, proof, retirement, and later review.
+- Replace `@tmustier/pi-files-widget` with an in-house, Tea House-native `/files` browser using Pi's built-in syntax and Markdown renderers; remove the bat, git-delta, and glow prerequisites and retire their legacy managed binaries on update.
+
+## 0.3.0 - 2026-08-29
+
+- Complete the local improvement loop with explicit collection consent, deterministic evidence ranking, lifecycle decisions, and regression-aware retirement.
+- Replace hard-coded implemented capability keys with a reviewed registry linked to closed `specpi doctor` validators; the browser smoke now verifies both exact and changed pixel comparisons.
+- Add reversible exact alias decisions, local sanitized issue drafts, and recoverable checksummed archive/reset operations.
+- Add the one-command `/harness-improvement` menu and `specpi-improve` workflow, with session-bound implementation authorization, repository and capability verification gates, and automatic retirement only after success.
+- Refresh the minimal README and showcase with explicit retired/review semantics plus accessible cycle and verification-outcome charts.
+
+## 0.2.0 - 2026-08-29
+
+- Add a native Windows command launcher and Windows-safe executable discovery for `pi.cmd`, `npm.cmd`, and access-restricted Windows App Execution Aliases such as `winget.exe`.
+- Invoke `.cmd`/`.bat` shims as a single quoted `ComSpec` command, avoiding Node's deprecated shell-plus-arguments path.
+- Make the npm binary entry invoke Node directly instead of requiring a POSIX shell.
+- Document platform-specific install commands and automatic dependency installation, and preflight the Pi 0.80.0 package API baseline.
+- Add Windows installation smoke coverage.
+- Offer missing bat, git-delta, glow, and DonSeTch tools individually during interactive installs; `--yes` attempts all and `--skip-tool-install` opts out.
+- Pin bat 0.26.1, git-delta 0.19.2 (0.18.2 on Intel macOS), glow 3.0.0, and DonSeTch 3.4.0; use exact Winget installs on Windows and checksum-verified managed archives on Linux/macOS.
+- Roll managed optional binaries back with failed installs and remove them on uninstall while documenting that Winget/global npm changes remain external.
+
+## 0.1.0 - 2026-08-28
+
+- Add explicit plan/install/update/doctor/uninstall workflow.
+- Add managed AGENTS and shell blocks with backups and checksums.
+- Add provider-safe strict native-subagent inheritance.
+- Disable external Codex subscription runners.
+- Bundle the Spec extension, Tea House theme, and DonSeTch skill.
+- Make `/spec` a focused execution mode with persistent activity UI, collapsed tool output, per-turn guidance, session persistence, and full toggle restoration.
+- Add a privacy-minimized, task-deduplicated capability-gap collector and generated tool wishlist, with `/wishlist` rendering the refreshed Markdown report directly in the conversation and retiring capabilities implemented by SpecPi.
+- Add managed isolated browser QA on hosts satisfying Playwright Chromium system requirements, with a pinned runtime, responsive viewport tools, bounded inline screenshots, explicit baselines, and pixel-diff artifacts.
+- Add browser runtime staging, rollback, doctor smoke validation, and uninstall cleanup while preserving browser artifacts.
+- Add a zero-dependency SpecPi showcase site with GitHub Pages publishing.
+- Pin the reviewed Pi package baseline.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpecPi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NPM_RELEASE.md

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,155 @@
+<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.

package/SECURITY.md

@@ -0,0 +1,85 @@
+# 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).
+
+## Supported versions
+
+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.
+
+| Release | Security support |
+| --- | --- |
+| Latest tagged release | Supported |
+| Older releases | Unsupported |
+
+## 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 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 |
+| 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.