opencode-code-archaeology 2.0.0 → 2.2.0

package/README.md

@@ -1,71 +1,220 @@
-# Code Archaeology
+<h1 align="center">Code Archaeology</h1>
+
+<p align="center">
+  <img src="assets/code-archaeology-banner.svg" alt="Code Archaeology multi-runtime banner" width="900">
+</p>
+
+<p align="center">
+  <a href="https://github.com/Maleick/Code-Archaeology/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/Maleick/Code-Archaeology?style=flat-square"></a>
+  <a href="https://github.com/Maleick/Code-Archaeology/commits/main"><img alt="Last commit" src="https://img.shields.io/github/last-commit/Maleick/Code-Archaeology?style=flat-square"></a>
+  <a href="https://github.com/Maleick/Code-Archaeology/releases"><img alt="GitHub release" src="https://img.shields.io/github/v/release/Maleick/Code-Archaeology?style=flat-square"></a>
+  <a href="https://www.npmjs.com/package/opencode-code-archaeology"><img alt="npm version" src="https://img.shields.io/npm/v/opencode-code-archaeology?style=flat-square"></a>
+  <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/Maleick/Code-Archaeology?style=flat-square"></a>
+  <a href="docs/README.md"><img alt="Docs" src="https://img.shields.io/badge/docs-open-blue?style=flat-square"></a>
+  <a href="https://github.com/sponsors/Maleick"><img alt="Sponsor" src="https://img.shields.io/badge/sponsor-Maleick-fafbfc?style=flat-square&logo=github-sponsors"></a>
+</p>
+
+<p align="center">
+  <a href="#installation">Install</a> |
+  <a href="docs/README.md">Docs</a> |
+  <a href="https://github.com/Maleick/Code-Archaeology/wiki">Wiki</a> |
+  <a href="#commands">Commands</a> |
+  <a href="#safety-model">Safety</a> |
+  <a href="#release-docs">Release</a>
+</p>
+
+Excavate technical debt. Restore with confidence.
+
+Code Archaeology is a multi-runtime plugin that surveys, catalogs, and safely restores codebases by removing accumulated technical sediment in a fixed, test-gated expedition order. It runs on **OpenCode** (interactive slash commands) and **Hermes Agent** (cron-based background execution).
+
+```text
++---------------------------------------------------------------+
+| CODE ARCHAEOLOGY CAPABILITY PANEL                             |
++-------------------+-------------------------------------------+
+| Default mode       | survey: reports only, zero source edits   |
+| Review mode        | excavate: reports plus mock patches       |
+| Restore mode       | applies approved changes with test gates  |
+| Local state        | .archaeology/ runtime artifacts           |
+| Runtimes           | OpenCode plugin + Hermes Agent cron       |
+| Platforms          | macOS/Linux (bash) + Windows (PowerShell) |
+| Expedition order   | fixed stratigraphy from survey to catalog |
++-------------------+-------------------------------------------+
+```
 
-A systematic excavation plugin for OpenCode. Removes accumulated sediment from a codebase—dead code, legacy fallbacks, circular dependencies, weak types, and defensive programming slop—to restore the original architecture.
+## What It Does
 
-## ⚠️ Site Safety
+Code Archaeology runs a systematic excavation of a repository before it changes code. It inventories the site, identifies technical debt strata, writes reviewable reports, and only applies approved changes in `restore` mode.
 
-This plugin modifies code. By default it runs in **survey** mode, producing site reports only. Review these before switching to `restore` mode.
+- Catalogs dead code, unused exports, unreachable functions, and stale artifacts.
+- Removes legacy fallbacks, deprecated shims, and compatibility layers after review.
+- Maps circular dependencies before extraction or type consolidation work.
+- Consolidates duplicate type definitions only after dead code and legacy layers are removed.
+- Hardens weak types without guessing uncertain replacements.
+- Finds semantic duplication and error-handling slop while preserving I/O boundaries.
+- Produces `.archaeology/` reports that stay local to the working repository.
+- Supports both **OpenCode** interactive sessions and **Hermes Agent** cron-based phased execution.
 
