refactor: hard-fork GSD -> MSD (Make Software Done)
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.
This commit is contained in:
Jakub Zych
@@ -4,51 +4,51 @@
|
||||
- **Date:** 2026-05-17
|
||||
- **Issue:** #3660
|
||||
- **Implementation:** #3663 (Phase 1), feat/3663-runtime-artifact-layout-module-phase-1-m
|
||||
- **Subsumed by:** [ADR-1239](1239-gsd-embeddable-orchestration-engine.md) (GSD 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 `/gsd-<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.
|
||||
- **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-gsd-embeddable-orchestration-engine.md) — **GSD 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 GSD meets a host.
|
||||
[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-gsd-embeddable-orchestration-engine.md) first.**
|
||||
**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** (`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 **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 `gsd-core/bin/lib/runtime-artifact-layout.cjs` as the single owner of the per-runtime artifact-placement table.
|
||||
- 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 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.).
|
||||
- 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/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.
|
||||
- **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/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)`.
|
||||
- **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/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.
|
||||
- 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 `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`.
|
||||
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/gsd/surface.md` and `tests/surface-apply.test.cjs` updated to construct + pass `Layout` values.
|
||||
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/gsd` nested case.
|
||||
- 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.
|
||||
@@ -61,11 +61,11 @@ Phase 1 should **not**:
|
||||
## Migration Inventory
|
||||
|
||||
### New file
|
||||
- `gsd-core/bin/lib/runtime-artifact-layout.cjs` — module body + runtime layout table.
|
||||
- `msd-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`.
|
||||
- `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)
|
||||
@@ -87,7 +87,7 @@ Phase 1 should **not**:
|
||||
* @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 {string} prefix 'msd-' for all runtimes (incl. Hermes after #947)
|
||||
* @property {(resolved) => string} stage returns staged dir path
|
||||
*/
|
||||
|
||||
@@ -95,7 +95,7 @@ Phase 1 should **not**:
|
||||
* @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
|
||||
* @property {ArtifactKind[]} kinds empty array = runtime has no msd-* surface
|
||||
*/
|
||||
|
||||
function resolveRuntimeArtifactLayout(runtime, configDir) { … }
|
||||
@@ -104,7 +104,7 @@ function resolveRuntimeArtifactLayout(runtime, configDir) { … }
|
||||
Call-site shape:
|
||||
|
||||
```js
|
||||
// commands/gsd/surface.md (runbook), tests/surface-apply.test.cjs, future install/uninstall
|
||||
// commands/msd/surface.md (runbook), tests/surface-apply.test.cjs, future install/uninstall
|
||||
const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir);
|
||||
applySurface(runtimeConfigDir, layout, manifest, CLUSTERS);
|
||||
```
|
||||
@@ -117,7 +117,7 @@ function applySurface(runtimeConfigDir, layout, 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);
|
||||
if (fs.existsSync(dest)) _syncMsdDir(staged, dest, kind.kind);
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -142,21 +142,21 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap) {
|
||||
|
||||
## References
|
||||
|
||||
- Confirmed bug: `#3659` — `applySurface` doesn't prune `~/.claude/skills/gsd-*/` dirs
|
||||
- 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: `gsd-core/bin/lib/runtime-homes.cjs`
|
||||
- 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`:
|
||||
- `gsd-core/bin/lib/runtime-artifact-layout.cjs` — 15-runtime layout table (grok intentionally excluded), `resolveRuntimeArtifactLayout(runtime, configDir, scope) → Layout`, walk-up `findInstallSourceRoot` helper.
|
||||
- `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.
|
||||
- `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.
|
||||
- `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.
|
||||
@@ -184,8 +184,8 @@ Per-runtime **agent** converters emit a **sanitized minimal frontmatter** — `n
|
||||
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`.
|
||||
- **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 `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.
|
||||
**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.
|
||||
|
||||
Reference in New Issue
Block a user