mirror of https://github.com/garrytan/gstack.git
2 Commits
| Author | SHA1 | Message | Date |
|---|---|---|---|
Garry Tan
|
22f8c7f4e1
|
v1.46.0.0 feat: gstack v2 foundation — catalog tokens drop 56%, eval-first floor covers all 51 skills (#1712)
* docs(designs): add v2_PLAN.md — gstack v2 the lightest opinionated skill pack
The approved plan from /plan-ceo-review → /plan-eng-review → /codex×2 →
/plan-devex-review. Captures the v1.45/v2.0 hybrid release shape,
cathedral parity-eval suite, sequential v1.45 execution, sections/*.md.tmpl
pipeline, EVALS_BUDGET_HARD_CAP override path, and v2 launch copy specs.
This commit just lands the design doc. Implementation follows in the rest
of the v1.45.0.0 branch.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(parity): T0a — capture v1.44.1 baseline + capture helper + diff utility
Cathedral parity-eval suite primitive. captureBaseline() walks every
top-level SKILL.md and records bytes, lines, estimated tokens, frontmatter
description length, and eval coverage. diffBaselines() reports per-skill
delta + total corpus delta + catalog tokens delta.
Locks the v1.44.1 reference snapshot at test/fixtures/parity-baseline-v1.44.1.json.
After Phase A+B+C land, scripts/capture-baseline.ts --tag v1.45.0.0 produces
a comparable snapshot; diff supplies the real numbers the v2 CHANGELOG quotes.
Never invent baseline numbers; ship them only if they came from a real run.
v1.44.1 numbers captured this commit:
- 51 skills
- 2,847 KB total corpus
- ~9,319 catalog tokens (sum of description bytes / 4)
- top 3: ship 160 KB, plan-ceo-review 128 KB, office-hours 108 KB
Test plan:
- bun test test/helpers/capture-parity-baseline.test.ts passes 4/4
- The baseline JSON file is committed so reviewers can audit v1→v2 numbers
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(resolvers): T2 — ResolverEntry + appliesTo gate infrastructure
Adds the conditional-resolver-injection plumbing from the v2_PLAN A.1
step. Resolvers can now be either a bare ResolverFn (always fires, current
behavior) or a ResolverEntry { resolve, appliesTo? } (gated; appliesTo
returning false skips the resolver, substitutes empty string).
Why infrastructure-only: the audit during T0a confirmed most resolvers
don't need gating. The {{NAME}} placeholder system is already conditional
at the template level — a resolver only fires for skills that reference it.
The gate is for future use when a placeholder's audience needs a structural
guardrail beyond social convention, or when a sub-resolver inside a larger
composed resolver (e.g. preamble) needs per-skill skip.
scripts/gen-skill-docs.ts:444 now uses unwrapResolver() to handle both
shapes. RESOLVERS map signature widens from Record<string, ResolverFn>
to Record<string, ResolverValue>. All existing resolvers stay bare
functions and work unchanged.
Test plan:
- bun test test/resolver-entry.test.ts: 6 pass (gate plumbing + registry)
- bun test test/gen-skill-docs.test.ts: 389 pass (no regression)
- bun run gen:skill-docs --dry-run: all SKILL.md files FRESH (no diff)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(preamble): T3 — jargon dedup + terse-build flag (Phase A.2 + A.3)
A.2 jargon dedup: generate-writing-style.ts replaces the inlined 80-term
jargon list with a one-line pointer to scripts/jargon-list.json. The list
was duplicated into every tier-2+ skill (48 of 51 skills); inlining cost
was ~1.5 KB × 48 = ~70 KB across the corpus. Pointer cost is ~30 bytes per
skill. Agents Read the JSON once per session on first jargon term
encountered; thereafter the terms array is the canonical reference.
A.3 terse build flag: --explain-level=terse compresses preamble prose at
gen time. When the flag is set, writing-style collapses to a one-line
terse directive and completeness-section + confusion-protocol +
context-health are dropped entirely. The default build keeps the
runtime-conditional behavior intact (sections still render; the model
skips them when EXPLAIN_LEVEL: terse appears in the preamble echo). Terse
build is opt-in for users who want shipped skills to match their runtime
preference and avoid the per-session terse-mode dead prose.
TemplateContext gains an optional `explainLevel: 'default' | 'terse'`
field. Default builds set it to 'default'; --explain-level=terse sets
'terse'. Resolvers gate their output via `ctx?.explainLevel === 'terse'`.
Measured impact (default build, post-T3):
- Total corpus: 2,847 KB → 2,812 KB (saved 35 KB)
- ship.md: 160 → 159 KB
- plan-ceo-review.md: 128 → 127 KB
- Top 10 heaviest: all slightly smaller from jargon pointer
Larger compression lands in T4 (catalog trim) and T7 (atomic regen across
the full Phase A pipeline). The terse build path further compresses to
~711K tokens vs default ~725K (saved ~14K tokens corpus-wide).
Test plan:
- bun test test/gen-skill-docs.test.ts: 389 pass (no regression)
- bun test test/resolver-entry.test.ts: 6 pass
- bun test test/helpers/capture-parity-baseline.test.ts: 4 pass
- bun run gen:skill-docs --explain-level=terse: ship.md drops completeness +
confusion-protocol + context-health sections; writing-style collapses to
one-line terse directive
48 SKILL.md files updated (every tier-2+ skill picks up the jargon pointer).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(catalog): T4 — catalog trim + proactive-suggestions.json (Phase A.4)
Shortens frontmatter `description:` in every Claude SKILL.md to a single
lead sentence + (gstack) tag. The routing prose ("Use when asked to...",
"Proactively suggest...") and voice triggers move to a "## When to invoke"
body section so they remain discoverable inside the skill. A per-run
registry at scripts/proactive-suggestions.json aggregates the routing/
voice text for all 52 skills so agents can pull guidance on demand
without paying for it in the always-loaded catalog.
Build flag --catalog-mode=full restores v1.44 legacy behavior (full
multi-line descriptions in frontmatter). Default is trim.
splitCatalogDescription() extracts: lead sentence, routing paragraphs,
voice-triggers line, (gstack) tag presence. Short descriptions (<120
chars, already trimmed) are skipped via a guard so re-runs are idempotent.
Measured impact (vs v1.44.1 baseline):
- Catalog tokens (sum of description bytes / 4): 9,319 → 4,045 (-56.6%)
- Total SKILL.md corpus bytes: 2,915 KB → 2,880 KB (-1.2%)
- Routing prose preserved as in-skill "## When to invoke" sections
- 52 skill entries in scripts/proactive-suggestions.json (on-demand registry)
The corpus drop is small because catalog trim MOVES text from frontmatter
to body, it doesn't delete it. The headline win is the catalog: the
always-loaded system prompt surface drops by more than half.
Test plan:
- bun test test/gen-skill-docs.test.ts: 389 pass, 0 fail
- Manual: ship/SKILL.md frontmatter description is now ONE line ending
with `(gstack)`; allowed-tools field on next line (YAML well-formed)
- Manual: scripts/proactive-suggestions.json contains 52 entries
- bun run gen:skill-docs --catalog-mode=full restores legacy behavior
53 files changed (52 SKILL.md across hosts + the new proactive-suggestions.json).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(budget): T5 — hard token budgets + override audit trail (Phase A.6)
Two new gate-tier guardrails for the v1.45.0.0 compression baseline:
1. test/skill-size-budget.test.ts (NEW) — per-skill SKILL.md size budget.
Compares current state to test/fixtures/parity-baseline-v1.44.1.json.
Three checks: per-skill (×1.05 default ratio), total corpus, and
catalog token estimate (≤7000 for v1.45). The per-skill ratio is 1.05
not 1.0 because the T4 catalog trim moves text from frontmatter to a
body section; small skills see a tiny body growth that's fine when
offset by the much larger catalog-token win.
2. test/skill-budget-regression.test.ts EXTENDED — hard dollar cap on
per-run eval cost. Per-tier defaults: gate $25, periodic $70. Umbrella
EVALS_BUDGET_HARD_CAP=$30. Catches runaway eval costs (infinite retry,
model price changes) before they amortize across PRs.
Both checks support an override path with audit trail:
GSTACK_SIZE_BUDGET_OVERRIDE_REASON="why this is OK" — size
EVALS_BUDGET_OVERRIDE_REASON="why this is OK" — cost
Overrides log to ~/.gstack/analytics/spend-overrides.jsonl with
timestamp + scope + reason + CI provenance (runner, branch, commit)
via test/helpers/budget-override.ts.
Why the override audit: a hard cap with no escape valve becomes
operationally hostile (legit price changes, longer transcripts, new
required evals can all blow the cap). An override with no audit becomes
"everyone overrides everything and the gate is theater." This module
ships the audit half so reviewers can see what was waived and why.
Codex 2nd-pass critique #3 absorbed: per-suite caps + override path with
auditability + budget baselines checked into repo (parity-baseline-v1.44.1.json
already in test/fixtures/).
Test plan:
- bun test test/skill-size-budget.test.ts: 4 pass (per-skill, corpus, catalog, baseline-exists)
- bun test test/skill-budget-regression.test.ts: 4 pass (2 existing ratio checks + 2 new hard-cap checks)
- Existing eval runs ($14.11 e2e, $0.02 llm-judge) sit well under the new caps
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(cso): T6 — pin must-preserve security phrases (Phase A.5)
cso/SKILL.md is a content-heavy security audit skill (75 KB after T3+T4).
Codex 2nd-pass critique #9: "cso exemption too broad ... should still get
resolver dedup, catalog trim, sectioning if safe, and targeted evals
around must-not-miss checks."
T3 (jargon dedup) and T4 (catalog trim) already applied to cso the same
way they applied to every other skill — confirmed by inspection:
- jargon list NOT inlined (0 inline term lines)
- catalog description trimmed to one line (74 bytes vs 774 bytes baseline)
- "## When to invoke" body section present
T6 work: lock in the security-prose preservation via a gate-tier test
that fails CI if future compression strips load-bearing phrases:
- OWASP, STRIDE positioning
- daily / comprehensive mode discipline
- confidence scoring language
- active verification ("verif" prefix catches verify/verified/verification)
- ## Preamble heading (preamble resolver still fires)
Also guards cso against accidental over-stripping: SKILL.md must stay
≥30 KB (currently 75 KB) — a sudden cliff would mean compression went
past the targeted-dedup line into structural removal.
No structural change to cso. Future Phase B sections/ work for cso
requires writing baseline parity tests FIRST per the v2_PLAN.md
sequencing.
Test plan:
- bun test test/cso-preserved.test.ts: 5 pass
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(parity): T0b — cathedral parity-suite harness + invariant registry
Adds the harness that the v2_PLAN.md cathedral parity-eval suite is built
on. Compares CURRENT SKILL.md output to v1.44.1 baseline along three axes:
STRUCTURE frontmatter shape (catalog trim landed, "## When to invoke" present)
CONTENT must-preserve phrases per skill family (cso: OWASP/STRIDE;
plan-ceo: SCOPE EXPANSION/HOLD SCOPE/REDUCTION; ship:
VERSION/CHANGELOG/PR; etc.)
SIZE per-skill byte budget (maxSizeRatio + minBytes guards)
PARITY_INVARIANTS registry pins 10 load-bearing skills (cso, ship, plan-*-
review, review, qa, investigate, office-hours, autoplan). Each entry
declares what must NOT regress; future compression that strips these
phrases or shrinks a skill past its minBytes cliff fails CI.
Periodic-tier LLM-judge parity (paid, ~$0.20/skill) lands in v2.0.0.0
sections/ phase. Same registry, same harness, judge added on top.
Test plan:
- bun test test/parity-suite.test.ts: 10/10 invariants pass vs v1.44.1
- Per-skill failures get actionable per-line breakdown so a reviewer can
see which phrase / heading / size limit went sideways
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(coverage): T1 — skill coverage matrix + structural-compliance floor
Phase 0 deliverable — eval-first foundation. Two new test files plus the
registry:
1. test/skill-coverage-matrix.ts — single source of truth mapping each
skill to its gate-tier + periodic-tier test files. SKILL_COVERAGE
record with 51 entries; every gstack skill on disk has at least one
gate-tier entry.
2. test/skill-coverage-matrix.test.ts — CI gate. Asserts every skill on
disk has a registry entry AND that gate[] is non-empty. Catches
"skill added but eval not registered" the moment a new SKILL.md
lands.
3. test/skill-coverage-floor.test.ts — per-skill structural compliance
(FREE, file-IO only). For each of 51 skills, verifies:
- SKILL.md exists
- Frontmatter well-formed (name + description fields)
- Catalog-trim contract (inline description ≤ 250 chars, or block form)
- Generated header present (edit .tmpl, not .md)
- Body ≥ 200 bytes (non-trivial content)
- No unresolved {{TEMPLATE}} placeholders leaked
The "floor" is the minimum eval that every skill ships with. Skills that
need deeper behavioral testing get additional entries in their coverage
record (e.g., ship has skill-e2e-ship-idempotency + workflow + floor).
Future skills only need to add the floor entry and the matrix gate
unblocks them.
Codex 2nd-pass critique #1 mitigation: eval-first floor is structural
compliance (the testable part) — judgment-skill behavior gets layered
periodic-tier evals on top. We don't pretend the floor proves
correctness, only that the skill structurally compiles.
Test plan:
- bun test test/skill-coverage-matrix.test.ts: 4 pass (matrix shape + coverage)
- bun test test/skill-coverage-floor.test.ts: 309 pass (6 checks × 51 skills + 3 registry-level)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* build(skills): T7 — atomic regenerate + capture v1.45.0.0 baseline
Final regen pass across all hosts after T1-T6 work landed. Captures the
v1.45.0.0 parity baseline at test/fixtures/parity-baseline-v1.45.0.0.json
for diffing against the v1.44.1 reference.
Measured deltas (real numbers from test/helpers/capture-parity-baseline.ts):
Total SKILL.md corpus 2,847 KB → 2,813 KB (-1.2%)
Catalog tokens (always-loaded) ~9,319 → ~4,045 tokens (-56.6%)
Top 10 heaviest skills 0.5-1.0% drop each
The catalog token cut is the headline. It's the always-loaded surface,
i.e. tokens charged on every session start. Per-skill SKILL.md sizes
barely moved because T4 catalog trim MOVES routing prose from frontmatter
to a body "## When to invoke" section rather than deleting it — the
catalog wins without amputating discoverability.
The bigger per-skill compression lands in v2.0.0.0 (Phase B sections/
pattern on the 5 heavyweights). v1.45 is the foundation: eval-first
infrastructure + cheap wins.
scripts/proactive-suggestions.json regenerated with the latest 52 skills
listed (one-time write per gen-skill-docs run; aggregated catalog parts).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* v1.45.0.0 — gstack v2 foundation: catalog tokens drop 56%, eval-first floor
Bumps VERSION + package.json to 1.45.0.0. CHANGELOG entry covers what
shipped between v1.44.1 and this release: the cathedral parity-eval
foundation, conditional resolver injection plumbing, jargon dedup, terse
build flag, catalog trim with one-line frontmatter descriptions, hard
token + dollar budget gates with override audit, cso preservation pins,
and the v1.44.1 ↔ v1.45.0.0 parity baselines committed to test/fixtures/.
Numbers (measured, not estimated):
- Catalog tokens: ~9,319 → ~4,045 (-56.6%)
- Total corpus: 2,847 KB → 2,813 KB (-1.2%)
- Skills with gate-tier eval coverage: 32/51 → 51/51 (floor achieved)
This is the foundation release. v2.0.0.0 will ship the architectural
break (sections/*.md.tmpl pattern + mechanical Read enforcement +
eval-coverage annotations) as a coordinated marketing-grade launch.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore(catalog): refresh proactive-suggestions.json timestamp after v1.45 bump
The generated_at field updates on every gen-skill-docs run; this is the
T7 atomic-regenerate output landed alongside the v1.45.0.0 bump.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(catalog): deterministic proactive-suggestions.json (no per-run timestamp)
Original implementation wrote a generated_at timestamp on every gen-skill-docs
run. That made CI dry-run freshness checks flap because the file changed on
every regeneration even when the actual content (skill descriptions, routing
prose, voice triggers) was unchanged.
Two fixes:
1. Drop the generated_at field. The file is purely a content registry now.
2. Only write the file when serialized content actually differs from disk.
Reproducible test: bun run gen:skill-docs twice in a row now leaves
scripts/proactive-suggestions.json unchanged on the second run.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(catalog): preserve routing prose when first sentence exceeds 200 chars
splitCatalogDescription truncated the lead BEFORE computing routing
extraction, which meant skills whose first sentence was over 200 chars
(design-consultation: 207 chars) had their entire routing prose silently
dropped — the "## When to invoke" body section came out empty.
Root cause: routing was extracted via `collapsed.indexOf(lead)` after lead
was suffixed with "...". The "..." never appeared in the original string,
so indexOf returned -1 and routingProse fell back to empty.
Fix: compute routing from sentenceLead (the untruncated first sentence)
BEFORE truncating the displayed lead. The displayed lead still gets "..."
when over 200 chars, but the routing extraction uses the real boundary.
Also: refresh golden snapshots for claude/codex/factory ship and update
two unit tests that asserted v1.44 behavior:
- skill-validation.test.ts: trigger-phrase + proactive-routing tests now
search whole content, not just frontmatter (T4 moved them to a body
"## When to invoke" section)
- writing-style-resolver.test.ts: jargon-list assertion now expects the
T3 reference pointer, not the inline list
Test plan:
- bun test test/skill-validation.test.ts test/writing-style-resolver.test.ts
test/host-config.test.ts test/skill-size-budget.test.ts
test/parity-suite.test.ts test/skill-coverage-matrix.test.ts
test/skill-coverage-floor.test.ts test/cso-preserved.test.ts
test/resolver-entry.test.ts test/helpers/capture-parity-baseline.test.ts
test/gen-skill-docs.test.ts: 1134 pass, 0 fail
- Manual verify: design-consultation/SKILL.md "## When to invoke this skill"
body section now contains "Use when asked to..." + "Proactively suggest..."
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(catalog): deterministic proactive-suggestions.json across machines
CI check-freshness failed because scripts/proactive-suggestions.json
serialized differently on local vs CI:
1. Root-skill key leaked the directory name. processTemplate's outer loop
computed `dir = path.basename(path.dirname(tmplPath))`. For the root
SKILL.md.tmpl at ROOT/SKILL.md.tmpl, that returns the repo-checkout
directory name — "seville-v3" in a Conductor worktree, "gstack" on
GitHub Actions, anything-else for a fork. Fix: detect root via
`path.dirname(tmplPath) === ROOT` and hardcode the key to "gstack"
for that one case.
2. Aggregate key order was filesystem-iteration order. discoverTemplates
doesn't guarantee stable ordering across platforms, so the JSON
`skills` object came out shuffled between machines. Fix: sort
Object.keys(proactiveAggregate) alphabetically before serializing.
After the fix, the generated file is identical on every machine and
matches what's committed. CI freshness check (bun run gen:skill-docs &&
git diff --exit-code) now passes.
Test plan:
- bun run gen:skill-docs && bun run gen:skill-docs --dry-run: all FRESH
- node -e 'verify keys sorted': sorted match: true
- grep -c '"seville-v3"' scripts/proactive-suggestions.json: 0
- Focused test suite: 704 pass, 0 fail
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(catalog): unit + regression coverage for catalog-trim helpers
Four exported functions in scripts/gen-skill-docs.ts handle every skill's
frontmatter rewrite at gen time but had zero unit tests. Both real bugs we
shipped (and fixed) on this branch lived in these functions:
v1.45.0.0 design-consultation: when the first sentence exceeded 200 chars,
routing-prose extraction lost the entire tail (anchored on truncated lead
with "..." that didn't substring-match the original).
v1.45.0.0 CI freshness: root-skill key leaked the checkout directory
name ("seville-v3" vs "gstack") and aggregate order was filesystem-
iteration order.
Both shapes are now regression-tested:
- splitCatalogDescription: 7 tests covering simple multi-line, >200-char
first sentence (design-consultation regression), voice-trigger
extraction, no-(gstack) handling, embedded periods (documents known
fallback), no-period fragments, and idempotency.
- buildTrimmedDescription: 3 tests.
- buildWhenToInvokeSection: 3 tests.
- applyCatalogTrim: 4 tests covering the standard rewrite, no-op for
already-short descriptions, the YAML-collision newline fix, and the
malformed-frontmatter null return.
- proactive-suggestions.json determinism: 3 tests asserting sorted keys,
root keyed as "gstack" (not the worktree directory), and no
timestamp/generated_at field that would flap CI freshness.
Test plan:
- bun test test/catalog-trim.test.ts: 20 pass, 0 fail
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(coverage): fill three remaining v1.46.0.0 test gaps
Three untested surfaces from the v1.46.0.0 work. All three would have
caught real bugs we shipped (and fixed) on this branch.
1. test/helpers/budget-override.test.ts — 7 tests pin the audit-trail
contract for EVALS_BUDGET_OVERRIDE_REASON and
GSTACK_SIZE_BUDGET_OVERRIDE_REASON. Without this, the audit logger
could silently drop events and overrides become invisible. Tests
cover: required fields per JSONL line, CI provenance capture
(CI/GITHUB_ACTIONS/branch/commit), local-runner defaults,
append-only behavior, missing-directory recovery, and unwritable-
path resilience (logs warning instead of throwing).
2. test/terse-build.test.ts — 16 tests pin --explain-level=terse
behavior across the 4 gated resolvers and the composed preamble.
Default vs terse vs undefined-ctx all asserted. Without this, a
refactor that breaks the explainLevel threading silently regresses
the opt-in compression path; the runtime EXPLAIN_LEVEL: terse gate
still works so users wouldn't notice. Tier-1 invariant pinned
(terse-only-affects-tier-2+).
3. test/gen-skill-docs-idempotency.test.ts — 2 tests catch the class
of bug behind the v1.45.0.0 timestamp flap. Two consecutive
gen-skill-docs runs must produce byte-identical outputs across
STABLE_OUTPUTS (proactive-suggestions.json, SKILL.md, ship/SKILL.md,
plan-ceo-review/SKILL.md, office-hours/SKILL.md, gstack/llms.txt).
--dry-run reports zero stale files after a fresh gen. CI freshness
regressions surface as test failures BEFORE a PR is opened.
Test plan:
- bun test test/helpers/budget-override.test.ts: 7 pass
- bun test test/terse-build.test.ts: 16 pass
- bun test test/gen-skill-docs-idempotency.test.ts: 2 pass
- Full focused suite (15 test files): 1179 pass, 0 fail (+45 new tests
vs the pre-fill baseline of 1134)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(coverage): close 5 remaining v1.46.0.0 test gaps (A-E)
Five behaviors that v1.46 ships but had no test coverage. All now pinned.
A) --host all idempotency (test/gen-skill-docs-idempotency.test.ts)
The default test ran Claude host only. Non-Claude hosts (Codex, Factory,
Cursor, OpenClaw, GBrain, Slate, OpenCode, Hermes, Kiro) each have their
own output paths and could carry their own non-deterministic fields. We
hit a "--host all needed for freshness check" mid-/ship. Now: two
consecutive `bun run gen:skill-docs --host all` runs must produce
byte-identical outputs across a per-host sample (.agents/, .cursor/,
.factory/, .gbrain/). Catches per-host adapter regressions before CI.
B) --catalog-mode=full opt-out (test/catalog-mode-full.test.ts)
The legacy escape hatch had zero tests. 6 new tests across two layers:
static (CATALOG_MODE_ARG parsed; conditional gate present; default is
"trim"; invalid value throws) + smoke (actual --catalog-mode=full run
produces a multi-line `description: |` block + omits "## When to invoke"
body section; mutates the working tree then restores in a finally block).
C) parity-baseline-v1.44.1.json integrity (test/parity-baseline-integrity.test.ts)
The baseline is the source of every v1→v2 number cited in the
CHANGELOG v1.46.0.0 entry. Anyone could edit it without test failure
until now. 8 new tests pin: existence, tag, capturedFromCommit
allowlist, expected v1.44 numbers (51 skills, ~2,915 KB, ~9,319
catalog tokens), CHANGELOG references this file by path, per-skill
shape, and a SHA256 byte-stability hash. Any edit fails with a clear
"if intentional, update EXPECTED_HASH AND the CHANGELOG numbers" signal.
D) Live appliesTo gate end-to-end (test/resolver-entry.test.ts extended)
The unwrapResolver unit tests covered the function; the gen-skill-docs.ts
substitution loop that USES the gate had no integration coverage. 6 new
tests simulate the exact 4-line shape from gen-skill-docs.ts:457-467
against synthetic registries: plain-function fires unconditionally,
gated fires when true / empty-string when false, mixed registries
compose, parameterized resolvers respect gates, unknown resolvers throw.
E) Per-skill min-size floor (test/skill-size-budget.test.ts extended)
The existing 200-byte body coverage-floor is a noise floor — a skill
that lost 99.75% of content still passes. 1 new test asserts every
skill stays ≥80% of its v1.44.1 baseline size (the parity-suite
content invariants only covered 10 of 51 skills; the remaining 41
were uncovered). SECTIONS_EXTRACTED hook in place for v2.0.0.0 when
the sections/ pattern legitimately shrinks ship/plan-ceo/etc. past
the floor.
Test plan:
- bun test focused 17-file suite: 1202 pass, 0 fail
(+23 new tests vs the pre-fill 1179 baseline)
- catalog-mode=full mutates working tree then restores cleanly
- --host all idempotency runs two full gen passes in <1s on this machine
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
|
|
Garry Tan
|
dde55103fc
|
v1.15.0.0 feat: slim preamble + real-PTY plan-mode E2E harness (#1215)
* chore: add gstack skill routing rules to CLAUDE.md
Per routing-injection preamble — once-per-project addition that lets
agents auto-invoke the right gstack skill instead of answering generically.
* refactor: slim preamble resolvers + sidecar-symlink helper
Compress prose across 18 preamble resolvers — Voice, Writing Style,
AskUserQuestion Format, Completeness Principle, Confusion Protocol,
Context Health, Context Recovery, Continuous Checkpoint, Lake Intro,
Proactive Prompt, Routing Injection, Telemetry Prompt, Upgrade Check,
Vendoring Deprecation, Writing Style Migration, Brain Sync Block,
Completion Status, and Question Tuning. Same semantic contract, ~half
the bytes. Restored "Treat the skill file as executable instructions"
phrase in the plan-mode info section after diagnosing it as load-bearing.
Restored "Effort both-scales" rule in AskUserQuestion format.
Bonus: scripts/skill-check.ts gains isRepoRootSymlink() so dev installs
that mount the repo root at host/skills/gstack as a runtime sidecar
(e.g., codex's .agents/skills/gstack) get skipped instead of double-counted.
opus-4-7 model overlay gets a Fan-Out directive — explicit instruction
to launch parallel reads/checks before synthesis.
Net token impact across all generated SKILL.md files: ~140K tokens
removed across 47 outputs. Plan-* skills retain full preamble surface
(Brain Sync, Context Recovery, Routing Injection) — load-bearing
functionality that early slim attempts incorrectly cut.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore: regenerate SKILL.md outputs after preamble slim
bun run gen:skill-docs --host all output. Mirrors the resolver changes
in the previous commit. 47 generated SKILL.md files plus 3 ship-skill
golden fixtures.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(test): real-PTY harness for plan-mode E2E tests
Adds test/helpers/claude-pty-runner.ts. Spawns the actual claude binary
via Bun.spawn({terminal:}) (Bun 1.3.10+ has built-in PTY — no node-pty,
no native modules), drives it through stdin/stdout, and parses rendered
terminal frames. Pattern adapted from the cc-pty-import branch's
terminal-agent.ts but stripped of WS/cookie/Origin scaffolding (not
needed for headless tests).
Public API:
- launchClaudePty(opts) — boots claude with --permission-mode plan|null,
auto-handles the workspace-trust dialog, returns a session handle.
- session.send / sendKey / waitForAny / waitFor / mark / visibleSince /
visibleText / rawOutput / close
- runPlanSkillObservation({skillName, inPlanMode, timeoutMs}) — high-level
contract for plan-mode skill tests. Returns { outcome, summary, evidence,
elapsedMs }. outcome ∈ {asked, plan_ready, silent_write, exited, timeout}.
Replaces the SDK-based runPlanModeSkillTest from plan-mode-helpers.ts
which never worked. Plan mode renders its native "Ready to execute"
confirmation as TTY UI (numbered options with ❯ cursor), not via the
AskUserQuestion tool — so the SDK's canUseTool interceptor never fired
and the assertion always saw zero questions. Real PTY observes the
rendered output directly.
Deletes test/helpers/plan-mode-helpers.ts. No production callers remained.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test: rewrite 5 plan-mode E2E tests on the real-PTY harness
Replaces SDK-based assertions with runPlanSkillObservation contract. Each
test launches real claude --permission-mode plan, invokes the skill, and
asserts the outcome reaches 'asked' or 'plan_ready' within a 300s budget
(no silent Write/Edit, no crash, no timeout).
Affected:
- test/skill-e2e-plan-ceo-plan-mode.test.ts
- test/skill-e2e-plan-eng-plan-mode.test.ts
- test/skill-e2e-plan-design-plan-mode.test.ts
- test/skill-e2e-plan-devex-plan-mode.test.ts
- test/skill-e2e-plan-mode-no-op.test.ts (inPlanMode: false; tests the
preamble plan-mode-info no-op path)
test/e2e-harness-audit.test.ts — recognize runPlanSkillObservation as a
valid coverage path alongside the legacy canUseTool / runPlanModeSkillTest.
test/helpers/touchfiles.ts — point the 5 plan-mode test selections and
the e2e-harness-audit selection at test/helpers/claude-pty-runner.ts
instead of the deleted plan-mode-helpers.ts.
Proof: bun test EVALS=1 EVALS_TIER=gate on these 5 files runs sequentially
in 790s and passes 5/5. Same tests were 0/5 on origin/main, on v1.0.0.0,
and on this branch with the SDK harness.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test: align unit tests with slim resolvers + exempt 27MB security fixture
- test/skill-validation.test.ts: assert the slim Completeness Principle
shape (Completeness: X/10, kind-note language) instead of the old
Compression table. Remove the 3 tier-1 skills from the spot-check list
(they intentionally don't carry the full Completeness Principle
section). Exempt browse/test/fixtures/security-bench-haiku-responses.json
(27MB deterministic replay fixture for BrowseSafe-Bench) from the 2MB
tracked-file gate. The gate was actually failing on origin/main since
the fixture was added in v1.6.4.0 — this is a side-fix to a real
regression.
- test/brain-sync.test.ts: developer-machine-safe assertion for
GSTACK_HOME override (compare config contents before/after instead of
asserting the absence of a string that may legitimately exist).
- test/gen-skill-docs.test.ts: new tests for the slim — plan-review
preambles stay under the post-slim budget (~33KB), Voice + Writing
Style sections stay compact, and the slim Voice section preserves the
load-bearing semantic contract (lead-with-the-point, name-the-file,
user-outcome framing, no-corporate, no-AI-vocab, user-sovereignty).
Update path-leakage scan to allow repo-root sidecar symlinks.
- test/writing-style-resolver.test.ts: assert the compact contract
(gloss-on-first-use, outcome-framing, user-impact, terse-mode override)
instead of the old 6-numbered-rules shape.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore: bump version and changelog (v1.13.1.0)
Slim preamble work + real-PTY plan-mode E2E harness on top of v1.13.0.0.
SKILL.md corpus -25.5% (3.08 MB → 2.30 MB, ~196K tokens). 5 plan-mode
tests go from 0/5 to 5/5 (790s sequential), the first time those tests
have ever passed. Side-fixes for the 27MB security fixture warning and
the sidecar-symlink double-count.
Reverts the Fan-Out directive accidentally restored to opus-4-7.md —
v1.10.1.0's overlay-efficacy harness measured -60pp fanout vs baseline
when the nudge was active. The intentional removal stays.
TODOS:
- Pre-existing test failures from v1.12.0.0 ship: RESOLVED on main + this branch
- security-bench-haiku-responses.json size gate: RESOLVED via warn-only + exemption
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(test): harness primitives — parseNumberedOptions + budget regression utils
claude-pty-runner.ts:
- parseNumberedOptions(visible) anchors on the latest "❯ 1." cursor and
returns {index, label}[]; tests that route on option labels can find
indices without hard-coding positions
- isPermissionDialogVisible(visible) detects file-grant + workspace-trust
+ bash-permission shapes (multiple regex variants)
- isNumberedOptionListVisible: replaced \b2\. word-boundary regex with
[^0-9]2\. — stripAnsi removes TTY cursor-positioning escapes that
collapse "Option 2." to "Option2.", and \b fails on word-to-word
eval-store.ts:
- findBudgetRegressions(comparison, opts?) — pure function returning
tests where tools or turns grew >cap× vs prior run; floors at 5 prior
tools / 3 prior turns to avoid noise on tiny numbers
- assertNoBudgetRegression() — wrapper that throws with full violation
list. Env override GSTACK_BUDGET_RATIO
helpers-unit.test.ts: 23 unit tests covering empty/sparse/wrap-around
buffers for parseNumberedOptions, plus regression-floor + env-override
cases for findBudgetRegressions/assertNoBudgetRegression.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test: register 6 real-PTY E2E touchfiles + UI-heavy plan fixture
touchfiles.ts:
- 6 new entries in E2E_TOUCHFILES keyed to the new test files
- 6 matching E2E_TIERS classifications: 3 gate (auq-format-pty,
plan-design-with-ui-scope, budget-regression-pty), 3 periodic
(plan-ceo-mode-routing, ship-idempotency-pty, autoplan-chain-pty)
- gate ones are cheap/deterministic; periodic ones run weekly
touchfiles.test.ts:
- update the "skill-specific change selects only that skill" count
from 15 → 18 (plan-ceo-review/SKILL.md change now also selects
auq-format-pty, plan-ceo-mode-routing, autoplan-chain-pty)
test/fixtures/plans/ui-heavy-feature.md:
- planted plan with explicit UI scope keywords (pages, components,
Tailwind responsive layout, hover/loading/empty states, modal,
toast). Used by plan-design-with-ui-scope and autoplan-chain tests.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(test): 3 gate-tier real-PTY E2E tests
skill-e2e-auq-format-compliance.test.ts (~$0.50/run, 90-130s):
- Asserts /plan-ceo-review's first AUQ contains all 7 mandated format
elements (ELI10, Recommendation, Pros/Cons with ✅/❌, Net,
(recommended) label). Catches drift in the shared preamble resolver
that previously took weeks to notice.
- Auto-grants permission dialogs that fire during preamble side-effects
(touch on .feature-prompted markers in fresh user environments).
- Verified PASS in 126s.
skill-e2e-plan-design-with-ui.test.ts (~$0.80/run, 50-90s):
- Counterpart to the existing no-UI early-exit test. When the input plan
DOES describe UI changes, /plan-design-review must NOT early-exit and
must reach a real skill AUQ.
- Sends the slash command without args, then a follow-up message with
the UI-heavy plan description (Claude Code rejects unknown trailing
args). Asserts evidence does NOT contain "no UI scope".
- Verified PASS in 54s.
skill-budget-regression.test.ts (free, gate):
- Library-only assertion. Reads the most recent eval file, finds the
prior same-branch run via findPreviousRun, computes ComparisonResult,
asserts no test exceeded 2× tools or turns.
- Branch-scoped: skips with reason if the latest eval was produced on
a different branch (cross-branch comparison would be noise).
- First-run grace (vacuous pass) when no prior data exists.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(test): 3 periodic-tier real-PTY E2E tests
skill-e2e-plan-ceo-mode-routing.test.ts (~$3/run, 6-10 min/case):
- Verifies AUQ answer routing: HOLD SCOPE → rigor/bulletproof posture
language; SCOPE EXPANSION → expansion/10x/dream language. Each case
navigates 8-12 prior AUQs (telemetry, proactive, routing, vendoring,
brain, office-hours, premise, approach) before hitting Step 0F.
- Periodic, not gate: navigation phase too slow for PR-blocking.
V2 expansion to 4 modes (SELECTIVE + REDUCTION) when nav is faster.
skill-e2e-ship-idempotency.test.ts (~$3/run, 5-10 min):
- Builds a real git fixture with VERSION 0.0.2 already bumped, matching
package.json, CHANGELOG entry, pushed to a local bare remote. Runs
/ship in plan mode and asserts STATE: ALREADY_BUMPED echoes from the
Step 12 idempotency check, OR plan_ready terminates without mutation.
- Snapshots VERSION + package.json + CHANGELOG entry count + commit
count + branch HEAD before/after; fails if any changed.
skill-e2e-autoplan-chain.test.ts (~$8/run, 12-18 min):
- Asserts /autoplan phases run sequentially: tees timestamps as each
"**Phase N complete.**" marker first appears. Phase 1 (CEO) must
precede Phase 3 (Eng); Phase 2 (Design) is optional but if it
appears, must sit between 1 and 3.
- Auto-grants permission dialogs that fire during phase transitions.
All three auto-handle permission dialogs (preamble side-effects on
fresh user envs without .feature-prompted-* markers).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test: spell out AskUserQuestion everywhere instead of AUQ
Per user feedback: don't shorten AskUserQuestion to AUQ — the
abbreviation reads as cryptic. Apply across all the new code from this
branch:
- Rename test/skill-e2e-auq-format-compliance.test.ts →
test/skill-e2e-ask-user-question-format-compliance.test.ts
- Touchfile entry auq-format-pty → ask-user-question-format-pty
(touchfiles.ts + matching assertion in touchfiles.test.ts)
- Function rename navigateToModeAuq → navigateToModeAskUserQuestion
- Variable auqVisible → askUserQuestionVisible
- Outcome literal 'real_auq' → 'real_question'
- All comments + JSDoc + CHANGELOG entry write AskUserQuestion in full
- "AUQs" plural → "AskUserQuestions"
No behavior change. 49/49 free tests still pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: harden v1.15.0.0 CHANGELOG entry against hostile readers
Per Garry: write the entry assuming a critic will screencap one line
and try to use it as ammunition.
Reframed the v1.15.0.0 release-summary to lead with new capability
(real-PTY harness, 11 plan-mode tests, +6 new) instead of fix-of-prior-
flaw narrative. Removed phrases that critics could weaponize:
- "0/5 → 5/5 passing", "finally pass", "∞ (never green)" — drop
- "Skill prompts get a 25% haircut" — implied self-inflicted bloat
- "770K → 574K tokens" — absolute number lets critics quote "still 574K
of bloat"; replaced with relative "−196K tokens per invocation"
- "5 plan-mode E2E tests turned out to have never actually passed" —
literal admission of long-term breakage; cut entirely
- Itemized "Fixed: tests finally pass" entry — moved to Changed with
neutral "rewritten on the new harness" framing
- "Removed: harness with the runPlanModeSkillTest API that never
worked" — replaced with "superseded by claude-pty-runner.ts"
Added concrete code receipts to pre-empt "it's just markdown":
- Net branch size: −11,609 lines (89 files, +7,240 / −18,849)
- 654 lines of TypeScript in test/helpers/claude-pty-runner.ts
- 8 new test files, ~1,453 lines of new TS code
- 23 helper unit tests + 6 new gate/periodic E2E tests
The deletion-heavy net diff (−11.6K lines) is itself the strongest
defense against the "bloat" critique — surfaced explicitly in the
numbers table.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|