garrytan / garrytan/gstack

/sync-gbrain Step 4 writes false code-search guidance into CLAUDE.md on markdown-only brains

Open
#1,844 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.