opencode-code-archaeology 2.0.2 → 2.2.0

package/.github/pull_request_template.md

@@ -4,6 +4,7 @@
 
 ## Verification
 
+- [ ] Polish pass completed before commit, push, and PR.
 - [ ] `npm run build`
 - [ ] `npm run typecheck`
 - [ ] `npm test`

package/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Type check
+        run: npm run typecheck
+
+      - name: Verify package
+        run: npm run verify:pack
+
+      - name: Test
+        run: npm test
+
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_CONFIG_PROVENANCE: true
+        run: npx semantic-release

package/AGENTS.md

@@ -1,27 +1,35 @@
 # Code Archaeology Agent Guide
 
-Code Archaeology is an OpenCode plugin for systematic codebase excavation, cataloging, and restoration.
+Code Archaeology is a multi-runtime plugin for systematic codebase excavation, cataloging, and restoration. It supports both **OpenCode** and **Hermes Agent** runtimes.
 
 ## Runtime Policy
 
-- OpenCode is the only supported worker runtime.
+- **OpenCode** is the primary interactive runtime (slash commands).
+- **Hermes Agent** is the cron-based background runtime (one phase per 15-minute run).
 - The plugin operates entirely within the target repository.
 - All changes are isolated to a configurable branch (`refactor/archaeology` by default).
 
 ## Available Hooks
 
-Core hooks in `hooks/opencode/`:
-- `init.sh` — Initialize `.archaeology/` directory and session state
-- `verify-phase.sh` — Run tests and typecheck between phases
-- `revert-phase.sh` — Revert changes if a phase fails verification
-- `update-expedition.sh` — Update expedition status in session.json
+### OpenCode hooks (`hooks/opencode/`)
+- `init.sh` / `init.ps1` — Initialize `.archaeology/` directory and session state
+- `verify-phase.sh` / `verify-phase.ps1` — Run tests and typecheck between phases
+- `revert-phase.sh` / `revert-phase.ps1` — Revert changes if a phase fails verification
+- `update-expedition.sh` / `update-expedition.ps1` — Update expedition status in session.json
+
+### Hermes hooks (`hooks/hermes/`)
+- `setup.sh` / `setup.ps1` — Detect Hermes capabilities and write `hermes-runtime.json`
+- `runner.sh` / `runner.ps1` — Execute one expedition phase per cron run with test gates
+
+**Platform support:** `.sh` scripts run on macOS/Linux; `.ps1` scripts run on Windows (PowerShell).
 
 ## Safety Hooks
 
-- `verify-phase.sh` — Mandatory test/typecheck gate between expeditions
-- `revert-phase.sh` — Automatic rollback on failure
+- `verify-phase.sh` — Mandatory test/typecheck gate between expeditions (OpenCode)
+- `revert-phase.sh` — Automatic rollback on failure (OpenCode)
+- `runner.sh` — Built-in pre/post verification and auto-revert (Hermes)
 
-## Workflow
+## OpenCode Workflow
 
 1. Run `hooks/opencode/init.sh` to initialize the session
 2. For each expedition:
@@ -31,6 +39,19 @@ Core hooks in `hooks/opencode/`:
    d. Run `hooks/opencode/update-expedition.sh <phase> <status> [findings]`
 3. Final verification runs all checks and generates `FINAL_CATALOG.md`
 
+## Hermes Workflow
+
+1. Run `hooks/hermes/setup.sh` to detect Hermes capabilities
+2. Create a Hermes cronjob (see `skills/hermes/INTEGRATION.md`)
+3. Each cron run executes **exactly ONE** phase:
+   a. Read `.archaeology/session.json` for current phase and mode
+   b. Run the phase (survey, excavate, or restore)
+   c. Run test/typecheck verification
+   d. Keep or revert changes automatically
+   e. Advance to next phase in `session.json`
+   f. **STOP** — next cron run continues
+4. After 10 phases, `FINAL_CATALOG.md` is generated
+
 ## Local State
 
 `.archaeology/` is runtime state and must not be committed.
