@opengsd/gsd-core 1.9.1 → 1.11.0

package/gsd-core/bin/lib/installed-surface-resolver.cjs

@@ -0,0 +1,381 @@
+"use strict";
+/**
+ * installed-surface-resolver.cts — Installed Surface Resolver Module (#2872,
+ * ADR-2866, Phase 3 — governed by
+ * `.gsd/phase/feat-2872-manifest-scope-runtime/40-design.md`).
+ *
+ * `resolveInstalledSurfaces(runtime?, opts?)` answers a question no existing
+ * module answers: "which surfaces actually exist on THIS machine, across
+ * BOTH install scopes, right now?" `capability-state.cts` answers "which
+ * capabilities are enabled in THIS config dir" — a different question at a
+ * different altitude. This module is a new leaf: it reads two scopes at
+ * once, composing three already-shipped, already-tested pieces
+ * (`resolveScope`, Phase 1; `resolveTriggerSurface`, Phase 2; and
+ * `readInstallManifest`, widened in this same phase) rather than
+ * re-implementing any of their rules.
+ *
+ * ── Probe-not-declared keying ───────────────────────────────────────────────
+ * A scope RECORD is keyed by the PROBED scope (`resolveScope`'s own `id`),
+ * never by what the manifest itself claims. `manifestVersion`/`runtime`/
+ * `scope` recorded inside a v2 manifest are corroboration, not identity: a
+ * manifest copied between config dirs, or a `--config-dir` install, must
+ * still be reported at the scope this machine actually resolves to.
+ *
+ * ── Report, don't correct ───────────────────────────────────────────────────
+ * When a declared `runtime`/`scope` disagrees with the probe, this module
+ * reports the mismatch (`declaredScopeMatchesProbe: false` /
+ * `declaredRuntimeMatchesProbe: false`) and otherwise proceeds exactly as it
+ * would for an undeclared (v1) manifest. It never silently substitutes the
+ * declared value for the probed one, and never throws on a mismatch — see
+ * B-row "Postel's Law" discussion in the design doc.
+ *
+ * ── One trigger call over installed scopes only ─────────────────────────────
+ * `resolveTriggerSurface` is called AT MOST once per runtime, with the
+ * scopes that are actually installed on this machine (per manifest
+ * presence — never per the new corroboration fields, which is what keeps a
+ * v1-only install fully functional with no reinstall required). A
+ * hypothetical "what if both scopes were installed" answer is deliberately
+ * not offered; #2218 is a fact about THIS machine, not a simulation.
+ *
+ * ── Installed-ness is manifest PRESENCE, never the new fields ───────────────
+ * `installed` is `manifestVersion !== null`. A v1 manifest (no
+ * `manifestVersion` key at all, `manifestVersion: 1` after normalization) is
+ * a correct manifest written by an older GSD — never a broken one, never
+ * grounds for `installed: false`, a warning, or a reinstall prompt.
+ *
+ * ── Stems come from the manifest, not the source tree ───────────────────────
+ * `resolveTriggerSurface` needs `stems`. They are derived from the
+ * INSTALLED manifest's own `files` keys (see the private stem-derivation
+ * helpers below), never from a roster read of the source tree — a global
+ * `claude` install ships no `commands/gsd` source, so a roster read would
+ * return `[]` in exactly the configuration #2218 is about. The derivation
+ * consumes `isNamespacedByDir` and `composeCommandFilename`
+ * (`runtime-artifact-layout.cjs`, #2871 Phase 2's exported helpers) rather
+ * than re-deriving either rule as a fourth independent copy.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveInstalledSurfaces = resolveInstalledSurfaces;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const install_scope_cjs_1 = require("./install-scope.cjs");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const runtimeArtifactLayoutMod = require("./runtime-artifact-layout.cjs");
+const { resolveRuntimeArtifactLayout, resolveRuntimeArtifactLayoutFromRegistry, resolveTriggerSurface, isNamespacedByDir, composeCommandFilename, } = runtimeArtifactLayoutMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const installerMigrationsMod = require("./installer-migrations.cjs");
+const { readInstallManifest, MANIFEST_NAME } = installerMigrationsMod;
+// In .cts (CommonJS output) files, `require` is available as a global.
+const _require = require;
+// ── Internals ───────────────────────────────────────────────────────────
+/**
+ * A trigger stem is a kebab-case token and nothing else. Verified against the
+ * real roster: all 71 `commands/gsd/*.md` stems match this, so it has no false
+ * negatives today.
+ *
+ * This is a SECURITY boundary, not cosmetics. A stem is derived from a manifest
+ * key — attacker-influenceable text, since a project-local
+ * `gsd-file-manifest.json` lives inside a repository a user may merely have
+ * cloned — and Phase 4 (#2873) renders it back to the user as `/gsd-<stem>`.
+ * Without this, `skills/gsd-../../../x` yields the stem `..`, and control
+ * characters, newlines, ANSI escapes and RTL-override codepoints all survive
+ * into that rendered trigger. The `commands` branch happened to be protected by
+ * its `composeCommandFilename` round-trip; the `skills` branch had no
+ * equivalent, so the rule is stated once here and applied to both.
+ */
+const SAFE_STEM = /^[a-z0-9][a-z0-9-]*$/;
+function getDefaultRuntimeRegistry() {
+    return _require('./capability-registry.cjs');
+}
+/** C7: every registered runtime id, sorted for determinism. Reads
+ *  `opts.registry` when provided (so a sweep is assertable without the real
+ *  capability registry), else the real one. */
+function listRegisteredRuntimeIds(opts) {
+    const registry = opts.registry ?? getDefaultRuntimeRegistry();
+    return Object.keys(registry.runtimes).sort();
+}
+/**
+ * D — the stem inverse for one `commands`/`skills` layout kind entry.
+ * Consumes `isNamespacedByDir` (to decide the commands filename shape) and
+ * `composeCommandFilename` (to VERIFY a candidate stem round-trips to the
+ * exact filename seen) rather than re-deriving either rule locally (design
+ * "Rejected" #6). Manifest keys are normalized with an unconditional
+ * `.replace(/\\/g, '/')` (D7) — never gated on `path.sep` — matching this
+ * repo's recorded path-separator-normalization defect class.
+ */
+function deriveStemsForKindEntry(kind, destSubpath, prefix, fileKeys) {
+    const destSubpathNorm = (0, shell_command_projection_cjs_1.posixNormalize)(destSubpath);
+    const boundary = `${destSubpathNorm}/`;
+    const namespacedByDir = isNamespacedByDir(kind, destSubpath, prefix);
+    const stems = new Set();
+    for (const rawKey of fileKeys) {
+        const key = rawKey.replace(/\\/g, '/');
+        if (!key.startsWith(boundary))
+            continue; // D4: key not under this declared subpath
+        const rest = key.slice(boundary.length);
+        if (rest === '')
+            continue;
+        const segments = rest.split('/');
+        if (kind === 'skills') {
+            const dirSegment = segments[0];
+            if (!dirSegment.startsWith(prefix))
+                continue; // D5: subpath matches, prefix does not
+            const stem = dirSegment.slice(prefix.length);
+            if (stem === '')
+                continue; // D7/B7: empty stem never emitted
+            if (!SAFE_STEM.test(stem))
+                continue; // security: reject anything but a kebab-case token
+            stems.add(stem); // D6: several files under one dir -> one stem
+            continue;
+        }
+        // commands: exactly one path segment — the composed filename itself.
+        if (segments.length !== 1)
+            continue;
+        const filename = segments[0];
+        if (!filename.endsWith('.md'))
+            continue;
+        const base = filename.slice(0, -3);
+        const candidateStem = namespacedByDir
+            ? base
+            : (base.startsWith(prefix) ? base.slice(prefix.length) : '');
+        if (candidateStem === '')
+            continue;
+        if (composeCommandFilename(namespacedByDir, prefix, candidateStem) !== filename)
+            continue;
+        if (!SAFE_STEM.test(candidateStem))
+            continue; // security: reject anything but a kebab-case token
+        stems.add(candidateStem);
+    }
+    return [...stems];
+}
+/** D — full stem set for one scope: every `commands`/`skills` layout kind
+ *  entry, unioned. Empty `files` (C13) short-circuits to `[]` without
+ *  resolving a layout at all. */
+function deriveStemsFromManifest(runtime, scopeId, configHome, files, opts) {
+    const fileKeys = Object.keys(files);
+    if (fileKeys.length === 0)
+        return [];
+    const layout = opts.registry !== undefined
+        ? resolveRuntimeArtifactLayoutFromRegistry(opts.registry, runtime, configHome, scopeId)
+        : resolveRuntimeArtifactLayout(runtime, configHome, scopeId);
+    const stems = new Set();
+    for (const kindEntry of layout.kinds) {
+        if (kindEntry.kind !== 'commands' && kindEntry.kind !== 'skills')
+            continue; // excludes agents/kimi-agents (D4)
+        for (const stem of deriveStemsForKindEntry(kindEntry.kind, kindEntry.destSubpath, kindEntry.prefix, fileKeys)) {
+            stems.add(stem);
+        }
+    }
+    return [...stems].sort();
+}
+/**
+ * True when `p` is a symlink. An `lstatSync` throw (ENOENT — nothing at this
+ * path) is NOT evidence of a symlink; it is treated as "not a symlink" here
+ * and left for `readManifest` to classify (it already owns the absent-file
+ * case, per C14 above).
+ */
+function isSymlinkPath(p, lstatSync) {
+    try {
+        return lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The shared "not installed" degraded shape (C14's EACCES path, and this
+ * phase's new symlink-guard path). A FACTORY, not a module-level constant
+ * object: a `const` object spread at each return site would still share the
+ * same `stems` ARRAY reference across every call (`...` shallow-copies the
+ * object but not the array a property points at), which would violate this
+ * module's own "builds fresh arrays/objects on every call" contract (C15) —
+ * a caller mutating one degraded record's `stems` must never be visible on
+ * another's.
+ */
+function notInstalledScopeRecordFields() {
+    return {
+        installed: false,
+        manifestVersion: null,
+        declaredRuntime: null,
+        declaredScope: null,
+        declaredScopeMatchesProbe: null,
+        declaredRuntimeMatchesProbe: null,
+        stems: [],
+    };
+}
+/**
+ * Build one scope's record. `resolvedConfigHome` has already been probed
+ * successfully by the time this is called (a `resolveScope` `TypeError` is
+ * handled by the caller, per C8 — it is never this function's concern).
+ *
+ * Two distinct failure modes are handled with two distinct, narrowly-scoped
+ * try/catches — NOT one catch-all around the whole function:
+ *
+ *  - The manifest READ (`readManifest`) is the only thing that can justify
+ *    `installed: false` (C14, e.g. EACCES). A failure here means "we could
+ *    not even tell whether this scope is installed".
+ *  - The stem DERIVATION (`deriveStemsFromManifest`, which resolves a
+ *    runtime artifact layout) is a separate concern. A `TypeError` thrown
+ *    while deriving stems is a layout-lookup failure, not evidence the
+ *    manifest is absent — the manifest was already read successfully, so
+ *    `installed` and every declared/*MatchesProbe field stay exactly as the
+ *    manifest reported. Conflating the two would report a genuinely
+ *    installed runtime as `installed: false`, hiding a real install from
+ *    #2218 shadow detection precisely when this module exists to surface it.
+ */
+function buildScopeRecord(runtime, scopeId, resolvedConfigHome, opts) {
+    // Hardening requirement 2 (#2873 design doc, "Hardening requirements
+    // claimed from #2873's comment"): `readInstallManifest` -> `readJsonIfPresent`
+    // uses `existsSync` + `readFileSync` and therefore FOLLOWS symlinks, and
+    // this module resolves `local` against `process.cwd()` — a directory that,
+    // as of this phase, becomes reachable from an arbitrary cloned repository
+    // (this is the same phase that makes the local scope's manifest a first
+    // read target, not merely a write target). The in-tree precedent is
+    // `getAgentsDir` (`agent-install-check.cts`), which probes with
+    // `fs.lstatSync(...).isDirectory()`/`.isFile()` and deliberately does not
+    // follow. #2872 left this resolver's read un-guarded only because the path
+    // had zero callers at the time; refusing to follow a symlinked config dir
+    // or manifest here closes that asymmetry rather than carrying it forward.
+    // Degrading to `installed: false` reuses the SAME shape the EACCES catch
+    // below already returns — no new failure shape is introduced.
+    const lstatSync = opts.lstatSync ?? node_fs_1.default.lstatSync;
+    const manifestPath = node_path_1.default.join(resolvedConfigHome, MANIFEST_NAME);
+    if (isSymlinkPath(resolvedConfigHome, lstatSync) || isSymlinkPath(manifestPath, lstatSync)) {
+        return { scope: scopeId, configHome: resolvedConfigHome, ...notInstalledScopeRecordFields() };
+    }
+    let manifest;
+    try {
+        const readManifest = opts.readManifest ?? readInstallManifest;
+        manifest = readManifest(resolvedConfigHome);
+    }
+    catch {
+        // C14: manifest read/probe failure degrades to not-installed, never throws.
+        // Deliberately a BARE catch, unlike the stem-derivation catch below: any
+        // read failure at all (EACCES, ENOENT-after-race, a corrupt filesystem)
+        // legitimately means "cannot tell whether installed" (design row C14), so
+        // there is no error TYPE here that should instead propagate.
+        return { scope: scopeId, configHome: resolvedConfigHome, ...notInstalledScopeRecordFields() };
+    }
+    const installed = manifest.manifestVersion !== null; // C9: presence, never the new fields
+    const declaredRuntime = manifest.runtime;
+    const declaredScope = manifest.scope;
+    const declaredRuntimeMatchesProbe = declaredRuntime === null ? null : declaredRuntime === runtime;
+    const declaredScopeMatchesProbe = declaredScope === null ? null : declaredScope === scopeId;
+    let stems = [];
+    if (installed) {
+        try {
+            stems = deriveStemsFromManifest(runtime, scopeId, resolvedConfigHome, manifest.files, opts);
+        }
+        catch (error) {
+            if (!(error instanceof TypeError))
+                throw error;
+            // A layout-lookup failure means "we could not enumerate this scope's
+            // triggers", NOT "this scope is not installed" — the manifest read
+            // already succeeded above, so `installed` and the declared fields
+            // stay as reported. Conflating the two would hide a real install.
+            // Anything that is not the expected `TypeError` (a genuine bug in
+            // `deriveStemsFromManifest`/`resolveRuntimeArtifactLayout`) is
+            // rethrown rather than silently degrading to `stems: []` — this
+            // matches `resolveInstalledSurfaces`'s own `TypeError` narrowing
+            // below, so the two catches cannot drift apart.
+            stems = [];
+        }
+    }
+    return {
+        scope: scopeId,
+        configHome: resolvedConfigHome,
+        installed,
+        manifestVersion: manifest.manifestVersion,
+        declaredRuntime,
+        declaredScope,
+        declaredScopeMatchesProbe,
+        declaredRuntimeMatchesProbe,
+        stems,
+    };
+}
+/**
+ * Resolve one runtime's full installed surface. A `resolveScope` `TypeError`
+ * (unknown runtime, or `configHome.kind === 'none'`, e.g. vscode) propagates
+ * from here uncaught — `resolveInstalledSurfaces` decides whether that
+ * means "skip" (C7 sweep) or "propagate" (explicit single-runtime ask, C8).
+ */
+function resolveOneRuntime(runtime, opts) {
+    const scopes = install_scope_cjs_1.SCOPE_ORDER.map((scopeId) => {
+        const resolved = (0, install_scope_cjs_1.resolveScope)({
+            id: scopeId,
+            runtime,
+            env: opts.env,
+            home: opts.home,
+            existsSync: opts.existsSync,
+            cwd: opts.cwd,
+        });
+        return buildScopeRecord(runtime, scopeId, resolved.configHome, opts);
+    });
+    // C12: dedupe by resolved configHome BEFORE the trigger call, keeping the
+    // higher-ranked (global, first in SCOPE_ORDER) scope. Both scope RECORDS
+    // above are unaffected — only the scope list handed to resolveTriggerSurface
+    // is deduped.
+    const seenConfigHomes = new Set();
+    const triggerScopeIds = [];
+    for (const record of scopes) {
+        if (!record.installed)
+            continue;
+        if (seenConfigHomes.has(record.configHome))
+            continue;
+        seenConfigHomes.add(record.configHome);
+        triggerScopeIds.push(record.scope);
+    }
+    const stemUnion = new Set();
+    for (const scopeId of triggerScopeIds) {
+        const record = scopes.find((s) => s.scope === scopeId);
+        for (const stem of record?.stems ?? [])
+            stemUnion.add(stem);
+    }
+    const triggers = triggerScopeIds.length > 0
+        ? resolveTriggerSurface(runtime, triggerScopeIds, {
+            stems: [...stemUnion].sort(),
+            registry: opts.registry,
+        })
+        : [];
+    return { runtime, scopes, triggers };
+}
+/**
+ * Read-only. Probes both install scopes for a runtime (or every registered
+ * runtime, sorted by id, when `runtime` is omitted), reads each scope's
+ * manifest, and resolves the trigger surface across the scopes that are
+ * actually installed on this machine. See the module-level comment for the
+ * non-obvious choices (probe-not-declared keying, report-don't-correct, one
+ * trigger call over installed scopes only).
+ *
+ * Pure with respect to caller-visible state: builds fresh arrays/objects on
+ * every call (C15) and performs no writes. Filesystem reads happen only via
+ * `resolveScope`'s injected `existsSync`/`env`/`home`/`cwd` and via
+ * `readManifest` (default: `readInstallManifest`).
+ *
+ * @throws {TypeError} when `runtime` is given explicitly and it is unknown,
+ *   or has no installable config directory (`configHome.kind === 'none'`,
+ *   e.g. vscode) — same contract `resolveScope` throws. In the all-runtimes
+ *   sweep (`runtime` omitted), a runtime that would throw this same
+ *   `TypeError` is skipped instead, so one non-installable runtime cannot
+ *   kill the sweep (C7/C8). Any other error type is never swallowed here.
+ */
+function resolveInstalledSurfaces(runtime, opts = {}) {
+    if (typeof runtime === 'string') {
+        return [resolveOneRuntime(runtime, opts)];
+    }
+    const results = [];
+    for (const runtimeId of listRegisteredRuntimeIds(opts)) {
+        try {
+            results.push(resolveOneRuntime(runtimeId, opts));
+        }
+        catch (error) {
+            if (error instanceof TypeError)
+                continue; // C8: sweep skips, never dies
+            throw error;
+        }
+    }
+    return results;
+}

package/gsd-core/bin/lib/installer-migration-authoring.cjs

@@ -109,7 +109,9 @@ function validateInstallerMigrationActions(actions, migration) {
         // Ownership and runtime-contract evidence are required by
         // docs/installer-migrations.md#action-types and
         // docs/adr/0008-installer-migration-module.md#runtime-contract-decision.
-        if (actType === 'remove-managed' || actType === 'rewrite-json') {
+        // `remove-empty-dir` carries the same evidence bar as `remove-managed`: it is
+        // still a destructive removal, just of a directory node instead of a file.
+        if (actType === 'remove-managed' || actType === 'rewrite-json' || actType === 'remove-empty-dir') {
             requireActionEvidence(act, 'ownershipEvidence', migration);
         }
         if (actType === 'rewrite-json') {

package/gsd-core/bin/lib/installer-migration-report.cjs

@@ -32,6 +32,7 @@ const VALID_CHOICES = ['keep', 'remove'];
 // on-disk `hooks/` directory in both directions: whitelist-but-missing
 // AND shipped-but-not-whitelisted both fail CI.
 exports.BUNDLED_GSD_HOOK_FILES = Object.freeze(new Set([
+    'hooks/gsd-agent-isolation-guard.js',
     'hooks/gsd-check-update-worker.js',
     'hooks/gsd-check-update.js',
     'hooks/gsd-config-reload.js',
@@ -57,6 +58,7 @@ exports.BUNDLED_GSD_HOOK_FILES = Object.freeze(new Set([
     'hooks/gsd-validate-commit.sh',
     'hooks/gsd-workflow-guard.js',
     'hooks/gsd-worktree-path-guard.js',
+    'hooks/gsd-write-guard.js',
 ]));
 // ── Internal helpers ──────────────────────────────────────────────────────────
 function installerMigrationActionLabel(action) {
@@ -74,6 +76,8 @@ function installerMigrationActionLabel(action) {
         return 'preserved';
     if (action.type === 'preserve-user')
         return 'preserved';
+    if (action.type === 'remove-empty-dir')
+        return 'removed';
     if (action.type === 'prompt-user')
         return 'blocked';
     return 'skipped';

package/gsd-core/bin/lib/installer-migrations/007-retire-config-root-commonjs-marker.cjs

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * Installer migration: retire the config-root `{"type":"commonjs"}` marker that
+ * pre-#2544 installs wrote over `<configRoot>/package.json`.
+ *
+ * What old artifact is being retired?
+ *   `package.json` at the runtime config root. Before #2544,
+ *   `installSharedHooksBundle(destRootDir)` wrote `{"type":"commonjs"}` there
+ *   unconditionally on every install and every re-install, to pin GSD's staged
+ *   `.js` hook scripts to CommonJS via Node's ancestor walk. #2544 moved that
+ *   marker into the directories GSD actually fills (`hooks/`, and the
+ *   `nativePlugin.dir` for runtimes declaring one) and stopped writing the
+ *   config root at all. Without this migration an upgrader keeps BOTH markers:
+ *   the new one under `hooks/` and the stale one at the root, so the config
+ *   root stays pinned to CommonJS and the PR's own claim — that GSD no longer
+ *   writes the shared config root — is false for every install made since the
+ *   marker was introduced, until the user uninstalls.
+ *
+ * How do we prove it is GSD-owned?
+ *   By exact content match, NOT by the manifest. The config-root marker was
+ *   never recorded in `gsd-file-manifest.json` — `writeManifest()` records
+ *   `hooks/`, `agents/`, `commands/`, `scripts/`, and the native plugin, and
+ *   has never had a `manifest.files['package.json']` entry — so
+ *   `classifyArtifact('package.json')` answers `unknown` and the planner's
+ *   own guard would downgrade a `remove-managed` to `preserve-user`.
+ *   This migration therefore supplies the "purpose-built detector for an old
+ *   GSD-owned shape" that `docs/installer-migrations.md#remove-managed`
+ *   sanctions, and declares the resulting classification on the action: the
+ *   file is removed only when its bytes are exactly the marker GSD writes
+ *   (`{"type":"commonjs"}`, trailing whitespace tolerated). That is the same
+ *   predicate `removeCommonJsMarker` has always used on the uninstall side, so
+ *   install, uninstall, and migration cannot drift apart.
+ *
+ * What happens if the user modified it?
+ *   Then it is not the marker, and this migration does not touch it. Any
+ *   `package.json` carrying a `name`, `dependencies`, `scripts`, or any key
+ *   beyond the single `type` — i.e. every file the #2544 defect destroyed —
+ *   fails the exact-content test and is left exactly as found. There is
+ *   deliberately no `backup-and-remove` branch: a modified file here is not a
+ *   patched GSD artifact, it is somebody else's file.
+ *
+ * What happens if it is missing?
+ *   No actions. Fresh post-#2544 installs never wrote it, already-migrated
+ *   installs no longer have it, and the executor additionally journals a
+ *   `missing` outcome if it disappears between plan and apply. Idempotent.
+ *
+ * What runtime and scope does it affect?
+ *   Every runtime whose config root received the marker — i.e. every runtime
+ *   not excluded from `installSharedHooksBundle(targetDir)` by
+ *   `hostBehaviors.skipSharedHooksInstall` and not Codex: antigravity,
+ *   augment, claude, claude-local, codebuddy, hermes, qwen, kilo, opencode,
+ *   and pi. The `runtimes` field is OMITTED — the framework's "all runtimes" —
+ *   rather than carrying that hand-list: a runtime that never received the
+ *   marker simply has no file to match, so enumerating them would add a second
+ *   place for the set to drift out of date without changing behavior. Note it
+ *   must be omitted and not `[]`; see the field's own comment below.
+ *
+ *   ONE DELIBERATE CARVE-OUT — kimi. Kimi's marker was written to its native
+ *   hook root (`~/.kimi`, `resolveKimiHooksTomlDir`), which is NOT under
+ *   kimi's `configDir` (its generic Agent-Skills root). Migration relPaths are
+ *   structurally confined to `configDir` (`validateSafeRelPath` /
+ *   `ensureInsideConfig`), so this framework cannot address that path at all.
+ *   Kimi's stale root marker is retired by the installer instead, at the same
+ *   call site that writes its replacement — see the `kimi-hooks-toml` branch
+ *   in `bin/install.js`. Named here so the gap is not mistaken for an
+ *   oversight.
+ *
+ * Is the action safe in non-interactive install?
+ *   Yes. `remove-managed` is non-interactive and journaled, the executor takes
+ *   a rollback snapshot before unlinking, and no branch of this migration can
+ *   emit `prompt-user`. A file that is not byte-identical to GSD's marker
+ *   produces no action at all.
+ *
+ * See docs/installer-migrations.md#shipped-migrations and #action-types.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+/** The config-root path the pre-#2544 installer wrote, relative to configDir. */
+const STALE_ROOT_MARKER = 'package.json';
+/**
+ * The exact marker content GSD wrote. Duplicated as a literal rather than
+ * imported from `src/commonjs-marker.cts` on purpose: a migration record is a
+ * frozen historical statement about what a PAST version installed, and it must
+ * keep matching those bytes even if the live module's constant is ever changed.
+ * Importing would silently re-point this detector at a future value.
+ */
+const LEGACY_MARKER_CONTENT = '{"type":"commonjs"}';
+const OWNERSHIP_EVIDENCE = 'file content is byte-identical to the {"type":"commonjs"} marker pre-#2544 installs '
+    + 'wrote at the config root (installSharedHooksBundle); same exact-content predicate '
+    + 'removeCommonJsMarker uses on uninstall. Never manifest-recorded, so this is the '
+    + 'purpose-built detector permitted by docs/installer-migrations.md#remove-managed';
+const REASON = 'superseded by the hooks/ and plugin-dir markers (#2544); leaving it pins the shared '
+    + 'config root to CommonJS and keeps GSD occupying a file it no longer writes';
+const migration = {
+    id: '2026-07-28-retire-config-root-commonjs-marker',
+    title: 'Retire the pre-#2544 config-root CommonJS marker',
+    description: 'Remove <configRoot>/package.json when it is exactly the {"type":"commonjs"} marker '
+        + 'pre-#2544 installs wrote there, now superseded by markers scoped to the directories '
+        + 'GSD owns. A package.json with any other content is left untouched.',
+    introducedIn: '1.8.0',
+    scopes: ['global', 'local'],
+    destructive: true,
+    plan: (ctx) => {
+        const markerPath = node_path_1.default.join(ctx.configDir, STALE_ROOT_MARKER);
+        let stat;
+        try {
+            // lstat, not existsSync: existsSync follows symlinks and reports false for
+            // a dangling one. A symlink here is not something GSD wrote, and removing
+            // it is never ours to do — mirrors classifyMarker's fail-closed posture.
+            stat = node_fs_1.default.lstatSync(markerPath);
+        }
+        catch {
+            return [];
+        }
+        if (!stat.isFile())
+            return [];
+        let content;
+        try {
+            content = node_fs_1.default.readFileSync(markerPath, 'utf8');
+        }
+        catch {
+            // Present but unreadable never downgrades to the permissive answer.
+            return [];
+        }
+        if (content.trim() !== LEGACY_MARKER_CONTENT)
+            return [];
+        const hash = node_crypto_1.default.createHash('sha256').update(content).digest('hex');
+        return [
+            {
+                type: 'remove-managed',
+                relPath: STALE_ROOT_MARKER,
+                reason: REASON,
+                ownershipEvidence: OWNERSHIP_EVIDENCE,
+                // Declared, not derived: classifyArtifact answers 'unknown' for this
+                // never-manifested path, and the planner downgrades a remove-managed on
+                // an 'unknown' classification to preserve-user. The exact-content match
+                // above IS the ownership proof, so the classification is stated here.
+                classification: 'managed-pristine',
+                originalHash: hash,
+                currentHash: hash,
+            },
+        ];
+    },
+};
+module.exports = migration;

package/gsd-core/bin/lib/installer-migrations/008-cursor-retire-commands-surface.cjs

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Installer migration: retire Cursor's duplicate commands/ surface (#2644).
+ *
+ * Cursor discovers GSD skills as slash-menu entries while also keeping them
+ * model-invocable. Older GSD releases installed the same workflows again as
+ * commands/gsd-*.md, so every action appeared twice. The skills remain the
+ * sole workflow surface; this migration removes only old command files proven
+ * managed by gsd-file-manifest.json. Modified files are backed up first and
+ * unmanifested files are preserved.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const COMMANDS_DIR = 'commands';
+const REASON = 'Cursor exposes skills directly in the slash menu; the parallel command file duplicated the same GSD action (#2644)';
+const OWNERSHIP_EVIDENCE = 'pre-#2644 Cursor installs record commands/gsd-*.md in gsd-file-manifest.json';
+const migration = {
+    id: '2026-07-29-cursor-retire-commands-surface',
+    title: 'Retire Cursor duplicate commands surface',
+    description: 'Remove manifest-managed Cursor commands/gsd-*.md files now that skills are the single slash-menu and model-invocation surface.',
+    introducedIn: '1.8.1',
+    runtimes: ['cursor'],
+    scopes: ['global', 'local'],
+    destructive: true,
+    plan: (ctx) => {
+        const commandsDir = node_path_1.default.join(ctx.configDir, COMMANDS_DIR);
+        let entries;
+        try {
+            if (!node_fs_1.default.existsSync(commandsDir) || node_fs_1.default.lstatSync(commandsDir).isSymbolicLink())
+                return [];
+            entries = node_fs_1.default.readdirSync(commandsDir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        const actions = [];
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.startsWith('gsd-') || !entry.name.endsWith('.md'))
+                continue;
+            const relPath = node_path_1.default.posix.join(COMMANDS_DIR, entry.name);
+            const artifact = ctx.classifyArtifact(relPath);
+            if (artifact.classification === 'managed-pristine') {
+                actions.push({ type: 'remove-managed', relPath, reason: REASON, ownershipEvidence: OWNERSHIP_EVIDENCE });
+            }
+            else if (artifact.classification === 'managed-modified') {
+                actions.push({ type: 'backup-and-remove', relPath, reason: REASON, ownershipEvidence: OWNERSHIP_EVIDENCE });
+            }
+        }
+        return actions;
+    },
+};
+module.exports = migration;