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

[harjothkhara]

Summary

On a markdown-only brain (a standard /setup-gbrain outcome — the repo path registered as the markdown default source, no code source), /sync-gbrain Step 4 writes the ## GBrain Search Guidance block into CLAUDE.md 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 — it overlaps the default markdown source at the same path, which gbrain rejects). The agent is then told to use tools that return nothing, and the block silently overwrites any hand-corrected version on every run.

Closes #1844.

Root cause

Step 4 gated the code-search template on the markdown capability round-trip (CAPABILITY_OK) — a put/search/delete check that says nothing about symbol search. Step 3 already computes the code source's page_count but only used it to prompt for a --full reindex; it never fed the Step 4 branch. So page_count=0 still produced full code-search guidance.

What this changes (sync-gbrain/SKILL.md.tmpl, the source of truth)

1. Gate on the real code corpus. Step 4's capability check now also computes the cwd source's CODE_PAGES (reusing Step 3's exact query) and branches on it:

   • CAPABILITY_OK=1 AND CODE_PAGES > 0 → the existing full code + memory block.
   • CAPABILITY_OK=1 AND CODE_PAGES is 0/empty → a new markdown-only block: advertises semantic/keyword search + ~/.gstack/ curated memory, and explicitly routes all code-symbol questions to Grep — no false .gbrain-source / code-def / code-refs / code-callers claims.
   • CAPABILITY_OK=0 → remove the block (unchanged).

2. Drop stale gbrain autopilot --install guidance. That command is gone in gbrain 0.42.x (replaced by sync --watch / sync --install-cron), and on pglite (single-writer) 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.

Verification

• Edited the source-of-truth SKILL.md.tmpl; regenerated SKILL.md with bun run gen:skill-docs. The diff is confined to the two sync-gbrain files, and regeneration is idempotent (a second run is a no-op).
• The new Step 4 bash passes bash -n.
• Relevant suites green: gen-skill-docs, gen-skill-docs-idempotency, gstack-gbrain-sync, no-stale-gstack-brain-refs, audit-compliance, section-manifest-consistency, preamble-compose — 453 tests, 0 fail.

🤖 Generated with Claude Code

[trunk-io]

❌ This pull request has been removed from the merge queue because required statuses are not defined in .trunk/trunk.yaml, your repo's branch protection rules for main, or the merge queue specific settings. See more details here.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

[jbetala7]

Independently reviewed against current main (c43c850c) — looks correct and complete.

Confirmed the bug on main: Step 4 gates the entire ## GBrain Search Guidance block on CAPABILITY_OK alone (sync-gbrain/SKILL.md:949, "If CAPABILITY_OK=1 — write or update the block"). But CAPABILITY_OK is set by a markdown put/search/delete round-trip (:924-937), which proves nothing about symbol search. On a markdown-only brain that block still advertises code-def/code-refs/code-callers and a .gbrain-source pin, none of which resolve. Gating the code-search guidance on CODE_PAGES is the correct signal, and the markdown-only fallback block is the right outcome.

One thing worth calling out as correct, not a smell: the PR recomputes SOURCE_ID + CODE_PAGES in Step 4 even though Step 3 already does the same extraction (:888-893). That's required here — per the repo's own SKILL-authoring rule, each bash block runs in a separate shell and variables don't persist between blocks, so Step 3's $PAGES/$SOURCE_ID aren't visible in Step 4. The grep '"source_id"' | head -1 form is the same one Step 3 already uses, and .gbrain-sync-state.json's source_id is the code stage's source (bin/gstack-gbrain-sync.ts: "Code stage carries source_id + page_count"), so head -1 picks the code source, not the markdown one.

Both sync-gbrain/SKILL.md and sync-gbrain/SKILL.md.tmpl are edited, so check-freshness should confirm no generator drift. Collision check: no competing open PR for #1844 (#1575 also touches sync-gbrain but is the source-fallback filesystem-walk path, unrelated). LGTM.

[harjothkhara]

/trunk merge

[harjothkhara]

These look ready from my side — the branch is clean/mergeable and an independent review confirmed the fix is correct and complete. The only red check is the Trunk merge-queue gate, which from what I can tell just needs a maintainer to enqueue it (no code/test failure). @garrytan whenever you have a moment, could these be added to the merge queue? Happy to rebase if anything is needed. Thanks!