ADR-0082: Eve canonical skill reconciliation

• Status: accepted for Phase 7 Task 7.6
• Date: 2026-09-09
• Owners: Eve runtime, @oshun/skill-system, Security, Evaluation, Product
• Scope: ownership and admission contract; no product rollout

Context#

Eve currently has three skill-shaped layers with different jobs:

1. SMX owns seven static, model-facing task-family playbooks in apps/oshun/bff/src/assistant/skills. Its router chooses a family, its allowlist narrows the already-built toolset, its registry requires versioned ids/changelogs/deck-case traceability, and the complete served prompt bytes are protected by the SMX prompt hash and evaluation process.
2. Hermes/Voyager owns mutable reusable recipes in libs/oshun/assistant/src/skills. It can save, retrieve, interpolate, and re-feed a recipe, and it has process-local and Postgres stores. These records use mutable ids rather than immutable semantic versions and are not part of the SMX prompt-hash or task-family evaluation path.
3. @oshun/skill-system already describes itself as the canonical cross-domain registry and contains semantic versions, immutable version snapshots, discovery, governance, sandbox, quality, migration, and execution primitives. Eve runtime does not currently consume it. One generic Agentic Studio page imports its static pipeline templates and graph helper, but does not consume SMX skills, Voyager recipes, or the reconciliation contract; its fixture marketplace/quality presentation is not evidence that Eve's Skills story is wired.

Calling all three things “skills” does not make them interchangeable. Replacing the measured SMX serving bytes with mutable Voyager recipes would bypass the SMX ratchet. Treating the Voyager store as a second canonical registry would leave version, provenance, quarantine, and rollback policy split. Treating a retrieved recipe as authority would allow untrusted content to grant itself tools.

Task 7.6 requires one ownership and user story before semantic recall or further Eve skill wiring proceeds.

Decision#

One control plane, two source projections#

@oshun/skill-system owns the canonical control plane for Eve skills:

• canonical identity and immutable version snapshots;
• exact active-version pins;
• source provenance and content hashes;
• security and governance admission;
• quarantine, feedback, and rollback state;
• the final privilege-clamp and exact execution-grant contract; and
• metadata returned by product-facing skill discovery.

SMX and Voyager remain source/serving adapters, not competing authorities.

The reconciliation contract is libs/oshun/skill-system/src/eve-reconciliation.ts. It deliberately represents SMX prompt projections and Voyager recipes as different closed modes. A mode cannot be relabelled as the other.

Version and pinning#

Every runnable projection has an exact (canonical skill id, SemVer, SHA-256 content hash) pin. The hash binds the operational instructions, scope, declared tools, retrieval terms, source system/id/version/revision, importing actor/time, source evidence, and—when the source is SMX—the global prompt hash and eval case ids.

SMX's skill.<family>.v<n> source id and v<n> must agree. A canonical SemVer is assigned without changing or concealing that source version. A Voyager record's mutable id/update revision is provenance for a new canonical candidate; updating that source never overwrites an existing canonical version. Reusing a canonical id/version with different content is rejected.

Retrieval never means “execute latest.” Discovery returns metadata and the exact active pin. The same pin is carried through activation and execution; hash, version, or identity drift refuses instead of silently resolving a newer snapshot.

Retrieval and the SMX measurement boundary#

Until Task 7.2 establishes the required runtime skill-selection evaluation families and floors, SMX's deterministic task-family router remains the serving selector for its measured playbooks. Reconciliation does not dynamically replace those prompt bytes or restamp the SMX ratchet.

Canonical discovery searches only active records visible to the exact product, tenant, or user scope. It returns name, description, source label, declared tools, score, and exact pin—not instructions. Instructions become available only after exact execution authorization. Semantic retrieval may later rank this metadata through an approved route, but it cannot bypass lifecycle, subject filtering, or exact pinning.

Voyager lexical/embedding results are candidate-retrieval evidence only. A saved or seeded recipe is not runnable through the canonical path until its immutable projection passes admission and is activated.

Privilege clamp#

Skill prose is untrusted data, never authority. The effective tool set is the ordered intersection of four explicit sets:

1. tools declared by the exact skill version;
2. tools allowed by the current authenticated execution grant;
3. tools allowed on the current channel/turn; and
4. tools actually registered by the runtime.

An absent or empty set widens nothing. Unknown declared tools block admission. The execution grant must exactly match tenant, user, purpose, channel, skill id, version, and content hash, must be authenticated by the caller's authority boundary, and is rechecked for issuance time, expiry, and revocation when the instructions are resolved. The contract returns a resolution; it does not execute a handler.

Provenance, poisoning, and quarantine#

Admission requires all of the following to bind the same exact content hash:

