fix(core): stop injecting unfiltered full-body skill dumps outside per-turn matching#6422
Merged
Merged
Conversation
bug-ops
enabled auto-merge (squash)
July 17, 2026 20:49
…r-turn matching Agent::new_with_registry_arc and reload_skills() built the system prompt from the entire skill registry with full SKILL.md bodies, bypassing the matcher/disambiguation_threshold/max_active_skills cap entirely. This force-loaded every skill's body via the registry's lazy accessor and inflated the startup/hot-reload token gauge to the size of the whole registry (e.g. ~100k tokens for 157 skills) before any turn ran. Both call sites now build a catalog-only prompt (name + description via format_skills_catalog) straight from SkillMeta, deferring full-body injection to the first per-turn rebuild_system_prompt(query) call, which already applies the cap correctly. reload_skills() also recomputes cached_prompt_tokens after mutating messages[0] so the gauge never goes stale between a reload and the next turn. Adds an explicit construction-time/reload-time contract to specs/005-skills/spec.md and specs/001-system-invariants/spec.md closing the spec gap that allowed this (all existing skill-injection invariants were framed per-turn and silent on the pre-first-turn prompt). Closes #6413
bug-ops
force-pushed
the
fix/6413-startup-context-token-gauge
branch
from
July 17, 2026 20:49
dff27b4 to
c6dff00
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Agent::new_with_registry_arcandreload_skills()built the initial/reloaded system prompt from the entire skill registry with fullSKILL.mdbodies, bypassing the matcher/disambiguation_threshold/max_active_skillscap entirely — the visible symptom was the TUI//statusstartup token gauge showing ~100k tokens (full registry size) before any turn ran, contradicting the project's resource-efficiency positioning.format_skills_catalog) straight fromSkillMeta, with no per-skill disk read, deferring full-body injection to the first per-turnrebuild_system_prompt(query)call — which already applies the matching/cap correctly.reload_skills()now recomputescached_prompt_tokensafter mutatingmessages[0], so the gauge never goes stale between a reload and the next turn.specs/005-skills/spec.mdand a cross-referencedNEVERclause tospecs/001-system-invariants/spec.md§7 — all prior skill-injection invariants were framed strictly "per turn" and silent on the pre-first-turn prompt.crates/zeph-subagent/src/agent_loop.rsrun_turn) does NOT share this defect — it resolves skills once at spawn time via a static include/exclude filter, architecturally distinct from the per-turn matcher. However, adversarial review found subagents with the default (emptyskills.include) configuration force-load every registered skill's full body into their one-shot prompt — same defect class, worse magnitude since it actually reaches the LLM. Correctly scoped out of this PR; filed separately as subagent default skills.include (empty) force-loads every skill's full body into the one-shot prompt #6421.Root cause investigation
Diagnosed via a dedicated diagnose-only session (debugger + live-tester + architect, no code changes) before this fix was implemented. Full evidence trail carried over into this worktree:
.local/handoff/2026-07-17T21-12-03-debug.md,.local/handoff/2026-07-17T21-14-58-live-tester.md,.local/handoff/2026-07-17T21-19-59-architect.md.Test plan
crates/zeph-core/src/agent/tests/agent_tests/skill_prompt_bloat_tests.rs: construction catalog-only + token ceiling, reload catalog-only +cached_prompt_tokensrecompute proof,last_skills_promptcatalog-only, 0-skill registry (construction + reload), Blocked-trust skill filtered at reloadcargo +nightly fmt --check— cleancargo clippy --profile ci --workspace --all-targets --features "desktop,ide,server,chat,pdf,scheduler,testing" -- -D warnings— cleancargo nextest run --config-file .github/nextest.toml --workspace --features "desktop,ide,server,chat,pdf,scheduler" --lib --bins— 14182 passed, 0 failedRUSTFLAGS="-D warnings" RUSTDOCFLAGS="--deny rustdoc::broken_intra_doc_links" cargo doc --no-deps --workspace --features "desktop,ide,server,chat,pdf,scheduler"— cleanRUSTFLAGS="-D warnings" cargo check --workspace --all-targets --features desktop,ide,server,chat,pdf,scheduler --locked— cleancargo test --doc --workspace --features "desktop,ide,server,chat,pdf,scheduler"— 40 passedgitleaks protect --staged— no leaksorigin/main, re-ran full check suite post-rebase (no conflicts, no source touched by rebase).local/testing/playbooks/skills.md(new scenario),.local/testing/coverage-status.md(new row)[Unreleased]/FixedCloses #6413