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

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gsd-core",
   "displayName": "GSD Core",
-  "version": "1.5.0",
+  "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/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

@@ -7118,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');
@@ -8066,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}`);
@@ -8849,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.
@@ -8875,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')) {
@@ -9985,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

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-core",
-  "version": "1.5.0",
+  "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"
 }