• a source revision on the current trusted-source allowlist;
• a security receipt whose full normalized verification key was authenticated, whose scanner version is trusted, whose age is bounded, and whose verdict is clean with no findings;
• a governance receipt whose full normalized verification key was authenticated, whose reviewer is trusted, whose age is bounded, and whose decision is approval; and
• only registered declared tools.

Receipt identity strings are not signatures. The surrounding authority boundary must authenticate the complete normalized receipt before placing its kind:id:SHA-256 verification key in the verified set. Reusing an authenticated id with altered receipt fields therefore fails. Self-asserted receipts do not pass. Execution grants use the same full-receipt binding.

Finding codes are closed and include prompt injection, secret references, undeclared tools, path traversal, untrusted provenance, hash mismatch, eval gaps, and unknown. Any failed admission is retained as quarantined rather than quietly disappearing. A later poisoning or integrity finding can quarantine an active version immediately; that removes its active pointer. Quarantine is terminal for that immutable version. Recovery requires a new reviewed version or a governed rollback to a different previously active version.

Feedback#

Feedback binds an exact pin, exact tenant/user, execution id, categorical outcome, time, evidence reference, and optional bounded quality score. The registry accepts it only when that id, subject, and pin match a retained successful authorization receipt. That receipt contains the grant id, authorization time, purpose, channel, and effective tool names, but no skill instructions, prompt, reply, or tool payload. The canonical feedback record also retains none of those payloads. Duplicate feedback ids are idempotent only when their complete normalized content matches; conflicting reuse rejects.

Feedback never edits, publishes, activates, or unquarantines a skill. Unsafe or corrected outcomes, or a sufficiently adverse bounded sample, recommend human review. SMX prompt edits still require its prompt-hash and measurement process; Voyager-derived edits create a new candidate version.

Rollback and restart#

Activating a new approved version retires the prior active pin without deleting it. Rollback targets only a previously active, now-retired exact pin. It requires a fresh authenticated security receipt, a fresh authenticated rollback governance receipt, a still-trusted source revision, and a still-valid tool declaration. A quarantined or never-active candidate cannot be selected as a rollback shortcut.

The process-local reference registry exports records, active pins, minimized execution authorization receipts, feedback, and control events. Restart validates all content hashes, review bindings, status/active-pointer consistency, activation history, execution and feedback scopes, event pins, and the current admission policy before restoring anything runnable. It retains the review that most recently made a pin runnable, including a rollback review. A malformed or newly untrusted runnable snapshot fails closed.

Durable storage must preserve the same invariants transactionally. This ADR does not claim that the existing generic Postgres registry already stores the Eve reconciliation overlay.

One user-visible story#

The product uses one noun: Skills. A person does not choose “SMX” or “Voyager.” They see a name, purpose, source label (Built-in, Organization skill, or My skill), version, status, permitted capabilities, and evidence or activity link.

• Built-in skills are measured Eve playbooks sourced from SMX.
• Saved or imported recipes appear as pending candidates until review; an approved user-scoped recipe appears as My skill.
• Running a skill uses the displayed exact version under current permissions.
• A revoked grant, quarantine, or version mismatch produces a visible refusal, not a fallback to an unreviewed recipe.
• Feedback can request review. Operators can quarantine or roll back, and the activity record names the exact pin and decision evidence.

This is the canonical vocabulary and interaction contract for later product work. The existing generic Agentic Studio skill-system page must either adopt this provenance/version/status vocabulary when real Eve records are admitted or remain explicitly separate as a pipeline-design surface. No UI is added by Task 7.6.

Migration sequence#

1. Project the seven current SMX skills into exact canonical records without changing their served bytes; bind each to its source id, prompt hash, and eval cases.
2. Add an audited Voyager import adapter that converts saved recipes into scoped candidates with explicit canonical SemVer. Do not execute legacy mutable rows through the canonical path.
3. Persist the reconciliation overlay transactionally and bind authenticated security/governance/authority receipt verification.
4. After Task 7.2's selection and long-horizon gates pass, resolve SMX routes through their exact active canonical pins while retaining the same prompt hash/eval discipline.
5. Add the single Skills product story only through the applicable product, privacy, and security admission gates. Retire direct legacy mutation/run entrypoints after migration and rollback evidence passes.

Consequences and honest boundary#

The repository now has a single testable decision for ownership, layering, pinning, retrieval, privilege clamping, provenance, poisoning/quarantine, feedback, rollback, and user vocabulary. It does not yet have a production consumer of the reconciliation registry, a Voyager import adapter, durable overlay storage, authenticated receipt verifier, live scanner, product Skills surface backed by Eve records, or live rollback exercise. The existing Studio page consumes only canonical pipeline templates. This task does not change the seven SMX prompt skills or their model-facing bytes.

Task 7.6 closes the reconciliation decision and reference contract only. Task 7.2 still owns runtime selection measurement; later admission work owns product wiring; Tasks 13 and 14 retain security and privacy gates. Phase 7 and G3/G11-G18 remain open.