opencode-code-archaeology 2.0.2 → 2.2.0

package/skills/hermes/code-archaeology-prompt.md

@@ -0,0 +1,203 @@
+---
+name: code-archaeology-hermes
+description: Code Archaeology expedition runner for Hermes Agent — systematic codebase excavation with test-gated phases.
+trigger: When running Code Archaeology on Hermes Agent via cronjob.
+---
+
+# Code Archaeology Hermes Skill
+
+## One Phase Per Cron Run
+
+Each cron run executes exactly ONE expedition phase. Do not combine phases.
+
+## Phase Detection (run FIRST)
+
+```bash
+cd {{workdir}}
+if [ -f .archaeology/session.json ]; then
+  phase=$(jq -r '.current_phase' .archaeology/session.json)
+  mode=$(jq -r '.mode' .archaeology/session.json)
+  status=$(jq -r '.status' .archaeology/session.json)
+else
+  phase="site-survey"
+  mode="survey"
+  status="running"
+fi
+```
+
+**Decision tree:**
+- `status` = "complete" → **STOP** (all phases done)
+- `status` = "blocked" → **STOP** (report blocker)
+- `phase` = "site-survey" → **Phase 1**
+- `phase` = "dead-code" → **Phase 2**
+- `phase` = "legacy-removal" → **Phase 3**
+- `phase` = "dependency-mapping" → **Phase 4**
+- `phase` = "type-consolidation" → **Phase 5**
+- `phase` = "type-hardening" → **Phase 6**
+- `phase` = "dry-stratification" → **Phase 7**
+- `phase` = "error-handling" → **Phase 8**
+- `phase` = "artifact-cleaning" → **Phase 9**
+- `phase` = "final-catalog" → **Phase 10**
+
+## Expedition Phases
+
+### Phase 1: Site Survey & Baseline
+
+1. Create `.archaeology/` directory if missing
+2. Generate `site_survey.md` — baseline inventory of codebase
+3. Record: file count, language distribution, test coverage, dependencies
+4. **No code changes**
+
+**STOP after survey.** Next run: Phase 2.
+
+### Phase 2: Dead Code Excavation
+
+1. Catalog dead code, unused exports, unreachable functions
+2. Generate `expedition2-report.md` with findings
+3. **Mode = survey**: reports only
+4. **Mode = restore**: remove dead code (test-gated)
+
+**STOP after catalog.** Next run: Phase 3.
+
+### Phase 3: Legacy Stratum Removal
+
+1. Identify legacy fallbacks, deprecated shims, compatibility layers
+2. Generate `expedition3-report.md`
+3. **Never remove try/catch from I/O boundaries**
+4. **Mode = restore**: remove approved legacy code (test-gated)
+
+**STOP after identification.** Next run: Phase 4.
+
+### Phase 4: Circular Dependency Cartography
+
+1. Map circular dependencies using language-specific tools
+2. Generate `expedition4-report.md` with dependency graph
+3. **No code changes** (mapping only)
+
+**STOP after mapping.** Next run: Phase 5.
+
+### Phase 5: Type Catalog Consolidation
+
+1. Find duplicate type definitions
+2. Generate `expedition5-report.md`
+3. **Only run AFTER dead code and legacy removal**
+4. **Mode = restore**: consolidate types (test-gated)
+
+**STOP after catalog.** Next run: Phase 6.
+
+### Phase 6: Type Restoration & Hardening
+
+1. Identify weak types without guessing replacements
+2. Generate `expedition6-report.md`
+3. Flag uncertain replacements for human review
+4. **Mode = restore**: harden approved types (test-gated)
+
+**STOP after identification.** Next run: Phase 7.
+
+### Phase 7: DRY Stratification
+
+1. Find semantic duplication and error-handling slop
+2. Generate `expedition7-report.md`
+3. **Preserve I/O boundaries**
+4. **Mode = restore**: DRY approved code (test-gated)
+
+**STOP after analysis.** Next run: Phase 8.
+
+### Phase 8: Error Handling Stratigraphy
+
+1. Review error-handling patterns
+2. Generate `expedition8-report.md`
+3. **Never remove try/catch from I/O or external input boundaries**
+4. **Mode = restore**: improve approved error handling (test-gated)
+
+**STOP after review.** Next run: Phase 9.
+
+### Phase 9: Artifact Cleaning & Documentation
+
+1. Identify stale artifacts and documentation gaps
+2. Generate `expedition9-report.md`
+3. Clean approved artifacts (test-gated)
+
+**STOP after cleaning.** Next run: Phase 10.
+
+### Phase 10: Site Preservation & Final Catalog
+
+1. Generate `FINAL_CATALOG.md` — complete excavation summary
+2. Run final verification (all tests + typecheck)
+3. Update session.json: `status = "complete"`
+
+**STOP. Expedition complete.**
+
+## Verification (between phases)
+
+```bash
+# Pre-phase: ensure clean state
+{{test_command}}
+{{typecheck_command}}
+
+# Post-phase (restore mode only): verify changes
+{{test_command}}
+{{typecheck_command}}
+```
+
+**If verification fails:**
+1. Revert changes: `git reset --hard HEAD`
+2. Update session: `status = "blocked"`, `blocked_reason = "..."`
+3. Report blocker and STOP
+
+## Mode Behavior
+
+| Mode | Action | File Changes? |
+|------|--------|---------------|
+| **survey** | Generate reports only | None outside `.archaeology/` |
+| **excavate** | Reports + mock patches | None outside `.archaeology/patches/` |
+| **restore** | Apply approved changes | Yes, test-gated |
+
+## Rules
+
+- **One phase per cron run** — never combine
+- **Fixed order** — never skip phases
+- **Survey first** — always generate reports before changes
+- **Test gates** — run tests between every phase
+- **Auto-revert** — revert on any verification failure
+- **Preserve I/O** — never remove try/catch from boundaries
+- **No guessing** — flag uncertain types for human review
+- **Use [SILENT]** for no-op phases
+
+## Context Variables
+
+| Variable | Source |
+|----------|--------|
+| `{{workdir}}` | Cronjob `workdir` setting |
+| `{{mode}}` | session.json (survey/excavate/restore) |
+| `{{test_command}}` | session.json |
+| `{{typecheck_command}}` | session.json |
+| `{{branch_name}}` | session.json (default: refactor/archaeology) |
+| `{{language}}` | session.json (default: typescript) |
+
+## Language Tool Mapping
+
+| Language | Dead Code | Dependencies | Types | DRY |
+|----------|-----------|--------------|-------|-----|
+| TypeScript | `knip` | `madge` | `tsc` | `jscpd` |
+| JavaScript | `knip` | `madge` | N/A | `jscpd` |
+| Python | `vulture` | `pydeps` | `mypy` | `pylint` |
+| Go | `deadcode` | `godepgraph` | `go vet` | `golangci-lint` |
+| Rust | `cargo-udeps` | `cargo-deps` | `rustc` | `clippy` |
+
+## STOP Conditions
+
+- All 10 phases complete
+- Verification fails (blocked)
+- `stop_requested` flag set
+- Human review required (strict mode findings)
+
+## Next Steps After Complete
+
+1. Review `.archaeology/FINAL_CATALOG.md`
+2. Review all `expedition*-report.md` files
+3. Apply mock patches from `.archaeology/patches/` if in excavate mode
+4. Merge `refactor/archaeology` branch if in restore mode
+5. Archive `.archaeology/` directory
+
+**Start by detecting phase from session.json. Execute exactly ONE phase with verification. STOP.**

