fix(gbrain): bind source mutations to canonical identity

[mamedov]

Summary

• compare registered GBrain sources by canonical filesystem identity, so equivalent relative, absolute, symlink, junction, and case-variant spellings remain a no-op
• bind every source remove/add, legacy cleanup, sync, pin, and dream operation to authoritative source provenance plus stable pre/post identity checks
• fail closed before destructive mutation when a path is missing, ambiguous, rebound, cross-volume, remotely managed, or no longer matches the recorded source row
• require GBrain 0.41.38.0+, the first release with the provenance, source-scoped dream, and pin-aware code graph behavior this workflow relies on
• document the version recovery path and source-identity safety contract

This is the source-identity and destructive-safety slice split from #2377. The adjacent docs-aware sync --strategy auto work remains a separate PR.

Why the diff is larger than a path helper

The initial equivalence fix exposed two destructive seams during independent correctness and security review: a source row could change between planning and cleanup, and local pin/gitignore writes could follow a replaced filesystem object. Keeping the fix safe required carrying the proven path through orchestration, rereading the authoritative registry around mutations, and making local writes atomic and symlink-safe. The expanded diff stays on one concern: a source operation must act only on the exact filesystem and registry identity it proved.

Verification

Current HEAD: 46ba3aa2412ed399dc2d5645e47f7f20950903ad

• bun test test/gbrain-sources-parse.test.ts test/gbrain-sources.test.ts test/gbrain-guards.test.ts test/gstack-gbrain-sync.test.ts test/gbrain-dream-stage.test.ts test/gbrain-source-gitignore.test.ts test/gbrain-detect-install.test.ts test/gbrain-sync-skip.test.ts test/gbrain-exec-invariant.test.ts test/gbrain-spawn-windows-shell.test.ts — 217 passed, 0 failed, 596 assertions
• bun test test/gstack-gbrain-source-wireup.test.ts test/gen-skill-docs.test.ts — 421 passed, 0 failed, 6,464 assertions
• bun test test/gbrain-detect-install.test.ts test/gstack-gbrain-sync.test.ts — 63 passed, 0 failed, 239 assertions
• bun run build — passed; the existing Factory gstack-ship token-ceiling warning remains non-fatal
• git diff --check origin/main...HEAD — passed
• independent correctness and security reviews — no remaining findings

bun run test:evals selected 11 broad LLM routing scenarios, but this environment has no Claude credentials. Every failure artifact reports Not logged in, zero tool calls, zero tokens, and $0.00; the failing suites and runners are unchanged from origin/main, and the changed sync-gbrain skill is not installed by those journey fixtures. Deterministic branch-owned tests above are green.

Documentation

• sync-gbrain/SKILL.md.tmpl and generated sync-gbrain/SKILL.md: document canonical identity, fail-closed drift handling, and the hard 0.41.38.0 floor
• USING_GBRAIN_WITH_GSTACK.md: add operator recovery, code-stage safety semantics, installer reference, and troubleshooting
• no VERSION or CHANGELOG change: upstream batches release metadata separately

Coverage: the changed source-identity and minimum-version surfaces have reference, how-to, and explanation coverage. No architecture diagram drift or new documentation debt was found.

Tracking

Basecamp: https://3.basecamp.com/4058523/buckets/34718435/card_tables/cards/10157486137

[trunk-io]

Merging to main in this repository is managed by Trunk.

• 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