opencode-code-archaeology 2.0.2 → 2.2.1

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.2.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.2.0 --no-git-tag-version`.
+3. Update `VERSION` to `2.2.0`.
 4. Update `CHANGELOG.md` with release notes.
 5. Run verification:
 
@@ -22,10 +22,10 @@ bash -n hooks/opencode/*.sh
 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.
+6. Confirm the package dry run includes `dist`, `assets`, `hooks`, `commands`, `skills`, `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.2.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.2.0` show the expected release.
 
 Do not claim GitHub Pages is enabled unless repository settings confirm it.

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,63 +0,0 @@
-name: Bug report
-description: Report a problem with the Code Archaeology OpenCode plugin.
-title: "bug: "
-labels:
-  - bug
-body:
-  - type: markdown
-    attributes:
-      value: Thanks for helping improve Code Archaeology. Do not include secrets, private code, or full `.archaeology/` state.
-  - type: textarea
-    id: summary
-    attributes:
-      label: Summary
-      description: What went wrong?
-    validations:
-      required: true
-  - type: dropdown
-    id: mode
-    attributes:
-      label: Mode
-      options:
-        - survey
-        - excavate
-        - restore
-        - install or CLI
-        - documentation
-        - other
-    validations:
-      required: true
-  - type: input
-    id: version
-    attributes:
-      label: Version
-      description: Package version, commit SHA, or install source.
-      placeholder: v2.0.2
-  - type: textarea
-    id: steps
-    attributes:
-      label: Steps to reproduce
-      placeholder: |
-        1. Run ...
-        2. See ...
-    validations:
-      required: true
-  - type: textarea
-    id: expected
-    attributes:
-      label: Expected behavior
-    validations:
-      required: true
-  - type: textarea
-    id: actual
-    attributes:
-      label: Actual behavior
-      description: Include sanitized logs or error output when useful.
-    validations:
-      required: true
-  - type: textarea
-    id: environment
-    attributes:
-      label: Environment
-      description: OS, Node version, OpenCode version, package manager, and target language.
-      placeholder: macOS 14, Node 20, OpenCode ..., npm ..., TypeScript

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,48 +0,0 @@
-name: Feature request
-description: Suggest an improvement for the Code Archaeology OpenCode plugin.
-title: "feat: "
-labels:
-  - enhancement
-body:
-  - type: markdown
-    attributes:
-      value: Please focus on the user workflow and safety impact. Do not include private repository contents.
-  - type: textarea
-    id: problem
-    attributes:
-      label: Problem
-      description: What workflow or limitation should this improve?
-    validations:
-      required: true
-  - type: textarea
-    id: proposal
-    attributes:
-      label: Proposed solution
-      description: What should Code Archaeology do differently?
-    validations:
-      required: true
-  - type: dropdown
-    id: area
-    attributes:
-      label: Area
-      options:
-        - survey reporting
-        - excavate mock patches
-        - restore safety
-        - language support
-        - CLI or install
-        - documentation
-        - CI or release
-        - other
-    validations:
-      required: true
-  - type: textarea
-    id: alternatives
-    attributes:
-      label: Alternatives considered
-      description: Any workaround or simpler approach?
-  - type: textarea
-    id: safety
-    attributes:
-      label: Safety considerations
-      description: Could this modify user code, expose local state, or affect restore behavior?

package/.github/pull_request_template.md

@@ -1,26 +0,0 @@
-## Summary
-
-- 
-
-## Verification
-
-- [ ] `npm run build`
-- [ ] `npm run typecheck`
-- [ ] `npm test`
-- [ ] `npm audit --audit-level=moderate`
-- [ ] `bash -n hooks/opencode/*.sh`
-- [ ] `npm pack --json --dry-run`
-
-## Safety Checklist
-
-- [ ] I did not commit `.archaeology/`, `.superpowers/`, secrets, logs, or local editor state.
-- [ ] Restore-mode changes are backed by reviewed survey or excavate output.
-- [ ] I did not remove try/catch around I/O or external input boundaries.
-- [ ] I flagged uncertain type or behavior changes for review instead of guessing.
-
-## Docs And Release Checklist
-
-- [ ] README, INSTALL, docs, and wiki source are updated if user behavior changed.
-- [ ] CHANGELOG includes user-visible changes.
-- [ ] Package metadata and npm package contents are correct for release-impacting changes.
-- [ ] Version, tag, publish, and release steps are not included unless this PR is the release PR.

package/.github/workflows/ci.yml

@@ -1,45 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-
-jobs:
-  verify:
-    name: Verify
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: npm
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Typecheck
-        run: npm run typecheck
-
-      - name: Test
-        run: npm test
-
-      - name: Audit dependencies
-        run: npm audit --audit-level=moderate
-
-      - name: Check shell hook syntax
-        run: bash -n hooks/opencode/*.sh
-
-      - name: Validate npm package contents
-        run: npm pack --json --dry-run

package/plugins/code-archaeology.ts

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