opencode-code-archaeology 2.0.2 → 2.2.1

package/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Code Archaeology Architecture
 
-Code Archaeology is an OpenCode plugin that operates entirely inside the target repository. It coordinates slash commands, a domain skill, shell hooks, prompts, schemas, and local `.archaeology/` artifacts to run a fixed excavation workflow.
+Code Archaeology is a multi-runtime plugin that operates entirely inside the target repository. It coordinates slash commands (OpenCode), cron-based execution (Hermes), a domain skill, shell hooks, prompts, schemas, and local `.archaeology/` artifacts to run a fixed excavation workflow.
 
 ## Repository Layout
 
@@ -11,39 +11,56 @@ Code-Archaeology/
 |-- dist/               # Built package output for GitHub-based installs
 |-- docs/               # Public documentation and release notes
 |-- hooks/opencode/     # Init, verification, revert, and status hooks
-|-- plugins/            # OpenCode plugin entry point
+|-- hooks/hermes/       # Setup and runner hooks for Hermes Agent
+|-- plugins/            # Repo-local legacy plugin shim
 |-- prompts/            # Expedition prompts by phase
 |-- schema/             # JSON schemas for reports
-|-- skills/             # Code Archaeology skill definition
+|-- skills/             # Code Archaeology skill definitions
+|   |-- code-archaeology/   # OpenCode skill
+|   `-- hermes/             # Hermes Agent skill and integration docs
 |-- src/                # TypeScript package and CLI source
 |-- wiki/               # Source pages for GitHub Wiki publication
 |-- INSTALL.md          # Root install handoff
 |-- README.md           # Public project overview
-`-- AGENTS.md           # Agent runtime guide
+|-- AGENTS.md           # Agent runtime guide
 ```
 
-## OpenCode Plugin Surfaces
+## Runtime Surfaces
 
-- `plugins/` exposes the plugin entry point consumed by OpenCode.
-- `commands/` defines the slash command family: `/code-archaeology`, `/code-archaeology-survey`, `/code-archaeology-excavate`, and `/code-archaeology-restore`.
-- `skills/` contains the domain workflow instructions agents follow during an expedition.
+### OpenCode Plugin Surfaces
+
+- `dist/index.js` and the `./plugin` package export expose the plugin entry point consumed by OpenCode. `plugins/` is a repo-local legacy shim and is not included in npm package contents.
+- `commands/` defines the slash command family: `/code-archaeology`, `/code-archaeology-survey`, `/code-archaeology-excavate`, and `/code-archaeology-restore`. The default `/code-archaeology` command runs the full survey chain without per-phase prompts and remains non-destructive.
+- `skills/code-archaeology/` contains the domain workflow instructions agents follow during an expedition.
 - `hooks/opencode/` provides shell gates for session setup, verification, rollback, and status updates.
 - `prompts/` and `schema/` provide phase-specific guidance and artifact structure.
 - `src/` builds the npm package and CLI used by `opencode-code-archaeology install`, `doctor`, and `version`.
 
+### Hermes Agent Surfaces
+
+- `hooks/hermes/setup.sh` detects Hermes capabilities and writes `hermes-runtime.json`.
+- `hooks/hermes/runner.sh` executes one expedition phase per cron run with built-in verification.
+- `skills/hermes/` contains the Hermes-specific skill prompt, integration guide, and README.
+- Hermes uses the same `.archaeology/session.json` state file as OpenCode.
+
 ## Commands, Skills, And Hooks
 
-Commands are the user-facing entry points. A command selects the mode and starts the archaeology workflow in the target repository.
+Commands are the user-facing entry points. `/code-archaeology` selects survey mode by default and runs all 10 phases to produce reports. The explicit restore command is required before source files are changed.
 
 The Code Archaeology skill defines the expedition order, safety constraints, language-tool preferences, and reporting expectations. It is the agent-facing control layer that prevents phases from running out of order.
 
 Hooks are the shell-level enforcement layer:
 
+### OpenCode hooks
 - `init.sh` initializes `.archaeology/` and session state.
 - `verify-phase.sh <phase>` runs configured tests and type checks between phases.
 - `revert-phase.sh <phase>` reverts changes when a restore phase fails verification.
 - `update-expedition.sh <phase> <status> [findings]` updates session progress.
 
+### Hermes hooks
+- `setup.sh` detects Hermes CLI / active session and writes runtime config.
+- `runner.sh` reads session state, executes one phase, verifies, and advances.
+
 ## Expedition Flow
 
 The phase order is fixed because later cleanup depends on earlier evidence:
@@ -61,6 +78,18 @@ The phase order is fixed because later cleanup depends on earlier evidence:
 
 `survey` mode writes reports only. `excavate` mode writes reports plus mock patches. `restore` mode applies approved changes and must pass verification between phases.
 
+## Runtime Comparison
+
+| Feature | OpenCode | Hermes |
+|---------|----------|--------|
+| Entry | `/code-archaeology` slash command | `cronjob` |
+| Phases | All in one session | One per cron run |
+| Verification | Between expeditions | Between every phase |
+| Revert | Manual or automatic | Automatic on failure |
+| State | `.archaeology/session.json` | Same file |
+| Background | Plugin stays active | Cron resumes automatically |
+| Real-time | Yes | Delayed (15-min intervals) |
+
 ## Artifact Lifecycle
 
 Runtime artifacts live in `.archaeology/` inside the target repository:
@@ -73,6 +102,7 @@ Runtime artifacts live in `.archaeology/` inside the target repository:
 | `FINAL_CATALOG.md` | Final excavation summary and recommendations. |
 | `excavation_log.txt` | `git diff --stat` for applied restoration work. |
 | `patches/` | Mock patches generated by `excavate` mode. |
+| `hermes-runtime.json` | Hermes runtime configuration (Hermes only). |
 
 `.archaeology/` is ignored local state and should not be committed.
 
@@ -83,7 +113,8 @@ Runtime artifacts live in `.archaeology/` inside the target repository:
 - Never consolidate types before dead code and legacy removal.
 - Never remove try/catch blocks from I/O or external input boundaries automatically.
 - Flag uncertain type replacements for human review instead of guessing.
-- Run `verify-phase.sh` between restore phases.
+- Run `verify-phase.sh` between restore phases (OpenCode).
+- Run built-in verification in `runner.sh` between phases (Hermes).
 - Run `revert-phase.sh` and stop if a phase introduces test failures.
 - Keep restore work isolated to the configured branch, `refactor/archaeology` by default.
 

package/docs/INSTALL.md

@@ -1,6 +1,6 @@
 # Install Code Archaeology
 
-This guide mirrors the root [`INSTALL.md`](../INSTALL.md) and covers the recommended OpenCode plugin configuration plus the npm CLI install path.
+This guide mirrors the root [`INSTALL.md`](../INSTALL.md) and covers the recommended OpenCode plugin configuration, npm CLI install path, and Hermes Agent setup.
 
 ## Prerequisites
 
@@ -8,6 +8,7 @@ This guide mirrors the root [`INSTALL.md`](../INSTALL.md) and covers the recomme
 - Node.js 18 or newer with npm.
 - Git installed and available in your shell.
 - A target repository with tests or type checks before running `restore` mode.
+- For Hermes: Hermes Agent CLI or an active Hermes session.
 
 ## Recommended OpenCode Plugin Install
 
@@ -16,7 +17,7 @@ Add Code Archaeology to the top-level `plugin` array in `opencode.json`:
 ```json
 {
   "plugin": [
-    "opencode-code-archaeology@git+https://github.com/Maleick/Code-Archaeology.git"
+    "opencode-code-archaeology@2.2.0"
   ]
 }
 ```
@@ -30,12 +31,14 @@ 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.
+
 ## npm Global Install
 
 Use the npm package when you want the CLI installer and diagnostics:
 
 ```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
