opencode-code-archaeology 2.0.0 → 2.0.2

package/prompts/errors.md

@@ -0,0 +1,52 @@
+# Expedition 7: Error Handling Stratigraphy
+
+## Objective
+Identify and catalog problematic error handling patterns: suppressed errors, empty catch blocks, overly broad try/catch, and error swallowing.
+
+## Instructions
+
+1. **Pattern Search**
+   Search for these anti-patterns:
+   - Empty or console-only catch blocks
+   - `catch (e) { return null; }` or similar suppression
+   - `try/catch` around non-throwing code (defensive overprogramming)
+   - Broad exception types when specific ones are available
+   - `suppress`, `silence`, `safe`, `onError` in function names (often indicate error hiding)
+   - Ignored Promise rejections (`.catch(() => {})`)
+
+2. **Context Analysis**
+   For each finding:
+   - Determine if the suppression is intentional (expected failure case)
+   - Identify what error information is being lost
+   - Assess if the error should propagate to a higher handler
+   - Check if logging/monitoring is adequate
+
+3. **Boundary Classification**
+   - I/O boundary: File system, network, external API calls (legitimate try/catch)
+   - Internal boundary: Business logic, pure functions (suspicious suppression)
+   - User input boundary: Form validation, CLI arguments (may need specific handling)
+
+## Output
+
+Write to `.archaeology/expedition7-report.md`:
+- Inventory of all error handling issues with locations
+- Classification by anti-pattern type
+- Risk assessment (data loss, silent failures, debugging difficulty)
+- Recommended fix for each issue
+- Boundary classification for each finding
+
+## Execution Rules
+- If `mode == survey`: catalog only
+- If `mode == excavate`: generate fix proposals
+- If `mode == restore`:
+  - Remove error hiding from internal boundaries
+  - Add proper logging or propagation
+  - NEVER remove try/catch from I/O or external input boundaries
+  - Run tests after each change
+
+## Constraints
+- NEVER remove try/catch from I/O operations (file read, network request, DB query)
+- NEVER remove try/catch from external API boundaries
+- ALWAYS preserve error information—replace suppression with logging or re-throwing
+- NEVER let errors propagate unhandled—replace with explicit error handling
+- ALWAYS consider if the catch block is testing an expected condition (if so, refactor to validation)

package/prompts/final_verify.md

@@ -0,0 +1,58 @@
+# Phase 9: Site Preservation & Final Catalog
+
+## Objective
+Verify all previous expeditions produced a healthy codebase. Generate final metrics and preserve the excavation record.
+
+## Instructions
+
+1. **Test Verification**
+   - Run `{{ test_command }}` — must exit 0
+   - Run `{{ typecheck_command }}` — must exit 0
+   - If either fails, STOP and revert to baseline
+
+2. **Regression Checks**
+   - Re-run dependency analysis—verify no NEW cycles introduced
+   - Re-run dead code analysis—verify no NEW dead code created
+   - Check that no types were weakened during previous expeditions
+   - Verify no new duplications were introduced
+
+3. **Metrics Collection**
+   - Calculate lines changed (added/removed)
+   - Calculate test coverage delta (if available)
+   - Count type errors resolved
+   - Count cycles broken
+   - Count dead code removed
+
+4. **Diff Preservation**
+   - Run `git diff --stat > .archaeology/excavation_log.txt`
+   - Capture the complete change summary
+
+## Output
+
+Write to `.archaeology/FINAL_CATALOG.md`:
+- Executive summary of all expeditions
+- Before/after metrics comparison table
+- List of all artifacts removed
+- List of all types consolidated
+- List of all cycles broken
+- Recommendations for future maintenance
+- Human review sign-off checklist (if mode != survey)
+
+Write to `.archaeology/excavation_log.txt`:
+- Complete `git diff --stat` output
+
+## Final Checks
+- [ ] All tests passing
+- [ ] Type checker zero errors
+- [ ] No new circular dependencies
+- [ ] No new dead code
+- [ ] Linting passes (if applicable)
+- [ ] Documentation updated
+- [ ] Human review completed (if mode != survey)
+
+## Constraints
+- NEVER claim success if any test fails
+- NEVER ignore new type errors introduced during expeditions
+- ALWAYS revert all changes if this phase fails—do not leave repo in broken state
+- ALWAYS preserve `.archaeology/` directory for historical record
+- NEVER delete `.archaeology/` reports even after successful completion