@@ -42,6 +63,7 @@ Key files:
 - `FINAL_CATALOG.md` — Completed excavation summary
 - `excavation_log.txt` — `git diff --stat`
 - `patches/` — Mock patches (excavate mode)
+- `hermes-runtime.json` — Hermes runtime configuration (Hermes only)
 
 ## Modes
 
@@ -63,6 +85,8 @@ Key files:
 
 ## Verification
 
+### OpenCode
+
 Before claiming work is complete:
 
 ```bash
@@ -70,6 +94,14 @@ bash hooks/opencode/verify-phase.sh final_verify
 bash -n hooks/opencode/*.sh
 ```
 
+### Hermes
+
+Verification is built into `runner.sh`:
+
+```bash
+bash hooks/hermes/runner.sh
+```
+
 ## Language Support
 
 | Language | Dead Code | Dependencies | Types | DRY |

package/CHANGELOG.md

@@ -1,5 +1,64 @@
+# [2.2.0](https://github.com/Maleick/Code-Archaeology/compare/v2.1.0...v2.2.0) (2026-05-07)
+
+
+### Bug Fixes
+
+* avoid session-sourced verification commands ([#10](https://github.com/Maleick/Code-Archaeology/issues/10)) ([9d3296d](https://github.com/Maleick/Code-Archaeology/commit/9d3296d1551ed7c97b90aca5c4be932bad5042e6))
+* harden PowerShell verification hooks ([#6](https://github.com/Maleick/Code-Archaeology/issues/6)) ([ae1c1fa](https://github.com/Maleick/Code-Archaeology/commit/ae1c1fab3b1ce84872ad8217959d321e8e42266b))
+* harden trusted publishing safety ([c78ee2e](https://github.com/Maleick/Code-Archaeology/commit/c78ee2e9bc75ff6554e75f848f64a3054a74344e))
+* **hermes:** require operator approval for restore mode ([#8](https://github.com/Maleick/Code-Archaeology/issues/8)) ([772cd67](https://github.com/Maleick/Code-Archaeology/commit/772cd67df32f853c562fe8ed46f6d1528b477fda))
+* only set completed_at when status is completed ([ebf1040](https://github.com/Maleick/Code-Archaeology/commit/ebf1040fb8a4a9ff23a40d6fa6042313e590b363))
+* pass model router args safely ([#11](https://github.com/Maleick/Code-Archaeology/issues/11)) ([a7379fc](https://github.com/Maleick/Code-Archaeology/commit/a7379fcf425eab70f2906de75f0a158e7d418e85))
+* secure Hermes session rewrites ([#7](https://github.com/Maleick/Code-Archaeology/issues/7)) ([55d5694](https://github.com/Maleick/Code-Archaeology/commit/55d5694684158d1ae471fed25b4f8de0706c7810))
+
+
+### Features
+
+* Add Windows/PowerShell support ([a6b74ea](https://github.com/Maleick/Code-Archaeology/commit/a6b74ea75c1eb60263e939df3dc27fa4cc8b7a72)), closes [#4](https://github.com/Maleick/Code-Archaeology/issues/4)
+
+# [2.1.0](https://github.com/Maleick/Code-Archaeology/compare/v2.0.2...v2.1.0) (2026-05-05)
+
+
+### Bug Fixes
+
+* align analysis tool types ([65b19b2](https://github.com/Maleick/Code-Archaeology/commit/65b19b2b581c2e3f196f3d53886fd8dfdab23ea2))
+* block invalid Hermes sessions ([aaafd4f](https://github.com/Maleick/Code-Archaeology/commit/aaafd4f0a0d6652ae92b5513caa13b2fabcab06e))
+* harden Hermes install checks ([bc034cc](https://github.com/Maleick/Code-Archaeology/commit/bc034cca6cb8af88287cc3656cd72adf8a4246c1))
+* remove embedded worktree and ignore .autoship/ ([400b554](https://github.com/Maleick/Code-Archaeology/commit/400b55452f96f604074d73f6eea79cf996a91aad))
+* remove stale PluginServer stub ([#3](https://github.com/Maleick/Code-Archaeology/issues/3)) ([f8b15a3](https://github.com/Maleick/Code-Archaeology/commit/f8b15a306f55cfa6e036cc05e115357ec68df023)), closes [#2](https://github.com/Maleick/Code-Archaeology/issues/2)
+
+
+### Features
+
+* **hermes:** add full Hermes Agent runtime support ([2f4ad41](https://github.com/Maleick/Code-Archaeology/commit/2f4ad41060994802c1fb3c5a480e88728838130b)), closes [#hermes-support](https://github.com/Maleick/Code-Archaeology/issues/hermes-support) [#multi-runtime](https://github.com/Maleick/Code-Archaeology/issues/multi-runtime)
+* prepare v2.1.0 release ([54507d4](https://github.com/Maleick/Code-Archaeology/commit/54507d423b421535116363be86fbcba30b161d9e))
+* **routing:** add intelligent model routing for free-tier priority ([a456556](https://github.com/Maleick/Code-Archaeology/commit/a45655602106933de64a0af5b63e18e6378847d7))
+
 # Changelog
 
+## Unreleased
+
+- Switched release publishing to npm trusted publishing with GitHub Actions OIDC.
+- Hardened Hermes restore mode so it blocks explicitly until implemented instead of reporting a successful no-op restore.
+- Changed OpenCode revert handling to preserve failed phase changes in a named git stash instead of dropping them.
+- Exposed public type definitions through package exports and excluded the repo-local legacy plugin shim from npm package contents.
+
+## v2.1.0
+
+- Changed `/code-archaeology` to run the full 10-phase survey chain by default without per-phase prompts.
+- Kept the default OpenCode flow non-destructive: survey mode writes report artifacts under `.archaeology/` only.
+- Clarified that `/code-archaeology-restore` remains the explicit command for applying source changes.
+- Updated command, CLI, plugin, and release tests for the new default survey-chain behavior.
+
+## v2.0.3
+
+- Hardened Hermes runner startup so clean repositories initialize `.archaeology/session.json` without requiring prior setup.
+- Added clear blocked-state handling for malformed Hermes session phases instead of allowing low-level `jq` failures.
+- Added invalid JSON protection for Hermes session files so corrupted state is reported without being overwritten.
+- Expanded CLI `doctor` checks and tests to verify Hermes hooks and integration docs are packaged alongside OpenCode assets.
+- Aligned the exported analysis-tool type contract with the documented TypeScript, JavaScript, Python, Go, and Rust tool matrix.
+- Updated install documentation to cover Hermes verification and troubleshooting parity with OpenCode.
+
 ## v2.0.2
 
 - Added release-ready repository parity files: CI workflow, issue templates, PR template, security policy, contribution guide, and changelog.

package/CONTRIBUTING.md

@@ -34,6 +34,8 @@ npm pack --json --dry-run
 
 If a restore-mode change modifies behavior, verify it against a disposable repository or fixture and document the result.
 
+Before committing, pushing, or opening a PR, run a polish pass over the changed surface. Check wording, links, visuals, accessibility, package contents, and whether the repository presentation still looks complete.
+
 ## Documentation Expectations
 
 - Update `README.md`, `INSTALL.md`, `docs/`, or `wiki/` when installation, commands, workflow, safety, or release behavior changes.

package/INSTALL.md

@@ -1,21 +1,27 @@
 # Install Code Archaeology
 
-Code Archaeology is an OpenCode plugin for systematic codebase excavation. It is non-destructive by default: `survey` mode writes reports only, while `restore` mode modifies code after review and verification.
+Code Archaeology is a multi-runtime plugin for systematic codebase excavation. It is non-destructive by default: `survey` mode writes reports only, while `restore` mode modifies code after review and verification.
+
+## Runtimes
+
+- **OpenCode** — Interactive slash-command runtime (`/code-archaeology`)
+- **Hermes Agent** — Cron-based background runtime (one phase per 15-minute run)
 
 ## OpenCode Handoff
 
 Paste this into OpenCode if you want the agent to install and verify the plugin for you:
 
 ```text
-Fetch and follow instructions from https://raw.githubusercontent.com/Maleick/Code-Archaeology/refs/heads/main/INSTALL.md
+Run `npm pack opencode-code-archaeology@2.2.0`, extract the resulting tarball, then open and follow `package/INSTALL.md` from that tarball. If you need a concrete command sequence: `npm pack opencode-code-archaeology@2.2.0 && tar -xof opencode-code-archaeology-2.2.0.tgz && cat package/INSTALL.md`.
 ```
 
 ## Prerequisites
 
-- OpenCode installed and available in your shell.
-- Node.js with npm, or Bun if your OpenCode setup uses Bun package resolution.
+- Node.js with npm, or Bun if your setup uses Bun package resolution.
 - Git installed and available in your shell.
 - A target repository with tests or type checks available before you run `restore` mode.
+- For Hermes: Hermes Agent CLI or an active Hermes session.
+- **Windows**: PowerShell 5.1 or later (hooks use `.ps1` scripts on Windows).
 
 ## Recommended OpenCode Plugin Install
 
@@ -24,7 +30,7 @@ Add Code Archaeology to your `opencode.json` plugin array:
 ```json
 {
   "plugin": [
-    "opencode-code-archaeology@git+https://github.com/Maleick/Code-Archaeology.git"
+    "opencode-code-archaeology@2.2.0"
   ]
 }
 ```
@@ -38,12 +44,48 @@ Restart OpenCode after editing the configuration. The command family should then
 /code-archaeology-restore
 ```
 
+`/code-archaeology` runs the full 10-phase survey chain by default without per-phase prompts. It writes reports under `.archaeology/` and makes no source-code changes. Use `/code-archaeology-restore` only after reviewing the reports and deciding to apply changes.
+
+## Hermes Setup
+
+### 1. Install Code Archaeology CLI
+
+```bash
+npm install -g opencode-code-archaeology@2.2.0
+```
+
+### 2. Setup Hermes Runtime
+
+**macOS/Linux:**
+```bash
+cd ~/projects/Code-Archaeology
+bash hooks/hermes/setup.sh
+```
+
+**Windows:**
+```powershell
+cd ~/projects/Code-Archaeology
+.\hooks\hermes\setup.ps1
+```
+
+### 3. Create Hermes Cronjob
+
+```bash
+hermes cronjob create \
+  --name "code-archaeology-expedition" \
+  --schedule "every 15m" \
+  --workdir ~/projects/Code-Archaeology \
+  --prompt "Run one Code Archaeology expedition phase. Read .archaeology/session.json, execute current phase with verification, advance to next phase."
+```
+
+See `skills/hermes/INTEGRATION.md` for full Hermes integration details.
+
 ## npm Global Install
 
 If you prefer a global package install:
 
 ```bash
-npm install -g opencode-code-archaeology
+npm install -g opencode-code-archaeology@2.2.0
 opencode-code-archaeology install
 opencode-code-archaeology doctor
 opencode-code-archaeology version
@@ -52,7 +94,7 @@ opencode-code-archaeology version
 Then restart OpenCode and run:
 
 ```text
-/code-archaeology-survey
+/code-archaeology
 ```
 
 ## One-Time Bun Path
@@ -60,8 +102,8 @@ Then restart OpenCode and run:
 If your environment supports one-time package execution through Bun:
 
 ```bash
-bunx opencode-code-archaeology install
-bunx opencode-code-archaeology doctor
+bunx opencode-code-archaeology@2.2.0 install
+bunx opencode-code-archaeology@2.2.0 doctor
 ```
 
 Use the plugin-array install for normal OpenCode usage.
@@ -83,41 +125,68 @@ npm install
 npm run build
 npm run typecheck
 bash -n hooks/opencode/*.sh
+bash -n hooks/hermes/*.sh
+```
+
+**Windows:**
+```powershell
+npm install
+npm run build
+npm run typecheck
+Get-ChildItem hooks/opencode/*.ps1 | ForEach-Object { Get-Command $_.FullName }
+Get-ChildItem hooks/hermes/*.ps1 | ForEach-Object { Get-Command $_.FullName }
 ```
 
 To verify command availability, restart OpenCode in a Git repository and run:
 
 ```text
-/code-archaeology-survey
+/code-archaeology
 ```
 
-The survey should create `.archaeology/` reports without modifying source files.
+The default survey chain should create `.archaeology/` reports without modifying source files or asking to proceed phase by phase.
 
 ## Updating
 
-For plugin-array installs, update through your OpenCode package manager flow, then restart OpenCode. If your setup caches git plugins, clear the cached plugin package and let OpenCode reinstall it.
+For plugin-array installs, update by changing the package version to a reviewed npm release, then restart OpenCode. Do not point OpenCode at a mutable Git branch such as `main` for automatic updates.
 
 For npm global installs:
 
 ```bash
-npm install -g opencode-code-archaeology@latest
+npm install -g opencode-code-archaeology@2.2.0
 npm list -g opencode-code-archaeology --depth=0
 ```
 
 ## Troubleshooting
 
-### Plugin Not Loading
+### Plugin Not Loading (OpenCode)
 
 - Confirm `opencode.json` is valid JSON.
 - Confirm the plugin entry is in the top-level `plugin` array.
 - Restart OpenCode after changing the config.
-- Check that Git can reach `https://github.com/Maleick/Code-Archaeology.git`.
+- Check that npm can resolve the pinned `opencode-code-archaeology` release.
 
-### Commands Not Found
+### Commands Not Found (OpenCode)
 
 - Restart OpenCode so it reloads plugin commands.
 - Confirm the package installed successfully with `npm list -g opencode-code-archaeology --depth=0` if using the global path.
-- Run `/code-archaeology-survey` from inside a Git repository, not from an empty directory.
+- Run `/code-archaeology` from inside a Git repository, not from an empty directory.
+
+### Cron Not Running (Hermes)
+
+```bash
+hermes cronjob list
+hermes cronjob log code-archaeology-expedition
+```
+
+### Phase Blocked (Hermes)
+
+```bash
+# Check blocker
+cat .archaeology/session.json | jq '.flags.blocked_reason'
+
+# Reset and retry
+jq '.status = "running" | del(.flags.blocked_reason)' .archaeology/session.json > tmp.json && mv tmp.json .archaeology/session.json
+```
 
 ### Stale Cache
 
@@ -127,10 +196,10 @@ npm list -g opencode-code-archaeology --depth=0
 
 ### Restore Safety
 
-- Start with `/code-archaeology-survey`; it writes reports only.
+- Start with `/code-archaeology` (OpenCode) or `mode = "survey"` (Hermes); it writes reports only.
 - Review `.archaeology/site_survey.md` and expedition reports before restore.
-- Use `/code-archaeology-excavate` for mock patches if you want another review gate.
-- Run `/code-archaeology-restore` only when the target repository has tests or type checks available.
+- Use `/code-archaeology-excavate` (OpenCode) or `mode = "excavate"` (Hermes) for mock patches if you want another review gate.
+- Run `/code-archaeology-restore` (OpenCode) or `mode = "restore"` (Hermes) only when the target repository has tests or type checks available.
 - Do not commit `.archaeology/`; it is local runtime state.
 
 ## Links
@@ -139,3 +208,4 @@ npm list -g opencode-code-archaeology --depth=0
 - Wiki: https://github.com/Maleick/Code-Archaeology/wiki
 - Releases: https://github.com/Maleick/Code-Archaeology/releases
 - Issues: https://github.com/Maleick/Code-Archaeology/issues
+- Hermes docs: https://hermes-agent.nousresearch.com/docs