a9a7a328e6
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD across contents and paths, upstream package/repo coordinates -> @golem15/msd-core and golem15com/msd-core. Deep links into upstream history, sibling upstream packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is. Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line, package/plugin identity, regenerated lockfile, install-tree fixtures, derived registries and benchmark baseline; migration checksum baseline re-locked (MSD keeps its own install state, so no install had applied the old sums); sort-order and regex-escaped expectations in tests adjusted.
192 lines
18 KiB
Markdown
192 lines
18 KiB
Markdown
# Runtime Artifact Layout Module owns per-runtime artifact placement
|
||
|
||
- **Status:** Accepted
|
||
- **Date:** 2026-05-17
|
||
- **Issue:** #3660
|
||
- **Implementation:** #3663 (Phase 1), feat/3663-runtime-artifact-layout-module-phase-1-m
|
||
- **Subsumed by:** [ADR-1239](1239-msd-embeddable-orchestration-engine.md) (MSD as an Embeddable Orchestration Engine) — read it first; see the amendment below
|
||
- **Amended by:** [ADR-2866](2866-install-surface-resolution.md) (Install-surface resolution) — **this module widens from *placement* to *placement + trigger resolution*.** The `Layout` returned here models where a file goes but not the `/msd-<name>` trigger it occupies, so nothing in the tree can express the cross-scope collision in [#2218](https://github.com/open-gsd/gsd-core/issues/2218). ADR-2866 adds a projection returning the resolved trigger, its kind and scope, its destination, and whether another install shadows it. **This ADR's placement decision is unchanged and still in force** — `resolveRuntimeArtifactLayout` stays for callers that only need placement, the per-runtime table remains the single owner of placement knowledge, and legacy-layout migrations stay in [ADR-0008](0008-installer-migration-module.md). **Timing:** Phase 2 ([#2871](https://github.com/open-gsd/gsd-core/issues/2871)) of epic [#2866](https://github.com/open-gsd/gsd-core/issues/2866) has landed — the module now resolves placement **and** triggers via the new `resolveTriggerSurface` function; `resolveRuntimeArtifactLayout` is unchanged for callers that need placement only.
|
||
|
||
## Amendment (2026-07-16): subsumed by ADR-1239 (EoS)
|
||
|
||
[ADR-1239](1239-msd-embeddable-orchestration-engine.md) — **MSD as an Embeddable Orchestration Engine** (EoS), Accepted — subsumes this ADR as an adapter: per-runtime artifact placement becomes one negotiated surface of the Host-Integration Interface rather than the outermost seam at which MSD meets a host.
|
||
|
||
**This ADR is not superseded and its status is unchanged.** The artifact-layout seam is live and load-bearing; it is now a *component* of the EoS frame.
|
||
|
||
**Read [ADR-1239](1239-msd-embeddable-orchestration-engine.md) first.**
|
||
|
||
Recorded because ADR-1239 declared this subsumption while this file recorded nothing.
|
||
|
||
## Context
|
||
|
||
The **Runtime Surface Module** (`msd-core/bin/lib/surface.cjs`, introduced by ADR-0011 Phase 2) re-materializes a resolved Skill Surface profile to disk via `applySurface`. It currently hardcodes two artifact kinds (`commands`, `agents`) and re-derives their source directories via `_findInstallSource` / `_findAgentsSource` walk-up heuristics. The install and uninstall pipelines in `bin/install.js` each encode the same per-runtime artifact layout independently across ~14 install sites and ~6 uninstall sites. Bug #3659 surfaced the resulting drift: `applySurface` omits the `skills` kind for runtimes whose canonical layout is `skills/msd-<stem>/SKILL.md`, so `msd-surface profile <name>` leaves ~67 skill directories on disk under the install-time profile's footprint when the resolved profile should have pruned them — roughly 2.7k tokens per session on a measured workstation.
|
||
|
||
The root problem is the absence of a typed seam for "where does runtime R put artifact kind K." Three lifecycle sites (install, uninstall, surface) each independently encode this knowledge and drift independently.
|
||
|
||
## Decision
|
||
|
||
- Add a **Runtime Artifact Layout Module** at `msd-core/bin/lib/runtime-artifact-layout.cjs` as the single owner of the per-runtime artifact-placement table.
|
||
- The module requires `runtime-homes.cjs` for the canonical runtime enum and global config-dir resolution. It adds the artifact-kind axis on top.
|
||
- Expose `resolveRuntimeArtifactLayout(runtime, configDir) → Layout`. The returned `Layout` is a plain typed object — `{ runtime, configDir, kinds: ArtifactKind[] }` — with no I/O on resolution.
|
||
- Each `ArtifactKind` is `{ kind: 'commands'|'agents'|'skills', destSubpath, prefix, stage }`. `stage` is a function `(resolvedProfile) → stagedDir` that closes over the per-runtime converter where one is needed (e.g. `convertClaudeCommandToClaudeSkill` for the `skills` kind on Claude global).
|
||
- The `kinds` array is empty for runtimes with no MSD surface (a hypothetical future runtime with no integration). The `skills` kind is **absent** for runtimes that don't materialize skill directories (Cline; Gemini today). The `commands` kind is **absent** for runtimes that consume only the skills/agents layout (Claude global, Codex, etc.).
|
||
- Per-runtime quirks live in the layout's record fields, not in caller branches:
|
||
- **Hermes**: `{ kind: 'skills', destSubpath: 'skills/msd', prefix: 'msd-' }` — preserves the nested namespace from #2841. **Note (#947):** The original decision used `prefix: ''` (bare stem) on the incorrect premise that the `skills/msd/` category directory namespaced the leaf identifier in Hermes's loader. Research showed category dirs are purely organisational; dispatch is by the skill `name:` field. The `msd-` prefix was restored by #947 to match every other runtime.
|
||
- **Cline**: `kinds: []` — Cline resolves to zero kinds in Phase 1 (no `commands` kind).
|
||
- **Gemini**: `kinds: [ { kind: 'commands', destSubpath: 'commands/msd', prefix: 'msd-' } ]` — no agents, no skills.
|
||
- `applySurface` migrates from `(runtimeConfigDir, commandsDir, agentsDir, manifest, clusterMap)` to `(runtimeConfigDir, layout, manifest, clusterMap)`. Body collapses to `for (const kind of layout.kinds) _syncMsdDir(kind.stage(resolved), path.join(layout.configDir, kind.destSubpath), kind.kind)`.
|
||
- `_findInstallSource` and `_findAgentsSource` in `surface.cjs` are removed. The layout owns source resolution.
|
||
- Phase 2 (separate PR): install and uninstall paths in `bin/install.js` migrate to iterate `layout.kinds`. Per-runtime if/else branches for skill-directory creation/removal collapse to one layout-driven loop per pipeline.
|
||
- Legacy-layout migrations (`bin/install.js:6710`/`:8402` for the pre-nested `skills/msd-*/` flat layout; `migrateLegacyDevPreferencesToSkill` for #2973) remain inside the Installer Migration Module (ADR-0008) and run **before** layout-driven copy. The layout module describes only the current canonical target — no historical kinds.
|
||
|
||
## Initial Scope
|
||
|
||
Phase 1 should land the module and one consumer (the bug-#3659 fix):
|
||
|
||
1. New `msd-core/bin/lib/runtime-artifact-layout.cjs` — `resolveRuntimeArtifactLayout`, the typed `Layout`/`ArtifactKind` shapes, and the runtime table covering every runtime currently enumerated in `runtime-homes.cjs`.
|
||
2. `surface.cjs:applySurface` migrates to layout-driven iteration. `_findInstallSource` and `_findAgentsSource` deleted. The `skills` kind is now iterated alongside `commands` and `agents` — bug #3659 closed.
|
||
3. `commands/msd/surface.md` and `tests/surface-apply.test.cjs` updated to construct + pass `Layout` values.
|
||
4. New `tests/runtime-artifact-layout-*.test.cjs` covering:
|
||
- Per-runtime fixture table: each runtime maps to the expected `kinds[]` shape.
|
||
- Hermes `skills/msd` nested case.
|
||
- Cline / Gemini "kind absent" cases.
|
||
- Source-root resolution (replacing the existing `surface.cjs` walk-up tests).
|
||
5. Address the adjacent `readSurface` partial-field silent-null bug noted in #3659 — out of scope here; track as a separate `confirmed-bug` ticket.
|
||
|
||
Phase 1 should **not**:
|
||
|
||
- Migrate the install/uninstall pipelines in `bin/install.js` in the same PR. That's a separate enhancement issue — same seam, larger blast radius. The layout module is dual-consumable from the start; converting `bin/install.js` is a sequenced follow-up.
|
||
- Move the per-runtime skill converters (`convertClaudeCommandToClaudeSkill`, etc.). They survive at their current file location as the stage adapters; the layout module references them. A future ADR may consolidate them into a Skill Conversion Module if a second consumer emerges.
|
||
|
||
## Migration Inventory
|
||
|
||
### New file
|
||
- `msd-core/bin/lib/runtime-artifact-layout.cjs` — module body + runtime layout table.
|
||
|
||
### Files modified (Phase 1)
|
||
- `msd-core/bin/lib/surface.cjs` — `applySurface` signature change; `_findInstallSource` + `_findAgentsSource` removal.
|
||
- `commands/msd/surface.md` — runbook updates the 3 sites that call `applySurface` to first call `resolveRuntimeArtifactLayout`.
|
||
- `tests/surface-apply.test.cjs` — 5 call sites pass `layout` instead of `commandsDir, agentsDir`.
|
||
|
||
### Files modified (Phase 2 — separate PR / separate issue)
|
||
- `bin/install.js` — install path: 4 per-runtime skill-stage blocks collapse to one layout-driven loop.
|
||
- `bin/install.js` — uninstall path: 6 per-runtime skill-removal blocks collapse to one layout-driven loop.
|
||
- Estimated reduction: ~250 lines.
|
||
|
||
### Files not touched
|
||
- `runtime-homes.cjs` — its narrow contract (runtime → global config dir / skills base) stays. The layout module is its sibling.
|
||
- `install-profiles.cjs` — `stageSkillsForProfile`, `stageAgentsForProfile` remain. The layout module's `kinds[i].stage` closures call them.
|
||
- The four skill converters at `bin/install.js:1622/1681/1792/2534` — remain in place; layout closures reference them.
|
||
|
||
## Interface sketch
|
||
|
||
```js
|
||
// runtime-artifact-layout.cjs
|
||
|
||
/**
|
||
* @typedef {Object} ArtifactKind
|
||
* @property {'commands'|'agents'|'skills'} kind
|
||
* @property {string} destSubpath joined to layout.configDir
|
||
* @property {string} prefix 'msd-' for all runtimes (incl. Hermes after #947)
|
||
* @property {(resolved) => string} stage returns staged dir path
|
||
*/
|
||
|
||
/**
|
||
* @typedef {Object} Layout
|
||
* @property {string} runtime canonical enum from runtime-homes.cjs
|
||
* @property {string} configDir caller-supplied (local or global scope)
|
||
* @property {ArtifactKind[]} kinds empty array = runtime has no msd-* surface
|
||
*/
|
||
|
||
function resolveRuntimeArtifactLayout(runtime, configDir) { … }
|
||
```
|
||
|
||
Call-site shape:
|
||
|
||
```js
|
||
// commands/msd/surface.md (runbook), tests/surface-apply.test.cjs, future install/uninstall
|
||
const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir);
|
||
applySurface(runtimeConfigDir, layout, manifest, CLUSTERS);
|
||
```
|
||
|
||
`applySurface` body after migration:
|
||
|
||
```js
|
||
function applySurface(runtimeConfigDir, layout, manifest, clusterMap) {
|
||
const resolved = resolveSurface(runtimeConfigDir, manifest, clusterMap);
|
||
for (const kind of layout.kinds) {
|
||
const staged = kind.stage(resolved);
|
||
const dest = path.join(layout.configDir, kind.destSubpath);
|
||
if (fs.existsSync(dest)) _syncMsdDir(staged, dest, kind.kind);
|
||
}
|
||
}
|
||
```
|
||
|
||
## Consequences
|
||
|
||
- Bug #3659 becomes a fixture-table omission, not a forgotten if/else block. The layout-table test asserts every runtime's `kinds[]` shape — forgetting the `skills` kind on Claude global would fail there.
|
||
- The cross-runtime test matrix collapses from `N runtimes × 3 lifecycle verbs × 3 kinds` (today: ~120 implicit assertion pairs) to `N (layout table) + 3 (one per lifecycle verb iterating layout.kinds)`.
|
||
- Adding a new runtime (recent example: Grok via commit `05316369`) becomes one row in the layout table plus one fixture row in the test. The three lifecycle verbs pick it up automatically.
|
||
- The four per-runtime skill converters become canonical **adapters** at the artifact-kind seam. Their existence is no longer accidental — they're the seam's content.
|
||
- `surface.cjs` shrinks (`_findInstallSource` + `_findAgentsSource` removed). The walk-up heuristics — which were only ever-incidentally correct — are replaced by an explicit table.
|
||
- Phase 2 (install/uninstall migration) shrinks `bin/install.js` by ~250 lines and removes a recurring class of bug: a new runtime added by a contributor who forgets to wire it through every install/uninstall branch.
|
||
- Future architecture reviews should treat per-runtime artifact-placement knowledge added outside `runtime-artifact-layout.cjs` as drift, parallel to how ADR-0011 made out-of-seam skill staging drift.
|
||
- The Skill Surface Budget Module's leverage (typed sets of `{ skills, agents }`) now extends all the way to disk through one seam rather than three independent re-materializations.
|
||
|
||
## Open questions
|
||
|
||
- Whether the `skills` kind's `stage` closure should accept the per-runtime converter as a parameter (preserving converter-as-pure-function purity) or import it directly. Implementation detail — settle in the PR.
|
||
- Whether the layout module should expose a `listKinds(runtime)` introspection helper for status/diagnostics surfaces, or keep `Layout` as the only public type. Lean toward a single public type; add helpers only when a second consumer needs them.
|
||
- Whether Phase 2 (install/uninstall migration in `bin/install.js`) should land as a single follow-up PR or be split per pipeline. Lean toward single PR — the install and uninstall sides share the runtime branch structure and migrating only one introduces a temporary asymmetry inverse to today's.
|
||
- The adjacent `readSurface` partial-field silent-null fallback in `surface.cjs:55-75` (also flagged in #3659) is **out of scope here** — track separately. It's an independent shallow interface in the same module, not a runtime-layout concern.
|
||
|
||
## References
|
||
|
||
- Confirmed bug: `#3659` — `applySurface` doesn't prune `~/.claude/skills/msd-*/` dirs
|
||
- See `0011-skill-surface-budget-module.md` — the Runtime Surface Module this seam serves
|
||
- See `0008-installer-migration-module.md` — legacy-layout migrations stay there
|
||
- See `0005-sdk-architecture-seam-map.md` — the seam map this module joins
|
||
- Existing canonical sibling: `msd-core/bin/lib/runtime-homes.cjs`
|
||
- Per-runtime skill converters this module references: `bin/install.js:1622` (Copilot), `:1681` (Claude), `:1792` (Antigravity), `:2534` (Codex)
|
||
- Hermes nested-skills layout rationale: `#2841`
|
||
|
||
## Implementation status
|
||
|
||
Phase 1 implementation landed on `feat/3663-runtime-artifact-layout-module-phase-1-m`:
|
||
- `msd-core/bin/lib/runtime-artifact-layout.cjs` — 15-runtime layout table (grok intentionally excluded), `resolveRuntimeArtifactLayout(runtime, configDir, scope) → Layout`, walk-up `findInstallSourceRoot` helper.
|
||
- Clarification: in this Phase 1 implementation, **Cline resolves to zero kinds** (`kinds: []`), so it carries no `commands` kind in the layout table.
|
||
- `msd-core/bin/lib/install-profiles.cjs` — new `stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converter, prefix) → stagedDir` helper.
|
||
- `msd-core/bin/lib/surface.cjs` — `applySurface(runtimeConfigDir, layout, manifest, clusterMap)` signature migration; `_findInstallSource` + `_findAgentsSource` deleted; `_syncMsdDir` extended to handle the `skills` kind via directory iteration.
|
||
- Tests: `runtime-artifact-layout-resolve.test.cjs` (16), `runtime-artifact-layout-edge-cases.test.cjs` (10), `runtime-artifact-layout-stage.test.cjs` (5), `install-profiles-stage.test.cjs` (+7 new), `surface-apply.test.cjs` (updated 5 call sites + new skills-kind test).
|
||
|
||
Phase 2 (separate issue #3664 — `bin/install.js` install/uninstall pipeline migration) is blocked on Phase 1 merge.
|
||
|
||
## Amendment (2026-06-11): adding a runtime that rides the established layout is an addendum, not a new ADR
|
||
|
||
**Maintainer governance decision.** Registering an additional runtime that reuses the *existing* install machinery — the `profile-marker-only` install surface (ADR-58 / the config-adapter registry) plus a single `skills` kind in this module's layout table — is an **enhancement governed by this ADR via this addendum**, not a change that requires its own ADR. New design rationale (and a fuller amendment) is required only when a runtime introduces something this ADR has not already decided: a **new install surface**, a **new `ArtifactKind`**, or a layout quirk not expressible in the existing record fields (cf. the Hermes nested-namespace and Cline zero-kinds cases in the Decision section).
|
||
|
||
This codifies the lightweight path the project has used since Phase 1 for Codex, Copilot, Trae, Windsurf, Qwen, CodeBuddy, Cline, Kimi, et al., and makes the addendum-vs-new-ADR test explicit so contributors and reviewers stop re-litigating it per runtime.
|
||
|
||
### Qualifying criteria (all three) for the addendum path
|
||
|
||
1. **No new install surface** — the runtime maps to an existing `installSurface` value in the config-adapter registry (`profile-marker-only`, etc.); `writesSharedSettings: false`; `finishPermissionWriter: null` or an existing writer.
|
||
2. **No new artifact kind** — the layout entry is composed only of the existing `commands` / `agents` / `skills` kinds via the existing `skillsKind(...)` / record-field machinery; no new `ArtifactKind` shape.
|
||
3. **Reuses the converter contract** — per-runtime converters follow the established shape (see the agent-frontmatter contract below); only the path/name substitutions differ.
|
||
|
||
A runtime failing any of the three needs a fuller amendment here (or a new ADR) documenting the new surface/kind and its rationale.
|
||
|
||
### Agent-frontmatter contract (normative)
|
||
|
||
Per-runtime **agent** converters emit a **sanitized minimal frontmatter** — `name` + `description` only — rebuilt through `yamlIdentifier(name)` / `yamlQuote(toSingleLine(description))`, matching `convertClaudeAgentToTraeAgent` / `convertClaudeAgentToClineAgent` / `convertClaudeAgentToCodebuddyAgent`. Claude-specific fields (`tools:`, `color:`, commented hook blocks) MUST NOT be passed through verbatim. A runtime that genuinely requires richer agent frontmatter must document the target schema in an amendment here and emit it deliberately — not arrive at pass-through by accident. (Recorded because PR #1021's first cut of `convertClaudeAgentToQoderAgent` fell through to full pass-through; it must be brought onto the sibling contract.)
|
||
|
||
### Qoder (issue #860 / PR #1021) — first runtime recorded under this addendum
|
||
|
||
Qoder qualifies on all three criteria and is added as a layout-table entry, not a new design:
|
||
|
||
- **Install surface:** `profile-marker-only` (config-adapter registry), identical shape to Trae/Windsurf — no statusline, no `package.json`, no shared `settings.json`/permission writes.
|
||
- **Layout:** `case 'qoder'` → `[ skillsKind('skills', 'msd-', 'convertClaudeCommandToQoderSkill', 'qoder', configDir) ]`; `'qoder'` added to `ALLOWED_RUNTIMES`.
|
||
- **Home:** `~/.qoder` (or `QODER_CONFIG_DIR`), via `runtime-homes`.
|
||
- **Converters:** `convertClaudeToQoderMarkdown`, `convertClaudeCommandToQoderSkill`, `convertClaudeAgentToQoderAgent` — the agent converter is subject to the contract above.
|
||
|
||
**Path note:** since ADR-457's `.cts` migration, the canonical module source is `src/runtime-artifact-layout.cts` (built to `msd-core/bin/lib/runtime-artifact-layout.cjs`); the runtime enumeration is owned by `src/runtime-homes.cts` and `src/runtime-config-adapter-registry.cts`. The original body above predates that move; paths read accordingly.
|