opencode-code-archaeology 2.0.0 → 2.2.0

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/skills/code-archaeology/SKILL.md

@@ -76,8 +76,8 @@ With `strict_mode: true`, restore also applies MEDIUM confidence findings.
 | `language` | `typescript` | Primary language |
 | `mode` | `survey` | `survey`, `excavate`, or `restore` |
 | `strict_mode` | `false` | Auto-restore medium-confidence findings |
-| `test_command` | `npm test` | Test runner command |
-| `typecheck_command` | `npx tsc --noEmit` | Type check command |
+| `test_command` | `npm test` | Recorded session default only; verification uses `CODE_ARCHAEOLOGY_TEST_COMMAND` for operator-approved overrides |
+| `typecheck_command` | `npx tsc --noEmit` | Recorded session default only; verification uses `CODE_ARCHAEOLOGY_TYPECHECK_COMMAND` for operator-approved overrides |
 | `branch_name` | `refactor/archaeology` | Git branch to create |
 
 ## Language-Specific Tooling

package/skills/hermes/INTEGRATION.md

@@ -0,0 +1,120 @@
+# Code Archaeology Hermes Integration
+
+## Overview
+
+Code Archaeology can run on Hermes Agent using cron-based phase execution. Each cron run executes exactly ONE expedition phase with test gates between phases.
+
+## Architecture
+
+```
+Hermes Cron (every 15m)
+  → Read .archaeology/session.json
+  → Detect current phase (1 of 10)
+  → Execute ONE phase:
+      survey → excavate → restore (per phase)
+  → Run test/typecheck verification
+  → Keep or revert changes
+  → Advance to next phase
+  → STOP (next cron continues)
+```
+
+## Key Differences from OpenCode
+
+| 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 |
+
+## Setup
+
+```bash
+# 1. Install Code Archaeology CLI
+npm install -g opencode-code-archaeology
+
+# 2. Setup Hermes runtime
+cd ~/projects/Code-Archaeology
+bash hooks/hermes/setup.sh
+
+# 3. Create Hermes cronjob
+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."
+```
+
+## Hermes Prompt Template
+
+See `skills/hermes/code-archaeology-prompt.md` for the full cron prompt.
+
+## Commands Mapping
+
+| OpenCode | Hermes |
+|----------|--------|
+| `/code-archaeology` | `cronjob` runs expedition loop |
+| `/code-archaeology-survey` | `mode = "survey"` in session.json |
+| `/code-archaeology-excavate` | `mode = "excavate"` in session.json |
+| `/code-archaeology-restore` | `mode = "restore"` in session.json |
+
+## Session File Format
+
+Hermes uses the same `.archaeology/session.json` format as OpenCode:
+
+```json
+{
+  "runtime": "hermes",
+  "status": "running",
+  "current_phase": "dead-code",
+  "completed_phases": ["site-survey"],
+  "mode": "survey",
+  "repo_path": ".",
+  "language": "typescript",
+  "test_command": "npm test",
+  "typecheck_command": "npx tsc --noEmit",
+  "branch_name": "refactor/archaeology",
+  "strict_mode": false,
+  "started_at": "2026-05-03T14:00:00Z"
+}
+```
+
+## 10-Phase Expedition Order
+
+| # | Phase | Hermes Action |
+|---|-------|---------------|
+| 1 | Site Survey & Baseline | Generate inventory report |
+| 2 | Dead Code Excavation | Catalog unused code |
+| 3 | Legacy Stratum Removal | Identify deprecated shims |
+| 4 | Circular Dependency Cartography | Map dependency cycles |
+| 5 | Type Catalog Consolidation | Find duplicate types |
+| 6 | Type Restoration & Hardening | Flag weak types |
+| 7 | DRY Stratification | Find semantic duplication |
+| 8 | Error Handling Stratigraphy | Review error patterns |
+| 9 | Artifact Cleaning & Documentation | Clean stale artifacts |
+| 10 | Site Preservation & Final Catalog | Generate FINAL_CATALOG.md |
+
+## Safety Model
+
+Same as OpenCode:
+- `survey` is default — reports only, zero edits
+- `restore` modifies code only after review
+- Tests and type checks gate each phase
+- Failed restores are automatically reverted
+- Never remove try/catch from I/O boundaries
+
+## Limitations
+
+- One phase per cron run (10 phases = ~2.5 hours minimum)
+- No real-time slash command variants
+- Phase order is fixed; cannot skip ahead
+- Memory is session-based; use `memory` tool for persistence
+
+## Future Enhancements
+
+- [ ] Auto-detect optimal phase interval based on repo size
+- [ ] Parallel subagent analysis within a phase (Scout + Analyst)
+- [ ] Cross-session memory for language-specific patterns
+- [ ] Integration with Hermes checkpoint/rollback for safe resets

