v1.57.9.0 feat: source-clean gbrain render (dev-setup --out-dir + machine-wide gbrain-refresh) (garrytan#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>

Author: garrytan

.gitignore

@@ -7,6 +7,7 @@ make-pdf/dist/
 bin/gstack-global-discover*
 .gstack/
 .claude/skills/
+.claude/gstack-rendered/
 .claude/scheduled_tasks.lock
 .claude/*.lock
 .agents/

CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## [1.57.9.0] - 2026-06-09
+
+## **Your gstack checkout stays clean when gbrain is installed.**
+## **Brain-aware skill blocks render to an untracked spot, never into tracked source.**
+
+Before this, finishing a Conductor or dev-workspace setup with gbrain installed
+rewrote 16 planning and review SKILL.md files in place, adding 326 lines of
+brain-aware blocks straight into tracked source. Your working tree came back dirty,
+one stray `git add` away from committing a token regression for everyone who does
+not run gbrain. Now `gen-skill-docs --out-dir` renders the brain-aware variant into
+an untracked per-workspace directory, and `bin/dev-setup` repoints the workspace's
+skill symlinks at it. The dev workspace gets the full gbrain experience (context-load
+and save-to-brain blocks live at runtime), while the tracked SKILL.md files stay
+byte-for-byte canonical. To turn the blocks on across all your projects' Claude
+sessions, `gstack-config gbrain-refresh` now renders them into your global install,
+guarded so it never mutates a symlinked or non-gstack directory.
+
+### The numbers that matter
+
+Structural facts of the change, verifiable from the diff plus `bun run gen:skill-docs`
+(zero drift) and the new behavioral test (`test/gen-skill-docs-out-dir.test.ts`).
+
+| When gbrain is installed | Before | After |
+|---|---|---|
+| Tracked SKILL.md files dirtied by dev-setup | 16 (+326 lines) | 0 |
+| Where brain-aware blocks render in a dev workspace | in-place, tracked source | `.claude/gstack-rendered/`, untracked |
+| Brain-aware blocks across other projects | re-run `./setup` or hand-edit | `gstack-config gbrain-refresh` (idempotent) |
+| "Is gbrain usable" check | per-caller JSON grep, can read stale state | `gstack-gbrain-detect --is-ok` (one live gate) |
+
+The section-path rewrite is surgical: only `~/.claude/skills/gstack/<skill>/sections/`
+references move to the render dir, so `bin/` and `docs/` references still resolve to
+the install.
+
+### What this means for you
+
+If you develop gstack with gbrain on, `git status` is clean again after setup, and
+you can stop fishing brain-block drift out of your commits. After a
+`git reset --hard` deploy of your install, re-run `gstack-config gbrain-refresh` to
+restore the machine-wide blocks (it is idempotent, and the deploy note in CLAUDE.md
+spells this out).
+
+### Itemized changes
+
+#### Added
+- `gen-skill-docs --out-dir <dir>`: render the Claude SKILL.md + sections into a
+  separate directory instead of in place, rewriting only the section-base path so
+  section reads resolve to the render. Default (no flag) output is unchanged.
+- `gstack-gbrain-detect --is-ok`: live-detection exit-code gate (0 iff gbrain is
+  usable), so setup, dev-setup, and gstack-config share one check.
+- `gstack-config gbrain-refresh` now renders brain-aware blocks into the global
+  install (`~/.claude/skills/gstack`), guarded against symlinked or non-gstack
+  targets and self-documenting about the `reset --hard` re-run cycle.
+
+#### Changed
+- `bin/dev-setup` renders the brain-aware variant into `.claude/gstack-rendered`
+  (gitignored) and repoints workspace skill symlinks at it; the worktree stays
+  canonical. `GSTACK_SKIP_GBRAIN_REGEN` is passed inline to the nested setup, never
+  exported.
+- `setup` honors `GSTACK_SKIP_GBRAIN_REGEN` (skips the in-place brain regen on dev
+  trees) and writes detection state to a PID-unique tmp so concurrent workspaces
+  cannot clobber it.
+- `scripts/dev-skill.ts` refreshes the workspace render on template change, only
+  when the render dir already exists.
+- `bin/dev-teardown` removes the untracked render.
+
+#### For contributors
+- New tests: `test/gen-skill-docs-out-dir.test.ts` (behavioral: worktree unchanged,
+  blocks rendered, section paths rewritten), `test/dev-setup-render-isolation.test.ts`
+  and `test/gbrain-refresh-install-render.test.ts` (static tripwires), plus
+  `--is-ok` coverage in `test/gbrain-detect-shape.test.ts`.
+
 ## [1.57.8.0] - 2026-06-09
 
 ## **`browse` is now the one Chromium on the box, for offline rendering too.**

CLAUDE.md

@@ -883,6 +883,12 @@ The active skill lives at `~/.claude/skills/gstack/`. After making changes:
 2. Fetch and reset in the skill directory: `cd ~/.claude/skills/gstack && git fetch origin && git reset --hard origin/main`
 3. Rebuild: `cd ~/.claude/skills/gstack && bun run build`
 
+**If you use gbrain:** the `git reset --hard` in step 2 reverts the brain-aware
+(`GBRAIN_CONTEXT_LOAD` / `GBRAIN_SAVE_RESULTS`) blocks that `gstack-config
+gbrain-refresh` renders into the install (those generated blocks differ from
+`main` by design). After deploying, re-run `gstack-config gbrain-refresh` to
+restore them across all your projects' Claude sessions. It's idempotent.
+
 Or copy the binaries directly:
 - `cp browse/dist/browse ~/.claude/skills/gstack/browse/dist/browse`
 - `cp design/dist/design ~/.claude/skills/gstack/design/dist/design`

CONTRIBUTING.md

@@ -106,6 +106,22 @@ bun run build
 bin/dev-teardown
 ```
 
+### Brain-aware blocks in a dev workspace (gbrain installed)
+
+If gbrain is installed and usable (`bin/gstack-gbrain-detect --is-ok` exits 0),
+`bin/dev-setup` keeps your tracked `SKILL.md` files canonical and renders the
+brain-aware variant (the `GBRAIN_CONTEXT_LOAD` / `GBRAIN_SAVE_RESULTS` blocks)
+into `.claude/gstack-rendered/` (gitignored, per-workspace). It then repoints the
+workspace's `SKILL.md` symlinks at that render, so your Claude sessions get the
+full gbrain experience while `git status` stays clean. Under the hood, dev-setup
+passes `GSTACK_SKIP_GBRAIN_REGEN=1` inline to the nested `./setup` (so it never
+dirties tracked source) and runs `gen:skill-docs:user --out-dir .claude/gstack-rendered`,
+which rewrites only the section-base paths to point at the render. `bin/dev-teardown`
+removes the render. To make the blocks live across your *other* projects' Claude
+sessions, run `gstack-config gbrain-refresh`, which renders them into the global
+install (`~/.claude/skills/gstack`), guarded so it never touches a symlinked or
+non-gstack directory.
+
 ## Testing & evals
 
 ### Setup
@@ -334,8 +350,8 @@ If you're using [Conductor](https://conductor.build) to run multiple Claude Code
 
 | Hook | Script | What it does |
 |------|--------|-------------|
-| `setup` | `bin/dev-setup` | Copies `.env` from main worktree, installs deps, symlinks skills, runs `./setup` non-interactively |
-| `archive` | `bin/dev-teardown` | Removes skill symlinks, cleans up `.claude/` directory |
+| `setup` | `bin/dev-setup` | Copies `.env` from main worktree, installs deps, symlinks skills, runs `./setup` non-interactively, and (if gbrain is installed) renders brain-aware blocks into `.claude/gstack-rendered/` without dirtying tracked source |
+| `archive` | `bin/dev-teardown` | Removes skill symlinks, the `.claude/gstack-rendered/` render, and cleans up `.claude/` directory |
 
 When Conductor creates a new workspace, `bin/dev-setup` runs automatically. It detects the main worktree (via `git worktree list`), copies your `.env` so API keys carry over, and sets up dev mode — no manual steps needed.
 

VERSION

@@ -1 +1 @@
-1.57.8.0
+1.57.9.0

bin/dev-setup

@@ -72,12 +72,56 @@ fi
 # no-op skip (no install, no decline marker). A dev workspace must never mutate
 # global settings.json. To install the hooks, run `./setup --plan-tune-hooks`
 # directly (outside dev-setup). Saved prefix/other config preferences still apply.
-"$GSTACK_LINK/setup" --plan-tune-hooks=prompt </dev/null
+#
+# GSTACK_SKIP_GBRAIN_REGEN=1 is passed INLINE (not exported) so it scopes to
+# exactly this nested setup call and can't leak into any other setup path. It
+# tells setup NOT to regenerate the gbrain :user variant into the tracked
+# worktree (that would dirty checked-in source). We render it into an untracked
+# per-workspace dir below instead.
+GSTACK_SKIP_GBRAIN_REGEN=1 "$GSTACK_LINK/setup" --plan-tune-hooks=prompt </dev/null
+
+# 7. Brain-aware (gbrain) blocks — render into an untracked workspace dir.
+#
+# The worktree's SKILL.md files stay canonical (the guard above). If gbrain is
+# installed, render the :user variant (with GBRAIN_CONTEXT_LOAD +
+# GBRAIN_SAVE_RESULTS) into .claude/gstack-rendered (gitignored, per-workspace)
+# and repoint the workspace's SKILL.md symlinks at it. gen-skill-docs --out-dir
+# also rewrites the section-base path so section reads resolve to the render, not
+# the global install. Result: this workspace gets the full gbrain experience
+# while git stays clean. Other projects pick up blocks via `gstack-config
+# gbrain-refresh` (printed below).
+GBRAIN_DETECT="$REPO_ROOT/bin/gstack-gbrain-detect"
+RENDER_DIR="$REPO_ROOT/.claude/gstack-rendered"
+if [ -x "$GBRAIN_DETECT" ] && "$GBRAIN_DETECT" --is-ok 2>/dev/null; then
+  echo ""
+  echo "gbrain detected — rendering brain-aware skills into .claude/gstack-rendered (workspace-only, untracked)..."
+  rm -rf "$RENDER_DIR"
+  if ( cd "$REPO_ROOT" && bun run gen:skill-docs:user --host claude --out-dir "$RENDER_DIR" >/dev/null 2>&1 ); then
+    # Repoint each project-local SKILL.md symlink whose worktree target has a
+    # rendered counterpart. The skill DIRECTORY name (basename of the symlink
+    # target's dir) maps to RENDER_DIR/<dir>/SKILL.md, which is robust to
+    # frontmatter renames and the gstack- prefix on the link name.
+    repointed=0
+    for skill_link in "$REPO_ROOT"/.claude/skills/*/SKILL.md; do
+      [ -L "$skill_link" ] || continue
+      target="$(readlink "$skill_link")"
+      skilldir="$(basename "$(dirname "$target")")"
+      rendered="$RENDER_DIR/$skilldir/SKILL.md"
+      if [ -f "$rendered" ]; then ln -snf "$rendered" "$skill_link"; repointed=$((repointed + 1)); fi
+    done
+    echo "  $repointed workspace skills now serve brain-aware blocks (worktree stays canonical)."
+  else
+    echo "  warning: brain-aware render failed — workspace uses canonical skills."
+  fi
+fi
 
 echo ""
 echo "Dev mode active. Skills resolve from this working tree."
 echo "  .claude/skills/gstack → $REPO_ROOT"
 echo "  .agents/skills/gstack → $REPO_ROOT"
 echo "Edit any SKILL.md and test immediately — no copy/deploy needed."
 echo ""
+echo "To make brain-aware blocks live across your OTHER projects too, run:"
+echo "  gstack-config gbrain-refresh"
+echo ""
 echo "To tear down: bin/dev-teardown"

bin/dev-teardown

@@ -24,9 +24,16 @@ if [ -d "$CLAUDE_SKILLS" ]; then
   fi
 
   rmdir "$CLAUDE_SKILLS" 2>/dev/null || true
-  rmdir "$REPO_ROOT/.claude" 2>/dev/null || true
 fi
 
+# ─── Clean up the untracked brain-aware render (bin/dev-setup step 7) ──
+RENDER_DIR="$REPO_ROOT/.claude/gstack-rendered"
+if [ -d "$RENDER_DIR" ]; then
+  rm -rf "$RENDER_DIR"
+  removed+=("claude/gstack-rendered")
+fi
+rmdir "$REPO_ROOT/.claude" 2>/dev/null || true
+
 # ─── Clean up .agents/skills/ ────────────────────────────────
 AGENTS_SKILLS="$REPO_ROOT/.agents/skills"
 if [ -d "$AGENTS_SKILLS" ]; then

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."

bin/gstack-gbrain-detect

@@ -234,4 +234,14 @@ function main(): void {
   process.stdout.write(JSON.stringify(out, null, 2) + "\n");
 }
 
+// --is-ok: live engine-status gate. Exits 0 iff gbrain is usable ("ok"), 1
+// otherwise. Runs detection live (never reads the possibly-stale
+// gbrain-detection.json), so callers — setup, bin/dev-setup, and
+// `gstack-config gbrain-refresh` — can decide whether to render the gbrain
+// :user variant without duplicating the JSON grep. Prints nothing on stdout.
+if (process.argv.includes("--is-ok")) {
+  const noCache = process.env.GSTACK_DETECT_NO_CACHE === "1";
+  process.exit(localEngineStatus({ noCache }) === "ok" ? 0 : 1);
+}
+
 main();

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gstack",
-  "version": "1.57.8.0",
+  "version": "1.57.9.0",
   "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
   "license": "MIT",
   "type": "module",