-## Prerequisites
+## Installation
 
-- Git repo with clean working tree
-- Passing test suite (even if minimal)
-- Type checker / linter installed
-- `opencode` CLI available
+### OpenCode
 
-## Installation
+Paste this handoff into your agent:
+
+```text
+Run `npm pack opencode-code-archaeology@2.2.0`, extract the tarball, then open `package/INSTALL.md` from that archive and follow its instructions.
+```
+
+Recommended plugin install in `opencode.json`:
+
+```json
+{
+  "plugin": [
+    "opencode-code-archaeology@2.2.0"
+  ]
+}
+```
+
+Global npm install path:
 
 ```bash
-# As an OpenCode plugin
-npm install -g opencode-code-archaeology
+npm install -g opencode-code-archaeology@2.2.0 && opencode-code-archaeology install && opencode-code-archaeology doctor
+```
+
+One-time package runner path, if your OpenCode setup supports package execution through Bun:
 
-# Or clone and link
-git clone https://github.com/Maleick/Code-Archaeology.git
-cd Code-Archaeology
-npm link
+```bash
+bunx opencode-code-archaeology@2.2.0 install
+bunx opencode-code-archaeology@2.2.0 doctor
 ```
 
-## Usage
+### Hermes Agent
 
 ```bash
-# 1. Survey — catalog artifacts, zero changes
-opencode run code-archaeology --mode survey
+npm install -g opencode-code-archaeology@2.2.0
+cd ~/projects/Code-Archaeology
+bash hooks/hermes/setup.sh
+
+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."
+```
+
+See [`INSTALL.md`](INSTALL.md) for prerequisites, verification, updating, and troubleshooting.
+
+## Quick Start
 
-# 2. Review reports in .archaeology/
-cat .archaeology/expedition1-report.md
-# ... etc
+### OpenCode
 
-# 3. Restore high-confidence findings only
-opencode run code-archaeology --mode restore --strict_mode false
+Run the command family from inside the repository you want to inspect:
 
-# 4. Or restore medium+high confidence
-opencode run code-archaeology --mode restore --strict_mode true
+```text
+/code-archaeology
 ```
 
