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

Merge remote-tracking branch 'origin/main' into garrytan/eng-review-askuser-fix 

# Conflicts:
#	test/helpers/touchfiles.ts
This commit is contained in:
Garry Tan 2026-05-06 19:49:28 -07:00
parent 3aee5a7476 f44de365c5
commit 2d400fbc85
No known key found for this signature in database
GPG Key ID: C1F69E85C74EFE1D
86 changed files with 6010 additions and 1290 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

209
CHANGELOG.md
View File

@ -1,5 +1,214 @@
# Changelog
## [1.27.0.0] - 2026-05-06
## **`/setup-gbrain` connects to a remote brain in one paste. Brain repo renamed to gstack-artifacts.**
`/setup-gbrain` now has a fourth path: paste a remote MCP URL plus a bearer
token, and the skill registers it as your gbrain MCP without provisioning a
local brain DB. No PGLite to install, no Supabase project to set up. Just
point this Mac at a brain that already runs somewhere else (Tailscale node,
ngrok endpoint, internal LAN, a teammate's server) and you have search +
write working in one Claude Code session restart. The same flow optionally
provisions a private `gstack-artifacts-$USER` repo on GitHub OR GitLab so
the remote brain can ingest your CEO plans, designs, and reports as a
federated source. The renamed repo replaces `gstack-brain-$USER` with a
clearer name; existing users get a journaled, interruption-safe migration
that handles the GitHub repo rename, the on-disk file moves, the config
key rewrite, and the gbrain federated-source swap (add-new-before-remove-old,
no downtime window).
### The numbers that matter
Verified end-to-end against a live remote brain (wintermute on Tailscale,
gbrain v0.27.1, 96K pages) plus the new test suite:
| Surface | Before | After | Δ |
|---|---|---|---|
| `/setup-gbrain` paths | 3 (Supabase / PGLite / Switch) | 4 (Supabase / PGLite / Switch / Remote MCP) | +1 path, no local install required |
| Time to working remote MCP | manual `claude mcp add --transport http`, then skip the rest of the skill | one Path 4 walkthrough, full verify + artifact-repo provision | ~30 sec setup, agent guided |
| Verify failure modes classified | none (raw curl error) | NETWORK / AUTH / MALFORMED, each with one-line remediation hint | 3 buckets, 0 wrong-layer debugging |
| Migration interruption safety | partial-state on Ctrl-C | journal at `.migrations/v1.27.0.0.journal`, resumes from the next un-done step | 6-step atomic rollback |
| Rename blast radius | one bin script | bin + scripts/ + 8 generated SKILL.md surfaces | grep regression test guards every caller |
| Tests added | — | 59 unit + 2 gate-tier E2E + 4 regression | full coverage of the rename + Path 4 prose contract |
| Path 4 step | What runs | Local dependency |
|---|---|---|
| Step 4c verify | `gstack-gbrain-mcp-verify $URL` (curl POST initialize) | none |
| Step 5a register | `claude mcp add --scope user --transport http gbrain $URL --header "Authorization: Bearer $TOKEN"` | claude CLI |
| Step 7 artifacts | `gstack-artifacts-init` (gh OR glab OR manual URL paste) | gh / glab / git |
| Step 8 CLAUDE.md | mode-aware block; token NEVER written to CLAUDE.md (only `~/.claude.json`) | filesystem |
| Step 9 smoke test | prints curl-equivalent for post-restart manual verification | none |
The verify helper's `Accept: application/json, text/event-stream` requirement
is a regression-tested invariant. Every MCP server that ships HTTP transport
returns 406 Not Acceptable without both values; missing this header costs
about 10 minutes of debugging per fresh setup.
### What this means for users running gbrain across machines
If you have a brain on a different Mac, a Tailscale-connected server, or a
teammate runs one for the team, you no longer need a local install on every
client. One paste of URL + bearer registers the MCP at user scope; restart
Claude Code and `mcp__gbrain__search` and friends become callable. The
artifacts repo is per-user (private), so each developer pushes their own
plans/designs/reports without crossing trust surfaces. Renaming
`gstack-brain-$USER` to `gstack-artifacts-$USER` is automatic if you accept
the migration prompt; everything keeps working if you decline.
Existing local-mode users (PGLite or Supabase) see no behavior change beyond
the rename. The path you picked in `/setup-gbrain` Step 2 still runs end to
end, just under the new "artifacts" terminology.
### Itemized changes
#### Added
- **`/setup-gbrain` Path 4 (Remote MCP).** Step 2 gains a fourth option:
paste an HTTPS MCP URL plus a bearer token. The skill verifies via
`gstack-gbrain-mcp-verify` (NETWORK / AUTH / MALFORMED classifier with
one-line remediation hints), registers via `claude mcp add --scope user
--transport http gbrain --header "Authorization: Bearer ..."`, then
skips local install / doctor / transcript ingest because Path 4 has
no local dependencies. Steps 5, 5a, 7, 8, 9, 10 all branch on mode.
Idempotent re-run skips Step 2 entirely when `gbrain_mcp_mode=remote-http`
is already detected.
- **`bin/gstack-gbrain-mcp-verify`** (new). POSTs `initialize` to a remote
MCP URL with the bearer from `$GBRAIN_MCP_TOKEN` (never argv) and
classifies failures into NETWORK / AUTH / MALFORMED with concrete
remediation hints. Probes `tools/list` for forward-compat with future
gbrain releases that ship `mcp__gbrain__sources_add` (returns
`sources_add_url_supported: true|false`).
- **`bin/gstack-artifacts-init`** (new). Replaces `gstack-brain-init`. Asks
the user to pick GitHub (auto via `gh`), GitLab (auto via `glab`), or
manual URL paste. Creates `gstack-artifacts-$USER` (private), stores the
HTTPS URL canonically in `~/.gstack-artifacts-remote.txt`, and prints the
brain-admin hookup command labeled "Send this to your brain admin" (always
prints, never auto-executes — see `setup-gbrain/memory.md` for why).
- **`bin/gstack-artifacts-url`** (new). Small helper for HTTPS↔SSH
conversion plus host / owner-repo extraction. Mirrors the spirit of
`gstack-slug` so URL-format string-mangling lives in one place.
- **`gbrain_mcp_mode` field in `gstack-gbrain-detect` output.** 3-tier
fallback: `claude mcp get gbrain --json` → `claude mcp list` text-grep →
`~/.claude.json` jq read. Defense in depth: if Anthropic moves the file
format, the first two tiers absorb it.
- **`gstack-upgrade/migrations/v1.27.0.0.sh`**. Six-step journaled migration
for the brain → artifacts rename. Each step writes its name to
`~/.gstack/.migrations/v1.27.0.0.journal` on success; re-entry resumes
from the next un-done step. On final success, journal is replaced by
`v1.27.0.0.done`. User opt-out writes a `skipped-by-user` marker so the
prompt doesn't fire again until `/setup-gbrain --rerun-migration`.
- **`setup-gbrain/memory.md`** has a new "Path 4: Remote MCP setup"
section covering the bearer storage trade-off, the always-print
brain-admin hookup pattern, the CLAUDE.md block format (no token), and
token-rotation guidance.
#### Changed
- **`gbrain_sync_mode` config key renamed to `artifacts_sync_mode`.** Hard
rename, no dual-read alias. The migration script rewrites the key in
`~/.gstack/config.yaml` and any "## GBrain Configuration" block in
CLAUDE.md. Internal callers updated:
`bin/gstack-config`, `bin/gstack-gbrain-detect`, `bin/gstack-brain-sync`,
`bin/gstack-brain-enqueue`, `bin/gstack-brain-uninstall`,
`bin/gstack-timeline-log`, `scripts/resolvers/preamble/generate-brain-sync-block.ts`.
- **Preamble `BRAIN_SYNC: ...` line renamed to `ARTIFACTS_SYNC: ...`** and
branches on `gbrain_mcp_mode`. In remote-http mode it emits
`ARTIFACTS_SYNC: remote-mode (managed by brain server <host>)` to make
clear that local sync is a no-op by design.
- **`bin/gstack-brain-restore`, `bin/gstack-gbrain-source-wireup`, and
`bin/gstack-brain-uninstall`** read `~/.gstack-artifacts-remote.txt` with
`~/.gstack-brain-remote.txt` as a migration-window fallback. Once the
v1.27.0.0 migration runs, only the artifacts file remains.
- **`/sync-gbrain` is a graceful no-op in remote-http mode** (V1). Prints a
one-line note pointing at the brain server and exits cleanly. Local-mode
users see no change.
#### Removed
- **`bin/gstack-brain-init` deleted.** Replaced by `bin/gstack-artifacts-init`.
Anyone running the old name post-upgrade gets a clean "command not found"
rather than a silent rename — per the gstack rule "avoid backwards-
compatibility hacks." Existing users on disk have their state migrated by
v1.27.0.0.sh.
- **`test/gstack-brain-init-gh-mock.test.ts` deleted.** Replaced by
`test/gstack-artifacts-init.test.ts` covering the same gh-mock pattern
plus the new GitLab branch and the brain-admin printout.
#### For contributors
- **59 new unit tests + 2 gate-tier E2E tests + 4 regression tests.**
Highlights:
- `test/gstack-gbrain-mcp-verify.test.ts` (13 tests) covers each error
class via mocked curl, asserts the dual `Accept` header is set on
every call, regression-tests the token-never-on-stdout invariant.
- `test/gstack-artifacts-init.test.ts` (16 tests) covers gh / glab /
both / neither provider selection, HTTPS canonical storage, the
URL-form-supported branch in the brain-admin printout, and idempotent
re-run.
- `test/gstack-gbrain-detect-mcp-mode.test.ts` (19 tests) verifies each
of the 3 detection tiers in isolation, plus the schema-regression
check that `/sync-gbrain`'s parser doesn't break on the new fields.
- `test/migrations-v1.27.0.0.test.ts` (11 tests) covers all six
migration steps including journal-resume, idempotent re-run, the
add-before-remove ordering for source swap, and the remote-MCP
print-only branch.
- `test/no-stale-gstack-brain-refs.test.ts` greps the broader tree
(bin, scripts, *.tmpl, generated *.md, test/) for stale identifiers.
- `test/post-rename-doc-regen.test.ts` confirms gen-skill-docs output
has no `gstack-brain` strings post-rename.
- `test/setup-gbrain-path4-structure.test.ts` is a fast structural lint
that catches AUQ-pacing regressions in the Path 4 prose without
spending eval tokens.
- **`scripts/resolvers/preamble/generate-brain-sync-block.ts`** detects
remote-http mode by reading `~/.claude.json` directly (no claude
subprocess on every preamble — the hot path stays fast).
- **`test/helpers/touchfiles.ts`** wires `setup-gbrain-remote` and
`setup-gbrain-bad-token` into the gate-tier E2E selection.
- **Preamble byte budget ratcheted from 35K to 36.5K** to honor the
remote-mode probe in `generate-brain-sync-block.ts`.
## [1.26.5.0] - 2026-05-06
## **The v1.26 memory feature now actually works on a fresh `/setup-gbrain` install, and `/sync-gbrain --full` actually registers github-hosted code sources.**
Two fix-wave bugs closed in one ship. Until this version, the headline v1.26 features ended setup green but did nothing: every transcript page failed `Unknown command: put_page`, and every `github.com/<org>/<repo>` repo got rejected for an invalid source id. After upgrade, clean-install transcripts land in gbrain with title/type/tags intact, and any github-hosted repo registers a code source on the first try.
### The numbers that matter
Both numbers come from running the binaries against the real gbrain v0.25.1 install on this machine, against `origin/main` first (buggy) and the merged branch second.
| Surface | Before (v1.26.4.0) | After (v1.26.5.0) | Δ |
|---|---|---|---|
| Memory-ingest writer verb | `gbrain put_page --slug ... --title ...` (CLI rejects: `Unknown command`) | `gbrain put <slug>` with frontmatter (CLI accepts) | from 100% fail to 0% fail |
| Transcript pages with title/type/tags | none — fields rode CLI flags that no gbrain version accepts | injected into existing frontmatter on every page | search/filter by `--type transcript` actually returns results now |
| Source id derived for `github.com/garrytan/gstack` | `gstack-code-github.com-garrytan-gstack` (38 chars, contains `.`, fails gbrain `[a-z0-9-]{1,32}` validator) | `gstack-code-garrytan-gstack` (27 chars, valid) | 100% of github-hosted repos go from rejected to accepted |
| Availability probe failure mode | every page errors with `Unknown command: put_page` | one clean error: `gbrain CLI not in PATH or missing put subcommand` | log spam goes from N copies to 1 |
| Available `gbrainPutPage()` timeout | 30 s (auto-link reconciliation hits 30 s on dense brains) | 60 s | brains with hundreds of existing pages stop hitting the ceiling on every put |
| `gbrainPutPage()` error surface | `Command failed:` (Node truncates 1 MB stderr) | first 300 chars of `err.stderr` | debugging stops requiring strace; the failure is visible |
The `gbrain put` verb has existed since v0.18.2 and was always the right CLI surface. The `put_page` shape was the MCP tool name leaking into the CLI path. The hybrid writer now handles both transcript pages (existing frontmatter from `buildTranscriptPage`, inject title/type/tags into it) and raw artifact pages (no frontmatter, wrap with new frontmatter).
### What this means for new users
Run `/setup-gbrain` on a clean install, choose any path, and Step 7.5 actually populates the brain with your transcripts plus their metadata. Run `/sync-gbrain --full` on any github-hosted repo and the code stage registers the source instead of failing the `sources add` validator. The headline v1.26 features finally do the thing they shipped to do.
### Itemized changes
#### Fixed
- `bin/gstack-memory-ingest.ts:gbrainPutPage` — switched the writer from the legacy flag-based `gbrain put_page --slug X --title Y --type Z --tags T` form to the CLI surface `gbrain put <slug>` (positional slug, content via stdin, metadata in YAML frontmatter). Two-branch hybrid: when the page body already starts with frontmatter (transcript pages from `buildTranscriptPage`, which prepends agent/session_id/cwd/git_remote/etc. but no title/type/tags), inject title/type/tags into the existing block before the closing `---`. When the body has no frontmatter (raw artifact pages: design-docs, learnings, builder-profile-entries), wrap with a fresh frontmatter carrying the same fields. Either branch produces a page that gbrain's pages list, search, and tag filters actually surface. Contributed by @smithjoshua (PR #1328: base writer + 60 s timeout + 16 MB maxBuffer + stderr first-line surface) and the artifact-wrap branch added on top here.
- `bin/gstack-memory-ingest.ts:gbrainAvailable` — adds a `gbrain --help` probe with a regex anchored on the indented subcommand format (`/^\s+put\s/m`). Replaces the previous `command -v` only check. If a future gbrain renames or removes `put`, the writer fails fast with one clean error per ingest pass instead of N copies of `Unknown command: put_page`. Contributed by @AZ-1224 (PR #1341: probe origin); regex tightening added on top here per Codex P2 plan-review feedback.
- `bin/gstack-gbrain-sync.ts:deriveCodeSourceId` — drops the host segment from canonical remote URLs (the same `github.com-` prefix on every user's id was eating 12 chars of the 32-char gbrain budget for nothing) and falls back to a 6-char sha1 hash on the slug tail when org/repo names still exceed the limit. Every `github.com/<org>/<repo>` derives a gbrain-valid id on the first try. Contributed by @radubach (PR #1330).
- `bin/gstack-gbrain-sync.ts:constrainSourceId` — handles the empty-slug edge case (input sanitizes to all non-alnum chars). Pre-fix the function returned `${prefix}-` which fails gbrain's validator on the trailing hyphen; now falls back to a deterministic sha1-prefixed id. Surfaced via the new `basename-sanitizes-to-empty` regression test added in this version per Codex plan-review.
#### Added
- `test/gstack-memory-ingest.test.ts` — two regression tests stand up a fake `gbrain` shim on PATH and run the real `--bulk` ingest pipeline against a planted Claude Code session. The first asserts the writer hits `gbrain put <slug>` (not `put_page`) and that title, type, AND tags arrive in the put stdin. The second points the writer at a legacy-only shim and asserts the availability probe surfaces a single missing-subcommand error instead of N per-page failures. Contributed by @AZ-1224 (PR #1341); the assertions for title/type/tags arriving in stdin are added on top here. The strengthened test surfaced a deeper issue in PR #1328's inject branch: it searched for `\n---\n` (with trailing newline) but `buildTranscriptPage` joins frontmatter without a trailing newline, so the search never matched. Two-line fix on top: search for `\n---` only.
- `test/gstack-gbrain-sync.test.ts` — four cases from PR #1330 (dot-host, SCP-style remote, multi-dot host, long org/repo forcing hash-truncate) plus two new edge cases this version (no-origin fallback path; basename-sanitizes-to-empty). Each test spawns the CLI inside a temp git repo and asserts the derived id passes gbrain's validator regex. Contributed by @radubach for the four core cases.
#### For contributors
- Codex outside-voice plan review caught three P1 ship-blockers in the originally proposed merge (the no-frontmatter-wrap branch from PR #1341 alone would have silently dropped title/type/tags from every transcript page — its own tests passed because they only asserted `agent: claude-code`). The plan pivoted from `merge #1341 + cherry-pick from #1328` to `merge #1328 + hybrid writer + cherry-pick #1341's tests, strengthened`. Two-pass live smoke against real gbrain (where the database connects) confirmed source-id length goes 38 → 27 chars; memory-ingest writer correctness was verified by the strengthened shim tests against a real `gbrain` CLI process.
- Two follow-up TODOs filed: P2 to bump the `bin/gstack-gbrain-install` pin in lockstep with gstack memory-feature releases (issue #1305 part 2), P3 to handle source-id cross-host collisions (`github.com/acme/foo` and `gitlab.com/acme/foo` currently collapse to the same id; rare but silent).
## [1.26.4.0] - 2026-05-05
## **`/autoplan` review reports now reliably land at the bottom of the plan, even when an older copy lives mid-file.**

50
SKILL.md
View File

@ -270,11 +270,17 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
- Focus on completing the task and reporting results via prose output.
- End with a completion report: what shipped, decisions made, anything uncertain.
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -307,13 +313,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -333,22 +352,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -359,11 +383,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

36
TODOS.md
View File

@ -88,6 +88,42 @@
---
### P2: Bump gbrain install-pin in lockstep with gstack memory-feature releases (#1305 part 2)
**What:** `bin/gstack-gbrain-install` pins gbrain to commit `08b3698` (v0.18.2). When gstack ships features that depend on newer gbrain ops or schema (e.g. v1.26.0 manifests + `code-def`/`code-refs`/`reindex-code`), the pin doesn't move with it. Fresh `/setup-gbrain` installs an old gbrain that fails `gbrain doctor` schema_version checks (24 vs latest 32+) until the user manually upgrades.
**Why:** Filed in #1305 alongside the `put_page` CLI bug. Out of scope for the v1.26.5.0 fix wave (separate release-coordination concern: which gbrain version we install vs. how we call it). The install-pin should either (a) auto-bump whenever gstack releases features that need newer gbrain, or (b) detect a stale pin during preamble and either auto-upgrade gbrain or print a one-line FIX hint.
**Pros:** Closes the "fresh-install paper-cut" path. New users land on a healthy schema. Reduces support noise on `/setup-gbrain` flows. Makes the gstack/gbrain release contract visible.
**Cons:** Adds release-cadence coupling between gstack and gbrain. Needs a policy: pin = "minimum version that still works" vs "latest known good." If gbrain ships a breaking change to `put` shape and gstack doesn't update the pin, fresh installs break in a new way.
**Context:** Issue #1305 part 1 (the `put_page` CLI verb bug) was handled in v1.26.5.0. Part 2 (this TODO) is the install-pin staleness. Pin lives in `bin/gstack-gbrain-install` near the top as a constant. Easiest minimal fix: ship the pin as a tracked release artifact (e.g. write it from `package.json` at build time) and add a doctor-style preamble check.
**Effort:** S (human: ~2 days / CC: ~3 hours)
**Priority:** P2
**Depends on:** Nothing.
---
### P3: Source-id host-collision risk in `deriveCodeSourceId` (cross-host duplicate org/repo)
**What:** v1.26.5.0's `deriveCodeSourceId` drops the host segment to fit gbrain's 32-char source-id budget. This means `github.com/acme/foo` and `gitlab.com/acme/foo` collapse to the same `gstack-code-acme-foo`. `ensureSourceRegisteredSync()` in `bin/gstack-gbrain-sync.ts:323` will silently re-register the source when `local_path` differs, evicting one side.
**Why:** Vanishingly rare in practice — same `<org>/<repo>` shape across both github.com and gitlab.com on the same machine almost never happens. But the failure mode is silent (one repo evicts the other in the brain), and the user has no signal anything is wrong.
**Pros:** Closes the silent-eviction edge. Two viable approaches: short host marker (`gh-` / `gl-` / `bb-`) eats 3 chars but keeps cross-host uniqueness; OR include a 3-char hash of the host alongside the org-repo.
**Cons:** Source IDs change shape again — anyone with existing registrations on v1.26.5.0 gets a one-time re-register. Net break-even because the current scheme also changed from v1.26.4.0.
**Context:** Filed in #1320 / #1322 / #1323 / #1331 (the underlying source-id validation bugs), addressed in v1.26.5.0 by dropping host segment + hash-truncating. Cross-host collision was a known accepted tradeoff in PR #1330's design ("vanishingly rare in practice"). Codex outside-voice plan review surfaced it as a long-tail concern; this TODO captures it for a future bump.
**Effort:** XS (human: ~4 hours / CC: ~30 min)
**Priority:** P3
**Depends on:** Nothing.
---
### P3: GBrain skillpack publishing for domain skills
**What:** Domain skills are agent-authored notes per hostname. Right now they're per-machine or per-agent-repo. The natural compounding extension: publish curated skill packs to GBrain (`gstack-brain-sync`) so others can subscribe. "Louise's LinkedIn skills" or "Garry's GitHub skills" become packs anyone can pull.

2
VERSION
View File

@ -1 +1 @@
1.26.4.0
1.27.0.0

50
autoplan/SKILL.md
View File

@ -338,11 +338,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -375,13 +381,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -401,22 +420,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -427,11 +451,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
benchmark-models/SKILL.md
View File

@ -272,11 +272,17 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
- Focus on completing the task and reporting results via prose output.
- End with a completion report: what shipped, decisions made, anything uncertain.
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -309,13 +315,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -335,22 +354,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -361,11 +385,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
benchmark/SKILL.md
View File

@ -272,11 +272,17 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
- Focus on completing the task and reporting results via prose output.
- End with a completion report: what shipped, decisions made, anything uncertain.
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -309,13 +315,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -335,22 +354,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -361,11 +385,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

389
bin/gstack-artifacts-init Executable file
View File

@ -0,0 +1,389 @@
#!/usr/bin/env bash
# gstack-artifacts-init — set up ~/.gstack/ as a git repo synced to a private
# git host (GitHub or GitLab) so a remote gbrain can ingest your artifacts
# (CEO plans, designs, /investigate reports) as a federated source.
#
# Replaces gstack-brain-init in v1.27.0.0 (per D4 hard-delete; no compat
# shim). Existing users are migrated by gstack-upgrade/migrations/v1.27.0.0.sh.
#
# Usage:
# gstack-artifacts-init [--remote <url>] [--host github|gitlab|manual]
# [--url-form-supported true|false]
#
# Interactive by default. Pass --remote to skip the host prompt.
#
# Idempotent: safe to re-run. If ~/.gstack/.git already exists AND points at
# the same remote, reconfigures drivers/hooks/attributes without clobbering
# history. If it points at a DIFFERENT remote, refuses.
#
# What it does:
# 1. git init ~/.gstack/ (or verify existing repo points at the right remote)
# 2. Write .gitignore = "*" (ignore everything; allowlist is explicit)
# 3. Write .brain-allowlist (canonical paths to sync)
# 4. Write .brain-privacy-map.json (paths → privacy class)
# 5. Write .gitattributes (register JSONL + union merge drivers)
# 6. git config merge.jsonl-append.driver + merge.union.driver
# 7. Install .git/hooks/pre-commit (defense-in-depth secret scan)
# 8. Provider-aware repo create (gh / glab) OR manual URL paste
# 9. Initial commit + push
# 10. Write ~/.gstack-artifacts-remote.txt (HTTPS URL — canonical form)
# 11. Print "Send this to your brain admin" hookup command
#
# Env:
# GSTACK_HOME — override ~/.gstack
# USER — fallback for repo naming if $USER is unset
set -euo pipefail
GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
URL_BIN="$SCRIPT_DIR/gstack-artifacts-url"
REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
REMOTE_URL=""
HOST_PREF=""
URL_FORM_SUPPORTED="false"
while [ $# -gt 0 ]; do
case "$1" in
--remote) REMOTE_URL="$2"; shift 2 ;;
--host) HOST_PREF="$2"; shift 2 ;;
--url-form-supported) URL_FORM_SUPPORTED="$2"; shift 2 ;;
--help|-h) sed -n '2,32p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
*) echo "Unknown flag: $1" >&2; exit 1 ;;
esac
done
# ---- preconditions ----
mkdir -p "$GSTACK_HOME"
EXISTING_REMOTE=""
if [ -d "$GSTACK_HOME/.git" ]; then
EXISTING_REMOTE=$(git -C "$GSTACK_HOME" remote get-url origin 2>/dev/null || echo "")
if [ -n "$EXISTING_REMOTE" ] && [ -n "$REMOTE_URL" ]; then
# Compare at the canonical level. The stored remote is SSH (for git push),
# the input is usually HTTPS — same logical repo, different surface form.
EXISTING_HTTPS=$("$URL_BIN" --to https "$EXISTING_REMOTE" 2>/dev/null || echo "$EXISTING_REMOTE")
INPUT_HTTPS=$("$URL_BIN" --to https "$REMOTE_URL" 2>/dev/null || echo "$REMOTE_URL")
if [ "$EXISTING_HTTPS" != "$INPUT_HTTPS" ]; then
cat >&2 <<EOF
gstack-artifacts-init: ~/.gstack/ is already a git repo pointing at:
$EXISTING_REMOTE (canonical: $EXISTING_HTTPS)
You asked to init with:
$REMOTE_URL (canonical: $INPUT_HTTPS)
Refusing to overwrite. To switch remotes, edit manually:
git -C ~/.gstack remote set-url origin <url>
EOF
exit 1
fi
fi
fi
# ---- detect available providers ----
gh_ok=false
glab_ok=false
if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then gh_ok=true; fi
if command -v glab >/dev/null 2>&1 && glab auth status >/dev/null 2>&1; then glab_ok=true; fi
# ---- choose remote URL ----
if [ -z "$REMOTE_URL" ] && [ -n "$EXISTING_REMOTE" ]; then
REMOTE_URL="$EXISTING_REMOTE"
echo "Using existing remote: $REMOTE_URL"
fi
REPO_NAME="gstack-artifacts-${USER:-$(whoami)}"
DESCRIPTION="gstack artifacts (CEO plans, designs, reports) — synced from ~/.gstack/projects/"
# Decide host preference if not pinned by --host.
if [ -z "$REMOTE_URL" ] && [ -z "$HOST_PREF" ]; then
if $gh_ok && $glab_ok; then
cat >&2 <<EOF
gstack-artifacts-init: which git host?
1) GitHub (gh CLI authenticated)
2) GitLab (glab CLI authenticated)
3) Other / paste a private git URL
EOF
printf "Choice [1]: " >&2
read -r CH || CH=""
case "$CH" in
""|1) HOST_PREF="github" ;;
2) HOST_PREF="gitlab" ;;
3) HOST_PREF="manual" ;;
*) echo "Invalid choice: $CH" >&2; exit 1 ;;
esac
elif $gh_ok; then
HOST_PREF="github"
echo "Using GitHub (gh CLI authenticated; glab not available)" >&2
elif $glab_ok; then
HOST_PREF="gitlab"
echo "Using GitLab (glab CLI authenticated; gh not available)" >&2
else
HOST_PREF="manual"
echo "(Neither gh nor glab CLI authenticated — falling through to manual URL)" >&2
fi
fi
# ---- create repo on chosen host ----
if [ -z "$REMOTE_URL" ]; then
case "$HOST_PREF" in
github)
echo "Creating GitHub repo: $REPO_NAME ..."
if ! gh repo create "$REPO_NAME" --private --description "$DESCRIPTION" 2>/dev/null; then
# Maybe already exists; try to fetch its URL.
REMOTE_URL=$(gh repo view "$REPO_NAME" --json url -q .url 2>/dev/null || echo "")
if [ -z "$REMOTE_URL" ]; then
echo "Failed to create or find '$REPO_NAME'. Try --remote <url>." >&2
exit 1
fi
echo "Repo already exists; using $REMOTE_URL"
else
REMOTE_URL=$(gh repo view "$REPO_NAME" --json url -q .url 2>/dev/null || echo "")
fi
;;
gitlab)
echo "Creating GitLab repo: $REPO_NAME ..."
if ! glab repo create "$REPO_NAME" --private --description "$DESCRIPTION" 2>/dev/null; then
REMOTE_URL=$(glab repo view "$REPO_NAME" -F json 2>/dev/null | jq -r '.web_url // empty' 2>/dev/null || echo "")
if [ -z "$REMOTE_URL" ]; then
echo "Failed to create or find '$REPO_NAME'. Try --remote <url>." >&2
exit 1
fi
echo "Repo already exists; using $REMOTE_URL"
else
REMOTE_URL=$(glab repo view "$REPO_NAME" -F json 2>/dev/null | jq -r '.web_url // empty' 2>/dev/null || echo "")
fi
;;
manual)
echo "(provide a private git URL)"
printf "Paste an HTTPS git URL (e.g. https://github.com/you/gstack-artifacts.git): " >&2
read -r REMOTE_URL || REMOTE_URL=""
if [ -z "$REMOTE_URL" ]; then
echo "No URL provided. Aborting." >&2
exit 1
fi
;;
*) echo "Unknown --host: $HOST_PREF (expected github|gitlab|manual)" >&2; exit 1 ;;
esac
fi
# ---- canonicalize to HTTPS form ----
# We store HTTPS in ~/.gstack-artifacts-remote.txt (codex Finding #10:
# canonical form, derive SSH at push time via gstack-artifacts-url --to ssh).
# Unrecognized forms (local bare paths, file:// URLs, self-hosted gitea, etc.)
# pass through verbatim so unusual remotes still work.
CANONICAL_HTTPS=$("$URL_BIN" --to https "$REMOTE_URL" 2>/dev/null || echo "")
if [ -z "$CANONICAL_HTTPS" ]; then
CANONICAL_HTTPS="$REMOTE_URL"
fi
# Use SSH for git push (more reliable for repeated pushes than HTTPS+token).
# Fall back to the canonical input if derivation fails.
PUSH_URL=$("$URL_BIN" --to ssh "$CANONICAL_HTTPS" 2>/dev/null || echo "$CANONICAL_HTTPS")
# ---- verify push URL is reachable ----
echo "Verifying remote connectivity: $PUSH_URL"
if ! git ls-remote "$PUSH_URL" >/dev/null 2>&1; then
cat >&2 <<EOF
Remote not reachable via SSH: $PUSH_URL
This could mean:
- Wrong URL
- SSH key not added to your git host (GitHub: gh ssh-key list; GitLab: glab ssh-key list)
- Network issue
Fix and re-run gstack-artifacts-init.
EOF
exit 1
fi
# ---- git init ----
if [ ! -d "$GSTACK_HOME/.git" ]; then
git -C "$GSTACK_HOME" init -q -b main 2>/dev/null || git -C "$GSTACK_HOME" init -q
git -C "$GSTACK_HOME" branch -M main 2>/dev/null || true
fi
if [ -z "$(git -C "$GSTACK_HOME" remote 2>/dev/null)" ]; then
git -C "$GSTACK_HOME" remote add origin "$PUSH_URL"
else
git -C "$GSTACK_HOME" remote set-url origin "$PUSH_URL"
fi
# ---- write canonical files (idempotent) ----
cat > "$GSTACK_HOME/.gitignore" <<'EOF'
# gstack-artifacts sync: ignore-everything base. Paths are included explicitly via
# .brain-allowlist and `git add -f` from gstack-brain-sync. Do not edit.
*
EOF
cat > "$GSTACK_HOME/.brain-allowlist" <<'EOF'
# Canonical allowlist of paths that gstack-brain-sync will publish.
# One glob per line. Anything not matching stays local.
# Do not edit directly; managed by gstack-artifacts-init. User additions go
# below the marker and survive re-init.
projects/*/learnings.jsonl
projects/*/*-reviews.jsonl
projects/*/ceo-plans/*.md
projects/*/ceo-plans/*/*.md
projects/*/designs/*.md
projects/*/designs/*/*.md
projects/*/timeline.jsonl
retros/*.md
developer-profile.json
builder-journey.md
builder-profile.jsonl
# NOT synced (machine-local UX state):
# projects/*/question-preferences.json (per-machine UX preferences)
# projects/*/question-log.jsonl (audit/derivation log stays with preferences)
# projects/*/question-events.jsonl (same)
# ---- USER ADDITIONS BELOW ---- (survives re-init; above is managed)
EOF
cat > "$GSTACK_HOME/.brain-privacy-map.json" <<'EOF'
[
{"pattern": "projects/*/learnings.jsonl", "class": "artifact"},
{"pattern": "projects/*/*-reviews.jsonl", "class": "artifact"},
{"pattern": "projects/*/ceo-plans/*.md", "class": "artifact"},
{"pattern": "projects/*/ceo-plans/*/*.md", "class": "artifact"},
{"pattern": "projects/*/designs/*.md", "class": "artifact"},
{"pattern": "projects/*/designs/*/*.md", "class": "artifact"},
{"pattern": "retros/*.md", "class": "artifact"},
{"pattern": "builder-journey.md", "class": "artifact"},
{"pattern": "projects/*/timeline.jsonl", "class": "behavioral"},
{"pattern": "developer-profile.json", "class": "behavioral"},
{"pattern": "builder-profile.jsonl", "class": "behavioral"}
]
EOF
cat > "$GSTACK_HOME/.gitattributes" <<'EOF'
# gstack-artifacts: merge drivers for cross-machine sync conflicts.
*.jsonl merge=jsonl-append
retros/*.md merge=union
projects/*/designs/**/*.md merge=union
projects/*/ceo-plans/**/*.md merge=union
EOF
# ---- register merge drivers in local git config ----
git -C "$GSTACK_HOME" config merge.jsonl-append.driver "$SCRIPT_DIR/gstack-jsonl-merge %O %A %B"
git -C "$GSTACK_HOME" config merge.jsonl-append.name "gstack JSONL append-only merger"
git -C "$GSTACK_HOME" config merge.union.driver "cat %A %B > %A.merged && mv %A.merged %A"
git -C "$GSTACK_HOME" config merge.union.name "union concat"
# ---- install pre-commit hook (defense-in-depth) ----
HOOK="$GSTACK_HOME/.git/hooks/pre-commit"
mkdir -p "$(dirname "$HOOK")"
cat > "$HOOK" <<'HOOK_EOF'
#!/usr/bin/env bash
# gstack-artifacts pre-commit hook — secret-scan defense-in-depth.
# The primary scanner runs inside gstack-brain-sync BEFORE staging. This hook
# catches any manual `git commit` a user might accidentally run against the
# artifacts repo.
set -uo pipefail
python3 -c "
import sys, re, subprocess
try:
out = subprocess.check_output(['git', 'diff', '--cached'], stderr=subprocess.DEVNULL).decode('utf-8', 'replace')
except Exception:
sys.exit(0)
patterns = [
('aws-access-key', re.compile(r'AKIA[0-9A-Z]{16}')),
('github-token', re.compile(r'\b(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})')),
('openai-key', re.compile(r'\bsk-[A-Za-z0-9_-]{20,}')),
('pem-block', re.compile(r'-----BEGIN [A-Z ]{3,}-----')),
('jwt', re.compile(r'\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b')),
('bearer-token-json',
re.compile(r'\"(authorization|api[_-]?key|apikey|token|secret|password)\"\s*:\s*\"[A-Za-z0-9_./+=-]{16,}\"',
re.IGNORECASE)),
]
for name, rx in patterns:
if rx.search(out):
sys.stderr.write(f'gstack-artifacts pre-commit: refusing commit — {name} detected in staged diff.\n')
sys.stderr.write('Either edit the offending file, or if intentional, run:\n')
sys.stderr.write(' gstack-brain-sync --skip-file <path> (to permanently exclude)\n')
sys.exit(1)
sys.exit(0)
"
HOOK_EOF
chmod +x "$HOOK"
# ---- initial commit (idempotent) ----
cd "$GSTACK_HOME"
git add -f .gitignore .brain-allowlist .brain-privacy-map.json .gitattributes
if git rev-parse HEAD >/dev/null 2>&1; then
if ! git diff --cached --quiet 2>/dev/null; then
git -c user.email="gstack@localhost" -c user.name="gstack-artifacts-init" \
commit -q -m "chore: gstack-artifacts-init (refresh sync config)"
fi
else
git -c user.email="gstack@localhost" -c user.name="gstack-artifacts-init" \
commit -q -m "chore: gstack-artifacts-init"
fi
# ---- initial push ----
if ! git push -q -u origin main 2>/dev/null; then
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
if git fetch origin 2>/dev/null && git pull --ff-only origin "$CURRENT_BRANCH" 2>/dev/null; then
git push -q -u origin "$CURRENT_BRANCH" || {
echo "Push to $PUSH_URL failed. The remote may have divergent content." >&2
echo "Try: cd ~/.gstack && git pull --rebase origin $CURRENT_BRANCH && git push origin $CURRENT_BRANCH" >&2
exit 1
}
else
echo "Push to $PUSH_URL failed and fetch/merge didn't help." >&2
echo "Manual recovery: cd ~/.gstack && git status, then push once conflicts are resolved." >&2
exit 1
fi
fi
# ---- write the remote-url helper file (HTTPS canonical) ----
echo "$CANONICAL_HTTPS" > "$REMOTE_FILE"
chmod 600 "$REMOTE_FILE"
# ---- print brain-admin hookup command (always print, never auto-execute;
# codex Finding #3) ----
SOURCE_ID="gstack-artifacts-${USER:-$(whoami)}"
cat <<EOF
gstack-artifacts-init complete.
Repo: $GSTACK_HOME (git)
Remote: $CANONICAL_HTTPS (canonical form, in ~/.gstack-artifacts-remote.txt)
Push: $PUSH_URL (derived SSH form for git push)
EOF
cat <<EOF
─────────────────────────────────────────────────────────────────────────
Send this to your brain admin (the person who runs your gbrain server)
─────────────────────────────────────────────────────────────────────────
EOF
if [ "$URL_FORM_SUPPORTED" = "true" ]; then
cat <<EOF
On the brain host, run:
gbrain sources add $SOURCE_ID --url $CANONICAL_HTTPS --federated
EOF
else
cat <<EOF
On the brain host (gbrain v0.26.x doesn't accept URLs directly yet), run:
git clone $CANONICAL_HTTPS ~/$SOURCE_ID
gbrain sources add $SOURCE_ID --path ~/$SOURCE_ID --federated
When gbrain ships --url support, this becomes a one-liner:
gbrain sources add $SOURCE_ID --url $CANONICAL_HTTPS --federated
EOF
fi
cat <<EOF
After that, your CEO plans / designs / reports become searchable via
'gbrain search' from any machine pointing at this brain.
─────────────────────────────────────────────────────────────────────────
New machine? Put a copy of $REMOTE_FILE in that machine's home directory,
then run: gstack-artifacts-init (it'll detect the remote and re-init).
EOF

106
bin/gstack-artifacts-url Executable file
View File

@ -0,0 +1,106 @@
#!/usr/bin/env bash
# gstack-artifacts-url — canonical-URL helper for the artifacts repo.
#
# We store the HTTPS URL as canonical (in ~/.gstack-artifacts-remote.txt) and
# derive other forms on demand. Centralizes the regex so callers don't each
# string-mangle, which is how URL-format bugs creep into branch logic
# (codex Finding #10).
#
# Usage:
# gstack-artifacts-url --to ssh <https-url> # https → git@host:owner/repo.git
# gstack-artifacts-url --to https <any-url> # idempotent canonicalization
# gstack-artifacts-url --host <any-url> # extract hostname
# gstack-artifacts-url --owner-repo <any-url> # extract owner/repo
#
# Inputs accepted:
# https://github.com/garrytan/gstack-artifacts-garrytan
# https://github.com/garrytan/gstack-artifacts-garrytan.git
# git@github.com:garrytan/gstack-artifacts-garrytan.git
# ssh://git@gitlab.com/garrytan/gstack-artifacts-garrytan.git
# git@gitlab.example.org:team/gstack-artifacts-team.git
#
# Output: the requested form on stdout. Exits non-zero on parse failure with
# an error on stderr.
set -euo pipefail
usage() {
echo "Usage: gstack-artifacts-url --to {ssh|https} <url>" >&2
echo " gstack-artifacts-url --host <url>" >&2
echo " gstack-artifacts-url --owner-repo <url>" >&2
exit 2
}
[ $# -ge 2 ] || usage
mode=""
to=""
case "$1" in
--to) mode="to"; to="$2"; shift 2 ;;
--host) mode="host"; shift ;;
--owner-repo) mode="owner-repo"; shift ;;
*) usage ;;
esac
[ $# -eq 1 ] || usage
url="$1"
# Strip trailing .git for normalization; reattach where needed.
strip_git() {
echo "${1%.git}"
}
# Parse to (host, owner_repo) regardless of input shape.
parse_url() {
local u="$1"
local host="" owner_repo=""
case "$u" in
https://*)
# https://host/owner/repo[.git]
local rest="${u#https://}"
host="${rest%%/*}"
owner_repo="${rest#*/}"
owner_repo=$(strip_git "$owner_repo")
;;
ssh://*)
# ssh://git@host/owner/repo[.git] OR ssh://host/owner/repo[.git]
local rest="${u#ssh://}"
# Strip optional user@
rest="${rest#*@}"
host="${rest%%/*}"
owner_repo="${rest#*/}"
owner_repo=$(strip_git "$owner_repo")
;;
git@*:*)
# git@host:owner/repo[.git]
local rest="${u#git@}"
host="${rest%%:*}"
owner_repo="${rest#*:}"
owner_repo=$(strip_git "$owner_repo")
;;
*)
echo "gstack-artifacts-url: unrecognized URL form: $u" >&2
exit 3
;;
esac
if [ -z "$host" ] || [ -z "$owner_repo" ] || [ "$owner_repo" = "$u" ]; then
echo "gstack-artifacts-url: failed to parse host/owner from: $u" >&2
exit 3
fi
printf '%s\n%s\n' "$host" "$owner_repo"
}
parsed=$(parse_url "$url")
host=$(echo "$parsed" | head -1)
owner_repo=$(echo "$parsed" | tail -1)
case "$mode" in
to)
case "$to" in
ssh) printf 'git@%s:%s.git\n' "$host" "$owner_repo" ;;
https) printf 'https://%s/%s\n' "$host" "$owner_repo" ;;
*) usage ;;
esac
;;
host) printf '%s\n' "$host" ;;
owner-repo) printf '%s\n' "$owner_repo" ;;
esac

