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

// 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:

// 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:

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.