beaver_project/docs/superpowers/specs/2026-06-15-plugin-skill-mirroring-design.md

Beaver Plugin Skill Mirroring Design

Decision

Beaver V1 plugins are declarative skill bundles. Enabling a plugin mirrors each declared SKILL.md and its supporting files into SkillSpecStore. From that point onward, the mirrored skill is a normal Beaver skill:

• it has the same resolver priority as any workspace-managed skill;
• runtime activation, receipts, performance scoring, replay evaluation, review, publish, rollback, and disable all use the existing skill lifecycle;
• self-learning only writes Beaver-managed versions and never edits the plugin package;
• plugin origin remains metadata, not a separate runtime class.

An arbitrary in-process Python entrypoint, hooks, providers, and custom runtime code are out of scope for this plan. Tool-providing plugins should continue to use MCP until a separate executable-plugin security design is approved.

Why The Proposed Flow Is Correct

The proposed "mirror, learn on the mirror, merge on plugin update, then evaluate" flow is correct with one important refinement: plugin upgrades must be treated as a three-way merge, not a two-document rewrite.

The three inputs are:

1. B, the last accepted upstream plugin snapshot;
2. L, the current Beaver-published skill, including local self-learning;
3. U, the newly discovered upstream plugin snapshot.

This distinction prevents a plugin update from silently deleting local learning and prevents local learning from silently discarding new upstream safety or workflow changes.

Package Contract

Each plugin directory contains beaver.plugin.json:

{
  "schema_version": 1,
  "id": "baoyu-comic",
  "name": "Baoyu Comic",
  "version": "1.2.0",
  "skills": [
    {
      "name": "baoyu-comic",
      "path": "skills/baoyu-comic"
    }
  ]
}

Rules:

• id and skill names use lowercase letters, digits, _, and -.
• Skill paths are relative to the plugin root and cannot escape it.
• Every skill directory must contain SKILL.md.
• Symlinks are rejected while mirroring.
• Two enabled plugins cannot own the same Beaver skill name.
• A plugin cannot overwrite an existing non-plugin workspace skill.
• Discovery does not enable a plugin. Enablement is an explicit admin action.

Storage Model

Plugin packages remain outside the managed skill version tree:

workspace/
  plugins/
    baoyu-comic/
      beaver.plugin.json
      skills/baoyu-comic/SKILL.md
  .beaver/
    plugins/state.json
  skills/
    baoyu-comic/
      skill.json
      current.json
      upstreams/
        baoyu-comic/
          <tree-hash>/
            upstream.json
            SKILL.md
            assets/...
      versions/
        v0001/
          version.json
          SKILL.md
          assets/...

upstreams/ stores immutable raw plugin snapshots. versions/ stores runtime-visible Beaver versions. A merged Beaver version may differ from its upstream snapshot.

Every upstream snapshot has two hashes:

• skill_content_hash: canonical hash of normalized SKILL.md; used by the LLM merge and skill-content preservation checks.
• skill_tree_hash: hash of every regular file in the skill tree, including normalized relative path, byte length, bytes, and executable-bit metadata. Symlinks are rejected. This is the supply-chain identity used for update detection and state.

The tree hash includes SKILL.md, templates, assets, examples, and scripts. Full Unix mode bits are not hashed because umask and extraction tools can change them; only whether any executable bit is set is normalized into the hash. Beaver metadata files such as version.json and upstream.json are excluded.

Every Beaver SkillVersion also stores a backward-compatible tree_hash. New versions compute it from the complete promoted version directory. Older versions without the field derive it on read, so L.tree is available for upgrade classification.

Plugin state records:

{
  "plugins": {
    "baoyu-comic": {
      "enabled": true,
      "installed_version": "1.2.0",
      "manifest_path": "plugins/baoyu-comic/beaver.plugin.json",
      "updates_paused": false,
      "skills": {
        "baoyu-comic": {
          "accepted_upstream_tree_hash": "sha256...",
          "observed_upstream_tree_hash": "sha256...",
          "accepted_beaver_version": "v0003",
          "current_beaver_version": "v0003",
          "pending_candidate_id": null,
          "status": "synced"
        }
      }
    }
  }
}

Skill versions and drafts also carry plugin provenance. State is operational metadata; version provenance is the durable audit record.

Initial Enable Flow

When an admin enables a valid plugin:

1. Discover and validate the manifest.
2. Copy each declared skill into an immutable upstream snapshot.
3. Reject ownership/name conflicts before changing any skill.
4. Run the existing deterministic skill safety checker against an in-memory initial-mirror draft and reject failed or critical results.
5. Publish an exact Beaver mirror as the next skill version.
6. Copy supporting files into that version.
7. Mark the skill source_kind="plugin" and active.
8. Record plugin ID, plugin version, source path, upstream hash, and mirror mode in SkillVersion.provenance.
9. Update plugin state only after all declared skills succeed.