package/skills/hermes/README.md

@@ -0,0 +1,167 @@
+# Code Archaeology Hermes Skill
+
+## Installation
+
+```bash
+# Clone Code Archaeology
+git clone https://github.com/Maleick/Code-Archaeology.git
+cd Code-Archaeology
+
+# Install dependencies
+npm install
+
+# Verify
+npm run typecheck
+bash hooks/verify-package.sh
+```
+
+## Hermes Setup
+
+### 1. Setup Hermes Runtime
+
+```bash
+cd ~/projects/Code-Archaeology
+bash hooks/hermes/setup.sh
+```
+
+### 2. Create Session Config
+
+```bash
+# Create session config
+cat > .archaeology/session.json <<'EOF'
+{
+  "runtime": "hermes",
+  "status": "running",
+  "current_phase": "site-survey",
+  "completed_phases": [],
+  "mode": "survey",
+  "repo_path": ".",
+  "language": "typescript",
+  "test_command": "npm test",
+  "typecheck_command": "npx tsc --noEmit",
+  "branch_name": "refactor/archaeology",
+  "strict_mode": false,
+  "started_at": "2026-05-03T14:00:00Z"
+}
+EOF
+```
+
+### 3. Create 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 test/typecheck verification, advance to next phase. STOP after one phase."
+```
+
+## Usage
+
+### Start Expedition
+
+```bash
+# Resume cron (first run auto-initializes)
+hermes cronjob resume code-archaeology-expedition
+```
+
+### Check Status
+
+```bash
+cat .archaeology/session.json | jq .
+ls .archaeology/expedition*-report.md
+```
+
+### Change Mode
+
+```bash
+# Switch from survey to excavate
+jq '.mode = "excavate"' .archaeology/session.json > tmp.json && mv tmp.json .archaeology/session.json
+
+# Switch from excavate to restore
+jq '.mode = "restore"' .archaeology/session.json > tmp.json && mv tmp.json .archaeology/session.json
+```
+
+### Stop Expedition
+
+```bash
+# Set stop flag
+jq '.status = "stopped"' .archaeology/session.json > tmp.json && mv tmp.json .archaeology/session.json
+
+# Or pause cron
+hermes cronjob pause code-archaeology-expedition
+```
+
+## Phase Timeline
+
+With 15-minute intervals:
+- 10 phases × 15 min = **2.5 hours minimum**
+- Survey mode: ~2.5 hours (reports only)
+- Restore mode: ~2.5 hours + verification time
+
+## Reports Generated
+
+| File | Content |
+|------|---------|
+| `.archaeology/site_survey.md` | Baseline inventory |
+| `.archaeology/expedition1-report.md` | Site Survey |
+| `.archaeology/expedition2-report.md` | Dead Code |
+| `.archaeology/expedition3-report.md` | Legacy Removal |
+| `.archaeology/expedition4-report.md` | Dependency Mapping |
+| `.archaeology/expedition5-report.md` | Type Consolidation |
+| `.archaeology/expedition6-report.md` | Type Hardening |
+| `.archaeology/expedition7-report.md` | DRY Stratification |
+| `.archaeology/expedition8-report.md` | Error Handling |
+| `.archaeology/expedition9-report.md` | Artifact Cleaning |
+| `.archaeology/FINAL_CATALOG.md` | Complete summary |
+| `.archaeology/patches/*.patch` | Mock patches (excavate mode) |
+
+## Safety
+
+Same as OpenCode:
+- Survey mode: **zero file changes outside `.archaeology/`**
+- Restore mode: **test-gated, auto-revert on failure**
+- Never removes try/catch from I/O boundaries
+- Never guesses types; flags for human review
+
+## Troubleshooting
+
+### Cron not running
+
+```bash
+hermes cronjob list
+hermes cronjob log code-archaeology-expedition
+```
+
+### Phase blocked
+
+```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
+```
+
+### Reports empty
+
+- Ensure `mode` is set correctly in session.json
+- Check that language tools are installed (`knip`, `madge`, etc.)
+- Run `bash hooks/opencode/init.sh` to reinitialize
+
+## Comparison with OpenCode
+
+| Feature | OpenCode | Hermes |
+|---------|----------|--------|
+| Entry | `/code-archaeology` | Cronjob |
+| Phases | All in one session | One per 15-min cron |
+| Real-time | Yes | Delayed |
+| Slash variants | 3 commands | Mode flag in session |
+| Background | Plugin active | Native cron |
+| State | `.archaeology/session.json` | Same |
+
+## Links
+
+- Code Archaeology repo: https://github.com/Maleick/Code-Archaeology
+- Hermes docs: https://hermes-agent.nousresearch.com/docs
+- OpenCode plugin: `opencode-code-archaeology`

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.**