opencode-code-archaeology 2.0.0 → 2.2.0

package/hooks/opencode/revert-phase.sh

@@ -1,4 +1,4 @@
-# Revert changes in the current working tree back to the last commit.
+# Move current working tree changes into a recoverable stash.
 # Usage: revert-phase.sh [phase-name]
 
 set -euo pipefail
@@ -7,11 +7,6 @@ PHASE="${1:-unknown}"
 
 echo "[$PHASE] ⚠️ Reverting changes due to failure..."
 
-# Stash any changes and drop them
-git stash push -m "code-archaeology-revert-$PHASE" --include-untracked 2>/dev/null || true
-git stash drop 2>/dev/null || true
+git stash push -m "code-archaeology-revert-$PHASE" --include-untracked >/dev/null 2>&1 || true
 
-# Reset to HEAD
-git reset --hard HEAD
-
-echo "[$PHASE] ✅ Reverted to last commit"
+echo "[$PHASE] ✅ Changes preserved in git stash"

package/hooks/opencode/update-expedition.ps1

@@ -0,0 +1,51 @@
+# Update expedition status in session.json
+# Usage: update-expedition.ps1 <phase> <status> [findings_count] [error_message]
+
+$ErrorActionPreference = 'Stop'
+
+$PHASE = $args[0]
+$STATUS = $args[1]
+$FINDINGS = if ($args[2]) { [int]$args[2] } else { 0 }
+$ERROR_MSG = if ($args[3]) { $args[3] } else { "" }
+
+$ARCHAEOLOGY_DIR = ".archaeology"
+$SESSION_FILE = "$ARCHAEOLOGY_DIR/session.json"
+
+if (!(Test-Path "$SESSION_FILE")) {
+    Write-Error "Error: session.json not found. Run init.ps1 first."
+    exit 1
+}
+
+$NOW = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
+
+$session = Get-Content "$SESSION_FILE" -Raw | ConvertFrom-Json
+
+foreach ($expedition in $session.expeditions) {
+    if ($expedition.phase -eq $PHASE) {
+        $expedition.status = $STATUS
+        $expedition.findings_count = $FINDINGS
+        if ($STATUS -eq "completed" -or $STATUS -eq "done") {
+            $expedition | Add-Member -MemberType NoteProperty -Name "completed_at" -Value $NOW -Force
+        }
+        if ($ERROR_MSG) {
+            $expedition | Add-Member -MemberType NoteProperty -Name "error" -Value $ERROR_MSG -Force
+        } else {
+            if ($expedition.PSObject.Properties["error"]) {
+                $expedition.PSObject.Properties.Remove("error")
+            }
+        }
+    }
+}
+
+$session.updated_at = $NOW
+
+# Update total findings
+$total = 0
+foreach ($expedition in $session.expeditions) {
+    $total += $expedition.findings_count
+}
+$session.total_findings = $total
+
+$session | ConvertTo-Json -Depth 10 | Set-Content "$SESSION_FILE" -Encoding UTF8
+
+Write-Host "[$PHASE] Updated status: $STATUS (findings: $FINDINGS)"

package/hooks/opencode/verify-package.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+pack_json=$(npm pack --json --dry-run)
+
+PACK_JSON="$pack_json" node <<'NODE'
+const pack = JSON.parse(process.env.PACK_JSON ?? '[]');
+const files = new Set((pack[0]?.files ?? []).map((file) => file.path));
+
+const requiredFiles = [
+  'dist/cli.js',
+  'dist/index.js',
+  'commands/code-archaeology.md',
+  'skills/code-archaeology/SKILL.md',
+  'hooks/opencode/init.sh',
+  'hooks/opencode/verify-phase.sh',
+  'hooks/opencode/revert-phase.sh',
+  'hooks/opencode/update-expedition.sh',
+  'hooks/opencode/verify-package.sh',
+  'prompts/discovery.md',
+  'schema/expedition-report.json',
+  'docs/index.html',
+  'docs/README.md',
+  'wiki/Home.md',
+  'assets/code-archaeology-banner.svg',
+  'AGENTS.md',
+  'VERSION',
+  'README.md',
+  'INSTALL.md',
+  'SECURITY.md',
+  'CONTRIBUTING.md',
+  'CHANGELOG.md',
+  'LICENSE',
+];
+
+const missingFiles = requiredFiles.filter((file) => !files.has(file));
+
+if (missingFiles.length > 0) {
+  console.error('Package is missing required files:');
+  for (const file of missingFiles) {
+    console.error(`- ${file}`);
+  }
+  process.exit(1);
+}
+
+console.log(`Package dry-run includes ${files.size} files and all required release assets.`);
+NODE

