prefix install: ./setup --status reports "1 of 114 broken" and exits 1, though the doc's own prefixed path resolves

Open Beginner friendly
  • Is something wrong?
#4,164 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
77/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
bash, typescript
Domain
cli, testing

Research direction

Start in setup at _status_install_checks() and inspect how its ../* branch resolves section links for prefixed installs. Reproduce with ./setup --status after a Claude prefix install, then compare against the unprefixed install. Done means all 114 links resolve and --status exits 0 for both layouts.

Written by the indexing model from the issue text.

Description

What happened

On a prefix install (--prefix, skills land as gstack-review, gstack-qa, …), ./setup --status reports a broken section link for the Claude host and exits 1 — but nothing is actually broken. Every prefix install fails this self-check permanently.

$ ./setup --status; echo "exit=$?"
Install checks:
  opencode global: router is a real file; section links: 75 checked, all resolve
  cursor global: router is a real file; section links: 75 checked, all resolve
  agy global: router is a real file; section links: 75 checked, all resolve
  gemini global: router is a real file; section links: 75 checked, all resolve
  codex global: router is a real file; section links: 74 checked, all resolve
  claude global: router is a real file; section links: 1 of 114 broken (first: gstack-review/SKILL.md names ../qa/sections/exploratory.md). Fix: cd ~/.claude/skills/gstack && ./setup --host claude
gstack: an install has broken section links (see Install checks above); exit 1
exit=1

Re-running the suggested ./setup --host claude reproduces it byte for byte, so the "Fix:" hint cannot clear it.

Steps to reproduce

  1. git clone --single-branch --depth 1 https://github.com/garrytan/gstack ~/gstack && cd ~/gstack && ./setup --host claude --prefix --global (any prefix install does it; the Claude host is the only one that ships the relative pointers)
  2. ./setup --status; echo $? → 1 of 114 broken, exit 1
  3. Drop --prefix (./setup --host claude --no-prefix --global) → 114 checked, all resolve, exit 0

Why it is a false positive

The installed gstack-review/SKILL.md states both layouts itself, one line apart:

- If the caller directory is `review`, Read `../qa/sections/exploratory.md` in full.
- If the caller directory is prefixed `gstack-review`, use `../gstack-qa/sections/exploratory.md` instead and read it in full.

_status_install_checks() (in setup) walks every Read `<path>/sections/<f>.md` pointer and resolves ../* literally:

          ../*) path="$dir/$tok" ;;

On a prefix install $dir is …/gstack-review, so ../qa/sections/exploratory.md points at …/qa/sections/…, which does not exist — while the very next line of the same doc tells the agent to use ../gstack-qa/sections/…, which does. The checker counts the first pointer as broken before ever reading the second.

Expected

./setup --status reports 114 checked, all resolve and exits 0 on a prefix install, because every pointer the doc offers resolves in the layout the doc itself describes.

Suggested fix

Either is enough, and neither touches installed content:

  1. Resolve the prefixed sibling in the ../*) arm — if $dir/$tok is unreadable, retry with the first path segment prefixed (../qa/… → ../gstack-qa/…) when that file exists.
  2. Rewrite body pointers in prefix mode next to the existing name: patch (bin/gstack-patch-names), so the installed doc carries only the path that exists in that layout.

Impact

--status is the readiness gate used in docs/hosts.md and quoted by the bug template; on a prefix install it returns a hard failure (exit 1) that no re-run clears, so any script or human gating on it learns to ignore it. Skill behavior is unaffected — the doc's second line is what actually gets used.

Readiness report

ok              install root    ~/.claude/skills/gstack: opencode/cursor/agy/gemini/codex/claude global current (1.98.0.0)
ok              bun             1.4.2 at ~/.bun/bin/bun (floor 1.3.3, tested 1.4.2)
ok              windows bash    C:/Program Files/Git/bin/bash.exe (chosen by git --exec-path)
ok              browse bundle   browse/dist built
ok              binaries        find-browse, design, pdf, gstack-global-discover launch (4 of 4)
13 ok, 2 warn, 1 not configured, 0 fail

Environment

  • Host: Claude Code 2.1.319 (the only host whose render carries the relative pointers), 6 global installs registered
  • OS: Windows 11, Git for Windows bash, Bun 1.4.2
  • gstack: 1.98.0.0 (9740bfd); setup is byte-identical to main at 6042f6ad48774504f918ab1391908c1ccdb11fe0, where _status_install_checks has the same ../*) path="$dir/$tok" line
Dominant language
TypeScript
Stars
139k
Forks
20.6k
Avg merge
10h 12m
Merged PRs (30d)
655

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from garrytan/gstack

All issues in garrytan/gstack

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.