From 53c2f8988cd22dc4f49b1caf9edc77011b21e040 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Tue, 25 Aug 2026 20:50:15 +0000 Subject: [PATCH] chore: bump version and changelog (v1.70.0.0) Co-Authored-By: Claude Fable 5 --- CHANGELOG.md | 55 +++++++++++++++++++++---------- TODOS.md | 93 +++++++++++++++++++++++++++++++++++----------------- VERSION | 2 +- package.json | 2 +- 4 files changed, 102 insertions(+), 50 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3aca7948b..83ee3a2f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,38 +1,57 @@ # Changelog -## [1.69.1.0] - 2026-08-25 +## [1.70.0.0] - 2026-08-25 -**Prompt bloat now fails CI.** -**Every skill's context cost has a ceiling, and ceilings only ratchet down.** +**Every skill invocation just got half the prompt bill.** +**Same behavior, measured by A/B evals, locked by CI ceilings.** -Every gstack skill invocation pays a fixed prompt cost before it does any work, and until now nothing stopped that cost from creeping. This release checks in a context-budget ratchet: a free test that grades two token ledgers, the always-on frontmatter catalog every session loads and the per-invocation cost of each skill, against ceilings committed in a fixture. A skill that grows past its ceiling fails `bun run test`. A new skill with no ceiling fails until someone consciously budgets it. When a reduction lands, one command re-captures the fixture and the win is locked. Five skills also shed dead frontmatter keys that no runtime, host, or test ever read from the generated files. +Every gstack skill pays a fixed prompt cost before doing any work. This release cuts that cost across all 62 skills and pins the wins so they can't creep back. The shared preamble's bash moved into two runtime scripts (`bin/gstack-skill-start`, `bin/gstack-skill-end`) that echo the same STATUS lines the prose always interpreted. One-time onboarding text now appears only when its gate actually fires, emitted as session-bound instruction blocks instead of riding along in every render. Twelve more skills got the section carve, taking the carved roster from 9 to 20: heavy reference bodies load on demand at the step that needs them, never before. ### The numbers that matter -Source: `bin/gstack-context-bill` (offline, calibrated estimate) and `test/fixtures/context-budget.json` in this release. +Source: `bin/gstack-context-bill --diff` comparing the main render against this branch's render, both regenerated from source. -| Metric | Value | -|---|---| -| Always-on frontmatter, whole catalog | ~6.0K tokens actual, 6,344 ceiling (x1.05) | -| Per-skill eager ceilings enforced | 59 (x1.10 headroom each) | -| Heaviest skills today | `/land-and-deploy` ~26.7K and `/review` ~26.6K tokens per invocation | -| Dead frontmatter lines removed | 8 across 5 skills | +| Ledger | Before | After | Δ | +|---|---|---|---| +| /review eager per invocation | 109.5KB (~26.6K tok) | 53.7KB (~13.0K tok) | −51% | +| /land-and-deploy eager | 109.8KB | 54.4KB | −50% | +| /codex eager | 100.0KB | 53.9KB | −46% | +| Corpus on disk | 6.4MB (~1,651K tok) | 5.4MB (~1,398K tok) | −15% | +| Repo CLAUDE.md (always-on in dev sessions) | 66.4KB | 44.9KB | −32% | -That ~26.7K number is the point. This release is the measurement-and-enforcement phase of a reviewed token-reduction program; the phases that follow move preamble bash into `bin/` scripts and carve the heavyweight skills, targeting ~13-15K for `/review`. The ratchet is what makes each of those wins permanent instead of aspirational. +Every one of the 62 skills dropped. The smallest cut is −4,780 tokens per invocation (tier-1 utilities); non-carved tier-2 skills each shed a flat ~20.8KB of preamble. Zero always-on or eager growth anywhere in the diff. -### What this means for gstack users +The behavioral proof ran before this shipped: an A/B eval pins the script render against the old inline render, a section-loading eval verifies a real agent Reads each carved section before doing its step (20 skills, data-driven), and the full paid gate passed with the environmental-only baseline. The context-budget ratchet re-captured after every wave, so each ceiling now sits at the new, lower number. -Nothing changes in how you invoke skills today. What changes is the trajectory: context cost is now a tested invariant, so every future release either holds the line or gets consciously cheaper. If you maintain skills, budget growth is a visible decision in your diff, not a silent tax on every session. Upgrade normally. +### What this means for you + +The agent reads roughly half the boilerplate before starting your task, so first-token latency and per-invocation cost drop across every skill you run. Onboarding prompts you already answered never render again. Nothing else should feel different: if a skill behaves differently than it did on v1.69, that's a bug, and the A/B harness exists to catch it. Run `bun run test` after upgrading; the ratchet will tell you if anything grew. ### Itemized changes ### Added -- Context-budget ratchet: `test/context-budget-ratchet.test.ts` grades the always-on and per-invocation token ledgers against `test/fixtures/context-budget.json` via `checkBudget`; regenerate ceilings with `bun test/helpers/capture-context-budget.ts` (atomic write). New skills must be budgeted; removed skills must be pruned; fixture shape is validated so a malformed ceiling cannot silently disable enforcement. -- Coverage for the previously-untested `alwaysOnTotal` violation branch in `lib/context-bill.ts`, a capture round-trip test pinning the headroom math, Windows path-separator normalization pins, and a regression pin that generated Claude renders strip gen-time-only frontmatter keys while keeping host-read (`hooks:`) and runtime-read (`gbrain:`) keys. +- `bin/gstack-skill-start` / `bin/gstack-skill-end`: the preamble and telemetry runtime, replacing ~18KB of inline bash per tier-2+ skill. Emits a `SKILL_START_PROTO: 1` handshake, STATUS lines, and gated one-time onboarding as `GSTACK_INSTRUCTION` blocks bound to a per-run session ID with a random suffix; passthrough output is sanitized so repo or prior-session content can never mint directive blocks or forge the session ID. +- `bin/gstack-retro-metrics`: deterministic git metrics for /retro (labeled contract, local reads only), replacing inline git/awk in the skill body. +- Section carves for 12 skills — review, codex, land-and-deploy, autoplan, spec, setup-gbrain, qa, browse, retro, office-hours (Phase 2A/2B), design-html, design-shotgun — each with registered guards, loading scenarios, and recomputed size floors. The design carves force-read their UX doctrine before design work begins. +- Context-budget ratchet: a free CI test grades the always-on catalog and each skill's per-invocation cost against committed ceilings; growth fails the suite, reductions re-capture and lock. +- Six reference docs extracted verbatim from the repo CLAUDE.md (browser internals, CHANGELOG format spec, project tree, hermetic-E2E notes, slop-scan guide, OpenClaw publishing), each replaced inline by a short rule plus pointer. ### Changed -- Claude renders no longer carry `interactive:` and `benefits-from:` frontmatter (gen-time inputs with no reader of the generated copy) — 8 dead lines across autoplan and the four plan-review skills, trimming the catalog every session loads. -- The ratchet bill pins the root skill to a stable key, dedupes symlink-aliased skills by realpath (one ceiling per physical skill, Windows-checkout safe), and rebuilds all totals from the filtered skill list. +- The AskUserQuestion tool-resolution and 5+-option rules render as a compact branch table keyed on echoed STATUS lines; full split/CJK rules live at absolute install paths read on demand. All 14 mandatory format pins stay in every tier-2+ skeleton. +- ios-fix, ios-clean, ios-sync, and ios-design-review dropped to preamble tier 2 (they never used the tier-3 sections). +- The preamble degrades safely on stale installs: missing handshake means safe defaults, deferred onboarding (consent is never lost), and a one-line upgrade hint. +- The privacy consent gate and telemetry prompt fire only in interactive sessions; spawned and headless runs defer them to the next human session. +- Hermetic E2E children get seeded onboarding state in their own `GSTACK_HOME`, so evals never burn turns on first-run prompts. + +### Fixed +- The once-daily artifacts pull is now non-interactive and slow-network bounded, so a hung remote can't stall the first skill invocation of the day. +- Branch names and artifacts-repo state files are sanitized before entering STATUS output and timeline records, closing log-forgery paths via hostile ref names or planted files. +- Skill-start no longer parses a multi-megabyte `~/.claude.json` on every invocation when no gbrain server is registered. + +### For contributors +- Preamble A/B eval (`skill-e2e-preamble-script-ab`, periodic tier) pins script-render behavior against the pre-consolidation inline render; the carve-section-loading eval covers all 20 carved skills at an honest 480s ceiling. +- New free tests: skill-start/skill-end contract and behavior (15), retro-metrics (11), onboarding moved-literals tombstone (12), context-budget ratchet (7). Parity baseline and ratchet fixtures re-captured; the shrink floor stays (OV8 evaluated). +- `test/helpers/touchfiles-data.ts`: the runtime scripts joined every dep list that named the moved generators, so diff-based eval selection still fires on script changes. ## [1.69.0.0] - 2026-08-22 diff --git a/TODOS.md b/TODOS.md index 0c3936069..0c464b02b 100644 --- a/TODOS.md +++ b/TODOS.md @@ -628,40 +628,41 @@ output, then retire or simplify the guard. Effort: human ~half day / CC ~20 min. ## Token-reduction follow-ups (Phase B, filed via /plan-eng-review on the plan-ceo-review carve) -### P3: Carve the always-loaded `{{PREAMBLE}}` reference blocks into an on-demand doc +### P2: v1.70 ship-review deferrals (specialist + adversarial findings, each verified) -**What:** The per-skill section carves (`/ship` v1.54, `/plan-ceo-review` v1.56) yield -real but bounded wins (-42% to -59% on the carved skill) because the shared -`{{PREAMBLE}}` (~40-50KB on every tier-3/4 skill) is the dominant always-loaded cost -and stays inline. Move the rarely-needed preamble REFERENCE blocks (the AskUserQuestion -split-rules and the CJK / lone-surrogate escaping reference) into an on-demand -section-style doc the agent reads only when it hits those edge cases, leaving the hot -path (voice, completeness principle, recommendation format) inline. +**What:** Follow-ups deferred from the v1.70.0.0 pre-landing review, none ship-blocking: -**Why:** Highest-ROI remaining token target. One preamble carve helps EVERY tier-≥2 -skill at once, not one skill per PR. The eng-review on the plan-ceo carve flagged that -per-skill carves stay modest precisely because the preamble dominates the always-loaded -surface. +- **Batch the 11 `gstack-config get` forks in `bin/gstack-skill-start`** into one config + read (~60-250ms of preamble latency per skill invocation, worse on macOS). The + consolidation into one script is what makes batching trivial now. +- **Cache the `gbrain --version` probe** (Node CLI cold start, 100-300ms per invocation + for gbrain users) keyed on binary path + mtime. +- **`bin/gstack-retro-metrics`: single-pass diffs** — combine the `--numstat` and `-p` + passes (`git log --numstat -p`), unify the three test-file definitions (`is_test`, + the awk regex, the repo-wide grep), and cover the `origin/` ref preference + + 300-commit/40-coauthor truncation paths with tests. +- **Rename `generate-upgrade-check.ts`** — it now emits only PROACTIVE/SKILL_PREFIX + rules; the name misleads anyone hunting for upgrade-prompt rendering. +- **evals.yml gate matrix drift:** 9 pre-existing gate-tier files in `E2E_TIERS` are + absent from the static suite matrix, so they never run in PR CI. Add them (or prune + their tier), plus a free tripwire test diffing gate-tier `E2E_TIERS` against the + workflow matrix so the class can't recur. +- **`_sanitize` case/separator variants:** the strip is exact-literal; make it + case-insensitive and separator-tolerant, with pinned variant cases. +- **Telemetry unset-vs-off semantics:** `gstack-skill-start` treats an UNSET telemetry + key as enabled for the LOCAL analytics write (pre-consent recording, local-only); + `gstack-telemetry-log` maps unset to off. Decide one semantic and document it. +- **Coverage gaps from the ship audit:** `--brain-health` block (zero tests), the + learnings `>5`-entries sanitize passthrough (poison test), session prune + + `.pending-*` finalize loop, and a shared `ONBOARDING_MARKERS` constant for the three + seed sites (hermetic-env, e2e-helpers, the script's gates). -**Pros:** A single change reduces always-loaded cost across the whole skill pack. -**Cons:** The preamble is load-bearing and shared; a botched carve regresses every skill. -Needs the same union-parity + per-push freshness guards the section carves use, applied -corpus-wide. +**Why:** Each was found by the v1.70 review army with file:line evidence; all are quality +or latency wins on the new runtime scripts, none change behavior contracts. -**Context:** Builds on the v2 section pipeline (`scripts/resolvers/sections.ts`, -`{{SECTION:id}}` / `{{SECTION_INDEX}}`). The preamble source is -`scripts/resolvers/preamble.ts`. Measure which sub-blocks are cold (escaping reference, -split-rules) vs hot (voice, recommendation format) before cutting. Validate on one skill, -then roll corpus-wide. - -**Effort estimate:** L (human team) → M (CC+gstack) -**Priority:** P3 -**Depends on / blocked by:** The section pipeline (shipped v1.54). No hard blocker. -**Status update (2026-08-25):** IN FLIGHT — superseded by the approved token-reduction -program on branch `prompt-token-load-reduction` (plan reviewed via CEO + eng + 2x -outside voice). Phases 1-3 of that program implement this carve in a stronger form -(bash → `bin/gstack-skill-start`/`-end`, conditional onboarding echo, AUQ slim). -Phase 0 (context-budget ratchet, dead-key strip) already landed on the branch. +**Effort estimate:** M (human team) → S (CC+gstack) +**Priority:** P2 +**Depends on / blocked by:** v1.70.0.0 landing. ### P3: Output-template carve wave — REVIEW_DASHBOARD + PLAN_FILE_REVIEW_REPORT @@ -2892,6 +2893,38 @@ needs one paid run to validate, so it didn't ride the ship. ## Completed +### P3: Carve the always-loaded `{{PREAMBLE}}` reference blocks into an on-demand doc + +**What:** The per-skill section carves (`/ship` v1.54, `/plan-ceo-review` v1.56) yield +real but bounded wins (-42% to -59% on the carved skill) because the shared +`{{PREAMBLE}}` (~40-50KB on every tier-3/4 skill) is the dominant always-loaded cost +and stays inline. Move the rarely-needed preamble REFERENCE blocks (the AskUserQuestion +split-rules and the CJK / lone-surrogate escaping reference) into an on-demand +section-style doc the agent reads only when it hits those edge cases, leaving the hot +path (voice, completeness principle, recommendation format) inline. + +**Why:** Highest-ROI remaining token target. One preamble carve helps EVERY tier-≥2 +skill at once, not one skill per PR. The eng-review on the plan-ceo carve flagged that +per-skill carves stay modest precisely because the preamble dominates the always-loaded +surface. + +**Pros:** A single change reduces always-loaded cost across the whole skill pack. +**Cons:** The preamble is load-bearing and shared; a botched carve regresses every skill. +Needs the same union-parity + per-push freshness guards the section carves use, applied +corpus-wide. + +**Context:** Builds on the v2 section pipeline (`scripts/resolvers/sections.ts`, +`{{SECTION:id}}` / `{{SECTION_INDEX}}`). The preamble source is +`scripts/resolvers/preamble.ts`. Measure which sub-blocks are cold (escaping reference, +split-rules) vs hot (voice, recommendation format) before cutting. Validate on one skill, +then roll corpus-wide. + +**Effort estimate:** L (human team) → M (CC+gstack) +**Priority:** P3 +**Depends on / blocked by:** The section pipeline (shipped v1.54). No hard blocker. +**Completed:** v1.70.0.0 (2026-08-25) — delivered in a stronger form by the token-reduction program: preamble bash moved to `bin/gstack-skill-start`/`-end`, one-time onboarding became gated instruction blocks, AUQ reference rules point at on-demand docs, and 12 more skills got section carves (20 total). Wins locked by the context-budget ratchet. + + ### ✅ DONE (v1.69.0.0): `./setup --host slate` accepted but installs nothing **Priority:** P4 (was filed as slate-only — shipped with the whole drift class gated) diff --git a/VERSION b/VERSION index 2c3f8d533..d36d926d9 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.69.1.0 +1.70.0.0 diff --git a/package.json b/package.json index 67ba3e978..6e7631517 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "gstack", - "version": "1.69.1", + "version": "1.70.0", "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.", "license": "MIT", "type": "module",