4
bin/gstack-brain-enqueue
View File

@ -10,7 +10,7 @@
# preamble at skill START and END boundaries.
#
# No-op when:
# - gbrain_sync_mode is off (the default)
# - artifacts_sync_mode is off (the default)
# - ~/.gstack/.git doesn't exist (feature not initialized)
# - <file-path> matches a line in ~/.gstack/.brain-skip.txt
#
@ -36,7 +36,7 @@ SKIP_FILE="$GSTACK_HOME/.brain-skip.txt"
# Check sync mode. off → silent no-op.
SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
MODE=$("$SCRIPT_DIR/gstack-config" get gbrain_sync_mode 2>/dev/null || echo off)
MODE=$("$SCRIPT_DIR/gstack-config" get artifacts_sync_mode 2>/dev/null || echo off)
[ "$MODE" = "off" ] && exit 0
# User-maintained skip list (for secret-scan false positives).

300
bin/gstack-brain-init
View File

@ -1,300 +0,0 @@
#!/usr/bin/env bash
# gstack-brain-init — set up ~/.gstack/ as a git repo that syncs to GBrain.
#
# Usage:
# gstack-brain-init [--remote <url>]
#
# Interactive by default. Pass --remote to skip the remote prompt.
#
# Idempotent: safe to re-run. If ~/.gstack/.git already exists AND points at
# the same remote, reconfigures drivers/hooks/attributes without clobbering
# history. If it points at a DIFFERENT remote, refuses and suggests
# `gstack-brain-uninstall` first.
#
# What it does:
# 1. git init ~/.gstack/ (or verify existing repo points at the right remote)
# 2. Write .gitignore = "*" (ignore everything; allowlist is explicit)
# 3. Write .brain-allowlist (canonical paths to sync)
# 4. Write .brain-privacy-map.json (paths → privacy class)
# 5. Write .gitattributes (register JSONL + union merge drivers)
# 6. git config merge.jsonl-append.driver + merge.union.driver
# 7. Install .git/hooks/pre-commit (defense-in-depth secret scan)
# 8. Prompt for remote (default: gh repo create --private gstack-brain-$USER)
# 9. Initial commit + push
# 10. Write ~/.gstack-brain-remote.txt (URL-only, safe to share)
#
# Env:
# GSTACK_HOME — override ~/.gstack
set -euo pipefail
GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
CONFIG_BIN="$SCRIPT_DIR/gstack-config"
REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
REMOTE_URL=""
while [ $# -gt 0 ]; do
case "$1" in
--remote) REMOTE_URL="$2"; shift 2 ;;
--help|-h) sed -n '2,32p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
*) echo "Unknown flag: $1" >&2; exit 1 ;;
esac
done
# ---- preconditions ----
mkdir -p "$GSTACK_HOME"
EXISTING_REMOTE=""
if [ -d "$GSTACK_HOME/.git" ]; then
EXISTING_REMOTE=$(git -C "$GSTACK_HOME" remote get-url origin 2>/dev/null || echo "")
if [ -n "$EXISTING_REMOTE" ] && [ -n "$REMOTE_URL" ] && [ "$EXISTING_REMOTE" != "$REMOTE_URL" ]; then
cat >&2 <<EOF
gstack-brain-init: ~/.gstack/ is already a git repo pointing at:
$EXISTING_REMOTE
You asked to init with:
$REMOTE_URL
Refusing to overwrite. To switch remotes, first run:
gstack-brain-uninstall
(or edit the remote manually with: git -C ~/.gstack remote set-url origin <url>)
EOF
exit 1
fi
fi
# ---- choose the remote ----
if [ -z "$REMOTE_URL" ] && [ -n "$EXISTING_REMOTE" ]; then
REMOTE_URL="$EXISTING_REMOTE"
echo "Using existing remote: $REMOTE_URL"
fi
if [ -z "$REMOTE_URL" ]; then
# Interactive prompt. Default: gh repo create (if available).
echo "gstack-brain-init will create a private git repo that holds your"
echo "gstack session memory across machines and lets GBrain index it."
echo
if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
DEFAULT_NAME="gstack-brain-${USER:-$(whoami)}"
echo "Default: gh will create a private repo named '$DEFAULT_NAME' under your account."
printf "Press Enter to accept, or paste a custom git URL: "
read -r REPLY || REPLY=""
if [ -z "$REPLY" ]; then
echo "Creating GitHub repo: $DEFAULT_NAME ..."
# Note: --source omitted intentionally. gh requires --source to point at
# an existing git repo, but we don't init $GSTACK_HOME until after the
# remote is chosen. Create bare, then fetch URL.
if ! gh repo create "$DEFAULT_NAME" --private --description "gstack session memory" 2>/dev/null; then
# Maybe the repo already exists; try to fetch its URL.
REMOTE_URL=$(gh repo view "$DEFAULT_NAME" --json sshUrl -q .sshUrl 2>/dev/null || echo "")
if [ -z "$REMOTE_URL" ]; then
echo "Failed to create or find '$DEFAULT_NAME'. Try --remote <url>." >&2
exit 1
fi
echo "Repo already exists; using $REMOTE_URL"
else
REMOTE_URL=$(gh repo view "$DEFAULT_NAME" --json sshUrl -q .sshUrl 2>/dev/null || echo "")
fi
else
REMOTE_URL="$REPLY"
fi
else
echo "(gh CLI not found or not authenticated; provide a git URL directly)"
printf "Paste a private git URL (e.g. git@github.com:you/gstack-brain.git): "
read -r REMOTE_URL || REMOTE_URL=""
if [ -z "$REMOTE_URL" ]; then
echo "No URL provided. Aborting." >&2
exit 1
fi
fi
fi
# ---- verify remote reachable ----
echo "Verifying remote connectivity: $REMOTE_URL"
if ! git ls-remote "$REMOTE_URL" >/dev/null 2>&1; then
cat >&2 <<EOF
Remote not reachable: $REMOTE_URL
This could mean:
- Wrong URL
- Not authenticated (GitHub: gh auth status; GitLab: glab auth status)
- Network issue
Fix and re-run gstack-brain-init.
EOF
exit 1
fi
# ---- git init ----
if [ ! -d "$GSTACK_HOME/.git" ]; then
git -C "$GSTACK_HOME" init -q -b main 2>/dev/null || git -C "$GSTACK_HOME" init -q
# If -b main wasn't supported, rename.
git -C "$GSTACK_HOME" branch -M main 2>/dev/null || true
fi
if [ -z "$(git -C "$GSTACK_HOME" remote 2>/dev/null)" ]; then
git -C "$GSTACK_HOME" remote add origin "$REMOTE_URL"
else
git -C "$GSTACK_HOME" remote set-url origin "$REMOTE_URL"
fi
# ---- write canonical files (idempotent) ----
cat > "$GSTACK_HOME/.gitignore" <<'EOF'
# gstack-brain sync: ignore-everything base. Paths are included explicitly via
# .brain-allowlist and `git add -f` from gstack-brain-sync. Do not edit.
*
EOF
cat > "$GSTACK_HOME/.brain-allowlist" <<'EOF'
# Canonical allowlist of paths that gstack-brain-sync will publish.
# One glob per line. Anything not matching stays local.
# Do not edit directly; managed by gstack-brain-init. User additions go below
# the marker and survive re-init.
projects/*/learnings.jsonl
projects/*/*-reviews.jsonl
projects/*/ceo-plans/*.md
projects/*/ceo-plans/*/*.md
projects/*/designs/*.md
projects/*/designs/*/*.md
projects/*/timeline.jsonl
retros/*.md
developer-profile.json
builder-journey.md
builder-profile.jsonl
# NOT synced (per Codex v2 review — machine-local UX state):
# projects/*/question-preferences.json (per-machine UX preferences)
# projects/*/question-log.jsonl (audit/derivation log stays with preferences)
# projects/*/question-events.jsonl (same)
# ---- USER ADDITIONS BELOW ---- (survives re-init; above is managed)
EOF
cat > "$GSTACK_HOME/.brain-privacy-map.json" <<'EOF'
[
{"pattern": "projects/*/learnings.jsonl", "class": "artifact"},
{"pattern": "projects/*/*-reviews.jsonl", "class": "artifact"},
{"pattern": "projects/*/ceo-plans/*.md", "class": "artifact"},
{"pattern": "projects/*/ceo-plans/*/*.md", "class": "artifact"},
{"pattern": "projects/*/designs/*.md", "class": "artifact"},
{"pattern": "projects/*/designs/*/*.md", "class": "artifact"},
{"pattern": "retros/*.md", "class": "artifact"},
{"pattern": "builder-journey.md", "class": "artifact"},
{"pattern": "projects/*/timeline.jsonl", "class": "behavioral"},
{"pattern": "developer-profile.json", "class": "behavioral"},
{"pattern": "builder-profile.jsonl", "class": "behavioral"}
]
EOF
cat > "$GSTACK_HOME/.gitattributes" <<'EOF'
# gstack-brain: merge drivers for cross-machine sync conflicts.
# Matching driver must be registered in local git config; gstack-brain-init
# and gstack-brain-restore run `git config merge.<name>.driver ...` after init.
*.jsonl merge=jsonl-append
retros/*.md merge=union
projects/*/designs/**/*.md merge=union
projects/*/ceo-plans/**/*.md merge=union
EOF
# ---- register merge drivers in local git config ----
git -C "$GSTACK_HOME" config merge.jsonl-append.driver "$SCRIPT_DIR/gstack-jsonl-merge %O %A %B"
git -C "$GSTACK_HOME" config merge.jsonl-append.name "gstack JSONL append-only merger"
git -C "$GSTACK_HOME" config merge.union.driver "cat %A %B > %A.merged && mv %A.merged %A"
git -C "$GSTACK_HOME" config merge.union.name "union concat"
# ---- install pre-commit hook (defense-in-depth) ----
HOOK="$GSTACK_HOME/.git/hooks/pre-commit"
mkdir -p "$(dirname "$HOOK")"
cat > "$HOOK" <<'HOOK_EOF'
#!/usr/bin/env bash
# gstack-brain pre-commit hook — secret-scan defense-in-depth.
# The primary scanner runs inside gstack-brain-sync BEFORE staging. This hook
# catches any manual `git commit` a user might accidentally run against the
# brain repo.
set -uo pipefail
python3 -c "
import sys, re, subprocess
try:
out = subprocess.check_output(['git', 'diff', '--cached'], stderr=subprocess.DEVNULL).decode('utf-8', 'replace')
except Exception:
sys.exit(0)
patterns = [
('aws-access-key', re.compile(r'AKIA[0-9A-Z]{16}')),
('github-token', re.compile(r'\b(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})')),
('openai-key', re.compile(r'\bsk-[A-Za-z0-9_-]{20,}')),
('pem-block', re.compile(r'-----BEGIN [A-Z ]{3,}-----')),
('jwt', re.compile(r'\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b')),
('bearer-token-json',
re.compile(r'\"(authorization|api[_-]?key|apikey|token|secret|password)\"\s*:\s*\"[A-Za-z0-9_./+=-]{16,}\"',
re.IGNORECASE)),
]
for name, rx in patterns:
if rx.search(out):
sys.stderr.write(f'gstack-brain pre-commit: refusing commit — {name} detected in staged diff.\n')
sys.stderr.write('Either edit the offending file, or if intentional, run:\n')
sys.stderr.write(' gstack-brain-sync --skip-file <path> (to permanently exclude)\n')
sys.exit(1)
sys.exit(0)
"
HOOK_EOF
chmod +x "$HOOK"
# ---- initial commit (idempotent; skips if already committed) ----
cd "$GSTACK_HOME"
git add -f .gitignore .brain-allowlist .brain-privacy-map.json .gitattributes
# Only commit if the index has changes from HEAD (if there is a HEAD).
if git rev-parse HEAD >/dev/null 2>&1; then
if ! git diff --cached --quiet 2>/dev/null; then
git -c user.email="gstack@localhost" -c user.name="gstack-brain-init" \
commit -q -m "chore: gstack-brain-init (refresh sync config)"
fi
else
# First commit ever.
git -c user.email="gstack@localhost" -c user.name="gstack-brain-init" \
commit -q -m "chore: gstack-brain-init"
fi
# ---- initial push ----
if ! git push -q -u origin main 2>/dev/null; then
# Maybe the default branch is master, or the remote has existing content.
# Try to resolve: fetch + fast-forward merge + push.
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
if git fetch origin 2>/dev/null && git pull --ff-only origin "$CURRENT_BRANCH" 2>/dev/null; then
git push -q -u origin "$CURRENT_BRANCH" || {
echo "Push to $REMOTE_URL failed. The remote may have divergent content." >&2
echo "Try: cd ~/.gstack && git pull --rebase origin $CURRENT_BRANCH && git push origin $CURRENT_BRANCH" >&2
exit 1
}
else
# Couldn't fetch/merge; print what to do.
echo "Push to $REMOTE_URL failed and fetch/merge didn't help." >&2
echo "Manual recovery: cd ~/.gstack && git status, then push once conflicts are resolved." >&2
exit 1
fi
fi
# ---- write the remote-url helper file (outside ~/.gstack/, survives restore) ----
echo "$REMOTE_URL" > "$REMOTE_FILE"
chmod 600 "$REMOTE_FILE"
# ---- done ----
cat <<EOF
gstack-brain-init complete.
Repo: $GSTACK_HOME (git)
Remote: $REMOTE_URL
Remote URL also saved at: $REMOTE_FILE
Sync to GitHub happens automatically at the start and end of each skill
(no daemon). Check status anytime with:
gstack-brain-sync --status
The next skill run will ask you one question about privacy mode (full /
artifacts-only / off). After that, /setup-gbrain Step 7 (or the
gstack-gbrain-source-wireup helper) registers this repo as a federated
source on gbrain so its content is searchable via 'gbrain search'.
New machine? On the other laptop, put a copy of:
$REMOTE_FILE
in that machine's home directory, then run: gstack-brain-restore
EOF

8
bin/gstack-brain-restore
View File

@ -30,7 +30,13 @@ set -euo pipefail
GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
CONFIG_BIN="$SCRIPT_DIR/gstack-config"
REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# v1.27.0.0+ canonical name; brain-remote is the legacy fallback during the
# migration window. The migration script renames the file in place.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
REMOTE_URL="${1:-}"
if [ -z "$REMOTE_URL" ]; then

6
bin/gstack-brain-sync
View File

@ -70,7 +70,7 @@ sync_active() {
return 1
fi
local mode
mode=$("$CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
mode=$("$CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
[ "$mode" = "off" ] && return 1
return 0
}
@ -236,7 +236,7 @@ subcmd_once() {
echo "$$" > "$lock_dir/pid" 2>/dev/null || true
local mode
mode=$("$CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
mode=$("$CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
local paths_file
paths_file=$(mktemp /tmp/brain-sync-paths.XXXXXX) || { rm -rf "$lock_dir" 2>/dev/null; write_status "error" "mktemp failed"; exit 1; }
@ -334,7 +334,7 @@ subcmd_status() {
local last_push="never"
[ -f "$LAST_PUSH_FILE" ] && last_push=$(cat "$LAST_PUSH_FILE" 2>/dev/null || echo never)
local mode
mode=$("$CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
mode=$("$CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
printf '{"queue_depth":%s,"last_push":"%s","mode":"%s"}\n' "$queue_depth" "$last_push" "$mode"
}

17
bin/gstack-brain-uninstall
View File

@ -28,8 +28,8 @@
# consumers.json — consumer/reader registry
#
# What it clears (via gstack-config):
# gbrain_sync_mode → off
# gbrain_sync_mode_prompted → false (so user re-prompts on re-init)
# artifacts_sync_mode → off
# artifacts_sync_mode_prompted → false (so user re-prompts on re-init)
#
# What it does NOT touch:
# Project data (projects/*, retros/*, developer-profile.json, etc.)
@ -42,7 +42,12 @@ set -euo pipefail
GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
CONFIG_BIN="$SCRIPT_DIR/gstack-config"
REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# v1.27.0.0+ canonical name; brain-remote is the legacy fallback during migration.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
ASSUME_YES=0
DELETE_REMOTE=0
@ -67,7 +72,7 @@ if [ "$ASSUME_YES" != "1" ]; then
cat <<EOF
This will remove gstack-brain sync from this machine:
- Remove ~/.gstack/.git and sync config files
- Clear gbrain_sync_mode in gstack-config
- Clear artifacts_sync_mode in gstack-config
- Remote: $REMOTE_URL will be $([ "$DELETE_REMOTE" = "1" ] && echo "DELETED" || echo "kept")
Local memory (learnings, plans, etc.) is NOT touched.
@ -133,8 +138,8 @@ fi
rm -f "$GSTACK_HOME/consumers.json" 2>/dev/null || true
# ---- clear config keys ----
"$CONFIG_BIN" set gbrain_sync_mode off >/dev/null 2>&1 || true
"$CONFIG_BIN" set gbrain_sync_mode_prompted false >/dev/null 2>&1 || true
"$CONFIG_BIN" set artifacts_sync_mode off >/dev/null 2>&1 || true
"$CONFIG_BIN" set artifacts_sync_mode_prompted false >/dev/null 2>&1 || true
# ---- leave remote-helper file alone unless user asked to delete remote ----
if [ "$DELETE_REMOTE" = "1" ]; then

18
bin/gstack-config
View File

@ -60,8 +60,8 @@ CONFIG_HEADER='# gstack configuration — edit freely, changes take effect on ne
# # Unknown values default to "default" with a warning.
# # See docs/designs/PLAN_TUNING_V1.md for rationale.
#
# ─── GBrain sync (v1.7+) ─────────────────────────────────────────────
# gbrain_sync_mode: off # off | artifacts-only | full
# ─── Artifacts sync (renamed from gbrain_sync_mode in v1.27.0.0) ─────
# artifacts_sync_mode: off # off | artifacts-only | full
# # off — no sync (default)
# # artifacts-only — sync plans/designs/retros/learnings only
# # (skip behavioral data: question-log,
@ -69,7 +69,7 @@ CONFIG_HEADER='# gstack configuration — edit freely, changes take effect on ne
# # full — sync everything allowlisted
# # Set by the first-run privacy stop-gate. See docs/gbrain-sync.md.
#
# gbrain_sync_mode_prompted: false
# artifacts_sync_mode_prompted: false
# # Set to true once the privacy gate has asked the user.
# # Flip back to false to be re-prompted.
#
@ -105,8 +105,8 @@ lookup_default() {
skip_eng_review) echo "false" ;;
workspace_root) echo "$HOME/conductor/workspaces" ;;
cross_project_learnings) echo "" ;; # intentionally empty → unset triggers first-time prompt
gbrain_sync_mode) echo "off" ;;
gbrain_sync_mode_prompted) echo "false" ;;
artifacts_sync_mode) echo "off" ;;
artifacts_sync_mode_prompted) echo "false" ;;
*) echo "" ;;
esac
}
@ -138,8 +138,8 @@ case "${1:-}" in
echo "Warning: explain_level '$VALUE' not recognized. Valid values: default, terse. Using default." >&2
VALUE="default"
fi
if [ "$KEY" = "gbrain_sync_mode" ] && [ "$VALUE" != "off" ] && [ "$VALUE" != "artifacts-only" ] && [ "$VALUE" != "full" ]; then
echo "Warning: gbrain_sync_mode '$VALUE' not recognized. Valid values: off, artifacts-only, full. Using off." >&2
if [ "$KEY" = "artifacts_sync_mode" ] && [ "$VALUE" != "off" ] && [ "$VALUE" != "artifacts-only" ] && [ "$VALUE" != "full" ]; then
echo "Warning: artifacts_sync_mode '$VALUE' not recognized. Valid values: off, artifacts-only, full. Using off." >&2
VALUE="off"
fi
mkdir -p "$STATE_DIR"
@ -171,7 +171,7 @@ case "${1:-}" in
for KEY in proactive routing_declined telemetry auto_upgrade update_check \
skill_prefix checkpoint_mode checkpoint_push codex_reviews \
gstack_contributor skip_eng_review workspace_root \
gbrain_sync_mode gbrain_sync_mode_prompted; do
artifacts_sync_mode artifacts_sync_mode_prompted; do
VALUE=$(grep -E "^${KEY}:" "$CONFIG_FILE" 2>/dev/null | tail -1 | awk '{print $2}' | tr -d '[:space:]' || true)
SOURCE="default"
if [ -n "$VALUE" ]; then
@ -187,7 +187,7 @@ case "${1:-}" in
for KEY in proactive routing_declined telemetry auto_upgrade update_check \
skill_prefix checkpoint_mode checkpoint_push codex_reviews \
gstack_contributor skip_eng_review workspace_root \
gbrain_sync_mode gbrain_sync_mode_prompted; do
artifacts_sync_mode artifacts_sync_mode_prompted; do
printf ' %-24s %s\n' "$KEY:" "$(lookup_default "$KEY")"
done
;;

84
bin/gstack-gbrain-detect
View File

@ -11,8 +11,10 @@
# "gbrain_config_exists": true|false,
# "gbrain_engine": "pglite"|"postgres" | null,
# "gbrain_doctor_ok": true|false,
# "gbrain_mcp_mode": "local-stdio"|"remote-http"|"none",
# "gstack_brain_sync_mode": "off"|"artifacts-only"|"full",
# "gstack_brain_git": true|false
# "gstack_brain_git": true|false,
# "gstack_artifacts_remote": "https://..." | ""
# }
#
# The /setup-gbrain skill reads this once at startup to decide which path
@ -78,10 +80,10 @@ if [ "$gbrain_on_path" = "true" ]; then
fi
fi
# --- gstack-brain-sync state (memory sync, separate from gbrain itself) ---
# --- artifacts sync state (renamed from gbrain_sync_mode in v1.27.0.0) ---
gstack_brain_sync_mode="off"
if [ -x "$CONFIG_BIN" ]; then
mode=$("$CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || true)
mode=$("$CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || true)
case "$mode" in
off|artifacts-only|full) gstack_brain_sync_mode="$mode" ;;
esac
@ -92,6 +94,76 @@ if [ -d "$STATE_DIR/.git" ]; then
gstack_brain_git=true
fi
# --- gbrain_mcp_mode: local-stdio | remote-http | none ---
# Defense-in-depth fallback chain (intentional ordering, do not reorder):
# 1. `claude mcp get gbrain --json` — public CLI surface, structured output
# 2. `claude mcp list` text-grep — older claude versions without --json
# 3. `~/.claude.json` jq read — last resort if `claude` isn't on PATH
# Fallback chain logged because if Anthropic moves the file or renames keys,
# the third tier breaks silently; the first two tiers should catch it.
gbrain_mcp_mode="none"
if command -v claude >/dev/null 2>&1; then
# Tier 1: claude mcp get --json
if mcp_get_json=$(claude mcp get gbrain --json 2>/dev/null); then
if echo "$mcp_get_json" | jq -e '.' >/dev/null 2>&1; then
mtype=$(echo "$mcp_get_json" | jq -r '.type // .transport // empty' 2>/dev/null)
mcommand=$(echo "$mcp_get_json" | jq -r '.command // empty' 2>/dev/null)
murl=$(echo "$mcp_get_json" | jq -r '.url // empty' 2>/dev/null)
case "$mtype" in
http|sse) gbrain_mcp_mode="remote-http" ;;
stdio) gbrain_mcp_mode="local-stdio" ;;
*)
# Newer claude versions may emit just url + command; infer.
if [ -n "$murl" ]; then gbrain_mcp_mode="remote-http"
elif [ -n "$mcommand" ]; then gbrain_mcp_mode="local-stdio"
fi
;;
esac
fi
fi
# Tier 2: claude mcp list text-grep (only if Tier 1 didn't resolve)
if [ "$gbrain_mcp_mode" = "none" ]; then
if mcp_list=$(claude mcp list 2>/dev/null); then
gbrain_line=$(echo "$mcp_list" | grep -E '^gbrain:' || true)
if [ -n "$gbrain_line" ]; then
if echo "$gbrain_line" | grep -q 'http\|HTTP'; then
gbrain_mcp_mode="remote-http"
else
gbrain_mcp_mode="local-stdio"
fi
fi
fi
fi
fi
# Tier 3: ~/.claude.json jq read (only if claude binary or earlier tiers failed)
if [ "$gbrain_mcp_mode" = "none" ]; then
if [ -f "$HOME/.claude.json" ]; then
# Look for a gbrain MCP server entry. Type field disambiguates http vs stdio.
mtype=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
murl=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null)
mcommand=$(jq -r '.mcpServers.gbrain.command // empty' "$HOME/.claude.json" 2>/dev/null)
case "$mtype" in
url|http|sse) gbrain_mcp_mode="remote-http" ;;
stdio) gbrain_mcp_mode="local-stdio" ;;
*)
if [ -n "$murl" ]; then gbrain_mcp_mode="remote-http"
elif [ -n "$mcommand" ]; then gbrain_mcp_mode="local-stdio"
fi
;;
esac
fi
fi
# --- artifacts remote URL (post-rename) with brain-* fallback during the
# migration window (gstack-upgrade migration runs the rename). ---
gstack_artifacts_remote=""
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
gstack_artifacts_remote=$(head -1 "$HOME/.gstack-artifacts-remote.txt" 2>/dev/null | tr -d '[:space:]' || true)
elif [ -f "$HOME/.gstack-brain-remote.txt" ]; then
# Pre-migration fallback. Migration v1.27.0.0 will mv this to the new path.
gstack_artifacts_remote=$(head -1 "$HOME/.gstack-brain-remote.txt" 2>/dev/null | tr -d '[:space:]' || true)
fi
# Emit single-object JSON.
jq -n \
--argjson on_path "$gbrain_on_path" \
@ -99,14 +171,18 @@ jq -n \
--argjson config_exists "$gbrain_config_exists" \
--argjson engine "$gbrain_engine" \
--argjson doctor_ok "$gbrain_doctor_ok" \
--arg mcp_mode "$gbrain_mcp_mode" \
--arg sync_mode "$gstack_brain_sync_mode" \
--argjson brain_git "$gstack_brain_git" \
--arg artifacts_remote "$gstack_artifacts_remote" \
'{
gbrain_on_path: $on_path,
gbrain_version: $version,
gbrain_config_exists: $config_exists,
gbrain_engine: $engine,
gbrain_doctor_ok: $doctor_ok,
gbrain_mcp_mode: $mcp_mode,
gstack_brain_sync_mode: $sync_mode,
gstack_brain_git: $brain_git
gstack_brain_git: $brain_git,
gstack_artifacts_remote: $artifacts_remote
}'

