fix(gen): preamble tiers are explicit; silent ?? 4 default becomes an error; spec stops rendering its preamble twice

Eight skills (scrape, diagram, spec, skillify, pair-agent, landing-report,
open-gstack-browser + its connect-chrome symlink) silently received the
HEAVIEST tier-4 preamble because a missing frontmatter field defaulted to 4.
Tiers are now declared in every {{PREAMBLE}} template's frontmatter and a
missing declaration throws at generation time with the template path (the 5
templates without {{PREAMBLE}} never invoke the resolver). The stale
hand-written tier-map comment (wrong in 3 of 4 rows) is gone.

Bonus bug fixed: spec/SKILL.md.tmpl mentioned {{PREAMBLE}} in prose, so the
generator inlined the ENTIRE preamble a second time — spec/SKILL.md shrinks
127,462 -> 80,924 bytes (-46,538) from de-duplication alone. skill-size-budget
gains a reasoned INTENTIONAL_SHRINKS entry (its frozen baseline had measured
the doubled-preamble bug). New tests: missing-tier throw carries the path;
every {{PREAMBLE}} template declares a tier. (Carries chunk-23 edits in the
shared test/gen-skill-docs.test.ts.)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-08-14 21:12:22 -07:00
co-authored by Claude Fable 5
parent 9124559810
commit 85388c66a5
18 changed files with 81 additions and 814 deletions
+7
View File
@@ -166,12 +166,19 @@ describe('SKILL.md size budget regression (gate, free)', () => {
// skeleton+sections union), so exempt the skeleton from the body-strip floor.
// EQ1: derived from the canonical CARVE_GUARDS registry — no parallel list.
const SECTIONS_EXTRACTED = new Set<string>(CARVED_SKILLS);
// Intentional one-off shrinks vs the frozen baseline (each needs a reason):
// - spec: the baseline measured a template bug — prose at Phase 5 mentioned
// {{PREAMBLE}} literally, so the generator expanded the ENTIRE preamble a
// second time mid-sentence (~47 KB of duplication). Fixed by rewording the
// prose; spec/SKILL.md now carries exactly one preamble (~80.9 KB, ×0.79).
const INTENTIONAL_SHRINKS = new Set<string>(['spec']);
const undershoots: Array<{
skill: string; beforeBytes: number; afterBytes: number; ratio: number;
}> = [];
for (const [skill, before] of Object.entries(baseline.skills)) {
if (SECTIONS_EXTRACTED.has(skill)) continue;
if (INTENTIONAL_SHRINKS.has(skill)) continue;
const after = current.skills[skill];
if (!after) continue; // skill removed since baseline — separate concern
const ratio = after.skillMdBytes / before.skillMdBytes;