msd-core/docs/adr/3660-runtime-artifact-layout-module.md

# 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

The **Runtime Surface Module** (`gsd-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/gsd-<stem>/SKILL.md`, so `gsd-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 `gsd-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 GSD 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/gsd', prefix: 'gsd-' }` — preserves the nested namespace from #2841. **Note (#947):** The original decision used `prefix: ''` (bare stem) on the incorrect premise that the `skills/gsd/` 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 `gsd-` 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/gsd', prefix: 'gsd-' } ]` — 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) _syncGsdDir(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/gsd-*/` 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 `gsd-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/gsd/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/gsd` 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
- `gsd-core/bin/lib/runtime-artifact-layout.cjs` — module body + runtime layout table.

### Files modified (Phase 1)
- `gsd-core/bin/lib/surface.cjs` — `applySurface` signature change; `_findInstallSource` + `_findAgentsSource` removal.
- `commands/gsd/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                   'gsd-' 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 gsd-* surface
 */

function resolveRuntimeArtifactLayout(runtime, configDir) { … }
```

Call-site shape:

```js
// commands/gsd/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)) _syncGsdDir(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/gsd-*/` 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: `gsd-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`:
- `gsd-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.
- `gsd-core/bin/lib/install-profiles.cjs` — new `stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converter, prefix) → stagedDir` helper.
- `gsd-core/bin/lib/surface.cjs` — `applySurface(runtimeConfigDir, layout, manifest, clusterMap)` signature migration; `_findInstallSource` + `_findAgentsSource` deleted; `_syncGsdDir` 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', 'gsd-', '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 `gsd-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.