mirror of
https://github.com/garrytan/gbrain.git
synced 2026-07-27 22:15:33 +00:00
814258dda67945ffec9457a1e73980e947b7e462
2
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
f1f9199ff4 |
v0.37.7.0 fix wave: federated brains + autopilot safety + OAuth confidential clients (#1253)
* fix(reindex-frontmatter): connect engine before query (#1225) `createEngine()` from src/core/engine-factory.ts only constructs the engine; callers MUST call connect() before any executeRaw. The reindex-frontmatter CLI was constructing the engine and going straight to countAffected, which crashed on PGLite with "PGLite not connected. Call connect() first." even on --dry-run. Fix follows the existing-command pattern (src/commands/auth.ts, src/commands/backfill.ts, src/commands/integrity.ts all do the same): pass toEngineConfig(cfg) into both createEngine() AND engine.connect(), then engine.initSchema() (idempotent on a current schema, ~1ms cost). Pre-fix verification: codex outside-voice CF5 flagged the related "can't import connectEngine from cli.ts" misdirection in the original fix plan. This implementation uses the canonical sibling pattern instead. Regression test pinned at test/reindex-frontmatter-connect.test.ts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: bump VERSION to 0.37.7.0 + stub CHANGELOG v0.37.5.0 claimed by #1229 (warsaw-v4); v0.37.6.0 by #1246 (OpenRouter recipe). v0.37.7.0 is the next free slot for this fix wave. CHANGELOG entry stubbed in user-facing voice per CLAUDE.md "CHANGELOG voice + release-summary format" — ELI10 lead-first, real fix details below. The "## To take advantage of v0.37.7.0" block follows the v0.13+ self-repair pattern from CLAUDE.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(subagent): short-circuit terminal-on-resume (#1151) Bug: when the worker resumed a subagent job whose persisted last message was an assistant turn with text-only content (no tool_use blocks), the replay reconciler at subagent.ts:241-247 had no branch for that case. The main loop then called messages.create against a conversation ending in assistant role, which Sonnet 4.6+ rejects with HTTP 400 "This model does not support assistant message prefill." 3 retries later → dead-letter, despite all the job's work having committed in earlier turns. @zscgeek's bug report pinned this exactly: dream-cycle Otter corpus runs hit ~7% dead-letter rate, every dead job's last subagent_messages row was a text-only synthesis summary listing slugs that already existed in `pages`. Their proposed fix mirrors this implementation. Fix: add an else branch to the assistant-tail check that mirrors the live-loop terminal logic at subagent.ts:440-447 — reconstruct finalText from the persisted text blocks, return stop_reason='end_turn' immediately. No LLM call, no schema change. Two new regression cases: - text-only terminal on resume returns immediately with zero messages.create calls - tool-use replay path unchanged (existing behavior preserved) Codex outside-voice (CF13) initially flagged this fix as mis-targeted, claiming subagent.ts already handled the case. /investigate run revealed the live-loop terminal at :440-447 was covered but the REPLAY-path terminal at :241-247 was missing — both branches need symmetric handling. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(autopilot): scope lockfile to GBRAIN_HOME (#1226) The autopilot lockfile was hardcoded at `~/.gbrain/autopilot.lock` (via `process.env.HOME`), bypassing GBRAIN_HOME. Two brains pointed at different GBRAIN_HOME directories still wrote to the same global lockfile; one would silently take over the other on each restart. Fix: route through `gbrainPath('autopilot.lock')` from src/core/config.ts (imported aliased as gbrainHomePath since the local `gbrainPath` var in installAutopilot references the CLI binary path). The mkdirSync(`~/.gbrain`) call also routes through the helper so the directory is created in the right place too. Co-authored with @rafaelreis-r — same fix shape as PR #1227, re-implemented against current master per the wave's "re-implement, credit, close" workflow. Tests cover: one GBRAIN_HOME → one canonical lock; two GBRAIN_HOME values → two distinct locks; default fall-through still works. Co-Authored-By: rafaelreis-r <noreply@github.com> Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(graph-query): foreign-edge footer + --include-foreign (#1153) The graph-query CLI silently dropped edges to pages in other sources on federated brains. Users had no signal those edges existed unless they read the source code. Fix: - New --include-foreign flag (off by default, preserves the existing scoping contract; on = explicit cross-source traversal). - After every traversal, count edges from rootSlug whose target page lives in a different source. When count > 0 AND user didn't opt in, emit a stderr footer: `(N edge(s) to foreign-source pages hidden; pass --include-foreign to include them)` - The "no edges found" path also runs the count + footer so users discover foreign edges even when scoped traversal returned nothing. - Thin-client path skips the count (engine query not available); future T1 work threads source resolution through MCP for that path. - Single quotation correctness in count SQL: page_links table is `links` (not `page_links`); JOIN both endpoints to pages and compare source_id, NULL-safe via `IS NOT NULL` guards on both sides. - Fail-open on missing source_id column for pre-v0.18 brains: return 0 (no foreign edges to report) instead of throwing. 4 new test cases: footer fires on scoped query with foreign edge, --include-foreign suppresses footer, zero-foreign no-footer case, pluralization regression guard. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(sources): `gbrain sources current` + tier attribution (#1222) Federated-brain users running destructive ops (extract, import, purge) need a way to verify which source they're targeting BEFORE the op runs. Pre-fix, the only way was to grep config files or run the op with --dry-run and inspect output. New command: gbrain sources current # human output gbrain sources current --json # machine-readable gbrain sources current --source X # show what an explicit --source # X would resolve to (validates # X exists in the sources table) Output names BOTH the resolved source id AND which tier of the 6-tier resolution chain won (flag / env / dotfile / local_path / brain_default / seed_default), plus a `detail` line naming the winning signal (e.g. "GBRAIN_SOURCE=dept-x" or ".gbrain-source" or "/work/gstack/src"). Implementation: - New `resolveSourceWithTier()` in source-resolver.ts as an additive variant of `resolveSourceId()`. Walks the same 6 steps in the same order; just returns `{ source_id, tier, detail? }` instead of bare string. Existing `resolveSourceId()` unchanged — all callers continue working. - New `SOURCE_TIER_NAMES` const + `SourceTier` type export so the CLI, doctor (Tier 5 follow-up), and future MCP consumers share one vocabulary instead of inlining strings. - Help text updated; `current` subcommand registered in dispatcher. 11 new tests pin the 6-tier ladder + priority semantics. Existing 19 source-resolver tests still pass (regression preserved). Per codex CF3 (the existing src/core/source-resolver.ts was missed in the original plan). Re-uses the existing helper instead of inventing a duplicate. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(extract): --source-id scopes extraction to one brain source (#1204) Federated brain users running `gbrain extract` had no way to scope extraction to one source. The DB path walks all sources together via listAllPageRefs(), which is correct for cross-source resolution but sometimes the user wants to extract per-source explicitly (e.g. re-running extract on a specific source after a manual import). The pre-existing `--source` flag is the data-source axis (fs|db) and can't be repurposed. New flag `--source-id <id>` joins it on the brain-source-id axis: gbrain extract all --source db --source-id alpha -> walks only alpha-source pages; extracts links + timeline from those, into the alpha source Important: the resolver maps (allSlugs + slugToSources) stay built from the FULL listAllPageRefs result, not the scoped subset. This ensures qualified cross-source wikilinks like `[[other-src:slug]]` still resolve correctly even when the extract walk is scoped — the filter is on which pages we extract FROM, not what we can resolve TO. Threaded through both `extractLinksFromDB` and `extractTimelineFromDB` with backward-compat: callers passing no opts get the old behavior. 4 new test cases pin: walks-all-without-flag baseline, alpha-only-when-scoped-to-alpha, beta-only-when-scoped-to-beta, empty-set-on-unknown-source. Note: #1204's wider "silent 0 links" report on federated brains has additional facets beyond this flag (resolver path edge cases on overlapping slugs). The scoped-walk fix gives users an explicit workaround AND closes the per-source extraction gap. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(todos): file v0.37.7.0 follow-ups (#1173, #1204, T5N) Three items deferred from v0.37.7.0: 1. #1173 .sql indexing — verify-first gate found tree-sitter-sql.wasm missing from src/assets/wasm/grammars/. Dedicated wave needed: vendor the wasm, add .sql to walker filter, address slug-shape collision with #1172. 2. #1204 deeper investigation — wave added --source-id flag as workaround. Underlying silent-zero-links bug on unscoped federated extracts needs its own /investigate pass against a cross-source-duplicate-slug fixture. 3. Tier 5N doctor sweep for dead-lettered subagent jobs matching the #1151 fingerprint. Deferred to v0.37.8+ behind the islamabad doctor.ts conflict resolution. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(sync): walker skips git submodule directories (#1169) Sync walker descended into git submodules and indexed their markdown content as if it belonged to the parent brain. Users with submodules in their brain repo saw foreign content in their pages table. Fix: pruneDir gains an optional `parentDir` arg. When set, the helper stats `<parentDir>/<name>/.git` and skips the directory if `.git` exists as a FILE (gitfile pointer — the canonical submodule shape). Directories containing `.git` as a DIRECTORY (a real nested repo, not a submodule) are descended into; the inner `.git` dir itself is then dot-prefix-excluded. Callers updated to pass parentDir: - src/commands/extract.ts walkMarkdownFiles - src/core/cycle/transcript-discovery.ts walker Back-compat preserved: existing pruneDir(name) callers without parentDir get the pre-v0.37.7.0 behavior unchanged. Companion `.gitignore`-respect feature from PR #1159 (@jetsetterfl) NOT in this wave — it would require adding the `ignore` npm package as a dep, which the plan's "no new deps in this PR" gate excludes. Filed as follow-up TODO for a dedicated wave. 5 new test cases pin the submodule shape + back-compat + nested-repo ambiguity. Existing extract-fs / extract-db tests unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(brain-routing): document 6-tier source resolution chain (#1222) The convention skill didn't have a tier-by-tier reference for how gbrain resolves the active source. Users running federated brains had to read the source code to know which signal wins. Added: - Canonical 6-tier table (flag → env → dotfile → local_path → brain_default → seed_default) matching src/core/source-resolver.ts. - Pointer to `gbrain sources current` (new in v0.37.7.0) as the verification command. - The CLI-layer trust boundary note: operations.ts handlers don't read env/dotfile (preserves v0.34.1.0 source-isolation work for MCP callers). - Per-command flag map: --source, --source-id (extract), and --include-foreign (graph-query). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(import): --source-id flag routes pages to a brain source (#1167) `gbrain import --source dept-x ./pages` silently fell back to the default source because the CLI parser never consumed --source. PR #707's design intent excluded the flag explicitly; users had no signal their pages were going to the wrong place. #1167 + #1222 filed the regression. Fix: parse `--source-id <id>` (matching v0.37.7.0 extract.ts T2's naming convention — --source-id stays out of conflict with future axes that may want --source). When set, the flag value wins over any programmatic opts.sourceId; back-compat preserved for callers that pass sourceId via opts only. Also threaded into the positional-dir arg parser's flagValues set so `--source-id <value> <dir>` doesn't treat <value> as the dir. Note on related surfaces: - `gbrain query "X" --source_id dept-x` already routed correctly via the operations.ts query op (added in v0.34) — no fix needed. - `gbrain extract --source-id <id>` shipped in T2. - `gbrain sync --source <id>` already worked (pre-existing). - `gbrain sources current` (shipped in T4) is the verification tool — run it before destructive ops to confirm routing. Closes the silent-fallback for the import path. Co-authored with @tyad67-netizen (#1168), @hnshah (#1124, #1120), whose patches informed the shape; re-implemented against current master per the wave's "re-implement, credit, close" workflow. 3 new test cases pin: default-without-flag, --source-id-routes-correctly, flag-value-not-treated-as-dirArg. Co-Authored-By: tyad67-netizen <noreply@github.com> Co-Authored-By: hnshah <noreply@github.com> Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(autopilot): reconnect classifier + launchd ThrottleInterval (#1162) Pre-fix: when database_url was unset/malformed, the DB-health-check reconnect loop logged `config.database_url undefined` forever because the catch swallowed every error type uniformly. launchd's KeepAlive=true respawned immediately on any exit, so even when the process did exit, it came right back into the same bad state. @colin477 reported the daemon-thrash pattern. Two-part fix: 1. In-process error classifier — `classifyReconnectError(err)`: - `unrecoverable` (database_url missing/empty/malformed, auth failure, no-brain-configured): exit immediately with a clear stderr line. Pattern-matched against postgres / config-loader error shapes. Tests pin the matcher against the #1162 fingerprint exactly. - `recoverable` (network blip, pool saturated, connection refused on a port coming up, Supabase 503): retry. Up to GBRAIN_AUTOPILOT_MAX_RECONNECT_FAILS (default 30 = ~5min) before finally giving up with `max_reconnect_fails_exceeded`. - Counter resets on every successful health probe or reconnect. 2. launchd plist gains `ThrottleInterval=60`. Combined with the in-process exit, launchd waits 60s before relaunching instead of immediate respawn. Pure-function `generateLaunchdPlist()` exported for tests. 16 new test cases: - 11 classifier cases (database_url shapes, malformed URL, auth, role-does-not-exist with quoted name, network blip, pool saturated, 503, non-Error inputs, case-insensitivity) - 5 plist generator cases (ThrottleInterval=60, KeepAlive preserved, wrapper path, XML escaping, StandardErrorPath). Pre-existing autopilot-lock-path tests unchanged — both fixes land cleanly side-by-side. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(oauth): confidential clients via custom /token middleware (#1166) v0.34.1.0 (#909) fixed PUBLIC PKCE clients (client_secret=undefined) by normalizing NULL → undefined in getClient. Confidential clients regressed: the MCP SDK's clientAuth middleware does plaintext `client.client_secret !== presented_secret` compare, but gbrain stores SHA-256 hashes, so the SDK's compare always failed for authorization_code and refresh_token grants on confidential clients. Result: /token returned `invalid_client` for every confidential exchange. Fix shape per locked-decision-5: custom /token middleware BEFORE the SDK's authRouter, similar to the pre-existing client_credentials handler. The middleware: 1. Detects confidential auth via `client_secret` in body (client_secret_post) OR `Authorization: Basic` header (client_secret_basic per RFC 6749 §2.3.1). 2. Falls through to the SDK when neither is present (public PKCE path stays canonical, preserves v0.34.1.0 behavior). 3. Calls new `verifyConfidentialClientSecret(clientId, presented)` on the provider which does SHA-256 hash compare ourselves (same shape as exchangeClientCredentials' existing hash check). 4. On verification success, calls existing `exchangeAuthorizationCode` / `exchangeRefreshToken` directly with the validated client. 5. RFC 6749 §5.2 error semantics: 401 invalid_client for auth failures, 400 invalid_grant for code/token problems. Per CLAUDE.md "GBRAIN:RLS_EXEMPT" annotation contract: this surface sits in front of the SDK's clientAuth and doesn't depend on the SDK's plaintext compare working — the SDK's middleware never fires for confidential paths the new middleware claims. 7 new test cases pin: correct-secret-returns-client, wrong-secret opaque rejection, non-existent client, public-client refuses the confidential path, case-sensitivity, soft-deleted revocation, verify-then-exchange-refresh round-trip with second-use rejection. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(doctor): 3 new checks — source routing + oauth + autopilot lock (T12/T13/T14) Three v0.37.7.0 doctor checks landing in one atomic commit (single file, shared merge-conflict surface with garrytan/islamabad-v3 per locked decision 1): 1. source_routing_health (T12 / #1167): Sample non-default sources for pages; warn when a registered source has zero pages (silent-collapse-to-default fingerprint). D5 lock: total-sample cap of 200 pages across all sources, with per-source cap = min(50, ceil(200/N)) so a 20-source CEO brain pays 200 selects, not 1000. Fix hint paste-ready to `gbrain sources current --json` for verification. 2. oauth_confidential_client_health (T13 / #1166): Probe every oauth_clients row. Confidential clients (auth_method != 'none') must have a non-NULL client_secret_hash; if any row claims confidential auth but stores NULL hash, that's the pre-v0.37.7.0 regression. Public clients (auth_method='none') correctly keep NULL hash per v0.34.1.0 #909. Fix hint: `gbrain auth revoke-client + register-client` OR `gbrain upgrade`. Pre-OAuth schemas (missing oauth_clients table) skip gracefully. 3. autopilot_lock_scope (T14 / #1226): Detect stale ~/.gbrain/autopilot.lock outside the current GBRAIN_HOME. Codex CF11: dangerous to paste-ready `rm` without verifying the owning PID isn't a live process. Hint reads the PID file and gives the user a `ps -p <pid>` check before any delete — matches sshd-style stale-lock recovery hints. 9 new test cases pin the canonical paths. Pre-existing 80+ doctor checks unchanged. Expected to conflict with garrytan/islamabad-v3 at merge time. The 3 new check functions live in their own block far from the islamabad skill_brain_first check; the conflict surface should be limited to the `checks.push(...)` call site near the end of runDoctor's DB-checks phase (~10 lines). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(test): withEnv wrapper in source-resolver-with-tier (test-isolation lint) The new source-resolver-with-tier.test.ts from T4 mutated process.env.GBRAIN_SOURCE directly in two cases, which violates scripts/check-test-isolation.sh R1 (env mutations leak across parallel-loaded test files in the same shard process). Fix: wrap both mutation sites in withEnv() from test/helpers/with-env.ts, which saves+restores via try/finally per the canonical pattern in CLAUDE.md. Pure refactor — all 11 cases still green. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: update project documentation for v0.37.7.0 CHANGELOG.md — populated the "What landed" stub with the 18-commit brisbane wave (source-id flag threading, sources current subcommand, graph-query foreign-edge footer, autopilot lockfile scope + reconnect classifier + launchd ThrottleInterval, OAuth confidential client middleware, reindex-frontmatter connect fix, subagent terminal-on-resume fix, sync walker submodule skip, 3 new doctor checks, brain-routing.md convention skill). Voice: ELI10 lead, capability table, paste-ready verification, "what's safe to know" + "what we caught" sections. CLAUDE.md — extended Key Files annotations for the v0.37.7.0 changes: import/extract --source-id flags, sources current subcommand, graph-query --include-foreign, resolveSourceWithTier() additive helper, autopilot classifyReconnectError + generateLaunchdPlist exports, OAuth confidential client middleware, pruneDir submodule detection, subagent terminal short-circuit, 3 new doctor checks. Pinned by their test files. llms-full.txt — regenerated via `bun run build:llms` (CI guard at test/build-llms.test.ts will fail otherwise). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: rafaelreis-r <noreply@github.com> |
||
|
|
81b3f7afac |
feat: knowledge graph layer — auto-link, typed relationships, graph-query (v0.10.3) (#188)
* feat(schema): graph layer migrations v5/v6/v7 + GraphPath/health types
Schema foundation for v0.10.3 knowledge graph layer:
- v5: links UNIQUE constraint widened to (from, to, link_type) so the same
person can both works_at AND advises the same company as separate rows.
Idempotent for fresh + upgrade (drops both old constraint names first).
- v6: timeline_entries gets UNIQUE index on (page_id, date, summary) for
ON CONFLICT DO NOTHING idempotency at DB level.
- v7: drops trg_timeline_search_vector trigger. Structured timeline entries
are now graph data, not search text. Markdown timeline still feeds search
via the pages trigger. Side benefit: extraction pagination is no longer
self-invalidating (trigger used to bump pages.updated_at on every insert).
Types: new GraphPath (edge-based traversal result), PageFilters.updated_after,
BrainHealth gets link_coverage / timeline_coverage / most_connected. Postgres
schema regenerated via build:schema.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(graph): auto-link on put_page + extract --source db + security hardening
Core graph layer wired into the operation surface:
- New src/core/link-extraction.ts: extractEntityRefs (canonical extractor used
by both backlinks.ts and the new graph code), extractPageLinks (combines
markdown refs + bare-slug scan + frontmatter source, dedups within-page),
inferLinkType (deterministic regex heuristics for attended/works_at/
invested_in/founded/advises/source/mentions), parseTimelineEntries (parses
multiple date format variants from page content), isAutoLinkEnabled
(engine config flag, defaults true, accepts false/0/no/off case-insensitive).
- put_page operation auto-link post-hook: extracts entity refs from freshly
written content, reconciles links table (adds new, removes stale). Returns
auto_links: { created, removed, errors } in response so MCP callers see
outcomes. Runs in a transaction so concurrent put_page on same slug can't
race the reconciliation. Default on; opt out with auto_link=false config.
- traverse_graph operation extended with link_type and direction params.
Returns GraphPath[] (edges) when filters set, GraphNode[] (nodes) for
backwards compat. Depth hard-capped at TRAVERSE_DEPTH_CAP=10 for remote
callers; without this, depth=1e6 from MCP burns memory on the recursive CTE.
- gbrain extract <links|timeline|all> --source db: walks pages from the
engine instead of from disk. Works for live brains with no local checkout
(MCP-driven Wintermute / OpenClaw). Filesystem mode (--source fs) is
unchanged. New --type and --since filters with date validation upfront
(invalid --since used to silently no-op the filter and reprocess everything).
- Security: auto-link skipped for ctx.remote=true (MCP). Bare-slug regex
matches `people/X` anywhere in page text including code fences and quoted
strings. Without this gate an untrusted MCP caller could plant arbitrary
outbound links by writing pages with intentional slug references; combined
with the new backlink boost, attacker-placed targets would surface higher
in search.
- Postgres orphan_pages aligned to PGLite definition (no inbound AND no
outbound). Comment used to claim alignment but code disagreed; engines
drifted silently when users migrated.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(cli): graph-query command + skill updates + v0.10.3 migration file
Agent-facing surface for the graph layer:
- New `gbrain graph-query <slug>` command with --type, --depth, --direction
in|out|both. Maps to traverse_graph operation with the new filters. Renders
the result as an indented edge tree.
- skills/migrations/v0.10.3.md: agent runs this post-upgrade to discover the
graph layer. Tells the agent to run `gbrain extract links --source db`,
then timeline, verify with stats, try graph-query, and lists the inferred
link types so they can be used in subsequent traversals.
- skills/brain-ops/SKILL.md Phase 2.5: documents that put_page now auto-links.
No more manual add_link calls in the Iron Law back-linking path.
- skills/maintain/SKILL.md: graph population phase. Shows the right command
to backfill links + timeline from existing pages.
- cli.ts: register graph-query in CLI_ONLY + handleCliOnly switch. Update help
text to describe `gbrain extract --source fs|db` and the new graph-query.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(graph): unit + e2e + 80-page A/B/C benchmark for graph layer
Coverage for the v0.10.3 graph layer (260+ new test assertions):
- test/link-extraction.test.ts (46 tests): extractEntityRefs both formats,
extractPageLinks dedup + frontmatter source, inferLinkType heuristics
(meeting/CEO/invested/founded/advises/default), parseTimelineEntries
multiple date formats + invalid date rejection, isAutoLinkEnabled
case-insensitive truthy/falsy parsing.
- test/extract-db.test.ts (12 tests): `gbrain extract <links|timeline|all>
--source db` happy paths, --type filter, --dry-run JSON output,
idempotency via DB constraint, type inference from CEO context.
- test/graph-query.test.ts (5 tests): direction in/out/both, type filter,
non-existent slug, indented tree output.
- test/pglite-engine.test.ts (+26 tests): getAllSlugs, listPages
updated_after filter, multi-type links via v5 migration, removeLink with
and without linkType, addTimelineEntry skipExistenceCheck flag,
getBacklinkCounts for hybrid search boost, traversePaths in/out/both with
cycle prevention via visited array, getHealth graph metrics
(link_coverage / timeline_coverage / most_connected).
- test/e2e/graph-quality.test.ts (6 tests): full pipeline against PGLite
in-memory. Auto-link via put_page operation handler. Reconciliation
removes stale links on edit. auto_link=false config skip.
- test/benchmark-graph-quality.ts: A/B/C comparison on 80 fictional pages,
35 queries across 7 categories. Hard thresholds: link_recall > 90%,
link_precision > 95%, timeline_recall > 85%, type_accuracy > 80%,
relational_recall > 80%. Currently passing all 9.
Built test-first: benchmark caught WORKS_AT_RE matching "founder" inside
slug names (frank-founder), "worked at" past-tense missing from regex,
PGLite Date object vs ISO string comparison bug. All fixed before merge.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore: bump version and changelog (v0.10.3)
CHANGELOG: knowledge graph layer headline. Auto-link on every page write.
Typed relationships (works_at, attended, invested_in, founded, advises).
gbrain extract --source db. graph-query CLI. Backlink boost in hybrid search.
Schema migrations v5/v6/v7 applied automatically.
Security hardening caught during /ship adversarial review: traverse_graph
depth capped at 10 from MCP, auto-link skipped for ctx.remote=true, runAutoLink
reconciliation in transaction, --since validates dates upfront.
TODOS.md: 2 P2 follow-ups (auto-link redundant SQL on skipped writes;
extract --source db not gated on auto_link config).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: sync CLAUDE.md with v0.10.3 graph layer
Updated key files list (extract.ts now describes --source fs|db, added
graph-query.ts and link-extraction.ts), test inventory (extract-db,
link-extraction, graph-query unit tests; e2e/graph-quality), and
test count (51 unit + 7 e2e, 1151 + 105 assertions).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(v0.10.3): wire graph layer into install flow + README + benchmark
Existing brains upgrading to v0.10.3 had no clear path to backfill the new
links/timeline tables. New installs had no instruction to run extract --source db
after import. This wires the knowledge graph into every install touchpoint so the
v0.10.3 features actually reach the user.
- README: headline now sells self-wiring graph + 94% benchmark numbers; new
Knowledge Graph section between Knowledge Model and Search; LINKS+GRAPH command
block expanded; Benchmarks docs group added
- INSTALL_FOR_AGENTS.md: new Step 4.5 (graph backfill) + Upgrade section now runs
gbrain init + post-upgrade and points to migrations/v<N>.md
- skills/setup/SKILL.md Phase C: new step 5 for graph backfill (idempotent,
skip-if-empty); existing file migration becomes step 6
- src/commands/init.ts: post-init hint detects existing brain (page_count > 0)
and prints extract commands for both PGLite and Postgres engines
- docs/GBRAIN_VERIFY.md: new Check #7 (knowledge graph wired) with backfill
fallback + graph-query smoke test
- docs/benchmarks/2026-04-18-graph-quality.md: checked-in benchmark report
matching the existing search-quality format (94% recall, 100% precision,
100% relational recall, idempotent both ways)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(claude): require PR descriptions to cover the whole branch
Adds a rule to CLAUDE.md so future PR bodies always cover the full diff
against the base branch, not just the most recent commit. Includes the
git log + gh pr view incantation to check what's actually in a PR.
This is a reaction to PR #189 being created with a body that described
only the last commit instead of the 7 commits it actually contained.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(upgrade): post-upgrade prints full body + --execute mode + downstream skill upgrade doc
PR #188 review caught two install-flow gaps that this commit closes:
1. `gbrain post-upgrade` only printed the migration headline + description
from YAML frontmatter, never the markdown body that contains the
step-by-step backfill instructions. Agents saw "Knowledge graph layer —
your brain now wires itself" and had no idea to run `gbrain extract
links --source db`. Now prints the full body after the headline.
2. New `--execute` flag reads a structured `auto_execute:` list from
migration frontmatter and runs the safe commands sequentially. Without
`--yes` it prints the plan only (preview mode). With `--yes` it actually
runs them. Stops on first failure with a clear error.
3. Downstream agents (Wintermute etc.) keep local skill forks that gbrain
can't push updates to. New `docs/UPGRADING_DOWNSTREAM_AGENTS.md` lists
the exact diffs each release needs applied to those forks. v0.10.3
diffs for brain-ops, meeting-ingestion, signal-detector, enrich.
Changes:
- src/commands/upgrade.ts:
- runPostUpgrade(args) accepts flags
- Prints full body via extractBody()
- Parses auto_execute: list via extractAutoExecute() (hand-rolled, no yaml dep)
- --execute previews, --execute --yes runs
- Fix cosmetic bug: `recipe: null` no longer prints "show null" message
- src/cli.ts: pass args to runPostUpgrade
- skills/migrations/v0.10.3.md:
- Add auto_execute: list (gbrain init + extract links/timeline + stats)
- Fix typo: completion record version was 0.10.1, now 0.10.3
- test/upgrade.test.ts: 5 new tests covering body printing, plan preview,
actual execution, no-auto_execute case, and --help output
- docs/UPGRADING_DOWNSTREAM_AGENTS.md: NEW
- CLAUDE.md: key files list updated
Test: 13 upgrade tests pass (was 8, +5 new). Full unit suite: 1078 pass,
zero regressions, 32 expected E2E skips (no DATABASE_URL).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* bench(graph): add Configuration A baseline (no graph) vs C comparison
Previous benchmark showed C numbers only (94.4% link recall, 100% relational
recall, etc.) but never quantified what a pre-v0.10.3 brain actually loses.
Reviewer caught this gap.
Adds measureBaselineRelational() that simulates a no-graph fallback:
- Outgoing queries: regex-extract entity refs from the seed page content
- Incoming queries: grep-style scan of all pages for the seed slug
This is what an agent without the structured links table can do today.
Honest result on the 5 relational queries in the benchmark:
- Recall: 100% A vs 100% C (+0%) — markdown contains the refs either way
- Precision: 58.8% A vs 100.0% C (+70%) — without typed links, you get the
right answers buried in 41% noise
Per-query breakdown shows the divergence is concentrated in INCOMING queries:
"Who works at startup-0?" returns 5 candidates without graph (2 employees +
3 noise pages that mention startup-0) vs exactly 2 with graph. For an LLM
agent, that's ~3x less reading work per relational question.
Also documented what the benchmark deliberately doesn't test (multi-hop,
search ranking with backlink boost, aggregate queries, type-disagreement
queries) so future benchmark work has a roadmap.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* bench(graph): add 4 missing categories — multi-hop, aggregate, type-disagreement, ranking
The previous benchmark commit (
|