-## Parameters
+`/code-archaeology` runs the full 10-phase survey chain without per-phase prompts. It writes reports under `.archaeology/` and makes no source-code changes. Review the reports, then choose whether to generate mock patches or apply approved changes:
 
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `repo_path` | `.` | Target repository |
-| `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 |
-| `branch_name` | `refactor/archaeology` | Git branch to create |
+```text
+/code-archaeology-survey
+/code-archaeology-excavate
+/code-archaeology-restore
+```
 
-## Output Artifacts
+### Hermes Agent
 
-All artifacts are written to `.archaeology/`:
+Each cron run executes exactly **one** phase. The runner reads `.archaeology/session.json`, runs the current phase with verification, and advances to the next phase:
 
-- `site_survey.md` — baseline inventory and stratum graph
-- `expedition1-report.md` through `expedition8-report.md` — per-expedition findings
-- `FINAL_CATALOG.md` — completed excavation metrics and recommendations
-- `excavation_log.txt` — `git diff --stat`
+```bash
+bash hooks/hermes/runner.sh
+```
+
+Ten phases complete in ~2.5 hours minimum (15-minute intervals).
+
+## Runtime Surfaces
+
+| Feature | OpenCode | Hermes Agent |
+|---------|----------|--------------|
+| 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 |
+| Real-time | Yes | Delayed (15-min intervals) |
+
+## Expedition Flow
+
+```mermaid
+flowchart TD
+  A[Start] --> B[Site Survey and Baseline]
+  B --> C[Dead Code Excavation]
+  C --> D[Legacy Stratum Removal]
+  D --> E[Circular Dependency Cartography]
+  E --> F[Type Catalog Consolidation]
+  F --> G[Type Restoration and Hardening]
+  G --> H[DRY Stratification]
+  H --> I[Error Handling Stratigraphy]
+  I --> J[Artifact Cleaning and Documentation]
+  J --> K[Site Preservation and Final Catalog]
+```
+
+## Safety Model
+
+```mermaid
+flowchart LR
+  Survey[survey mode] --> Reports[write site reports]
+  Reports --> Review[human review]
+  Review --> Excavate[excavate mode: mock patches]
+  Review --> Restore[restore mode: approved changes]
+  Restore --> Verify[verify phase]
+  Verify -->|pass| Next[next expedition]
+  Verify -->|fail| Revert[revert phase and stop]
+```
 
-## Expedition Order (Fixed)
+- `survey` is the default and writes reports only.
+- `restore` modifies code and should run only after reports are reviewed.
+- `.archaeology/` is local runtime state and should not be committed.
+- Work is isolated to a configurable branch, `refactor/archaeology` by default.
+- Tests and type checks gate each restore phase.
+- Failed restore phases are reverted before the next expedition can proceed.
+- Try/catch blocks around I/O and external input boundaries are never removed automatically.
 
-The expeditions MUST run in this order due to stratigraphic dependencies:
+## Commands
+
+### OpenCode
+
+| Command | Purpose | File changes |
+| --- | --- | --- |
+| `/code-archaeology` | Run the full 10-phase survey chain without per-phase prompts. | None outside `.archaeology/`. |
+| `/code-archaeology-survey` | Generate site reports for review. | None outside `.archaeology/`. |
+| `/code-archaeology-excavate` | Generate reports and mock patches. | None outside `.archaeology/patches/`. |
+| `/code-archaeology-restore` | Apply approved high-confidence changes. | Yes, test-gated. |
+
+### Hermes Agent
+
+| OpenCode Equivalent | Hermes Mechanism | File changes |
+| --- | --- | --- |
+| `/code-archaeology` | `cronjob` runs expedition loop | Depends on mode |
+| `/code-archaeology-survey` | `mode = "survey"` in `session.json` | None outside `.archaeology/` |
+| `/code-archaeology-excavate` | `mode = "excavate"` in `session.json` | None outside `.archaeology/patches/` |
+| `/code-archaeology-restore` | `mode = "restore"` in `session.json` | Yes, test-gated |
+
+## Parameters
+
+| Parameter | Default | Description | Hermes Notes |
+| --- | --- | --- | --- |
+| `repo_path` | `.` | Target repository to excavate. | Set in `session.json` before first cron run. |
+| `language` | `typescript` | Primary language for tooling selection. | Same |
+| `mode` | `survey` | `survey`, `excavate`, or `restore`. | Change in `session.json` to switch modes. |
+| `strict_mode` | `false` | When true, restore may also apply medium-confidence findings. | Same |
+| `test_command` | `npm test` | Recorded session default only; verification hooks do not execute repository-local command values. Use `CODE_ARCHAEOLOGY_TEST_COMMAND` to approve an override for the current process. | Same |
+| `typecheck_command` | `npx tsc --noEmit` | Recorded session default only; verification hooks do not execute repository-local command values. Use `CODE_ARCHAEOLOGY_TYPECHECK_COMMAND` to approve an override for the current process. | Same |
+| `branch_name` | `refactor/archaeology` | Branch used for isolated restore work. | Same |
+
+## Expedition Order
+
+The expedition order is fixed because each layer depends on the previous excavation:
 
 1. Site Survey & Baseline
 2. Dead Code Excavation
@@ -78,51 +227,86 @@ The expeditions MUST run in this order due to stratigraphic dependencies:
 9. Artifact Cleaning & Documentation
 10. Site Preservation & Final Catalog
 
-**Why this order?** You cannot consolidate types before removing dead code (you might catalog code that should be discarded). You cannot DRY before untangling cycles (abstractions over cyclic deps create worse stratification).
+Do not consolidate types before dead code and legacy removal. Do not DRY code before dependency cycles are mapped.
 
-## Language-Specific Tooling
+## Language Tooling
 
 | Language | Dead Code | Dependencies | Types | DRY |
-|----------|-----------|--------------|-------|-----|
-| TypeScript | `knip`, `unimported` | `madge` | `tsc` | `jscpd` |
-| JavaScript | `knip`, `depcheck` | `madge` | N/A | `jscpd` |
+| --- | --- | --- | --- | --- |
+| TypeScript | `knip` | `madge` | `tsc` | `jscpd` |
+| JavaScript | `knip` | `madge` | N/A | `jscpd` |
 | Python | `vulture` | `pydeps` | `mypy` | `pylint` |
-| Go | `deadcode`, `staticcheck` | `godepgraph` | `go vet` | `golangci-lint` |
-| Rust | `cargo-udeps`, `rustc` | `cargo-deps` | `rustc` | `clippy` |
+| Go | `deadcode` | `godepgraph` | `go vet` | `golangci-lint` |
+| Rust | `cargo-udeps` | `cargo-deps` | `rustc` | `clippy` |
 
-If tools are missing, the skill falls back to AST-based manual analysis.
+If a preferred tool is missing, Code Archaeology falls back to AST-based manual analysis and flags uncertain findings for human review.
 
 ## Architecture
 
-```
+```text
 Code-Archaeology/
-├── src/              # TypeScript source (plugin entry, types)
-├── plugins/          # OpenCode plugin entry point
-├── skills/           # Agent skill definitions (SKILL.md)
-├── commands/         # CLI command documentation
-├── hooks/            # Shell scripts for expedition workflow
-├── prompts/          # Detailed expedition prompts
-├── schema/           # JSON schemas for reports
-├── AGENTS.md         # Agent runtime guide
-└── README.md         # This file
+|-- assets/             # README and repository visual assets
+|-- commands/           # OpenCode slash command definitions
+|-- dist/               # Built package output for GitHub-based installs
+|-- docs/               # Public docs and release notes
+|-- hooks/opencode/     # Init, verification, revert, and status hooks
+|-- hooks/hermes/       # Setup and runner hooks for Hermes Agent
+|-- plugins/            # Repo-local legacy plugin shim
+|-- prompts/            # Expedition prompts by phase
+|-- schema/             # JSON schemas for reports
+|-- skills/             # Code Archaeology skill definitions
+|   |-- code-archaeology/   # OpenCode skill
+|   `-- hermes/             # Hermes Agent skill and integration docs
+|-- src/                # TypeScript source
+|-- INSTALL.md          # Multi-runtime install handoff
+|-- README.md           # Public project overview
+`-- AGENTS.md           # Agent runtime guide
 ```
 
