Files
gstack/test/catalog-trim.test.ts
T
Garry Tanandcapy-ai[bot] ab114c5308 Say when to use each gstack skill in Claude Code's skill list (GST-2774) (#4387)
* Say when to use each gstack skill in Claude Code's skill list (GST-2774)

Claude Code's listing of each gstack skill now keeps a short when-to-use
clause after its first sentence, so Opus 5.5 loads /review on "review my
changes" and /plan-eng-review on "plan this feature" (GSTA-558).

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Keep /review and /plan-eng-review within their size pins and refresh budgets

CI on the first head found five size and fact checks the new catalog
clause moved: the per-host SKILL.md size pins, the context-budget
ceilings, the deslop-shared-libs catalog byte pin, the Claude ship golden
and the catalog ceiling CLAUDE.md states. /review's and /plan-eng-review's
full descriptions are now shorter than before, so their pins go down, and
/plan-eng-review's scope gate is unchanged from main.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Say which skills keep no when-to-use clause in the changelog entry

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Update the catalog budget and voice-trigger docs for the when-to-use clause

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Drop "deploy this" from /ship's Claude Code skill list line

Deploying belongs to /land-and-deploy, so /ship's when-to-use clause keeps
"ship it, create a pr, push to main" only. Budgets, the size ledger and the
Claude ship golden are re-measured.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix: pre-landing review fixes

Review-Finding: p1/specialist-batched#1 reader=specialist-batched
Review-Finding: p1/red-team#1 reader=red-team
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* Re-measure the setup-gbrain size cap after merging main

Main grew setup-gbrain's always-loaded part to 38,621 bytes, and this
branch's when-to-use clause adds 55 more, so the cap measured on the old
base (38,637) is stale. The cap is now the merged measurement, 38,676.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
2026-11-17 12:23:35 +00:00

338 lines
16 KiB
TypeScript