package/prompts/legacy.md

@@ -0,0 +1,49 @@
+# Expedition 2: Legacy Stratum Removal
+
+## Objective
+Identify and catalog legacy code patterns: deprecated APIs, polyfills, compatibility shims, and fallback code for outdated environments.
+
+## Instructions
+
+1. **Pattern Search**
+   Search for these patterns across the codebase:
+   - `@deprecated` annotations or JSDoc tags
+   - `TODO(legacy)` or similar markers
+   - `polyfill`, `shim`, `compat`, `fallback` in filenames or code
+   - Feature detection for obsolete browsers/environments
+   - Version checks for long-EOL dependencies
+
+2. **Context Analysis**
+   For each legacy artifact found:
+   - Determine when it was added (git blame if possible)
+   - Identify what modern replacement exists
+   - Assess if any active code still depends on it
+   - Check if tests specifically cover the legacy path
+
+3. **Risk Assessment**
+   - HIGH confidence: Marked deprecated, no internal references, modern replacement available
+   - MEDIUM confidence: Legacy pattern but may have edge-case consumers
+   - LOW confidence: Unclear if removal would break downstream consumers
+
+## Output
+
+Write to `.archaeology/expedition2-report.md`:
+- Inventory of all legacy artifacts with location and context
+- Classification by confidence level
+- Recommended replacement for each artifact
+- Migration path for consumers (if applicable)
+
+## Execution Rules
+- If `mode == survey`: catalog only
+- If `mode == excavate`: generate migration guide + mock patches
+- If `mode == restore`:
+  - Remove HIGH confidence legacy code
+  - Remove MEDIUM confidence only if `strict_mode == true`
+  - Update documentation to reflect removals
+  - Run tests after each batch
+
+## Constraints
+- NEVER remove polyfills for features still needed by supported environments
+- NEVER remove fallback code for external APIs that are still unstable
+- ALWAYS verify no active imports before removing deprecated exports
+- NEVER break public API without explicit deprecation period documentation

package/prompts/polish.md

@@ -0,0 +1,48 @@
+# Expedition 8: Artifact Cleaning & Documentation
+
+## Objective
+Final cleanup pass: remove unnecessary comments, fix formatting, update documentation, and remove any remaining slop accumulated during previous expeditions.
+
+## Instructions
+
+1. **Documentation Audit**
+   - Remove outdated JSDoc comments (references to removed parameters, old behavior)
+   - Update README files to reflect removed features or changed APIs
+   - Remove boilerplate comments that state the obvious
+   - Ensure all public APIs have accurate documentation
+
+2. **Code Cleanup**
+   - Remove debug console.log statements
+   - Remove commented-out code blocks (if not already removed in Expedition 1)
+   - Fix inconsistent formatting (trailing whitespace, mixed indentation)
+   - Remove unused imports (if not caught by Expedition 1)
+
+3. **Slop Detection**
+   - Look for defensive programming that is no longer needed
+   - Remove type assertions that are now properly typed (from Expedition 5)
+   - Clean up temporary variables used during previous expeditions
+   - Verify no TODO comments were left unresolved
+
+## Output
+
+Write to `.archaeology/expedition8-report.md`:
+- Summary of all cleanup actions taken
+- Documentation updates made
+- Files modified in this expedition
+- Remaining slop flagged for human review (if any)
+
+## Execution Rules
+- If `mode == survey`: catalog only
+- If `mode == excavate`: generate cleanup patch
+- If `mode == restore`:
+  - Perform all safe cleanup actions
+  - NEVER remove meaningful comments explaining complex logic
+  - NEVER change code semantics during cleanup
+  - Run tests after cleanup
+
+## Constraints
+- NEVER remove comments explaining WHY (only remove WHAT comments that state the obvious)
+- NEVER change formatting in files that weren't otherwise modified (noise in diff)
+- ALWAYS preserve license headers and legal comments
+- NEVER remove TODO comments that are still valid—move them to issue tracker instead
+- ALWAYS run linter/formatter after cleanup if available

package/prompts/types_consolidate.md

