@opengsd/gsd-core 1.5.0-rc.4 → 1.5.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gsd-core",
   "displayName": "GSD Core",
-  "version": "1.5.0-rc.4",
+  "version": "1.5.0",
   "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-phase-researcher.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-phase-researcher
 description: Researches how to implement a phase before planning. Produces RESEARCH.md consumed by gsd-planner. Spawned by /gsd:plan-phase orchestrator.
-tools: Read, Write, Edit, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*
+tools: Read, Write, Edit, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*, mcp__perplexity__*
 color: cyan
 # hooks:
 #   PostToolUse:

package/agents/gsd-planner.md

@@ -198,6 +198,10 @@ Every task has four required fields:
 Full rules + worked examples: @gsd-core/references/planner-antipatterns.md ("Comment-Text Discipline").
 </comment_text_discipline>
 
+<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").
+</region_scoped_negative_gate>
+
 **<done>:** Acceptance criteria - measurable state of completion.
 - Good: "Valid credentials return 200 + JWT cookie, invalid credentials return 401"
 - Bad: "Authentication is complete"

package/agents/gsd-project-researcher.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-project-researcher
 description: Researches domain ecosystem before roadmap creation. Produces files in .planning/research/ consumed during roadmap creation. Spawned by /gsd:new-project or /gsd:new-milestone orchestrators.
-tools: Read, Write, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*
+tools: Read, Write, Bash, Grep, Glob, Skill, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*, mcp__tavily__*, mcp__ref__*, mcp__jina__*, mcp__perplexity__*
 color: cyan
 # hooks:
 #   PostToolUse:

package/agents/gsd-verifier.md

@@ -180,21 +180,28 @@ For each truth, determine if codebase enables it.
 
 **Verification status:**
 
-- ✓ VERIFIED: All supporting artifacts pass all checks
+- ✓ VERIFIED: All supporting artifacts pass all checks — and, for a behavior-dependent truth, a behavioral test exercises the asserted behavior (see below)
+- ⚠️ PRESENT_BEHAVIOR_UNVERIFIED: Supporting artifacts are present and wired, but the truth asserts runtime behavior that no test exercises — present, not behaviorally proven. Routes to human verification (Step 8) and does NOT count toward the verified score (Step 9).
 - ✗ FAILED: One or more artifacts missing, stub, or unwired
 - ? UNCERTAIN: Can't verify programmatically (needs human)
 
+**Behavior-dependent truths.** A truth is *behavior-dependent* when its correctness hinges on runtime behavior grep/presence checks cannot see — a **state transition** or a **cancellation / cleanup / ordering invariant** (e.g. "cancels the in-flight task and bumps the generation counter", "resets the busy flag on abort", "rolls back on failure"). For these, symbol presence + wiring is *necessary but not sufficient*: the code can be present and wired yet still leak state on the very path the invariant covers.
+
 For each truth:
 
 1. Identify supporting artifacts
 2. Check artifact status (Step 4)
 3. Check wiring status (Step 5)
