opencode-worktree-guardian 0.1.0

package/docs/adr/0001-guardian-safety-policy.md

@@ -0,0 +1,192 @@
+# ADR 0001: Guardian Safety Policy
+
+## Status
+
+Accepted.
+
+## Context
+
+Guardian protects multi-session Git worktree workflows by routing normal work into owned worktrees and by requiring native, token-gated tools for destructive or lifecycle operations. This policy records the canonical safety contract for public Guardian surfaces.
+
+This document is the authority for block, allow, route, plan/apply, confirmation, and deletion posture. README, skills, slash commands, packaged markdown commands, and Codex adapter docs are discoverability surfaces and must summarize or point here instead of defining a conflicting policy.
+
+## Policy Authority And Public Surfaces
+
+The public native tools are:
+
+- `guardian_start`
+- `guardian_status`
+- `guardian_recover`
+- `guardian_report_html`
+- `guardian_done`
+- `guardian_finish`
+- `guardian_finish_workflow`
+- `guardian_preserve`
+- `guardian_unblock_finish`
+- `guardian_delete_worktree`
+- `guardian_delete_paths`
+- `guardian_hygiene`
+
+OpenCode slash commands and packaged `commands/*.md` wrappers are prompt surfaces only. They must instruct the agent to use the matching native tool and must not authorize raw shell cleanup, raw worktree removal, stash mutation, raw branch deletion, force-push, protected-branch bypasses, or deletion outside Guardian preflights.
+
+The Codex adapter is also a first-class public surface. It must invoke the same Guardian tool policies through the adapter CLI and hooks, not through raw destructive Git or shell commands.
+
+## Raw Destructive Git And Shell Blocks
+
+Guardian blocks raw destructive shell and Git commands in `tool.execute.before`. Blocked command classes include:
+
+- hard reset and forced clean,
+- raw worktree removal or prune,
+- raw `git worktree add` outside Guardian-owned roots,
+- raw branch deletion,
+- stash mutation,
+- force push,
+- destructive checkout, restore, or switch forms,
+- shell-wrapped variants and context-mode code payloads,
+- `rm -rf` against known Guardian worktrees.
+
+Agents must use Guardian-native tools for lifecycle and deletion work. A prompt, slash command, skill, or adapter invocation cannot override these blocks.
+
+## Read-Only And Normal Safe Git Allowances
+
+Read-only inventory and recovery surfaces are allowed through `guardian_status`, `guardian_recover`, and `guardian_hygiene` without `mode`. Their output is evidence only and does not authorize cleanup.
+
+When a session owns a valid Guardian worktree, normal safe mutating commands such as `git add` and `git commit` may proceed through Guardian routing. Without recorded ownership, normal non-destructive commands may run in the current worktree, but destructive cleanup, reset, stash, force-push, worktree-removal, and protected-branch bypass guards still apply.
+
+## `guardian_start` Session And Worktree Ownership
+
+Guardian owns a session worktree after the chat-system hook creates or attaches one, unless repo config disables automatic ownership with `autoStart: false`. `guardian_start` is the explicit path to create or attach ownership before the hook has run.
+
+Ownership is proven by Guardian state or by token-bound target resolution, not by branch prefix alone. Explicit descriptive branch names are allowed when state or a token-bound target proves the exact branch/worktree binding.
+
+If older or corrupted state records an active session on the primary repo worktree or a protected branch, `guardian_start` with `createWorktree: true` is the repair path. It creates a fresh Guardian worktree, overwrites the poisoned binding, and leaves the primary worktree untouched. Without allowed worktree creation, Guardian must block rather than return the bad binding.
+
+## Session Routing And Mismatch Fail-Closed Rules
+
+Guardian hooks do not move the OpenCode host process cwd. Before safe shell or Git tools run, Guardian rewrites the execution directory to the recorded worktree and then reapplies destructive-command guards.
+
+Direct file mutation tool paths under the primary repo are rewritten into the recorded worktree when the session owns one. They are blocked when the recorded worktree cannot be validated. Missing, unresolvable, unrecorded, stale, primary-worktree, or protected-branch session bindings fail closed.
+
+## Protected Branch Bypass Prevention
+
+Protected branches include the configured `protectedBranches`, with defaults including `main`, `master`, `develop`, and `production`.
+
+When config context is available, Guardian blocks manual bypasses such as pushing `HEAD` or `guardian/*` directly to a protected branch, and merging `guardian/*` while already on a protected branch. Normal Guardian work must finish through `guardian_done` or the lower-level finish tools. A command wrapper must not ask the agent to bypass this policy with raw push, merge, switch, or branch commands.
+
+## `guardian_done` Implementation-Done Policy
+
+`guardian_done` is the user-facing implementation-done workflow. Run `mode: "plan"` first and inspect the selected lane, preflight facts, dirty files, blockers, and confirmation posture.
+
+The supported lanes are:
+
+- `session-finish`: delegates recorded session worktrees to `guardian_finish`.
+- `cleanup-only`: routes clean primary-base cleanup through `guardian_finish_workflow`.
+- `primary-main-publish`: handles dirty protected primary `baseBranch` work only with an explicit `commitMessage`, explicit confirmation, and the matching internally token-bound dirty snapshot.
+
+Primary-main apply creates a pre-commit safety ref, commits only token-bound dirty paths, pushes normally to the configured remote/base branch, fetches, proves remote reachability, and returns a separate cleanup plan. It must not silently apply cleanup, force-push, mutate stashes, delete remote branches, merge PRs, or treat old primary/protected session records as ownership.
+
+In plugin flow, the internal plan token may be cached and reused only when session, repo, options, and dirty snapshot still match the plan. Blank token values and confirmation placeholders are treated as absent.
+
+## `guardian_finish` Session Finish Policy
+
+Use `guardian_finish` for explicit low-level session finishing. Prefer `guardian_done` for normal completion.
+
+Finish always creates a safety ref before risky operations and reports preflight facts and blockers. Dirty worktrees block finish unless every dirty path matches explicit `allowDirtyPaths` config. Allowed dirty paths are reported as `allowedDirtyFiles` and left untouched. Guardian must not delete, stash, revert, stage, or commit allowed dirty files.
+
+`create-pr` pushes the session branch and suggests a PR command; it does not create a PR natively. `merge-to-base` requires explicit approval. Cleanup can run only when `autoCleanup` or `allowCleanup` is enabled and ancestry is proven.
+
+## `guardian_finish_workflow` Cleanup Policy
+
+Use `guardian_finish_workflow` only after implementation is already committed, pushed, merged to the configured base, and synced locally.
+
+Run `mode: "plan"` first. The workflow verifies the primary worktree is clean, stash policy is satisfied, the configured remote can be fetched, and redundant cleanup candidates are already merged to the freshly resolved `remote/baseBranch` commit. It discovers Guardian-root worktrees and non-protected, checked-out-nowhere local branches whose heads are ancestors of that base commit. At most 25 cleanup candidates can be applied from one plan.
+
+Run `mode: "apply"` only with the returned token after explicit confirmation. The token binds the resolved base commit and cleanup targets. Apply re-plans each target and delegates deletion to `guardian_delete_worktree`. It must not create commits, choose commit messages, merge protected branches, mutate stashes, force-delete branches, or run raw filesystem/Git cleanup. Any blocker fails closed and apply deletes nothing until a fresh plan has no blockers.
+
+## `guardian_preserve` Policy
+
+`guardian_preserve` marks the current Guardian-owned session terminal/preserved and creates a preserved ref. It does not delete, clean, reset, stash, push, or merge.
+
+Preservation is not a permanent retention instruction. Preserved worktrees remain cleanup-eligible through `guardian_delete_worktree` once that tool proves deletion is safe.
+
+## `guardian_unblock_finish` Policy
+
+Use `guardian_unblock_finish` only when `guardian_finish` is blocked by narrow generated review-rating artifacts. It is not a broad cleanup or source-change commit tool.
+
+Run `mode: "plan"` first. The supported action is `commit-review-artifacts`, which may commit only `.milestones/reviews/*impl-rating-YYYYMMDD.md` or `.milestones/reviews/*impl-rating-YYYYMMDD.txt` review artifacts. If Guardian state does not record the session, plan must receive an explicit `branch` or `worktreePath` that resolves exactly one checked-out worktree under the configured Guardian worktree root.
+
+Run `mode: "apply"` only with the fresh token and the same explicit branch or worktree path when state is still missing. Apply creates a safety ref, stages only approved review artifacts, commits them, and updates Guardian state. It refuses mixed dirty/source paths, renames/copies, symlink artifacts, deletions, ignored files, stashes, and cleanup.
+
+## `guardian_delete_worktree` Worktree Deletion Policy
+
+Use `guardian_delete_worktree` for stale, preserved, finished, orphaned, or explicitly abandoned Guardian worktree cleanup. Raw `git worktree remove`, `git worktree prune`, raw branch deletion, and filesystem deletion are forbidden substitutes.
+
+Run `mode: "plan"` first. It resolves exactly one target by `targetPath`, `sessionId`, or `branch`, runs preflight checks, and returns a confirm token. Run `mode: "apply"` only with that token and the same options after explicit confirmation.
+
+Apply recomputes the token from the normalized repo root, target kind, target path, worktree-listed state, branch or detached marker, HEAD, session identity/status, `deleteBranch`, `abandonUnmerged`, ancestry evidence, unmerged commits, and `allowIgnoredFiles`. Stale or missing tokens block.
+
+Apply refuses primary repo worktree deletion, current execution worktree deletion, dirty or untracked targets, protected-branch worktrees even when `deleteBranch` is false, detached HEADs, ignored files unless `allowIgnoredFiles: true` is present in both plan and apply, and repo stashes unless `allowStashIfUnrelated` is enabled. Passing the primary repo as `targetPath` remains blocked.
+
+Apply creates a safety ref before non-force `git worktree remove <path>`. Branch deletion is opt-in with `deleteBranch: true`; by default it requires ancestry proof and uses non-force `git branch -d`.
+
+## `guardian_delete_worktree` Orphan And Stale-Branch Policy
+
+If a recorded Guardian session's worktree path is absent from `git worktree list`, or state points at the primary repo path while the recorded Guardian branch is checked out nowhere, `guardian_delete_worktree` can perform branch-only orphan cleanup with `deleteBranch: true`. It deletes no filesystem path, does not allow primary repo worktree deletion, verifies the branch exists, verifies it is checked out nowhere, verifies it is not protected, creates a safety ref, and uses non-force branch deletion after ancestry and checkout checks pass.
+
+If a local Guardian branch remains after its worktree and active state are gone, pass the exact `branch` or terminal `sessionId` with `deleteBranch: true` for stale-branch cleanup. Terminal states include `deleted`, `abandoned`, `finished`, and `preserved`. This branch-only path is allowed only when terminal Guardian state or matching `refs/opencode-guardian` safety refs prove ownership. Branch prefixes alone are not ownership proof.
+
+## `guardian_delete_worktree` Unmerged Abandon Policy
+
+Intentional unmerged local abandonment requires `deleteBranch: true` and `abandonUnmerged: true` in both plan and apply. Plan reports ancestry evidence, the base ref, and unmerged commits that remain recoverable from the safety ref.
+
+Apply creates the safety ref first, then removes the clean Guardian worktree and deletes the local branch, recording the session as `abandoned`. This lane does not relax primary/current worktree, dirty-target, protected-branch, checked-out orphan branch, stale-token, stash, ignored-file, or missing-safety-ref blockers.
+
+## `guardian_delete_paths` Exact Path Deletion Policy
+
+Use `guardian_delete_paths` when the user intentionally wants to delete exact files or directories that are not Guardian hygiene findings, including source files.
+
+Run `mode: "plan"` first with explicit `paths`. The plan reports each path's repo-relative path, absolute path, kind, tracked/ignored/untracked status, tracked contents, and blockers. Apply only after explicit confirmation with `mode: "apply"` and `confirmDelete: true`; low-level direct calls also require the matching `confirmToken`.
+
+Tracked source deletion requires `allowTracked: true`. Directory deletion requires `allowRecursive: true`. Worktree deletion must use `guardian_delete_worktree`, not `guardian_delete_paths`.
+
+The tool blocks paths outside the repo, the repo root, `.git`, `.opencode`, dependency roots such as `node_modules` and `vendor`, configured or registered Guardian worktree roots, the current worktree root, missing paths, symlink roots, overlapping selections, tracked contents without `allowTracked: true`, and directories without `allowRecursive: true`.
+
+Apply re-runs the same fingerprinted preflight immediately before deletion, deletes files with internal Node `fs` APIs, and does not stage changes. Tracked deletions remain visible in `git status` for review and commit.
+
+## `guardian_hygiene` Scan Policy
+
+`guardian_hygiene` without `mode` is report-only. It detects untracked or ignored scratch artifacts, nested Git repositories, suspicious research dumps, generated cache roots, and protected exclusions. Scan output does not authorize deletion.
+
+`guardian_status`, `guardian_recover`, and `guardian_hygiene` scan output are evidence-only surfaces. Research clones, downloaded upstream repos, generated fixtures, and temporary test data should live outside the active project tree, preferably under OS temp space such as `$TMPDIR/opencode/<repo>/<session>/`.
+
+## `guardian_hygiene` Plan/Apply Cleanup Policy
+
+`guardian_hygiene` is the single hygiene scan/plan/apply surface. Use `mode: "plan"` before cleanup; inspect exact approved targets, blockers, and summary; then get explicit user confirmation. Apply with `mode: "apply"` and `confirmDelete: true` using the same cleanup options.
+
+Default cleanup includes current hygiene finding categories: known scratch artifacts, clean nested Git repositories, suspicious residue roots, generated `node-compile-cache/`, `node-coverage-*`, and `tsx-<digits>/` cache roots. Dirty `nested-git` findings require explicit `allowDirtyNestedGit: true`.
+
+The plugin tool flow caches the plan token only for matching session, repo, and options. Empty token values and `CONFIRM_DELETE` placeholders are treated as absent; the cached token may be injected only when the plan matches. Low-level direct calls to `guardianHygiene` still require the matching `confirmToken`.
+
+Apply re-runs preflight and removes only token-bound approved paths using internal Node `fs` APIs. It never suggests or shells out to broad cleanup commands. Cleanup blocks tracked files, protected directories, configured or registered Guardian worktrees, paths outside the repo root, `.git`, symlink cleanup roots, missing selected paths, stale fingerprints, and selected roots with unexpected tracked contents.
+
+## Stale Tokens, Fingerprints, And Safety Ref Posture
+
+Plan output is evidence, not approval. Apply must bind to the current preflight state through a fresh confirm token, cached internal token, or fingerprint appropriate to that tool surface.
+
+Tokens and fingerprints must cover the target identity and safety-relevant options. Apply must re-run preflight and block when token data is stale, missing, mismatched, or derived from a different repo, session, dirty snapshot, base commit, path list, target, or cleanup option set.
+
+Safety refs are required before risky finish, preserve, deletion, orphan cleanup, stale-branch cleanup, explicit unmerged abandon, and finish-unblock operations. Safety refs are recovery evidence; they do not authorize raw cleanup or bypass plan/apply gates.
+
+## Codex Adapter Hook Policy
+
+The Codex adapter must route Guardian workflows through `codex/hooks/guardian-hook.ts` in this source repository, or through `node_modules/opencode-worktree-guardian/codex/hooks/guardian-hook.ts` after package install. Codex plugin hooks invoke the same adapter from `hooks/hooks.json`.
+
+For `guardian done`, `guardian_hygiene`, `guardian_delete_paths`, and `guardian_finish_workflow`, Codex usage must run plan first and apply only after explicit user confirmation with the same options. The adapter may reuse matching cached internal plan tokens and must not ask users to copy internal confirm tokens.
+
+The Codex adapter must never replace Guardian workflows with raw `git reset --hard`, `git clean -fd`, `git worktree remove`, `git worktree prune`, `git branch -D`, `git stash drop`, `git stash clear`, force-push, broad filesystem deletion, or protected-branch bypass commands.
+
+## Legacy Alias Deprecation And Removal Policy
+
+Legacy command or tool aliases that overlap a current safety surface must be removed only as an intentional public-surface change. Removal must update native tool registries, slash command rewrites, TUI commands, packaged markdown commands, README, skills, package smoke expectations, and contract tests.
+
+Removed aliases must not remain documented as active commands. Historical notes may mention them only as removed or deprecated legacy surfaces. The current hygiene cleanup authority is `guardian_hygiene` with scan, plan, and apply modes; there is no separate active hygiene cleanup alias.

