opencode-autoresearch 3.3.0 → 3.4.0

package/docs/QUICKSTART.md

@@ -0,0 +1,145 @@
+# Quick Start Guide
+
+## Installation
+
+### OpenCode
+
+```bash
+npm install -g opencode-autoresearch
+autoresearch doctor
+```
+
+### Hermes Agent
+
+```bash
+# 1. Install the skill
+git clone https://github.com/Maleick/AutoResearch.git
+cd AutoResearch
+npm install
+mkdir -p ~/.hermes/skills/software-development/autoresearch
+cp skills/hermes/autoresearch-prompt.md ~/.hermes/skills/software-development/autoresearch/SKILL.md
+cp skills/hermes/INTEGRATION.md ~/.hermes/skills/software-development/autoresearch/REFERENCES.md
+
+# 2. Create a cronjob
+hermes cron create \
+  --name "autoresearch-loop" \
+  --workdir ~/projects/AutoResearch \
+  --skill autoresearch-hermes \
+  "every 15m" \
+  "Run AutoResearch iteration loop. Detect phase from .autoresearch/state.json and execute one phase. Approved verify command: 'npm run test:coverage'. Approved guard command: 'npm run typecheck'."
+```
+
+## Basic Usage
+
+### 1. Initialize a run
+
+```bash
+autoresearch init \
+  --goal "Improve response time" \
+  --metric "response_time_ms" \
+  --direction "lower" \
+  --verify "npm test"
+```
+
+### 2. Check status
+
+```bash
+autoresearch status
+```
+
+### 3. Record an iteration
+
+```bash
+autoresearch record \
+  --decision keep \
+  --metric-value "120" \
+  --verify-status pass \
+  --change-summary "Optimized database queries" \
+  --labels "perf,database"
+```
+
+### 4. View history
+
+```bash
+autoresearch history
+```
+
+### 5. Complete the run
+
+```bash
+autoresearch complete
+```
+
+## Background Runs
+
+For overnight or long-running improvements:
+
+```bash
+autoresearch init \
+  --goal "Refactor codebase" \
+  --metric "complexity" \
+  --direction "lower" \
+  --verify "npm test" \
+  --mode background \
+  --iterations 20
+
+autoresearch launch
+# ... work on other things ...
+autoresearch status
+```
+
+### Hermes Background Runs
+
+```bash
+# Initialize state from a trusted shell before enabling unattended cron
+autoresearch init \
+  --goal "Improve test coverage" \
+  --metric "coverage_pct" \
+  --direction "higher" \
+  --verify "npm run test:coverage" \
+  --guard "npm run typecheck" \
+  --iterations 20 \
+  --mode background
+
+# Start cron
+hermes cron resume autoresearch-loop
+
+# Check progress
+cat .autoresearch/state.json | jq .
+```
+
+## Self-Improvement
+
+Run AutoResearch on itself:
+
+```bash
+autoresearch init \
+  --goal "Improve test coverage" \
+  --metric "test_count" \
+  --direction "higher" \
+  --verify "npm test" \
+  --mode background
+```
+
+## Shell Completion
+
+```bash
+# Bash
+autoresearch completion --shell bash >> ~/.bashrc
+
+# Zsh
+autoresearch completion --shell zsh >> ~/.zshrc
+
+# Fish
+autoresearch completion --shell fish >> ~/.config/fish/completions/autoresearch.fish
+```
+
+## Exporting Results
+
+```bash
+# JSON export
+autoresearch export --format json > results.json
+
+# Markdown report
+autoresearch report > report.md
+```

package/docs/RELEASE.md

@@ -4,7 +4,7 @@ This package uses npm publish for releases. GitHub Actions automates the full re
 
 ## Version Alignment
 
-`VERSION`, `package.json`, `src/constants.ts`, and `.opencode-plugin/plugin.json` must all stay aligned. The `VERSION` file is the canonical source of truth.
+`VERSION`, `package.json`, `package-lock.json`, `src/constants.ts`, and `.opencode-plugin/plugin.json` must all stay aligned. The `VERSION` file is the canonical source of truth.
 
 ## Release Steps
 
