mirror of
https://github.com/garrytan/gstack.git
synced 2026-10-03 09:56:57 +02:00
Garry Tan
7fca42ad8b
* test: delete test-infrastructure dead code (G) - exit-propagation drives the runner's real strict verdict (BunTestOutputClassifier + strictTestExitCode); delete the unused shardRunLooksTruncated predicate. - delete skill-coverage-matrix registry + its gate (nothing reads it; the floor already iterates skillCensus()). - delete touchfiles-facade export-parity tests (Bun fails missing imports at link time) and the duplicated E2E_TIERS tier-value test. - delete brain-cache-spec TRANSPORT_DEFAULT_POLICY, SKILL_RUN_RETENTION_DAYS and the now-unused BrainTrustPolicy type with their literal tests. AUTOPLAN_PREFLIGHT_BUDGET_BYTES stays: skill-preflight-budget enforces it against real resolver output. - delete audit-compliance's JSDoc-comment grep. * test: replace product tests that fake the product with real-boundary tests (F) - design: serve.test.ts drove an inline mirror server; now two tests run the real serve() on an ephemeral port (reload confinement, submit exit 0). - setup-gbrain: rollback + voyage tests execute the template-extracted init blocks (3 sites) instead of drifted local bash copies. - terminal-agent: internalHandler source greps replaced by a behavioral /internal/grant + /internal/revoke auth matrix (no/wrong/valid token). - /health: server-security-surface and the server-auth / security-audit-r2 / sidebar-tabs source greps fold into one liveness-only check on the real body; the L4 sidecar wiring gets a behavioral /pty-inject-scan test. - delete tautologies (browser-manager onDisconnect, memory-command #12), ios swiftui tap fixture self-check, memory-ingest put_page grep, detach source greps, sidebar-agent absence pins, dead-CSS pins + the dead CSS, security-audit-r2 Task 1 + the test-only meta-commands re-export, duplicate generated-SKILL.md checks. - make-pdf coverage-gaps cases move into their owner test files. * test: delete tests of dead eval code (A) - A1: the retired Eng lexical oracle (evaluateEngSeedCoverage, isEngSeedDecisionAUQ), the completion-handoff detector and the retained corpus had no paid caller since v1.87.6; delete their 26 replay files, ~2.6k helper LOC and fixtures, and the dead blocks in 8 mixed files (live hasNativePlanTerminal / batching assertions stay). - A2: dead viewport approvers in autoplan-artifact-permission and their 11 replay files + fixtures; recorder/launcher cases stay. - A3: never-wired oracles and seeders (autoplan-phase-order, eng-finding-fixture, ceo-paired-fixture, design-ui-scope, plan-skill-completion, pty-current-screen, required-reads, transcript-section-logger); plan-seed-submission now decodes through the production createPtyScreen; section manifests name their actual guard. - A4: zero-reference helper exports, plus execGit and invokeAndObserve found by the reachability pass. - 52 fixtures orphaned by the deletions; touchfile and selection-table entries for every deleted path. * test: clean up the paid eval lane (B1-B4, B6, B7) - B1: delete paid files that assert nothing or cannot pass meaningfully: skill-llm-eval-spec and skill-e2e-spec-execute (test.todo), gemini-e2e (+ gemini-session-runner; no gemini CLI in CI), ship-idempotency (red since v1.63), the two opus-4-7 *-sonnet overlay wrappers, conductor-prose (+ its source-evaluation replay), codex-e2e-plan-format; drop their keys, scripts and census rows. - B2: skill-llm-eval grades browse/sections/command-list.md with one union judge that also carries the baseline score pin; regression-vs-baseline deleted (paid run: pass, c4/c4/a4). - B3: memory-pipeline, ios-qa, ios-qa-swift-build and plan-tune-cathedral make no model calls; renamed out of the paid glob so they run on every PR. Swift builds need GSTACK_TEST_SWIFT=1; device stub deleted. - B4: codex-e2e*, outside-voice, aside and ios-device cannot run in the CI image; excluded from the weekly lane with a tracked re-entry condition. - B6: fold opus-47's negative routing controls into skill-routing-e2e journey-negatives (paid run: 3/3 unrouted) and delete the file. - B7: delete the never-green brain-privacy-gate eval; a free gstack-skill-start test now proves consent precedes artifacts egress. * test: retire the finding-count cluster and trim its helpers (C) - C0/C1: the five never-green evals (skill-e2e-autoplan-chain and skill-e2e-plan-{ceo,eng,design,devex}-finding-count) failed on harness and budget, never on skill behavior; delete them, their touchfile/tier ids, AUTOPLAN_CHAIN_BUDGET and the dedicated eighth periodic slice (--slices 7). - C2: delete the helper groups whose only paid consumers were those files (11 modules), trim claude-pty-runner and eng-seeded-coverage to the paid closure, and delete the free replay tests whose assertions exercised only that dead code (89 files, 135 orphaned fixtures). Blocks that used dead code only as input for a live subject keep their assertions: the multiSelect default moved to plan-review-decisions, runner PTY tests use inline caller policies, and the timer-safe budget checks moved to eng-finding-retry-budget. - The eight production-touching files stay except ceo-current-decision-record (its template read only feeds the retired counter). - CARVE_GUARDS.autoplan is behavioral 'none'; TODOS records the lost chain and per-finding cadence coverage with their re-entry tests. * test: fold per-incident replay series into their detector owners (D) Twelve detector families move into one owner test each: 73 incident files become describe blocks in ceo-section-loading-fixture (stale-fill race), model-overlays, coverage-audit-evidence, autoplan-phase-observer, native-auto-decide, outside-voice-evidence, eng-first-review, plan-count-completion, plan-count-file-permission, ceo-mode-option, plan-scope-selection and plan-count-prerequisite. Each block keeps its original code and fixture, so every case still runs; only tests asserting the incident file's own touchfile registration are dropped (41). Touchfile lists that named an incident now name its owner. * test: start the plan-count history PTY on its readiness marker (H) The fake CLI prints a startup marker and the runner waits for it instead of the fixed 8 s startup sleep (8.6 s -> 0.9 s locally). eng-semantic-terminal's sleeping registration cases went with C; plan-count-timeout keeps the fixed wait because it asserts deadline behavior. * test: derive paid touchfiles from each eval's static closure (E) touchfiles.test.ts now checks, per key, that the paid file's static test/helpers and test/fixtures closure (plus fixture paths it names in string literals) is covered, and names the file, path, chain and key to fix when it is not. Free *.test.ts files are no longer touchfiles, so editing a free replay test stops selecting paid evals: 950 entries removed, 653 real closure paths added. The hand-copied inventories go: periodic-fixture-selection, fake-impeccable-touchfiles and 45 per-file selection examples. Selection for the sample edits (plan-eng-review template, claude-pty-runner, plan-count-fixture, gstack-config) loses no case under either profile. CONTRIBUTING documents the rule and its lower bound. * test: skip hollow tier shards and census judges in the paid planner (B5) A paid file is now skipped for a tier lane only when every E2E id it registers is known statically and none has that tier; ids come from the touchfile registrations and literal testName/*IfSelected arguments, so a comment or skill path that quotes another id cannot unschedule it, and computed names keep today's scheduling. --list and the manifest show each skip as "skipped: no E2E_TIERS id has tier <tier>". The weekly gate census drops the LLM judges (--skip-judges); they still run in the periodic census and PR gate lanes. Gate lane 52 -> 42 files, census 41; periodic 77 -> 69. * test: run seven paid evals on the current default capture model (B8) skill-e2e-{auq-matrix,plan-format,qa-bugs,retro,workflow} pinned claude-opus-4-7 and skill-e2e-office-hours plus -brain-writeback pinned claude-sonnet-4-6; none tests a historical model, so they now capture with resolveEvalModel('capture'), and the free harness tests that execute these registrations receive the same resolver. The paid re-pin run passed all of them. skill-e2e-{design,office-hours-phase4,plan-prosons,plan} keep claude-opus-4-7: six of their cases failed on the default model (three timeouts, a missing report file, a format miss and a posture score of 3), so per the plan's fallback they keep their pins with a TODOS entry. The pre-spend estimate and drop threshold are in docs/test-audit-2026-09.md. * test: guard the reduced suite against new test-of-test files - test/test-of-test-ratchet.test.ts records the 228 free tests that import only test/ code and fails on a new one, naming the owner test to extend instead; a stale baseline entry fails with the remove instruction. - test/helpers/resolve-repo-path.ts is the one specifier/literal resolver for the ratchet and the touchfile closure invariant, with its own unit tests. - CONTRIBUTING "Test tiers" describes the paid-failure workflow (fix, then one row in the detector's owner test) and the ratchet; TEST_PORTFOLIO gains the detector -> owner-test table and no longer claims an Autoplan chain eval. - TODOS: automatic exclusion policy for chronically red periodic files (P3), the deferred native-completion table collapse, the unused CEO payment seeder; the PTY readiness item is narrowed to the paid runner. - docs/test-audit-2026-09.md collects the triage, security mapping, inventories, selection proof, behavior-commit decisions and retained false positives. * v1.91.8.0 test: smaller suite, derived paid selection, retired never-green evals Release metadata for the test-reduction branch: VERSION 1.91.8.0 (1.91.7.0 is claimed by #2983), CHANGELOG with the measured before/after table and a contributor section, durations re-recorded on Ubicloud standard-16 (857 files, 0 failures), the agents digest, CONTRIBUTING's after-measurement row, the B8 fallback TODOS entry, and the after metrics, kept-vs-plan notes, B8 run and census estimate in docs/test-audit-2026-09.md. * fix(ubicloud): skip retrieval globs that match nothing instead of reporting a failed pull * test: pin DISABLE_AUTOUPDATER in hermetic env and capture corrupt-seed warning Both EVALS_HERMETIC branches of buildHermeticEnv now carry DISABLE_AUTOUPDATER=1 (the allowlist scrubbed the workflow's copy, so every PTY screen showed the updater's npm-prefix failure). Per-test overrides still win. The corrupt durations-seed test now captures its expected warning and restores the console spy. * style(cso): format lib/cso TypeScript with pinned Prettier Mechanical reformat only. Minified transpile output is byte-identical for 21 of 22 files; witness.ts differs only in three regex flag orders (/mi -> /im), which JavaScript canonicalizes. Source-text assertions over lib/cso now compare whitespace-insensitively with the same tokens. * fix(cso): import join for compiled-launcher assertion witnesses Compiled installs always take the non-Bun branch, which called an unimported join and threw before any runtime-tested assertion could be witnessed. The child command selection is now a pure, platform-aware function; a missing sibling launcher fails with its expected path. * fix(browse): make connect --supervise actually respawn a crashed server The supervisor respawned with a block-scoped env that no longer existed, so every attempt threw and the loop gave up after five tries. The headed env is now one pure helper used by connect and respawn, the loop is an injectable runHeadedSupervisor with behavioral tests, failures name the daemon log and relaunch command, and connect's usage advertises --supervise. * test: one finite PR world for the shared-libs fixture; name dual-voice probe evidence The shared-libs shim served 2 PRs for pulls?state=all and endless full pages for state=open. gh pr list, pulls?state=open|all|closed (per_page/page, short last page, direction) and search/issues now page one deterministic table: PR 7, 600 older open PRs, PR 42 and 3 closed PRs, so five 100-item open-metadata pages still leave older open PRs unchecked. The Contents API lists pinned directories (the captured attempt got 404 for contents/ and contents/src while files resolved, then fell back to a raw host), unknown endpoints return 404 instead of repo metadata, and the read-only detector is unchanged. Free tests cover view agreement, the budget bound, gh/curl agreement and the empty world. Dual-voice outside-voice failures now report probeToolUseId, probeMode and the canonical-match result with the reason the probe output was rejected. * feat: require a zero-error product typecheck and a test type-debt ratchet Adds tsconfig.json (strict) over product code, fixes its remaining 90 diagnostics (type-only, interface corrections, and explicit narrowing), and adds a typecheck job to the required free-tests aggregate running bun run typecheck, the test-code ratchet (identity -> count baseline, fails on new, repeated, or unlocked fixed diagnostics), and the lib/cso format check. Reuses fixes from #2447 where they still applied. * test: follow the headed env helper and the typecheck gate in source-shape checks * fix(test): pin the package.json change kind in shared-input selection tests computePaidCaseSelection read the version-only exemption from git even when changed files were injected, so the shared-input test failed on main and on version-only branches. The exemption is now an optional input; the test pins a real package.json change and covers the version-only case. * test: judge plan-count completion on structured evidence, not wording Replaying run 36385945043's two Design attempts showed the existing routes rejected correct endings: attempt 1 at the typed-completion path field ('- Reviewed plan written to …' is not a 'Plan written to' line), attempt 2 at the leading-fence veto (its final message opens with the dashboard). nativePlanTerminalPreconditions is the structural prefix of hasNativePlanTerminal (behavior unchanged). structuredPlanCompletion adds, inside the existing nativeSummary branch: a complete report (Design binding for Design), a completed review-log row for the expected skill appended during this attempt under the child's GSTACK_HOME/project slug (resolved with bin/gstack-slug) and stamped with the fixture commit, timed between the report/last answer (second resolution) and the final native message, a final message with stop_reason end_turn (now carried on public transcript messages), and no visible question or permission prompt. Timeout summaries add idleFor and lastTerminalCandidate. Terminal and throw captures copy the plan file and review-log rows into the artifact directory; copies are best-effort and recorded in evidence-copy.json. Free regressions: both captured Design endings (trimmed fixture with provenance; report, row and end_turn reconstructed and labelled), the negative controls, and real-PTY completion/timeout runs through the real review logger. * test: structural Design count boundary; TODO proposals are not findings Replaying run 36385945043 through the Design count predicates: routing, focus and learnings setup was not recognized as setup, Issue 1 was counted pre-review in both attempts (the boundary fired on it), and attempt 2 counted the Font TODO proposal as a finding (review=4 and review=5 for five issues). The paid caller now starts review at the first answered native decision that is not setup (recognized packet, or setup header/question ID), a completion handoff, artifact rendering or a TODO proposal (the review's Add to TODOS.md / Skip / Build it now menu). TODO proposals are recorded as administrative extra decisions. The replay asserts each counted call: both attempts review=5 (Issues 1-5). isDesignCountFirstReview and its controls are unchanged. * test: CEO classifier throws name the question and matched predicates Replaying run 36385945043's FAN-1 and ERR-1 throws (ledger rows reconstructed from rendered diffs) through ceoPaymentFinding: the email obligation's row, subject, option and proposal predicates pass and the ELI10 explanation-defect predicate fails first ('lets that exception fly out', 'the error bubbles up'). Binding the defect to the named ledger row instead (the planned fix) was tried and reverted: scoped to the email seed it flips 30+ existing cf74 still-rejects replays, which require a vocabulary-free, ledger-bound email question to earn credit only through a complete saved comparison. With FAN-1's rendered currentDecision payload reconstructed, the recorded- decision path counts it, so the real saved plan (not uploaded) must have differed; failure artifacts now retain it. The classifier stays fail-closed and unchanged. Its throw now prints the header, the first 200 question characters and each obligation's predicate results. Free regressions with provenance and negative controls: an unrelated question, an email question whose row says it is already rescued, and a ledger ID whose row belongs to another seed. * chore: regenerate the test type-debt baseline on top of #2994 * fix(typecheck): strip the checkout root from ratchet diagnostic identities * fix(test): recognize ledger row-ID split candidates so collection stops at the last ACK Run 36385945043's split-overflow case asked all five candidate decisions by 8m55s, but the live candidate check required the question to open with "E1:" and every option to be a known disposition. The skill cited ledger row IDs ("D2.1 — R-E1: …") and offered "Hold, discuss first", so no candidate was recognized and the attempt ran the whole review (1302s). Identity now comes from the native header; the question must open with that candidate's ledger reference, name only that candidate, and offer exactly one include, defer and cut disposition. The selected answer must still be one of those three. The semantic evaluator and every existing negative control are unchanged; a trimmed capture from the run adds the positive case and four row-ID negative controls. * fix(test): stop the eng batching eval once its floor is proven The case's only verdict is reviewCount >= FLOOR (3). Run 36385945043 had three distinct acknowledged review decisions at 6m41s but kept answering until the ceiling (7) at 12m13s. The registration now passes the runner's existing isCollectionComplete stop once FLOOR non-setup, non-administrative review decisions are acknowledged; the floor check, ceiling, budget and counter are unchanged. A child-process registration test proves the stop predicate and that below-floor and timeout outcomes still fail. * test: add the non-blocking 'marathon' E2E tier Full start-to-finish flows move out of the blocking lanes. E2E_TIERS and E2ETier gain 'marathon'; describeE2ETier('marathon') is enabled only when EVALS_TIER=marathon, so the gate/PR and periodic lanes (and the gate census) never run those cases. The PR profile accepts marathon ids as scheduled elsewhere and defers them with their own reason, even on full fallback. * test: move the full office-hours workflow to marathon; add a periodic design-draft checkpoint The full startup workflow runs 1–3 real spec-review rounds (~280s each) and hit its 1200s capture in run 36385945043 at finalize. Review depth is the product's loop, so the case cannot fit a blocking lane without cutting rounds. It is now marathon tier with every assertion unchanged. skill-e2e-office-hours-design-draft.test.ts (periodic) runs the same fixed interview only through the Write that creates the design (269s in that run) and applies the full validator's design-draft checks, the required section reads and the launch/foreign-skill-read guards. validateOfficeHoursDesignDraft is extracted from validateOfficeHoursCompletion, which still applies it. Selection: office-hours-design-draft is registered periodic; the marathon-only file is already excluded from the gate and periodic plans by the B5 planner rule. Tier-alignment regexes and the valid-tier check accept 'marathon'. A type-only cast in plan-scope-selection.test.ts removes a diagnostic whose union print order made the ratchet identity unstable; baseline tightened. * test: supply the split-overflow fixture's HOLD SCOPE mode as a prerequisite The split actor always answered 0E's mode question with HOLD SCOPE. The skill skips that question on an explicit choice, so the fixture now states it and the attempt starts at the five candidate decisions (about 1.5 min earlier in run 36385945043). Candidates, actor policy, floor and semantic evaluation are unchanged; the fixture test pins the supplied choice. * test: start the eng batching eval with its setup prerequisites supplied Routing setup and cross-project learnings (D1/D2 in run 36385945043) are never counted and are not what the case measures. The registration now uses the runner's existing preconfiguredReviewActor so the attempt starts at the review; engSetupAUQ still vetoes any late setup question. The registration test pins the option. * test: count the design-draft paid file and defer marathon ids in PR selection pins The discovered paid-file census grows by one (skill-e2e-office-hours-design-draft). Full-fallback PR selection defers every non-gate id; the shared-input pins now expect periodic and marathon ids there. * fix(review): resolve the judged revalidation, setup-authority, plan-gate and findings-record ambiguities The census review workflow judge scored clarity/actionability 3 on both attempts: smoke-clock limits appeared to forbid post-repair revalidation, the caller deadline was undefined, 'ask for setup' conflicted with the report-only browser rule, fallback-sourced HIGH discrepancies had no gate decision, and the Step 5.8 record omitted adversarial findings. * fix(office-hours): load the builder section for every builder-mode reply Both census builder-wildness attempts answered a direct request for adjacent unlocks without reading phase-2b-builder-brainstorm.md, whose trigger read as applying only to the generative questions. * fix(sync-gbrain): define Step 4 helper args and one atomic write path Both census read-ready attempts spent turns reading the helper source to resolve <user-args>, inspecting fixture internals kept inside the repo, and reconciling 'Read + Edit' with the tmp+mv atomic write, then hit max turns before the verdict. * refactor(evals): share the import-closure walker and add the E2E shard reuse identity sourceDependencyClosure moves from the workflow-judge adapter into scripts/eval-input-cache.ts unchanged, so judge keys stay byte-identical. scripts/e2e-shard-reuse.ts builds the consumed-input identity of one PR-lane E2E shard (test import closure, every registered case's touchfiles, globals, runner/workflow/setup actions, child env pins, CI image, Claude CLI) and fails closed on anything unknown. Marathon joins the always-fresh purposes. * feat(evals): ~12-minute blocking paid lanes and a non-blocking marathon lane - Planner budget mode (--slice-budget S --jobs J): recorded per-tier wall times pack into as many ~9-minute executors as the work needs; the plan records per-slice estimates and the CI job timeout (supervised worst case + 20 min). evals.yml and evals-periodic.yml derive matrix size and timeout-minutes from it; max-parallel covers every slice at once. - Case shards: plan/design/review-army/shared-libs(-paths) run one registered case per process (<file>#<case id>, exact name pattern, exactly one case). - Retry rule: a timed-out attempt is a verdict. Only files whose every case budget is CAPTURE tier or shorter keep one retry; walls shrink to match. - Marathon tier: positive selection, excluded from gate/periodic planners, run by the new evals-marathon.yml (weekly + dispatch, fresh, own report). - PR-lane E2E reuse of verified first-attempt passes on identical inputs; the report rejects reuse outside the fast PR profile. - Duration seed from census run 36385945043, per tier and per case shard. * docs: blocking lane budget, marathon lane, retry policy and E2E reuse * chore(typecheck): lock in two fixed test diagnostics * fix(ci): drop a duplicated env/jobs block in evals-marathon.yml * test(ship-docsync): shard the doc-sync lifecycle by case and drop the duplicate dispatch-only case ship-docsync ran the same fixture and prompt as ship-docsync-completion and asserted a subset of it. The file now runs one case per process, so its lane wall is its longest case instead of half the sum of thirteen. * fix(evals): plan CI-unrunnable cases as excluded entries, not empty case shards design-review-fix drives the Aside browser and registers test.skip on Linux runners, so its case shard executed zero cases and failed the exact-one-case check in proof census 36597762183 (eval-slices 6). CASE_CI_EXCLUDE (reason + tracking, beside PERIODIC_CI_EXCLUDE) now turns such cases into excluded manifest entries that --list and the manifest surface; every planned case shard still must execute exactly its case. * docs(todos): list the case-level Aside exclusion with the CI-unrunnable evals * fix(plan-ceo-review): restore experience-first expansion framing, require the mode handoff, skip pacing menus Census 36597762183: both mode-routing runs logged provenance and moved on without the mandated handoff chat; the EXPANSION run asked an unauthorized batch/narrow pacing menu instead of the first per-addition question; the expansion-energy proposals led with the spec because v1.87.6.0 dropped 'lead with the felt experience'. The HOLD review detector also rejected a decision whose grounding line named no plan file although the owned source Read binds it. * test(outside-plan-disabled): bind quoted prior-record values by their sentence, not phrase order The parent obeyed the off switch and twice named the seeded completed record as pre-existing, once with the quotation after its owner and once with slash separators; the order-specific stripper counted both as current completion. Timestamp, location, current-claim and value-match controls still reject. * test(outside-plan-disabled): compare named record timestamps as instants; negated authorship is not a current claim The repair rerun named the seeded record by its ISO second (2026-09-29T16:58:52Z vs .727Z) and said 'I did not write'; both were misread as a foreign timestamp and a current write. * test(ceo-section-loading): recognize an arrow-ordered stale-fill execution by event roles The census review traced the seeded race as 'R1 miss -> R1 store read (v1) -> W commit v2 -> W cache.delete -> W fulfills -> R1 cache.set(v1) -> R2 (begun after W) hits v1', but the in-flight gate only accepted race vocabulary or fixed sentence shapes. Order, actor, version and dismissal mutations still fail. * test(design-floor): answer the seed-declared all-seven 0D focus menu while it is pending The actor declares 'Design: review all seven dimensions', but its picker reused designReviewSetupAUQ, which only matches already-answered calls (and a narrower header/label set), so the pending D1 focus menu was never answered and the case waited out its 609 s deadline. The skill's Step 0D requires asking; the fixture now answers it. * test(ceo-mode-routing): accept the skill-mandated Note form and Recommendation reason as HOLD posture HOLD Defer/Keep briefs must use 'Note: options differ in kind' (preamble), but the answered-HOLD path demanded a Completeness score, rejected a one-line Net with a semicolon, and read posture only from ELI10. The rerun's brief applied HOLD SCOPE in its Recommendation reason. Revert the ineffective 'always'/'handoff chat' wording: two runs still skipped the mode handoff. * test(qa-bugs): keep claude-opus-4-7 after qa-b6-static stalled on the default model qa-b6-static timed out on claude-fable-5-1 in census 36597762183 and in one of two targeted reruns. Both times the stream stopped mid-message with no pending tool, right after the model found the disabled submit button, and stayed silent until the 300 s deadline. Per the B8 fallback, re-pin with a TODOS entry; budgets and retries are unchanged. A rerun on opus-4-7 passed (125 s, 5/5 detected). * test(evals): add E2E_KINDS, BEHAVIOR_WHY, EVAL_POLICY and CASE_QUARANTINE skeletons Every E2E_TIERS and LLM_JUDGE_TOUCHFILES key starts as 'rule'; BEHAVIOR_WHY and CASE_QUARANTINE start empty. EVAL_POLICY pre-registers the approved panel (3, majority 2), quarantine entry 0.95/10 and exit 0.97/10, 10% cap, 8-weekly-run expiry, Fisher drift alarm and one INFRA re-dispatch. * test(evals): add trial records, panelVerdict, expectContract and trial-outcomes JSONL EvalTestEntry gains case_id, kind, trial, panel, failure_class and policy_version, stamped from the runner's TRIAL_ENV on isolated trial shards. panelVerdict() is the single verdict function (INCOMPLETE on missing or duplicate trials, contract veto at any count, quarantine hard-break rule, INFRA/INCOMPLETE machine classification). expectContract() records failure_class 'contract' on the collector entry and a sidecar before throwing. trial-outcomes JSONL has a fail-closed writer and a data-only reader. * test(evals): pin the fail-closed rule-shard gate through the real --report path Synthetic slice artifacts for rule fail, timeout, missing slice, unreported entry, hollow, never-started, collector failure and wrong-slice reports all exit red before the panel-verdict gate change lands. * test(evals): retire every paid automatic retry Paid evals never retry (approved 2026-09-29): delete SHORT_CASE_RETRY_FILES and retriesWithinCaseCap, drop the retry fields from the registered wall rows (walls now cover one run plus reserve), make retriesForFiles return 0, pass --retry 0 explicitly, and drop --retry 1 from the package.json paid scripts. Add the eval:pass-rates alias. Tests that pinned the old retry allowance are updated as a policy change; review-finalization-budget now proves late-result recording under the production zero-retry arguments. * test(llm-judge): sample every judge as a pre-registered 3-sample panel Each of the 24 skill-llm-eval judges now draws EVAL_POLICY.judge.samples independent samples of the same prompt concurrently inside the unchanged JUDGE_MS budget. Numeric dimensions gate on the per-dimension panel mean against the unchanged threshold; booleans (would_browse, consistent) on a strict majority. An erroring sample fails the whole panel and is never resampled; a refusal is an unscored panel only when every sample refused. callJudge's 429 backoff stays: it is transport before any model output. The workflow-judge cache stores and validates only complete panels, and its identity now records the panel and zero file retries. Harness tests that pinned one provider call per case now pin the panel size. * test(evals): classify every live case and re-select a case when its kind changes E2E_KINDS: rule by default (191 E2E ids), 22 behavior cases whose verdict is a live model choice with an acceptable sub-100% per-trial rate, each with a BEHAVIOR_WHY tolerance, and 25 judge entries (the 24 workflow judges plus the fixed-fixture llm-judge-recommendation rubric check). Contract-shaped cases (ask-before-decide, plan-mode no-writes, mandated steps, secrets, the batching floor) stay rule. Behavior requires a known literal registration and an exact Bun test name so the case runs as its own trial shard. Map-diff selection now diffs E2E_KINDS and BEHAVIOR_WHY per key, and a base revision without them selects every key, so a kind flip runs the panel it introduces. test/eval-kinds.test.ts enforces coverage, tolerances, isolatability and the reviewed counts, printing the literal to add. * feat(evals): per-case pass rates with Wilson intervals, identity series and quarantine policy scripts/eval-flake-rank.ts becomes eval:pass-rates (eval:flake-rank stays an alias, and the legacy aggregate stays exported). It reads eval-store's trial-outcomes JSONL from the last N completed evals-periodic runs on this branch and main (gh, downloading only the trial-outcomes artifact, cached and size-capped, parsed as data), plus local eval dirs, and prints per-case per-trial pass rates with 95% Wilson intervals. A series is a case's own touchfiles minus GLOBAL_TOUCHFILES (caseSeriesIdentities, for the report job to stamp), per model, CLI version and policy version. Labels: INCONCLUSIVE, BROKEN, FLAKY, FAILING, PASSING. --backfill imports legacy slice artifacts as pre-policy trials (first attempt only, attributed by registry id, never guessed) for display only. --gate fails with ACTION REQUIRED on post-policy evidence only: drift below the quarantine entry rule, a rule case behaving like behavior, a one-sided Fisher drop against the previous identity (Holm-controlled), and quarantine entries that met their exit rule, expired after 8 weekly runs, broke the 10% tier cap or are invalid. CASE_QUARANTINE entries now carry a failureClass (detector, harness or model-latency); a product defect has no class and is never quarantined. The policy test pins EVAL_POLICY's approved constants. * feat(eval-pass-rates): attribute legacy records by the exact slug of their display name * ci(image): pin Claude Code 2.1.284 so the eval model is recognized 2.1.251 logs [claude-code:unrecognized_model] for claude-fable-5-1, the eval capture/judge default. 2.1.284 does not. The gate PTY smoke subset (plan-ceo/plan-devex plan-mode, plan-mode-no-op) parses on the new TUI; plan-design-review-plan-mode passed at 293 s on 2.1.284 and timed out at 300 s on 2.1.251 on the same tree. * test(eng-batching): grade the floor once the review report is complete A completed GSTACK REVIEW REPORT ends the review, so the review-question count is final there. Run 36606688266 wrote its report at 1,248 s and closed the session at 1,318 s; the case now stops collection and applies the unchanged floor at the report instead of waiting out the session. No budget changes. * test(eng-batching): bind unsourced native briefs through the report's target Run 36606688266 asked ten separate native review questions (D1-D9 bound to ledger records R1-R9) and failed reviewCount=0 < FLOOR=3: its briefs named the plan by title instead of citing PLAN.md, its report declared 'Review target (fixed): PLAN.md' under '# Engineering review: <plan>', and it kept an unfenced copy of the plan's own H1. The named-source route now accepts those spellings and non-inline ledger briefs. The same replay rejects a foreign, mixed, duplicate or missing target, another plan's title or copied H1, a brief naming another plan or file, a mismatched saved brief, and re-asks. The run-36597762183 capture still counts 3. * fix(plan-design-review): treat a designer with no API key as unavailable Both proof runs (36597762183, 36606688266) printed DESIGN_READY, hit 'No OpenAI API key found' on the first $D variants call, then hand-built HTML/CSS wireframes, screenshots and a comparison board for ~195-245 s before the first review question; the second run timed out at 600 s. A failed first generation now takes the existing text-only path, and the skill forbids substituting hand-built mockups. * fix(deslop-shared-libs): read related sources together within the turn limit Run 36606688266's opportunity audit read sixteen sources one per turn and stopped at error_max_turns; the passing run 36597762183 read the same files in three batched commands. The skill now says turns are bounded and asks for parallel reads or one read-only command per step. * test(ceo-mode-routing): submit a mode review that scrolled past the viewport Run 36606688266 bundled routing, learnings and the mode choice into one native call. Its review panel was taller than the terminal, so the tab bar scrolled off, ceoModeSubmissionInput returned null for 240 s and HOLD SCOPE was never submitted ('no posture match'). With no bar on screen the viewport must still end at the focused Submit prompt, and the accumulated screen text supplies the one complete panel, authenticated exactly as before. Replay controls reject another mode, an unoffered answer, an altered question, a quoted panel, trailing output, a moved cursor and an answered or changed call. * docs(evals): document the pre-registered verdict policy, quarantine, pass-rate history and arithmetic AGENTS.md replaces the retry rule with the approved policy text (no retries; kind fixes trials; no added trials, samples or dispatches after a result; quarantine by CASE_QUARANTINE only; one INFRA/INCOMPLETE re-dispatch) and notes that a pre-registered fixed panel is not rejudging. CONTRIBUTING gains the kind rules, the judge panel, eval:pass-rates and an 'Add a paid eval' checklist. TESTING_INTERNALS describes verdicts, quarantine, history and the arithmetic, including the rule term: 1 trial vs 2-of-3 red rates at p = 0.99/0.95/0.90/0.70/0.30 and lane all-green probabilities for the current 191 rule / 22 behavior / 25 judge registry. * feat(evals): trial planner, slice exit split and panel-verdict report Planner: behavior and quarantined cases become panels of isolated trial shards (<file>#<id>~t<N>) bound by EVALS_SELECTION_JSON=[id] and the exact test name; the file shard excludes them by name. Trials of one case never share a slice, result slugs are unique, panels are validated whole, unknown registrations throw, and the planner prints a capacity preflight. Executor: each trial shard gets its TRIAL_ENV identity and a trial record (outcome, failure class, cause, cost); every shard writes a JUnit report. The slice exit now means execution completeness: a failed rule shard or a trial without a record reds the runner, a failed trial does not. Report: panelVerdict() decides every panel of the first run attempt (later attempts are reported, never replacing it); rule shards keep the unchanged fail-closed checks; collector records all count (no last-attempt wins); census runs enforce the quarantine cap and expiry. It writes collector-outcomes v2, trial-outcomes.jsonl (trials plus JUnit rule/judge cases), report-summary.md, and one headline + failure block with rerun commands, and flags INFRA/INCOMPLETE-only reds for the one re-dispatch. The fail-open suite gains the panel cases: behavior 1/3 red, 2/3 green with its failed trial shown, missing trial INCOMPLETE, contract at 2/3 red, quarantined 1/3 green, 0/3 and contract red, missing slice red, and a later attempt never replacing the first. * chore(evals): refresh paid duration seeds from proof runs 36597762183 and 36606688266 Both tiers, merged in run order (the later run wins). Notable: split-overflow 1332s -> 504s, section-loading 604s -> 342s, mode-routing 575s -> 444s; multi-finding-batching 734s -> 1318s (its red path in run 36606688266). * feat(evals): stamp trial series identities and fit panels to the live registry - scripts/eval-trial-series.ts stamps series_identity (eval-flake-rank's caseSeriesIdentities) on a report's trial-outcomes JSONL as its own step, keeping the history tool out of the paid runner's closure; TrialOutcomeRecord gains the optional series_identity field. - Slice-count plans let a registered trial spill into an ordinary lane when its siblings hold every long lane, so panels never share a runner. - Re-audited test-selection.ts (Stream B added the E2E_KINDS/BEHAVIOR_WHY map-diff; no new module loading) and repinned its hash. - Detach and release floors now count trial shards (66 periodic trials in 22 panels): periodic floor 33,821s, still under eval:bg:periodic's 67,380s. - Coordination fixtures supply the executor's trial records. * ci(evals): attempt-scoped artifacts, verdict-v2 PR comment, weekly pass-rate gate and one INFRA re-dispatch - Slice, census and marathon artifacts carry -a<run_attempt>; reports download them per artifact (no merge), so records never overwrite and a re-run never replaces the first attempt's verdict. - Planners pass --max-parallel for the capacity preflight (24/16 unchanged: the refreshed periodic plan needs 24 slices, the gate census 12). - PR comment: jq-only job reads collector-outcomes v2 (headline, sanitized failure block); the group_by(.name)|last recomputation is gone. - Reports stamp series identities, upload trial-outcomes-* for history, and shard logs upload always (a failed trial no longer reds its runner). - Weekly report: headline + failure block of both lanes in the issue body, the eval:pass-rates --gate step (fails closed without history), close the issue on a green run, and UC-E1: when every red is machine-classified INFRA/INCOMPLETE, one re-dispatch as a new run in its own concurrency group (redispatch_of), both runs reported. * feat(evals): planner-side whole-panel reuse and negative receipts The planner job restores this PR's receipt store once and ships a single filtered set with the plan: a pass or panel receipt with a same-or-newer FAIL for its input identity is dropped, and a panel receipt ships only as a whole PASS panel (re-verified with panelVerdict) from one run. Executors read only that set (no per-slice cache restore or save), so every trial of a panel sees the same receipts; a trial reuses its own record from the panel receipt, keeping a split PASS's failed trial. Trial identities drop the trial index (run-scoped) and bind the panel policy. Executed shards carry their input identity; the report turns a whole fresh PASS panel into a panel receipt and a FAIL panel or failed rule shard into a negative receipt, and marks a panel that mixes reused and fresh trials INCOMPLETE. The report job merges plan, slice and report receipts (newest per file) and saves one store per run. Also fixes two TS2352 casts in browse/test/dia-macos-qualification.test.ts whose diagnostic text drifted with program order (baseline locked, fix only). * feat(evals): --case/--trials local diagnosis and panels in local sharded runs bun run scripts/test-paid-shards.ts --case <id> [--trials N] runs N independent trials of one case through the CI panel runner (trial shards, TRIAL_ENV identity, name-pattern isolation) and prints its panelVerdict(); N defaults to the case's policy panel and CI never reads it. The local sharded path (test:gate:sharded, test:periodic:sharded) now plans the same trial shards and exclusions as CI and exits on execution completeness plus panel verdicts. * test(pty): grant an owned Create pane whose title row is cropped The targeted batching rerun on Claude Code 2.1.284 left its first report Write unanswered for 1,372 s and timed out: the viewport began at the pane's relative file row and rule, with the 'Create file' title cropped above, so the preview parser rejected the file row as foreign. That row must now resolve to the owned path and is skipped before the unchanged line-by-line preview match. Replay controls reject another file, another directory and an edited preview row. * fix(evals): tsx-safe generics in eval-flake-rank, legacy artifact names, no-retry wall docs * test(evals): record the read-only and detector-row invariants as contracts shared-libs-opportunity-judgment and review-design-lite are behavior cases: their recommendation and checklist judgments may vary, but the read-only invariant (commands, provider requests, fixture bytes, hooks, state) and the deterministic fake-engine detector rows are contracts. Both now go through expectContract, so any failure vetoes the panel. * test(judges): sample the recommendation rubric as a panel; never re-ask armJudge llm-judge-recommendation is a judge case: each fixture now draws a 3-sample judgePanel, gates reason_substance on the panel mean and the present/commits/has_because checks on a 2-of-3 majority, thresholds unchanged. armJudge no longer re-asks on a malformed verdict; it is a failed sample, as the judge policy requires. * test(evals): record a pre-turn API or CLI failure as infra recordE2E sets failure_class 'infra' on a failed session whose runner reports error_api, timeout_startup, error_output_stream or a non-zero CLI exit with zero turns and no assistant event. A model refusal, a timeout after model work, max turns, or an explicit caller pass/class keeps its ordinary classification. * test: pin every-record outcome counts and the twelve doc-sync callbacks * test(eng-batching): read the report target as a field, not a spelling The next targeted rerun (Claude Code 2.1.284) again asked eleven separate native questions and again counted zero: its briefs named no plan and its report declared '- **Review target (fixed):** `/abs/PLAN.md`' under '# Eng Review — PLAN.md: <plan>'. An unsourced brief now inherits the one current target field that names a PLAN.md file, whatever its list or emphasis markup; its ledger record still supplies the cited finding and must reproduce the brief exactly. A brief that names its plan must still match the report title. Replays of all three captures count 9, 9 and 3; controls reject a foreign, duplicate or missing target and an archived title. * fix(evals): --case list mode and name precheck; case-shard qa-callers; refresh batching and design-with-ui seeds * chore(release): v1.91.9.0 * test: settle the post-response composer before seeding; give the TPA recorder adapter its infra helper submitPlanSeed accepted a stale empty composer when the transcript recorded end_turn before the CLI repainted (late-repaint-typed-current fails 5/5 on the old helper, passes 5/5 now). The TPA recording fixture extracted recordE2E without isPreTurnInfraFailure, so every failed case threw before recording. * test(autoplan-dual-voice): unwrap Claude Code 2.1.284 subagent hand-back frames; accept read-only probe diagnostics; record before asserting Census run 36626737820: the native CEO report arrived framed and indented, so its INPUT line never matched, and the model's exact probe plus two variable echoes was not canonical. A column-zero line inside a frame, command substitution, backticks, redirects, assignments, CODEX_MODE echoes and output line-count mismatches stay rejected. The failure now records before asserting. * ci(image): keep Claude Code 2.1.251; test(ceo-mode-routing): keep HOLD's own deferrals in scope before assessing its rigor decision 2.1.284 enables per-turn effort for claude-fable-5-1: in gate census 36626737820, 66 of 84 sessions ran longer than on 2.1.251 (+20% session time, +32% thinking tokens) and 11 cases timed out on unchanged budgets. HOLD SCOPE's 0G step asks its own defer/keep menu; the actor answered it Defer and the assessment then judged that scope question as the rigor decision. The actor now answers that menu Keep and assesses the next one. * test: attribute quoted prior-record field lists, state the judge reason bound in its schema, move split-overflow to marathon Census 36629958451 reds: - outside-plan-disabled-no-fallback: the model quoted the pre-existing record as a parenthesized field list with its exact timestamp; attribution now requires that exact timestamp and the record's own field values. - plan-devex-peer-comparison-classification: the judge correctly returned missing but wrote a 1069-character reason, voiding the judgment; structured outputs cannot enforce maxLength, so the bound is stated on the field. - plan-ceo-split-overflow ran 504-1188 s as one PTY flow and set the periodic lane's wall clock; it now runs weekly in the marathon lane. * test: supply holdDeferKeepIndex to the CEO routing mocks and follow split-overflow into the marathon lane The registered-callback fixtures mock ceo-mode-option and lacked the new export; the split fixtures asserted the periodic tier; the registered-budget check looked for split-overflow only in the periodic manifest. * fix(qa): checkpoint receipts print the report link for their exploration file qa-functional-webhook-report failed in two of three censuses because the report linked .qa-evidence/NNN capture folders as "checkpoints" and never linked exploration-NNN.json. The checkpoint receipt now prints link: [checkpoint NNN](exploration-NNN.json), and the functional report template says capture folders are not checkpoints. * docs: final census numbers in the v1.91.9.0 entry; file the paid-eval follow-ups * ci(evals): name the PR-comment loop's unused fields so shellcheck passes (SC2034) * fix(plan-ceo-review): tighten expansion pacing wording to fit the skeleton cap after the main merge The merged skeleton measured 80,166 bytes against its unchanged 80,150 cap. Same instructions: ask separately for each addition, in turn, with no pacing menu; lead each proposal with the felt experience, then shape, effort and impact. * fix(eval-pass-rates): match trial-outcome files by basename so Windows backslash paths are read * fix(evals): repair proof-run reds in design-consultation, document-release, design and QA fixtures - design-consultation Phase 1 asks one brief that confirms context and decides research; the confirm-only first question scored substance 2. - document-release defines ship-owned inputs, exact steps and the JSON result, and drops stale spawned-from-/ship text (judge actionability 3.67 -> 4/4/4). - plan-design-with-ui accepts the Step 0D focus menu the same way the shared picker does ("focus on specific ones?"). - plan-design-review plan-mode saves in three Edits instead of one final Write. - QA functional annotations ask for the full 40-character revision. - Outside-disabled attribution judges quoted prior-record data by its exact timestamp or a dated, pre-existing-record sentence; four captured phrasings replay clean and current claims still fail. - --case can select autoplan-dual-voice by its literal test name. * test(design): revert the three-Edit plan-mode flow A focused paid run still timed out at 300 s: the first three passes alone took 150 s of thinking. The case stays a named timeout red rather than cutting review depth. * test: accept 'review mode = X' auto-decide declarations and parenthetical scope exclusions in the shared-libs actor auto-decide-preserved: the product auto-decided HOLD SCOPE and said "Decision: review mode = HOLD SCOPE"; the grammar knew only "is" and ":". shared-libs-plan-callers: the recommended option said "(no hardening)" and the actor read "hardening" as an expansion. Both replay the captured text, keep negative controls, and passed focused paid runs. * fix(review): pass Review Army checklists by path, run research alongside dispatch, always probe the design detector; state review-log invocation and statuses in the caller fixture - review-army-perf-n-plus-one: the parent copied full checklists into agent prompts and ran web research before dispatch (290 s on a 12-line diff); 212 s now. - review-design-lite: 5 of 6 captured trials reported the detector absent without probing; the probe is mandatory and its first line is reported, and the contract credits only fake-engine rule ids the checklist never names. - review-exploratory-small-cli: the fixture never gave review-log's direct invocation or status vocabulary; the model ran it through bun and wrote status "blocked". The prompt states both and the validator rejects out-of-vocabulary review statuses. Each case passed a focused paid run after repair. * docs(changelog): proof-run product fixes * fix(ship): always run the design-lite detector probe; test(shared-libs): credit a failed first file view and deferred-reuse Skip wording - /ship design-lite: the probe is mandatory and any non-ready first line is stated, matching /review (5 of 6 captured /review trials had skipped it). - shared-libs-pr-coverage: the first PR 42 page-1 read printed only a jq error, so the one refetch is a legitimate recovery, charged to the same budget. - shared-libs-review-prior-coverage: the Skip option said a future review can "reuse it once snapshot coverage holds"; a conditional tail on the recorded decision is not product work. Captured-text regressions and negative controls. * fix(ship,qa,document-release): repair proof-run regressions and fixture gaps - ship-docsync-completion: yesterday's audit-scope result dropped the section's status, so /ship spliced one in; the section now opens with **Status:**. - ship-docsync-missing-asset: a missing section or old Ship-owned mode blocks before launch. - ship-docsync-late-result: the invocation record says prepare already saves the candidate selection (no extra Read; budget unchanged). - qa exploratory: await the method Reads before the first probe. - qa-callers fixture: quote the real review-log record template; allow the git log command plan-completion prescribes. - qa functional observer: a receipt caught mid-link(2) is checked at stop instead of failing with ENOENT (reproduced from CI). Each repaired case passed a focused paid run. * ci(image): pin Claude Code 2.1.284, the version users run Request-body capture shows both 2.1.251 and 2.1.284 send effort "high" to claude-fable-5-1; 2.1.284 adds the model's own profile. The slower 2.1.284 census was mostly API latency: its SDK-only judges were 25% slower too. Nine previously slow cases pass on 2.1.284 within unchanged budgets. * test: one owner per case id, a structural devex 0B setup rule, and correct design/gbrain actors - plan-design-review-plan-mode was registered by two files; the PTY smoke is now plan-design-review-plan-mode-smoke, and a registry test requires one owner per case in case-sharded files. - plan-devex-finding-floor: the template's 0B narrative-confirmation question is classified as setup structurally instead of timing out a Haiku assessor. - setup-gbrain-remote: the actor accepted 'skip' on the MCP-registration question the test asserts; it now accepts that question and declines others. - design-review-plugin-handoff: the fake engine cited a file absent from the fixture repo and index.html linked a missing styles.css. Captured-question regressions with negative controls; each case passed a focused paid run. * test: PTY harness handles clipped reviews and bundled setup tabs; AUQ judge uses structured output; design-consultation carve declines optional outside voices - ceo mode routing: a Submit review taller than the viewport, a setup tab bundled after the mode tab, and a clip through the mode question each hung or misread the run; the native answer is still verified after Submit. - judgeRecommendation requests a 1-5 enum schema; a malformed Haiku reply had scored substance 0 for a 4/5 brief. Judge failures now propagate. - carve section-loading for design-consultation declines the optional outside voices (a supported path) and treats DESIGN.md as the report; timeout unchanged. The Step 0E handoff defect is not fixed (0/15 samples across four wordings, none shipped) and is filed in TODOS. * test: fold the design-consultation completion replay into carve-section-sharding (test-of-test ratchet) * docs(todos): record the pre-push hook shard-order hang * test(qa-callers): disable git auto maintenance in the fixture repo (same guard as shared-libs; from #3002) * test(office-hours-attempt): the fake judge SDK response carries stop_reason like the real API (structured judge requires end_turn) * fix(qa): the caller STOP line says to await the method Reads before any probe ship-exploratory-plan-checks: the model read exploratory.md and sent a capture in the same response, before seeing the section's own await rule. * fix(qa): number the qa value-bar questions from 1 and say reproduced bugs already answer the first two * fix(qa): define evidence.json where it is built, point the preparation gate at the next section, name measured command durations in the report template Recurring qa/qa-only workflow-judge complaints in CI (clarity/actionability 3.33). * fix(plan-eng-review,review): a disallowed question tool is not headless; report kept tests only when some were skipped * fix(plan-eng-review): keep the headless-rule contract phrases adjacent * fix(evals): cut path variance at its measured sources - gstack-qa-evidence capture prints startedAt/completedAt/durationMs and, for --deadline captures, remainingMs; the functional report takes durations from them. The section clock notice asks for one clock read up front instead of one after every checkpoint (QA runs spent 7-14% of tool calls on date -u). - ship plan-completion: skip the audit dispatch when discovery already found no plan (the dispatch-vs-skip conflict produced an optional 60-100 s subagent). - materialize/checkpoint validation errors state the expected schema, so a rejected annotations file is fixable in one call instead of blocking the phase. - session-runner counts turns from the transcript when a run times out, so timeouts stop reporting 'turn 0'. * fix(evals): count timeout turns only from object transcript events * test(qa-callers): deterministic child transport, completion-time handoff reads, compact phase report The exploratory caller cases exist to prove the caller starts and bounds exploratory QA. Their native adversarial reviewer (review) and plan audit (ship plan-checks) now come from recorded child outputs instead of a live subagent, handoff freshness reads are required before completion records rather than every bookkeeping log, and the phase report is compact. Measured: 194-257 s per case against 208-284 s before, no subagent calls. * test(ship-docsync): seed fault cases at their gate instead of replaying attempt 1 The post-dispatch fault cases (missing-marker, launch-failure, timeout-unsettled, late-result, stale-before, stale-after, recovery) now start from a fixture-owned attempt 1: the real actor prepares and dispatches it, its verbatim output is saved once, and the invocation journal carries its pre-dispatch entry with the child asset hashes. The model resumes at Parent processing with a trimmed read list, inspect named as the authoritative repository observation, and recovery's intermediate checkpoint folded into the next attempt's pre-dispatch entry. Assertions count only parent-issued transport events and require a read of the saved attempt-1 output; missing-asset and the legacy failure case keep the full model-driven first attempt, and their prompts are byte-identical. * test(ship-docsync): name the seeded read list and cap journal/report length The first seeded stale-before run spent calls locating documentation.md (two ls sweeps), reading through cat and re-Reading the record before Edit, and ~40 s composing 1.5-2.2 KB entries and report. Name every seeded read path, ask for native Read, and bound entry/report length. * test(ship-docsync): trim the seeded parent's measured model time Measured on the seeded runs: one read the 78 KB ship/SKILL.md, the post-child freshness comparison spent 18-32 s of thinking over full inspect contents, and the final response restated the report (~1.1 KB). Say the phase excerpt stands in for ship/SKILL.md, compare hashes first and read content only for changed paths, and end with one status line. * feat(qa-evidence): enforce the checkpoint sequence and fill report bookkeeping in code - capture refuses to run another probe until a checkpoint anchored on the latest complete capture names this capture as its next command, and every complete capture prints that requirement. - materialize fills revision, runtime, cwd and learning (checkpoints whose next native command differs) when omitted and prints the reportLinks the report must include; the QA section shrinks accordingly. * test(qa-callers): hand the caller phase its invocation-start observations and review token; fix(next-version): fetch without auto maintenance - Every caller case receives the diff, status, log, untracked list, HEAD and an already-captured review start token, so the phase spends its budget on the contract under test instead of re-running setup reads. - gstack-next-version's fetches pass --no-auto-maintenance. On git 2.55 a completed fetch forks detached maintenance in the caller's repository; the free suite's live smoke test ran it inside the CI checkout, and every shard-12 pre-push hook hang so far followed a completed smoke fetch. * feat(deslop-shared-libs): route every Git read through bin/gstack-safe-git The skill made the model retype a long safe-Git prefix on each call and a dropped flag failed shared-libs-read-only. bin/gstack-safe-git applies the fixed env + flag prefix, adds --no-ext-diff --no-textconv to log/show/diff, allows diff only between two explicit object IDs and ls-files only in the NUL-delimited overlay form, and refuses every other shape with one line naming the allowed forms. The template now points at the installed helper (host global runtime via {{SAFE_GIT}}) and drops the prose it enforces. Fixtures resolve the helper to this checkout, the git shim records the safety environment, and isGuardedGitRequest requires the complete prefix (env included) for every repository read. * test(shared-libs): tee to a discard device is not a file write Paid shared-libs-opportunity-judgment t1 on 1213b01 failed read-only on '... | tee /dev/null | sha256sum'. The detector flagged any tee operand while the same devices are allowed for redirection. tee now fails only when an operand is a real file; tee to a file, -a file and -- -a stay violations. * fix(qa-evidence,observer): reject placeholder metadata and replay-only learning; declare the docs atomic-write target - materialize measures revision, runtime and cwd itself and rejects supplied values that differ (CI run wrote revision "HEAD" and runtime "bun"), and refuses learning checkpoints that replay the same probe, naming the fix. - The docs write observer treats Claude Code's atomic temp for the authorized doc target as transient, so a temp renamed before its per-file watch no longer marks the observation incomplete (ship-docsync-completion flake). Per-file monitoring outside declared targets stays fail-closed. * test(qa-functional): fix mode requires only the happy scenario from the model (carried byte-identical from #3002 183b01f4..3e6074b4) verifyQANativeRegression already reruns all eight webhook scenarios on the repaired source, so the model-side eight-scenario requirement in fix mode duplicated harness coverage and pushed qa-functional-webhook-fix past its budget. qa-only still requires every scenario. * fix(deslop-shared-libs): probe the audited repository with -C <repo> A CI run probed safe-git from the session directory above the target repo, so the capability probe never touched the repository and the run fell back to the API without a local attempt. The probe (and any call from elsewhere) now names the audited repository. * test(qa-deadline): never attach a reader to the full-pipe fixture's stdout The full-pipe receipt test attached a 'data' listener (flowing mode) and then paused; on CI the reader could drain the 2 MB write before the pause, so the receipt write never blocked and the helper exited 0 in ~126 ms. The stdout pipe now stays unread until the assertion, which is what the test means to model. * feat(qa): helpers answer --help, and the QA eval interfaces declare it Approved by Garry: asking gstack-qa-evidence or gstack-qa-deadline for usage is read-only, so both helpers print usage and exit 0 on --help (the evidence usage now names the annotation shape), and the functional and caller command allowlists accept exactly 'bun <path>/bin/gstack-qa-{evidence,deadline} --help'. Two CI runs failed only on that call. * fix(qa): after an input change, a probe is affected unless shown otherwise CI late-input run finished in time but revalidated only the happy probe after the locale input changed and reported the stale adverse probe green. The revalidation step now treats any probe not shown to be unaffected as affected. * test(shared-libs): seed the lifecycle replay's first Step 3 pass instead of replaying it shared-libs-review-lifecycle ran ~88% of its 300 s session budget (12-run census median 265 s, 4/24 sessions timed out). The fixture now executes pass 1's Step 3 once with the real logger and Git: a real unused REVIEW_START, then the diff, inventories, attributes/config/index flags, gstack-review-read output and every file's bytes and sha256, saved to one observation. The model resumes at Step 4 with an exact four-file first read, the observation named as the authoritative pass-1 repository read, one post-fix verification, an explicit pass-2 read list and a twelve-line summary. Pass 2 still runs its own --start, diff, reads, fingerprint and stage actor before --finish. The actor scope now states that a current settled final-pass actor result supplies the replaced QA/adversarial prerequisites and that the no-credit disclosure is a reporting label: one r1 session persisted completed:false from that ambiguity. New assertions: the final binding never uses the seeded token's start or tree, and the observation was read; free controls finish the seeded token (binding changed) and omit the observation read, and both fail. * test(shared-libs): trim the resumed review replays' setup and report Every sibling review session (revalidation, path-eligibility, index-flags, prior-coverage) loaded qa/sections/exploratory.md and often scope.md although its QA and native adversarial results are supplied synthetic inputs, then spent a second request on shared-code-reuse.md and base metadata. The resumed scope now states that the supplied results replace Step 4's QA method loading; the revalidation contract names one first response (workflow, checklist, finding, prerequisites, shared-code-reuse.md, base metadata) and caps the summary at twelve lines. Receipt order, direct source reads, the checker, the question and final persistence are unchanged. * fix(review): define what a Step 5c Skip option says Step 5c named "B) Skip" without saying what its description may claim. Two CI captures (path-eligibility on131d43be, index-flags on4643cb85) offered a Skip whose description added effects beyond declining: "The extraction can be applied in a later editing review pass" and "replacing the invalidated prior Skip". Those read as change commitments, so the no-change actor refused both. Step 5c now says to describe Skip only as no code/index change with the Skip recorded; adjacent lines are compacted so the review parity caps hold unchanged. Both exact packets are kept as a free regression: still refused, and accepted once Skip follows the rule. The actor's classifier is unchanged. * fix(qa-evidence): every complete capture needs an evidence row; test(tpa): accept the hyphenated app-specific-password spelling - materialize refuses when a complete capture has no evidence row and is not named in limits (CI cli-report omitted capture 004), naming the missing IDs. - tpa-apple-ban's detector required 'app-specific password' with a space; the CI answer said 'app-specific-password path' and was otherwise correct. * test(qa-observer): fix mode treats atomic temps of authorized src/test writes as transient CI webhook-fix failed with 'Could not watch test/worker.regression-1.test.ts.tmp...': Claude Code's Write renamed its temp before the per-file watch was added. The functional eval now tells the observer its mode, and a temp whose target that mode may write is observed through its directory watch. Report-only mode and undeclared paths keep failing closed. * feat(qa-evidence): refuse evidence observed on an older input snapshot than the latest capture When native probe output declares a top-level input snapshot, materialize compares each evidence row with the latest capture's snapshot and refuses stale rows unless they are classified superseded, naming the captures to rerun. ship-exploratory-late-input kept reporting a pre-change adverse probe green after the input changed. * test(qa-functional): point the fixture at the helper's --help instead of its source A CI webhook-fix run spent three turns reading lib/qa-evidence.ts to learn the interface and timed out just before materialize (agreed with #3002's owner). * feat(qa-evidence): captures list the caller's declared-but-unrun required probes GSTACK_QA_REQUIRED_PROBES (a JSON array of native child commands) makes every capture print requiredRemaining; it never judges pass or fail. The functional eval passes the webhook list from QA_WEBHOOK_REQUIRED_SCENARIOS, which the verdict now reads too, so the nudge and the verdict share one source (agreed with #3002's owner). CI webhook-report kept stopping with scenarios unrun. * test(review-army): record N+1's pre-dispatch stages and scope the session to Step 4.5 review-army-perf-n-plus-one timed out in 7 of 13 CI runs on this branch (passing 245-280 s of 300). Each session spent ~95 s on setup (the full extracted SKILL, checklist, section greps, exploratory.md, diff-scope/stats/learnings, tooling checks), ran Step 4's core pass, a search-before-recommending WebSearch, and wrote a 10-16 KB report (~100 s after the Red Team returned). The fixture now stages only review/sections/review-army.md plus the performance and red-team checklists, and hands the session the recorded detect-scope, specialist-stats and learnings outputs and the diff. The caller passes --performance (every CI parent already treated the prompt as that force flag against the <50-line skip), declares the core pass, QA, adversarial review, web research, Fix-First and persistence out of scope, and caps the report at the selection line, the SPECIALIST REVIEW block and the Red Team result (30 lines). The Performance specialist and the conditional Red Team are still real foreground subagents, and the report still has to surface the N+1. New assertion: a foreground Performance specialist dispatch precedes the Red Team dispatch. Free controls omit the Performance dispatch or background it, and both fail; the budget lifecycle adapter supplies the current result shape. Touchfiles now include the .rb fixture the case reads. * test(review-army): share the recorded Step 4.5 staging with consensus and supply its Red Team review-army-consensus (periodic) timed out in 2 of 13 census sessions; passing runs took 213-297 s of 300. Like N+1 it spent ~30-50 s reading the whole extracted SKILL, checklist and every specialist file, sometimes dispatched an unrequested Maintainability specialist, then ran a Red Team (60-70 s) and a second merge before writing a 9-15 KB report. The N+1 staging and scope text move into stageReviewArmySession / reviewArmyScope / reviewArmyChecklists (the N+1 prompt renders byte-identical). Consensus now records its detect-scope, stats, learnings and diff, stages the Review Army section with the security and testing checklists, forces --security --testing, and caps the report like N+1. Its Red Team is outside the multi-specialist contract, so the fixture supplies a labeled synthetic NO FINDINGS result instead of a dispatch. The existing SQL-finding and browser-error assertions are unchanged; the lifecycle adapter's spawnSync now returns the git output the staging reads. * docs(changelog): v1.91.10.0 records the flake census and its repairs * test(strict-output): give the spool-prefix child time to finish before the pending stream times out windows-free-tests failed on9a7a7e54: the 150 ms shared deadline raced Bun startup on Windows, so the child was killed mid-write and the spool held a partial payload. Only the never-released extra stream should time out; the child now has 3 s. * fix(qa-evidence): accept a single limits string; test(qa-callers): read the handoff first when a probe snapshot changes CI late-input spent a turn rewriting limits as an array after materialize refused a string, and a ten-read sweep hunting for the changed input before it read reports/HANDOFF.md, then timed out at 300 s. * test(autoplan-dual-voice): unwrap the framed native report before Claude Code 2.1.284's agentId/usage trailer * test(section-loading): credit a Bash print that contains every line of the carved section * test(auto-decide): ask for the selected mode in the skill's mode handoff line, not a separate public decision * test(plan-ceo floor): scope preservation approves no premise, approach or remedy * test(autoplan-dual-voice): the fixture declares that delivered bash blocks run alone, diagnostics separately * test(coverage-audit): a fenced plain-word caption in a successful && read chain is display only Census 36776104571 plan-eng capture read both owned files with cat -n in one successful && chain; the caption 'echo "=== git diff main --stat ==="' fell outside the two-token caption grammar, so both reads lost credit. Accept a fenced caption of plain words; unfenced command strings, expansions, redirection, -e escapes and ; / || tails stay rejected. * test(office-hours): a fork whose outer options are the seeded shapes is the Phase 4 question Census trials 1-2 captured complete Phase 4 forks (A) Server-side B) Client-side C) Hybrid, recommendation with because) whose prose used none of the vocabulary words. Accept two seeded shapes as outer options as Phase 4 specificity; the earlier-phase, nested, fenced and single-shape controls still fail. * fix(review): design-lite rows keep the detector's [rule-id]; the e2e detector rows point at the diff The output template had no rule-id slot, so rows merged with checklist items dropped the detector id (census t2, local t1). Rows now carry [rule-id]. The fake engine's sample rows named a foreign fixture path at line 0; the e2e remaps them to landing.html/styles.css so trials stop spending turns reconciling it. * test(shared-libs): the plan actor reads scheduler parity and unchanged-scope lists Census 36776104571's question preserved the contract ('behaving exactly like the scheduler', 'scheduler parity holds by construction') and excluded work with 'Existing copies and helper hardening stay unchanged'. Accept exactly/parity as preservation (negated forms refuse) and a bare noun list that stays unchanged as an exclusion for the expansion scan only; verb-led clauses still refuse. * fix(qa-only,qa): name the exploratory read point and finalization order; judge qa with its browser assets qa-only judges cited 'next section' pointing at the wrong heading, an exploratory trigger that contradicted its read point, clock ownership in mixed runs and the unstated order of exploratory section 4 vs reporting. The qa judge penalized the absent qa-report-template and issue-taxonomy that qa-patterns loads; with them in, it found issue-taxonomy's dangling 'rule 13' (the consent rule is browser rule 3). * test(ship-docsync): seeded attempt 1 counts toward the limit; transport counts ignore calls that never reached the state file - CI launch-failure retried after the seeded attempt 1 as if that attempt were the fixture's; the seeded prompt now says attempt 1 is this invocation's and a further attempt needs what Blocked recovery requires. - A late-result run typo'd the state path once (ENOENT, the actor never ran), then repeated the call correctly; the per-action count compared both calls with one actor event. Only calls naming the real state file are counted. * fix(plan-eng-review): show the accepted dedicated read form for coverage-diagram sources CI plan-eng-coverage-audit mixed package/config and git diff into the source read; the review variant, whose prompt shows the && display form, does not. The plan trace step now shows it too, within the unchanged size cap. * test(sync-gbrain-readiness): a negation earlier in the claim clause is not a search/write readiness claim The census unknown actor wrote 'nothing about read, search, or write capability is confirmed either way' after a YELLOW/WARN verdict. The claim window started at 'write', so the leading 'nothing' was outside it. Check the clause subject for nothing/neither/none/no; keep the original in-claim negations. Replay of the captured output passes; positive controls still flag an unnegated claim. * fix(office-hours): a forcing question's recommendation takes the position the founder's words support auq-matrix office-hours asked D1 Demand as options about the founder's own evidence and, with no rule for that shape, recommended 'answer whichever is TRUE — A is marked recommended only because it is the strongest position' (substance 2). Say what such a recommendation is: the option the founder's own words support, why it matters for the next step, and what would change it. * fix(plan-ceo-review): name the mode preference command and the exact handoff line auto-decide-preserved at6fcb0981: the model never ran the preference check, read 'check ... through the preamble' as already done, auto-selected 'per your preference setting', and wrote 'Selected mode: HOLD SCOPE, auto-decided from your tuned preference' instead of the AUTO_DECIDE handoff line. At9a7a7e54it ran the check but wrote 'Decision: HOLD SCOPE is the review mode for ...'. Neither matched the handoff template the observer recognizes. Name gstack-question-preference --check at the point of use and say the handoff begins with the exact matching line. Collapse the audit block's comment padding to stay within the unchanged 80150-byte skeleton cap. * test(section-loading): record the CEO capture's report and transcript The6fcb0981census failed hasStaleFillRaceFinding (line 98), but the case records nothing beyond junit, so the report the detector judged is gone. Return the SkillTestResult from captureSectionReads and record it, with the full saved report, through the eval collector on pass and fail. * test(design): plan-mode names its read list and caps its additions and summary At6fcb0981plan-design-review-plan-mode timed out at 300 s (9 turns): 22 cat/sed chunk reads (~50 s), then a 28 KB plan Write (~150 s), before the read-back finished. The9a7a7e54pass took 240 s with a 24.6 KB Write. Read SKILL.md, review-sections.md and plan.md natively in one response, keep additions under 14,000 characters and the summary within ten lines. Budgets unchanged. * test(plan-mode-no-op): require prose evidence before a waiting verdict ends eng/design runs (carried byte-identical from #3002) With the prose fallback forced, the gate renders as a lettered menu; a judge 'waiting' verdict on a spinner-only frame ended the run as 'asked' before the menu rendered, so the scope-gate check failed on unchanged behavior. * feat(qa-evidence): materialize computes the phase verdict; callers must report it Approved by Garry: the helper, not the model, decides whether evidence can pass. materialize writes verdict {status, open} into evidence.json and prints it: fail or blocked from row classifications, inconclusive while any row is superseded, a complete capture is withheld, a declared required probe is unrun or there is no evidence, else pass. The caller fixture requires receipt.status to equal that verdict. CI late-input kept reporting pass with a superseded happy probe. * test(qa-callers): compare the receipt with the helper verdict only when evidence.json was materialized The producer free tests run captures without materialize; evidence.json is optional for callers, so its absence is not a verdict mismatch. * test(llm-judge): run the ship workflow judge at medium effort so its panel fits JUDGE_MS claude-fable-5-1 accepts only adaptive thinking (thinking.type.enabled with budget_tokens returns 400), so effort is the available thinking control. Measured on the exact ship judge request (105,301 input tokens): - default effort, 18 samples: thinking 5,086-10,881 tokens, 75.9-144.7 s; 3 of 18 passed the 120 s deadline (about 42% of 3-sample panels). - medium effort, 18 samples: thinking 2,749-5,762, output at most 6,144 tokens, 43.1-77.9 s; scores 4/4/4 in 16 of 18 (clarity 3 in two), versus 14 of 18 at default. callJudge gains an effort option sent as output_config.effort; only the ship judge sets it. Rubric, floors, panel size, deadline, model and max_tokens are unchanged. The cache identity records effort. * test(llm-judge): ask frontier workflow judges for 120-word reasoning under the unchanged 150-word check Told "under 150 words", the ship judge's reasoning landed at 130-156 words (3 of 18 probe samples at 152-156), so the structured-response check failed about one panel in three independent of effort. The prompt's frontier block and the response schema description now say under 120 words; the validator still rejects 150 words or more. The changed prompt bytes reach only the two frontier judges: ship/SKILL.md workflow (prompt and schema) and review/SKILL.md workflow (prompt). * test(llm-judge): type the stream transport mock call * test(plan-ceo floor): the request answers only the questions it names PR lane 36794871032 (head20d6e98f): the CEO floor ran 608 s without a question. Its Step 0 recorded the premise gap and approach choice as unresolved ledger rows, then said "this session supplies all answers up front, so no decision brief was dispatched" and wrote Sections 1-11.2734e203stopped scope preservation from approving the premise; this time the actor block (declined setup, recall, outside voices, HOLD SCOPE) and the fixture's "complete user request is available from the start" were read as pre-answering every review question. The CEO actor now states that the request answers only the routing, recall, outside-reviewer and review-mode questions it names. * test(plan-devex floor): a 'Partly wrong' 0B answer is the narrative confirmation PR lane 36794871032: the DX floor asked its D1 narrative confirmation (Accurate, proceed / Partly wrong, correct it / Way off, actual is...). The deterministic setup rule accepted only 'Some ... wrong', so the question went to the LLM assessor, which hit its 30 s spawnSync cap (ETIMEDOUT) and ended the case as assessment_error at 141 s, the same failure as census 36641820398. The rule now accepts 'partly' beside 'some'; the captured question is a free regression and the remedy-option controls still go to the assessor. * test(design-review plugin handoff): quoted report text is not an install command PR lane 36794871032: every behavioral check passed except noInstallOrOverride, which matched "no `npx impeccable`" inside the quoted heredoc that wrote detector-output.md. Nothing was installed or downloaded. The check now drops quoted-delimiter heredoc bodies (literal data) before matching; unquoted bodies, which can expand $(...), and unterminated bodies stay checked. Free controls cover the captured write, bare npx, an IMPECCABLE_BIN override, an unquoted $(npx ...), npx after the delimiter and an unterminated body. * test(review-army delivery audit): stage only the plan-completion section and record its git reads PR lane 36794871032: the case timed out at its 120 s budget after 7 turns (previous lane passed in 45 s). The session read the 46 KB extracted SKILL in three passes (cat to persisted output, grep, sed), ran its own git reads, wrote a 74-line report, then inspected and ran gstack-learnings-log and rewrote the report's Learnings section. As in the Step 4.5 cases (17ee2e54/2bd4651c), the fixture now stages only review/sections/plan-completion.md, hands the session the recorded git log and diff, declares the HIGH-impact question, its Scope Check, learnings logging and later steps outside the capture, and caps the report at the audit block and its DISCREPANCY entries (30 lines). The NOT DONE and email assertions are unchanged. * feat(qa-evidence): one capture call records the causal note for the previous capture capture R NNN [--public] (--deadline D|--timeout-ms MS) --after PREV --hypothesis 'TEXT' -- CMD publishes exploration-NNN.json {observationCapture, observationArgv, observed, hypothesis, nextCapture, nextArgv} before running CMD, refusing unless PREV is the latest complete capture. The receipt carries checkpoint/checkpointSha256; validators bind the note to the transcript's capture calls by capture ID and receipt hash instead of exact command strings. The separate checkpoint command and the capture guard keep working; materialize learning accepts both note shapes and still rejects same-probe replays. Prose and eval fixture prompts teach the merged form. * fix(qa-evidence): a superseded row stops holding the verdict open once its probe is rerun on current inputs materialize requires an old-snapshot row to be classified superseded, and its verdict kept every superseded row open, so rerunning the probe (what its own error tells the model to do) could never reach pass; late-input reran 3 and 9 on the new snapshot and still got inconclusive. A superseded row now closes only when a non-superseded row with the same captured argv observed the current snapshot. Re-materializing an already-published evidence.json names the cause instead of failing generically. * test(plan-eng batching): count saved decisions whose label drops the (recommended) marker or whose report is titled 'Eng Review Report — <plan>' * fix(qa): browser-only runs skip annotations/materialize; only Q captures can anchor evidence rows * test(design): plan-mode length is a drafting target, not a check to measure and trim * test(llm-judge): structured output for doc, outcome and posture judges so reasoning quotes cannot break JSON * test(ship-docsync): steer skill file reads to Read; large cat output becomes an unpageable preview * docs(changelog): browser-only QA evidence and structured judge output * test(qa-only cleanup): refusal scenarios get a 1 s budget and an absolute worker deadline; 300 ms starved under parallel load * fix(office-hours, design-consultation): ask the goal question and read the mode section first; ask the memorable-thing question on its own * test(outside-disabled): a record named by the retained record's own clock and then disowned owns its completed status * test(context-skills): install gstack-paths in the fixture bin; without it the model guessed the checkpoint root * test(ceo mode routing): SCOPE EXPANSION posture credits plural 'expansions' * test(ship-docsync): name the unmet atomic-replacement check on a forbidden temp-file write * fix(qa): browser-only runs materialize an empty evidence list with checkpoints in limits, matching /qa-only * test(qa callers): an accepted review-log record may cite checkpoints as finding evidence * fix(plan-eng-review): state that a disallowed question tool never qualifies as headless before the headless action * merge follow-up: re-record paid CLI parity for #2999's flags; trim merged review, qa-only and plan-eng wording toward the size caps * test(golden): refresh codex/factory ship goldens for the trimmed caller QA wording * test(coverage-audit fixture): disable git auto maintenance so cleanup is not racing a detached git writer * test(parity): raise review, qa and plan-eng caps to the measured merged size of #2999 and #3002 (each fit alone), documented per cap * fix(qa-evidence): materialize rejects an unrecognized classification before publishing, so the one-shot verdict cannot be locked inconclusive by a descriptive label
860 lines
58 KiB
Markdown
860 lines
58 KiB
Markdown
# 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.
|
||
|
||
```bash
|
||
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 1` for speed. As a contributor, use a full clone (no `--depth` flag) — you'll need history for `git log`, `git blame`, `git bisect`, and reviewing PRs against earlier versions. If you already have a `--depth 1` clone from following the README, promote it to a full clone with `git fetch --unshallow`.
|
||
|
||
### First free check (no API key, no browser)
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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
|
||
|
||
1. **Use gstack normally** — operational learnings are captured automatically
|
||
2. **Check your learnings:** `/learn` or `ls ~/.gstack/projects/*/learnings.jsonl`
|
||
3. **Fork and clone gstack** (if you haven't already)
|
||
4. **Symlink your fork into the project where you hit the bug:**
|
||
```bash
|
||
# 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 && ./setup
|
||
```
|
||
Setup creates per-skill directories with SKILL.md symlinks inside (`qa/SKILL.md -> gstack/qa/SKILL.md`),
|
||
links each skill's runtime assets alongside (sections/, templates, checklists — everything except
|
||
SKILL.md, tests, build output, and `.tmpl` sources), and asks your prefix preference.
|
||
Pass `--no-prefix` to skip the prompt and use short names.
|
||
5. **Fix the issue** — your changes are live immediately in this project
|
||
6. **Test by actually using gstack** — do the thing that annoyed you, verify it's fixed
|
||
7. **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.
|
||
|
||
### 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
|
||
|
||
```bash
|
||
# 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_MODEL` applies 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.
|
||
|
||
### Setup
|
||
|
||
Development and tests require Bun 1.4.0 or newer; CI pins and tests 1.4.0.
|
||
Earlier Linux versions can close unrelated live file descriptors during
|
||
subprocess garbage collection, causing intermittent browser and HTTP fixture
|
||
failures ([upstream diagnosis](https://github.com/oven-sh/bun/issues/34785#issuecomment-5020318035)).
|
||
|
||
```bash
|
||
# 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 | Command | Cost | 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 | `bun run test:e2e` | ~$4.20 | Full skill execution via `claude -p` subprocess |
|
||
| 3 — LLM eval | `EVALS=1 bun test test/skill-llm-eval.test.ts` | ~$0.15 standalone | LLM-as-judge scoring of generated SKILL.md docs |
|
||
| 2+3 | `bun run test:evals` | ~$4 combined | E2E + LLM-as-judge (runs both) |
|
||
|
||
```bash
|
||
bun run test:quick # Measured fast free subset for ordinary edits; not full acceptance
|
||
bun run eval:bg:pr # Changed fast live probes + selected quality judges, detached
|
||
bun run test # Final full free acceptance after focused repairs and source freeze
|
||
bun run test:ubicloud # Same suite on an ephemeral 16-vCPU Ubicloud VM; needs UBICLOUD_API_KEY
|
||
bun run test:e2e # Tier 2: E2E only (needs EVALS=1, can't run inside Claude Code)
|
||
bun run test:evals # Tier 2 + 3 combined (~$4.35/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. 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 locally.
|
||
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 to
|
||
finish in about 12 minutes including setup. The planner packs recorded wall
|
||
times (`scripts/paid-test-durations.json`, per tier) into as many ~9-minute
|
||
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
|
||
job timeout come from that plan. Preview it for free with
|
||
`bun run scripts/test-paid-shards.ts --tier periodic --list --slice-budget 540 --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 in `BEHAVIOR_WHY`.
|
||
- `judge`: an LLM judge scoring a fixed input; 3 samples of the same prompt,
|
||
gated on the per-dimension mean (booleans on a majority) against the
|
||
unchanged threshold. 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.
|
||
|
||
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](docs/TEST_PORTFOLIO.md#measurement-contract)
|
||
are machine-specific measurements. CI setup, build and queue time are reported
|
||
separately. Refresh measurements with `bun run test:ubicloud --record-durations`;
|
||
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](docs/TESTING_INTERNALS.md) 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](docs/test-audit-2026-09.md)):
|
||
|
||
| 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](https://github.com/garrytan/gstack/actions/runs/35642667809)
|
||
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](docs/TEST_PORTFOLIO.md#repeated-work-removed).
|
||
|
||
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](docs/TEST_PORTFOLIO.md#detector-owner-tests)); 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 and names the owner test to use instead.
|
||
|
||
Follow [Validation discipline in AGENTS.md](AGENTS.md#validation-discipline):
|
||
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 JSONL ledger artifact that `bun run eval:flake-rank` folds in).
|
||
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](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 `$B` command from SKILL.md bash code blocks and validates against the command registry in `browse/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 against `scripts/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 where `aside` is 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 of `lib/aside-render.ts` everywhere, and drives both engines hermetically with fake `aside` / `browse` executables (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`) and `test/skill-e2e-diagram.test.ts` are engine-agnostic: they run through whichever engine resolves (`browserAvailable()` — Aside, or the browse binary `bun run build:gates` compiles, which is what Linux CI does) and skip only when neither exists.
|
||
- **Render CLI** (`test/gstack-render-cli.test.ts`) — Pins `bin/gstack-render.ts` against a fake daemon (`GSTACK_SKIP_ASIDE=1` + `GSTACK_BROWSE_BIN`): argv guards exit 1 with the usage line, `--help` exits 0, `ENGINE=` first then `OK <path>` then fenced `EVAL` / `PAGE_ERRORS`, `--serve-root` containment, the no-browser first line, and prompt exit after a successful render. `make-pdf/test/cli-exit-codes.test.ts` and `make-pdf/test/setup-smoke.test.ts` pin the `pdf` binary'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. `is` lists valid states, `press` lists 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`) — Drive `bin/gstack-design-detect.ts` through the fake engine in `test/fixtures/fake-impeccable.ts` (probe order, the never-execute-a-repository-file rule, the `--changed` target allow-list, `design_detector: off`, analytics lines, output sanitizing), pin the catalog invariants and the generated `review/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.ts` runs `lib/dom-dump.js` in 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-gated `test/skill-e2e-*.test.ts` named in a touchfiles dep list, the file's `EVALS_TIER` self-gate must match its declared tier in `E2E_TIERS`. Kills the "inert demotion" class where a test is re-tiered in `touchfiles.ts` but 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 frontmatter `name` + `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 in `test/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 against `test/fixtures/context-budget.json` via `lib/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-run `bun test/helpers/capture-context-budget.ts` and 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`) — Run `bun test test/dependency-security.test.ts` to check the resolved `sharp` and `adm-zip` version 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` (~$4.20/run)
|
||
|
||
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?"
|
||
|
||
```bash
|
||
# 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=1` env var (prevents accidental expensive runs)
|
||
- Auto-skips if running inside Claude Code (`claude -p` can'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 in `test/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](docs/TESTING_INTERNALS.md)
|
||
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`. 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 dashboard:** Run `bun run eval:watch` in a second terminal to see a live dashboard showing completed tests, the currently running test, and cost. Use `--tail` to also show the last 10 lines of progress.log.
|
||
|
||
**Eval history tools:**
|
||
|
||
```bash
|
||
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); eval:flake-rank is an alias
|
||
```
|
||
|
||
**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. They
|
||
wrap the eval command in `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/`, a per-tier watchdog,
|
||
and a guaranteed `### gstack-detach EXIT=<code> ###` sentinel so a poller never
|
||
mistakes silence for success.
|
||
|
||
```bash
|
||
bun run eval:bg # detached test:evals (diff-based)
|
||
bun run eval:bg:all # detached test:evals:all
|
||
bun run eval:bg:gate # detached gate-tier suite
|
||
bun run eval:bg:periodic # detached periodic-tier suite
|
||
```
|
||
|
||
Each prints its log path. The gate and periodic variants run their tier 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); `EVALS_CONCURRENCY` is bun's concurrency WITHIN a shard
|
||
(default 2) — they are deliberately separate knobs. `eval:list`,
|
||
`eval:compare`, `eval:summary`, and `eval:flake-rank` are shard-aware. Humans running
|
||
`bun run test:evals` 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 (~$0.15/run)
|
||
|
||
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 mean 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.
|
||
|
||
```bash
|
||
# Needs ANTHROPIC_API_KEY in .env — included in bun run test:evals
|
||
```
|
||
|
||
- 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
|
||
|
||
1. **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 in `expectContract()`.
|
||
2. **Touchfiles.** Add `'<case-id>': [...]` to `E2E_TOUCHFILES`; `bun test
|
||
test/touchfiles.test.ts` names any missing closure path.
|
||
3. **Tier.** Add it to `E2E_TIERS`: `gate` for cheap contracts every PR needs,
|
||
`periodic` for long or model-quality cases, `marathon` for complete flows.
|
||
4. **Kind.** Add it to `E2E_KINDS` (`rule` unless a live model choice may
|
||
acceptably deviate; then `behavior` plus a `BEHAVIOR_WHY` line).
|
||
`bun test test/eval-kinds.test.ts` prints the literal to add.
|
||
5. **PR profile.** If a PR should run it, add it to `scripts/test-pr-profile.ts`
|
||
and check `bun run scripts/test-paid-shards.ts --tier gate --profile pr --list`.
|
||
6. **Try the panel locally.** `bun run scripts/test-paid-shards.ts --tier <tier>
|
||
--case <case-id> --trials 3` runs the same panel CI runs, before you push.
|
||
|
||
### 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 gates critical dependency advisories and runs ShellCheck on the setup/build boundaries.
|
||
- **Dependency review** (`.github/workflows/dependency-review.yml`) — reviews dependency changes on PRs that touch lockfiles or workflow files.
|
||
- **OSV scanner** (`.github/workflows/osv-scanner.yml`) — weekly vulnerability scan against the OSV database. Config lives in `.osv-scanner.toml` and is loaded via an explicit `--config` flag (OSV does not auto-discover that filename); every ignore entry needs a reason and an `ignoreUntil` expiry, enforced by `test/osv-config-wiring.test.ts`.
|
||
- **Dependabot** (`.github/dependabot.yml`) — grouped dependency update PRs.
|
||
|
||
The supply-chain workflows pin their third-party actions to commit SHAs. 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.
|
||
|
||
```bash
|
||
# 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).
|
||
|
||
## 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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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](docs/ADDING_A_HOST.md) for the full guide. Short version:
|
||
|
||
1. Create `hosts/myhost.ts` (copy from `hosts/opencode.ts`)
|
||
2. Add to `hosts/index.ts`
|
||
3. Add `.myhost/` to `.gitignore`
|
||
4. Run `bun run gen:skill-docs --host myhost`
|
||
5. Run `bun run test` (parameterized tests auto-cover it)
|
||
|
||
Zero generator, setup, or tooling code changes needed.
|
||
|
||
### Adding a new skill
|
||
|
||
When you add a new skill template, all hosts get it automatically:
|
||
1. Create `{skill}/SKILL.md.tmpl`
|
||
2. Run `bun run gen:skill-docs --host all`
|
||
3. The dynamic template discovery picks it up, no static list to update
|
||
4. Budget it: run `bun test/helpers/capture-context-budget.ts` and commit the refreshed `test/fixtures/context-budget.json` — the context-budget ratchet fails any skill without a ceiling
|
||
5. Commit `{skill}/SKILL.md`, external host output is generated at setup time and gitignored
|
||
|
||
## Conductor workspaces
|
||
|
||
If you're using [Conductor](https://conductor.build) 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 `.tmpl` template, not the `.md`. Run `bun run gen:skill-docs` to regenerate. The same run generates `review/design-checklist.md` from `lib/design-catalog.ts` and `lib/dom-dump.js` from `lib/dom-dump-script.ts`: edit those sources, never the generated files (`test/design-checklist-sync.test.ts` fails on drift).
|
||
- **TODOS.md is the unified backlog.** Organized by skill/component with P0-P4 priorities. `/ship` auto-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 touch `browse/src/*.ts`, `make-pdf/src/*.ts`, `design/src/*.ts`, or anything under `lib/` (the canonical `claude-bin.ts`, `error-handling.ts`, and `aside-render.ts` the binaries embed, plus `design-catalog.ts`, whose `MOCKUP_NEVER_NAMES` the design binary's mockup prompt embeds; `browse/src` re-exports the first three), run `bun run build`. `./setup` makes the same call on its own: it rebuilds when any of the three binaries is missing or when those sources, `package.json`, or `bun.lock` are newer than the browse binary (`test/setup-needs-build.test.ts` pins the decision).
|
||
- **Dev mode shadows your global install.** Project-local skills take priority over `~/.claude/skills/gstack`. `bin/dev-teardown` restores the global one.
|
||
- **Conductor workspaces are independent.** Each workspace is its own git worktree. `bin/dev-setup` runs automatically via `conductor.json`.
|
||
- **`.env` propagates 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 -snf` in `setup`.** Every link site in `setup` MUST route through the `_link_or_copy SRC DST` helper near the `IS_WINDOWS` detection. The helper preserves `ln -snf` on Unix and switches to `cp -R` / `cp -f` on Windows without Developer Mode, where plain `ln -snf` produces frozen file copies that don't refresh on `git pull`. `test/setup-windows-fallback.test.ts` enforces this with a static invariant — a single raw `ln` call 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 to `GENERATED_WITH_GUIDANCE` in `test/run-in-background-guidance.test.ts` in 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 `setup` cannot prove is gstack's.** Every destructive site in `setup` (the linker, the alias installer, both prefix-flip cleanups) and in `bin/gstack-relink` goes through the ownership helpers (`_claude_entry_is_ours` / `_claude_entry_owned_strongly` in `setup`, `_entry_is_ours` / `_entry_owned_strongly` in 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-owned` marker 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`, and `test/relink.test.ts` pin it. The rule is duplicated in the two scripts until the shared helper filed in TODOS.md lands: change both.
|
||
- **`./setup` never fails on Chromium.** The Playwright bootstrap (section `# 2` of `setup`) 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=1` skips it, the right knob for a no-browser box or a setup-only test loop. `GSTACK_SKIP_ASIDE=1` makes 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.ts` pins 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
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
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/`:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
1. **Categorize** — group by theme (security, features, infra, docs)
|
||
2. **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.
|
||
3. **Collector branch** — create `pr-wave-N`, merge clean PRs, resolve
|
||
conflicts for dirty ones, verify with `bun run test && bun run build`
|
||
4. **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.
|
||
5. **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](../../pull/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
|
||
|
||
1. Create `gstack-upgrade/migrations/v{VERSION}.sh` where `{VERSION}` matches
|
||
the VERSION file for the release that needs the fix.
|
||
2. Make it executable: `chmod +x gstack-upgrade/migrations/v{VERSION}.sh`
|
||
3. The script must be **idempotent** (safe to run multiple times) and
|
||
**non-fatal** (failures are logged but don't block the upgrade).
|
||
4. Include a comment block at the top explaining what changed, why the
|
||
migration is needed, and which users are affected.
|
||
|
||
Example:
|
||
|
||
```bash
|
||
#!/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:
|
||
|
||
```bash
|
||
/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.
|