Initial enable is an explicit trust action, so it does not require LLM synthesis. Manifest validation, path validation, and the existing static skill safety checks still apply.

All files are first written below a transaction staging directory on the same filesystem. Only after manifest validation, tree hashing, conflict checks, and safety checks pass are immutable upstream/version directories promoted with os.replace(). current.json, skill.json, and indexes are atomically replaced under the workspace write lock; plugin state is written last. A failed transaction may leave an unreferenced immutable directory, which cleanup can remove, but it cannot make a partial version runtime-visible.

For a new skill, the complete staged skill directory is promoted once. For an existing skill, immutable directories and metadata are promoted first and current.json is replaced last as the runtime visibility switch. This provides per-skill atomic visibility; the workspace lock serializes writers across a multi-skill plugin operation.

Runtime Priority

Mirrored plugin skills are loaded exclusively from SkillSpecStore. They are not supplied through SkillsLoader.extra_dirs.

This makes priority deterministic:

1. active published workspace versions, including plugin-origin versions;
2. builtin skills.

source_kind="plugin" is displayed for provenance but does not lower selection priority or exclude the skill from self-learning.

Upgrade Classification

For each linked skill, compare upstream tree hashes:

Condition	Action
U.tree == B.tree	No upstream change; no action.
L.tree == U.tree	Acknowledge the new upstream snapshot; no draft needed.
L.tree == B.tree and U.tree != B.tree	Create a deterministic fast_forward plugin update draft containing U.
L.tree != B.tree and U.tree != B.tree	Create a three_way plugin update candidate using B, L, and U.

Even the fast_forward case goes through safety, replay evaluation, review, and publish. It skips LLM merge synthesis because there is no local divergence.

Candidate IDs are deterministic:

plugin-update:<plugin-id>:<skill-name>:<new-upstream-hash-prefix>

This makes boot-time sync idempotent.

Supporting files use a deterministic path-level three-way merge:

• local unchanged from B: take U;
• upstream unchanged from B: keep L;
• both sides equal: keep either;
• a file added on only one side: keep it;
• divergent edits, delete-versus-edit, or different additions at the same path: record an unresolved file conflict and block publication.

The LLM merges only SKILL.md. It does not attempt to merge arbitrary or binary supporting files.

Learning Integration

Add candidate kind plugin_skill_update. Its evidence contains only references:

{
  "plugin_id": "baoyu-comic",
  "plugin_version": "1.2.0",
  "skill_name": "baoyu-comic",
  "merge_mode": "three_way",
  "base_upstream_tree_hash": "old-hash",
  "new_upstream_tree_hash": "new-hash",
  "local_version": "v0003"
}

The learning service resolves the actual snapshots from SkillSpecStore; raw skill content is not duplicated into learning-candidates.jsonl.

For three_way, the synthesizer receives:

• old upstream B;
• current local skill L;
• new upstream U;
• relevant historical run evidence for L, when available.

The synthesizer must return the merged skill plus explicit merge decisions:

{
  "frontmatter": {},
  "content": "...",
  "change_reason": "...",
  "preserved_local_sections": [],
  "adopted_upstream_sections": [],
  "resolved_conflicts": [],
  "dropped_sections": []
}

The generated draft uses proposal_kind="plugin_skill_update" and carries the complete plugin merge provenance.

Evaluation And Publish Gates

The existing flow remains authoritative:

candidate
  -> draft
  -> static safety
  -> replay eval
  -> review
  -> publish
  -> rollback if needed

Replay eval compares:

• baseline arm: current local version L;
• candidate arm: merged draft M.

The preservation report is extended for plugin updates:

• local preservation: important instructions from L are not silently removed;
• upstream adoption: new important instructions from U are represented;
• safety/tool preservation: Safety and Required Tools changes require explicit handling;
• unresolved conflicts cause evaluation failure.

Publishing is blocked when:

• static safety fails;
• replay evaluation regresses;
• confidence is low under the existing gate;
• local or upstream preservation fails;
• merge decisions contain unresolved SKILL.md conflicts;
• the supporting-file merge plan contains unresolved path/content conflicts.

On publish, the pipeline notifies PluginManager, which advances accepted_upstream_tree_hash, clears the pending candidate, and records the new Beaver version.

Observer delivery is not the source of truth. At the start of every sync, reconciliation inspects the current published version provenance. If it contains a valid, newer plugin_skill_update result and its upstream snapshot exists, plugin state is repaired:

• advance accepted_upstream_tree_hash;
• advance accepted_beaver_version;
• clear the matching pending candidate;
• set status to synced.

Reconciliation never moves accepted_beaver_version backwards after a runtime rollback. An observer failure is audited but does not make an already-successful publish request fail, which avoids client retries creating misleading duplicate operations.

Concurrent And Failure Behavior

• All plugin sync, skill version allocation/publication, plugin state mutation, and learning-candidate mutation share a reentrant cross-process workspace write lock at .beaver/locks/plugin-skill-write.lock.
• The lock uses the repository's existing fcntl/msvcrt pattern plus an in-process reentrant guard. Nested store calls reuse the held lock instead of deadlocking.
• Candidate existence checks and JSONL writes happen inside the lock.
• Version-number allocation and version promotion happen inside the lock.
• Explicit enable/sync waits for the lock with a bounded timeout and returns a busy error on timeout.
• Engine boot never calls an LLM. Its auto-sync uses a non-blocking lock attempt; when the lock is busy, boot proceeds with the current published skills and reports sync deferred.
• Repeated and concurrent boot/sync is idempotent across processes, not only within one Python object.
• If another active draft targets the same skill, the plugin update remains pending and is not synthesized until the skill is free.
• If a newer plugin version appears while an older update is pending, the old candidate is marked superseded and a new candidate is created against the last accepted upstream.
• Rejecting a draft preserves the plugin package, upstream snapshots, current skill, and candidate audit history. Regeneration remains possible.
• Partial multi-skill plugin enable never promotes metadata/current pointers until every staged skill passes validation.
• Plugin files are never modified by learning or publication.

Pause, Disable, Missing, And Adopt

• Pausing updates suspends discovery-to-candidate sync while linked skills remain active.
• Resuming updates reconciles state and performs sync.
• Disabling a plugin is an explicit destructive runtime action: it pauses updates and disables linked skills, but never deletes versions or upstream snapshots. The API requires an explicit disable_linked_skills=true confirmation.
• Re-enabling restores linked skills and performs sync.
• A missing plugin package is a supply-chain status only. It marks the plugin missing, suspends sync/update, and leaves the current Beaver skills active.
• An explicit adopt action detaches a skill from its plugin, changes source_kind to managed, keeps the current version active, and prevents future plugin updates from targeting it.

Management API And UI

Backend endpoints:

GET  /api/plugins
POST /api/plugins/sync
POST /api/plugins/{plugin_id}/enable
POST /api/plugins/{plugin_id}/pause
POST /api/plugins/{plugin_id}/resume
POST /api/plugins/{plugin_id}/disable
POST /api/plugins/{plugin_id}/skills/{skill_name}/adopt

API payloads never expose absolute server paths. Workspace manifests use workspace-relative paths. External manifests use a redacted display path such as <external>/baoyu-comic/beaver.plugin.json.

The existing Skills page gains a Plugins tab showing:

• discovered/enabled/missing/error state;
• installed and discovered plugin versions;
• declared skills and their current Beaver versions;
• sync state and pending learning candidate;
• enable, pause, resume, disable, sync, and adopt actions.

Plugin-origin skills continue to appear in the normal Published, Candidates, and Drafts tabs with provenance and merge-mode labels.

Non-Goals

• Importing arbitrary plugin Python modules into the Beaver process.
• Plugin-defined hooks, providers, channels, or frontend bundles.
• Automatic downloading from a plugin marketplace.
• Automatically publishing plugin upgrades without review.
• Editing or rebasing plugin source files in place.

Acceptance Criteria

1. Enabling a plugin mirrors all declared skills and supporting files into managed versions.
2. Mirrored skills have the same resolver priority and learning eligibility as ordinary workspace skills.
3. Self-learning never modifies the plugin package.
4. Plugin updates create idempotent plugin_skill_update candidates.
5. Local divergence triggers a three-way merge; no divergence triggers a deterministic fast-forward draft.
6. Every plugin update passes the existing safety, replay, review, and publish gates.
7. Publishing advances plugin state and preserves complete provenance.
8. Pause, disable, missing package, rejection, restart, and newer-update races do not lose the current skill or its learned versions; missing packages leave current skills active.
9. Existing non-plugin skills and legacy candidate payloads remain backward compatible.
10. Supporting-file-only updates change the upstream tree hash and create an update candidate.
11. Concurrent boot, sync, and enable operations do not allocate duplicate versions or append duplicate candidates.
12. Sync reconciliation repairs plugin state after a published version succeeds but its observer/state update fails.