RomanNum3ral
/
gstack
mirror of https://github.com/garrytan/gstack.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

fix(sync-gbrain): gate code-search guidance on real page_count, not the markdown capability check (#1844) 

On a markdown-only brain (no registered code source), /sync-gbrain Step 4 wrote
the `## GBrain Search Guidance` block claiming working `.gbrain-source` pins and
`code-def`/`code-refs`/`code-callers` symbol search. None of that resolves —
the code source never registered (and structurally can't, when its path overlaps
the `default` markdown source). The block then instructs the agent to use tools
that return nothing, and silently overwrites any hand-corrected version on every
run.

Root cause: Step 4 gated the code-search template on the *markdown* capability
round-trip (`CAPABILITY_OK`), which only proves `put`/`search`/`delete` work —
nothing about symbol search. Step 3 already computes the code source page_count
but only used it to prompt for a `--full` reindex.

- Compute the cwd source's `CODE_PAGES` in Step 4's check and branch on it:
  `CAPABILITY_OK=1 AND CODE_PAGES>0` → full code+memory block (unchanged);
  `CAPABILITY_OK=1 AND CODE_PAGES==0/empty` → new markdown-only block that
  advertises semantic/keyword search + `~/.gstack/` memory and routes all
  code-symbol questions to Grep (no false `.gbrain-source`/`code-def` claims);
  `CAPABILITY_OK=0` → remove block (unchanged).
- Drop stale `gbrain autopilot --install` guidance: the command is gone in
  gbrain 0.42.x, and on pglite a background sync daemon can't coexist with an
  always-on MCP `gbrain serve`. The `/sync-gbrain`-after-changes guidance and
  the still-valid `sources add --path` safety note remain.

Edited the source-of-truth `SKILL.md.tmpl`; regenerated `SKILL.md` via
`bun run gen:skill-docs` (idempotent — re-run is a no-op).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
harjoth 2026-06-02 22:21:06 -07:00
parent 3bef43bc5a
commit ecd361c3ae
2 changed files with 122 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
sync-gbrain/SKILL.md
View File

@ -942,17 +942,30 @@ if [ -f ~/.gbrain/config.json ] && \
fi
fi
gbrain delete "$SLUG" 2>/dev/null || true
# Code-corpus check (#1844). The round-trip above only proves the *markdown*
# put/search path works — it says nothing about symbol search. code-def /
# code-refs / code-callers need a registered code source with indexed pages.
# On a markdown-only brain (no code source, or one that can't register because
# its path overlaps the `default` markdown source) this is 0, so the
# code-search guidance must gate on it, not on CAPABILITY_OK.
SOURCE_ID=$(grep -o '"source_id":"[^"]*"' ~/.gstack/.gbrain-sync-state.json 2>/dev/null \
| head -1 | sed 's/.*"source_id":"//;s/".*//')
CODE_PAGES=$(gbrain sources list --json 2>/dev/null \
| jq -r --arg id "$SOURCE_ID" '.sources[] | select(.id==$id) | .page_count' 2>/dev/null \
|| echo 0)
[ -z "$CODE_PAGES" ] && CODE_PAGES=0
```
Then update CLAUDE.md based on capability state:
Then update CLAUDE.md based on capability state **and whether an indexed code
corpus exists** (`CODE_PAGES` from the check above). In every write case the
block is 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. The
block is machine-AGNOSTIC (no engine, no page counts, no last-sync time — those
live in the existing `## GBrain Configuration` block).
**If `CAPABILITY_OK=1`** — 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):
**If `CAPABILITY_OK=1` AND `CODE_PAGES` > 0** — full code + memory brain. Write
or update the block with this verbatim content (copy exactly):
```markdown
## GBrain Search Guidance (configured by /sync-gbrain)
@ -986,15 +999,47 @@ Prefer gbrain when:
`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.
file globs. Run `/sync-gbrain` after meaningful code changes to refresh the
index.
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 (#1734). 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.
Safety: 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 -->
```
**If `CAPABILITY_OK=1` AND `CODE_PAGES` is 0 or empty** — markdown-only brain.
gbrain works, but there is no indexed code source: symbol search resolves
against a 0-page corpus and there is no `.gbrain-source` worktree pin. Do NOT
claim `code-def` / `code-refs` / `code-callers` / `.gbrain-source` here — they
return nothing. Write or update the block with this markdown-only content
instead (copy exactly):
```markdown
## GBrain Search Guidance (configured by /sync-gbrain)
<!-- gstack-gbrain-search-guidance:start -->
GBrain is set up and synced on this machine, indexing **markdown/prose only** —
there is no registered code source, so symbol search is unavailable here. Prefer
gbrain over Grep for semantic questions and past decisions; use Grep for code.
One indexed corpus available via the `gbrain` CLI:
- `~/.gstack/` curated memory (registered as `gstack-brain-<user>` source via
the existing federation pipeline) — plans, retros, learnings, notes.
Prefer gbrain when:
- "What did we decide / learn last time?" / past plans, retros, learnings:
`gbrain search "<terms>"` or `gbrain query "<question>"`
(add `--source gstack-brain-<user>` to scope to curated memory).
Use Grep for ALL code questions — "where is X handled?", "where is symbol Y
defined?", "what calls Y?". The `code-def`, `code-refs`, `code-callers`, and
`code-callees` commands resolve against a 0-page corpus on this brain and return
nothing; there is no `.gbrain-source` worktree pin.
To enable code-symbol search, register a code source whose path does not overlap
the existing markdown `default` source, then run `/sync-gbrain --full`.
<!-- gstack-gbrain-search-guidance:end -->
```

77
sync-gbrain/SKILL.md.tmpl
View File

@ -247,17 +247,30 @@ if [ -f ~/.gbrain/config.json ] && \
fi
fi
gbrain delete "$SLUG" 2>/dev/null || true
# Code-corpus check (#1844). The round-trip above only proves the *markdown*
# put/search path works — it says nothing about symbol search. code-def /
# code-refs / code-callers need a registered code source with indexed pages.
# On a markdown-only brain (no code source, or one that can't register because
# its path overlaps the `default` markdown source) this is 0, so the
# code-search guidance must gate on it, not on CAPABILITY_OK.
SOURCE_ID=$(grep -o '"source_id":"[^"]*"' ~/.gstack/.gbrain-sync-state.json 2>/dev/null \
| head -1 | sed 's/.*"source_id":"//;s/".*//')
CODE_PAGES=$(gbrain sources list --json 2>/dev/null \
| jq -r --arg id "$SOURCE_ID" '.sources[] | select(.id==$id) | .page_count' 2>/dev/null \
|| echo 0)
[ -z "$CODE_PAGES" ] && CODE_PAGES=0
```
Then update CLAUDE.md based on capability state:
Then update CLAUDE.md based on capability state **and whether an indexed code
corpus exists** (`CODE_PAGES` from the check above). In every write case the
block is 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. The
block is machine-AGNOSTIC (no engine, no page counts, no last-sync time — those
live in the existing `## GBrain Configuration` block).
**If `CAPABILITY_OK=1`** — 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):
**If `CAPABILITY_OK=1` AND `CODE_PAGES` > 0** — full code + memory brain. Write
or update the block with this verbatim content (copy exactly):
```markdown
## GBrain Search Guidance (configured by /sync-gbrain)
@ -291,15 +304,47 @@ Prefer gbrain when:
`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.
file globs. Run `/sync-gbrain` after meaningful code changes to refresh the
index.
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 (#1734). 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.
Safety: 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 -->
```
**If `CAPABILITY_OK=1` AND `CODE_PAGES` is 0 or empty** — markdown-only brain.
gbrain works, but there is no indexed code source: symbol search resolves
against a 0-page corpus and there is no `.gbrain-source` worktree pin. Do NOT
claim `code-def` / `code-refs` / `code-callers` / `.gbrain-source` here — they
return nothing. Write or update the block with this markdown-only content
instead (copy exactly):
```markdown
## GBrain Search Guidance (configured by /sync-gbrain)
<!-- gstack-gbrain-search-guidance:start -->
GBrain is set up and synced on this machine, indexing **markdown/prose only** —
there is no registered code source, so symbol search is unavailable here. Prefer
gbrain over Grep for semantic questions and past decisions; use Grep for code.
One indexed corpus available via the `gbrain` CLI:
- `~/.gstack/` curated memory (registered as `gstack-brain-<user>` source via
the existing federation pipeline) — plans, retros, learnings, notes.
Prefer gbrain when:
- "What did we decide / learn last time?" / past plans, retros, learnings:
`gbrain search "<terms>"` or `gbrain query "<question>"`
(add `--source gstack-brain-<user>` to scope to curated memory).
Use Grep for ALL code questions — "where is X handled?", "where is symbol Y
defined?", "what calls Y?". The `code-def`, `code-refs`, `code-callers`, and
`code-callees` commands resolve against a 0-page corpus on this brain and return
nothing; there is no `.gbrain-source` worktree pin.
To enable code-symbol search, register a code source whose path does not overlap
the existing markdown `default` source, then run `/sync-gbrain --full`.
<!-- gstack-gbrain-search-guidance:end -->
```