fix(hook-check): cover skill frontmatter hooks, sourced helpers, conflict markers and the caller's tsconfig

Rewrite of #3066. bin/gstack-hook-check only listed setup's hooks plus
/autoplan's by name, so the /careful and /freeze PreToolUse checks (also run
by /guard and /investigate), /plan-ceo-review's hand-off hook and the helpers
they source were never parse-checked before Claude Code ran them.

- The hook list is setup's _hook_command_path arguments plus every gstack path
  on a `command:` line in a generated */SKILL.md frontmatter (9 hooks, up from
  6). The generated files are read rather than the .tmpl sources because the
  /autoplan and /plan-ceo-review commands come from resolvers.
- Each shell hook's gstack-tree helpers (`.`/`source` lines, assignments and
  shellcheck source= directives, followed transitively) are parsed too:
  careful/bin/hook-extract.sh and bin/gstack-state-root.sh for /careful and
  /freeze.
- The shim, its helpers, each TypeScript entry and every local module the
  bundle used (bun build --metafile; entry only when bun lacks it) are scanned
  for conflict-marker lines, which still parse inside heredocs, strings and
  template literals.
- bun build runs from the gstack root, so the caller's broken tsconfig.json or
  bunfig.toml no longer fails every TypeScript hook. Lists are newline
  separated, so a root with spaces works.

Tests in test/setup-hook-syntax-gate.test.ts cover each case; the gstack-doctor
fixture now copies autoplan/SKILL.md, whose frontmatter registers the hook its
hooks-row test breaks. docs/troubleshooting.md describes the wider check.

Co-authored-by: Benjamin D. Smith <7134745+BenjaminDSmithy@users.noreply.github.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
committed 2026-10-08 06:23:53 +00:00
1 parent 2ec5275db5
commit f629bd560d
4 files changed
+178 -22

No files matched your search

+17 -8
View File
@@ -615,13 +615,21 @@ Bun first.
**Meaning.** Claude Code runs gstack's hook shims through `/bin/sh`, and a hook
that does not parse exits 2, which blocks the tool call it guards in every
session. Setup parse-checks every hook it registers (the shim, and the
TypeScript it runs with its local imports). It registers the hooks that parse,
skips the ones listed, finishes the rest of the install, and exits non-zero.
Claude Code runs hooks straight from `~/.claude/skills/gstack`, so a skipped
hook that an earlier setup registered keeps running the broken file until it
is fixed. This is a gstack bug, or a half-applied edit or merge in your
checkout: report the printed `<file>:<line>`.
session. Setup parse-checks every hook it registers and every hook a skill's
frontmatter runs (`/autoplan`, `/careful`, `/freeze`, `/guard`, `/investigate`
and `/plan-ceo-review`): the shim, the gstack shell helpers it sources (such as
`careful/bin/hook-extract.sh` and `bin/gstack-state-root.sh`), and the
TypeScript it runs with its local imports. A merge conflict marker line in any
of those files fails as `unresolved merge conflict marker`, even when the file
still parses (markers inside a heredoc, a string or a template literal do).
The TypeScript is bundled from the gstack checkout, so the `tsconfig.json` or
`bunfig.toml` of the project you run it from is never read. It registers the
hooks that parse, skips the ones listed, finishes the rest of the install, and
exits non-zero. Claude Code runs hooks straight from `~/.claude/skills/gstack`,
so a skipped hook that an earlier setup registered, or that a skill runs,
keeps running the broken file until it is fixed. This is a gstack bug, or a
half-applied edit or merge in your checkout: report the printed
`<file>:<line>`.
**Fix.**
@@ -637,7 +645,8 @@ cd ~/.claude/skills/gstack && ./setup
### `gstack auto-update: update held (hook-does-not-parse: <file>:<line>: <error>); nothing was installed or changed, and your current hooks keep running. ...`
**Meaning.** Team-mode auto-update fetched a release with a hook that does not
parse. It checked the incoming revision before moving your checkout, so your
parse or still holds a merge conflict marker (the same check setup runs). It
checked the incoming revision before moving your checkout, so your
checkout, installed skills and registered hooks stay at the current revision.
gstack checks again at the next update check and installs the first release
whose hooks parse. This is a gstack bug: report the printed `<file>:<line>`.