Garry Tan
55f8151fbe
* docs: approved reliability follow-ups plan (Oct 2026)
* D1: score overlay wrong answers as comparison results (contract v4)
A completed answer that fails the fixture's output check is now a valid
measurement with taskCorrect false and answerError set, in either arm.
Only execution, scope and metric failures invalidate a trial. ON
correctness still gates the case, so an OFF wrong answer stays in the
comparison. OVERLAY_CONTRACT moves to v4; v3 verdicts are not
reinterpreted. Replays the 37198445662 sonnet trials (OFF-0 wrong).
* C4: score auq-matrix substance with a 3-sample judge panel
Each skill keeps one native capture in the same execution; the
recommendation-substance grader now runs as a JUDGE_PANEL_SAMPLES panel on
that capture and gates on the mean against the unchanged minimum of 4. A
failed sample fails the panel without resampling. Approved at the gate
2026-10-04 for censuses after this change.
* E1: one Bun version source; setup refuses below the 1.3.3 floor, updater checks before advancing
bin/gstack-bun-version.sh holds the security floor (1.3.3) and the tested
version (1.4.0, the CI pin and engines.bun). setup refuses Bun below the
floor before writing anything, warns between floor and tested, warns and
continues on an unparseable version, and prints a 1.4.0 install hint.
Prereleases sort below their release (semver).
gstack-session-update now fetches, reads the incoming release's floor and
checks the bun setup will run before fast-forwarding to that exact
revision; below it the update is held with reason bun-too-old and a
resume command, leaving the revision and installs untouched.
Fixture copies of setup (team-mode, claude-code migration) now include the
sourced file; the slow-git lock test sleeps on fetch, the updater's
network step.
* E3: record the owned Chromium's PID over CDP so the #2709 reap runs on Playwright 1.62
Playwright 1.62's Browser has no process(), so chromiumProcInfo was always
null and browse stop never reaped a surviving headless Chromium. The owned
headless launch now reads the browser PID from CDP SystemInfo.getProcessInfo
(bounded at 2s; a hung or failed call logs once and records nothing). The
reaper's start-time and cmdline identity checks are unchanged, so a recycled
PID or an externally owned browser is never signalled.
* A1: ship docs gate records post-child hashes with gstack-docs-candidate, saves each record once
Stored transcripts (37198445662 gate-census-2) show the parent's reads of
release files take ~1 s; the parent's own model time dominates (completion
268 s of 392 s, store ~270 s of 387 s), and 45-78 s of it is retyping hash
maps, child output and records into several artifacts after the child
returns. The child contract is unchanged.
* A2: /plan-ceo-review sends the mode handoff line before any other tool call
plan-ceo-mode-routing's HOLD SCOPE session spends its 240 s post-selection
window on model work: 37176837432 skipped the handoff helper and paraphrased
the mode, 37198445662 ran it, then wrote the plan, loaded sections and probed
Codex for 114 s before the posture chat. The handoff line is the posture.
* B3: accept wrapped unchanged rows in the cropped Edit preview
PR run 37176835584 timed out with the floor's owned Edit menu on screen:
unchanged diff rows soft-wrap under their gutter with a blank marker
column, and a trimmed empty unchanged row keeps only its number. The
parser accepted wrapped +/- rows only, so it never verified the owned
edit. Both forms are now parsed and still compared with the exact source
lines; the captured viewport is replayed with negative controls.
* A3: record per-phase headroom diagnosis for docsync, plan-mode-no-op, mode-routing and gate slice 11
* E4: /review Step 1 keeps going when the base fetch fails and reports stale base coverage
Under Codex's read-only .git, 'git fetch && merge-base && diff --stat'
stopped at the fetch, so the empty output read as 'Nothing to review'.
The fetch is now separate, prints BASE_REFRESH fresh or stale with the
local base revision, and the review states stale coverage.
* D2: reword the format-approach question prompt
Both plan-ceo-review-format-approach refusals in census 37195203538
(Fable 5.1 model_refusal_no_fallback, category reasoning_extraction:
"duplicating model outputs") were anchored on the session prompt, whose
capture instruction asked for the "verbatim" question and "the exact
prose you would have shown" in a "format-capture test". The approach
case now asks for the same question in the same file as the step's
output, without that wording. The other three plan-format cases keep
their unchanged prompt (no refusals in 72 trials).
* C2: /qa defines its outcome filename fields; QA report templates name the measured timing fields
Low judge samples in failing panels named both: qa workflow (37186854666)
'an undefined {user} in the outcome filename', and qa-only workflow
(37198445662) 'template asks for Duration / durationMs totals while
reporting.md mandates Probe budget and Guarded command time'. The qa
union stays under its 1.11 size ratio (93292 of 93294 bytes).
* 0.1: session ledger written by the claude -p, Agent SDK, PTY and Codex runners
Each armed model session appends one best-effort line to
$GSTACK_EVAL_DIR/session-ledger.jsonl: a stable session key, the timeout it
armed, monotonic elapsed time, its end reason (completed, session_timeout,
observer_timeout, api_error, refusal, aborted, error), one sanitized evidence
line and, for stream-JSON runners, a compact liveness summary (longest
in-request silence with nothing outstanding, last event kind, tool open at
end). Partial messages now stream for every claude -p session and for SDK
sessions without a custom query provider (runSharedInteractive opts in); their
rows feed only the summary, so transcripts keep their size unless
publicStreamDiagnostics is set. Structured refusal and API-error signals win
over phrases, and tool results are never read for them.
* 0.2: failure_cause beside failure_class, from runner facts and the session ledger
One pure failureCauseOf() beside failureClassOf() sets failure_cause
(contract > pre_turn_infra > api_error > refusal > provider_stall >
session_timeout > observer_timeout > assertion > unknown; no machine-set
'detector') with one bounded evidence line, and failureDetailOf() keeps a
Bun matcher's Expected/Received or a judge's failing dimensions in
failure_detail. Both record builders (classifyTrialShard, junitCensus) call
them and attach the trial's ledger sessions. failure_class, error and
TRIAL_ERROR_MAX are computed exactly as before; the new fields are optional,
bounded and validated only when present, and a frozen copy of the v1 reader
accepts every new record. A provider stall needs partial messages and
STALL_WINDOW_MS (120 s, eval-budgets.ts beside HEADROOM_WARN/FAIL) of
in-request silence with nothing outstanding; it stays a failure under
EVAL_POLICY v1.
* E4: fingerprint under a read-only .git via a private object dir owned by review-log
Codex's sandbox mounts .git read-only, so gstack-wtree's git add -A could not
write blobs and /review lost its start capture. gstack-review-log now creates
a private 0700 object directory under TMPDIR, passes it to gstack-wtree (which
writes new objects there with the common-dir object store, resolved before
exporting, as an alternate, so linked worktrees work), exposes it to the
bindReview/checkSharedLibsReuse consumers that read the tree and blobs, and
removes it on EXIT/INT/TERM after they finish. gstack-wtree prints one stderr
line and exits 1 on a failed write or unwritable TMPDIR instead of printing a
partial hash; review-log no longer swallows that line. Standalone gstack-wtree
keeps writing to the repository store so git diff between saved snapshots
(/ship) still works.
* 0.3: red lines name their values, evidence and an after-a-repair command; one published-text sanitizer
Each red line in the census report keeps its stored error and adds the
machine cause with its evidence, the failure_detail values (Expected/Received,
or each failing judge dimension with its mean, sample count and the sample
sentence naming it), the slice artifact and shard directory that hold the
transcript, a fetch command (eval:pass-rates --run <id> --case <id>), and
'after a repair:' with a command that selects only that case (E2E ids via
--case, judges via their selection and an exact test-name filter). A
session that completed and failed a check says so instead of 'assertion
(success)'. Report text that reaches a PR comment, issue or committed file
goes through scripts/lib/published-text.ts: control and bidi characters
stripped, credential-scan patterns redacted, mentions neutralized, HTML and
link brackets escaped inline, blocks in a fence longer than any backtick run,
length capped. Verdicts and collector verdict objects are unchanged.
* E2: one make-pdf resolver for readiness and every $P block on env-var hosts
make-pdf exported $P from its readiness block, which Codex and the other
env-var hosts lose between blocks. binaryAssignment gains 'make-pdf': the
MAKE-PDF SETUP readiness check and the runtime prelude both use it, so every
block that runs $P derives the same make-pdf/dist/pdf binary, with
MAKE_PDF_BIN (dev builds) winning when it is executable. Claude output keeps
its repo-local-first probe; only the false 'subsequent blocks' comment
changed. Root plus P=... fits the 400-byte prelude budget; the fixed
MAKE_PDF_OVERRIDE segment is the one exemption, named in runtime-root.ts and
the conformance test.
* 0.1: eval:pass-rates --headroom, --reds and --run report views; 85% headroom alarm in --gate
A new pure module, scripts/lib/eval-history.ts, reports per case the slowest
armed session against the timeout it armed (censored when it timed out,
insufficient below 3 samples, unknown without a session ledger, with the
case wall shown separately as an upper bound), the census critical path from
the slice jobs' timings, the verdict red ledger per census by failure class
and machine cause with shrunk per-case rates, and the all-green probability
(an approximation: the product of 1 - p_i, with an interval). --run <id>
lists one census's reds with their values and history and downloads only the
slice artifacts those reds name, reporting any over 64 MB instead of skipping
them. eval-flake-rank.ts only routes flags: --help works offline, an unknown
flag or case id exits 2 before any fetch, --case narrows the JSON and the
alarms, every view prints its run/branch scope, and --gate also alarms on a
session above HEADROOM_FAIL (85%) of its budget.
* E5: GSTACK_DESIGN_IMAGE_MODEL override; the live model check always tests the defaults
The image_generation tool model gains an env override validated against a
conservative gpt-image-<version> pattern; a bad value fails before any
request and the error names the variable. Pairing and rejection hints name
the tool model actually requested. design/scripts/live-model-check.ts now
ignores GSTACK_DESIGN_MODEL and GSTACK_DESIGN_IMAGE_MODEL (and says so), so
an override cannot mask a retirement of a default, and its exit 2 (no key)
says nothing was checked.
* C3: /deslop-shared-libs names a concrete risk for each recommendation, never 'none'
Both shared-libs-opportunity-judgment reds (37193478719 t3, 37195203538 t1)
failed adoption_and_risk because the top recommendation said 'Main risk:
none found inside the repo' / 'none in behavior'. The skill asked to 'name
the main risk or uncertainty' without saying what counts.
* B4: --case selects loop-registered cases; an unknown id exits before any process
caseSelection() resolves the one paid file that registers a case and how a
trial selects it: by its literal Bun test name, by the id a registration loop
names its test at runtime (coverage audits, TPA, journeys), or by running the
whole file when it registers no other case (plan-mode-no-op, whose test names
are not the id, so the old name pattern ran nothing). A whole-file case runs
one file shard per trial and is judged by shard status, as CI judges it.
--list prints the selection. Every E2E_TIERS id now resolves except
carve-section-loading, which fifteen files register (CI runs each as its own
shard) and which still fails with the owning files named.
* 0.3: after-a-repair runs the shard file when --case cannot resolve a case
A case that several files register (carve-section-loading) cannot be selected
by --case; its red line now prints the bun test command for the shard file
that went red, so every printed command selects exactly one case.
* C1: pre-register workflow-judge control bundles for qa, qa-only, review and setup-deploy
Positive (production bundle), negative (headings only) and one targeted
execution-blocking defect per judge, one 3-sample panel each, built with the
eval's own reader, prompt builder, options and floors.
* F: cost_known: a trial whose harness captured no billing says so; totals never hide it
cost_usd stays a finite number. Trial and eval records gain an optional
cost_known boolean (absent means known, so old records still parse; the
validator accepts only a boolean). Session-ledger rows record whether the
session's terminal result carried total_cost_usd; PTY and Codex sessions
never do, and SDK captures without a terminal result do not. A trial is
cost-known only when it has eval records and every record and session
captured billing, so JUnit-only PTY cases (125 of 298 trials in run
37198445662 recorded 0) now read cost unknown. The census headline prints the
known sum plus the unknown count, never a bare total over unknown costs, and
no total when every cost is unknown; the history import keeps the flag.
PTY transcripts are not priced: test/helpers/pricing.ts estimates exclude
cache writes, so they cannot give the billed cost.
* B1: replay corpora for the five repeat-offender cases
shared-libs-plan-callers, plan-ceo-section-loading, auto-decide-preserved,
plan-design-review-plan-mode and ship-docsync-late-result each get an
inventory of every wave census in scope (all artifacts still available)
and minimal, redacted detector or actor inputs replayed through the real
detector in the free suite: census passes, every distinct census red, and
derived negative controls labelled as derived. Fixed false reds stay as
expected passes with their history; the two genuine auto-decide product
failures (37176837432, 37179171083) stay refused. A contract test bounds
each entry at 64 KB, scans it for HIGH credentials, requires a pass and a
refusal per case, and reports entries whose series identity is stale.
Building the auto-decide corpus exposed a latent native detector misread:
a bold 'Mode application and rationale.' heading was parsed as a
withdrawn Mode field (37186854666). A field status now ends at its
sentence.
* B2: read approved stale-fill decisions from more valid ledger records
The structured ledger reader is authoritative before the prose fallback,
but it missed two valid approved records in passing censuses
(37186854666: a camelCase writeProfile subject; 37195203538: a
slash-joined 'D1 / STALE-FILL' row id), which then rested on the prose
detector that caused both historical reds. Both forms are accepted; an
unresolved row, an unrelated decision, the copied fixture plan and
non-write camelCase words stay refused.
* C1: record workflow-judge control results (negatives separated; qa and review miss a removed step)
* C2: record every low workflow-judge sample in the wave censuses with its disposition
* 0.3: published lines cannot break a fixed fence
evals.yml wraps collector-outcomes failures in a fixed three-backtick fence
for the PR comment, so those lines (and eval:pass-rates output meant for the
tracking issue) go through sanitizeFixedFenceLine: cleaned like every
published line, with backticks turned into quotes. Inline published text
also neutralizes backticks.
* A1: fit the post-child record wording under ship's 1.428 parity size cap
* E4: inline the Step 1 base refresh to fit review's 1.199 parity size cap
* B2: inventory of gate and periodic phrase-only detector checks
docs/evals/detector-inventory.md lists every pass/fail decision in gate
and periodic E2E cases that rests on phrases in model free text, with
its structured source (if any), whether the contract is user-visible,
and a disposition: already structured-first, convert candidate, phrase
witness required, or no structured source. Convert candidates are
ordered by census red history.
* 0.2: failureCauseOf takes the stall window instead of importing it; the PTY ledger never throws
eval-store.ts imported STALL_WINDOW_MS from eval-budgets.ts, which free tests
replace with mock.module stubs (review-finalization-budget, office-hours,
qa-fix-loop, qa-only), so loading eval-store failed there. failureCauseOf is
now dependency-free: the record builders pass STALL_WINDOW_MS. A PTY session
whose handle cannot show its text (test doubles) records no panel instead of
throwing from runPtySession's cleanup. The 37186854666 replay also runs
through classifyTrialShard.
* A2/auto-decide: the CEO handoff chat repeats the helper's printed line verbatim
Claude Code 2.1.284 collapses the helper's Bash output ('Ran 1 shell
command'), so the 'Auto-decided review mode → …' line reaches the user only
through chat. In lane D's auto-decide-preserved corpus every passing capture's
chat starts with that line, and the reds paraphrased it ('HOLD SCOPE was
auto-selected…', 'Mode decision done…', "I'm defaulting to HOLD SCOPE…").
The template now says verbatim and why.
* C2: record the judge panels rerun on the final ship and review wording
* integrate: touchfiles and module-size ratchet entries for the wave's new modules
GLOBAL_TOUCHFILES gains session-ledger.ts, published-text.ts and
auq-substance-panel.ts; bin/gstack-bun-version.sh joins every entry that
lists setup or the updater; auq-matrix stays a rule case with its C4
evidence beside E2E_KINDS; eval-history, published-text and session-ledger
are registered new modules.
* E1: BROWSE SETUP install hint pins the tested Bun (1.4.0)
* E2: quote "$P" in make-pdf commands so install paths with spaces work
* E1: /gstack-upgrade checks the incoming Bun floor before pulling
gstack_bun_incoming_hold (bin/gstack-bun-version.sh) is now the one
pre-advance check: the auto-updater calls it before its fast-forward and
/gstack-upgrade's git path calls it after fetching. Below the incoming
release's floor the upgrade stops with BUN_TOO_OLD and the checkout,
VERSION and installs stay untouched. Vendored installs were already safe:
setup refuses before writing and the swap restores the previous install.
* 0.3: only main posts or closes tracking issues; reports carry alarms, red ledger, headroom and all-green
A branch-dispatched periodic or marathon run writes its report to the step
summary and a report artifact; the upsert and close steps run only on
refs/heads/main. The periodic body now keeps every pass-rate alarm line (the
old grep kept only the header), adds the red ledger and session headroom read
with an explicit --branch, the all-green estimate and the triage guide link,
and routes report text through scripts/lib/published-text.ts. The marathon
lane gains the matching close-on-green step.
Migrated: evals-workflow-wiring pinned report-summary.md in the upsert step;
the body is now written by 'Write the census report'.
* C3: prosons neutral-posture detector ignores a negated "taste call"
Both plan-review-prosons-neutral-neg reds (37179171083 t3, 37193478719 t3)
recommended A and closed with "a coverage call, not a taste call"; the
old /taste call/i matched the negation. The detector moves to a helper so
the two census captures replay free as negatives, with positive controls.
* B2: credit the CEO mode handoff only when the chat shows its line
Claude Code 2.1.284 collapses the gstack-ceo-mode-handoff Bash result, so
the printed AUTO_DECIDE line is user-visible only when a later chat message
of the session begins with it. The native detector now requires that
witness; the helper's tool result locates it but no longer replaces it, and
a generic mode statement cannot stand in once a handoff ran. Census
37182865432 is relabelled a genuine miss (expected: refused): the chat said
"I'm defaulting to HOLD SCOPE…" and "Mode decided: HOLD SCOPE". Corpus
replay: 5 credited, 3 refused. ceo-mode-handoff tests migrated to the
witness rule (deliberate behavior change).
* test: baseline the wave's approved detector and harness replay tests
B1 corpora, B3, C3, C4 and D2 replay captures through paid-case detectors,
actors or fixtures (test code by design); each entry carries its reason.
* E6: live Codex multi-block periodic case in the host-run Codex job
test/codex-e2e-multiblock-live.test.ts runs ./setup --host codex once from the
job's checkout into a fresh HOME and CODEX_HOME (auth.json copied from the CI
login home), asserts codex debug prompt-input lists the gstack router as a
real file, seeds one learning, and runs /learn's Show recent block through
codex exec: that later block must root itself through its prelude, run the
installed gstack-learnings-search and print the seeded learning; no block may
report a missing install or an unresolved gstack helper path.
The file joins CODEX_CI_FILES so the planner gives it to the host-run Codex
job. paid-test-durations.json carries a 180 s packing estimate (refreshed by
--write-durations after the first census) so the plan keeps every slice
within max-parallel. Oracles live in test/helpers/codex-multiblock.ts with
free replays in test/codex-multiblock.test.ts. Registration (E2E_TOUCHFILES,
E2E_TIERS periodic, E2E_KINDS rule) is the integrator's.
* E5: design live-model check as a periodic case
test/skill-e2e-design-model-smoke.test.ts runs design/scripts/live-model-check.ts
(default models only) under a temp HOME. Without OPENAI_API_KEY the case is a
Bun skip that the census lists as SKIPPED with no coverage credit; with a key,
exit 0 passes and any other exit fails with the script output (exit 2 under a
present key fails as 'nothing was checked'). paid-test-durations.json carries
a 90 s packing estimate. Registration (E2E_TOUCHFILES, E2E_TIERS periodic,
E2E_KINDS rule) is the integrator's.
* A1: docsync parent points children at a saved interface file
The /ship docsync fixture saved its observation interface only in the
parent prompt and told the parent to copy it into every child prompt,
about 30-40 s of parent generation per session (lane S, 37198445662).
docsSessionOptions now writes it to <home>/fixture-interface.md (0600) and
the parent tells each child to Read that file first. Fault-actor prompts,
which prepare already writes to a file, are unchanged. Fixture-only.
* A3: a JUnit case's recorded wall is capped by its shard's wall
junitCensus summed a case's JUnit test times as duration_ms; for
plan-mode-no-op's concurrent PTY tests that is 346 s inside a 176 s shard
(the "432-613 s" history). The case wall headroom shows is now
min(sum, shard elapsed), a true upper bound. Session headroom already
used the ledger's per-session clocks.
* A3: refresh paid-test durations from census 37198445662
Recorded 2026-09-29 estimates under-packed gate slice 11 (17 files
estimated 1078 s ran 1353 s; plan-review-report 76 s -> 198 s,
plan-ceo-plan-mode 37 s -> 112 s, safety-codex-consult 83 s -> 150 s).
Refreshed both tiers with --report --write-durations from the latest
census's slice walls. Old plan re-costed with observed walls: worst slice
~677 s (slice 11); refreshed plan: every slice estimated <= 539 s.
* C2: Browser Quick gets a feasible budget; QA loop names its directory and stop path
Judge rationales on the qa-only panels (2 of the last 3) cited the 30 s
Browser Quick budget: homepage + 5 targets, each a checkpoint write and a
guarded command, left ~5 s per probe. Quick is now 180 s (method text: 3
minutes); the qa-only-no-fix paid check expects the same native deadline.
PROBE_DIR points at its source line, a stopped loop goes to the final
report steps (annotations, materialize, Markdown), and /review and /ship
say that after smoke expiry only plan checks rerun in revalidation.
* C2: name the flows judges found implicit in review resolvers
Structured outside review: MISSING COVERAGE asks no fix question and is
never reported clean (was "preserve the existing user decision flow").
/review's HIGH-impact plan gate: spawned or non-interactive runs report
REQUIREMENTS MISSING and continue, writing no TODOs. Value cards: the byte
clamp applies to card lines; JSON records you write keep full values.
* C1: a free test catches a removed workflow step, which the judges missed
C1 controls showed the qa workflow judge passing /qa without Phase 10 and
the review judge passing /review without Step 3. The new test pins every
step/phase heading of qa, qa-only, review, ship, plan-ceo-review,
plan-eng-review and setup-deploy (derived from the templates' step
headings) and names any that goes missing or out of order; new step
headings must be pinned. The judge rubric is unchanged (EVAL_POLICY).
* size: fit the wave's wording under ship, review and qa parity caps
Measured after all lane merges: ship -79, review -210, qa -68 bytes over.
Trimmed the added wording first (post-expiry rule, MISSING COVERAGE,
plan-gate default, value-card JSON, stop line) and folded /review's
redundant INFORMATIONAL sentence and findings bullet. ship 268,036 (room
8), review 130,118 (room 1). qa needed 11 more bytes: cap 1.11 -> 1.1102
with the measured 93,305 / 84,049 = 1.11013 and its reason beside it.
* docs: troubleshooting sections for the wave's new messages
Bun floor (setup, auto-update, /gstack-upgrade), /review stale base and
fingerprint temp-dir errors, the design image model override, the
unrecorded Chromium PID, and a contributor section for census report
lines (pass-rates flags, failure causes, headroom, cost unknown, overlay
v4, stale corpora, auq substance). A free test checks every
troubleshooting.md#anchor printed by setup or bin scripts exists.
* TODOS: reliability follow-ups deferrals; close the Bun floor, make-pdf $P and #2709 reap
* 0.4: 'A census went red' guide; docs for causes, session ledger, headroom and new messages
docs/evals/census-red.md walks one red line to a diagnosis: prerequisites, the
report fields, eval:pass-rates --run/--reds/--headroom with expected output,
what unknown/insufficient/unrecorded data means, free replay, and the single
'after a repair' paid run allowed by TESTING_INTERNALS. Linked from
CONTRIBUTING, TESTING_INTERNALS and both census reports.
TESTING_INTERNALS documents the failure_cause glossary (one row per
FAILURE_CAUSES value, diagnostic only under EVAL_POLICY v1), failure_detail,
sessions[], cost_known, the session ledger, the pass-rates views and the 85%
headroom alarm, main-only tracking issues, overlay contract v4, auq-matrix's
3-sample substance panel and the E5/E6 periodic cases. troubleshooting.md
gains #bun-too-old and an anchor per new user-facing message from lanes P, D
and F. README names GSTACK_DESIGN_IMAGE_MODEL. test/census-red-docs.test.ts
pins the glossary to FAILURE_CAUSES, parses every guide command and checks the
links.
* v1.91.20.0: CHANGELOG and version for the reliability follow-ups
* regen: SKILL.md and sections for all hosts, digest, context-budget fixture
bun run gen:skill-docs --host all; goldens and llms.txt re-rendered
unchanged; bun test/helpers/capture-context-budget.ts.
* integrate: register codex-multiblock-live and design-model-smoke (periodic, rule)
* 0.4: census report and eval:pass-rates views link the census-red guide
* test: cookie approval fixture reverses the Bun install-hint pin (E1)
The historical approved cookie-workflow prompt carried BUN_VERSION=1.3.10;
the regenerated install hint now pins 1.4.0, so the fixture's reversal
list gains that edit like the earlier waves' entries.
* test: release floor counts the two new periodic cases (E5, E6)
* fix: /freeze, /guard, /unfreeze and /investigate work on Codex and other env-var hosts
Templates quoted "$HOME/.claude/skills/gstack/...", which the env-var hosts'
rewrites turned into "$HOME/.agents/skills/gstack/..." on Codex (a path a
global install never has; same class on the other hosts), and setup's
runtime roots had no freeze/bin. Quoted runtime paths now use
{{RUNTIME_ROOT}}: $GSTACK_ROOT on env-var hosts (the fence gets the
runtime prelude), the unchanged $HOME path on Claude. _link_runtime_dists
links freeze/bin and the careful/bin helper it sources into every
env-var host's root. Also fixes the same guess in /benchmark-models,
/retro and /diagram. test/env-host-runtime-assets.test.ts fails on the
previous code: no fence guesses a $HOME/<dir>/skills/gstack path, every
$GSTACK_ROOT path a fence uses is in the host's runtime root, and the
installed Codex /freeze and /unfreeze fences run from a fresh shell.
Template-reading tests now read the Claude render or expect the
placeholder (deliberate change).
* CHANGELOG/TODOS: lane W's workflow, cases and guide; the env-var host freeze fix
* E6: a block that reads a SKILL.md is not a missing install
The first live codex-multiblock-live run passed its real check (the /learn
block found the install and printed the seeded learning) but the oracle
flagged a sed of the learn SKILL.md, whose prelude source quotes the
'gstack: no install found (tried $_r)' text. Only an emitted line that
starts with the message and names a real root counts now; free replay
negative added.
* test: qa-only fixture keeps its caller-set 30 s deadline
The qa-only-no-fix fixture tells the model to start the guard with 30 s
(a caller limit), so its deadline assertion's default stays 30 000 ms; the
product's Browser Quick default (180 s) does not apply to it. Reverts the
helper and its test to their base.
* C2: keep PROBE_DIR 'owned' (qa-functional-prompt pins it); qa measured 93,311
* test: paid file count and periodic floor include the two new periodic cases
* test: ship docs freshness pin checks meaning after A1's wording trim
The snapshot still hashes selected release paths (--select narrows them),
generated outputs and docs; the pin now checks that instead of the
pre-trim sentence.
* E3: reap the recorded Chromium only after the daemon has exited
With the PID now recorded (E3), browse stop reaped Chromium while the
daemon was still shutting down; the daemon read that as a crash, exited 1
and left its state file (chromium-profile-isolation's headless stop test
failed 3/3 locally, passes on base). The CLI waits up to 5 s for the daemon
to exit before reaping a survivor.
* regen: qa and qa-only exploratory sections (PROBE_DIR wording)
* B1: batching counter reads a target declared mid-line; replay corpus
GSTA-23's census 37228573062 failed plan-eng-multi-finding-batching with
reviewCount=0 after 975 s although D1-D10 were asked one per finding,
each with its saved decision-ledger record. The report wrote 'Report
destination requested by the user. Review target (fixed): `PLAN.md` ...'
and the counter read target fields only at a line start, so no brief
inherited the plan identity. A target field may now open any sentence of
its line; a mid-sentence mention or another file still gives no identity.
Floor (3), budget and kind unchanged. Corpus: 9 earlier passing censuses,
the red (now credited at D5), and a derived batching refusal; 975 s noted
in the headroom diagnosis.
* B1: shared-libs corpus labels its git path and covers the supported shape
Every census entry was recorded in CI's eval image (git 2.43), where
gstack-safe-git falls back because --no-lazy-fetch is rejected; each entry
now says so (git_path: fallback). Two synthetic supported-path entries
(HEAD and a history citation in the brief, as git >= 2.44 produces) keep
the 37193478719 pass and the 37195203538 refusal, and a test asserts both
shapes are covered and the actor reads no git-path-specific text.
* v1.91.21.0: move off v1.91.20.0 (claimed by #3031)
* test: settle nav-guard commands before asserting; make two new tests Windows-safe
navigation-guard: Bun's expect(promise).rejects slows each Playwright round-trip
to ~1s while it waits (50 page.evaluate: 43ms plain vs 46.6s inside the matcher),
so the click's 5s timeout expired before the guard saw the link-local request
(CI: 'click: Timeout 5000ms exceeded ... waiting for scheduled navigations').
Settle the command first, then assert on the refusal; a source check keeps it so.
env-host-runtime-assets: PROBE_FILES now matches either path separator.
detector-corpus ship-docsync-late-result: JSON-escape the <ROOT> substitution so a
Windows temp path's backslashes do not break JSON.parse.
* fix: CI run/job ids are not phone numbers; context-recovery fixture gets the full runtime bin
pii.phone.e164 redacted the run id in the published eval report's fetch command
(--run 37235771700), breaking the command it prints. Digit-only spans in a run/job
flag, gh run argument, actions/runs/ or /job/ URL segment, or run_id/job_id key are
now exempt; the same digits elsewhere still report.
context-recovery-artifacts: the fixture's ./bin/ lacked gstack-skill-start and
gstack-context-recovery (the preamble's runtime scripts since v1.71), so the agent
spent its 10 turns hunting for them and hit error_max_turns with no final message
(run 37235771700, 11 turns). Link the whole runtime bin; diagnostic rerun passed
in 6 turns.
* test: replay run 37237194905's late-result capture through the docs authority detector
The only failure was call 20's write to a mistyped shard root (3GanyY for 3GanyU),
which the model disclosed; the detector is correct and the A1 post-snapshot
--out under the fixture home stays permitted. Named red recorded in TODOS.
* test: keep docsync-authority in the Windows profile
The replay test's literal helper path tripped the Windows curator's shebang-spawn
pattern, dropping the whole file from the Windows profile (test-free-shards
invariant). The snapshot --out case is already covered by docsync-command-grammar,
so it is removed here, and the Linux-path replay skips on win32.
* fix: gstack-docs-candidate --help works; docs gate red lines name the denying tool failure
PR run 37239016858 ship-docsync-completion: the parent ran
'gstack-docs-candidate --help' (the helper's usage error points at --help, which
failed). That undeclared command made docsToolFailures non-empty, which denied
the atomic-replacement proof of the child's legitimate native Edit, so the red
line blamed the Edit's temp file. A replay of the capture proves the atomic
replace once --help is declared.
- the helper prints its usage for --help/-h and exits 0
- the fixture interface and command grammar admit the helper's bare --help
- the atomic-proof denial names its check and the tool failures behind it
(deny labels renumbered to their lines)
- replay with negative controls (undeclared command, temp left behind, renamed
elsewhere); diagnostic rerun of ship-docsync-completion passed
* test: retro-base-branch fixture uses main and a shallow report path
PR run 37241493377: the agent wrote retro-output.md one directory above the
requested <tmp>/retro-base/retro-output.md (it dropped the retro-base segment),
so the report check found nothing. The fixture also ran plain git init, which
makes master on CI's git while the prompt says the repo is on main; the agent
logged that mismatch as a learning. Init on main and use the temp dir itself as
the repo. Diagnostic rerun passed (18 turns, 203s).
* test: qa-quick sets a caller probe limit and drains past its session budget
C2 raised Browser Quick's native budget to 180 s. qa-quick is the only gate case
on the native budget, and its wall went 194 s (main periodic, pre-C2) -> 254 s and
274 s (this PR's runs) -> 300 s session timeout (run 37242691913): the agent now
probes every navigation target with a checkpoint, then needs ~80 s to report.
Like qa-only-no-fix, the eval now sets a caller probe limit (30 s), scopes the
fixture, and gives bun's outer timeout the session drain margin instead of racing
the 300 s session. The product's 180 s budget and the session budget are unchanged.
Diagnostic rerun passed in 195 s.
* review/ship: use main's post-expiry smoke sentence; v1.91.24.0
GSTA-23's measurement on the review workflow judge: main's 'Post-expiry smoke
rechecks are not-run.' passed 10/10; the C2 wording passed 6/10 and the
'..., even in 4c.' variant failed in PR run 37248650879. qa-probe-gates pins
main's sentence before step 4c.
* test: record the plan-design corpus test in the test-of-test baseline
#3031's ratchet now counts tests that slice a paid test file's source; the B1
plan-design-review-plan-mode replay corpus reads test/skill-e2e-design.test.ts
like its sibling corpora already listed.
* fix: --case no longer deadlocks importing the running CLI
runCaseDiagnosis loaded runPaidShards with a dynamic import of
scripts/test-paid-shards.ts; when that file is the entry it is still in its
top-level await, so the import never resolved and `--case` hung after its
first line (on main since #3031, found by the per-case measurement runs). The
CLI now passes its runner in; library callers keep the lazy import.
* test: name the in-flight file and the native error when bun dies before its summary (#3037)
* Bun 1.4.2 everywhere CI and setup pin the tested version
Bun 1.4.0 on Windows aborts about 3% of free-suite shards with native
bad-handle errors (main too; #3037); the same head on 1.4.2 had none in 180
shard runs. Every current 1.4.0 pin moves together, as bun-version-drift
requires: setup-bun in every workflow (CSO orchestration included), the eval
image (sha256 from bun-v1.4.2's SHASUMS256.txt, re-hashed locally), GitLab,
the Ubicloud free-suite setup, gstack-bun-version.sh's tested version,
engines.bun and @types/bun, the install hint in generated skills, the Dia and
cookie native-qualification pins, and docs and tests that state the current
pin. Recorded 1.4.0 observations, fixtures, CHANGELOG history and the CSO
images' oven/bun:1.3.10 base stay.
* fix: --case runs a single-case file whole
A session option naming the case (testName: 'office-hours-section-loading')
made caseSelection pick test-name mode, whose filter matched no Bun test, so
every trial would run hollow. A file that registers only this case now runs
whole before any name match is tried.
* fix(office-hours): reviewer returns a hash-bound receipt instead of echoing its verdict
The spec reviewer now Writes its verdict once, seals it with
gstack-office-hours-review seal (validates the saved JSON and prints
OFFICE_HOURS_VERDICT round=N sha256=<hash> path=<verdict>), and returns
only that line. check --receipt recomputes the hash and fails closed on a
missing, malformed, stale-round, wrong-path or mismatched receipt. The
saved file stays the sole findings inventory; validators bind the receipt
to the saved bytes and the judge reads those bytes.
* fix(office-hours): only blocking findings send a design back for another review round
Review findings carry severity blocking|minor (verdict schema v2). PASS when
no blocking findings remain; minor findings are recorded in Reviewer
Concerns and the Spec Review table, never a reason for another round.
CONVERGENCE needs a persisting blocking prior. A persisting or unverified
blocking prior cannot be relabeled minor. The 3-round cap is unchanged.
* fix(office-hours): rounds 2 and 3 are delta re-reviews of the captured design diff
prepare saves each reviewed design as round-N.design.md and gives later
reviewers the exact line diff since the previous round. A new later-round
blocking finding must cite (changed_text) an excerpt of a changed line;
seal, check and the validators verify it against the snapshots and fail
closed when a citation or snapshot is missing. Other new observations are
minor. Severity, anti-downgrade and CONVERGENCE rules are unchanged.
* test(office-hours): preservation judge accepts COMPLETED with recorded minor findings
* fix(office-hours): parent fixes only blocking findings; callers may set --max-rounds
Between rounds the parent edits for blocking findings only; minor findings
stay recorded. gstack-office-hours-review takes --max-rounds 1|2|3 (default
3) on every command; reaching it stops at MAX_ITERATIONS. The marathon
fixture sets 2 rounds so round 1 (full) and round 2 (delta) run live.
* docs(changelog): office-hours review loop changes in v1.91.28.0
* fix(cso): helper JSON keeps run URLs only in the validated workflow slot
The shared redactor now treats GitHub Actions run ids as CI metadata
(c245d1bc2), so main's #3041 invariant that the same run digits stay
redacted outside qualification.workflow held only through the phone
false positive. Make it explicit in the CSO sanitizer.
* test(plan-ceo): split-overflow progress detector accepts the skill's candidate wording
Collection never ended when the model wrote 'E1 Slack:' / 'E1-SLACK:' or
labels like 'Include in this quarter' / 'Defer with flip trigger', so the
session ran the whole review (930-1464 s) and failed on its extra findings
or the case deadline (6 of 21 runs). The candidate check now accepts a
platform-bound E-id and the action is the bucket's leading verb, as the
skill names them (Include/Defer/Cut/Hold). The semantic judge, call floor
and include/defer/cut validation are unchanged. Replays the captured CI
37374526437, t2, t9 and t15 menus with negative controls.
* test(plan-ceo): split-overflow candidate identity is the one E1-E5 token
The skill fixes no header or question wording, and shape-matching kept
missing new forms (header 'D1.1 Slack' with 'SCOPE-E1:', 'D1.1 E1 Slack',
'E1 Slack DM bot ...:', a misspelled 'Mattermst'). Identity is now exactly
one E1-E5 token across the header and the question's first line, with no
other candidate's platform named. Options rules, judge, call floor and
include/defer/cut validation are unchanged. Replays all 31 measured runs;
the quoted-row controls now quote a second ledger id.
* v1.91.30.0: move past #3044's claimed 1.91.29.0
* test: register the split-overflow wording replay as a free fixture
* fix(skills): resolve judge-cited ambiguities in /qa and /plan-eng-review
- tasks JSONL keeps the raw branch as GIT_BRANCH instead of overwriting
gstack-slug's sanitized BRANCH used for artifact names
- the Codex outside-voice block runs for ready or unverified, matching
its routing rule
- plan-eng startup names the preamble's own setup prompts; the
cross-project question waits for Step 0
- /qa 8c: a fix that applies but leaves the finding reproducing gets one
revised fix, else it is reverted; browser verification names its before
screenshot; the exploratory loop drops its duplicate 3-step summary
* fix(plan-eng): keep the startup steps in their pinned order
* fix(plan-eng): explicit spawned sessions follow the spawned rule at the scope gate; one announcement rule
A missing tool still sends the prose menu whatever the session type, but a
session the caller or host explicitly marks spawned selects the menu's
Recommendation without prose or BLOCKED. The pre-load announcement
sentence now states Step 0's single check.
* eval policy v3: judge panels gate on the per-dimension median of 3 samples
A judge dimension now passes when at least 2 of its 3 samples meet the
unchanged threshold (judgePanelMedian); any other sample count or a
non-numeric sample fails closed. Thresholds, sample count, judge model and
prompts are unchanged; panel logs show every sample and the mean, and name
the median as the gate. Applies to the skill-llm-eval panels, the
workflow-judge cache, the auq-matrix substance panel and the calibration
replicas. EVAL_POLICY 2 -> 3 and HARNESS_VERSION 1 -> 2 (verdicts change),
so every case starts a new pass-rate series. Replays the captured panels
from jobs 112032744416 and 112049856586 as replayed evidence.
69 KiB
Contributing to gstack
Thanks for wanting to make gstack better. Whether you're fixing a typo in a skill prompt or building an entirely new workflow, this guide will get you up and running fast.
Quick start
gstack skills are Markdown files that Claude Code discovers from a skills/ directory. Normally they live at ~/.claude/skills/gstack/ (your global install). But when you're developing gstack itself, you want Claude Code to use the skills in your working tree — so edits take effect instantly without copying or deploying anything.
That's what dev mode does. It symlinks your repo into the local .claude/skills/ directory so Claude Code reads skills straight from your checkout.
git clone https://github.com/garrytan/gstack.git && cd gstack
bun install # install dependencies
bin/dev-setup # activate dev mode
Full clone vs shallow. The README's user-facing install uses
--depth 1for speed. As a contributor, use a full clone (no--depthflag) — you'll need history forgit log,git blame,git bisect, and reviewing PRs against earlier versions. If you already have a--depth 1clone from following the README, promote it to a full clone withgit fetch --unshallow.
First free check (no API key, no browser)
bun install --frozen-lockfile
bun run typecheck # expect no output and exit 0 (about a second)
bun run typecheck:test # expect "test typecheck ratchet: N known diagnostics, none new."
typecheck covers product code (browse/src, lib, scripts, bin, hosts, and the other
entries in tsconfig.json) and must stay at zero errors. typecheck:test holds test code to the
committed scripts/typecheck-test-baseline.json: a new or repeated diagnostic fails and names
the file, TS code and message; fixing diagnostics also fails until you lock the smaller allowance
in with bun run typecheck:test --write-baseline. Editing lib/cso/*.ts? Run
bun run format:cso before committing; CI runs format:cso:check. All three run in the required
free-tests check.
Now edit any SKILL.md, invoke it in Claude Code (e.g. /review), and see your changes live. When you're done developing:
bin/dev-teardown # deactivate — back to your global install
Operational self-improvement
gstack automatically learns from failures. At the end of every skill session, the agent
reflects on what went wrong (CLI errors, wrong approaches, project quirks) and logs
operational learnings to ~/.gstack/projects/{slug}/learnings.jsonl. Future sessions
surface these learnings automatically, so gstack gets smarter on your codebase over time.
No setup needed. Learnings are logged automatically. View them with /learn.
The contributor workflow
- Use gstack normally — operational learnings are captured automatically
- Check your learnings:
/learnorls ~/.gstack/projects/*/learnings.jsonl - Fork and clone gstack (if you haven't already)
- Symlink your fork into the project where you hit the bug:
Setup creates per-skill directories with SKILL.md symlinks inside (
# In your core project (the one where gstack annoyed you) ln -sfn /path/to/your/gstack-fork .claude/skills/gstack cd .claude/skills/gstack && bun install && bun run build && ./setupqa/SKILL.md -> gstack/qa/SKILL.md), links each skill's runtime assets alongside (sections/, templates, checklists — everything except SKILL.md, tests, build output, and.tmplsources), and asks your prefix preference. Pass--no-prefixto skip the prompt and use short names. - Fix the issue — your changes are live immediately in this project
- Test by actually using gstack — do the thing that annoyed you, verify it's fixed
- Open a PR from your fork
This is the best way to contribute: fix gstack while doing your real work, in the project where you actually felt the pain.
What CI does on a fork PR. GitHub never gives a fork PR this repository's
secrets, so CI runs everything that needs none: the required free-tests check
(the Linux free suite, typecheck, the macOS and Windows gates), Windows Free
Tests, Skill Docs Freshness, Workflow Lint, Version Gate, Quality gate, the
make-pdf gate, and any path-triggered gates your change touches. E2E Evals
still builds the CI image from your Dockerfile.ci without publishing it, and
skips its paid eval jobs, which need provider API keys. That skip is expected
and does not block your PR. It is also not a pass: a maintainer runs the paid
evals from a branch in this repository before merging. A first-time
contributor's runs wait for a maintainer to approve them.
Session awareness
When you have 3+ gstack sessions open simultaneously, every question tells you which project, which branch, and what's happening. No more staring at a question thinking "wait, which window is this?" The format is consistent across all skills.
Working on gstack inside the gstack repo
When you're editing gstack skills and want to test them by actually using gstack
in the same repo, bin/dev-setup wires this up. It creates .claude/skills/
symlinks (gitignored) pointing back to your working tree, so Claude Code uses
your local edits instead of the global install.
gstack/ <- your working tree
├── .claude/skills/ <- created by dev-setup (gitignored)
│ ├── gstack -> ../../ <- symlink back to repo root
│ ├── review/ <- real directory (short name, default)
│ │ └── SKILL.md -> gstack/review/SKILL.md
│ ├── ship/ <- or gstack-review/, gstack-ship/ if --prefix
│ │ └── SKILL.md -> gstack/ship/SKILL.md
│ └── ... <- one directory per skill
├── review/
│ └── SKILL.md <- edit this, test with /review
├── ship/
│ └── SKILL.md
├── browse/ <- /browse skill + gstack's own browser engine (the fallback)
│ ├── src/ <- TypeScript source
│ └── dist/ <- compiled binary (gitignored)
├── lib/
│ ├── aside-render.ts <- local-HTML rendering: Aside first, browse engine fallback
│ └── design-catalog.ts <- typed design anti-pattern catalog; review/design-checklist.md is generated from it
├── bin/
│ └── gstack-render.ts <- the CLI skills call to render a local HTML file
└── ...
Setup creates real directories (not symlinks) at the top level with a SKILL.md
symlink inside, plus links to each skill's runtime assets (sections/, templates,
checklists). Alias skills (_gstack-command, connect-chrome) install as
rewritten copies, never symlinks — editing a symlinked alias would corrupt the
generated source. This ensures Claude discovers them as top-level skills, not nested
under gstack/. Names depend on your prefix setting (~/.gstack/config.yaml).
Short names (/review, /ship) are the default. Run ./setup --prefix if you
prefer namespaced names (/gstack-review, /gstack-ship).
Day-to-day workflow
# 1. Enter dev mode
bin/dev-setup
# 2. Edit a skill template (SKILL.md files are generated — edit the .tmpl)
vim review/SKILL.md.tmpl
bun run gen:skill-docs # or: bun run dev:skill (watch mode, auto-regen on change)
# 3. Test it in Claude Code — changes are live
# > /review
# 4. Editing browse source? Rebuild the binary
bun run build
# 5. Done for the day? Tear down
bin/dev-teardown
Brain-aware blocks in a dev workspace (gbrain installed)
If gbrain is installed and usable (bin/gstack-gbrain-detect --is-ok exits 0),
bin/dev-setup keeps your tracked SKILL.md files canonical and renders the
brain-aware variant (the GBRAIN_CONTEXT_LOAD / GBRAIN_SAVE_RESULTS blocks)
into .claude/gstack-rendered/ (gitignored, per-workspace). It then repoints the
workspace's SKILL.md symlinks at that render, so your Claude sessions get the
full gbrain experience while git status stays clean. Under the hood, dev-setup
passes GSTACK_SKIP_GBRAIN_REGEN=1 inline to the nested ./setup (so it never
dirties tracked source) and runs gen:skill-docs:user --out-dir .claude/gstack-rendered,
which rewrites only the section-base paths to point at the render. bin/dev-teardown
removes the render. To make the blocks live across your other projects' Claude
sessions, run gstack-config gbrain-refresh, which renders them to a user render
dir (${GSTACK_USER_RENDER_DIR:-~/.gstack/render/claude}, swapped in only on a
successful render) and repoints the installed skills at it via gstack-relink —
the global install checkout stays git-clean, and the refresh is guarded so it
never touches a symlinked or non-gstack directory.
Testing & evals
Codex evals and the GPT benchmark adapter default to gpt-6-astra:
explicit model > GSTACK_CODEX_MODEL > default. Claude capture and judge
defaults are claude-fable-5-1, resolved through lib/eval-model.ts:
- Claude session, PTY, and Agent SDK eval runners and the Claude benchmark adapter: explicit model >
EVALS_MODEL>GSTACK_EVAL_MODEL_CAPTURE>GSTACK_EVAL_MODEL> default. - Shared judge calls (including benchmark quality scoring): explicit model >
GSTACK_EVAL_MODEL_JUDGE>GSTACK_EVAL_MODEL> default.EVALS_MODELapplies to capture runners, not judges.
Warmup stays on claude-haiku-4-5; distill stays on
claude-haiku-4-5-20251001. Explicit test and historical benchmark model
selections still win. Known frontier defaults are maintained in releases;
there is no automatic model discovery. Paid-run costs shown below are
historical estimates from before this default change, not measurements of
the new defaults.
Which command do I run?
| I want to… | Command | Cost / time | Needs |
|---|---|---|---|
| Check an ordinary edit quickly | bun run test:quick |
Free, about a minute | Bun 1.4.2 |
| Run one free test file while repairing | bun test <file> |
Free, seconds | Never bare bun test for the suite |
| Run full free acceptance before publishing | bun run test |
Free, a few minutes | Bun 1.4.2 |
| Run the full free suite from a small machine | bun run test:ubicloud |
Free suite on a billed 16-vCPU VM, about 5 minutes | UBICLOUD_API_KEY |
| Run the curated Windows-safe subset | bun run test:windows (CI: six windows-latest jobs) |
Free | Windows, Git Bash |
| Refresh the Windows duration seed | gh workflow run windows-free-tests.yml --ref <branch> -f record_durations=true, then commit the free-test-durations-windows artifact |
Free CI runners | Pushed branch, gh with workflow rights |
| Run a native Windows or Dia qualification campaign | gh workflow run native-qualification.yml --ref <branch> -f mode=<mode> (modes) |
Free CI runners | Pushed branch, gh with workflow rights |
| Preview which paid cases my diff selects | bun run eval:select (PR profile; --profile full for the plain touchfile selection) |
Free | — |
| Preview the CI paid slice plan | bun run scripts/test-paid-shards.ts --tier periodic --list --slice-budget 420 --jobs 2 (diff-selected; EVALS_ALL=1 lists everything) |
Free | — |
| Run paid coverage for my change (agents: detached) | bun run eval:bg:pr (foreground: bun run test:pr) |
API spend for the selected cases only; about 10 minutes when dispatched to CI | Dispatch: a clean, pushed HEAD and gh. Local fallback: ANTHROPIC_API_KEY, Claude Code CLI, a plain terminal |
| Run the full gate + periodic censuses before a release | bun run eval:bg:release (foreground: bun run test:release) |
The largest API spend; local runs are capped at 4 hours | Same as above |
| Run one paid tier | bun run test:gate:sharded / bun run test:periodic:sharded (detached: eval:bg:gate / eval:bg:periodic) |
API spend for that tier | Same as above |
| Run one paid case as its CI panel | bun run scripts/test-paid-shards.ts --tier <tier> --case <case-id> --trials 3 |
API spend for that case | Same as above |
| Validate gate cases on a branch in CI | gh workflow run evals.yml --ref <branch> -f evals_all=true |
CI runners + API spend | Pushed branch, gh with workflow rights |
| Validate periodic cases on a branch in CI | gh workflow run evals-periodic.yml --ref <branch> (periodic lane only) |
CI runners + API spend | Pushed branch, gh with workflow rights |
| Validate periodic cases plus the weekly gate census on a branch | gh workflow run evals-periodic.yml --ref <branch> -f include_gate_census=true |
CI runners + API spend | Pushed branch, gh with workflow rights |
| Run the opt-in ML, gitleaks and Swift checks | gh workflow run platform-qualification.yml --ref <branch> |
Free CI runners | Pushed branch, gh with workflow rights |
| Look at past local eval runs | bun run eval:list / eval:compare / eval:summary |
Free | Local eval history |
| See a case's pass rate across recent weekly runs | bun run eval:pass-rates --case <case-id> |
Free | gh with repo read access |
| See the audit success metrics and weekly health | bun run test:health [--since-days 7] [--json] [--enforce] |
Free; 5–20 minutes of gh reads |
gh with repo read access |
Old command names are listed under Retired commands.
Setup
Development and tests require Bun 1.4.2 or newer; CI pins and tests 1.4.2. Earlier Linux versions can close unrelated live file descriptors during subprocess garbage collection, causing intermittent browser and HTTP fixture failures (upstream diagnosis).
# 1. Copy .env.example and add your API key
cp .env.example .env
# Edit .env → set ANTHROPIC_API_KEY=sk-ant-...
# 2. Install deps (if you haven't already)
bun install
Bun auto-loads .env — no extra config. Conductor workspaces inherit .env from the main worktree automatically (see "Conductor workspaces" below).
Test tiers
Functional QA changes need native fixture proof as well as prompt checks. Add declared CLI or loopback API/worker contracts in isolated temporary repositories, outside this checkout. Exercise success and adverse paths, durable effects, and setup failure. Report-only evaluations must leave mutation-capable tools available and independently detect forbidden writes, including an edit later restored; a clean final diff is not enough. Validate the observer with deliberately bad controls before a paid run.
For exploratory regressions, retain the actual pre-repair failure, post-repair pass, original probe and adjacent happy path. Automatic caller tests must enter through review/ship, not tell the agent to run the component being tested. Documentation tests must prove the real child completed and the parent used its result before publication; the existing dispatch-only test is narrower evidence. Register new cases and all consumed section/resolver inputs in touchfiles, tiers and the PR profile so they run. Share sanitized reproduction commands and fixture evidence when reporting a problem, never credentials, private payloads or an entire unreviewed agent transcript.
| Tier | Runs through | What it tests |
|---|---|---|
| 1 — Static | bun run test (free) |
Command validation, snapshot flags, Aside contract pins, render-wrapper option mapping, SKILL.md correctness, TODOS-format.md refs, observability unit tests |
| 2 — E2E | The sharded paid runner (bun run eval:bg:pr, eval:bg:release) |
Full skill execution via claude -p, PTY and Agent SDK sessions |
| 3 — LLM eval | The same runner; test/skill-llm-eval*.test.ts |
LLM-as-judge scoring of generated SKILL.md docs |
Pick commands from Which command do I run?.
The PR paid gate uses an explicit short behavioral profile. Every selected quality
judge remains included; the manifest lists deferred behaviors separately from
passes. Unknown source dependencies restore the full gate; the job summary names
each file that caused it and its fix (PR paid lane fallback).
A new prompt without
registered coverage fails planning. Known broad behaviors remain visibly deferred
when their prompts change; they do not silently gain PR-pass credit. The full
gate and periodic censuses run fresh weekly and on manual
dispatch of evals-periodic.yml; bun run eval:bg:release runs both.
Some broad behavioral failures will therefore be found after the PR gate.
Blocking paid lanes (the PR gate and the weekly periodic + gate census) aim for
a median of about 10 minutes including setup. The planner packs recorded wall
times (scripts/paid-test-durations.json, per tier) into as many 7-minute
(420-second) runners as the work needs, one file or a tightly packed group each;
files whose cases are short but whose total is long run one case per runner.
Matrix size and each runner's job timeout come from that plan, so a hung runner
fails within its own ceiling. Preview it for free with
bun run scripts/test-paid-shards.ts --tier periodic --list --slice-budget 420 --jobs 2.
Complete start-to-finish flows belong to the marathon tier
(describeE2ETier('marathon')), which runs only in the non-blocking
evals-marathon.yml lane (weekly and on dispatch) and never gates a merge.
Verdicts: paid evals never retry. Each case's kind in E2E_KINDS
(test/helpers/touchfiles-data.ts) fixes its trials before the run, from the
constants in EVAL_POLICY (test/helpers/periodic-exclude-data.ts):
rule(the default): one trial; any failed assertion fails the case. Use it when nothing stochastic decides the verdict, or when the verdict checks a contract the product must meet every run (no writes in plan mode, a question before a decision, a skill-mandated step, no leaked secret).behavior: a panel of 3 independent trials run as parallel case shards, PASS at 2 or more with no contract violation (expectContract()). Use it only when a live model choice decides the verdict and an occasional deviation is acceptable product behavior; the one-line reason goes inBEHAVIOR_WHY.judge: an LLM judge scoring a fixed input; exactly 3 samples of the same prompt, each dimension gated on its median, at least 2 of 3 samples, against the unchanged threshold (booleans on a majority; the mean is reported only). An erroring sample fails the panel and is never resampled.
A timed-out, crashed or infrastructure-failed trial counts as a failed trial and
is reported with its class; a missing trial makes the case INCOMPLETE, which
fails the lane. A 2-of-3 pass is reported as PASS 2/3 with the failed trial's
cause, never as a clean pass. Case budgets and thresholds never change with
this policy. Quarantine (CASE_QUARANTINE) and history are described in
docs/TESTING_INTERNALS.md; bun run eval:pass-rates --case <id> shows a
case's per-trial pass rate with its Wilson interval.
A census went red? Follow docs/evals/census-red.md:
read the red line, inspect its evidence with bun run eval:pass-rates --run <id>,
check --reds and --headroom, repair with a free regression test, and only
then spend one paid run with the line's after a repair: command. A red census
on main is reported on the weekly tracking issue; a census dispatched on a
branch writes the same report to its run summary and census-report artifact.
CI enables verified first-attempt reuse for 16 workflow quality judges for
24 hours within the same PR. The cookie workflow's custom input and the other 11
quality cases stay fresh. PR-profile E2E shards that run once (no retry, so the
pass is provably a first attempt) reuse a pass from the same PR when every
consumed input is byte-identical: the test's import closure, every tracked file
its registered cases' touchfiles and the global touchfiles match, the runner and
workflow, the child's EVALS_/GSTACK_/CLAUDE_/ANTHROPIC_ environment (secret
presence only), the CI image and Claude CLI version (scripts/e2e-shard-reuse.ts).
A computed case registration or a touchfile pattern matching nothing keeps the
shard fresh. The weekly census, marathon and release lanes never reuse. Local runs stay fresh unless
the complete scoped cache and runtime configuration is supplied. The key includes complete prompt bytes, generated inputs,
fixtures, runner/rubric code, installed dependencies, model settings and runtime.
The current assertions validate a reused score again. Records retain the original
run, revision and time; reuse never renews that time. Failed, retried, partial or
unknown-input results cannot be reused.
EVALS_FRESH=1 bypasses reuse; periodic and release runs always bypass it.
Timing goals are under one minute for edit feedback, 3–5 minutes for typical PR
checks, and 60–90 seconds for complete free test execution across isolated CI
machines. They are targets, not timeout reductions or guarantees. The complete
local suite uses available CPU affinity, up to 16 workers on Linux and six on
macOS and Windows; use test:quick for the shorter edit loop. On a small dev
box, container, or cloud sandbox, bun run test:ubicloud runs the complete suite
on a fresh 16-vCPU Ubicloud VM with the CI lane's environment instead (about
four and a half minutes end to end, including VM boot and setup). The
historical six-worker result below and the
four-CPU portfolio comparison
are machine-specific measurements. CI setup, build and queue time are reported
separately. Refresh measurements with bun run test:ubicloud --record-durations
(a laptop recording is not an acceptable seed; see
free suite duration seed);
before publication, classify new regressions for quick feedback using that seed
and the existing QUICK_CORE list. Do not classify unknown files as fast or use
quick results as release acceptance. The runner retains full logs in
.context/free-test-logs/ and explains the next repair step on failure; see
free-runner recovery for details. For full acceptance,
the required free CI lane packs the complete inventory across isolated runners,
then checks every shard's receipt before reporting success. Local worker counts
remain bounded to avoid browser/process contention.
Historical measurements from 2026-09-21:
| Run | Coverage | Elapsed |
|---|---|---|
| Local edit feedback | 861 of 993 free test files | 38 seconds |
| Local complete free suite | All 993 files, six workers | 4m 35s |
| Complete Linux CI | All 993 files, 20 isolated runners | 1m 40s across test steps; 3m 7s including setup and aggregation |
After the 2026-09-29 test audit (evidence):
| Run | Coverage | Elapsed |
|---|---|---|
Complete free suite, bun run test:ubicloud (standard-16) |
All 857 files, 20,302 passing tests | 136 seconds on the VM; 1,738 seconds of recorded serial test time |
The Linux CI run
on 25030d68 included one recorded successful retry. Its slowest test step was 77 seconds;
staggered starts made the complete test span longer. Typical PR paid-gate timing
still needs measurement on a small change. Explicitly exempt free-only runner
changes do not select paid work; mapped dependencies take precedence, and unknown
dependencies retain the broad fallback. See the
coverage boundaries.
When a paid eval fails, fix the product or the harness and add the captured case as one row in
the detector's owner test (the detector → owner table is in
TEST_PORTFOLIO.md); never add a new per-incident file.
A row is one describe block or table entry next to the others, for example a new
describe('eng-cache-writes-at', …) in test/eng-first-review.test.ts that loads its fixture and asserts
engFirstReviewAUQ on the captured call. Run bun test <owner-test>, then
bun test test/test-of-test-ratchet.test.ts: the ratchet fails on any new test file that imports only
test/ code, or that reads a paid test file's source and slices it, and names the owner test to use instead.
Tests on templates and generated SKILL.md use test/helpers/prompt-structure.ts (between,
expectTokens, expectAbsent, expectOrdered, expectMentions): machine-read tokens and step order
exactly, safety rules as case-insensitive keyword co-occurrence in one sentence. Don't pin English
sentences; see the test value bar.
Follow Validation discipline in AGENTS.md: reproduce known failures with focused checks, verify adjacent source and generation contracts, then run the affected and remaining required selected evaluations. Finish review fixes and release preparation before running the full free suite once on the frozen code. During repairs, focused checks replace a full-suite run before every commit.
Tier 1: Static validation (free)
Runs with bun run test, which routes through scripts/test-free-shards.ts: N
concurrent shard processes under a strict output contract — a shard that exits
without bun's own terminal summary line, or a crashed worker, fails the run, so
silent truncation can never report green. Pass --verbose to forward the full
child stream; --wall-timeout <secs> overrides the per-shard kill deadline.
GSTACK_FREE_JOBS=<n> overrides the shard count (digits only, loud on garbage),
and GSTACK_FREE_RETRY_FLAKY=1 opts into one serial retry pass for
syscall-supervised sandboxes (off by default locally — dev boxes should see
flakes; the required CI free lane turns it on and uploads every flaky pass
in a flake-ledger-<shard> JSONL artifact; the weekly test-health run fails when
a file flakes in more than 5% of main runs, see
flake ledger).
Working in a cloud sandbox? Run scripts/sandbox-doctor.sh once per boot to
make the suite run green (details in
docs/TESTING_INTERNALS.md), or skip the sandbox's
limits entirely with bun run test:ubicloud.
Don't type bare bun test for the suite: it walks the whole repo, loads paid
eval files, and misses the strict classifier. No API keys needed.
- Skill parser tests (
test/skill-parser.test.ts) — Extracts every$Bcommand from SKILL.md bash code blocks and validates against the command registry inbrowse/src/commands.ts. Catches typos, removed commands, and invalid snapshot flags. - Skill validation tests (
test/skill-validation.test.ts) — Validates that SKILL.md files reference only real commands and flags, and that command descriptions meet quality thresholds. Also cross-checks the skill inventory in AGENTS.md and docs/skills.md. - Aside driver contract (
test/aside-driver.test.ts) — Browser behaviour in skills is written againstscripts/resolvers/aside.ts({{ASIDE_SETUP}}) and verified live against the Aside CLI on a Mac. CI cannot run Aside, so the Aside E2E tests self-skip whereasideis not installed; the static pins (detection, fallback hand-off, consent, credential, one-flow-per-script, sentinel) are what CI proves. - Aside render wrapper (
test/aside-render.test.ts) — Pins the option mapping and generated script oflib/aside-render.tseverywhere, and drives both engines hermetically with fakeaside/browseexecutables (probe classification, the stdout contract, loopback-server policy, failure paths, the timeout kill, engine choice and the mid-run fallback); the live render (PDF + screenshot through a real Aside) runs only where Aside is open and self-skips elsewhere. make-pdf's render gates (make-pdf/test/e2e/*-gate.test.ts) andtest/skill-e2e-diagram.test.tsare engine-agnostic: they run through whichever engine resolves (browserAvailable()— Aside, or the browse binarybun run build:gatescompiles, which is what Linux CI does) and skip only when neither exists. - Render CLI (
test/gstack-render-cli.test.ts) — Pinsbin/gstack-render.tsagainst a fake daemon (GSTACK_SKIP_ASIDE=1+GSTACK_BROWSE_BIN): argv guards exit 1 with the usage line,--helpexits 0,ENGINE=first thenOK <path>then fencedEVAL/PAGE_ERRORS,--serve-rootcontainment, the no-browser first line, and prompt exit after a successful render.make-pdf/test/cli-exit-codes.test.tsandmake-pdf/test/setup-smoke.test.tspin thepdfbinary's error-to-exit-code map and$P setup's engine report. - Generator tests (
test/gen-skill-docs.test.ts) — Tests the template system: verifies placeholders resolve correctly, output includes value hints for flags (e.g.-d <N>not just-d), enriched descriptions for key commands (e.g.islists valid states,presslists key examples). - Design detector, catalog, and DESIGN.md (
test/gstack-design-detect.test.ts,test/design-detect-contract.test.ts,test/design-catalog.test.ts,test/design-checklist-sync.test.ts,test/design-md.test.ts,test/frontend-scope.test.ts,test/impeccable-fixtures.test.ts) — Drivebin/gstack-design-detect.tsthrough the fake engine intest/fixtures/fake-impeccable.ts(probe order, the never-execute-a-repository-file rule, the--changedtarget allow-list,design_detector: off, analytics lines, output sanitizing), pin the catalog invariants and the generatedreview/design-checklist.md, round-trip the open DESIGN.md reader/writer, and check the real engine captures (test/fixtures/impeccable-*.json, engine 0.1.3) against the contract.test/dom-dump-hygiene.test.tsrunslib/dom-dump.jsin a real Chromium page through the built browse binary; it self-skips without the binary and is opt-in outside CI (GSTACK_DOM_DUMP_HYGIENE=1). - Tier-alignment invariant (
test/e2e-tier-alignment.test.ts) — For every self-gatedtest/skill-e2e-*.test.tsnamed in a touchfiles dep list, the file'sEVALS_TIERself-gate must match its declared tier inE2E_TIERS. Kills the "inert demotion" class where a test is re-tiered intouchfiles.tsbut the file still gates on the old tier and keeps running in the wrong lane. Unmapped or mixed-tier files are reported, never silently skipped. - Catalog budget (
test/catalog-budget.test.ts) — Caps the aggregate discovery surface: the sum of every skill's frontmattername+description(what every host loads at discovery, every session) must stay under 1,171 token-equivalents, with a 260-byte per-skill cap. Counting goes through the shared census intest/helpers/skill-census.ts(physical files vs authored skills vs registry entries — three deliberately different counts). Adding a skill? The failure message carries the re-measure + ratchet protocol. - Context-budget ratchet (
test/context-budget-ratchet.test.ts) — CI ceilings on the two token ledgers the catalog budget doesn't cover: the always-on full-frontmatter aggregate and each skill's per-invocation eager tokens (SKILL.md + forced-read references), graded againsttest/fixtures/context-budget.jsonvialib/context-bill.ts. New skills fail until they have a ceiling; ceilings for removed skills must be pruned. Legitimate growth or a landed reduction: re-runbun test/helpers/capture-context-budget.tsand commit the refreshed fixture in the same commit, so the change is a visible decision in the diff. - Dependency security regressions (
test/dependency-security.test.ts) — Runbun test test/dependency-security.test.tsto check the resolvedsharpandadm-zipversion floors, load Sharp, verify ordinary ZIP extraction, and reject extraction through destination-file and destination-directory symlinks. The symlink cases skip Windows. These checks complement the OSV scan; they do not change its existing exceptions.
Tier 2: E2E via claude -p
Spawns claude -p as a subprocess with --output-format stream-json --verbose, streams NDJSON for real-time progress, and scans for browse errors. This is the closest thing to "does this skill actually work end-to-end?"
# Must run from a plain terminal — can't nest inside Claude Code or Conductor
EVALS_RUN_ID="local-$(bun -e 'console.log(crypto.randomUUID())')" EVALS=1 bun test test/skill-e2e-*.test.ts
- Gated by
EVALS=1env var (prevents accidental expensive runs) - Auto-skips if running inside Claude Code (
claude -pcan't nest) - API connectivity pre-check — fails fast on ConnectionRefused before burning budget
- Real-time progress to stderr:
[Ns] turn T tool #C: Name(...) - Saves full NDJSON transcripts and failure JSON for debugging
- Tests live in
test/skill-e2e-*.test.ts(split by category), runner logic intest/helpers/session-runner.ts
Supply a fresh EVALS_RUN_ID for each invocation, including detached runs below.
Functional QA and documentation cases refuse acceptance without it. CI supplies
its own run/attempt/job/slice identity; see Testing internals
for the retained native-capture artifacts.
Hermetic by default. Every E2E runner (claude -p, the real-PTY plan-mode
runner, the Agent SDK runner, plus the codex and gemini runners) spawns its child
through test/helpers/hermetic-env.ts: an allowlist-scrubbed environment, a fresh
seeded CLAUDE_CONFIG_DIR, a temp GSTACK_HOME, and --strict-mcp-config. Your
operator ~/.claude config, MCP servers (gbrain, Conductor), skills, ~/.gstack
decision logs, and CONDUCTOR_* env never leak into the child. The GITHUB_
and EVALS_ prefix rules preserve CI metadata but reject credential-shaped
names such as GITHUB_TOKEN, GITHUB_PERSONAL_ACCESS_TOKEN, and
GITHUB_APP_PRIVATE_KEY. The screen reads every underscore-separated segment, so a trailing qualifier does not carry a name past it (GITHUB_APP_PRIVATE_KEY_BASE64, GITHUB_TOKEN_1), while a segment that merely contains a credential word stays metadata (GITHUB_PATH, GITHUB_TOKENIZER). Named provider auth, runner extraAllow entries, and
per-test overrides are deliberate exceptions; a name-based rule cannot identify
a secret assigned to an arbitrary metadata name. This keeps local eval signal
aligned with CI instead of disagreeing for reasons unrelated to the code under
test. The hermetic CLAUDE_CONFIG_DIR seeds no skills by default; a PTY test
that types a /skill slash command passes seedSkills: true to the PTY runner,
which swaps in hermeticSkillsConfigDir() — a seeded skill registry that
symlinks the LIVE working tree's SKILL.md files (by design: the skills are the
subject under test, so a snapshot would measure stale copies). Set
EVALS_HERMETIC=0 to debug against your real operator state (this also
drops --strict-mcp-config). The wiring is pinned by test/hermetic-wiring.test.ts
(a free static tripwire), two gate-tier isolation canaries in
test/skill-e2e-hermetic-canary.test.ts, and the skill-seeding tripwires in
test/hermetic-skills-seeding.test.ts / test/pty-skill-seeding-wiring.test.ts.
E2E observability
When E2E tests run, they produce machine-readable artifacts in ~/.gstack-dev/:
| Artifact | Path | Purpose |
|---|---|---|
| Heartbeat | e2e-live.json |
Current test status (updated per tool call) |
| Partial results | evals/_partial-e2e.json |
Completed tests (survives kills) |
| Progress log | e2e-runs/{runId}/progress.log |
Append-only text log |
| NDJSON transcripts | e2e-runs/{runId}/{test}.ndjson |
Raw claude -p output per test |
| Failure JSON | e2e-runs/{runId}/{test}-failure.json |
Diagnostic data on failure |
Live progress: a detached run's log under ~/.gstack-dev/eval-runs/ streams each shard's result as it lands; for a CI run use gh run watch <run-id>. Per-test progress is in each shard's progress.log.
Eval history tools:
bun run eval:list # list all eval runs (turns, duration, cost per run)
bun run eval:compare # compare two runs — shows per-test deltas + Takeaway commentary
bun run eval:summary # aggregate stats + per-test efficiency averages across runs
bun run eval:pass-rates # per-case trial pass rates + Wilson intervals from recent weekly runs (--case, --runs, --dir, --backfill, --json, --gate)
bun run eval:pass-rates --reds # verdict reds per census by failure class and cause, all-green probability
bun run eval:pass-rates --headroom # slowest session per case vs its armed budget (alarm above 85% in --gate)
bun run eval:pass-rates --run <id> # one census's reds with their values and fetched transcript evidence
Detached runs for agents and long suites. When an agent (or you, for a run
you don't want to babysit) launches a long eval, use the eval:bg:* scripts
(scripts/eval-bg.ts). Each picks a backend and prints it:
- dispatch (a clean HEAD pushed to garrytan/gstack, with
gh): runs the lane in CI on that exact revision and follows the run from a local log; - local (anything else, or
--local): runs the sharded paid runner on this machine, capped at ceil(1.5 × planned serial seconds /EVALS_JOBS) + 20 minutes, at most 4 hours (--timeout SECSoverrides).
Both run under bin/gstack-detach: a fresh session that escapes a
turn-boundary SIGTERM, a caffeinate wrapper that blocks idle-sleep, a machine-wide
gstack-evals lock so concurrent worktrees serialize instead of saturating the
model API, a run-scoped log under ~/.gstack-dev/eval-runs/, and a guaranteed
### gstack-detach EXIT=<code> ### sentinel so a poller never mistakes silence
for success. bun run scripts/eval-bg.ts --help lists the flags and
bun run scripts/eval-bg.ts status <log-or-run-id> reconnects to a run.
bun run eval:bg:pr # changed coverage (CI: evals.yml, evals_all=false)
bun run eval:bg:release # fresh full gate + periodic (CI: both workflows)
bun run eval:bg:gate # gate tier (CI: evals.yml, evals_all=true)
bun run eval:bg:periodic # periodic tier (CI: evals-periodic.yml)
The local backend runs through
the sharded paid runner (scripts/test-paid-shards.ts, also available directly
as bun run test:gate:sharded / bun run test:periodic:sharded): one Bun
process per test file, an external wall-clock timeout that kills the shard's
whole process group (stray claude/codex grandchildren included), a per-shard
eval dir (GSTACK_EVAL_DIR=<evalDir>/shards/<slug>/), and an aggregate that
distinguishes failed vs timed-out vs never-started shards. The runner also
selects by diff: shards untouched by your branch are reported as
skipped-by-diff, with a selection banner naming the reason (EVALS_ALL=1
forces everything). EVALS_JOBS sets how many shard processes run at once
(default 8; test:pr sets 2); EVALS_CONCURRENCY is bun's concurrency WITHIN a shard
(default 2) — they are deliberately separate knobs. eval:list,
eval:compare, eval:summary, and eval:pass-rates are shard-aware. Humans running
bun run test:pr foreground in their own terminal don't need this — Ctrl-C
is intended there.
Eval comparison commentary: eval:compare generates natural-language Takeaway sections interpreting what changed between runs — flagging regressions, noting improvements, calling out efficiency gains (fewer turns, faster, cheaper), and producing an overall summary. This is driven by generateCommentary() in eval-store.ts.
Artifacts are never cleaned up — they accumulate in ~/.gstack-dev/ for post-mortem debugging and trend analysis.
Tier 3: LLM-as-judge
Uses claude-fable-5-1 by default to score generated SKILL.md docs on three dimensions.
Override the judge model per run with GSTACK_EVAL_MODEL_JUDGE:
- Clarity — Can an AI agent understand the instructions without ambiguity?
- Completeness — Are all commands, flags, and usage patterns documented?
- Actionability — Can the agent execute tasks using only the information in the doc?
Each dimension is scored 1-5 by a panel of 3 samples of the same prompt, drawn
concurrently; each dimension's panel median (at least 2 of 3 samples) must meet
that judge's threshold (≥ 4 for most dimensions; see each case). An erroring sample fails the panel. There's also a regression test that compares generated docs against the hand-maintained baseline from origin/main — generated must score equal or higher.
Needs ANTHROPIC_API_KEY in .env. The judge files run in every paid lane
(bun run eval:bg:pr selects the ones your diff touches).
- Resolves the judge model through
lib/eval-model.ts, using the override order above - Tests live in
test/skill-llm-eval.test.ts - Calls the Anthropic API directly (not
claude -p), so it works from anywhere including inside Claude Code
Paid-test touchfiles
test/helpers/touchfiles-data.ts maps each paid case to the files whose edits select it. Free
*.test.ts files are never listed: editing a free test does not run paid evals. test/touchfiles.test.ts
derives each paid file's static test/helpers / test/fixtures import closure, plus the fixture and helper
paths it names in string literals, and fails when that closure is not covered by the case's key. When it
fails, add the named path to the named key and check selection with
bun run scripts/test-paid-shards.ts --tier gate --profile pr --list. The rule is a lower bound: a fixture
path the test builds at runtime is not visible to it, so add such paths to the key by hand.
Add a paid eval
- Test file. Write the case in a paid test file, registered with a literal
name (
testIfSelected('<case-id>', ...)), grading the outcome (files, git state, native questions, exit status) rather than wording, unless the step itself is the contract. Wrap contract assertions inexpectContract(). - Touchfiles. Add
'<case-id>': [...]toE2E_TOUCHFILES;bun test test/touchfiles.test.tsnames any missing closure path. - Tier. Add it to
E2E_TIERS:gatefor cheap contracts every PR needs,periodicfor long or model-quality cases,marathonfor complete flows. - Kind. Add it to
E2E_KINDS(ruleunless a live model choice may acceptably deviate; thenbehaviorplus aBEHAVIOR_WHYline).bun test test/eval-kinds.test.tsprints the literal to add. - PR profile. If a PR should run it, add it to
scripts/test-pr-profile.tsand checkbun run scripts/test-paid-shards.ts --tier gate --profile pr --list. - Try the panel locally.
bun run scripts/test-paid-shards.ts --tier <tier> --case <case-id> --trials 3runs the same panel CI runs, before you push.
Retired commands
These package scripts are stubs for one release: each prints its replacement
and exits 1 (scripts/retired-command.ts). The next release deletes them.
| Retired | Use instead | Why it was retired |
|---|---|---|
test:evals |
bun run eval:bg:pr |
Tierless: skipped every tier-gated paid file |
test:evals:all |
bun run eval:bg:release |
Tierless: skipped every tier-gated paid file |
test:e2e |
bun run eval:bg:pr |
Tierless: skipped every tier-gated paid file |
test:e2e:all |
bun run eval:bg:release |
Tierless: skipped every tier-gated paid file |
test:gate |
bun run test:gate:sharded |
The single-process fan-out never completed a run |
test:periodic |
bun run test:periodic:sharded |
The single-process fan-out never completed a run |
test:codex |
bun run test:periodic:sharded |
Set no EVALS_TIER, so both periodic-tier Codex files ran zero cases |
test:codex:all |
bun run test:periodic:sharded |
Same as test:codex |
eval:bg |
bun run eval:bg:pr |
Detached the retired test:evals |
eval:bg:all |
bun run eval:bg:release |
Detached the retired test:evals:all |
eval:flake-rank |
bun run eval:pass-rates |
Second name for the same script |
eval:watch |
Tail the gstack-detach log, or gh run watch <run-id> |
Read a file only the unsharded runner wrote, so it showed nothing for sharded runs |
test:audit |
bun run test |
test/audit-compliance.test.ts already runs in the free suite |
CI
A GitHub Action (.github/workflows/skill-docs.yml) generates all hosts on pushes to main and on PRs, then rejects tracked differences and nonignored untracked output. Generation errors also fail the job. Optional ignored host caches are not compared against Git.
Supply-chain gates run alongside it:
-
Quality gate (
.github/workflows/quality-gate.yml, every PR and push) — scans the diff's added lines for credentials using gstack's own redact engine (.github/scripts/gate-secret-scan.mjs). HIGH findings fail the job; MEDIUM findings surface as an advisory count. Fails closed if the scan can't produce a report. Also runs ShellCheck on the setup/build boundaries. -
Dependency review (
.github/workflows/dependency-review.yml) — reviews dependency changes on PRs that touchpackage.jsonorbun.lockfiles and fails on high or critical advisories. It and the weekly OSV scan are the dependency gates. -
OSV scanner (
.github/workflows/osv-scanner.yml) — weekly vulnerability scan against the OSV database. Config lives in.osv-scanner.tomland is loaded via an explicit--configflag (OSV does not auto-discover that filename); every ignore entry needs a reason and anignoreUntilexpiry, enforced bytest/osv-config-wiring.test.ts. A failed main scan upserts the tracking issue "OSV scanner: vulnerable dependency needs triage" and a clean scan closes it;test/osv-ignore-expiry.test.tsfails 14 days before anyignoreUntil, so an expiring suppression surfaces in a PR. -
Weekly test health (
.github/workflows/test-health.yml, Mondays and on dispatch) — runsbun run test:health --since-days 7 --enforce. It fails when a free test file flakes in more than 5% of at least 20 main runs or more than 5 free files are missing from the duration seed, upserts one tracking issue on failure and closes it only when every previously failing check has evidence and passes. Metrics it cannot read print "unavailable: ; next: " and never fail the run. -
Dependabot (
.github/dependabot.yml) — grouped dependency update PRs. -
OpenSSF Scorecard (
.github/workflows/scorecard.yml) — weekly and on main pushes; results in the Security tab and api.scorecard.dev. -
Platform qualification (
.github/workflows/platform-qualification.yml, dispatch and quarterly) — runs the opt-in tests no other lane has prerequisites for: the ML prompt-injection classifier (SECURITY_BENCH=1), memory ingest against real gitleaks (GSTACK_TEST_GITLEAKS), and the DebugBridge Swift build (GSTACK_TEST_SWIFT=1, macOS).test/platform-qualification-workflow.test.tspins each gate to its job.
Every workflow pins its third-party actions to commit SHAs (test/workflow-action-pins.test.ts). The PR template (.github/PULL_REQUEST_TEMPLATE.md) asks for evidence — tests run, eval output — not promises.
Tests run against the browse binary directly — they don't require dev mode. Anything that needs Aside itself (test/skill-e2e-aside.test.ts, the Aside qa/design cases, the live render in test/aside-render.test.ts) runs only on a Mac with the Aside app open and self-skips elsewhere; make-pdf's render gates and the /diagram E2E run on whichever engine resolves, so CI runs them on the browse binary it builds with bun run build:gates.
Editing SKILL.md files
SKILL.md files are generated from .tmpl templates. Don't edit the .md directly — your changes will be overwritten on the next build.
# 1. Edit the template
vim SKILL.md.tmpl # or browse/SKILL.md.tmpl
# 2. Regenerate for all hosts
bun run gen:skill-docs --host all
# 3. Check health (reports all hosts)
bun run skill:check
# Or use watch mode — auto-regenerates on save
bun run dev:skill
skill:check renders all hosts into temporary storage using canonical content
paths and host defaults, validates the complete generated content, and compares
expected tracked artifacts against the checkout. Missing, changed, or nonignored
untracked output fails. Local ignored host caches, including symlinked caches,
are left untouched; the checker works without them. A generation failure cannot
produce a successful check of partial output.
For template authoring best practices (natural language over bash-isms, dynamic branch detection, {{BASE_BRANCH_DETECT}} usage), see CLAUDE.md's "Writing SKILL templates" section.
Browser steps in skills are aside repl scripts that follow the cookbook in scripts/resolvers/aside.ts, each paired with its $B equivalent for the fallback engine; run the Aside shape against the Aside CLI before committing. To add a browse command, add it to browse/src/commands.ts. To add a snapshot flag, add it to SNAPSHOT_FLAGS in browse/src/snapshot.ts. Then rebuild.
Render through lib/aside-render.ts; don't bundle puppeteer/Chromium in a
skill. A skill that needs to rasterize or print its own HTML/JSON (diagrams,
cards, og-images, PDFs) calls bin/gstack-render.ts from its template
(--screenshot, --pdf, --eval JS --out FILE) or imports render from
lib/aside-render.ts in TypeScript (renderWithAside / renderWithBrowse are
the engine-specific halves; render picks between them and retries once on the
browse engine if Aside's CLI cannot start or loses its CDP bridge mid-run). The
wrapper prints through Aside when it is open and through the browse daemon
when it is not (newtab --json, goto the loopback URL, js readiness
polling, pdf --from-file, viewport + screenshot, js --out, closetab)
— the one shared Chromium per box, same flags and OK <path> lines,
ENGINE=aside|browse saying which one actually rendered, EVAL /
PAGE_ERRORS lines fenced as untrusted web content. The loopback server
serves one per-render secret URL and never follows a symlink out of its
directory. Sized screenshots are 1x on the fallback (2x on Aside); JPEG
quality and pageRanges/scale are Aside-only; --landscape swaps paper
dimensions. Never npm i puppeteer, never download a second Chromium that
drifts out of version sync, never point the renderer at a website. If the
wrapper lacks an option you need, add it to lib/aside-render.ts (pin it in
test/aside-render.test.ts, and in test/gstack-render-cli.test.ts when it
is a CLI flag) so every caller gets it on both paths. Exported test seams:
pickEngine(fresh, deps) (inject the probe and the binary resolver),
serveDir(root, nonce), SAFE_TMP_DIR, and PAGE_NUMBER_FOOTER (the one
page-number footer make-pdf, gstack-render, and the browse pdf command share).
Prompt audit at each frontier-model release
When a new frontier Claude model ships, audit the text models read for
instructions the new model over-applies or no longer needs. The audit is
Anthropic's /claude-api prompt-audit, a Claude Code skill you run in your own
Claude Code session; gstack only prints what to feed it.
bun run audit:manifest # slices of templates, resolvers, overlays, CLAUDE.md and wording-pinning tests (--json for a machine-readable list)
- In Claude Code, run
/claude-api prompt-auditwith the new model as the target, one slice at a time, giving it that slice's file list.s01is the shared text every skill reads (CLAUDE.md, model overlays, preamble resolvers); a skill's template and its sections share one slice. - Fix findings in templates and resolvers, never in generated SKILL.md files,
then run
bun run gen:skill-docs --host all. - Treat safety rules as held: reword one only where an eval shows the model obeys it both before and after the change.
- Work through the "tests that pin skill wording" slices last. Where prose changed, replace exact-sentence pins with structural or meaning checks (the prompt-bytes rule in CLAUDE.md's testing section).
test/archaeology-lint.test.tskeeps issue numbers and incident stories out of the generated text; its failure names the source file to fix.
Jargon list (V1 writing style)
gstack's Writing Style section (injected into every tier-≥2 skill's preamble)
glosses technical terms on first use per skill invocation. The list of terms
that qualify for glossing lives at scripts/jargon-list.json — ~50 curated
high-frequency terms (idempotent, race condition, N+1, backpressure, etc.).
Terms not on the list are assumed plain-English enough.
Adding or removing a term: open a PR editing scripts/jargon-list.json.
Run bun run gen:skill-docs after the edit — terms are baked into every
generated SKILL.md at gen time, so changes take effect only after regeneration.
No runtime loading; no user-side override. The repo list is the source of truth.
Good candidates for addition: high-frequency terms that non-technical users encounter in review output without context (common database/concurrency terminology, security jargon, frontend framework concepts). Don't add terms that only appear in one or two niche skills — the cost-to-value trade isn't worth the review overhead.
Multi-host development
gstack generates SKILL.md files for 10 hosts from one set of .tmpl templates.
Each host is a typed config in hosts/*.ts. The generator reads these configs
to produce host-appropriate output (different frontmatter, paths, tool names).
Supported hosts: Claude (primary), Codex, Factory, Kiro, OpenCode, Slate, Cursor, OpenClaw, Hermes, GBrain.
Generating for all hosts
# Generate for a specific host
bun run gen:skill-docs # Claude (default)
bun run gen:skill-docs --host codex # Codex
bun run gen:skill-docs --host opencode # OpenCode
bun run gen:skill-docs --host all # All 10 hosts
# Or use build, which does all hosts + compiles binaries
bun run build
What changes between hosts
Each host config (hosts/*.ts) controls:
| Aspect | Example (Claude vs Codex) |
|---|---|
| Output directory | {skill}/SKILL.md vs .agents/skills/gstack-{skill}/SKILL.md |
| Frontmatter | Full (name, description, hooks, version) vs minimal (name + description) |
| Paths | ~/.claude/skills/gstack vs $GSTACK_ROOT |
| Tool names | "use the Bash tool" vs same (Factory rewrites to "run this command") |
| Hook skills | hooks: frontmatter vs inline safety advisory prose |
| Suppressed sections | GBrain blocks vs GBrain blocks and Review Army; Codex retains outside-review sections routed to Claude Code |
| Model overlay | claude vs gpt (per-host defaultModel; --model or, at setup time, the Codex config.toml model overrides) |
See scripts/host-config.ts for the full HostConfig interface.
Testing host output
# Run all static tests (includes parameterized smoke tests for all hosts)
bun run test
# Check freshness for all hosts
bun run gen:skill-docs --host all --dry-run
# Health dashboard covers all hosts
bun run skill:check
Adding a new host
See docs/ADDING_A_HOST.md for the full guide. Short version:
- Create
hosts/myhost.ts(copy fromhosts/opencode.ts), including itstierandcapabilities - Add to
hosts/index.ts - Add
.myhost/to.gitignore - Run
bun run gen:skill-docs --host myhost - Run
bun run test(parameterized tests auto-cover it)
Rendering needs no generator code. Installing does: an installable host also
needs a setup install arm, a row in gstack_host_tier
(bin/gstack-install-registry.sh), a README host-matrix row, and the
conformance kit (test/host-conformance.test.ts). It ships as experimental
until a dated certification record exists; see "Certify your host" and the
install ownership rules in the guide.
Adding a new skill
When you add a new skill template, all hosts get it automatically:
- Create
{skill}/SKILL.md.tmpl - Run
bun run gen:skill-docs --host all - The dynamic template discovery picks it up, no static list to update
- Budget it: run
bun test/helpers/capture-context-budget.tsand commit the refreshedtest/fixtures/context-budget.json— the context-budget ratchet fails any skill without a ceiling - Commit
{skill}/SKILL.md, external host output is generated at setup time and gitignored
Conductor workspaces
If you're using Conductor to run multiple Claude Code sessions in parallel, conductor.json wires up workspace lifecycle automatically:
| Hook | Script | What it does |
|---|---|---|
setup |
bin/dev-setup |
Copies .env from main worktree, installs deps, symlinks skills, runs ./setup non-interactively, and (if gbrain is installed) renders brain-aware blocks into .claude/gstack-rendered/ without dirtying tracked source |
archive |
bin/dev-teardown |
Removes skill symlinks, the .claude/gstack-rendered/ render, and cleans up .claude/ directory |
When Conductor creates a new workspace, bin/dev-setup runs automatically. It detects the main worktree (via git worktree list), copies your .env so API keys carry over, and sets up dev mode — no manual steps needed.
bin/dev-setup runs ./setup fully non-interactively (it passes --plan-tune-hooks=prompt and closes stdin), so a forwarded Conductor TTY can never hang on a hidden setup prompt. It also never installs the plan-tune Claude Code hooks, which means a throwaway workspace can't rewrite your global ~/.claude/settings.json to point at an ephemeral worktree path. To install the plan-tune hooks deliberately, run ./setup --plan-tune-hooks outside dev-setup (or gstack-config set plan_tune_hooks yes). The explicit flag counts as an explicit decision: setup's Conductor auto-opt-in for AskUserQuestion hooks fires only on the true silent fall-through (no flag, no GSTACK_PLAN_TUNE_HOOKS env var, no plan_tune_hooks key literally present in config, checked via gstack-config has), so it can never override dev-setup into installing hooks. One stated repair exception: setup's heal-first pass (gstack-settings-hook prune-stale --repoint) may prune dead gstack hook entries and re-point existing ones at the stable ~/.claude/skills/gstack install. That is strictly convergent repair, never a new registration, and registration itself is canonical-only, so an ephemeral tree path can never be baked into settings.json.
First-time setup: Put your ANTHROPIC_API_KEY in .env in the main repo (see .env.example). Every Conductor workspace inherits it automatically.
GSTACK_* env prefix (Conductor-injected keys). Conductor explicitly strips ANTHROPIC_API_KEY and OPENAI_API_KEY from every workspace's process env. The .env copy path doesn't restore them either — the strip happens after env inheritance. Users who want paid evals, /sync-gbrain embeddings, or claude-agent-sdk calls to work in a Conductor workspace must set GSTACK_ANTHROPIC_API_KEY and GSTACK_OPENAI_API_KEY in Conductor's workspace env config; Conductor passes those through untouched. On the gstack side, TS entry points import lib/conductor-env-shim.ts as a side effect, which promotes GSTACK_FOO_API_KEY to FOO_API_KEY when the canonical name is empty. If you add a new TS entry point that hits a paid API, add import "../lib/conductor-env-shim"; to the top of the file. Today the shim is imported from bin/gstack-gbrain-sync.ts, bin/gstack-model-benchmark, scripts/preflight-agent-sdk.ts, and test/helpers/e2e-helpers.ts.
Things to know
- SKILL.md files are generated. Edit the
.tmpltemplate, not the.md. Runbun run gen:skill-docsto regenerate. The same run generatesreview/design-checklist.mdfromlib/design-catalog.tsandlib/dom-dump.jsfromlib/dom-dump-script.ts: edit those sources, never the generated files (test/design-checklist-sync.test.tsfails on drift). - TODOS.md is the unified backlog. Organized by skill/component with P0-P4 priorities.
/shipauto-detects completed items. All planning/review/retro skills read it for context. - Browse, make-pdf, design, and
lib/source changes need a rebuild. If you touchbrowse/src/*.ts,make-pdf/src/*.ts,design/src/*.ts, or anything underlib/(the canonicalclaude-bin.ts,error-handling.ts, andaside-render.tsthe binaries embed, plusdesign-catalog.ts, whoseMOCKUP_NEVER_NAMESthe design binary's mockup prompt embeds;browse/srcre-exports the first three), runbun run build../setupmakes the same call on its own: it rebuilds when any of the three binaries is missing or when those sources,package.json, orbun.lockare newer than the browse binary (test/setup-needs-build.test.tspins the decision). - Dev mode shadows your global install. Project-local skills take priority over
~/.claude/skills/gstack.bin/dev-teardownrestores the global one. - Conductor workspaces are independent. Each workspace is its own git worktree.
bin/dev-setupruns automatically viaconductor.json. .envpropagates across worktrees. Set it once in the main repo, all Conductor workspaces get it..claude/skills/is gitignored. The symlinks never get committed.- Never write raw
ln -snfinsetup. Every link site insetupMUST route through the_link_or_copy SRC DSThelper near theIS_WINDOWSdetection. The helper preservesln -snfon Unix and switches tocp -R/cp -fon Windows without Developer Mode, where plainln -snfproduces frozen file copies that don't refresh ongit pull.test/setup-windows-fallback.test.tsenforces this with a static invariant — a single rawlncall outside the helper body fails CI. - Synchronous subagent dispatches must state the flag. Claude Code runs Agent-tool subagents in the background by default (since v2.1.198), so any template step that dispatches a subagent and consumes its output must carry
run_in_background: false. Use the{{FOREGROUND_DISPATCH_NOTE}}placeholder (scripts/resolvers/constants.ts) instead of hand-writing the guidance, and add the generated carrier file toGENERATED_WITH_GUIDANCEintest/run-in-background-guidance.test.tsin the same commit — its structural scanner fails CI on any generated dispatch imperative that lacks the flag. - Never delete or link over a skill entry
setupcannot prove is gstack's. Every destructive site insetup(the linker, the alias installer, both prefix-flip cleanups) and inbin/gstack-relinkgoes through the ownership helpers (_claude_entry_is_ours/_claude_entry_owned_stronglyinsetup,_entry_is_ours/_entry_owned_stronglyin relink). The retired-skill prune (_prune_stale_generated) applies the same strong/weak split through its own gate: a real host directory is a candidate only when its SKILL.md carries the generated banner (_owned_for_windows_refresh), a host symlink is removed only when it resolves into gstack (_gstack_target_is_ours), a bannered real directory is cleaned through_cleanup_weak_dir, and a symlink inside the render tree is never followed. A symlink into gstack or the.gstack-ownedmarker proves the whole directory; a byte-identical or generated-banner SKILL.md proves only that file, and a differing one is moved to~/.gstack/backups/skills/<ts>/first.test/setup-link-ownership.test.ts,test/setup-cleanup-orphans.test.ts,test/setup-prune-stale-generated.test.ts, andtest/relink.test.tspin it. The rule is duplicated in the two scripts until the shared helper filed in TODOS.md lands: change both. ./setupnever fails on Chromium. The Playwright bootstrap (section# 2ofsetup) is best-effort and bounded: every failure becomes a reason code (skipped,chromium-install,chromium-install-timeout,chromium-install-locked,windows-no-node,windows-node-modules,post-install-launch) printed in the final summary alongside the browser-dependent skills, and skill registration always runs.GSTACK_PLAYWRIGHT_INSTALL_TIMEOUT=<seconds>(default 600) bounds the download;GSTACK_SKIP_PLAYWRIGHT=1skips it, the right knob for a no-browser box or a setup-only test loop.GSTACK_SKIP_ASIDE=1makes the browser summary (like the skills' probe and the renderer) treat Aside as absent, so the summary never promises a fallback the bootstrap did not deliver (test/setup-browser-hint.test.ts). Anything you add after the bootstrap must stay independent of the browser.test/setup-playwright-best-effort.test.tspins the block.
Testing your changes in a real project
This is the recommended way to develop gstack. Symlink your gstack checkout into the project where you actually use it, so your changes are live while you do real work.
Step 1: Symlink your checkout
# In your core project (not the gstack repo)
ln -sfn /path/to/your/gstack-checkout .claude/skills/gstack
Step 2: Run setup to create per-skill symlinks
The gstack symlink alone isn't enough. Claude Code discovers skills through
individual top-level directories (qa/SKILL.md, ship/SKILL.md, etc.), not through
the gstack/ directory itself. Run ./setup to create them:
cd .claude/skills/gstack && bun install && bun run build && ./setup
Setup will ask whether you want short names (/qa) or namespaced (/gstack-qa).
Your choice is saved to ~/.gstack/config.yaml and remembered for future runs.
To skip the prompt, pass --no-prefix (short names) or --prefix (namespaced).
Step 3: Develop
Edit a template, run bun run gen:skill-docs, and the next /review or /qa
call picks it up immediately. No restart needed.
Going back to the stable global install
Remove the project-local symlink. Claude Code falls back to ~/.claude/skills/gstack/:
rm .claude/skills/gstack
The per-skill directories (qa/, ship/, etc.) contain SKILL.md symlinks that point
to gstack/..., so they'll resolve to the global install automatically.
Switching prefix mode
If you installed gstack with one prefix setting and want to switch:
cd .claude/skills/gstack && ./setup --no-prefix # switch to /qa, /ship
cd .claude/skills/gstack && ./setup --prefix # switch to /gstack-qa, /gstack-ship
Setup cleans up the old symlinks automatically. No manual cleanup needed. Only
entries gstack created are removed: a skill of your own that shares a name (a
hand-written qa/, say) is left in place and named in setup's final summary.
Alternative: point your global install at a branch
If you don't want per-project symlinks, you can switch the global install:
cd ~/.claude/skills/gstack
git fetch origin
git checkout origin/<branch>
bun install && bun run build && ./setup
This affects all projects. To revert: git checkout main && git pull && bun run build && ./setup.
Community PR triage (wave process)
When community PRs accumulate, batch them into themed waves:
- Categorize — group by theme (security, features, infra, docs)
- Deduplicate — if two PRs fix the same thing, pick the one that changes fewer lines. Close the other with a note pointing to the winner.
- Collector branch — create
pr-wave-N, merge clean PRs, resolve conflicts for dirty ones, verify withbun run test && bun run build - Close with context — every closed PR gets a comment explaining why and what (if anything) supersedes it. Contributors did real work; respect that with clear communication.
- Ship as one PR — single PR to main with all attributions preserved in merge commits. Include a summary table of what merged and what closed.
See PR #205 (v0.8.3) for the first wave as an example.
Upgrade migrations
When a release changes on-disk state (directory structure, config format, stale
files) in ways that ./setup alone can't fix, add a migration script so existing
users get a clean upgrade.
When to add a migration
- Changed how skill directories are created (symlinks vs real dirs)
- Renamed or moved config keys in
~/.gstack/config.yaml - Need to delete orphaned files from a previous version
- Changed the format of
~/.gstack/state files
Don't add a migration for: new features (users get them automatically), new skills (setup discovers them), or code-only changes (no on-disk state).
How to add one
- Create
gstack-upgrade/migrations/v{VERSION}.shwhere{VERSION}matches the VERSION file for the release that needs the fix. - Make it executable:
chmod +x gstack-upgrade/migrations/v{VERSION}.sh - The script must be idempotent (safe to run multiple times) and non-fatal (failures are logged but don't block the upgrade).
- Include a comment block at the top explaining what changed, why the migration is needed, and which users are affected.
Example:
#!/usr/bin/env bash
# Migration: v0.15.2.0 — Fix skill directory structure
# Affected: users who installed with --no-prefix before v0.15.2.0
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
"$SCRIPT_DIR/bin/gstack-relink" 2>/dev/null || true
How it runs
During /gstack-upgrade, after ./setup completes (Step 4.75), the upgrade
skill scans gstack-upgrade/migrations/ and runs every v*.sh script whose
version is newer than the user's old version. Scripts run in version order.
Failures are logged but never block the upgrade.
Testing migrations
Migrations are tested as part of bun run test (tier 1, free). The test suite
verifies that all migration scripts in gstack-upgrade/migrations/ are
executable and parse without syntax errors.
Shipping your changes
When you're happy with your skill edits:
/ship
This runs tests, reviews the diff, triages Greptile comments (with 2-tier escalation), manages TODOS.md, bumps the version, and opens a PR. See ship/SKILL.md for the full workflow.