@amg555/frameforge-mcp 2.7.6 → 2.7.7

package/.agent/skills/gstack-sync-gbrain/SKILL.md.tmpl

@@ -1,615 +0,0 @@
----
-name: sync-gbrain
-preamble-tier: 2
-version: 1.0.0
-description: |
-  Keep gbrain current with this repo's code and refresh agent search
-  guidance in CLAUDE.md. Wraps the gstack-gbrain-sync orchestrator with
-  state probing, native code-surface registration, capability checks,
-  and a verdict block. Re-runnable, idempotent. Use when: "sync gbrain",
-  "refresh gbrain", "re-index this repo", "gbrain search isn't finding
-  things". (gstack)
-triggers:
-  - sync gbrain
-  - refresh gbrain
-  - reindex repo
-  - update gbrain
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-
-{{PREAMBLE}}
-
-# /sync-gbrain — Keep gbrain current and teach the agent to use it
-
-You are running the canonical "keep this brain up to date" verb. /setup-gbrain
-installs gbrain once; /sync-gbrain runs every time the user wants the brain
-refreshed against this repo's current state, and refreshes the agent-side
-guidance in CLAUDE.md so the coding agent knows when to prefer `gbrain`
-search over Grep.
-
-**Architecture:** This skill uses gbrain v0.20.0+'s
-**native code surfaces** (`gbrain sources add`, `gbrain sync --strategy code`,
-`gbrain reindex-code`, `gbrain code-def/code-refs/code-callers/code-callees`).
-It does NOT use `gbrain import` (that path is for markdown directories).
-It does NOT touch `~/.gstack/` indexing (the existing `gstack-gbrain-source-wireup`
-owns that — never double-store).
-
-## User-invocable
-
-When the user types `/sync-gbrain`, run this skill. Argument modes (parsed by
-the skill itself, not a dispatcher binary):
-
-- `/sync-gbrain` — incremental sync (default; mtime fast-path; ~50ms steady-state)
-- `/sync-gbrain --full` — full code reindex via `gbrain reindex-code` (~25-35 min on a big repo). Auto-builds the call graph (`gbrain dream --phase resolve_symbol_edges`) **only when it was never built**.
-- `/sync-gbrain --dream` — build this source's call graph (`gbrain code-callers`/`code-callees`) via `gbrain dream --source <id> --phase resolve_symbol_edges`; ~minutes; runs lock-free after the sync stages. Always forces, even if already built. Runs only that phase, never gbrain's full maintenance cycle (about 35 minutes with LLM phases); if the installed gbrain cannot scope the phase, the dream row says so and nothing runs. Only produces a graph on a code-aware schema pack; otherwise the run reports a WARN explaining why the graph is still empty.
-- `/sync-gbrain --no-dream` — skip the dream cycle that `--full` would otherwise auto-run.
-- `/sync-gbrain --code-only` — only run the code stage; skip memory + brain-sync
-- `/sync-gbrain --dry-run` — preview what would sync; no writes anywhere
-- `/sync-gbrain --no-memory` / `--no-brain-sync` — selectively skip stages
-- `/sync-gbrain --sources <types|all>` — memory types to ingest (env `GSTACK_MEMORY_INGEST_SOURCES`); by default, types a federated gstack source already indexes are skipped, and transcripts are skipped unless `transcript_ingest_mode` is `recent` or `all` (a list naming `transcript` overrides that for one run)
-- `/sync-gbrain --quiet` — suppress per-stage output
-- `/sync-gbrain --refresh-cache` — force-rebuild brain-aware planning cache. Skips code + memory stages; routes to `gstack-brain-cache refresh --project <slug>`.
-- `/sync-gbrain --audit` — emit summary of gstack-owned pages per project + sensitive-content audit. Read-only.
-
-Pass-through args go straight to the orchestrator at
-`{{BIN_DIR}}/gstack-gbrain-sync.ts`.
-
-**`--refresh-cache` short-circuit:** when this flag is present, the skill
-runs ONLY the cache refresh (`gstack-brain-cache refresh --project <slug>`
-for the current worktree's slug, plus a cross-project refresh of
-user-profile if `gstack/user-profile/<user-slug>` exists). Code +
-memory + brain-sync stages are skipped. Useful when the user knows the
-brain has new info gstack should pick up before the next planning skill.
-
-**`--audit` short-circuit:** when this flag is present, the skill runs
-`gstack-brain-cache list --project <slug> --json`, summarizes by page
-type, then scans for any cached salience entries that ended up outside
-the SALIENCE_DEFAULT_ALLOWLIST (leak check). Read-only; no
-modifications to brain or cache.
-
----
-
-## Step 1: State probe
-
-Before doing anything, check that /setup-gbrain has been run on this machine.
-
-```bash
-~/.claude/skills/gstack/bin/gstack-gbrain-detect 2>/dev/null
-```
-
-**Brain trust policy gate:**
-If `gbrain_mcp_mode == "remote-http"` from the detect output AND the per-
-endpoint policy is `unset`, the policy question MUST fire here before
-the orchestrator runs. Local engines auto-set to `personal` silently per
-the per-transport default table.
-
-```bash
-_HASH=$(~/.claude/skills/gstack/bin/gstack-config endpoint-hash 2>/dev/null)
-_POLICY=$(~/.claude/skills/gstack/bin/gstack-config get brain_trust_policy@$_HASH 2>/dev/null || echo unset)
-echo "BRAIN_TRUST_POLICY[$_HASH]: $_POLICY"
-```
-
-If `_POLICY == "unset"` AND `_HASH != "local"`, AskUserQuestion per the
-Step 9.5 wording in `/setup-gbrain` (personal vs shared, with persistence
-to `brain_trust_policy@<hash>` and conditional `artifacts_sync_mode=full`
-flip for personal). Then continue.
-
-If `_POLICY == "unset"` AND `_HASH == "local"`, auto-set personal:
-
-```bash
-~/.claude/skills/gstack/bin/gstack-config set brain_trust_policy@$_HASH personal
-```
-
-**Split-engine model.** Code stage runs locally against the
-per-machine gbrain engine (PGLite or whatever `gbrain config` points to),
-with each worktree of a repo registered as its own source. **Memory stage
-also runs locally** in local-stdio MCP mode — `gstack-memory-ingest` shells
-out to `gbrain import` against the same local engine. In remote-http MCP
-mode (Path 4), the memory stage instead persists staged markdown to
-`~/.gstack/transcripts/<run-id>/` and the artifacts pipeline pushes it to
-the brain admin's pull job. Brain-sync (the `gstack-brain-sync`
-push to git) is the one stage that never touches local engine and runs
-regardless of mode.
-
-Practically: local PGLite stays code-only on remote-http machines; the
-remote brain holds everything else. Local-stdio machines mix code +
-transcripts in one local engine.
-
-Also check the per-repo trust policy. If `gstack-gbrain-repo-policy get` for
-this repo returns `deny`, STOP:
-
-> "This repo's gbrain trust policy is `deny`. Run `/setup-gbrain --repo` to
-> change it before syncing."
-
----
-
-## Step 1.5: Local engine pre-flight
-
-Read `gbrain_local_status` from the Step 1 detect output. Branch as follows
-BEFORE invoking the orchestrator:
-
-- **`ok`**: proceed to Step 2 normally.
-- **`timeout`**: proceed to Step 2 — the engine is most likely healthy but
-  slow (cold pooler connection). Tell the user in one line: "Engine
-  probe timed out (>15s) — proceeding; raise `GSTACK_GBRAIN_PROBE_TIMEOUT_MS`
-  if your pooler is slow." Do NOT treat this as a broken config.
-- **`thin-client`**: proceed to Step 2 — this machine is a thin client of a
-  remote-HTTP MCP brain: no local engine BY DESIGN, so the code,
-  memory, and dream stages will SKIP with a thin-client reason (code indexing
-  runs on the brain server; memory syncs via the remote brain's artifacts
-  pull). Only the brain-sync push runs locally. Tell the user in one line:
-  "Thin client of a remote brain — local stages skip by design; brain queries
-  work via remote MCP (reachability is verified at use time, not probed
-  here)." Do NOT route this into the broken-config remediation.
-- **`engine-locked`**: STOP. "The local PGLite database is busy, usually
-  because `gbrain serve` from a live Claude session owns it. Stop that process
-  or run `/sync-gbrain` outside the live session, then retry. This identifies
-  the conflict but does not remove PGLite's single-process limit."
-- **`no-cli`**: STOP. "Local gbrain CLI not installed. Run `/setup-gbrain`
-  first."
-- **`missing-config`** AND `gbrain_mcp_mode == "remote-http"`: tell the user
-  "Your brain queries (the `mcp__gbrain__*` tools) work via remote MCP, but
-  symbol code search needs a local PGLite. Run `/setup-gbrain` and pick
-  'Yes' at the local code-search prompt (Path 4, step 4d), or run
-  `gbrain init --pglite --json --embedding-model voyage:voyage-code-3 --embedding-dimensions 1024`
-  directly (drop the voyage flags if `VOYAGE_API_KEY` isn't set). Continuing
-  without code stage."
-  Then proceed to Step 2 — the orchestrator's `runCodeImport()` and
-  `runMemoryIngest()` will return SKIP; only `runBrainSyncPush()`
-  will run. Do NOT abort.
-- **`missing-config`** AND `gbrain_mcp_mode != "remote-http"`: STOP. "Local
-  gbrain CLI is installed but no engine config. Run `/setup-gbrain` first."
-- **`db-unreachable`**: STOP. Print `gbrain_local_status_detail` from the
-  detect JSON verbatim (for example "database host unreachable (ENOTFOUND
-  db.example.com); your gbrain config is unchanged. Fix: check network or
-  VPN, then re-run /sync-gbrain."). Never suggest moving the config aside.
-- **`broken-config`** OR **`broken-db`**: STOP with a clear message:
-  ```
-  Local gbrain config at ~/.gbrain/config.json points at an unreachable
-  engine (status: {gbrain_local_status}). Two options:
-    1. Re-run /setup-gbrain — Step 1.5 offers Retry / Switch to PGLite /
-       Switch brain mode / Quit.
-    2. Repair manually: mv ~/.gbrain/config.json ~/.gbrain/config.json.bak
-       && gbrain init --pglite --json --embedding-model voyage:voyage-code-3 \
-          --embedding-dimensions 1024   (drop voyage flags if VOYAGE_API_KEY unset)
-  Re-run /sync-gbrain after.
-  ```
-  Do NOT continue — the orchestrator would skip code+memory and only run
-  brain-sync, which is a degraded state the user should fix explicitly.
-
-This pre-flight short-circuits the orchestrator before it spends ~80ms
-probing the engine again. The orchestrator independently runs the same
-classifier for defense-in-depth, but Step 1.5's STOP is where the user
-gets the actionable remediation message.
-
----
-
-## Step 1.6: Transcript consent
-
-Claude Code and Codex session transcripts are ingested only when
-`transcript_ingest_mode` is `recent` (last 90 days), `all` (all history) or
-`new@<UTC time>` (only sessions that start after it), optionally narrowed to
-the repos in `transcript_repos` (the value then ends in `+repos`).
-Skip this step for `--code-only`, `--no-memory`, `--dry-run`,
-`--refresh-cache` and `--audit`. Otherwise check whether the user chose;
-`has` tells an absent key from the `off` default that `get` prints:
-
-```bash
-_TIM=$(~/.claude/skills/gstack/bin/gstack-config get transcript_ingest_mode 2>/dev/null || true)
-if ~/.claude/skills/gstack/bin/gstack-config has transcript_ingest_mode; then
-  _T='[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]t[0-9][0-9]:[0-9][0-9]:[0-9][0-9]z'
-  case "$(printf '%s' "$_TIM" | tr -d '[:space:]' | tr '[:upper:]' '[:lower:]')" in
-    recent|all|off|recent+repos|all+repos|new@$_T|new@$_T+repos)
-      echo "TRANSCRIPT_MODE: $_TIM (repos: $(~/.claude/skills/gstack/bin/gstack-config get transcript_repos 2>/dev/null || true))" ;;
-    *) echo "TRANSCRIPT_MODE: ask (stored value '$_TIM' is not recognized by this version)" ;;
-  esac
-else
-  echo "TRANSCRIPT_MODE: ask (not set)"
-fi
-```
-
-A stored value (`recent`, `all`, `off`, `new@<time>`, any with `+repos`):
-continue to Step 2 without asking. On `ask`, with
-`SESSION_KIND: spawned` or `headless`, do not ask and store nothing: the sync
-skips transcripts and prints how to choose. In an interactive session, ask
-once. Count first (`--sources transcript` counts sessions that are not
-consented yet):
-
-```bash
-bun run ~/.claude/skills/gstack/bin/gstack-memory-ingest.ts --probe --sources transcript
-bun run ~/.claude/skills/gstack/bin/gstack-memory-ingest.ts --probe --sources transcript --all-history
-```
-
-If both report `Total files in window: 0`, ask yes/no: "Ingest coding-agent
-sessions as they appear?" Yes means `recent`, No stores `off`. Otherwise
-AskUserQuestion: name both sources (Claude Code and Codex sessions from every
-project on this machine that repo policy allows), the counts from the two
-probes, and the destination: the local brain (`gbrain_engine` from Step 1:
-PGLite or Supabase) or, in remote-http mode, the artifacts repo the remote
-brain pulls from. Say that a full sync of a large history can take a while
-and skills stay usable meanwhile. Options:
-
-- A) Yes, last 90 days (`recent`)
-- B) Yes, all history (`all`)
-- C) Yes, only new sessions starting now (`new`)
-- E) No, never ingest transcripts (`off`)
-
-On any yes (the yes/no form included), ask a second, separate question:
-"Which repos' sessions?" A) every project repo your repo policy allows, or
-B) only this repo (offer B only when `git remote get-url origin` succeeds).
-Store nothing until both answers are known; a cancel in between stores
-nothing. Then store the scope, then the value (never the letter; `new`
-stores `new@` plus the current UTC time), and continue to Step 2:
-
-```bash
-~/.claude/skills/gstack/bin/gstack-config set transcript_repos "$(git remote get-url origin)"  # only this repo
-~/.claude/skills/gstack/bin/gstack-config unset transcript_repos                                 # every repo
-~/.claude/skills/gstack/bin/gstack-config set transcript_ingest_mode <recent|all|off|new@$(date -u +%Y-%m-%dT%H:%M:%SZ)>
-```
-
-The sync prints what it will ingest, in words; repeat that line to the user.
-
-Other memory types sync whatever the answer. Details:
-`setup-gbrain/memory.md#transcripts`.
-
----
-
-## Step 2: Run the orchestrator
-
-Pass the user's flags to the orchestrator as `<user-args>`, unchanged (empty for a
-plain run). Use them only when every word is one of `--incremental`, `--full`,
-`--dry-run`, `--quiet`, `--no-code`, `--no-memory`, `--no-brain-sync`,
-`--code-only`, `--dream`, `--no-dream`, `--allow-reclone`,
-`--prune-gone-worktrees`, or `--sources` followed by one comma-separated list of
-lowercase memory types (or `all`). Any other value is not used: do not run the
-command; tell the user which value was rejected.
-
-```bash
-bun run ~/.claude/skills/gstack/bin/gstack-gbrain-sync.ts <user-args>
-```
-
-The orchestrator runs three stages: code → memory → brain-sync. Each stage failure is non-fatal; subsequent stages
-still run. State is persisted to `~/.gstack/.gbrain-sync-state.json` via
-tmp-file + atomic rename. Concurrent runs are blocked by a lock file at
-`~/.gstack/.sync-gbrain.lock` (5-min stale-takeover).
-
----
-
-## Step 3: Code-index health check
-
-After the sync run, verify the cwd source registration and its page count:
-
-```bash
-SOURCE_JSON=$(bun run ~/.claude/skills/gstack/bin/gstack-gbrain-read-capability.ts --source-only 2>/dev/null)
-SOURCE_ID=$(printf '%s' "$SOURCE_JSON" | jq -er 'if .status=="source" then .source_id else empty end' 2>/dev/null)
-PAGES=$(printf '%s' "$SOURCE_JSON" | jq -er 'if .status=="source" and (.page_count | type)=="number" then .page_count else empty end' 2>/dev/null)
-echo "cwd source: $SOURCE_ID, page_count: $PAGES"
-```
-
-`--source-only` validates the pretty state schema, writer, successful code stage,
-real worktree path, `.gbrain-source` pin, and gbrain's registration path before
-returning its safe integer page count. It does not read any page. An empty source
-or page count is **unknown**, not zero: report WARN and do not offer a full
-reindex on that evidence. If `PAGES` is proven `0` AND the user did NOT
-pass `--no-code` AND mode was not `--full`, AskUserQuestion via the format in
-the preamble:
-
-> D1 — This repo has 0 indexed pages in gbrain. Run a full code reindex now?
->
-> ELI10: gbrain hasn't indexed this repo's code yet. The semantic search
-> tools (`gbrain search`, `code-def`, `code-refs`) will return nothing
-> until we run a full pass. Takes ~25-35 minutes on a big repo.
->
-> Recommendation: A — the brain is unusable for code search until indexed,
-> and Step 2 of this skill already verified gbrain is configured correctly.
->
-> Note: options differ in kind, not coverage — no completeness score.
->
-> A) Run /sync-gbrain --full now (recommended)
-> B) Skip — I'll run it later
-
-If A: re-invoke the orchestrator with `--full --code-only`.
-If B: continue to Step 4 with the empty-corpus state recorded.
-
----
-
-## Step 3.5: Call-graph health check (offer `--dream`)
-
-`gbrain code-callers` / `code-callees` (who-calls-this / what-this-calls) return
-`count: 0` until a `gbrain dream` cycle runs the `resolve_symbol_edges` phase for
-this source — not done by the code import in Step 2.
-
-**One hard prerequisite:** building a call graph requires this source's active
-**schema pack to extract code symbols** (the `extract_atoms` phase). On a pack
-that doesn't declare it (e.g. `gbrain-base` / `gbrain-base-v2`), a `dream` cycle
-completes but `resolve_symbol_edges` matches nothing — the graph stays empty no
-matter how many times you run it. So "build the call graph" is only meaningful on
-a code-aware pack. The `--dream` stage detects this and reports it honestly
-(a WARN row) rather than claiming a build that didn't happen. `code-def` /
-`code-refs` need the same symbol extraction; they are NOT free "direct lookups"
-on a non-code-aware pack.
-
-A source can also hold no code pages at all while reporting a healthy page count
-(a source added outside gstack syncs with gbrain's default markdown strategy).
-On gbrain 0.60 or later, `code-def` for a symbol that cannot exist answers
-`.status`: `ready` (the source holds code), `out_of_scope` (it holds none, so
-`--dream` cannot help), or nothing usable on older gbrain or an error.
-
-Detect whether this source's call graph is built via doctor's `cycle_freshness`
-check, matching the cwd `SOURCE_ID` literally. `doctor --fast` skips the DB
-checks that carry it, so this reads `--scope=brain` (DB checks, no skill walk):
-
-```bash
-SOURCE_JSON=$(bun run ~/.claude/skills/gstack/bin/gstack-gbrain-read-capability.ts --source-only 2>/dev/null)
-SOURCE_ID=$(printf '%s' "$SOURCE_JSON" | jq -er 'if .status=="source" then .source_id else empty end' 2>/dev/null)
-CYCLE=unknown
-CYCLE_WHY=""
-if [ -n "$SOURCE_ID" ]; then
-  # doctor exits 1 when any check fails; its JSON report is still complete.
-  CYCLE=$(gbrain doctor --json --scope=brain 2>/dev/null \
-    | jq -er --arg id "$SOURCE_ID" '
-        if type!="object" or has("error") then "unknown"
-        else ([.checks[]? | select(.name=="cycle_freshness")][0]) as $c
-          | if $c == null then "unexposed"
-            elif $c.status=="ok" then "completed"
-            else ((($c.message // "") / "; ") | map(select(index("\u0027" + $id + "\u0027"))) | .[0] // "") as $i
-              | if ($i | index("never completed")) then "never"
-                elif ($i | index("last cycled")) then "completed"
-                else "unknown" end end end' 2>/dev/null || echo unknown)
-  if [ "$CYCLE" = unexposed ]; then CYCLE=unknown; CYCLE_WHY="installed gbrain does not expose cycle_freshness"; fi
-fi
-# index() = literal substring (NOT test() regex), matching the lib reader in
-# readCycleStatus(). A fail/warn that doesn't name this source → "unknown"
-# (don't mask other-source failures).
-echo "call graph for $SOURCE_ID: $CYCLE${CYCLE_WHY:+: $CYCLE_WHY}"
-CODE_SCOPE=unknown
-if [ -n "$SOURCE_ID" ]; then
-  CODE_SCOPE=$(gbrain code-def ZzzGstackProbeSymbolThatCannotExist --source "$SOURCE_ID" --limit 1 2>/dev/null \
-    | sed -n '/^[[:space:]]*{/,$p' | jq -r '.status // "unknown"' 2>/dev/null || echo unknown)
-  case "$CODE_SCOPE" in ready|out_of_scope) ;; *) CODE_SCOPE=unknown ;; esac
-fi
-echo "code scope for $SOURCE_ID: $CODE_SCOPE"
-```
-
-If `CODE_SCOPE == out_of_scope`, do not offer a build: report "this source holds
-no code pages (it syncs with gbrain's markdown strategy), so a call-graph build
-cannot help; re-sync it with `gbrain sync --strategy code --source <id>` to index
-its code" and continue to Step 4.
-
-If `CYCLE == never` AND `CODE_SCOPE` is `ready` or `unknown` AND the user did NOT
-pass `--dream`/`--full` AND Step 3 `PAGES > 0`, AskUserQuestion via the format in
-the preamble:
-
-> D2 — This repo's call graph isn't built. Build it now?
->
-> ELI10: `gbrain code-callers`/`code-callees` (who calls this function / what it
-> calls) return nothing until the `resolve_symbol_edges` phase runs for this
-> source. `gbrain dream --source <this source> --phase resolve_symbol_edges`
-> runs only that phase (scoped to this worktree's code, takes a few minutes,
-> not the full ~35-minute maintenance cycle). It only produces a graph if this
-> source's schema pack extracts code symbols; if it doesn't, the run completes
-> but the graph stays empty and the dream row will say so.
->
-> Recommendation: A — call-graph queries return 0 until this runs, and the code
-> index is already populated. If A comes back as a WARN ("pack does not extract
-> code symbols"), the fix is a code-aware schema pack, not re-running dream.
->
-> Note: options differ in kind, not coverage — no completeness score.
->
-> A) Run /sync-gbrain --dream now (recommended)
-> B) Skip — I'll run it later
-
-If A: re-invoke the orchestrator with `--dream --code-only` (skips memory +
-brain-sync; the dream stage still runs because it's gated on `--dream`). Then
-report the dream stage's ACTUAL row — `OK call graph built (N edges)` vs a
-`WARN` that names why the graph is still empty (non-code-aware pack, missing
-embedding key, or 0 edges matched). Do not claim success on a WARN.
-If B: continue to Step 4 with the call-graph-not-built state recorded for the
-verdict.
-
-If `CYCLE == completed` or `unknown`, do not prompt — but note `completed` means
-only that a cycle has run, not that edges exist (a non-code-aware pack reports
-`completed` with an empty graph). Step 5's verdict row surfaces the real state.
-
----
-
-## Step 4: Refresh `## GBrain Search Guidance` block in CLAUDE.md
-
-Capability check:
-
-```bash
-bun run ~/.claude/skills/gstack/bin/gstack-gbrain-read-capability.ts <user-args>
-```
-
-`<user-args>` are the same checked flags this /sync-gbrain invocation passed to
-Step 2, unchanged (empty for a plain run). The helper needs no other input: run it once
-and use its JSON result; do not inspect its source or the gbrain CLI first.
-
-The helper reports JSON `status: ready` only after the successful code sync's
-source and real worktree match `.gbrain-source`, the source registration points
-to that worktree, and a bounded, source-scoped list/get returns the same page.
-It never creates or deletes a page. A `get` may update gbrain's internal
-retrieval metadata; the guarantee is no page or source mutation, not zero
-internal writes. `status: unknown` (including transient CLI errors, stale state,
-or an unverified response) is NOT evidence that the brain is unusable. A
-`status: skipped` result for `--no-code`, `--dry-run`, `--refresh-cache`, or
-`--audit` means no code-read probe was attempted. Do not run a write probe,
-switch to another source, or claim a successful read.
-
-Then update CLAUDE.md based on the helper's status:
-
-**If `status=ready`** — write or update the block. Idempotent: find the
-HTML-comment-delimited block; replace its body if it exists; append at the
-end of CLAUDE.md if it doesn't. NEVER duplicate. Block is machine-AGNOSTIC
-(no engine, no page counts, no last-sync time — those are in the existing
-`## GBrain Configuration` block).
-
-Verbatim block content (copy exactly):
-
-```markdown
-## GBrain Search Guidance (configured by /sync-gbrain)
-<!-- gstack-gbrain-search-guidance:start -->
-
-This worktree's pinned code source answered a source-scoped page read. This
-does not verify semantic search or write availability. Prefer gbrain over Grep
-when the question is semantic or when you don't know the exact identifier yet;
-if a query fails, report that failure rather than assuming the index is healthy.
-
-**This worktree is pinned to a worktree-scoped code source** via the
-`.gbrain-source` file in the repo root (kubectl-style context).
-`gbrain code-def`, `code-refs`, `code-callers`, `code-callees`, `search`, and
-`query` from anywhere under this worktree route to that source by default —
-no `--source` flag needed (gbrain >= 0.41.38.0; on older gbrain the call-graph
-commands need `--source "$(cat .gbrain-source)"`). Conductor sibling worktrees
-of the same repo each have their own pin and their own indexed pages, so
-semantic results match the code on disk here.
-
-Call-graph queries (`code-callers`/`code-callees`) also need the graph to be
-built first. A `count: 0` has several causes, and only one is fixed by
-`/sync-gbrain --dream` (or `--full`): the graph was never built. Check the others
-first: the source may hold no code at all (`gbrain code-def <any-symbol>
---source <id>` answers `status: out_of_scope`), the symbol may be dotted (these
-verbs take a bare name), or `--all-sources` was used. `--dream` also needs a
-schema pack that extracts code symbols; on another pack it completes, the graph
-stays empty and it reports a WARN. `code-def`/`code-refs` need the same
-extraction.
-
-Two indexed corpora available via the `gbrain` CLI:
-- This worktree's code (auto-pinned via `.gbrain-source`).
-- `~/.gstack/` curated memory (registered as `gstack-brain-<user>` source via
-  the existing federation pipeline).
-
-Prefer gbrain when:
-- "Where is X handled?" / semantic intent, no exact string yet:
-    `gbrain search "<terms>"` or `gbrain query "<question>"`
-- "Where is symbol Y defined?" / symbol-based code questions:
-    `gbrain code-def <symbol>` or `gbrain code-refs <symbol>`
-- "What calls Y?" / "What does Y depend on?":
-    `gbrain code-callers <symbol>` / `gbrain code-callees <symbol>`
-- "What did we decide last time?" / past plans, retros, learnings:
-    `gbrain search "<terms>" --source gstack-brain-<user>`
-
-Grep is still right for known exact strings, regex, multiline patterns, and
-file globs. Run `/sync-gbrain` after meaningful code changes; for ongoing
-auto-sync across all worktrees, run `gbrain autopilot --install` once per
-machine — gbrain's daemon handles incremental refresh on a schedule.
-
-Safety: don't run `/sync-gbrain` while `gbrain autopilot` is active — the
-orchestrator refuses destructive source ops when it detects a running autopilot
-to avoid racing it. Prefer registering user repos with `gbrain sources
-add --path <dir>` (no `--url`): URL-managed sources can auto-reclone, and the
-sync code walk for them requires an explicit `--allow-reclone` opt-in.
-
-<!-- gstack-gbrain-search-guidance:end -->
-```
-
-Read CLAUDE.md once and compute its new content. The replacement target is
-the entire region from `<!-- gstack-gbrain-search-guidance:start -->` through
-`<!-- gstack-gbrain-search-guidance:end -->`. If those markers are missing,
-search for `## GBrain Search Guidance (configured by /sync-gbrain)` heading
-and replace from there to the next `## ` or EOF. If no heading exists, append
-the entire block at the end of CLAUDE.md.
-
-**Atomic write (the only write path; do not Edit CLAUDE.md in place):** Write
-the complete new content to `CLAUDE.md.sync-gbrain.tmp` beside it, then `mv` it
-over CLAUDE.md, so a crash mid-write never leaves the file half-modified. Verify
-the block count in the same Bash call as the `mv`, then go to Step 5.
-
-**If `status=unknown`** — preserve the existing guidance block, if any, and
-report the helper's reason as WARN with advice to retry `/sync-gbrain` or the
-read check when the transient failure clears. Do not install new guidance on
-an unknown result or remove the existing guidance merely because this read
-could not verify it. The `## GBrain Configuration` block stays in place.
-
-**If `status=skipped`** — leave guidance unchanged. Report that code readiness
-was not probed in this mode, not that it passed or failed.
-
-Do NOT crash if CLAUDE.md is missing or unwritable — log a warning and
-continue.
-
----
-
-## Step 5: Verdict block (idempotent doctor output)
-
-Print a status block matching `/setup-gbrain` Step 10 conventions. Each row
-is `[OK]/[FIX]/[WARN]/[ERR]`. Reuse `gbrain doctor --json --fast` for
-informational rows but DO NOT gate the guidance block on doctor (doctor
-fails for reasons unrelated to code search).
-
-```
-gbrain status: GREEN
-
-  CLI ............. OK   <gbrain version>
-  Engine .......... OK   <pglite|supabase>
-  Capability ...... OK   source-scoped page read verified (no page/source mutation)
-  CWD source ...... OK   <gstack-code-{repo_slug}> (page_count=<N>)
-  Call graph ...... OK   <N> edges resolved (code-callers/callees live)
-  ~/.gstack source. OK   <gstack-brain-{user}> (page_count=<N>) — managed by /setup-gbrain
-  Memory sync ..... OK   <artifacts_sync_mode>
-  Transcripts ..... OK   <recent|all> | INFO <off|not set>: skipped
-  CLAUDE.md ....... OK   ## GBrain Search Guidance present
-  Last sync ....... OK   <last_sync from state file>
-
-Run `/sync-gbrain` again any time gbrain feels off; safe and idempotent.
-```
-
-The **Call graph** row reports the most authoritative signal available:
-
-1. **If a dream stage ran this invocation** (`--dream`, or `--full` auto-build),
-   mirror its row verbatim — it's the ground truth for this run:
-   - `OK   <N> edges resolved (code-callers/callees live)`
-   - `WARN dream ran but this source's schema pack does not extract code symbols
-     — switch to a code-aware pack (\`gbrain schema use <pack>\`)`
-   - `WARN dream ran but the embed phase failed (missing embedding key)`
-   - `WARN dream ran but resolved 0 edges (no code symbols matched yet)`
-2. **Otherwise** fall back to the `CYCLE` value from Step 3.5, with honest wording
-   (a completed cycle proves a cycle ran, NOT that edges exist):
-   - `completed` → `OK   cycle complete — code-callers/callees live IF this source's pack extracts code symbols`
-   - `never` → `WARN call graph not built — run /sync-gbrain --dream`
-   - `unknown` → `WARN could not probe call graph (doctor unavailable) — run /sync-gbrain --dream if code-callers returns 0`
-
-Any `WARN` Call graph row flips the verdict to YELLOW.
-
-If any row is YELLOW or RED, the verdict line says so and the failing rows
-surface a one-line next action. An unknown read gives `Capability ...... WARN
-source-scoped read unverified; guidance preserved — retry /sync-gbrain` and
-flips the verdict to YELLOW, not RED.
-For a skipped probe, show `Capability ...... WARN  code read not probed in
-this mode; guidance unchanged` and do not print a GREEN capability verdict.
-A `never`/`unknown` Call graph row flips the verdict to YELLOW.
-
----
-
-## Concurrency note
-
-This skill is safe to run concurrently from multiple terminals on the same
-machine. The orchestrator acquires a lock at `~/.gstack/.sync-gbrain.lock` before
-any state-file or CLAUDE.md mutation and exits with code 2 if another sync is
-in flight. Stale locks (process died) auto-clear after 5 minutes.
-
-## Cross-machine note
-
-The `## GBrain Search Guidance` block is committed to the repo's CLAUDE.md
-and travels with `git push`/`git pull` — NOT through `~/.gstack/.brain-allowlist`
-(which is for `~/.gstack/` brain-sync only). On a different machine with a synced
-CLAUDE.md but no local gbrain, /sync-gbrain reports an unknown read and
-preserves the block rather than deleting committed instructions based on a
-transient or machine-local failure. Agents must not treat unknown as ready.
-
-## Status reporting
-
-End with a Completion Status (per the preamble protocol):
-- **DONE** — all stages green, CLAUDE.md guidance block present, verdict GREEN.
-- **DONE_WITH_CONCERNS** — sync ran but at least one stage failed or capability
-  read was unverified. List which and preserve retry guidance.
-- **BLOCKED** — could not acquire lock, gbrain not on PATH, or per-repo policy
-  is deny. State the blocker.
-- **NEEDS_CONTEXT** — /setup-gbrain has not been run, or `gbrain doctor` shows
-  a state that requires user decision (e.g., engine migration).