opencode-autoresearch 3.3.1 → 3.4.1

package/docs/superpowers/specs/2026-05-03-install-release-security-design.md

@@ -1,80 +0,0 @@
-# Install, Release, and Security Update Design
-
-## Goal
-
-Prepare Auto Research for the next patch release by adding a native OpenCode install guide, aligning release/package documentation, and fixing security issues found during the audit.
-
-## Current Context
-
-Auto Research is distributed as the `opencode-autoresearch` npm package and exposes an OpenCode plugin surface through `.opencode-plugin/plugin.json`, `plugins/autoresearch.ts`, `commands/`, `skills/`, and `hooks/`. The repo already documents npm global installation, but it does not provide a repo-level `.opencode/INSTALL.md` like the Superpowers OpenCode guide.
-
-The audit found these release-readiness issues:
-
-- `AGENTS.md` is ignored and absent, but package metadata and release docs reference it.
-- `docs/ARCHITECTURE.md` still says the current reference is v3.3.0 while released metadata is v3.3.1.
-- `docs/RELEASE.md` says CI runs tests, but `.github/workflows/release.yml` currently runs build, typecheck, and package verification only.
-- `hooks/status.sh` and `hooks/stop.sh` interpolate `AUTORESEARCH_STATE` directly into inline JavaScript, which can break the JavaScript string if the environment variable contains quotes.
-- Dependencies are clean: `npm audit --audit-level=moderate` found 0 vulnerabilities and `npm outdated` reported no outdated packages.
-
-## Approach
-
-Use both supported install paths:
-
-- Primary: OpenCode native plugin install through `opencode.json` using the npm package name.
-- Alternative: npm global CLI install for users who want the `autoresearch` and `opencode-autoresearch` commands on `PATH`.
-
-This matches current OpenCode plugin documentation, which supports npm package entries in the `plugin` array and automatically installs them at startup. It also keeps the current npm CLI distribution intact.
-
-## Files and Responsibilities
-
-- `.opencode/INSTALL.md`: New concise OpenCode install guide modeled after the Superpowers install guide.
-- `README.md`: Main install section should show the OpenCode plugin path first and npm global CLI path second.
-- `docs/OPENCODE_INSTALL.md`: Full install guide should mirror the new install flow and include verification/troubleshooting.
-- `wiki/Installation.md`: Wiki install page should point users to the native plugin path and CLI alternative.
-- `AGENTS.md`: New tracked agent guide with repository-specific working, validation, security, and release rules.
-- `.gitignore`: Stop ignoring tracked `AGENTS.md` while continuing to ignore private local instruction files that should not ship.
-- `package.json`: Include `.opencode/INSTALL.md` in package contents and bump the patch version.
-- `package-lock.json`: Keep npm lock metadata aligned with `package.json`.
-- `.opencode-plugin/plugin.json`: Bump plugin manifest version.
-- `src/constants.ts`: Bump runtime version constant.
-- `VERSION`: Bump canonical version marker.
-- `CHANGELOG.md`: Add the new release entry.
-- `docs/ARCHITECTURE.md`: Align current version and package layout references.
-- `docs/RELEASE.md`: Align release docs with current version surfaces and trusted npm publishing workflow.
-- `.github/workflows/release.yml`: Add `npm test` to match documented release gates.
-- `hooks/status.sh`: Pass state path safely to Node without JavaScript string interpolation.
-- `hooks/stop.sh`: Pass state path safely to Node without JavaScript string interpolation.
-- `hooks/verify-package.sh`: Allow and require `.opencode/INSTALL.md`; keep package allowlist explicit.
-
-## Security Design
-
-The hook hardening should pass `STATUS_FILE` through Node's `process.env` instead of embedding it in JavaScript source. This prevents an environment value from changing the JavaScript program text and keeps shell quoting simple.
-
-The install docs must avoid `curl | sh` and destructive migration commands. They should show an explicit `opencode.json` plugin entry and a separate npm global CLI path.
-
-The package verifier remains allowlist-based. Adding `.opencode/INSTALL.md` must be explicit so unexpected files still fail `npm run verify:pack`.
-
-## Versioning
-
-This is a patch release because it adds install documentation, fixes release packaging metadata, and hardens hooks without changing the command surface or runtime data format.
-
-Target version: `3.3.2`.
-
-## Verification
-
-Run these gates before claiming release readiness:
-
-```bash
-npm audit --audit-level=moderate
-npm run typecheck
-npm run build
-npm run verify:pack
-npm test
-npm pack --dry-run
-```
-
-Also inspect the package dry-run output enough to confirm `.opencode/INSTALL.md`, `AGENTS.md`, `README.md`, `VERSION`, `.opencode-plugin/plugin.json`, `commands/`, `skills/`, `hooks/`, `plugins/`, and `docs/` are present while `.autoresearch/` and local context files are absent.
-
-## Release Boundary
-
-This work prepares the repository for release. Creating the git commit, tag, push, GitHub release, or npm publish requires explicit user approval after verification passes.