opencode-code-archaeology 2.0.0 → 2.0.2

package/README.md

@@ -1,71 +1,168 @@
-# Code Archaeology
+<h1 align="center">Code Archaeology</h1>
+
+<p align="center">
+  <img src="assets/code-archaeology-banner.svg" alt="Code Archaeology OpenCode plugin 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>
+
+Code Archaeology is an OpenCode plugin that surveys, catalogs, and safely restores codebases by removing accumulated technical sediment in a fixed, test-gated expedition order.
+
+```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           |
+| Runtime            | OpenCode plugin inside the target repo    |
+| 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.
 
-## Prerequisites
+## Installation
 
-- Git repo with clean working tree
-- Passing test suite (even if minimal)
-- Type checker / linter installed
-- `opencode` CLI available
+For OpenCode, paste this handoff into your agent:
 
-## Installation
+```text
+Fetch and follow instructions from https://raw.githubusercontent.com/Maleick/Code-Archaeology/refs/heads/main/INSTALL.md
+```
+
+Recommended plugin install in `opencode.json`:
+
+```json
+{
+  "plugin": [
+    "opencode-code-archaeology@git+https://github.com/Maleick/Code-Archaeology.git"
+  ]
+}
+```
+
+Global npm install path:
 
 ```bash
-# As an OpenCode plugin
 npm install -g opencode-code-archaeology
-
-# Or clone and link
-git clone https://github.com/Maleick/Code-Archaeology.git
-cd Code-Archaeology
-npm link
+opencode-code-archaeology install
+opencode-code-archaeology doctor
+opencode-code-archaeology version
 ```
 
-## Usage
+One-time package runner path, if your OpenCode setup supports package execution through Bun:
 
 ```bash
-# 1. Survey — catalog artifacts, zero changes
-opencode run code-archaeology --mode survey
+bunx opencode-code-archaeology install
+bunx opencode-code-archaeology doctor
+```
+
+See [`INSTALL.md`](INSTALL.md) for prerequisites, verification, updating, and troubleshooting.
 
-# 2. Review reports in .archaeology/
-cat .archaeology/expedition1-report.md
-# ... etc
+## Quick Start
 
-# 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
+Start non-destructively, 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
+```
+
+## Expedition Flow
+
+```mermaid
+flowchart TD
+  A[Start /code-archaeology] --> 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]
+```
+
+- `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.
 
-## Output Artifacts
+## Commands
 
-All artifacts are written to `.archaeology/`:
+| Command | Purpose | File changes |
+| --- | --- | --- |
+| `/code-archaeology` | Start the full expedition in the configured mode. | Depends on mode; defaults to none. |
+| `/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. |
 
-- `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`
+## Parameters
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `repo_path` | `.` | Target repository to excavate. |
+| `language` | `typescript` | Primary language for tooling selection. |
+| `mode` | `survey` | `survey`, `excavate`, or `restore`. |
+| `strict_mode` | `false` | When true, restore may also apply medium-confidence findings. |
+| `test_command` | `npm test` | Test command run by verification hooks. |
+| `typecheck_command` | `npx tsc --noEmit` | Type-check command run by verification hooks. |
+| `branch_name` | `refactor/archaeology` | Branch used for isolated restore work. |
 
-## Expedition Order (Fixed)
+## Expedition Order
 
-The expeditions MUST run in this order due to stratigraphic dependencies:
+The expedition order is fixed because each layer depends on the previous excavation:
 
 1. Site Survey & Baseline
 2. Dead Code Excavation