package/docs/publishing.md

@@ -0,0 +1,55 @@
+# Publishing Policy
+
+This project publishes only from an intentional release branch after the release checklist passes. Do not run `npm publish` from routine development or remediation tasks.
+
+## Versioning Policy
+
+- The package uses semver.
+- Patch versions are for compatible fixes, documentation updates shipped with the package, and release-process corrections.
+- Minor versions are for new compatible public Guardian surfaces, new host or adapter support, or substantial safety-policy additions.
+- Major versions are for breaking public-surface changes, removed commands or tools, changed confirmation semantics, changed package exports, or changed host requirements.
+- `package.json` is the source of the package version being prepared. `CHANGELOG.md` records public-surface changes but must not claim the version has been published until publication has happened.
+
+Before publishing, update the version intentionally with npm's versioning flow or another explicit semver change. Do not change the version as a side effect of unrelated work.
+
+## What Must Be True Before Publishing
+
+- `docs/release-checklist.md` has been completed.
+- `npm run test:readiness` exits 0.
+- `npm audit --registry=https://registry.npmjs.org --omit=dev --audit-level=low` exits 0.
+- `npm pack --dry-run --json` has been inspected and contains only intended package files.
+- OpenCode host smoke and manual disposable-repo host QA have passed.
+- Codex adapter tests and manual disposable-repo adapter QA have passed.
+- The README, safety policy, OpenCode skill docs, Codex skill docs, and packaged command docs agree on the same public surface.
+- `CHANGELOG.md` has a dated section for the version being published, moved from `Unreleased`, with no claim that the version shipped before the publish actually happens.
+- The worktree is clean except for intentional release changes.
+
+## npm Publish Notes
+
+Use npm's dry run before publication:
+
+```bash
+npm pack --dry-run --json
+```
+
+Use npm publish only after the dry-run package contents and release checklist are accepted:
+
+```bash
+npm publish --access public
+```
+
+Do not publish if the package includes local evidence files, `.omo/`, `.milestones/`, `.worktrees/`, generated caches, test output, or untracked scratch data.
+
+If publication fails after a version bump or tag was created locally, do not reuse ambiguous state. Record the failure, inspect npm and git state, and either retry the same unchanged artifact when safe or prepare a new patch version.
+
+## Commit And Tag Policy
+
+- The release commit should contain the version bump, changelog entry, and any release-only documentation updates.
+- Tag only the commit that was actually published.
+- Use an annotated git tag named `v<version>`, for example `v0.1.0`.
+- Push the tag only after `npm publish` succeeds for the same version.
+- If `npm publish` has not succeeded, do not create or push a release tag that implies the package is public.
+
+## Post-Publish Checks
+
+After publish, verify the package metadata and install path from npm, then update release notes if the project uses GitHub releases. Do not backfill the changelog with unverifiable claims; record only what was actually published and tagged.