179
bin/gstack-gbrain-mcp-verify Executable file
View File

@ -0,0 +1,179 @@
#!/usr/bin/env bash
# gstack-gbrain-mcp-verify — probe a remote gbrain MCP endpoint.
#
# Usage:
# GBRAIN_MCP_TOKEN=<bearer> gstack-gbrain-mcp-verify <url>
#
# Output (always valid JSON):
# {
# "status": "success" | "network" | "auth" | "malformed",
# "server_name": "gbrain" | null,
# "server_version": "0.26.8" | null,
# "error_class": "NETWORK" | "AUTH" | "MALFORMED" | null,
# "error_text": "<remediation hint + raw>" | null,
# "sources_add_url_supported": true | false,
# "raw_initialize_body": "<full body for debugging>" | null
# }
#
# Token is consumed from the GBRAIN_MCP_TOKEN env var, never argv. Prevents
# shell-history / `ps` exposure of the bearer.
#
# Three error classes:
# NETWORK — DNS / TCP / no HTTP response
# AUTH — 401, 403, or 500 with stale-token-shaped body
# MALFORMED — 2xx but missing serverInfo, OR `Not Acceptable` (the dual
# Accept-header gotcha)
#
# `sources_add_url_supported` probes capability via tools/list — true iff the
# remote exposes `mcp__gbrain__sources_add` (gbrain hasn't shipped this as
# of v0.26.x; field is forward-compatible).
#
# Exit codes: 0 on success, 1 on classified failure, 2 on usage error.
set -euo pipefail
die_usage() {
echo "Usage: GBRAIN_MCP_TOKEN=<bearer> gstack-gbrain-mcp-verify <url>" >&2
exit 2
}
[ $# -eq 1 ] || die_usage
URL="$1"
[ -n "${GBRAIN_MCP_TOKEN:-}" ] || { echo "gstack-gbrain-mcp-verify: GBRAIN_MCP_TOKEN env var required" >&2; exit 2; }
command -v curl >/dev/null 2>&1 || { echo "gstack-gbrain-mcp-verify: curl is required" >&2; exit 2; }
command -v jq >/dev/null 2>&1 || { echo "gstack-gbrain-mcp-verify: jq is required (brew install jq)" >&2; exit 2; }
emit() {
# emit <status> <server_name> <server_version> <error_class> <error_text> <url_supported> <raw_body>
jq -n \
--arg status "$1" \
--arg server_name "${2:-}" \
--arg server_version "${3:-}" \
--arg error_class "${4:-}" \
--arg error_text "${5:-}" \
--argjson url_supported "${6:-false}" \
--arg raw "${7:-}" \
'{
status: $status,
server_name: (if $server_name == "" then null else $server_name end),
server_version: (if $server_version == "" then null else $server_version end),
error_class: (if $error_class == "" then null else $error_class end),
error_text: (if $error_text == "" then null else $error_text end),
sources_add_url_supported: $url_supported,
raw_initialize_body: (if $raw == "" then null else $raw end)
}'
}
# JSON-RPC initialize body. Both `application/json` AND `text/event-stream`
# in Accept — the MCP server returns 406 Not Acceptable without both. The
# transcript that motivated this script hit that exact failure.
INIT_BODY='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"gstack-mcp-verify","version":"1"}}}'
# Capture HTTP code + body in one pass; --max-time 10 caps total wall time.
TMPBODY=$(mktemp -t gstack-mcp-verify.XXXXXX)
trap 'rm -f "$TMPBODY"' EXIT
set +e
HTTP_CODE=$(curl -s -o "$TMPBODY" -w '%{http_code}' \
--max-time 10 \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H "Authorization: Bearer $GBRAIN_MCP_TOKEN" \
-d "$INIT_BODY" \
"$URL" 2>/dev/null)
CURL_EXIT=$?
set -e
BODY=$(cat "$TMPBODY" 2>/dev/null || echo "")
# --- NETWORK class: curl exited nonzero, no HTTP response ---
if [ "$CURL_EXIT" -ne 0 ] || [ -z "$HTTP_CODE" ] || [ "$HTTP_CODE" = "000" ]; then
HOST=$(echo "$URL" | sed -E 's|^https?://([^/:]+).*|\1|')
emit "network" "" "" "NETWORK" "check Tailscale/DNS to ${HOST} (curl exit=${CURL_EXIT})" false "$BODY"
exit 1
fi
# --- AUTH class: 401, 403, or 500 with stale-token-shaped body ---
case "$HTTP_CODE" in
401|403)
emit "auth" "" "" "AUTH" "rotate token on the brain host, re-run /setup-gbrain (HTTP $HTTP_CODE)" false "$BODY"
exit 1
;;
500)
if echo "$BODY" | grep -qiE '"(error_description|message)":[[:space:]]*"[^"]*(auth|token|unauthorized)' 2>/dev/null; then
emit "auth" "" "" "AUTH" "rotate token on the brain host, re-run /setup-gbrain (HTTP 500 stale-token shape)" false "$BODY"
exit 1
fi
;;
esac
# Anything not 2xx that isn't auth-shaped → MALFORMED with raw HTTP code.
case "$HTTP_CODE" in
2*) ;;
*)
emit "malformed" "" "" "MALFORMED" "server returned HTTP $HTTP_CODE; verify URL + version compatibility" false "$BODY"
exit 1
;;
esac
# --- 2xx path: body may be JSON or SSE-wrapped JSON. Strip SSE if present. ---
# MCP servers return SSE format: `event: message\ndata: {...}\n\n`. Extract
# just the JSON payload from the data: line, falling back to the body as-is.
if echo "$BODY" | head -1 | grep -q '^event:'; then
JSON_BODY=$(echo "$BODY" | sed -n 's/^data: //p' | head -1)
else
JSON_BODY="$BODY"
fi
# `Not Acceptable` is a JSON-RPC error from the MCP server itself, returned
# with HTTP 200 if the SSE Accept header was missing. Detect it explicitly.
if echo "$JSON_BODY" | jq -e '.error.message | test("[Nn]ot [Aa]cceptable")' >/dev/null 2>&1; then
emit "malformed" "" "" "MALFORMED" "Accept-header gotcha: pass both 'application/json' AND 'text/event-stream'" false "$BODY"
exit 1
fi
SERVER_NAME=$(echo "$JSON_BODY" | jq -r '.result.serverInfo.name // empty' 2>/dev/null)
SERVER_VERSION=$(echo "$JSON_BODY" | jq -r '.result.serverInfo.version // empty' 2>/dev/null)
if [ -z "$SERVER_NAME" ] || [ -z "$SERVER_VERSION" ]; then
emit "malformed" "" "" "MALFORMED" "server may be on a newer gbrain version; missing result.serverInfo. Verify with: curl -H 'Accept: application/json, text/event-stream'" false "$BODY"
exit 1
fi
# --- Capability probe: tools/list to detect sources_add ---
# Best-effort. A failure here doesn't fail the verify; we just default
# sources_add_url_supported=false. Future gbrain versions that ship
# mcp__gbrain__sources_add will flip this true and gstack-artifacts-init
# will print the one-liner form instead of the clone-then-path form.
URL_SUPPORTED=false
TOOLS_BODY_FILE=$(mktemp -t gstack-mcp-tools.XXXXXX)
TOOLS_REQ='{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
set +e
curl -s -o "$TOOLS_BODY_FILE" \
--max-time 10 \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H "Authorization: Bearer $GBRAIN_MCP_TOKEN" \
-d "$TOOLS_REQ" \
"$URL" >/dev/null 2>&1
TOOLS_EXIT=$?
set -e
if [ "$TOOLS_EXIT" -eq 0 ]; then
TOOLS_BODY=$(cat "$TOOLS_BODY_FILE" 2>/dev/null || echo "")
if echo "$TOOLS_BODY" | head -1 | grep -q '^event:'; then
TOOLS_JSON=$(echo "$TOOLS_BODY" | sed -n 's/^data: //p' | head -1)
else
TOOLS_JSON="$TOOLS_BODY"
fi
if echo "$TOOLS_JSON" | jq -e '.result.tools[] | select(.name | test("sources_add"))' >/dev/null 2>&1; then
URL_SUPPORTED=true
fi
fi
rm -f "$TOOLS_BODY_FILE"
emit "success" "$SERVER_NAME" "$SERVER_VERSION" "" "" "$URL_SUPPORTED" "$BODY"
exit 0

7
bin/gstack-gbrain-source-wireup
View File

@ -44,7 +44,12 @@ CONFIG_BIN="$SCRIPT_DIR/gstack-config"
GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
WORKTREE="${GSTACK_BRAIN_WORKTREE:-$HOME/.gstack-brain-worktree}"
REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# v1.27.0.0+ canonical name; brain-remote is the legacy fallback during migration.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
PLIST_PATH="$HOME/Library/LaunchAgents/com.gstack.brain-sync.plist"
GBRAIN_CONFIG="$HOME/.gbrain/config.json"

46
bin/gstack-gbrain-sync.ts
View File

@ -33,6 +33,7 @@ import { existsSync, statSync, mkdirSync, writeFileSync, readFileSync, unlinkSyn
import { join, dirname } from "path";
import { execSync, execFileSync, spawnSync } from "child_process";
import { homedir } from "os";
import { createHash } from "crypto";
import { detectEngineTier, withErrorContext, canonicalizeRemote } from "../lib/gstack-memory-helpers";
import { sourcePageCount } from "../lib/gbrain-sources";
@ -158,20 +159,51 @@ function originUrl(): string | null {
}
/**
* Derive a stable source id for the cwd code corpus. Pattern: `gstack-code-<slug>`,
* where <slug> comes from canonicalizeRemote() then `/` → `-` (e.g.,
* `github.com/garrytan/gstack` → `gstack-code-github-com-garrytan-gstack`).
* Derive a stable source id for the cwd code corpus. Pattern: `gstack-code-<slug>`.
*
* Falls back to `gstack-code-<basename(repo)>` when there is no origin (local repo).
* gbrain enforces source ids to be 1-32 lowercase alnum chars with optional interior
* hyphens. We use the last two segments of the canonical remote (org/repo) and skip
* the host — `github.com` etc. is the same for nearly every user and just eats budget.
* If the resulting id still exceeds 32 chars, we keep the tail (most distinctive end)
* and append a 6-char hash of the full slug for collision resistance.
*
* Falls back to the repo basename when there is no origin (local repo).
*/
function deriveCodeSourceId(repoPath: string): string {
const remote = canonicalizeRemote(originUrl());
if (remote) {
return `gstack-code-${remote.replace(/[\/\s]+/g, "-").replace(/-+/g, "-")}`;
const segs = remote.split("/").filter(Boolean);
const slugSource = segs.slice(-2).join("-");
return constrainSourceId("gstack-code", slugSource);
}
// Fallback for repos without a remote.
const base = repoPath.split("/").pop() || "repo";
return `gstack-code-${base.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/-+/g, "-")}`;
return constrainSourceId("gstack-code", base);
}
/**
* Build a gbrain-valid source id (1-32 lowercase alnum + interior hyphens). Sanitizes
* `raw`, prefixes with `prefix`, and falls back to a hashed-tail form when total length
* would exceed 32 chars.
*/
function constrainSourceId(prefix: string, raw: string): string {
const MAX = 32;
const slug = raw.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
// Empty slug after sanitize (e.g. raw was all non-alnum like "___") would
// produce "${prefix}-" which fails gbrain's validator on the trailing
// hyphen. Fall back to a deterministic hash of the original input so the
// result is stable across runs of the same repo.
if (!slug) {
const hash = createHash("sha1").update(raw || "_empty").digest("hex").slice(0, 6);
return `${prefix}-${hash}`;
}
const full = `${prefix}-${slug}`;
if (full.length <= MAX) return full;
const hash = createHash("sha1").update(slug).digest("hex").slice(0, 6);
// Total budget: prefix + "-" + tail + "-" + hash
const tailBudget = MAX - prefix.length - 2 - hash.length;
if (tailBudget < 1) return `${prefix}-${hash}`;
const tail = slug.slice(-tailBudget).replace(/^-+|-+$/g, "");
return tail ? `${prefix}-${tail}-${hash}` : `${prefix}-${hash}`;
}
function gbrainAvailable(): boolean {

2
bin/gstack-jsonl-merge
View File

@ -4,7 +4,7 @@
# Usage (called by git, not by users):
# gstack-jsonl-merge <base> <ours> <theirs>
#
# Registered in local git config by bin/gstack-brain-init and
# Registered in local git config by bin/gstack-artifacts-init and
# bin/gstack-brain-restore:
# git config merge.jsonl-append.driver \
# "$GSTACK_BIN/gstack-jsonl-merge %O %A %B"

84
bin/gstack-memory-ingest.ts
View File

@ -34,8 +34,9 @@
* keep V1 ship-tight. See TODOS.md.
*
* V1.5 NOTE: When `gbrain put_file` ships in the gbrain CLI (cross-repo P0 TODO),
* transcripts will route to Supabase Storage instead of put_page. Until then, all
* content rides put_page; gbrain's native dedup keys on session_id.
* transcripts will route to Supabase Storage instead of the page-write path.
* Until then, all content rides `gbrain put <slug>` (stdin, YAML frontmatter for
* title/type/tags); gbrain's native dedup keys on session_id.
*/
import {
@ -745,14 +746,25 @@ function buildArtifactPage(path: string, type: MemoryType): PageRecord {
};
}
// ── Writer (calls gbrain put_page) ─────────────────────────────────────────
// ── Writer (calls `gbrain put`) ────────────────────────────────────────────
let _gbrainAvailability: boolean | null = null;
function gbrainAvailable(): boolean {
if (_gbrainAvailability !== null) return _gbrainAvailability;
try {
execSync("command -v gbrain", { stdio: "ignore" });
_gbrainAvailability = true;
// gbrain v0.27 retired the legacy `put_page` flag-form for `put <slug>`
// (content via stdin, metadata as YAML frontmatter). Probe `--help` for
// the `put` subcommand so we surface a single clean error here rather
// than failing every page with "Unknown command: put_page". The regex
// anchors on the indented subcommand format gbrain's help actually uses
// (" put ..."), not any whitespace-bordered "put" word in prose.
const help = execFileSync("gbrain", ["--help"], {
encoding: "utf-8",
timeout: 5000,
stdio: ["ignore", "pipe", "pipe"],
});
_gbrainAvailability = /^\s+put\s/m.test(help);
} catch {
_gbrainAvailability = false;
}
@ -761,25 +773,63 @@ function gbrainAvailable(): boolean {
function gbrainPutPage(page: PageRecord): { ok: boolean; error?: string } {
if (!gbrainAvailable()) {
return { ok: false, error: "gbrain CLI not in PATH" };
return { ok: false, error: "gbrain CLI not in PATH or missing `put` subcommand" };
}
// gbrain v0.27+ uses `put <slug>` (positional, content via stdin) instead
// of the legacy `put_page` flag form. Metadata rides as YAML frontmatter:
// - When the page body already starts with frontmatter (transcripts), inject
// title/type/tags into the existing block so gbrain's frontmatter parser
// picks them up.
// - When the page body has no frontmatter (raw artifacts: design-docs,
// learnings, builder-profile-entries), wrap with a fresh frontmatter
// carrying the same fields. Without this branch, artifact pages would
// land in gbrain with empty title/type/tags.
let body = page.body;
if (body.startsWith("---\n")) {
// Locate the closing --- delimiter. buildTranscriptPage joins with "\n"
// and does not append a trailing newline, so the close fence looks like
// "...\n---" followed directly by body content (no "\n---\n" pattern).
// Match the close on "\n---" only — the inject lands BEFORE the close
// fence, inside the frontmatter block, regardless of what follows it.
const end = body.indexOf("\n---", 4);
if (end > 0) {
const inject = [
`title: ${JSON.stringify(page.title)}`,
`type: ${page.type}`,
`tags:`,
...page.tags.map((t) => ` - ${t}`),
].join("\n");
body = body.slice(0, end) + "\n" + inject + body.slice(end);
}
} else {
body = [
"---",
`title: ${JSON.stringify(page.title)}`,
`type: ${page.type}`,
`tags: [${page.tags.map((t) => JSON.stringify(t)).join(", ")}]`,
"---",
"",
body,
].join("\n");
}
try {
const args = [
"put_page",
"--slug", page.slug,
"--title", page.title,
"--type", page.type,
"--tags", page.tags.join(","),
];
execFileSync("gbrain", args, {
input: page.body,
execFileSync("gbrain", ["put", page.slug], {
input: body,
encoding: "utf-8",
timeout: 30000,
// Bumped from 30s: auto-link reconciliation on dense transcripts hits
// 30s once the brain has a few hundred existing pages.
timeout: 60000,
// Bumped from default 1MB: without this, gbrain's actual stderr gets
// truncated and callers see only "Command failed:" with no detail.
maxBuffer: 16 * 1024 * 1024,
stdio: ["pipe", "pipe", "pipe"],
});
return { ok: true };
} catch (err) {
return { ok: false, error: err instanceof Error ? err.message : String(err) };
} catch (err: any) {
const stderr = err?.stderr?.toString?.() ?? "";
const stdout = err?.stdout?.toString?.() ?? "";
const detail = stderr || stdout || (err instanceof Error ? err.message : String(err));
return { ok: false, error: detail.split("\n")[0].slice(0, 300) };
}
}

4
bin/gstack-timeline-log
View File

@ -2,9 +2,9 @@
# gstack-timeline-log — append a timeline event to the project timeline
# Usage: gstack-timeline-log '{"skill":"review","event":"started","branch":"main"}'
#
# Session timeline: local by default. If the user enables `gbrain_sync_mode`
# Session timeline: local by default. If the user enables `artifacts_sync_mode`
# with the `full` (not `artifacts-only`) privacy tier — via the first-run
# stop-gate from `gstack-brain-init` or the preamble — timeline events are
# stop-gate from `gstack-artifacts-init` or the preamble — timeline events are
# published to the user's private GBrain sync repo. See docs/gbrain-sync.md.
# Required fields: skill, event (started|completed).
# Optional: branch, outcome, duration_s, session, ts.

50
browse/SKILL.md
View File

@ -271,11 +271,17 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
- Focus on completing the task and reporting results via prose output.
- End with a completion report: what shipped, decisions made, anything uncertain.
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -308,13 +314,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -334,22 +353,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -360,11 +384,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
canary/SKILL.md
View File

@ -330,11 +330,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -367,13 +373,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -393,22 +412,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -419,11 +443,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
codex/SKILL.md
View File

@ -332,11 +332,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -369,13 +375,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -395,22 +414,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -421,11 +445,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
context-restore/SKILL.md
View File

@ -334,11 +334,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -371,13 +377,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -397,22 +416,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -423,11 +447,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
context-save/SKILL.md
View File

@ -334,11 +334,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -371,13 +377,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -397,22 +416,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -423,11 +447,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
cso/SKILL.md
View File

@ -335,11 +335,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -372,13 +378,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -398,22 +417,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -424,11 +448,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
design-consultation/SKILL.md
View File

@ -358,11 +358,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -395,13 +401,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -421,22 +440,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -447,11 +471,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
design-html/SKILL.md
View File

@ -337,11 +337,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -374,13 +380,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -400,22 +419,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -426,11 +450,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
design-review/SKILL.md
View File

@ -335,11 +335,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -372,13 +378,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -398,22 +417,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -424,11 +448,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
design-shotgun/SKILL.md
View File

@ -352,11 +352,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -389,13 +395,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -415,22 +434,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -441,11 +465,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
devex-review/SKILL.md
View File

@ -335,11 +335,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -372,13 +378,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -398,22 +417,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -424,11 +448,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
document-release/SKILL.md
View File

@ -332,11 +332,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -369,13 +375,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -395,22 +414,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -421,11 +445,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

344
gstack-upgrade/migrations/v1.27.0.0.sh Executable file
View File

@ -0,0 +1,344 @@
#!/usr/bin/env bash
# Migration: v1.27.0.0 — rename gstack-brain-* → gstack-artifacts-*
#
# Phase C of the v1.27.0.0 plan. Hard-rename, no compat shim. Steps:
# 1. gh_repo_renamed — gh/glab repo rename gstack-brain-$USER →
# gstack-artifacts-$USER (skipped on user opt-out)
# 2. remote_txt_renamed — mv ~/.gstack-brain-remote.txt → artifacts-remote.txt
# 3. config_key_renamed — rewrite gbrain_sync_mode → artifacts_sync_mode
# in ~/.gstack/config.yaml
# 4. claude_md_block_rewritten — find-and-replace any existing GBrain
# Configuration block that references "Memory sync"
# 5. sources_swapped — gbrain sources add new (verify) → remove old
# (codex Finding #6: add-before-remove ordering)
# 6. done — write touchfile, delete journal
#
# Interruption-safe via journal at ~/.gstack/.migrations/v1.27.0.0.journal:
# each step writes its name on success; re-entry resumes from the next un-done
# step. Done touchfile at ~/.gstack/.migrations/v1.27.0.0.done.
#
# Three host-mode branches per the plan:
# Local CLI + GitHub — all steps run automatically
# Local CLI + GitLab — same with glab repo rename
# Remote MCP only — steps 1-4 still run; step 5 prints commands for
# the brain admin to run on the brain host
#
# All steps are idempotent. Re-running after partial completion is safe.
set -euo pipefail
if [ -z "${HOME:-}" ]; then
echo " [v1.27.0.0] HOME is unset — skipping migration." >&2
exit 0
fi
# ---------------------------------------------------------------------------
# Configuration
# ---------------------------------------------------------------------------
GSTACK_HOME="${HOME}/.gstack"
SKILLS_DIR="${HOME}/.claude/skills"
BIN_DIR="${SKILLS_DIR}/gstack/bin"
CONFIG_BIN="${BIN_DIR}/gstack-config"
URL_BIN="${BIN_DIR}/gstack-artifacts-url"
MIGRATION_DIR="${GSTACK_HOME}/.migrations"
JOURNAL="${MIGRATION_DIR}/v1.27.0.0.journal"
DONE="${MIGRATION_DIR}/v1.27.0.0.done"
SKIPPED="${MIGRATION_DIR}/v1.27.0.0.skipped-by-user"
USER_NAME="${USER:-$(whoami 2>/dev/null || echo unknown)}"
OLD_REPO_NAME="gstack-brain-${USER_NAME}"
NEW_REPO_NAME="gstack-artifacts-${USER_NAME}"
OLD_REMOTE_TXT="${HOME}/.gstack-brain-remote.txt"
NEW_REMOTE_TXT="${HOME}/.gstack-artifacts-remote.txt"
OLD_SOURCE_ID="${OLD_REPO_NAME}"
NEW_SOURCE_ID="${NEW_REPO_NAME}"
# ---------------------------------------------------------------------------
# Journal helpers
# ---------------------------------------------------------------------------
mkdir -p "$MIGRATION_DIR"
# Already done? exit silently.
[ -f "$DONE" ] && exit 0
# User opted out previously? exit silently. (Re-invoke via
# `/setup-gbrain --rerun-migration` removes this marker.)
[ -f "$SKIPPED" ] && exit 0
journal_done() {
# Returns 0 if the named step is recorded as complete in the journal.
local step="$1"
[ -f "$JOURNAL" ] && grep -q "^${step}$" "$JOURNAL" 2>/dev/null
}
mark_done() {
local step="$1"
echo "$step" >> "$JOURNAL"
}
# ---------------------------------------------------------------------------
# Detect environment + ask once if there's anything to migrate
# ---------------------------------------------------------------------------
# Has the user ever opted into brain sync? Two signals:
# - presence of ~/.gstack-brain-remote.txt (legacy file)
# - presence of ~/.gstack/.git (brain-init ever ran)
HAS_LEGACY_STATE=0
[ -f "$OLD_REMOTE_TXT" ] && HAS_LEGACY_STATE=1
[ -d "$GSTACK_HOME/.git" ] && HAS_LEGACY_STATE=1
# If nothing to migrate, finalize silently.
if [ "$HAS_LEGACY_STATE" = "0" ]; then
echo " [v1.27.0.0] no legacy gstack-brain state detected — nothing to migrate." >&2
touch "$DONE"
rm -f "$JOURNAL" 2>/dev/null || true
exit 0
fi
# Ask once (idempotent: if journal exists from a prior partial run, skip ask).
if [ ! -f "$JOURNAL" ]; then
cat >&2 <<EOF
[v1.27.0.0] gstack-brain has been renamed to gstack-artifacts.
This is a clearer name for what it actually holds: CEO plans, designs,
/investigate reports, retros (i.e. artifacts, not behavioral memory).
This migration will:
1. Rename your private GitHub/GitLab repo "$OLD_REPO_NAME" → "$NEW_REPO_NAME"
2. mv ~/.gstack-brain-remote.txt → ~/.gstack-artifacts-remote.txt
3. Rename gbrain_sync_mode → artifacts_sync_mode in ~/.gstack/config.yaml
4. Update any "## GBrain Configuration" block in CLAUDE.md
5. Update gbrain federated source registration (local CLI mode)
OR print commands for your brain admin (remote MCP mode)
Each step is journaled so a Ctrl-C mid-flight is safe to re-run.
EOF
if [ -t 0 ]; then
printf " Proceed? [Y/n/skip-for-now]: " >&2
read -r REPLY || REPLY=""
case "$REPLY" in
n|N|no|No|NO)
echo " Skipping migration. Re-run via /setup-gbrain --rerun-migration." >&2
touch "$SKIPPED"
exit 0
;;
skip|skip-for-now|s)
echo " Skipping for now. Will ask again next upgrade." >&2
# Don't write SKIPPED — leave both old + new state untouched, ask again next time.
exit 0
;;
esac
else
# Non-interactive (CI, scripted upgrade): proceed automatically.
echo " (non-interactive: proceeding automatically)" >&2
fi
fi
# ---------------------------------------------------------------------------
# Detect host (gh / glab / manual) for steps 1 + 5
# ---------------------------------------------------------------------------
detect_host() {
# Read the canonical-form remote URL (the legacy file in the migration window).
local url=""
if [ -f "$OLD_REMOTE_TXT" ]; then
url=$(head -1 "$OLD_REMOTE_TXT" 2>/dev/null | tr -d '[:space:]' || echo "")
elif [ -f "$NEW_REMOTE_TXT" ]; then
url=$(head -1 "$NEW_REMOTE_TXT" 2>/dev/null | tr -d '[:space:]' || echo "")
fi
if echo "$url" | grep -q 'github\.com'; then
echo "github"
elif echo "$url" | grep -q 'gitlab'; then
echo "gitlab"
else
echo "manual"
fi
}
HOST=$(detect_host)
# ---------------------------------------------------------------------------
# Detect MCP mode (so step 5 knows whether to execute or print)
# ---------------------------------------------------------------------------
detect_mcp_mode() {
# Cheap probe: ~/.claude.json type field. Defense-in-depth tier 3 only;
# the migration script avoids invoking `claude` to keep upgrade fast.
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
local t
t=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$t" in
url|http|sse) echo "remote-http"; return ;;
stdio) echo "local-stdio"; return ;;
esac
fi
echo "none"
}
MCP_MODE=$(detect_mcp_mode)
# ---------------------------------------------------------------------------
# Step 1: gh/glab repo rename
# ---------------------------------------------------------------------------
if ! journal_done "gh_repo_renamed"; then
echo " [v1.27.0.0] step 1: rename remote repo $OLD_REPO_NAME → $NEW_REPO_NAME" >&2
case "$HOST" in
github)
if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
# Idempotent: if new name already exists, treat as success.
if gh repo view "$NEW_REPO_NAME" >/dev/null 2>&1; then
echo " repo already named $NEW_REPO_NAME on GitHub — no-op" >&2
mark_done "gh_repo_renamed"
else
if gh repo rename "$NEW_REPO_NAME" --repo "$OLD_REPO_NAME" --yes 2>/dev/null \
|| gh repo edit "$OLD_REPO_NAME" --name "$NEW_REPO_NAME" 2>/dev/null; then
echo " renamed on GitHub" >&2
mark_done "gh_repo_renamed"
else
echo " WARNING: gh rename failed (repo may not exist or permission denied)" >&2
echo " skipping step 1; subsequent steps still run" >&2
mark_done "gh_repo_renamed"
fi
fi
else
echo " gh CLI not available — skipping rename step (manual: gh repo rename ...)" >&2
mark_done "gh_repo_renamed"
fi
;;
gitlab)
if command -v glab >/dev/null 2>&1 && glab auth status >/dev/null 2>&1; then
if glab repo view "$NEW_REPO_NAME" >/dev/null 2>&1; then
echo " repo already named $NEW_REPO_NAME on GitLab — no-op" >&2
mark_done "gh_repo_renamed"
else
# GitLab CLI doesn't have a direct rename; user has to do it via API.
echo " glab repo rename isn't a single command on GitLab." >&2
echo " Manual: visit your GitLab project Settings → General → Advanced → Rename" >&2
echo " or use: glab api projects/:id -X PUT -f name=$NEW_REPO_NAME -f path=$NEW_REPO_NAME" >&2
mark_done "gh_repo_renamed"
fi
else
echo " glab not available — manual rename required" >&2
mark_done "gh_repo_renamed"
fi
;;
manual|*)
echo " unknown host (not github/gitlab) — manual rename required" >&2
mark_done "gh_repo_renamed"
;;
esac
fi
# ---------------------------------------------------------------------------
# Step 2: rename ~/.gstack-brain-remote.txt → ~/.gstack-artifacts-remote.txt
# ---------------------------------------------------------------------------
if ! journal_done "remote_txt_renamed"; then
echo " [v1.27.0.0] step 2: rename ~/.gstack-brain-remote.txt → ~/.gstack-artifacts-remote.txt" >&2
if [ -f "$OLD_REMOTE_TXT" ] && [ ! -f "$NEW_REMOTE_TXT" ]; then
# Update the URL inside if the rename happened on the host: replace
# gstack-brain-$USER with gstack-artifacts-$USER in the URL.
OLD_URL=$(head -1 "$OLD_REMOTE_TXT" 2>/dev/null)
NEW_URL=$(echo "$OLD_URL" | sed "s|/${OLD_REPO_NAME}|/${NEW_REPO_NAME}|; s|:${OLD_REPO_NAME}|:${NEW_REPO_NAME}|")
echo "$NEW_URL" > "$NEW_REMOTE_TXT"
chmod 600 "$NEW_REMOTE_TXT"
rm -f "$OLD_REMOTE_TXT"
echo " moved + URL rewritten: $OLD_URL → $NEW_URL" >&2
elif [ -f "$NEW_REMOTE_TXT" ]; then
echo " new file already exists — no-op" >&2
rm -f "$OLD_REMOTE_TXT" 2>/dev/null || true
else
echo " no $OLD_REMOTE_TXT to migrate — no-op" >&2
fi
mark_done "remote_txt_renamed"
fi
# ---------------------------------------------------------------------------
# Step 3: rename gbrain_sync_mode → artifacts_sync_mode in config.yaml
# ---------------------------------------------------------------------------
if ! journal_done "config_key_renamed"; then
echo " [v1.27.0.0] step 3: rename gbrain_sync_mode → artifacts_sync_mode in config.yaml" >&2
CFG="$GSTACK_HOME/config.yaml"
if [ -f "$CFG" ]; then
# Atomic in-place rewrite with a tmpfile.
TMP=$(mktemp "${CFG}.v1.27.0.0.XXXXXX")
sed -e 's/^gbrain_sync_mode:/artifacts_sync_mode:/' \
-e 's/^gbrain_sync_mode_prompted:/artifacts_sync_mode_prompted:/' \
"$CFG" > "$TMP" && mv "$TMP" "$CFG"
echo " rewritten in place" >&2
else
echo " no $CFG to migrate — no-op" >&2
fi
mark_done "config_key_renamed"
fi
# ---------------------------------------------------------------------------
# Step 4: rewrite CLAUDE.md "## GBrain Configuration" block fields
# ---------------------------------------------------------------------------
if ! journal_done "claude_md_block_rewritten"; then
echo " [v1.27.0.0] step 4: rewrite CLAUDE.md GBrain Configuration block fields" >&2
# Look in cwd's CLAUDE.md (where /setup-gbrain wrote it) and ~/.gstack/CLAUDE.md
# if it exists. We can't know every project's CLAUDE.md; users rerunning
# /setup-gbrain in any project will overwrite that block fresh anyway.
for CMD in "$PWD/CLAUDE.md" "$GSTACK_HOME/CLAUDE.md"; do
[ -f "$CMD" ] || continue
if grep -q "## GBrain Configuration" "$CMD"; then
TMP=$(mktemp "${CMD}.v1.27.0.0.XXXXXX")
sed -e 's/^- Memory sync:/- Artifacts sync:/' "$CMD" > "$TMP" && mv "$TMP" "$CMD"
echo " rewritten field in $CMD" >&2
fi
done
mark_done "claude_md_block_rewritten"
fi
# ---------------------------------------------------------------------------
# Step 5: gbrain sources swap (add-new before remove-old per codex Finding #6)
# ---------------------------------------------------------------------------
if ! journal_done "sources_swapped"; then
echo " [v1.27.0.0] step 5: gbrain federated source rename" >&2
if [ "$MCP_MODE" = "remote-http" ]; then
# Print commands for the brain admin; we can't execute them locally.
cat >&2 <<EOF
Remote MCP detected. The local gbrain CLI can't update the brain's
federated source registration. Send this to your brain admin:
gbrain sources add ${NEW_SOURCE_ID} --path <new-clone-path> --federated
# verify the new source is searching as expected, then:
gbrain sources remove ${OLD_SOURCE_ID} --yes
(Add-new before remove-old keeps search uninterrupted.)
EOF
mark_done "sources_swapped"
elif command -v gbrain >/dev/null 2>&1 && [ -d "$GSTACK_HOME/.git" ]; then
# Local CLI mode. Sources point at the worktree path; rename the source
# ID add-then-remove. The actual on-disk worktree path stays the same.
WORKTREE="${GSTACK_BRAIN_WORKTREE:-$HOME/.gstack-brain-worktree}"
if gbrain sources list 2>/dev/null | grep -q "$OLD_SOURCE_ID"; then
if gbrain sources add "$NEW_SOURCE_ID" --path "$WORKTREE" --federated 2>/dev/null; then
echo " added $NEW_SOURCE_ID" >&2
if gbrain sources remove "$OLD_SOURCE_ID" --yes 2>/dev/null; then
echo " removed $OLD_SOURCE_ID" >&2
else
echo " WARNING: failed to remove $OLD_SOURCE_ID; both registered. Run manually:" >&2
echo " gbrain sources remove $OLD_SOURCE_ID --yes" >&2
fi
else
echo " WARNING: failed to add $NEW_SOURCE_ID. Old source still registered." >&2
fi
else
echo " no $OLD_SOURCE_ID source registered — no-op" >&2
fi
mark_done "sources_swapped"
else
echo " gbrain CLI not available or no ~/.gstack/.git — skipping" >&2
mark_done "sources_swapped"
fi
fi
# ---------------------------------------------------------------------------
# Step 6: finalize (touchfile + clear journal)
# ---------------------------------------------------------------------------
touch "$DONE"
rm -f "$JOURNAL"
echo " [v1.27.0.0] migration complete." >&2
exit 0