@@ -78,51 +175,77 @@ 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
+|-- plugins/            # OpenCode plugin entry point
+|-- prompts/            # Expedition prompts by phase
+|-- schema/             # JSON schemas for reports
+|-- skills/             # Code Archaeology skill definition
+|-- src/                # TypeScript source
+|-- INSTALL.md          # OpenCode 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. |
+
+## 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
+```
 
-# Verify package
-npm run verify:pack
+For a restore expedition, run the configured test and type-check commands between phases. The bundled verification hook is:
+
+```bash
+bash hooks/opencode/verify-phase.sh final_verify
 ```
 
+## 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 OpenCode 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.0.2

package/assets/code-archaeology-banner.svg

@@ -0,0 +1,66 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="900" height="300" viewBox="0 0 900 300" role="img" aria-labelledby="title desc">
+  <title id="title">Code Archaeology OpenCode Plugin</title>
+  <desc id="desc">Dark archaeology themed banner for the Code Archaeology OpenCode plugin.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#071018"/>
+      <stop offset="0.48" stop-color="#111827"/>
+      <stop offset="1" stop-color="#2a1809"/>
+    </linearGradient>
+    <linearGradient id="sand" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#c0843f"/>
+      <stop offset="0.5" stop-color="#e0b15b"/>
+      <stop offset="1" stop-color="#8b5a2b"/>
+    </linearGradient>
+    <linearGradient id="tablet" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#334155"/>
+      <stop offset="1" stop-color="#111827"/>
+    </linearGradient>
+    <filter id="glow" x="-30%" y="-30%" width="160%" height="160%">
+      <feGaussianBlur stdDeviation="4" result="blur"/>
+      <feMerge>
+        <feMergeNode in="blur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+
+  <rect width="900" height="300" fill="url(#bg)"/>
+  <path d="M0 222 C120 198 214 236 322 213 C452 186 549 216 672 194 C764 178 827 190 900 171 L900 300 L0 300 Z" fill="#20140b" opacity="0.92"/>
+  <path d="M0 244 C152 214 244 266 386 231 C505 202 626 242 744 210 C806 193 852 201 900 189 L900 300 L0 300 Z" fill="#2f1d0f"/>
+  <path d="M0 268 C138 246 267 281 405 258 C523 238 650 270 770 244 C827 232 865 232 900 222 L900 300 L0 300 Z" fill="url(#sand)" opacity="0.82"/>
+
+  <g opacity="0.35" stroke="#e0b15b" stroke-width="1" fill="none">
+    <path d="M41 96 H312"/>
+    <path d="M586 66 H852"/>
+    <path d="M640 103 H828"/>
+    <path d="M68 128 H242"/>
+  </g>
+
+  <g transform="translate(78 58)">
+    <path d="M74 8 L141 34 L116 146 L22 146 L0 35 Z" fill="url(#tablet)" stroke="#64748b" stroke-width="3"/>
+    <path d="M28 48 H103 M31 75 H111 M36 102 H91" stroke="#cbd5e1" stroke-width="6" stroke-linecap="round" opacity="0.72"/>
+    <path d="M95 138 L136 179" stroke="#d6a23f" stroke-width="12" stroke-linecap="round"/>
+    <path d="M126 169 L169 126" stroke="#d6a23f" stroke-width="12" stroke-linecap="round"/>
+    <path d="M138 120 C154 103 182 104 198 120 L169 149 Z" fill="#111827" stroke="#f6c453" stroke-width="6"/>
+    <circle cx="71" cy="31" r="9" fill="#f6c453" filter="url(#glow)"/>
+  </g>
+
+  <g transform="translate(300 70)">
+    <text x="0" y="43" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="46" font-weight="800" fill="#f8fafc" letter-spacing="1">Code Archaeology</text>
+    <text x="2" y="83" font-family="Inter, Segoe UI, Arial, sans-serif" font-size="20" font-weight="600" fill="#f6c453">OpenCode plugin for systematic codebase excavation</text>
+    <text x="2" y="122" font-family="SFMono-Regular, Consolas, Liberation Mono, monospace" font-size="15" fill="#cbd5e1">survey - excavate - restore - verify</text>
+    <g transform="translate(0 145)" font-family="SFMono-Regular, Consolas, Liberation Mono, monospace" font-size="13" fill="#94a3b8">
+      <rect x="0" y="0" width="455" height="42" rx="10" fill="#020617" opacity="0.72" stroke="#334155"/>
+      <text x="18" y="26">dead code | legacy | cycles | types | DRY | errors</text>
+    </g>
+  </g>
+
+  <g opacity="0.55" fill="#f6c453">
+    <circle cx="807" cy="54" r="2"/>
+    <circle cx="846" cy="93" r="1.8"/>
+    <circle cx="758" cy="120" r="1.5"/>
+    <circle cx="63" cy="39" r="1.5"/>
+    <circle cx="219" cy="48" r="2"/>
+  </g>
+</svg>

package/dist/cli.d.ts

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

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+const PLUGIN = "opencode-code-archaeology@git+https://github.com/Maleick/Code-Archaeology.git";
+const REQUIRED_FILES = [
+    "commands/code-archaeology.md",
+    "skills/code-archaeology/SKILL.md",
+    "hooks/opencode/init.sh",
+    "hooks/opencode/verify-phase.sh",
+    "AGENTS.md",
+    "README.md",
+    "INSTALL.md",
+];
+const cliFile = fileURLToPath(import.meta.url);
+const root = dirname(dirname(cliFile));
+function configPath() {
+    const configDir = process.env.OPENCODE_CONFIG_DIR || join(process.env.HOME || ".", ".config", "opencode");
+    return join(configDir, "opencode.json");
+}
+function backupPath(target) {
+    let candidate = `${target}.bak`;
+    let index = 1;
+    while (existsSync(candidate)) {
+        candidate = `${target}.bak.${index}`;
+        index += 1;
+    }
+    return candidate;
+}
+async function readPackageVersion() {
+    const packageJson = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+    return packageJson.version;
+}
+function printHelp() {
+    console.log(`Code Archaeology CLI
+
+Usage:
+  opencode-code-archaeology help
+  opencode-code-archaeology install
+  opencode-code-archaeology doctor
+  opencode-code-archaeology version
+
+Commands:
+  install   Add Code Archaeology to opencode.json plugin array
+  doctor    Verify core package files are present
+  version   Print the package version
+  help      Show this help`);
+}
+async function install() {
+    const target = configPath();
+    let config = {};
+    const exists = existsSync(target);
+    if (exists) {
+        config = JSON.parse(await readFile(target, "utf8"));
+    }
+    const plugins = Array.isArray(config.plugin) ? config.plugin : [];
+    if (!plugins.includes(PLUGIN)) {
+        config.plugin = [...plugins, PLUGIN];
+    }
+    await mkdir(dirname(target), { recursive: true });
+    let backup;
+    if (exists) {
+        backup = backupPath(target);
+        await copyFile(target, backup);
+    }
+    await writeFile(target, `${JSON.stringify(config, null, 2)}\n`);
+    console.log(`Updated ${target}`);
+    if (backup) {
+        console.log(`Backup written to ${backup}`);
+    }
+    console.log("Next steps:");
+    console.log("1. Restart OpenCode.");
+    console.log("2. Run /code-archaeology-survey in your target repository.");
+}
+function doctor() {
+    const missing = REQUIRED_FILES.filter((file) => !existsSync(join(root, file)));
+    if (missing.length > 0) {
+        console.error("Missing Code Archaeology package files:");
+        for (const file of missing) {
+            console.error(`- ${file}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    console.log("Code Archaeology package files present:");
+    for (const file of REQUIRED_FILES) {
+        console.log(`- ${file}`);
+    }
+}
+const command = process.argv[2] || "help";
+try {
+    if (command === "version") {
+        console.log(await readPackageVersion());
+    }
+    else if (command === "doctor") {
+        doctor();
+    }
+    else if (command === "install") {
+        await install();
+    }
+    else {
+        printHelp();
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/plugin.d.ts

@@ -0,0 +1,3 @@
+export { id, repoRoot, version, server, } from "./index.js";
+export type * from "./types.js";
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,EAAE,EACF,QAAQ,EACR,OAAO,EACP,MAAM,GACP,MAAM,YAAY,CAAC;AAEpB,mBAAmB,YAAY,CAAC"}

package/dist/plugin.js

@@ -0,0 +1,2 @@
+export { id, repoRoot, version, server, } from "./index.js";
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,EAAE,EACF,QAAQ,EACR,OAAO,EACP,MAAM,GACP,MAAM,YAAY,CAAC"}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,92 @@
+# Code Archaeology Architecture
+
+Code Archaeology is an OpenCode plugin that operates entirely inside the target repository. It coordinates slash commands, a domain skill, shell hooks, prompts, schemas, and local `.archaeology/` artifacts to run a fixed excavation workflow.
+
+## Repository Layout
+
+```text
+Code-Archaeology/
+|-- assets/             # README and repository visual assets
+|-- commands/           # OpenCode slash command definitions
+|-- dist/               # Built package output for GitHub-based installs
+|-- docs/               # Public documentation and release notes
+|-- hooks/opencode/     # Init, verification, revert, and status hooks
+|-- plugins/            # OpenCode plugin entry point
+|-- prompts/            # Expedition prompts by phase
+|-- schema/             # JSON schemas for reports
+|-- skills/             # Code Archaeology skill definition
+|-- src/                # TypeScript package and CLI source
+|-- wiki/               # Source pages for GitHub Wiki publication
+|-- INSTALL.md          # Root install handoff
+|-- README.md           # Public project overview
+`-- AGENTS.md           # Agent runtime guide
+```
+
+## OpenCode Plugin Surfaces
+
+- `plugins/` exposes the plugin entry point consumed by OpenCode.
+- `commands/` defines the slash command family: `/code-archaeology`, `/code-archaeology-survey`, `/code-archaeology-excavate`, and `/code-archaeology-restore`.
+- `skills/` contains the domain workflow instructions agents follow during an expedition.
+- `hooks/opencode/` provides shell gates for session setup, verification, rollback, and status updates.
+- `prompts/` and `schema/` provide phase-specific guidance and artifact structure.
+- `src/` builds the npm package and CLI used by `opencode-code-archaeology install`, `doctor`, and `version`.
+
+## Commands, Skills, And Hooks
+
+Commands are the user-facing entry points. A command selects the mode and starts the archaeology workflow in the target repository.
+
+The Code Archaeology skill defines the expedition order, safety constraints, language-tool preferences, and reporting expectations. It is the agent-facing control layer that prevents phases from running out of order.
+
+Hooks are the shell-level enforcement layer:
+
+- `init.sh` initializes `.archaeology/` and session state.
+- `verify-phase.sh <phase>` runs configured tests and type checks between phases.
+- `revert-phase.sh <phase>` reverts changes when a restore phase fails verification.
+- `update-expedition.sh <phase> <status> [findings]` updates session progress.
+
+## Expedition Flow
+
+The phase order is fixed because later cleanup depends on earlier evidence:
+
+1. Site Survey & Baseline
+2. Dead Code Excavation
+3. Legacy Stratum Removal
+4. Circular Dependency Cartography
+5. Type Catalog Consolidation
+6. Type Restoration & Hardening
+7. DRY Stratification
+8. Error Handling Stratigraphy
+9. Artifact Cleaning & Documentation
+10. Site Preservation & Final Catalog
+
+`survey` mode writes reports only. `excavate` mode writes reports plus mock patches. `restore` mode applies approved changes and must pass verification between phases.
+
+## Artifact Lifecycle
+
+Runtime artifacts live in `.archaeology/` inside the target repository:
+
+| Artifact | Purpose |
+| --- | --- |
+| `session.json` | Current expedition progress and configuration. |
+| `site_survey.md` | Baseline inventory and site report. |
+| `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. |
+
+`.archaeology/` is ignored local state and should not be committed.
+
+## Safety Gates
+
+- Default to `survey` mode for reports only.
+- Write a site report before removing or modifying code.
+- Never consolidate types before dead code and legacy removal.
+- Never remove try/catch blocks from I/O or external input boundaries automatically.
+- Flag uncertain type replacements for human review instead of guessing.
+- Run `verify-phase.sh` between restore phases.
+- Run `revert-phase.sh` and stop if a phase introduces test failures.
+- Keep restore work isolated to the configured branch, `refactor/archaeology` by default.
+
+## Local State
+
+The plugin keeps operational state in the target repository, not in a remote service. This makes expeditions reviewable and reproducible, but maintainers must keep `.archaeology/` out of commits and inspect generated reports before applying restore changes.