docs(013): RFC 0001 for the skillrig mise backend plugin

[so0k]

What

Adds a research spike and an RFC for a skillrig mise backend plugin that co-installs multiple backing CLIs from one origin monorepo, plus a correction to ARCHITECTURE-v0 §8b. Resolves the investigation in #23.

The RFC is written to bootstrap a new, separate repo (skillrig/mise-skillrig — the plugin is Lua, not Go, so it does not belong in skillrig/cli).

The key finding (why this RFC matters)

#23 proposed the plugin to fix a multi-binary install collision. While researching open question #4, the premise shifted — and then a reviewer pushback sharpened it into the real justification:

• Layer A — install scheduler. The collision (two aliases → same github:org/repo@version deduped to one install) was a scheduler bug, fixed in mise 2026.4.12 (PR #9093). We require it, but it only fixes Layer A.
• Layer B — version resolution. PR #9093 explicitly does not touch version listing/resolution. The origin's strict-semver tag policy forbids prefix tags (iii-v0.1.0) and forces build-metadata streams (v0.5.0+iii). Per SemVer 2.0.0, build metadata is ignored for precedence, so those streams collapse to one version, and version_prefix (a leading-prefix stripper; there is no tag_regex) cannot select a + suffix.

Option	Indep. versions	Co-location	Strict-semver	Native mise
prefix streams + version_prefix	✅	✅	❌ forbidden	✅
build-metadata streams	✅	✅	✅	❌ broken (Layer B)
one release, all binaries	❌	✅	✅	✅ (post-#9093)
separate repo per CLI	✅	❌	✅	✅
skillrig backend plugin	✅	✅	✅	✅ (owns listing)

Only the plugin satisfies independent versioning + co-location + strict-semver together — because its BackendListVersions hook owns version listing. That is a capability justification, not just ergonomics.

Open questions answered (from #23)

• OQ4 (native coverage): partially — #9093 is scheduler-only; build-metadata streams stay native-unresolvable. Plugin justified.
• OQ1 (home/cadence): own repo skillrig/mise-skillrig, backend name skillrig, independent release cadence.
• OQ2 (origin metadata): new convention-versioned [[binaries]] block in .skillrig-origin.toml, mirrored into index.json (stream selector + asset template + checksums). Shared by plugin and CLI (AP-04).
• OQ3 (verification): checksum-only for v1 (origin already ships checksums.txt); treeSha/provenance parity is v2.

Contents

• specledger/013-mise-backend/research/2026-06-02-mise-backend-plugin.md — the spike (corrected after review).
• docs/rfcs/0001-mise-skillrig-backend.md — the RFC: how the origin template, mise + plugin, and skillrig CLI fit together; the [[binaries]] contract; the three Lua hooks (with snippets); auth (incl. the keyring-404 gotcha); verification depth; alternatives; phasing.
• docs/ARCHITECTURE-v0.md §8b — correction callout pointing to the RFC.

Notes for reviewers

• The RFC documents the native fallbacks honestly — an org that can relax its tag policy to prefix streams doesn't need the plugin.
• Docs-only; no code or CLI behavior change. The plugin itself is not built here.

https://claude.ai/code/session_01Nr5ZxzqTGefujhtEVPzMeV

---

Generated by Claude Code

[qodo-code-review]

Review Summary by Qodo

RFC 0001 and research spike for skillrig mise backend plugin

📝 Documentation ✨ Enhancement

Walkthroughs

Description

• Adds RFC 0001 defining a skillrig mise backend plugin for co-installing multiple backing CLIs
  from one origin monorepo with independent versioning under strict-semver tag policy
• Documents the origin-side contract ([[binaries]] block in .skillrig-origin.toml) that the
  plugin depends on, including stream selectors and asset templates
• Explains why native mise cannot resolve build-metadata streams (v0.5.0+iii) due to SemVer
  precedence rules, making the plugin a capability requirement not just ergonomics
• Includes comprehensive research spike validating that mise 2026.4.12 (PR #9093) fixes only the
  install scheduler layer, not version resolution layer
• Corrects ARCHITECTURE-v0 §8b to clarify version_prefix vs non-existent tag_regex, and notes
  that build-metadata streams remain natively unresolvable
• Specifies the three Lua hooks (BackendListVersions, BackendInstall, BackendExecEnv), auth
  token precedence, and v1 verification (checksum-only)

Diagram

flowchart LR
  A["Origin Monorepo<br/>cmd/iii cmd/console<br/>build-metadata tags<br/>v0.5.0+iii v0.2.0+console"] -->|"[[binaries]] contract<br/>index.json"| B["skillrig Backend Plugin<br/>BackendListVersions<br/>BackendInstall<br/>BackendExecEnv"]
  B -->|"skillrig:iii<br/>skillrig:console"| C["Consumer mise.toml<br/>independent versions<br/>per-stream resolution"]
  D["mise 2026.4.12<br/>Layer A: scheduler dedup<br/>PR #9093"] -.->|"necessary but<br/>insufficient"| B
  E["Native mise<br/>Layer B: version resolution<br/>SemVer precedence"] -.->|"cannot resolve<br/>build-metadata"| B

Loading

File Changes

1. docs/ARCHITECTURE-v0.md 📝 Documentation +11/-0

Correct mise backend realities and justify plugin

• Adds correction callout to §8b clarifying that tag_regex does not exist; the real knob is
 version_prefix (leading-prefix stripper only)
• Documents that mise 2026.4.12 (PR #9093) fixes only the install scheduler layer (Layer A), not
 version resolution (Layer B)
• Explains that build-metadata streams (v0.5.0+iii) remain natively unresolvable because SemVer
 precedence collapses them and version_prefix cannot select + suffixes
• Points to RFC 0001 and the research spike as the justification for the skillrig backend plugin
 on capability grounds

docs/ARCHITECTURE-v0.md

---

2. docs/rfcs/0001-mise-skillrig-backend.md 📝 Documentation +377/-0

RFC 0001 for skillrig mise backend plugin

• Defines the skillrig mise backend plugin (new repo skillrig/mise-skillrig, Lua-based) for
 co-installing N backing CLIs as distinct skillrig: tools
• Specifies the origin-side contract: convention-versioned [[binaries]] block in
 .skillrig-origin.toml with stream selector, asset template, checksums, and platform mappings
• Documents the three Lua hooks: BackendListVersions (owns version listing, filters build-metadata
 streams), BackendInstall (downloads, verifies checksums, extracts), BackendExecEnv (sets PATH)
• Explains why native mise cannot satisfy independent versioning + co-location + strict-semver
 together; only the plugin's BackendListVersions can parse and filter build-metadata tags
• Details auth token precedence (reuses mise's native resolver), the keyring-404 gotcha workaround,
 and CLI auto-wiring for skillrig add
• Covers verification depth (v1 checksum-only; v2 treeSha/provenance binding), alternatives
 considered, open questions, and phasing (P0–P4)

docs/rfcs/0001-mise-skillrig-backend.md

---

3. specledger/013-mise-backend/research/2026-06-02-mise-backend-plugin.md 📝 Documentation +257/-0

Research spike validating mise backend plugin necessity

• Research spike answering four open questions from issue #23 about multi-binary co-install from one
 origin monorepo
• Finding 1: Corrects earlier conclusion that mise 2026.4.12 fully resolves the problem; PR #9093
 fixes only the install scheduler (Layer A), not version resolution (Layer B)
• Finding 1b: Proves build-metadata streams (v0.5.0+iii) are structurally unresolvable natively
 because SemVer precedence ignores build metadata and version_prefix cannot select + suffixes
• Finding 2: Clarifies that tag_regex does not exist; per-stream selection uses version_prefix
 (leading-prefix stripper only)
• Finding 3: Documents backend-plugin hook surface (vfox-style Lua) with three hooks, ctx fields,
 and that plugins must re-implement checksum verification
• Finding 4: Validates the keyring-404 gotcha and confirms mise's token precedence already
 centralizes auth via credential_command and env vars
• Finding 5: Establishes plugin justification on capability (owns version listing for build-metadata
 streams), not just ergonomics
• Decisions and recommendations: build the plugin in its own repo, land the origin-metadata contract
 first, document native fallbacks, verify checksums in v1, correct §8b

specledger/013-mise-backend/research/2026-06-02-mise-backend-plugin.md

---

ⓘ You are approaching your monthly quota for Qodo. Upgrade your plan

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📎 Requirement gaps (0)

Context used

✅ Tickets: 🎫 Feat: custom mise backend for consuming multiple backing CLIs from one origin monorepo

✅ Compliance rules (platform): 152 rules

1. Stale tag_regex guidance 🐞 Bug ⚙ Maintainability

Description

docs/ARCHITECTURE-v0.md now says mise has no tag_regex, but the same section and later “open
questions”/roadmap text still refer to tag_regex as an option to stamp/use, creating contradictory
implementation guidance.

Code

docs/ARCHITECTURE-v0.md[R298-307]

Evidence

The new correction explicitly states tag_regex does not exist, but the same doc still mentions
“tag-regex options” and an open question about stamping tag_regex, and the roadmap repeats
tag_regex language—contradicting the correction.

docs/ARCHITECTURE-v0.md[296-307]
docs/ARCHITECTURE-v0.md[313-314]
docs/ARCHITECTURE-v0.md[439-449]
docs/ROADMAP.md[72-77]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/ARCHITECTURE-v0.md` adds a correction stating mise has no `tag_regex`, but other parts of the doc (including immediately below the correction, plus the open-questions section) still discuss stamping/using `tag_regex` as if it exists. This contradiction will confuse readers and can lead to attempted implementations/config generation using a non-existent option.

## Issue Context
The section is explicitly labeled “retained for history”, which helps, but the doc still uses `tag_regex` language in places that read like current planning items (e.g., open technical questions).

## Fix Focus Areas
- docs/ARCHITECTURE-v0.md[311-314]
- docs/ARCHITECTURE-v0.md[433-449]
- docs/ROADMAP.md[72-77]

(Replace `tag_regex` references with `version_prefix`/"version filters" where applicable, or explicitly label them as historical/outdated and not to be implemented.)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. SLSA/GPG docs conflict 🐞 Bug ≡ Correctness

Description

The RFC/spike state SLSA/GPG verification is not a current mise github-backend feature (deferred to
v2), but docs/ARCHITECTURE-v0.md still claims mise supports SLSA provenance and GPG asset
verification, leaving the documented verification posture inconsistent.

Code

docs/rfcs/0001-mise-skillrig-backend.md[318]

Evidence

The RFC and spike both state SLSA/GPG are not currently supported (and deferred), while ARCHITECTURE
states mise supports SLSA provenance and GPG asset verification—two incompatible assertions within
this repo’s docs.

docs/rfcs/0001-mise-skillrig-backend.md[309-318]
specledger/013-mise-backend/research/2026-06-02-mise-backend-plugin.md[183-187]
docs/ARCHITECTURE-v0.md[320-322]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new RFC/spike explicitly says SLSA/GPG verification is not a current mise github-backend feature (and is v2 work), while ARCHITECTURE asserts mise supports SLSA provenance and GPG asset verification. These statements conflict, so readers won’t know what guarantees exist today.

## Issue Context
This PR adds the RFC/spike and also updates ARCHITECTURE §8b with a correction block; it’s a good opportunity to reconcile the remaining verification claims in ARCHITECTURE with the newer RFC/spike position (or adjust the RFC/spike if ARCHITECTURE is the canonical/verified claim).

## Fix Focus Areas
- docs/ARCHITECTURE-v0.md[320-322]
- docs/rfcs/0001-mise-skillrig-backend.md[309-318]
- specledger/013-mise-backend/research/2026-06-02-mise-backend-plugin.md[183-187]

(Choose one accurate statement and update the other docs to match; if unsure, qualify ARCHITECTURE’s claim as "unverified/aspirational" or move it into v2.)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ You are approaching your monthly quota for Qodo. Upgrade your plan