mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-28 07:32:14 +02:00
v1.91.2.0 fix: consolidate gstack reliability wave (#2959)
* fix(memory-ingest): --scan-secrets scans the rendered page and fails closed --scan-secrets ran gitleaks on the raw transcript .jsonl, then imported a page rendered from it. gitleaks' assignment rules don't match across a JSON-escaped quote (KEY=\"v\" on disk), so a secret the rendered page shows as KEY="v" was imported unflagged. And the gate skipped a file only on scanner "gitleaks" with findings, so a scan that errored (non-zero exit, 16MB maxBuffer overflow on a file with many findings, unparseable report) or could not run (gitleaks missing, slow-probe cooldown) imported the file unscanned. Scan the rendered page body, the exact bytes writeStaged() writes, via a new secretScanText() helper, and skip the file whenever the scan did not complete. Skipped files stay out of the state file, so the next run retries them. Reword the helper warnings and setup-gbrain/memory.md, which described the fail-open as intended. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(test): reconcile Bun failure markers and footer counts * fix(sync-gbrain): verify source-scoped reads without mutation * fix(test): recognize grounded TTHW target choices structurally * fix(aside): make the readiness probe work under zsh and report why it failed The probe built its deadline into `_T` and expanded it unquoted, so `$_T aside repl …` only worked in a shell that word-splits. zsh does not: it looked for a command literally named "gtimeout 30", the probe answered ASIDE_NOT_RUNNING with Aside installed and ready, and every browsing skill fell back to the bundled Chromium in silence. zsh is the macOS default and Aside is macOS-only, so on a stock Mac the probe could never report READY. The deadline becomes a function, `_gs_d`. It receives the command as "$@", already split, so sh, bash and zsh all behave the same, and the gtimeout → timeout → perl alarm chain is unchanged. A 4th arm runs the call unbounded when none of the three is present, which is what the empty `_T` did before. Not `eval`: it re-parses the string, so the parens and `;` of the perl arm become syntax and that arm dies in bash *and* zsh — on a stock Mac, the arm that actually runs. On failure the probe now prints the CLI's reason after ASIDE_NOT_RUNNING:, the shape gstack-render already uses: the first line that starts with a capital letter, i.e. the CLI's own sentence or Node's `Error:` line below its loader frame. "Not running" covers states with different fixes — no window open for the profile, a NODE_OPTIONS preload that kills the CLI — and a bare verdict sent all of them to "open the Aside app". The BROWSER SETUP prose quotes that reason before asking the user to open the app. The text pin asserted the broken invocation verbatim, so it now pins the function and asserts neither `$_T aside repl` nor an eval form comes back. A second test executes the rendered probe in sh, bash and zsh on each of the four deadline arms with stubbed binaries on a narrowed PATH, plus two failing CLIs: one that prints its own sentence, one that crashes like Node with the useful line below the frame. The deadline function costs zero bytes against the lines it replaces; the reason costs 53 per copy of the probe (44 where the reworded BROWSER SETUP line gives 9 back). That moves four guards by the measured amount: plan-devex-review's skeleton cap to 68,550 (measured 68,544), plan-ceo-review's skeleton cap to 80,150 (measured 80,111) and union ratio to 1.081 (measured 1.0803), and plan-eng-review's union ratio to 1.151 (measured 1.1504). Fixes #2842, #2941. * Clarify engineering review startup and decision flow * Fix Windows readiness fixture PATH and command shim * fix(test): recognize grounded TTHW target choices structurally * Clarify engineering review startup and decision flow * fix(test): restrict QA-only fixture tools to its no-Edit contract * v1.90.0.0 fix(sync-gbrain): guard readiness verdicts and refresh metadata * fix(browse): validate canonical upload targets * fix(gbrain): classify structured PGLite busy response * fix(browse): preserve native extension runtime APIs * Fix displayless browser handoff ownership * Accept unique installed autoplan methodology aliases * fix(skills): preserve positional literals during installation * fix(browse): checksum installer contents through stdin * fix(test): normalize Windows checksum fixture paths * test: emulate unavailable shasum in Windows checksum fixture * fix(investigate): preserve owned freeze lifecycle * fix(review): preserve N+1 retry and Red Team completion * fix: bound Aside readiness and preserve safe fallback * test: exercise setup and Chromium on native ARM * fix: preserve install ownership and ARM browser selection * Fix gbrain ingest scan boundaries and seed observation * Refresh managed ship hooks and supervise expanded paid census * Reject resumed gbrain pages excluded by current policy * Recover zombie agent locks safely and enable CI Python venv * Repair paid actor declarations and Aside pitch assertions * Bump consolidated wave to next free minor release * Clarify CEO review admin choices and option tradeoffs * Preserve CEO mode handoff anchors in clarified workflow * Make Windows portability fixtures use shell-native paths * Restore ARM Bun alias and clarify ship review gates * Refresh ship workflow golden snapshots * Fix Windows DX documentation controls without piped stdin * Decode Codex child pipes without Bun's encoded-stream stall * Bound DX pre-review audit before product questions * Clarify trusted review-start read in paid revalidation * Bump consolidated wave to next free minor release * Clarify CEO review admin choices and option tradeoffs * Preserve CEO mode handoff anchors in clarified workflow * Make Windows portability fixtures use shell-native paths * Restore ARM Bun alias and clarify ship review gates * Refresh ship workflow golden snapshots * Fix Windows DX documentation controls without piped stdin * Decode Codex child pipes without Bun's encoded-stream stall * Bound DX pre-review audit before product questions * Clarify trusted review-start read in paid revalidation * Reconcile new main planning flow and paid judge census * fix: reconcile rebased planning and source-bound validation * test: pin cookie workflow judge to scored Sonnet model * fix: keep terminal agent boot out of module imports * fix: preserve pending-question uncertainty in engineering review * fix: stabilize Windows reliability-wave fixtures * fix: clarify design consultation research workflow * fix: preserve independent design consultation inputs * fix: resolve design taste scope and browser research guidance * fix: make consultation opt-in preflight unambiguous * test: await native Edge owner readiness or terminal result --------- Co-authored-by: Bruce Krysiak <brucek@alum.mit.edu> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Antonio Vitalic <antoninte99@gmail.com>
This commit is contained in:
Garry Tan
co-authored by
Bruce Krysiak
Claude Opus 5.5
Antonio Vitalic
Bruce Krysiak
Claude Opus 5.5
Antonio Vitalic
parent
2a113ae7e6
commit
01593aa67c
+59
-58
@@ -554,19 +554,22 @@ tmp-file + atomic rename. Concurrent runs are blocked by a lock file at
|
||||
|
||||
## Step 3: Code-index health check
|
||||
|
||||
After the sync run, query gbrain for the cwd source's page_count:
|
||||
After the sync run, verify the cwd source registration and its page count:
|
||||
|
||||
```bash
|
||||
SOURCE_ID=$(grep -o '"source_id":"[^"]*"' ~/.gstack/.gbrain-sync-state.json 2>/dev/null \
|
||||
| head -1 | sed 's/.*"source_id":"//;s/".*//')
|
||||
PAGES=$(gbrain sources list --json 2>/dev/null \
|
||||
| jq -r --arg id "$SOURCE_ID" '.sources[] | select(.id==$id) | .page_count' 2>/dev/null \
|
||||
|| echo 0)
|
||||
SOURCE_JSON=$(bun run ~/.claude/skills/gstack/bin/gstack-gbrain-read-capability.ts --source-only 2>/dev/null)
|
||||
SOURCE_ID=$(printf '%s' "$SOURCE_JSON" | jq -er 'if .status=="source" then .source_id else empty end' 2>/dev/null)
|
||||
PAGES=$(printf '%s' "$SOURCE_JSON" | jq -er 'if .status=="source" and (.page_count | type)=="number" then .page_count else empty end' 2>/dev/null)
|
||||
echo "cwd source: $SOURCE_ID, page_count: $PAGES"
|
||||
```
|
||||
|
||||
If `PAGES` is 0 or empty AND the user did NOT pass `--no-code` AND mode was
|
||||
not `--full`, AskUserQuestion via the format in the preamble:
|
||||
`--source-only` validates the pretty state schema, writer, successful code stage,
|
||||
real worktree path, `.gbrain-source` pin, and gbrain's registration path before
|
||||
returning its safe integer page count. It does not read any page. An empty source
|
||||
or page count is **unknown**, not zero: report WARN and do not offer a full
|
||||
reindex on that evidence. If `PAGES` is proven `0` AND the user did NOT
|
||||
pass `--no-code` AND mode was not `--full`, AskUserQuestion via the format in
|
||||
the preamble:
|
||||
|
||||
> D1 — This repo has 0 indexed pages in gbrain. Run a full code reindex now?
|
||||
>
|
||||
@@ -608,14 +611,18 @@ Detect whether this source's call graph is built via doctor's `cycle_freshness`
|
||||
check, matching the cwd `SOURCE_ID` literally:
|
||||
|
||||
```bash
|
||||
SOURCE_ID=$(grep -o '"source_id":"[^"]*"' ~/.gstack/.gbrain-sync-state.json 2>/dev/null \
|
||||
| head -1 | sed 's/.*"source_id":"//;s/".*//')
|
||||
CYCLE=$(gbrain doctor --json --fast 2>/dev/null \
|
||||
| jq -r --arg id "$SOURCE_ID" '
|
||||
(.checks[] | select(.name=="cycle_freshness")) as $c
|
||||
| if $c.status=="ok" then "completed"
|
||||
elif ($c.message | index($id)) then "never"
|
||||
else "unknown" end' 2>/dev/null || echo unknown)
|
||||
SOURCE_JSON=$(bun run ~/.claude/skills/gstack/bin/gstack-gbrain-read-capability.ts --source-only 2>/dev/null)
|
||||
SOURCE_ID=$(printf '%s' "$SOURCE_JSON" | jq -er 'if .status=="source" then .source_id else empty end' 2>/dev/null)
|
||||
CYCLE=unknown
|
||||
if [ -n "$SOURCE_ID" ]; then
|
||||
CYCLE=$(gbrain doctor --json --fast 2>/dev/null \
|
||||
| jq -er --arg id "$SOURCE_ID" '
|
||||
if type=="object" and has("error") then empty
|
||||
else (.checks[]? | select(.name=="cycle_freshness")) as $c
|
||||
| if $c.status=="ok" then "completed"
|
||||
elif (($c.message // "") | index($id)) then "never"
|
||||
else "unknown" end end' 2>/dev/null || echo unknown)
|
||||
fi
|
||||
# index($id) = literal substring (NOT test() regex), matching the lib reader in
|
||||
# cycleCompleted(). A fail/warn that doesn't name this source → "unknown" (don't
|
||||
# mask other-source failures).
|
||||
@@ -662,38 +669,23 @@ only that a cycle has run, not that edges exist (a non-code-aware pack reports
|
||||
Capability check (per /plan-eng-review §6):
|
||||
|
||||
```bash
|
||||
SLUG="_capability_check_$$"
|
||||
CAPABILITY_OK=0
|
||||
if [ -f ~/.gbrain/config.json ] && \
|
||||
gbrain --version 2>/dev/null | grep -q '^gbrain '; then
|
||||
# Do NOT export GBRAIN_PREPARE here (#1965). gbrain auto-disables prepared
|
||||
# statements on transaction-mode poolers (port 6543) — forcing them on
|
||||
# breaks every write with "prepared statement does not exist". Users on a
|
||||
# session-mode pooler at 6543 can set GBRAIN_PREPARE=true themselves (the
|
||||
# gbrain banner documents this override).
|
||||
if echo "ping" | gbrain put "$SLUG" >/dev/null 2>&1; then
|
||||
# Retry search up to 3 times with 1s delay — under transaction-mode
|
||||
# pooling the search index may not be visible on the next connection
|
||||
# immediately after the put.
|
||||
for _attempt in 1 2 3; do
|
||||
if gbrain search "ping" 2>/dev/null | grep -q "$SLUG"; then
|
||||
CAPABILITY_OK=1
|
||||
break
|
||||
fi
|
||||
sleep 1
|
||||
done
|
||||
fi
|
||||
fi
|
||||
gbrain delete "$SLUG" 2>/dev/null || true
|
||||
# #2503: on worktree-pinned brains `gbrain put` can materialize the page as
|
||||
# <slug>.md in the CURRENT directory (the user's repo), and `gbrain delete`
|
||||
# removes the page, not the file. Remove the litter explicitly.
|
||||
rm -f "./${SLUG}.md" 2>/dev/null || true
|
||||
bun run ~/.claude/skills/gstack/bin/gstack-gbrain-read-capability.ts <user-args>
|
||||
```
|
||||
|
||||
Then update CLAUDE.md based on capability state:
|
||||
The helper reports JSON `status: ready` only after the successful code sync's
|
||||
source and real worktree match `.gbrain-source`, the source registration points
|
||||
to that worktree, and a bounded, source-scoped list/get returns the same page.
|
||||
It never creates or deletes a page. A `get` may update gbrain's internal
|
||||
retrieval metadata; the guarantee is no page or source mutation, not zero
|
||||
internal writes. `status: unknown` (including transient CLI errors, stale state,
|
||||
or an unverified response) is NOT evidence that the brain is unusable. A
|
||||
`status: skipped` result for `--no-code`, `--dry-run`, `--refresh-cache`, or
|
||||
`--audit` means no code-read probe was attempted. Do not run a write probe,
|
||||
switch to another source, or claim a successful read.
|
||||
|
||||
**If `CAPABILITY_OK=1`** — write or update the block. Idempotent: find the
|
||||
Then update CLAUDE.md based on the helper's status:
|
||||
|
||||
**If `status=ready`** — write or update the block. Idempotent: find the
|
||||
HTML-comment-delimited block; replace its body if it exists; append at the
|
||||
end of CLAUDE.md if it doesn't. NEVER duplicate. Block is machine-AGNOSTIC
|
||||
(no engine, no page counts, no last-sync time — those are in the existing
|
||||
@@ -705,9 +697,10 @@ Verbatim block content (copy exactly):
|
||||
## GBrain Search Guidance (configured by /sync-gbrain)
|
||||
<!-- gstack-gbrain-search-guidance:start -->
|
||||
|
||||
GBrain is set up and synced on this machine. The agent should prefer gbrain
|
||||
over Grep when the question is semantic or when you don't know the exact
|
||||
identifier yet.
|
||||
This worktree's pinned code source answered a source-scoped page read. This
|
||||
does not verify semantic search or write availability. Prefer gbrain over Grep
|
||||
when the question is semantic or when you don't know the exact identifier yet;
|
||||
if a query fails, report that failure rather than assuming the index is healthy.
|
||||
|
||||
**This worktree is pinned to a worktree-scoped code source** via the
|
||||
`.gbrain-source` file in the repo root (kubectl-style context).
|
||||
@@ -764,9 +757,14 @@ the entire block at the end of CLAUDE.md.
|
||||
(e.g., `CLAUDE.md.sync-gbrain.tmp`) then `mv` to atomic-rename, so a crash
|
||||
mid-write never leaves the file half-modified.
|
||||
|
||||
**If `CAPABILITY_OK=0`** — REMOVE the block entirely if present. Use the same
|
||||
Edit tool to strip the start/end-marker region. The `## GBrain Configuration`
|
||||
block stays in place (it's a record of the install, not a capability claim).
|
||||
**If `status=unknown`** — preserve the existing guidance block, if any, and
|
||||
report the helper's reason as WARN with advice to retry `/sync-gbrain` or the
|
||||
read check when the transient failure clears. Do not install new guidance on
|
||||
an unknown result or remove the existing guidance merely because this read
|
||||
could not verify it. The `## GBrain Configuration` block stays in place.
|
||||
|
||||
**If `status=skipped`** — leave guidance unchanged. Report that code readiness
|
||||
was not probed in this mode, not that it passed or failed.
|
||||
|
||||
Do NOT crash if CLAUDE.md is missing or unwritable — log a warning and
|
||||
continue.
|
||||
@@ -785,7 +783,7 @@ gbrain status: GREEN
|
||||
|
||||
CLI ............. OK <gbrain version>
|
||||
Engine .......... OK <pglite|supabase>
|
||||
Capability ...... OK write+search round-trip
|
||||
Capability ...... OK source-scoped page read verified (no page/source mutation)
|
||||
CWD source ...... OK <gstack-code-{repo_slug}> (page_count=<N>)
|
||||
Call graph ...... OK <N> edges resolved (code-callers/callees live)
|
||||
~/.gstack source. OK <gstack-brain-{user}> (page_count=<N>) — managed by /setup-gbrain
|
||||
@@ -814,8 +812,11 @@ The **Call graph** row reports the most authoritative signal available:
|
||||
Any `WARN` Call graph row flips the verdict to YELLOW.
|
||||
|
||||
If any row is YELLOW or RED, the verdict line says so and the failing rows
|
||||
surface a one-line "next action" (e.g., `Capability ...... ERR capability
|
||||
check failed; CLAUDE.md guidance block REMOVED — run /setup-gbrain to repair`).
|
||||
surface a one-line next action. An unknown read gives `Capability ...... WARN
|
||||
source-scoped read unverified; guidance preserved — retry /sync-gbrain` and
|
||||
flips the verdict to YELLOW, not RED.
|
||||
For a skipped probe, show `Capability ...... WARN code read not probed in
|
||||
this mode; guidance unchanged` and do not print a GREEN capability verdict.
|
||||
A `never`/`unknown` Call graph row flips the verdict to YELLOW.
|
||||
|
||||
---
|
||||
@@ -832,16 +833,16 @@ in flight. Stale locks (process died) auto-clear after 5 minutes.
|
||||
The `## GBrain Search Guidance` block is committed to the repo's CLAUDE.md
|
||||
and travels with `git push`/`git pull` — NOT through `~/.gstack/.brain-allowlist`
|
||||
(which is for `~/.gstack/` brain-sync only). On a different Mac with a synced
|
||||
CLAUDE.md but no local gbrain, /sync-gbrain detects the mismatch via the
|
||||
capability check and REMOVES the block (the local agent shouldn't be told to
|
||||
use a tool that isn't installed).
|
||||
CLAUDE.md but no local gbrain, /sync-gbrain reports an unknown read and
|
||||
preserves the block rather than deleting committed instructions based on a
|
||||
transient or machine-local failure. Agents must not treat unknown as ready.
|
||||
|
||||
## Status reporting
|
||||
|
||||
End with a Completion Status (per the preamble protocol):
|
||||
- **DONE** — all stages green, CLAUDE.md guidance block present, verdict GREEN.
|
||||
- **DONE_WITH_CONCERNS** — sync ran but at least one stage failed or capability
|
||||
check failed. List which.
|
||||
read was unverified. List which and preserve retry guidance.
|
||||
- **BLOCKED** — could not acquire lock, gbrain not on PATH, or per-repo policy
|
||||
is deny. State the blocker.
|
||||
- **NEEDS_CONTEXT** — /setup-gbrain has not been run, or `gbrain doctor` shows
|
||||
|
||||
+59
-58
@@ -205,19 +205,22 @@ tmp-file + atomic rename. Concurrent runs are blocked by a lock file at
|
||||
|
||||
## Step 3: Code-index health check
|
||||
|
||||
After the sync run, query gbrain for the cwd source's page_count:
|
||||
After the sync run, verify the cwd source registration and its page count:
|
||||
|
||||
```bash
|
||||
SOURCE_ID=$(grep -o '"source_id":"[^"]*"' ~/.gstack/.gbrain-sync-state.json 2>/dev/null \
|
||||
| head -1 | sed 's/.*"source_id":"//;s/".*//')
|
||||
PAGES=$(gbrain sources list --json 2>/dev/null \
|
||||
| jq -r --arg id "$SOURCE_ID" '.sources[] | select(.id==$id) | .page_count' 2>/dev/null \
|
||||
|| echo 0)
|
||||
SOURCE_JSON=$(bun run ~/.claude/skills/gstack/bin/gstack-gbrain-read-capability.ts --source-only 2>/dev/null)
|
||||
SOURCE_ID=$(printf '%s' "$SOURCE_JSON" | jq -er 'if .status=="source" then .source_id else empty end' 2>/dev/null)
|
||||
PAGES=$(printf '%s' "$SOURCE_JSON" | jq -er 'if .status=="source" and (.page_count | type)=="number" then .page_count else empty end' 2>/dev/null)
|
||||
echo "cwd source: $SOURCE_ID, page_count: $PAGES"
|
||||
```
|
||||
|
||||
If `PAGES` is 0 or empty AND the user did NOT pass `--no-code` AND mode was
|
||||
not `--full`, AskUserQuestion via the format in the preamble:
|
||||
`--source-only` validates the pretty state schema, writer, successful code stage,
|
||||
real worktree path, `.gbrain-source` pin, and gbrain's registration path before
|
||||
returning its safe integer page count. It does not read any page. An empty source
|
||||
or page count is **unknown**, not zero: report WARN and do not offer a full
|
||||
reindex on that evidence. If `PAGES` is proven `0` AND the user did NOT
|
||||
pass `--no-code` AND mode was not `--full`, AskUserQuestion via the format in
|
||||
the preamble:
|
||||
|
||||
> D1 — This repo has 0 indexed pages in gbrain. Run a full code reindex now?
|
||||
>
|
||||
@@ -259,14 +262,18 @@ Detect whether this source's call graph is built via doctor's `cycle_freshness`
|
||||
check, matching the cwd `SOURCE_ID` literally:
|
||||
|
||||
```bash
|
||||
SOURCE_ID=$(grep -o '"source_id":"[^"]*"' ~/.gstack/.gbrain-sync-state.json 2>/dev/null \
|
||||
| head -1 | sed 's/.*"source_id":"//;s/".*//')
|
||||
CYCLE=$(gbrain doctor --json --fast 2>/dev/null \
|
||||
| jq -r --arg id "$SOURCE_ID" '
|
||||
(.checks[] | select(.name=="cycle_freshness")) as $c
|
||||
| if $c.status=="ok" then "completed"
|
||||
elif ($c.message | index($id)) then "never"
|
||||
else "unknown" end' 2>/dev/null || echo unknown)
|
||||
SOURCE_JSON=$(bun run ~/.claude/skills/gstack/bin/gstack-gbrain-read-capability.ts --source-only 2>/dev/null)
|
||||
SOURCE_ID=$(printf '%s' "$SOURCE_JSON" | jq -er 'if .status=="source" then .source_id else empty end' 2>/dev/null)
|
||||
CYCLE=unknown
|
||||
if [ -n "$SOURCE_ID" ]; then
|
||||
CYCLE=$(gbrain doctor --json --fast 2>/dev/null \
|
||||
| jq -er --arg id "$SOURCE_ID" '
|
||||
if type=="object" and has("error") then empty
|
||||
else (.checks[]? | select(.name=="cycle_freshness")) as $c
|
||||
| if $c.status=="ok" then "completed"
|
||||
elif (($c.message // "") | index($id)) then "never"
|
||||
else "unknown" end end' 2>/dev/null || echo unknown)
|
||||
fi
|
||||
# index($id) = literal substring (NOT test() regex), matching the lib reader in
|
||||
# cycleCompleted(). A fail/warn that doesn't name this source → "unknown" (don't
|
||||
# mask other-source failures).
|
||||
@@ -313,38 +320,23 @@ only that a cycle has run, not that edges exist (a non-code-aware pack reports
|
||||
Capability check (per /plan-eng-review §6):
|
||||
|
||||
```bash
|
||||
SLUG="_capability_check_$$"
|
||||
CAPABILITY_OK=0
|
||||
if [ -f ~/.gbrain/config.json ] && \
|
||||
gbrain --version 2>/dev/null | grep -q '^gbrain '; then
|
||||
# Do NOT export GBRAIN_PREPARE here (#1965). gbrain auto-disables prepared
|
||||
# statements on transaction-mode poolers (port 6543) — forcing them on
|
||||
# breaks every write with "prepared statement does not exist". Users on a
|
||||
# session-mode pooler at 6543 can set GBRAIN_PREPARE=true themselves (the
|
||||
# gbrain banner documents this override).
|
||||
if echo "ping" | gbrain put "$SLUG" >/dev/null 2>&1; then
|
||||
# Retry search up to 3 times with 1s delay — under transaction-mode
|
||||
# pooling the search index may not be visible on the next connection
|
||||
# immediately after the put.
|
||||
for _attempt in 1 2 3; do
|
||||
if gbrain search "ping" 2>/dev/null | grep -q "$SLUG"; then
|
||||
CAPABILITY_OK=1
|
||||
break
|
||||
fi
|
||||
sleep 1
|
||||
done
|
||||
fi
|
||||
fi
|
||||
gbrain delete "$SLUG" 2>/dev/null || true
|
||||
# #2503: on worktree-pinned brains `gbrain put` can materialize the page as
|
||||
# <slug>.md in the CURRENT directory (the user's repo), and `gbrain delete`
|
||||
# removes the page, not the file. Remove the litter explicitly.
|
||||
rm -f "./${SLUG}.md" 2>/dev/null || true
|
||||
bun run ~/.claude/skills/gstack/bin/gstack-gbrain-read-capability.ts <user-args>
|
||||
```
|
||||
|
||||
Then update CLAUDE.md based on capability state:
|
||||
The helper reports JSON `status: ready` only after the successful code sync's
|
||||
source and real worktree match `.gbrain-source`, the source registration points
|
||||
to that worktree, and a bounded, source-scoped list/get returns the same page.
|
||||
It never creates or deletes a page. A `get` may update gbrain's internal
|
||||
retrieval metadata; the guarantee is no page or source mutation, not zero
|
||||
internal writes. `status: unknown` (including transient CLI errors, stale state,
|
||||
or an unverified response) is NOT evidence that the brain is unusable. A
|
||||
`status: skipped` result for `--no-code`, `--dry-run`, `--refresh-cache`, or
|
||||
`--audit` means no code-read probe was attempted. Do not run a write probe,
|
||||
switch to another source, or claim a successful read.
|
||||
|
||||
**If `CAPABILITY_OK=1`** — write or update the block. Idempotent: find the
|
||||
Then update CLAUDE.md based on the helper's status:
|
||||
|
||||
**If `status=ready`** — write or update the block. Idempotent: find the
|
||||
HTML-comment-delimited block; replace its body if it exists; append at the
|
||||
end of CLAUDE.md if it doesn't. NEVER duplicate. Block is machine-AGNOSTIC
|
||||
(no engine, no page counts, no last-sync time — those are in the existing
|
||||
@@ -356,9 +348,10 @@ Verbatim block content (copy exactly):
|
||||
## GBrain Search Guidance (configured by /sync-gbrain)
|
||||
<!-- gstack-gbrain-search-guidance:start -->
|
||||
|
||||
GBrain is set up and synced on this machine. The agent should prefer gbrain
|
||||
over Grep when the question is semantic or when you don't know the exact
|
||||
identifier yet.
|
||||
This worktree's pinned code source answered a source-scoped page read. This
|
||||
does not verify semantic search or write availability. Prefer gbrain over Grep
|
||||
when the question is semantic or when you don't know the exact identifier yet;
|
||||
if a query fails, report that failure rather than assuming the index is healthy.
|
||||
|
||||
**This worktree is pinned to a worktree-scoped code source** via the
|
||||
`.gbrain-source` file in the repo root (kubectl-style context).
|
||||
@@ -415,9 +408,14 @@ the entire block at the end of CLAUDE.md.
|
||||
(e.g., `CLAUDE.md.sync-gbrain.tmp`) then `mv` to atomic-rename, so a crash
|
||||
mid-write never leaves the file half-modified.
|
||||
|
||||
**If `CAPABILITY_OK=0`** — REMOVE the block entirely if present. Use the same
|
||||
Edit tool to strip the start/end-marker region. The `## GBrain Configuration`
|
||||
block stays in place (it's a record of the install, not a capability claim).
|
||||
**If `status=unknown`** — preserve the existing guidance block, if any, and
|
||||
report the helper's reason as WARN with advice to retry `/sync-gbrain` or the
|
||||
read check when the transient failure clears. Do not install new guidance on
|
||||
an unknown result or remove the existing guidance merely because this read
|
||||
could not verify it. The `## GBrain Configuration` block stays in place.
|
||||
|
||||
**If `status=skipped`** — leave guidance unchanged. Report that code readiness
|
||||
was not probed in this mode, not that it passed or failed.
|
||||
|
||||
Do NOT crash if CLAUDE.md is missing or unwritable — log a warning and
|
||||
continue.
|
||||
@@ -436,7 +434,7 @@ gbrain status: GREEN
|
||||
|
||||
CLI ............. OK <gbrain version>
|
||||
Engine .......... OK <pglite|supabase>
|
||||
Capability ...... OK write+search round-trip
|
||||
Capability ...... OK source-scoped page read verified (no page/source mutation)
|
||||
CWD source ...... OK <gstack-code-{repo_slug}> (page_count=<N>)
|
||||
Call graph ...... OK <N> edges resolved (code-callers/callees live)
|
||||
~/.gstack source. OK <gstack-brain-{user}> (page_count=<N>) — managed by /setup-gbrain
|
||||
@@ -465,8 +463,11 @@ The **Call graph** row reports the most authoritative signal available:
|
||||
Any `WARN` Call graph row flips the verdict to YELLOW.
|
||||
|
||||
If any row is YELLOW or RED, the verdict line says so and the failing rows
|
||||
surface a one-line "next action" (e.g., `Capability ...... ERR capability
|
||||
check failed; CLAUDE.md guidance block REMOVED — run /setup-gbrain to repair`).
|
||||
surface a one-line next action. An unknown read gives `Capability ...... WARN
|
||||
source-scoped read unverified; guidance preserved — retry /sync-gbrain` and
|
||||
flips the verdict to YELLOW, not RED.
|
||||
For a skipped probe, show `Capability ...... WARN code read not probed in
|
||||
this mode; guidance unchanged` and do not print a GREEN capability verdict.
|
||||
A `never`/`unknown` Call graph row flips the verdict to YELLOW.
|
||||
|
||||
---
|
||||
@@ -483,16 +484,16 @@ in flight. Stale locks (process died) auto-clear after 5 minutes.
|
||||
The `## GBrain Search Guidance` block is committed to the repo's CLAUDE.md
|
||||
and travels with `git push`/`git pull` — NOT through `~/.gstack/.brain-allowlist`
|
||||
(which is for `~/.gstack/` brain-sync only). On a different Mac with a synced
|
||||
CLAUDE.md but no local gbrain, /sync-gbrain detects the mismatch via the
|
||||
capability check and REMOVES the block (the local agent shouldn't be told to
|
||||
use a tool that isn't installed).
|
||||
CLAUDE.md but no local gbrain, /sync-gbrain reports an unknown read and
|
||||
preserves the block rather than deleting committed instructions based on a
|
||||
transient or machine-local failure. Agents must not treat unknown as ready.
|
||||
|
||||
## Status reporting
|
||||
|
||||
End with a Completion Status (per the preamble protocol):
|
||||
- **DONE** — all stages green, CLAUDE.md guidance block present, verdict GREEN.
|
||||
- **DONE_WITH_CONCERNS** — sync ran but at least one stage failed or capability
|
||||
check failed. List which.
|
||||
read was unverified. List which and preserve retry guidance.
|
||||
- **BLOCKED** — could not acquire lock, gbrain not on PATH, or per-repo policy
|
||||
is deny. State the blocker.
|
||||
- **NEEDS_CONTEXT** — /setup-gbrain has not been run, or `gbrain doctor` shows
|
||||
|
||||
Reference in New Issue
Block a user