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

package/gsd-core/bin/lib/capability-validator.cjs

@@ -697,26 +697,35 @@ const VALID_CONVERTER_NAMES = new Set([
   'convertClaudeAgentToCodebuddyAgent',
   'convertClaudeAgentToClineAgent',
   'convertClaudeAgentToCodexAgent',
+  // ADR-1239 / #2092 Phase B Upgrade 1 — native .qwen/agents/*.md subagent projection.
+  'convertClaudeAgentToQwenAgent',
 ]);
 
 // C3: Validate role:runtime body
 const VALID_CONFIG_FORMATS = new Set(['settings-json', 'toml', 'markdown', 'markdown-dir', 'none']);
-const VALID_CONFIG_HOME_KINDS = new Set(['dot-home', 'dot-home-nested', 'xdg', 'generic-agents-root']);
+// 'none' added #2103 — Marketplace/VSIX-distributed hosts (e.g. VS Code) with
+// no file-projected config directory at all.
+const VALID_CONFIG_HOME_KINDS = new Set(['dot-home', 'dot-home-nested', 'xdg', 'generic-agents-root', 'none']);
 const VALID_COMMAND_STYLES = new Set(['slash-hyphen', 'shell-var']);
-const VALID_HOOKS_SURFACES = new Set(['settings-json', 'codex-hooks-json', 'cursor-hooks-json', 'copilot-inline', 'cline-rules', 'none']);
+const VALID_HOOKS_SURFACES = new Set(['settings-json', 'codex-hooks-json', 'cursor-hooks-json', 'copilot-inline', 'cline-rules', 'kimi-hooks-toml', 'windsurf-hooks-json', 'none']);
 const VALID_HOOK_EVENTS = new Set(['claude', 'gemini']);
 // extensionEvents — the plugin/extension-system event dialect (ADR-1239 amendment / #1943).
 // DISTINCT from hookEvents (managed-hook dialect): extensionEvents describes the
 // plugin-owned event subset imperative hosts expose (opencode / pi); 'none' = the
 // host exposes no extension surface (engine owns the bus, e.g. VS Code).
-const VALID_EXTENSION_EVENTS = new Set(['opencode', 'pi', 'hermes', 'none']);
+const VALID_EXTENSION_EVENTS = new Set(['opencode', 'pi', 'hermes', 'kilo', 'none']);
 const VALID_SANDBOX_TIERS = new Set(['none', 'codex-agent-sandbox']);
 const VALID_ARTIFACT_KIND_NAMES = new Set(['commands', 'agents', 'skills', 'kimi-agents']);
 const VALID_ARTIFACT_NESTINGS = new Set(['flat', 'nested']);
 const FEATURE_FIELDS_FORBIDDEN_ON_RUNTIME = ['skills', 'agents', 'steps', 'contributions', 'gates', 'hooks', 'activationKey'];
-const VALID_INSTALL_SURFACES = new Set(['settings-json', 'codex-toml', 'copilot-instructions', 'cline-rules', 'cursor-hooks-json', 'profile-marker-only']);
-const VALID_PERMISSION_WRITERS = new Set(['opencode', 'kilo']);
-const VALID_EXTENDED_HOOK_EVENTS = new Set(['SubagentStop', 'Stop', 'PreCompact', 'FileChanged', 'BeforeAgent', 'AfterAgent', 'BeforeModel']);
+// 'none' added #2103 — Marketplace/VSIX-distributed hosts (e.g. VS Code) that
+// are never CLI-installed (no allRuntimes membership, no install flag).
+const VALID_INSTALL_SURFACES = new Set(['settings-json', 'codex-toml', 'copilot-instructions', 'cline-rules', 'cursor-hooks-json', 'profile-marker-only', 'none']);
+// 'antigravity' added #2096 Phase B Upgrade 1 — settings.json permissions.allow writer.
+const VALID_PERMISSION_WRITERS = new Set(['opencode', 'kilo', 'antigravity']);
+// SubagentStart added #2092 Phase B Upgrade 2 (qwen-only today — see
+// capabilities/qwen/capability.json's extendedHookEvents).
+const VALID_EXTENDED_HOOK_EVENTS = new Set(['SubagentStop', 'Stop', 'PreCompact', 'FileChanged', 'BeforeAgent', 'AfterAgent', 'BeforeModel', 'SubagentStart']);
 
 // ADR-1239 Phase A: hostIntegration axes (MUST stay parity-identical to HOST_INTEGRATION_AXES in src/host-integration.cts)
 const VALID_EMBEDDING_MODES   = new Set(['imperative', 'declarative']);