package/docs/release-checklist.md

@@ -0,0 +1,84 @@
+# Release Checklist
+
+Use this checklist before any public package publication. Run it from the repository root on a clean release branch.
+
+## Preconditions
+
+- `package.json` names the intended package, version, exports, files, scripts, engines, repository, license, and `prepublishOnly` policy.
+- `CHANGELOG.md` has an `Unreleased` section and does not claim a version has shipped before publication.
+- `README.md`, `docs/adr/0001-guardian-safety-policy.md`, OpenCode command docs, OpenCode skill docs, and Codex adapter docs describe the same public tool surface.
+- The worktree contains only intentional release changes.
+- No `npm publish` command has been run from this checklist.
+
+## Required Commands
+
+```bash
+npm run test:readiness
+npm audit --registry=https://registry.npmjs.org --omit=dev --audit-level=low
+npm pack --dry-run --json
+```
+
+The release is blocked if any required command exits non-zero, reports a dependency audit issue at or above the configured audit level, or shows an unexpected package file list.
+
+## Package Dry-Run Inspection
+
+Inspect `npm pack --dry-run --json` output and confirm the package includes the expected public assets:
+
+- `README.md`
+- `LICENSE`
+- `CHANGELOG.md`
+- `commands/`
+- `skills/`
+- `src/`
+- `scripts/`
+- `codex/`
+- `docs/`
+
+Confirm the output does not include local evidence files, worktree state, test logs, untracked scratch directories, or generated caches.
+
+## OpenCode Host Check
+
+Run the deterministic host smoke before manual host validation:
+
+```bash
+npm run test:smoke:host
+```
+
+For manual QA, use a disposable Git repository only:
+
+1. Install or shim the release candidate into the disposable repo.
+2. Start OpenCode from that disposable repo.
+3. Confirm the Guardian plugin loads and exposes `guardian_status`.
+4. Confirm `guardian_status` returns repository inventory.
+5. Confirm a safe Git write is routed into the Guardian-owned worktree when ownership exists.
+6. Confirm a raw destructive command such as `git reset --hard` is blocked before mutation.
+
+Do not validate manual OpenCode behavior against a live project repository.
+
+## Codex Adapter Check
+
+Run the Codex adapter smoke coverage before publication:
+
+```bash
+npm run test -- test/codex-adapter.test.ts test/package-smoke.test.ts
+```
+
+Then inspect `npm pack --dry-run --json` output and confirm the packed package contains:
+
+- `codex/.codex-plugin/plugin.json`
+- `codex/hooks/hooks.json`
+- `codex/hooks/guardian-hook.ts`
+- `codex/skills/worktree-guardian/SKILL.md`
+
+For manual QA, invoke the adapter only in a disposable Git repository. Confirm `guardian_status` returns readable output and the pre-tool hook blocks a raw destructive command such as `git reset --hard`.
+
+## Final Gate
+
+Publish only when:
+
+- all required commands pass,
+- OpenCode host smoke and manual host checks pass,
+- Codex adapter tests and manual adapter checks pass,
+- `npm pack --dry-run --json` contains exactly the intended public package surface,
+- `CHANGELOG.md` has been updated for the release without inventing unpublished history,
+- the git tag and package version policy in `docs/publishing.md` is satisfied.

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "opencode-worktree-guardian",
+  "version": "0.1.0",
+  "description": "OpenCode plugin that guards Git worktree workflows from unsafe cleanup, reset, stash, and force-push operations.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./codex": "./codex/hooks/guardian-hook.ts",
+    "./server": "./src/index.ts",
+    "./tui": "./src/tui.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "codex",
+    "commands",
+    "docs",
+    "src",
+    "scripts",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node scripts/with-safe-node-temp.mjs -- node --import tsx --test test/*.test.ts",
+    "lint": "npm run typecheck",
+    "typecheck": "tsc --noEmit",
+    "coverage": "node scripts/with-safe-node-temp.mjs -- node --import tsx --test --experimental-test-coverage --test-coverage-lines=80 test/*.test.ts",
+    "verify": "npm run lint && npm run coverage",
+    "audit:deps": "npm audit --registry=https://registry.npmjs.org --omit=dev",
+    "test:contract": "node scripts/with-safe-node-temp.mjs -- node --import tsx --test test/plugin-contract.test.ts test/index.test.ts",
+    "test:smoke:package": "node scripts/with-safe-node-temp.mjs -- node --import tsx --test test/package-smoke.test.ts",
+    "test:smoke:host": "node scripts/with-safe-node-temp.mjs -- node --import tsx --test test/opencode-host-smoke.test.ts",
+    "test:readiness": "node scripts/with-safe-node-temp.mjs -- node --import tsx scripts/readiness.ts",
+    "prepublishOnly": "npm run test:readiness"
+  },
+  "engines": {
+    "node": ">=20",
+    "opencode": ">=1.14.48"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.14.48",
+    "tsx": "^4.22.4",
+    "zod": "^4.4.3"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nashgao/opencode-worktree-guardian.git"
+  },
+  "homepage": "https://github.com/nashgao/opencode-worktree-guardian#readme",
+  "bugs": {
+    "url": "https://github.com/nashgao/opencode-worktree-guardian/issues"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "git",
+    "worktree",
+    "guardian",
+    "safety"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "typescript": "^6.0.3"
+  },
+  "types": "./src/index.ts",
+  "directories": {
+    "test": "test"
+  },
+  "author": ""
+}

package/scripts/readiness.ts

@@ -0,0 +1,75 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const authoredRoots = ["src", "test", "scripts"];
+const forbiddenExtensions = new Set([".js", ".mjs", ".cjs"]);
+const allowedAuthoredJavaScript = new Set(["scripts/with-safe-node-temp.mjs"]);
+const commandTimeoutMs = 10 * 60 * 1000;
+const commands: Array<[string, string[]]> = [
+  ["npm", ["run", "verify"]],
+  ["npm", ["run", "audit:deps"]],
+  ["npm", ["run", "test:contract"]],
+  ["npm", ["run", "test:smoke:package"]],
+  ["npm", ["run", "test:smoke:host"]],
+  ["npm", ["pack", "--dry-run", "--json"]],
+];
+
+function normalizeRelative(value: string) {
+  return value.split(path.sep).join("/");
+}
+
+async function collectForbiddenAuthoredFiles(root: string) {
+  const found: string[] = [];
+  async function visit(directory: string) {
+    const entries = await fs.readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        await visit(fullPath);
+        continue;
+      }
+      const relative = normalizeRelative(path.relative(root, fullPath));
+      if (forbiddenExtensions.has(path.extname(entry.name)) && !allowedAuthoredJavaScript.has(relative)) found.push(fullPath);
+    }
+  }
+
+  for (const authoredRoot of authoredRoots) await visit(path.join(root, authoredRoot));
+  return found;
+}
+
+const forbiddenAuthoredFiles = await collectForbiddenAuthoredFiles(process.cwd());
+if (forbiddenAuthoredFiles.length) {
+  console.error("Authored JavaScript files are not allowed:");
+  for (const file of forbiddenAuthoredFiles) console.error(`- ${normalizeRelative(path.relative(process.cwd(), file))}`);
+  process.exit(1);
+}
+
+for (const [command, args] of commands) {
+  const label = [command, ...args].join(" ");
+  process.stdout.write(`\n> ${label}\n`);
+  try {
+    const { stdout, stderr } = await execFileAsync(command, args, {
+      maxBuffer: 30 * 1024 * 1024,
+      timeout: commandTimeoutMs,
+      killSignal: "SIGTERM",
+      env: { ...process.env, CI: "true", GIT_TERMINAL_PROMPT: "0" },
+    });
+    if (stdout) process.stdout.write(stdout);
+    if (stderr) process.stderr.write(stderr);
+  } catch (error: unknown) {
+    const commandError = error as { stdout?: string; stderr?: string; code?: number | string | null; signal?: NodeJS.Signals | null; killed?: boolean };
+    if (commandError.stdout) process.stdout.write(commandError.stdout);
+    if (commandError.stderr) process.stderr.write(commandError.stderr);
+    if (commandError.killed || commandError.signal === "SIGTERM") {
+      console.error(`\nReadiness command timed out after ${commandTimeoutMs}ms: ${label}`);
+      process.exit(124);
+    }
+    console.error(`\nReadiness command failed: ${label}`);
+    process.exit(typeof commandError.code === "number" ? commandError.code : 1);
+  }
+}
+
+console.log("\nReadiness checks passed.");

package/scripts/with-safe-node-temp.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const safeTempDirectoryName = "opencode-worktree-guardian-node";
+const fallbackTempBases = [
+  path.join("/tmp", "opencode"),
+  path.join(os.homedir(), ".cache", "opencode", "tmp"),
+];
+
+function isSameOrInside(candidate, root) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+async function resolveSafeTempRoot(projectRoot) {
+  for (const candidate of [os.tmpdir(), ...fallbackTempBases]) {
+    try {
+      const candidatePath = path.resolve(candidate);
+      await fs.mkdir(candidatePath, { recursive: true });
+      const realCandidate = await fs.realpath(candidatePath);
+      if (isSameOrInside(realCandidate, projectRoot)) continue;
+      const safeRoot = path.join(realCandidate, safeTempDirectoryName);
+      await fs.mkdir(safeRoot, { recursive: true });
+      return fs.realpath(safeRoot);
+    } catch {}
+  }
+  throw new Error("Unable to resolve an external temp directory for Node test scripts");
+}
+
+function envPathInsideProject(value, projectRoot) {
+  if (!value) return false;
+  return isSameOrInside(path.resolve(value), projectRoot);
+}
+
+const separatorIndex = process.argv.indexOf("--");
+const command = separatorIndex >= 0 ? process.argv[separatorIndex + 1] : process.argv[2];
+const args = separatorIndex >= 0 ? process.argv.slice(separatorIndex + 2) : process.argv.slice(3);
+
+if (!command) {
+  console.error("Usage: node scripts/with-safe-node-temp.mjs -- <command> [...args]");
+  process.exit(2);
+}
+
+const projectRoot = await fs.realpath(process.cwd());
+const safeTempRoot = await resolveSafeTempRoot(projectRoot);
+const nodeCompileCache = path.join(safeTempRoot, "node-compile-cache");
+await fs.mkdir(nodeCompileCache, { recursive: true });
+
+const env = {
+  ...process.env,
+  TMPDIR: safeTempRoot,
+  TMP: safeTempRoot,
+  TEMP: safeTempRoot,
+  NODE_COMPILE_CACHE: envPathInsideProject(process.env.NODE_COMPILE_CACHE, projectRoot) ? nodeCompileCache : process.env.NODE_COMPILE_CACHE ?? nodeCompileCache,
+};
+
+if (args.includes("--experimental-test-coverage") || envPathInsideProject(process.env.NODE_V8_COVERAGE, projectRoot)) {
+  const existingCoverage = process.env.NODE_V8_COVERAGE;
+  env.NODE_V8_COVERAGE = existingCoverage && !envPathInsideProject(existingCoverage, projectRoot)
+    ? existingCoverage
+    : path.join(safeTempRoot, `node-coverage-${process.pid}`);
+}
+
+const child = spawn(command, args, { stdio: "inherit", env });
+child.on("error", (error) => {
+  console.error(error.message);
+  process.exit(1);
+});
+child.on("exit", (code, signal) => {
+  if (signal) {
+    console.error(`${command} exited with signal ${signal}`);
+    process.exit(1);
+  }
+  process.exit(code ?? 1);
+});

package/skills/worktree-guardian/SKILL.md

@@ -0,0 +1,73 @@
+# Worktree Guardian
+
+Use the native guardian tools for worktree inspection and completion. The skill is guidance only; the plugin hooks enforce safety.
+
+Canonical safety policy: [ADR 0001: Guardian Safety Policy](../../docs/adr/0001-guardian-safety-policy.md).
+
+## Packaged command surface
+
+- Hosts with packaged plugin command discovery, such as `oh-my-openagent`, can expose this package's top-level `commands/*.md` files as namespaced commands like `/opencode-worktree-guardian:status`, `/opencode-worktree-guardian:hygiene`, `/opencode-worktree-guardian:delete-paths`, and `/opencode-worktree-guardian:delete-worktree`.
+- Treat those slash commands as prompt wrappers only. The native `guardian_*` tools remain the authority for safety checks and mutation gates.
+- Native OpenCode user/project commands are separate files under `~/.config/opencode/commands/*.md` or `<repo>/.opencode/commands/*.md`.
+
+## Rules
+
+- Do not run raw cleanup, reset, stash mutation, force-push, worktree removal, raw `git worktree add` outside Guardian-owned roots, raw branch deletion, or `rm -rf` against worktrees. Use the matching native Guardian tool.
+- Use `guardian_status` for read-only inventory.
+- Use `guardian_done` for normal implementation completion. Prefer it over raw protected-branch push/merge commands or low-level finish tools unless the user explicitly asks for those tools.
+- Use `guardian_hygiene` for hygiene scan/plan/apply cleanup. With no `mode`, it scans only. For cleanup, first run `mode: "plan"`; inspect exact approved targets and blockers, get explicit user confirmation, then run `mode: "apply"` with `confirmDelete: true`.
+- Use `guardian_delete_paths` when the user intentionally wants exact files or directories deleted, including tracked source only with explicit `allowTracked: true`. Worktree deletion must use `guardian_delete_worktree`.
+- Use `guardian_report_html` or `/guardian report` when the user wants a browser-readable branch/worktree/session report. It writes a static offline file at `.git/opencode-guardian/report.html` and returns the exact path.
+- Use `guardian_delete_worktree` only when the user explicitly wants Guardian-mediated worktree, orphan-branch, stale-branch, or unmerged-abandon cleanup. First run `mode: "plan"`; only run `mode: "apply"` with the returned `confirmToken` after checking blockers and confirming intent.
+- Use `guardian_unblock_finish` only when `guardian_finish` is blocked by narrow generated review artifacts. First run `mode: "plan"`; only apply after explicit confirmation with the returned `confirmToken` and the same target options.
+- Use `guardian_finish` for explicit low-level gated completion.
+- Use `guardian_preserve` only to create a safety ref and mark a session terminal/preserved. Preserved worktrees are cleanup-eligible; do not treat preservation as a reason to keep disk state forever.
+- Use `guardian_recover` for safety refs, orphaned sessions, stash inventory, reflog, and recovery suggestions.
+- For mutating commands such as `git add` or `git commit`, rely on Guardian routing after the default auto-start hook or explicit `guardian_start` records a session worktree. Repo config `autoStart=false` disables automatic ownership; without recorded ownership, normal non-destructive commands run in the current worktree.
+- If Guardian state records the current session on the primary repo worktree or a protected branch, use `guardian_start` with `createWorktree: true` to repair the session into a proper Guardian worktree. Do not use raw `git switch`, raw branch creation, or protected-branch bypass commands to escape the poisoned binding.
+- If the plugin blocks a command, report the blocker, preserved path, branch, safety refs, and suggested guardian tool.
+
+## Defaults
+
+- `finishMode`: `create-pr`
+- `branchPrefix`: default branch naming only, not ownership proof
+- `autoStart`: enabled by default; repo config `autoStart=false` opts out of automatic ownership
+- `autoFinish`: disabled unless repo config opts in
+- `autoCleanup`: disabled unless repo config opts in
+- stash mutation is never cleanup
+- workspace hygiene scan mode is report-only; cleanup requires `guardian_hygiene mode=plan`, exact-target review, explicit confirmation, and `mode=apply confirmDelete=true`
+- `guardian_delete_paths` is the exact intentional path deletion surface
+- `guardian_delete_worktree` is the only worktree deletion surface
+- read-only scan/report surfaces are evidence, not approval to mutate
+
+## Scratch posture
+
+- Put research clones, downloaded upstream repos, generated fixtures, and temporary test data outside the active project tree, preferably under OS temp space such as `$TMPDIR/opencode/<repo>/<session>/`.
+- If scratch inside a repo is explicitly required, use a configured scratch root and keep it clearly session-scoped.
+- Treat `guardian_hygiene` scan findings as evidence to report. If cleanup is approved, use `guardian_hygiene mode=plan`, inspect targets/blockers, get explicit confirmation, then apply with `confirmDelete: true`.
+- Treat `external-temp-worktree` and `external-worktree` findings in `guardian_status`/`guardian_recover` as report-only evidence, not cleanup approval.
+
+## Delete posture
+
+- Never run raw `git worktree remove`, `git worktree prune`, `rm -rf`, or raw branch deletion. The hooks intentionally block those commands.
+- Use `guardian_hygiene` for hygiene findings, `guardian_delete_paths` for exact file or directory deletion, and `guardian_delete_worktree` for Guardian worktree/branch cleanup.
+- `guardian_delete_worktree` requires plan/apply and explicit confirmation. Branch deletion is opt-in with `deleteBranch: true`; unmerged abandonment additionally requires `abandonUnmerged: true` in both plan and apply.
+- `guardian_status`, `guardian_recover`, and `guardian_hygiene` scan output are evidence-only. Their output can identify candidates, but it is not approval to delete.
+
+## Recovery posture
+
+Recovery is read-only by default. Creating recovery branches requires explicit user approval.
+
+## Finish-unblock posture
+
+- Never loosen `guardian_finish` dirty-worktree safety to force progress.
+- `guardian_finish` may tolerate dirty runtime/local-state files only when every dirty path matches explicit repo config `allowDirtyPaths`. File-specific patterns match untracked runtime files, so prefer narrow entries like `.claude/logs/hooks.log` over broad directory allowlists unless the whole directory is intentionally allowed. Allowed dirty files are reported and left untouched; Guardian must not delete, stash, revert, stage, or commit them.
+- Treat any non-matching dirty source, config, doc, or policy file as a blocker even when some runtime dirt is allowed.
+- Prefer `guardian_unblock_finish` for the narrow case where review-rating artifacts are the only blocker.
+- Treat plan output as evidence, not approval. Apply requires an explicit fresh confirm token for the exact current preflight.
+- Do not use the unblocker for source changes, deletions, ignored files, stashes, or cleanup.
+
+## Release references
+
+- Release checklist: [docs/release-checklist.md](../../docs/release-checklist.md)
+- Publishing policy: [docs/publishing.md](../../docs/publishing.md)