package/hooks/opencode/verify-phase.ps1

@@ -0,0 +1,35 @@
+# Verify that tests pass and typecheck succeeds.
+# Usage: verify-phase.ps1 [phase-name]
+
+$ErrorActionPreference = 'Stop'
+
+$PHASE = if ($args[0]) { $args[0] } else { "unknown" }
+$ARCHAEOLOGY_DIR = ".archaeology"
+$SESSION_FILE = "$ARCHAEOLOGY_DIR/session.json"
+$SCRIPT_DIR = Split-Path -Parent $MyInvocation.MyCommand.Path
+. (Join-Path $SCRIPT_DIR "../shared/command-utils.ps1")
+
+# Verification commands must not be read from repository-local state.
+# A malicious repository can pre-seed .archaeology/session.json; executing commands
+# from that file would cross the repository-to-workstation trust boundary.
+# Operators who intentionally need custom commands can approve them explicitly via
+# environment variables for the current process.
+$TEST_CMD = if ($env:CODE_ARCHAEOLOGY_TEST_COMMAND) { $env:CODE_ARCHAEOLOGY_TEST_COMMAND } else { "npm test" }
+$TYPECHECK_CMD = if ($env:CODE_ARCHAEOLOGY_TYPECHECK_COMMAND) { $env:CODE_ARCHAEOLOGY_TYPECHECK_COMMAND } else { "npx tsc --noEmit" }
+
+Write-Host "[$PHASE] Running test command: $TEST_CMD"
+try {
+    Invoke-CheckedCommand -CommandLine $TEST_CMD | Out-Default
+} catch {
+    Write-Error "[$PHASE] Tests FAILED"
+    exit 1
+}
+
+Write-Host "[$PHASE] Running typecheck: $TYPECHECK_CMD"
+try {
+    Invoke-CheckedCommand -CommandLine $TYPECHECK_CMD 2>$null | Out-Default
+} catch {
+    Write-Warning "[$PHASE] Typecheck reported errors (non-blocking for some languages)"
+}
+
+Write-Host "[$PHASE] Verification passed"

package/hooks/opencode/verify-phase.sh

@@ -9,13 +9,13 @@ SESSION_FILE="$ARCHAEOLOGY_DIR/session.json"
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
-# Source config from session file if jq is available
-TEST_CMD="npm test"
-TYPECHECK_CMD="npx tsc --noEmit"
-if command -v jq >/dev/null 2>&1 && [[ -f "$SESSION_FILE" ]]; then
-  TEST_CMD=$(jq -r '.config.test_command // "npm test"' "$SESSION_FILE")
-  TYPECHECK_CMD=$(jq -r '.config.typecheck_command // "npx tsc --noEmit"' "$SESSION_FILE")
-fi
+# Verification commands must not be read from repository-local state.
+# A malicious repository can pre-seed .archaeology/session.json; executing commands
+# from that file would cross the repository-to-workstation trust boundary.
+# Operators who intentionally need custom commands can approve them explicitly via
+# environment variables for the current process.
+TEST_CMD="${CODE_ARCHAEOLOGY_TEST_COMMAND:-npm test}"
+TYPECHECK_CMD="${CODE_ARCHAEOLOGY_TYPECHECK_COMMAND:-npx tsc --noEmit}"
 
 echo "[$PHASE] Running test command: $TEST_CMD"
 if ! bash -c "$TEST_CMD"; then

package/hooks/shared/command-utils.ps1

