/sync-gbrain Step 4 writes false code-search guidance into CLAUDE.md on markdown-only brains
- Dominant language
- TypeScript
- Stars
- 133k
- Forks
- 19.9k
- Avg merge
- 18h 46m
- Merged PRs (30d)
- 26
Description
## Summary
On a markdown-only brain (no registered code source), `/sync-gbrain` Step 4 writes the `## GBrain Search Guidance` block into the user's CLAUDE.md claiming working `.gbrain-source` pins and `gbrain code-def`/`code-refs`/`code-callers` symbol search. None of that resolves against anything — the code source never registered. The agent is then instructed to use tools that return nothing, and the block silently overwrites any hand-corrected version on every run.
## Environment
- gstack v1.55.0.0
- gbrain 0.42.8.0, engine pglite (local-stdio MCP), macOS
- Brain: single `default` markdown source at the repo path; `~/.gstack/` artifacts; no code source
## Repro
1. Have a brain where the repo path is registered as the markdown `default` source (a standard `/setup-gbrain` outcome).
2. Run `/sync-gbrain`. The orchestrator's code stage fails:
```
ERR code source registration failed: gbrain sources add
gstack-code-… failed: path "/…/repo" overlaps with existing source
"default" at "/…/repo". Overlapping sources are not allowed.
```
3. Step 4's capability check (`CAPABILITY_OK`) still passes — it only tests a markdown `put`/`search`/`delete` round-trip, which works.
4. Because `CAPABILITY_OK=1`, Step 4 writes the verbatim template asserting code-symbol search. The block now tells the agent to use `code-def` etc., which have a 0-page corpus.
## Root cause
Step 4 gates the code-search template on the **markdown** capability check, not on whether the **code source** actually registered. Step 3 already computes the code source `page_count`, but only uses it to *prompt for a `--full` reindex* — it doesn't feed the Step 4 branch. So `page_count=0` still yields code-search guidance.
Compounding: a code source can't even register when it overlaps the `default` markdown source at the same path (the error above), so on these brains code search is structurally impossible — yet the guidance claims it works.
## Suggested fix
Gate the code-search portion of the Step 4 template on the code source's real `page_count` (already available from Step 3), not on `CAPABILITY_OK`:
- code source `page_count > 0` → write the full template (code + memory).
- code source absent / `page_count == 0` → write a markdown-only variant (semantic/keyword search + `~/.gstack/` memory; point code-symbol questions at Grep).
Optionally, when the code stage fails with the overlap error, surface it as a real warning instead of letting Step 4 paper over it.
## Secondary: stale template content
The current template recommends `gbrain autopilot --install` for "ongoing auto-sync," and the "Safety" note warns about a running `gbrain autopilot`. The `autopilot` command is gone in gbrain 0.42.x (replaced by `sync --watch` / `sync --install-cron`). On pglite (single-writer) a background sync daemon also can't coexist with an always-on MCP `gbrain serve` — that combination crash-loops. The template should drop the `autopilot --install` guidance.
Contributor guide
Assessment
This issue has not been assessed yet.