garrytan · mamedov · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -64,8 +64,8 @@ Invoke them by name (e.g., `/office-hours`).
 | `/benchmark` | Performance regression detection (page load, Core Web Vitals). |
 | `/benchmark-models` | Cross-model benchmark for skills (Claude, GPT, Gemini side-by-side). |
 | `/cso` | OWASP Top 10 + STRIDE security audit. |
-| `/setup-gbrain` | Set up gbrain for cross-machine session memory sync. |
-| `/sync-gbrain` | Keep gbrain current with this repo's code; refresh agent search guidance in CLAUDE.md. |
+| `/setup-gbrain` | Configure gbrain, MCP, and per-repository trust without claiming the current repository index is synced. |
+| `/sync-gbrain` | Sync code and tracked Markdown through strict version/source/path, expected-state, and preview/apply `plan_digest` gates; a missing source needs a registration invocation followed by a sync invocation, and search guidance requires a trusted live HEAD-bound receipt. |
 
 ### Browser + agent integration
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,114 @@
 # Changelog
 
+## [1.63.0.0] - 2026-07-28
+
+## **/sync-gbrain now proves which repository commit it indexed before it calls the result current.**
+
+The repository stage used to make a weak health decision from page count and
+path spelling. A source registered as `.` could later look different from the
+same worktree's absolute path, trigger remove-and-re-add recovery, and come back
+with code indexed but tracked Markdown missing. A successful command could also
+leave later stages to imply everything was healthy without a receipt tied to
+the live Git commit.
+
+The new repository-index stage resolves canonical filesystem identity, keeps
+the source in place, and runs GBrain `0.42.71.0` or newer with the exact HEAD and
+prior bookmark. It validates a dry-run plan, binds apply to the plan's full
+immutable `plan_digest`, and requires the apply result to echo that digest. It
+indexes admitted code and tracked Markdown with strategy `auto`, then writes a
+bounded receipt only after the source, marker, bookmark, strategy, clean HEAD,
+plan binding, and result all verify.
+
+### The numbers that matter
+
+| Contract | Before | v1.63.0.0 |
+|---|---|---|
+| Wrapper dry-run probes or writes | Not clearly bounded | 0 |
+| Source snapshots around apply | Best-effort | 3 strict reads |
+| Affected items stored in the receipt | Unbounded or absent | First 100, plus a digest over all |
+| Preview/apply identity | Unbound | Exact shared 64-character `plan_digest` |
+| Missing-source bootstrap | Register and continue | Register only, stop, then rerun |
+| Required GBrain release | Not pinned to the fix | `0.42.71.0` or newer |
+
+### What this means for builders
+
+Run `/sync-gbrain --code-only` when you want only this worktree's repository
+index. If its source is missing, the first call registers it and stops; run the
+same command again after inspecting the source. `--dry-run` is now explicitly
+an `ORCHESTRATION PREVIEW — unvalidated`: it returns before Git, engine, lock,
+source, or content probes and makes no writes. Use the validated direct GBrain
+preview in `docs/repository-index-recovery.md` when you need to inspect actual
+content operations.
+
+A repository refusal, partial apply, or failed postcondition is terminal.
+Memory ingest, cross-machine artifact sync, attach, cleanup, reindex, and dream
+do not run past it. A dirty worktree may be indexed deliberately, but it cannot
+produce a trusted clean-HEAD receipt.
+
+### Itemized changes
+
+#### Added
+
+- `lib/gbrain-repository-index.ts` implements four-component version parsing,
+  canonical source identity, exact target/bookmark invocation, strict schema-1
+  preview/apply plan binding, bounded receipt evidence, and live receipt
+  verification.
+- `docs/repository-index-recovery.md` documents normal operation, both preview
+  assurance levels, every result/state class, and paste-ready recovery commands.
+- `/sync-gbrain --json` emits one `repository_index` document, while
+  `--verify-receipt` rebinds persisted evidence to the current canonical root,
+  attached source, clean full HEAD, and tracked marker without contacting
+  GBrain.
+
+#### Changed
+
+- Every real repository attempt now writes a fail-closed watermark and removes
+  the prior receipt before the first GBrain probe. A verified result publishes
+  its new receipt while the watermark still blocks readers, then clears the
+  watermark. Failed same-HEAD retries therefore cannot resurrect historical
+  GREEN evidence.
+- The read-only receipt verifier refuses both an active wrapper lock and a
+  superseding attempt watermark before and after its live Git/source checks.
+  Global skill preambles recommend GBrain repository search only when this
+  verifier exits zero for the current clean HEAD; otherwise they explicitly
+  fall back to repository files and `rg`.
+- `/setup-gbrain` now delegates read-write repository setup to the safe
+  repository wrapper. It no longer bypasses the expected-state contract with
+  raw `gbrain import`/background embedding or writes search guidance from a
+  generic engine smoke test.
+- `bin/gstack-gbrain-sync` is now a real executable launcher (and package bin),
+  so generated skills, recovery output, and manual invocations share one
+  runnable entry point.
+- `--code-only` now means “repository-index stage only,” covering both code and
+  tracked Markdown; it no longer implies GBrain strategy `code`.
+- The wrapper requires GBrain `0.42.71.0`, forces multimodal admission off in a
+  copied child environment, and previews strategy `auto` with `--no-pull`,
+  exact target/bookmark checks, and clean-tree enforcement when applicable.
+  Apply receives the preview's exact `--expected-plan-digest`; missing,
+  malformed, changed, or non-echoed plan evidence fails closed.
+- Bounded affected-item hashes bind operation, path, slug, and the rename
+  source path (or an explicit empty field), matching GBrain's schema-1 byte
+  contract.
+- Source-path drift is classified as equivalent, different, or ambiguous.
+  Different or unprovable paths refuse; the wrapper never repairs them by
+  deleting and re-adding the source.
+- Missing sources use a two-invocation bootstrap. The registration call exits
+  incomplete with `state_changed: registry_only`; sync and attach wait for the
+  next invocation.
+- Repository terminal failures stop every later stage. Post-apply failures are
+  reported as `applied_unverified`, never as a rollback or GREEN result.
+- `.gbrain-source` and receipts use wrapper-owned atomic replacement; final
+  source and Git snapshots must still match before cleanup can proceed.
+
+#### Documentation
+
+- README, `USING_GBRAIN_WITH_GSTACK.md`, the generated `/sync-gbrain` skill,
+  error guide, suggestions, and `gstack/llms.txt` now distinguish repository
+  indexing from cross-machine GStack artifact sync and link the recovery guide.
+- Recovery examples validate source/bookmark inputs and quote every shell
+  argument; generated host skills and public catalogs now describe the
+  two-invocation bootstrap and live receipt requirement.
+
 ## [1.60.1.0] - 2026-07-09
 
 ## **The /autoplan dual-voice eval is back on the board, catching real regressions.**

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -982,17 +982,22 @@ enhancement layered on top, never a dependency.)
 ## GBrain Search Guidance (configured by /sync-gbrain)
 <!-- gstack-gbrain-search-guidance:start -->
 