@@ -736,13 +745,18 @@ const INSTALL_SURFACE_TO_ALLOWED_HOOKS_SURFACES = new Map([
   ['copilot-instructions', new Set(['copilot-inline'])],
   ['cline-rules',          new Set(['cline-rules'])],
   ['cursor-hooks-json',    new Set(['cursor-hooks-json'])],
-  ['profile-marker-only',  new Set(['none'])],
+  ['profile-marker-only',  new Set(['none', 'kimi-hooks-toml', 'windsurf-hooks-json'])],
+  // 'none' added #2103 — VS Code has no CLI install surface at all; its only
+  // valid hooksSurface pairing is the other 'none' (engine owns the hook bus).
+  ['none',                 new Set(['none'])],
 ]);
 
 // GATE B: extended hook event families → required hookEvents value
 // Gemini agent-events require hookEvents='gemini'; Claude-family events require hookEvents='claude'.
 const GEMINI_AGENT_EVENTS = new Set(['BeforeAgent', 'AfterAgent', 'BeforeModel']);
-const CLAUDE_FAMILY_EVENTS = new Set(['SubagentStop', 'Stop', 'PreCompact', 'FileChanged']);
+// SubagentStart added #2092 Phase B Upgrade 2 — Claude hook-event dialect
+// counterpart of SubagentStop (qwen-only today).
+const CLAUDE_FAMILY_EVENTS = new Set(['SubagentStop', 'Stop', 'PreCompact', 'FileChanged', 'SubagentStart']);
 
 /**
  * Validate a runtime.configHome object per ADR-1016 Decision 1.
@@ -771,9 +785,18 @@ function validateConfigHome(capId, ch) {
     );
   }
 
-  // name — required string
-  if (typeof ch.name !== 'string' || ch.name.length === 0) {
-    errors.push(ctx + '.name must be a non-empty string');
+  // name — required string, except when kind === 'none': the runtime has no
+  // file-projected config directory at all, so a descriptive name is
+  // optional (a carve-out mirroring the dot-home-nested⇒parent conditional
+  // below, not a new validation mechanism). If present it must still be a
+  // non-empty string (e.g. vscode's configHome.name stays a descriptive
+  // "vscode" string even though it is never used to build a path).
+  if (ch.kind !== 'none') {
+    if (typeof ch.name !== 'string' || ch.name.length === 0) {
+      errors.push(ctx + '.name must be a non-empty string');
+    }
+  } else if (ch.name !== undefined && (typeof ch.name !== 'string' || ch.name.length === 0)) {
+    errors.push(ctx + '.name must be a non-empty string if present when kind is "none"');
   }
 
   // parent — required when kind == dot-home-nested
@@ -973,7 +996,7 @@ function validateRuntimeBody(cap) {
     );
   }
 
-  // hooksSurface — closed 6-enum (ADR-1016 Decision 5); inline literal guard (CodeQL barrier)
+  // hooksSurface — closed 7-enum (ADR-1016 Decision 5); inline literal guard (CodeQL barrier)
   if (r.hooksSurface === '__proto__' || r.hooksSurface === 'constructor' || r.hooksSurface === 'prototype') {
     errors.push('runtime.hooksSurface "' + r.hooksSurface + '" is a reserved name');
   } else if (!VALID_HOOKS_SURFACES.has(r.hooksSurface)) {
@@ -1054,15 +1077,27 @@ function validateRuntimeBody(cap) {
   // localConfigDir — REQUIRED non-empty dot-dir string (ADR-1239 Phase B #1679)
   // Must start with '.' (e.g. ".claude", ".cursor"). Validated here so the registry
   // generator catches any descriptor missing the field before regenerating.
-  if (typeof r.localConfigDir !== 'string' || r.localConfigDir.length === 0) {
+  //
+  // #2103: conditional on configHome.kind !== 'none' — a Marketplace/VSIX
+  // host with no file-projected config directory (e.g. VS Code) has no
+  // local dir to name; localConfigDir may be null/absent for such runtimes.
+  const configHomeKind = (r.configHome && typeof r.configHome === 'object') ? r.configHome.kind : undefined;
+  if (configHomeKind !== 'none') {
+    if (typeof r.localConfigDir !== 'string' || r.localConfigDir.length === 0) {
+      errors.push(
+        'runtime.localConfigDir is required and must be a non-empty string (e.g. ".claude"); ' +
+        'got: ' + JSON.stringify(r.localConfigDir),
+      );
+    } else if (!r.localConfigDir.startsWith('.')) {
+      errors.push(
+        'runtime.localConfigDir must start with "." (a dot-dir); got: ' + JSON.stringify(r.localConfigDir),
+      );
+    }
+  } else if (r.localConfigDir !== null && r.localConfigDir !== undefined) {
     errors.push(
-      'runtime.localConfigDir is required and must be a non-empty string (e.g. ".claude"); ' +
+      'runtime.localConfigDir must be null or absent when configHome.kind is "none"; ' +
       'got: ' + JSON.stringify(r.localConfigDir),
     );
-  } else if (!r.localConfigDir.startsWith('.')) {
-    errors.push(
-      'runtime.localConfigDir must start with "." (a dot-dir); got: ' + JSON.stringify(r.localConfigDir),
-    );
   }
 
   // extendedHookEvents — required array; every element must be in closed enum
@@ -2168,6 +2203,9 @@ const INSTALL_SURFACE_TO_CONFIG_FORMAT = new Map([
   ['cline-rules',          'markdown-dir'],
   ['cursor-hooks-json',    'none'],
   ['profile-marker-only',  'none'],
+  // 'none' added #2103 — a runtime with NO CLI install surface at all (e.g.
+  // VS Code) has no config-file format to write either.
+  ['none',                 'none'],
 ]);
 
 /**

package/gsd-core/bin/lib/host-integration.cjs

@@ -430,14 +430,25 @@ function hookEventSurfaceFor(hookEvents) {
 // events (session/tool/file/permission); pi ~30 fine-grained extension events;
 // 'none' = the host exposes no extension surface and the engine owns the bus
 // (VS Code). Declarative hosts (no plugin API) do not set `extensionEvents`.
+// OpenCode's plugin event surface (ADR-1239 §research; ~25 documented events,
+// GSD binds this subset). Hoisted to a named const — rather than duplicated
+// object literals — so the `kilo` dialect below (#2093) can reuse the IDENTICAL
+// array instead of a copy-pasted one that could silently drift out of sync.
+const OPENCODE_EXTENSION_EVENTS = Object.freeze([
+    'session.created', 'session.idle', 'experimental.session.compacting',
+    'tool.execute.before', 'tool.execute.after', 'file.edited',
+    // #2087 — additional documented plugin events GSD binds (opencode.ai/docs/plugins):
+    // permission decisions + session error surface.
+    'permission.asked', 'permission.replied', 'session.error',
+]);
 const EXTENSION_EVENT_SURFACES = Object.freeze({
-    opencode: Object.freeze([
-        'session.created', 'session.idle', 'experimental.session.compacting',
-        'tool.execute.before', 'tool.execute.after', 'file.edited',
-        // #2087 — additional documented plugin events GSD binds (opencode.ai/docs/plugins):
-        // permission decisions + session error surface.
-        'permission.asked', 'permission.replied', 'session.error',
-    ]),
+    opencode: OPENCODE_EXTENSION_EVENTS,
+    // #2093 — Kilo Code is an OpenCode fork sharing the same plugin/extension
+    // event bus (host hook bus, UPGRADE 1): reuses OPENCODE_EXTENSION_EVENTS
+    // verbatim (not a re-derivation), so the two dialects stay pinned together
+    // by construction. See .kilo/plugins/gsd-core.js (copied verbatim from
+    // .opencode/plugins/gsd-core.js).
+    kilo: OPENCODE_EXTENSION_EVENTS,
     // #2091 — Hermes Agent real plugin hook vocabulary (13 events).
     // Cite: https://github.com/nousresearch/hermes-agent/blob/main/website/docs/user-guide/features/hooks.md
     // Replaces the borrowed `hookEvents: "claude"` 6-event surface that silently
@@ -451,7 +462,21 @@ const EXTENSION_EVENT_SURFACES = Object.freeze({
         'pre_gateway_dispatch', 'pre_approval_request',
         'transform_tool_result',
     ]),
-    pi: Object.freeze(['tool_call']),
+    // #2102 Stage 2 — pi's real ExtensionAPI event vocabulary (~30 fine-grained
+    // extension events; documentation-sourced, ADR-1239 §research). Replaces the
+    // placeholder single-event ['tool_call'] surface — the Stage 1 value only
+    // covered the one event pi/gsd.cjs happened to bind at the time, not the
+    // full declared surface.
+    pi: Object.freeze([
+        'session_start', 'project_trust', 'resources_discover', 'input',
+        'before_agent_start', 'agent_start', 'message_start', 'message_update',
+        'message_end', 'turn_start', 'context', 'before_provider_request',
+        'after_provider_response', 'tool_execution_start', 'tool_execution_update',
+        'tool_execution_end', 'tool_call', 'tool_result', 'turn_end', 'agent_end',
+        'session_before_switch', 'session_shutdown', 'session_before_fork',
+        'session_info_changed', 'session_before_compact', 'session_compact',
+        'session_before_tree', 'session_tree', 'thinking_level_select', 'model_select',
+    ]),
     none: Object.freeze([]),
 });
 /**

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

@@ -63,7 +63,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 +74,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 +88,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'];
 }
@@ -258,9 +260,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 +363,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;
     }
@@ -679,15 +672,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 +729,9 @@ 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);
     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 +752,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 = {

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

@@ -102,6 +102,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 +313,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 +455,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 +512,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 +667,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 +707,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 +804,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 +822,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'
@@ -812,15 +889,7 @@ function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfi
     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 +948,7 @@ module.exports = {
     installOpencodeFamilySkills,
     installOpencodeFamilyCommands,
     installOpencodeFamilyArtifacts,
+    _installNativePluginIfDeclared,
     _hostBehaviors,
     _copyStaged,
     hasExistingSymlinkBetween,

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/mcp-server.cjs

@@ -5,8 +5,16 @@
  * so any MCP-consuming host (Claude/Codex/OpenCode/VS Code/Gemini/Cursor/Cline/
  * Hermes) can drive GSD with NO bespoke plugin:
  *
- *   - point 1 (command): tool `gsd_invoke_command` → the command-routing hub
- *     (`createHub`/`dispatch`, src/command-routing-hub.cts).
+ *   - point 1 (command): tool `gsd_invoke_command` → `dispatchGsdCommand`
+ *     (src/shell-command-projection.cts), a bounded subprocess-shim to
+ *     gsd-tools.cjs. #2102 Stage 2: `commandRoutingHub.createHub()` called
+ *     with no args here always hit `if(!_cjsRegistry) return
+ *     makeUnknownCommand()` — every dispatch was UnknownCommand. No
+ *     fully-populated hub factory exists anywhere in gsd-core (every
+ *     createHub() caller builds a single-family hub for its own narrow
+ *     purpose), so the fix routes through the SAME shared dispatch helper
+ *     the pi extension uses (pi/gsd.cjs), mirroring the SUBPROCESS-REUSE
+ *     precedent already established for the OpenCode/Kilo hook bridge.
  *   - point 5 (state IO): tools `gsd_read_state` / `gsd_write_state` → the
  *     Phase 3 `stateIO` seam (src/state-io.cts, filesystem default).
  *
@@ -24,9 +32,10 @@ exports.SERVER_NAME = exports.PROTOCOL_VERSION = void 0;
 exports.handleMessage = handleMessage;
 exports.runServer = runServer;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
-const commandRoutingHub = require("./command-routing-hub.cjs");
-// eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateIo = require("./state-io.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const shellCommandProjection = require("./shell-command-projection.cjs");
+const { dispatchGsdCommand } = shellCommandProjection;
 exports.PROTOCOL_VERSION = '2024-11-05';
 exports.SERVER_NAME = 'gsd-core';
 const SERVER_VERSION = '1.7.0';
@@ -94,9 +103,11 @@ function callTool(name, args, ctx) {
             if (!family || !subcommand) {
                 return { isError: true, content: [{ type: 'text', text: 'gsd_invoke_command requires string "family" and "subcommand".' }] };
             }
-            const hub = commandRoutingHub.createHub();
-            const res = hub.dispatch({ family, subcommand, args: Array.isArray(a.args) ? a.args : [], cwd, raw: undefined });
-            return { content: [{ type: 'text', text: JSON.stringify(res) }] };
+            const res = dispatchGsdCommand({ family, subcommand, args: Array.isArray(a.args) ? a.args : [], cwd });
+            if (!res.ok) {
+                return { isError: true, content: [{ type: 'text', text: res.stderr || res.stdout || `dispatch failed (exit ${res.code})` }] };
+            }
+            return { content: [{ type: 'text', text: res.stdout }] };
         }
         if (name === 'gsd_read_state') {
             const p = asString(a.path);

package/gsd-core/bin/lib/review-reviewer-selection.cjs

@@ -15,25 +15,42 @@
  * per-instance CLI flags). An instance is available iff its base `cli` is
  * detected. The instance→cli mapping lives HERE (single source; see the parity
  * test in tests/review-reviewer-instances.test.cjs — DEFECT.GENERATIVE-FIX).
+ *
+ * KNOWN_REVIEWER_SLUGS (post-review #2092): registry-derived, not a flat
+ * hand-maintained array. Each capability-runtime descriptor that is a valid
+ * reviewer CLI declares `runtime.hostBehaviors.reviewerCli: true`
+ * (capabilities/<id>/capability.json); this module reads that flag off the
+ * generated capability-registry.cjs at require-time. A handful of reviewer
+ * CLIs are NOT install-time runtimes at all (no capabilities/<id>/ descriptor
+ * exists) — those stay a small hardcoded tail:
+ *   - `gemini` — hook-event dialect name only (see runtime-hooks-surface.cts);
+ *     the Gemini CLI reviewer is not an installable runtime (#1928 folded
+ *     gemini into antigravity's descriptor).
+ *   - `coderabbit` / `ollama` / `lm_studio` / `llama_cpp` — third-party
+ *     review/model CLIs with no GSD install surface at all.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.INSTANCE_NAME_PATTERN = exports.KNOWN_REVIEWER_SLUGS = void 0;
 exports.normalizeConfiguredDefaultReviewers = normalizeConfiguredDefaultReviewers;
 exports.normalizeReviewerInstances = normalizeReviewerInstances;
 exports.resolveReviewerSelection = resolveReviewerSelection;
-exports.KNOWN_REVIEWER_SLUGS = [
+const NON_RUNTIME_REVIEWER_SLUGS = [
     'gemini',
-    'claude',
-    'codex',
     'coderabbit',
-    'opencode',
-    'qwen',
-    'cursor',
-    'antigravity',
     'ollama',
     'lm_studio',
     'llama_cpp',
 ];
+function deriveRuntimeReviewerSlugs() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const registry = require('./capability-registry.cjs');
+    const runtimes = registry.runtimes || {};
+    return Object.keys(runtimes).filter((id) => runtimes[id]?.runtime?.hostBehaviors?.reviewerCli === true);
+}
+exports.KNOWN_REVIEWER_SLUGS = [
+    ...deriveRuntimeReviewerSlugs(),
+    ...NON_RUNTIME_REVIEWER_SLUGS,
+];
 /** Instance names are lowercase slugs that must not shadow a built-in slug. */
 exports.INSTANCE_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 function normalizeConfiguredDefaultReviewers(rawValue) {