@snarkipus/opencode-beads 1.1.0-beta.1 → 1.1.0-beta.2

package/README.md

@@ -7,21 +7,21 @@
 
 [Beads](https://github.com/gastownhall/beads) issue tracker integration for [OpenCode](https://opencode.ai).
 
-`@snarkipus/opencode-beads` is a maintained OpenCode adapter that gives OpenCode 2 the integration `bd setup claude` gives Claude Code: `bd prime` workflow context on every request, refreshed after compaction and when a session resumes, plus a bounded task agent. Published 1.0.2 completes one Bead per invocation; the beta/next candidate below follows the authorized scope. It does not replace Beads: the installed `bd` CLI remains authoritative for issues, project initialization, skills, migrations, backups, and Dolt synchronization.
+`@snarkipus/opencode-beads` is a maintained OpenCode adapter that gives OpenCode 2 the integration `bd setup claude` gives Claude Code: `bd prime` workflow context on every request, refreshed after compaction and when a session resumes, plus a bounded task agent. Published 1.0.2 completes one Bead per invocation; the published beta/next release follows the authorized scope. It does not replace Beads: the installed `bd` CLI remains authoritative for issues, project initialization, skills, migrations, backups, and Dolt synchronization.
 
 This is an independent project maintained by Matt Jackson under the MIT license. It began as a fork of [Josh Thomas's `opencode-beads`](https://github.com/joshuadavidthomas/opencode-beads), and the original work remains credited to its author. 1.0 rebuilt the plugin for OpenCode 2, and development now continues here independently. It vendors nothing from upstream Beads; instead, every Beads release is checked against the `bd` behavior the plugin relies on (see [Tracking upstream Beads](#tracking-upstream-beads)).
 
-This branch prepares **1.1.0-beta.1**, an opt-in beta for npm dist-tag `next`; publication remains pending owner approval. The beta's normal public entrypoint enables the eleven qualified operations in the native `beads` code-mode namespace on supported hosts: find, get, edges, memories, recall, claim, note, selected-field update, close, create and remember. No wrapper, internal dependency injection, manual skill copy or activation setting is needed. The opt-in is selecting the beta artifact. The published stable 1.0.2 package is unchanged.
+This release is **1.1.0-beta.2**, an opt-in beta targeting npm dist-tag `next`; its integration diagnostic command is `oc-beads:diagnostics`. Beta.1 used `oc-beads:status`; the rename is documented below. The beta's normal public entrypoint enables the eleven qualified operations in the native `beads` code-mode namespace on supported hosts: find, get, edges, memories, recall, claim, note, selected-field update, close, create and remember. No wrapper, internal dependency injection, manual skill copy or activation setting is needed. The opt-in is selecting the beta artifact. The published stable 1.0.2 package is unchanged.
 
-The beta registers 29 `oc-beads:<stem>` workflows plus `oc-beads:status` through ordinary native command registration and owns its packaged `oc-beads` skill at the installed path, with all 15 corpus resources plus CODE_MODE and ADR (17 links). User configuration/file commands retain native precedence on load and rebuild; removing an override restores the package definition. Other plugin conflicts follow native ordering. Status reports observed registration and name/description mismatches; identical-description overrides and public owner identity remain unobservable.
+Beta.2 registers 29 `oc-beads:<stem>` workflows plus `oc-beads:diagnostics` through ordinary native command registration and owns its packaged `oc-beads` skill at the installed path, with all 15 corpus resources plus CODE_MODE and ADR (17 links). User configuration/file commands retain native precedence on load and rebuild; removing an override restores the package definition. Other plugin conflicts follow native ordering. Diagnostics reports observed registration and name/description mismatches; identical-description overrides and public owner identity remain unobservable.
 
-Typed registration requires the host tool, permission and session interfaces. Status reports unavailable interfaces honestly; actual request capabilities, catalog discovery and per-operation permissions determine which operations can run. Native shell remains direct-only and cannot be called inside execute. Structured results preserve partial, failed and uncertain outcomes, and writes retain the actual session-and-agent Beads actor. Read [CODE_MODE.md](assets/oc-beads/resources/CODE_MODE.md) for composition and recovery.
+Typed registration requires the host tool, permission and session interfaces. The integration diagnostic command reports unavailable interfaces honestly; actual request capabilities, catalog discovery and per-operation permissions determine which operations can run. Native shell remains direct-only and cannot be called inside execute. Structured results preserve partial, failed and uncertain outcomes, and writes retain the actual session-and-agent Beads actor. Read [CODE_MODE.md](assets/oc-beads/resources/CODE_MODE.md) for composition and recovery.
 
-All 16 implementation tasks have parent acceptance on exact OpenCode 2.1.1 / Beads 1.3.1. The [final acceptance record](docs/code-mode-final-acceptance-vuy9.md) and [bounded installed/model evaluation](docs/opencode-installed-model-continuation-vuy9.md) retain their historical candidates and probes; this beta adds the public entrypoint and release-channel wiring. **Known limitation:** plain decline of a nested permission request does not stop the entire composition; a later independent operation can ask again. Use explicit Stop/Cancel to stop the composition. No token-saving, cross-provider checkpoint portability or multi-hour reliability claim is made.
+All 16 implementation tasks have parent acceptance on exact OpenCode 2.1.1 / Beads 1.3.1. The [final acceptance record](docs/code-mode-final-acceptance-vuy9.md) and [bounded installed/model evaluation](docs/opencode-installed-model-continuation-vuy9.md) retain their historical candidates and probes; the published beta adds the public entrypoint and release-channel wiring. **Known limitation:** plain decline of a nested permission request does not stop the entire composition; a later independent operation can ask again. Use explicit Stop/Cancel to stop the composition. No token-saving, cross-provider checkpoint portability or multi-hour reliability claim is made.
 
 ## Design
 
-The beta/next candidate uses scope-bounded task execution:
+The published beta/next release uses scope-bounded task execution:
 
 - The primary OpenCode thread retains planning context, decisions, and control.
 - An exact assignment or explicit one-bead mode stops with that item; read-only graph requests never authorize claims or writes.
@@ -41,19 +41,19 @@ The beta requires OpenCode `>=2.1.1 <2.2` and `bd` 1.3.1 or later. Exact OpenCod
 
    `bd init` owns project initialization and creates the canonical shared Beads skill at `.agents/skills/beads`, which OpenCode discovers. It also writes a minimal Beads section to `AGENTS.md` that points to `bd prime`, the same pointer Beads gives Claude Code in `CLAUDE.md`. The published stable package relies on that shared skill. The beta additionally owns its packaged `oc-beads` skill; it does not write startup files or change `.agents/skills/beads/SKILL.md`.
 
-2. After beta publication, add the version-pinned plugin to `~/.config/opencode/opencode.json` for every project, or to a project's `.opencode/opencode.json`:
+2. Add the published, version-pinned plugin to `~/.config/opencode/opencode.json` for every project, or to a project's `.opencode/opencode.json`:
 
    ```json
    {
-     "plugins": ["@snarkipus/opencode-beads@1.1.0-beta.1"]
+     "plugins": ["@snarkipus/opencode-beads@1.1.0-beta.2"]
    }
    ```
 
-   To follow the beta channel after publication, use `"plugins": ["@snarkipus/opencode-beads@next"]` instead. To stay on stable, use `"plugins": ["@snarkipus/opencode-beads@latest"]` (currently 1.0.2); do not select the beta. Stable promotion requires separate approval.
+   To follow the published beta channel, use `"plugins": ["@snarkipus/opencode-beads@next"]` instead. To stay on stable, use `"plugins": ["@snarkipus/opencode-beads@latest"]` (currently 1.0.2); do not select the beta. Stable promotion requires separate approval.
 
    OpenCode loads configuration changes automatically. Update the pin explicitly when upgrading; an unpinned package entry is less reproducible. OpenCode 1.x plugins are not supported; use 0.10.x or earlier there.
 
-3. Check the install: `opencode debug agents` lists `beads-task-agent`; `/oc-beads:status` reports native registration and observed capabilities. Discover `beads` through execute on a host/agent with the required permissions.
+3. Check the beta.2 install: `opencode debug agents` lists `beads-task-agent`; `/oc-beads:diagnostics` reports native registration and observed capabilities. Discover `beads` through execute on a host/agent with the required permissions. An installation still pinned to beta.1 continues to use `/oc-beads:status` until explicitly upgraded.
 
 ### Plugin options
 
@@ -63,7 +63,7 @@ Plugin options use the object form:
 {
   "plugins": [
     {
-      "package": "@snarkipus/opencode-beads@1.1.0-beta.1",
+      "package": "@snarkipus/opencode-beads@1.1.0-beta.2",
       "options": { "luna": true, "autoMigrate": false }
     }
   ]
@@ -119,7 +119,13 @@ Before running prime, the plugin checks `bd version` and the configuration-only
 
 Published stable 1.0.2 registers no slash commands; `bd setup claude` installs none either. Ask the agent to work with Beads, have it load the canonical `beads` skill that `bd init` installs at `.agents/skills/beads` (OpenCode lists it and loads it with its `skill` tool), or use the `bd` CLI and the generated [Beads CLI reference](https://beads.gascity.com/cli-reference/index) directly. Versions before 1.0.0 shipped `/beads:*` commands adapted from upstream's Claude Code plugin; they duplicated `bd prime` and the skill.
 
-## Removal and customization in the source candidate
+The commands are workflow prompts, not exact CLI aliases. In particular, init guides human onboarding, prime reuses context or requests a guarded refresh, version reports installed versions and qualification limits, decision records rationale, template discovers formulas, and workflow guides authorized work and recovery. These purposes do not imply native `bd decision`, `bd template` or `bd workflow` commands.
+
+Starting with beta.2, the package-owned `oc-beads:status` is removed without an alias. Use `oc-beads:diagnostics` for integration health and `oc-beads:stats` for the issue-database overview via `bd status` (alias `bd stats`). User-defined old status overrides are untouched and are not migrated; the package does not edit configuration.
+
+`oc-beads:compact` guides semantic issue compaction with `bd admin compact`; `bd compact` squashes Dolt history and is a different operation. Neither is conversation compaction. A bare invocation explains the workflow; action requires explicit operation and authority. See the packaged [compact guidance](assets/oc-beads/resources/TROUBLESHOOTING.md) for mode/actor boundaries and upstream help uncertainty. `oc-beads:restore` retrieves pre-compaction issue content, displaying it by default; `--apply` requires explicit authority to write it back and does not mean database backup recovery. Quickstart uses installed help and authorized context; sync guides Dolt-remote synchronization, distinct from `bd federation sync`.
+
+## Removal and customization
 
 Remove the plugin's `plugins` entry to unload it. Cleanup aborts owned context/process work and its event observer, then awaits the scoped agent, skill, tool and hook disposers. It is idempotent and reports disposal failures. It never promises a final checkpoint after interruption. Reload starts with fresh session/location state. Package updates/removal belong to OpenCode's package lifecycle; this plugin has no installer or recursive asset watcher.
 

package/assets/oc-beads/SKILL.md

@@ -31,6 +31,25 @@ When typed composition is available, discover current signatures through native
 Follow [code-mode composition](resources/CODE_MODE.md) for bounded reads,
 projection, ordered writes, completeness, uncertainty and decline/Stop semantics.
 
+## Command purposes
+
+The package's commands are workflow prompts, not exact CLI aliases. Use
+`oc-beads:diagnostics` for integration discovery, compatibility and context health
+without opening a store; use `oc-beads:stats` for the issue-database overview via
+`bd status` (alias `bd stats`). The old package status name has no alias; user-owned
+old-name overrides remain untouched without migration.
+
+Broader workflows retain their purposes: init guides human onboarding, prime uses
+current context or a guarded refresh, version reports installed versions and
+qualification limits, decision records rationale, template discovers formulas,
+and workflow guides authorized work/recovery. They do not invent absent native
+commands. Quickstart uses installed `bd quickstart` help and authorized context.
+Compact targets semantic `bd admin compact`, not Dolt-history `bd compact` or
+conversation compaction; restore retrieves pre-compaction issue content, displaying
+it by default and requiring explicit write authority for `--apply`. Sync means
+Dolt-remote synchronization, distinct from `bd federation sync`. Follow the linked
+CLI reference, troubleshooting, resumability and worktree guidance before action.
+
 ## Work within the assigned scope
 
 - Read the relevant issue and its dependencies before changing tracked state.

package/assets/oc-beads/resources/CLI_REFERENCE.md

@@ -18,3 +18,25 @@ If a command or flag in an old example is absent from current help, do not guess
 its spelling or use a hidden interface. State the limitation and use a supported
 equivalent only when it preserves the requested outcome and authority. A static
 resource cannot prove installed host behavior or package delivery.
+
+## Package workflows and native operations
+
+Package commands are workflow prompts, not exact CLI aliases. `oc-beads:diagnostics`
+reports integration health without opening a store; `oc-beads:stats` guides the
+issue-database overview using `bd status` (alias `bd stats`). The package's old
+status command is removed without an alias; user-owned old-name overrides remain
+untouched and are not migrated.
+
+Init guides human onboarding; prime uses supplied context or a guarded refresh;
+version reports installed versions and qualification limits; decision records
+rationale; template discovers formulas; workflow guides authorized work/recovery.
+Do not manufacture native decision, template or workflow commands. Quickstart
+uses installed `bd quickstart` help and authorized context, without implicit setup.
+
+Compact guides semantic `bd admin compact`, not `bd compact` Dolt-history
+squashing or conversation compaction; consult TROUBLESHOOTING.md for authority,
+modes, explicit actor and inconsistent upstream help. Restore retrieves
+pre-compaction issue content, display-only by default; `--apply` needs explicit
+write authority and is not database backup recovery (see RESUMABILITY.md). Sync
+uses Dolt-remote synchronization, distinct from `bd federation sync` and removed
+JSONL sync (see WORKTREES.md). Inspect installed help and preserve authority.

package/assets/oc-beads/resources/RESUMABILITY.md

@@ -81,3 +81,12 @@ manual fallback. If a write timed out, read the issue before retrying; the first
 write may have landed. Preserve uncertainty explicitly until it is resolved.
 
 Use the current CLI syntax from `bd prime` and command help when authorized.
+
+## Restore pre-compaction issue content
+
+`oc-beads:restore` guides `bd restore` retrieval of pre-compaction issue content,
+display-only by default. `--apply` requires explicit authority to write that
+content back to the issue. This is not database backup recovery, Git history
+restoration or general store repair. Inspect installed help and report missing
+content or uncertainty honestly; conflicting compact/restore help does not
+establish guaranteed recovery or reversibility.

package/assets/oc-beads/resources/TROUBLESHOOTING.md

@@ -19,6 +19,28 @@ limitation and use a documented replacement only when it preserves the needed
 semantics. The specialized `bd agent` and `bd slot` commands are absent from the
 inspected CLI; see [AGENTS.md](AGENTS.md).
 
+## Compact operation and authority
+
+`oc-beads:compact` guides semantic issue compaction with `bd admin compact`.
+`bd compact` squashes Dolt history and is a different operation; neither means
+conversation compaction. A bare invocation explains the workflow, not authority
+to act. Clarify the operation and scope when a request is ambiguous, and inspect
+applicable installed help before any explicitly authorized action.
+
+Prefer the agent-driven analyze/apply path. `--auto` sends issue content to an
+external AI provider; `--dolt` performs storage garbage collection rather than
+semantic summarization. These modes each require separate explicit authority;
+ordinary compact approval selects neither. Always supply explicit `--actor`
+for admin compact, which has its own local default of `agent`; do not inherit
+that default or the human Git identity.
+
+In the inspected Beads 1.3.1 help, admin compact's Usage/flags identify the semantic
+operation but its examples still say `bd compact`. Its discard wording also
+conflicts with restore's snapshot description. Do not copy those stale examples
+or promise reversibility from that conflicting help. Report the uncertainty and
+use applicable help and explicit authority for a future actual request. Do not
+execute administration to validate this prose or repair upstream behavior.
+
 ## Store, migration, or routing problem
 
 If the CLI reports no store, an outdated schema, an unexpected location, or a

package/assets/oc-beads/resources/WORKTREES.md

@@ -17,3 +17,8 @@ Use `bd worktree --help` and relevant subcommand help for current commands and
 safety checks. Inspect local changes before removal, preserve work that is not
 yours, and remove only a worktree whose cleanup is authorized. This resource
 does not create or clean up a worktree automatically.
+
+`oc-beads:sync` guides `bd sync` Dolt-remote synchronization, distinct from
+`bd federation sync` and removed JSONL sync. Inspect current help and synchronize
+only with explicit authority. Report conflicts without forcing a side; the
+installed Beads CLI owns synchronization and consistency semantics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snarkipus/opencode-beads",
-  "version": "1.1.0-beta.1",
+  "version": "1.1.0-beta.2",
   "type": "module",
   "description": "A maintained OpenCode V2 integration for the Beads issue tracker: bd prime context injection with a schema-migration guard, and a bounded task agent.",
   "author": "Matt Jackson",

package/src/host.ts

@@ -254,7 +254,7 @@ export async function setupBeads(
         try { effectiveSkills = ctx.skill ? (await ctx.skill.list()).data.map((entry) => String(entry.id)) : "unavailable"; }
         catch { effectiveSkills = "unavailable: registry lookup failed"; }
         return JSON.stringify({
-          host: hostVersion, admission: SUPPORTED_OPENCODE_RANGE, liveQualification: "not measured by status; see release acceptance evidence",
+          host: hostVersion, admission: SUPPORTED_OPENCODE_RANGE, liveQualification: "not measured by diagnostics; see release acceptance evidence",
           commands: {
             registration: commandRegistration,
             lookup: effectiveCommands ? "available" : "failed",

package/src/workflows.ts

@@ -16,7 +16,7 @@ export const WORKFLOWS = {
   blocked: ["Inspect blocked work; distinguish explicit blocked status from dependency blocking.", "DEPENDENCIES"],
   close: ["Close only the requested work with acceptance and validation evidence and closure authority.", "WORKFLOWS"],
   comments: ["Read discussion or append the requested comment/checkpoint without replacing prior notes.", "RESUMABILITY"],
-  compact: ["Explain or perform explicitly authorized administrative issue compaction using current CLI help; this is separate from conversation compaction.", "TROUBLESHOOTING"],
+  compact: ["Guide semantic issue compaction with bd admin compact only when explicitly authorized; bd compact squashes Dolt history and is a different operation. This is not conversation compaction.", "TROUBLESHOOTING"],
   create: ["Create the requested issue with useful description, acceptance/design and discovered-from provenance when applicable; leave it unassigned unless assignment is intentional.", "ISSUE_CREATION"],
   decision: ["Record the requested decision, rationale and alternatives; reference intended behavior and detailed rationale in their project-owned homes.", "INTEGRATION_PATTERNS"],
   delete: ["Inspect the requested deletion and its effects; delete only with explicit scoped authority, never as a substitute for closure.", "TROUBLESHOOTING"],
@@ -28,15 +28,15 @@ export const WORKFLOWS = {
   label: ["Inspect or update only requested labels while preserving the project's taxonomy.", "CLI_REFERENCE"],
   list: ["Retrieve issues with the requested supported filters. Retrieval does not authorize claims or task execution.", "CLI_REFERENCE"],
   prime: ["Use supplied current context when available; request a guarded full-context refresh only when authorized and no hold is active.", "RESUMABILITY"],
-  quickstart: ["Provide onboarding using current prime/help and packaged guidance; the deprecated bd quickstart command is not assumed available.", "BOUNDARIES"],
+  quickstart: ["Guide onboarding with installed bd quickstart help, current authorized context and packaged guidance; do not initialize a store or assume commands unavailable in the installed CLI.", "BOUNDARIES"],
   ready: ["Inspect actionable work. Honor an exact assignment; claim and execute only work already within the authorized scope.", "WORKFLOWS"],
   "rename-prefix": ["Explain the requested project identifier migration and reference impact using current CLI help; require explicit migration authority.", "TROUBLESHOOTING"],
   reopen: ["Inspect current state, then reopen only the requested issue with the supplied regression/correction reason.", "WORKFLOWS"],
-  restore: ["Inspect supported historical retrieval/restoration in the installed Dolt-based CLI; do not assume legacy Git restore syntax or restore without authority.", "RESUMABILITY"],
+  restore: ["Retrieve pre-compaction issue content with bd restore; display-only by default. Use --apply only with explicit authority to write that content back; this is not database backup recovery.", "RESUMABILITY"],
   search: ["Search issues using supported filters; distinguish issue search from reusable memory search.", "CLI_REFERENCE"],
   show: ["Read requested issue details, prior notes, acceptance and dependencies without mutating them.", "RESUMABILITY"],
-  stats: ["Report the requested issue overview without automatically claiming work.", "CLI_REFERENCE"],
-  sync: ["Inspect current bd sync help: current federation synchronization differs from removed JSONL sync. Synchronize only with explicit authority; disclose conflicts without forcing a side.", "WORKTREES"],
+  stats: ["Report the issue-database overview using bd status (alias bd stats); use oc-beads:diagnostics for integration health. Do not claim work.", "CLI_REFERENCE"],
+  sync: ["Inspect current bd sync help for Dolt-remote synchronization, distinct from bd federation sync and removed JSONL sync. Synchronize only with explicit authority; disclose conflicts without forcing a side.", "WORKTREES"],
   template: ["Discover supported templates/formulas through installed help; replace obsolete static template syntax and do not execute a formula automatically.", "MOLECULES"],
   update: ["Apply only requested field changes; use an atomic claim for authorized execution and append-style progress notes. Replacement of notes is intentional, never routine.", "RESUMABILITY"],
   version: ["Report actual installed CLI, package and host versions and qualification limits; do not hardcode a latest version or install/upgrade anything.", "CLI_REFERENCE"],
@@ -90,11 +90,12 @@ export function applyBeadsSkill(editor: SkillEditor, skill: BeadsSkill, diagnose
 /** Build native prompt commands, never shell/template interpolation or synthetic continuation. */
 export function createBeadsCommands(
   session: Pick<Plugin.Context["session"], "prompt">,
-  status: (sessionID: string) => Promise<string>,
+  diagnostics: (sessionID: string) => Promise<string>,
   skillPath = BEADS_SKILL_PATH,
   signal?: AbortSignal,
 ): CommandDefinition[] {
   const common = [
+    "Workflow commands guide permitted operations, not exact CLI aliases.",
     "Follow repository/user authority and the exact requested scope. Do not bypass a hold with manual prime or other store access.",
     "Use actual request capabilities: discover the native beads namespace and compose supported daily operations in code mode when present. Native shell is direct-only; advanced/admin workflows use permissioned direct shell and current CLI help. Do not call tools.shell inside execute. Advanced guidance does not enable automation.",
     "Every agent-authored write, claim and heartbeat needs the host-rendered actual executor's command-scoped BEADS_ACTOR or --actor. Preserve authorship; read created_by, owner and assignee separately.",
@@ -115,11 +116,11 @@ export function createBeadsCommands(
     },
   }));
   commands.push({
-    name: "oc-beads:status",
-    description: "Inspect native discovery, conflicts, compatibility and context/persistence status without opening a store.",
+    name: "oc-beads:diagnostics",
+    description: "Inspect OpenCode Beads integration discovery, conflicts, compatibility and context/persistence diagnostics without opening a store; use oc-beads:stats for the issue-database overview.",
     async execute(input) {
       if (signal?.aborted) throw new Error("Beads workflow unloaded");
-      const report = await status(input.sessionID);
+      const report = await diagnostics(input.sessionID);
       if (signal?.aborted) throw new Error("Beads workflow unloaded");
       await session.prompt({
         ...input.prompt, sessionID: input.sessionID, delivery: input.delivery,