package/wiki/Expedition-Workflow.md

@@ -2,7 +2,7 @@
 
 [Home](Home) | [Installation](Installation) | [Security](Security-and-Safety) | [Release](Release-Process)
 
-Code Archaeology runs phases in a fixed order so later changes are based on earlier evidence.
+Code Archaeology runs phases in a fixed order so later changes are based on earlier evidence. In OpenCode, `/code-archaeology` runs the full 10-phase survey chain by default without per-phase prompts.
 
 1. Site Survey & Baseline
 2. Dead Code Excavation
@@ -23,6 +23,8 @@ Code Archaeology runs phases in a fixed order so later changes are based on earl
 | `excavate` | Reports plus mock patches in `.archaeology/patches/`. |
 | `restore` | Applies approved changes with verification gates. |
 
+Use `/code-archaeology-restore` explicitly when you are ready to apply changes. The default `/code-archaeology` command remains survey-only and writes reports under `.archaeology/`.
+
 ## Local Artifacts
 
 `.archaeology/` contains `session.json`, `site_survey.md`, expedition reports, `FINAL_CATALOG.md`, `excavation_log.txt`, and optional mock patches. It is local runtime state and should not be committed.

package/wiki/Home.md

@@ -21,7 +21,7 @@ opencode-code-archaeology version
 Restart OpenCode inside a Git repository and run:
 
 ```text
-/code-archaeology-survey
+/code-archaeology
 ```
 
