mirror of
https://github.com/garrytan/gbrain.git
synced 2026-07-27 22:15:33 +00:00
7be17261bc
* skill: compress-agents-md — functional-area resolver pattern Proven via A/B eval: 100% routing accuracy at 48% size reduction. Converts granular per-skill resolver rows into functional-area dispatchers with '(dispatcher for: ...)' sub-skill lists. Includes: - SKILL.md with full pattern docs, before/after examples, eval results - routing-eval.jsonl with 5 fixtures - Anti-patterns (resolver-of-resolvers pipe table = 15% accuracy) * skill: rename compress-agents-md → functional-area-resolver, cite prior art The contribution is a pattern (functional-area dispatcher with `(dispatcher for: ...)` clauses), not a file. Rename describes the contribution; triggers broaden to cover both AGENTS.md and RESOLVER.md phrasings. SKILL.md rewrite: - Three-model A/B table (Opus 4.7 / Sonnet 4.6 / Haiku 4.5) replaces the original Sonnet-only claim. Functional-areas beats baseline by +13 to +17pp training (lenient) across all three models at 48% the size. - Strict + lenient scoring documented side by side. Lenient (predicted shares dispatcher area with expected) matches production agent behavior. - Preconditions added: refuse to compress if file <12KB or working tree dirty. - Multi-file routing precedence section for the v0.31.7 RESOLVER.md/AGENTS.md merge case. - Mandatory verification step (≥95% via the harness). - Daily-doctor.mjs reference scrubbed (didn't exist in gbrain). - Three prior-art citations: AnyTool (arXiv:2402.04253), RAG-MCP (arXiv:2505.03275), Anthropic Agent Skills progressive disclosure. The pattern is the static-prompt analog of runtime hierarchical routing. routing-eval.jsonl: 8 positive (5 original + 3 broadened triggers) + 4 adversarial negatives targeting skillify, skill-creator, book-mirror, concept-synthesis to prove broadened triggers don't over-capture adjacent meta-skills. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * evals: A/B harness for functional-area-resolver (gateway-routed, strict + lenient scoring) evals/functional-area-resolver/ lives outside skills/ deliberately. The skillpack bundler walks skills/<skill>/ recursively, so an eval surface in there would copy harness + variants + fixtures + tests into every downstream install. The pattern (in SKILL.md) ships everywhere; the eval evidence stays in the gbrain repo. What ships: - Three variant resolvers in variants/ — baseline.md (verbose 25KB) and functional-areas.md (compressed 13KB) extracted from a real production AGENTS.md at git commits 93848ff3b^ and 93848ff3b (owner PII scrubbed). resolver-of-resolvers.md derived mechanically by stripping (dispatcher for: ...) clauses — the ablation case. - 20 hand-authored training fixtures + 5 held-out blind fixtures. - harness-runner.ts — TypeScript runner via gbrain gateway. Flags: --model {opus|sonnet|haiku|<full-id>}, --variants-dir, --variants for description-length sweeps, --parallel N (rate-lease bound), --limit N for smoke runs, --yes for non-TTY. - Every output row carries BOTH `correct` (strict) and `correct_lenient` (predicted shares dispatcher area with expected). Lenient matches production behavior. - Receipt header binds (model, prompt_template_hash, fixtures_hash, harness_sha, ts, cmd_args). Re-runs are auditable. - harness.mjs — thin Node shim that spawns the TS runner via bun. - rescore.mjs — zero-cost lenient re-score of an existing JSONL. - harness-runner.test.ts — 45 unit tests (no API key needed) covering every pure function plus the dispatcher-list parser. The prompt template is load-bearing: without the "drill into (dispatcher for: ...) list" instruction, every compression variant collapses to ~30-60%. Documented in SKILL.md and README.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * evals: baseline receipts (Opus 4.7 + Sonnet 4.6 + Haiku 4.5, 2026-05-11) Three canonical 225-row receipts (3 variants × 25 fixtures × 3 seeds per model). Each receipt header binds (model, prompt_template_hash, fixtures_hash, harness_sha, ts) so the published SKILL.md numbers are reproducible. Training corpus (n=20, lenient): baseline | Opus 81.7% | Sonnet 86.7% | Haiku 73.3% | 25KB functional-areas | Opus 98.3% | Sonnet 100% | Haiku 88.3% | 13KB resolver-of-resolvers | Opus 63.3% | Sonnet 41.7% | Haiku 65.0% | 10KB functional-areas beats baseline by +13 to +17pp across all three models at 48% the size. resolver-of-resolvers' Sonnet collapse (41.7%) is the SKILL.md "compression without dispatcher clause is broken" claim, observed. Held-out (n=5, lenient) saturates at 100% across most cells (Sonnet × resolver-of-resolvers is 73.3% — the same failure mode visible on a smaller sample). ~$3 API spend across all three runs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: wire functional-area-resolver into RESOLVER.md + manifests skills/RESOLVER.md gets a new row in Operational, adjacent to skillify. Triggers: "Compress my resolver", "AGENTS.md too large", "RESOLVER.md too big", "functional area dispatcher", "shrink routing table". skills/manifest.json adds the new entry and bumps manifest version 0.25.1 → 0.32.3.0 (loadOrDeriveManifest reads this for sync-guard). openclaw.plugin.json adds functional-area-resolver to the skills array and bumps version 0.25.1 → 0.32.3.0 so install receipts stop being stale (src/core/skillpack/installer.ts:307-311 uses manifest version on every install). Verified: - gbrain check-resolvable --json: 42/42 reachable, 0 errors. - gbrain routing-eval: 70/70 pass (100% structural). - bun test test/skillpack-sync-guard.test.ts: passes (manifest in sync). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * v0.32.3.0 skill: functional-area-resolver — pattern for compressing routing tables Headline: compress a 25KB AGENTS.md down to 13KB without losing routing accuracy. Pattern proven across Opus 4.7, Sonnet 4.6, and Haiku 4.5 — beats the verbose baseline by +13 to +17pp at 48% the size. Empirical (training, n=20, 3 seeds, lenient): baseline 25KB: Opus 81.7% | Sonnet 86.7% | Haiku 73.3% functional-areas 13KB: Opus 98.3% | Sonnet 100% | Haiku 88.3% resolver-of-resolvers 10KB: Opus 63.3% | Sonnet 41.7% | Haiku 65.0% The (dispatcher for: ...) clause is the load-bearing signal. Strip it (the resolver-of-resolvers variant) and Sonnet collapses to 41.7% — the failure case the pattern's authors predicted, now observed. Files in this release: - VERSION + package.json bumped to 0.32.3.0 (4-segment per CLAUDE.md). - CHANGELOG.md: full empirical story, cross-model table, three prior-art citations (AnyTool, RAG-MCP, Anthropic Agent Skills progressive disclosure). - TODOS.md: nine v0.33.x follow-ups (dogfood on gbrain's own RESOLVER.md, CLI promotion to gbrain routing-eval --ab-compare, held-out corpus growth, cross-vendor Gemini+GPT verification, per-row description length sweep, structural compression to ~10KB, hierarchical area-of-areas, embedding pre-router, adversarial fixtures, prompt-design ablation doc). - llms-full.txt regenerated. Bisect-friendly history on this branch:502d447eskill: rename + content rewrite + routing-eval.jsonl472cc686evals: A/B harness + variants + fixtures + tests (no receipts)243e013eevals: cross-model baseline receipts (Opus + Sonnet + Haiku)ecab180bskill: wire-up to RESOLVER.md + manifest.json + openclaw.plugin.json THIS: v0.32.3.0 release marker Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * evals: codex review fixes — accept ASCII -> arrow + provider-aware auth gate Two P2 findings from /codex review on commit8870c64e: P2-2: parseDispatcherLists regex required Unicode `→`, but SKILL.md Step 4 documents the template with ASCII `->`. Downstream-authored resolvers following the template silently fell through to strict-only scoring (correct_lenient == correct always), under-reporting same-area accuracy with no warning. Regex now accepts both `→` and `->`. Two new test cases pin the behavior — pure-ASCII variant + mixed-arrow variant. P2-3: main() exited with `ANTHROPIC_API_KEY is not set` even when the user passed `--model openai:gpt-4o` with a valid OPENAI_API_KEY. The CLI advertises full provider:model support (resolveModel tests cover openai:* explicitly) and the gateway routes by recipe; the env check should match the provider that will actually be called. Now extracts the provider id from the model string and looks up the right env var from REQUIRED_ENV_BY_PROVIDER (anthropic, openai, google, groq, voyage, together, deepseek, minimax, dashscope, zhipu). Unknown providers fall through to the gateway, which raises a clear recipe-specific error. 47/47 harness unit tests pass after the change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * skill: codex review P2-1 — verification gate now tests the user's edited file The original SKILL.md Step 6 told users to run `node harness.mjs` from the gbrain repo as the mandatory ≥95% gate. But that runs the harness against the COMMITTED sample variants in evals/functional-area-resolver/variants/, not the file the user just compressed. The gate could pass while the edit dropped a sub-skill. Step 6 now: - Gate 1 stays at `gbrain routing-eval --json` (structural, runs against the user's actual routing-eval.jsonl fixtures). - Gate 2 is rewritten: copy the user's edited routing file into a tmp variants dir, then run `node harness.mjs --variants-dir <tmp> --variants my-edit --model opus`. This exercises the harness's existing --variants flag (added in commit472cc686/ T4) but now points at the user's actual edit. The harness uses gbrain-bundled fixtures, so this is a regression check on shared skills, not a full eval of the user's fixture set — and the SKILL.md says so explicitly. Also adds a "common false negatives" callout: when the user's routing file doesn't expose the skills gbrain's bundled fixtures target (e.g. `gmail`, `enrich`), expect strict-scoring fails on those rows; lenient scoring remains accurate. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * evals: codex review P3 — regenerate Opus baseline with current schema The prior Opus receipt was generated before commit472cc686(T4 added harness_sha to ReceiptRow and correct_lenient to every RunRow). The Sonnet and Haiku receipts shipped with the new schema, but Opus was the outlier. This run was produced with the current harness (shaca99fbfeb, after the P2-1 + P2-2 + P2-3 fixes). The harness_sha in the receipt header binds the numbers to a specific harness revision so consumers can detect schema drift. Numbers (training, lenient, n=20, 3 seeds): baseline: 81.7% ± 7.2% (unchanged — strict and lenient are equal) functional-areas: 100% ± 0% (was 98.3% — one nondeterministic seed is now in-cluster; pattern continues to beat baseline at 48% the size) resolver-of-resolvers: 66.7% ± 7.2% (was 63.3% — still in noise; absent dispatcher clause keeps it ~30pp behind functional-areas on training) Held-out (n=5, 3 seeds, lenient): all variants 100% except resolver-of- resolvers on Sonnet (committed in earlier baseline) — Opus held-out saturates the small fixture set. Run cost: ~$1.40 at Opus 4.7 pricing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * post-merge: scrub fork-private paths + add Contract/Output Format sections Two CI gates landed on master after this branch was cut: 1) scripts/check-privacy.sh (v0.32.2): banned /data/brain/ and /data/.openclaw/ in committed files. The eval variants extracted from a real production AGENTS.md still contained those fork-private path literals. Rewrote to /your/brain/path/, /your/agent/.openclaw/, /your/gbrain, /your/gstack, /your/tmp, /your/git-projects/. Only path strings changed — the routing structure (skill names, dispatcher clauses, trigger phrases) is byte-for- byte identical, so harness baseline-runs/ receipts are still valid. 2) test/skills-conformance.test.ts (master): added required sections `## Contract` and `## Output Format` to every skill. Added both to skills/functional-area-resolver/SKILL.md following the book-mirror convention (short body referencing the canonical content above + a conformance-test footnote). Contract notes the privacy guarantee + the verification-gate semantics; Output Format documents the area entry template (with both ASCII -> and Unicode → arrows accepted). Full unit suite: 5578 pass / 0 fail. bun run verify clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: surface functional-area-resolver in CLAUDE.md + README.md for v0.32.3.0 CLAUDE.md — adds a "Routing-table compression (v0.32.3.0)" entry under Skills, covering the two-layer dispatch pattern, the load-bearing (dispatcher for: ...) clause, the eval surface at evals/functional-area-resolver/, the three cross-model baseline receipts, the 25KB → 13KB compression numbers, and the nine v0.33.x follow-up TODOs. Cites AnyTool / RAG-MCP / Anthropic Agent Skills prior art so the pattern's position in the literature is discoverable from the agent entry point. README.md — adds a "New in v0.32.3.0" callout in the intro section so users landing on the repo see the new skill before scrolling to the skills list. Links the SKILL.md and eval directory; states the cross-model gain (+13 to +17pp at 48% the size) so the reason to apply the pattern is one click away. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: garrytan-agents <garrytan-agents@users.noreply.github.com> Co-authored-by: Garry Tan <garrytan@gmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>