Context
A recurring [KB_GAP] surfaced across three PR self-reviews in a single session (PR #10076, PR #10078, PR #10084): new code, new skills, and new architectural patterns aren't queryable via ask_knowledge_base until someone manually runs manage_knowledge_base sync. Until that sync runs, agents booting after the merge get stale synthesized answers about concepts that exist on disk but aren't yet indexed.
This is a toil problem. Every merge creates a knowledge-indexing debt that compounds silently until the next manual sync. Three merges in one session = three instances where the current observation is "yep, we have a recurring KB_GAP — same solution." The compensating manual step is easy to forget.
The Fix
Evaluate and pick one (or a combination):
Option A — GitHub Action on merge
Runs npm run ai:sync-kb (which invokes buildScripts/ai/syncKnowledgeBase.mjs) on every merge to dev. Pros: central, applies to all contributors uniformly. Cons: runs in CI environment; KB data lives on contributor machines, so CI sync doesn't directly benefit the agents running locally. Needs a separate mechanism to propagate.
Option B — husky post-merge hook
Runs the sync locally on git merge / git pull of dev. Pros: each contributor's local KB stays current. Cons: opt-in via hook install; adds boot time to git operations.
Option C — DreamService boot check
On DreamService initAsync, check git HEAD vs last-synced SHA (stored in config or a local state file); if different, trigger sync before processing memories. Pros: agent-owned, no git hook dependency. Cons: adds boot-time latency to every agent session where the SHA moved.
Lean: Option C. Aligns with the agent-OS philosophy (DreamService already handles "catch up on work that accumulated while offline"); doesn't require contributor-side configuration; latency is paid once per session when sync is actually needed (no-op when SHA is current).
Acceptance Criteria
Origin Session ID
62d6f155-e57f-4279-9b59-36c9e4ecbc5e — recurring tag across multiple PR self-reviews this session
Related
- Broad utility — not specifically scoped under #10030
- Evidence: PR #10076, PR #10078, PR #10084 — all three self-reviews flagged this
Context
A recurring
[KB_GAP]surfaced across three PR self-reviews in a single session (PR #10076, PR #10078, PR #10084): new code, new skills, and new architectural patterns aren't queryable viaask_knowledge_baseuntil someone manually runsmanage_knowledge_base sync. Until that sync runs, agents booting after the merge get stale synthesized answers about concepts that exist on disk but aren't yet indexed.This is a toil problem. Every merge creates a knowledge-indexing debt that compounds silently until the next manual sync. Three merges in one session = three instances where the current observation is "yep, we have a recurring KB_GAP — same solution." The compensating manual step is easy to forget.
The Fix
Evaluate and pick one (or a combination):
Option A — GitHub Action on merge
Runs
npm run ai:sync-kb(which invokesbuildScripts/ai/syncKnowledgeBase.mjs) on every merge todev. Pros: central, applies to all contributors uniformly. Cons: runs in CI environment; KB data lives on contributor machines, so CI sync doesn't directly benefit the agents running locally. Needs a separate mechanism to propagate.Option B — husky post-merge hook
Runs the sync locally on
git merge/git pullofdev. Pros: each contributor's local KB stays current. Cons: opt-in via hook install; adds boot time to git operations.Option C — DreamService boot check
On DreamService
initAsync, check git HEAD vs last-synced SHA (stored in config or a local state file); if different, trigger sync before processing memories. Pros: agent-owned, no git hook dependency. Cons: adds boot-time latency to every agent session where the SHA moved.Lean: Option C. Aligns with the agent-OS philosophy (DreamService already handles "catch up on work that accumulated while offline"); doesn't require contributor-side configuration; latency is paid once per session when sync is actually needed (no-op when SHA is current).
Acceptance Criteria
[KB_GAP]as a recurring required actionOrigin Session ID
62d6f155-e57f-4279-9b59-36c9e4ecbc5e— recurring tag across multiple PR self-reviews this sessionRelated