@opengsd/gsd-core 1.7.0-rc.5 → 1.7.0

package/gsd-core/bin/lib/init.cjs

@@ -13,6 +13,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const clock_cjs_1 = require("./clock.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- io.cjs is an export= CommonJS module
 const io = require("./io.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- config-loader.cjs is an export= CommonJS module
@@ -63,7 +64,7 @@ const { resolveModelInternal, resolveGranularityInternal, assertValidGranularity
 const { findPhaseInternal } = phaseLocator;
 const { getRoadmapPhaseInternal, getMilestoneInfo, getMilestonePhaseFilter, stripShippedMilestones, extractCurrentMilestone, } = roadmapParser;
 const { pathExistsInternal, generateSlugInternal, toPosixPath } = coreUtils;
-const { escapeRegex, normalizePhaseName, phaseTokenMatches, stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE } = phaseId;
+const { escapeRegex, normalizePhaseName, phaseTokenMatches, stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE, isForeignPrefixedPhaseQuery } = phaseId;
 const { pruneOrphanedWorktrees } = worktreeSafety;
 const { planningPaths, planningDir, planningRoot, listAvailableWorkstreams, getActiveWorkstream, findContextMdIn, } = planningWorkspace;
 const { determinePhaseStatus } = commandsMod;
@@ -74,25 +75,10 @@ const { evaluateUatPassed } = uatPredicateMod;
 void stripShippedMilestones;
 // Accept all bold/colon variants of the Requirements header (#2769)
 const REQUIREMENTS_HEADER_RE = /^\*\*Requirements:?\*\*[^\S\n]*:?[^\S\n]*([^\n]*)$/m;
-// #2056: normalizePhaseName() strips ANY [A-Z][A-Z0-9_]*- prefix as a project
-// code (e.g. 'MEM-01' → '01'), so a foreign-prefixed workstream/task id would
-// collapse to its numeric suffix and resolve to an unrelated numeric phase via
-// the dir/roadmap fallback. init plan-phase must require EXACT prefixed
-// evidence — a phase dir whose token literally IS the prefixed query, or a
-// roadmap entry literally headed with it — before accepting such a match. The
-// configured project_code's own prefix (e.g. LKML-01 under project_code: LKML)
-// is never foreign and always passes through.
-function parsePhasePrefix(phase) {
-    const match = String(phase).match(/^([A-Z][A-Z0-9_]*)-(?=\d)/i);
-    return match ? match[1] : null;
-}
-function isForeignPrefixedPhaseQuery(phase, projectCode) {
-    const prefix = parsePhasePrefix(phase);
-    if (!prefix)
-        return false;
-    const configured = typeof projectCode === 'string' ? projectCode.trim() : '';
-    return !configured || prefix.toUpperCase() !== configured.toUpperCase();
-}
+// #2056/#2104: isForeignPrefixedPhaseQuery is imported from phase-id.cts
+// (the canonical predicate). parsePhasePrefix is no longer needed locally.
+// phaseInfoMatchesExactPrefix and roadmapPhaseMatchesExactPrefix are local
+// helpers that post-filter the lookup results for foreign-prefix queries.
 function phaseInfoMatchesExactPrefix(phaseInfo, phase) {
     const num = phaseInfo?.['phase_number'];
     const numStr = typeof num === 'string' ? num : (typeof num === 'number' ? String(num) : '');
@@ -103,6 +89,23 @@ function roadmapPhaseMatchesExactPrefix(roadmapPhase, phase) {
     const section = typeof sectionRaw === 'string' ? sectionRaw : '';
     return new RegExp(`^#{2,4}\\s*Phase\\s+${escapeRegex(phase)}(?:\\b|\\s|:)`, 'i').test(section);
 }
+// #2104: shared helpers that wrap findPhaseInternal / getRoadmapPhaseInternal
+// with the #2056 foreign-prefix guard, so every init command gets the same
+// protection without duplicating the guard logic at each call site.
+function guardedFindPhase(cwd, phase, projectCode) {
+    let phaseInfo = findPhaseInternal(cwd, phase);
+    if (isForeignPrefixedPhaseQuery(phase, projectCode) && !phaseInfoMatchesExactPrefix(phaseInfo, phase)) {
+        phaseInfo = null;
+    }
+    return phaseInfo;
+}
+function guardedGetRoadmapPhase(cwd, phase, projectCode) {
+    let roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+    if (isForeignPrefixedPhaseQuery(phase, projectCode) && !roadmapPhaseMatchesExactPrefix(roadmapPhase, phase)) {
+        roadmapPhase = null;
+    }
+    return roadmapPhase;
+}
 function listPhaseSummaryFiles(phaseDir) {
     return scanPhasePlans(phaseDir)['summaryFiles'];
 }
@@ -201,7 +204,7 @@ function getInitGitState(cwd) {
         }
         resolved = node_path_1.default.resolve(resolved);
         if (process.platform === 'win32') {
-            return resolved.replace(/\//g, '\\').toLowerCase();
+            return (0, shell_command_projection_cjs_1.toNativePath)(resolved).toLowerCase();
         }
         return resolved;
     };
@@ -211,7 +214,7 @@ function getInitGitState(cwd) {
         try {
             const prefixResult = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--show-prefix'], { cwd, timeout: 5000 });
             if (prefixResult['exitCode'] === 0) {
-                const prefix = (typeof prefixResult['stdout'] === 'string' ? prefixResult['stdout'] : '').trim().replace(/\\/g, '/');
+                const prefix = (0, shell_command_projection_cjs_1.posixNormalize)((typeof prefixResult['stdout'] === 'string' ? prefixResult['stdout'] : '').trim());
                 inNestedSubdir = prefix.length > 0 && prefix !== '.' && prefix !== './';
                 resolvedByGitPrefix = true;
             }
@@ -228,7 +231,7 @@ function getInitGitState(cwd) {
                 }
                 else {
                     const rel = node_path_1.default.relative(rootNorm, cwdNorm);
-                    const relNorm = process.platform === 'win32' ? rel.replace(/\//g, '\\') : rel;
+                    const relNorm = (0, shell_command_projection_cjs_1.toNativePath)(rel);
                     inNestedSubdir =
                         relNorm !== '' &&
                             relNorm !== '.' &&
@@ -242,7 +245,7 @@ function getInitGitState(cwd) {
         }
     }
     if (inNestedSubdir && typeof worktreeRoot === 'string') {
-        const toComparableRaw = (p) => p.replace(/\\/g, '/').replace(/\/+$/g, '').toLowerCase();
+        const toComparableRaw = (p) => (0, shell_command_projection_cjs_1.posixNormalize)(p).replace(/\/+$/g, '').toLowerCase();
         if (toComparableRaw(worktreeRoot) === toComparableRaw(String(cwd))) {
             inNestedSubdir = false;
         }
@@ -258,9 +261,9 @@ function cmdInitExecutePhase(cwd, phase, raw, options = {}) {
         error('phase required for init execute-phase');
     }
     const config = loadConfig(cwd);
-    let phaseInfo = findPhaseInternal(cwd, phase);
+    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code);
     const milestone = getMilestoneInfo(cwd);
-    const roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+    const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
     if (phaseInfo?.['archived'] && roadmapPhase?.['found']) {
         phaseInfo = null;
     }
@@ -361,18 +364,9 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
         error('phase required for init plan-phase');
     }
     const config = loadConfig(cwd);
-    const foreignPrefixedPhase = isForeignPrefixedPhaseQuery(phase, config.project_code);
-    let phaseInfo = findPhaseInternal(cwd, phase);
-    // #2056: a foreign-prefixed query must only match a phase whose token literally
-    // IS the prefixed query (e.g. a real 'MEM-01-*' dir); otherwise the numeric
-    // fallback ('MEM-01' → '01') would resolve to the unrelated numeric phase.
-    if (foreignPrefixedPhase && !phaseInfoMatchesExactPrefix(phaseInfo, phase)) {
-        phaseInfo = null;
-    }
-    let roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
-    if (foreignPrefixedPhase && !roadmapPhaseMatchesExactPrefix(roadmapPhase, phase)) {
-        roadmapPhase = null;
-    }
+    // #2056/#2104: foreign-prefixed queries must not collapse to numeric phases.
+    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code);
+    const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
     if (phaseInfo?.['archived'] && roadmapPhase?.['found']) {
         phaseInfo = null;
     }
@@ -620,8 +614,8 @@ function cmdInitQuick(cwd, description, raw) {
         quick_id: quickId,
         slug: slug,
         description: description || null,
-        date: now.toISOString().split('T')[0],
-        timestamp: now.toISOString(),
+        date: clock_cjs_1.realClock.localToday(),
+        timestamp: clock_cjs_1.realClock.nowIso(),
         quick_dir: '.planning/quick',
         task_dir: slug ? `.planning/quick/${quickId}-${slug}` : null,
         roadmap_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md')),
@@ -679,15 +673,15 @@ function cmdInitVerifyWork(cwd, phase, raw) {
     }
     const config = loadConfig(cwd);
     const _slashRuntime = (0, runtime_slash_cjs_1.resolveRuntime)(cwd);
-    let phaseInfo = findPhaseInternal(cwd, phase);
+    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code);
     if (phaseInfo?.['archived']) {
-        const roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+        const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
         if (roadmapPhase?.['found']) {
             phaseInfo = null;
         }
     }
     if (!phaseInfo) {
-        const roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+        const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
         if (roadmapPhase?.['found']) {
             const phaseName = roadmapPhase['phase_name'];
             phaseInfo = {
@@ -736,9 +730,24 @@ function cmdInitVerifyWork(cwd, phase, raw) {
 }
 function cmdInitPhaseOp(cwd, phase, raw) {
     const config = loadConfig(cwd);
-    let phaseInfo = findPhaseInternal(cwd, phase);
+    let phaseInfo = guardedFindPhase(cwd, phase, config.project_code);
+    // #2237: surface ambiguous phase-directory collisions instead of silently
+    // taking the first match when unrelated projects share a .planning/phases/ tree.
+    if (phaseInfo?.['ambiguous_matches']) {
+        const matches = phaseInfo['ambiguous_matches'];
+        const result = {
+            phase_found: false,
+            phase_dir: null,
+            phase_number: null,
+            phase_name: null,
+            ambiguous_matches: matches,
+            warning: `Phase ${phase} is ambiguous: ${matches.length} directories match (${matches.map((m) => `"${m}"`).join(', ')}). Set a distinct project_code in .planning/config.json to scope resolution.`,
+        };
+        output(withProjectRoot(cwd, result), raw);
+        return;
+    }
     if (phaseInfo?.['archived']) {
-        const roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+        const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
         if (roadmapPhase?.['found']) {
             const phaseName = roadmapPhase['phase_name'];
             phaseInfo = {
@@ -759,7 +768,7 @@ function cmdInitPhaseOp(cwd, phase, raw) {
         }
     }
     if (!phaseInfo) {
-        const roadmapPhase = getRoadmapPhaseInternal(cwd, phase);
+        const roadmapPhase = guardedGetRoadmapPhase(cwd, phase, config.project_code);
         if (roadmapPhase?.['found']) {
             const phaseName = roadmapPhase['phase_name'];
             phaseInfo = {
@@ -856,7 +865,6 @@ function cmdInitPhaseOp(cwd, phase, raw) {
 }
 function cmdInitTodos(cwd, area, raw) {
     const config = loadConfig(cwd);
-    const now = new Date();
     const pendingDir = node_path_1.default.join(planningDir(cwd), 'todos', 'pending');
     let count = 0;
     const todos = [];
@@ -892,8 +900,8 @@ function cmdInitTodos(cwd, area, raw) {
     }
     const result = {
         commit_docs: config.commit_docs,
-        date: now.toISOString().split('T')[0],
-        timestamp: now.toISOString(),
+        date: clock_cjs_1.realClock.localToday(),
+        timestamp: clock_cjs_1.realClock.nowIso(),
         todo_count: count,
         todos,
         area_filter: area || null,
@@ -1014,7 +1022,6 @@ function cmdInitMilestoneOp(cwd, raw) {
 }
 function cmdInitMapCodebase(cwd, raw) {
     const config = loadConfig(cwd);
-    const now = new Date();
     const codebaseDir = node_path_1.default.join(planningRoot(cwd), 'codebase');
     let existingMaps = [];
     try {
@@ -1029,8 +1036,8 @@ function cmdInitMapCodebase(cwd, raw) {
         search_gitignored: config.search_gitignored,
         parallelization: config.parallelization,
         subagent_timeout: config.subagent_timeout,
-        date: now.toISOString().split('T')[0],
-        timestamp: now.toISOString(),
+        date: clock_cjs_1.realClock.localToday(),
+        timestamp: clock_cjs_1.realClock.nowIso(),
         codebase_dir: '.planning/codebase',
         existing_maps: existingMaps,
         has_maps: existingMaps.length > 0,
@@ -1770,7 +1777,7 @@ function buildAgentSkillsBlock(config, agentType, projectRoot, diagnostics) {
         if (entry.kind === 'directive') {
             return `- Load the \`${entry.name}\` skill via the Skill tool before proceeding (plugin-provided).`;
         }
-        return `- @${String(entry.ref).replace(/\\/g, '/')}`;
+        return `- @${(0, shell_command_projection_cjs_1.posixNormalize)(String(entry.ref))}`;
     }).join('\n');
     return `<agent_skills>\nRead these user-configured skills:\n${lines}\n</agent_skills>`;
 }

package/gsd-core/bin/lib/install-engine.cjs

@@ -27,6 +27,7 @@ const runtimeArtifactLayout = require("./runtime-artifact-layout.cjs");
 const runtimeArtifactInstallPlan = require("./runtime-artifact-install-plan.cjs");
 const runtimeNamePolicy = require("./runtime-name-policy.cjs");
 const installProfiles = require("./install-profiles.cjs");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const { processAttribution } = runtimeArtifactConversion;
 // resolveRuntimeArtifactLayout: accessed via module ref (not destructured) so
 // test stubs that monkeypatch the module's exports are seen at call time.
@@ -102,6 +103,17 @@ function convertClaudeCommandToOpencodeSkill(content, skillName) {
 function convertClaudeCommandToKiloSkill(content, skillName) {
     return runtimeArtifactConversion.convertClaudeCommandToKiloSkill(content, skillName);
 }
+/**
+ * Converter-name registry for the OpenCode-family combined skills installer
+ * (ADR-1239 / #2093). Maps the `converter` string declared on each runtime's
+ * artifactLayout skills-kind descriptor (capabilities/<runtime>/capability.json)
+ * to the actual conversion function, so `installOpencodeFamilySkills` dispatches
+ * off the descriptor instead of a `frontmatterDialect === 'kilo'` runtime check.
+ */
+const SKILLS_CONVERTER_REGISTRY = {
+    convertClaudeCommandToOpencodeSkill,
+    convertClaudeCommandToKiloSkill,
+};
 // ---------------------------------------------------------------------------
 // User-artifact preservation helpers
 // ---------------------------------------------------------------------------
@@ -302,9 +314,13 @@ function _copyStaged(stagedDir, destDir, kind, configDir, runtime) {
         let destName;
         if (kind.kind === 'agents') {
             // Agent files already carry the gsd- prefix in the source dir.
-            // #1575: copilot agents get .agent.md suffix (mirrors inline loop line ~9118).
-            destName = runtime === 'copilot'
-                ? entry.name.replace(/\.md$/, '.agent.md')
+            // #2099: descriptor-driven via hostBehaviors.agentFileExtension (was
+            // hardcoded `runtime === 'copilot'`). copilot declares '.agent.md';
+            // every other runtime's descriptor leaves this unset, so destName falls
+            // back to entry.name unchanged (byte-parity, #1575 origin comment).
+            const _agentExt = runtime ? _hostBehaviors(runtime).agentFileExtension : undefined;
+            destName = _agentExt
+                ? entry.name.replace(/\.md$/, _agentExt)
                 : entry.name;
         }
         else if (namespacedByDir) {
@@ -440,7 +456,7 @@ function _runLegacyInstallMigrations(runtime, configDir, scope = 'global') {
     // that for Hermes the flat skills/gsd-*/ removal (below) does not delete the freshly
     // created skills/gsd-dev-preferences/ skill dir.
     let savedLegacyArtifacts = null;
-    if (runtime === 'claude' || runtime === 'qwen' || runtime === 'hermes') {
+    if (_hostBehaviors(runtime).legacyCommandsGsdInstallMigration) {
         if (node_fs_1.default.existsSync(legacyCommandsGsd)) {
             savedLegacyArtifacts = preserveUserArtifacts(legacyCommandsGsd, ['dev-preferences.md']);
             node_fs_1.default.rmSync(legacyCommandsGsd, { recursive: true });
@@ -497,7 +513,8 @@ function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
     // commands/gsd/ for claude local, preserving dev-preferences.md by restoring it
     // to the same location (#1423). Using migrateLegacyDevPreferencesToSkill here
     // (which would redirect to skills/) conflicts with the test contract for local installs.
-    const isLegacyCommandsGsd = runtime === 'qwen' || runtime === 'hermes' || (runtime === 'claude' && scope === 'global');
+    const _lu = _hostBehaviors(runtime).legacyCommandsGsdUninstall;
+    const isLegacyCommandsGsd = _lu === true || (_lu === 'global' && scope === 'global');
     if (isLegacyCommandsGsd) {
         const legacyCommandsGsd = node_path_1.default.join(configDir, 'commands', 'gsd');
         if (node_fs_1.default.existsSync(legacyCommandsGsd)) {
@@ -651,6 +668,18 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
         const nestedGsdDirForCleanup = node_path_1.default.join(configDir, 'skills', 'gsd');
         _removeHermesBareStemDirs(nestedGsdDirForCleanup);
     }
+    // Generic-branch nativePlugin staging (ADR-1239 / #2102 Stage 1): runtimes
+    // outside the OpenCode/Kilo combined-family install (e.g. pi, whose
+    // artifactLayout is empty and which never sets combinedFamilyInstall) still
+    // need their declared hostBehaviors.nativePlugin file copied into configDir.
+    // findInstallSourceRoot resolves the repo/package root independent of
+    // configDir contents (marker check, then a walk-up from __dirname), so this
+    // is safe even when configDir has no .gsd-source marker (artifactLayout: []).
+    if (behaviors.nativePlugin) {
+        const commandsGsdDir = runtimeArtifactLayout.findInstallSourceRoot(configDir);
+        const src = node_path_1.default.dirname(node_path_1.default.dirname(commandsGsdDir));
+        _installNativePluginIfDeclared(runtime, configDir, behaviors, src);
+    }
 }
 // ---------------------------------------------------------------------------
 // installOpencodeFamilySkills
@@ -679,9 +708,16 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
     const rawDir = rawCommandsDir;
     if (!rawDir || !node_fs_1.default.existsSync(rawDir))
         return 0;
-    const converter = _hostBehaviors(runtime).frontmatterDialect === 'kilo'
-        ? convertClaudeCommandToKiloSkill
-        : convertClaudeCommandToOpencodeSkill;
+    // #2093: descriptor-driven — dispatch off the skills-kind entry's `converter`
+    // string (capabilities/<runtime>/capability.json artifactLayout) via the
+    // SKILLS_CONVERTER_REGISTRY, instead of a `frontmatterDialect === 'kilo'`
+    // runtime check. Fail loud if the descriptor names an unregistered converter
+    // (mirrors the converter=null throw in runtime-artifact-layout.cts).
+    const converterName = skillsKindEntry.converter;
+    const converter = converterName ? SKILLS_CONVERTER_REGISTRY[converterName] : undefined;
+    if (!converter) {
+        throw new TypeError(`installOpencodeFamilySkills: unknown skills converter '${String(converterName)}' for runtime '${runtime}'`);
+    }
     const dest = runtimeArtifactInstallPlan.assertDestWithinConfigHome(targetDir, skillsKindEntry.destSubpath);
     // Symlink-escape guard: reject if any path component between targetDir and
     // dest is a symlink that would redirect writes outside the config root.
@@ -769,6 +805,16 @@ function installOpencodeFamilyCommands(runtime, destDir, srcDir, pathPrefix, res
             let content = node_fs_1.default.readFileSync(srcPath, 'utf8');
             content = applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix);
             content = processAttribution(content, resolveAttribution(runtime));
+            // #2093: this commands-kind entry's descriptor `converter` field is
+            // intentionally `null` (see capabilities/{kilo,opencode}/capability.json —
+            // the flattened-command writer above applies its own path/attribution
+            // rewrites and has no per-file converter slot to key on), so there is no
+            // descriptor string to dispatch through here. `frontmatterDialect` is the
+            // documented, intentional dispatch key for frontmatter-shape selection —
+            // it is itself descriptor-driven (not a `runtime === 'kilo'` check), so it
+            // already satisfies the fold-to-descriptor requirement. Only the SKILLS
+            // converter site above (installOpencodeFamilySkills) has a real
+            // `converter` string to key on via SKILLS_CONVERTER_REGISTRY.
             content = _hostBehaviors(runtime).frontmatterDialect === 'kilo'
                 ? runtimeArtifactConversion.convertClaudeToKiloFrontmatter(content)
                 : runtimeArtifactConversion.convertClaudeToOpencodeFrontmatter(content);
@@ -777,12 +823,44 @@ function installOpencodeFamilyCommands(runtime, destDir, srcDir, pathPrefix, res
     }
 }
 // ---------------------------------------------------------------------------
+// _installNativePluginIfDeclared
+// ---------------------------------------------------------------------------
+/**
+ * Copy a runtime's declared native-extension/plugin file (hostBehaviors.nativePlugin)
+ * into its resolved config dir, when the runtime descriptor declares one.
+ *
+ * Extracted (ADR-1239 / #2102 Stage 1) from the body previously inlined in
+ * installOpencodeFamilyArtifacts so a runtime that is NOT part of the
+ * OpenCode/Kilo combined-family install (e.g. pi, whose artifactLayout is
+ * empty and which never sets combinedFamilyInstall) can still get its
+ * nativePlugin file staged via the generic installRuntimeArtifacts branch.
+ * Behavior for opencode/kilo is unchanged — same source resolution, same
+ * mkdir + copyFileSync call, same silent no-op when the source is missing.
+ *
+ * @param runtime  - canonical runtime id (only used for the assertDestWithinConfigHome guard)
+ * @param configDir - resolved runtime config directory
+ * @param behaviors - the runtime's hostBehaviors descriptor
+ * @param src       - repo/package root (two levels up from the commands/gsd source dir)
+ */
+function _installNativePluginIfDeclared(runtime, configDir, behaviors, src) {
+    const np = behaviors.nativePlugin;
+    if (np && np.source) {
+        const pluginSrc = node_path_1.default.join(src, np.source);
+        if (node_fs_1.default.existsSync(pluginSrc)) {
+            const destDir = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, np.dir);
+            node_fs_1.default.mkdirSync(destDir, { recursive: true });
+            node_fs_1.default.copyFileSync(pluginSrc, node_path_1.default.join(destDir, np.file));
+        }
+    }
+}
+// ---------------------------------------------------------------------------
 // installOpencodeFamilyArtifacts
 // ---------------------------------------------------------------------------
 /**
- * Combined-family install orchestrator for OpenCode/Kilo (ADR-1239 / #2087).
- * Stages the flattened commands surface + skills surface + (OpenCode only)
- * native plugin adapter, mirroring the bespoke `else if (isOpencode ||
+ * Combined-family install orchestrator for OpenCode/Kilo (ADR-1239 / #2087,
+ * #2093). Stages the flattened commands surface + skills surface + (any
+ * runtime whose hostBehaviors declares `nativePlugin` — OpenCode and, since
+ * #2093, Kilo) native plugin adapter, mirroring the bespoke `else if (isOpencode ||
  * isKilo)` block previously inlined in bin/install.js.
  *
  * @param runtime - 'opencode' or 'kilo'
@@ -806,21 +884,13 @@ function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfi
         isGlobal,
         isOpencode: behaviors.skipHomePrefixSubstitution === true,
         isWindowsHost: process.platform === 'win32',
-        resolvedTarget: node_path_1.default.resolve(configDir).replace(/\\/g, '/'),
-        homeDir: node_os_1.default.homedir().replace(/\\/g, '/'),
+        resolvedTarget: (0, shell_command_projection_cjs_1.posixNormalize)(node_path_1.default.resolve(configDir)),
+        homeDir: (0, shell_command_projection_cjs_1.posixNormalize)(node_os_1.default.homedir()),
     });
     const commandDir = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, 'command');
     installOpencodeFamilyCommands(runtime, commandDir, rawCommandsDir, pathPrefix, resolveAttribution);
     installOpencodeFamilySkills(runtime, configDir, rawCommandsDir, pathPrefix, resolveAttribution);
-    const np = behaviors.nativePlugin;
-    if (np && np.source) {
-        const pluginSrc = node_path_1.default.join(src, np.source);
-        if (node_fs_1.default.existsSync(pluginSrc)) {
-            const destDir = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, np.dir);
-            node_fs_1.default.mkdirSync(destDir, { recursive: true });
-            node_fs_1.default.copyFileSync(pluginSrc, node_path_1.default.join(destDir, np.file));
-        }
-    }
+    _installNativePluginIfDeclared(runtime, configDir, behaviors, src);
 }
 // ---------------------------------------------------------------------------
 // uninstallRuntimeArtifacts
@@ -879,6 +949,7 @@ module.exports = {
     installOpencodeFamilySkills,
     installOpencodeFamilyCommands,
     installOpencodeFamilyArtifacts,
+    _installNativePluginIfDeclared,
     _hostBehaviors,
     _copyStaged,
     hasExistingSymlinkBetween,

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

@@ -14,6 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateInstallerMigrationRecord = validateInstallerMigrationRecord;
 exports.validateInstallerMigrationActions = validateInstallerMigrationActions;
 const node_path_1 = __importDefault(require("node:path"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 function getStr(record, field) {
     const v = record[field];
     return typeof v === 'string' ? v : '';
@@ -56,7 +57,7 @@ function requireActionEvidence(action, field, migration) {
 }
 function validateSafeRelPath(relPath, migration, actionType) {
     const source = actionSource(migration, { relPath });
-    const normalized = relPath.replace(/\\/g, '/');
+    const normalized = (0, shell_command_projection_cjs_1.posixNormalize)(relPath);
     if (node_path_1.default.isAbsolute(normalized) || node_path_1.default.win32.isAbsolute(normalized)) {
         throw new Error(`migration action ${actionType} relPath must stay inside configDir: ${source}`);
     }

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

@@ -42,6 +42,9 @@ exports.BUNDLED_GSD_HOOK_FILES = Object.freeze(new Set([
     'hooks/gsd-cursor-stop.js',
     'hooks/gsd-cursor-subagent-start.js',
     'hooks/gsd-cursor-subagent-stop.js',
+    // Windsurf/Cascade blocking hooks — registered by writeWindsurfHooksJson (#2100).
+    'hooks/gsd-windsurf-pre-write.js',
+    'hooks/gsd-windsurf-pre-command.js',
     'hooks/gsd-ensure-canonical-path.js',
     'hooks/gsd-graphify-update.sh',
     'hooks/gsd-phase-boundary.sh',

package/gsd-core/bin/lib/installer-migrations.cjs

@@ -118,7 +118,7 @@ function normalizeRelPath(relPath) {
     if (typeof relPath !== 'string' || relPath.trim() === '') {
         throw new Error('migration action relPath must be a non-empty string');
     }
-    const normalized = relPath.replace(/\\/g, '/');
+    const normalized = (0, shell_command_projection_cjs_1.posixNormalize)(relPath);
     if (node_path_1.default.isAbsolute(normalized) || node_path_1.default.win32.isAbsolute(normalized)) {
         throw new Error(`migration action relPath must stay inside configDir: ${relPath}`);
     }