@@ -44,9 +47,31 @@ opencode-code-archaeology version
 Then restart OpenCode and run:
 
 ```text
-/code-archaeology-survey
+/code-archaeology
+```
+
+## Hermes Setup
+
+Install the CLI globally so Hermes can invoke Code Archaeology commands. To initialize Hermes runtime metadata, run the hook from a local clone or from the unpacked package contents:
+
+```bash
+npm install -g opencode-code-archaeology@2.2.0
+cd ~/projects/Code-Archaeology
+bash hooks/hermes/setup.sh
+```
+
+Create a cronjob that runs exactly one expedition phase per invocation:
+
+```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`](../skills/hermes/INTEGRATION.md) for the full Hermes workflow.
+
 ## Verification
 
 Confirm the published package and local CLI are visible:
@@ -65,24 +90,25 @@ npm install
 npm run build
 npm run typecheck
 bash -n hooks/opencode/*.sh
+bash -n hooks/hermes/*.sh
 ```
 
 To verify plugin behavior, 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 `opencode-code-archaeology` 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
 opencode-code-archaeology doctor
 ```
@@ -94,13 +120,26 @@ opencode-code-archaeology doctor
 - Confirm `opencode.json` is valid JSON.
 - Confirm the package entry is in the top-level `plugin` array, not `plugins`.
 - Restart OpenCode after changing configuration.
-- Confirm Git can reach `https://github.com/Maleick/Code-Archaeology.git`.
+- Confirm npm can resolve the pinned `opencode-code-archaeology` release.
 
 ### Commands Not Found
 
 - Restart OpenCode so it reloads plugin commands.
 - Confirm the npm package installed with `npm list -g opencode-code-archaeology --depth=0` if using the global path.
-- Run `/code-archaeology-survey` from inside a Git repository.
+- Run `/code-archaeology` from inside a Git repository.
+
+### Cron Not Running
+
+```bash
+hermes cronjob list
+hermes cronjob log code-archaeology-expedition
+```
+
+### Phase Blocked
+
+```bash
+cat .archaeology/session.json | jq '.flags.blocked_reason'
+```
 
 ### Stale Cache
 
@@ -110,7 +149,7 @@ opencode-code-archaeology doctor
 
 ### Restore Safety
 
-- Start with `/code-archaeology-survey`; it writes reports only.
+- Start with `/code-archaeology`; 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.

package/docs/README.md

@@ -1,8 +1,10 @@
 # Code Archaeology Documentation
 
-Code Archaeology is an OpenCode plugin for systematic codebase excavation, cataloging, and restoration. It runs inside the target repository, writes local `.archaeology/` reports, and only modifies source files in `restore` mode after review and verification.
+Excavate technical debt. Restore with confidence.
 
-These Markdown files are ready to serve from GitHub Pages, but this repository does not assume Pages is already enabled.
+Code Archaeology is a multi-runtime plugin for systematic codebase excavation, cataloging, and restoration. It supports both **OpenCode** (interactive slash commands) and **Hermes Agent** (cron-based background execution). It runs inside the target repository, writes local `.archaeology/` reports, and only modifies source files in `restore` mode after review and verification.
+
+The public landing page is [`index.html`](index.html). These Markdown files remain the detailed documentation source.
 
 ## Quick Links
 
@@ -12,24 +14,33 @@ These Markdown files are ready to serve from GitHub Pages, but this repository d
 - [Security Audit](SECURITY_AUDIT.md)
 - [Repository README](../README.md)
 - [Root Install Handoff](../INSTALL.md)
+- [Hermes Integration](../skills/hermes/INTEGRATION.md)
+- [Hermes Skill](../skills/hermes/README.md)
 
 ## Quick Start
 
+### OpenCode
+
 Install the package globally, register the plugin, then verify the CLI:
 
 ```bash
-npm install -g opencode-code-archaeology
-opencode-code-archaeology install
-opencode-code-archaeology doctor
-opencode-code-archaeology version
+npm install -g opencode-code-archaeology@2.2.0 && opencode-code-archaeology install && opencode-code-archaeology doctor
 ```
 
-Restart OpenCode in the repository you want to inspect and start with the non-destructive survey command:
+Or tell OpenCode:
 
 ```text
-/code-archaeology-survey
+Fetch and follow the instructions in the installed package's INSTALL.md at $(npm root -g)/opencode-code-archaeology/INSTALL.md for opencode-code-archaeology@2.2.0
 ```
 
+Restart OpenCode in the repository you want to inspect and start with the non-destructive default command:
+
+```text
+/code-archaeology
+```
+
+This runs the full 10-phase survey chain without per-phase prompts, writes reports under `.archaeology/`, and makes no source-code changes.
+
 Review `.archaeology/site_survey.md` and expedition reports before using:
 
 ```text
@@ -37,8 +48,25 @@ Review `.archaeology/site_survey.md` and expedition reports before using:
 /code-archaeology-restore
 ```
 
+### Hermes Agent
+
+Setup the Hermes runtime and create a cronjob:
+
+```bash
+cd ~/projects/Code-Archaeology
+bash hooks/hermes/setup.sh
+
+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 test/typecheck verification, advance to next phase. STOP after one phase."
+```
+
+Each cron run executes exactly **one** phase. Ten phases complete in ~2.5 hours minimum.
+
 ## Safety Warning
 
-`survey` mode writes reports only. `excavate` mode writes reports and mock patches. `restore` mode can edit source files and should only run after report review, on an isolated branch, with tests or type checks available.
+`/code-archaeology` defaults to survey mode and writes reports only. `excavate` mode writes reports and mock patches. `restore` mode can edit source files and should only run after report review, on an isolated branch, with tests or type checks available.
 
 Do not commit `.archaeology/`; it is local runtime state.

package/docs/RELEASE.md

@@ -1,6 +1,6 @@
 # Release Process
 
-This checklist is for future `opencode-code-archaeology` releases. `v2.0.2` is the current release example; replace it with the next version when preparing a new release.
+This checklist is for future `opencode-code-archaeology` releases. `v2.2.0` is the current release example; replace it with the next version when preparing a new release.
 
 ## 1. Preflight
 
@@ -12,23 +12,23 @@ This checklist is for future `opencode-code-archaeology` releases. `v2.0.2` is t
 
 ## 2. Version Bump
 
-For a future release, replace `2.0.2` with the target version:
+For a future release, replace `2.2.0` with the target version:
 
 ```bash
-npm version 2.0.2 --no-git-tag-version
+npm version 2.2.0 --no-git-tag-version
 ```
 
 Update `VERSION` to the same value:
 
 ```text
-2.0.2
+2.2.0
 ```
 
 Confirm `package.json`, `package-lock.json`, and `VERSION` agree.
 
 ## 3. Changelog
 
-- Add a `v2.0.2` entry, or the future target version, to `CHANGELOG.md`.
+- Add a `v2.2.0` entry, or the future target version, to `CHANGELOG.md`.
 - Include user-visible changes, safety notes, and any migration instructions.
 - Keep the release notes factual and avoid claiming publication steps that have not happened yet.
 
@@ -43,6 +43,7 @@ npm run typecheck
 npm audit --audit-level=moderate
 npm outdated --json
 bash -n hooks/opencode/*.sh
+bash -n hooks/hermes/*.sh
 npm pack --json --dry-run
 ```
 
@@ -51,7 +52,7 @@ Expected outcomes:
 - Build and typecheck pass.
 - npm audit reports no moderate-or-higher vulnerabilities.
 - npm outdated reports `{}` or no actionable outdated dependencies.
-- Shell hooks pass syntax checks.
+- Shell hooks pass syntax checks (both OpenCode and Hermes).
 - The package dry run includes required files.
 
 ## 5. npm Pack Required Files
@@ -63,7 +64,6 @@ Inspect `npm pack --json --dry-run` output for the package contents. Required fi
 - `hooks/`
 - `commands/`
 - `skills/`
-- `plugins/`
 - `schema/`
 - `prompts/`
 - `docs/`
@@ -77,6 +77,8 @@ Inspect `npm pack --json --dry-run` output for the package contents. Required fi
 - `SECURITY.md`
 - `LICENSE`
 
+`plugins/` is intentionally repo-local and should not appear in npm package contents.
+
 If any required file is missing, update the `files` array in `package.json`, rerun `npm install` if the lockfile needs to change, and repeat the package dry run.
 
 ## 6. Commit, Tag, And Push
@@ -86,10 +88,10 @@ Only perform these steps after verification passes and after confirming the bran
 ```bash
 git status --short
 git add README.md INSTALL.md docs wiki assets .github SECURITY.md CONTRIBUTING.md CHANGELOG.md package.json package-lock.json VERSION .gitignore
-git commit -m "chore: prepare v2.0.2 release"
-git tag v2.0.2
+git commit -m "chore: prepare v2.2.0 release"
+git tag v2.2.0
 git push origin HEAD
-git push origin v2.0.2
+git push origin v2.2.0
 ```
 
 For a future release, use the future version in the commit message and tag.
@@ -99,18 +101,20 @@ For a future release, use the future version in the commit message and tag.
 Create the GitHub release from the matching tag:
 
 ```bash
-gh release create v2.0.2 --title "v2.0.2" --notes-file CHANGELOG.md
+gh release create v2.2.0 --title "v2.2.0" --notes-file CHANGELOG.md
 ```
 
 Before publishing, trim the notes to the specific version section if `CHANGELOG.md` contains multiple releases.
 
 ## 8. npm Publish
 
-Publish only after the GitHub tag and release are correct:
+Publishing is performed by `.github/workflows/release.yml` through npm trusted publishing. Configure npm Trusted Publisher with:
 
-```bash
-npm publish --access public
-```
+- Publisher: `GitHub Actions`
+- Organization or user: `Maleick`
+- Repository: `Code-Archaeology`
+- Workflow filename: `release.yml`
+- Environment name: leave blank unless the workflow adds a GitHub Actions `environment`
 
 If publishing fails, do not create a replacement tag unless the failure requires a new package version. Fix the issue, rerun verification, and follow npm versioning rules.
 
@@ -121,7 +125,7 @@ Confirm the public release surfaces report the expected version:
 ```bash
 npm view opencode-code-archaeology version
 npm view opencode-code-archaeology dist-tags
-gh release view v2.0.2
+gh release view v2.2.0
 ```
 
 Optionally verify a fresh install path: