@opengsd/gsd-core 1.5.0-rc.5 → 1.6.0-rc.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gsd-core",
   "displayName": "GSD Core",
-  "version": "1.5.0-rc.5",
+  "version": "1.6.0-rc.1",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "open-gsd",

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Lex Christopherson
+Copyright (c) 2026 Open GSD
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/agents/gsd-executor.md

@@ -103,6 +103,24 @@ PLAN_START_EPOCH=$(date +%s)
 ```
 </step>
 
+<worktree_metadata_capture>
+If running inside a git worktree, capture authoritative worktree identity before
+any task commit changes HEAD. The execute-phase orchestrator consumes this from
+your final `<worktree_metadata>` return block to build the wave cleanup manifest
+without relying on runtime harness metadata (#1297).
+
+```bash
+GSD_WORKTREE_PATH=""
+GSD_WORKTREE_BRANCH=""
+GSD_WORKTREE_EXPECTED_BASE=""
+if [ -f .git ]; then
+  GSD_WORKTREE_PATH=$(git rev-parse --show-toplevel)
+  GSD_WORKTREE_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+  GSD_WORKTREE_EXPECTED_BASE=$(git rev-parse HEAD)
+fi
+```
+</worktree_metadata_capture>
+
 <step name="determine_execution_pattern">
 ```bash
 grep -n "type=\"checkpoint" [plan-path]
@@ -761,6 +779,10 @@ into the user's project history.
 **Tasks:** {completed}/{total}
 **SUMMARY:** {path to SUMMARY.md}
 
+<worktree_metadata>
+{"agent_id":"{phase}-{plan}","worktree_path":"${GSD_WORKTREE_PATH:-}","branch":"${GSD_WORKTREE_BRANCH:-}","expected_base":"${GSD_WORKTREE_EXPECTED_BASE:-}"}
+</worktree_metadata>
+
 **Commits:**
 - {hash}: {message}
 - {hash}: {message}

package/agents/gsd-plan-checker.md

@@ -647,6 +647,40 @@ issue:
   fix_hint: "Add auth middleware pattern from PATTERNS.md ## Shared Patterns to plan"
 ```
 
+## Dimension: Verify Command Format Sanity (#1478, #1479)
+
+**Question:** Do `<verify>` commands use patterns that can actually match the tool's output? Are numeric counts measured? Are errors suppressed into comparison-feeding defaults?
+
+**Red flags — BLOCKER:**
+- `pnpm ls … | grep -E '^package'` — `^` anchor on tree-formatted package manager output (never matches tree-prefixed lines)
+- Any verify block with `VAR=$(cmd 2>/dev/null || echo "0"); [ "$VAR" = ... ]` — swallowed error feeds passing comparison
+- `|| true` or `|| :` as right-hand side of assignments that feed comparisons
+
+**Red flags — WARNING:**
+- Hard-coded count assertion (`grep '52 test files'`, `grep '714 passed'`) with no measurement provenance in the plan
+
+**Process:**
+1. For each `<automated>` block piping a package-manager list command into grep with a `^` anchor: BLOCKER.
+2. For each `<automated>` block containing `2>/dev/null || echo` where the result feeds a `[ "$VAR" = ... ]` comparison: BLOCKER.
+3. For each `<automated>` block asserting a specific numeric count not cited as measured in this plan: WARNING.
+
+## Dimension: Numeric/Factual Claim Authority (#1480)
+
+**Rule:** RESEARCH.md is produced at research time and may be stale. Numeric claims (test counts, file counts, version numbers) and factual state claims ("feature X is implemented") in RESEARCH.md may not reflect the current codebase. The plan may be more current. RESEARCH.md is authoritative for architectural decisions and constraints — not for measurements.
+
+**Process when a plan's numeric/factual claim conflicts with RESEARCH.md:**
+
+1. **Attempt live measurement first** with a targeted read-only command (e.g., `find . -name '*.test.*' | wc -l`). Run it. Use the result as ground truth:
+   - Measurement confirms plan → WARNING: RESEARCH.md is stale; recommend updating it.
+   - Measurement contradicts plan → BLOCKER: plan value is wrong; prescribe the measured value.
+
+2. **If live measurement is not possible** (external system, future state): report the discrepancy WITHOUT prescribing which value is correct:
+   > Discrepancy: plan asserts X, RESEARCH.md asserts Y. Cannot determine ground truth without live measurement. Verify manually and update the stale artifact.
+
+**NEVER** prescribe a specific value by assuming RESEARCH.md is authoritative for a numeric/factual claim.
+
+**Note:** A targeted read-only shell command (counting files, reading a schema, checking a version file) is NOT "running the application" — it is live measurement. Such commands are permitted under this dimension even when the anti-pattern block says "DO NOT run the application."
+
 </verification_dimensions>
 
 <verification_process>

package/agents/gsd-planner.md

@@ -200,6 +200,8 @@ Full rules + worked examples: @gsd-core/references/planner-antipatterns.md ("Com
 
 <region_scoped_negative_gate>
 **Region-scoped negative gates (WARN, #968):** Region-scope a file-wide negative grep when a sibling task needs that construct elsewhere in the same file; `validate_plan` WARNS. See: @gsd-core/references/planner-antipatterns.md ("Region-Scoped Negative Gates").
+
+**Verify-gate hygiene (#1478/#1479):** See @gsd-core/references/planner-antipatterns.md.
 </region_scoped_negative_gate>
 
 **<done>:** Acceptance criteria - measurable state of completion.

package/bin/install.js

@@ -1796,6 +1796,10 @@ function skillFrontmatterName(skillDirName) {
   return skillDirName;
 }
 
+function normalizeClaudeSkillEffort(effort) {
+  return effort === 'xhigh' ? 'max' : effort;
+}
+
 /**
  * Qwen Code skills accept an optional numeric `priority` frontmatter field.
  * Per the Qwen skills spec (qwen-code/docs/users/features/skills.md, verified
@@ -1892,7 +1896,7 @@ function convertClaudeCommandToClaudeSkill(content, skillName, runtime = null, c
   // token-budget tier). Fields are Claude-specific; unknown frontmatter
   // fields are silently ignored by other runtimes (backward-compatible).
   if (context) fm += `context: ${context}\n`;
-  if (effort) fm += `effort: ${effort}\n`;
+  if (effort) fm += `effort: ${normalizeClaudeSkillEffort(effort)}\n`;
   if (toolsBlock) fm += toolsBlock;
   fm += '---';
 
@@ -3194,110 +3198,55 @@ function generateCodexAgentToml(agentName, agentContent, modelOverrides = null,
 }
 
 /**
- * Generate the agents/openai.yaml TUI chip metadata content for a Codex skill.
+ * Remove stale agents/openai.yaml sidecar files from GSD-managed Codex skill dirs.
  *
- * This file is written alongside SKILL.md as <skill-dir>/agents/openai.yaml.
- * Codex loads it as a SkillMetadataFile (codex-rs/core-skills/src/loader.rs),
- * making the skill discoverable in the /skills TUI popup with a display name
- * and short description. If the file is absent, Codex silently skips it (fails open).
+ * Prior to #1326, GSD's Codex install path wrote an agents/openai.yaml file
+ * alongside each gsd-* SKILL.md. Recent Codex builds index BOTH SKILL.md and
+ * the sidecar, causing each GSD skill to appear twice in autocomplete. This
+ * function removes those stale sidecars and — if the agents/ subdirectory is
+ * now empty — prunes it too.
  *
- * Schema (interface section):
- *   display_name: short human-readable skill name (strip gsd- prefix)
- *   short_description: 1-2 sentence description for TUI chip, ≤180 chars
- *
- * @param {string} skillName - Full skill name e.g. "gsd-plan-phase"
- * @param {string} shortDescription - Description text (already truncated by caller)
- * @returns {string} YAML content for agents/openai.yaml
- */
-function generateCodexSkillMetadataYaml(skillName, shortDescription) {
-  // Display name: strip "gsd-" prefix and convert hyphens to spaces for readability.
-  const displayName = skillName.replace(/^gsd-/, '').replace(/-/g, ' ');
-  // yamlQuote (= JSON.stringify) handles all YAML-unsafe chars: backslashes,
-  // quotes, newlines, control characters, and Unicode escapes.
-  return [
-    'interface:',
-    `  display_name: ${yamlQuote(displayName)}`,
-    `  short_description: ${yamlQuote(shortDescription)}`,
-    '',
-  ].join('\n');
-}
-
-/**
- * Write agents/openai.yaml TUI chip metadata for each gsd-* skill directory.
- *
- * Called after layout-driven skill install for Codex. Iterates every gsd-*
- * skill directory in skillsDir, reads the SKILL.md frontmatter to extract the
- * short-description already emitted by convertClaudeCommandToCodexSkill, then
- * writes <skill-dir>/agents/openai.yaml using generateCodexSkillMetadataYaml.
- *
- * Fails open: individual skill directories that cannot be processed are silently
- * skipped so a single malformed SKILL.md cannot block the whole install.
- *
- * User-owned skill directories (e.g. gsd-dev-preferences) are explicitly
- * skipped so existing user-authored agents/openai.yaml files are never
- * overwritten. These dirs are listed in the same USER_OWNED_SKILL_DIRS
- * constant used by installOpencodeFamilySkills.
- *
- * The YAML-quoted description value is unescaped before embedding so that
- * YAML escape sequences (e.g. \" in a double-quoted scalar) become the
- * literal characters they represent rather than being double-escaped in the
- * output.
+ * Behaviour:
+ *   - Returns immediately if skillsDir does not exist (fails open).
+ *   - Only touches directories whose names start with "gsd-".
+ *   - Skips user-owned dirs (gsd-dev-preferences) — their agents/ content is
+ *     never modified, mirroring the same USER_OWNED_SKILL_DIRS guard used by
+ *     installOpencodeFamilySkills.
+ *   - For each managed gsd-* dir, if agents/openai.yaml exists, deletes it.
+ *   - If agents/ is now empty, removes the directory; if it still contains
+ *     other files (e.g. user-added content), leaves it in place.
+ *   - Non-gsd-* dirs and their agents/ content are never touched.
+ *   - Individual failures are caught and swallowed so a single bad dir cannot
+ *     block the install (fail-open, matching the original design).
  *
  * @param {string} skillsDir - Path to the skills/ directory (e.g. ~/.codex/skills)
  */
-function writeCodexSkillMetadataFiles(skillsDir) {
+function cleanupCodexSkillMetadataSidecars(skillsDir) {
   if (!fs.existsSync(skillsDir)) return;
   // Mirror the user-owned list from installOpencodeFamilySkills (#2973).
   // We MUST skip these dirs — their contents are user-generated and must
-  // never be overwritten by GSD's install path.
+  // never be modified by GSD's install path.
   const _userOwnedSkillDirs = new Set(['gsd-dev-preferences']);
   for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
     if (!entry.isDirectory() || !entry.name.startsWith('gsd-')) continue;
     if (_userOwnedSkillDirs.has(entry.name)) continue; // preserve user content
-    const skillDir = path.join(skillsDir, entry.name);
-    const skillMdPath = path.join(skillDir, 'SKILL.md');
+    const agentsSubdir = path.join(skillsDir, entry.name, 'agents');
+    const sidecarPath = path.join(agentsSubdir, 'openai.yaml');
     try {
-      const content = fs.readFileSync(skillMdPath, 'utf8');
-      const { frontmatter } = extractFrontmatterAndBody(content);
-      // Prefer the short-description field emitted by convertClaudeCommandToCodexSkill;
-      // fall back to description, then a synthetic label from the skill name.
-      let shortDesc = '';
-      if (frontmatter) {
-        // SKILL.md uses YAML frontmatter with a nested metadata.short-description key.
-        // extractFrontmatterField handles only top-level keys; parse the metadata block
-        // by looking for "  short-description:" directly.
-        const metaMatch = frontmatter.match(/^[ \t]*metadata\s*:\s*\n((?:[ \t]+.*\n?)*)/m);
-        if (metaMatch) {
-          const metaBlock = metaMatch[1];
-          const sdMatch = metaBlock.match(/^[ \t]+short-description\s*:\s*(.+)$/m);
-          if (sdMatch) {
-            // Unescape YAML double-quoted scalar escapes before embedding.
-            // convertClaudeCommandToCodexSkill always emits a double-quoted
-            // value (via yamlQuote) so only double-quote unescaping is needed.
-            let raw = sdMatch[1].trim();
-            if (raw.startsWith('"') && raw.endsWith('"')) {
-              // Strip outer double-quotes and decode \" → " and \\ → \
-              raw = raw.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
-            } else {
-              // Single-quoted or unquoted: strip surrounding quotes/whitespace
-              raw = raw.replace(/^["']|["']$/g, '');
-            }
-            shortDesc = raw;
-          }
-        }
-        if (!shortDesc) {
-          shortDesc = extractFrontmatterField(frontmatter, 'description') || '';
-        }
-      }
-      if (!shortDesc) {
-        shortDesc = `Run GSD workflow ${entry.name}.`;
+      // Symlink guard: if agents/ is a symlink pointing outside the skills tree,
+      // deleting through it could escape the tree. Skip this dir entirely.
+      let agentsStat;
+      try { agentsStat = fs.lstatSync(agentsSubdir); } catch (_e) { continue; }
+      if (agentsStat.isSymbolicLink()) continue;
+      if (fs.existsSync(sidecarPath)) {
+        fs.rmSync(sidecarPath);
+      }
+      // Prune the agents/ dir only if it is now empty (leave it if other files remain).
+      if (fs.existsSync(agentsSubdir) && fs.readdirSync(agentsSubdir).length === 0) {
+        fs.rmdirSync(agentsSubdir);
       }
-      const yamlContent = generateCodexSkillMetadataYaml(entry.name, shortDesc);
-      const agentsSubdir = path.join(skillDir, 'agents');
-      fs.mkdirSync(agentsSubdir, { recursive: true });
-      fs.writeFileSync(path.join(agentsSubdir, 'openai.yaml'), yamlContent);
     } catch (_err) {
-      // Fail open — missing or unreadable SKILL.md must not block the install.
+      // Fail open — a single bad dir must not block the install.
     }
   }
 }
@@ -6843,6 +6792,12 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false) {
       content = content.replace(/~\/\.claude\//g, pathPrefix);
       content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
       content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
+      // Bare forms (no trailing slash) — use (?![\w-]) instead of \b so that
+      // .claude-plugin / .claudeignore are NOT corrupted (the \b word-boundary
+      // fires between 'e' and '-', which rewrites .claude-plugin → .cursor-plugin).
+      content = content.replace(/~\/\.claude(?![\w-])/g, normalizedPathPrefix);
+      content = content.replace(/\$HOME\/\.claude(?![\w-])/g, normalizedPathPrefix);
+      content = content.replace(/\.\/\.claude(?![\w-])/g, `./${dirName}`);
       content = content.replace(/~\/\.cursor\//g, pathPrefix);
       content = processAttribution(content, getCommitAttribution(runtime));
       break;
@@ -7163,18 +7118,23 @@ function _runLegacyInstallMigrations(runtime, configDir, scope = 'global') {
  * @param {'global'|'local'} [scope]
  */
 function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
-  // Claude global / Qwen: commands/gsd/ is a legacy location (global Claude
-  // uses skills/ now; Qwen always uses skills/). Remove whole directory.
-  // Claude local: commands/gsd/ is the primary current location — skip here,
-  // let layout's _removeGsdEntries handle gsd-prefixed file removal.
+  // commands/gsd/ is a legacy location for Qwen, Hermes, and all Claude installs.
+  // Prior to #1367 fix, Claude-local used commands/gsd/<cmd>.md (colon-namespaced).
+  // After #1367, Claude-local uses flat commands/gsd-<cmd>.md. The inline uninstall
+  // block (1c) handles removal of flat files; this function handles the legacy
+  // commands/gsd/ directory for all Claude scopes (global was already included,
+  // local is now added since that layout is also legacy post-#1367).
   // #2973 / Codex review (bd1f06c9): preserve user-owned dev-preferences.md
   // before destructive wipe. Migration to skills/gsd-dev-preferences/SKILL.md
   // is deferred and returned so the caller can apply it AFTER layout-driven
   // removal — this prevents the layout's gsd-* prefix removal from wiping the
   // freshly created skill dir (same pattern as _runLegacyInstallMigrations).
   let savedLegacyArtifacts = null;
-  // commands/gsd/ is a legacy location for Qwen, Hermes, and Claude-global.
-  // Claude-local commands/gsd/ is the primary current location — skip here.
+  // commands/gsd/ is a legacy location for Qwen, Hermes, and Claude global.
+  // Claude local is intentionally excluded: the inline uninstall block (1c) handles
+  // 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');
   if (isLegacyCommandsGsd) {
     const legacyCommandsGsd = path.join(configDir, 'commands', 'gsd');
@@ -8111,23 +8071,37 @@ function uninstall(isGlobal, runtime = 'claude') {
     } catch { /* best-effort */ }
   }
 
-  // 1c. Claude local: remove commands/gsd/ (primary local install location).
-  //     The layout's _removeGsdEntries uses the 'gsd-' prefix which applies to
-  //     flat command dirs (OpenCode/Kilo). Claude local files use no prefix inside
-  //     the namespaced directory, so layout does not remove them. Handle inline.
-  //     Preserve dev-preferences.md across the wipe (#1423).
+  // 1c. Claude local: remove flat gsd-*.md commands from commands/ (current layout,
+  //     #1367 fix). Also remove legacy commands/gsd/ subdirectory from prior installs.
   if (!isGlobal && runtime === 'claude') {
-    const gsdCommandsDir = path.join(targetDir, 'commands', 'gsd');
-    if (fs.existsSync(gsdCommandsDir)) {
-      const devPrefsPath = path.join(gsdCommandsDir, 'dev-preferences.md');
-      const preservedDevPrefs = fs.existsSync(devPrefsPath) ? fs.readFileSync(devPrefsPath, 'utf-8') : null;
-      fs.rmSync(gsdCommandsDir, { recursive: true });
+    const commandsDir = path.join(targetDir, 'commands');
+    // Remove flat gsd-*.md files (current layout after #1367 fix)
+    if (fs.existsSync(commandsDir)) {
+      let removed = 0;
+      for (const f of fs.readdirSync(commandsDir)) {
+        if (f.startsWith('gsd-') && f.endsWith('.md')) {
+          fs.rmSync(path.join(commandsDir, f), { force: true });
+          removed++;
+        }
+      }
+      if (removed > 0) {
+        removedCount++;
+        console.log(`  ${green}✓${reset} Removed ${removed} flat gsd-*.md commands from commands/`);
+      }
+    }
+    // Remove legacy commands/gsd/ subdirectory if it still exists (pre-#1367 layout).
+    // Preserve user-owned dev-preferences.md if present (#1423 parity).
+    const legacyGsdCommandsDir = path.join(targetDir, 'commands', 'gsd');
+    if (fs.existsSync(legacyGsdCommandsDir)) {
+      const legacyDevPrefsPath = path.join(legacyGsdCommandsDir, 'dev-preferences.md');
+      const savedDevPrefs = fs.existsSync(legacyDevPrefsPath) ? fs.readFileSync(legacyDevPrefsPath, 'utf-8') : null;
+      fs.rmSync(legacyGsdCommandsDir, { recursive: true });
       removedCount++;
-      console.log(`  ${green}✓${reset} Removed commands/gsd/`);
-      if (preservedDevPrefs) {
+      console.log(`  ${green}✓${reset} Removed legacy commands/gsd/`);
+      if (savedDevPrefs) {
         try {
-          fs.mkdirSync(gsdCommandsDir, { recursive: true });
-          fs.writeFileSync(devPrefsPath, preservedDevPrefs);
+          fs.mkdirSync(legacyGsdCommandsDir, { recursive: true });
+          fs.writeFileSync(legacyDevPrefsPath, savedDevPrefs);
           console.log(`  ${green}✓${reset} Preserved commands/gsd/dev-preferences.md`);
         } catch (err) {
           console.error(`  ${red}✗${reset} Failed to restore dev-preferences.md: ${err.message}`);
@@ -8894,7 +8868,11 @@ function writeManifest(configDir, runtime = 'claude', options = {}) {
   const isKimi = runtime === 'kimi';
   const isHermes = runtime === 'hermes';
   const gsdDir = path.join(configDir, 'gsd-core');
+  // #1367: Claude local now writes flat gsd-*.md files at commands/ (not commands/gsd/).
+  // commandsDir points to the old location for Gemini (which still uses commands/gsd/).
+  // Claude local uses flatCommandsDir instead for manifest recording.
   const commandsDir = path.join(configDir, 'commands', 'gsd');
+  const flatCommandsDir = path.join(configDir, 'commands');
   const opencodeCommandDir = path.join(configDir, 'command');
   // Hermes nests GSD skills under skills/gsd/ as a single category (#2841).
   // All other runtimes that use the Codex-style skills layout use a flat skills/ root.
@@ -8920,17 +8898,27 @@ function writeManifest(configDir, runtime = 'claude', options = {}) {
     if (USER_OWNED_ARTIFACTS.includes(rel)) continue;
     manifest.files['gsd-core/' + rel] = hash;
   }
-  // Record commands/gsd/ for any runtime that emits it (Gemini globally,
-  // Claude Code locally — see #2923). Manifest must reflect everything on
-  // disk so saveLocalPatches() can detect user edits and so per-runtime
-  // assertions about minimal-mode emit can read manifest.files instead of
-  // re-walking the dir.
-  if (fs.existsSync(commandsDir)) {
+  // Record commands surface for runtimes that emit it:
+  //   Gemini: commands/gsd/<cmd>.toml (nested, colon-namespaced)
+  //   Claude local (#1367 fix): flat gsd-<cmd>.md at commands/ level
+  // Manifest must reflect everything on disk so saveLocalPatches() can detect
+  // user edits and per-runtime minimal-mode assertions can read manifest.files.
+  if (isGemini && fs.existsSync(commandsDir)) {
     const cmdHashes = generateManifest(commandsDir);
     for (const [rel, hash] of Object.entries(cmdHashes)) {
       manifest.files['commands/gsd/' + rel] = hash;
     }
   }
+  // Claude local (#1367): flat gsd-*.md files at commands/ level.
+  // Only claude local writes gsd-*.md here; global installs don't emit commands,
+  // so this branch is a no-op for global (no matching files to find).
+  if (runtime === 'claude' && fs.existsSync(flatCommandsDir)) {
+    for (const file of fs.readdirSync(flatCommandsDir)) {
+      if (file.startsWith('gsd-') && file.endsWith('.md')) {
+        manifest.files['commands/' + file] = fileHash(path.join(flatCommandsDir, file));
+      }
+    }
+  }
   if ((isOpencode || isKilo) && fs.existsSync(opencodeCommandDir)) {
     for (const file of fs.readdirSync(opencodeCommandDir)) {
       if (file.startsWith('gsd-') && file.endsWith('.md')) {
@@ -9837,14 +9825,14 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     const scope = isGlobal ? 'global' : 'local';
     installRuntimeArtifacts(runtime, targetDir, scope, _resolvedProfile);
 
-    // #774 — Codex only: write agents/openai.yaml TUI chip metadata alongside each
-    // installed skill so the /skills popup shows name + description for each gsd-* skill.
-    // The SkillMetadataFile is loaded by codex-rs/core-skills/src/loader.rs from
-    // <skill-dir>/agents/openai.yaml; absence is silently tolerated (fails open).
-    // We parse the SKILL.md frontmatter to extract short-description already emitted
-    // by convertClaudeCommandToCodexSkill and use it as the TUI chip description.
+    // #1326 — Codex only: remove stale agents/openai.yaml sidecars from managed
+    // gsd-* skill dirs. Prior installs wrote these files so Codex would show a
+    // display name and description in the /skills TUI popup. Recent Codex builds
+    // index BOTH SKILL.md and the sidecar, causing each GSD skill to appear twice
+    // in autocomplete. Cleaning them up fixes the duplication; SKILL.md alone is
+    // sufficient for Codex discovery. User-owned dirs are never touched.
     if (isCodex) {
-      writeCodexSkillMetadataFiles(path.join(targetDir, 'skills'));
+      cleanupCodexSkillMetadataSidecars(path.join(targetDir, 'skills'));
     }
 
     // Hermes only: write DESCRIPTION.md for the gsd/ category after layout install
@@ -10030,18 +10018,59 @@ function install(isGlobal, runtime = 'claude', options = {}) {
       }
     }
   } else {
-    // Claude Code local: commands/gsd/ format — Claude Code reads local project
-    // commands from .claude/commands/gsd/, not .claude/skills/
+    // Claude Code local: flat gsd-<cmd>.md layout — Claude Code registers
+    // commands from .claude/commands/ using the filename stem as the command
+    // name, so gsd-<cmd>.md produces the /gsd-<cmd> hyphen form used everywhere
+    // in the framework. The old commands/gsd/<cmd>.md subdirectory layout caused
+    // Claude Code to namespace commands as /gsd:<cmd> (colon form). (#1367)
     const commandsDir = path.join(targetDir, 'commands');
     fs.mkdirSync(commandsDir, { recursive: true });
     const gsdSrc = _stageSkills(_commandsDir);
-    const gsdDest = path.join(commandsDir, 'gsd');
-    copyWithPathReplacement(gsdSrc, gsdDest, pathPrefix, runtime, true, isGlobal);
-    if (verifyInstalled(gsdDest, 'commands/gsd')) {
-      const count = fs.readdirSync(gsdDest).filter(f => f.endsWith('.md')).length;
-      console.log(`  ${green}✓${reset} Installed ${count} commands to commands/gsd/`);
+    const cmdNames = readGsdCommandNames();
+
+    // Remove stale gsd-*.md files before writing new ones (clean install)
+    if (fs.existsSync(commandsDir)) {
+      for (const f of fs.readdirSync(commandsDir)) {
+        if (f.startsWith('gsd-') && f.endsWith('.md')) {
+          fs.unlinkSync(path.join(commandsDir, f));
+        }
+      }
+    }
+
+    // Write each command as gsd-<stem>.md (flat, hyphen-prefixed)
+    let cmdCount = 0;
+    if (fs.existsSync(gsdSrc)) {
+      for (const entry of fs.readdirSync(gsdSrc, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+        const stem = entry.name.slice(0, -3);
+        let content = fs.readFileSync(path.join(gsdSrc, entry.name), 'utf8');
+        content = _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal);
+        content = normalizeAgentBodyForRuntime(content, runtime, cmdNames);
+        fs.writeFileSync(path.join(commandsDir, `gsd-${stem}.md`), content);
+        cmdCount++;
+      }
+    }
+
+    if (cmdCount > 0) {
+      console.log(`  ${green}✓${reset} Installed ${cmdCount} commands to commands/ (gsd-<cmd>.md flat form)`);
     } else {
-      failures.push('commands/gsd');
+      failures.push('commands/gsd-*');
+    }
+
+    // Legacy cleanup: remove old commands/gsd/ subdirectory from prior installs
+    // that used the namespaced layout (wrote bare-name files under commands/gsd/).
+    const legacyGsdDir = path.join(commandsDir, 'gsd');
+    if (fs.existsSync(legacyGsdDir)) {
+      // Preserve user-owned dev-preferences.md before wiping
+      const devPrefsPath = path.join(legacyGsdDir, 'dev-preferences.md');
+      const preservedDevPrefs = fs.existsSync(devPrefsPath) ? fs.readFileSync(devPrefsPath, 'utf-8') : null;
+      fs.rmSync(legacyGsdDir, { recursive: true });
+      console.log(`  ${green}✓${reset} Removed legacy commands/gsd/ (migrated to flat gsd-<cmd>.md layout)`);
+      if (preservedDevPrefs) {
+        // Migrate dev-preferences to the new flat form
+        fs.writeFileSync(path.join(commandsDir, 'gsd-dev-preferences.md'), preservedDevPrefs);
+        console.log(`  ${green}✓${reset} Migrated dev-preferences.md to commands/gsd-dev-preferences.md`);
+      }
     }
 
     // Clean up any stale skills/ from a previous local install
@@ -12126,8 +12155,7 @@ module.exports = {
     convertClaudeToGeminiAgent,
     convertClaudeAgentToCodexAgent,
     generateCodexAgentToml,
-    generateCodexSkillMetadataYaml,
-    writeCodexSkillMetadataFiles,
+    cleanupCodexSkillMetadataSidecars,
     generateCodexConfigBlock,
     stripGsdFromCodexConfig,
     migrateCodexHooksMapFormat,

package/commands/gsd/autonomous.md

@@ -2,7 +2,7 @@
 name: gsd:autonomous
 description: Run all remaining phases autonomously — discuss→plan→execute per phase
 argument-hint: "[--from N] [--to N] [--only N] [--interactive] [--converge]"
-effort: xhigh
+effort: max
 allowed-tools:
   - Read
   - Write

package/commands/gsd/execute-phase.md

@@ -2,7 +2,7 @@
 name: gsd:execute-phase
 description: Execute all plans in a phase with wave-based parallelization
 argument-hint: "<phase-number> [--wave N] [--gaps-only] [--interactive] [--tdd]"
-effort: xhigh
+effort: max
 allowed-tools:
   - Read
   - Write

package/commands/gsd/plan-phase.md

@@ -2,7 +2,7 @@
 name: gsd:plan-phase
 description: Create detailed phase plan (PLAN.md) with verification loop
 argument-hint: "[phase] [--auto] [--research] [--skip-research] [--research-phase <N>] [--view] [--gaps] [--skip-verify] [--prd <file>] [--ingest <path-or-glob>] [--ingest-format <auto|nygard|madr|narrative>] [--reviews] [--text] [--tdd] [--mvp]"
-effort: xhigh
+effort: max
 allowed-tools:
   - Read
   - Write

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-core",
-  "version": "1.5.0-rc.5",
+  "version": "1.6.0-rc.1",
   "description": "GSD Core — a meta-prompting, context engineering, and spec-driven development system for AI coding agents. Loads gsd's operating context into every Gemini CLI session.",
   "contextFileName": "GEMINI.md"
 }