fix(#725): route Codex gsd-tools calls through shim

[j2h4u]

Fix PR

Using the wrong template?
— Enhancement: use enhancement.md
— Feature: use feature.md

---

Linked Issue

Fixes #725

---

What was broken

Generated Codex skills and agent TOML could still ask agents to execute bare gsd-tools commands. Shim-only Codex installs materialize $gsd-* skills under ~/.codex, but they do not guarantee a gsd-tools binary on PATH, so those generated calls could fail with command not found.

What this fix does

Codex markdown conversion now rewrites command-position bare gsd-tools invocations to node "$HOME/.codex/gsd-core/bin/gsd-tools.cjs" while preserving resolver probes such as command -v gsd-tools. The shared runtime launcher also probes repo-local and home-local .codex/gsd-core/bin/gsd-tools.cjs fallbacks, and the launcher snippet is re-synced across workflow files.

This is a conflict-free branch based on current next; related PR #731 is currently CONFLICTING.

Root cause

The installer converted Claude paths to Codex paths, but it did not normalize command-position gsd-tools references in generated Codex surfaces. The shared launcher also only had .claude local/home fallback arms plus the optional PATH binary, leaving Codex shim-only installs without a local fallback path.

Testing

How I verified the fix

• npm ci --ignore-scripts --no-audit --no-fund
• npm run build:lib
• git diff --check
• node scripts/changeset/lint.cjs
• node --test tests/codex-config.test.cjs tests/bug-3582-codex-skills-materialized.test.cjs tests/runtime-launcher-parity.test.cjs — 150 passed
• node --test tests/roadmap.test.cjs — 32 passed after full-suite failure triage
• Baseline check: tests/roadmap.test.cjs also passes on clean upstream/next at 29c0a2f5
• npm test was attempted; it failed once in tests/roadmap.test.cjs with planningPaths is not a function. The same file passes in isolation on this branch and on clean upstream/next, so I am treating it as an existing order-dependent full-suite isolation issue rather than part of this Codex shim fix.

Regression test added?

• Yes — added tests covering generated Codex skill/agent surfaces and launcher fallback behavior
• No — explain why:

Platforms tested

• macOS
• Windows (including backslash path handling)
• Linux
• N/A (not platform-specific)

Runtimes tested

• Claude Code
• Gemini CLI
• OpenCode
• Other: Codex
• N/A (not runtime-specific)

---

Checklist

• Issue linked above with Fixes #NNN — PR will be auto-closed if missing
• Linked issue has the confirmed-bug label
• Fix is scoped to the reported bug — no unrelated changes included
• Regression test added (or explained why not)
• All existing tests pass (npm test)
• .changeset/ fragment added if this is a user-facing fix (npm run changeset -- --type Fixed --pr <NNN> --body "...") — or no-changelog label applied
• No unnecessary dependencies added

Breaking changes

None

---

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}

[trek-e]

Summary

fix(#725) routes Codex-generated SKILL.md / agent-TOML bare gsd-tools calls through the home-local shim and adds .codex/gsd-core/bin/ fallback arms to the runtime launcher, re-synced across the workflow files. Bug-Fix Track — issue #725 carries confirmed-bug. Reviewed per the gsd-core PR review directive and verified in an isolated checkout with base-vs-PR test runs.

Classification & gate compliance

• Linked issue: ✅ Fixes #725 + confirmed-bug → Bug-Fix Track (RULESET.CONTRIB.CLASSIFY.fix=requires confirmed/confirmed-bug before implementation).
• Branch fix/725-codex-gsd-tools-shim-conflict-free ✅ matches fix/NNN-slug.
• Commit fix(#725): … ✅ conventional.
• Changeset .changeset/725-codex-gsd-tools-shim.md ✅ type: Fixed, valid frontmatter+body; Fixed → docs gate exempt ✅.
• One concern ✅ — the ~80 workflow-file edits are mechanical launcher re-sync (verified: only the snippet line changed in sampled files), not scope creep.

Root-cause & paper-over verdict: PASS

rewriteBareGsdToolsCommandsForCodex (bin/install.js ~3014) rewrites command-position bare gsd-tools — line-start, $( … ), backtick, and after && || ; | — to node "$HOME/.codex/gsd-core/bin/gsd-tools.cjs", and preserves resolver probes. Verified by live evaluation: command -v gsd-tools, which gsd-tools, type gsd-tools, and identifier substrings (my_gsd-tools_var) are untouched. The launcher snippet adds repo-local + $HOME-local .codex arms alongside the existing .claude arms while keeping the PATH probe. This corrects behavior at the root cause (generation and resolution) — no output suppression, no error swallowing, no test-input special-casing.

Fail-first regression proof: PASS (all three modified test files)

Each test run on the PR branch (pass) and against base code with the PR's test file applied (fail):

Test file	PR	Base	Base failure
runtime-launcher-parity	8/8 ✅	7/8 ❌	snippet.sh must contain the Codex fallback arm (".codex/gsd-core/bin/") (line 403)
codex-config	136/136 ✅	133/136 ❌	rewrites command-substitution / line-start; gsd-code-fixer.toml must not contain a command-position bare gsd-tools
bug-3582-codex-skills-materialized	6/6 ✅	5/6 ❌	gsd-autonomous/SKILL.md must not contain a command-position bare gsd-tools

Launcher parity holds (parity test green; sampled workflow files show only the snippet line changed).

Findings by severity

Minor

1. RULESET.TESTS.property-based-testing — the converter is a text-transformation contract; the standard asks for ≥1 fast-check property test. The four regex branches are well covered by enumerated cases (including the critical probe-preservation cases), but a property test over fuzzed content would guard against future regex interactions. Recommend adding one.
2. CONTEXT.md ### Runtime Launcher Module (line 68) describes the chain as "node when present, falls back to a gsd-tools binary on PATH, else errors" — it now omits the per-runtime (.claude / .codex) home fallback arms. It was already non-exhaustive (never enumerated the .claude arms), so this is not a hard gate violation, but a one-line update mentioning multi-runtime home fallbacks would keep the seam description accurate.

Nit
3. rewriteBareGsdToolsCommandsForCodex is not exported; it's covered indirectly via the two converters. A direct export would enable isolated unit + property testing (ties to finding 1).

Verdict: Comment (no blockers)

Correct, root-cause fix with a solid fail-first proof and clean format. The items above are quality/precision improvements, not merge blockers. Nice work on the probe-preservation regex — that's the part most likely to regress and it's well guarded.

[j2h4u]

Pushed the requested follow-up: the Codex gsd-tools rewrite helper is exported and covered with property tests, and CONTEXT.md now documents the Claude/Codex/OpenCode home-fallback shim behavior.