-4. **Before marking FAIL:** Check for override (Step 3b)
-5. Determine truth status
+4. **Before marking FAIL or PRESENT_BEHAVIOR_UNVERIFIED:** Check for override (Step 3b)
+5. **Classify behavior-dependence.** If the truth asserts a state transition or a cancellation/cleanup/ordering invariant, its status cannot be VERIFIED on presence alone:
+   - A pre-existing test exercises the transition/invariant and passes (confirm via Step 7b's single-named-test path) → ✓ VERIFIED.
+   - No such test exists, or it can't run without a server/state mutation → ⚠️ PRESENT_BEHAVIOR_UNVERIFIED. Emit a human-verification item (Step 8) and do not count it toward the verified score (Step 9).
+   - An accepted override (Step 3b) carries the truth as PASSED (override), exactly as it does for a FAILED truth.
+6. Determine truth status
 
 ## Step 3b: Check Verification Overrides
 
-Before marking any must-have as FAILED, check the VERIFICATION.md frontmatter for an `overrides:` entry that matches this must-have.
+Before marking any must-have as FAILED or ⚠️ PRESENT_BEHAVIOR_UNVERIFIED, check the VERIFICATION.md frontmatter for an `overrides:` entry that matches this must-have.
 
 **Override check procedure:**
 
@@ -204,12 +211,12 @@ Before marking any must-have as FAILED, check the VERIFICATION.md frontmatter fo
 4. Key technical terms (file paths, component names, API endpoints) have higher weight
 
 **If override found:**
-- Mark as `PASSED (override)` instead of FAIL
+- Mark as `PASSED (override)` instead of FAIL/PRESENT_BEHAVIOR_UNVERIFIED
 - Evidence: `Override: {reason} — accepted by {accepted_by} on {accepted_at}`
-- Count toward passing score, not failing score
+- Count toward passing score (`verified_truths`), not failing score
 
 **If no override found:**
-- Mark as FAILED as normal
+- Mark as FAILED (or ⚠️ PRESENT_BEHAVIOR_UNVERIFIED, per Step 3 step 5) as normal
 - Consider suggesting an override if the failure looks intentional (alternative implementation exists)
 
 **Suggesting overrides:** When a must-have FAILs but evidence shows an alternative implementation that achieves the same intent, include an override suggestion in the report:
@@ -461,6 +468,8 @@ Anti-pattern scanning (Step 7) checks for code smells. Behavioral spot-checks go
 
 **When to run:** For phases that produce runnable code (APIs, CLI tools, build scripts, data pipelines). Skip for documentation-only or config-only phases.
 
+**Behavioral evidence for behavior-dependent truths (Step 3).** When a truth asserts a state transition or a cancellation/cleanup/ordering invariant, the single named test below is what upgrades it from ⚠️ PRESENT_BEHAVIOR_UNVERIFIED to ✓ VERIFIED. Run only the one named test that exercises the transition/invariant — never the full suite (per #25/#753). If no such test exists, leave the truth ⚠️ PRESENT_BEHAVIOR_UNVERIFIED and route it to human verification (Step 8); do not mark it VERIFIED on presence.
+
 **How:**
 
 1. **Identify checkable behaviors** from must-haves truths. Select 2-4 that can be tested with a single command:
@@ -548,6 +557,8 @@ done
 
 **Needs human if uncertain:** Complex wiring grep can't trace, dynamic state behavior, edge cases.
 
+**Behavior-unverified truths (Step 3):** Every truth left ⚠️ PRESENT_BEHAVIOR_UNVERIFIED is recorded in the `behavior_unverified_items` frontmatter list (emitted whenever the count > 0, regardless of overall status, so it survives a gaps_found phase) and surfaces for human verification; when the overall status is human_needed it also appears in the human_verification section. Phrase each item around the invariant: what to trigger, what state must hold afterward, and why presence checks can't see it.
+
 **Harvest deferred items from PLAN.md (#3309 / `workflow.human_verify_mode = end-of-phase`):** Scan every PLAN file in the phase for `<verify><human-check>` blocks on `auto` tasks. These are verification items the planner deliberately deferred from `checkpoint:human-verify` to end-of-phase to avoid the executor cold-start cost. Each block has the same shape used by the planner:
 
 ```xml
@@ -579,18 +590,30 @@ Classify status using this decision tree IN ORDER (most restrictive first):
 1. IF any truth FAILED, artifact MISSING/STUB, key link NOT_WIRED, or blocker anti-pattern found:
    → **status: gaps_found**
 
-2. IF Step 8 produced ANY human verification items (section is non-empty):
+2. IF Step 8 produced ANY human verification items (section is non-empty) — this includes every ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truth from Step 3:
    → **status: human_needed**
-   (Even if all truths are VERIFIED and score is N/N — human items take priority)
+   (Even if all other truths are VERIFIED — human items take priority)
 
 3. IF all truths VERIFIED, all artifacts pass, all links WIRED, no blockers, AND no human verification items:
    → **status: passed**
 
-**passed is ONLY valid when the human verification section is empty.** If you identified items requiring human testing in Step 8, status MUST be human_needed.
+**passed is ONLY valid when the human verification section is empty.** If Step 8 produced any items — including any truth left ⚠️ PRESENT_BEHAVIOR_UNVERIFIED — the status is not `passed`: it is `human_needed`, or `gaps_found` when rule 1 also fires (the ordered tree keeps gaps_found's precedence).
+
+**A ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truth is never FAILED and never VERIFIED.** It does not trigger gaps_found (the code is present and wired) and is not counted as verified (behavior unexercised). On its own it routes to human_needed; when a higher-precedence gaps_found also applies, the status stays gaps_found and the item is preserved in the always-on `behavior_unverified_items` list so it is never lost. Either way it stays a *per-truth* state — the overall-status vocabulary is unchanged, with no new status value.
 
 > **Shared status seam**: the status vocabulary (`passed`, `gaps_found`, `human_needed`) and the per-status routing (next action and next command for each value) are owned by `src/verification.cts` via `gsd_run query verification.status`. This agent is the single emitter of the frontmatter status field; consumers (ship.md, execute-phase.md) read routing from that query instead of re-deriving it.
 
-**Score:** `verified_truths / total_truths`
+**Score (presence- vs behavior-verified split):**
+
+- `verified_truths` counts ✓ VERIFIED truths plus PASSED (override) truths (Step 3b). For a behavior-dependent truth, VERIFIED means a behavioral test passed, not just that symbols are present.
+- ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truths are the *only* ones excluded from `verified_truths`; they are reported separately as `behavior_unverified`.
+
+```text
+score: verified_truths / total_truths        # e.g. 6/7
+behavior_unverified: P                        # truths present + wired but behavior not exercised
+```
+
+A headline N/N therefore certifies that every behavior-dependent truth had behavioral evidence — a clean score can no longer be reached on symbol presence alone.
 
 ## Step 9b: Filter Deferred Items
 
@@ -699,6 +722,7 @@ phase: XX-name
 verified: YYYY-MM-DDTHH:MM:SSZ
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
+behavior_unverified: 0 # Count of ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truths (present + wired, behavior not exercised); each is detailed in behavior_unverified_items below (and in human_verification when status is human_needed)
 overrides_applied: 0 # Count of PASSED (override) items included in score
 overrides: # Only if overrides exist — carried forward or newly added
   - must_have: "Must-have text that was overridden"
@@ -725,6 +749,11 @@ deferred: # Only if deferred items exist (Step 9b)
   - truth: "Observable truth addressed in a later phase"
     addressed_in: "Phase N"
     evidence: "Matching goal or success criteria text"
+behavior_unverified_items: # Only if behavior_unverified > 0 — emitted regardless of overall status, so these survive a gaps_found phase
+  - truth: "Observable truth whose state transition or cancellation/cleanup/ordering invariant no test exercises"
+    test: "What to trigger"
+    expected: "What state must hold afterward"
+    why_human: "Why presence checks can't see it"
 human_verification: # Only if status: human_needed
   - test: "What to do"
     expected: "What should happen"
@@ -746,8 +775,9 @@ human_verification: # Only if status: human_needed
 | --- | ------- | ---------- | -------------- |
 | 1   | {truth} | ✓ VERIFIED | {evidence}     |
 | 2   | {truth} | ✗ FAILED   | {what's wrong} |
+| 3   | {truth} | ⚠️ PRESENT_BEHAVIOR_UNVERIFIED | {present + wired; no test exercises the transition/invariant — see Human Verification} |
 
-**Score:** {N}/{M} truths verified
+**Score:** {N}/{M} truths verified ({P} present, behavior-unverified)
 
 ### Deferred Items
 
@@ -834,7 +864,7 @@ Structured gaps in VERIFICATION.md frontmatter for `/gsd:plan-phase --gaps`.
 
 {If human_needed:}
 ### Human Verification Required
-{N} items need human testing:
+{N} items need human testing (including {P} present-but-behavior-unverified truths — code wired, transition/invariant not exercised by a test):
 1. **{Test name}** — {what to do}
    - Expected: {what should happen}
 
@@ -857,6 +887,8 @@ Automated checks passed. Awaiting human verification.
 
 **Keep verification fast.** Use grep/file checks, not running the app.
 
+**Presence is not behavior.** Grep/file checks prove a symbol is present and wired — they do not prove a state transition or a cancellation/cleanup/ordering invariant holds at runtime. For a behavior-dependent truth, require a passing behavioral test (Step 7b's single named test) or mark it ⚠️ PRESENT_BEHAVIOR_UNVERIFIED and route to human verification. Never let symbol presence alone produce a VERIFIED on a behavior-dependent truth.
+
 **DO NOT commit.** Leave committing to the orchestrator.
 
 </critical_rules>

package/bin/install.js

@@ -265,9 +265,11 @@ const _gsdLibDir = path.join(__dirname, '..', 'gsd-core', 'bin', 'lib');
 const { MODEL_PROFILES: GSD_MODEL_PROFILES } = require(path.join(_gsdLibDir, 'model-profiles.cjs'));
 const {
   RUNTIME_PROFILE_MAP: GSD_RUNTIME_PROFILE_MAP,
+} = require(path.join(_gsdLibDir, 'model-catalog.cjs'));
+const {
   resolveTierEntry: gsdResolveTierEntry,
   EFFORT_SET: GSD_EFFORT_SET,
-} = require(path.join(_gsdLibDir, 'core.cjs'));
+} = require(path.join(_gsdLibDir, 'model-resolver.cjs'));
 
 // #443 — model-catalog and config-defaults.manifest.json exports needed only
 // by effort-resolution code paths (resolveInstallTimeEffort /
@@ -1794,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
@@ -1890,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 += '---';
 
@@ -3192,110 +3198,55 @@ function generateCodexAgentToml(agentName, agentContent, modelOverrides = null,
 }
 
 /**
- * Generate the agents/openai.yaml TUI chip metadata content for a Codex skill.
- *
- * 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).
- *
- * 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.
+ * Remove stale agents/openai.yaml sidecar files from GSD-managed Codex skill dirs.
  *
- * Fails open: individual skill directories that cannot be processed are silently
- * skipped so a single malformed SKILL.md cannot block the whole install.
+ * 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.
  *
- * 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') || '';
-        }
+      // 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);
       }
-      if (!shortDesc) {
-        shortDesc = `Run GSD workflow ${entry.name}.`;
-      }
-      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.
     }
   }
 }
@@ -6841,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;
@@ -9835,14 +9792,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
@@ -12124,8 +12081,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.4",
+  "version": "1.5.0",
   "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"
 }