v1.26.3.0 feat: /sync-gbrain skill + native code-surface orchestrator

[garrytan]

Summary

Two functional gaps closed in one ship. The cwd repo wasn't actually being indexed by gbrain (the orchestrator called gbrain import which only handles markdown directories, not code), and the coding agent had no idea gbrain existed in any session that didn't explicitly opt in.

• /sync-gbrain skill (new top-level): wraps the orchestrator with state probing, capability check (write+search round-trip, NOT gbrain doctor), CLAUDE.md guidance lifecycle (write iff healthy, remove iff broken), per-source verdict block. Idempotent, re-runnable.
• Native code-surface orchestrator: bin/gstack-gbrain-sync.ts switches from gbrain import (markdown only) to gbrain sources add + gbrain sync --strategy code (incremental) or gbrain reindex-code --yes (--full). Idempotent source registration via the new lib/gbrain-sources.ts helper. Lock file + tmp+atomic-rename for state file. Dry-run skips both writes.
• Live preamble injection (scripts/resolvers/preamble/generate-brain-sync-block.ts): every gstack skill start emits a 4-line "prefer gbrain over Grep" hint when capability is healthy and cwd page_count > 0; emits a 3-line emergency hint when corpus is empty; resolves to empty string when gbrain isn't configured (zero context tax for non-gbrain users).
• ## GBrain Search Guidance CLAUDE.md block written by /setup-gbrain Step 8 (gated on smoke test) and by /sync-gbrain (gated on capability check). Machine-agnostic content; HTML-comment delimited so removal regex never eats user content.

7 commits, ~1.5K lines added. The previously-deferred V1.5 P0 watch daemon can wire through to gbrain v0.25.1's native gbrain sync --watch rather than building gstack-side.

Test Coverage

• 9 new unit tests in test/gbrain-sources.test.ts covering ensureSourceRegistered (4 cases: absent, no-op-match, drift recreate, no-reregister-on-drift), probeSource (2), sourcePageCount (3). Fake gbrain shell script on PATH via test-only env parameter (Bun's execFileSync caches PATH at process start; explicit env is the only reliable redirect).
• 12 tests in test/gstack-gbrain-sync.test.ts (was 8) — adds source-id derivation, dry-run no-lock, stale-lock takeover, fresh-lock blocking, all using the post-codex native surface.
• Preamble resolver covered indirectly via gen-skill-docs + manual 3-state smoke test (Variant A, Variant B, empty).
• test/skill-e2e-memory-pipeline.test.ts updated to assert would: gbrain sources add instead of would: gbrain import.
• All 3 ship golden fixtures (test/fixtures/golden/{claude,codex,factory}-ship-SKILL.md) refreshed.
• Coverage: ~12/13 paths tested (92%). Single gap: live --full against real gbrain DB — gbrain is mid-migration on this Mac (config points at unreachable localhost:5435), so live exercise is deferred to CI/post-merge.

Tests: 720 → 729 free tests pass on merged code (bun test exit 0).

Pre-Landing Review

No findings. New TypeScript uses execFileSync with explicit timeouts and structured error handling. Bash in resolver uses strict quoting and [ ] tests. Lock file uses wx flag for atomic create. No SQL, no auth surfaces, no LLM trust violations.

Plan Completion

• ✅ /sync-gbrain skill (template + per-host SKILL.md generated)
• ✅ Native code-surface orchestrator (gbrain sources add + sync --strategy code)
• ✅ lib/gbrain-sources.ts DRY extraction (eng-review D3)
• ✅ Lock file + tmp+rename atomicity (eng-review D1)
• ✅ Dry-run skips writes (eng-review D2)
• ✅ Capability check, NOT gbrain doctor (codex M7)
• ✅ HTML-comment delimited CLAUDE.md guidance block, machine-agnostic
• ✅ Preamble Variant A / Variant B / empty
• ❌ REJECTED post-codex (correctly absent from diff): .brainignore, double-indexing ~/.gstack, gbrain doctor as gate

8/8 accepted plan items DONE.

Verification Results

Skipped — no dev server running (gbrain DB on this Mac is unreachable due to config drift, unrelated to this PR). The dry-run smoke test on this repo confirms source-id derivation (gstack-code-github.com-garrytan-gstack), three-stage preview, no writes. Live --full exercise will run post-merge.

TODOS

No items completed by this PR.

Documentation

Docs synced for v1.26.3.0:

• README.md: added /sync-gbrain to the Power tools table; added a "Keeping the brain current" paragraph in the GBrain section explaining the gbrain sources add + gbrain sync --strategy code flow and the auto-removed ## GBrain Search Guidance block; added /sync-gbrain to the CLAUDE.md available-skills snippet.
• AGENTS.md + docs/skills.md: registered /sync-gbrain (already landed in 7414f45).
• CHANGELOG.md: v1.26.3.0 entry covers the full scope.
• VERSION: 1.26.3.0, covers all branch changes.

Test plan

• All free tests pass (bun test exit 0)
• bun run gen:skill-docs --host all clean
• /sync-gbrain --dry-run smoke test on this repo: source-id derived, three stages preview, no writes
• Bash preamble manual smoke test confirms Variant A on page_count > 0, Variant B on missing/zero, empty on no gbrain
• Post-merge: live /sync-gbrain --full against a healthy gbrain DB; confirm gbrain code-def detectEngineTier returns the function from lib/gstack-memory-helpers.ts

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith with what you need.}

• Let Codesmith autofix CI failures and bot reviews

[github-actions]

E2E Evals: ✅ PASS

61/61 tests passed | $9.14 total cost | 12 parallel runners

Suite	Result	Status	Cost
e2e-browse	4/4	✅	$0.18
e2e-deploy	6/6	✅	$1.16
e2e-design	4/4	✅	$0.83
e2e-plan	8/8	✅	$1.82
e2e-qa-workflow	3/3	✅	$1.15
e2e-review	6/6	✅	$1.99
e2e-workflow	3/3	✅	$0.38
llm-judge	24/24	✅	$0.48
e2e-qa-workflow	3/3	✅	$1.15

---

12x ubicloud-standard-2 (Docker: pre-baked toolchain + deps) | wall clock ≈ slowest suite