fix(hooks): use ${CLAUDE_PLUGIN_ROOT} instead of ${CLAUDE_SKILL_DIR}

[ivansamartino]

Summary

Replaces \${CLAUDE_SKILL_DIR} with \${CLAUDE_PLUGIN_ROOT} throughout the skill-registered hook commands (and adjacent skill-body references) in freeze, careful, guard, investigate, and ship. Claude Code does not define \${CLAUDE_SKILL_DIR} — the only variable it substitutes for hooks registered via a skill's frontmatter is \${CLAUDE_PLUGIN_ROOT}, which points at the skill's install directory.

Fixes #961.

What was broken

Every time a skill with a \${CLAUDE_SKILL_DIR} hook was loaded into a Claude Code session, the subsequent Write/Edit/Bash tool calls failed with:

```
PreToolUse:Write hook error
Failed with non-blocking status code: bash: /../freeze/bin/check-freeze.sh: No such file or directory
```

Bash expanded the undefined \${CLAUDE_SKILL_DIR} to the empty string at hook execution time, producing paths rooted at / that don't exist. Because the hooks are non-blocking, tool calls still succeeded — so this presented as noise in the transcript rather than a hard failure. But it also meant the freeze-boundary and careful-command checks these hooks were supposed to enforce never actually ran for any user: the check-freeze.sh / check-careful.sh script was never reached.

I reproduced this on gstack `0.16.2.0` (commit `dbd7aee5`, branch base) with Claude Code `2.1.101` native binary on macOS (arm64), where I verified against the compiled binary that:

• \${CLAUDE_PLUGIN_ROOT} is whitelisted, substituted, and exported into the hook process env (value = skill install directory).
• \${CLAUDE_PLUGIN_DATA} is plugin-scoped and rejected for skill hooks (error message: `Hook command references ${...} but only ${CLAUDE_PLUGIN_ROOT} is available for skill hooks (${CLAUDE_PLUGIN_DATA} is plugin-only)`).
• \${CLAUDE_SKILL_DIR} is not referenced anywhere in the binary — it isn't substituted and isn't exported.

The fix is a mechanical `s/CLAUDE_SKILL_DIR/CLAUDE_PLUGIN_ROOT/` across the 6 source files that feed the generator, followed by regenerating the committed `SKILL.md` outputs via `bun run gen:skill-docs --host all`. The sibling-path structure (`${CLAUDE_PLUGIN_ROOT}/../freeze/bin/check-freeze.sh` in `guard`/`investigate`) continues to work because Claude Code points `${CLAUDE_PLUGIN_ROOT}` at the skill's own directory and its siblings are reachable via `..`.

Files changed

• `freeze/SKILL.md.tmpl` — 2× hook commands
• `careful/SKILL.md.tmpl` — 1× hook command
• `guard/SKILL.md.tmpl` — 3× hook commands (siblings into `careful/` and `freeze/`)
• `investigate/SKILL.md.tmpl` — 2× hook commands + 1× availability probe
• `ship/SKILL.md.tmpl` — 1× `cat ... /document-release/SKILL.md` reference (Step 8.5)
• `scripts/resolvers/review.ts` — 1× `cat ... /qa-only/SKILL.md` reference (injected into ship Step 5.3)
• 5 corresponding regenerated `SKILL.md` files

22 lines changed across 11 files.

Testing

• Generator round-trip: `bun run gen:skill-docs --host all` on the unchanged tree produces no diff, confirming the regenerated outputs are deterministic and the only delta comes from my `.tmpl` edits.
• Hook script tests: `bun test test/hook-scripts.test.ts` → 32/32 pass. The `check-freeze.sh` and `check-careful.sh` logic is unchanged and its unit tests still pass.
• Host-config tests: `bun test test/host-config.test.ts` → 69 pass / 3 fail. Identical pass/fail counts to upstream `main` on the same commit base. The 3 failures are pre-existing `golden-file regression` tests comparing committed `ship/SKILL.md` against stale fixtures in `test/fixtures/golden/`, which already diverged on main before my change (the golden diff is +40 lines, my contribution is 2 substituted lines inside that diff). I left the golden fixtures alone so as not to conflate the fix with a fixture refresh.
• End-to-end install verification: `npx skills add ivansamartino/gstack#fix/skill-dir-var` into a clean temp `$HOME`, then simulated Claude Code's variable substitution manually (`${CLAUDE_PLUGIN_ROOT}` → skill-dir-path) — resolved sibling paths like `investigate/../freeze/bin/check-freeze.sh` exist on disk and execute correctly.
• Live session verification: Installed the fork via a nix flake, started a fresh Claude Code session, invoked `/investigate`, and ran `Write` + `Edit` tool calls. Before: `PreToolUse:Write hook error` on every call. After: no hook error, tool calls run clean. The installed `SKILL.md` shows `${CLAUDE_PLUGIN_ROOT}` references as expected.

Notes for reviewers

• This branch is based on `dbd7aee5` (`v0.16.2.0`). Upstream has since moved to `c6e6a21d` (`v0.16.3.0`). The refactor in `c6e6a21d` touches `browse/`, `extension/`, and `scripts/slop-diff.ts` — zero overlap with my patched files — so a rebase onto current main should be conflict-free. Happy to rebase and force-push if you'd prefer the branch linearized on top of `v0.16.3.0`.
• The `test/fixtures/golden/*.md` fixtures are stale on main already — refreshing them is worth a separate PR and I didn't want to bundle an unrelated change here.
• Cosmetic: the name: ... frontmatter in the 5 patched `SKILL.md` files is unchanged, so skill routing/discovery is unaffected.