@snarkipus/opencode-beads 0.8.0 → 0.9.1

package/README.md

@@ -2,13 +2,13 @@
 
 [Beads](https://github.com/gastownhall/beads) issue tracker integration for [OpenCode](https://opencode.ai).
 
-This maintained fork provides the OpenCode-facing product layer around Beads: full `bd prime` context injection, vendored workflows, an autonomous task agent, project-scoped runtime integration, and an explicit managed companion skill lifecycle. It is deliberately an adapter rather than a second issue tracker: the `bd` CLI remains authoritative for issues, Dolt synchronization, migrations, and general Beads behavior.
+This maintained fork provides the OpenCode-facing product layer around Beads: full `bd prime` context injection, vendored workflows, an autonomous task agent, and project-scoped runtime integration. It is deliberately an adapter rather than a second issue tracker: the `bd` CLI remains authoritative for issues, project initialization, skills, Dolt synchronization, migrations, and general Beads behavior.
 
 The project originated as [Josh Thomas's `opencode-beads`](https://github.com/joshuadavidthomas/opencode-beads) and continues under the MIT license. This fork is maintained by Matt Jackson and tracks reviewed upstream Beads releases while adapting their plugin artifacts to OpenCode's CLI-only execution model.
 
 ## Installation
 
-Install the beads CLI:
+Install the `bd` CLI once on the host:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
@@ -20,65 +20,48 @@ Add the version-pinned plugin to your OpenCode config (`~/.config/opencode/openc
 
 ```json
 {
-  "plugin": ["@snarkipus/opencode-beads@0.8.0"]
+  "plugin": ["@snarkipus/opencode-beads@0.9.1"]
 }
 ```
 
 Restart OpenCode. OpenCode caches pinned plugins, so update this version explicitly when upgrading. An unpinned `@snarkipus/opencode-beads` entry follows npm updates on startup but is less reproducible.
 
-In a project without a Beads database, run `/beads:init` or `bd init` before using issue commands. This initializes Beads data only; it does not install the companion OpenCode skill.
-
-### Optional skill
-
-Install the companion OpenCode skill for durable Beads guidance in the current Git worktree:
+Initialize every new project separately. Create a Git worktree first if necessary, then run `bd init`:
 
 ```bash
-bunx @snarkipus/opencode-beads@0.8.0 init
+git init
+bd init
 ```
 
-The project target is `<worktree>/.opencode/skills/beads`, even when the command runs from a nested directory. Use `init --global` for `$XDG_CONFIG_HOME/opencode/skills/beads` when `XDG_CONFIG_HOME` is absolute, otherwise `~/.config/opencode/skills/beads`.
+Skip `git init` when the project is already a Git worktree. `bd init` performs the per-project Beads initialization and its automatic Codex project integration creates the canonical shared skill at `.agents/skills/beads`, which OpenCode also discovers. `/beads:init` invokes the same project initialization workflow; this plugin has no separate skill lifecycle or companion CLI.
+
+### Upgrading from 0.8.0
 
-The package CLI is the canonical lifecycle because OpenCode does not guarantee that plugin npm bins are on `PATH`:
+Version 0.8.0 installed a fork-managed skill under `.opencode/skills/beads`. Remove that old managed skill with the version-pinned 0.8.0 CLI before changing the plugin pin to 0.9.1:
 
 ```bash
-bunx @snarkipus/opencode-beads@0.8.0 init [--global]
-bunx @snarkipus/opencode-beads@0.8.0 check [--global]
-bunx @snarkipus/opencode-beads@0.8.0 update [--global]
-bunx @snarkipus/opencode-beads@0.8.0 remove [--global]
+bunx @snarkipus/opencode-beads@0.8.0 remove
 ```
 
-Every command supports `--dry-run` for an exact non-mutating plan and `--json` for one deterministic result object. Add `--global` to select the global scope. `/beads:setup` prints commands for the running package version; it does not write files. `/beads:init` remains DB-only.
-
-Lifecycle states are:
-
-| State | Meaning |
-| --- | --- |
-| `missing` | The selected target does not exist. |
-| `current` | The ownership manifest, package metadata, inventory, and file hashes match. |
-| `stale` | The target is recognized and unmodified, but its managed package or provenance metadata differs from the running package. |
-| `modified` | The target has a recognized manifest, but a managed file, hash, symlink, or inventory differs. |
-| `conflicting` | The target is unmanaged or differently managed, another discovered Beads skill blocks the operation, or stale transaction residue exists. |
-
-`init` installs a missing target or safely refreshes a recognized stale target. `update` changes only a recognized stale target whose old managed hashes still match. `init` and `update` are no-ops for current targets. `remove` deletes only a recognized, unmodified current or stale target. Modified and conflicting targets are never overwritten or removed, and there is no force option.
+If the old skill was installed globally, append `--global` to that exact command. Do not substitute 0.9.1 in the removal command: the companion CLI no longer exists in 0.9.1.
 
-Before `init` or `update`, discovery checks `.opencode/skills/beads`, `.agents/skills/beads`, and `.claude/skills/beads` from the current directory through the Git worktree root, plus their global equivalents. Unrelated discovered skills block writes. `remove` may remove the selected verified-owned target despite an unrelated skill elsewhere, but stale transaction residue still blocks it.
+For a repository that has not been initialized with Beads, run `bd init`; it creates the canonical shared skill as part of normal initialization. For an already-initialized repository that is missing the skill, upstream currently has no skill-only setup command. Do not run `bd setup codex` as a substitute because it also installs Codex hooks and generated instructions. Instead, initialize a temporary Git repository with the same `bd` version and copy only its canonical skill directory into the target repository:
 
-The lifecycle is fully offline from immutable package artifacts. Updates use sibling staging, backup, and recovery directories so caught filesystem errors restore the prior installation; this does not claim crash-proof atomicity across multiple renames. OpenCode does not discover skills inside npm packages, so passive npm discovery is unsupported. Plugin startup is read-only and never installs, updates, or removes skill files automatically.
-
-CLI exit codes are stable:
-
-| Exit | Meaning |
-| --- | --- |
-| `0` | Lifecycle command succeeded, or `check` found the current managed skill. |
-| `1` | `check` found a missing, stale, modified, or conflicting skill. |
-| `2` | Invalid usage, lifecycle refusal, package validation failure, git discovery failure, or operational error. |
+```bash
+scratch="$(mktemp -d)"
+git -C "$scratch" init
+(cd "$scratch" && bd init)
+mkdir -p .agents/skills
+cp -R "$scratch/.agents/skills/beads" .agents/skills/beads
+rm -rf "$scratch"
+```
 
-With `--json`, every exit writes exactly one JSON object plus a trailing newline to stdout and writes nothing to stderr. The stable `code` and `message` fields classify success, non-current checks, refusals, usage errors, discovery failures, package failures, and other operational failures.
+This bounded migration copies only `.agents/skills/beads`; it does not copy `.codex` artifacts or generated instruction files.
 
 ## Features
 
 - **Context injection** - Loads the canonical Beads workflow and persistent memories on session start and after compaction
-- **Commands** - Vendored Beads workflows plus native `/beads:setup`, available under the `/beads:*` namespace
+- **Commands** - Vendored Beads workflows available under the `/beads:*` namespace
 - **Task agent** - Autonomous issue completion via `beads-task-agent` subagent
 
 ## Usage
@@ -97,13 +80,11 @@ Commands are available as `/beads:<name>`, for example `/beads:ready`, `/beads:c
 
 Explicit command and agent definitions in your OpenCode configuration take precedence over plugin-provided definitions with the same name. The plugin emits a grouped, rate-limited warning for exact `beads:*` or `beads-task-agent` collisions while continuing to register every non-conflicting definition.
 
-This configuration precedence is separate from skill-file collision safety. User-defined commands and agents win without blocking plugin startup; unmanaged, differently managed, or modified skill files instead cause the explicit companion CLI operation to refuse without mutation.
-
 ## Agent
 
 ### beads-task-agent
 
-A subagent for read-only status and graph analysis or one-bead task completion. Analysis requests never mutate beads; completion requests inspect and process one caller-selected or highest-priority ready bead, quarantine work created during that invocation, and return after closing or blocking the selected bead. Its configured prompt is role-specific; session injection supplies the shared CLI and lifecycle safety rules once.
+A subagent for read-only status and graph analysis or one-bead task completion. Analysis requests never mutate beads; completion requests inspect and process one caller-selected or highest-priority ready bead, quarantine work created during that invocation, validate before closure, and return after closing or blocking the selected bead. Its configured prompt is role-specific; session injection supplies compact OpenCode-specific CLI, validation, delegation, and conservative commit/push/sync policy without duplicating `bd prime`.
 
 ## Compatibility
 
@@ -115,25 +96,19 @@ The compatibility ranges and validated baselines for this release are:
 | `bd` CLI | 1.0.5 through 1.x | 1.1.0 |
 | Bun | >=1.3.14 | 1.3.14 |
 
-The OpenCode adapter builds against the exact paired `@opencode-ai/plugin` and `@opencode-ai/sdk` `1.18.4` releases and declares compatible optional peers from `1.18.3` through the stable `1.x` line. Both imports are type-only; the package does not install a second OpenCode runtime. The command, agent, and managed-skill provenance is currently synced from Beads v1.1.0. Newer compatible releases may work but are not guaranteed until validated; when diagnosing a regression, reproduce it with the baselines above.
+The OpenCode adapter builds against the exact paired `@opencode-ai/plugin` and `@opencode-ai/sdk` `1.18.4` releases and declares compatible optional peers from `1.18.3` through the stable `1.x` line. Both imports are type-only; the package does not install a second OpenCode runtime. Command and agent provenance is currently synced from Beads v1.1.0. Newer compatible releases may work but are not guaranteed until validated; when diagnosing a regression, reproduce it with the baselines above.
 
 ## Vendored Content
 
 Files under `vendor/` are copied from the upstream Beads plugin by [`scripts/sync-beads.sh`](scripts/sync-beads.sh). The current inventory includes the complete upstream command-template directory and task agent, rather than a duplicate of the much larger `bd` CLI. [`vendor/manifest.json`](vendor/manifest.json) records the stable upstream tag and commit, source paths, sorted inventory, byte lengths, and SHA-256 checksums. A deterministic adaptation layer translates known MCP- or Claude-specific instructions to OpenCode's CLI-only model when prompts load; sync fails if provenance, checksums, inventory, or reviewed transformations differ. Do not edit vendored files directly: the next sync replaces them. Adapter behavior lives in `src/`, while general Beads behavior and documentation remain upstream.
 
-The vendor manifest, task agent, and every recorded command file are required package content. The separately reviewed skill fork records exact upstream source paths and hashes mapped to each adapted output in `dist/init/manifest.json`; these mappings, the output inventory, and output hashes are all strict package inputs. Initialization fails with the artifact path and validation reason if required content is missing or malformed. Command frontmatter supports `description`, `argument-hint`, `agent`, `model`, and `subtask`; task-agent frontmatter supports `description`, `mode: subagent`, `model`, `temperature`, `top_p`, `disable`, `color`, and `maxSteps`. Unsupported fields or shapes fail validation so upstream changes receive explicit review. Reinstall the package or rerun the sync script from a source checkout rather than repairing generated files by hand.
+The vendor manifest, task agent, and every recorded command file are required package content. Their exact upstream source paths, inventory, byte lengths, and hashes are strict package inputs. Plugin loading fails with the artifact path and validation reason if required content is missing or malformed. Command frontmatter supports `description`, `argument-hint`, `agent`, `model`, and `subtask`; task-agent frontmatter supports `description`, `mode: subagent`, `model`, `temperature`, `top_p`, `disable`, `color`, and `maxSteps`. Unsupported fields or shapes fail validation so upstream changes receive explicit review. Reinstall the package or rerun the sync script from a source checkout rather than repairing generated files by hand.
 
 ## Troubleshooting
 
 - **No Beads context:** Run `bd prime` in the project. Install `bd` if the command is missing, or run `bd init` if the project has no Beads workspace.
-- **Managed skill is missing:** Run `bunx @snarkipus/opencode-beads@0.8.0 init [--global]`. Use the same scope for later lifecycle commands.
-- **Managed skill is stale:** Run `bunx @snarkipus/opencode-beads@0.8.0 update [--global]`. The command proceeds only if every old managed hash still matches.
-- **Managed skill is modified:** Preserve or revert local edits before retrying. To discard an installation deliberately, move the entire target out of every OpenCode discovery root, then run `init`; no force mode exists.
-- **Managed skill is conflicting:** Run `check --json` with the intended scope and inspect `target` and `collisions`. Move or remove unmanaged or differently managed Beads skills deliberately, then retry. Do not treat another discovery root as the selected target.
-- **Stale transaction residue:** Preserve and inspect sibling `.beads.opencode-beads-stage-*`, `-backup-*`, or `-recovery-*` directories before manual recovery. The CLI refuses to guess which residue is authoritative.
-- **Global target is unexpected:** Use an absolute `XDG_CONFIG_HOME` for `$XDG_CONFIG_HOME/opencode/skills/beads`; relative or absent values intentionally fall back to `~/.config/opencode/skills/beads`. Global `.agents` and `.claude` roots remain under the home directory.
-- **Lifecycle reports package validation failure:** Reinstall the exact scoped package version. The CLI will not install from missing, unexpected, or checksum-invalid packaged artifacts.
-- **Lifecycle cannot discover Git:** Run the command inside the intended Git worktree. Project and global lifecycle operations both require a worktree boundary for collision discovery.
+- **Canonical skill is missing:** For a repository without a Beads workspace, run `bd init`. For an already-initialized repository, use the bounded manual-copy migration above; upstream currently has no skill-only setup command, and `bd setup codex` installs additional Codex integration artifacts.
+- **Upgrading from 0.8.0:** Run the exact version-pinned removal command in the upgrade section before updating the plugin pin, then use the appropriate fresh-initialization or existing-workspace path above.
 - **Vendor artifact initialization error:** Reinstall the package. If using a source checkout, rerun the vendor sync and validation scripts; the error names the missing or malformed manifest, command, or task-agent file.
 - **Unexpected command or agent definition:** Check the OpenCode configuration for a colliding `beads:*` or `beads-task-agent` entry. Your explicit configuration wins on an exact name collision; OpenCode logs a rate-limited warning naming the collision.
 - **A regular subagent has no Beads context:** This is intentional. Delegate Beads work to `beads-task-agent`, or run the required `bd` command explicitly.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@snarkipus/opencode-beads",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "type": "module",
-  "description": "A maintained OpenCode integration for the Beads issue tracker, including context injection, vendored workflows, a task agent, and managed skill lifecycle tooling.",
+  "description": "A maintained OpenCode integration for the Beads issue tracker, including context injection, vendored workflows, and a task agent.",
   "author": "Matt Jackson",
   "contributors": [
     {
@@ -40,13 +40,9 @@
   "files": [
     "src",
     "vendor",
-    "dist",
     "README.md",
     "LICENSE"
   ],
-  "bin": {
-    "opencode-beads": "src/init-cli.ts"
-  },
   "scripts": {
     "test": "bun test",
     "test:docs": "bun test tests/docs.test.ts",

package/src/vendor.ts

@@ -16,21 +16,6 @@ function getVendorDir(): string {
   return path.join(__dirname, "..", "vendor");
 }
 
-async function getPackageIdentity(): Promise<string> {
-  const packagePath = path.join(getVendorDir(), "..", "package.json");
-  const value = JSON.parse(await fs.readFile(packagePath, "utf8")) as {
-    name?: unknown;
-    version?: unknown;
-  };
-  if (typeof value.name !== "string") {
-    throw new Error("Invalid package artifact package.json: name must be a string");
-  }
-  if (typeof value.version !== "string") {
-    throw new Error("Invalid package artifact package.json: version must be a string");
-  }
-  return `${value.name}@${value.version}`;
-}
-
 interface ParsedMarkdown {
   frontmatter: Record<string, string>;
   body: string;
@@ -189,7 +174,9 @@ function rejectUnsupportedFields(
 const BEADS_HOST_GUIDANCE = `## CLI Safety
 
 There is no native \`bd\` or Beads MCP tool in OpenCode. Run \`bd\` through \`bash\`.
-Treat the injected \`bd prime\` output as the canonical workflow reference. Use \`bd --help\` to discover commands, \`bd <command> --help\` for current syntax, and \`--json\` when structured output improves reliability. Distinguish command failures from output parsing failures.`;
+Treat the injected \`bd prime\` output as the canonical workflow reference. Use \`bd --help\` to discover commands, \`bd <command> --help\` for current syntax, and \`--json\` when structured output improves reliability. Distinguish command failures from output parsing failures.
+
+Run relevant validation before closing an issue. Do not commit, push, or run Dolt synchronization automatically; do so only when current instructions or repository policy explicitly require it.`;
 
 const BEADS_DELEGATION_GUIDANCE = `## Delegation
 
@@ -286,12 +273,5 @@ export async function loadCommands(vendorDirectory = getVendorDir()): Promise<Co
     commands[name] = command;
   }
 
-  const packageIdentity = await getPackageIdentity();
-  const cli = `bunx ${packageIdentity}`;
-  commands["beads:setup"] = {
-    description: "Install or manage the OpenCode Beads skill",
-    template: `The package CLI is canonical for the OpenCode Beads skill lifecycle. Use exact version-matched commands: \`${cli} init\`, \`${cli} init --global\`, \`${cli} check\`, \`${cli} update\`, and \`${cli} remove\`. Add \`--global\` to check, update, or remove for global scope. \`/beads:init\` is DB-only: it initializes a Beads database and does not install the skill.`,
-  };
-
   return commands;
 }

package/dist/init/artifacts/beads/SKILL.md

@@ -1,16 +0,0 @@
----
-name: beads
-description: Use when managing work with the bd CLI, especially "create task", "what's ready", "track this work", dependencies, blockers, multi-session work, or recovery after compaction.
----
-
-# Beads
-
-Use `bd` through the shell for issue tracking. Run `bd prime` for the current project workflow and `bd <command> --help` for current command syntax.
-
-Keep issue state in Beads rather than parallel TODO files. Claim work before implementation, validate before closing it, and record discovered follow-up with its dependency relationship.
-
-## References
-
-- [Dependencies](references/DEPENDENCIES.md)
-- [Issue creation](references/ISSUE_CREATION.md)
-- [Resumability](references/RESUMABILITY.md)

package/dist/init/artifacts/beads/references/DEPENDENCIES.md

@@ -1,5 +0,0 @@
-# Dependencies
-
-Model ordering and discovery relationships in Beads so `bd ready` reflects genuinely unblocked work. Use `bd dep --help` for current dependency commands and types; do not infer direction from prose alone.
-
-When implementation reveals separate follow-up, create it with a `discovered-from` relationship to the issue that exposed it. Avoid dependencies between work that can proceed independently.

package/dist/init/artifacts/beads/references/ISSUE_CREATION.md

@@ -1,5 +0,0 @@
-# Issue Creation
-
-Create durable work with enough context, acceptance criteria, and priority for another session to act without reconstructing intent. Select the issue type that describes the work, not the current activity.
-
-Use `bd create --help` for current flags and `--json` when structured output improves reliability. Search existing issues before creating a duplicate.

package/dist/init/artifacts/beads/references/RESUMABILITY.md

@@ -1,5 +0,0 @@
-# Resumability
-
-Keep issue state useful across sessions: claim before changing code, record material findings and blockers, and close only after validation. Leave concise notes when the next step is not evident from the issue itself.
-
-Use `bd prime` for the current lifecycle policy and `bd <command> --help` for syntax. Do not make automatic commit, push, or sync behavior part of issue completion.

package/dist/init/manifest.json

@@ -1,54 +0,0 @@
-{
-  "schemaVersion": 1,
-  "owner": "opencode-beads",
-  "upstream": {
-    "repository": "https://github.com/gastownhall/beads.git",
-    "tag": "v1.1.0",
-    "commit": "8e4e59d39f3459a43cf21a3236a13eca4dd874f7"
-  },
-  "adaptationRevision": 1,
-  "sources": [
-    {
-      "source": "plugins/beads/skills/beads/SKILL.md",
-      "sourceSha256": "01555fe65d19be401d820d9dec029cd048fb0791d433b4b575374477d6f1d827",
-      "target": "SKILL.md"
-    },
-    {
-      "source": "plugins/beads/skills/beads/resources/DEPENDENCIES.md",
-      "sourceSha256": "9c3327611bfbdc47124736dd0cc928bfeff1c135d4ae79d4ea46cba1900df335",
-      "target": "references/DEPENDENCIES.md"
-    },
-    {
-      "source": "plugins/beads/skills/beads/resources/ISSUE_CREATION.md",
-      "sourceSha256": "ff465ed1fb13fbb6c42b42ec15c1bd8fd677c4661237e4fc1675c179f7fca460",
-      "target": "references/ISSUE_CREATION.md"
-    },
-    {
-      "source": "plugins/beads/skills/beads/resources/RESUMABILITY.md",
-      "sourceSha256": "8a7db4e967ace1b4f60dc85e3fb2d02f70749a18056fe90c61b2685bb172d7df",
-      "target": "references/RESUMABILITY.md"
-    }
-  ],
-  "files": [
-    {
-      "path": "SKILL.md",
-      "bytes": 710,
-      "sha256": "55a99d3f7bbfdd8dbf71097905086260455d7e14c7d133304b6645b930d16df3"
-    },
-    {
-      "path": "references/DEPENDENCIES.md",
-      "bytes": 412,
-      "sha256": "4befbc8d17df863d3f8af7af934f7c503e66af2e3893d9fadd8c7ef156271e77"
-    },
-    {
-      "path": "references/ISSUE_CREATION.md",
-      "bytes": 376,
-      "sha256": "5f7e2c73a2d206478c469a8777071a99c8a83f0a2970da3e8af56b2bcfcabb75"
-    },
-    {
-      "path": "references/RESUMABILITY.md",
-      "bytes": 400,
-      "sha256": "782053cb6c091d3a87c1e4dc6b0cf3777bd1321b8a92ad38fe6351116b6fa363"
-    }
-  ]
-}

package/src/init-cli.ts

@@ -1,172 +0,0 @@
-#!/usr/bin/env bun
-
-import { homedir } from "node:os";
-import { dirname, isAbsolute, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { runInitCommand, type InitCommand, type InitScope } from "./init";
-
-const USAGE = "Usage: opencode-beads <init|check|update|remove> [--global] [--dry-run] [--json]";
-const VALID_COMMANDS: InitCommand[] = ["init", "check", "update", "remove"];
-const VALID_FLAGS = new Set(["--global", "--dry-run", "--json"]);
-
-interface CliOptions {
-  command: InitCommand;
-  scope: InitScope;
-  dryRun: boolean;
-  json: boolean;
-}
-
-type CliErrorCode =
-  | "GIT_DISCOVERY_FAILED"
-  | "OPERATION_FAILED"
-  | "PACKAGED_ARTIFACT_INVALID"
-  | "USAGE";
-
-class CliFailure extends Error {
-  constructor(readonly code: CliErrorCode, message: string, readonly humanMessage = message) {
-    super(message);
-  }
-}
-
-function writeJson(value: unknown): void {
-  process.stdout.write(`${JSON.stringify(value)}\n`);
-}
-
-function parseArgs(args: string[]): CliOptions {
-  const commands = args.filter((arg) => !arg.startsWith("--"));
-  const flags = args.filter((arg) => arg.startsWith("--"));
-  const command = commands[0];
-  if (
-    commands.length !== 1 ||
-    !VALID_COMMANDS.includes(command as InitCommand) ||
-    flags.some((flag) => !VALID_FLAGS.has(flag)) ||
-    new Set(flags).size !== flags.length
-  ) {
-    throw new Error(USAGE);
-  }
-  return {
-    command: command as InitCommand,
-    scope: flags.includes("--global") ? "global" : "project",
-    dryRun: flags.includes("--dry-run"),
-    json: flags.includes("--json"),
-  };
-}
-
-async function discoverWorktree(cwd: string): Promise<string> {
-  try {
-    const process = Bun.spawn(["git", "rev-parse", "--show-toplevel"], {
-      cwd,
-      stdout: "pipe",
-      stderr: "ignore",
-    });
-    const output = await new Response(process.stdout).text();
-    if ((await process.exited) !== 0 || !output.trim()) throw new Error("git failed");
-    return resolve(output.trim());
-  } catch {
-    throw new CliFailure("GIT_DISCOVERY_FAILED", "Unable to discover git worktree from cwd");
-  }
-}
-
-/** Run the companion lifecycle CLI and return its process exit code. */
-export async function runCli(
-  args = process.argv.slice(2),
-  environment: {
-    cwd?: string;
-    home?: string;
-    packageRoot?: string;
-    xdgConfigHome?: string;
-  } = {}
-): Promise<number> {
-  const jsonRequested = args.includes("--json");
-  let options: CliOptions;
-  try {
-    options = parseArgs(args);
-  } catch (error) {
-    if (jsonRequested) writeJson({ ok: false, code: "USAGE", message: USAGE });
-    else console.error(error instanceof Error ? error.message : String(error));
-    return 2;
-  }
-
-  try {
-    const packageRoot = environment.packageRoot ?? resolve(dirname(fileURLToPath(import.meta.url)), "..");
-    let packageJson: { version?: unknown };
-    try {
-      packageJson = (await Bun.file(resolve(packageRoot, "package.json")).json()) as { version?: unknown };
-      if (typeof packageJson.version !== "string") throw new Error("Package version is missing");
-    } catch (error) {
-      throw new CliFailure(
-        "PACKAGED_ARTIFACT_INVALID",
-        "Packaged artifacts failed validation",
-        error instanceof Error ? error.message : String(error)
-      );
-    }
-    const cwd = resolve(environment.cwd ?? process.cwd());
-    const home = resolve(environment.home ?? homedir());
-    const xdgConfigHome = environment.xdgConfigHome ?? process.env.XDG_CONFIG_HOME;
-    const opencodeConfigDirectory =
-      xdgConfigHome && isAbsolute(xdgConfigHome)
-        ? resolve(xdgConfigHome, "opencode")
-        : join(home, ".config", "opencode");
-    let result;
-    try {
-      result = await runInitCommand(options.command, {
-        cwd,
-        worktree: await discoverWorktree(cwd),
-        home,
-        opencodeConfigDirectory,
-        packageRoot,
-        packageVersion: packageJson.version,
-        scope: options.scope,
-        dryRun: options.dryRun,
-      });
-    } catch (error) {
-      if (error instanceof CliFailure) throw error;
-      const humanMessage = error instanceof Error ? error.message : String(error);
-      const packaged = humanMessage.startsWith("Invalid packaged artifact");
-      throw new CliFailure(
-        packaged ? "PACKAGED_ARTIFACT_INVALID" : "OPERATION_FAILED",
-        packaged ? "Packaged artifacts failed validation" : "Lifecycle operation failed",
-        humanMessage
-      );
-    }
-    let exitCode: number;
-    let code: "CHECK_NOT_CURRENT" | "LIFECYCLE_REFUSED" | "OK";
-    let message: string;
-    if (!result.ok) {
-      exitCode = 2;
-      code = "LIFECYCLE_REFUSED";
-      message = result.error ?? "Lifecycle command refused";
-    } else if (options.command === "check" && result.state !== "current") {
-      exitCode = 1;
-      code = "CHECK_NOT_CURRENT";
-      message = "Managed skill is not current";
-    } else {
-      exitCode = 0;
-      code = "OK";
-      message = "Lifecycle command completed";
-    }
-    if (options.json) {
-      writeJson({ ...result, code, message });
-    } else if (result.ok) {
-      const verb = result.changed ? (result.dryRun ? "Would change" : "Changed") : "No change";
-      console.log(`${verb}: ${result.target} (${result.state})`);
-    } else {
-      console.error(`${result.error}: ${result.target}`);
-    }
-    return exitCode;
-  } catch (error) {
-    const failure =
-      error instanceof CliFailure
-        ? error
-        : new CliFailure(
-            "OPERATION_FAILED",
-            "Lifecycle operation failed",
-            error instanceof Error ? error.message : String(error)
-          );
-    if (options.json) writeJson({ ok: false, code: failure.code, message: failure.message });
-    else console.error(failure.humanMessage);
-    return 2;
-  }
-}
-
-if (import.meta.main) process.exitCode = await runCli();

package/src/init.ts

@@ -1,700 +0,0 @@
-import { createHash } from "node:crypto";
-import * as fs from "node:fs/promises";
-import { basename, dirname, join, relative, resolve, sep } from "node:path";
-import {
-  beadsSkillLocations,
-  inspectBeadsSkillLocations,
-  type ManagedSkillState,
-  type SkillLocation,
-} from "./skill-collision-policy";
-
-export const OWNERSHIP_MANIFEST = ".opencode-beads-manifest.json";
-const OWNER = "opencode-beads";
-const PAYLOAD_PATHS = [
-  "SKILL.md",
-  "references/DEPENDENCIES.md",
-  "references/ISSUE_CREATION.md",
-  "references/RESUMABILITY.md",
-] as const;
-
-export type InitCommand = "check" | "init" | "remove" | "update";
-export type InitState = "conflicting" | "current" | "missing" | "modified" | "stale";
-export type InitScope = "global" | "project";
-
-interface ArtifactFile {
-  path: string;
-  bytes: number;
-  sha256: string;
-}
-
-interface ArtifactSource {
-  source: string;
-  sourceSha256: string;
-  target: string;
-}
-
-const ARTIFACT_SOURCES: ArtifactSource[] = [
-  {
-    source: "plugins/beads/skills/beads/SKILL.md",
-    sourceSha256: "01555fe65d19be401d820d9dec029cd048fb0791d433b4b575374477d6f1d827",
-    target: "SKILL.md",
-  },
-  {
-    source: "plugins/beads/skills/beads/resources/DEPENDENCIES.md",
-    sourceSha256: "9c3327611bfbdc47124736dd0cc928bfeff1c135d4ae79d4ea46cba1900df335",
-    target: "references/DEPENDENCIES.md",
-  },
-  {
-    source: "plugins/beads/skills/beads/resources/ISSUE_CREATION.md",
-    sourceSha256: "ff465ed1fb13fbb6c42b42ec15c1bd8fd677c4661237e4fc1675c179f7fca460",
-    target: "references/ISSUE_CREATION.md",
-  },
-  {
-    source: "plugins/beads/skills/beads/resources/RESUMABILITY.md",
-    sourceSha256: "8a7db4e967ace1b4f60dc85e3fb2d02f70749a18056fe90c61b2685bb172d7df",
-    target: "references/RESUMABILITY.md",
-  },
-];
-
-interface ArtifactManifest {
-  schemaVersion: 1;
-  owner: typeof OWNER;
-  upstream: { repository: string; tag: string; commit: string };
-  adaptationRevision: number;
-  sources: ArtifactSource[];
-  files: ArtifactFile[];
-}
-
-export interface InitMutationFileSystem {
-  mkdir(path: string, options?: { recursive?: boolean }): Promise<string | undefined | void>;
-  mkdtemp(prefix: string): Promise<string>;
-  rmdir(path: string): Promise<void>;
-  writeFile(
-    path: string,
-    data: string | Uint8Array,
-    options?: { flag?: "w" | "wx" }
-  ): Promise<void>;
-  rename(oldPath: string, newPath: string): Promise<void>;
-  cp(
-    source: string,
-    destination: string,
-    options: { recursive: true; errorOnExist: true; force: false }
-  ): Promise<void>;
-  rm(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>;
-}
-
-interface OwnershipManifest {
-  schemaVersion: 1;
-  owner: typeof OWNER;
-  packageVersion: string;
-  upstream: { tag: string; commit: string };
-  adaptationRevision: number;
-  scope: InitScope;
-  target: string;
-  files: Array<Pick<ArtifactFile, "path" | "sha256">>;
-}
-
-export interface InitInputs {
-  cwd: string;
-  worktree: string;
-  home: string;
-  opencodeConfigDirectory?: string;
-  packageRoot: string;
-  packageVersion: string;
-  scope?: InitScope;
-  dryRun?: boolean;
-  /** Test seam for mutation failures; reads always use the real filesystem. */
-  mutationFileSystem?: InitMutationFileSystem;
-}
-
-export type InitPlanOperation = {
-  action: "mkdir" | "remove" | "rmdir" | "write-manifest" | "write-payload";
-  path: string;
-};
-
-export interface InitResult {
-  command: InitCommand;
-  scope: InitScope;
-  target: string;
-  state: InitState;
-  ok: boolean;
-  changed: boolean;
-  dryRun: boolean;
-  plan: InitPlanOperation[];
-  collisions: string[];
-  error?: string;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function exactKeys(value: Record<string, unknown>, keys: string[]): boolean {
-  return Object.keys(value).sort().join("\0") === [...keys].sort().join("\0");
-}
-
-function validRelativePath(path: string): boolean {
-  return path.length > 0 && !path.startsWith("/") && !path.split(/[\\/]/).includes("..");
-}
-
-function sha256(content: Uint8Array): string {
-  return createHash("sha256").update(content).digest("hex");
-}
-
-function isMissing(error: unknown): boolean {
-  return isRecord(error) && error.code === "ENOENT";
-}
-
-async function readJson(path: string): Promise<unknown> {
-  return JSON.parse(await fs.readFile(path, "utf8"));
-}
-
-function parseArtifactManifest(value: unknown): ArtifactManifest {
-  if (
-    !isRecord(value) ||
-    !exactKeys(value, ["schemaVersion", "owner", "upstream", "adaptationRevision", "sources", "files"]) ||
-    value.schemaVersion !== 1 ||
-    value.owner !== OWNER ||
-    typeof value.adaptationRevision !== "number" ||
-    !Number.isInteger(value.adaptationRevision) ||
-    !isRecord(value.upstream) ||
-    !exactKeys(value.upstream, ["repository", "tag", "commit"]) ||
-    typeof value.upstream.repository !== "string" ||
-    typeof value.upstream.tag !== "string" ||
-    typeof value.upstream.commit !== "string" ||
-    !Array.isArray(value.sources) ||
-    !Array.isArray(value.files)
-  ) {
-    throw new Error("invalid packaged manifest schema");
-  }
-  if (
-    value.upstream.repository !== "https://github.com/gastownhall/beads.git" ||
-    value.upstream.tag !== "v1.1.0" ||
-    value.upstream.commit !== "8e4e59d39f3459a43cf21a3236a13eca4dd874f7" ||
-    value.adaptationRevision !== 1
-  ) {
-    throw new Error("packaged manifest provenance is not the reviewed adaptation");
-  }
-
-  const sources = value.sources.map((source, index): ArtifactSource => {
-    if (
-      !isRecord(source) ||
-      !exactKeys(source, ["source", "sourceSha256", "target"]) ||
-      typeof source.source !== "string" ||
-      typeof source.sourceSha256 !== "string" ||
-      typeof source.target !== "string"
-    ) {
-      throw new Error(`invalid packaged manifest source ${index}`);
-    }
-    return {
-      source: source.source,
-      sourceSha256: source.sourceSha256,
-      target: source.target,
-    };
-  });
-  if (JSON.stringify(sources) !== JSON.stringify(ARTIFACT_SOURCES)) {
-    throw new Error("packaged manifest must contain the fixed sorted source mappings");
-  }
-
-  const files = value.files.map((file, index): ArtifactFile => {
-    if (
-      !isRecord(file) ||
-      !exactKeys(file, ["path", "bytes", "sha256"]) ||
-      typeof file.path !== "string" ||
-      !validRelativePath(file.path) ||
-      typeof file.bytes !== "number" ||
-      !Number.isInteger(file.bytes) ||
-      file.bytes < 0 ||
-      typeof file.sha256 !== "string" ||
-      !/^[a-f0-9]{64}$/.test(file.sha256)
-    ) {
-      throw new Error(`invalid packaged manifest file ${index}`);
-    }
-    return { path: file.path, bytes: file.bytes, sha256: file.sha256 };
-  });
-  const paths = files.map((file) => file.path);
-  if (
-    paths.join("\0") !== [...paths].sort().join("\0") ||
-    paths.join("\0") !== PAYLOAD_PATHS.join("\0")
-  ) {
-    throw new Error("packaged manifest must contain the fixed sorted payload inventory");
-  }
-  return {
-    schemaVersion: 1,
-    owner: OWNER,
-    upstream: {
-      repository: value.upstream.repository,
-      tag: value.upstream.tag,
-      commit: value.upstream.commit,
-    },
-    adaptationRevision: value.adaptationRevision,
-    sources,
-    files,
-  };
-}
-
-function parseOwnershipManifest(value: unknown): OwnershipManifest | undefined {
-  if (!isRecord(value) || value.owner !== OWNER) return undefined;
-  if (
-    !exactKeys(value, [
-      "schemaVersion",
-      "owner",
-      "packageVersion",
-      "upstream",
-      "adaptationRevision",
-      "scope",
-      "target",
-      "files",
-    ]) ||
-    value.schemaVersion !== 1 ||
-    typeof value.packageVersion !== "string" ||
-    value.packageVersion.length === 0 ||
-    !isRecord(value.upstream) ||
-    !exactKeys(value.upstream, ["tag", "commit"]) ||
-    typeof value.upstream.tag !== "string" ||
-    value.upstream.tag.length === 0 ||
-    typeof value.upstream.commit !== "string" ||
-    value.upstream.commit.length === 0 ||
-    typeof value.adaptationRevision !== "number" ||
-    !Number.isInteger(value.adaptationRevision) ||
-    value.adaptationRevision < 1 ||
-    (value.scope !== "project" && value.scope !== "global") ||
-    typeof value.target !== "string" ||
-    !Array.isArray(value.files)
-  ) {
-    return undefined;
-  }
-  const files: OwnershipManifest["files"] = [];
-  for (const file of value.files) {
-    if (
-      !isRecord(file) ||
-      !exactKeys(file, ["path", "sha256"]) ||
-      typeof file.path !== "string" ||
-      !validRelativePath(file.path) ||
-      file.path === OWNERSHIP_MANIFEST ||
-      typeof file.sha256 !== "string" ||
-      !/^[a-f0-9]{64}$/.test(file.sha256)
-    ) {
-      return undefined;
-    }
-    files.push({ path: file.path, sha256: file.sha256 });
-  }
-  const paths = files.map((file) => file.path);
-  if (new Set(paths).size !== paths.length || paths.join("\0") !== [...paths].sort().join("\0")) {
-    return undefined;
-  }
-  return {
-    schemaVersion: 1,
-    owner: OWNER,
-    packageVersion: value.packageVersion,
-    upstream: { tag: value.upstream.tag, commit: value.upstream.commit },
-    adaptationRevision: value.adaptationRevision,
-    scope: value.scope,
-    target: value.target,
-    files,
-  };
-}
-
-async function listTree(root: string): Promise<{ files: string[]; symlink: boolean }> {
-  const files: string[] = [];
-  let symlink = false;
-  async function visit(directory: string): Promise<void> {
-    const entries = await fs.readdir(join(root, directory), { withFileTypes: true });
-    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
-      const path = directory ? `${directory}/${entry.name}` : entry.name;
-      if (entry.isSymbolicLink()) {
-        symlink = true;
-        files.push(path);
-      } else if (entry.isDirectory()) {
-        await visit(path);
-      } else {
-        files.push(path);
-      }
-    }
-  }
-  await visit("");
-  return { files: files.sort(), symlink };
-}
-
-async function loadArtifacts(packageRoot: string): Promise<{
-  manifest: ArtifactManifest;
-  contents: Map<string, Uint8Array>;
-}> {
-  const initRoot = join(packageRoot, "dist", "init");
-  let manifest: ArtifactManifest;
-  try {
-    manifest = parseArtifactManifest(await readJson(join(initRoot, "manifest.json")));
-  } catch (error) {
-    throw new Error(`Invalid packaged artifact manifest: ${error instanceof Error ? error.message : String(error)}`);
-  }
-  const contents = new Map<string, Uint8Array>();
-  for (const file of manifest.files) {
-    const path = join(initRoot, "artifacts", "beads", file.path);
-    const stats = await fs.lstat(path).catch(() => undefined);
-    if (!stats?.isFile() || stats.isSymbolicLink()) {
-      throw new Error(`Invalid packaged artifact ${file.path}: missing, symlinked, or not a file`);
-    }
-    const content = await fs.readFile(path);
-    if (content.byteLength !== file.bytes || sha256(content) !== file.sha256) {
-      throw new Error(`Invalid packaged artifact ${file.path}: size or checksum mismatch`);
-    }
-    contents.set(file.path, content);
-  }
-  const tree = await listTree(join(initRoot, "artifacts", "beads"));
-  if (tree.symlink || tree.files.join("\0") !== manifest.files.map((file) => file.path).join("\0")) {
-    throw new Error("Invalid packaged artifacts: inventory differs from manifest");
-  }
-  return { manifest, contents };
-}
-
-function expectedOwnership(
-  artifact: ArtifactManifest,
-  packageVersion: string,
-  scope: InitScope,
-  target: string
-): OwnershipManifest {
-  return {
-    schemaVersion: 1,
-    owner: OWNER,
-    packageVersion,
-    upstream: { tag: artifact.upstream.tag, commit: artifact.upstream.commit },
-    adaptationRevision: artifact.adaptationRevision,
-    scope,
-    target,
-    files: artifact.files.map(({ path, sha256: hash }) => ({ path, sha256: hash })),
-  };
-}
-
-async function inspectTarget(
-  target: string,
-  scope: InitScope,
-  expected: OwnershipManifest
-): Promise<{ state: InitState; ownership?: OwnershipManifest }> {
-  let stats;
-  try {
-    stats = await fs.lstat(target);
-  } catch (error) {
-    if (isMissing(error)) return { state: "missing" };
-    return { state: "conflicting" };
-  }
-  if (!stats.isDirectory() || stats.isSymbolicLink()) return { state: "conflicting" };
-
-  const manifestPath = join(target, OWNERSHIP_MANIFEST);
-  const manifestStats = await fs.lstat(manifestPath).catch(() => undefined);
-  if (!manifestStats?.isFile() || manifestStats.isSymbolicLink()) return { state: "conflicting" };
-  let ownership: OwnershipManifest | undefined;
-  try {
-    ownership = parseOwnershipManifest(await readJson(manifestPath));
-  } catch {
-    return { state: "conflicting" };
-  }
-  if (!ownership || resolve(ownership.target) !== target || ownership.scope !== scope) {
-    return { state: "conflicting" };
-  }
-
-  const tree = await listTree(target);
-  const expectedFiles = [...ownership.files.map((file) => file.path), OWNERSHIP_MANIFEST].sort();
-  if (tree.symlink || tree.files.join("\0") !== expectedFiles.join("\0")) {
-    return { state: "modified", ownership };
-  }
-  for (const file of ownership.files) {
-    const content = await fs.readFile(join(target, file.path)).catch(() => undefined);
-    if (!content || sha256(content) !== file.sha256) return { state: "modified", ownership };
-  }
-  const metadataMatches =
-    ownership.packageVersion === expected.packageVersion &&
-    ownership.upstream.tag === expected.upstream.tag &&
-    ownership.upstream.commit === expected.upstream.commit &&
-    ownership.adaptationRevision === expected.adaptationRevision &&
-    ownership.scope === expected.scope &&
-    ownership.target === expected.target &&
-    JSON.stringify(ownership.files) === JSON.stringify(expected.files);
-  return metadataMatches
-    ? { state: "current", ownership }
-    : { state: "stale", ownership };
-}
-
-function targetFor(
-  worktree: string,
-  opencodeConfigDirectory: string,
-  scope: InitScope
-): string {
-  return scope === "global"
-    ? resolve(opencodeConfigDirectory, "skills", "beads")
-    : resolve(worktree, ".opencode", "skills", "beads");
-}
-
-async function assertNoTargetSymlink(target: string, boundary: string): Promise<void> {
-  const parts = relative(resolve(boundary), target).split(sep).filter(Boolean);
-  let current = resolve(boundary);
-  for (const part of parts) {
-    current = join(current, part);
-    const stats = await fs.lstat(current).catch((error) => {
-      if (isMissing(error)) return undefined;
-      throw error;
-    });
-    if (stats?.isSymbolicLink()) throw new Error(`Refusing symlink in target path: ${current}`);
-  }
-}
-
-function refusal(command: InitCommand, state: InitState): string | undefined {
-  if (command === "check") return undefined;
-
-  const isManagedState = state === "current" || state === "stale";
-  if (command === "init") {
-    return state === "modified" || state === "conflicting"
-      ? `Refusing to initialize ${state} skill`
-      : undefined;
-  }
-  if (command === "update") {
-    return isManagedState ? undefined : `Refusing to update ${state} skill`;
-  }
-  return isManagedState ? undefined : `Refusing to remove ${state} skill`;
-}
-
-async function installPlan(target: string, old: OwnershipManifest | undefined, expected: OwnershipManifest): Promise<InitPlanOperation[]> {
-  const operations: InitPlanOperation[] = [];
-  const targetStats = await fs.lstat(target).catch(() => undefined);
-  const references = join(target, "references");
-  const referenceStats = await fs.lstat(references).catch(() => undefined);
-  if (!targetStats) operations.push({ action: "mkdir", path: target });
-  if (!referenceStats) operations.push({ action: "mkdir", path: references });
-  const expectedPaths = new Set(expected.files.map((file) => file.path));
-  for (const path of old?.files.map((file) => file.path).filter((path) => !expectedPaths.has(path)).sort() ?? []) {
-    operations.push({ action: "remove", path: join(target, path) });
-  }
-  const expectedDirectories = new Set(expected.files.map((file) => dirname(file.path)).filter((path) => path !== "."));
-  const obsoleteDirectories = new Set<string>();
-  for (const file of old?.files ?? []) {
-    for (let directory = dirname(file.path); directory !== "."; directory = dirname(directory)) {
-      if (!expectedDirectories.has(directory)) obsoleteDirectories.add(directory);
-    }
-  }
-  for (const directory of [...obsoleteDirectories].sort().reverse()) {
-    operations.push({ action: "rmdir", path: join(target, directory) });
-  }
-  for (const file of expected.files) operations.push({ action: "write-payload", path: join(target, file.path) });
-  operations.push({ action: "write-manifest", path: join(target, OWNERSHIP_MANIFEST) });
-  return operations;
-}
-
-function removePlan(target: string, ownership: OwnershipManifest): InitPlanOperation[] {
-  const directories = new Set<string>();
-  for (const file of ownership.files) {
-    for (let directory = dirname(file.path); directory !== "."; directory = dirname(directory)) {
-      directories.add(directory);
-    }
-  }
-  return [
-    ...ownership.files.map((file) => ({ action: "remove" as const, path: join(target, file.path) })),
-    { action: "remove", path: join(target, OWNERSHIP_MANIFEST) },
-    ...[...directories]
-      .sort((left, right) => right.split("/").length - left.split("/").length || left.localeCompare(right))
-      .map((directory) => ({ action: "rmdir" as const, path: join(target, directory) })),
-    { action: "rmdir", path: target },
-  ];
-}
-
-function transactionPrefix(target: string, kind: "backup" | "recovery" | "stage"): string {
-  return `.${basename(target)}.opencode-beads-${kind}-`;
-}
-
-async function staleTransactions(target: string): Promise<string[]> {
-  const parent = dirname(target);
-  const entries = await fs.readdir(parent).catch((error) => {
-    if (isMissing(error)) return [];
-    throw error;
-  });
-  const prefixes = (["backup", "recovery", "stage"] as const).map((kind) => transactionPrefix(target, kind));
-  return entries
-    .filter((entry) => prefixes.some((prefix) => entry.startsWith(prefix)))
-    .sort()
-    .map((entry) => join(parent, entry));
-}
-
-async function cleanup(mutationFs: InitMutationFileSystem, path: string): Promise<void> {
-  await mutationFs.rm(path, { recursive: true, force: true }).catch(() => undefined);
-}
-
-async function buildStage(
-  contents: Map<string, Uint8Array>,
-  ownership: OwnershipManifest,
-  target: string,
-  mutationFs: InitMutationFileSystem
-): Promise<string> {
-  await mutationFs.mkdir(dirname(target), { recursive: true });
-  const stage = await mutationFs.mkdtemp(join(dirname(target), transactionPrefix(target, "stage")));
-  try {
-    for (const file of ownership.files) {
-      const content = contents.get(file.path);
-      if (!content) throw new Error(`Missing planned payload for ${file.path}`);
-      await mutationFs.mkdir(dirname(join(stage, file.path)), { recursive: true });
-      await mutationFs.writeFile(join(stage, file.path), content, { flag: "wx" });
-    }
-    await mutationFs.writeFile(
-      join(stage, OWNERSHIP_MANIFEST),
-      `${JSON.stringify(ownership, null, 2)}\n`,
-      { flag: "wx" }
-    );
-    return stage;
-  } catch (error) {
-    await cleanup(mutationFs, stage);
-    throw error;
-  }
-}
-
-async function installTransaction(
-  target: string,
-  targetExists: boolean,
-  contents: Map<string, Uint8Array>,
-  ownership: OwnershipManifest,
-  mutationFs: InitMutationFileSystem
-): Promise<void> {
-  const stage = await buildStage(contents, ownership, target, mutationFs);
-  if (!targetExists) {
-    try {
-      await mutationFs.rename(stage, target);
-    } catch (error) {
-      await cleanup(mutationFs, stage);
-      throw error;
-    }
-    return;
-  }
-
-  let backup: string | undefined;
-  let recovery: string | undefined;
-  let moved = false;
-  try {
-    backup = await mutationFs.mkdtemp(join(dirname(target), transactionPrefix(target, "backup")));
-    recovery = await mutationFs.mkdtemp(join(dirname(target), transactionPrefix(target, "recovery")));
-    await mutationFs.rmdir(backup);
-    await mutationFs.rmdir(recovery);
-    await mutationFs.rename(target, backup);
-    moved = true;
-    await mutationFs.cp(backup, recovery, { recursive: true, errorOnExist: true, force: false });
-    await mutationFs.rename(stage, target);
-    try {
-      await mutationFs.rm(backup, { recursive: true });
-    } catch (error) {
-      await mutationFs.rename(target, stage);
-      await mutationFs.rename(recovery, target);
-      await cleanup(mutationFs, stage);
-      await cleanup(mutationFs, backup);
-      throw error;
-    }
-    await cleanup(mutationFs, recovery);
-  } catch (error) {
-    if (moved && !(await fs.exists(target))) {
-      const restore = backup && (await fs.exists(backup)) ? backup : recovery;
-      if (restore && (await fs.exists(restore))) await mutationFs.rename(restore, target);
-    }
-    await cleanup(mutationFs, stage);
-    if (backup) await cleanup(mutationFs, backup);
-    if (recovery) await cleanup(mutationFs, recovery);
-    throw error;
-  }
-}
-
-async function removeTransaction(target: string, mutationFs: InitMutationFileSystem): Promise<void> {
-  let backup: string | undefined;
-  let recovery: string | undefined;
-  let moved = false;
-  try {
-    backup = await mutationFs.mkdtemp(join(dirname(target), transactionPrefix(target, "backup")));
-    recovery = await mutationFs.mkdtemp(join(dirname(target), transactionPrefix(target, "recovery")));
-    await mutationFs.rmdir(backup);
-    await mutationFs.rmdir(recovery);
-    await mutationFs.rename(target, backup);
-    moved = true;
-    await mutationFs.cp(backup, recovery, { recursive: true, errorOnExist: true, force: false });
-    await mutationFs.rm(backup, { recursive: true });
-    await cleanup(mutationFs, recovery);
-  } catch (error) {
-    if (moved && !(await fs.exists(target))) {
-      const restore = recovery && (await fs.exists(recovery)) ? recovery : backup;
-      if (restore && (await fs.exists(restore))) await mutationFs.rename(restore, target);
-    }
-    if (backup) await cleanup(mutationFs, backup);
-    if (recovery) await cleanup(mutationFs, recovery);
-    throw error;
-  }
-}
-
-/** Validate, inspect, plan, and optionally execute one managed-skill lifecycle command. */
-export async function runInitCommand(command: InitCommand, inputs: InitInputs): Promise<InitResult> {
-  const scope = inputs.scope ?? "project";
-  const cwd = resolve(inputs.cwd);
-  const worktree = resolve(inputs.worktree);
-  const home = resolve(inputs.home);
-  const opencodeConfigDirectory = resolve(
-    inputs.opencodeConfigDirectory ?? join(home, ".config", "opencode")
-  );
-  const target = targetFor(worktree, opencodeConfigDirectory, scope);
-  // This call validates cwd containment even when no collision locations exist.
-  beadsSkillLocations(cwd, worktree, home, opencodeConfigDirectory);
-  const { manifest: artifact, contents } = await loadArtifacts(resolve(inputs.packageRoot));
-  const expected = expectedOwnership(artifact, inputs.packageVersion, scope, target);
-  await assertNoTargetSymlink(
-    target,
-    scope === "global" ? dirname(opencodeConfigDirectory) : worktree
-  );
-  const transactions = await staleTransactions(target);
-  const targetInspection = await inspectTarget(target, scope, expected);
-
-  const inspections = await inspectBeadsSkillLocations(
-    cwd,
-    worktree,
-    home,
-    async (location: SkillLocation): Promise<ManagedSkillState | "differently-managed" | undefined> => {
-      const locationScope = location.scope;
-      const locationExpected = expectedOwnership(artifact, inputs.packageVersion, locationScope, resolve(location.path));
-      const inspection = await inspectTarget(resolve(location.path), locationScope, locationExpected);
-      if (inspection.state === "current" || inspection.state === "stale" || inspection.state === "modified") return inspection.state;
-      if (inspection.state === "conflicting") return "differently-managed";
-      return undefined;
-    },
-    opencodeConfigDirectory
-  );
-  const discoveryCollisions = inspections
-    .filter((inspection) => resolve(inspection.path) !== target && inspection.state !== "absent")
-    .map((inspection) => resolve(inspection.path));
-  const collisions = [...transactions, ...discoveryCollisions].sort();
-  const blockedByCollision =
-    transactions.length > 0 || (command !== "remove" && discoveryCollisions.length > 0);
-  const state: InitState = blockedByCollision ? "conflicting" : targetInspection.state;
-  const error = refusal(command, state);
-  const canMutate = error === undefined;
-  const shouldInstall =
-    canMutate &&
-    ((command === "init" && (state === "missing" || state === "stale")) ||
-      (command === "update" && state === "stale"));
-  const shouldRemove = canMutate && command === "remove";
-
-  let plan: InitPlanOperation[] = [];
-  if (shouldInstall) {
-    plan = await installPlan(target, targetInspection.ownership, expected);
-  } else if (shouldRemove && targetInspection.ownership) {
-    plan = removePlan(target, targetInspection.ownership);
-  }
-  const changed = plan.length > 0;
-  if (canMutate && changed && !inputs.dryRun) {
-    const mutationFs = inputs.mutationFileSystem ?? fs;
-    if (shouldInstall) {
-      await installTransaction(target, targetInspection.state !== "missing", contents, expected, mutationFs);
-    } else {
-      await removeTransaction(target, mutationFs);
-    }
-  }
-  return {
-    command,
-    scope,
-    target,
-    state,
-    ok: error === undefined,
-    changed,
-    dryRun: inputs.dryRun ?? false,
-    plan,
-    collisions,
-    ...(error ? { error } : {}),
-  };
-}

package/src/skill-collision-policy.ts

@@ -1,133 +0,0 @@
-import { lstat } from "node:fs/promises";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-
-const SKILL_ROOTS = [".opencode", ".agents", ".claude"] as const;
-
-export type SkillScope = "global" | "project";
-export type ManagedSkillState = "current" | "modified" | "stale";
-export type SkillLocationState =
-  | "absent"
-  | "differently-managed"
-  | "managed-current"
-  | "managed-modified"
-  | "managed-stale"
-  | "unmanaged";
-
-export interface SkillLocation {
-  path: string;
-  root: (typeof SKILL_ROOTS)[number];
-  scope: SkillScope;
-}
-
-export interface SkillLocationInspection extends SkillLocation {
-  state: SkillLocationState;
-}
-
-export type ManagedSkillInspector = (
-  location: SkillLocation
-) => Promise<ManagedSkillState | "differently-managed" | undefined>;
-
-function isMissing(error: unknown): boolean {
-  return (
-    typeof error === "object" &&
-    error !== null &&
-    "code" in error &&
-    error.code === "ENOENT"
-  );
-}
-
-/** Resolve every project and global discovery location for a skill named beads. */
-export function beadsSkillLocations(
-  cwd: string,
-  worktree: string,
-  homeDirectory: string,
-  opencodeConfigDirectory = join(homeDirectory, ".config", "opencode")
-): SkillLocation[] {
-  const canonicalCwd = resolve(cwd);
-  const canonicalWorktree = resolve(worktree);
-  const fromWorktree = relative(canonicalWorktree, canonicalCwd);
-  if (fromWorktree === ".." || fromWorktree.startsWith(`..${sep}`) || isAbsolute(fromWorktree)) {
-    throw new Error(`cwd must be within worktree: ${canonicalCwd}`);
-  }
-
-  const projectDirectories: string[] = [];
-  for (let current = canonicalCwd; ; current = dirname(current)) {
-    projectDirectories.push(current);
-    if (current === canonicalWorktree) break;
-  }
-
-  const locations = [
-    ...projectDirectories.flatMap((directory) =>
-      SKILL_ROOTS.map((root) => ({
-        path: resolve(directory, root, "skills", "beads"),
-        root,
-        scope: "project" as const,
-      }))
-    ),
-    ...SKILL_ROOTS.map((root) => ({
-      path:
-        root === ".opencode"
-          ? join(opencodeConfigDirectory, "skills", "beads")
-          : join(homeDirectory, root, "skills", "beads"),
-      root,
-      scope: "global" as const,
-    })),
-  ];
-  const uniqueLocations: SkillLocation[] = [];
-  const seenPaths = new Set<string>();
-  for (const location of locations) {
-    if (seenPaths.has(location.path)) continue;
-    seenPaths.add(location.path);
-    uniqueLocations.push(location);
-  }
-  return uniqueLocations;
-}
-
-/** Inspect all discovery locations without mutating them. */
-export async function inspectBeadsSkillLocations(
-  cwd: string,
-  worktree: string,
-  homeDirectory: string,
-  inspectManaged: ManagedSkillInspector,
-  opencodeConfigDirectory = join(homeDirectory, ".config", "opencode")
-): Promise<SkillLocationInspection[]> {
-  return Promise.all(
-    beadsSkillLocations(cwd, worktree, homeDirectory, opencodeConfigDirectory).map(
-      async (location) => {
-        let stats;
-        try {
-          stats = await lstat(location.path);
-        } catch (error) {
-          if (isMissing(error)) return { ...location, state: "absent" as const };
-          return { ...location, state: "unmanaged" as const };
-        }
-
-        if (!stats.isDirectory() || stats.isSymbolicLink()) {
-          return { ...location, state: "unmanaged" as const };
-        }
-
-        const managedState = await inspectManaged(location).catch(() => undefined);
-        let state: SkillLocationState = "unmanaged";
-        if (managedState === "differently-managed") {
-          state = managedState;
-        } else if (managedState) {
-          state = `managed-${managedState}`;
-        }
-        return { ...location, state };
-      }
-    )
-  );
-}
-
-/** Return every location that prevents a managed operation at the requested target. */
-export function blockingSkillCollisions(
-  inspections: ReadonlyArray<SkillLocationInspection>,
-  target: string
-): SkillLocationInspection[] {
-  const resolvedTarget = resolve(target);
-  return inspections.filter((inspection) => {
-    if (inspection.state === "absent") return false;
-    if (resolve(inspection.path) !== resolvedTarget) return true;
-    return inspection.state !== "managed-current" && inspection.state !== "managed-stale";
-  });
-}