opencode-code-archaeology 2.0.2 → 2.2.1

package/hooks/hermes/runner.ps1

@@ -0,0 +1,247 @@
+# Hermes agent expedition runner - execute one Code Archaeology phase per cron run
+$ErrorActionPreference = 'Stop'
+
+$SCRIPT_DIR = Split-Path -Parent $MyInvocation.MyCommand.Path
+$REPO_ROOT = Resolve-Path "$SCRIPT_DIR/../.." | Select-Object -ExpandProperty Path
+$ARCHAEOLOGY_DIR = "$REPO_ROOT/.archaeology"
+$SESSION_FILE = "$ARCHAEOLOGY_DIR/session.json"
+
+# Restore mode can execute operator-provided verification commands. Keep the
+# authorization outside repository-controlled files so a malicious checkout
+# cannot enable unattended command execution by shipping .archaeology state.
+$RESTORE_APPROVAL_ENV = "HERMES_RESTORE_APPROVED"
+
+New-Item -ItemType Directory -Force -Path "$ARCHAEOLOGY_DIR" | Out-Null
+. (Join-Path $SCRIPT_DIR "../shared/command-utils.ps1")
+
+function Block-Session {
+    param(
+        [string]$Reason,
+        [string]$Message = $Reason
+    )
+    if (Test-Path "$SESSION_FILE") {
+        $session = Get-Content "$SESSION_FILE" -Raw | ConvertFrom-Json
+        $session.status = "blocked"
+        if (!($session.PSObject.Properties["flags"])) {
+            $session | Add-Member -MemberType NoteProperty -Name "flags" -Value @{}
+        }
+        $session.flags.blocked_reason = $Reason
+        $session | ConvertTo-Json -Depth 10 | Set-Content "$SESSION_FILE" -Encoding UTF8
+    }
+    Write-Host "ERROR: $Message" -ForegroundColor Red
+    exit 1
+}
+
+function Read-SessionString {
+    param([object]$Session, [string]$Key)
+    if (!($Session.PSObject.Properties[$Key]) -or !($Session.$Key -is [string]) -or [string]::IsNullOrWhiteSpace($Session.$Key)) {
+        Block-Session -Reason "invalid session field: $Key" -Message "Invalid Hermes session field: $Key"
+    }
+    return $Session.$Key
+}
+
+function Require-RestoreApproval {
+    if ([Environment]::GetEnvironmentVariable($RESTORE_APPROVAL_ENV) -ne "1") {
+        Block-Session `
+            -Reason "restore mode requires $RESTORE_APPROVAL_ENV=1" `
+            -Message "Hermes restore mode is disabled until the operator sets $RESTORE_APPROVAL_ENV=1 outside session.json"
+    }
+}
+
+function Validate-BranchName {
+    param([string]$Branch)
+    if ([string]::IsNullOrWhiteSpace($Branch) -or $Branch.StartsWith("-") -or $Branch -match "\s") {
+        Block-Session -Reason "invalid branch_name" -Message "Invalid Hermes branch_name: $Branch"
+    }
+    git check-ref-format --branch "$Branch" *> $null
+    if ($LASTEXITCODE -ne 0) {
+        Block-Session -Reason "invalid branch_name" -Message "Invalid Hermes branch_name: $Branch"
+    }
+}
+
+# Phase definitions (fixed order)
+$PHASES = @(
+    "site-survey"
+    "dead-code"
+    "legacy-removal"
+    "dependency-mapping"
+    "type-consolidation"
+    "type-hardening"
+    "dry-stratification"
+    "error-handling"
+    "artifact-cleaning"
+    "final-catalog"
+)
+
+# Detect current phase from session file
+$current_phase = ""
+if (Test-Path "$SESSION_FILE") {
+    $session = Get-Content "$SESSION_FILE" -Raw | ConvertFrom-Json
+    if ($session.PSObject.Properties["current_phase"] -and $session.current_phase) {
+        $current_phase = $session.current_phase
+    } else {
+        Block-Session -Reason "invalid session.json" -Message "Invalid Hermes session file: $SESSION_FILE"
+    }
+}
+
+if (-not $current_phase) {
+    $current_phase = $PHASES[0]
+    # Initialize session
+    $NOW = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
+    $session = @{
+        runtime = "hermes"
+        status = "running"
+        current_phase = $current_phase
+        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 = $NOW
+    }
+    $session | ConvertTo-Json -Depth 10 | Set-Content "$SESSION_FILE" -Encoding UTF8
+    Write-Host "Initialized Hermes session. Starting phase: $current_phase"
+}
+
+# Find phase index
+$phase_idx = 0
+$phase_found = $false
+for ($i = 0; $i -lt $PHASES.Count; $i++) {
+    if ($PHASES[$i] -eq $current_phase) {
+        $phase_idx = $i
+        $phase_found = $true
+        break
+    }
+}
+
+if (-not $phase_found) {
+    Block-Session -Reason "unknown phase: $current_phase" -Message "Unknown Hermes phase: $current_phase"
+}
+
+$phase_number = $phase_idx + 1
+$total_phases = $PHASES.Count
+
+Write-Host "=== Code Archaeology Hermes Runner ==="
+Write-Host "Phase $phase_number/$total_phases: $current_phase"
+$session = Get-Content "$SESSION_FILE" -Raw | ConvertFrom-Json
+Write-Host "Mode: $(Read-SessionString -Session $session -Key 'mode')"
+Write-Host ""
+
+# Run the phase
+Set-Location "$REPO_ROOT"
+
+$mode = Read-SessionString -Session $session -Key "mode"
+if ($mode -eq "restore") {
+    Require-RestoreApproval
+    Block-Session -Reason "restore mode is not implemented in Hermes runner" -Message "Hermes restore mode is not implemented. Use OpenCode restore after reviewing generated patches."
+}
+
+# Create branch if needed
+$branch = Read-SessionString -Session $session -Key "branch_name"
+Validate-BranchName -Branch $branch
+git checkout -b "$branch" 2>$null
+if (-not $?) {
+    git checkout "$branch"
+}
+
+# Execute phase based on mode
+if ($mode -eq "survey") {
+    Write-Host "Running SURVEY for phase $current_phase..."
+    # Generate reports only, no file changes
+    try {
+        & "$SCRIPT_DIR/../opencode/init.ps1" 2>$null
+    } catch {}
+
+    # Run phase-specific analysis
+    switch ($current_phase) {
+        "site-survey" { Write-Host "Generating site survey and baseline inventory..." }
+        "dead-code" { Write-Host "Cataloging dead code, unused exports, unreachable functions..." }
+        "legacy-removal" { Write-Host "Identifying legacy fallbacks, deprecated shims, compatibility layers..." }
+        "dependency-mapping" { Write-Host "Mapping circular dependencies..." }
+        "type-consolidation" { Write-Host "Finding duplicate type definitions..." }
+        "type-hardening" { Write-Host "Identifying weak types..." }
+        "dry-stratification" { Write-Host "Finding semantic duplication..." }
+        "error-handling" { Write-Host "Reviewing error-handling patterns..." }
+        "artifact-cleaning" { Write-Host "Identifying stale artifacts and documentation gaps..." }
+        "final-catalog" { Write-Host "Generating final excavation catalog..." }
+    }
+
+    # Write report
+    $report_file = "$ARCHAEOLOGY_DIR/expedition${phase_number}-report.md"
+    $reportTimestamp = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
+    @"
+# Expedition $phase_number`: $current_phase
+
+**Mode:** survey
+**Phase:** $phase_number/$total_phases
+**Runtime:** hermes
+**Timestamp:** $reportTimestamp
+
+## Findings
+
+Hermes recorded this phase handoff. It does not perform autonomous static analysis in this hook.
+
+## Recommendations
+
+Run the matching Code Archaeology prompt with OpenCode, then keep this report with the reviewed findings.
+
+## Safety Notes
+
+- All findings are reports only; no code changes made
+- Review before proceeding to excavate or restore mode
+"@ | Set-Content "$report_file" -Encoding UTF8
+
+    Write-Host "Report written: $report_file"
+
+} elseif ($mode -eq "excavate") {
+    Write-Host "Running EXCAVATE for phase $current_phase..."
+    # Generate mock patches (no file changes)
+    New-Item -ItemType Directory -Force -Path "$ARCHAEOLOGY_DIR/patches" | Out-Null
+    $patch_file = "$ARCHAEOLOGY_DIR/patches/expedition${phase_number}-mock.patch"
+    @"
+    # Patch handoff for $current_phase
+    # Hermes does not generate code changes from this hook.
+    # Run the matching OpenCode prompt, review the diff, then restore manually.
+"@ | Set-Content "$patch_file" -Encoding UTF8
+    Write-Host "Mock patch written: $patch_file"
+
+} else {
+    Block-Session -Reason "unknown mode: $mode" -Message "Unknown Hermes mode: $mode"
+}
+
+# Update session: mark phase complete, advance to next
+$session = Get-Content "$SESSION_FILE" -Raw | ConvertFrom-Json
+$completed = if ($session.PSObject.Properties["completed_phases"]) {
+    if ($session.completed_phases -and $session.completed_phases.Count -gt 0) {
+        ($session.completed_phases -join ",") + ",$current_phase"
+    } else {
+        $current_phase
+    }
+} else {
+    $current_phase
+}
+
+$next_phase = ""
+if ($phase_idx -lt ($PHASES.Count - 1)) {
+    $next_phase = $PHASES[$phase_idx + 1]
+}
+
+$session.completed_phases = $completed -split ","
+$session.current_phase = $next_phase
+$session | ConvertTo-Json -Depth 10 | Set-Content "$SESSION_FILE" -Encoding UTF8
+
+if ($next_phase) {
+    Write-Host ""
+    Write-Host "Phase $current_phase complete. Next: $next_phase"
+    Write-Host "STOP. Next cron run will execute phase: $next_phase"
+} else {
+    Write-Host ""
+    Write-Host "=== ALL PHASES COMPLETE ==="
+    Write-Host "Final catalog: $ARCHAEOLOGY_DIR/FINAL_CATALOG.md"
+    $session = Get-Content "$SESSION_FILE" -Raw | ConvertFrom-Json
+    $session.status = "complete"
+    $session | ConvertTo-Json -Depth 10 | Set-Content "$SESSION_FILE" -Encoding UTF8
+}

