opencode-code-archaeology 2.0.0 → 2.2.0

package/docs/README.md

@@ -0,0 +1,72 @@
+# Code Archaeology Documentation
+
+Excavate technical debt. Restore with confidence.
+
+Code Archaeology is a multi-runtime plugin for systematic codebase excavation, cataloging, and restoration. It supports both **OpenCode** (interactive slash commands) and **Hermes Agent** (cron-based background execution). It runs inside the target repository, writes local `.archaeology/` reports, and only modifies source files in `restore` mode after review and verification.
+
+The public landing page is [`index.html`](index.html). These Markdown files remain the detailed documentation source.
+
+## Quick Links
+
+- [Install Guide](INSTALL.md)
+- [Architecture](ARCHITECTURE.md)
+- [Release Process](RELEASE.md)
+- [Security Audit](SECURITY_AUDIT.md)
+- [Repository README](../README.md)
+- [Root Install Handoff](../INSTALL.md)
+- [Hermes Integration](../skills/hermes/INTEGRATION.md)
+- [Hermes Skill](../skills/hermes/README.md)
+
+## Quick Start
+
+### OpenCode
+
+Install the package globally, register the plugin, then verify the CLI:
+
+```bash
+npm install -g opencode-code-archaeology@2.2.0 && opencode-code-archaeology install && opencode-code-archaeology doctor
+```
+
+Or tell OpenCode:
+
+```text
+Fetch and follow the instructions in the installed package's INSTALL.md at $(npm root -g)/opencode-code-archaeology/INSTALL.md for opencode-code-archaeology@2.2.0
+```
+
+Restart OpenCode in the repository you want to inspect and start with the non-destructive default command:
+
+```text
+/code-archaeology
+```
+
+This runs the full 10-phase survey chain without per-phase prompts, writes reports under `.archaeology/`, and makes no source-code changes.
+
+Review `.archaeology/site_survey.md` and expedition reports before using:
+
+```text
+/code-archaeology-excavate
+/code-archaeology-restore
+```
+
+### Hermes Agent
+
+Setup the Hermes runtime and create a cronjob:
+
+```bash
+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 test/typecheck verification, advance to next phase. STOP after one phase."
+```
+
+Each cron run executes exactly **one** phase. Ten phases complete in ~2.5 hours minimum.
+
+## Safety Warning
+
+`/code-archaeology` defaults to survey mode and writes reports only. `excavate` mode writes reports and mock patches. `restore` mode can edit source files and should only run after report review, on an isolated branch, with tests or type checks available.
+
+Do not commit `.archaeology/`; it is local runtime state.

package/docs/RELEASE.md

