CalvinBackup/gstack
1
0
Fork 0
mirror of https://github.com/garrytan/gstack.git synced 2026-08-23 14:32:33 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
410b4928e7caa229b92827fa3e8cc95a49bb757b
gstack/CLAUDE.md
T
Garry TanandClaude Fable 5 410b4928e7 v1.66.0.0 feat: test/evals/CI speedup — 90s truthful free suite, diff-billed evals, required Linux lane (#2593) 
* ci: bump CI image Bun 1.3.10 -> 1.3.13

Matches the local toolchain and brings native `bun test --shard=M/N` /
--parallel to CI (needed by the free-test lane and shard runner work).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci: stop version bumps rebuilding the eval Docker image (cache key trio)

Three coupled fixes, atomic because any subset is worse than none:

1. Image tag keys on hashFiles(Dockerfile.ci, bun.lock) — package.json is
   out: its version field changed on 60/60 recent commits, forcing a ~2min
   image rebuild per PR for a dependency set only bun.lock determines.
2. ci-image.yml now pushes that same content-hash tag (previously only
   :latest/:sha, so the weekly prebuild never warmed the tag the eval
   matrix actually looks up) and both eval workflows get registry layer
   cache (cache-to export gated to same-repo runs; fork tokens cannot
   write GHCR).
3. Dockerfile bakes /opt/node_modules_cache/.bun.lock and the runtime
   Restore-deps guard diffs bun.lock instead of package.json — otherwise
   every version-only bump made all 14 matrix jobs fall back to a live
   bun install, which is slower than today's behavior.

Worst-case failure mode is self-healing: a missing tag or cache falls
back to exactly the previous rebuild-and-install path.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci: stop double-running lint + skill-docs on every PR commit

Both fired on unrestricted push AND pull_request, so each PR push ran
them twice (12 duplicate (headSha, workflow) pairs in the last 200 runs).
push is now main-only; pull_request covers PR branches.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci: run actionlint from the prebuilt image (16s -> ~2s)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci: right-size five single-core jobs to ubicloud-standard-2

actionlint, skill-docs, version-gate, pr-title-sync, and the evals report
job never exceed one core; standard-8 was ~4x the cost for zero wall-clock.
build-image and the eval matrix keep standard-8.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci: fix workflow_dispatch concurrency collisions (head_ref || run_id)

head_ref is empty on workflow_dispatch, so every manual dispatch of these
four workflows shared one empty-suffix group and cancelled each other.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci(windows): cache bun installs; run the curated suite, not a hand list

- actions/cache on ~/.bun/install/cache keyed on bun.lock (install was
  35-45s of both 55-64s jobs, all network) and Bun pinned to 1.3.13 to
  match the other lanes.
- windows-free-tests now runs `bun run test:windows` (the runner's
  --windows-only curation) instead of a hand-listed 13-file subset that
  had drifted from the registry it sampled. POSIX-bound tests get
  excluded in ONE place (the curation patterns), not two.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* evals: retry 1, not 2, on every paid path

Measured on the llm-judge shard: --retry 2 amplified 25 tests into 46
executions (+84%), with retried runs at 138s vs a 10-12s baseline (429
backoff), and a permanently-failing test paying 3x. One retry still
absorbs one-off flakes; chronic flakes become visible fix-work instead
of silent wall-clock.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* evals: split skill-e2e-review into three per-file CI shards

Bun runs describe blocks as concurrency barriers, so the e2e-review CI
job executed its tests serially: 741s of an 860s PR critical path for
tests whose slowest member is 224s. The per-file matrix is the repo's
parallelism unit, so the split moves:

- Retro E2E + retro-base-branch  -> test/skill-e2e-retro.test.ts
- review/ship base-branch + Review Dashboard Via Attribution
                                  -> test/skill-e2e-review-attribution.test.ts
- sql-injection / enum-completeness / design-lite stay in
  test/skill-e2e-review.test.ts

One 741s job becomes three ~180-250s jobs. Locally the worst paid shard
drops from 1705s (94.7% of the 1800s kill) to under 700s. Test names,
bodies, suite strings, and eval-store collectors are unchanged, so
baselines carry over. Matrix rows added to both eval workflows
(attribution is gate-only, so no periodic row); the report job's
hardcoded runner count is gone (drift-proof).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: gate security-bench on SECURITY_BENCH=1, not model-cache existence

The existsSync gate ran ~12s of ONNX inference (plus a HuggingFace
dataset fetch) on every free-suite run on any dev box that had ever
warmed the classifier, while CI (no cache) silently skipped it. Now
explicit opt-in: SECURITY_BENCH=1 bun test browse/test/security-bench.test.ts.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: watchdog E2E in 1.5s instead of 22.7s (tunable poll interval)

server.ts gains BROWSE_WATCHDOG_INTERVAL_MS (floor 50ms, default 15s
unchanged). The #994 stay-alive test runs a 250ms tick and waits for the
stay-alive log line instead of blind-sleeping 2s + 20s past the
production interval.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: dedupe coverage gates; route both walks through skill-census

skill-coverage-floor duplicated two matrix assertions (registry
completeness, gate-tier floor) with a DIFFERENT hand-rolled directory
walk — matrix's skipped nothing, floor's skipped node_modules/docs/test.
Two 'same' gates disagreeing on the census is the bug class
test/helpers/skill-census.ts was written to kill. Registry assertions
now live in matrix only (with floor's better error message), both files
walk via skillCensus().authoredSkills, and floor keeps the per-skill
structural checks it owns.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* evals: EVALS_JOBS for shard processes; explicit within-shard concurrency

EVALS_CONCURRENCY was overloaded: the legacy bun-test path used it as
--max-concurrency (default 15) while the sharded runner read it as the
process count — exporting the legacy value gave 15 concurrent Bun
processes each spawning claude (the 429 storm). Now: EVALS_JOBS = shard
processes (default 4); EVALS_CONCURRENCY = bun --max-concurrency inside
a shard (default 4, explicit in shard args — omitting it made
within-shard parallelism silently differ from the legacy path). Stale
49/59 header math replaced with the live-count rule.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* evals: enforce detach-timeout floor from the live shard census

New free tripwire: eval:bg:gate / eval:bg:periodic --timeout must cover
ceil(shards/jobs) x shard-timeout x 1.05, recomputed from the actual paid
test census every run. Hand-derived numbers go stale every time a paid
file lands — the review split just proved it: periodic's 28800s dropped
BELOW its new 32130s worst case (raised to 32400s here). An undersized
watchdog kills healthy runs and the tail reports never-started.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* evals: preflight ping once in the sharded parent, not per shard

The Anthropic fail-fast ping ran at module load in every paid test file
importing e2e-helpers — ~30 paid claude -p calls (30s timeout each) per
full sharded run for one bit of information. The parent now pings once
before spawning shards and sets EVALS_PREFLIGHT_OK=1; the module-load
path honors the flag. Extracted to test/helpers/anthropic-preflight.ts
(injectable spawn seam) with regression pins in both directions: the
flag must skip, its absence must ping exactly once, dead API must throw.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* evals: split touchfiles into pure data + selection logic + facade

touchfiles.ts listed ITSELF in GLOBAL_TOUCHFILES, so adding one test's
dep entry forced the full ~$38 / 30-45min suite — measured on 21.9% of
recent commits (42/192). The self-reference existed because data and
logic shared a file: any edit COULD be a selection-logic change.

Now: touchfiles-data.ts (the four maps, literals only, zero imports —
the future map-diff target), test-selection.ts (matchGlob/detectBase
Branch/getChangedFiles/selectTests), and touchfiles.ts as a re-export
facade so all ~12 import sites are untouched. GLOBAL_TOUCHFILES drops
the self-ref, adds test-selection.ts (logic stays maximally
conservative), and TEMPORARILY adds touchfiles-data.ts until the
map-diff change lands. New free test pins the literal-only property
(comment-aware state-machine scan with a self-test) and facade export
parity (===), so neither can silently rot.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: free runner — strict output, parallel execution, stable shard indices

Three coupled changes to scripts/test-free-shards.ts:

1. STRICT OUTPUT: runFreeShard streams through the paid runner's
   BunTestOutputClassifier — exit 0 without bun's 'Ran N tests across M
   files' summary, with (fail) lines, or with a wrong file count is a
   FAILURE (anti-truncation backstop at the runner layer), plus an
   external wall-clock timeout that SIGKILLs the process group
   (timed-out distinct from failed; exit 124 vs 1). Also fixes a latent
   shard-bleed: file selectors now use exactTestFileSelectors (relative
   paths were substring filters that matched sibling roots).

2. PARALLEL: full-suite mode is one 'bun test --parallel' invocation
   (Bun 1.3.13). Measured semantics recorded in the header: per-file
   worker isolation, standard summary, and mid-suite process.exit
   surfaces as a crashed-worker FAIL with exit 1 — strictly safer than
   serial, where the same exit truncates silently. No static weight
   lists; --shards M --shard i keeps deterministic hash partitioning for
   CI matrices (native --shard rejected: round-robin renumbers when
   files land). Spawned shards get throwaway GSTACK_HOME/TMPDIR so
   parallel shards can't contend on real state. Per-shard epilogue
   prints files/seconds/status every run.

3. Stable indices: assignFilesToShards no longer drops empty shards, so
   a shard's index depends only on the file hash and requested count —
   an empty CI matrix slot is a fast no-op success, not a renumbering.

package.json 'test' now delegates to the runner (TEST_ROOTS becomes the
single source of truth for roots; slop:diff tail preserved; the runner
inherits the 30s per-test timeout the old glob passed inline).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci: Linux free-test lane — ~400 files get CI coverage for the first time

New required, secretless free-tests job: the canonical runner's single
'bun test --parallel' invocation with strict-output classification on
ubicloud-standard-8. The free suite previously ran on NO Linux CI — only
a curated Windows subset ran anywhere — so every 'tests pass' claim
about main rested on contributors running them locally.

Secretless by design (no API keys; fork PRs finally get real test
signal) and pinned by test/free-tests-workflow-wiring.test.ts: canonical
runner invoked, zero secrets.* references, pull_request never
pull_request_target, and matrix-count/--shards agreement if anyone
switches to the sharded fallback.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* evals: map-diff selection — a touchfiles-data edit runs only what changed

Editing the eval dep-list data no longer forces the full ~$38 /
30-45min suite (measured on 21.9% of recent commits). When
touchfiles-data.ts is in the diff, selection now evaluates the BASE
version (git show -> mkdtemp -> spawnSync bun child printing the four
maps as JSON — sync because e2e-helpers selects at module scope) and
JSON-diffs per key: added entries, edited dep lists, and tier flips are
selected; keys removed from all maps are reported, never silently
dropped; a GLOBAL_TOUCHFILES edit still runs everything.

FAIL-CLOSED with named causes: missing-base-ref, git-show-failed,
import-failed, shape-mismatch each degrade to run-all and print
'selection: global — touchfiles-data changed (<cause>)' (D9 — silently
expensive beats silently wrong, but never silently). eval:select prints
'selected N of M, reason: ...' + removed tests; --base scopes the
map-diff too.

The temporary conservative GLOBAL entry for touchfiles-data.ts is gone —
its changes route through the map-diff. 23 new free tests: pure-core
fixtures, selectTests wiring incl. a poison-injection guard, and a temp
git repo exercising every fail-closed cause end-to-end.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* evals: selection sees uncommitted work; git errors fail closed

getChangedFiles is now the deduped union of committed (base...HEAD),
staged+unstaged (git diff HEAD), and untracked (git status --porcelain
--untracked-files=all) — an agent that edits files and runs evals
BEFORE committing no longer gets the full $38 suite every time because
the committed diff looked empty. Clean tree still returns [] (run-all
by design for main-branch/periodic runs).

Git failures now THROW with the failing command, stderr, and 'set
EVALS_ALL=1 to deliberately run the full suite' — the old return []
silently became run-all, which is silently expensive. 11 new free tests
cover every source, dedupe, quoted paths, and both failure shapes via
an injectable spawn seam.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: revert GSTACK_HOME injection in the free runner — shared mutable state

The first full run under the strict runner surfaced 12 failures with one
root cause: injecting a single throwaway GSTACK_HOME per invocation made
6,900 tests share a MUTABLE scratch home. gstack-config tests wrote keys
into it; relink and update-check tests then read them (e.g. relink saw
skill_prefix left behind by a config test and produced prefixed names).
All 12 pass when run directly.

TMPDIR isolation stays (mkdtemp inside it is still per-call unique).
Tests needing GSTACK_HOME isolation mkdtemp their own per test — the
repo convention — and hermetic-env covers E2E children. The env-dump pin
now asserts GSTACK_HOME passes through UNTOUCHED so the injection can't
come back.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: rebase parity baseline to v1.64.0.0; fix capture-vs-check drift

The parity ratchet had quietly failed for 7 skills — v1.58-v1.64 growth
landed past the v1.57.7.0 anchors and nothing caught it because this
test had no CI lane (verified pre-existing: SKILL.md content is
byte-identical to origin/main). Same rebase protocol as
v1.53->v1.57.7.0; old baseline retained for the audit trail.

Root-caused a second latent bug while rebasing: captureBaseline recorded
SKELETON-ONLY bytes while the checker compares UNION bytes (skeleton +
carved sections/*.md), so a fresh capture read carved skills at ~2x
ratio (ship: 82KB captured vs 183KB checked). captureBaseline now takes
sectionedSkills and records unions for carved skills — capture and check
measure the same thing, so the NEXT rebase can't hit this. Four
CARVE_GUARDS skeleton caps re-ratcheted to current +headroom
(plan-ceo 92K, plan-eng 70K, office-hours 100K, design-consultation
70K), annotated inline.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: package.json version matches VERSION (1.64.0.0)

v1.64.0.0 shipped with VERSION bumped but package.json left at 1.63.0.0
— the 'package.json version matches VERSION file' test fails on
origin/main today. Nothing caught it because that test had no CI lane
until this branch's free-tests job.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: fix variants-retry-after HTTP-date flake (TODOS P2)

toUTCString() truncates to whole seconds, so a +3000ms Retry-After date
could mean an effective wait of ~2001ms — flaking against the 2500ms
assertion floor ~1-2 in 9 runs under suite load. +4000ms puts the
truncation floor at 3001ms with the assertion floor safely below it.
Pulled forward from U4 because the free-tests lane is now a required
check and this flake would randomly block PRs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: skill-fixture helper — extract SKILL.md sections, don't copy files

extractSkillSections (fence-aware H2 scanner, loud-throw on missing
sections with available-heading list), extractSkillBody (drops the
shared generated preamble), extractSkillHead (frontmatter + first 30
lines, for routing fixtures). Pinned section lists per consumer, and
free-tier real-skill pins so a gen-skill-docs heading rename fails the
FREE suite instead of a paid run. skill-fixture.ts joins
GLOBAL_TOUCHFILES (fail-safe polarity: over-select).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(evals): review E2E fixtures extract sections — 1871 -> 207 lines

CLAUDE.md's extract-don't-copy rule, applied: the three review fixtures
carry only the sections the sql-injection/enum/design-lite prompts and
judges exercise (89% cut). Full-file copies made claude -p read 1871
lines per test — the direct cause of the 1705s worst shard (94.7% of
the 1800s kill).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(evals): retro E2E fixtures extract sections — 1821 -> 757 lines

Keeps every section the retro flow exercises incl. base-branch detect;
drops preamble, Global Retrospective Mode, Compare Mode (58% cut).
retro-base-branch was the single slowest CI test at 224s.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(evals): review-army fixture extracts sections — 1871 -> 650 lines

CS1's set plus Step 1.5 (PLAN COMPLETION AUDIT machinery) and Step 4.5
(army dispatch, quality_score, findings schema) that the 7 army tests
assert on. Pin test guards the three load-bearing strings.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(evals): skillify fixtures via extractSkillBody — 63-83% smaller

Tests follow all 11 skillify steps, so the whole body stays; only the
shared generated preamble drops (skillify 1239->453, scrape 958->167).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(evals): context-skills fixtures via extractSkillBody — 74-82% smaller

context-save 1037->267 lines, context-restore 952->168; the 8 tests
exercise full save/restore/list flows so the body stays, preamble drops.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(evals): opus-47 discovery fixtures via extractSkillHead — ~95% smaller

Routing/fanout tests only read frontmatter + opening lines of the 14
installed skills (review 1871->54, office-hours 1706->80).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(evals): codex runner gains sections option — review variant 88% smaller

runCodexSkill/installSkillToTempHome accept sections?: string[] routed
through extractSkillSections; codex-review-findings wired (1465->181
lines). codex-discover-skill deliberately keeps the FULL copy — its
stderr assertions validate that the real generated artifact loads.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test(evals): routing fixture installs skill HEADS, not ~18 full SKILL.md

Routing reads frontmatter only; extractSkillHead per skill (root
611->48, ship 1435->54 lines). This was the single worst fixture bloat
site: one fixture dir holding ~18 full skills.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* evals: parent-side shard skipping — a one-test diff runs 3 of 44 shards

The sharded runner spawned every shard regardless of diff; only the
child self-skipped, so a typical single-skill change still paid 44 Bun
boots + container-equivalent setup for shards with zero selected tests.
The parent now computes selection once (mirroring e2e-helpers exactly:
EVALS_ALL -> run-all, empty union -> run-all, git errors propagate the
fail-closed throw) and drops shards where no selected test name maps in.

Mapping = quoted E2E map keys in the file's source UNION keys whose dep
list registers the file (constructed-name families need the second
direction). FAIL-OPEN everywhere it matters: run-all, non-skill-e2e
files, unreadable source, zero mapped names all keep the shard — the
child filter stays authoritative, so a parent bug can only run extra.

New taxonomy status skipped-by-diff (never conflated with
never-started); selection banner prints once; --list is selection-aware.
C6 lands in the same commit: a HARD tier-alignment test — every paid
skill-e2e file must be parent-mappable or provably fail-open-safe.
Note: this change-set's 14 dep-list registrations in touchfiles-data.ts
rode along in f945c841 (concurrent-agent staging); they belong to this
change logically.

Demo: selection of one test -> 'running 3 of 44 shards, 41
skipped-by-diff'. 13 new $0 tests via injected seams.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* evals: fix context-save-list test that was 0-for-26 ($5.28, zero passes)

Disposition for the eval store's only permanently-red test. Root cause:
the hide-other-branches assertions scanned the FULL output surface
(incl. bash tool_results), so any agent that ran ls on the checkpoints
dir — the natural first step of a list flow — surfaced all three seeded
filenames and failed, even when its user-facing listing filtered
correctly. The test punished the agent for looking at the directory.

The hide-assertions now scan the agent's FINAL TEXT (the listing the
user sees); showsMain keeps the broad surface for its documented reason.
Validated live in the final gate run rather than quarantined: the test
guards real behavior (branch filtering) and the assertion was the bug.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: wire 12 orphaned test files into the free suite (D3a)

ios-qa/daemon/test (10 files), ios-qa/scripts/gen-accessors.test.ts, and
browser-skills/hackernews-frontpage/script.test.ts ran under NO script
or CI — written coverage catching nothing. All 174 tests green on
arrival (4.6s), zero quarantines needed. TODOS P2 closed: main wired
design/test in v1.64, the variants-retry-after flake it named is fixed
on this branch, and this commit lands the remaining orphans.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: supabase-provision runs in-process — 16.5s -> 0.45s

bin/gstack-gbrain-supabase-provision (482-line bash) becomes a 26-line
bun-shebang entry over a new importable lib/gbrain-supabase-provision.ts
with an injected-deps seam (fetch/env/stdout/sleep — D7: args, never
env-mutation-before-import). The 33 spawn-per-test cases run in-process
against the same Bun.serve mocks; exactly one spawn smoke keeps the
shebang/CLI/receipt contract covered.

Byte-compat proven by a 25-case differential harness (old bash bin from
git vs new, same mock): stdout, stderr, exit codes identical across all
subcommands, JSON/plain modes, and error paths. Egress receipts stay
per-attempt, receipt-before-send, fail-closed (scanner updated:
SHELL_SINKS -> MODULE_SINKS). No-op sleep injection makes retry/backoff
paths instant.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* evals: kill the 3,372-line zombie monolith; revive 4 never-run tests

test/skill-e2e.test.ts survived the v1.56 split as a zombie: the paid
glob needs the skill-e2e-* hyphen, so with EVALS=1 NOTHING has executed
it for ~8 releases — and it held the ONLY implementations of four
map-registered tests: review-coverage-audit (gate), plan-eng-coverage-
audit (gate), ship-triage (gate), ship-idempotency (periodic). Three
gate tests silently never ran — the exact 0%-execution class this
branch exists to kill.

Rehomed into test/skill-e2e-coverage-audit.test.ts, -triage.test.ts, and
-ship-idempotency-sdk.test.ts with bodies byte-identical modulo collector
wiring and fixture extraction (drift observed in the skills since v1.56
is DOCUMENTED in each header, not fixed — their first paid run in 8
releases must attribute failures to drift, not to this move). All 24
other monolith names were true duplicates of the split files — dropped
with the monolith. Matrix rows added to both eval workflows; the paid
glob's zombie-exclusion is now a commented regression pin.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: fix two parallelism-exposed flakes (probe re-run, live-tree census)

Both pass solo and on main but flaked under the parallel runner:

1. gstack-brain-context-load probed 'gbrain --version' PER QUERY with a
   500ms budget — a cold probe on a saturated box timed out (observed
   505ms), branding gbrain 'missing' for one query while siblings
   passed. The probe is now memoized (availability can't change
   mid-invocation) with a generous one-time 5s budget; query calls keep
   the tight timeout.

2. skill-size-budget's catalog estimate read the LIVE tree, so a
   concurrent worker's transient skill-shaped scratch dirs exactly
   doubled it (8356 vs 4177). The ratchet now counts git-TRACKED skills
   only — the catalog that ships, immune to sibling workers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* evals: demote 4 expensive posture tests to periodic (D2a)

design-consultation-research ($0.91/304s) and -preview ($0.89/481s) —
the two most expensive gate tests — plus office-hours-forcing-energy
(LLM-judge posture score; its sibling was already demoted) and
cso-full-audit (250s/$0.57; the targeted cso tests stay gate). Saves
~$8-12 and 10-15 min per gate run. The plan-*-finding-floor tests stay
gate deliberately: cheap insurance on the most-edited skill surface.
Housing files have no whole-file self-gates, so the runtime E2E_TIERS
filter handles both tiers; tier-alignment tripwire green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* evals: judge default Sonnet -> Haiku 4.5 (D1a)

The 25 doc-quality judges are rubric-scoring calls — a duty Haiku is
already proven at in this repo (pty hung/working classifier,
first-task-scaffold, hermetic-canary). Tests needing a stronger judge
pass a model explicitly. Note: eval-store judge costs were hardcoded
synthetic (0.02), so no baseline distortion. Re-baselined by the
periodic run in this branch's final verification.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* evals: SDK runner default Opus -> Sonnet (D1a)

agent-sdk-runner defaulted to Opus 4.7 while session-runner (the claude
-p path) defaulted to Sonnet — an inconsistency between the two runners,
not a decision anyone made. Unpinned tests were implicitly asserting the
expensive model. The 30+ tests that genuinely need Opus already pin it
via opts.model. Re-baselined by the periodic run in this branch's final
verification; regressors get explicit Opus pins.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: CLAUDE.md tells the truth about the free suite; make-pdf gate is macOS-only

The '<2s' claim was off by two orders of magnitude (measured 454s serial
at v1.63; ~90-100s now under the parallel runner), and the bare
'bun test' guidance walked the whole repo, loading paid eval files and
missing the strict classifier. Commands now say 'bun run test' with real
numbers, document the strict-output invariant, the EVALS_JOBS /
EVALS_CONCURRENCY split, the computed detach-timeout floor, and the
required free-tests lane. make-pdf-gate drops its Linux leg (redundant
with the free lane running make-pdf tests on every PR); macOS rendering
coverage stays.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: catalog ratchet reads committed content; SDK unit pins follow D1a default

Two follow-ups from the verification runs:

1. skill-size-budget's catalog estimate still flaked under --parallel
   (8356, then 8041, vs 4177 solo) even after filtering to tracked
   skills: sibling workers REGENERATE real SKILL.md files mid-run, so
   any live-tree read is a moving target. The ratchet now reads each
   tracked skill's frontmatter from git show HEAD: — the catalog that
   ships — which no concurrent worker can perturb.

2. agent-sdk-runner unit pins asserted the old Opus default through the
   default-flow fixtures; flipped to the Sonnet default (the explicit-
   override pass-through pins keep Opus — that path is unchanged).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(browse): SIGKILL abandoned Chromium on close-race timeout (suite wedge)

close()'s launched-mode path raced browser.close() against 5s and on
timeout ABANDONED the child: this.browser nulled, process handle lost,
Chromium alive holding keep-alive connections into test servers whose
stop() then waits forever. Reproduced twice as an intermittent (~50%)
whole-suite wedge — a 44min 0.1%-CPU hang pinned by a leaked LISTEN
socket, and a 400s hang with commands.test.ts teardown in flight.

The child handle is now captured BEFORE the race and SIGKILLed on
race-timeout (launched mode only; headed keeps context.close). Race
timers are unref'd so a successful close stops pinning the caller's
event loop for the window. The four browse test servers force-close
keep-alives (stop(true)) as belt-and-braces.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: delete two dead-architecture security contract tests

browse/test/security-source-contracts.test.ts and sidebar-security.test.ts
read browse/src/sidebar-agent.ts at module scope — a file deleted (on main
too) when the sidebar chat-queue path was ripped in favor of the terminal
PTY. Both files have errored on load ever since: the old truncating suite
never surfaced it, and no CI lane ran them. Their subjects (queue-spawn
canary injection, preSpawnSecurityCheck, queued args, chat system prompt)
no longer exist; server.ts retains processAgentEvent only in a comment.

Live security coverage continues in security.test.ts (canary/verdict),
content-security.test.ts (L1-L3), server-sanitize-surrogates.test.ts,
and the security-bench suite. If the terminal-agent path should inherit
any of the deleted contracts, that is a separately scoped piece of work
against the component that actually exists.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(redact): calibrate placeholder recognition for code and doc shapes

Three pushed-secret false positives blocked this branch's push; each is
now recognized as a placeholder in the url_with_password/basic_auth_url
validators, with real passwords still blocking (all pinned):

- ${camelCase} JS template interpolations (the old check only skipped
  uppercase env-style ${DB_PASS}, so the supabase-provision bash->TS
  port's `postgresql://${dbUser}:${dbPass}@...` flagged as two
  pushed secrets).
- The literal PASSWORD/pass placeholder in URL-format doc comments.
- The provision lib's doc comments now use <PASSWORD>/PASSWORD forms.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: opt-in gate for live-playwright ML tests; ios-qa build hygiene

security-live-playwright's L4 tests dlopen onnxruntime inside a bun
--parallel worker whenever the dev box has a warm model cache — the
source of the intermittent 'panic: Segmentation fault' + crashed-worker
retries (and likely the residual run wedges). Same SECURITY_BENCH=1
opt-in as security-bench.test.ts; the L1-L3 tests in the file still run
everywhere.

Also: gitignore the ios-qa gen-accessors-tool Swift .build/ output (a
side-effect of running its tests that kept polluting git status) and
commit its Package.resolved so tool builds resolve reproducibly.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: free runner output contract — name the failure, quiet the noise

Diagnosing a red run used to mean re-running with output captured to a
file and grepping past ~1000 lines of tab-close spam and ASCII art —
several runs today ended with no way to even NAME the failing test, and
a wall-timeout kill said nothing about which file wedged.

New contract: the full child stream ALWAYS lands in a per-run log file
(path printed up front); the console shows only runner lines, (fail)
results, crash markers, and the terminal summary (--verbose restores
the firehose; the strict classifier consumes the full stream in every
mode). After every run a stable epilogue names the outcome:

  [test:free] FAIL — k failing test(s) in j file(s), c crashed
  worker(s). Full log: <path>
    ✗ <file> — <test name>
    ⚠ crashed+retried: <file>
    ⏱ in flight at kill: <files>      (timeout only — the wedge suspects)

Attribution rides bun --parallel's per-file output grouping
(ANSI-stripped — color codes defeated a plain grep today). 12 new pins:
epilogue formats, crash surfacing, quiet/verbose console policy, log
completeness, in-flight-at-kill on a real hang.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: quarantine 5 pre-existing env failures individually (receipts in-file)

Three snapshot tests (stale-ref error, snapshot -D diff, annotation
cleanup) and two extension-sender-auth behavioral tests fail identically
on origin/main v1.64.1.0, solo, on dev machines — verified per the blame
protocol. Main's CI lane skip-lists both FILES wholesale; quarantining
only the five failing tests keeps the other 60 guarding. Each carries
the un-skip condition.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: stealth-webdriver launch gets parallel-load headroom (120s)

Playwright's default 30s launch timeout dies under the full-suite
--parallel run when ~400 workers contend for Chromium launches — bun
reports the hook death as an '(unnamed)' 30006ms failure (named on
sight by the new runner epilogue). Both launch sites get explicit 120s
timeouts; the runner's external wall-clock still bounds the ceiling.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: free-runner wall timeout 15min -> 6min (faster wedge diagnosis)

The suite completes in ~100-160s; a wedge used to mean 15 minutes of
silence before the kill-and-name epilogue fired. 6min keeps ~3.5x
headroom over the slowest observed clean run while naming wedge
suspects in minutes. --wall-timeout <secs> overrides per run.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: run worker-hostile files in a serial child (first entry: security-live-playwright)

The residual full-suite wedge, named by the new epilogue: Bun 1.3.13
segfaults running browse/test/security-live-playwright.test.ts in a
--parallel worker ('panic: Segmentation fault ... a bug in Bun'), and
the crashed-worker retry then wedges the whole invocation past the wall
clock. The file passes serially.

New WORKER_HOSTILE placement list: full-suite mode excludes listed files
from the parallel invocation and runs them in their own strict-classified
serial child afterward — execution placement, not a skip; each entry
carries its reason and removal condition.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: gate compare-board's file-level hooks too — the intermittent staller

Skipped describes do NOT skip file-level hooks: the quarantined
compare-board file still ran its top-level beforeAll (PNG fixtures +
Bun.serve + a BrowserManager launch — exactly the 'needs a
display-shaped env' code) on every run, and under parallel load that
setup wedges. Caught red-handed by the runner's in-flight-at-kill
epilogue: '⏱ in flight at kill: browse/test/compare-board.test.ts'.
This was the suite's intermittent staller. Hooks now honor the same
GSTACK_COMPARE_BOARD_TESTS gate; the gated file drops from 3.7s of live
setup to 0.4s of pure skips.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: full suite runs as N shard processes; scrub spec-sync child env

Two fixes from the wedge-hunt endgame:

1. Full-suite mode switches from one 'bun test --parallel' invocation to
   N concurrent shard PROCESSES, serial within each (the paid runner's
   proven model; N = min(6, cpus-2)). The single-invocation strategy hit
   three distinct Bun 1.3.13 worker pathologies in one day — a segfault
   whose crashed-worker retry wedged the run, a quarantined file's
   still-running file-level hooks stalling a worker, and spawn-heavy
   files hanging under load — and each one stalled the WHOLE invocation.
   Process shards isolate any wedge to its own shard. First full run
   under this model: no wedge, six epilogues, one real failure named.
   WORKER_HOSTILE stays as the paper trail; --parallel remains available
   per-shard for a future Bun.

2. That one real failure: spec-template-sync regenerates SKILL.md via a
   child that inherited the shard process's env — an earlier test's
   GSTACK_*/GBRAIN_* mutations changed generator output (failed in-suite,
   passed solo on an identical tree). The child now gets a scrubbed env:
   generator output must be a function of the templates, not of whichever
   test ran before.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: tree-mutating tests run after the parallel shards; scrub relink env

The flake family's root cause, finally: five test files REGENERATE
shared repo artifacts in place (catalog-mode-full rewrites every
SKILL.md in full-catalog mode; spec-sync and idempotency regenerate all
skills; gen-skill-docs and skill-validation rewrite .agents/). Any
concurrent shard reading those files sees a moving target — this one
family produced the exactly-doubled catalog estimate, the golden-file
drift, and the spec-sync mismatch chased earlier today. Full-suite mode
now runs TREE_MUTATING files in one serial shard AFTER the parallel
shards complete; CI's matrix is unaffected (per-runner checkouts).

Also: relink's run() helper spread process.env into its children, so a
sibling file's leaked GSTACK_HOME made the 'fresh install' test see a
neighbor's skill_prefix. GSTACK_HOME is now dropped unless the test
passes it explicitly.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: gbrain-detection-override joins TREE_MUTATING (mutator #6)

It regenerates SKILL.md in place with --respect-detection (the gbrain
variant adds ~1-3KB per carved skeleton) and git-restores afterward —
its own header documents the approach. During that window the parity
suite in a concurrent shard read inflated skeletons and failed 4 caps.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: tree-ratchet readers join the serial phase (quiet tree by construction)

Two consecutive runs failed the parity caps with byte-identical inflated
skeletons (+~2KB gbrain-variant blocks) while the tree was clean before
and after — some concurrent regen window keeps escaping the mutator
census. Rather than hunt every present and future mutator, the tests
that MEASURE the shared tree (parity caps, size budgets, carve guards)
now run in the serial phase after the parallel shards: a quiet tree by
construction, immune to any regen we haven't found.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* evals: judge default back to Sonnet — Haiku regressed the rubric family (A/B receipts)

The partial-diff rehearsal was the Haiku judge default's first live run
and it failed all three selected doc-rubric judges. Controlled A/B on
the identical health-rubric prompt: Haiku 2/2/2 vs Sonnet 4/3/4, both
with coherent reasoning — Haiku is simply a harsher grader on
long-document rubrics, and every >=4 threshold in skill-llm-eval was
calibrated against months of Sonnet baselines. Per D1a's
pin-on-regressors protocol the default reverts; a new
GSTACK_EVAL_MODEL_JUDGE override makes future recalibration a one-var
experiment. Haiku keeps the classifier-grade duties (pty hung/working,
warmup, distill via lib/eval-model.ts) and D1a's capture->Sonnet stands.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(test-runner): per-origin classifier buffers — interleaved pipes can't shear lines

stdout and stderr are independent pipes; a chunk from one can arrive
between two halves of a line from the other. The single shared
pending-buffer glued those fragments into garbled lines: a sheared
(fail) line went uncounted (defeating the exit-0-with-failures
backstop) and a sheared terminal summary read as truncation.
Counters stay shared; line assembly is now per-stream, and both
runners tag the stream origin. Also drops the dead ChildProcess
type import left by the killProcessGroup move.

* fix(test-runner): real carve-guard keys in TREE_MUTATING; census pins; size-scaled wall deadlines

TREE_MUTATING listed 'test/carve-guard-checks.test.ts' — a file that
has never existed (the real ratchet readers are
carve-guard-completeness and carve-section-ordering), so the intended
serialization was silently absent. New census pin tests fail on any
key that doesn't name a real free test file, and on a TEST_ROOTS
entry that stops contributing files. Full-suite wall deadlines now
scale with shard size (max(6min, files x 5s)) so a jobs=1 machine or
the ~130-file Windows shards can't false-timeout a healthy run;
explicit --wall-timeout disables scaling. Stale --parallel wording in
the dry-run message, jsdoc, and the TREE_MUTATING ordering comment
corrected to the shipped process-shard model.

* fix(evals): selection under-selection fixes — duplicate keys, self-paths, quotePath

Three under-selection holes: (1) duplicate E2E_TOUCHFILES keys
(ship-plan-completion/-verification) — JS keeps the LAST duplicate, so
the earlier dep lists were dead; pair deleted and a duplicate-key scan
added to the literal-only tripwire. (2) The five rehomed e2e files
didn't list themselves in their own dep lists, so editing the test
never selected it. (3) git C-escapes non-ASCII paths without
core.quotePath=false, so an accented filename matched no glob and
deselected its tests. Also updates the stale --retry cost comment.

* fix(evals): destructive-actions guard actually inspects Bash commands

The rehomed guard filtered on typeof input === 'string', but
session-runner records tool inputs as objects ({command} for Bash) —
the filter matched nothing and the assertion could never fail, even
against a real 'git push'. Now extracts the command from the object
shape, same as the usedGitDiff check above it.

* fix(redact): interpolation allowance can't swallow a real $word password

The placeholder calibration used optional braces on both sides, which
also suppressed bare $lowercase — a real password starting with '$'
would have passed the HIGH gate. Interpolation now means ${identifier}
(braced, any case) or bare $UPPER_SNAKE only; both connection-string
patterns share one validator so they can't drift. Pins added for the
bare-$word block, $UPPER allowance, and mismatched-brace block.

* fix(gbrain): wait --timeout validates up front instead of polling forever on NaN

Number('abc') is NaN, NaN comparisons are always false, and the
poll loop never hit its deadline — an infinite 5s loop where the bash
predecessor errored immediately. die(2) at parse time, with a test.

* ci: least-privilege tokens on the two lanes that execute PR-controlled code

free-tests runs PR code (install lifecycle scripts + the suite) with
whatever the repo-default GITHUB_TOKEN grant is, persisted into
.git/config by checkout. Now: permissions contents:read,
persist-credentials false, pinned by the wiring test. actionlint gets
the same treatment plus a digest pin on the third-party Docker Hub
image (a tag is repointable with no GitHub-side audit trail, and the
image sees the mounted checkout). restore-keys added to both caches so
a lockfile bump warms from the previous cache; stale --parallel header
wording corrected.

* test(browse): unit coverage for the close() SIGKILL fallback

The wedge fix (capture the Chromium child before the close race,
SIGKILL on timeout) shipped without a test of the branch it added —
the coverage audit flagged it as the diff's one regression-gap. The
5s race window becomes an injectable closeRaceMs field, and four unit
tests pin: SIGKILL on hang, no SIGKILL on clean close, no SIGKILL on
an already-exited child, SIGKILL on a rejecting close.

* docs: CLAUDE.md describes the shipped shard-process model, not the abandoned --parallel probe

* fix(test-runner): cancellation terminates the run; win32 kills the whole tree

Installing SIGINT/SIGTERM forwarders suppresses Node's default
terminate-on-signal, so a cancelled run killed the current child and
kept LAUNCHING shards — observed as paid runs continuing to burn API
spend after Ctrl-C (codex adversarial, repro'd ALIVE_AFTER_SIGTERM).
The first signal now also schedules the parent's own exit after the
children's SIGKILL grace, and both shard pools consult
isTerminationRequested() before taking new work. On win32,
killProcessGroup uses taskkill /T /F — detached:true creates no
killable group there, and a bare child.kill orphaned every grandchild
(ports, locks, and the inherited pipes that kept close from firing).
Also: the tree-mutating serial shard prints dirty generated artifacts
when it dies mid-regeneration, and --shard CI-matrix mode gets the
same size-scaled wall deadline as full-suite mode.

* fix(evals): preflight fails fast on spawn error, timeout, and exit 127

The ping only grepped stdout for two connection strings — a missing
claude binary, a 30s timeout kill, or command-not-found all returned
'ok', and the fleet then burned ~30 shard timeouts discovering the
outage one child at a time. Cross-model finding (testing specialist +
codex adversarial). Other non-zero exits stay deliberately fail-open:
a flaky preflight must not block a runnable suite; pinned both ways.

* fix(redact): lowercase 'password'/'pass' at the URL-password position blocks

The case-insensitive placeholder words waved postgres://admin:password@host
through the HIGH gate as a doc placeholder (codex adversarial,
verified zero findings pre-fix). URL-password position is now stricter
than generic placeholder detection: ALL-CAPS doc convention
(USER:PASSWORD), ${identifier} interpolations, bare $UPPER_SNAKE, and
structural shapes (<your-password>) suppress; lowercase dictionary
words block. Pinned in both directions.

* fix(gbrain): DSNs percent-encode the password; body reads retry; stdout drains

Three codex-adversarial findings in the provision port: (1) raw DB_PASS
interpolation — a reserved character (/ # ? % @) restructured the URI,
provisioning succeeded, and every consumer then failed to parse the DSN
(unusable billable orphan); now encodeURIComponent, round-trip pinned.
(2) await res.text() sat outside the transport try — a server that sent
headers then reset the stream was an uncaught exit 1 instead of a
retry-then-exit-8. (3) The bin entrypoint called process.exit() after
unawaited stdout writes, truncating piped JSON; exitCode lets writes
drain.

* fix(evals): selection-path helpers join GLOBAL_TOUCHFILES; base-branch keys self-register

The three-file split moved test-selection.ts into the globals but
dropped the facade — an edit to test/helpers/touchfiles.ts (executable
selection-path code imported by every consumer) selected ZERO paid
tests, the exact invisible-non-execution class this branch exists to
kill (claude adversarial, finding 1). e2e-helpers.ts (the harness every
paid test imports) and paid-test-set.ts (paid-vs-free classification)
had the same gap. The review/ship base-branch keys also register
test/skill-e2e-review-attribution.test.ts so editing those tests
selects them.

* ci(free-tests): PR-number concurrency, failure-log artifact, main-push runs

Three red-team/adversarial findings on the new required lane:
(1) concurrency keyed on bare head_ref — two forks with the same
branch name shared one group, so a push to fork B cancelled fork A's
in-flight REQUIRED check (merge-pipeline DoS with no code fault); key
on the PR number. (2) The runner's full logs die with the runner in
os.tmpdir() — a red check named WHICH test failed but never why;
upload the shard logs as an artifact on failure. (3) PR-only trigger
meant two individually-green PRs could merge into a red main with
nothing running the suite there; add push: branches: [main].

* ci: PR-number concurrency keying on the eval and Windows lanes too

Same fork-branch-name collision as free-tests.yml: bare head_ref
carries no owner prefix, so same-name branches from different forks
shared a cancel-in-progress group.

* test(evals): retro E2E passes require the report on disk

Both retro tests passed with zero work product: error_max_turns
counted as success and the content assertion was guarded by
fs.existsSync — a run that burned 30 turns and wrote nothing recorded
green (red team). The report is now load-bearing for pass/fail.

* chore: bump version and changelog (v1.66.0.0)

Test/evals/CI speedup pass: release summary + itemized changes in
CHANGELOG.md; TODOS.md marks the free-suite exit-code P1 complete and
files the review-army follow-ups.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(redact): fully-braced ${...} interpolations are code, whatever they contain

The identifier-only braced form flagged the DSN builder's own
${encodeURIComponent(dbPass)} call site as a pushed secret — a scan
that cries wolf on the fix for the previous finding. Any ${...}
spanning the whole password segment is template code; bare $word
stays uppercase-only so $hunter2 still blocks. The mismatched-brace
negative fixture assembles at runtime so this file's own pushed bytes
carry no blockable URL shape.

* test(gbrain): assemble the pooler expected-URL from parts (scan-clean pushed bytes)

* docs: sync docs for v1.66.0.0 (test/evals/CI speedup)

CONTRIBUTING.md, AGENTS.md, and ARCHITECTURE.md still taught bare
`bun test` for the suite; the shipped runner deprecates it (walks the
whole repo, loads paid eval files, misses the strict classifier). All
suite-level references now say `bun run test`, the Tier 1 section
describes the strict shard runner (~90-100s, --verbose, --wall-timeout),
the sharded paid-runner paragraph documents diff-based shard skipping
and the EVALS_JOBS / EVALS_CONCURRENCY split, the Tier 3 row points at
the actual judge-only invocation, and GSTACK_EVAL_MODEL_JUDGE is
documented at the judge it overrides.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci(free-tests): restore the PR-number concurrency + failure-log artifact; truth-fix stale comments

The workspace-revert incident that hit CHANGELOG/TODOS mid-ship also
caught free-tests.yml between edits: commit 8d6c2ff8's message claims
PR-number concurrency + artifact upload + main-push runs, but only the
push trigger survived to the commit (caught by the /document-release
doc-vs-code audit). Both re-applied. Also: eval-model.ts header said
capture defaults to Opus (it's Sonnet per D1a), paid-shards' header
pinned a stale 44/63 shard census, and two CHANGELOG phrases
over-claimed ('six' -> 'up to six' shard processes; retry-1 scoped to
retry-bearing paid paths).

* ci: setup-buildx before every cache-exporting image build

First live run of the cache trio failed at flag-parse time: the
default buildx `docker` driver hard-errors on cache-to registry
export ('Cache export is not supported for the docker driver'), which
failed build-image on PR #2593 and skipped the entire gate eval
matrix behind it. docker/setup-buildx-action creates the
docker-container builder that supports registry cache export; all
three build sites (evals, evals-periodic, ci-image) get it.

* fix(browse): Xvfb identity is argv[0]'s basename, not a cmdline substring

First Linux CI run: isOurXvfb identified the TEST RUNNER as our Xvfb —
the suite's own argv contains 'xvfb.test.ts', the substring match over
the whole cmdline passed, and the start-time check matched because the
pid was real. Any process whose ARGUMENTS mention xvfb (a runner, an
editor) was killable — the sibling-kill class the identity check
exists to prevent. Identity now rests on argv[0]'s basename ('Xvfb'),
with a sh-$0 regression pin. isDisplayFree falls back to the X
socket/lock files when xdpyinfo isn't installed (x11-utils is absent
on some images that ship Xvfb).

* fix(test-runner): strip GHA ::group:: wrappers before file attribution

On GitHub Actions bun wraps each file's log section in ::group::. The
un-stripped header failed FILE_HEADER_RE, failures attributed to the
PREVIOUS file, and the terminal recap's re-printed (fail) lines landed
under a phantom second file — the first Linux run reported 5 real
failures as 10 across 2 files (one of them innocent). Strip the prefix
before matching; the existing file+test dedupe then absorbs the recap.

* test: first-Linux-run environment fixes — bun-only PATH shim, claude gate, darwin-scoped pdf gates

Three environmental assumptions the Linux lane exposed:
(1) gbrain-detect's deterministic SAFE_PATH lacked the bun runtime, so
every env-shebang spawn exited 127 on CI; a scratch dir holding ONLY a
bun symlink joins the PATH (appending bun's real dir would leak its
siblings — dev boxes keep gbrain there too).
(2) host-config's 'detect finds claude' assumed a claude binary; the
secretless lane deliberately has none — gated on Bun.which.
(3) The four make-pdf render gates hard-required prerequisites on ANY
CI, but the make-pdf gate workflow is macOS-only by decision and the
Linux lane doesn't build dist/pdf — hard-require scoped to darwin.

* ci(free-tests): run the suite under xvfb-run

Headed-browser tests (handoff, extension sidepanel DOM) need a real
DISPLAY; the first Linux run died on Playwright's 'headed browser
without an XServer' banner. xvfb-run -a provides the display; x11-utils
ships xdpyinfo for display probing.

* fix(test-runner): bun's headerless failure recap can't invent a phantom failing file

Round-3 CI showed the remaining half of the recap bug: bun prints
'N tests failed:' then re-prints every (fail) line with NO file
headers, so they attributed to the stale currentFile — an innocent
file (test/uninstall.test.ts) was charged with another file's 5
failures. The recap marker now ends attribution (currentFile=null,
chunk closed) and recap re-prints of already-recorded test names
dedupe; a recap-only failure the main run never attributed still
records, unattributed, as belt and braces.

* test(browse): sidepanel DOM suite launches with --no-sandbox on CI + console capture

The suite's raw chromium.launch had no --no-sandbox — every browse
test that goes through gstack's launcher (which always passes it)
survived the Linux lane, while this file's sandboxed renderer died on
first navigation: waitForFunction hung to the 15s test timeout, then
every newContext failed with Target.createBrowserContext. Also wires
pageerror/console-error capture at all six pages so a page-side
failure reads as itself in CI logs instead of a bare timeout.

* test(browse): delete the sidepanel security-DOM suite — it tests UI removed in v1.14

Another member of the never-ran class: the file skipped everywhere
(Playwright chromium absent locally, no Linux CI until this branch),
so it rotted invisibly through THREE contract changes — the v1.63
/extension-token bootstrap, the endpoint growth (/memory,
/pty-session, /sse-session), and finally the v1.14 sidebar-REPL
rewrite that removed the security shield/banner UI it asserts on
(#security-shield survives in sidepanel.html as a dead hidden stub
with no JS driver; sidepanel.js:87 and :1317 document the removal).
The Linux lane executed it for the first time and it can never pass:
the behavior is gone. The L1-L3 security filters it name-checked stay
covered by the ~83 unit/behavioral security tests. The free-tests
lane also vendors xterm assets (bun run vendor:xterm) so the
sidepanel terminal scripts load for any future DOM coverage.

* ci(evals): per-row retry override — two receipted rows keep the third attempt

Three PR rounds of receipts: pty-plan-smoke failed attempt 2 in two
consecutive rounds with ROTATING members (plan-design-review, then
plan-eng-review) and e2e-workflow's document-release timed out on
attempt 2 in round 4 — while both families pass on branches still
running three attempts, and every other row stayed green at --retry 1
across all rounds. Matrix rows gain an optional retries field
(default 1); only these two rows set 2, keeping the measured
retry-amplification win everywhere else.

* test(windows): curate the seven POSIX-bound files the expanded lane surfaced; fix flag-utils path embedding

First full run of the expanded Windows lane (13 -> ~258 files, PR #2593
run 31918591602) failed in exactly 8 files. One was a real test bug,
fixed: design-flag-utils embedded a raw Windows ROOT into a bun -e
string where backslashes act as escapes (D:\a\gstack imported as
D:agstack) — forward slashes work on every platform. The other seven
are POSIX-bound in ways the content patterns cannot see (sed/ln/bash
ARE their subject, a shebang shim arrives via variable, wall-clock
retry bounds on the slowest runner) — each gets a receipted
KNOWN_WINDOWS_INCOMPATIBLE entry, and the census pin now covers that
list so a renamed file fails the suite instead of silently keeping a
stale exclusion.

* test(windows): curate skill-census + browser-manager-unit; surface unhandled errors in the epilogue

Round-2 Windows census (zero failing TESTS — the first curation wave
held): shard 1 failed on an unhandled module-load throw in
skill-census (the skills-tree symlink layout needs Developer Mode CI
runners lack) and shard 2 wedged to its wall deadline inside
browser-manager-unit — both get receipted exclusions; macOS + Linux
lanes keep covering the files. The unhandled-error class also exposed
an epilogue gap: it fails the shard via the strict classifier but
produces no (fail) lines, so the epilogue read 'FAIL — 0 failing
test(s)' with no culprit. The reporter now attributes each
'# Unhandled error between tests' marker to its chunk and the FAIL
line carries the count.

* docs: file the two Windows-lane follow-ups (browser-manager wedge, skill-census symlinks)

* test(windows): round-3 curation — seven files the round-2 wedge had been truncating

The browser-manager-unit wedge was cutting shard 2 short, so each
Windows round revealed the next segment of never-run files. With the
wedge excluded, shard 2 completes (50s) and shows its real failures:
seven more POSIX-environment files (PID/cmdline identity probing,
bash scripts as the subject under test, env-scrubbed bun spawns).
Shards 1 and 3 (including all tree-mutators) now PASS on
windows-latest — this should be the fixed point: ~234 files of real
Windows coverage vs the 13 hand-picked before.

* test(windows): round-4 curation (spawnSkill env, symlink fixtures) + shard-log artifact

Shard 2 ran all 132 files with zero (fail) lines yet bun exited 1 —
unhandled errors in a shape neither counter names, and the Windows
lane had no log artifact to attribute them. Statically attributed and
excluded: browser-skill-commands (spawnSkill spawns bun with a
constructed env; resolution fails under Windows spawn) and
security-audit-r2 (evil-link symlink fixtures need Developer Mode).
The lane now uploads its shard logs on failure like free-tests.yml,
with os.tmpdir() pointed at runner.temp so the glob can find them.

* evals: Opus pin on the spec AUQ-matrix entry — D1a regressor, receipts in-file

The periodic re-baseline for the capture default (Opus -> Sonnet)
found exactly one regressor across the seven-entry AUQ behavioral
matrix: spec failed twice under Sonnet ('never reached a question in
budget', 242s) while its six siblings passed; the controlled Opus
re-run passed cleanly (7/7 format, substance 5, 160s), and a second
run through the new per-entry model plumbing confirms. MatrixSkill
gains an optional model field wired into captureFirstAuq; only spec
sets it. TODOS gains the re-baseline receipts for the never-baselined
periodic tail (three setup-gbrain files + ship-idempotency, all
local-only).

* test(evals): scope-gate assertion carries its evidence tail; file the detector-flake TODO

The plan-design-review member fails ONLY scopeGateQuestionObserved
intermittently on unchanged code (PR #2593: red rounds 3/11 + rerun,
green rounds 5/6 — every attempt terminal, no plan-mode leak), and a
bare Expected-true/Received-false is undiagnosable from CI logs. The
check now throws with the last-2KB visible evidence, so the next
failure distinguishes a detector-sensitivity miss from a real silent
bypass. TODO filed with the full receipt trail.

* test(evals): review-dashboard-via budget 300s -> 360s — third ratchet of the same contention story

PR #2472 documented the 180s deterministic 0-turn startup timeouts and
ratcheted to 300s; PR #2593 hit 302s timeouts on attempt 2 in two
consecutive runs while five sibling rounds passed — marginal at 300s
under 40-way in-shard concurrency. Same headroom its contention-class
sibling (retro-base-branch) carries; outer bun timeout rises to 480s.

* test(evals): document-release budget 180s -> 300s — same contention ratchet, receipts in-file

Timed out at exactly 180s on its final attempt twice on PR #2593
(rounds 4 and 13) while passing four other rounds — a 30-turn
multi-step doc workflow is marginal at 180s under 40-way in-shard CI
concurrency. Same story and same fix as review-dashboard-via and
retro-base-branch; outer bun timeout rises to 360s.

* docs: file the systemic in-shard-concurrency follow-up behind the timeout-flake family

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-15 22:20:30 -07:00

1088 lines
63 KiB
Markdown
Raw Blame History

# gstack development
## Commands
```bash
bun install # install dependencies
bun run test # run free tests via the strict parallel runner (~90-100s full suite)
bun run test:evals # run paid evals: LLM judge + E2E (diff-based, ~$4/run max)
bun run test:evals:all # run ALL paid evals regardless of diff
bun run test:gate # run gate-tier tests only (CI default, blocks merge)
bun run test:periodic # run periodic-tier tests only (weekly cron / manual)
bun run test:gate:sharded # gate tier via the sharded paid runner (one Bun process per test file)
bun run test:periodic:sharded # periodic tier via the sharded paid runner (implies EVALS_ALL=1)
bun run test:e2e # run E2E tests only (diff-based, ~$3.85/run max)
bun run test:e2e:all # run ALL E2E tests regardless of diff
bun run eval:select # show which tests would run based on current diff
bun run dev <cmd> # run CLI in dev mode, e.g. bun run dev goto https://example.com
bun run build # gen docs + compile binaries
bun run gen:skill-docs # regenerate SKILL.md files from templates
bun run skill:check # health dashboard for all skills
bun run dev:skill # watch mode: auto-regen + validate on change
bun run eval:list # list all eval runs from ~/.gstack-dev/evals/
bun run eval:compare # compare two eval runs (auto-picks most recent)
bun run eval:summary # aggregate stats across all eval runs
bun run slop # full slop-scan report (all files)
bun run slop:diff # slop findings in files changed on this branch only
```
`test:evals` requires `ANTHROPIC_API_KEY`. Codex E2E tests (`test/codex-e2e.test.ts`)
use Codex's own auth from `~/.codex/` config — no `OPENAI_API_KEY` env var needed.
**Env keys in Conductor workspaces.** The `GSTACK_*` env-shim (v1.39.2.0+,
`lib/conductor-env-shim.ts`) promotes `GSTACK_ANTHROPIC_API_KEY` /
`GSTACK_OPENAI_API_KEY` to their canonical names inside gstack's TS binaries.
Tests run through gstack entrypoints inherit this promotion automatically.
Don't echo the key value to stdout, logs, or shell history. The historical
"never pass `env:` to `runAgentSdkTest`" rule is retired: the failure was
partial-env replacement (the SDK's `Options.env` REPLACES the child's entire
environment, so an object without the key broke auth). The runner now always
passes a COMPLETE hermetic env with per-test `env:` merged last, so per-test
overrides are safe; ambient `process.env.ANTHROPIC_API_KEY` mutation also
still works (the env builder reads process.env at call time).
**Hermetic local E2E (default).** Every E2E runner (claude -p, PTY, Agent
SDK, codex, gemini) spawns children through `test/helpers/hermetic-env.ts`:
allowlist-scrubbed env (operator `CONDUCTOR_*`, `CLAUDE_*`, `GSTACK_*`,
`MCP_*`, `GBRAIN_*`, and credentials like `GH_TOKEN` never reach children),
a fresh seeded `CLAUDE_CONFIG_DIR` (no operator `~/.claude` CLAUDE.md /
MCP servers / skills), a temp `GSTACK_HOME`, and `--strict-mcp-config`.
Local eval signal matches CI. Debug against real operator state with
`EVALS_HERMETIC=0` (restores the legacy env AND drops the strict-MCP flag).
Per-test `env:` overrides merge last, so deliberate contamination
(`CONDUCTOR_WORKSPACE_PATH`, per-test `GSTACK_HOME`) keeps working. The
hermetic config dir seeds NO skills by default; a PTY test that types a
`/skill` slash command must pass `seedSkills: true` to the PTY runner, which
points the child's `CLAUDE_CONFIG_DIR` at `hermeticSkillsConfigDir()` — a
seeded registry that symlinks the LIVE working tree's SKILL.md files (by
design: the skills ARE the subject under test; a snapshot would measure stale
copies). Wiring is pinned by `test/hermetic-wiring.test.ts` (static tripwire),
two gate-tier canaries in `test/skill-e2e-hermetic-canary.test.ts`, and the
seeding tripwires in `test/hermetic-skills-seeding.test.ts` /
`test/pty-skill-seeding-wiring.test.ts`.
E2E tests stream progress in real-time (tool-by-tool via `--output-format stream-json
--verbose`). Results are persisted to `~/.gstack-dev/evals/` with auto-comparison
against the previous finalized run (in-flight `_partial` files are never used as
a baseline, so a run can't compare against itself).
**Diff-based test selection:** `test:evals` and `test:e2e` auto-select tests based
on `git diff` against the base branch. Each test declares its file dependencies in
`test/helpers/touchfiles.ts`. Changes to global touchfiles (session-runner, eval-store,
touchfiles.ts itself) trigger all tests. Use `EVALS_ALL=1` or the `:all` script
variants to force all tests. Run `eval:select` to preview which tests would run.
**Two-tier system:** Tests are classified as `gate` or `periodic` in `E2E_TIERS`
(in `test/helpers/touchfiles.ts` — a facade over `touchfiles-data.ts` +
`test-selection.ts`). CI runs only gate tests (`EVALS_TIER=gate`); the free
suite runs on every PR via `.github/workflows/free-tests.yml` (a REQUIRED
check, secretless — fork PRs get real signal);
periodic tests run weekly via cron or manually. Use `EVALS_TIER=gate` or
`EVALS_TIER=periodic` to filter. When adding new E2E tests, classify them:
1. Safety guardrail or deterministic functional test? -> `gate`
2. Quality benchmark, Opus model test, or non-deterministic? -> `periodic`
3. Requires external service (Codex, Gemini)? -> `periodic`
Tier declarations are enforced by `test/e2e-tier-alignment.test.ts` (free, runs
in `bun test`): a `skill-e2e-*` file named in a touchfiles dep list whose
`EVALS_TIER` self-gate disagrees with its declared tier in `E2E_TIERS` fails the
suite. Files not named in any dep list are reported, not enforced — keep both
in sync.
## Testing
```bash
bun run test # run before every commit — free, ~90-100s for the full ~7,000-test suite
bun run test:evals # run before shipping — paid, diff-based (~$4/run max)
```
`bun run test` routes through `scripts/test-free-shards.ts` (N concurrent
shard processes, serial within each, plus a trailing serial tree-mutating
shard — with strict-output classification per shard: a shard without bun's
terminal summary line FAILS — silent truncation
cannot report green). Never type bare `bun test` for the suite: it walks the
whole repo, loading paid eval files and missing the strict classifier.
It covers skill validation, gen-skill-docs quality checks, and browse
integration tests. `bun run test:evals` runs LLM-judge quality evals and E2E
tests via `claude -p`. Both must pass before creating a PR.
## Project structure
```
gstack/
├── browse/ # Headless browser CLI (Playwright)
│ ├── src/ # CLI + server + commands
│ │ ├── commands.ts # Command registry (single source of truth)
│ │ └── snapshot.ts # SNAPSHOT_FLAGS metadata array
│ ├── test/ # Integration tests + fixtures
│ └── dist/ # Compiled binary
├── hosts/ # Typed host configs (one per AI agent)
│ ├── claude.ts # Primary host config
│ ├── codex.ts, factory.ts, kiro.ts # Existing hosts
│ ├── opencode.ts, slate.ts, cursor.ts, openclaw.ts # IDE hosts
│ ├── hermes.ts, gbrain.ts # Agent runtime hosts
│ └── index.ts # Registry: exports all, derives Host type
├── scripts/ # Build + DX tooling
│ ├── gen-skill-docs.ts # Template → SKILL.md generator (config-driven)
│ ├── host-config.ts # HostConfig interface + validator
│ ├── host-config-export.ts # Shell bridge for setup script
│ ├── resolvers/ # Template resolver modules (preamble, design, review, gbrain, etc.)
│ ├── skill-check.ts # Health dashboard
│ ├── test-paid-shards.ts # Sharded paid-tier runner (one Bun process per shard)
│ └── dev-skill.ts # Watch mode
├── test/ # Skill validation + eval tests
│ ├── helpers/ # skill-parser.ts, session-runner.ts, llm-judge.ts, eval-store.ts
│ ├── fixtures/ # Ground truth JSON, planted-bug fixtures, eval baselines
│ ├── skill-validation.test.ts # Tier 1: static validation (free, <1s)
│ ├── gen-skill-docs.test.ts # Tier 1: generator quality (free, <1s)
│ ├── skill-llm-eval.test.ts # Tier 3: LLM-as-judge (~$0.15/run)
│ └── skill-e2e-*.test.ts # Tier 2: E2E via claude -p (~$3.85/run, split by category)
├── qa-only/ # /qa-only skill (report-only QA, no fixes)
├── plan-design-review/ # /plan-design-review skill (report-only design audit)
├── design-review/ # /design-review skill (design audit + fix loop)
├── ship/ # Ship workflow skill
├── review/ # PR review skill
├── plan-ceo-review/ # /plan-ceo-review skill
├── plan-eng-review/ # /plan-eng-review skill
├── autoplan/ # /autoplan skill (auto-review pipeline: CEO → design → eng)
├── benchmark/ # /benchmark skill (performance regression detection)
├── canary/ # /canary skill (post-deploy monitoring loop)
├── codex/ # /codex skill (multi-AI second opinion via OpenAI Codex CLI)
├── land-and-deploy/ # /land-and-deploy skill (merge → deploy → canary verify)
├── office-hours/ # /office-hours skill (YC Office Hours — startup diagnostic + builder brainstorm)
├── investigate/ # /investigate skill (systematic root-cause debugging)
├── spec/ # /spec skill (five-phase spec → GitHub issue, optional agent spawn, /ship auto-closes)
├── retro/ # Retrospective skill (includes /retro global cross-project mode)
├── bin/ # CLI utilities (gstack-repo-mode, gstack-slug, gstack-config, etc.)
├── document-release/ # /document-release skill (post-ship doc updates + Diataxis coverage map)
├── document-generate/ # /document-generate skill (Diataxis doc generator: tutorial/how-to/reference/explanation)
├── cso/ # /cso skill (OWASP Top 10 + STRIDE security audit)
├── design-consultation/ # /design-consultation skill (design system from scratch)
├── design-shotgun/ # /design-shotgun skill (visual design exploration)
├── open-gstack-browser/ # /open-gstack-browser skill (launch GStack Browser)
├── connect-chrome/ # symlink → open-gstack-browser (backwards compat)
├── design/ # Design binary CLI (GPT Image API)
│ ├── src/ # CLI + commands (generate, variants, compare, serve, etc.)
│ ├── test/ # Integration tests
│ └── dist/ # Compiled binary
├── extension/ # Chrome extension (side panel + activity feed + CSS inspector)
├── lib/ # Shared libraries (worktree.ts, egress-receipt.ts, context-bill.ts, redact-engine.ts, code-intelligence/)
├── docs/designs/ # Design documents
├── setup-deploy/ # /setup-deploy skill (one-time deploy config)
├── .github/ # CI workflows + Docker image
│ ├── workflows/ # evals.yml (E2E on Ubicloud), quality-gate.yml (secret scan), dependency-review.yml, osv-scanner.yml, skill-docs.yml, actionlint.yml, and 7 more (windows, periodic evals, release gates, ci-image)
│ └── docker/ # Dockerfile.ci (pre-baked toolchain + Playwright/Chromium)
├── contrib/ # Contributor-only tools (never installed for users)
│ └── add-host/ # /gstack-contrib-add-host skill
├── setup # One-time setup: build binary + symlink skills
├── SKILL.md # Generated from SKILL.md.tmpl (don't edit directly)
├── SKILL.md.tmpl # Template: edit this, run gen:skill-docs
├── ETHOS.md # Builder philosophy (Boil the Ocean, Search Before Building)
└── package.json # Build scripts for browse
```
## SKILL.md workflow
SKILL.md files are **generated** from `.tmpl` templates. To update docs:
1. Edit the `.tmpl` file (e.g. `SKILL.md.tmpl` or `browse/SKILL.md.tmpl`)
2. Run `bun run gen:skill-docs` (or `bun run build` which does it automatically)
3. Commit both the `.tmpl` and generated `.md` files
To add a new browse command: add it to `browse/src/commands.ts` and rebuild.
To add a snapshot flag: add it to `SNAPSHOT_FLAGS` in `browse/src/snapshot.ts` and rebuild.
**Token ceiling:** Generated SKILL.md files trip a warning above 160KB (~40K tokens).
This is a "watch for feature bloat" guardrail, not a hard gate. Modern flagship
models have 200K-1M context windows, so 40K is 4-20% of window, and prompt caching
makes the marginal cost of larger skills small. The ceiling exists to catch runaway
preamble/resolver growth, not to force compression on carefully-tuned big skills
(`ship`, `plan-ceo-review`, `office-hours` legitimately pack 25-35K tokens of
behavior). If you blow past 40K, the right fix is usually: (1) look at WHAT grew,
(2) if one resolver added 10K+ in a single PR, question whether it belongs inline
or as a reference doc, (3) only compress carefully-tuned prose as a last resort —
cuts to the coverage audit, review army, or voice directive have real quality cost.
A second, harder ceiling guards the DISCOVERY surface: `test/catalog-budget.test.ts`
caps the aggregate frontmatter `name` + `description` across all skills at 1,150
token-equivalents (260-byte per-skill sub-cap), counted through the shared census
in `test/helpers/skill-census.ts`. This one is enforced, not a warning — every
host loads the full catalog every session, so growth here taxes every
conversation. The failure message carries the re-measure + ratchet protocol.
`bin/gstack-context-bill` shows the full token bill-of-materials for a skills
tree (always-on vs per-invocation, `--diff`, `--budget`; `--exact` opts into the
real tokenizer and POSTs file text to api.anthropic.com with an egress receipt).
**Merge conflicts on SKILL.md files:** NEVER resolve conflicts on generated SKILL.md
files by accepting either side. Instead: (1) resolve conflicts on the `.tmpl` templates
and `scripts/gen-skill-docs.ts` (the sources of truth), (2) run `bun run gen:skill-docs`
to regenerate all SKILL.md files, (3) stage the regenerated files. Accepting one side's
generated output silently drops the other side's template changes.
## Platform-agnostic design
Skills must NEVER hardcode framework-specific commands, file patterns, or directory
structures. Instead:
1. **Read CLAUDE.md** for project-specific config (test commands, eval commands, etc.)
2. **If missing, AskUserQuestion** — let the user tell you or let gstack search the repo
3. **Persist the answer to CLAUDE.md** so we never have to ask again
This applies to test commands, eval commands, deploy commands, and any other
project-specific behavior. The project owns its config; gstack reads it.
## Writing SKILL templates
SKILL.md.tmpl files are **prompt templates read by Claude**, not bash scripts.
Each bash code block runs in a separate shell — variables do not persist between blocks.
Rules:
- **Use natural language for logic and state.** Don't use shell variables to pass
state between code blocks. Instead, tell Claude what to remember and reference
it in prose (e.g., "the base branch detected in Step 0").
- **Don't hardcode branch names.** Detect `main`/`master`/etc dynamically via
`gh pr view` or `gh repo view`. Use `{{BASE_BRANCH_DETECT}}` for PR-targeting
skills. Use "the base branch" in prose, `<base>` in code block placeholders.
- **Keep bash blocks self-contained.** Each code block should work independently.
If a block needs context from a previous step, restate it in the prose above.
- **Express conditionals as English.** Instead of nested `if/elif/else` in bash,
write numbered decision steps: "1. If X, do Y. 2. Otherwise, do Z."
## Writing style (V1)
Default output from every tier-≥2 skill follows the Writing Style section in
`scripts/resolvers/preamble.ts`: jargon glossed on first use (curated list in
`scripts/jargon-list.json`, baked at gen-skill-docs time), questions framed in
outcome terms ("what breaks for your users if...") not implementation terms,
short sentences, decisions close with user impact. Power users who want the
tighter V0 prose set `gstack-config set explain_level terse` (binary switch,
no middle mode). See `docs/designs/PLAN_TUNING_V1.md` for the full design
rationale. The review pacing overhaul that originally tried to ride alongside
writing-style was extracted to V1.1 — see `docs/designs/PACING_UPDATES_V0.md`.
## Browser interaction
When you need to interact with a browser (QA, dogfooding, cookie setup), use the
`/browse` skill or run the browse binary directly via `$B <command>`. NEVER use
`mcp__claude-in-chrome__*` tools — they are slow, unreliable, and not what this
project uses.
**Sidebar architecture:** Before modifying `sidepanel.js`, `background.js`,
`content.js`, `terminal-agent.ts`, or sidebar-related server endpoints,
read `docs/designs/SIDEBAR_MESSAGE_FLOW.md`. The sidebar has one primary
surface — the **Terminal** pane (interactive `claude` PTY) — with
Activity / Refs / Inspector as debug overlays behind the footer's
`debug` toggle. The chat queue path was ripped once the PTY proved out;
`sidebar-agent.ts` and the `/sidebar-command` / `/sidebar-chat` /
`/sidebar-agent/event` endpoints are gone. The doc covers the WS auth
flow, dual-token model, and threat-model boundary — silent failures
here usually trace to not understanding the cross-component flow.
**Embedder terminal-agent ownership** (v1.42.1.0+, identity-based kill v1.44.0.0+).
`buildFetchHandler` in `browse/src/server.ts` accepts `ServerConfig.ownsTerminalAgent?:
boolean` (default `true`). When `true`, factory shutdown runs the full teardown:
identity-based kill via `killAgentByRecord(readAgentRecord(stateDir))` from
`browse/src/terminal-agent-control.ts` plus `safeUnlinkQuiet` on
`<stateDir>/terminal-port`, `<stateDir>/terminal-internal-token`, and
`<stateDir>/terminal-agent-pid` (the per-boot agent record introduced in v1.44).
Embedders (e.g. the gbrowser phoenix overlay) that pre-launch their own PTY
server must pass `false` so their discovery files survive gstack teardown cycles.
The flag is the third caller-owned teardown gate in `ServerConfig` (alongside
`xvfb?` and `proxyBridge?`); polarity is inverted (explicit bool vs presence) and
documented in the field's JSDoc. CLI `start()` always passes `true` explicitly —
the static-grep test in `browse/test/server-embedder-terminal-port.test.ts` fails
CI if a refactor drops it. Pre-v1.44 used `pkill -f terminal-agent\.ts` (regex
match) which would kill sibling gstack sessions on the same host; the new
`browse/test/terminal-agent-pid-identity.test.ts` static-grep tripwire fails CI
if any source file re-introduces `pkill ... terminal-agent` or `spawnSync('pkill', ...)`.
**WebSocket auth uses Sec-WebSocket-Protocol, not cookies.** Browsers
can't set `Authorization` on a WebSocket upgrade, but they CAN set
`Sec-WebSocket-Protocol` via `new WebSocket(url, [token])`. The agent
reads it, validates against `validTokens`, and MUST echo the protocol
back in the upgrade response — without the echo, Chromium closes the
connection immediately. `Set-Cookie: gstack_pty=...` is kept as a
fallback for non-browser callers (the cross-port `SameSite=Strict`
cookie path doesn't survive from a chrome-extension origin).
**Cross-pane PTY injection.** The toolbar's Cleanup button and the
Inspector's "Send to Code" action both pipe text into the live claude
PTY via `window.gstackInjectToTerminal(text)`, exposed by
`sidepanel-terminal.js`. No `/sidebar-command` POST — the live REPL is
the only execution surface in the sidebar now.
**`/health` MUST NOT surface any token — and it no longer does** (v1.63+).
The historical headed-mode leak of `AUTH_TOKEN` is fixed: `GET /health` is
liveness/status only in every mode. Token bootstrap is `POST /extension-token`,
which validates the caller's Origin against the pinned extension identity
(the `key` field in `extension/manifest.json` pins the extension ID —
`GSTACK_EXTENSION_ID` in `browse/src/server.ts`, derivation reproducible via
`bun browse/scripts/extension-id.ts`) plus a loopback Host. PTY auth still
flows through `POST /pty-session` only. Don't add any token to `/health`.
**Transport-layer security** (v1.6.0.0+). When `pair-agent` starts an ngrok tunnel,
the daemon binds two HTTP listeners: a local listener (127.0.0.1, full command
surface, never forwarded) and a tunnel listener (locked allowlist: `/connect`,
`/command` with a scoped token + 26-command browser-driving allowlist,
`/sidebar-chat`). ngrok forwards only the tunnel port. Root tokens over the tunnel
return 403. SSE endpoints use a 30-minute HttpOnly `gstack_sse` cookie minted via
`POST /sse-session` (never valid against `/command`). Tunnel-surface rejections go
to `~/.gstack/security/attempts.jsonl` via `tunnel-denial-log.ts`. Before editing
`server.ts`, `sse-session-cookie.ts`, or `tunnel-denial-log.ts`, read
[ARCHITECTURE.md](ARCHITECTURE.md#dual-listener-tunnel-architecture-v1600) —
the module boundary (no imports from `token-registry.ts` into `sse-session-cookie.ts`)
is load-bearing for scope isolation.
**Unicode sanitization at server egress** (v1.38.0.0+). Every server egress that
ships page-content-derived strings MUST go through `JSON.stringify(payload,
sanitizeReplacer)` for object payloads or `sanitizeLoneSurrogates(body)` for text
bodies. Lone UTF-16 surrogate halves from CDP page content otherwise reach the
Anthropic API as `\uD800`-style escapes and trigger a 400. Wired at four egress
points today: `handleCommandInternal` (HTTP + batch via a sanitizing wrapper around
`handleCommandInternalImpl`) and both SSE producers (`/activity/stream`,
`/inspector/events`). Post-stringify regex is a no-op — `JSON.stringify` has
already escaped the surrogate before regex could match, so the replacer must run
inside the encoding pipeline. Before adding a new SSE/WebSocket writer or HTTP
response in `server.ts`, read
[ARCHITECTURE.md](ARCHITECTURE.md#unicode-sanitization-at-server-egress-v13800).
`browse/test/server-sanitize-surrogates.test.ts` pins the wiring with invariant
tests, so bypasses fail CI.
**Egress receipts at every off-machine sink** (v1.63.0.0+). Every gstack-initiated
send off the machine MUST write a hash-chained receipt to
`~/.gstack/security/egress.jsonl` BEFORE the send: TypeScript callers use
`writeReceipt` from `lib/egress-receipt.ts`; shell scripts source
`bin/gstack-egress-lib.sh` and use `_receipted_curl` / `_receipted_git`. Failure
polarity is per-class: fail-closed for sensitive sinks (brain-sync, memory-ingest,
gbrain-sync, telemetry, ngrok tunnels, mcp-verify, supabase-provision), fail-open
+ stderr warning for user-facing ones (design OpenAI calls, update-check,
dashboards, git-class ops). The new-sink scanner in
`test/egress-receipt-wiring.test.ts` fails CI on an unreceipted `curl` /
`git push` / `fetch` to a non-loopback host unless the file carries a reasoned
entry in its `SCANNER_EXEMPT` list (user-directed page fetches, reachability
probes, instruction strings, skill prose) — if you add a new off-machine sink,
wire it through the helpers and add it to the enumerated sink list. Inspect with
`bin/gstack-egress` (`list` | `verify`, exit 3 on tamper | `grants`). Threat
model: forensic observability of ATTEMPTED egress, not an exfiltration control.
**SSE endpoint helper** (v1.51.0.0+). New SSE endpoints in `server.ts` MUST route
through `createSseEndpoint(req, config)` from `browse/src/sse-helpers.ts`. The
helper owns the cleanup contract (abort + enqueue-throw + heartbeat-throw, all
idempotent) and bakes in `sanitizeLoneSurrogates` on every JSON.stringify, so
new subscribers can't accidentally regress either invariant. Inline
`ReadableStream` wiring leaked subscribers when the TCP connection died without
firing `req.signal.abort` (Chromium MV3 service-worker suspend, intermediate
proxy half-close). `/activity/stream`, `/inspector/events`, and `/memory`
(SSE-eligible) all route through it. `browse/test/sse-helpers.test.ts` pins the
cleanup contract.
**CDP session lifecycle** (v1.51.0.0+). Direct `page.context().newCDPSession(page)`
calls outside `browse/src/cdp-bridge.ts` fail CI via the static-grep tripwire in
`browse/test/cdp-session-cleanup.test.ts`. Use `withCdpSession(page, async (s) => {...})`
for one-shot CDP work (try/finally detach) or `getOrCreateCdpSession(page, cache)`
for cached sessions tied to a page's lifetime (close-detach via `Map<page, session>`).
Three sites migrated: cdp-bridge frame events, write-commands archive capture,
cdp-inspector. The helpers prevent the per-session leak class where successful-path
detach happened but error-path detach was missed.
**Setup symlink hardening** (v1.38.0.0+). Every link site in `setup` MUST route
through the `_link_or_copy SRC DST` helper near the `IS_WINDOWS` detection. On
Windows without Developer Mode, plain `ln -snf` produces frozen file copies that
don't refresh on `git pull` — silent staleness across every host adapter. The
helper preserves `ln -snf` on Unix and switches to `cp -R` / `cp -f` on Windows.
`test/setup-windows-fallback.test.ts` enforces a static invariant: a single raw
`ln` call outside the helper body fails CI. Windows users get a one-line note
from `_print_windows_copy_note_once` reminding them to re-run `./setup` after
every `git pull`.
**Sidebar security stack** (layered defense against prompt injection):
| Layer | Module | Lives in |
|-------|--------|----------|
| L1-L3 | `content-security.ts` | server + read path — datamarking, hidden element strip, ARIA regex, URL blocklist, envelope wrapping |
| L4 | `security-classifier.ts` (TestSavantAI ONNX) | **security sidecar subprocess only** (`security-sidecar-entry.ts`, driven by `security-sidecar-client.ts` from server.ts) |
| Canary | `security.ts` (generate/inject/detect) | pure utilities — no production injector today (the chat prompt-builder that injected them was ripped) |
| Combiner | `security.ts` (combineVerdict + THRESHOLDS) | pure, tested; retains transcript/deberta vote handling for LayerSignal inputs no live layer produces anymore |
History note: an L4b Haiku transcript classifier and an opt-in DeBERTa ensemble
(`GSTACK_SECURITY_ENSEMBLE=deberta`) existed until the chat-path agent that
invoked them was ripped; both were deleted as dead code (zero production
callers). Do not re-document them as live.
**Critical constraint:** `security-classifier.ts` CANNOT be imported from the
compiled browse binary. `@huggingface/transformers` v4 requires `onnxruntime-node`
which fails to `dlopen` from Bun compile's temp extract dir — hence the sidecar
subprocess. Only `security.ts` (pure-string operations — canary utilities,
verdict combiner, status) is safe for `server.ts`. See
`~/.gstack/projects/garrytan-gstack/ceo-plans/2026-04-19-prompt-injection-guard.md`
§"Pre-Impl Gate 1 Outcome" for the original architectural decision.
**Thresholds** (in `security.ts`): `BLOCK: 0.85`, `WARN: 0.75`, `LOG_ONLY: 0.40`,
`SOLO_CONTENT_BLOCK: 0.92` (label-less content classifiers can't distinguish
"injection" from "phishing aimed at the user", so their solo bar is higher).
The live L4 path applies these in server.ts's sidecar-scan handling; canary
leak always BLOCKs (deterministic).
**Env knobs:**
- `GSTACK_SECURITY_OFF=1` — emergency kill switch. Classifier stays off even if
warmed; the L1-L3 filters keep running.
- Classifier model cache: `~/.gstack/models/testsavant-small/` (112MB, first run only)
- Attack log: `~/.gstack/security/attempts.jsonl` — written by
`tunnel-denial-log.ts` (tunnel-surface rejections; rotates at 10MB, 5 generations)
- Session state: `~/.gstack/security/session-state.json` (cross-process, atomic;
NOTE: classifierStatus currently has no live writer — shield status derives
from what's on disk)
## Dev symlink awareness
When developing gstack, `.claude/skills/gstack` may be a symlink back to this
working directory (gitignored). This means skill changes are **live immediately**,
great for rapid iteration, risky during big refactors where half-written skills
could break other Claude Code sessions using gstack concurrently.
**Check once per session:** Run `ls -la .claude/skills/gstack` to see if it's a
symlink or a real copy. If it's a symlink to your working directory, be aware that:
- Template changes + `bun run gen:skill-docs` immediately affect all gstack invocations
- Breaking changes to SKILL.md.tmpl files can break concurrent gstack sessions
- During large refactors, remove the symlink (`rm .claude/skills/gstack`) so the
global install at `~/.claude/skills/gstack/` is used instead
**Prefix setting:** Setup creates real directories (not symlinks) at the top level
with a SKILL.md symlink inside (e.g., `qa/SKILL.md -> gstack/qa/SKILL.md`). This
ensures Claude discovers them as top-level skills, not nested under `gstack/`.
Names are either short (`qa`) or namespaced (`gstack-qa`), controlled by
`skill_prefix` in `~/.gstack/config.yaml`. Pass `--no-prefix` or `--prefix` to
skip the interactive prompt.
**Note:** Vendoring gstack into a project's repo is deprecated. Use global install
+ `./setup --team` instead. See README.md for team mode instructions.
**For plan reviews:** When reviewing plans that modify skill templates or the
gen-skill-docs pipeline, consider whether the changes should be tested in isolation
before going live (especially if the user is actively using gstack in other windows).
**Upgrade migrations:** When a change modifies on-disk state (directory structure,
config format, stale files) in ways that could break existing user installs, add a
migration script to `gstack-upgrade/migrations/`. Read CONTRIBUTING.md's "Upgrade
migrations" section for the format and testing requirements. The upgrade skill runs
these automatically after `./setup` during `/gstack-upgrade`.
## Compiled binaries — never commit browse/dist/, design/dist/, or make-pdf/dist/
The `browse/dist/`, `design/dist/`, and `make-pdf/dist/` directories contain
compiled Bun binaries (`browse`, `find-browse`, `design`, ~62MB each). These are
Mach-O arm64 only — they do NOT work on Linux, Windows, or Intel Macs. The
`./setup` script builds from source for every platform.
These directories are **untracked and gitignored** (`.gitignore:3-6`; the
`browse/dist/` binaries were untracked in `64d5a3e4`, v0.11.16.0; the others were
never tracked). They will NOT appear in `git status`. If a dist binary ever does
show up in `git status`, something force-added it (`git add -f`) — do not commit
it; unstage it and find out how it got there.
When staging files, always use specific filenames (`git add file1 file2`) — never
`git add .` or `git add -A`, which can sweep in build outputs and junk.
## Redaction guard (PII / secrets / legal content)
Shared redaction engine catches credentials, PII, and legal/damaging content
before it reaches an external sink (codex dispatch, GitHub issue/PR body, pushed
commit). It is a **guardrail, not airtight enforcement** — `git push --no-verify`,
direct `gh issue create`, and `GSTACK_REDACT_PREPUSH=skip` all bypass it. It
catches accidents and carelessness, the 99% case. Do not claim it stops a
determined leaker (a CHANGELOG line that does would fail a hostile screenshotter).
- **Engine + taxonomy:** `lib/redact-patterns.ts` (the single source of truth —
3 tiers; HIGH = genuinely-secret credentials that block, MEDIUM = PII/legal/
internal + high-FP credential shapes that confirm via AskUserQuestion, LOW =
FYI) and `lib/redact-engine.ts` (pure `scan()` + `applyRedactions()`).
Calibration matters: a gate that cries wolf gets ignored, so context-variable
shapes (Stripe `pk_live_`, Google `AIza`, JWT, env `*_KEY=`) sit at MEDIUM.
- **CLI:** `bin/gstack-redact` (exit 0 clean / 2 MEDIUM / 3 HIGH; `--json`,
`--auto-redact`, `--repo-visibility`, `--from-file`). `bin/gstack-redact-prepush`
is the opt-in git hook.
- **Skill docs are generated** from `scripts/resolvers/redact-doc.ts`
(`{{REDACT_INVOCATION_BLOCK:<sink>}}`) so /spec,
/cso, /ship, /document-release, /document-generate never drift from the engine.
- **Scan-at-sink:** always scan the EXACT bytes that will be sent — write to a
temp file, scan that file, pass the SAME file to `gh`/`git`. Never scan a string
then re-render (that reopens a scan-vs-send gap).
- **Visibility (no tier promotion):** resolve once per run, order = local config
(`gstack-config get redact_repo_visibility`, ~/.gstack so never committed) → gh
→ glab → unknown(=public-strict). Public repos get STERNER per-finding
confirmation (no batch-acknowledge, no silent-proceed); MEDIUM is never
auto-promoted to HIGH.
- **Tool-attributed fences:** wrap Codex/Greptile/eval output in ` ```codex-review `
/ ` ```greptile ` fences so example credentials those tools quote WARN-degrade
instead of blocking. A live-format credential inside the fence still blocks.
- **Config keys:** `redact_repo_visibility` (public|private|unknown, local-only
override for repos gh/glab can't read), `redact_prepush_hook` (true|false).
There is intentionally NO key to disable HIGH blocking.
- **Audit:** the /spec semantic pass appends a content-free record (categories +
body sha256, no spec text) to `~/.gstack/security/semantic-reviews.jsonl` (0600).
## Commit style
**Always bisect commits.** Every commit should be a single logical change. When
you've made multiple changes (e.g., a rename + a rewrite + new tests), split them
into separate commits before pushing. Each commit should be independently
understandable and revertable.
Examples of good bisection:
- Rename/move separate from behavior changes
- Test infrastructure (touchfiles, helpers) separate from test implementations
- Template changes separate from generated file regeneration
- Mechanical refactors separate from new features
When the user says "bisect commit" or "bisect and push," split staged/unstaged
changes into logical commits and push.
## Slop-scan: AI code quality, not AI code hiding
We use [slop-scan](https://github.com/benvinegar/slop-scan) to catch patterns where
AI-generated code is genuinely worse than what a human would write. We are NOT trying
to pass as human code. We are AI-coded and proud of it. The goal is code quality.
```bash
npx slop-scan scan . # human-readable report
npx slop-scan scan . --json # machine-readable for diffing
```
Config: `slop-scan.config.json` at repo root (currently excludes `**/vendor/**`).
### What to fix (genuine quality improvements)
- **Empty catches around file ops** — use `safeUnlink()` (ignores ENOENT, rethrows
EPERM/EIO). A swallowed EPERM in cleanup means silent data loss.
- **Empty catches around process kills** — use `safeKill()` (ignores ESRCH, rethrows
EPERM). A swallowed EPERM means you think you killed something you didn't.
- **Redundant `return await`** — remove when there's no enclosing try block. Saves a
microtask, signals intent.
- **Typed exception catches** — `catch (err) { if (!(err instanceof TypeError)) throw err }`
is genuinely better than `catch {}` when the try block does URL parsing or DOM work.
You know what error you expect, so say so.
### What NOT to fix (linter gaming, not quality)
- **String-matching on error messages** — `err.message.includes('closed')` is brittle.
Playwright/Chrome can change wording anytime. If a fire-and-forget operation can fail
for ANY reason and you don't care, `catch {}` is the correct pattern.
- **Adding comments to exempt pass-through wrappers** — "alias for active session" above
a method just to trip slop-scan's exemption rule is noise, not documentation.
- **Converting extension catch-and-log to selective rethrow** — Chrome extensions crash
entirely on uncaught errors. If the catch logs and continues, that IS the right pattern
for extension code. Don't make it throw.
- **Tightening best-effort cleanup paths** — shutdown, emergency cleanup, and disconnect
code should use `safeUnlinkQuiet()` (swallows ALL errors). A cleanup path that throws
on EPERM means the rest of cleanup doesn't run. That's worse.
### Utilities in `browse/src/error-handling.ts`
| Function | Use when | Behavior |
|----------|----------|----------|
| `safeUnlink(path)` | Normal file deletion | Ignores ENOENT, rethrows others |
| `safeUnlinkQuiet(path)` | Shutdown/emergency cleanup | Swallows all errors |
| `safeKill(pid, signal)` | Sending signals | Ignores ESRCH, rethrows others |
| `isProcessAlive(pid)` | Boolean process checks | Returns true/false, never throws |
### Score tracking
Baseline (2026-04-09, before cleanup): 100 findings, 432.8 score, 2.38 score/file.
After cleanup: 90 findings, 358.1 score, 1.96 score/file.
Don't chase the number. Fix patterns that represent actual code quality problems.
Accept findings where the "sloppy" pattern is the correct engineering choice.
## Community PR guardrails
When reviewing or merging community PRs, **always AskUserQuestion** before accepting
any commit that:
1. **Touches ETHOS.md** — this file is Garry's personal builder philosophy. No edits
from external contributors or AI agents, period.
2. **Removes or softens promotional material** — YC references, founder perspective,
and product voice are intentional. PRs that frame these as "unnecessary" or
"too promotional" must be rejected.
3. **Changes Garry's voice** — the tone, humor, directness, and perspective in skill
templates, CHANGELOG, and docs are not generic. PRs that rewrite voice to be
more "neutral" or "professional" must be rejected.
Even if the agent strongly believes a change improves the project, these three
categories require explicit user approval via AskUserQuestion. No exceptions.
No auto-merging. No "I'll just clean this up."
## Checking out PRs from garrytan-agents
When the user says "check out <PR link>" and the PR is from `garrytan-agents/gstack`
(or any other fork that is NOT a collaborator on `garrytan/gstack`), do NOT just
`gh pr checkout`. Fork PRs don't receive base-repo secrets (`ANTHROPIC_API_KEY`,
`OPENAI_API_KEY`, etc.), so the eval/E2E CI jobs fail with empty-env auth errors
regardless of what's set on the base repo.
**Workflow:** push the branch to `garrytan/gstack` (the base repo) and re-target
the PR from there.
Concretely, after `gh pr checkout <N>`:
1. Note the original PR number and head branch name.
2. Push the same branch to the base repo: `git push origin HEAD:<branch-name>`
(origin = `garrytan/gstack`, since the worktree is set up with that remote).
3. Close the fork PR (`gh pr close <N> --comment "moving to base-repo branch for secret access"`).
4. Open a new PR from the base-repo branch: `gh pr create --base main --head <branch-name>`.
5. New PR's workflows will get secrets automatically.
Why not fix it on the fork side? `garrytan-agents` isn't a collaborator on
`garrytan/gstack`. Adding it as a collaborator (option A) or flipping the
repo-wide "send secrets to fork PRs" toggle (option B) would let secrets reach
fork PRs from anyone — broader blast radius than just moving this one branch.
Option C (this section) keeps secret-distribution scope tight.
If the user asks you to skip the move (e.g., "just leave it as a fork PR"),
respect that — eval CI will fail with empty-env auth, but check-freshness,
workflow-lint, and windows-tests will still pass on the fork PR.
## CHANGELOG + VERSION style
**Versioning invariant (workspace-aware ship).** VERSION is a monotonic ordered
release identifier, not a strict semver commitment. The bump level
(major/minor/patch/micro) expresses intent at ship time. Queue-advancing past a
claimed version within the same bump level is explicitly permitted — if branch A
claims v1.7.0.0 as a MINOR and branch B is also a MINOR, B lands at v1.8.0.0
(still a MINOR relative to main). Downstream consumers must NOT rely on
"MINOR = feature-only, PATCH = fix-only" as a strict contract. This is why
`bin/gstack-next-version` advances within the chosen bump level rather than
repicking the level when collisions happen.
**Scale-aware bumps — use common sense.** When the diff is big, bump MINOR (or
MAJOR), not PATCH. PATCH is for bug fixes and small additions; MINOR is for
substantial new capability or substantial reduction; MAJOR is for breaking
changes. Rough guideposts (don't treat as rules, treat as smell-checks):
- **PATCH (X.Y.Z+1.0)**: bug fix, doc tweak, small additive change, single
test/file added. Net diff under ~500 lines, no new user-facing capability.
- **MINOR (X.Y+1.0.0)**: new capability shipped (skill, harness, command, big
refactor), substantial code reduction (compression, migration), or coordinated
multi-file change. Net diff over ~2000 lines added/removed, OR a user-visible
feature you'd put in a tweet.
- **MAJOR (X+1.0.0.0)**: breaking change to public surface (CLI flag rename,
skill removed, config format changed), OR a release big enough to be the
headline of a blog post.
If you find yourself debating "is 10K added + 24K removed really a PATCH?" — it
isn't. Bump MINOR. Same for "this adds a whole new test harness with 6 new E2E
tests + helper utilities" — MINOR. The bump level is communication to the user
about what kind of release this is; don't undersell it.
When merging origin/main brings a higher VERSION, re-evaluate the bump level
against the SCALE of your branch's work, not just whether main moved forward.
If main bumped MINOR and your branch is also a substantial change, you bump
MINOR again on top (e.g., main at v1.14.0.0, your branch lands v1.15.0.0).
**VERSION and CHANGELOG are branch-scoped.** Every feature branch that ships gets its
own version bump and CHANGELOG entry. The entry describes what THIS branch adds —
not what was already on main.
**The CHANGELOG entry is the diff between main and the shipping branch — what users
get when they upgrade. NOT how the branch got there.** A reader landing on the entry
should learn what they can do now that they couldn't before; they should not learn
about the branch's internal version bumps, the bugs we caught and fixed mid-branch,
the plan reviews we ran, or the commits we squashed. That is branch development
narrative. It belongs in PR descriptions and commit messages, not CHANGELOG.
**Never reference branch-internal versions in a CHANGELOG entry.** If your branch
bumped VERSION from v1.5.0.0 → v1.5.1.0 → v1.6.0.0 during development and only the
final v1.6.0.0 ships to main, the entry must read as if v1.5.1.0 never existed.
Concretely, NEVER write:
- "v1.5.1.0 had a bug that v1.6.0.0 fixes" — readers don't know about v1.5.1.0; it's
a branch-internal artifact.
- "The shipping headline of v1.5.1.0 was broken because..." — same reason. From main's
perspective, v1.5.1.0 was never released.
- "Pre-fix tests encoded the broken behavior" — that's a contributor's victory lap,
not a user benefit.
- "Two surgical edits, both in the dispatch path" — micro-narrative of the patch.
Instead, describe the released system: "Browser-skills run end-to-end with the
expected tab-access semantics." If a property of the shipped system is worth calling
out (e.g., "skill spawns get permissive tab access; pair-agent tunnel tokens require
ownership"), document it as a property, not as a fix. The shipped system is what
the user gets; the path to that system is invisible to them.
**When to write the CHANGELOG entry:**
- At `/ship` time (Step 13), not during development or mid-branch.
- The entry covers ALL commits on this branch vs the base branch.
- Never fold new work into an existing CHANGELOG entry from a prior version that
already landed on main. If main has v0.10.0.0 and your branch adds features,
bump to v0.10.1.0 with a new entry — don't edit the v0.10.0.0 entry.
**Key questions before writing:**
1. What branch am I on? What did THIS branch change?
2. Is the base branch version already released? (If yes, bump and create new entry.)
3. Does an existing entry on this branch already cover earlier work? (If yes, replace
it with one unified entry for the final version.)
**Merging main does NOT mean adopting main's version.** When you merge origin/main into
a feature branch, main may bring new CHANGELOG entries and a higher VERSION. Your branch
still needs its OWN version bump on top. If main is at v0.13.8.0 and your branch adds
features, bump to v0.13.9.0 with a new entry. Never jam your changes into an entry that
already landed on main. Your entry goes on top because your branch lands next.
**After merging main, always check:**
- Does CHANGELOG have your branch's own entry separate from main's entries?
- Is VERSION higher than main's VERSION?
- Is your entry the topmost entry in CHANGELOG (above main's latest)?
If any answer is no, fix it before continuing.
**After any CHANGELOG edit that moves, adds, or removes entries,** immediately run
`grep "^## \[" CHANGELOG.md` to verify no duplicates and a sensible reverse-chronological
order. Gaps between version numbers are fine. A branch that ships at v1.6.4.0 without
a prior v1.5.2.0 or v1.5.3.0 entry on main is correct — those were branch-internal
version numbers that never landed. Do not back-fill gaps with placeholder entries.
**Never orphan branch-internal versions.** If your branch bumped VERSION several times
during development (v1.5.1.0 → v1.5.2.0 → v1.6.4.0, say) and those earlier entries were
never released to main, the final ship consolidates ALL of them into a single entry at
the final version (v1.6.4.0). Collapse them — delete the old entries and move their
content into the final entry, re-version table columns accordingly. Readers see one
release, not a branch diary. Gaps are fine (v1.6.3.0 → v1.6.4.0 with no v1.5.x
in between on main is correct).
CHANGELOG.md is **for users**, not contributors. Write it like product release notes:
- Lead with what the user can now **do** that they couldn't before. Sell the feature.
- Use plain language, not implementation details. "You can now..." not "Refactored the..."
- **Never mention TODOS.md, internal tracking, eval infrastructure, or contributor-facing
details.** These are invisible to users and meaningless to them.
- Put contributor/internal changes in a separate "For contributors" section at the bottom.
- Every entry should make someone think "oh nice, I want to try that."
- No jargon: say "every question now tells you which project and branch you're in" not
"AskUserQuestion format standardized across skill templates via preamble resolver."
**Only document what shipped between main and this change.** Readers do not care how
we got here. Keep out of the CHANGELOG, always:
- Branch resyncs, merge commits with main, rebase activity.
- Plan approvals, review outcomes (CEO / eng / design / outside-voice / codex findings),
AskUserQuestion decisions, scope negotiations.
- "Work queued," "plan approved," "in-progress," "will ship later" — the CHANGELOG
documents what DID ship, not what MIGHT ship.
- Version-bump housekeeping when no user-facing work actually landed.
If the diff between the base branch version and this version has no user-facing change
(only merges, only CHANGELOG edits, only placeholder work), the honest entry is one
sentence: "Version bump for branch-ahead discipline. No user-facing changes yet." Stop
there. Do not pad. Do not explain the plan that will ship eventually. Do not narrate
the branch's history. When real work lands, the entry will replace this at /ship time.
### Release-summary format (every `## [X.Y.Z]` entry)
Every version entry in `CHANGELOG.md` MUST start with a release-summary section in
the GStack/Garry voice, one viewport's worth of prose + tables that lands like a
verdict, not marketing. The itemized changelog (subsections, bullets, files) goes
BELOW that summary, separated by a `### Itemized changes` header.
The release-summary section gets read by humans, by the auto-update agent, and by
anyone deciding whether to upgrade. The itemized list is for agents that need to
know exactly what changed.
Structure for the top of every `## [X.Y.Z]` entry:
1. **Two-line bold headline** (10-14 words total). Should land like a verdict, not
marketing. Sound like someone who shipped today and cares whether it works.
2. **Lead paragraph** (3-5 sentences). What shipped, what changed for the user.
Specific, concrete, no AI vocabulary, no em dashes, no hype.
3. **A "The X numbers that matter" section** with:
- One short setup paragraph naming the source of the numbers (real production
deployment OR a reproducible benchmark, name the file/command to run).
- A table of 3-6 key metrics with BEFORE / AFTER / Δ columns.
- A second optional table for per-category breakdown if relevant.
- 1-2 sentences interpreting the most striking number in concrete user terms.
4. **A "What this means for [audience]" closing paragraph** (2-4 sentences) tying
the metrics to a real workflow shift. End with what to do.
Voice rules for the release summary:
- No em dashes (use commas, periods, "...").
- No AI vocabulary (delve, robust, comprehensive, nuanced, fundamental, etc.) or
banned phrases ("here's the kicker", "the bottom line", etc.).
- Real numbers, real file names, real commands. Not "fast" but "~30s on 30K pages."
- Short paragraphs, mix one-sentence punches with 2-3 sentence runs.
- Connect to user outcomes: "the agent does ~3x less reading" beats "improved precision."
- Be direct about quality. "Well-designed" or "this is a mess." No dancing.
Source material:
- CHANGELOG previous entry for prior context.
- Benchmark files or `/retro` output for headline numbers.
- Recent commits (`git log <prev-version>..HEAD --oneline`) for what shipped.
- Don't make up numbers. If a metric isn't in a benchmark or production data,
don't include it. Say "no measurement yet" if asked.
Target length: ~250-350 words for the summary. Should render as one viewport.
### Itemized changes (below the release summary)
Write `### Itemized changes` and continue with the detailed subsections (Added,
Changed, Fixed, For contributors). Same rules as the user-facing voice guidance
above, plus:
- **Always credit community contributions.** When an entry includes work from a
community PR, name the contributor with `Contributed by @username`. Contributors
did real work. Thank them publicly every time, no exceptions.
## AI effort compression
When estimating or discussing effort, always show both human-team and CC+gstack time:
| Task type | Human team | CC+gstack | Compression |
|-----------|-----------|-----------|-------------|
| Boilerplate / scaffolding | 2 days | 15 min | ~100x |
| Test writing | 1 day | 15 min | ~50x |
| Feature implementation | 1 week | 30 min | ~30x |
| Bug fix + regression test | 4 hours | 15 min | ~20x |
| Architecture / design | 2 days | 4 hours | ~5x |
| Research / exploration | 1 day | 3 hours | ~3x |
Completeness is cheap. Don't recommend shortcuts when the complete implementation
is achievable. Boil the ocean — the complete thing is the goal; only genuinely
unrelated multi-quarter migrations are separate scope, never an excuse for a
shortcut. See the Completeness Principle in the skill preamble for the full
philosophy.
## Search before building
Before designing any solution that involves concurrency, unfamiliar patterns,
infrastructure, or anything where the runtime/framework might have a built-in:
1. Search for "{runtime} {thing} built-in"
2. Search for "{thing} best practice {current year}"
3. Check official runtime/framework docs
Three layers of knowledge: tried-and-true (Layer 1), new-and-popular (Layer 2),
first-principles (Layer 3). Prize Layer 3 above all. See ETHOS.md for the full
builder philosophy.
## Local plans
Contributors can store long-range vision docs and design documents in `~/.gstack-dev/plans/`.
These are local-only (not checked in). When reviewing TODOS.md, check `plans/` for candidates
that may be ready to promote to TODOs or implement.
## E2E eval failure blame protocol
When an E2E eval fails during `/ship` or any other workflow, **never claim "not
related to our changes" without proving it.** These systems have invisible couplings —
a preamble text change affects agent behavior, a new helper changes timing, a
regenerated SKILL.md shifts prompt context.
**Required before attributing a failure to "pre-existing":**
1. Run the same eval on main (or base branch) and show it fails there too
2. If it passes on main but fails on the branch — it IS your change. Trace the blame.
3. If you can't run on main, say "unverified — may or may not be related" and flag it
as a risk in the PR body
"Pre-existing" without receipts is a lazy claim. Prove it or don't say it.
## Long-running tasks: don't give up
When running evals, E2E tests, or any long-running background task, **poll until
completion**. Use `sleep 180 && echo "ready"` + `TaskOutput` in a loop every 3
minutes. Never switch to blocking mode and give up when the poll times out. Never
say "I'll be notified when it completes" and stop checking — keep the loop going
until the task finishes or the user tells you to stop.
The full E2E suite can take 30-45 minutes. That's 10-15 polling cycles. Do all of
them. Report progress at each check (which tests passed, which are running, any
failures so far). The user wants to see the run complete, not a promise that
you'll check later.
## Running evals as an agent: always detach (SIGTERM-proof)
When **you (an agent/harness)** launch a long eval/benchmark run, run it through
`bin/gstack-detach` — NEVER as a plain backgrounded Bash task. A plain background
task lives in the harness's process group, so a SIGTERM ("polite quit") on a turn
boundary, a stopped Monitor, or an interruption kills the run mid-flight (observed:
`script "test:gate" was terminated by signal SIGTERM` ~40 min into a run). On macOS
the run can also die to idle-sleep. `gstack-detach` fixes both: a fresh session
(escapes the group SIGTERM) wrapped in `caffeinate -i` (blocks idle-sleep).
- Use the `eval:bg*` scripts (`eval:bg`, `eval:bg:all`, `eval:bg:gate`,
`eval:bg:periodic`) — they wrap the eval command in `gstack-detach` with the
machine-wide `gstack-evals` lock (concurrent worktrees serialize instead of
saturating the shared model API), a per-tier watchdog, and a **run-scoped** log
under `~/.gstack-dev/eval-runs/` (no shared-`/tmp` collision). Each prints its
log path. `eval:bg:gate` / `eval:bg:periodic` run their tier through the
sharded paid runner (`scripts/test-paid-shards.ts`, also exposed as
`test:gate:sharded` / `test:periodic:sharded`): one Bun process per test
file, an external wall-clock timeout that kills the shard's process GROUP
(stray `claude`/`codex` grandchildren included), a per-shard
`GSTACK_EVAL_DIR=<evalDir>/shards/<slug>/` honored by the `EvalCollector`
constructor, and an aggregate that separates failed vs timed-out vs
never-started shards — the detach timeouts (25200s gate / 32400s periodic;
floor enforced against the live shard census by
test/eval-detach-timeout-floor.test.ts)
are sized against worst-case shard wall clock. `EVALS_JOBS` sets the shard
process count (default 4); `EVALS_CONCURRENCY` is bun's --max-concurrency
WITHIN a shard (default 4) — they are deliberately separate knobs. `eval:list` / `eval:compare` /
`eval:summary` read the shard dirs too. Or call
`gstack-detach [--lock NAME] [--timeout SECS] [--label LBL] --
<cmd>` directly for any long agent job. Export `ANTHROPIC_API_KEY` first (never
pass keys in argv).
- Then **poll the printed logfile** with a death-aware watcher: break on the
guaranteed `### gstack-detach EXIT=<code> ###` sentinel (success AND failure are
both marked, so silence is never mistaken for success). The detached run survives
even if your watcher gets reaped, so re-checking the log always works.
- Why the lock: a shared dev box with several Conductor worktrees will rate-limit
the model API if two eval suites run at once (15-way concurrency each), which
mass-times-out E2E tests. The lock makes the second run WAIT, not collide.
- Humans running `bun run test:evals` foreground in their own terminal don't need
this — Ctrl-C is intended there. Detachment is for agent-launched runs only.
## E2E test fixtures: extract, don't copy
**NEVER copy a full SKILL.md file into an E2E test fixture.** SKILL.md files are
1500-2000 lines. When `claude -p` reads a file that large, context bloat causes
timeouts, flaky turn limits, and tests that take 5-10x longer than necessary.
Instead, extract only the section the test actually needs:
```typescript
// BAD — agent reads 1900 lines, burns tokens on irrelevant sections
fs.copyFileSync(path.join(ROOT, 'ship', 'SKILL.md'), path.join(dir, 'ship-SKILL.md'));
// GOOD — agent reads ~60 lines, finishes in 38s instead of timing out
const full = fs.readFileSync(path.join(ROOT, 'ship', 'SKILL.md'), 'utf-8');
const start = full.indexOf('## Review Readiness Dashboard');
const end = full.indexOf('\n---\n', start);
fs.writeFileSync(path.join(dir, 'ship-SKILL.md'), full.slice(start, end > start ? end : undefined));
```
Also when running targeted E2E tests to debug failures:
- Run in **foreground** (`bun test ...`), not background with `&` and `tee`
- Never `pkill` running eval processes and restart — you lose results and waste money
- One clean run beats three killed-and-restarted runs
## Publishing native OpenClaw skills to ClawHub
Native OpenClaw skills live in `openclaw/skills/gstack-openclaw-*/SKILL.md`. These are
hand-crafted methodology skills (not generated by the pipeline) published to ClawHub
so any OpenClaw user can install them.
**Publishing:** The command is `clawhub publish` (NOT `clawhub skill publish`):
```bash
clawhub publish openclaw/skills/gstack-openclaw-office-hours \
--slug gstack-openclaw-office-hours --name "gstack Office Hours" \
--version 1.0.0 --changelog "description of changes"
```
Repeat for each skill: `gstack-openclaw-ceo-review`, `gstack-openclaw-investigate`,
`gstack-openclaw-retro`. Bump `--version` on each update.
**Auth:** `clawhub login` (opens browser for GitHub auth). `clawhub whoami` to verify.
**Updating:** Same `clawhub publish` command with a higher `--version` and `--changelog`.
**Verification:** `clawhub search gstack` to confirm they're live.
## Deploying to the active skill
The active skill lives at `~/.claude/skills/gstack/`. After making changes:
1. Push your branch
2. Fetch and reset in the skill directory: `cd ~/.claude/skills/gstack && git fetch origin && git reset --hard origin/main`
3. Rebuild: `cd ~/.claude/skills/gstack && bun run build`
**If you use gbrain:** the `git reset --hard` in step 2 reverts the brain-aware
(`GBRAIN_CONTEXT_LOAD` / `GBRAIN_SAVE_RESULTS`) blocks that `gstack-config
gbrain-refresh` renders into the install (those generated blocks differ from
`main` by design). After deploying, re-run `gstack-config gbrain-refresh` to
restore them across all your projects' Claude sessions. It's idempotent.
Or copy the binaries directly:
- `cp browse/dist/browse ~/.claude/skills/gstack/browse/dist/browse`
- `cp design/dist/design ~/.claude/skills/gstack/design/dist/design`
## Skill routing
When the user's request matches an available skill, invoke it via the Skill tool. When in doubt, invoke the skill.
Key routing rules:
- Product ideas/brainstorming → invoke /office-hours
- Strategy/scope → invoke /plan-ceo-review
- Architecture → invoke /plan-eng-review
- Design system/plan review → invoke /design-consultation or /plan-design-review
- Full review pipeline → invoke /autoplan
- Bugs/errors → invoke /investigate
- QA/testing site behavior → invoke /qa or /qa-only
- Code review/diff check → invoke /review
- Visual polish → invoke /design-review
- Ship/deploy/PR → invoke /ship or /land-and-deploy
- Save progress → invoke /context-save
- Resume context → invoke /context-restore
## Cross-session decision memory
Durable decisions and their rationale are captured in an append-only, event-sourced
store at `~/.gstack/projects/<slug>/decisions.jsonl` so neither you nor the user
re-litigates a settled call or loses the "why" across sessions. This is the reliable,
file-only path: it works with gbrain OFF. (gbrain semantic recall is an optional
enhancement layered on top, never a dependency.)
- **Resurface** active decisions before re-deciding: `bin/gstack-decision-search`
(`--recent N`, `--scope repo|branch|issue`, `--query KW`, `--all`, `--json`).
Add `--semantic` (with `--query`) to append related hits from gbrain memory when
it's up; it degrades silently to the reliable file results when gbrain is off.
Session start already surfaces scope-relevant active decisions via Context Recovery.
If a decision is listed, treat it as settled with its rationale; if you're about to
reverse it, say so explicitly.
- **Capture** a DURABLE decision when you or the user make one:
`bin/gstack-decision-log '{"decision":"...","rationale":"...","scope":"repo|branch|issue","source":"user|skill|agent","confidence":1-10}'`.
Reverse a prior call with `--supersede <id>`; expunge an accidental secret with
`--redact <id>`; rewrite the log to the active set with `--compact`. Non-interactive
(never prompts), injection-sanitized, and HIGH-secret-blocking on write.
- **Durable means:** architecture choice, scope cut, tool/vendor choice, or a reversal
of a prior call. NOT a turn-level edit, a phrasing tweak, or anything trivially
re-derivable. Capture is curated at the source — log durable decisions only, or the
store becomes noise.
## GBrain Search Guidance (configured by /sync-gbrain)
<!-- gstack-gbrain-search-guidance:start -->
GBrain is set up and synced on this machine. The agent should prefer gbrain
over Grep when the question is semantic or when you don't know the exact
identifier yet.
**This worktree is pinned to a worktree-scoped code source** via the
`.gbrain-source` file in the repo root (kubectl-style context). Any
`gbrain code-def`, `code-refs`, `code-callers`, `code-callees`, or `query`
call from anywhere under this worktree routes to that source by default —
no `--source` flag needed. Conductor sibling worktrees of the same repo
each have their own pin and their own indexed pages, so semantic results
match the actual code on disk in this worktree.
Two indexed corpora available via the `gbrain` CLI:
- This worktree's code (auto-pinned via `.gbrain-source`).
- `~/.gstack/` curated memory (registered as `gstack-brain-<user>` source via
the existing federation pipeline).
Prefer gbrain when:
- "Where is X handled?" / semantic intent, no exact string yet:
`gbrain search "<terms>"` or `gbrain query "<question>"`
- "Where is symbol Y defined?" / symbol-based code questions:
`gbrain code-def <symbol>` or `gbrain code-refs <symbol>`
- "What calls Y?" / "What does Y depend on?":
`gbrain code-callers <symbol>` / `gbrain code-callees <symbol>`
- "What did we decide last time?" / past plans, retros, learnings:
`gbrain search "<terms>" --source gstack-brain-<user>`
Grep is still right for known exact strings, regex, multiline patterns, and
file globs. Run `/sync-gbrain` after meaningful code changes; for ongoing
auto-sync across all worktrees, run `gbrain autopilot --install` once per
machine — gbrain's daemon handles incremental refresh on a schedule.
Safety: don't run `/sync-gbrain` while `gbrain autopilot` is active — the
orchestrator refuses destructive source ops when it detects a running autopilot
to avoid racing it (#1734). Prefer registering user repos with `gbrain sources
add --path <dir>` (no `--url`): URL-managed sources can auto-reclone, and the
sync code walk for them requires an explicit `--allow-reclone` opt-in.
<!-- gstack-gbrain-search-guidance:end -->
Reference in New Issue View Git Blame Copy Permalink