opencode-autoresearch 3.3.0 → 3.3.1

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

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

package/hooks/verify-package.sh

@@ -16,7 +16,7 @@ const packResult = JSON.parse(raw);
 const entries = Array.isArray(packResult) ? packResult : [packResult];
 const files = entries.flatMap((entry) => Array.isArray(entry.files) ? entry.files : []);
 
-const allowedRoots = new Set(["dist", "hooks", "commands", "skills", "docs", ".opencode-plugin"]);
+const allowedRoots = new Set(["dist", "hooks", "commands", "skills", "plugins", "docs", ".opencode-plugin"]);
 const allowedFiles = new Set(["package.json", "README.md", "LICENSE", "AGENTS.md", "VERSION"]);
 const requiredFiles = [
   ".opencode-plugin/plugin.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-autoresearch",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "description": "Autonomous recursive self-improvement engine for OpenCode. Subagent-first iteration loop with standing-pool orchestration and mechanical verification.",
   "author": {
     "name": "Maleick",
@@ -42,6 +42,7 @@
     "hooks",
     "commands",
     "skills",
+    "plugins",
     "docs",
     ".opencode-plugin",
     "AGENTS.md",
@@ -52,7 +53,7 @@
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit",
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --config jest.config.json",
+    "test": "node --no-warnings --experimental-vm-modules node_modules/jest/bin/jest.js --config jest.config.json",
     "verify:pack": "bash hooks/verify-package.sh",
     "prepack": "tsc"
   },

package/plugins/autoresearch.ts

@@ -0,0 +1,13 @@
+export {
+  id,
+  repoRoot,
+  version,
+} from "../dist/index.js";
+
+export async function server() {
+  return {
+    event() {
+      return undefined;
+    },
+  };
+}

package/AGENTS.md

@@ -1,42 +0,0 @@
-# Auto Research Agent Guide
-
-Auto Research is an OpenCode-only autonomous iteration engine with recursive self-improvement capabilities.
-
-## Runtime Policy
-
-- OpenCode is the only supported runtime.
-- The iteration engine is subagent-first: a standing pool of specialized subagents supports the orchestrator.
-- Mechanical verification is mandatory — no keep decisions on intuition alone.
-- Background runs support overnight unattended operation.
-
-## Local State
-
-`.autoresearch/` is runtime state and must not be committed.
-
-## Verification
-
-Before claiming work is complete, run:
-
-```bash
-npm run typecheck
-npm run build
-npm run verify:pack
-```
-
-## Self-Improvement
-
-Auto Research can run on itself. See `skills/autoresearch/references/self-improve-loop.md` for recursive loop semantics.
-
-When running self-improvement:
-
-1. Define a measurable meta-goal.
-2. Use `--mode background` for long runs.
-3. Always set a `--guard` command to catch regressions.
-4. Review `autoresearch-memory.md` between meta-iterations.
-
-## Docs
-
-- [README.md](README.md) — Product overview
-- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — Architecture reference
-- [docs/RELEASE.md](docs/RELEASE.md) — Release process
-- [wiki/Home.md](wiki/Home.md) — Wiki index