@@ -0,0 +1,48 @@
+# Expedition 4: Type Catalog Consolidation
+
+## Objective
+Consolidate duplicate or redundant type definitions. Remove type definitions for code that was removed in previous expeditions.
+
+## Instructions
+
+1. **Type Discovery**
+   - Scan for duplicate interface/type definitions
+   - Find types defined in multiple files with same or similar shapes
+   - Identify types that shadow or extend each other unnecessarily
+   - Catalog type definitions for dead code removed in Expedition 1
+
+2. **Deduplication Analysis**
+   For each duplicate cluster:
+   - Compare structural similarity (are they actually the same?)
+   - Check usage patterns (which variant is more widely used?)
+   - Assess if they diverge intentionally (business logic differences)
+   - Determine canonical location (shared types directory, domain module, etc.)
+
+3. **Migration Planning**
+   - Plan imports to redirect to canonical type
+   - Identify if any type refinements are needed during consolidation
+   - Flag types that should merge vs. types that should remain separate
+
+## Output
+
+Write to `.archaeology/expedition4-report.md`:
+- Catalog of duplicate type clusters
+- Consolidation plan for each cluster
+- File paths affected by migration
+- Types flagged for human review (uncertain merges)
+
+## Execution Rules
+- If `mode == survey`: catalog only
+- If `mode == excavate`: generate type migration maps
+- If `mode == restore`:
+  - Consolidate HIGH confidence duplicates
+  - Update all imports to point to canonical definitions
+  - Remove orphaned type definitions
+  - Run type checker after each consolidation batch
+
+## Constraints
+- NEVER merge types that have semantic differences (even if structurally similar)
+- NEVER guess at the correct merged type—flag for review if uncertain
+- ALWAYS run the type checker after changes—zero errors before proceeding
+- ALWAYS preserve JSDoc comments on types during migration
+- NEVER consolidate before dead code removal is complete (prevents cataloging discarded code)

package/prompts/types_harden.md

@@ -0,0 +1,51 @@
+# Expedition 5: Type Restoration & Hardening
+
+## Objective
+Replace weak types (`any`, `unknown`, `Object`, `Function`) with precise types. Strengthen interfaces and add missing type constraints.
+
+## Instructions
+
+1. **Weak Type Scan**
+   Search for these patterns:
+   - Explicit `any` annotations
+   - `unknown` used where a specific type is inferable
+   - `Object` or `{}` as parameter/return types
+   - `Function` type (use specific call signatures instead)
+   - Missing return type annotations on exported functions
+   - `map[string]interface{}` (Go) or equivalent weak structures
+
+2. **Type Inference**
+   For each weak type found:
+   - Examine usage patterns to infer the correct type
+   - Check test files for type expectations
+   - Look at how the value is destructured or accessed
+   - Consider if a branded type or discriminated union is appropriate
+
+3. **Confidence Assessment**
+   - HIGH: Usage clearly indicates specific type, tests confirm
+   - MEDIUM: Type is inferable but has some dynamic access
+   - LOW: Too many possible shapes, requires domain knowledge
+
+## Output
+
+Write to `.archaeology/expedition5-report.md`:
+- Inventory of all weak types with locations
+- Proposed replacement type for each
+- Confidence level per replacement
+- Files that would be affected by changes
+
+## Execution Rules
+- If `mode == survey`: catalog only
+- If `mode == excavate`: generate type patch proposals
+- If `mode == restore`:
+  - Replace HIGH confidence weak types
+  - Replace MEDIUM confidence only if `strict_mode == true`
+  - NEVER replace LOW confidence types—flag for human review
+  - Run type checker after each file—stop on errors
+
+## Constraints
+- NEVER use `any` to "fix" a complex type—use proper typing
+- NEVER remove necessary `unknown` types (e.g., from external APIs)
+- NEVER change runtime behavior when adding types—types only
+- ALWAYS verify type checker passes with zero errors before proceeding
+- NEVER guess types for external library internals—use their type definitions

package/wiki/Expedition-Workflow.md

