mirror of
https://github.com/garrytan/gbrain.git
synced 2026-07-27 22:15:33 +00:00
5d42f3295e
* Merge branch 'master' into garrytan/type-taxonomy-unification Resolve VERSION, package.json, CHANGELOG conflicts with v0.41.22.0 on top, preserving master's v0.41.19.0 entry below. * feat: v0.41.22.0 type-unification cathedral — collapse 94 types to 15 (closes #1479) Ships gbrain-base-v2 as the new install default (15 canonical types: 14 + note catch-all) and the unify-types PROTECTED Minion handler that runs the gbrain-base→v2 migration end-to-end on existing brains. What this delivers: - gbrain-base-v2.yaml standalone schema pack (no extends:) with 14 canonical page_types + 9 cluster mapping_rules + catch-all sentinel - 3 new schema-pack primitives: runRetypeCore (chunked UPDATE with legacy_type stamping), runPageToLinkCore (edge-shaped pages → link rows), runPageToAliasCore (concept-redirect → slug_aliases) - rewriteLinksBatch for N-pair atomic FK rewrite - Migration v104 slug_aliases table (forward-bootstrap probed on both engines for safe upgrade chain) - New engine method resolveSlugWithAlias(slug, sourceOrSources) on both Postgres + PGLite with multi-source ambiguity warning - inferTypeAndSubtypeFromPack overload + subtypes: + mapping_rules: + migration_from: schema-pack manifest extensions - findPackSuccessors version-range walker (1.x / 1.0.x / exact match) - expandTypeFilter for --type back-compat (D14): legacy aliases route through mapping_rules → canonical+subtype before the SQL filter fires - 3 new onboard checks: pack_upgrade_available, type_proliferation, dangling_aliases (source-scoped per F12) - unify-types Minion handler (PROTECTED, manual_only via render.ts allowlist per D17): retype-explicit → retype-catch-all → page-to-link → page-to-alias → final sync → active-pack flip - alias_resolved 1.05x post-fusion search boost stage; KNOBS_HASH_VERSION bumped 5→6 (one-time cache miss on upgrade, self-healing in TTL) - ELIGIBLE_TYPES for facts extraction extended with v2 canonicals (codex F-ELIGIBLE: blocker not v0.43 follow-up) Tests: 79 new unit/integration cases + 3 E2E cases covering all 9 production clusters end-to-end. 124-case verification on the cache-key + build-llms fixes. KNOBS_HASH_VERSION assertions updated in 3 tests. Plan: ~/.claude/plans/system-instruction-you-are-working-transient-elephant.md (16 locked decisions D1-D17, 12 baseline fixes F7-F21 absorbed from codex outside voice). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix: CI verify failures — system-of-record allow-comment + schema-unify manifest registration Two CI failures on PR #1542: 1. check:system-of-record flagged page-to-link.ts:207 addLinksBatch as a direct write to a derived table. The call IS the reconcile surface for page_to_link mapping_rules — it converts edge-shaped pages into canonical link rows under the PROTECTED unify-types Minion handler, source-scoped, atomic per-rule. Added the canonical `// gbrain-allow-direct-insert: <reason>` comment on the same line. 2. check:resolver emitted 11 orphan_trigger warnings for `schema-unify` because the skill was added to skills/RESOLVER.md without a corresponding entry in skills/manifest.json. Added the registration under the existing skills[] array. bun run verify: 28/28 checks pass locally. * fix: CI test failures — schema-unify conformance + eligibility regression Six test failures across shards 2 + 10 on PR #1542: 1. resolver.test.ts: round-trip parser requires frontmatter triggers to be quoted (`- "..."` or `- '...'`). schema-unify shipped with bare YAML strings; quoted the 10 triggers to round-trip correctly. 2. skills-conformance.test.ts (×3): schema-unify SKILL.md was missing the required Contract, Anti-Patterns, and Output Format sections that every conformant skill must declare. Added all three: - Contract: inputs / outputs / side effects / failure modes - Anti-Patterns: 5 DON'Ts including the autopilot trust boundary - Output Format: per-phase stderr lines + celebration summary + JSON envelope shape 3. facts-eligibility.test.ts (×2): the v0.41.22 ELIGIBLE_TYPES expansion added `concept` to the eligible list, but the existing test suite pins concept as rejected (it's `extractable: true` in the schema pack but the v0.41.11 contract documented this as "cosmetic on the backstop path because backstop uses hardcoded ELIGIBLE_TYPES"). Removed `concept` from the expansion; other v2 canonicals (media, tweet, atom, analysis) stay. Comment updated to document the deliberate omission. All 6 failing tests now pass locally (370/370 across the 3 affected files). bun run verify: 28/28 checks green. * fix: harden findPackSuccessors test against shard pollution CI shard 8 reported 1 fail (1.00ms — too fast for any real loadActivePack file I/O) on `finds gbrain-base-v2 as successor of gbrain-base@1.0.0`. Local triple-run passes 9/9 in isolation. Root cause: the existing afterEach reset clears the module-level pack cache AFTER each test, but the FIRST test in the file inherits whatever state sibling files in the same bun shard process left behind. With 24+ schema-pack tests in shard 8 (mutate, mutate-audit, best-effort, registry-reload, manifest-v041_2, etc.) running before this file, the first test can read a poisoned cache. Fix: add `beforeEach(_resetPackCacheForTests)`. Two-sided reset guarantees clean state regardless of file ordering within the shard. bun run verify: 28/28 checks pass. * fix: quarantine two flaky tests to serial runner CI shard 1 + shard 8 each surfaced one intermittent failure: shard 1: buildBrainTools > execute() on put_page with valid namespace shard 8: findPackSuccessors > finds gbrain-base-v2 as successor Both pass cleanly in isolation. Both are concurrency races against shared in-shard state: - brain-allowlist.test.ts shares a singleton PGLiteEngine across 18 tests with a beforeEach DELETE FROM pages. With max-concurrency=4, two put_page tests can interleave their TRUNCATE + write phases, so the auto-link/extract sub-steps inside put_page race against the sibling test's DELETE. - schema-pack-find-pack-successors.test.ts reads bundled YAML packs via loadActivePack. The module-level pack cache is shared across parallel tests in the same shard; the previous beforeEach reset helped but didn't fully isolate against concurrent file reads under CI load. Fix per CLAUDE.md test-isolation lint rule R2 (concurrency-fragile files belong in the .serial.test.ts quarantine): rename both files to *.serial.test.ts. Serial runner picks them up at max-concurrency=1. 49/49 serial files pass locally. 28/28 verify checks pass. * fix: quarantine embed-stale test to serial runner CI shard 9 reported 6 failures, all from the embedStaleForSource describe block, all ~120-150ms each — classic shared-engine concurrency race shape. Passes 7/7 locally in isolation. Root cause: embed-stale.test.ts shares a singleton PGLiteEngine across 7 tests with beforeEach resetPgliteState. Under bun's max-concurrency=4 in the parallel shard, two tests can interleave their TRUNCATE + seedPage + upsertChunks + embedStaleForSource flow, so one test's stale-chunk count sees another test's mid-flight writes. Same fix as brain-allowlist.serial.test.ts and schema-pack-find-pack-successors.serial.test.ts: rename to *.serial.test.ts so the serial runner picks it up at max-concurrency=1. bun run verify: 28/28 checks pass. 7/7 embed-stale tests pass via serial. --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
10 KiB
10 KiB
GBrain Skill Resolver
This is the dispatcher. Skills are the implementation. Read the skill file before acting. If two skills could match, read both. They are designed to chain (e.g., ingest then enrich for each entity).
Always-on (every message)
| Trigger | Skill |
|---|---|
| Every inbound message (spawn parallel, don't block) | skills/signal-detector/SKILL.md |
| Any brain read/write/lookup/citation | skills/brain-ops/SKILL.md |
Brain operations
| Trigger | Skill |
|---|---|
| "What do we know about", "tell me about", "search for", "who is", "background on", "notes on" | skills/query/SKILL.md |
| "Who knows who", "relationship between", "connections", "graph query" | skills/query/SKILL.md (use graph-query) |
| Creating/enriching a person or company page | skills/enrich/SKILL.md |
| Where does a new file go? Filing rules | skills/repo-architecture/SKILL.md |
| "where does this brain page go", "file this in the brain", "brain taxonomist", "taxonomy check", "refile brain page", "which directory does this page go" | skills/brain-taxonomist/SKILL.md |
| "EIIRP", "everything in its right place", "store this research", "put this in the brain", "make this re-doable", "DRY this up", "file all of this", "organize all of this work", "archive this research thread" | skills/eiirp/SKILL.md |
| Fix broken citations in brain pages | skills/citation-fixer/SKILL.md |
| "citation audit", "check citations", "fix citations" | skills/citation-fixer/SKILL.md (focused fix). For broader brain health, chain into skills/maintain/SKILL.md |
| "Research", "track", "extract from email", "investor updates", "donations" | skills/data-research/SKILL.md |
| Share a brain page as a link | skills/publish/SKILL.md |
| "validate frontmatter", "check frontmatter", "fix frontmatter", "frontmatter audit", "brain lint" | skills/frontmatter-guard/SKILL.md |
| "what search mode", "is my cache hot", "tune my retrieval", "compare search modes", "clear search overrides" | gbrain search modes/stats/tune directly. See skills/conventions/search-modes.md |
| "eval results", "search benchmark", "haters-immune methodology", "regression check on retrieval" | gbrain eval run-all / gbrain eval compare. See docs/eval/SEARCH_MODE_METHODOLOGY.md |
Content & media ingestion
| Trigger | Skill |
|---|---|
| "capture this", "save this thought", "remember this", "drop this in the inbox", "save to brain" | skills/capture/SKILL.md |
| User shares a link, article, tweet, or idea | skills/idea-ingest/SKILL.md |
| "watch this video", "process this YouTube link", "ingest this PDF", "save this podcast", "process this book", "summarize this book", "PDF book", "ingest it into my brain", "what's in this screenshot", "check out this repo" | skills/media-ingest/SKILL.md |
| Meeting transcript received | skills/meeting-ingestion/SKILL.md |
| Generic "ingest this" (auto-routes to above) | skills/ingest/SKILL.md |
Thinking skills (from GStack)
| Trigger | Skill |
|---|---|
| "Brainstorm", "I have an idea", "office hours" | GStack: office-hours |
| "Review this plan", "CEO review", "poke holes" | GStack: ceo-review |
| "Debug", "fix", "broken", "investigate" | GStack: investigate |
| "Retro", "what shipped", "retrospective" | GStack: retro |
These skills come from GStack. If GStack is installed, the agent reads them directly. If not, brain-only mode still works (brain skills function without thinking skills).
Operational
| Trigger | Skill |
|---|---|
| Task add/remove/complete/defer/review | skills/daily-task-manager/SKILL.md |
| Morning prep, meeting context, day planning | skills/daily-task-prep/SKILL.md |
| Daily briefing, "what's happening today" | skills/briefing/SKILL.md |
| Cron scheduling, quiet hours, job staggering | skills/cron-scheduler/SKILL.md |
| Save or load reports | skills/reports/SKILL.md |
| "Create a skill", "improve this skill" | skills/skill-creator/SKILL.md |
| "Skillify this", "is this a skill?", "make this proper" | skills/skillify/SKILL.md |
| "Compress my resolver", "AGENTS.md too large", "RESOLVER.md too big", "functional area dispatcher", "shrink routing table" | skills/functional-area-resolver/SKILL.md |
| "Is gbrain healthy?", morning health check, skillpack-check | skills/skillpack-check/SKILL.md |
| "harvest this skill into gbrain", "publish this skill to gbrain", "lift this skill upstream", "share this skill with other gbrain clients", "promote my skill to gbrain" | skills/skillpack-harvest/SKILL.md |
| Post-restart health + auto-fix, "did the container restart break anything", smoke test | skills/smoke-test/SKILL.md |
| Cross-modal review, second opinion | skills/cross-modal-review/SKILL.md |
| "Validate skills", skill health check | skills/testing/SKILL.md |
| Webhook setup, external event processing | skills/webhook-transforms/SKILL.md |
| "Spawn agent", "background task", "parallel tasks", "steer agent", "pause/resume agent", "gbrain jobs submit", "submit a gbrain job", "submit a shell job", "shell job" | skills/minion-orchestrator/SKILL.md |
| "present options", "ask before proceeding", "choice gate", "user decision" | skills/ask-user/SKILL.md |
Setup & migration
| Trigger | Skill |
|---|---|
| "Set up GBrain", first boot | skills/setup/SKILL.md |
| "Now what?", "fill my brain", "cold start", "bootstrap", "import my data", "what should I import first" | skills/cold-start/SKILL.md |
| "Migrate from Obsidian/Notion/Logseq" | skills/migrate/SKILL.md |
| Brain health check, maintenance run | skills/maintain/SKILL.md |
| "Extract links", "build link graph", "populate timeline" | skills/maintain/SKILL.md (extraction sections) |
| "Run dream", "process today's session", "synthesize my conversations", "consolidate yesterday's conversations", "what patterns did you see", "did the dream cycle run" | skills/maintain/SKILL.md (dream cycle section) |
| "Brain health", "what features am I missing", "brain score" | Run gbrain features --json |
| "Set up autopilot", "run brain maintenance", "keep brain updated" | Run gbrain autopilot --install --repo ~/brain |
| Agent identity, "who am I", customize agent | skills/soul-audit/SKILL.md |
| "Populate links", "extract links", "backfill graph" | skills/maintain/SKILL.md (graph population phase) |
| "Populate timeline", "extract timeline entries" | skills/maintain/SKILL.md (graph population phase) |
Identity & access (always-on)
| Trigger | Skill |
|---|---|
| Non-owner sends a message | Check ACCESS_POLICY.md before responding |
| Agent needs to know its identity/vibe | Read SOUL.md |
| Agent needs user context | Read USER.md |
| Operational cadence (what to check and when) | Read HEARTBEAT.md |
Disambiguation rules
When multiple skills could match:
- Prefer the most specific skill (meeting-ingestion over ingest)
- If the user mentions a URL, route by content type (link → idea-ingest, video → media-ingest)
- If the user mentions a person/company, check if enrich or query fits better
- Chaining is explicit in each skill's Phases section
- When in doubt, ask the user (see
skills/ask-user/SKILL.mdfor the choice-gate pattern)
Conventions (cross-cutting)
These apply to ALL brain-writing skills:
skills/conventions/quality.md— citations, back-links, notability gateskills/conventions/brain-first.md— check brain before external APIsskills/conventions/brain-routing.md— which brain (DB) and which source (repo) to target; cross-brain federation is latent-space onlyskills/conventions/schema-evolution.md— when to add a type vs alias vs prefix (read beforeschema-author)skills/conventions/subagent-routing.md— when to use Minions vs inline workskills/ask-user/SKILL.md— choice-gate pattern for human input at decision pointsskills/_brain-filing-rules.md— where files goskills/_output-rules.md— output quality standards
Uncategorized
| Trigger | Skill |
|---|---|
| "personalized version of this book", "mirror this book", "two-column book analysis", "apply this book to my life", "how does this book apply to me" | skills/book-mirror/SKILL.md |
| "enrich this article", "enrich brain pages", "batch enrich", "make brain pages useful" | skills/article-enrichment/SKILL.md |
| "strategic reading", "read this through the lens of", "apply this to my problem", "what can I learn from this about", "extract a playbook from" | skills/strategic-reading/SKILL.md |
| "concept synthesis", "synthesize my concepts", "find patterns across my notes", "build my intellectual map", "trace idea evolution" | skills/concept-synthesis/SKILL.md |
| "perplexity research", "what's new about", "current state of", "web research", "what changed about" | skills/perplexity-research/SKILL.md |
| "crawl my archive", "find gold in my archive", "archive crawler", "scan my dropbox for", "mine my old files for" | skills/archive-crawler/SKILL.md |
| "verify this academic claim", "check this study", "academic verify", "validate citation", "is this study real" | skills/academic-verify/SKILL.md |
| "make pdf from brain", "brain pdf", "convert brain page to pdf", "publish this page as pdf", "export brain page" | skills/brain-pdf/SKILL.md |
| "voice note", "ingest this voice memo", "transcribe and file", "voice note ingest", "save this audio note" | skills/voice-note-ingest/SKILL.md |
| "add a page type", "add a type to my schema", "schema author", "schema mutate", "schema pack add", "my brain has untyped pages", "propose new types from my corpus", "backfill page types", "evolve my schema", "researcher type", "make X an expert type" (dispatcher for: gbrain schema active/list/show/validate/graph/lint/stats/explain/use/downgrade/reload/init/fork/edit/diff/add-type/remove-type/update-type/add-alias/remove-alias/add-prefix/remove-prefix/add-link-type/remove-link-type/set-extractable/set-expert-routing/detect/suggest/review-candidates/review-orphans/sync) | skills/schema-author/SKILL.md |
| "unify my types", "migrate to gbrain-base-v2", "94 types to 14", "apply canonical taxonomy", "clean up my page types", "pack upgrade", "shrink type proliferation", "consolidate page types", "retype pages to canonical" (dispatcher for: gbrain onboard --check, gbrain onboard --check --explain, gbrain jobs submit unify-types, gbrain pages restore) | skills/schema-unify/SKILL.md |