/**
* Unit tests for catalog-trim helpers (gen-skill-docs.ts T4 functions).
*
* splitCatalogDescription, buildTrimmedDescription, applyCatalogTrim — these handle every skill's frontmatter rewrite at gen
* time. Two bugs already shipped here:
*
* v1.45.0.0 design-consultation: when the first sentence exceeded 200 chars,
* the routing-prose extraction lost the entire tail. design-consultation's
* "Use when asked to..." silently disappeared from the body section.
*
* v1.45.0.0 CI freshness: the root-skill key leaked the checkout directory
* name ("seville-v3" vs "gstack") and aggregate order was filesystem-
* iteration order. Two machines produced two different JSON files.
*
* Both are regression-tested here. Future bugs in these functions surface as
* unit-test failures before they hit CI or production.
*/
import { describe, test, expect } from 'bun:test';
import {
splitCatalogDescription,
buildTrimmedDescription,
applyCatalogTrim,
toYamlInlineScalar,
} from '../scripts/gen-skill-docs';
describe('toYamlInlineScalar', () => {
const parses = (out: string) => Bun.YAML.parse(`d: ${out}`);
test("scalar containing '...' (YAML document-end marker) is quoted and round-trips", () => {
const out = toYamlInlineScalar('Truncated lead ends with... more (gstack)');
expect(out.startsWith('"')).toBe(true);
expect((parses(out) as { d: string }).d).toContain('...');
});
test("interior ': ' is quoted (nested-mapping ambiguity, #1778)", () => {
const out = toYamlInlineScalar('Ship workflow: detect and merge');
expect(out.startsWith('"')).toBe(true);
expect((parses(out) as { d: string }).d).toBe('Ship workflow: detect and merge');
});
test('plain safe scalar passes through unquoted', () => {
expect(toYamlInlineScalar('Simple description here')).toBe('Simple description here');
});
test('leading YAML indicator char is quoted', () => {
expect(toYamlInlineScalar('- leading dash').startsWith('"')).toBe(true);
});
test('trailing whitespace is quoted', () => {
expect(toYamlInlineScalar('has trailing space ').startsWith('"')).toBe(true);
});
});
describe('splitCatalogDescription', () => {
test('extracts lead sentence + routing prose from simple multi-line description', () => {
const desc =
'Pre-landing PR review. Analyzes diff against the base branch for SQL safety, LLM trust\n' +
'boundary violations, conditional side effects, and other structural issues. Use when\n' +
'asked to "review this PR", "code review", "pre-landing review", or "check my diff".\n' +
'Proactively suggest when the user is about to merge or land code changes. (gstack)';
const parts = splitCatalogDescription(desc);
expect(parts.lead).toBe('Pre-landing PR review.');
expect(parts.hasGstackTag).toBe(true);
expect(parts.voiceLine).toBeNull();
expect(parts.routingProse).toContain('Use when');
expect(parts.routingProse).toContain('Proactively suggest');
expect(parts.routingProse).toContain('Analyzes diff');
// (gstack) tag stripped from routingProse
expect(parts.routingProse).not.toContain('(gstack)');
});
test('REGRESSION (design-consultation v1.45.0.0): >200 char first sentence keeps routing', () => {
// This is the exact shape that broke. First sentence (with embedded periods)
// is 207 chars. Original bug: routing extraction ran AFTER lead truncation,
// so collapsed.indexOf(lead) returned -1 (lead ended in "...") and the
// entire "Use when..." + "Proactively..." tail dropped to empty string.
const desc =
'Design consultation: understands your product, researches the landscape, ' +
'proposes a complete design system (aesthetic, typography, color, layout, ' +
'spacing, motion), and generates font+color preview pages. ' +
'Creates DESIGN.md as your project\'s design source of truth. ' +
'For existing sites, use /plan-design-review to infer the system instead. ' +
'Use when asked to "design system", "brand guidelines", or "create DESIGN.md". ' +
'Proactively suggest when starting a new project\'s UI with no existing ' +
'design system or DESIGN.md. (gstack)';
const parts = splitCatalogDescription(desc);
// Lead may be truncated with "..." since it exceeds 200 chars
expect(parts.lead.length).toBeLessThanOrEqual(205);
// Critical: routing MUST contain the "Use when..." and "Proactively..." prose
expect(parts.routingProse).toContain('Use when asked to');
expect(parts.routingProse).toContain('design system');
expect(parts.routingProse).toContain('Proactively suggest');
expect(parts.routingProse).toContain('Creates DESIGN.md');
});
test('extracts voice-triggers line when present', () => {
const desc =
'Quick fix. Use when asked to fix the bug. ' +
'Voice triggers (speech-to-text aliases): "fix it", "patch this", "make it work". ' +
'(gstack)';
const parts = splitCatalogDescription(desc);
expect(parts.lead).toBe('Quick fix.');
expect(parts.voiceLine).toContain('Voice triggers');
expect(parts.voiceLine).toContain('"fix it"');
expect(parts.routingProse).toContain('Use when asked to fix');
// Voice line should NOT leak into routing
expect(parts.routingProse).not.toContain('speech-to-text');
});
test('handles description without (gstack) tag', () => {
const desc = 'Single sentence description. With routing prose afterward.';
const parts = splitCatalogDescription(desc);
expect(parts.lead).toBe('Single sentence description.');
expect(parts.hasGstackTag).toBe(false);
expect(parts.routingProse).toBe('With routing prose afterward.');
});
test('REGRESSION: embedded-period first sentence splits at real boundary', () => {
// The old regex `^([^.!?]*[.!?])(?:\s|$)` could not cross ANY period —
// [^.!?]* stops at the first `.` even mid-token ("DESIGN.md"), the
// boundary check then fails, and the whole match failed. The code
// silently fell back to a 20-word cut mid-phrase (observed with a
// description mentioning "TODOS.md"). The fixed regex
// `^((?:[^.!?]|[.!?](?!\s|$))*[.!?])(?:\s|$)` consumes terminators NOT
// followed by whitespace/end, so embedded periods no longer break it.
const desc =
'Skill that mentions DESIGN.md and v1.45.0.0 in the lead. ' +
'Use when asked to do something.';
const parts = splitCatalogDescription(desc);
expect(parts.lead).toBe('Skill that mentions DESIGN.md and v1.45.0.0 in the lead.');
expect(parts.routingProse).toBe('Use when asked to do something.');
});
test('REGRESSION: "TODOS.md backlog" style sentence keeps full lead + routing', () => {
const desc =
'Drive an approved plan to completion on a TODOS.md backlog. ' +
'Use when asked to "autobuilder" or "run the build loop". ' +
'Proactively suggest after a plan is approved. (gstack)';
const parts = splitCatalogDescription(desc);
expect(parts.lead).toBe('Drive an approved plan to completion on a TODOS.md backlog.');
expect(parts.routingProse).toContain('Use when asked to "autobuilder"');
expect(parts.routingProse).toContain('Proactively suggest');
expect(parts.hasGstackTag).toBe(true);
});
test('URL in first sentence does not end the lead early', () => {
const desc =
'See https://example.com/docs/v2 for the workflow. ' +
'Use when asked to consult the docs.';
const parts = splitCatalogDescription(desc);
expect(parts.lead).toBe('See https://example.com/docs/v2 for the workflow.');
expect(parts.routingProse).toBe('Use when asked to consult the docs.');
});
test('>200 char first sentence WITH embedded periods still truncates with ellipsis and keeps routing', () => {
const firstSentence =
'Regenerate the iOS debug bridge against files like Bridge.swift and TODOS.md, ' +
'walking every target listed in Project.xcodeproj while preserving v1.45.0.0 ' +
'compatibility shims, custom entitlements, and the long tail of per-target ' +
'build settings nobody remembers configuring.';
expect(firstSentence.length).toBeGreaterThan(200);
const desc = firstSentence + ' Use when asked to resync the bridge. (gstack)';
const parts = splitCatalogDescription(desc);
// Lead is the truncated first sentence (ellipsis path), not a 20-word cut.
expect(parts.lead.endsWith('...')).toBe(true);
expect(parts.lead.length).toBeLessThanOrEqual(200);
expect(parts.lead).toContain('TODOS.md');
// Routing prose survives intact.
expect(parts.routingProse).toContain('Use when asked to resync the bridge.');
expect(parts.hasGstackTag).toBe(true);
});
test('description without a period uses first ~20 words as lead', () => {
const desc = 'A long fragment with no sentence terminator drifting on and on across many words for an unusual frontmatter shape';
const parts = splitCatalogDescription(desc);
expect(parts.lead.length).toBeGreaterThan(0);
expect(parts.lead.split(/\s+/).length).toBeLessThanOrEqual(21);
});
test('idempotent: calling on already-trimmed output returns the same parts', () => {
const desc = 'Already trimmed. (gstack)';
const parts1 = splitCatalogDescription(desc);
const parts2 = splitCatalogDescription(buildTrimmedDescription(parts1));
// Re-split of a one-line trimmed result keeps lead identical, routing empty.
expect(parts2.lead).toBe(parts1.lead);
expect(parts2.hasGstackTag).toBe(true);
expect(parts2.routingProse).toBe('');
});
});
describe('buildTrimmedDescription', () => {
test('appends (gstack) when hasGstackTag is true', () => {
const out = buildTrimmedDescription({
lead: 'Some lead.',
routingProse: 'routing',
voiceLine: null,
hasGstackTag: true,
});
expect(out).toBe('Some lead. (gstack)');
});
test('omits (gstack) when hasGstackTag is false', () => {
const out = buildTrimmedDescription({
lead: 'No tag.',
routingProse: '',
voiceLine: null,
hasGstackTag: false,
});
expect(out).toBe('No tag.');
});
test('trims whitespace from lead', () => {
const out = buildTrimmedDescription({
lead: ' Lead with whitespace. ',
routingProse: '',
voiceLine: null,
hasGstackTag: true,
});
expect(out).toBe('Lead with whitespace. (gstack)');
});
// GSTA-558: a lead alone says what a skill is, not when to load it, so the Claude catalog keeps a when-to-use clause.
const parts = (lead: string, routingProse = '') => ({ lead, routingProse, voiceLine: null, hasGstackTag: true });
test('adds the triggers list as the when-to-use clause', () => {
const out = buildTrimmedDescription(parts('Pre-landing PR review.', 'Use when asked to review.'), ['review my changes', 'look over my diff']);
expect(out).toBe('Pre-landing PR review. Use for: review my changes, look over my diff. (gstack)');
});
test('keeps only the triggers that fit the clause cap', () => {
const out = buildTrimmedDescription(parts('Lead.'), ['first trigger here', 'second trigger here', 'third trigger here', 'fourth trigger here']);
expect(out).toBe('Lead. Use for: first trigger here, second trigger here. (gstack)');
});
test('without triggers, uses the "Use when" sentence from the routing prose', () => {
const out = buildTrimmedDescription(parts('Quick fix.', 'Applies a patch. Use when asked to fix it. Proactively suggest it.'));
expect(out).toBe('Quick fix. Use when asked to fix it. (gstack)');
});
test('a lead that is already the "Use when" sentence is not repeated', () => {
expect(buildTrimmedDescription(parts('Use when you review a diff.', 'Checks it.'))).toBe('Use when you review a diff. (gstack)');
});
test('without triggers or a "Use when" sentence, the lead stands alone', () => {
expect(buildTrimmedDescription(parts('A long lead sentence that says what the skill does.', 'More detail here.'))).toBe('A long lead sentence that says what the skill does. (gstack)');
});
test('a lead that fills the catalog line gets no clause', () => {
const lead = 'x'.repeat(200) + '.';
expect(buildTrimmedDescription(parts(lead), ['review my changes'])).toBe(lead + ' (gstack)');
});
});
describe('applyCatalogTrim', () => {
const minimalSkill = `---
name: example
description: |
Example skill: this is the first sentence of the description, intended to be
the lead displayed in the catalog. Use when asked to do an example task.
Proactively suggest when the user mentions examples. (gstack)
preamble-tier: 2
---
<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
<!-- Regenerate: bun run gen:skill-docs -->
# Example body
Original body content here.
`;
test('rewrites multi-line description into one line and adds no body section', () => {
const result = applyCatalogTrim(minimalSkill, 'example');
expect(result).not.toBeNull();
const { content, parts } = result!;
// Frontmatter description is now ONE line ending with (gstack). #1778: a
// description with an interior colon ("Example skill:") is YAML-quoted, so
// the value is wrapped in double quotes — tolerate the optional quotes.
expect(content).toMatch(/^description: "?Example skill:[^\n]*\(gstack\)"?\n/m);
// The body gains no routing section: Claude Code reads a skill body only
// after invocation, so routing prose there routes nothing.
expect(content).not.toContain('## When to invoke this skill');
expect(content.slice(content.indexOf('\n---', 4))).not.toContain('Use when asked to do an example task.');
// The catalog line keeps the when-to-use sentence (GSTA-558) and drops the rest of the routing prose.
expect(content).toMatch(/^description: "?Example skill:[^\n]*\. Use when asked to do an example task\. \(gstack\)"?\n/m);
expect(content).not.toContain('Proactively suggest');
// Original body still present
expect(content).toContain('# Example body');
expect(content).toContain('Original body content here.');
// parts is populated for the aggregator
expect(parts.lead).toContain('Example skill');
expect(parts.hasGstackTag).toBe(true);
});
test('returns null for already-short descriptions (no-op)', () => {
const shortSkill = minimalSkill.replace(
/description: \|[\s\S]*?(?=preamble-tier:)/,
'description: Already short. (gstack)\n',
);
const result = applyCatalogTrim(shortSkill, 'example');
expect(result).toBeNull();
});
test('keeps the newline between description and next YAML field (no field collision)', () => {
// Bug shape from v1.45.0.0 first attempt: produced
// `description: ... (gstack)preamble-tier:` with no newline.
const result = applyCatalogTrim(minimalSkill, 'example');
expect(result).not.toBeNull();
expect(result!.content).not.toMatch(/\(gstack\)preamble-tier/);
expect(result!.content).not.toMatch(/\(gstack\)allowed-tools/);
// #1778: optional closing quote when the description was YAML-quoted.
expect(result!.content).toMatch(/\(gstack\)"?\n[a-z-]+:/);
});
test('returns null on content without proper frontmatter', () => {
expect(applyCatalogTrim('no frontmatter here', 'whatever')).toBeNull();
expect(applyCatalogTrim('---\nincomplete frontmatter', 'whatever')).toBeNull();
});
});
describe('proactive-suggestions.json stays retired', () => {
test('the generator no longer emits scripts/proactive-suggestions.json', () => {
// The aggregated routing registry was removed (no consumer ever read it).
// If someone re-adds the emitter, this pins the decision to delete it —
// reintroduce only with an actual consumer, and restore the determinism
// tests (sorted keys, root keyed as "gstack", no timestamp fields) that
// lived here before.
const fs = require('fs');
const path = require('path');
expect(fs.existsSync(path.join(__dirname, '..', 'scripts', 'proactive-suggestions.json'))).toBe(false);
});
});