@@ -0,0 +1,100 @@
+# Shared PowerShell command parsing and execution helpers for verification hooks.
+
+function Convert-CommandElementToArgument {
+    param(
+        [Parameter(Mandatory=$true)]
+        [System.Management.Automation.Language.CommandElementAst]$Element,
+
+        [Parameter(Mandatory=$true)]
+        [string]$CommandLine
+    )
+
+    if ($Element -is [System.Management.Automation.Language.StringConstantExpressionAst]) {
+        return $Element.Value
+    }
+
+    if ($Element -is [System.Management.Automation.Language.ExpandableStringExpressionAst]) {
+        return $Element.Value
+    }
+
+    if ($Element -is [System.Management.Automation.Language.CommandParameterAst]) {
+        if ($null -ne $Element.Argument) {
+            $argumentValue = Convert-CommandElementToArgument -Element $Element.Argument -CommandLine $CommandLine
+            return "-$($Element.ParameterName):$argumentValue"
+        }
+
+        return "-$($Element.ParameterName)"
+    }
+
+    throw "Unsupported command syntax in command: $CommandLine"
+}
+
+function Split-CommandLine {
+    param([Parameter(Mandatory=$true)][string]$CommandLine)
+
+    [System.Management.Automation.Language.Token[]]$tokens = @()
+    [System.Management.Automation.Language.ParseError[]]$parseErrors = @()
+    $ast = [System.Management.Automation.Language.Parser]::ParseInput($CommandLine, [ref]$tokens, [ref]$parseErrors)
+
+    if ($parseErrors.Count -gt 0) {
+        $message = ($parseErrors | ForEach-Object { $_.Message }) -join "; "
+        throw "Invalid command syntax: $CommandLine. $message"
+    }
+
+    $statements = @($ast.EndBlock.Statements)
+    if ($statements.Count -ne 1 -or $statements[0] -isnot [System.Management.Automation.Language.PipelineAst]) {
+        throw "Only a single simple command is supported: $CommandLine"
+    }
+
+    $pipeline = [System.Management.Automation.Language.PipelineAst]$statements[0]
+    if ($pipeline.PipelineElements.Count -ne 1 -or $pipeline.PipelineElements[0] -isnot [System.Management.Automation.Language.CommandAst]) {
+        throw "Only a single simple command is supported: $CommandLine"
+    }
+
+    $commandAst = [System.Management.Automation.Language.CommandAst]$pipeline.PipelineElements[0]
+    if ($commandAst.Redirections.Count -gt 0) {
+        throw "Command must not contain redirections: $CommandLine"
+    }
+
+    $parts = [System.Collections.Generic.List[string]]::new()
+    foreach ($element in $commandAst.CommandElements) {
+        $parts.Add((Convert-CommandElementToArgument -Element $element -CommandLine $CommandLine))
+    }
+
+    return $parts.ToArray()
+}
+
+function Invoke-CheckedCommand {
+    param([Parameter(Mandatory=$true)][string]$CommandLine)
+
+    [string[]]$parts = @(Split-CommandLine -CommandLine $CommandLine)
+    if ($parts.Count -eq 0) {
+        throw "Empty command"
+    }
+
+    $command = $parts[0]
+    $arguments = @()
+    if ($parts.Count -gt 1) {
+        $arguments = $parts[1..($parts.Count - 1)]
+    }
+
+    $resolvedCommand = Get-Command -Name $command -ErrorAction Stop | Select-Object -First 1
+    $isExternalApplication = $resolvedCommand.CommandType -eq [System.Management.Automation.CommandTypes]::Application
+    if ($isExternalApplication) {
+        $global:LASTEXITCODE = 0
+    }
+
+    & $command @arguments
+
+    if ($isExternalApplication) {
+        $exitCode = $LASTEXITCODE
+        if ($exitCode -ne 0) {
+            throw "Command failed with exit code $exitCode: $CommandLine"
+        }
+        return
+    }
+
+    if (-not $?) {
+        throw "Command failed: $CommandLine"
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-code-archaeology",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Excavate, catalog, and restore a codebase by removing accumulated sediment—dead code, legacy fallbacks, circular dependencies, weak types, and defensive programming slop.",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,6 +12,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
     }
   },
   "files": [
@@ -19,16 +27,29 @@
     "hooks",
     "commands",
     "skills",
-    "plugins",
-    "policies",
+    "prompts",
     "schema",
+    "docs/README.md",
+    "docs/index.html",
+    "docs/INSTALL.md",
+    "docs/ARCHITECTURE.md",
+    "docs/RELEASE.md",
+    "docs/SECURITY_AUDIT.md",
+    "wiki",
+    "assets",
+    ".github",
     "AGENTS.md",
     "VERSION",
     "README.md",
+    "INSTALL.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsc",
+    "test": "npm run build && node --test tests/*.test.mjs",
     "typecheck": "tsc --noEmit",
     "verify:pack": "bash hooks/opencode/verify-package.sh",
     "prepack": "tsc"
@@ -46,14 +67,28 @@
     "type": "git",
     "url": "git+https://github.com/Maleick/Code-Archaeology.git"
   },