@@ -0,0 +1,32 @@
+# Expedition Workflow
+
+[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.
+
+1. Site Survey & Baseline
+2. Dead Code Excavation
+3. Legacy Stratum Removal
+4. Circular Dependency Cartography
+5. Type Catalog Consolidation
+6. Type Restoration & Hardening
+7. DRY Stratification
+8. Error Handling Stratigraphy
+9. Artifact Cleaning & Documentation
+10. Site Preservation & Final Catalog
+
+## Modes
+
+| Mode | Behavior |
+| --- | --- |
+| `survey` | Reports only; no source edits. |
+| `excavate` | Reports plus mock patches in `.archaeology/patches/`. |
+| `restore` | Applies approved changes with verification gates. |
+
+## 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.
+
+## Gates
+
+`hooks/opencode/init.sh` initializes the session. `verify-phase.sh` runs tests and type checks between restore phases. `revert-phase.sh` reverts a failed restore phase. `update-expedition.sh` records progress.

package/wiki/Home.md

@@ -0,0 +1,27 @@
+# Code Archaeology Wiki
+
+Code Archaeology is an OpenCode plugin for systematic codebase excavation, cataloging, and restoration. It runs a fixed, report-first workflow and keeps runtime artifacts local in `.archaeology/`.
+
+## Navigation
+
+- [Installation](Installation)
+- [Expedition Workflow](Expedition-Workflow)
+- [Security and Safety](Security-and-Safety)
+- [Release Process](Release-Process)
+
+## Quick Start
+
+```bash
+npm install -g opencode-code-archaeology
+opencode-code-archaeology install
+opencode-code-archaeology doctor
+opencode-code-archaeology version
+```
+
+Restart OpenCode inside a Git repository and run:
+
+```text
+/code-archaeology-survey
+```
+
+Start with `survey`, review reports, then choose `excavate` for mock patches or `restore` for approved, test-gated changes.

package/wiki/Installation.md

@@ -0,0 +1,42 @@
+# Installation
+
+[Home](Home) | [Workflow](Expedition-Workflow) | [Security](Security-and-Safety) | [Release](Release-Process)
+
+## OpenCode Plugin Install
+
+Add the package to the top-level `plugin` array in `opencode.json`:
+
+```json
+{
+  "plugin": [
+    "opencode-code-archaeology@git+https://github.com/Maleick/Code-Archaeology.git"
+  ]
+}
+```
+
+Restart OpenCode. Commands should be available inside a Git repository:
+
+```text
+/code-archaeology
+/code-archaeology-survey
+/code-archaeology-excavate
+/code-archaeology-restore
+```
+
+## npm CLI Path
+
+```bash
+npm install -g opencode-code-archaeology
+opencode-code-archaeology install
+opencode-code-archaeology doctor
+opencode-code-archaeology version
+```
+
+For updates:
+
+```bash
+npm install -g opencode-code-archaeology@latest
+npm list -g opencode-code-archaeology --depth=0
+```
+
+If commands do not appear, restart OpenCode, verify `opencode.json` uses `plugin` singular, and clear any stale OpenCode plugin cache.

package/wiki/Release-Process.md

@@ -0,0 +1,31 @@
+# Release Process
+
+[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.
+
+## 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`.
+4. Update `CHANGELOG.md` with release notes.
+5. Run verification:
+
+```bash
+npm install
+npm run build
+npm run typecheck
+npm audit --audit-level=moderate
+npm outdated --json
+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.
+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.
+
+Do not claim GitHub Pages is enabled unless repository settings confirm it.

package/wiki/Security-and-Safety.md

@@ -0,0 +1,21 @@
+# Security And Safety
+
+[Home](Home) | [Installation](Installation) | [Workflow](Expedition-Workflow) | [Release](Release-Process)
+
+## Current Audit Notes
+
+- `npm audit --audit-level=moderate` is expected to be clean.
+- `npm outdated --json` is expected to be clean.
+- No hardcoded secrets are expected in source, docs, hooks, commands, prompts, schemas, or metadata.
+- `.archaeology/` and `.superpowers/` are ignored local state.
+- Shell hooks can be syntax checked with `bash -n hooks/opencode/*.sh`.
+
+## Restore Caveat
+
+`restore` mode can edit source files. Run it only after reviewing `survey` reports, preferably after reviewing `excavate` mock patches, and only when tests or type checks are available.
+
+Failed restore phases should be reverted before continuing. The workflow must not remove try/catch blocks around I/O or external input boundaries automatically, and uncertain type replacements should be flagged for review.
+
+## Before Publishing
+
+Run build, typecheck, npm audit, npm outdated, shell syntax checks, and `npm pack --json --dry-run`. Inspect the package contents for accidental local state or secrets before publishing.