-## Development
+## Runtime Artifacts
+
+All expedition state is written to `.archaeology/` inside the target repository:
+
+| Artifact | Purpose |
+| --- | --- |
+| `session.json` | Current expedition progress and configuration. |
+| `site_survey.md` | Baseline inventory and stratum graph. |
+| `expedition1-report.md` through `expedition8-report.md` | Per-expedition findings. |
+| `FINAL_CATALOG.md` | Final excavation summary and recommendations. |
+| `excavation_log.txt` | `git diff --stat` for applied restoration work. |
+| `patches/` | Mock patches generated by `excavate` mode. |
+| `hermes-runtime.json` | Hermes runtime configuration (Hermes only). |
+
+## Local Testing
+
+For plugin development:
 
 ```bash
-# Install dependencies
 npm install
-
-# Build
 npm run build
-
-# Type check
 npm run typecheck
+npm pack --json --dry-run
+bash -n hooks/opencode/*.sh
+bash -n hooks/hermes/*.sh
+```
 
-# Verify package
-npm run verify:pack
+For a restore expedition, run the configured test and type-check commands between phases. The bundled verification hooks are:
+
+```bash
+# OpenCode
+bash hooks/opencode/verify-phase.sh final_verify
+
+# Hermes
+bash hooks/hermes/runner.sh
 ```
 