-GBrain is set up and synced on this machine. The agent should prefer gbrain
-over Grep when the question is semantic or when you don't know the exact
-identifier yet.
+This checked-in block is guidance, not proof of live index freshness. Before
+relying on GBrain for this repository, the skill preamble must run
+`./bin/gstack-gbrain-sync --verify-receipt --json --quiet` and observe all
+three exact markers: `"status":"verified"`,
+`"state_changed":"applied_verified"`, and `"trusted":true`. Only then should
+the agent prefer GBrain when the question is semantic or the exact identifier
+is unknown.
 
 **This worktree is pinned to a worktree-scoped code source** via the
 `.gbrain-source` file in the repo root (kubectl-style context). Any
 `gbrain code-def`, `code-refs`, `code-callers`, `code-callees`, or `query`
 call from anywhere under this worktree routes to that source by default —
 no `--source` flag needed. Conductor sibling worktrees of the same repo
 each have their own pin and their own indexed pages, so semantic results
-match the actual code on disk in this worktree.
+are isolated by worktree. The pin alone never proves that indexed content
+matches the current HEAD.
 
 Two indexed corpora available via the `gbrain` CLI:
 - This worktree's code (auto-pinned via `.gbrain-source`).
@@ -1009,15 +1014,10 @@ Prefer gbrain when:
 - "What did we decide last time?" / past plans, retros, learnings:
     `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.
-
-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.
+If receipt verification fails, is unavailable, or does not return all three
+exact markers, use repository files and `rg` instead. Run
+`/sync-gbrain --code-only`; source registration may require one bootstrap
+invocation and a second invocation for the expected-state sync. Re-verify
+after every committed source-code or tracked-Markdown change.
 
 <!-- gstack-gbrain-search-guidance:end -->
diff --git a/README.md b/README.md
@@ -230,7 +230,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan-
 | `/open-gstack-browser` | **GStack Browser** — launch GStack Browser with sidebar, anti-bot stealth, auto model routing (Sonnet for actions, Opus for analysis), one-click cookie import, and Claude Code integration. Clean up pages, take smart screenshots, edit CSS, and pass info back to your terminal. |
 | `/setup-deploy` | **Deploy Configurator** — one-time setup for `/land-and-deploy`. Detects your platform, production URL, and deploy commands. |
 | `/setup-gbrain` | **GBrain Onboarding** — from zero to running gbrain in under 5 minutes. PGLite local, Supabase existing URL, or auto-provision a new Supabase project via Management API. MCP registration for Claude Code + per-repo trust triad (read-write/read-only/deny). [Full guide](USING_GBRAIN_WITH_GSTACK.md). |
-| `/sync-gbrain` | **Keep Brain Current** — re-index this repo's code into gbrain via `gbrain sources add` + `gbrain sync --strategy code`, refresh the `## GBrain Search Guidance` block in CLAUDE.md, and auto-remove guidance when the capability check fails. `--incremental` (default), `--full`, `--dry-run`. Idempotent; safe to re-run. |
+| `/sync-gbrain` | **Keep Repository Index Current** — sync this worktree's code and tracked Markdown through a strict GBrain version/source/path gate, bind the exact HEAD/bookmark, and write a bounded verification receipt. `--code-only` means repository-index stage only. `--dry-run` is an explicitly unvalidated no-probe orchestration preview. [Sync and recovery](docs/repository-index-recovery.md). |
 | `/gstack-upgrade` | **Self-Updater** — upgrade gstack to latest. Detects global vs vendored install, syncs both, shows what changed. |
 | `/ios-qa` | **iOS Live-Device QA (v1.43.0.0+)** — drive a real iPhone over USB CoreDevice via an embedded `StateServer` in the app. Read Swift source, codegen typed `@Observable` accessors, run the agent loop. Optional `--tailnet` flag exposes the device to OpenClaw or any HTTP-capable agent on your Tailscale tailnet so remote agents can run iOS QA without ever touching the hardware. Capability-tier allowlist (observe/interact/mutate/restore), per-device session lock, audit log. |
 | `/ios-fix`, `/ios-design-review`, `/ios-clean`, `/ios-sync` | iOS bug-fix loop, designer's-eye HIG audit, debug-bridge cleanup, and accessor resync. See `docs/skills.md`. End-to-end walkthrough: [docs/howto-ios-testing-with-gstack.md](docs/howto-ios-testing-with-gstack.md). |