-  "homepage": "https://github.com/Maleick/Code-Archaeology",
+  "author": {
+    "name": "Maleick",
+    "url": "https://github.com/Maleick"
+  },
+  "homepage": "https://github.com/Maleick/Code-Archaeology#readme",
   "bugs": {
     "url": "https://github.com/Maleick/Code-Archaeology/issues"
   },
   "license": "MIT",
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/node": "^25.6.0",
+    "semantic-release": "^25.0.3",
+    "typescript": "^6.0.3"
+  },
+  "overrides": {
+    "npm": "^11.14.0"
   },
   "engines": {
     "node": ">=18"

package/prompts/dead_code.md

@@ -0,0 +1,45 @@
+# Expedition 1: Dead Code Excavation
+
+## Objective
+Identify and catalog all dead code—unused exports, unreachable functions, unreferenced variables, and orphaned files.
+
+## Instructions
+
+1. **Tool-Based Discovery**
+   - Run `knip` (TypeScript/JavaScript) or `vulture` (Python)
+   - Run `jscpd` to find duplicate code that may indicate dead copies
+   - If tools unavailable, perform AST-based manual analysis
+
+2. **Classification**
+   For each finding, classify confidence:
+   - **HIGH**: Tool-confirmed unused export with zero references
+   - **MEDIUM**: Likely unused but has dynamic access or test references
+   - **LOW**: Possibly used via reflection or build-time injection
+
+3. **Impact Assessment**
+   - Note if removal affects public API
+   - Check for test files that import but don't meaningfully test
+   - Verify no build scripts or CI depend on the code
+
+## Output
+
+Write to `.archaeology/expedition1-report.md`:
+- Table of all findings with file paths, line numbers, confidence levels
+- Categorized by type (unused export, unreachable code, orphaned file, duplicate)
+- Recommended action per finding (remove, flag for review, keep)
+- Estimated lines of code affected
+
+## Execution Rules
+- If `mode == survey`: catalog only, zero changes
+- If `mode == excavate`: generate mock patch files for review
+- If `mode == restore`:
+  - Remove HIGH confidence artifacts always
+  - Remove MEDIUM confidence artifacts only if `strict_mode == true`
+  - NEVER remove LOW confidence artifacts
+  - Run tests after each removal batch
+  - Revert immediately if tests fail
+
+## Constraints
+- NEVER remove code that is dynamically accessed (eval, require(variable), etc.)
+- NEVER remove exports that are part of a public API unless explicitly deprecated
+- ALWAYS verify with grep that no references exist before removing

package/prompts/dependencies.md

@@ -0,0 +1,49 @@
+# Expedition 3: Circular Dependency Cartography
+
+## Objective
+Map all circular dependencies in the module graph and provide remediation strategies.
+
+## Instructions
+
+1. **Tool-Based Analysis**
+   - Run `madge --circular` (TypeScript/JavaScript)
+   - Run `pydeps` (Python) or equivalent
+   - If tools unavailable, build import graph manually
+
+2. **Dependency Mapping**
+   For each cycle found:
+   - List all files in the cycle
+   - Identify the specific imports creating the cycle
+   - Determine if the cycle is direct (A→B→A) or indirect (A→B→C→A)
+   - Calculate cycle complexity (number of nodes, edges)
+
+3. **Remediation Strategy**
+   For each cycle, determine the best fix:
+   - Extract shared code to a new module (preferred)
+   - Use dependency inversion / interfaces
+   - Move code to break the cycle
+   - Convert to dynamic imports (if appropriate)
+   - Flag as architectural issue requiring human design review
+
+## Output
+
+Write to `.archaeology/expedition3-report.md`:
+- Complete cycle inventory with file paths and import chains
+- Visualization data (can be rendered with graphviz)
+- Remediation recommendation per cycle
+- Estimated effort to resolve each cycle
+
+## Execution Rules
+- If `mode == survey`: catalog only
+- If `mode == excavate`: generate detailed migration plans
+- If `mode == restore`:
+  - Fix simple cycles (2-node, clear extraction path) automatically
+  - Flag complex cycles for human review
+  - NEVER create new abstractions that obscure the cycle—break it properly
+  - Run tests after each fix
+
+## Constraints
+- NEVER introduce dynamic imports just to hide a cycle—fix the architecture
+- NEVER extract code into poorly-named "utils" files—use domain-appropriate names
+- ALWAYS ensure the fixed graph has no new cycles introduced
+- ALWAYS verify the cycle is real (not a type-only import that tree-shakes away)

package/prompts/discovery.md

@@ -0,0 +1,47 @@
+# Phase 0: Site Survey & Baseline
+
+## Objective
+Establish a complete inventory of the codebase before any modifications. Document the baseline state so all subsequent expeditions have a reference point.
+
+## Instructions
+
+1. **Verify Preconditions**
+   - Confirm working tree is clean
+   - Confirm tests pass at baseline
+   - Create branch `{{ branch_name }}`
+   - Create `.archaeology/` directory
+
+2. **File Inventory**
+   - Catalog all source files by directory
+   - Note file counts, line counts, and language distribution
+   - Identify configuration files (package.json, tsconfig, etc.)
+
+3. **Dependency Mapping**
+   - Document all external dependencies
+   - Note devDependencies vs production dependencies
+   - Flag any deprecated or outdated packages
+
+4. **Baseline Metrics**
+   - Record test count and coverage (if available)
+   - Record type error count
+   - Record lint error count
+   - Save current git HEAD to `.archaeology/baseline.txt`
+
+## Output
+
+Write to `.archaeology/site_survey.md`:
+- Executive summary of codebase size and structure
+- Dependency health assessment
+- Baseline metrics table
+- Risk factors identified
+
+Write to `.archaeology/artifact_inventory.json`:
+- Machine-readable file inventory
+
+Write to `.archaeology/stratum_graph.json`:
+- Dependency graph data for visualization
+
+## Constraints
+- ZERO file modifications in this phase
+- If tests fail at baseline, abort immediately
+- Do not proceed to Expedition 1 until this report is complete

package/prompts/dry.md

@@ -0,0 +1,49 @@
+# Expedition 6: DRY Stratification
+
+## Objective
+Identify semantic duplication across the codebase and extract shared abstractions. Only extract true semantic duplicates, not coincidental similarity.
+
+## Instructions
+
+1. **Duplicate Detection**
+   - Run `jscpd` with `min_duplicate_lines: 5`
+   - Search for repeated patterns manually (error messages, validation logic, API calls)
+   - Look for copy-pasted code blocks with minor variations
+
+2. **Semantic Analysis**
+   For each duplicate found:
+   - Determine if the duplication is coincidental (same structure, different semantics)
+   - Check if the duplicated code represents a real domain concept
+   - Assess if extraction would create a meaningful abstraction
+   - Verify the duplicated code isn't better left inline (trivial one-liners)
+
+3. **Extraction Planning**
+   - Identify the canonical location for the extracted code
+   - Determine the appropriate abstraction level (function, class, constant, etc.)
+   - Plan parameterization for minor variations
+   - Check for existing utility libraries that could host the code
+
+## Output
+
+Write to `.archaeology/expedition6-report.md`:
+- Catalog of all duplications with locations and similarity scores
+- Classification: semantic vs. coincidental
+- Extraction recommendation for each semantic duplicate
+- Proposed abstraction name and location
+- Files affected by extraction
+
+## Execution Rules
+- If `mode == survey`: catalog only
+- If `mode == excavate`: generate extraction plans with before/after code
+- If `mode == restore`:
+  - Extract HIGH confidence semantic duplications
+  - Extract MEDIUM confidence only if `strict_mode == true`
+  - NEVER extract coincidental similarities—leave them inline
+  - Run tests after each extraction
+
+## Constraints
+- NEVER extract code into a "utils" grab bag—use domain-appropriate names
+- NEVER create abstractions over cyclic dependencies (fix cycles in Expedition 3 first)
+- ALWAYS ensure the extracted code is actually used in 3+ places or is likely to be
+- NEVER change behavior during extraction—pure refactor only
+- ALWAYS prefer composition over premature abstraction

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