@@ -0,0 +1,139 @@
+# Release Process
+
+This checklist is for future `opencode-code-archaeology` releases. `v2.1.0` is the current release example; replace it with the next version when preparing a new release.
+
+## 1. Preflight
+
+- Work from the release readiness branch or a dedicated release worktree.
+- Confirm the worktree has no unrelated changes you intend to publish accidentally.
+- Confirm no secrets or local runtime state are staged.
+- Review `README.md`, `INSTALL.md`, `docs/`, `wiki/`, `CHANGELOG.md`, and package metadata for version-specific claims.
+- Confirm `.archaeology/`, `.superpowers/`, `node_modules/`, and logs are ignored.
+
+## 2. Version Bump
+
+For a future release, replace `2.1.0` with the target version:
+
+```bash
+npm version 2.1.0 --no-git-tag-version
+```
+
+Update `VERSION` to the same value:
+
+```text
+2.1.0
+```
+
+Confirm `package.json`, `package-lock.json`, and `VERSION` agree.
+
+## 3. Changelog
+
+- Add a `v2.1.0` entry, or the future target version, to `CHANGELOG.md`.
+- Include user-visible changes, safety notes, and any migration instructions.
+- Keep the release notes factual and avoid claiming publication steps that have not happened yet.
+
+## 4. Verification
+
+Run focused release checks before committing:
+
+```bash
+npm install
+npm run build
+npm run typecheck
+npm audit --audit-level=moderate
+npm outdated --json
+bash -n hooks/opencode/*.sh
+bash -n hooks/hermes/*.sh
+npm pack --json --dry-run
+```
+
+Expected outcomes:
+
+- Build and typecheck pass.
+- npm audit reports no moderate-or-higher vulnerabilities.
+- npm outdated reports `{}` or no actionable outdated dependencies.
+- Shell hooks pass syntax checks (both OpenCode and Hermes).
+- The package dry run includes required files.
+
+## 5. npm Pack Required Files
+
+Inspect `npm pack --json --dry-run` output for the package contents. Required files should include:
+
+- `dist/`
+- `assets/`
+- `hooks/`
+- `commands/`
+- `skills/`
+- `schema/`
+- `prompts/`
+- `docs/`
+- `wiki/`
+- `AGENTS.md`
+- `VERSION`
+- `INSTALL.md`
+- `README.md`
+- `CHANGELOG.md`
+- `CONTRIBUTING.md`
+- `SECURITY.md`
+- `LICENSE`
+
+`plugins/` is intentionally repo-local and should not appear in npm package contents.
+
+If any required file is missing, update the `files` array in `package.json`, rerun `npm install` if the lockfile needs to change, and repeat the package dry run.
+
+## 6. Commit, Tag, And Push
+
+Only perform these steps after verification passes and after confirming the branch is safe to publish:
+
+```bash
+git status --short
+git add README.md INSTALL.md docs wiki assets .github SECURITY.md CONTRIBUTING.md CHANGELOG.md package.json package-lock.json VERSION .gitignore
+git commit -m "chore: prepare v2.1.0 release"
+git tag v2.1.0
+git push origin HEAD
+git push origin v2.1.0
+```
+
+For a future release, use the future version in the commit message and tag.
+
+## 7. GitHub Release
+
+Create the GitHub release from the matching tag:
+
+```bash
+gh release create v2.1.0 --title "v2.1.0" --notes-file CHANGELOG.md
+```
+
+Before publishing, trim the notes to the specific version section if `CHANGELOG.md` contains multiple releases.
+
+## 8. npm Publish
+
+Publishing is performed by `.github/workflows/release.yml` through npm trusted publishing. Configure npm Trusted Publisher with:
+
+- Publisher: `GitHub Actions`
+- Organization or user: `Maleick`
+- Repository: `Code-Archaeology`
+- Workflow filename: `release.yml`
+- Environment name: leave blank unless the workflow adds a GitHub Actions `environment`
+
+If publishing fails, do not create a replacement tag unless the failure requires a new package version. Fix the issue, rerun verification, and follow npm versioning rules.
+
+## 9. Final Checks
+
+Confirm the public release surfaces report the expected version:
+
+```bash
+npm view opencode-code-archaeology version
+npm view opencode-code-archaeology dist-tags
+gh release view v2.1.0
+```
+
+Optionally verify a fresh install path:
+
+```bash
+npm install -g opencode-code-archaeology@latest
+opencode-code-archaeology doctor
+opencode-code-archaeology version
+```
+
+Do not claim GitHub Pages is enabled unless repository settings confirm it.

package/docs/SECURITY_AUDIT.md

@@ -0,0 +1,38 @@
+# Security Audit Notes
+
+These notes capture the current release-readiness security posture for Code Archaeology. They are intended to accompany the release checklist and should be refreshed before each publication.
+
+## Current Findings
+
+- `npm audit --audit-level=moderate` is expected to be clean for the current dependency set.
+- `npm outdated --json` is expected to be clean for the current dependency set.
+- No hardcoded secrets are expected in source, docs, hooks, commands, prompts, schemas, or package metadata.
+- `.archaeology/` is local runtime state and is ignored by Git.
+- `.superpowers/` is local planning state and is ignored by Git.
+- Shell hooks in `hooks/opencode/` are syntax-checkable with `bash -n hooks/opencode/*.sh`.
+
+## Local State
+
+Code Archaeology writes operational state into `.archaeology/` in the target repository. This directory can contain project structure, findings, generated reports, mock patches, and restoration logs. It should stay local unless a maintainer intentionally extracts a report for review.
+
+## Restore-Mode Safety Caveat
+
+`restore` mode can modify source files. It should only run after `survey` reports are reviewed, preferably after `excavate` mock patches are reviewed, and only when the target repository has tests or type checks available. Failed restore phases should be reverted with the bundled revert hook before continuing.
+
+The tool must not remove try/catch blocks around I/O or external input boundaries automatically, and uncertain type replacements should be flagged for human review instead of guessed.
+
+## Release Checklist
+
+Before publishing a release:
+
+```bash
+npm install
+npm run build
+npm run typecheck
+npm audit --audit-level=moderate
+npm outdated --json
+bash -n hooks/opencode/*.sh
+npm pack --json --dry-run
+```
+
+Inspect the package dry run for required files and for accidental inclusion of local state. Do not publish if `.archaeology/`, `.superpowers/`, credentials, logs, or editor state appear in the package contents.