v1.57.9.0 feat: source-clean gbrain render (dev-setup --out-dir + machine-wide gbrain-refresh) (#1951)

* feat(gbrain-detect): add --is-ok live-detection exit-code gate

Single source of truth for 'is gbrain usable'. Runs live detection (never
reads the possibly-stale gbrain-detection.json) and exits 0 iff status is ok,
so setup, bin/dev-setup, and gstack-config can gate brain-aware rendering on
one shared check instead of re-grepping the JSON.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(gen-skill-docs): add --out-dir with surgical section-path rewrite

--out-dir <abs-dir> mirrors the Claude skill tree (SKILL.md + sections) into a
separate directory instead of writing in place, and rewrites the literal
section-base path (~/.claude/skills/gstack/<skill>/sections/) in generated
content to point at the out-dir. The rewrite is surgical: only /sections/ paths
move; bin/, browse/, docs/ references stay pointed at the global install.
Global extras (proactive-suggestions.json) are skipped in out-dir mode. Default
(no flag) behavior is unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(dev-setup): render gbrain :user variant to an untracked workspace dir

Stops the dev/Conductor workspace from dirtying tracked SKILL.md source. setup
honors GSTACK_SKIP_GBRAIN_REGEN (passed inline by dev-setup, never exported) and
skips the in-place :user regen; detection is still persisted (PID-unique tmp so
concurrent workspaces can't clobber it). dev-setup instead renders the :user
variant into .claude/gstack-rendered (gitignored, per-workspace) and repoints
the workspace SKILL.md symlinks at it, so the workspace gets brain-aware blocks
while the worktree stays canonical. dev-teardown removes the render.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(dev-skill): refresh the untracked brain-aware render on template change

After the default in-place regen (which keeps the worktree canonical and runs
validation), also re-render the :user variant into .claude/gstack-rendered when
it exists, so live template edits reflect at the workspace's runtime. Never
creates the render dir during plain template dev.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(gstack-config): gbrain-refresh renders brain-aware blocks into the install

Extends gbrain-refresh to render the :user variant into the global install
(~/.claude/skills/gstack) so every project's Claude sessions get brain-aware
blocks, not just the gstack dev workspace. Guarded against mutating the wrong
directory: the target must exist, not be a symlink (a symlinked install points
at a dev worktree), and look like a real gstack clone (VERSION + package.json).
Idempotent and self-documenting. CLAUDE.md's deploy section now notes that
'git reset --hard' reverts the blocks and to re-run gbrain-refresh.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test: cover gstack-gbrain-detect --is-ok + dev-skill render refresh

Fills the two automated-coverage gaps from the eng review: --is-ok exit-code
gate (no-cli -> nonzero, healthy -> 0, plus an agrees-with-JSON no-skew check
reusing the deterministic fake-gbrain harness) and a static tripwire that
dev-skill re-renders the :user variant into the workspace render dir only when
it already exists.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore: bump version and changelog (v1.57.9.0)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: document brain-aware dev-setup render for v1.57.9.0

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

bin/gstack-config

@@ -396,8 +396,29 @@ case "${1:-}" in
 
     case "$STATUS" in
       ok)
-        echo "Detected gbrain v$VERSION → brain-aware blocks will render in planning-skill SKILL.md files."
-        echo "Run 'bun run gen:skill-docs' in the gstack repo (or re-run ./setup) to regenerate now."
+        echo "Detected gbrain v$VERSION."
+        # Render brain-aware blocks INTO the global install so EVERY project's
+        # Claude sessions get them (other projects read SKILL.md + sections from
+        # ~/.claude/skills/gstack via absolute paths baked at gen time). Guards
+        # (never mutate an arbitrary directory): the target must exist, not be a
+        # symlink (a symlinked install points at a dev worktree — rendering there
+        # would dirty tracked source), and look like a real gstack clone.
+        INSTALL_DIR="$HOME/.claude/skills/gstack"
+        if [ ! -d "$INSTALL_DIR" ]; then
+          echo "No global install at $INSTALL_DIR — nothing to render. (Dev workspaces get blocks via bin/dev-setup.)"
+        elif [ -L "$INSTALL_DIR" ]; then
+          echo "Skip: $INSTALL_DIR is a symlink (likely a dev worktree). Rendering there would dirty tracked source — run bin/dev-setup in that worktree instead."
+        elif [ ! -f "$INSTALL_DIR/VERSION" ] || [ ! -f "$INSTALL_DIR/package.json" ]; then
+          echo "Skip: $INSTALL_DIR doesn't look like a gstack clone (missing VERSION/package.json) — refusing to modify it."
+        elif ! command -v bun >/dev/null 2>&1; then
+          echo "Skip: bun not on PATH — can't render. Install bun, then re-run 'gstack-config gbrain-refresh'."
+        elif ( cd "$INSTALL_DIR" && bun run gen:skill-docs:user --host claude >/dev/null 2>&1 ); then
+          echo "Rendered brain-aware blocks into $INSTALL_DIR — now live across all your projects' Claude sessions."
+          echo "Note: this dirties the install's git tree (generated blocks differ from main, by design)."
+          echo "      A 'git reset --hard origin/main' there reverts them; re-run 'gstack-config gbrain-refresh' to restore."
+        else
+          echo "Warning: render failed. Run 'cd $INSTALL_DIR && bun run gen:skill-docs:user --host claude' manually to see the error."
+        fi
         ;;
       *)
         echo "gbrain not detected (local-status: $STATUS) → brain-aware blocks will be suppressed in planning-skill SKILL.md files."