@@ -405,7 +405,9 @@ Four paths, pick one:
 
 After init, the skill offers to register gbrain as an MCP server for Claude Code (`claude mcp add gbrain -- gbrain serve`) so `gbrain search`, `gbrain put`, etc. show up as first-class typed tools — not bash shell-outs.
 
-**Keeping the brain current.** Run `/sync-gbrain` from any repo to re-index its code into gbrain (incremental by default, `--full` for a full reindex, `--dry-run` to preview). The skill registers the cwd as a federated source via `gbrain sources add`, runs `gbrain sync --strategy code`, and writes a `## GBrain Search Guidance` block to your project's CLAUDE.md so the agent prefers `gbrain search`/`code-def`/`code-refs` over Grep. The block is removed automatically if the capability check fails — no stale guidance pointing at tools that aren't installed.
+**Keeping the repository index current.** Run `/sync-gbrain` after committed code or tracked Markdown changes. Compatible releases use `gbrain sync --strategy auto --no-pull` with the exact source, canonical worktree root, full HEAD, and prior bookmark. A missing source is registered on the first invocation and deliberately stops before content sync; the second invocation can plan against its real bookmark. For an existing source, the wrapper validates a schema-1 dry-run, passes its full immutable `plan_digest` through `--expected-plan-digest`, and requires apply to echo the same digest. Before its first GBrain probe, every real attempt invalidates the prior receipt with a fail-closed watermark. After clean-HEAD bookmark, strategy, wrapper-owned source-marker attachment, a final strict source reread, bounded affected-item, zero-image-operation, and paired plan checks pass, a fully verified run writes `~/.gstack/.gbrain-repository-index-receipt.json` while the watermark still blocks readers, then clears the watermark to reveal the receipt. Consume it through `/sync-gbrain --verify-receipt --json`, which refuses active lock/watermark state and binds the persisted evidence to the live canonical root and full HEAD.
+
+`/sync-gbrain --dry-run` is only **`ORCHESTRATION PREVIEW — unvalidated`**: it performs no Git, engine, source, path, or content probes. Use the version/source-gated direct GBrain preview in the [repository index sync and recovery guide](docs/repository-index-recovery.md) when you need an actual content plan. GBrain `0.42.71.0` is the paired-release floor.
 
 **Per-remote trust policy.** Each repo on your machine gets one of three tiers:
 