+## Release Docs
+
+- [`docs/README.md`](docs/README.md) is the documentation landing page.
+- [`docs/RELEASE.md`](docs/RELEASE.md) covers release preparation and publishing.
+- [`INSTALL.md`](INSTALL.md) is the raw handoff for multi-runtime installation.
+- [GitHub Releases](https://github.com/Maleick/Code-Archaeology/releases) lists published versions.
+
 ## License
 
-MIT
+MIT. See [`LICENSE`](LICENSE).

package/SECURITY.md

@@ -0,0 +1,20 @@
+# Security Policy
+
+## Reporting A Vulnerability
+
+Please report suspected vulnerabilities through a GitHub private security advisory for this repository. Do not open a public issue for vulnerabilities, secrets, private repository contents, or exploit details.
+
+Include the affected version or commit, a concise reproduction, expected impact, and any relevant sanitized logs. A maintainer will review the advisory and coordinate a fix before public disclosure.
+
+## Safety Model
+
+Code Archaeology is designed to inspect and improve repositories without surprising users:
+
+- `survey` is the default mode and produces reports without changing project files.
+- `excavate` produces reports and mock patches without applying changes.
+- `restore` can modify code only after review and should be run with tests or type checks available.
+- Failed restore phases should be reverted before continuing.
+- Runtime state is written to `.archaeology/` and should remain ignored and local.
+- Documentation and examples must not include secrets, tokens, credentials, or private code.
+
+The plugin must not remove try/catch blocks around I/O or external input boundaries automatically, and uncertain type replacements should be flagged for human review.

package/VERSION

@@ -1 +1 @@
-2.0.0
+2.2.0

package/assets/code-archaeology-banner.svg

@@ -0,0 +1,195 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 460" width="1200" height="460" role="img" aria-labelledby="title desc">
+  <title id="title">Code Archaeology — Multi-runtime Plugin</title>
+  <desc id="desc">Dark-themed archaeological excavation banner showing code strata layers, dual runtime badges for OpenCode and Hermes, and a 10-phase expedition indicator.</desc>
+
+  <defs>
+    <!-- Background gradient -->
+    <linearGradient id="bgGrad" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#0b1020"/>
+      <stop offset="1" stop-color="#1e293b"/>
+    </linearGradient>
+
+    <!-- Strata gradients -->
+    <linearGradient id="surfaceGrad" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#334155"/>
+      <stop offset="1" stop-color="#475569"/>
+    </linearGradient>
+    <linearGradient id="legacyGrad" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#78350f"/>
+      <stop offset="1" stop-color="#92400e"/>
+    </linearGradient>
+    <linearGradient id="bedrockGrad" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#1e1b4b"/>
+      <stop offset="1" stop-color="#312e81"/>
+    </linearGradient>
+
+    <!-- Glow filter for accents -->
+    <filter id="glow" x="-30%" y="-30%" width="160%" height="160%">
+      <feGaussianBlur stdDeviation="3" result="blur"/>
+      <feMerge>
+        <feMergeNode in="blur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+
+    <!-- Subtle grid pattern -->
+    <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
+      <path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5" opacity="0.3"/>
+    </pattern>
+  </defs>
+
+  <!-- Background -->
+  <rect width="1200" height="460" fill="url(#bgGrad)"/>
+  <rect width="1200" height="460" fill="url(#grid)"/>
+
+  <!-- Geological strata layers (left side, showing code layers) -->
+  <g transform="translate(60, 80)">
+    <!-- Surface layer -->
+    <path d="M0 0 L280 0 L260 55 L20 55 Z" fill="url(#surfaceGrad)" stroke="#64748b" stroke-width="1.5"/>
+    <text x="140" y="35" text-anchor="middle" font-family="SFMono-Regular, Consolas, monospace" font-size="14" fill="#94a3b8">Surface // Active Code</text>
+
+    <!-- Legacy layer -->
+    <path d="M20 55 L260 55 L240 115 L40 115 Z" fill="url(#legacyGrad)" stroke="#f97316" stroke-width="1.5" opacity="0.85"/>
+    <text x="140" y="92" text-anchor="middle" font-family="SFMono-Regular, Consolas, monospace" font-size="14" fill="#fdba74">Legacy // Deprecated Shims</text>
+
+    <!-- Bedrock layer -->
+    <path d="M40 115 L240 115 L220 180 L60 180 Z" fill="url(#bedrockGrad)" stroke="#6366f1" stroke-width="1.5" opacity="0.9"/>
+    <text x="140" y="155" text-anchor="middle" font-family="SFMono-Regular, Consolas, monospace" font-size="14" fill="#a5b4fc">Bedrock // Core Types</text>
+
+    <!-- Stratum divider lines -->
+    <line x1="290" y1="27" x2="340" y2="27" stroke="#64748b" stroke-width="1" stroke-dasharray="4 3"/>
+    <line x1="270" y1="85" x2="340" y2="85" stroke="#f97316" stroke-width="1" stroke-dasharray="4 3"/>
+    <line x1="250" y1="147" x2="340" y2="147" stroke="#6366f1" stroke-width="1" stroke-dasharray="4 3"/>
+  </g>
+
+  <!-- Archaeologist / excavation tools (right side) -->
+    <g transform="translate(980, 70)">
+    <!-- Brush -->
+    <rect x="15" y="0" width="12" height="70" rx="3" fill="#78350f" opacity="0.9"/>
+    <rect x="10" y="65" width="22" height="35" rx="4" fill="#d97706" opacity="0.9"/>
+    <line x1="21" y1="100" x2="21" y2="130" stroke="#d97706" stroke-width="3" stroke-linecap="round"/>
+
+    <!-- Trowel -->
+    <path d="M60 20 L75 20 L85 80 L50 80 Z" fill="#475569" stroke="#94a3b8" stroke-width="1.5"/>
+    <line x1="67" y1="80" x2="67" y2="130" stroke="#64748b" stroke-width="4" stroke-linecap="round"/>
+
+    <!-- Small artifacts / code fragments -->
+    <text x="-30" y="160" font-family="SFMono-Regular, Consolas, monospace" font-size="11" fill="#fbbf24" opacity="0.7">{ }</text>
+    <text x="10" y="175" font-family="SFMono-Regular, Consolas, monospace" font-size="10" fill="#f97316" opacity="0.6">// TODO</text>
+    <text x="45" y="155" font-family="SFMono-Regular, Consolas, monospace" font-size="9" fill="#a5b4fc" opacity="0.5">fn main()</text>
+  </g>
+
+  <!-- Wordmark -->
+  <g transform="translate(420, 105)">
+    <text x="0" y="0" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="56" font-weight="900" fill="#f8fafc" letter-spacing="-1">Code Archaeology</text>
+    <text x="2" y="42" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="20" font-weight="600" fill="#fbbf24">Excavate technical debt. Restore with confidence.</text>
+  </g>
+
+  <!-- Runtime badges -->
+  <g transform="translate(420, 185)">
+    <!-- OpenCode badge -->
+    <rect x="0" y="0" width="130" height="32" rx="8" fill="#0f172a" stroke="#38bdf8" stroke-width="1.5"/>
+    <circle cx="20" cy="16" r="5" fill="#38bdf8"/>
+    <text x="34" y="21" font-family="SFMono-Regular, Consolas, monospace" font-size="13" fill="#e0f2fe" font-weight="600">OpenCode</text>
+
+    <!-- Hermes badge -->
+    <rect x="150" y="0" width="120" height="32" rx="8" fill="#0f172a" stroke="#a78bfa" stroke-width="1.5"/>
+    <circle cx="170" cy="16" r="5" fill="#a78bfa"/>
+    <text x="184" y="21" font-family="SFMono-Regular, Consolas, monospace" font-size="13" fill="#ede9fe" font-weight="600">Hermes</text>
+
+    <!-- Multi-runtime label -->
+    <text x="290" y="21" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="14" fill="#94a3b8" font-weight="500">Multi-runtime plugin</text>
+  </g>
+
+  <!-- 10-phase indicator -->
+  <g transform="translate(420, 255)">
+    <text x="0" y="-10" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="12" fill="#64748b" font-weight="600" letter-spacing="2">10-PHASE EXPEDITION</text>
+
+    <!-- Phase boxes 1-10 -->
+    <g font-family="SFMono-Regular, Consolas, monospace" font-size="11" font-weight="700">
+      <!-- Phase 1 -->
+      <rect x="0" y="0" width="36" height="28" rx="5" fill="#0f172a" stroke="#38bdf8" stroke-width="1.5"/>
+      <text x="18" y="19" text-anchor="middle" fill="#e0f2fe">1</text>
+      <!-- Arrow -->
+      <text x="42" y="19" fill="#475569">→</text>
+
+      <!-- Phase 2 -->
+      <rect x="56" y="0" width="36" height="28" rx="5" fill="#0f172a" stroke="#38bdf8" stroke-width="1.5"/>
+      <text x="74" y="19" text-anchor="middle" fill="#e0f2fe">2</text>
+      <text x="98" y="19" fill="#475569">→</text>
+
+      <!-- Phase 3 -->
+      <rect x="112" y="0" width="36" height="28" rx="5" fill="#0f172a" stroke="#38bdf8" stroke-width="1.5"/>
+      <text x="130" y="19" text-anchor="middle" fill="#e0f2fe">3</text>
+      <text x="154" y="19" fill="#475569">→</text>
+
+      <!-- Phase 4 -->
+      <rect x="168" y="0" width="36" height="28" rx="5" fill="#0f172a" stroke="#38bdf8" stroke-width="1.5"/>
+      <text x="186" y="19" text-anchor="middle" fill="#e0f2fe">4</text>
+      <text x="210" y="19" fill="#475569">→</text>
+
+      <!-- Phase 5 -->
+      <rect x="224" y="0" width="36" height="28" rx="5" fill="#0f172a" stroke="#fbbf24" stroke-width="1.5"/>
+      <text x="242" y="19" text-anchor="middle" fill="#fef3c7">5</text>
+      <text x="266" y="19" fill="#475569">→</text>
+
+      <!-- Phase 6 -->
+      <rect x="280" y="0" width="36" height="28" rx="5" fill="#0f172a" stroke="#fbbf24" stroke-width="1.5"/>
+      <text x="298" y="19" text-anchor="middle" fill="#fef3c7">6</text>
+      <text x="322" y="19" fill="#475569">→</text>
+
+      <!-- Phase 7 -->
+      <rect x="336" y="0" width="36" height="28" rx="5" fill="#0f172a" stroke="#f97316" stroke-width="1.5"/>
+      <text x="354" y="19" text-anchor="middle" fill="#ffedd5">7</text>
+      <text x="378" y="19" fill="#475569">→</text>
+
+      <!-- Phase 8 -->
+      <rect x="392" y="0" width="36" height="28" rx="5" fill="#0f172a" stroke="#f97316" stroke-width="1.5"/>
+      <text x="410" y="19" text-anchor="middle" fill="#ffedd5">8</text>
+      <text x="434" y="19" fill="#475569">→</text>
+
+      <!-- Phase 9 -->
+      <rect x="448" y="0" width="36" height="28" rx="5" fill="#0f172a" stroke="#a78bfa" stroke-width="1.5"/>
+      <text x="466" y="19" text-anchor="middle" fill="#ede9fe">9</text>
+      <text x="490" y="19" fill="#475569">→</text>
+
+      <!-- Phase 10 -->
+      <rect x="504" y="0" width="42" height="28" rx="5" fill="#0f172a" stroke="#a78bfa" stroke-width="1.5"/>
+      <text x="525" y="19" text-anchor="middle" fill="#ede9fe">10</text>
+    </g>
+  </g>
+
+  <!-- Bottom info bar -->
+  <g transform="translate(420, 340)">
+    <rect x="0" y="0" width="560" height="42" rx="10" fill="#020617" opacity="0.72" stroke="#334155" stroke-width="1"/>
+    <text x="20" y="26" font-family="SFMono-Regular, Consolas, monospace" font-size="13" fill="#94a3b8">survey · excavate · restore · verify · dead code · legacy · cycles · types · DRY · errors</text>
+  </g>
+
+  <!-- Decorative particles / dust motes -->
+  <g opacity="0.4" fill="#fbbf24">
+    <circle cx="1100" cy="60" r="2"/>
+    <circle cx="1150" cy="120" r="1.5"/>
+    <circle cx="1080" cy="200" r="2.5"/>
+    <circle cx="1120" cy="280" r="1.8"/>
+    <circle cx="1160" cy="350" r="2"/>
+    <circle cx="1090" cy="400" r="1.5"/>
+    <circle cx="1140" cy="430" r="2"/>
+  </g>
+
+  <!-- Subtle excavation grid markers -->
+  <g opacity="0.15" stroke="#fbbf24" stroke-width="1" fill="none">
+    <rect x="50" y="70" width="300" height="200" rx="4"/>
+    <line x1="50" y1="130" x2="350" y2="130"/>
+    <line x1="50" y1="190" x2="350" y2="190"/>
+    <line x1="150" y1="70" x2="150" y2="270"/>
+    <line x1="250" y1="70" x2="250" y2="270"/>
+  </g>
+
+  <!-- Corner accent lines -->
+  <g opacity="0.3" stroke="#f97316" stroke-width="2" fill="none">
+    <path d="M0 0 L60 0 L0 60 Z" fill="#f97316" opacity="0.05"/>
+    <path d="M1140 0 L1200 0 L1200 60 Z" fill="#f97316" opacity="0.05"/>
+    <path d="M0 400 L0 460 L60 460 Z" fill="#f97316" opacity="0.05"/>
+    <path d="M1140 460 L1200 460 L1200 400 Z" fill="#f97316" opacity="0.05"/>
+  </g>
+</svg>

package/commands/code-archaeology.md

@@ -13,6 +13,8 @@ trigger:
 
 Excavate, catalog, and restore a codebase by removing accumulated sediment: dead code, legacy fallbacks, circular dependencies, weak types, and defensive programming slop. Produces human-reviewable site reports before any artifacts are disturbed. Non-destructive by default.
 
+By default, `/code-archaeology` runs the full 10-phase survey chain without stopping for a prompt between phases. It generates the complete report set in `.archaeology/` and makes zero source-code changes. To apply changes after review, use `/code-archaeology-restore` explicitly.
+
 ## Quick Start
 
 ```
@@ -36,7 +38,7 @@ Run: /code-archaeology
 
 | Command | Description |
 |---------|-------------|
-| `/code-archaeology` | Start full expedition (default: survey mode) |
+| `/code-archaeology` | Run the full 10-phase survey chain without per-phase prompts |
 | `/code-archaeology-survey` | Site survey only — zero file changes |
 | `/code-archaeology-excavate` | Generate reports + mock patches for review |
 | `/code-archaeology-restore` | Execute approved changes after review |
@@ -49,8 +51,8 @@ Run: /code-archaeology
 | `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 |
 
 ## Requirements
@@ -62,9 +64,9 @@ Run: /code-archaeology
 
 ## Safety
 
-- **Survey mode (default)**: Zero file changes. Only reports generated.
+- **Survey mode (default)**: Zero file changes. Runs every phase and generates the full report set.
 - **Excavate mode**: Mock patches for human review. No actual modifications.
-- **Restore mode**: Applies approved changes. Always runs tests between phases.
+- **Restore mode**: Applies approved changes only when explicitly requested with `/code-archaeology-restore`. Always runs tests between phases.
 - **Branch isolation**: All work happens on `refactor/archaeology` (configurable).
 - **Test gating**: Any phase that breaks tests is automatically reverted.
 

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map