-Start with `survey`, review reports, then choose `excavate` for mock patches or `restore` for approved, test-gated changes.
+`/code-archaeology` runs the full 10-phase survey chain without per-phase prompts, writes `.archaeology/` reports only, and makes no source-code changes. Review reports, then choose `excavate` for mock patches or `restore` for approved, test-gated changes.

package/wiki/Installation.md

@@ -23,6 +23,8 @@ Restart OpenCode. Commands should be available inside a Git repository:
 /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 CLI Path
 
 ```bash

package/wiki/Release-Process.md

@@ -2,13 +2,13 @@
 
 [Home](Home) | [Installation](Installation) | [Workflow](Expedition-Workflow) | [Security](Security-and-Safety)
 
-Use this checklist for future `opencode-code-archaeology` releases. `v2.0.2` is the current example version; replace it with the target version.
+Use this checklist for future `opencode-code-archaeology` releases. `v2.1.0` is the current example version; replace it with the target version.
 
 ## Checklist
 
 1. Review the worktree for unrelated changes and local state.
-2. Bump package files with `npm version 2.0.2 --no-git-tag-version`.
-3. Update `VERSION` to `2.0.2`.
+2. Bump package files with `npm version 2.1.0 --no-git-tag-version`.
+3. Update `VERSION` to `2.1.0`.
 4. Update `CHANGELOG.md` with release notes.
 5. Run verification:
 
@@ -23,9 +23,9 @@ npm pack --json --dry-run
 ```
 
 6. Confirm the package dry run includes `dist`, `assets`, `hooks`, `commands`, `skills`, `plugins`, `schema`, `prompts`, `docs`, `wiki`, `README.md`, `INSTALL.md`, `CHANGELOG.md`, `SECURITY.md`, `CONTRIBUTING.md`, `VERSION`, `AGENTS.md`, and `LICENSE`.
-7. Commit release files, tag `v2.0.2`, push the branch, and push the tag.
+7. Commit release files, tag `v2.1.0`, push the branch, and push the tag.
 8. Create the GitHub release from the tag.
 9. Publish npm with `npm publish --access public`.
-10. Confirm `npm view opencode-code-archaeology version` and `gh release view v2.0.2` show the expected release.
+10. Confirm `npm view opencode-code-archaeology version` and `gh release view v2.1.0` show the expected release.
 
 Do not claim GitHub Pages is enabled unless repository settings confirm it.

package/plugins/code-archaeology.ts

@@ -1,8 +0,0 @@
-export {
-  id,
-  repoRoot,
-  version,
-  server,
-} from "../src/index.ts";
-
-export type * from "../src/types";