54
health/SKILL.md
View File

@ -332,11 +332,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -369,13 +375,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -395,22 +414,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -421,11 +445,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:
@ -847,9 +871,9 @@ doctor_component: 10 if `gbrain doctor --json | jq -r .status` == "ok";
7 if "warnings"; 0 otherwise (or command times out after 5s).
queue_component: 10 if ~/.gstack/.brain-queue.jsonl has <10 lines;
7 if 10-100; 0 if >=100 (suggests secret-scan rejections
piling up). N/A if gbrain_sync_mode == off.
piling up). N/A if artifacts_sync_mode == off.
push_component: 10 if (now - mtime of ~/.gstack/.brain-last-push) < 24h;
7 if <72h; 0 if >=72h. N/A if gbrain_sync_mode == off.
7 if <72h; 0 if >=72h. N/A if artifacts_sync_mode == off.
gbrain_score = 0.5 * doctor_component + 0.3 * queue_component + 0.2 * push_component
(redistribute 0.3 + 0.2 into doctor when sync_mode is off:
gbrain_score = doctor_component in that case)

4
health/SKILL.md.tmpl
View File

@ -169,9 +169,9 @@ doctor_component: 10 if `gbrain doctor --json | jq -r .status` == "ok";
7 if "warnings"; 0 otherwise (or command times out after 5s).
queue_component: 10 if ~/.gstack/.brain-queue.jsonl has <10 lines;
7 if 10-100; 0 if >=100 (suggests secret-scan rejections
piling up). N/A if gbrain_sync_mode == off.
piling up). N/A if artifacts_sync_mode == off.
push_component: 10 if (now - mtime of ~/.gstack/.brain-last-push) < 24h;
7 if <72h; 0 if >=72h. N/A if gbrain_sync_mode == off.
7 if <72h; 0 if >=72h. N/A if artifacts_sync_mode == off.
gbrain_score = 0.5 * doctor_component + 0.3 * queue_component + 0.2 * push_component
(redistribute 0.3 + 0.2 into doctor when sync_mode is off:
gbrain_score = doctor_component in that case)

50
investigate/SKILL.md
View File

@ -371,11 +371,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -408,13 +414,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -434,22 +453,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -460,11 +484,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
land-and-deploy/SKILL.md
View File

@ -329,11 +329,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -366,13 +372,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -392,22 +411,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -418,11 +442,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
landing-report/SKILL.md
View File

@ -330,11 +330,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -367,13 +373,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -393,22 +412,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -419,11 +443,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
learn/SKILL.md
View File

@ -332,11 +332,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -369,13 +375,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -395,22 +414,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -421,11 +445,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
make-pdf/SKILL.md
View File

@ -271,11 +271,17 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
- Focus on completing the task and reporting results via prose output.
- End with a completion report: what shipped, decisions made, anything uncertain.
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -308,13 +314,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -334,22 +353,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -360,11 +384,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
office-hours/SKILL.md
View File

@ -367,11 +367,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -404,13 +410,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -430,22 +449,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -456,11 +480,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
open-gstack-browser/SKILL.md
View File

@ -329,11 +329,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -366,13 +372,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -392,22 +411,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -418,11 +442,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

2
package.json
View File

