* fix(security): scope cross-source reads to the caller grant; close get_page exact-path leak
One shared resolveRequestedScope() routes every source-scoped read op
(query, code_callers/callees, search_by_image, code_blast/flow, get_page)
through a single fail-closed trust+grant ladder: a remote caller's __all__
collapses to its granted sources (never the whole brain) and an explicit
out-of-grant source_id is rejected. get_page's exact-match path now honors a
federated grant via getPage(sourceIds[]) in both engines. Legacy bearer tokens
carry their stored permissions.source_id grant (bounded, never widened). Also
retries getConfig on transient connection loss.
Closes#1924, #1371, #1393, #1336, #1603.
* fix(ingest): non-string frontmatter no longer aborts lint/sync; embed/hook/catalog papercuts
Parser coerces a non-string title to a string and falls back to inference for
slug/type (never fabricating a "123" slug), with a lint NON_STRING_FIELD finding
surfacing the malformed frontmatter; a defensive guard in content-sanity stops a
non-string title from crashing the whole lint/sync run brain-wide. Plus: embed
--catch-up no longer arms the overflowed 32-bit budget timer (and surfaces
unembeddable chunks); the frontmatter pre-commit hook ships a correct .md/.mdx
regex; and the skill catalog parses YAML block-scalar descriptions.
Closes#1883, #1658, #1556, #1948, #1946, #1840, #1711.
* v0.42.37.0 fix(security,ingest): source-isolation grant enforcement + non-string frontmatter guard + papercuts
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: add NON_STRING_FIELD frontmatter validation class to docs for v0.42.37.0
The v0.42.37.0 non-string-frontmatter fix added an eighth validation
class (NON_STRING_FIELD / lint code frontmatter-non-string-field). Update
the two current-state docs that enumerate the validation classes:
- skills/frontmatter-guard/SKILL.md (seven->eight + table row)
- docs/integrations/pre-commit.md (seven->eight + table row)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(recipes/openai): add max_batch_tokens to embedding touchpoint
OpenAI is the only recipe in the codebase without a max_batch_tokens cap.
Every other provider declares one (voyage=120K, azure-openai=8K, dashscope=8K,
zhipu=8K, minimax=4K). Without it, gbrain's recursive-halving safety net never
engages — batches dispatched purely on the char/4 estimator window will trip
OpenAI's 1M-token TPM ceiling on token-dense pages (Discord exports, JSON
dumps, code-heavy markdown), then retry storm and block the queue head.
Setting cap to 100_000:
- gbrain's batcher estimates tokens as chars/4
- Token-dense markdown+JSON tokenizes at ~chars/2.7
- 100K estimated = ~150K real worst-case, safely under OpenAI's 300K
per-request hard cap and the 1M/min TPM ceiling
- Leaves headroom for recursive-halving on outlier chunks
(cherry picked from commit 40536aace5)
* fix(ai/embed): recognize OpenAI 'maximum request size' error in isTokenLimitError
OpenAI's /v1/embeddings endpoint hard-caps a single request at 300k tokens
total across all input items. When the cap is exceeded it returns:
Invalid 'input': maximum request size is 300000 tokens per request.
None of the three existing regexes in isTokenLimitError matched this
phrasing, so the recursive-halving safety net in embedSubBatch never
engaged for OpenAI. The same fat page (a token-dense markdown export,
e.g. a Discord transcript) would re-fail every pass, blocking forward
progress on the whole batch indefinitely.
Locally reproduced on a 31,129-chunk Postgres brain: 2,125 chunks
stuck at 'remaining' across 30+ embed --stale passes with retry
loops + sleep delays. Adding the two new patterns lets halving fire;
the same backlog cleared in one pass after the regex change (the
companion max_batch_tokens recipe fix from PR #924 caps fresh batches,
but existing oversize pages still need halving to recover).
Adds:
- /maximum request size.*tokens/i — OpenAI verbatim
- /max.*tokens.*per.*request/i — defensive against minor rewording
Tests:
- Regression test for the exact OpenAI error string
- Coverage for the generic 'max tokens per request' variant
- All 25 tests in adaptive-embed-batch.test.ts pass
No behavior change for providers whose errors already matched.
(cherry picked from commit b834e84c56)
* fix(connection-manager): strip .<project-ref> suffix from username when deriving direct URL
`deriveDirectUrl()` correctly rewrites the host (`aws-0-us-east-1.pooler.supabase.com`
→ `db.abcxyz.supabase.co`) but preserves the full pooler-form username
(`postgres.abcxyz`). Supabase direct connections expect a bare `postgres`
username — Supavisor uses the `.<ref>` suffix for tenant routing, but it's
not a real database user. The auto-derived URL therefore fails to authenticate
even with the correct password:
password authentication failed for user "postgres.abcxyz"
Strip the suffix to `postgres` whenever the project-ref was successfully
extracted (same condition that triggers the host rewrite). The non-pooler
username branch is unaffected — preserved as-is to keep the port-only
fallback case working.
Hit while exercising v0.30.1's dual-pool routing on a real Supabase brain;
the kill switch (`GBRAIN_DISABLE_DIRECT_POOL=1`) papered over it locally
but every Supabase user with a stock pooler URL would silently fall through
to single-pool until the user-supplied a `GBRAIN_DIRECT_DATABASE_URL`
override. With this fix, dual-pool works out of the box for the canonical
Supabase shape.
Test additions:
- 1 case asserting bare `postgres:secret@` in the derived URL when
project-ref is parseable from the pooler URL (the new behavior)
- extends the existing "falls back to port-only" case with an
assertion that non-pooler usernames are preserved (unchanged behavior)
`bun run typecheck` clean. `deriveDirectUrl` test block passes 5/5.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
(cherry picked from commit ddf2c6a9a0)
* fix(init): --help should not mutate config or scan filesystem
`gbrain init --help` (and `-h`) currently fall through to the smart-detection
branch in runInit(), which scans cwd for .md files and on a directory with
1000+ files prints "Found ~1500 .md files. For a brain this size, Supabase
gives faster search..." then defaults to PGLite — calling saveConfig() and
overwriting any existing Postgres config with `engine: 'pglite' +
database_path: ~/.gbrain/brain.pglite`.
Confirmed in the wild: ran `gbrain init --help` from $HOME on a machine where
~/.gbrain/config.json pointed at a Supabase Postgres brain with 10K+ pages.
The config was silently flipped to PGLite. The Supabase data was intact, but
gbrain stopped pointing at it until the config was manually restored.
Root cause: cli.ts:62-69 only routes --help → printOpHelp() for shared-op
commands; CLI_ONLY commands (init, embed, etc.) fall through to their handler
with --help still in argv. None of them check for it.
Fix: add a --help/-h guard at the top of runInit() that prints help text and
returns. Help should never mutate state — Postel's robustness principle for
CLI tools.
Help text covers all flags (engine selection, AI provider options, thin-client
mode) so users running `--help` get the canonical list rather than having to
read the source.
A wider architectural fix — adding --help routing for all CLI_ONLY commands in
cli.ts — is plausible follow-up, but each CLI_ONLY command would still need
its own help text. This per-command pattern matches how shared ops handle it
via printOpHelp(). Init is the highest-stakes case because it's the only
CLI_ONLY command that calls saveConfig().
Smoke test: from a directory with 1500 .md files, with GBRAIN_HOME pointed at
a fresh tempdir:
- Before fix: ~/.gbrain/config.json materialized with engine: 'pglite'
- After fix: help text printed, no config dir created
`bun run typecheck` clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
(cherry picked from commit ed11fdd58c)
* test(frontmatter-install-hook): isolate hooksPath assertion from developer global config
The "installHook writes ... and sets core.hooksPath" test asserted
`git config --get core.hooksPath` returns `.githooks`, which falls
back to the global scope when local is unset. Developers who set
`core.hooksPath` globally (common with dotfiles managers pointing at
~/.config/git/hooks) saw a deterministic FAIL because installHook
intentionally respects an existing global value and skips writing
the local one — exactly the documented contract.
Fix: read via `git config --local --get core.hooksPath` (scope-locked)
and branch the assertion on whether a global is already set. Both
clean-CI (local should be '.githooks') and developer-with-global
(local should be empty; installHook correctly didn't clobber) now
pass deterministically.
No API change. installHook behavior is unchanged.
Verified locally with the affected test passing under
`GIT_CONFIG_GLOBAL=~/.gitconfig` carrying `core.hooksPath=...`.
(cherry picked from commit 0e4da2cb38)
* fix: guard against missing 'intent' field in routing-eval fixtures
Two defensive fixes:
1. normalizeText(): return empty string on null/undefined input instead
of crashing with 'undefined is not an object (evaluating s.toLowerCase)'
2. loadRoutingFixtures(): validate that parsed fixture has 'intent' as a
string before adding to fixtures array. Fixtures with wrong field
names (e.g. 'input' instead of 'intent') are now reported as
malformed with a helpful error message listing the actual keys found.
Root cause: a skill's routing-eval.jsonl used {"input": ...} instead
of {"intent": ...}. The JSON parsed fine but the cast to
RoutingFixture was unchecked, so fixture.intent was undefined.
normalizeText(undefined) then crashed. This made 'gbrain doctor'
completely unusable.
(cherry picked from commit b142bbdb0d)
* fix(test): isolate HOME in run-e2e.sh to stop config corruption
Replaces #517 (re-ported fresh against current scripts/run-e2e.sh after
v0.23.1 rewrote the script — original cherry-pick would not apply).
E2E tests call setupDB which writes $HOME/.gbrain/config.json pointing at
the docker test container. When the container tears down, the user's real
autopilot daemon wedges trying to connect to a vanished postgres. Three
operators hit this within 16 days before the original PR filed.
Fix: wrapper exports HOME + GBRAIN_HOME to a mktemp tmpdir BEFORE bun
starts so config writes land in the tmpdir, with a post-run breach
detector that compares md5 of the user's real config against pre-run.
Both env vars required: loadConfig/saveConfig resolve via HOME while
configPath honors GBRAIN_HOME. HOME set before bun starts because
os.homedir() caches at first call.
Test seam: test/gbrain-home-isolation.test.ts updated to assert against
homedir() === configDir() when GBRAIN_HOME unset (correct under the
safety wrapper itself) instead of the prior "not /tmp/" sentinel.
Revert path: git revert <this-sha> if test:e2e regresses on master.
Co-Authored-By: orendi84 <orendi84@users.noreply.github.com>
* test(dream-cycle): add schema-suggest to EXPECTED_PHASES
v0.40.7.0 Schema Cathedral v3 added the 'schema-suggest' phase between
'orphans' and 'purge' in ALL_PHASES, but the E2E phase-order test was
not updated to match. ALL_PHASES vs EXPECTED_PHASES diverged and the
shape-pin test failed every run on master.
Surfaced during fix-wave: warm-narwhal E2E gate.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(autopilot-fanout): use relative timestamp inside freshness window
The 'end-to-end: updateSourceConfig persists timestamp visible to next
listAllSources' test pinned last_full_cycle_at to a hardcoded
'2026-05-22T15:00:00.000Z'. The 60-minute freshness window passed
within ~1 hour of write — every run after the deadline classified the
source as stale and dispatched it, breaking the test's
.skippedFresh expectation.
Switch to Date.now() - 30min relative timestamp (mirrors the prior
'source with last_full_cycle_at < 60min ago is skipped by gate' test).
Surfaced during fix-wave: warm-narwhal E2E gate.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(fresh-install-pglite): unset other provider keys in beforeEach
init.ts:455 fails loud when multiple embedding providers are env-ready
in non-TTY mode. The test sets ZEROENTROPY_API_KEY then runs init,
but developer machines commonly have OPENAI_API_KEY + VOYAGE_API_KEY +
ZEROENTROPY_API_KEY all set, so init sees 3 providers and exits 1.
Save+unset OPENAI_API_KEY + VOYAGE_API_KEY in beforeEach, restore in
afterEach. Now only ZE is env-ready, init picks it, schema sized to
zembed-1's 1280d as the test expects.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(voyage-multimodal): switch fixture from AVIF to PNG
Voyage's /multimodalembeddings endpoint rejects AVIF as of 2026-05
with 'Please provide a valid base64-encoded image'. The prior comment
('AVIF is fine for an embed call') held at v0.27.x and regressed
silently on the provider side.
Add test/fixtures/images/tiny.png (16x16 RGB PNG, 1307 bytes generated
via sips from the macOS default wallpaper). PNG is universally
accepted by Voyage and other multimodal providers.
Surfaced during fix-wave: warm-narwhal E2E gate.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(cycle/synthesize): prefix bare anthropic model ids before queue.add
queue.add's subagent capability validator (classifyCapabilities →
resolveRecipe) requires provider:model format and rejects bare ids
with 'unknown provider'. resolveModel returns the bare id from
TIER_DEFAULTS / DEFAULT_ALIASES (e.g. 'claude-sonnet-4-6'), which the
validator then rejects, dropping the synthesize phase to status:fail
with SYNTH_PHASE_FAIL.
Narrow fix at the call site: if config.model has no colon AND starts
with 'claude-', prefix 'anthropic:'. Other providers must already
declare a colon. Avoids changing TIER_DEFAULTS / DEFAULT_ALIASES
constant shapes, which would ripple across every resolveModel caller.
Surfaced by dream-synthesize-chunking E2E during fix-wave: warm-narwhal.
Affected tests: 'single-chunk transcript uses legacy idempotency key'
and 'multi-chunk transcript spawns N children with chunk-suffixed
idempotency keys' — both relied on result.details.children_submitted
which only the ok() path sets; the failed() path returns details: {}.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(mechanical): pin doctor init embedding model + clean non-default sources
Two fixes in the E2E Doctor Command describe block, both surfaced by
cross-file state pollution under the full sequential E2E run:
1. Pass --embedding-model openai:text-embedding-3-large to the init
subprocess. Without the explicit flag, doctor inherits whatever the
resolver picks from env keys (ZE if ZEROENTROPY_API_KEY is set,
defaulting to zembed-1 at 1280d). The test's setupDB initialized
schema at 1536d, so the dim mismatch fires
embedding_width_consistency WARN, exiting doctor 1.
2. DELETE FROM sources WHERE id != 'default' in beforeAll. Prior E2E
files leave non-default source rows (e.g. 'delta' from autopilot /
sources tests). sync_freshness + cycle_freshness then FAIL on those
orphans because they were never synced/cycled, exiting doctor 1.
setupDB TRUNCATEs sources but schema.sql re-seeds 'default' via
initSchema; this leaves only the canonical single-source brain
the test expects.
Surfaced during fix-wave: warm-narwhal E2E gate.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(run-e2e): per-file connection flush + 180s outer timeout
Two cross-file isolation hardenings for the sequential E2E runner:
1. Terminate stale Postgres connections before each file. Without this,
idle connections from the prior bun process's pool race with the
next file's setupDB() TRUNCATE CASCADE, producing 'fixture pages
disappear mid-test' failures. The terminate call is idempotent +
~50ms; first iteration is a no-op.
2. Hard outer timeout (180s per file) via gtimeout / timeout. bun's
--timeout=60000 is per-test; if a PGLite WASM call hangs in
beforeAll/afterAll (e.g. ingestion-roundtrip.test.ts wedging
30+ minutes on macOS), --timeout never fires and the entire suite
wedges. Outer SIGKILL lets the suite advance and the file is
recorded as failed for triage. Falls through to bare bun if neither
gtimeout nor timeout is on PATH.
Surfaced during fix-wave: warm-narwhal — 3 of 5 cross-file flakes
caught by the connection flush; ingestion-roundtrip 30-min wedge
caught by the outer timeout.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore: bump version and changelog (v0.41.3.0)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* docs: annotate synthesize.ts narrow prefix fix (v0.41.3.0)
CLAUDE.md gains the v0.41.3.0 note on src/core/cycle/synthesize.ts (narrow
anthropic: prefix at the queue.add boundary so resolveModel's bare ids
satisfy the subagent validator). llms-full.txt regenerated to match.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* chore: rebump v0.41.3.0 → v0.41.5.0 (queue drift; PR #1377 claimed .4.0)
Sibling fix-wave PR #1377 (garrytan/community-pr-wave) claimed v0.41.4.0
between my queue check (.3.0 was available) and PR creation. Re-bump to
the next available slot per workspace-aware allocator.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* fix(cycle/synthesize): refuse empty brainDir + resolve relative paths
Pre-fix, runPhaseSynthesize accepted any brainDir string and passed it
to writeReversePages which does join(brainDir, '<slug>.md'). When
brainDir is '' or relative ('.' / './brain' / etc), join() produces a
relative path that writeFileSync resolves against cwd. Result: every
synthesize reverse-write spills into <cwd>/companies/<slug>.md,
<cwd>/people/<slug>.md, etc. instead of the intended brainDir tempdir.
Surfaced by the warm-narwhal wave when E2E test cleanup found orphan
synthesize pages (companies/novamind.md, people/sarah-chen.md,
meetings/2025-04-01-novamind-board-update.md) at the gbrain repo root
from a runCycle({brainDir: '.'}) chain that ran during morning E2E
execution.
Fix at the function entry, single location, all callers protected:
1. Empty/whitespace brainDir → return failed(BRAINDIR_EMPTY) loud
instead of silently resolving against cwd
2. Relative brainDir → resolve(opts.brainDir) before any read/write
can use it. opts.brainDir mutated so writeReversePages,
writeSummaryPage, and every join() downstream see the absolute path
Regression test pins all 4 contracts:
- empty string → fail(BRAINDIR_EMPTY)
- whitespace-only → fail(BRAINDIR_EMPTY)
- '.' → mutated to absolute on entry
- already-absolute → unchanged
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* fix(dream): resolve brainDir to absolute at CLI surface
Defense-in-depth for the synthesize-braindir spillage bug class. The
core fix lives in runPhaseSynthesize (commit 98222a08); this resolves
brainDir one layer earlier so the entire 9-phase runCycle gets the
absolute path, not just synthesize.
Two paths in resolveBrainDir get path.resolve():
- explicit --dir argument (e.g., `gbrain dream --dir .`)
- sync.repo_path config (in case it was ever stored relative)
resolveBrainDir already checked existsSync; resolve() just canonicalizes
before return. No behavior change for paths already absolute.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---------
Co-authored-by: Matt Gunnin <mgunnin@esports.one>
Co-authored-by: Brandon Lipman <brandon@offdeck.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Jeremy Knows <jeremy@veefriends.com>
Co-authored-by: root <root@localhost>
Co-authored-by: orendi84 <orendigergo@gmail.com>
Co-authored-by: orendi84 <orendi84@users.noreply.github.com>
Co-authored-by: Garry Tan <garry@ycombinator.com>
* fix: resolve check-resolvable warnings on master
- skills/maintain/SKILL.md: drop "citation audit" trigger; the focused
citation-fixer skill is the single owner. Silences the MECE overlap
warning surfaced by src/core/check-resolvable.ts.
- skills/RESOLVER.md: add citation-audit disambiguation row pointing
citation-fixer (focused fix) and chain-into maintain for broader audit.
Broaden query triggers ("who is", "background on", "notes on") so
the failing routing-eval fixtures resolve.
- skills/enrich/SKILL.md: replace inlined Citation Requirements block with
backtick-wrapped `skills/conventions/quality.md` reference (the format
extractDelegationTargets recognizes). Silences the dry_violation warning.
- skills/citation-fixer/routing-eval.jsonl: rewrite the two failing fixtures
to embed "fix citations" verbatim so the substring matcher passes.
- skills/query/SKILL.md frontmatter: mirror the broadened RESOLVER.md
triggers so the trigger round-trip test passes.
Result: gbrain check-resolvable reports 0 warnings, 0 errors against
the actual checked-in skills/ tree.
* feat: extend parseMarkdown + lint with frontmatter validation surface
Add an opt-in validation surface to parseMarkdown(): when called with
{ validate: true }, returns errors[] populated with seven canonical
ParseValidationError codes:
MISSING_OPEN, MISSING_CLOSE, YAML_PARSE, SLUG_MISMATCH,
NULL_BYTES, NESTED_QUOTES, EMPTY_FRONTMATTER
Existing callers are unaffected — validation is opt-in via the new
opts argument. The validation logic lives here as the single source of
truth for what counts as malformed brain-page frontmatter.
src/commands/lint.ts now consumes parseMarkdown(..., { validate: true })
and emits stable lint rule names (frontmatter-missing-close,
frontmatter-yaml-parse, frontmatter-null-bytes, frontmatter-nested-quotes,
frontmatter-slug-mismatch, frontmatter-empty). MISSING_OPEN is suppressed
to avoid double-reporting with the legacy no-frontmatter rule.
Tests: test/markdown-validation.test.ts (NEW, all 7 codes) +
test/lint-frontmatter.test.ts (NEW, lint integration + suppression).
* feat: add brain-writer.ts orchestrator (scan / autoFix / writeBrainPage)
Thin orchestrator (~280 lines) on top of parseMarkdown(..., {validate:true})
and isSyncable() (the canonical brain-page filter from src/core/sync.ts).
Three consumers call into this module: the gbrain frontmatter CLI, the
frontmatter_integrity doctor subcheck, and the v0.22.4 migration audit
phase. Single source of truth — no parallel validation stack.
Public API:
- autoFixFrontmatter(content, opts?): { content, fixes }
Mechanical auto-repair for the fixable subset (NULL_BYTES,
MISSING_CLOSE, NESTED_QUOTES, SLUG_MISMATCH). Idempotent.
- writeBrainPage(filePath, content, opts): path-guarded, .bak backup
before any in-place mutation. Path guard refuses writes outside
sourcePath. .bak is the safety contract for non-git brain repos.
- scanBrainSources(engine, opts?): walks every registered source via
direct SQL on sources.local_path, uses isSyncable() to filter,
blocks symlinks (matches sync's no-symlink policy), respects
AbortSignal.
The dirty-tree guard from src/core/dry-fix.ts:getWorkingTreeStatus() is
NOT used here — it rejects non-git repos as unsafe, but brain repos
aren't always git repos. .bak backups are the contract that works
universally.
Tests: test/brain-writer.test.ts (NEW, 16 cases) — autoFix idempotency,
path-guard reject, .bak backup, per-source rollup, AbortSignal mid-scan,
single-source filter, missing-source-path graceful skip, symlink no-loop.
* feat: gbrain frontmatter CLI (validate / audit / install-hook)
New top-level command surface for the frontmatter-guard feature:
gbrain frontmatter validate <path> [--json] [--fix] [--dry-run]
Validate one .md file or recursively scan a directory. --fix writes
.bak then rewrites in place. No git-tree-clean guard — .bak is the
safety contract (works for both git and non-git brain repos).
gbrain frontmatter audit [--source <id>] [--json]
Read-only scan via scanBrainSources(). Per-source rollup grouped by
error code. --fix is intentionally NOT available here; use validate
--fix on the source path to repair.
gbrain frontmatter install-hook [--source <id>] [--force] [--uninstall]
Drops a pre-commit hook in each source that's a git repo (skips
non-git sources with a one-line note). Hook script gracefully
degrades when gbrain is missing on PATH (prints a warning, exits 0).
Refuses to clobber existing hooks without --force; writes <hook>.bak.
--uninstall reverses cleanly.
src/cli.ts wires frontmatter through handleCliOnly so --help works
without a DB connection. The audit subcommand instantiates an engine
internally only when needed.
Tests: test/frontmatter-cli.test.ts (NEW, 9 cases) +
test/frontmatter-install-hook.test.ts (NEW, 6 cases) — --help no-DB,
clean/broken validate, --fix dry-run, --fix non-git, --json envelope,
recursive directory scan with isSyncable filter parity, hook install
+ overwrite-protection + --force + --uninstall + silent-refresh.
* feat: doctor frontmatter_integrity subcheck
Adds a frontmatter_integrity subcheck under gbrain doctor that calls
scanBrainSources() (the same shared scanner the CLI and migration use).
Reports per-source counts grouped by error code, with a fix hint
pointing at `gbrain frontmatter validate <path> --fix`. Wrapped in
a doctor progress phase with heartbeat so 50K-page brain scans stay
visible.
Tests: test/doctor.test.ts (UPDATE) — assertion that the subcheck
calls scanBrainSources and the fix hint references the correct CLI.
* feat: frontmatter-guard skill (registered in manifest + RESOLVER)
New skill at skills/frontmatter-guard/SKILL.md that wraps the gbrain
frontmatter CLI for agent-driven workflows. Agent-agnostic — no
references to private host libraries. Registered in skills/manifest.json
and skills/RESOLVER.md (the trigger row was added in the Part A commit).
Triggers: "validate frontmatter", "check frontmatter", "fix frontmatter",
"frontmatter audit", "brain lint".
Includes routing-eval fixtures that pass the substring matcher. The
SKILL.md has the conformance-required Output Format and Anti-Patterns
sections. Anti-patterns explicitly call out: don't auto-fix MISSING_OPEN
or EMPTY_FRONTMATTER without user input, don't skip .bak backups, don't
install the pre-commit hook on non-git brain dirs.
* feat: v0.22.4 migration orchestrator (audit-only, source-aware)
Adds the v0.22.4 migration that surveys every registered source for
frontmatter issues and queues per-source repair commands without ever
mutating brain content. Three idempotent phases:
- schema: no-op (no DB changes in v0.22.4)
- audit: scanBrainSources() across ALL registered sources; writes
JSON report to ~/.gbrain/migrations/v0.22.4-audit.json
- emit-todo: appends one entry per source-with-issues to
~/.gbrain/migrations/pending-host-work.jsonl, each with the exact
`gbrain frontmatter validate <source-path> --fix` command
The agent reads skills/migrations/v0.22.4.md after upgrade, surfaces
the report counts to the user, and runs the fix command only with
explicit consent. `apply-migrations --yes` never silently rewrites
brain pages.
Filename convention: TS orchestrator at v0_22_4.ts (underscores, since
TS module paths can't have dots); user-facing migration doc at
skills/migrations/v0.22.4.md (dotted, matches existing convention).
The pending-host-work.jsonl skill field references the dotted-path doc.
Skips cleanly when no sources are registered (fresh install).
Tests: test/migrations-v0_22_4.test.ts (NEW, 9 cases) + updated
test/migration-orchestrator-v0_21_0.test.ts to allow v0.22.4 after,
test/apply-migrations.test.ts skippedFuture arrays extended to include
v0.22.4, test/check-resolvable.test.ts regression guard asserting the
actual checked-in skills/ tree has 0 warnings + 0 errors.
* docs: pre-commit recipe + downstream agent upgrade notes for v0.22.4
- docs/integrations/pre-commit.md (NEW): recipe doc covering install,
bypass (`git commit --no-verify`), uninstall, and downstream-fork
integration notes. Includes the full pipeline diagram showing how
the hook (write-time gate), doctor (audit gate), and CLI (fix tool)
share parseMarkdown(..., {validate:true}) as the single source of
truth.
- docs/UPGRADING_DOWNSTREAM_AGENTS.md: append v0.22.4 section with the
diff pattern for forks that had inline frontmatter validators. Covers
the five upgrade actions: replace ad-hoc validators, drop
lib/brain-writer.mjs references (it never shipped), wire the doctor
subcheck into custom health pipelines, optionally install the
pre-commit hook on git-backed brain repos, and walk
pending-host-work.jsonl after apply-migrations.
- llms.txt + llms-full.txt: regenerated from build:llms script after
the new docs landed.
* chore: bump version and changelog (v0.22.4)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* fix: handle null loadConfig() return in frontmatter + migration paths
CI typecheck caught three call sites that passed loadConfig()'s
GBrainConfig | null result straight into toEngineConfig() (which
expects GBrainConfig, not null):
- src/commands/frontmatter.ts:64 (audit subcommand connect)
- src/commands/frontmatter-install-hook.ts:86 (install-hook connect)
- src/commands/migrations/v0_22_4.ts:59 (audit phase connect)
The frontmatter CLI and install-hook paths follow the existing
src/commands/repair-jsonb.ts pattern: throw 'No brain configured. Run:
gbrain init' so users get an actionable message instead of a TS-shaped
runtime crash.
The v0.22.4 migration audit phase takes a different shape: a fresh
install or test environment running apply-migrations shouldn't fail
hard just because there's no brain to scan yet. Return a clean
'skipped: no_brain_configured' phase result so the orchestrator
continues normally and the ledger records a complete (skipped) run.
* test: add v0.22.4 migration E2E + injection point for testability
Closes plan item B14 (the E2E that was promised but not delivered before
the original ship). Runs the v0_22_4 orchestrator end-to-end on PGLite
against a fixture brain with two registered sources and synthetic
malformed pages on disk. Asserts:
- audit phase writes ~/.gbrain/migrations/v0.22.4-audit.json with
per-source counts (NESTED_QUOTES + NULL_BYTES on alpha,
NESTED_QUOTES on beta)
- emit-todo phase appends one entry per source-with-issues to
pending-host-work.jsonl, each pointing at skills/migrations/v0.22.4.md
with the exact `gbrain frontmatter validate <source> --fix` command
- the migration is audit-only — no fixture page is mutated
during apply-migrations (no .bak created, contents byte-identical)
- re-running the orchestrator is idempotent — JSONL stays at 2 lines
Adds a small test-injection point to v0_22_4.ts:
__setTestEngineOverride(engine: BrainEngine | null): void
Mirrors src/commands/repair-jsonb.ts pattern. When set, phaseBAudit
uses the injected engine instead of loadConfig + createEngine. Production
path is unchanged: the override is null by default and the existing
loadConfig logic runs end-to-end. Required because Bun's os.homedir()
does not observe mid-process process.env.HOME mutations, so we can't
redirect loadConfig's config-file lookup via env-var overrides; the
injection point is the only hermetic way to E2E-test the orchestrator
without writing to the user's real ~/.gbrain/config.json.
Test runs unconditionally in CI's Tier 1 (no DATABASE_URL needed,
PGLite in-memory).
---------
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