@@ -425,7 +427,7 @@ gstack-brain-init
 
 **Full monty — every scenario, every flag, every bin helper, every troubleshooting step:** [USING_GBRAIN_WITH_GSTACK.md](USING_GBRAIN_WITH_GSTACK.md)
 
-Other references: [docs/gbrain-sync.md](docs/gbrain-sync.md) (sync-specific guide) • [docs/gbrain-sync-errors.md](docs/gbrain-sync-errors.md) (error index)
+Other references: [repository index sync and recovery](docs/repository-index-recovery.md) • [cross-machine GStack artifact sync](docs/gbrain-sync.md) • [artifact-sync error index](docs/gbrain-sync-errors.md)
 
 ## Docs
 
@@ -435,7 +437,8 @@ Other references: [docs/gbrain-sync.md](docs/gbrain-sync.md) (sync-specific guid
 | [Diagrams & Document Formats](docs/howto-diagrams-and-formats.md) | Mermaid/excalidraw fences in PDFs, image sizing and safety defaults, `--to html\|docx`, `/diagram` triplets |
 | [Builder Ethos](ETHOS.md) | Builder philosophy: Boil the Ocean, Search Before Building, three layers of knowledge |
 | [Using GBrain with GStack](USING_GBRAIN_WITH_GSTACK.md) | Every path, flag, bin helper, and troubleshooting step for `/setup-gbrain` |
-| [GBrain Sync](docs/gbrain-sync.md) | Cross-machine memory setup, privacy modes, troubleshooting |
+| [Repository Index Sync and Recovery](docs/repository-index-recovery.md) | Version/source/path gates, preview assurance, receipts, and recovery |
+| [GStack Artifact Sync](docs/gbrain-sync.md) | Cross-machine memory setup, privacy modes, troubleshooting |
 | [Architecture](ARCHITECTURE.md) | Design decisions and system internals |
 | [Browser Reference](BROWSER.md) | Full command reference for `/browse` |
 | [Contributing](CONTRIBUTING.md) | Dev setup, testing, contributor mode, and dev mode |

diff --git a/SKILL.md b/SKILL.md
@@ -339,33 +339,32 @@ else
 fi
 _BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
 _BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
+_GBRAIN_REPOSITORY_SYNC_BIN=~/.claude/skills/gstack/bin/gstack-gbrain-sync
 
-# /sync-gbrain context-load: teach the agent to use gbrain when it's available.
-# Per-worktree pin: post-spike redesign uses kubectl-style `.gbrain-source` in the
-# git toplevel to scope queries. Look for the pin in the worktree (not a global
-# state file) so that opening worktree B without a pin doesn't claim "indexed"
-# just because worktree A was synced. Empty string when gbrain is not
-# configured (zero context cost for non-gbrain users).
+# /sync-gbrain context-load: recommend repository search only when the bounded
+# receipt still verifies against this live canonical worktree and clean HEAD.
+# A .gbrain-source pin or a prior successful receipt is not sufficient.
 _GBRAIN_CONFIG="$HOME/.gbrain/config.json"
-if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
-  _GBRAIN_VERSION_OK=$(gbrain --version 2>/dev/null | grep -c '^gbrain ' || echo 0)
-  if [ "$_GBRAIN_VERSION_OK" -gt 0 ] 2>/dev/null; then
-    _GBRAIN_PIN_PATH=""
-    _REPO_TOP=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
-    if [ -n "$_REPO_TOP" ] && [ -f "$_REPO_TOP/.gbrain-source" ]; then
-      _GBRAIN_PIN_PATH="$_REPO_TOP/.gbrain-source"
-    fi
-    if [ -n "$_GBRAIN_PIN_PATH" ]; then
-      echo "GBrain configured. Prefer \`gbrain search\`/\`gbrain query\` over Grep for"
-      echo "semantic questions; use \`gbrain code-def\`/\`code-refs\`/\`code-callers\` for"
-      echo "symbol-aware code lookup. See \"## GBrain Search Guidance\" in CLAUDE.md."
-      echo "Run /sync-gbrain to refresh."
-    else
-      echo "GBrain configured but this worktree isn't pinned yet. Run \`/sync-gbrain --full\`"
-      echo "before relying on \`gbrain search\` for code questions in this worktree."
-      echo "Falls back to Grep until pinned."
+if [ -f "$_GBRAIN_CONFIG" ]; then
+  _GBRAIN_RECEIPT_JSON=""
+  _GBRAIN_RECEIPT_OK=0
+  if command -v gbrain >/dev/null 2>&1 && [ -x "$_GBRAIN_REPOSITORY_SYNC_BIN" ]; then
+    if _GBRAIN_RECEIPT_JSON=$("$_GBRAIN_REPOSITORY_SYNC_BIN" --verify-receipt --json --quiet 2>/dev/null); then
+      _GBRAIN_RECEIPT_OK=1
     fi
   fi
+  if [ "$_GBRAIN_RECEIPT_OK" = "1" ] &&
+     printf '%s' "$_GBRAIN_RECEIPT_JSON" | grep -Fq '"status":"verified"' &&
+     printf '%s' "$_GBRAIN_RECEIPT_JSON" | grep -Fq '"state_changed":"applied_verified"' &&
+     printf '%s' "$_GBRAIN_RECEIPT_JSON" | grep -Fq '"trusted":true'; then
+    echo "GBrain receipt verified for this clean HEAD. Prefer \`gbrain search\`/\`gbrain query\`"
+    echo "for semantic questions and \`gbrain code-def\`/\`code-refs\`/\`code-callers\`"
+    echo "for symbol-aware lookup. See \"## GBrain Search Guidance\" in CLAUDE.md."
+  else
+    echo "GBrain is not receipt-verified for this worktree's current clean HEAD."
+    echo "Use repository files and \`rg\`; run \`/sync-gbrain --code-only\` before relying"
+    echo "on GBrain repository search."
+  fi
 fi
 
 _BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)