package/hooks/hermes/runner.sh

@@ -0,0 +1,262 @@
+#!/usr/bin/env bash
+# Hermes agent expedition runner — execute one Code Archaeology phase per cron run
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+ARCHAEOLOGY_DIR="$REPO_ROOT/.archaeology"
+SESSION_FILE="$ARCHAEOLOGY_DIR/session.json"
+
+# Restore mode can execute operator-provided verification commands. Keep the
+# authorization outside repository-controlled files so a malicious checkout
+# cannot enable unattended command execution by shipping .archaeology state.
+RESTORE_APPROVAL_ENV="HERMES_RESTORE_APPROVED"
+
+mkdir -p "$ARCHAEOLOGY_DIR"
+
+block_session() {
+  local reason="$1"
+  local message="${2:-$reason}"
+  echo "ERROR: $message" >&2
+  if command -v jq >/dev/null 2>&1 && [[ -f "$SESSION_FILE" ]]; then
+    write_session_jq --arg reason "$reason" \
+      '.status = "blocked" | .flags = (.flags // {}) | .flags.blocked_reason = $reason' || true
+  fi
+  exit 1
+}
+
+require_jq() {
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "ERROR: jq is required for Hermes session management" >&2
+    exit 1
+  fi
+}
+
+write_session_jq() {
+  local tmp
+  tmp=$(mktemp "$ARCHAEOLOGY_DIR/session.json.XXXXXX")
+  if jq "$@" "$SESSION_FILE" > "$tmp"; then
+    chmod 600 "$tmp" 2>/dev/null || true
+    mv -f "$tmp" "$SESSION_FILE"
+  else
+    rm -f "$tmp"
+    return 1
+  fi
+}
+
+read_session_string() {
+  local key="$1"
+  if ! jq -er --arg key "$key" '.[$key] | strings | select(test("\\S"))' "$SESSION_FILE" 2>/dev/null; then
+    block_session "invalid session field: $key" "Invalid Hermes session field: $key"
+  fi
+}
+
+require_restore_approval() {
+  if [[ "${!RESTORE_APPROVAL_ENV:-}" != "1" ]]; then
+    block_session \
+      "restore mode requires ${RESTORE_APPROVAL_ENV}=1" \
+      "Hermes restore mode is disabled until the operator sets ${RESTORE_APPROVAL_ENV}=1 outside session.json"
+  fi
+}
+
+validate_branch_name() {
+  local branch="$1"
+  if [[ -z "$branch" || "$branch" == -* || "$branch" =~ [[:space:]] ]]; then
+    block_session "invalid branch_name" "Invalid Hermes branch_name: $branch"
+  fi
+  if ! git check-ref-format --branch "$branch" >/dev/null 2>&1; then
+    block_session "invalid branch_name" "Invalid Hermes branch_name: $branch"
+  fi
+}
+
+require_jq
+
+# Phase definitions (fixed order)
+PHASES=(
+  "site-survey"
+  "dead-code"
+  "legacy-removal"
+  "dependency-mapping"
+  "type-consolidation"
+  "type-hardening"
+  "dry-stratification"
+  "error-handling"
+  "artifact-cleaning"
+  "final-catalog"
+)
+
+# Detect current phase from session file
+current_phase=""
+if [[ -f "$SESSION_FILE" ]]; then
+  if ! current_phase=$(jq -er '.current_phase // empty' "$SESSION_FILE" 2>/dev/null); then
+    block_session "invalid session.json" "Invalid Hermes session file: $SESSION_FILE"
+  fi
+fi
+
+if [[ -z "$current_phase" ]]; then
+  current_phase="${PHASES[0]}"
+  # Initialize session
+  cat > "$SESSION_FILE" <<EOF
+{
+  "runtime": "hermes",
+  "status": "running",
+  "current_phase": "$current_phase",
+  "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": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+}
+EOF
+  echo "Initialized Hermes session. Starting phase: $current_phase"
+fi
+
+# Find phase index
+phase_idx=0
+phase_found=false
+for i in "${!PHASES[@]}"; do
+  if [[ "${PHASES[$i]}" == "$current_phase" ]]; then
+    phase_idx=$i
+    phase_found=true
+    break
+  fi
+done
+
+if [[ "$phase_found" != true ]]; then
+  block_session "unknown phase: $current_phase" "Unknown Hermes phase: $current_phase"
+fi
+
+phase_number=$((phase_idx + 1))
+total_phases=${#PHASES[@]}
+
+echo "=== Code Archaeology Hermes Runner ==="
+echo "Phase $phase_number/$total_phases: $current_phase"
+echo "Mode: $(read_session_string mode)"
+echo ""
+
+# Run the phase
+cd "$REPO_ROOT"
+
+mode=$(read_session_string mode)
+if [[ "$mode" == "restore" ]]; then
+  require_restore_approval
+  block_session \
+    "restore mode is not implemented in Hermes runner" \
+    "Hermes restore mode is not implemented. Use OpenCode restore after reviewing generated patches."
+fi
+
+# Create branch if needed
+branch=$(read_session_string branch_name)
+validate_branch_name "$branch"
+git checkout -b "$branch" 2>/dev/null || git checkout "$branch"
+
+# Execute phase based on mode
+if [[ "$mode" == "survey" ]]; then
+  echo "Running SURVEY for phase $current_phase..."
+  # Generate reports only, no file changes
+  bash "$SCRIPT_DIR/../opencode/init.sh" 2>/dev/null || true
+  
+  # Run phase-specific analysis
+  case "$current_phase" in
+    "site-survey")
+      echo "Generating site survey and baseline inventory..."
+      ;;
+    "dead-code")
+      echo "Cataloging dead code, unused exports, unreachable functions..."
+      ;;
+    "legacy-removal")
+      echo "Identifying legacy fallbacks, deprecated shims, compatibility layers..."
+      ;;
+    "dependency-mapping")
+      echo "Mapping circular dependencies..."
+      ;;
+    "type-consolidation")
+      echo "Finding duplicate type definitions..."
+      ;;
+    "type-hardening")
+      echo "Identifying weak types..."
+      ;;
+    "dry-stratification")
+      echo "Finding semantic duplication..."
+      ;;
+    "error-handling")
+      echo "Reviewing error-handling patterns..."
+      ;;
+    "artifact-cleaning")
+      echo "Identifying stale artifacts and documentation gaps..."
+      ;;
+    "final-catalog")
+      echo "Generating final excavation catalog..."
+      ;;
+  esac
+  
+  # Write report
+  report_file="$ARCHAEOLOGY_DIR/expedition${phase_number}-report.md"
+  cat > "$report_file" <<EOF
+# Expedition $phase_number: $current_phase
+
+**Mode:** survey
+**Phase:** $phase_number/$total_phases
+**Runtime:** hermes
+**Timestamp:** $(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+## Findings
+
+Hermes recorded this phase handoff. It does not perform autonomous static analysis in this hook.
+
+## Recommendations
+
+Run the matching Code Archaeology prompt with OpenCode, then keep this report with the reviewed findings.
+
+## Safety Notes
+
+- All findings are reports only; no code changes made
+- Review before proceeding to excavate or restore mode
+EOF
+
+  echo "Report written: $report_file"
+  
+elif [[ "$mode" == "excavate" ]]; then
+  echo "Running EXCAVATE for phase $current_phase..."
+  # Generate mock patches (no file changes)
+  mkdir -p "$ARCHAEOLOGY_DIR/patches"
+  patch_file="$ARCHAEOLOGY_DIR/patches/expedition${phase_number}-mock.patch"
+  echo "# Patch handoff for $current_phase" > "$patch_file"
+  echo "# Hermes does not generate code changes from this hook." >> "$patch_file"
+  echo "# Run the matching OpenCode prompt, review the diff, then restore manually." >> "$patch_file"
+  echo "Mock patch written: $patch_file"
+  
+else
+  block_session "unknown mode: $mode" "Unknown Hermes mode: $mode"
+fi
+
+# Update session: mark phase complete, advance to next
+completed=$(jq -r '.completed_phases | join(",")' "$SESSION_FILE")
+if [[ -n "$completed" ]]; then
+  completed="$completed,$current_phase"
+else
+  completed="$current_phase"
+fi
+
+next_phase=""
+if [[ $phase_idx -lt $((${#PHASES[@]} - 1)) ]]; then
+  next_phase="${PHASES[$((phase_idx + 1))]}"
+fi
+
+write_session_jq --arg completed "$completed" --arg next "$next_phase" \
+  '.completed_phases = ($completed | split(",")) | .current_phase = $next'
+
+if [[ -n "$next_phase" ]]; then
+  echo ""
+  echo "Phase $current_phase complete. Next: $next_phase"
+  echo "STOP. Next cron run will execute phase: $next_phase"
+else
+  echo ""
+  echo "=== ALL PHASES COMPLETE ==="
+  echo "Final catalog: $ARCHAEOLOGY_DIR/FINAL_CATALOG.md"
+  write_session_jq '.status = "complete"'
+fi

package/hooks/hermes/setup.ps1

@@ -0,0 +1,41 @@
+# Hermes agent setup - discover Hermes capabilities for Code Archaeology
+$ErrorActionPreference = 'Stop'
+
+$SCRIPT_DIR = Split-Path -Parent $MyInvocation.MyCommand.Path
+$REPO_ROOT = Resolve-Path "$SCRIPT_DIR/../.." | Select-Object -ExpandProperty Path
+$ARCHAEOLOGY_DIR = "$REPO_ROOT/.archaeology"
+
+New-Item -ItemType Directory -Force -Path "$ARCHAEOLOGY_DIR" | Out-Null
+
+# Check if Hermes CLI is available
+$HERMES_AVAILABLE = $false
+try {
+    $null = Get-Command hermes -ErrorAction Stop
+    $HERMES_AVAILABLE = $true
+} catch {}
+
+# Check if we're running inside a Hermes session
+$HERMES_ACTIVE = $false
+if ($env:HERMES_SESSION_ID -or $env:HERMES_CWD -or $env:HERMES_PROVIDER) {
+    $HERMES_ACTIVE = $true
+}
+
+# Write Hermes runtime config
+$hermesRuntime = @{
+    runtime = "hermes"
+    available = $HERMES_AVAILABLE
+    active_session = $HERMES_ACTIVE
+    max_concurrent = 1
+    dispatch_method = "cronjob"
+    phase_interval = "15m"
+    notes = "Code Archaeology runs one expedition phase per cron run. Test gates between phases."
+}
+
+$hermesRuntime | ConvertTo-Json -Depth 5 | Set-Content "$ARCHAEOLOGY_DIR/hermes-runtime.json" -Encoding UTF8
+
+Write-Host "Hermes runtime configured for Code Archaeology:"
+Write-Host "  CLI available: $HERMES_AVAILABLE"
+Write-Host "  Active session: $HERMES_ACTIVE"
+Write-Host "  Max concurrent: 1 (one phase at a time)"
+Write-Host "  Phase interval: 15 minutes"
+Write-Host "  Config: $ARCHAEOLOGY_DIR/hermes-runtime.json"

package/hooks/hermes/setup.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Hermes agent setup — discover Hermes capabilities for Code Archaeology
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+ARCHAEOLOGY_DIR="$REPO_ROOT/.archaeology"
+
+mkdir -p "$ARCHAEOLOGY_DIR"
+
+# Check if Hermes CLI is available
+HERMES_AVAILABLE=false
+if command -v hermes &>/dev/null; then
+  HERMES_AVAILABLE=true
+fi
+
+# Check if we're running inside a Hermes session
+HERMES_ACTIVE=false
+if [[ -n "${HERMES_SESSION_ID:-}" || -n "${HERMES_CWD:-}" || -n "${HERMES_PROVIDER:-}" ]]; then
+  HERMES_ACTIVE=true
+fi
+
+# Write Hermes runtime config
+cat > "$ARCHAEOLOGY_DIR/hermes-runtime.json" <<EOF
+{
+  "runtime": "hermes",
+  "available": $HERMES_AVAILABLE,
+  "active_session": $HERMES_ACTIVE,
+  "max_concurrent": 1,
+  "dispatch_method": "cronjob",
+  "phase_interval": "15m",
+  "notes": "Code Archaeology runs one expedition phase per cron run. Test gates between phases."
+}
+EOF
+
+echo "Hermes runtime configured for Code Archaeology:"
+echo "  CLI available: $HERMES_AVAILABLE"
+echo "  Active session: $HERMES_ACTIVE"
+echo "  Max concurrent: 1 (one phase at a time)"
+echo "  Phase interval: 15 minutes"
+echo "  Config: $ARCHAEOLOGY_DIR/hermes-runtime.json"

package/hooks/opencode/init.ps1

@@ -0,0 +1,83 @@
+# Initialize .archaeology/ directory for Code Archaeology.
+
+$ErrorActionPreference = 'Stop'
+
+$ARCHAEOLOGY_DIR = ".archaeology"
+$SESSION_FILE = "$ARCHAEOLOGY_DIR/session.json"
+
+$SCRIPT_DIR = Split-Path -Parent $MyInvocation.MyCommand.Path
+$RELEASE_ROOT = Resolve-Path "$SCRIPT_DIR/../.." | Select-Object -ExpandProperty Path
+if (Test-Path "$RELEASE_ROOT/VERSION") {
+    $PLUGIN_VERSION = (Get-Content "$RELEASE_ROOT/VERSION" -Raw).Trim()
+} else {
+    $PLUGIN_VERSION = "dev"
+}
+
+$REPO_ROOT = $null
+try {
+    $REPO_ROOT = (git rev-parse --show-toplevel 2>$null).Trim()
+} catch {
+    Write-Error "Error: not inside a git repository"
+    exit 1
+}
+Set-Location "$REPO_ROOT"
+
+Write-Host "Code Archaeology v${PLUGIN_VERSION} initializing..."
+
+New-Item -ItemType Directory -Force -Path "$ARCHAEOLOGY_DIR" | Out-Null
+New-Item -ItemType Directory -Force -Path "$ARCHAEOLOGY_DIR/patches" | Out-Null
+
+# Initialize session.json
+if (!(Test-Path "$SESSION_FILE")) {
+    $NOW = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
+    $SESSION_ID = "archaeology-$([DateTimeOffset]::UtcNow.ToUnixTimeSeconds())-$PID"
+    $BASELINE_COMMIT = "unknown"
+    try {
+        $BASELINE_COMMIT = (git rev-parse HEAD 2>$null).Trim()
+    } catch {}
+
+    $session = @{
+        version = 1
+        plugin_version = $PLUGIN_VERSION
+        session_id = $SESSION_ID
+        config = @{
+            repo_path = "."
+            language = "typescript"
+            mode = "survey"
+            strict_mode = $false
+            test_command = "npm test"
+            typecheck_command = "npx tsc --noEmit"
+            branch_name = "refactor/archaeology"
+        }
+        started_at = $NOW
+        updated_at = $NOW
+        expeditions = @(
+            @{phase = "survey"; name = "Site Survey & Baseline"; status = "pending"; findings_count = 0}
+            @{phase = "dead_code"; name = "Dead Code Excavation"; status = "pending"; findings_count = 0}
+            @{phase = "legacy"; name = "Legacy Stratum Removal"; status = "pending"; findings_count = 0}
+            @{phase = "dependencies"; name = "Circular Dependency Cartography"; status = "pending"; findings_count = 0}
+            @{phase = "types_consolidate"; name = "Type Catalog Consolidation"; status = "pending"; findings_count = 0}
+            @{phase = "types_harden"; name = "Type Restoration & Hardening"; status = "pending"; findings_count = 0}
+            @{phase = "dry"; name = "DRY Stratification"; status = "pending"; findings_count = 0}
+            @{phase = "errors"; name = "Error Handling Stratigraphy"; status = "pending"; findings_count = 0}
+            @{phase = "polish"; name = "Artifact Cleaning & Documentation"; status = "pending"; findings_count = 0}
+            @{phase = "final_verify"; name = "Site Preservation & Final Catalog"; status = "pending"; findings_count = 0}
+        )
+        total_findings = 0
+        auto_fixable_count = 0
+        baseline_commit = $BASELINE_COMMIT
+        completed = $false
+    }
+
+    $session | ConvertTo-Json -Depth 10 | Set-Content "$SESSION_FILE" -Encoding UTF8
+    Write-Host "Initialized $SESSION_FILE"
+} else {
+    $NOW = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
+    $session = Get-Content "$SESSION_FILE" -Raw | ConvertFrom-Json
+    $session.updated_at = $NOW
+    $session.plugin_version = $PLUGIN_VERSION
+    $session | ConvertTo-Json -Depth 10 | Set-Content "$SESSION_FILE" -Encoding UTF8
+    Write-Host "Refreshed $SESSION_FILE"
+}
+
+Write-Host "Code Archaeology workspace ready at $ARCHAEOLOGY_DIR"

package/hooks/opencode/revert-phase.ps1

@@ -0,0 +1,12 @@
+# Move current working tree changes into a recoverable stash.
+# Usage: revert-phase.ps1 [phase-name]
+
+$ErrorActionPreference = 'Stop'
+
+$PHASE = if ($args[0]) { $args[0] } else { "unknown" }
+
+Write-Host "[$PHASE] Reverting changes due to failure..."
+
+git stash push -m "code-archaeology-revert-$PHASE" --include-untracked *> $null
+
+Write-Host "[$PHASE] Changes preserved in git stash"