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>

test/gbrain-detect-shape.test.ts

@@ -16,7 +16,7 @@
  */
 
 import { describe, it, expect } from "bun:test";
-import { execFileSync } from "child_process";
+import { execFileSync, spawnSync } from "child_process";
 import {
   mkdtempSync,
   mkdirSync,
@@ -47,6 +47,16 @@ function runDetect(env: Partial<NodeJS.ProcessEnv>): string {
   });
 }
 
+/** Run detect with --is-ok and return its exit code (never throws). */
+function runIsOk(env: Partial<NodeJS.ProcessEnv>): number {
+  const r = spawnSync(BUN_BIN, ["run", DETECT_BIN, "--is-ok"], {
+    timeout: 15_000,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, ...env },
+  });
+  return r.status ?? 1;
+}
+
 interface DetectShape {
   gbrain_on_path: boolean;
   gbrain_version: string | null;
@@ -244,3 +254,66 @@ exit 0
     }
   });
 });
+
+describe("bin/gstack-gbrain-detect --is-ok — live gate", () => {
+  it("exits non-zero when gbrain is not on PATH (no-cli)", () => {
+    const tmp = mkdtempSync(join(tmpdir(), "detect-isok-"));
+    try {
+      const code = runIsOk({
+        HOME: tmp,
+        PATH: "/usr/bin:/bin", // no gbrain
+        GSTACK_HOME: tmp,
+        GSTACK_DETECT_NO_CACHE: "1",
+      });
+      expect(code).not.toBe(0);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("exits 0 when a fake gbrain reports a healthy engine (ok)", () => {
+    const tmp = mkdtempSync(join(tmpdir(), "detect-isok-"));
+    const bindir = join(tmp, "bin");
+    const home = join(tmp, "home");
+    const configDir = join(home, ".gbrain");
+    try {
+      mkdirSync(bindir, { recursive: true });
+      mkdirSync(configDir, { recursive: true });
+      writeFileSync(join(configDir, "config.json"), JSON.stringify({ engine: "pglite" }));
+      const fake = `#!/bin/sh
+case "$1 $2" in
+  "--version ")        echo "gbrain 0.33.1.0"; exit 0 ;;
+  "sources list")      echo '{"sources":[]}'; exit 0 ;;
+  "doctor "*)          echo '{"status":"ok","checks":[]}'; exit 0 ;;
+esac
+exit 0
+`;
+      const gbrainPath = join(bindir, "gbrain");
+      writeFileSync(gbrainPath, fake);
+      chmodSync(gbrainPath, 0o755);
+
+      const code = runIsOk({
+        HOME: home,
+        PATH: `${bindir}:/usr/bin:/bin`,
+        GSTACK_HOME: tmp,
+        GSTACK_DETECT_NO_CACHE: "1",
+      });
+      expect(code).toBe(0);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("exit code agrees with the JSON gbrain_local_status (no skew)", () => {
+    // Run both surfaces against the same env and assert they never disagree.
+    const tmp = mkdtempSync(join(tmpdir(), "detect-isok-"));
+    try {
+      const env = { HOME: tmp, PATH: "/usr/bin:/bin", GSTACK_HOME: tmp, GSTACK_DETECT_NO_CACHE: "1" };
+      const status = (JSON.parse(runDetect(env)) as DetectShape).gbrain_local_status;
+      const code = runIsOk(env);
+      expect(code === 0).toBe(status === "ok");
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});