@ -1,6 +1,6 @@
{
"name": "gstack",
"version": "1.26.4.0",
"version": "1.27.0.0",
"description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
"license": "MIT",
"type": "module",

50
pair-agent/SKILL.md
View File

@ -330,11 +330,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -367,13 +373,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -393,22 +412,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -419,11 +443,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
plan-ceo-review/SKILL.md
View File

@ -361,11 +361,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -398,13 +404,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -424,22 +443,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -450,11 +474,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
plan-design-review/SKILL.md
View File

@ -334,11 +334,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -371,13 +377,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -397,22 +416,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -423,11 +447,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
plan-devex-review/SKILL.md
View File

@ -338,11 +338,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -375,13 +381,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -401,22 +420,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -427,11 +451,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
plan-eng-review/SKILL.md
View File

@ -336,11 +336,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -373,13 +379,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -399,22 +418,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -425,11 +449,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
plan-tune/SKILL.md
View File

@ -343,11 +343,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -380,13 +386,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -406,22 +425,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -432,11 +456,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
qa-only/SKILL.md
View File

@ -331,11 +331,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -368,13 +374,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -394,22 +413,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -420,11 +444,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
qa/SKILL.md
View File

@ -337,11 +337,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -374,13 +380,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -400,22 +419,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -426,11 +450,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
retro/SKILL.md
View File

@ -349,11 +349,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -386,13 +392,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -412,22 +431,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -438,11 +462,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
review/SKILL.md
View File

@ -334,11 +334,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -371,13 +377,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -397,22 +416,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -423,11 +447,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
scrape/SKILL.md
View File

@ -330,11 +330,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -367,13 +373,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -393,22 +412,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -419,11 +443,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

69
scripts/resolvers/preamble/generate-brain-sync-block.ts
View File

@ -1,19 +1,24 @@
/**
* gbrain-sync preamble block.
* artifacts-sync preamble block (renamed from gbrain-sync in v1.27.0.0).
*
* Emits bash that runs at every skill invocation:
* 0. Live gbrain-availability hint (per /plan-eng-review): when gbrain is
* configured, emit one of two variants (steady-state vs empty-corpus
* emergency). Zero context cost when gbrain is not configured.
* 1. If ~/.gstack-brain-remote.txt exists AND ~/.gstack/.git is missing,
* surface a restore-available hint (does NOT auto-run restore).
* 2. If sync is on, run `gstack-brain-sync --once` (drain + push).
* 1. If ~/.gstack-artifacts-remote.txt (or legacy ~/.gstack-brain-remote.txt
* during the v1.27.0.0 migration window) exists AND ~/.gstack/.git is
* missing, surface a restore-available hint (does NOT auto-run restore).
* 2. If sync is on, run `gstack-brain-sync --once` (drain + push). The
* script keeps its old name; only the config-key + state-file names flip.
* 3. On first skill of the day (24h cache via .brain-last-pull):
* `git fetch` + ff-only merge (JSONL merge driver handles conflicts).
* 4. Emit a `BRAIN_SYNC:` status line so every skill surfaces health.
* 4. Emit an `ARTIFACTS_SYNC:` status line so every skill surfaces health.
* In remote-MCP mode, the line reads `ARTIFACTS_SYNC: remote-mode
* (managed by brain server <host>)` since this machine doesn't sync
* anything locally — the brain admin's server pulls from GitHub/GitLab.
*
* Also emits prose instructions for the host LLM to fire a one-time privacy
* stop-gate via AskUserQuestion when gbrain_sync_mode is unset and gbrain
* stop-gate via AskUserQuestion when artifacts_sync_mode is unset and gbrain
* is available on the host.
*
* Block emitted across all tiers. Internal bash short-circuits when feature
@ -26,11 +31,17 @@ import type { TemplateContext } from '../types';
export function generateBrainSyncBlock(ctx: TemplateContext): string {
const isBrainHost = ctx.host === 'gbrain' || ctx.host === 'hermes';
return `## GBrain Sync (skill start)
return `## Artifacts Sync (skill start)
\`\`\`bash
_GSTACK_HOME="\${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="${ctx.paths.binDir}/gstack-brain-sync"
_BRAIN_CONFIG_BIN="${ctx.paths.binDir}/gstack-config"
@ -63,13 +74,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -89,22 +113,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server \${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
\`\`\`
${isBrainHost ? `If output shows \`BRAIN_SYNC: brain repo detected\`, offer \`gstack-brain-restore\` via AskUserQuestion; otherwise continue.` : ''}
${isBrainHost ? `If output shows \`ARTIFACTS_SYNC: artifacts repo detected\`, offer \`gstack-brain-restore\` via AskUserQuestion; otherwise continue.` : ''}
Privacy stop-gate: if output shows \`BRAIN_SYNC: off\`, \`gbrain_sync_mode_prompted\` is \`false\`, and gbrain is on PATH or \`gbrain doctor --fast --json\` works, ask once:
Privacy stop-gate: if output shows \`ARTIFACTS_SYNC: off\`, \`artifacts_sync_mode_prompted\` is \`false\`, and gbrain is on PATH or \`gbrain doctor --fast --json\` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -115,11 +144,11 @@ After answer:
\`\`\`bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
\`\`\`
If A/B and \`~/.gstack/.git\` is missing, ask whether to run \`gstack-brain-init\`. Do not block the skill.
If A/B and \`~/.gstack/.git\` is missing, ask whether to run \`gstack-artifacts-init\`. Do not block the skill.
At skill END before telemetry:

50
setup-browser-cookies/SKILL.md
View File

@ -268,11 +268,17 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions:
- Focus on completing the task and reporting results via prose output.
- End with a completion report: what shipped, decisions made, anything uncertain.
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -305,13 +311,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -331,22 +350,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -357,11 +381,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
setup-deploy/SKILL.md
View File

@ -333,11 +333,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -370,13 +376,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -396,22 +415,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -422,11 +446,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

315
setup-gbrain/SKILL.md
View File

@ -334,11 +334,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -371,13 +377,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -397,22 +416,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -423,11 +447,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:
@ -758,7 +782,12 @@ invocation flags here and skip to the matching step.
## Step 2: Pick a path (AskUserQuestion)
Only fire this if Step 1 shows no existing working config AND no shortcut
flag was passed. The question title: "Where should your brain live?"
flag was passed. **Special case:** if `gbrain_mcp_mode=remote-http` in the
detect output, an HTTP MCP is already registered — skip directly to Step 5a
verification (re-test the registration) and Step 6 onward, treating this run
as idempotent. Don't ask Step 2 again.
The question title: "Where should your brain live?"
Options (present based on detected state):
@ -775,6 +804,11 @@ Options (present based on detected state):
yourself; paste the URL back when ready.
- **3 — PGLite local.** Zero accounts, ~30 seconds. Isolated brain on this
Mac only. Best for try-first.
- **4 — Remote gbrain MCP.** Someone else (or another machine of yours) is
already running `gbrain serve` with HTTP transport. You paste the MCP URL
+ a bearer token; this skill registers it as your MCP. No local brain DB,
no local install needed. Recommended when the brain is shared across
machines or run by a teammate.
- **Switch** (only if Step 1 detected an existing engine): "You already have
a `<engine>` brain. Migrate it to the other engine?" → runs
`gbrain migrate --to <other>` wrapped in `timeout 180s` (D9).
@ -785,7 +819,11 @@ Do NOT silently pick; fire the AskUserQuestion.
## Step 3: Install gbrain CLI (if missing)
Only if `gbrain_on_path=false`:
**SKIP entirely on Path 4 (Remote MCP).** Path 4 doesn't need a local gbrain
binary — all calls go through MCP to the remote server. Jump to Step 4 (the
Path 4 subsection).
For Paths 1, 2a, 2b, 3, switch — only if `gbrain_on_path=false`:
```bash
~/.claude/skills/gstack/bin/gstack-gbrain-install
@ -930,6 +968,64 @@ gbrain init --pglite --json
Done. No network, no secrets.
### Path 4 (Remote gbrain MCP — HTTP transport with bearer token)
For users whose brain runs on another machine (Tailscale, ngrok, internal
LAN, or a teammate's server). No local gbrain CLI install, no local DB.
This skill registers the remote MCP and stops; ingestion + indexing happens
on the brain host.
**4a. Collect MCP URL.** Prompt the user:
```
Paste your gbrain MCP URL (e.g. https://wintermute.tail554574.ts.net:3131/mcp):
```
Read with plain `read -r` (no secret hygiene needed — the URL alone isn't
a credential). Validate it starts with `https://` (require TLS for any
non-loopback host); refuse `http://` for non-localhost.
**4b. Collect bearer token via the secret-read helper (D10, never argv).**
```bash
. ~/.claude/skills/gstack/bin/gstack-gbrain-lib.sh
read_secret_to_env GBRAIN_MCP_TOKEN "Paste bearer token: " \
--echo-redacted 's/.\{6\}$/***REDACTED***/'
```
**4c. Verify via gstack-gbrain-mcp-verify.** Run the helper; capture the
classified JSON output:
```bash
verify_json=$(GBRAIN_MCP_TOKEN="$GBRAIN_MCP_TOKEN" \
~/.claude/skills/gstack/bin/gstack-gbrain-mcp-verify "$MCP_URL")
status=$(echo "$verify_json" | jq -r .status)
```
If `status != "success"`, the helper has already classified the failure
into NETWORK / AUTH / MALFORMED and emitted a one-line remediation hint.
Surface the hint above the raw error from `error_text` and **STOP** with
a clear "fix and re-run /setup-gbrain" message. Do NOT continue to Step 5a
on a failed verify — partial registration would leave the user with a
half-broken state.
Capture two values from the verify output for downstream steps:
- `SERVER_VERSION` (e.g., `0.27.1`) — written to the CLAUDE.md block in Step 8.
- `URL_FORM_SUPPORTED` (`true|false`) — passed to `gstack-artifacts-init` in
Step 7 to control which form of the brain-admin hookup command is printed.
**4d. Skip Steps 3, 4 (other paths), 5 (local doctor), 7.5 (transcript ingest).**
All four require a working local `gbrain` CLI that Path 4 does not install.
The skill jumps straight to Step 5a (HTTP+bearer registration) → Step 6
(per-remote policy) → Step 7 (artifacts repo) → Step 8 (CLAUDE.md) → Step 9
(remote smoke test) → Step 10 (verdict).
The bearer token (`GBRAIN_MCP_TOKEN`) stays in process env until Step 5a's
`claude mcp add --header` consumes it; then `unset GBRAIN_MCP_TOKEN`
immediately. Token security trade-off documented in
`setup-gbrain/memory.md`: brief argv exposure during `claude mcp add`,
resting state in `~/.claude.json` mode 0600.
### Switch (from detect's existing-engine state)
```bash
@ -948,6 +1044,13 @@ holding a lock on the source brain. Close other workspaces and re-run
## Step 5: Verify gbrain doctor
**SKIP entirely on Path 4 (Remote MCP).** The brain host runs its own
doctor; we don't have local DB access to introspect. Step 4c's verify
round-trip already proved the server is reachable, authed, and on a
compatible MCP version.
For Paths 1, 2a, 2b, 3, switch:
```bash
doctor=$(gbrain doctor --json)
status=$(echo "$doctor" | jq -r .status)
@ -963,7 +1066,33 @@ doctor output and STOP.
Only if `which claude` resolves. Ask: "Give Claude Code a typed tool surface
for gbrain? (recommended yes)"
If yes, register at **user scope** with an **absolute path** to the gbrain
The registration form depends on the path picked in Step 2:
### Path 4 (Remote MCP — HTTP transport with bearer)
Tear down any prior registration (could be local-stdio from an old setup,
or stale remote-http with a rotated token), then register with HTTP +
bearer at user scope:
```bash
claude mcp remove gbrain -s user 2>/dev/null || true
claude mcp remove gbrain 2>/dev/null || true
claude mcp add --scope user --transport http gbrain "$MCP_URL" \
--header "Authorization: Bearer $GBRAIN_MCP_TOKEN"
unset GBRAIN_MCP_TOKEN # zero from process env after registration
claude mcp list | grep gbrain # verify: should show "✓ Connected"
```
**Token-storage note:** `claude mcp add --header "Authorization: Bearer ..."`
puts the bearer on argv during process startup, briefly visible to `ps` for
~10ms. The token's resting state is `~/.claude.json` (mode 0600 — Claude
Code's own credential surface for every MCP server). This trade-off is
documented in `setup-gbrain/memory.md`. If a future Claude Code release adds
a stdin or env-var input form for headers, switch to that.
### Paths 1, 2a, 2b, 3 (Local stdio)
Register at **user scope** with an **absolute path** to the gbrain
binary. User scope makes the MCP available in every Claude Code session on
this machine, not just the current workspace. Absolute path avoids PATH
resolution issues when Claude Code spawns `gbrain serve` as a subprocess.
@ -971,19 +1100,17 @@ resolution issues when Claude Code spawns `gbrain serve` as a subprocess.
```bash
GBRAIN_BIN=$(command -v gbrain)
[ -z "$GBRAIN_BIN" ] && GBRAIN_BIN="$HOME/.bun/bin/gbrain"
claude mcp remove gbrain -s user 2>/dev/null || true
claude mcp remove gbrain 2>/dev/null || true
claude mcp add --scope user gbrain -- "$GBRAIN_BIN" serve
claude mcp list | grep gbrain # verify: should show "✓ Connected"
```
If the user already had a local-scope registration from an earlier run,
remove it first so both scopes don't conflict:
```bash
claude mcp remove gbrain 2>/dev/null || true
```
### Both paths
If `claude` is not on PATH: emit "MCP registration skipped — this skill is
Claude-Code-targeted; register `gbrain serve` in your agent's MCP config
manually." Continue to step 6.
Claude-Code-targeted; register `gbrain serve` (or your remote MCP URL) in
your agent's MCP config manually." Continue to step 6.
**Heads-up for the user:** an already-open Claude Code session will not
pick up the new MCP tools until restart. Tell them: "Restart any open
@ -1025,30 +1152,53 @@ For `/setup-gbrain --repo` invocations, execute ONLY Step 6 and exit.
---
## Step 7: Offer gstack-brain-sync + wire it into gbrain
## Step 7: Offer artifacts sync + wire it into gbrain
Separate AskUserQuestion: "Also sync your gstack session memory (learnings,
plans, retros) to a private git repo that gbrain can index across machines?"
Renamed from "session memory sync" in v1.27.0.0 — the on-disk concept is
artifacts (CEO plans, designs, /investigate reports, retros) rather than
"session memory," which was a confusing name for what was always a
human-readable artifact bucket. Behavioral transcript ingest is its own
step (7.5) with its own option set.
Separate AskUserQuestion: "Also sync your gstack artifacts (CEO plans,
designs, reports, retros) to a private git repo that gbrain can index
across machines?"
Options:
- Yes, full sync (everything allowlisted)
- Yes, artifacts-only (plans, designs, retros — skip behavioral data)
- No thanks
If yes:
If yes, run the artifacts-init helper. It asks the user to pick a git host
(GitHub via `gh`, GitLab via `glab`, or paste a URL manually), creates
`gstack-artifacts-$USER` (private), and writes the canonical HTTPS URL to
`~/.gstack-artifacts-remote.txt`. Pass `--url-form-supported` from Step 4c's
verify output (Path 4) or `false` (Paths 1/2/3 — local mode doesn't probe):
```bash
~/.claude/skills/gstack/bin/gstack-brain-init
~/.claude/skills/gstack/bin/gstack-config set gbrain_sync_mode artifacts-only
URL_FORM=${URL_FORM_SUPPORTED:-false}
~/.claude/skills/gstack/bin/gstack-artifacts-init --url-form-supported "$URL_FORM"
~/.claude/skills/gstack/bin/gstack-config set artifacts_sync_mode artifacts-only
# or "full" if user picked yes-full
```
Then wire the brain repo into gbrain so its content is searchable from any
gbrain client (this Claude Code session, future Macs, optional cloud agents).
The helper creates a `git worktree` of `~/.gstack/`, registers it as a
federated source on the user's gbrain (Supabase or PGLite), and runs an
initial `gbrain sync`. Local-Mac only. No cloud agent required. Subsequent
skill runs trigger incremental sync via the existing skill-end push hook.
`gstack-artifacts-init` always prints a "Send this to your brain admin" block
at the end with the exact `gbrain sources add` command. Per codex Finding #3:
the skill never auto-executes server-side gbrain commands; even if the user
IS the brain admin, copy-pasting the printed command is the consistent UX.
### Path 4 (Remote MCP) — done after artifacts-init
In remote mode, the local `gstack-gbrain-source-wireup` helper does NOT run
(it shells out to a local `gbrain` CLI which Path 4 doesn't install). The
brain admin runs the printed command on the brain host instead. Skip to Step 7.5.
### Paths 1, 2a, 2b, 3 (Local stdio) — wire up the federated source
Then wire the artifacts repo into gbrain so its content is searchable from
any gbrain client. The helper creates a `git worktree` of `~/.gstack/`,
registers it as a federated source via `gbrain sources add --path
--federated`, and runs an initial `gbrain sync`. Local-Mac only.
Capture the database URL out of `~/.gbrain/config.json` first and pass it
explicitly so the wireup is robust against any other process rewriting
@ -1078,6 +1228,15 @@ the prereq is fixed.
## Step 7.5: Transcript & memory ingest gate
**SKIP entirely on Path 4 (Remote MCP).** Transcript ingest shells out to
the local `gbrain` CLI which Path 4 doesn't install. Remote-mode users
rely on the brain server's own ingest cadence — if your brain admin wants
this machine's transcripts indexed, they pull from your `gstack-artifacts-$USER`
repo (set up in Step 7) on whatever schedule they prefer. Set
`gstack-config set transcript_ingest_mode off` and continue to Step 8.
For Paths 1, 2a, 2b, 3:
After memory sync is wired (Step 7) but before persisting the CLAUDE.md
config (Step 8), offer to bring this Mac's coding-agent transcripts +
curated `~/.gstack/` artifacts into gbrain so the retrieval surface
@ -1147,15 +1306,37 @@ Step 8).
## Step 8: Persist `## GBrain Configuration` in CLAUDE.md
Find-and-replace (or append) this section in CLAUDE.md:
Find-and-replace (or append) the section. Block format depends on mode:
### Path 4 (Remote MCP)
```markdown
## GBrain Configuration (configured by /setup-gbrain)
- Mode: remote-http
- MCP URL: {MCP_URL}
- Server version: gbrain v{SERVER_VERSION} (from Step 4c verify)
- Setup date: {today}
- MCP registered: yes (user scope)
- Token: stored in ~/.claude.json (do not commit; never written to CLAUDE.md)
- Artifacts repo: {gstack_artifacts_remote URL or "none"}
- Artifacts sync: {off|artifacts-only|full}
- Current repo policy: {read-write|read-only|deny|unset}
```
The bearer token is **never** written to CLAUDE.md (CLAUDE.md is checked
in to git in many projects). It lives only in `~/.claude.json` where
`claude mcp add` placed it.
### Paths 1, 2a, 2b, 3 (Local stdio)
```markdown
## GBrain Configuration (configured by /setup-gbrain)
- Mode: local-stdio
- Engine: {pglite|postgres}
- Config file: ~/.gbrain/config.json (mode 0600)
- Setup date: {today}
- MCP registered: {yes/no}
- Memory sync: {off|artifacts-only|full}
- Artifacts sync: {off|artifacts-only|full}
- Current repo policy: {read-write|read-only|deny|unset}
```
@ -1207,6 +1388,34 @@ the round-trip works.
## Step 9: Smoke test
### Path 4 (Remote MCP)
The `mcp__gbrain__*` tools aren't visible mid-session — they're loaded at
Claude Code session start. So the live smoke test in this same skill run is
informational: print the curl-equivalent the user can run after restarting
Claude Code. The verify round-trip in Step 4c already proved the server is
reachable + authed + on a compatible MCP version, so we don't re-test that.
Print to stdout:
```
After restarting Claude Code, the `mcp__gbrain__*` tools become callable.
Smoke test: ask the agent to run `mcp__gbrain__search` with any query
("test page" works). You should see a JSON list of pages.
To verify from the shell right now (without waiting for restart):
curl -s -X POST -H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'Authorization: Bearer <YOUR_TOKEN>' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
<YOUR_MCP_URL>
```
Do NOT print the actual token in the curl command — leave the placeholder
`<YOUR_TOKEN>` so the snippet is safe to copy into chat / share.
### Paths 1, 2a, 2b, 3 (Local stdio)
```bash
SLUG="setup-gbrain-smoke-test-$(date +%s)"
echo "Set up on $(date). Smoke test for /setup-gbrain." | gbrain put "$SLUG"
@ -1227,15 +1436,37 @@ state, repairs only what's missing, and reports here.
```bash
~/.claude/skills/gstack/bin/gstack-gbrain-detect 2>/dev/null || true
~/.claude/skills/gstack/bin/gstack-config get transcript_ingest_mode 2>/dev/null || echo "off"
~/.claude/skills/gstack/bin/gstack-config get gbrain_sync_mode 2>/dev/null || echo "off"
~/.claude/skills/gstack/bin/gstack-config get artifacts_sync_mode 2>/dev/null || echo "off"
[ -f ~/.gstack/.gbrain-sync-state.json ] && cat ~/.gstack/.gbrain-sync-state.json || echo "{}"
```
Print the verdict block. Each row is `[OK]/[FIX]/[WARN]/[ERR]` — see
template below; substitute your detect outputs:
Read `gbrain_mcp_mode` from the detect output and pick the right verdict
template. Each row is `[OK]/[FIX]/[WARN]/[ERR]`.
### Path 4 (Remote MCP)
```
gbrain status: GREEN
gbrain status: GREEN (mode: remote-http)
MCP ............. OK {SERVER_NAME} v{SERVER_VERSION} at {MCP_URL}
Auth ............ OK bearer accepted (verified via /tools/list)
Engine .......... N/A remote mode
Doctor .......... N/A remote mode (brain admin runs `gbrain doctor`)
Repo policy ..... OK {read-write|read-only|deny}
Artifacts repo .. OK {gstack_artifacts_remote URL}
Artifacts sync .. OK {artifacts_sync_mode}
Transcripts ..... N/A remote mode (ingest happens on brain host)
CLAUDE.md ....... OK
Smoke test ...... INFO printed for post-restart manual verification
Restart Claude Code to pick up the `mcp__gbrain__*` tools.
Re-run `/setup-gbrain` any time the bearer rotates or the URL moves.
```
### Paths 1, 2a, 2b, 3 (Local stdio)
```
gbrain status: GREEN (mode: local-stdio)
CLI ............. OK <gbrain version>
Engine .......... OK <pglite|supabase> at <path>
@ -1243,7 +1474,7 @@ gbrain status: GREEN
MCP ............. OK registered (user scope)
Repo policy ..... OK <read-write|read-only|deny>
Code import ..... OK <last_imported_head>
Memory sync ..... OK <gbrain_sync_mode> to <remote>
Artifacts sync .. OK <artifacts_sync_mode> to <remote>
Transcripts ..... OK <N> sessions, last ingest <when>
CLAUDE.md ....... OK
Smoke test ...... OK put → search → delete round-trip

265
setup-gbrain/SKILL.md.tmpl
View File

@ -80,7 +80,12 @@ invocation flags here and skip to the matching step.
## Step 2: Pick a path (AskUserQuestion)
Only fire this if Step 1 shows no existing working config AND no shortcut
flag was passed. The question title: "Where should your brain live?"
flag was passed. **Special case:** if `gbrain_mcp_mode=remote-http` in the
detect output, an HTTP MCP is already registered — skip directly to Step 5a
verification (re-test the registration) and Step 6 onward, treating this run
as idempotent. Don't ask Step 2 again.
The question title: "Where should your brain live?"
Options (present based on detected state):
@ -97,6 +102,11 @@ Options (present based on detected state):
yourself; paste the URL back when ready.
- **3 — PGLite local.** Zero accounts, ~30 seconds. Isolated brain on this
Mac only. Best for try-first.
- **4 — Remote gbrain MCP.** Someone else (or another machine of yours) is
already running `gbrain serve` with HTTP transport. You paste the MCP URL
+ a bearer token; this skill registers it as your MCP. No local brain DB,
no local install needed. Recommended when the brain is shared across
machines or run by a teammate.
- **Switch** (only if Step 1 detected an existing engine): "You already have
a `<engine>` brain. Migrate it to the other engine?" → runs
`gbrain migrate --to <other>` wrapped in `timeout 180s` (D9).
@ -107,7 +117,11 @@ Do NOT silently pick; fire the AskUserQuestion.
## Step 3: Install gbrain CLI (if missing)
Only if `gbrain_on_path=false`:
**SKIP entirely on Path 4 (Remote MCP).** Path 4 doesn't need a local gbrain
binary — all calls go through MCP to the remote server. Jump to Step 4 (the
Path 4 subsection).
For Paths 1, 2a, 2b, 3, switch — only if `gbrain_on_path=false`:
```bash
~/.claude/skills/gstack/bin/gstack-gbrain-install
@ -252,6 +266,64 @@ gbrain init --pglite --json
Done. No network, no secrets.
### Path 4 (Remote gbrain MCP — HTTP transport with bearer token)
For users whose brain runs on another machine (Tailscale, ngrok, internal
LAN, or a teammate's server). No local gbrain CLI install, no local DB.
This skill registers the remote MCP and stops; ingestion + indexing happens
on the brain host.
**4a. Collect MCP URL.** Prompt the user:
```
Paste your gbrain MCP URL (e.g. https://wintermute.tail554574.ts.net:3131/mcp):
```
Read with plain `read -r` (no secret hygiene needed — the URL alone isn't
a credential). Validate it starts with `https://` (require TLS for any
non-loopback host); refuse `http://` for non-localhost.
**4b. Collect bearer token via the secret-read helper (D10, never argv).**
```bash
. ~/.claude/skills/gstack/bin/gstack-gbrain-lib.sh
read_secret_to_env GBRAIN_MCP_TOKEN "Paste bearer token: " \
--echo-redacted 's/.\{6\}$/***REDACTED***/'
```
**4c. Verify via gstack-gbrain-mcp-verify.** Run the helper; capture the
classified JSON output:
```bash
verify_json=$(GBRAIN_MCP_TOKEN="$GBRAIN_MCP_TOKEN" \
~/.claude/skills/gstack/bin/gstack-gbrain-mcp-verify "$MCP_URL")
status=$(echo "$verify_json" | jq -r .status)
```
If `status != "success"`, the helper has already classified the failure
into NETWORK / AUTH / MALFORMED and emitted a one-line remediation hint.
Surface the hint above the raw error from `error_text` and **STOP** with
a clear "fix and re-run /setup-gbrain" message. Do NOT continue to Step 5a
on a failed verify — partial registration would leave the user with a
half-broken state.
Capture two values from the verify output for downstream steps:
- `SERVER_VERSION` (e.g., `0.27.1`) — written to the CLAUDE.md block in Step 8.
- `URL_FORM_SUPPORTED` (`true|false`) — passed to `gstack-artifacts-init` in
Step 7 to control which form of the brain-admin hookup command is printed.
**4d. Skip Steps 3, 4 (other paths), 5 (local doctor), 7.5 (transcript ingest).**
All four require a working local `gbrain` CLI that Path 4 does not install.
The skill jumps straight to Step 5a (HTTP+bearer registration) → Step 6
(per-remote policy) → Step 7 (artifacts repo) → Step 8 (CLAUDE.md) → Step 9
(remote smoke test) → Step 10 (verdict).
The bearer token (`GBRAIN_MCP_TOKEN`) stays in process env until Step 5a's
`claude mcp add --header` consumes it; then `unset GBRAIN_MCP_TOKEN`
immediately. Token security trade-off documented in
`setup-gbrain/memory.md`: brief argv exposure during `claude mcp add`,
resting state in `~/.claude.json` mode 0600.
### Switch (from detect's existing-engine state)
```bash
@ -270,6 +342,13 @@ holding a lock on the source brain. Close other workspaces and re-run
## Step 5: Verify gbrain doctor
**SKIP entirely on Path 4 (Remote MCP).** The brain host runs its own
doctor; we don't have local DB access to introspect. Step 4c's verify
round-trip already proved the server is reachable, authed, and on a
compatible MCP version.
For Paths 1, 2a, 2b, 3, switch:
```bash
doctor=$(gbrain doctor --json)
status=$(echo "$doctor" | jq -r .status)
@ -285,7 +364,33 @@ doctor output and STOP.
Only if `which claude` resolves. Ask: "Give Claude Code a typed tool surface
for gbrain? (recommended yes)"
If yes, register at **user scope** with an **absolute path** to the gbrain
The registration form depends on the path picked in Step 2:
### Path 4 (Remote MCP — HTTP transport with bearer)
Tear down any prior registration (could be local-stdio from an old setup,
or stale remote-http with a rotated token), then register with HTTP +
bearer at user scope:
```bash
claude mcp remove gbrain -s user 2>/dev/null || true
claude mcp remove gbrain 2>/dev/null || true
claude mcp add --scope user --transport http gbrain "$MCP_URL" \
--header "Authorization: Bearer $GBRAIN_MCP_TOKEN"
unset GBRAIN_MCP_TOKEN # zero from process env after registration
claude mcp list | grep gbrain # verify: should show "✓ Connected"
```
**Token-storage note:** `claude mcp add --header "Authorization: Bearer ..."`
puts the bearer on argv during process startup, briefly visible to `ps` for
~10ms. The token's resting state is `~/.claude.json` (mode 0600 — Claude
Code's own credential surface for every MCP server). This trade-off is
documented in `setup-gbrain/memory.md`. If a future Claude Code release adds
a stdin or env-var input form for headers, switch to that.
### Paths 1, 2a, 2b, 3 (Local stdio)
Register at **user scope** with an **absolute path** to the gbrain
binary. User scope makes the MCP available in every Claude Code session on
this machine, not just the current workspace. Absolute path avoids PATH
resolution issues when Claude Code spawns `gbrain serve` as a subprocess.
@ -293,19 +398,17 @@ resolution issues when Claude Code spawns `gbrain serve` as a subprocess.
```bash
GBRAIN_BIN=$(command -v gbrain)
[ -z "$GBRAIN_BIN" ] && GBRAIN_BIN="$HOME/.bun/bin/gbrain"
claude mcp remove gbrain -s user 2>/dev/null || true
claude mcp remove gbrain 2>/dev/null || true
claude mcp add --scope user gbrain -- "$GBRAIN_BIN" serve
claude mcp list | grep gbrain # verify: should show "✓ Connected"
```
If the user already had a local-scope registration from an earlier run,
remove it first so both scopes don't conflict:
```bash
claude mcp remove gbrain 2>/dev/null || true
```
### Both paths
If `claude` is not on PATH: emit "MCP registration skipped — this skill is
Claude-Code-targeted; register `gbrain serve` in your agent's MCP config
manually." Continue to step 6.
Claude-Code-targeted; register `gbrain serve` (or your remote MCP URL) in
your agent's MCP config manually." Continue to step 6.
**Heads-up for the user:** an already-open Claude Code session will not
pick up the new MCP tools until restart. Tell them: "Restart any open
@ -347,30 +450,53 @@ For `/setup-gbrain --repo` invocations, execute ONLY Step 6 and exit.
---
## Step 7: Offer gstack-brain-sync + wire it into gbrain
## Step 7: Offer artifacts sync + wire it into gbrain
Separate AskUserQuestion: "Also sync your gstack session memory (learnings,
plans, retros) to a private git repo that gbrain can index across machines?"
Renamed from "session memory sync" in v1.27.0.0 — the on-disk concept is
artifacts (CEO plans, designs, /investigate reports, retros) rather than
"session memory," which was a confusing name for what was always a
human-readable artifact bucket. Behavioral transcript ingest is its own
step (7.5) with its own option set.
Separate AskUserQuestion: "Also sync your gstack artifacts (CEO plans,
designs, reports, retros) to a private git repo that gbrain can index
across machines?"
Options:
- Yes, full sync (everything allowlisted)
- Yes, artifacts-only (plans, designs, retros — skip behavioral data)
- No thanks
If yes:
If yes, run the artifacts-init helper. It asks the user to pick a git host
(GitHub via `gh`, GitLab via `glab`, or paste a URL manually), creates
`gstack-artifacts-$USER` (private), and writes the canonical HTTPS URL to
`~/.gstack-artifacts-remote.txt`. Pass `--url-form-supported` from Step 4c's
verify output (Path 4) or `false` (Paths 1/2/3 — local mode doesn't probe):
```bash
~/.claude/skills/gstack/bin/gstack-brain-init
~/.claude/skills/gstack/bin/gstack-config set gbrain_sync_mode artifacts-only
URL_FORM=${URL_FORM_SUPPORTED:-false}
~/.claude/skills/gstack/bin/gstack-artifacts-init --url-form-supported "$URL_FORM"
~/.claude/skills/gstack/bin/gstack-config set artifacts_sync_mode artifacts-only
# or "full" if user picked yes-full
```
Then wire the brain repo into gbrain so its content is searchable from any
gbrain client (this Claude Code session, future Macs, optional cloud agents).
The helper creates a `git worktree` of `~/.gstack/`, registers it as a
federated source on the user's gbrain (Supabase or PGLite), and runs an
initial `gbrain sync`. Local-Mac only. No cloud agent required. Subsequent
skill runs trigger incremental sync via the existing skill-end push hook.
`gstack-artifacts-init` always prints a "Send this to your brain admin" block
at the end with the exact `gbrain sources add` command. Per codex Finding #3:
the skill never auto-executes server-side gbrain commands; even if the user
IS the brain admin, copy-pasting the printed command is the consistent UX.
### Path 4 (Remote MCP) — done after artifacts-init
In remote mode, the local `gstack-gbrain-source-wireup` helper does NOT run
(it shells out to a local `gbrain` CLI which Path 4 doesn't install). The
brain admin runs the printed command on the brain host instead. Skip to Step 7.5.
### Paths 1, 2a, 2b, 3 (Local stdio) — wire up the federated source
Then wire the artifacts repo into gbrain so its content is searchable from
any gbrain client. The helper creates a `git worktree` of `~/.gstack/`,
registers it as a federated source via `gbrain sources add --path
--federated`, and runs an initial `gbrain sync`. Local-Mac only.
Capture the database URL out of `~/.gbrain/config.json` first and pass it
explicitly so the wireup is robust against any other process rewriting
@ -400,6 +526,15 @@ the prereq is fixed.
## Step 7.5: Transcript & memory ingest gate
**SKIP entirely on Path 4 (Remote MCP).** Transcript ingest shells out to
the local `gbrain` CLI which Path 4 doesn't install. Remote-mode users
rely on the brain server's own ingest cadence — if your brain admin wants
this machine's transcripts indexed, they pull from your `gstack-artifacts-$USER`
repo (set up in Step 7) on whatever schedule they prefer. Set
`gstack-config set transcript_ingest_mode off` and continue to Step 8.
For Paths 1, 2a, 2b, 3:
After memory sync is wired (Step 7) but before persisting the CLAUDE.md
config (Step 8), offer to bring this Mac's coding-agent transcripts +
curated `~/.gstack/` artifacts into gbrain so the retrieval surface
@ -469,15 +604,37 @@ Step 8).
## Step 8: Persist `## GBrain Configuration` in CLAUDE.md
Find-and-replace (or append) this section in CLAUDE.md:
Find-and-replace (or append) the section. Block format depends on mode:
### Path 4 (Remote MCP)
```markdown
## GBrain Configuration (configured by /setup-gbrain)
- Mode: remote-http
- MCP URL: {MCP_URL}
- Server version: gbrain v{SERVER_VERSION} (from Step 4c verify)
- Setup date: {today}
- MCP registered: yes (user scope)
- Token: stored in ~/.claude.json (do not commit; never written to CLAUDE.md)
- Artifacts repo: {gstack_artifacts_remote URL or "none"}
- Artifacts sync: {off|artifacts-only|full}
- Current repo policy: {read-write|read-only|deny|unset}
```
The bearer token is **never** written to CLAUDE.md (CLAUDE.md is checked
in to git in many projects). It lives only in `~/.claude.json` where
`claude mcp add` placed it.
### Paths 1, 2a, 2b, 3 (Local stdio)
```markdown
## GBrain Configuration (configured by /setup-gbrain)
- Mode: local-stdio
- Engine: {pglite|postgres}
- Config file: ~/.gbrain/config.json (mode 0600)
- Setup date: {today}
- MCP registered: {yes/no}
- Memory sync: {off|artifacts-only|full}
- Artifacts sync: {off|artifacts-only|full}
- Current repo policy: {read-write|read-only|deny|unset}
```
@ -529,6 +686,34 @@ the round-trip works.
## Step 9: Smoke test
### Path 4 (Remote MCP)
The `mcp__gbrain__*` tools aren't visible mid-session — they're loaded at
Claude Code session start. So the live smoke test in this same skill run is
informational: print the curl-equivalent the user can run after restarting
Claude Code. The verify round-trip in Step 4c already proved the server is
reachable + authed + on a compatible MCP version, so we don't re-test that.
Print to stdout:
```
After restarting Claude Code, the `mcp__gbrain__*` tools become callable.
Smoke test: ask the agent to run `mcp__gbrain__search` with any query
("test page" works). You should see a JSON list of pages.
To verify from the shell right now (without waiting for restart):
curl -s -X POST -H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'Authorization: Bearer <YOUR_TOKEN>' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
<YOUR_MCP_URL>
```
Do NOT print the actual token in the curl command — leave the placeholder
`<YOUR_TOKEN>` so the snippet is safe to copy into chat / share.
### Paths 1, 2a, 2b, 3 (Local stdio)
```bash
SLUG="setup-gbrain-smoke-test-$(date +%s)"
echo "Set up on $(date). Smoke test for /setup-gbrain." | gbrain put "$SLUG"
@ -549,15 +734,37 @@ state, repairs only what's missing, and reports here.
```bash
~/.claude/skills/gstack/bin/gstack-gbrain-detect 2>/dev/null || true
~/.claude/skills/gstack/bin/gstack-config get transcript_ingest_mode 2>/dev/null || echo "off"
~/.claude/skills/gstack/bin/gstack-config get gbrain_sync_mode 2>/dev/null || echo "off"
~/.claude/skills/gstack/bin/gstack-config get artifacts_sync_mode 2>/dev/null || echo "off"
[ -f ~/.gstack/.gbrain-sync-state.json ] && cat ~/.gstack/.gbrain-sync-state.json || echo "{}"
```
Print the verdict block. Each row is `[OK]/[FIX]/[WARN]/[ERR]` — see
template below; substitute your detect outputs:
Read `gbrain_mcp_mode` from the detect output and pick the right verdict
template. Each row is `[OK]/[FIX]/[WARN]/[ERR]`.
### Path 4 (Remote MCP)
```
gbrain status: GREEN
gbrain status: GREEN (mode: remote-http)
MCP ............. OK {SERVER_NAME} v{SERVER_VERSION} at {MCP_URL}
Auth ............ OK bearer accepted (verified via /tools/list)
Engine .......... N/A remote mode
Doctor .......... N/A remote mode (brain admin runs `gbrain doctor`)
Repo policy ..... OK {read-write|read-only|deny}
Artifacts repo .. OK {gstack_artifacts_remote URL}
Artifacts sync .. OK {artifacts_sync_mode}
Transcripts ..... N/A remote mode (ingest happens on brain host)
CLAUDE.md ....... OK
Smoke test ...... INFO printed for post-restart manual verification
Restart Claude Code to pick up the `mcp__gbrain__*` tools.
Re-run `/setup-gbrain` any time the bearer rotates or the URL moves.
```
### Paths 1, 2a, 2b, 3 (Local stdio)
```
gbrain status: GREEN (mode: local-stdio)
CLI ............. OK <gbrain version>
Engine .......... OK <pglite|supabase> at <path>
@ -565,7 +772,7 @@ gbrain status: GREEN
MCP ............. OK registered (user scope)
Repo policy ..... OK <read-write|read-only|deny>
Code import ..... OK <last_imported_head>
Memory sync ..... OK <gbrain_sync_mode> to <remote>
Artifacts sync .. OK <artifacts_sync_mode> to <remote>
Transcripts ..... OK <N> sessions, last ingest <when>
CLAUDE.md ....... OK
Smoke test ...... OK put → search → delete round-trip

98
setup-gbrain/memory.md
View File

@ -176,3 +176,101 @@ the recovery path is:
on the brain remote for hard-delete from history
4. File a gitleaks issue with the pattern (or extend the gitleaks config
at `~/.gitleaks.toml`).
## Path 4: Remote MCP setup (v1.27.0.0+)
If you don't run gbrain locally — you have a teammate or another machine
running `gbrain serve` over HTTP, accessible via Tailscale, ngrok, or
internal LAN — `/setup-gbrain` Path 4 is the one-paste flow.
You provide:
- The MCP URL (e.g., `https://wintermute.tail554574.ts.net:3131/mcp`)
- A bearer token (issued by the brain admin via `gbrain access-token issue`)
What `/setup-gbrain` does:
1. Verifies the URL + token via `gstack-gbrain-mcp-verify`. Three failure
modes get classified with one-line remediation hints:
**NETWORK** ("check Tailscale/DNS"), **AUTH** ("rotate token"),
**MALFORMED** ("Accept-header gotcha — pass both `application/json`
AND `text/event-stream`").
2. Registers the MCP at user scope:
```
claude mcp add --scope user --transport http gbrain "$URL" \
--header "Authorization: Bearer $TOKEN"
```
3. Skips local install, local doctor, transcript ingest, and federated
source registration. All four require a local `gbrain` CLI that Path 4
doesn't install.
4. Optionally provisions a `gstack-artifacts-$USER` private repo on
GitHub or GitLab and prints the one-line `gbrain sources add` command
for your brain admin to run on the brain host.
### Token storage trade-off
The bearer token lives in `~/.claude.json` (mode 0600), where Claude Code
stores every MCP server's credentials. During `claude mcp add --header
"Authorization: Bearer $TOKEN"`, the token is briefly visible in
process argv (~10ms) — visible to `ps` running concurrently. The window
is small but it's not zero.
Mitigations we've considered:
- **Stdin or env-var input form for headers** — would close the argv
window. As of Claude Code v1.0.x, the CLI doesn't expose either.
When it does, `/setup-gbrain` Path 4 will switch automatically.
- **Keychain storage** — explicitly out of scope (the token's resting
state in `~/.claude.json` is the existing trust surface for every MCP
credential; expanding to Keychain would touch every MCP server, not
just gbrain).
### Why Path 4 is "always print" for the brain-admin hookup
`gstack-artifacts-init` always prints the `gbrain sources add` command
labeled "Send this to your brain admin" — even when the user IS the
brain admin (consistent UX, no mode-detection fragility).
A previous design proposed probing whether the user's bearer has admin
scope (via a benign MCP write call like `add_tag`) and auto-executing
the source registration when scope was sufficient. The design review
flagged that page-write doesn't actually prove source-management
permission — those are different scopes in any sensible auth model.
Until gbrain ships:
- a `mcp__gbrain__whoami` capability tool that returns the bearer's
scope set, AND
- a `mcp__gbrain__sources_add` MCP tool with admin-scope gating
we always print the command rather than pretending we know who has
permission to run it.
### CLAUDE.md block in Path 4
Distinct from local-stdio mode. Token is **never** written to CLAUDE.md
(many projects check CLAUDE.md into git). The block records the URL,
the verified server version, the artifacts repo URL (if provisioned),
and the per-repo trust policy.
```markdown
## GBrain Configuration (configured by /setup-gbrain)
- Mode: remote-http
- MCP URL: https://wintermute.tail554574.ts.net:3131/mcp
- Server version: gbrain v0.27.1
- Setup date: 2026-05-06
- MCP registered: yes (user scope)
- Token: stored in ~/.claude.json (do not commit; never written to CLAUDE.md)
- Artifacts repo: github.com/garrytan/gstack-artifacts-garrytan (private)
- Artifacts sync: artifacts-only
- Current repo policy: read-write
```
### Token rotation
Server-side. When verify hits `AUTH` (e.g., the brain admin rotated the
token), the helper says: "rotate token on the brain host, re-run
/setup-gbrain." On wintermute or wherever your gbrain server lives:
```
gbrain access-token rotate # invalidates old, issues new
```
(See `gstack/setup-gbrain/SKILL.md.tmpl` for the full Path 4 flow plus
the gbrain enhancement requests around scoped tokens that would let
gstack auto-rotate in V2.)

50
ship/SKILL.md
View File

@ -335,11 +335,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -372,13 +378,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -398,22 +417,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -424,11 +448,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
skillify/SKILL.md
View File

@ -331,11 +331,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -368,13 +374,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -394,22 +413,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -420,11 +444,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

68
sync-gbrain/SKILL.md
View File

@ -334,11 +334,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -371,13 +377,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -397,22 +416,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -423,11 +447,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:
@ -744,6 +768,22 @@ Before doing anything, check that /setup-gbrain has been run on this Mac.
~/.claude/skills/gstack/bin/gstack-gbrain-detect 2>/dev/null
```
**Remote-MCP mode (Path 4 of /setup-gbrain):** if `gbrain_mcp_mode=remote-http`,
this skill is a graceful no-op. The brain server's own indexing cadence
handles code import + search refresh; this Mac doesn't run a local gbrain
CLI to drive `gbrain sources add` / `sync --strategy code`. Print:
> "Remote MCP detected (Path 4). /sync-gbrain is local-mode-only in V1.
> Your brain server (`<host>` from claude.json) handles indexing on its own
> cadence. If indexing seems stale, ping your brain admin or trigger a
> manual sync there. To wire `/sync-gbrain` through MCP tools (when gbrain
> ships `mcp__gbrain__sources_add` and friends), see the v1.27.0.0+
> follow-on TODO."
Then exit cleanly. Do NOT proceed to Step 2.
For local-stdio mode and unconfigured states:
If `gbrain_on_path=false` OR `gbrain_config_exists=false` OR CLAUDE.md does
not contain `## GBrain Configuration (configured by /setup-gbrain)`, STOP and
tell the user:
@ -904,7 +944,7 @@ gbrain status: GREEN
Capability ...... OK write+search round-trip
CWD source ...... OK <gstack-code-{repo_slug}> (page_count=<N>)
~/.gstack source. OK <gstack-brain-{user}> (page_count=<N>) — managed by /setup-gbrain
Memory sync ..... OK <gbrain_sync_mode>
Memory sync ..... OK <artifacts_sync_mode>
CLAUDE.md ....... OK ## GBrain Search Guidance present
Last sync ....... OK <last_sync from state file>

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

@ -66,6 +66,22 @@ Before doing anything, check that /setup-gbrain has been run on this Mac.
~/.claude/skills/gstack/bin/gstack-gbrain-detect 2>/dev/null
```
**Remote-MCP mode (Path 4 of /setup-gbrain):** if `gbrain_mcp_mode=remote-http`,
this skill is a graceful no-op. The brain server's own indexing cadence
handles code import + search refresh; this Mac doesn't run a local gbrain
CLI to drive `gbrain sources add` / `sync --strategy code`. Print:
> "Remote MCP detected (Path 4). /sync-gbrain is local-mode-only in V1.
> Your brain server (`<host>` from claude.json) handles indexing on its own
> cadence. If indexing seems stale, ping your brain admin or trigger a
> manual sync there. To wire `/sync-gbrain` through MCP tools (when gbrain
> ships `mcp__gbrain__sources_add` and friends), see the v1.27.0.0+
> follow-on TODO."
Then exit cleanly. Do NOT proceed to Step 2.
For local-stdio mode and unconfigured states:
If `gbrain_on_path=false` OR `gbrain_config_exists=false` OR CLAUDE.md does
not contain `## GBrain Configuration (configured by /setup-gbrain)`, STOP and
tell the user:
@ -226,7 +242,7 @@ gbrain status: GREEN
Capability ...... OK write+search round-trip
CWD source ...... OK <gstack-code-{repo_slug}> (page_count=<N>)
~/.gstack source. OK <gstack-brain-{user}> (page_count=<N>) — managed by /setup-gbrain
Memory sync ..... OK <gbrain_sync_mode>
Memory sync ..... OK <artifacts_sync_mode>
CLAUDE.md ....... OK ## GBrain Search Guidance present
Last sync ....... OK <last_sync from state file>

60
test/brain-sync.test.ts
View File

@ -6,7 +6,7 @@
* - bin/gstack-brain-enqueue (atomicity, skip list, no-op gates)
* - bin/gstack-jsonl-merge (3-way, ts-sort, hash-fallback)
* - bin/gstack-brain-sync --once (drain, commit, push, secret-scan, skip-file)
* - bin/gstack-brain-init + --restore round-trip
* - bin/gstack-artifacts-init + --restore round-trip
* - bin/gstack-brain-uninstall preserves user data
* - env isolation (GSTACK_HOME never bleeds into real ~/.gstack/config.yaml)
*
@ -69,30 +69,30 @@ afterEach(() => {
// Config key validation + env isolation
// ---------------------------------------------------------------
describe('gstack-config gbrain keys', () => {
test('default gbrain_sync_mode is off', () => {
const r = run(['gstack-config', 'get', 'gbrain_sync_mode']);
test('default artifacts_sync_mode is off', () => {
const r = run(['gstack-config', 'get', 'artifacts_sync_mode']);
expect(r.status).toBe(0);
expect(r.stdout.trim()).toBe('off');
});
test('default gbrain_sync_mode_prompted is false', () => {
const r = run(['gstack-config', 'get', 'gbrain_sync_mode_prompted']);
test('default artifacts_sync_mode_prompted is false', () => {
const r = run(['gstack-config', 'get', 'artifacts_sync_mode_prompted']);
expect(r.stdout.trim()).toBe('false');
});
test('accepts full / artifacts-only / off', () => {
for (const val of ['full', 'artifacts-only', 'off']) {
const set = run(['gstack-config', 'set', 'gbrain_sync_mode', val]);
const set = run(['gstack-config', 'set', 'artifacts_sync_mode', val]);
expect(set.status).toBe(0);
const get = run(['gstack-config', 'get', 'gbrain_sync_mode']);
const get = run(['gstack-config', 'get', 'artifacts_sync_mode']);
expect(get.stdout.trim()).toBe(val);
}
});
test('invalid gbrain_sync_mode value warns + defaults', () => {
const r = run(['gstack-config', 'set', 'gbrain_sync_mode', 'bogus']);
test('invalid artifacts_sync_mode value warns + defaults', () => {
const r = run(['gstack-config', 'set', 'artifacts_sync_mode', 'bogus']);
expect(r.stderr).toContain('not recognized');
const get = run(['gstack-config', 'get', 'gbrain_sync_mode']);
const get = run(['gstack-config', 'get', 'artifacts_sync_mode']);
expect(get.stdout.trim()).toBe('off');
});
@ -102,11 +102,11 @@ describe('gstack-config gbrain keys', () => {
const realConfig = path.join(os.homedir(), '.gstack', 'config.yaml');
const before = fs.existsSync(realConfig) ? fs.readFileSync(realConfig, 'utf-8') : null;
run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
// The override actually took effect — temp config got the new value.
const tempConfig = fs.readFileSync(path.join(tmpHome, 'config.yaml'), 'utf-8');
expect(tempConfig).toContain('gbrain_sync_mode: full');
expect(tempConfig).toContain('artifacts_sync_mode: full');
// Real ~/.gstack/config.yaml must not be touched.
const after = fs.existsSync(realConfig) ? fs.readFileSync(realConfig, 'utf-8') : null;
@ -133,7 +133,7 @@ describe('gstack-brain-enqueue', () => {
test('enqueues when mode is full and .git exists', () => {
fs.mkdirSync(path.join(tmpHome, '.git'), { recursive: true });
run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
run(['gstack-brain-enqueue', 'projects/foo/learnings.jsonl']);
const queue = fs.readFileSync(path.join(tmpHome, '.brain-queue.jsonl'), 'utf-8');
expect(queue).toContain('projects/foo/learnings.jsonl');
@ -144,7 +144,7 @@ describe('gstack-brain-enqueue', () => {
test('skip list honored', () => {
fs.mkdirSync(path.join(tmpHome, '.git'), { recursive: true });
run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
fs.writeFileSync(path.join(tmpHome, '.brain-skip.txt'), 'projects/foo/secret.jsonl\n');
run(['gstack-brain-enqueue', 'projects/foo/secret.jsonl']);
run(['gstack-brain-enqueue', 'projects/foo/ok.jsonl']);
@ -155,7 +155,7 @@ describe('gstack-brain-enqueue', () => {
test('concurrent enqueues all land (atomic append)', async () => {
fs.mkdirSync(path.join(tmpHome, '.git'), { recursive: true });
run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
const procs = [];
for (let i = 0; i < 10; i++) {
procs.push(new Promise<void>((resolve) => {
@ -218,7 +218,7 @@ describe('gstack-jsonl-merge', () => {
// ---------------------------------------------------------------
describe('init + sync + restore round-trip', () => {
test('init creates canonical files + registers drivers', () => {
const r = run(['gstack-brain-init', '--remote', bareRemote]);
const r = run(['gstack-artifacts-init', '--remote', bareRemote]);
expect(r.status).toBe(0);
expect(fs.existsSync(path.join(tmpHome, '.git'))).toBe(true);
expect(fs.existsSync(path.join(tmpHome, '.gitignore'))).toBe(true);
@ -232,18 +232,18 @@ describe('init + sync + restore round-trip', () => {
});
test('refuses init on different remote', () => {
run(['gstack-brain-init', '--remote', bareRemote]);
run(['gstack-artifacts-init', '--remote', bareRemote]);
const otherRemote = fs.mkdtempSync(path.join(os.tmpdir(), 'brain-other-'));
spawnSync('git', ['init', '--bare', '-q', '-b', 'main', otherRemote]);
const r = run(['gstack-brain-init', '--remote', otherRemote]);
const r = run(['gstack-artifacts-init', '--remote', otherRemote]);
expect(r.status).not.toBe(0);
expect(r.stderr).toContain('already a git repo pointing at');
fs.rmSync(otherRemote, { recursive: true, force: true });
});
test('full sync: init → enqueue → --once → commit pushed', () => {
run(['gstack-brain-init', '--remote', bareRemote]);
run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
run(['gstack-artifacts-init', '--remote', bareRemote]);
run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
fs.mkdirSync(path.join(tmpHome, 'projects', 'p'), { recursive: true });
fs.writeFileSync(path.join(tmpHome, 'projects/p/learnings.jsonl'),
'{"skill":"x","insight":"y","ts":"2026-04-22T10:00:00Z"}\n');
@ -257,8 +257,8 @@ describe('init + sync + restore round-trip', () => {
test('restore round-trip: writes on machine A visible on machine B', () => {
// Machine A.
run(['gstack-brain-init', '--remote', bareRemote]);
run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
run(['gstack-artifacts-init', '--remote', bareRemote]);
run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
fs.mkdirSync(path.join(tmpHome, 'projects', 'myproj'), { recursive: true });
const aLearning = '{"skill":"x","insight":"machine A wisdom","ts":"2026-04-22T10:00:00Z"}\n';
fs.writeFileSync(path.join(tmpHome, 'projects/myproj/learnings.jsonl'), aLearning);
@ -296,8 +296,8 @@ describe('gstack-brain-sync secret scan', () => {
for (const [name, content] of SECRETS) {
test(`blocks ${name}`, () => {
run(['gstack-brain-init', '--remote', bareRemote]);
run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
run(['gstack-artifacts-init', '--remote', bareRemote]);
run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
fs.mkdirSync(path.join(tmpHome, 'projects', 'p'), { recursive: true });
fs.writeFileSync(path.join(tmpHome, 'projects/p/learnings.jsonl'),
`{"leaked":"${content}"}\n`);
@ -314,8 +314,8 @@ describe('gstack-brain-sync secret scan', () => {
}
test('--skip-file unblocks specific file', () => {
run(['gstack-brain-init', '--remote', bareRemote]);
run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
run(['gstack-artifacts-init', '--remote', bareRemote]);
run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
fs.mkdirSync(path.join(tmpHome, 'projects', 'p'), { recursive: true });
const leakPath = 'projects/p/leaked.jsonl';
fs.writeFileSync(path.join(tmpHome, leakPath),
@ -335,7 +335,7 @@ describe('gstack-brain-sync secret scan', () => {
// ---------------------------------------------------------------
describe('gstack-brain-uninstall', () => {
test('removes sync config but preserves learnings/project data', () => {
run(['gstack-brain-init', '--remote', bareRemote]);
run(['gstack-artifacts-init', '--remote', bareRemote]);
fs.mkdirSync(path.join(tmpHome, 'projects', 'user-data'), { recursive: true });
const preservedContent = '{"keep":"me","ts":"2026-04-22T12:00:00Z"}\n';
fs.writeFileSync(path.join(tmpHome, 'projects/user-data/learnings.jsonl'), preservedContent);
@ -349,7 +349,7 @@ describe('gstack-brain-uninstall', () => {
const preserved = fs.readFileSync(path.join(tmpHome, 'projects/user-data/learnings.jsonl'), 'utf-8');
expect(preserved).toBe(preservedContent);
// Config key reset.
const mode = run(['gstack-config', 'get', 'gbrain_sync_mode']);
const mode = run(['gstack-config', 'get', 'artifacts_sync_mode']);
expect(mode.stdout.trim()).toBe('off');
});
});
@ -359,8 +359,8 @@ describe('gstack-brain-uninstall', () => {
// ---------------------------------------------------------------
describe('gstack-brain-sync --discover-new', () => {
test('enqueues new allowlisted files; idempotent on re-run', () => {
run(['gstack-brain-init', '--remote', bareRemote]);
run(['gstack-config', 'set', 'gbrain_sync_mode', 'full']);
run(['gstack-artifacts-init', '--remote', bareRemote]);
run(['gstack-config', 'set', 'artifacts_sync_mode', 'full']);
fs.mkdirSync(path.join(tmpHome, 'retros'), { recursive: true });
fs.writeFileSync(path.join(tmpHome, 'retros/week-1.md'), '# retro\n');
run(['gstack-brain-sync', '--discover-new']);

50
test/fixtures/golden/claude-ship-SKILL.md vendored
View File

@ -335,11 +335,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
@ -372,13 +378,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -398,22 +417,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -424,11 +448,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
test/fixtures/golden/codex-ship-SKILL.md vendored
View File

@ -324,11 +324,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="$GSTACK_BIN/gstack-brain-sync"
_BRAIN_CONFIG_BIN="$GSTACK_BIN/gstack-config"
@ -361,13 +367,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -387,22 +406,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -413,11 +437,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

50
test/fixtures/golden/factory-ship-SKILL.md vendored
View File

@ -326,11 +326,17 @@ Before calling AskUserQuestion, verify:
- [ ] You are calling the tool, not writing prose
## GBrain Sync (skill start)
## Artifacts Sync (skill start)
```bash
_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users
# upgrading mid-stream before the migration script runs.
if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
_BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt"
else
_BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
fi
_BRAIN_SYNC_BIN="$GSTACK_BIN/gstack-brain-sync"
_BRAIN_CONFIG_BIN="$GSTACK_BIN/gstack-config"
@ -363,13 +369,26 @@ if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then
fi
fi
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get gbrain_sync_mode 2>/dev/null || echo off)
_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off)
# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is
# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its
# own cadence. Read claude.json directly to keep this preamble fast (no
# subprocess to claude CLI on every skill start).
_GBRAIN_MCP_MODE="none"
if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then
_GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null)
case "$_GBRAIN_MCP_TYPE" in
url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;;
stdio) _GBRAIN_MCP_MODE="local-stdio" ;;
esac
fi
if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then
_BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
if [ -n "$_BRAIN_NEW_URL" ]; then
echo "BRAIN_SYNC: brain repo detected: $_BRAIN_NEW_URL"
echo "BRAIN_SYNC: run 'gstack-brain-restore' to pull your cross-machine memory (or 'gstack-config set gbrain_sync_mode off' to dismiss forever)"
echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL"
echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)"
fi
fi
@ -389,22 +408,27 @@ if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
"$_BRAIN_SYNC_BIN" --once 2>/dev/null || true
fi
if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then
# Remote-MCP mode: local artifacts sync is a no-op (brain admin's server
# pulls from GitHub/GitLab). Show the user this is by design, not broken.
_GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|')
echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})"
elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then
_BRAIN_QUEUE_DEPTH=0
[ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ')
_BRAIN_LAST_PUSH="never"
[ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never)
echo "BRAIN_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH"
else
echo "BRAIN_SYNC: off"
echo "ARTIFACTS_SYNC: off"
fi
```
Privacy stop-gate: if output shows `BRAIN_SYNC: off`, `gbrain_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once:
> gstack can publish your session memory to a private GitHub repo that GBrain indexes across machines. How much should sync?
> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync?
Options:
- A) Everything allowlisted (recommended)
@ -415,11 +439,11 @@ After answer:
```bash
# Chosen mode: full | artifacts-only | off
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set gbrain_sync_mode_prompted true
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode <choice>
"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true
```
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-brain-init`. Do not block the skill.
If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill.
At skill END before telemetry:

8
test/gen-skill-docs.test.ts
View File

@ -313,15 +313,17 @@ describe('gen-skill-docs', () => {
];
// Plan skills carry the same preamble surface as other tier-≥2 skills
// (Brain Sync, Context Recovery, Routing Injection are load-bearing
// (Artifacts Sync, Context Recovery, Routing Injection are load-bearing
// functionality, not optional). Budget is set to current size + small
// headroom; ratchet down if a future slim trims real bytes.
// Ratcheted from 33000 → 35000 when the gbrain context-load block was
// added to generate-brain-sync-block.ts (per /sync-gbrain plan §4).
// added (per /sync-gbrain plan §4). Ratcheted 35000 → 36500 in v1.27.0.0
// when generate-brain-sync-block.ts gained the gbrain_mcp_mode probe +
// remote-mode ARTIFACTS_SYNC status line (Path 4 of /setup-gbrain).
for (const skill of reviewSkills) {
const content = fs.readFileSync(skill.path, 'utf-8');
const preamble = extractPreambleBeforeWorkflow(content, skill.markers);
expect(Buffer.byteLength(preamble, 'utf-8')).toBeLessThan(35_000);
expect(Buffer.byteLength(preamble, 'utf-8')).toBeLessThan(36_500);
}
});

320
test/gstack-artifacts-init.test.ts Normal file
View File

@ -0,0 +1,320 @@
/**
* gstack-artifacts-init — provider-selection + brain-admin-hookup tests.
*
* Mirrors the gstack-brain-init-gh-mock.test.ts pattern: install fake gh /
* glab / git binaries on PATH, drive the script's three host-pref branches,
* assert it (a) creates the right repo name, (b) stores HTTPS canonical in
* ~/.gstack-artifacts-remote.txt, (c) prints the "Send this to your brain
* admin" block in the right form depending on --url-form-supported.
*
* Per codex Finding #3: the script always prints the hookup command, never
* auto-executes (no MCP probe). Per Finding #10: stored URL is HTTPS.
*/
import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import { spawnSync } from 'child_process';
const ROOT = path.resolve(import.meta.dir, '..');
const INIT_BIN = path.join(ROOT, 'bin', 'gstack-artifacts-init');
let tmpHome: string;
let bareRemote: string;
let fakeBinDir: string;
let ghCallLog: string;
let glabCallLog: string;
function makeFakeGh(opts: { authStatus?: 'ok' | 'fail'; repoCreate?: 'success' | 'already-exists' | 'fail'; webUrl?: string } = {}) {
const authStatus = opts.authStatus ?? 'ok';
const repoCreate = opts.repoCreate ?? 'success';
const webUrl = opts.webUrl ?? `https://github.com/testuser/gstack-artifacts-testuser`;
const script = `#!/bin/bash
echo "gh $@" >> "${ghCallLog}"
case "$1" in
auth) ${authStatus === 'ok' ? 'exit 0' : 'exit 1'} ;;
repo)
shift
case "$1" in
create)
${
repoCreate === 'success'
? 'exit 0'
: repoCreate === 'already-exists'
? 'echo "GraphQL: Name already exists on this account" >&2; exit 1'
: 'echo "network error" >&2; exit 1'
}
;;
view)
# gh repo view <name> --json url -q .url
echo "${webUrl}"
exit 0
;;
esac
;;
esac
exit 0
`;
fs.writeFileSync(path.join(fakeBinDir, 'gh'), script, { mode: 0o755 });
}
function makeFakeGlab(opts: { authStatus?: 'ok' | 'fail'; repoCreate?: 'success' | 'fail'; webUrl?: string } = {}) {
const authStatus = opts.authStatus ?? 'ok';
const repoCreate = opts.repoCreate ?? 'success';
const webUrl = opts.webUrl ?? 'https://gitlab.com/testuser/gstack-artifacts-testuser';
const script = `#!/bin/bash
echo "glab $@" >> "${glabCallLog}"
case "$1" in
auth) ${authStatus === 'ok' ? 'exit 0' : 'exit 1'} ;;
repo)
shift
case "$1" in
create) ${repoCreate === 'success' ? 'exit 0' : 'exit 1'} ;;
view)
# glab repo view <name> -F json
echo '{"web_url":"${webUrl}"}'
exit 0
;;
esac
;;
esac
exit 0
`;
fs.writeFileSync(path.join(fakeBinDir, 'glab'), script, { mode: 0o755 });
}
/**
* git shim that no-ops the network calls (ls-remote, fetch, push, pull) so
* tests don't actually need a reachable remote. Real git is used for local
* operations like init / config / commit / remote set-url. This keeps the
* test focused on artifacts-init's branching logic, not git plumbing.
*/
function makeFakeGit() {
const realGit = spawnSync('which', ['git'], { encoding: 'utf-8' }).stdout.trim();
const script = `#!/bin/bash
# Walk argv past leading -C <dir> and similar flags to find the real subcommand.
args=("$@")
i=0
while [ $i -lt \${#args[@]} ]; do
case "\${args[$i]}" in
-C) i=$((i+2)) ;;
-c) i=$((i+2)) ;;
--) break ;;
-*) i=$((i+1)) ;;
*) break ;;
esac
done
sub="\${args[$i]:-}"
case "$sub" in
ls-remote|fetch|push|pull) exit 0 ;;
*) exec "${realGit}" "$@" ;;
esac
`;
fs.writeFileSync(path.join(fakeBinDir, 'git'), script, { mode: 0o755 });
}
function run(argv: string[], opts: { env?: Record<string, string>; input?: string } = {}) {
// Include the bin/ dir so artifacts-init can find artifacts-url.
const binDir = path.join(ROOT, 'bin');
const env = {
PATH: `${fakeBinDir}:${binDir}:/usr/bin:/bin:/opt/homebrew/bin`,
GSTACK_HOME: tmpHome,
USER: 'testuser',
HOME: tmpHome,
...(opts.env || {}),
};
const res = spawnSync(INIT_BIN, argv, {
env,
encoding: 'utf-8',
input: opts.input,
cwd: ROOT,
});
return {
stdout: res.stdout || '',
stderr: res.stderr || '',
status: res.status ?? -1,
};
}
function readCalls(file: string): string[] {
if (!fs.existsSync(file)) return [];
return fs.readFileSync(file, 'utf-8').trim().split('\n').filter(Boolean);
}
beforeEach(() => {
tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'artifacts-init-'));
bareRemote = fs.mkdtempSync(path.join(os.tmpdir(), 'artifacts-bare-'));
fakeBinDir = fs.mkdtempSync(path.join(os.tmpdir(), 'artifacts-fake-bin-'));
ghCallLog = path.join(fakeBinDir, 'gh-calls.log');
glabCallLog = path.join(fakeBinDir, 'glab-calls.log');
spawnSync('git', ['init', '--bare', '-q', '-b', 'main', bareRemote]);
makeFakeGit();
});
afterEach(() => {
fs.rmSync(tmpHome, { recursive: true, force: true });
fs.rmSync(bareRemote, { recursive: true, force: true });
fs.rmSync(fakeBinDir, { recursive: true, force: true });
});
describe('gstack-artifacts-init provider selection', () => {
test('--host github invokes gh repo create with gstack-artifacts-$USER', () => {
makeFakeGh({});
const r = run(['--host', 'github']);
if (r.status !== 0) console.error('STDERR:', r.stderr);
expect(r.status).toBe(0);
const calls = readCalls(ghCallLog);
const createCall = calls.find((c) => c.startsWith('gh repo create'));
expect(createCall).toBeDefined();
expect(createCall).toContain('gstack-artifacts-testuser');
expect(createCall).toContain('--private');
});
test('--host gitlab invokes glab repo create', () => {
makeFakeGlab({});
const r = run(['--host', 'gitlab']);
if (r.status !== 0) console.error('STDERR:', r.stderr);
expect(r.status).toBe(0);
const calls = readCalls(glabCallLog);
const createCall = calls.find((c) => c.startsWith('glab repo create'));
expect(createCall).toBeDefined();
expect(createCall).toContain('gstack-artifacts-testuser');
expect(createCall).toContain('--private');
});
test('both gh and glab authed → interactive prompt picks GitHub by default (Enter = 1)', () => {
makeFakeGh({});
makeFakeGlab({});
const r = run([], { input: '\n' });
expect(r.status).toBe(0);
expect(readCalls(ghCallLog).some((c) => c.startsWith('gh repo create'))).toBe(true);
expect(readCalls(glabCallLog).some((c) => c.startsWith('glab repo create'))).toBe(false);
});
test('both gh and glab authed → user picks 2 → glab is used', () => {
makeFakeGh({});
makeFakeGlab({});
const r = run([], { input: '2\n' });
expect(r.status).toBe(0);
expect(readCalls(glabCallLog).some((c) => c.startsWith('glab repo create'))).toBe(true);
expect(readCalls(ghCallLog).some((c) => c.startsWith('gh repo create'))).toBe(false);
});
test('only gh authed → defaults to github (no prompt)', () => {
makeFakeGh({});
// No glab installed.
const r = run([]);
expect(r.status).toBe(0);
expect(readCalls(ghCallLog).some((c) => c.startsWith('gh repo create'))).toBe(true);
});
test('only glab authed → defaults to gitlab (no prompt)', () => {
makeFakeGlab({});
const r = run([]);
expect(r.status).toBe(0);
expect(readCalls(glabCallLog).some((c) => c.startsWith('glab repo create'))).toBe(true);
});
test('neither authed → falls through to manual URL paste', () => {
// No gh, no glab fakes.
const r = run([], { input: 'https://github.com/testuser/gstack-artifacts-testuser\n' });
expect(r.status).toBe(0);
expect(r.stderr).toContain('Neither gh nor glab');
});
});
describe('gstack-artifacts-init canonical URL storage (codex Finding #10)', () => {
test('stores HTTPS URL canonical in ~/.gstack-artifacts-remote.txt', () => {
makeFakeGh({ webUrl: 'https://github.com/testuser/gstack-artifacts-testuser' });
const r = run(['--host', 'github']);
expect(r.status).toBe(0);
const remoteFile = path.join(tmpHome, '.gstack-artifacts-remote.txt');
expect(fs.existsSync(remoteFile)).toBe(true);
const stored = fs.readFileSync(remoteFile, 'utf-8').trim();
// HTTPS, NOT SSH (codex Finding #10: canonical = HTTPS).
expect(stored).toMatch(/^https:\/\//);
expect(stored).toBe('https://github.com/testuser/gstack-artifacts-testuser');
});
test('strips trailing .git from gh repo view output', () => {
makeFakeGh({ webUrl: 'https://github.com/testuser/gstack-artifacts-testuser.git' });
const r = run(['--host', 'github']);
expect(r.status).toBe(0);
const stored = fs.readFileSync(path.join(tmpHome, '.gstack-artifacts-remote.txt'), 'utf-8').trim();
expect(stored).toBe('https://github.com/testuser/gstack-artifacts-testuser');
});
test('configures git origin with SSH form (derived from canonical HTTPS)', () => {
makeFakeGh({ webUrl: 'https://github.com/testuser/gstack-artifacts-testuser' });
const r = run(['--host', 'github']);
expect(r.status).toBe(0);
const remote = spawnSync('git', ['-C', tmpHome, 'remote', 'get-url', 'origin'], { encoding: 'utf-8' });
expect(remote.stdout.trim()).toBe('git@github.com:testuser/gstack-artifacts-testuser.git');
});
});
describe('gstack-artifacts-init brain-admin hookup printout (codex Finding #3)', () => {
test('--url-form-supported false prints the two-line clone-then-path form', () => {
makeFakeGh({});
const r = run(['--host', 'github', '--url-form-supported', 'false']);
expect(r.status).toBe(0);
expect(r.stdout).toContain('Send this to your brain admin');
expect(r.stdout).toContain('git clone');
expect(r.stdout).toContain('--path');
expect(r.stdout).toContain('--federated');
// The forward-compat hint should still appear.
expect(r.stdout).toContain('When gbrain ships --url support');
});
test('--url-form-supported true prints the one-liner with --url', () => {
makeFakeGh({});
const r = run(['--host', 'github', '--url-form-supported', 'true']);
expect(r.status).toBe(0);
expect(r.stdout).toContain('Send this to your brain admin');
expect(r.stdout).toContain('gbrain sources add gstack-artifacts-testuser --url');
expect(r.stdout).not.toContain('git clone');
});
test('the gbrain command line uses canonical HTTPS, not SSH', () => {
makeFakeGh({ webUrl: 'https://github.com/testuser/gstack-artifacts-testuser' });
const r = run(['--host', 'github', '--url-form-supported', 'true']);
expect(r.status).toBe(0);
// Find the line with the gbrain command and check ITS URL is HTTPS.
const gbrainLine = r.stdout
.split('\n')
.find((l) => l.includes('gbrain sources add'));
expect(gbrainLine).toBeDefined();
expect(gbrainLine).toContain('https://github.com/testuser/gstack-artifacts-testuser');
expect(gbrainLine).not.toContain('git@github.com');
// Note: the SSH form does appear in the printout as informational
// (the "Push: ..." line), which is intentional — that's the URL git
// actually uses for push.
});
});
describe('gstack-artifacts-init idempotency', () => {
test('--remote <url> bypasses provider selection entirely', () => {
makeFakeGh({});
const r = run(['--remote', 'https://github.com/testuser/gstack-artifacts-testuser']);
expect(r.status).toBe(0);
// gh auth was checked (still useful for provider detection) but no repo create.
expect(readCalls(ghCallLog).some((c) => c.startsWith('gh repo create'))).toBe(false);
});
test('re-run with same --remote is safe (no conflict error)', () => {
makeFakeGh({});
const url = 'https://github.com/testuser/gstack-artifacts-testuser';
run(['--remote', url]);
const r2 = run(['--remote', url]);
expect(r2.status).toBe(0);
});
test('re-run with DIFFERENT --remote exits 1 with conflict message', () => {
makeFakeGh({});
run(['--remote', 'https://github.com/testuser/gstack-artifacts-testuser']);
const r2 = run(['--remote', 'https://github.com/other/repo']);
expect(r2.status).not.toBe(0);
expect(r2.stderr).toContain('already a git repo');
});
});

87
test/gstack-artifacts-url.test.ts Normal file
View File

@ -0,0 +1,87 @@
/**
* gstack-artifacts-url — URL canonicalization helper.
*
* Centralizes HTTPS↔SSH conversion so callers don't each string-mangle. Per
* codex Finding #10: store one canonical form (HTTPS) and derive all others.
*/
import { describe, test, expect } from 'bun:test';
import * as path from 'path';
import { spawnSync } from 'child_process';
const ROOT = path.resolve(import.meta.dir, '..');
const URL_BIN = path.join(ROOT, 'bin', 'gstack-artifacts-url');
function run(args: string[]): { code: number; stdout: string; stderr: string } {
const r = spawnSync(URL_BIN, args, { encoding: 'utf-8' });
return {
code: r.status ?? -1,
stdout: (r.stdout || '').trim(),
stderr: (r.stderr || '').trim(),
};
}
describe('gstack-artifacts-url', () => {
test('--to ssh from canonical https', () => {
const r = run(['--to', 'ssh', 'https://github.com/garrytan/gstack-artifacts-garrytan']);
expect(r.code).toBe(0);
expect(r.stdout).toBe('git@github.com:garrytan/gstack-artifacts-garrytan.git');
});
test('--to ssh from https-with-.git', () => {
const r = run(['--to', 'ssh', 'https://github.com/garrytan/gstack-artifacts-garrytan.git']);
expect(r.stdout).toBe('git@github.com:garrytan/gstack-artifacts-garrytan.git');
});
test('--to https is idempotent on https input', () => {
const r = run(['--to', 'https', 'https://github.com/garrytan/gstack-artifacts-garrytan']);
expect(r.stdout).toBe('https://github.com/garrytan/gstack-artifacts-garrytan');
});
test('--to https from git@host:owner/repo.git', () => {
const r = run(['--to', 'https', 'git@github.com:garrytan/gstack-artifacts-garrytan.git']);
expect(r.stdout).toBe('https://github.com/garrytan/gstack-artifacts-garrytan');
});
test('--to https from ssh:// scheme (gitlab self-hosted style)', () => {
const r = run(['--to', 'https', 'ssh://git@gitlab.example.org/team/gstack-artifacts-team.git']);
expect(r.stdout).toBe('https://gitlab.example.org/team/gstack-artifacts-team');
});
test('--host extracts hostname from any form', () => {
expect(run(['--host', 'https://github.com/x/y']).stdout).toBe('github.com');
expect(run(['--host', 'git@gitlab.com:x/y.git']).stdout).toBe('gitlab.com');
expect(run(['--host', 'ssh://git@gitlab.example.org/x/y.git']).stdout).toBe('gitlab.example.org');
});
test('--owner-repo extracts the path segment', () => {
expect(run(['--owner-repo', 'https://github.com/garrytan/gstack-artifacts-garrytan']).stdout)
.toBe('garrytan/gstack-artifacts-garrytan');
expect(run(['--owner-repo', 'git@github.com:team/gstack-artifacts-team.git']).stdout)
.toBe('team/gstack-artifacts-team');
});
test('rejects unrecognized URL form with exit 3', () => {
const r = run(['--to', 'ssh', 'not a url']);
expect(r.code).toBe(3);
expect(r.stderr).toContain('unrecognized URL form');
});
test('rejects missing args with exit 2', () => {
expect(run([]).code).toBe(2);
expect(run(['--to']).code).toBe(2);
expect(run(['--to', 'ssh']).code).toBe(2);
});
test('rejects unknown --to target', () => {
const r = run(['--to', 'svn', 'https://github.com/x/y']);
expect(r.code).toBe(2);
});
test('round-trip: https → ssh → https is identity', () => {
const original = 'https://github.com/garrytan/gstack-artifacts-garrytan';
const ssh = run(['--to', 'ssh', original]).stdout;
const back = run(['--to', 'https', ssh]).stdout;
expect(back).toBe(original);
});
});

236
test/gstack-brain-init-gh-mock.test.ts
View File

@ -1,236 +0,0 @@
/**
* gstack-brain-init — mocked-gh integration tests.
*
* The regular brain-sync tests pass `--remote <bare-git-url>` to skip the
* gh-repo-creation path entirely. That left the happy path (user just
* presses Enter, gstack-brain-init calls `gh repo create --private`)
* with zero coverage — you'd only know it broke when a real user tried
* it with a real GitHub account.
*
* These tests put a fake `gh` binary on PATH that records every call
* into a file, then run gstack-brain-init in its non-flag interactive
* mode and assert the fake `gh` was invoked with the expected arguments.
*
* No real GitHub account, no live API, deterministic per-run.
*/
import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import { spawnSync } from 'child_process';
const ROOT = path.resolve(import.meta.dir, '..');
const BIN_DIR = path.join(ROOT, 'bin');
const INIT_BIN = path.join(BIN_DIR, 'gstack-brain-init');
let tmpHome: string;
let bareRemote: string;
let fakeBinDir: string;
let ghCallLog: string;
function makeFakeGh(opts: {
authStatus?: 'ok' | 'fail';
repoCreate?: 'success' | 'already-exists' | 'fail';
sshUrl?: string;
}) {
const authStatus = opts.authStatus ?? 'ok';
const repoCreate = opts.repoCreate ?? 'success';
const sshUrl = opts.sshUrl ?? bareRemote;
const script = `#!/bin/bash
echo "gh $@" >> "${ghCallLog}"
case "$1" in
auth)
${authStatus === 'ok' ? 'exit 0' : 'exit 1'}
;;
repo)
shift
case "$1" in
create)
${
repoCreate === 'success'
? 'exit 0'
: repoCreate === 'already-exists'
? 'echo "GraphQL: Name already exists on this account" >&2; exit 1'
: 'echo "network error" >&2; exit 1'
}
;;
view)
# Emulate \`gh repo view <name> --json sshUrl -q .sshUrl\`
echo "${sshUrl}"
exit 0
;;
esac
;;
esac
exit 0
`;
const ghPath = path.join(fakeBinDir, 'gh');
fs.writeFileSync(ghPath, script, { mode: 0o755 });
return ghPath;
}
function run(
argv: string[],
opts: { env?: Record<string, string>; input?: string } = {}
) {
const env = {
// Put the fake bin dir FIRST on PATH so our mock gh wins.
PATH: `${fakeBinDir}:/usr/bin:/bin:/opt/homebrew/bin`,
GSTACK_HOME: tmpHome,
USER: 'testuser',
HOME: tmpHome,
...(opts.env || {}),
};
const res = spawnSync(INIT_BIN, argv, {
env,
encoding: 'utf-8',
input: opts.input,
cwd: ROOT,
});
return {
stdout: res.stdout || '',
stderr: res.stderr || '',
status: res.status ?? -1,
};
}
function readGhCalls(): string[] {
if (!fs.existsSync(ghCallLog)) return [];
return fs.readFileSync(ghCallLog, 'utf-8').trim().split('\n').filter(Boolean);
}
beforeEach(() => {
tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'brain-init-gh-mock-'));
bareRemote = fs.mkdtempSync(path.join(os.tmpdir(), 'brain-init-bare-'));
fakeBinDir = fs.mkdtempSync(path.join(os.tmpdir(), 'brain-init-fake-bin-'));
ghCallLog = path.join(fakeBinDir, 'gh-calls.log');
spawnSync('git', ['init', '--bare', '-q', '-b', 'main', bareRemote]);
});
afterEach(() => {
fs.rmSync(tmpHome, { recursive: true, force: true });
fs.rmSync(bareRemote, { recursive: true, force: true });
fs.rmSync(fakeBinDir, { recursive: true, force: true });
const remoteFile = path.join(os.homedir(), '.gstack-brain-remote.txt');
if (fs.existsSync(remoteFile)) {
const contents = fs.readFileSync(remoteFile, 'utf-8');
if (contents.includes(bareRemote)) fs.unlinkSync(remoteFile);
}
});
describe('gstack-brain-init uses gh CLI when present + authed', () => {
test('calls gh repo create --private with the computed default name', () => {
makeFakeGh({ authStatus: 'ok', repoCreate: 'success' });
// Interactive mode; pressing Enter accepts the gh default.
const r = run([], { input: '\n' });
expect(r.status).toBe(0);
const calls = readGhCalls();
// First call: auth status check
expect(calls.some((c) => c.startsWith('gh auth'))).toBe(true);
// The create call
const createCall = calls.find((c) => c.startsWith('gh repo create'));
expect(createCall).toBeDefined();
expect(createCall).toContain('gstack-brain-testuser');
expect(createCall).toContain('--private');
expect(createCall).toContain('--description');
// --source is intentionally omitted: gh requires the source dir to already
// be a git repo, but brain-init doesn't `git init $GSTACK_HOME` until later.
// Creating bare and wiring up the remote explicitly avoids that ordering bug.
expect(createCall).not.toContain('--source');
});
test('falls back to gh repo view when create reports already-exists', () => {
makeFakeGh({ authStatus: 'ok', repoCreate: 'already-exists' });
const r = run([], { input: '\n' });
expect(r.status).toBe(0);
const calls = readGhCalls();
// create was attempted
expect(calls.some((c) => c.startsWith('gh repo create'))).toBe(true);
// then view was called to recover the URL
expect(calls.some((c) => c.startsWith('gh repo view') && c.includes('gstack-brain-testuser'))).toBe(true);
// The view output (bareRemote URL) should have been wired up as origin.
const remote = spawnSync('git', ['-C', tmpHome, 'remote', 'get-url', 'origin'], {
encoding: 'utf-8',
});
expect(remote.stdout.trim()).toBe(bareRemote);
});
test('user-provided URL bypasses gh create entirely', () => {
makeFakeGh({ authStatus: 'ok', repoCreate: 'fail' });
const r = run([], { input: `${bareRemote}\n` });
expect(r.status).toBe(0);
const calls = readGhCalls();
// gh auth was still checked
expect(calls.some((c) => c.startsWith('gh auth'))).toBe(true);
// but create was NOT called (user bypassed the default)
expect(calls.some((c) => c.startsWith('gh repo create'))).toBe(false);
});
});
describe('gstack-brain-init without gh CLI', () => {
test('prompts for URL when gh is not on PATH', () => {
// Don't install fake gh — PATH will not have it.
// Use a bare-minimum PATH so nothing else shadows.
const stripped = `${fakeBinDir}:/usr/bin:/bin`;
const res = spawnSync(INIT_BIN, [], {
env: {
PATH: stripped,
GSTACK_HOME: tmpHome,
USER: 'testuser',
HOME: tmpHome,
},
encoding: 'utf-8',
input: `${bareRemote}\n`,
cwd: ROOT,
});
expect(res.status).toBe(0);
expect(res.stdout).toContain('gh CLI not found');
// Remote got set from the stdin paste
const remote = spawnSync('git', ['-C', tmpHome, 'remote', 'get-url', 'origin'], {
encoding: 'utf-8',
});
expect(remote.stdout.trim()).toBe(bareRemote);
});
test('prompts for URL when gh is present but not authed', () => {
makeFakeGh({ authStatus: 'fail' });
const r = run([], { input: `${bareRemote}\n` });
expect(r.status).toBe(0);
expect(r.stdout).toContain('gh CLI not found or not authenticated');
const calls = readGhCalls();
// Only `gh auth status` was called; no create attempt.
expect(calls.some((c) => c.startsWith('gh auth'))).toBe(true);
expect(calls.some((c) => c.startsWith('gh repo create'))).toBe(false);
});
});
describe('idempotency via flag', () => {
test('--remote <url> skips all gh calls', () => {
makeFakeGh({ authStatus: 'ok', repoCreate: 'success' });
const r = run(['--remote', bareRemote]);
expect(r.status).toBe(0);
const calls = readGhCalls();
// Zero calls to gh — the --remote flag short-circuits the interactive path.
expect(calls.length).toBe(0);
});
test('re-run with matching --remote is safe (no conflicting-remote error)', () => {
run(['--remote', bareRemote]);
const r2 = run(['--remote', bareRemote]);
expect(r2.status).toBe(0);
});
test('re-run with DIFFERENT --remote exits 1 with a conflict message', () => {
run(['--remote', bareRemote]);
const otherRemote = fs.mkdtempSync(path.join(os.tmpdir(), 'brain-init-other-'));
spawnSync('git', ['init', '--bare', '-q', '-b', 'main', otherRemote]);
try {
const r2 = run(['--remote', otherRemote]);
expect(r2.status).not.toBe(0);
expect(r2.stderr).toContain('already a git repo');
} finally {
fs.rmSync(otherRemote, { recursive: true, force: true });
}
});
});

275
test/gstack-gbrain-detect-mcp-mode.test.ts Normal file
View File

@ -0,0 +1,275 @@
/**
* gstack-gbrain-detect — gbrain_mcp_mode + gstack_artifacts_remote tests.
*
* The script has a 3-tier fallback chain for resolving gbrain_mcp_mode:
* 1. `claude mcp get gbrain --json` (preferred — public CLI surface)
* 2. `claude mcp list` text-grep (older claude versions without --json)
* 3. `~/.claude.json` jq read (fallback if claude binary is absent)
*
* Each layer is tested by mocking the layer it depends on. Per codex
* Finding #3 (defense-in-depth ordering): if Anthropic moves the
* ~/.claude.json file format, the first two tiers should still work.
*/
import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import { spawnSync } from 'child_process';
const ROOT = path.resolve(import.meta.dir, '..');
const DETECT_BIN = path.join(ROOT, 'bin', 'gstack-gbrain-detect');
let tmpHome: string;
let fakeBinDir: string;
function makeFakeClaude(opts: {
hasGetJson?: boolean;
getJsonOutput?: string; // raw JSON string
hasMcpList?: boolean;
mcpListOutput?: string;
exitOnAll?: number; // if set, claude always exits with this code
}) {
const { hasGetJson, getJsonOutput, hasMcpList, mcpListOutput, exitOnAll } = opts;
const script = `#!/bin/bash
${exitOnAll !== undefined ? `exit ${exitOnAll}` : ''}
case "$1 $2" in
"mcp get")
if [ "$3" = "gbrain" ] && [ "$4" = "--json" ]; then
${hasGetJson ? `cat <<'JSON'
${getJsonOutput || '{}'}
JSON` : 'exit 1'}
exit 0
fi
;;
"mcp list")
${hasMcpList ? `cat <<'EOM'
${mcpListOutput || ''}
EOM` : 'exit 1'}
exit 0
;;
esac
exit 1
`;
fs.writeFileSync(path.join(fakeBinDir, 'claude'), script, { mode: 0o755 });
}
function runDetect(extraEnv: Record<string, string> = {}): { code: number; json: any; stderr: string } {
const realPath = process.env.PATH ?? '';
const r = spawnSync(DETECT_BIN, [], {
env: {
// Put fakeBinDir first so our claude shim wins; include the project bin
// for any sibling scripts and standard paths for jq/etc.
PATH: `${fakeBinDir}:${path.join(ROOT, 'bin')}:${realPath}`,
HOME: tmpHome,
GSTACK_HOME: path.join(tmpHome, '.gstack'),
...extraEnv,
},
encoding: 'utf-8',
});
let json: any = null;
try {
json = JSON.parse(r.stdout || '{}');
} catch {
json = null;
}
return { code: r.status ?? -1, json, stderr: r.stderr || '' };
}
beforeEach(() => {
tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'detect-mcp-mode-'));
fakeBinDir = fs.mkdtempSync(path.join(os.tmpdir(), 'detect-fake-bin-'));
});
afterEach(() => {
fs.rmSync(tmpHome, { recursive: true, force: true });
fs.rmSync(fakeBinDir, { recursive: true, force: true });
});
describe('gbrain_mcp_mode — Tier 1: claude mcp get --json', () => {
test('type=http → remote-http', () => {
makeFakeClaude({
hasGetJson: true,
getJsonOutput: JSON.stringify({ type: 'http', url: 'https://example.com/mcp' }),
});
const r = runDetect();
expect(r.code).toBe(0);
expect(r.json.gbrain_mcp_mode).toBe('remote-http');
});
test('type=stdio → local-stdio', () => {
makeFakeClaude({
hasGetJson: true,
getJsonOutput: JSON.stringify({ type: 'stdio', command: '/usr/local/bin/gbrain' }),
});
expect(runDetect().json.gbrain_mcp_mode).toBe('local-stdio');
});
test('type=sse → remote-http', () => {
makeFakeClaude({
hasGetJson: true,
getJsonOutput: JSON.stringify({ type: 'sse', url: 'https://example.com/sse' }),
});
expect(runDetect().json.gbrain_mcp_mode).toBe('remote-http');
});
test('no type field but has url → remote-http (newer claude shape)', () => {
makeFakeClaude({
hasGetJson: true,
getJsonOutput: JSON.stringify({ url: 'https://example.com/mcp' }),
});
expect(runDetect().json.gbrain_mcp_mode).toBe('remote-http');
});
test('no type field but has command → local-stdio', () => {
makeFakeClaude({
hasGetJson: true,
getJsonOutput: JSON.stringify({ command: '/path/to/gbrain' }),
});
expect(runDetect().json.gbrain_mcp_mode).toBe('local-stdio');
});
});
describe('gbrain_mcp_mode — Tier 2: claude mcp list text-grep', () => {
test('falls back to mcp list when get --json fails', () => {
makeFakeClaude({
hasGetJson: false,
hasMcpList: true,
mcpListOutput: 'gbrain: https://wintermute.tail554574.ts.net:3131/mcp (HTTP) - ✓ Connected',
});
expect(runDetect().json.gbrain_mcp_mode).toBe('remote-http');
});
test('mcp list text-grep with stdio entry → local-stdio', () => {
makeFakeClaude({
hasGetJson: false,
hasMcpList: true,
mcpListOutput: 'gbrain: /usr/local/bin/gbrain serve - ✓ Connected',
});
expect(runDetect().json.gbrain_mcp_mode).toBe('local-stdio');
});
test('mcp list with no gbrain entry → none', () => {
makeFakeClaude({
hasGetJson: false,
hasMcpList: true,
mcpListOutput: 'posthog: https://mcp.posthog.com/mcp (HTTP)\nslack: https://slack.com/mcp (HTTP)',
});
expect(runDetect().json.gbrain_mcp_mode).toBe('none');
});
});
describe('gbrain_mcp_mode — Tier 3: ~/.claude.json jq read', () => {
test('reads mcpServers.gbrain.type=url → remote-http', () => {
// No fake claude binary; force fallback to file read.
fs.writeFileSync(
path.join(tmpHome, '.claude.json'),
JSON.stringify({
mcpServers: { gbrain: { type: 'url', url: 'https://example.com/mcp' } },
})
);
expect(runDetect().json.gbrain_mcp_mode).toBe('remote-http');
});
test('reads mcpServers.gbrain.type=stdio → local-stdio', () => {
fs.writeFileSync(
path.join(tmpHome, '.claude.json'),
JSON.stringify({
mcpServers: { gbrain: { type: 'stdio', command: '/path/gbrain' } },
})
);
expect(runDetect().json.gbrain_mcp_mode).toBe('local-stdio');
});
test('infers from url field if type is missing', () => {
fs.writeFileSync(
path.join(tmpHome, '.claude.json'),
JSON.stringify({
mcpServers: { gbrain: { url: 'https://example.com/mcp' } },
})
);
expect(runDetect().json.gbrain_mcp_mode).toBe('remote-http');
});
test('infers from command field if type is missing', () => {
fs.writeFileSync(
path.join(tmpHome, '.claude.json'),
JSON.stringify({
mcpServers: { gbrain: { command: '/path/gbrain' } },
})
);
expect(runDetect().json.gbrain_mcp_mode).toBe('local-stdio');
});
test('no gbrain entry in ~/.claude.json → none', () => {
fs.writeFileSync(
path.join(tmpHome, '.claude.json'),
JSON.stringify({ mcpServers: { posthog: { type: 'url', url: 'https://x' } } })
);
expect(runDetect().json.gbrain_mcp_mode).toBe('none');
});
});
describe('gbrain_mcp_mode — no info anywhere', () => {
test('no claude binary AND no ~/.claude.json → none', () => {
// No fake claude, no file.
expect(runDetect().json.gbrain_mcp_mode).toBe('none');
});
});
describe('gstack_artifacts_remote', () => {
test('reads ~/.gstack-artifacts-remote.txt when present', () => {
fs.writeFileSync(
path.join(tmpHome, '.gstack-artifacts-remote.txt'),
'https://github.com/garrytan/gstack-artifacts-garrytan\n'
);
expect(runDetect().json.gstack_artifacts_remote).toBe(
'https://github.com/garrytan/gstack-artifacts-garrytan'
);
});
test('migration-window fallback: reads ~/.gstack-brain-remote.txt if artifacts file is missing', () => {
fs.writeFileSync(
path.join(tmpHome, '.gstack-brain-remote.txt'),
'git@github.com:garrytan/gstack-brain-garrytan.git\n'
);
expect(runDetect().json.gstack_artifacts_remote).toBe(
'git@github.com:garrytan/gstack-brain-garrytan.git'
);
});
test('artifacts file wins over brain file when both exist', () => {
fs.writeFileSync(
path.join(tmpHome, '.gstack-artifacts-remote.txt'),
'https://github.com/x/new\n'
);
fs.writeFileSync(
path.join(tmpHome, '.gstack-brain-remote.txt'),
'https://github.com/x/old\n'
);
expect(runDetect().json.gstack_artifacts_remote).toBe('https://github.com/x/new');
});
test('empty when neither file exists', () => {
expect(runDetect().json.gstack_artifacts_remote).toBe('');
});
});
describe('schema regression', () => {
test('output JSON has all expected keys (sync-gbrain compat)', () => {
const r = runDetect();
expect(r.code).toBe(0);
const keys = Object.keys(r.json).sort();
expect(keys).toEqual([
'gbrain_config_exists',
'gbrain_doctor_ok',
'gbrain_engine',
'gbrain_mcp_mode',
'gbrain_on_path',
'gbrain_version',
'gstack_artifacts_remote',
'gstack_brain_git',
'gstack_brain_sync_mode',
]);
});
});

256
test/gstack-gbrain-mcp-verify.test.ts Normal file
View File

@ -0,0 +1,256 @@
/**
* gstack-gbrain-mcp-verify — error-classification tests with a mocked curl.
*
* The script POSTs initialize to a remote MCP URL and classifies failures into
* NETWORK / AUTH / MALFORMED. Each branch fires from a different curl shape
* (exit code, body, HTTP status) so we drive them by replacing curl on PATH
* with a shim that emits whatever the test wants.
*
* The Accept-header gotcha (server returns `Not Acceptable` if the client
* doesn't pass BOTH application/json and text/event-stream) is a verified
* historical regression — there's a dedicated assertion that the real curl
* invocation includes both values.
*/
import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import { spawnSync } from 'child_process';
const ROOT = path.resolve(import.meta.dir, '..');
const VERIFY_BIN = path.join(ROOT, 'bin', 'gstack-gbrain-mcp-verify');
let tmpDir: string;
let fakeBinDir: string;
let curlCallLog: string;
/**
* Write a fake curl shim. Three knobs:
* exitCode — what `curl` returns (0=ok, 6=DNS, 28=timeout, etc).
* httpCode — what `-w '%{http_code}'` should print to stdout.
* bodyFile — what `curl` writes to its `-o <file>` target.
* bodyOnInit — body to write only on the initialize call (request 1).
* bodyOnTools — body to write on the tools/list follow-up (request 2).
*/
function makeFakeCurl(opts: {
exitCode?: number;
httpCode?: string;
bodyOnInit?: string;
bodyOnTools?: string;
}) {
const exitCode = opts.exitCode ?? 0;
const httpCode = opts.httpCode ?? '200';
const bodyInit = opts.bodyOnInit ?? '';
const bodyTools = opts.bodyOnTools ?? '{"jsonrpc":"2.0","id":2,"result":{"tools":[]}}';
// Logs every call's argv to curlCallLog and pulls -o + -d to disambiguate
// the initialize call from the tools/list follow-up by inspecting the
// request body for "initialize" or "tools/list".
const script = `#!/bin/bash
# Log full argv (one line per call).
printf 'CURL_CALL '"'"'%s'"'"' ' "$@" >> "${curlCallLog}"
echo "" >> "${curlCallLog}"
# Walk argv to find -o <out> and -d <data>.
out=""
data=""
while [ $# -gt 0 ]; do
case "$1" in
-o) out="$2"; shift 2 ;;
-d) data="$2"; shift 2 ;;
*) shift ;;
esac
done
# Decide which body to write.
if [ -n "$out" ]; then
case "$data" in
*initialize*) printf '%s' '${bodyInit.replace(/'/g, "'\\''")}' > "$out" ;;
*tools/list*) printf '%s' '${bodyTools.replace(/'/g, "'\\''")}' > "$out" ;;
esac
fi
# httpCode goes to stdout (caller uses -w '%{http_code}').
printf '${httpCode}'
exit ${exitCode}
`;
fs.writeFileSync(path.join(fakeBinDir, 'curl'), script, { mode: 0o755 });
}
function runVerify(token: string, url: string): { code: number; stdout: string; stderr: string } {
const result = spawnSync(VERIFY_BIN, [url], {
env: {
...process.env,
PATH: `${fakeBinDir}:${process.env.PATH}`,
GBRAIN_MCP_TOKEN: token,
},
encoding: 'utf-8',
});
return {
code: result.status ?? -1,
stdout: result.stdout || '',
stderr: result.stderr || '',
};
}
beforeEach(() => {
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-mcp-verify-test-'));
fakeBinDir = path.join(tmpDir, 'fake-bin');
curlCallLog = path.join(tmpDir, 'curl-calls.log');
fs.mkdirSync(fakeBinDir, { recursive: true });
fs.writeFileSync(curlCallLog, '');
});
afterEach(() => {
fs.rmSync(tmpDir, { recursive: true, force: true });
});
describe('gstack-gbrain-mcp-verify', () => {
test('SUCCESS: returns server name + version, sources_add_url_supported=false when no sources_add tool', () => {
const initBody =
'event: message\ndata: {"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"gbrain","version":"0.27.1"}},"jsonrpc":"2.0","id":1}';
const toolsBody = '{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"search"},{"name":"put_page"}]}}';
makeFakeCurl({ httpCode: '200', bodyOnInit: initBody, bodyOnTools: toolsBody });
const r = runVerify('faketoken', 'https://example.com/mcp');
expect(r.code).toBe(0);
const j = JSON.parse(r.stdout);
expect(j.status).toBe('success');
expect(j.server_name).toBe('gbrain');
expect(j.server_version).toBe('0.27.1');
expect(j.error_class).toBeNull();
expect(j.sources_add_url_supported).toBe(false);
});
test('SUCCESS: sources_add_url_supported=true when MCP exposes a sources_add tool', () => {
const initBody =
'event: message\ndata: {"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"gbrain","version":"0.99.0"}},"jsonrpc":"2.0","id":1}';
const toolsBody = '{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"search"},{"name":"sources_add"}]}}';
makeFakeCurl({ httpCode: '200', bodyOnInit: initBody, bodyOnTools: toolsBody });
const r = runVerify('faketoken', 'https://example.com/mcp');
expect(r.code).toBe(0);
const j = JSON.parse(r.stdout);
expect(j.sources_add_url_supported).toBe(true);
});
test('NETWORK: curl exit 6 (DNS failure)', () => {
makeFakeCurl({ exitCode: 6, httpCode: '000' });
const r = runVerify('faketoken', 'https://nope.invalid/mcp');
expect(r.code).toBe(1);
const j = JSON.parse(r.stdout);
expect(j.status).toBe('network');
expect(j.error_class).toBe('NETWORK');
expect(j.error_text).toContain('Tailscale/DNS');
expect(j.error_text).toContain('nope.invalid');
});
test('AUTH: HTTP 401', () => {
makeFakeCurl({ httpCode: '401', bodyOnInit: '{"error":"unauthorized"}' });
const r = runVerify('badtoken', 'https://example.com/mcp');
expect(r.code).toBe(1);
const j = JSON.parse(r.stdout);
expect(j.status).toBe('auth');
expect(j.error_class).toBe('AUTH');
expect(j.error_text).toContain('rotate token');
});
test('AUTH: HTTP 403', () => {
makeFakeCurl({ httpCode: '403', bodyOnInit: '{}' });
const r = runVerify('badtoken', 'https://example.com/mcp');
expect(JSON.parse(r.stdout).error_class).toBe('AUTH');
});
test('AUTH: HTTP 500 with stale-token-shaped body', () => {
makeFakeCurl({
httpCode: '500',
bodyOnInit: '{"error":"server_error","error_description":"Internal Server Error: invalid auth token"}',
});
const r = runVerify('staletoken', 'https://example.com/mcp');
expect(r.code).toBe(1);
const j = JSON.parse(r.stdout);
expect(j.status).toBe('auth');
expect(j.error_text).toContain('stale-token');
});
test('MALFORMED: HTTP 500 without auth-shape (e.g., real server crash)', () => {
makeFakeCurl({ httpCode: '500', bodyOnInit: '{"error":"oom","stacktrace":"..."}' });
const r = runVerify('faketoken', 'https://example.com/mcp');
expect(r.code).toBe(1);
const j = JSON.parse(r.stdout);
expect(j.status).toBe('malformed');
expect(j.error_class).toBe('MALFORMED');
expect(j.error_text).toContain('HTTP 500');
});
test('MALFORMED: Not Acceptable (Accept-header gotcha)', () => {
makeFakeCurl({
httpCode: '200',
bodyOnInit: '{"jsonrpc":"2.0","error":{"code":-32000,"message":"Not Acceptable: Client must accept both application/json and text/event-stream"},"id":null}',
});
const r = runVerify('faketoken', 'https://example.com/mcp');
expect(r.code).toBe(1);
const j = JSON.parse(r.stdout);
expect(j.status).toBe('malformed');
expect(j.error_text).toContain('Accept-header');
expect(j.error_text).toContain('text/event-stream');
});
test('MALFORMED: 200 OK but missing serverInfo', () => {
makeFakeCurl({ httpCode: '200', bodyOnInit: '{"jsonrpc":"2.0","id":1,"result":{}}' });
const r = runVerify('faketoken', 'https://example.com/mcp');
expect(r.code).toBe(1);
expect(JSON.parse(r.stdout).status).toBe('malformed');
});
test('REGRESSION: curl is invoked with BOTH application/json AND text/event-stream Accept', () => {
const initBody =
'event: message\ndata: {"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"gbrain","version":"0.27.1"}},"jsonrpc":"2.0","id":1}';
makeFakeCurl({ httpCode: '200', bodyOnInit: initBody });
runVerify('faketoken', 'https://example.com/mcp');
const log = fs.readFileSync(curlCallLog, 'utf-8');
// Both substrings must appear in the same Accept header. Order matters
// for reasonable readability ("application/json, text/event-stream"),
// but the server doesn't care about order — only assert presence.
expect(log).toContain('application/json');
expect(log).toContain('text/event-stream');
});
test('REGRESSION: token never appears in argv (must be in env, not command line)', () => {
const initBody =
'event: message\ndata: {"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"gbrain","version":"0.27.1"}},"jsonrpc":"2.0","id":1}';
makeFakeCurl({ httpCode: '200', bodyOnInit: initBody });
runVerify('SECRET-TOKEN-MARKER-12345', 'https://example.com/mcp');
const log = fs.readFileSync(curlCallLog, 'utf-8');
// The token IS passed as a curl -H header value, so it WILL appear in
// the curl argv when the script invokes curl. This is fine for the
// shim (it's a localhost-only argv) but the corresponding production
// concern (argv visible to ps) is documented in the plan and outside
// this script's responsibility. Here we only assert the token doesn't
// leak into stdout/stderr of the verify wrapper.
expect(log).toContain('SECRET-TOKEN-MARKER-12345'); // it's in the curl call
});
test('USAGE: missing GBRAIN_MCP_TOKEN env exits 2', () => {
makeFakeCurl({});
const r = spawnSync(VERIFY_BIN, ['https://example.com/mcp'], {
env: { ...process.env, PATH: `${fakeBinDir}:${process.env.PATH}`, GBRAIN_MCP_TOKEN: '' },
encoding: 'utf-8',
});
expect(r.status).toBe(2);
expect(r.stderr).toContain('GBRAIN_MCP_TOKEN');
});
test('USAGE: missing URL arg exits 2', () => {
makeFakeCurl({});
const r = spawnSync(VERIFY_BIN, [], {
env: { ...process.env, PATH: `${fakeBinDir}:${process.env.PATH}`, GBRAIN_MCP_TOKEN: 'x' },
encoding: 'utf-8',
});
expect(r.status).toBe(2);
});
});

102
test/gstack-gbrain-sync.test.ts
View File

@ -108,6 +108,108 @@ describe("gstack-gbrain-sync CLI", () => {
rmSync(home, { recursive: true, force: true });
});
it("derived source ids are gbrain-valid (≤32 chars, alnum + interior hyphens, no dots) for any remote", () => {
// gbrain enforces source ids to be 1-32 lowercase alnum chars with optional interior
// hyphens. Pre-fix, the slug came from canonicalizeRemote() with only `/` and
// whitespace stripped — leaving dots from hostnames (`github.com`) and no length cap.
// For `github.com/<org>/<repo>`, the id was `gstack-code-github.com-<org>-<repo>`,
// which fails validation on both counts. This test exercises the derivation against
// controlled remotes by spawning the CLI in a temp git repo.
const cases = [
"https://github.com/radubach/platform.git", // dot in hostname, total > 32 with old slug
"git@github.com:garrytan/gstack.git", // SCP-style remote
"https://gitlab.example.com/team/proj.git", // multi-dot host, non-github
"https://github.com/some-very-long-org-name/some-very-long-repo-name.git", // forces hash-truncate
];
const VALID_ID = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
for (const remote of cases) {
const home = makeTestHome();
const gstackHome = join(home, ".gstack");
mkdirSync(gstackHome, { recursive: true });
const repo = mkdtempSync(join(tmpdir(), "gstack-source-id-repo-"));
spawnSync("git", ["init", "--quiet", "-b", "main"], { cwd: repo });
spawnSync("git", ["remote", "add", "origin", remote], { cwd: repo });
const r = spawnSync("bun", [SCRIPT, "--dry-run", "--code-only", "--quiet"], {
encoding: "utf-8",
timeout: 60000,
cwd: repo,
env: { ...process.env, HOME: home, GSTACK_HOME: gstackHome },
});
expect(r.status).toBe(0);
const m = (r.stdout || "").match(/gbrain sources add (\S+)/);
expect(m).not.toBeNull();
const id = m![1];
expect(id.length).toBeLessThanOrEqual(32);
expect(id).toMatch(VALID_ID);
expect(id.startsWith("gstack-code-")).toBe(true);
rmSync(repo, { recursive: true, force: true });
rmSync(home, { recursive: true, force: true });
}
});
it("derives a gbrain-valid source id when the cwd repo has NO origin remote", () => {
// Fallback path in deriveCodeSourceId(): no `origin` remote configured,
// so the slug comes from the repo basename. The fallback must still
// produce a gbrain-valid id (no dots, ≤32 chars, no trailing hyphen).
const home = makeTestHome();
const gstackHome = join(home, ".gstack");
mkdirSync(gstackHome, { recursive: true });
const repo = mkdtempSync(join(tmpdir(), "gstack-no-origin-"));
spawnSync("git", ["init", "--quiet", "-b", "main"], { cwd: repo });
// No `git remote add origin` — this is the no-remote case.
const r = spawnSync("bun", [SCRIPT, "--dry-run", "--code-only", "--quiet"], {
encoding: "utf-8",
timeout: 60000,
cwd: repo,
env: { ...process.env, HOME: home, GSTACK_HOME: gstackHome },
});
expect(r.status).toBe(0);
const m = (r.stdout || "").match(/gbrain sources add (\S+)/);
expect(m).not.toBeNull();
const id = m![1];
expect(id.startsWith("gstack-code-")).toBe(true);
expect(id.length).toBeLessThanOrEqual(32);
expect(id).toMatch(/^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/);
rmSync(repo, { recursive: true, force: true });
rmSync(home, { recursive: true, force: true });
});
it("derives a gbrain-valid source id when the basename sanitizes to empty", () => {
// Pathological edge: a repo whose basename is all non-alnum (e.g. "___")
// sanitizes to an empty slug. Pre-fix, constrainSourceId returned
// "gstack-code-" — invalid per the gbrain validator on the trailing
// hyphen. Fix falls back to a deterministic hash of the original input.
const home = makeTestHome();
const gstackHome = join(home, ".gstack");
mkdirSync(gstackHome, { recursive: true });
const parent = mkdtempSync(join(tmpdir(), "gstack-empty-base-"));
const repo = join(parent, "___");
mkdirSync(repo);
spawnSync("git", ["init", "--quiet", "-b", "main"], { cwd: repo });
// No `origin` remote — forces the basename-fallback path.
const r = spawnSync("bun", [SCRIPT, "--dry-run", "--code-only", "--quiet"], {
encoding: "utf-8",
timeout: 60000,
cwd: repo,
env: { ...process.env, HOME: home, GSTACK_HOME: gstackHome },
});
expect(r.status).toBe(0);
const m = (r.stdout || "").match(/gbrain sources add (\S+)/);
expect(m).not.toBeNull();
const id = m![1];
// Expect hash-only fallback shape: gstack-code-<6 hex chars>
expect(id).toMatch(/^gstack-code-[0-9a-f]{6}$/);
expect(id.length).toBeLessThanOrEqual(32);
rmSync(parent, { recursive: true, force: true });
rmSync(home, { recursive: true, force: true });
});
it("dry-run does NOT acquire the lock file (lock is for write paths only)", () => {
const home = makeTestHome();
const gstackHome = join(home, ".gstack");

143
test/gstack-memory-ingest.test.ts
View File

@ -15,7 +15,7 @@
*/
import { describe, it, expect, beforeEach, afterEach } from "bun:test";
import { mkdtempSync, writeFileSync, readFileSync, existsSync, rmSync, mkdirSync, statSync } from "fs";
import { mkdtempSync, writeFileSync, readFileSync, existsSync, rmSync, mkdirSync, statSync, chmodSync } from "fs";
import { tmpdir } from "os";
import { join } from "path";
import { spawnSync } from "child_process";
@ -265,3 +265,144 @@ describe("gstack-memory-ingest --limit", () => {
expect(r.stderr).toContain("--limit requires a positive integer");
});
});
// ── Writer regression: gbrain v0.27+ uses `put`, not `put_page` ───────────
/**
* Stand up a fake `gbrain` shim on PATH that:
* - advertises `put` in `--help` output (so gbrainAvailable() passes)
* - records `put <slug>` invocations + their stdin to a log
* - rejects `put_page` with a non-zero exit, mimicking real gbrain v0.27+
*
* If the writer ever regresses to the legacy flag-form, the bulk pass will
* report 0 writes and the assertion on `Wrote: 1` will fail loudly.
*/
function installFakeGbrain(home: string): { binDir: string; logFile: string; stdinFile: string } {
const binDir = join(home, "fake-bin");
mkdirSync(binDir, { recursive: true });
const logFile = join(home, "gbrain-calls.log");
const stdinFile = join(home, "gbrain-stdin.log");
const script = `#!/usr/bin/env bash
set -euo pipefail
LOG="${logFile}"
STDIN_LOG="${stdinFile}"
case "\${1:-}" in
--help|-h)
cat <<EOF
Usage: gbrain <command> [options]
Commands:
put <slug> Write a page (content via stdin, YAML frontmatter for metadata)
search <query> Keyword search across pages
ask <question> Hybrid semantic + keyword query
EOF
exit 0
;;
put)
if [ "\${2:-}" = "--help" ]; then
echo "Usage: gbrain put <slug>"
exit 0
fi
echo "put \${2:-}" >> "\$LOG"
{
echo "--- slug=\${2:-} ---"
cat
echo
} >> "\$STDIN_LOG"
exit 0
;;
put_page|put-page)
echo "Unknown command: \$1" >&2
exit 2
;;
*)
echo "Unknown command: \${1:-<empty>}" >&2
exit 2
;;
esac
`;
const binPath = join(binDir, "gbrain");
writeFileSync(binPath, script, "utf-8");
chmodSync(binPath, 0o755);
return { binDir, logFile, stdinFile };
}
describe("gstack-memory-ingest writer (gbrain v0.27+ `put` interface)", () => {
it("invokes `gbrain put <slug>` with stdin body, not legacy `put_page`", () => {
const home = makeTestHome();
const gstackHome = join(home, ".gstack");
mkdirSync(gstackHome, { recursive: true });
const { binDir, logFile, stdinFile } = installFakeGbrain(home);
// Single Claude Code session fixture. --include-unattributed lets it write
// even though there's no resolvable git remote in /tmp.
const session =
`{"type":"user","message":{"role":"user","content":"hi"},"timestamp":"2026-05-01T00:00:00Z","cwd":"/tmp/foo"}\n` +
`{"type":"assistant","message":{"role":"assistant","content":"hello"},"timestamp":"2026-05-01T00:00:01Z"}\n`;
writeClaudeCodeSession(home, "tmp-foo", "abc123", session);
const r = runScript(["--bulk", "--include-unattributed", "--quiet"], {
HOME: home,
GSTACK_HOME: gstackHome,
PATH: `${binDir}:${process.env.PATH || ""}`,
});
expect(r.exitCode).toBe(0);
expect(existsSync(logFile)).toBe(true);
const calls = readFileSync(logFile, "utf-8");
expect(calls).toContain("put ");
expect(calls).not.toContain("put_page");
// Body should ride stdin and carry frontmatter that gbrain can parse.
// The transcript builder prepends its own frontmatter (agent, session_id,
// etc.) but does NOT include title/type/tags — the writer injects those
// into the existing frontmatter so gbrain pages list/search/filter
// actually surface the page. Asserting all three guards against the
// exact regression that landed in v1.26.0.0 (writer ignored these fields
// entirely; pages landed empty-titled, un-typed, un-tagged).
const stdin = readFileSync(stdinFile, "utf-8");
expect(stdin).toContain("---");
expect(stdin).toMatch(/agent:\s+claude-code/);
expect(stdin).toMatch(/title:\s/);
expect(stdin).toMatch(/type:\s+transcript/);
expect(stdin).toMatch(/tags:/);
rmSync(home, { recursive: true, force: true });
});
it("fails fast when gbrain CLI is missing the `put` subcommand", () => {
const home = makeTestHome();
const gstackHome = join(home, ".gstack");
mkdirSync(gstackHome, { recursive: true });
// Fake gbrain that ONLY advertises legacy `put_page` (no `put`).
const binDir = join(home, "legacy-bin");
mkdirSync(binDir, { recursive: true });
const script = `#!/usr/bin/env bash
case "\${1:-}" in
--help|-h) echo "Commands:"; echo " put_page Write a page (legacy)"; exit 0 ;;
*) echo "Unknown command: \$1" >&2; exit 2 ;;
esac
`;
const binPath = join(binDir, "gbrain");
writeFileSync(binPath, script, "utf-8");
chmodSync(binPath, 0o755);
const session =
`{"type":"user","message":{"role":"user","content":"hi"},"timestamp":"2026-05-01T00:00:00Z","cwd":"/tmp/bar"}\n`;
writeClaudeCodeSession(home, "tmp-bar", "def456", session);
const r = runScript(["--bulk", "--include-unattributed"], {
HOME: home,
GSTACK_HOME: gstackHome,
PATH: `${binDir}:${process.env.PATH || ""}`,
});
// Bulk completes (the script is per-page tolerant), but every page
// surfaces the missing-`put` error rather than the old "Unknown command".
expect(r.stderr + r.stdout).toMatch(/missing `put` subcommand|gbrain CLI not in PATH/);
rmSync(home, { recursive: true, force: true });
});
});

25
test/helpers/touchfiles.ts
View File

@ -136,14 +136,21 @@ export const E2E_TOUCHFILES: Record<string, string[]> = {
// Gate-tier reviewCount-floor counterparts. Catch the May 2026 transcript
// bug (model wrote a plan-mode plan and ExitPlanMode'd without firing any
// review-phase AskUserQuestion). Same harness as the periodic
// finding-count tests (runPlanSkillCounting), smaller seeds, floor=1
// assertion. ~6 min wall time per test, ~25 min total for all four.
// review-phase AskUserQuestion). Uses runPlanSkillFloorCheck — minimal
// "did agent fire ANY AUQ?" observer that exits early on first non-permission
// numbered-option render. ~1-3 min typical wall time per test, ~$2-6 total.
'plan-eng-finding-floor': ['plan-eng-review/**', 'scripts/resolvers/preamble.ts', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble/generate-completion-status.ts', 'scripts/resolvers/review.ts', 'test/helpers/claude-pty-runner.ts', 'test/fixtures/forcing-finding-seeds.ts', 'test/skill-e2e-plan-eng-finding-floor.test.ts'],
'plan-ceo-finding-floor': ['plan-ceo-review/**', 'scripts/resolvers/preamble.ts', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble/generate-completion-status.ts', 'scripts/resolvers/review.ts', 'test/helpers/claude-pty-runner.ts', 'test/fixtures/forcing-finding-seeds.ts', 'test/skill-e2e-plan-ceo-finding-floor.test.ts'],
'plan-design-finding-floor': ['plan-design-review/**', 'scripts/resolvers/preamble.ts', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble/generate-completion-status.ts', 'scripts/resolvers/review.ts', 'test/helpers/claude-pty-runner.ts', 'test/fixtures/forcing-finding-seeds.ts', 'test/skill-e2e-plan-design-finding-floor.test.ts'],
'plan-devex-finding-floor': ['plan-devex-review/**', 'scripts/resolvers/preamble.ts', 'scripts/resolvers/preamble/generate-ask-user-format.ts', 'scripts/resolvers/preamble/generate-completion-status.ts', 'scripts/resolvers/review.ts', 'test/helpers/claude-pty-runner.ts', 'test/fixtures/forcing-finding-seeds.ts', 'test/skill-e2e-plan-devex-finding-floor.test.ts'],
'brain-privacy-gate': ['scripts/resolvers/preamble/generate-brain-sync-block.ts', 'scripts/resolvers/preamble.ts', 'bin/gstack-brain-sync', 'bin/gstack-brain-init', 'bin/gstack-config', 'test/helpers/agent-sdk-runner.ts'],
'brain-privacy-gate': ['scripts/resolvers/preamble/generate-brain-sync-block.ts', 'scripts/resolvers/preamble.ts', 'bin/gstack-brain-sync', 'bin/gstack-artifacts-init', 'bin/gstack-config', 'test/helpers/agent-sdk-runner.ts'],
// /setup-gbrain Path 4 (Remote MCP) — happy + bad-token end-to-end via
// Agent SDK. Gate-tier (deterministic stub server, fixed inputs); fires
// when the skill template, the verify helper, the artifacts-init helper,
// or the detect script changes.
'setup-gbrain-remote': ['setup-gbrain/SKILL.md.tmpl', 'bin/gstack-gbrain-mcp-verify', 'bin/gstack-artifacts-init', 'bin/gstack-gbrain-detect', 'test/helpers/agent-sdk-runner.ts'],
'setup-gbrain-bad-token': ['setup-gbrain/SKILL.md.tmpl', 'bin/gstack-gbrain-mcp-verify', 'test/helpers/agent-sdk-runner.ts'],
// AskUserQuestion format regression (RECOMMENDATION + Completeness: N/10)
// Fires when either template OR the two preamble resolvers change.
@ -441,6 +448,16 @@ export const E2E_TIERS: Record<string, 'gate' | 'periodic'> = {
// costs ~$0.30-$0.50 per run, not needed on every commit)
'brain-privacy-gate': 'periodic',
// /setup-gbrain Path 4 (Remote MCP) — periodic-tier. The stub HTTP
// server is deterministic but the model's interpretation of "follow
// Path 4 only" is not — assertions on which steps the model ran are
// flaky. The deterministic gate-tier coverage for Path 4 lives in
// test/setup-gbrain-path4-structure.test.ts (free, <200ms). These
// E2E tests stay available for on-demand verification of the live
// model's behavior against a stub MCP server.
'setup-gbrain-remote': 'periodic',
'setup-gbrain-bad-token': 'periodic',
// AskUserQuestion format regression — periodic (Opus 4.7 non-deterministic benchmark)
'plan-ceo-review-format-mode': 'periodic',
'plan-ceo-review-format-approach': 'periodic',

290
test/migrations-v1.27.0.0.test.ts Normal file
View File

@ -0,0 +1,290 @@
/**
* v1.27.0.0 migration — gstack-brain → gstack-artifacts rename.
*
* Exercises the journaled migration in a temp HOME with mocked gh / git /
* gbrain. Tests the four host-mode cases (GitHub, GitLab, remote-MCP,
* nothing-to-migrate) plus interruption resume.
*/
import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import { spawnSync } from 'child_process';
const ROOT = path.resolve(import.meta.dir, '..');
const MIGRATION = path.join(ROOT, 'gstack-upgrade', 'migrations', 'v1.27.0.0.sh');
let tmpHome: string;
let fakeBinDir: string;
function makeFakeGh(opts: { authStatus?: 'ok' | 'fail'; renameSucceeds?: boolean; alreadyRenamed?: boolean } = {}) {
const authStatus = opts.authStatus ?? 'ok';
const renameSucceeds = opts.renameSucceeds ?? true;
const alreadyRenamed = opts.alreadyRenamed ?? false;
const callLog = path.join(fakeBinDir, 'gh-calls.log');
const script = `#!/bin/bash
echo "gh $@" >> "${callLog}"
case "$1" in
auth) ${authStatus === 'ok' ? 'exit 0' : 'exit 1'} ;;
repo)
shift
case "$1" in
view)
# gh repo view <name>
shift
${alreadyRenamed ? `if echo "$@" | grep -q gstack-artifacts; then exit 0; else exit 1; fi` : `exit 1`}
;;
rename) ${renameSucceeds ? 'exit 0' : 'exit 1'} ;;
edit) ${renameSucceeds ? 'exit 0' : 'exit 1'} ;;
esac
;;
esac
exit 0
`;
fs.writeFileSync(path.join(fakeBinDir, 'gh'), script, { mode: 0o755 });
}
function makeFakeGbrain(opts: { hasOldSource?: boolean; addSucceeds?: boolean; removeSucceeds?: boolean } = {}) {
const hasOld = opts.hasOldSource ?? true;
const addOk = opts.addSucceeds ?? true;
const rmOk = opts.removeSucceeds ?? true;
const callLog = path.join(fakeBinDir, 'gbrain-calls.log');
const script = `#!/bin/bash
echo "gbrain $@" >> "${callLog}"
case "$1 $2" in
"sources list")
${hasOld ? `echo "gstack-brain-testuser ~/.gstack-brain-worktree"` : 'true'}
exit 0
;;
"sources add") ${addOk ? 'exit 0' : 'exit 1'} ;;
"sources remove") ${rmOk ? 'exit 0' : 'exit 1'} ;;
esac
exit 0
`;
fs.writeFileSync(path.join(fakeBinDir, 'gbrain'), script, { mode: 0o755 });
}
function run(extraEnv: Record<string, string> = {}, input = ''): { code: number; stdout: string; stderr: string } {
const r = spawnSync(MIGRATION, [], {
env: {
PATH: `${fakeBinDir}:${path.join(ROOT, 'bin')}:/usr/bin:/bin:/opt/homebrew/bin`,
HOME: tmpHome,
USER: 'testuser',
// Disable interactive prompt: empty stdin = treat as non-interactive.
...extraEnv,
},
encoding: 'utf-8',
input,
cwd: tmpHome,
});
return { code: r.status ?? -1, stdout: r.stdout || '', stderr: r.stderr || '' };
}
beforeEach(() => {
tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'mig-v1.27-'));
fakeBinDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mig-v1.27-fake-'));
fs.mkdirSync(path.join(tmpHome, '.gstack'), { recursive: true });
});
afterEach(() => {
fs.rmSync(tmpHome, { recursive: true, force: true });
fs.rmSync(fakeBinDir, { recursive: true, force: true });
});
describe('v1.27.0.0 migration — nothing to migrate', () => {
test('no legacy state → exits 0, writes done touchfile, no journal', () => {
// Fresh HOME: no brain-remote.txt, no .gstack/.git
const r = run();
expect(r.code).toBe(0);
expect(r.stderr).toContain('nothing to migrate');
expect(fs.existsSync(path.join(tmpHome, '.gstack/.migrations/v1.27.0.0.done'))).toBe(true);
expect(fs.existsSync(path.join(tmpHome, '.gstack/.migrations/v1.27.0.0.journal'))).toBe(false);
});
test('done touchfile present → exits 0 silently (no re-prompt)', () => {
fs.mkdirSync(path.join(tmpHome, '.gstack/.migrations'), { recursive: true });
fs.writeFileSync(path.join(tmpHome, '.gstack/.migrations/v1.27.0.0.done'), '');
const r = run();
expect(r.code).toBe(0);
expect(r.stderr).toBe('');
});
test('skipped-by-user touchfile → exits 0 silently', () => {
fs.mkdirSync(path.join(tmpHome, '.gstack/.migrations'), { recursive: true });
fs.writeFileSync(path.join(tmpHome, '.gstack/.migrations/v1.27.0.0.skipped-by-user'), '');
fs.writeFileSync(path.join(tmpHome, '.gstack-brain-remote.txt'), 'https://github.com/x/gstack-brain-testuser');
const r = run();
expect(r.code).toBe(0);
expect(r.stderr).toBe('');
});
});
describe('v1.27.0.0 migration — GitHub host (non-interactive)', () => {
beforeEach(() => {
fs.writeFileSync(
path.join(tmpHome, '.gstack-brain-remote.txt'),
'https://github.com/testuser/gstack-brain-testuser\n'
);
fs.writeFileSync(
path.join(tmpHome, '.gstack/config.yaml'),
'gbrain_sync_mode: full\ngbrain_sync_mode_prompted: true\n'
);
makeFakeGh({});
});
test('renames repo, mvs remote.txt, rewrites config key, writes done', () => {
const r = run();
expect(r.code).toBe(0);
// gh rename was called (or edit fallback).
const ghLog = fs.readFileSync(path.join(fakeBinDir, 'gh-calls.log'), 'utf-8');
expect(ghLog).toMatch(/gh repo (rename|edit)/);
// Old remote.txt is gone, new one exists with rewritten URL.
expect(fs.existsSync(path.join(tmpHome, '.gstack-brain-remote.txt'))).toBe(false);
const newUrl = fs.readFileSync(path.join(tmpHome, '.gstack-artifacts-remote.txt'), 'utf-8').trim();
expect(newUrl).toBe('https://github.com/testuser/gstack-artifacts-testuser');
// Config key renamed.
const cfg = fs.readFileSync(path.join(tmpHome, '.gstack/config.yaml'), 'utf-8');
expect(cfg).toContain('artifacts_sync_mode: full');
expect(cfg).toContain('artifacts_sync_mode_prompted: true');
expect(cfg).not.toContain('gbrain_sync_mode');
// Done touchfile written, journal cleared.
expect(fs.existsSync(path.join(tmpHome, '.gstack/.migrations/v1.27.0.0.done'))).toBe(true);
expect(fs.existsSync(path.join(tmpHome, '.gstack/.migrations/v1.27.0.0.journal'))).toBe(false);
});
test('idempotent: re-run after success is a no-op', () => {
run();
const r2 = run();
expect(r2.code).toBe(0);
expect(r2.stderr).toBe('');
});
test('repo already renamed (gh repo view succeeds with new name) → no rename attempt', () => {
makeFakeGh({ alreadyRenamed: true });
const r = run();
expect(r.code).toBe(0);
expect(r.stderr).toContain('already named');
});
});
describe('v1.27.0.0 migration — interruption resume', () => {
beforeEach(() => {
fs.writeFileSync(
path.join(tmpHome, '.gstack-brain-remote.txt'),
'https://github.com/testuser/gstack-brain-testuser\n'
);
makeFakeGh({});
});
test('partial journal: skips already-done steps', () => {
// Pre-plant journal with steps 1+2 marked done.
const migDir = path.join(tmpHome, '.gstack/.migrations');
fs.mkdirSync(migDir, { recursive: true });
fs.writeFileSync(path.join(migDir, 'v1.27.0.0.journal'), 'gh_repo_renamed\nremote_txt_renamed\n');
const r = run();
expect(r.code).toBe(0);
// gh should NOT have been called (step 1 already done).
if (fs.existsSync(path.join(fakeBinDir, 'gh-calls.log'))) {
const ghLog = fs.readFileSync(path.join(fakeBinDir, 'gh-calls.log'), 'utf-8');
expect(ghLog).not.toMatch(/gh repo rename/);
expect(ghLog).not.toMatch(/gh repo edit/);
}
// Final state: done touchfile written, journal removed.
expect(fs.existsSync(path.join(migDir, 'v1.27.0.0.done'))).toBe(true);
expect(fs.existsSync(path.join(migDir, 'v1.27.0.0.journal'))).toBe(false);
});
});
describe('v1.27.0.0 migration — remote-MCP mode (step 5 prints, never executes)', () => {
test('with mcpServers.gbrain.type=url → step 5 prints commands, doesn\'t call gbrain', () => {
fs.writeFileSync(
path.join(tmpHome, '.gstack-brain-remote.txt'),
'https://github.com/testuser/gstack-brain-testuser\n'
);
fs.writeFileSync(
path.join(tmpHome, '.claude.json'),
JSON.stringify({ mcpServers: { gbrain: { type: 'url', url: 'https://example.com/mcp' } } })
);
makeFakeGh({});
makeFakeGbrain({}); // installed, but should NOT be called for sources commands
const r = run();
expect(r.code).toBe(0);
expect(r.stderr).toContain('Remote MCP detected');
expect(r.stderr).toContain('Send this to your brain admin');
expect(r.stderr).toContain('gbrain sources add');
// Confirm the script did NOT call `gbrain sources add/remove` locally.
if (fs.existsSync(path.join(fakeBinDir, 'gbrain-calls.log'))) {
const log = fs.readFileSync(path.join(fakeBinDir, 'gbrain-calls.log'), 'utf-8');
expect(log).not.toMatch(/gbrain sources add/);
expect(log).not.toMatch(/gbrain sources remove/);
}
});
});
describe('v1.27.0.0 migration — local CLI sources swap (codex Finding #6 ordering)', () => {
test('add-new before remove-old (verify by call order in log)', () => {
fs.writeFileSync(
path.join(tmpHome, '.gstack-brain-remote.txt'),
'https://github.com/testuser/gstack-brain-testuser\n'
);
fs.mkdirSync(path.join(tmpHome, '.gstack/.git'), { recursive: true }); // brain repo present
makeFakeGh({});
makeFakeGbrain({ hasOldSource: true });
const r = run();
expect(r.code).toBe(0);
const log = fs.readFileSync(path.join(fakeBinDir, 'gbrain-calls.log'), 'utf-8');
const addIdx = log.indexOf('gbrain sources add gstack-artifacts-testuser');
const removeIdx = log.indexOf('gbrain sources remove gstack-brain-testuser');
expect(addIdx).toBeGreaterThan(-1);
expect(removeIdx).toBeGreaterThan(-1);
// Critical: add must come BEFORE remove (no downtime window).
expect(addIdx).toBeLessThan(removeIdx);
});
test('add fails → old source stays registered (no silent loss)', () => {
fs.writeFileSync(
path.join(tmpHome, '.gstack-brain-remote.txt'),
'https://github.com/testuser/gstack-brain-testuser\n'
);
fs.mkdirSync(path.join(tmpHome, '.gstack/.git'), { recursive: true });
makeFakeGh({});
makeFakeGbrain({ addSucceeds: false });
const r = run();
expect(r.code).toBe(0); // step 5 warns, doesn't fail the migration
expect(r.stderr).toContain('failed to add');
const log = fs.readFileSync(path.join(fakeBinDir, 'gbrain-calls.log'), 'utf-8');
// Remove was NOT called because add failed.
expect(log).not.toMatch(/gbrain sources remove/);
});
});
describe('v1.27.0.0 migration — CLAUDE.md block field rewrite', () => {
test('rewrites "- Memory sync:" → "- Artifacts sync:" in CLAUDE.md', () => {
fs.writeFileSync(
path.join(tmpHome, '.gstack-brain-remote.txt'),
'https://github.com/testuser/gstack-brain-testuser\n'
);
const claudeMd = `# Project notes
## GBrain Configuration (configured by /setup-gbrain)
- Engine: pglite
- Memory sync: full
- Current repo policy: read-write
`;
fs.writeFileSync(path.join(tmpHome, 'CLAUDE.md'), claudeMd);
makeFakeGh({});
const r = run();
expect(r.code).toBe(0);
const updated = fs.readFileSync(path.join(tmpHome, 'CLAUDE.md'), 'utf-8');
expect(updated).toContain('- Artifacts sync: full');
expect(updated).not.toContain('- Memory sync:');
});
});

120
test/no-stale-gstack-brain-refs.test.ts Normal file
View File

@ -0,0 +1,120 @@
/**
* Regression: no stale `gstack-brain-init`, `gbrain_sync_mode`, or
* `~/.gstack-brain-remote.txt` references survive the v1.27.0.0 rename.
*
* Per codex Findings #1 + #8 + #9: the rename's blast radius is wider than
* the obvious bin/ + scripts/ surface. This test grep-scans the broader
* tree (bin, scripts, *.tmpl, generated *.md, test/, docs/) for the
* deprecated identifiers and fails CI if any callers were missed.
*
* Allowlist: the migration script (`gstack-upgrade/migrations/v1.27.0.0.sh`)
* legitimately references the old names — it's the rename actor itself.
* Old migration scripts (v1.17.0.0.sh and similar) reference the old names
* for their own historical context and are also allowlisted.
*
* The test is mechanical: if you find yourself adding a non-historical
* file to the allowlist, you probably need to actually fix the rename
* instead.
*/
import { describe, test, expect } from 'bun:test';
import * as fs from 'fs';
import * as path from 'path';
import { spawnSync } from 'child_process';
const ROOT = path.resolve(import.meta.dir, '..');
const ALLOWLIST = [
// The migration script that performs the rename. Self-references are expected.
'gstack-upgrade/migrations/v1.27.0.0.sh',
// Older migration scripts — historical references; these document past state.
'gstack-upgrade/migrations/v1.17.0.0.sh',
// The migration test itself — it asserts on the migration's behavior.
'test/migrations-v1.27.0.0.test.ts',
// The test for the v1.17.0.0 historical migration.
'test/gstack-upgrade-migration-v1_17_0_0.test.ts',
// CHANGELOG entries describe historical state by their nature.
'CHANGELOG.md',
// TODOS may reference past or future states by name.
'TODOS.md',
// The plan file for v1.27.0.0 documents why we're renaming.
'.context/plans/setup-gbrain-remote-mcp-rename-brain-artifacts.md',
// The bin/gstack-config comment explicitly preserves the rename note.
'bin/gstack-config',
// Detect script's "renamed in v1.27.0.0" comment + brain-remote-fallback path.
'bin/gstack-gbrain-detect',
// brain-restore + source-wireup keep the old file as a migration-window fallback
// (read both, prefer artifacts). brain-uninstall has the same fallback.
'bin/gstack-brain-restore',
'bin/gstack-gbrain-source-wireup',
'bin/gstack-brain-uninstall',
// The preamble resolver reads the legacy file as a fallback during the
// migration window — same pattern.
'scripts/resolvers/preamble/generate-brain-sync-block.ts',
// gstack-upgrade.test.ts may exercise old migration behavior.
'test/gstack-upgrade.test.ts',
// This test itself references the patterns to grep for.
'test/no-stale-gstack-brain-refs.test.ts',
// memory.md documents the rename context.
'setup-gbrain/memory.md',
// The new init script's header comment intentionally cites the rename.
'bin/gstack-artifacts-init',
// The replacement test mirrors the pattern of the old test (lineage note).
'test/gstack-artifacts-init.test.ts',
// The post-rename-doc-regen test references the patterns it greps for.
'test/post-rename-doc-regen.test.ts',
// The Path 4 structural lint references some legacy names in comments.
'test/setup-gbrain-path4-structure.test.ts',
// Generated docs that include the preamble bash (which has the fallback).
// We grep template sources, not generated output, by limiting scan paths.
];
const FORBIDDEN_PATTERNS = [
'gstack-brain-init',
'gbrain_sync_mode',
];
const SCAN_PATHS = [
'bin/',
'scripts/',
'setup-gbrain/SKILL.md.tmpl',
'sync-gbrain/SKILL.md.tmpl',
'health/SKILL.md.tmpl',
'plan-eng-review/SKILL.md.tmpl',
'plan-ceo-review/SKILL.md.tmpl',
'review/SKILL.md.tmpl',
'ship/SKILL.md.tmpl',
'test/',
];
function grepRefs(pattern: string): string[] {
const args = ['-rn', '--', pattern, ...SCAN_PATHS.map((p) => path.join(ROOT, p))];
const r = spawnSync('grep', args, { encoding: 'utf-8' });
// grep exits 1 when no matches — that's fine for our purposes.
const lines = (r.stdout || '').split('\n').filter((l) => l.trim().length > 0);
return lines
.map((line) => {
// Strip ROOT prefix to get repo-relative path.
const colon = line.indexOf(':');
const file = line.slice(0, colon);
return path.relative(ROOT, file);
})
.filter((file) => !ALLOWLIST.includes(file))
// Filter out any file that's inside a directory we don't actually scan.
.filter((file) => !file.startsWith('node_modules/') && !file.startsWith('.git/'));
}
describe('no stale gstack-brain refs (v1.27.0.0 rename)', () => {
for (const pattern of FORBIDDEN_PATTERNS) {
test(`no non-allowlisted references to "${pattern}"`, () => {
const offenders = [...new Set(grepRefs(pattern))];
if (offenders.length > 0) {
console.error(`Found stale "${pattern}" references in:\n${offenders.map((f) => ` - ${f}`).join('\n')}`);
console.error(
`If a file is intentionally referencing the old name (migration, historical doc, fallback path), add it to ALLOWLIST in this test.`
);
}
expect(offenders).toEqual([]);
});
}
});

74
test/post-rename-doc-regen.test.ts Normal file
View File

@ -0,0 +1,74 @@
// Post-rename doc-regen regression: after `bun run gen:skill-docs`, no
// `gstack-brain-init` or `gbrain_sync_mode` strings appear in any of the
// generated SKILL.md files (the cross-product blind spot codex
// Finding #12 flagged).
//
// The check runs against the canonical claude-host output already on
// disk. We don't shell out to gen-skill-docs again; the existing
// freshness check in gen-skill-docs.test.ts covers that. This test
// just verifies the rename actually propagated to the generated
// artifacts that users see.
import { describe, test, expect } from 'bun:test';
import * as fs from 'fs';
import * as path from 'path';
const ROOT = path.resolve(import.meta.dir, '..');
const FORBIDDEN_PATTERNS = [
// Bare identifier — should NEVER appear in generated docs (if it does,
// a template still has the old call site).
/^.*\bgstack-brain-init\b.*$/m,
/^.*\bgbrain_sync_mode\b.*$/m,
];
// Per the preamble resolver: generated docs DO contain the
// "~/.gstack-brain-remote.txt" string in the migration-window fallback. We
// don't grep for that — it's intentional. We grep for the call-site
// identifiers only.
function findSkillMdFiles(): string[] {
const skillMd = path.join(ROOT, 'SKILL.md');
const files: string[] = [skillMd];
// Top-level skill directories with their own SKILL.md.
const entries = fs.readdirSync(ROOT, { withFileTypes: true });
for (const e of entries) {
if (e.isDirectory() && !e.name.startsWith('.') && !['node_modules', 'test'].includes(e.name)) {
const inner = path.join(ROOT, e.name, 'SKILL.md');
if (fs.existsSync(inner)) files.push(inner);
}
}
return files;
}
describe('post-rename doc-regen regression (codex Finding #12)', () => {
test('no generated SKILL.md contains "gstack-brain-init"', () => {
const offenders: string[] = [];
for (const file of findSkillMdFiles()) {
const content = fs.readFileSync(file, 'utf-8');
const m = content.match(/^.*\bgstack-brain-init\b.*$/m);
if (m) offenders.push(`${path.relative(ROOT, file)}: ${m[0].slice(0, 100)}`);
}
if (offenders.length > 0) {
console.error(`Stale "gstack-brain-init" in generated SKILL.md files:\n${offenders.map((o) => ' ' + o).join('\n')}`);
}
expect(offenders).toEqual([]);
});
test('no generated SKILL.md contains "gbrain_sync_mode"', () => {
const offenders: string[] = [];
for (const file of findSkillMdFiles()) {
const content = fs.readFileSync(file, 'utf-8');
const m = content.match(/^.*\bgbrain_sync_mode\b.*$/m);
if (m) offenders.push(`${path.relative(ROOT, file)}: ${m[0].slice(0, 100)}`);
}
if (offenders.length > 0) {
console.error(`Stale "gbrain_sync_mode" in generated SKILL.md files:\n${offenders.map((o) => ' ' + o).join('\n')}`);
}
expect(offenders).toEqual([]);
});
test('top-level SKILL.md exists and is regenerated', () => {
expect(fs.existsSync(path.join(ROOT, 'SKILL.md'))).toBe(true);
});
});

133
test/setup-gbrain-path4-structure.test.ts Normal file
View File

@ -0,0 +1,133 @@
// setup-gbrain Path 4 structural lint.
//
// Verifies the SKILL.md.tmpl has the prose contract that Path 4 (Remote MCP)
// depends on: STOP gates after verify failures, never-write-token rules,
// mode-aware CLAUDE.md block, idempotent re-run path.
//
// Why a structural test instead of a full Agent SDK E2E:
// - Side effects (claude.json mutation, MCP registration) are covered
// by unit tests for gstack-gbrain-mcp-verify and gstack-artifacts-init.
// - The structural prose is the source of regressions for AUQ pacing
// (the failure mode the gstack repo has tracked since v1.26.x:
// "wrote_findings_before_asking"). A grep-based regression on the
// template prose is fast (<200ms), free, and catches the same drift
// as the paid E2E without spending tokens.
// - The full Agent SDK E2E remains the right tool for end-to-end
// pacing eval; this is the gate-tier check that catches the failure
// class deterministically.
import { describe, test, expect } from 'bun:test';
import * as fs from 'fs';
import * as path from 'path';
const ROOT = path.resolve(import.meta.dir, '..');
const TMPL = path.join(ROOT, 'setup-gbrain', 'SKILL.md.tmpl');
const tmpl = fs.readFileSync(TMPL, 'utf-8');
describe('setup-gbrain Path 4 (Remote MCP) — structural contract', () => {
test('Step 2 lists Path 4 as one of the path options', () => {
// "4 — Remote gbrain MCP" with em-dash (—, U+2014 — one codepoint).
expect(tmpl).toMatch(/\*\*4 . Remote gbrain MCP/);
});
test('Step 4 has a Path 4 sub-section', () => {
expect(tmpl).toMatch(/### Path 4 \(Remote gbrain MCP/);
});
test('Step 4 collects the bearer via read_secret_to_env, never argv', () => {
// The secret-read helper is the canonical token-capture pattern.
// Without it, tokens land in shell history.
expect(tmpl).toContain('read_secret_to_env GBRAIN_MCP_TOKEN');
});
test('Step 4c invokes gstack-gbrain-mcp-verify and STOPs on failure', () => {
expect(tmpl).toContain('gstack-gbrain-mcp-verify');
// The STOP rule is what prevents partial registration after auth fail.
const path4Section = tmpl.split('### Path 4')[1] || '';
expect(path4Section).toMatch(/STOP/);
});
test('Step 4d explicitly skips Steps 3, 4 (other paths), 5, 7.5 in remote mode', () => {
expect(tmpl).toMatch(/4d.*[Ss]kip Steps? 3, 4.*5.*7\.5/s);
});
test('Step 5a has a Path 4 branch with claude mcp add --transport http', () => {
expect(tmpl).toMatch(/Path 4 \(Remote MCP/);
expect(tmpl).toMatch(/claude mcp add --scope user --transport http gbrain/);
expect(tmpl).toContain('Authorization: Bearer $GBRAIN_MCP_TOKEN');
// Token must be unset after registration so it doesn't linger in env.
expect(tmpl).toMatch(/unset GBRAIN_MCP_TOKEN/);
});
test('Step 5a removes any prior gbrain registration before adding the new one', () => {
// Otherwise local-stdio + remote-http coexist, which breaks routing.
expect(tmpl).toMatch(/claude mcp remove gbrain/);
});
test('Step 7 calls gstack-artifacts-init with --url-form-supported flag', () => {
expect(tmpl).toMatch(/gstack-artifacts-init.*--url-form-supported/);
});
test('Step 8 CLAUDE.md block branches on mode', () => {
// The remote-http block has Mode: remote-http; local-stdio block has Engine:.
expect(tmpl).toMatch(/### Path 4 \(Remote MCP\)/);
expect(tmpl).toMatch(/Mode: remote-http/);
expect(tmpl).toMatch(/Mode: local-stdio/);
});
test('Step 8 explicitly says the bearer is never written to CLAUDE.md', () => {
// Token-leak regression guard. CLAUDE.md is committed in many projects.
expect(tmpl).toMatch(/bearer token is \*\*never\*\* written to CLAUDE\.md/);
});
test('Step 9 smoke test on Path 4 prints a placeholder, never the real token', () => {
// Don't paste the token into the curl example the user might share.
expect(tmpl).toMatch(/<YOUR_TOKEN>/);
});
test('Step 10 verdict block has a remote-http variant separate from local-stdio', () => {
expect(tmpl).toMatch(/### Path 4 \(Remote MCP\)/);
expect(tmpl).toMatch(/mode: remote-http/);
expect(tmpl).toMatch(/N\/A.*remote mode/);
});
test('idempotency: re-running with gbrain_mcp_mode=remote-http skips Step 2', () => {
// Re-run path stays graceful; no double-registration.
expect(tmpl).toMatch(/gbrain_mcp_mode=remote-http/);
});
test('Step 5 (local doctor) explicitly skips on Path 4', () => {
expect(tmpl).toMatch(/SKIP entirely on Path 4 \(Remote MCP\)/);
});
test('Step 7.5 (transcript ingest) explicitly skips on Path 4', () => {
// Transcript ingest needs local gbrain CLI which Path 4 doesn't install.
const matches = tmpl.match(/SKIP entirely on Path 4 \(Remote MCP\)/g);
expect(matches?.length).toBeGreaterThanOrEqual(2);
});
});
describe('setup-gbrain Path 4 — token security regressions', () => {
test('the template never inlines a real-shaped bearer string', () => {
// We never want a literal "gbrain_<hex>" token to appear in the
// template — placeholders only. This catches the failure mode where
// someone copies a real token into the template by accident.
const realTokenShape = /gbrain_[a-f0-9]{40,}/;
expect(tmpl).not.toMatch(realTokenShape);
});
test('Path 4 always uses env-var $GBRAIN_MCP_TOKEN, never inline strings', () => {
// Find every reference to the bearer header in Path 4 and verify it's
// either an env-var expansion or an explicit placeholder. Allow:
// - $GBRAIN_MCP_TOKEN (env-var expansion)
// - <bearer>, <YOUR_TOKEN>, <TOKEN> (placeholder)
// - "..." (rest-of-doc-text continuation; a doc note showing how
// `claude mcp add --header` shapes its argv).
const path4Section = tmpl.match(/### Path 4 \(Remote MCP[\s\S]*?(?=###|## )/g)?.join('') || '';
const bearerLines = path4Section.match(/Bearer\s+\S+/g) || [];
for (const line of bearerLines) {
expect(line).toMatch(/Bearer (\$GBRAIN_MCP_TOKEN|<bearer>|<YOUR_TOKEN>|<TOKEN>|\.\.\."?)/);
}
});
});

10
test/skill-e2e-brain-privacy-gate.test.ts
View File

@ -4,7 +4,7 @@
* The gbrain-sync preamble block instructs the model to fire a one-time
* AskUserQuestion when:
* - `BRAIN_SYNC: off` in the preamble echo (sync mode not on)
* - config `gbrain_sync_mode_prompted` is "false"
* - config `artifacts_sync_mode_prompted` is "false"
* - gbrain is detected on the host (binary on PATH or `gbrain doctor`
* --fast --json succeeds)
*
@ -31,14 +31,14 @@ const describeE2E = shouldRun ? describe : describe.skip;
describeE2E('gbrain-sync privacy gate fires once via preamble', () => {
test('gstack skill preamble fires the 3-option AskUserQuestion when gbrain is detected', async () => {
// Stage a fresh GSTACK_HOME with gbrain_sync_mode_prompted=false.
// Stage a fresh GSTACK_HOME with artifacts_sync_mode_prompted=false.
const gstackHome = fs.mkdtempSync(path.join(os.tmpdir(), 'privacy-gate-gstack-'));
const fakeBinDir = fs.mkdtempSync(path.join(os.tmpdir(), 'privacy-gate-bin-'));
// Seed the config so the gate's condition passes.
fs.writeFileSync(
path.join(gstackHome, 'config.yaml'),
'gbrain_sync_mode: off\ngbrain_sync_mode_prompted: false\n',
'artifacts_sync_mode: off\nartifacts_sync_mode_prompted: false\n',
{ mode: 0o600 }
);
@ -151,14 +151,14 @@ describeE2E('gbrain-sync privacy gate fires once via preamble', () => {
}
}, 180_000);
test('privacy gate does NOT fire when gbrain_sync_mode_prompted is already true', async () => {
test('privacy gate does NOT fire when artifacts_sync_mode_prompted is already true', async () => {
// Same staging, but prompted=true this time. Gate should be silent.
const gstackHome = fs.mkdtempSync(path.join(os.tmpdir(), 'privacy-gate-off-'));
const fakeBinDir = fs.mkdtempSync(path.join(os.tmpdir(), 'privacy-gate-off-bin-'));
fs.writeFileSync(
path.join(gstackHome, 'config.yaml'),
'gbrain_sync_mode: off\ngbrain_sync_mode_prompted: true\n',
'artifacts_sync_mode: off\nartifacts_sync_mode_prompted: true\n',
{ mode: 0o600 }
);

150
test/skill-e2e-setup-gbrain-bad-token.test.ts Normal file
View File

@ -0,0 +1,150 @@
// E2E: /setup-gbrain Path 4 with a bad bearer token via Agent SDK.
//
// Drives the skill against a stub HTTP MCP server that returns 401
// (auth-shape body). Asserts that the AUTH classifier hint shows up
// AND no MCP registration happens (no claude mcp add --transport http
// in the call log; no half-written CLAUDE.md block). This is the
// regression guard for the "verify failed → STOP" gate.
//
// Cost: ~$0.30-$0.50 per run. Gate-tier (EVALS=1 EVALS_TIER=gate).
import { describe, test, expect } from 'bun:test';
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import * as http from 'http';
import { runAgentSdkTest, passThroughNonAskUserQuestion, resolveClaudeBinary } from './helpers/agent-sdk-runner';
// Periodic-tier (companion to skill-e2e-setup-gbrain-remote.test.ts).
// Deterministic gate coverage lives in setup-gbrain-path4-structure.test.ts.
const shouldRun = !!process.env.EVALS && process.env.EVALS_TIER === 'periodic';
const describeE2E = shouldRun ? describe : describe.skip;
function startStub401(): Promise<{ url: string; close: () => Promise<void> }> {
return new Promise((resolve) => {
const server = http.createServer((req, res) => {
let body = '';
req.on('data', (c) => (body += c));
req.on('end', () => {
res.statusCode = 401;
res.setHeader('Content-Type', 'application/json');
res.end(
JSON.stringify({ error: 'unauthorized', error_description: 'invalid or expired auth token' })
);
});
});
server.listen(0, '127.0.0.1', () => {
const addr = server.address();
if (!addr || typeof addr === 'string') throw new Error('no address');
resolve({
url: `http://127.0.0.1:${addr.port}/mcp`,
close: () => new Promise((r) => server.close(() => r())),
});
});
});
}
function makeFakeClaude(fakeBinDir: string): string {
const callLog = path.join(fakeBinDir, 'claude-calls.log');
const script = `#!/bin/bash
echo "claude $@" >> "${callLog}"
case "$1 $2" in
"mcp add") exit 0 ;;
"mcp list") echo "no gbrain" ; exit 0 ;;
"mcp remove") exit 0 ;;
"mcp get") exit 1 ;;
esac
exit 0
`;
fs.writeFileSync(path.join(fakeBinDir, 'claude'), script, { mode: 0o755 });
return callLog;
}
describeE2E('/setup-gbrain Path 4 — bad token STOPs cleanly', () => {
test('AUTH classifier fires, no MCP registration, no CLAUDE.md mutation', async () => {
const stubServer = await startStub401();
const gstackHome = fs.mkdtempSync(path.join(os.tmpdir(), 'setup-gbrain-bad-'));
const fakeBinDir = fs.mkdtempSync(path.join(os.tmpdir(), 'setup-gbrain-bad-bin-'));
const callLog = makeFakeClaude(fakeBinDir);
const ORIGINAL_CLAUDE_MD = '# Test project\n\nSome existing content here.\n';
fs.writeFileSync(path.join(gstackHome, 'CLAUDE.md'), ORIGINAL_CLAUDE_MD);
const BAD_TOKEN = 'gbrain_BAD_TOKEN_67890_DELIBERATELY_INVALID';
const askUserQuestions: Array<{ input: Record<string, unknown> }> = [];
const binary = resolveClaudeBinary();
const orig = {
gstackHome: process.env.GSTACK_HOME,
pathEnv: process.env.PATH,
mcpToken: process.env.GBRAIN_MCP_TOKEN,
};
process.env.GSTACK_HOME = gstackHome;
process.env.PATH = `${fakeBinDir}:${path.join(path.resolve(import.meta.dir, '..'), 'bin')}:${process.env.PATH ?? '/usr/bin:/bin:/opt/homebrew/bin'}`;
process.env.GBRAIN_MCP_TOKEN = BAD_TOKEN;
let modelTextOutput = '';
try {
const skillPath = path.resolve(import.meta.dir, '..', 'setup-gbrain', 'SKILL.md');
const result = await runAgentSdkTest({
systemPrompt: { type: 'preset', preset: 'claude_code' },
userPrompt:
`Read the skill file at ${skillPath} and follow Path 4 (Remote MCP) only. ` +
`Use this MCP URL: ${stubServer.url}. ` +
`The bearer token is already in the GBRAIN_MCP_TOKEN env var. ` +
`If verify fails (Step 4c), follow the skill's STOP rule — surface the error and stop. ` +
`Do NOT register the MCP if verify failed. ` +
`Do NOT modify CLAUDE.md if verify failed.`,
workingDirectory: gstackHome,
maxTurns: 15,
allowedTools: ['Read', 'Grep', 'Glob', 'Bash', 'Write', 'Edit'],
...(binary ? { pathToClaudeCodeExecutable: binary } : {}),
canUseTool: async (toolName, input) => {
if (toolName === 'AskUserQuestion') {
askUserQuestions.push({ input });
const q = (input.questions as Array<{
question: string;
options: Array<{ label: string }>;
}>)[0];
const decline = q.options.find((o) => /skip|decline|no/i.test(o.label)) ?? q.options[0]!;
return {
behavior: 'allow',
updatedInput: { questions: input.questions, answers: { [q.question]: decline.label } },
};
}
return passThroughNonAskUserQuestion(toolName, input);
},
});
modelTextOutput = JSON.stringify(result);
// Assertion 1: the AUTH classifier hint surfaced somewhere in the run.
// The verify helper outputs `"error_class": "AUTH"` and the hint
// "rotate token on the brain host" — at least one should be visible.
const hintShown =
/error_class.*AUTH/i.test(modelTextOutput) ||
/rotate token/i.test(modelTextOutput) ||
/AUTH.*HTTP 401/i.test(modelTextOutput);
expect(hintShown).toBe(true);
// Assertion 2: claude mcp add was NEVER called (verify failed → STOP).
const calls = fs.existsSync(callLog) ? fs.readFileSync(callLog, 'utf-8') : '';
expect(calls).not.toMatch(/mcp add.*--transport http/);
// Assertion 3: CLAUDE.md is unchanged (no half-written block).
const finalClaudeMd = fs.readFileSync(path.join(gstackHome, 'CLAUDE.md'), 'utf-8');
expect(finalClaudeMd).toBe(ORIGINAL_CLAUDE_MD);
// Assertion 4: the bad token never leaked to CLAUDE.md.
expect(finalClaudeMd).not.toContain(BAD_TOKEN);
} finally {
if (orig.gstackHome === undefined) delete process.env.GSTACK_HOME; else process.env.GSTACK_HOME = orig.gstackHome;
if (orig.pathEnv === undefined) delete process.env.PATH; else process.env.PATH = orig.pathEnv;
if (orig.mcpToken === undefined) delete process.env.GBRAIN_MCP_TOKEN; else process.env.GBRAIN_MCP_TOKEN = orig.mcpToken;
await stubServer.close();
fs.rmSync(gstackHome, { recursive: true, force: true });
fs.rmSync(fakeBinDir, { recursive: true, force: true });
}
}, 240_000);
});

223
test/skill-e2e-setup-gbrain-remote.test.ts Normal file
View File

@ -0,0 +1,223 @@
// E2E: /setup-gbrain Path 4 (Remote MCP) happy path via Agent SDK.
//
// Drives the skill against a stub HTTP MCP server and a stubbed `claude`
// binary that records `claude mcp add` calls. Asserts:
// - The verify helper succeeds (no AUTH/MALFORMED/NETWORK error in output)
// - The skill calls `claude mcp add --transport http` with the bearer
// - The token NEVER appears in the CLAUDE.md block the skill writes
// - The wrote_findings_before_asking failure mode is NOT triggered
//
// Cost: ~$0.30-$0.50 per run. Gate-tier (EVALS=1 EVALS_TIER=gate).
//
// See setup-gbrain/SKILL.md.tmpl Step 4 (Path 4) for the contract under test.
import { describe, test, expect } from 'bun:test';
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import * as http from 'http';
import { runAgentSdkTest, passThroughNonAskUserQuestion, resolveClaudeBinary } from './helpers/agent-sdk-runner';
// Periodic-tier: the model's interpretation of "follow Path 4 only" is
// non-deterministic (it sometimes skips Step 8 CLAUDE.md write, sometimes
// shortcuts past the verify helper). The deterministic gate coverage for
// Path 4 lives in test/setup-gbrain-path4-structure.test.ts (free, <200ms).
const shouldRun = !!process.env.EVALS && process.env.EVALS_TIER === 'periodic';
const describeE2E = shouldRun ? describe : describe.skip;
// Spin up a stub MCP server that responds to initialize + tools/list.
function startStubMcpServer(opts: { failWithStatus?: number; failBody?: string } = {}): Promise<{ url: string; close: () => Promise<void> }> {
return new Promise((resolve) => {
const server = http.createServer((req, res) => {
if (req.method !== 'POST' || !(req.url ?? '').endsWith('/mcp')) {
res.statusCode = 404;
res.end();
return;
}
let body = '';
req.on('data', (c) => (body += c));
req.on('end', () => {
if (opts.failWithStatus) {
res.statusCode = opts.failWithStatus;
res.setHeader('Content-Type', 'application/json');
res.end(opts.failBody ?? JSON.stringify({ error: 'fail' }));
return;
}
const reqJson = (() => {
try { return JSON.parse(body); } catch { return {} as any; }
})();
let respBody: any;
if (reqJson.method === 'initialize') {
respBody = {
result: {
protocolVersion: '2024-11-05',
capabilities: { tools: {} },
serverInfo: { name: 'gbrain', version: '0.27.1' },
},
jsonrpc: '2.0',
id: reqJson.id,
};
} else if (reqJson.method === 'tools/list') {
respBody = { result: { tools: [{ name: 'search' }, { name: 'put_page' }] }, jsonrpc: '2.0', id: reqJson.id };
} else {
respBody = { error: { code: -32601, message: 'unknown method' }, jsonrpc: '2.0', id: reqJson.id };
}
// SSE-shape since the verify helper supports both, and many MCP
// servers (including wintermute) wrap responses as SSE.
res.statusCode = 200;
res.setHeader('Content-Type', 'text/event-stream');
res.end(`event: message\ndata: ${JSON.stringify(respBody)}\n\n`);
});
});
server.listen(0, '127.0.0.1', () => {
const addr = server.address();
if (!addr || typeof addr === 'string') throw new Error('no address');
resolve({
url: `http://127.0.0.1:${addr.port}/mcp`,
close: () => new Promise((r) => server.close(() => r())),
});
});
});
}
// Stubbed `claude` binary: intercepts `mcp add` and `mcp list` commands so
// the skill's Step 5a registration appears to succeed, while we record
// every invocation for assertions.
function makeFakeClaude(fakeBinDir: string): string {
const claudeJsonPath = path.join(fakeBinDir, 'claude.json');
const callLog = path.join(fakeBinDir, 'claude-calls.log');
const script = `#!/bin/bash
echo "claude $@" >> "${callLog}"
case "$1 $2" in
"mcp add")
# Just record the call; pretend it succeeded.
exit 0
;;
"mcp list")
echo "gbrain: http://127.0.0.1:0/mcp (HTTP) - ✓ Connected"
exit 0
;;
"mcp remove")
exit 0
;;
"mcp get")
# First few calls return "no entry"; after mcp add fires, return success.
if [ -f "${claudeJsonPath}" ]; then
cat "${claudeJsonPath}"
exit 0
fi
exit 1
;;
esac
exit 0
`;
fs.writeFileSync(path.join(fakeBinDir, 'claude'), script, { mode: 0o755 });
return callLog;
}
describeE2E('/setup-gbrain Path 4 (Remote MCP) — happy path', () => {
test('verifies, registers HTTP MCP, never writes token to CLAUDE.md', async () => {
const stubServer = await startStubMcpServer();
const gstackHome = fs.mkdtempSync(path.join(os.tmpdir(), 'setup-gbrain-remote-'));
const fakeBinDir = fs.mkdtempSync(path.join(os.tmpdir(), 'setup-gbrain-remote-bin-'));
const callLog = makeFakeClaude(fakeBinDir);
// The skill writes CLAUDE.md in cwd. Use gstackHome as cwd so we
// can inspect it after the run.
fs.writeFileSync(path.join(gstackHome, 'CLAUDE.md'), '# Test project\n');
const SECRET_TOKEN = 'gbrain_TEST_TOKEN_THAT_MUST_NEVER_LEAK_84613';
const askUserQuestions: Array<{ input: Record<string, unknown> }> = [];
const binary = resolveClaudeBinary();
// Ambient env mutations. Restored in finally.
const orig = {
gstackHome: process.env.GSTACK_HOME,
pathEnv: process.env.PATH,
mcpToken: process.env.GBRAIN_MCP_TOKEN,
};
process.env.GSTACK_HOME = gstackHome;
process.env.PATH = `${fakeBinDir}:${path.join(path.resolve(import.meta.dir, '..'), 'bin')}:${process.env.PATH ?? '/usr/bin:/bin:/opt/homebrew/bin'}`;
process.env.GBRAIN_MCP_TOKEN = SECRET_TOKEN;
let modelTextOutput = '';
try {
const skillPath = path.resolve(import.meta.dir, '..', 'setup-gbrain', 'SKILL.md');
const result = await runAgentSdkTest({
systemPrompt: { type: 'preset', preset: 'claude_code' },
userPrompt:
`Read the skill file at ${skillPath} and follow Path 4 (Remote MCP) only. ` +
`Use this MCP URL: ${stubServer.url}. ` +
`The bearer token is already in the GBRAIN_MCP_TOKEN env var (do not echo it). ` +
`Skip the privacy gate — answer "Decline" if the preamble fires. ` +
`Skip the artifacts-repo provisioning step (Step 7) — answer "No thanks". ` +
`Skip per-remote policy (Step 6) — answer "skip-for-now". ` +
`Walk through Steps 4a, 4b, 4c, 5a, 8, 10 ONLY.`,
workingDirectory: gstackHome,
maxTurns: 25,
allowedTools: ['Read', 'Grep', 'Glob', 'Bash', 'Write', 'Edit'],
...(binary ? { pathToClaudeCodeExecutable: binary } : {}),
canUseTool: async (toolName, input) => {
if (toolName === 'AskUserQuestion') {
askUserQuestions.push({ input });
const q = (input.questions as Array<{
question: string;
options: Array<{ label: string }>;
}>)[0];
// Auto-decline / skip everything except the path-pick (which the
// user-prompt already directed to Path 4).
const decline =
q.options.find((o) => /skip|decline|no thanks|local/i.test(o.label)) ?? q.options[q.options.length - 1]!;
return {
behavior: 'allow',
updatedInput: {
questions: input.questions,
answers: { [q.question]: decline.label },
},
};
}
return passThroughNonAskUserQuestion(toolName, input);
},
});
modelTextOutput = JSON.stringify(result);
// Assertion 1: no classified failure surfaced.
// Match the literal verify-helper field shape (avoid false-positives
// from parent session's "needs-auth" MCP server discovery markers).
// We can't deterministically force the model to invoke the verify
// helper through user-prompt alone, so the bound here is "if verify
// ran and emitted an error class, it wasn't NETWORK / AUTH / MALFORMED."
expect(modelTextOutput).not.toMatch(/"error_class"\s*:\s*"NETWORK"/);
expect(modelTextOutput).not.toMatch(/"error_class"\s*:\s*"AUTH"/);
expect(modelTextOutput).not.toMatch(/"error_class"\s*:\s*"MALFORMED"/);
// Assertion 2: claude mcp add was called with --transport http.
const calls = fs.existsSync(callLog) ? fs.readFileSync(callLog, 'utf-8') : '';
expect(calls).toMatch(/mcp add.*--transport http/);
// Assertion 3: the secret token NEVER appears in the final CLAUDE.md.
const claudeMd = fs.readFileSync(path.join(gstackHome, 'CLAUDE.md'), 'utf-8');
expect(claudeMd).not.toContain(SECRET_TOKEN);
// Assertion 4: CLAUDE.md got the remote-http block.
expect(claudeMd).toMatch(/Mode: remote-http/);
// Assertion 5: classifier — the model didn't write findings before
// asking. The Path 4 prose has 5 STOP gates; if any of them got
// skipped, that's the wrote_findings_before_asking pattern.
const wroteBefore = /## GSTACK REVIEW REPORT|critical_gaps/i.test(modelTextOutput);
// Setup-gbrain doesn't have a review report contract, so this is
// a structural shape check, not a hard failure mode.
expect(wroteBefore).toBe(false);
} finally {
if (orig.gstackHome === undefined) delete process.env.GSTACK_HOME; else process.env.GSTACK_HOME = orig.gstackHome;
if (orig.pathEnv === undefined) delete process.env.PATH; else process.env.PATH = orig.pathEnv;
if (orig.mcpToken === undefined) delete process.env.GBRAIN_MCP_TOKEN; else process.env.GBRAIN_MCP_TOKEN = orig.mcpToken;
await stubServer.close();
fs.rmSync(gstackHome, { recursive: true, force: true });
fs.rmSync(fakeBinDir, { recursive: true, force: true });
}
}, 240_000);
});