@@ -12,10 +12,10 @@ This package uses npm publish for releases. GitHub Actions automates the full re
 
 ```bash
 # Update VERSION file
-echo "3.2.0" > VERSION
+echo "3.3.3" > VERSION
 
 # Sync to package.json
-npm version 3.2.0 --no-git-tag-version
+npm version 3.3.3 --no-git-tag-version
 
 # Sync to src/constants.ts
 # Update the VERSION export manually or use sed
@@ -36,25 +36,24 @@ npm test
 Add a new section for the version in `CHANGELOG.md`:
 
 ```markdown
-## [3.2.0] - YYYY-MM-DD
+## [3.3.3] - YYYY-MM-DD
 
 ### Added
-- Recursive self-improvement loop support
-- Mermaid diagrams in documentation
-- Enhanced subagent pool with meta-orchestrator role
+- Root install handoff
+- Public install verification notes
 
 ### Changed
-- Updated README with banner and visual diagrams
-- Improved wiki pages with architecture charts
+- Installation docs
+- Package verification allowlist
 ```
 
 ### 4. Commit and tag
 
 ```bash
 git add -A
-git commit -m "Release v3.2.0"
-git tag v3.2.0
-git push origin main v3.2.0
+git commit -m "Release v3.3.3"
+git tag v3.3.3
+git push origin main v3.3.3
 ```
 
 ### 5. Automated release
@@ -64,8 +63,8 @@ GitHub Actions will:
 1. Build and type-check
 2. Verify package contents
 3. Run tests
-4. Create a GitHub Release with CHANGELOG section
-5. Publish to npm
+4. Create a GitHub Release with the CHANGELOG section
+5. Publish to npm with provenance through trusted publishing
 
 ## Manual publish (fallback)
 
@@ -86,7 +85,9 @@ The shipped package includes:
 - `commands/` — OpenCode command surfaces (`autoresearch.md`, `autoresearch/*.md`)
 - `skills/autoresearch/` — Skill bundle with references
 - `hooks/` — Shell hooks for session lifecycle
-- `docs/` — Installation, architecture, and release docs
+- selected `docs/` files — `ARCHITECTURE.md`, `OPENCODE_INSTALL.md`, `QUICKSTART.md`, `RELEASE.md`, documentation site assets, and `CNAME`
+- `INSTALL.md` — Public raw OpenCode install handoff
+- `.opencode/INSTALL.md` — OpenCode native plugin install guide
 - `.opencode-plugin/plugin.json` — OpenCode plugin manifest
 - `AGENTS.md` — Agent guide
 - `VERSION` — Version marker

package/hooks/status.sh

@@ -7,18 +7,20 @@ set -e
 STATUS_FILE="${AUTORESEARCH_STATE:-.autoresearch/state.json}"
 
 if [ -f "$STATUS_FILE" ]; then
-  node --input-type=module -e "
-    import { readFileSync } from 'fs';
-    const s = JSON.parse(readFileSync('$STATUS_FILE', 'utf8'));
-    console.log('Auto Research run: ' + s.run_id);
-    console.log('Status: ' + s.status);
-    console.log('Mode: ' + s.mode);
-    console.log('Goal: ' + s.goal);
-    console.log('Iterations: ' + s.stats.total_iterations);
-    console.log('Kept: ' + s.stats.kept + ' | Discarded: ' + s.stats.discarded);
-    if (s.flags.needs_human) console.log('NEEDS HUMAN');
-    if (s.flags.stop_requested) console.log('STOP REQUESTED');
-  " 2>/dev/null || echo "No active run."
+  AUTORESEARCH_STATUS_FILE="$STATUS_FILE" node --input-type=module -e '
+    import { readFileSync } from "fs";
+    const statusFile = process.env.AUTORESEARCH_STATUS_FILE;
+    if (!statusFile) throw new Error("Missing AUTORESEARCH_STATUS_FILE");
+    const s = JSON.parse(readFileSync(statusFile, "utf8"));
+    console.log("Auto Research run: " + s.run_id);
+    console.log("Status: " + s.status);
+    console.log("Mode: " + s.mode);
+    console.log("Goal: " + s.goal);
+    console.log("Iterations: " + s.stats.total_iterations);
+    console.log("Kept: " + s.stats.kept + " | Discarded: " + s.stats.discarded);
+    if (s.flags.needs_human) console.log("NEEDS HUMAN");
+    if (s.flags.stop_requested) console.log("STOP REQUESTED");
+  ' 2>/dev/null || echo "No active run."
 else
   echo "No active run."
 fi

package/hooks/stop.sh

@@ -5,24 +5,58 @@
 set -e
 
 STATUS_FILE="${AUTORESEARCH_STATE:-.autoresearch/state.json}"
+WORKSPACE_ROOT="$(pwd -P)"
 
-if [ -f "$STATUS_FILE" ]; then
-  mode=$(node --input-type=module -e "
-    import { readFileSync } from 'fs';
-    const s = JSON.parse(readFileSync('$STATUS_FILE', 'utf8'));
-    console.log(s.mode || '');
-  " 2>/dev/null || true)
+case "$STATUS_FILE" in
+  /*) STATUS_FILE_ABS="$STATUS_FILE" ;;
+  *) STATUS_FILE_ABS="$WORKSPACE_ROOT/$STATUS_FILE" ;;
+esac
+
+if [ -L "$STATUS_FILE_ABS" ]; then
+  echo "Refusing symlinked state file."
+  exit 0
+fi
+
+STATUS_DIR="${STATUS_FILE_ABS%/*}"
+STATUS_NAME="${STATUS_FILE_ABS##*/}"
+STATUS_DIR_REAL="$(cd "$STATUS_DIR" 2>/dev/null && pwd -P)" || {
+  echo "No active run."
+  exit 0
+}
+STATUS_FILE_REAL="$STATUS_DIR_REAL/$STATUS_NAME"
+WORKSPACE_STATE_DIR="$WORKSPACE_ROOT/.autoresearch"
+
+case "$STATUS_FILE_REAL" in
+  "$WORKSPACE_STATE_DIR"/*) ;;
+  *)
+    echo "Refusing state file outside workspace."
+    exit 0
+    ;;
+esac
+
+if [ -f "$STATUS_FILE_ABS" ]; then
+  mode=$(AUTORESEARCH_STATUS_FILE="$STATUS_FILE_ABS" node --input-type=module -e '
+    import { readFileSync } from "fs";
+    const statusFile = process.env.AUTORESEARCH_STATUS_FILE;
+    if (!statusFile) throw new Error("Missing AUTORESEARCH_STATUS_FILE");
+    const s = JSON.parse(readFileSync(statusFile, "utf8"));
+    console.log(s.mode || "");
+  ' 2>/dev/null || true)
   if [ "$mode" = "background" ]; then
-    node --input-type=module -e "
-      import { readFileSync, writeFileSync } from 'fs';
-      const s = JSON.parse(readFileSync('$STATUS_FILE', 'utf8'));
+    AUTORESEARCH_STATUS_FILE="$STATUS_FILE_ABS" node --input-type=module -e '
+      import { readFileSync, renameSync, writeFileSync } from "fs";
+      const statusFile = process.env.AUTORESEARCH_STATUS_FILE;
+      if (!statusFile) throw new Error("Missing AUTORESEARCH_STATUS_FILE");
+      const s = JSON.parse(readFileSync(statusFile, "utf8"));
       s.updated_at = new Date().toISOString();
       s.flags.stop_requested = true;
       s.flags.background_active = false;
-      s.status = 'stopping';
-      writeFileSync('$STATUS_FILE', JSON.stringify(s, null, 2) + '\n');
-      console.log('Stop requested for run: ' + s.run_id);
-    " 2>/dev/null || echo "Could not update state."
+      s.status = "stopping";
+      const tmp = `${statusFile}.tmp.${process.pid}`;
+      writeFileSync(tmp, JSON.stringify(s, null, 2) + "\n", { mode: 0o600 });
+      renameSync(tmp, statusFile);
+      console.log("Stop requested for run: " + s.run_id);
+    ' 2>/dev/null || echo "Could not update state."
   else
     echo "Only background runs can be stopped."
   fi

package/hooks/verify-package.sh

@@ -16,17 +16,50 @@ 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 allowedFiles = new Set(["package.json", "README.md", "LICENSE", "AGENTS.md", "VERSION"]);
+const allowedRoots = new Set(["dist", "hooks", "commands", "skills", ".opencode-plugin"]);
+const allowedFiles = new Set([
+  "package.json",
+  "README.md",
+  "LICENSE",
+  "AGENTS.md",
+  "VERSION",
+  "INSTALL.md",
+  ".opencode/INSTALL.md",
+  "plugins/autoresearch.ts",
+  "docs/ARCHITECTURE.md",
+  "docs/autoresearch-loop.svg",
+  "docs/CNAME",
+  "docs/index.html",
+  "docs/OPENCODE_INSTALL.md",
+  "docs/QUICKSTART.md",
+  "docs/RELEASE.md",
+]);
 const requiredFiles = [
+  "INSTALL.md",
+  ".opencode/INSTALL.md",
   ".opencode-plugin/plugin.json",
+  "AGENTS.md",
+  "dist/cli.js",
+  "dist/index.js",
+  "dist/index.d.ts",
   "hooks/init.sh",
   "skills/autoresearch/SKILL.md",
   "commands/autoresearch.md",
 ];
 
 const normalizePath = (filePath) => filePath.replace(/^package\//, "");
-const isForbidden = (filePath) => filePath === ".autoresearch" || filePath.startsWith(".autoresearch/");
+const forbiddenFiles = new Set([
+  "autoresearch-results.tsv",
+  "autoresearch-report.md",
+  "autoresearch-memory.md",
+  "autoresearch-hook-context.json",
+]);
+const isForbidden = (filePath) =>
+  filePath === ".autoresearch" ||
+  filePath.startsWith(".autoresearch/") ||
+  filePath === ".autoresearch-test-tmp" ||
+  filePath.startsWith(".autoresearch-test-tmp/") ||
+  forbiddenFiles.has(filePath);
 const isAllowed = (filePath) => {
   if (allowedFiles.has(filePath)) return true;
   const [root] = filePath.split("/");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-autoresearch",
-  "version": "3.3.0",
-  "description": "Autonomous recursive self-improvement engine for OpenCode. Subagent-first iteration loop with standing-pool orchestration and mechanical verification.",
+  "version": "3.4.0",
+  "description": "Autonomous recursive self-improvement engine for OpenCode and Hermes Agent. Subagent-first iteration loop with mechanical verification.",
   "author": {
     "name": "Maleick",
     "url": "https://github.com/Maleick"
@@ -17,7 +17,9 @@
   "license": "MIT",
   "keywords": [
     "opencode",
+    "hermes",
     "plugin",
+    "agent",
     "autoresearch",
     "automation",
     "workflows",
@@ -42,7 +44,16 @@
     "hooks",
     "commands",
     "skills",
-    "docs",
+    "plugins/autoresearch.ts",
+    "docs/ARCHITECTURE.md",
+    "docs/autoresearch-loop.svg",
+    "docs/CNAME",
+    "docs/index.html",
+    "docs/OPENCODE_INSTALL.md",
+    "docs/QUICKSTART.md",
+    "docs/RELEASE.md",
+    "INSTALL.md",
+    ".opencode/INSTALL.md",
     ".opencode-plugin",
     "AGENTS.md",
     "VERSION",
@@ -52,14 +63,23 @@
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit",
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --config jest.config.json",
+    "audit": "npm audit --audit-level=moderate",
+    "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"
+    "prepack": "node scripts/sync-version.mjs && tsc"
   },
   "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^20.0.0",
     "jest": "^30.3.0",
+    "semantic-release": "^25.0.3",
     "ts-jest": "^29.4.9",
     "typescript": "^5.9.3"
   },

package/plugins/autoresearch.ts

@@ -0,0 +1,7 @@
+export {
+  default,
+  id,
+  repoRoot,
+  server,
+  version,
+} from "../dist/index.js";

package/skills/hermes/INTEGRATION.md

@@ -0,0 +1,156 @@
+# AutoResearch Hermes Integration
+
+## Overview
+
+AutoResearch can run on Hermes Agent using `delegate_task` for subagent pools and `cronjob` for recurring iteration loops.
+
+## Architecture
+
+```
+Hermes Cron (every 15m)
+  → Check state.json for active run
+  → If running: spawn subagents (Scout, Analyst, Verifier)
+  → Each subagent performs one iteration phase
+  → Verify results mechanically
+  → Keep/Discard based on metrics
+  → Update state.json
+  → Repeat until stop condition
+```
+
+## Key Differences from OpenCode
+
+| Feature | OpenCode | Hermes |
+|---------|----------|--------|
+| Entry | `/autoresearch` slash command | `cronjob` or `delegate_task` |
+| Subagents | Standing pool | `delegate_task` batch (max 3) |
+| State | `.autoresearch/state.json` | Same file + Hermes memory |
+| Verification | `npm test`, etc. | Same — mechanical verification |
+| Background | `autoresearch launch` | `cronjob` with `background=True` |
+| Resume | `autoresearch resume` | Cron continues automatically |
+
+## Setup
+
+```bash
+# 1. Install AutoResearch CLI (for state management)
+npm install -g opencode-autoresearch
+
+# 2. Create Hermes cron for AutoResearch
+cd ~/projects/AutoResearch
+hermes cron create \
+  --name "autoresearch-loop" \
+  --workdir ~/projects/AutoResearch \
+  --skill autoresearch-hermes \
+  "every 15m" \
+  "Run AutoResearch iteration loop. Detect phase from .autoresearch/state.json and execute one phase. Approved verify command is \`npm run test:coverage\` and approved guard command is \`npm run typecheck\`"
+```
+
+## Hermes Prompt Template
+
+See `skills/hermes/autoresearch-prompt.md` for the full cron prompt.
+
+## Commands Mapping
+
+| OpenCode Command | Hermes Equivalent |
+|-----------------|-------------------|
+| `/autoresearch` | Cron runs iteration loop |
+| `/autoresearch:plan` | Subagent task: plan experiments |
+| `/autoresearch:debug` | Subagent task: debug failures |
+| `/autoresearch:fix` | Subagent task: fix issues |
+| `/autoresearch:learn` | Memory tool + pattern analysis |
+| `autoresearch init` | Manual setup (same CLI) |
+| `autoresearch status` | `cat .autoresearch/state.json` |
+| `autoresearch launch` | `hermes cron create` |
+| `autoresearch stop` | `hermes cron pause` |
+| `autoresearch resume` | `hermes cron resume` |
+
+## State File Format
+
+Hermes uses the same `.autoresearch/state.json` format as OpenCode:
+
+```json
+{
+  "schema_version": 1,
+  "run_id": "2026-05-03-001",
+  "status": "initialized",
+  "mode": "background",
+  "goal": "Improve test coverage",
+  "metric": {
+    "name": "coverage_pct",
+    "direction": "higher",
+    "baseline": "72.4",
+    "best": "72.4",
+    "latest": "72.4"
+  },
+  "verify": "npm run test:coverage",
+  "guard": "npm run typecheck",
+  "stats": {
+    "total_iterations": 12,
+    "kept": 8,
+    "discarded": 4
+  },
+  "flags": {
+    "needs_human": false,
+    "stop_requested": false,
+    "background_active": true,
+    "stop_ready": false
+  }
+}
+```
+
+## Subagent Roles
+
+### Scout
+- **Goal**: Find improvement opportunities
+- **Toolsets**: `["terminal", "file", "web"]`
+- **Context**: Current codebase, test results, coverage reports
+
+### Analyst
+- **Goal**: Analyze patterns in kept/discarded iterations
+- **Toolsets**: `["file", "web"]`
+- **Context**: `autoresearch-results.tsv`, memory
+
+### Verifier
+- **Goal**: Run mechanical verification
+- **Toolsets**: `["terminal"]`
+- **Context**: Operator-approved verify command and guard command; repository state commands are metadata only
+
+## Memory Integration
+
+Hermes `memory` tool stores:
+- Successful strategies per project type
+- Common failure patterns
+- Optimal iteration counts per goal type
+- Best verify/guard command combinations
+
+## Example Cron Prompt
+
+```markdown
+You are AutoResearch running on Hermes Agent.
+
+## Current Run
+Run ID: {{run_id}}
+Goal: {{goal}}
+Metric: {{metric}}
+Iteration: {{current}}/{{max}}
+
+## Phase: {{phase}}
+
+{{phase_instructions}}
+
+## STOP after completing this phase.
+Next cron run will continue with the next phase.
+```
+
+## Limitations
+
+- Hermes max 3 concurrent subagents vs OpenCode's standing pool
+- Hermes cron intervals minimum 5 minutes vs OpenCode's real-time
+- No `/autoresearch:` slash command variants (use separate cron jobs)
+- Memory is session-based; use `memory` tool for persistence
+- Commits and destructive rollback require explicit user approval
+
+## Future Enhancements
+
+- [ ] Auto-detect optimal cron interval based on iteration duration
+- [ ] Integration with Hermes checkpoint/rollback for safe resets
+- [ ] Cross-session memory for strategy learning