CLAUDE.md

1# gstack development
2 
3## Commands
4 
5```bash
6bun install          # install dependencies
7bun test             # run free tests (browse + snapshot + skill validation)
8bun run test:evals   # run paid evals: LLM judge + E2E (diff-based, ~$4/run max)
9bun run test:evals:all  # run ALL paid evals regardless of diff
10bun run test:gate    # run gate-tier tests only (CI default, blocks merge)
11bun run test:periodic  # run periodic-tier tests only (weekly cron / manual)
12bun run test:gate:sharded    # gate tier via the sharded paid runner (one Bun process per test file)
13bun run test:periodic:sharded  # periodic tier via the sharded paid runner (implies EVALS_ALL=1)
14bun run test:e2e     # run E2E tests only (diff-based, ~$3.85/run max)
15bun run test:e2e:all # run ALL E2E tests regardless of diff
16bun run eval:select  # show which tests would run based on current diff
17bun run dev <cmd>    # run CLI in dev mode, e.g. bun run dev goto https://example.com
18bun run build        # gen docs + compile binaries
19bun run gen:skill-docs  # regenerate SKILL.md files from templates
20bun run skill:check  # health dashboard for all skills
21bun run dev:skill    # watch mode: auto-regen + validate on change
22bun run eval:list    # list all eval runs from ~/.gstack-dev/evals/
23bun run eval:compare # compare two eval runs (auto-picks most recent)
24bun run eval:summary # aggregate stats across all eval runs
25bun run slop          # full slop-scan report (all files)
26bun run slop:diff     # slop findings in files changed on this branch only
27```
28 
29`test:evals` requires `ANTHROPIC_API_KEY`. Codex E2E tests (`test/codex-e2e.test.ts`)
30use Codex's own auth from `~/.codex/` config — no `OPENAI_API_KEY` env var needed.
31 
32**Env keys in Conductor workspaces.** The `GSTACK_*` env-shim (v1.39.2.0+,
33`lib/conductor-env-shim.ts`) promotes `GSTACK_ANTHROPIC_API_KEY` /
34`GSTACK_OPENAI_API_KEY` to their canonical names inside gstack's TS binaries.
35Tests run through gstack entrypoints inherit this promotion automatically.
36Don't echo the key value to stdout, logs, or shell history. The historical
37"never pass `env:` to `runAgentSdkTest`" rule is retired: the failure was
38partial-env replacement (the SDK's `Options.env` REPLACES the child's entire
39environment, so an object without the key broke auth). The runner now always
40passes a COMPLETE hermetic env with per-test `env:` merged last, so per-test
41overrides are safe; ambient `process.env.ANTHROPIC_API_KEY` mutation also
42still works (the env builder reads process.env at call time).
43 
44**Hermetic local E2E (default).** Every E2E runner (claude -p, PTY, Agent
45SDK, codex, gemini) spawns children through `test/helpers/hermetic-env.ts`:
46allowlist-scrubbed env (operator `CONDUCTOR_*`, `CLAUDE_*`, `GSTACK_*`,
47`MCP_*`, `GBRAIN_*`, and credentials like `GH_TOKEN` never reach children),
48a fresh seeded `CLAUDE_CONFIG_DIR` (no operator `~/.claude` CLAUDE.md /
49MCP servers / skills), a temp `GSTACK_HOME`, and `--strict-mcp-config`.
50Local eval signal matches CI. Debug against real operator state with
51`EVALS_HERMETIC=0` (restores the legacy env AND drops the strict-MCP flag).
52Per-test `env:` overrides merge last, so deliberate contamination
53(`CONDUCTOR_WORKSPACE_PATH`, per-test `GSTACK_HOME`) keeps working. The
54hermetic config dir seeds NO skills by default; a PTY test that types a
55`/skill` slash command must pass `seedSkills: true` to the PTY runner, which
56points the child's `CLAUDE_CONFIG_DIR` at `hermeticSkillsConfigDir()` — a
57seeded registry that symlinks the LIVE working tree's SKILL.md files (by
58design: the skills ARE the subject under test; a snapshot would measure stale
59copies). Wiring is pinned by `test/hermetic-wiring.test.ts` (static tripwire),
60two gate-tier canaries in `test/skill-e2e-hermetic-canary.test.ts`, and the
61seeding tripwires in `test/hermetic-skills-seeding.test.ts` /
62`test/pty-skill-seeding-wiring.test.ts`.
63 
64E2E tests stream progress in real-time (tool-by-tool via `--output-format stream-json
65--verbose`). Results are persisted to `~/.gstack-dev/evals/` with auto-comparison
66against the previous finalized run (in-flight `_partial` files are never used as
67a baseline, so a run can't compare against itself).
68 
69**Diff-based test selection:** `test:evals` and `test:e2e` auto-select tests based
70on `git diff` against the base branch. Each test declares its file dependencies in
71`test/helpers/touchfiles.ts`. Changes to global touchfiles (session-runner, eval-store,
72touchfiles.ts itself) trigger all tests. Use `EVALS_ALL=1` or the `:all` script
73variants to force all tests. Run `eval:select` to preview which tests would run.
74 
75**Two-tier system:** Tests are classified as `gate` or `periodic` in `E2E_TIERS`
76(in `test/helpers/touchfiles.ts`). CI runs only gate tests (`EVALS_TIER=gate`);
77periodic tests run weekly via cron or manually. Use `EVALS_TIER=gate` or
78`EVALS_TIER=periodic` to filter. When adding new E2E tests, classify them:
791. Safety guardrail or deterministic functional test? -> `gate`
802. Quality benchmark, Opus model test, or non-deterministic? -> `periodic`
813. Requires external service (Codex, Gemini)? -> `periodic`
82 
83Tier declarations are enforced by `test/e2e-tier-alignment.test.ts` (free, runs
84in `bun test`): a `skill-e2e-*` file named in a touchfiles dep list whose
85`EVALS_TIER` self-gate disagrees with its declared tier in `E2E_TIERS` fails the
86suite. Files not named in any dep list are reported, not enforced — keep both
87in sync.
88 
89## Testing
90 
91```bash
92bun test             # run before every commit — free, <2s
93bun run test:evals   # run before shipping — paid, diff-based (~$4/run max)
94```
95 
96`bun test` runs skill validation, gen-skill-docs quality checks, and browse
97integration tests. `bun run test:evals` runs LLM-judge quality evals and E2E
98tests via `claude -p`. Both must pass before creating a PR.
99 
100## Project structure
101 
102```
103gstack/
104├── browse/          # Headless browser CLI (Playwright)
105│   ├── src/         # CLI + server + commands
106│   │   ├── commands.ts  # Command registry (single source of truth)
107│   │   └── snapshot.ts  # SNAPSHOT_FLAGS metadata array
108│   ├── test/        # Integration tests + fixtures
109│   └── dist/        # Compiled binary
110├── hosts/           # Typed host configs (one per AI agent)
111│   ├── claude.ts    # Primary host config
112│   ├── codex.ts, factory.ts, kiro.ts  # Existing hosts
113│   ├── opencode.ts, slate.ts, cursor.ts, openclaw.ts  # IDE hosts
114│   ├── hermes.ts, gbrain.ts  # Agent runtime hosts
115│   └── index.ts     # Registry: exports all, derives Host type
116├── scripts/         # Build + DX tooling
117│   ├── gen-skill-docs.ts  # Template → SKILL.md generator (config-driven)
118│   ├── host-config.ts     # HostConfig interface + validator
119│   ├── host-config-export.ts  # Shell bridge for setup script
120│   ├── host-adapters/     # Host-specific adapters (OpenClaw tool mapping)
121│   ├── resolvers/   # Template resolver modules (preamble, design, review, gbrain, etc.)
122│   ├── skill-check.ts     # Health dashboard
123│   ├── test-paid-shards.ts  # Sharded paid-tier runner (one Bun process per shard)
124│   └── dev-skill.ts       # Watch mode
125├── test/            # Skill validation + eval tests
126│   ├── helpers/     # skill-parser.ts, session-runner.ts, llm-judge.ts, eval-store.ts
127│   ├── fixtures/    # Ground truth JSON, planted-bug fixtures, eval baselines
128│   ├── skill-validation.test.ts  # Tier 1: static validation (free, <1s)
129│   ├── gen-skill-docs.test.ts    # Tier 1: generator quality (free, <1s)
130│   ├── skill-llm-eval.test.ts   # Tier 3: LLM-as-judge (~$0.15/run)
131│   └── skill-e2e-*.test.ts       # Tier 2: E2E via claude -p (~$3.85/run, split by category)
132├── qa-only/         # /qa-only skill (report-only QA, no fixes)
133├── plan-design-review/  # /plan-design-review skill (report-only design audit)
134├── design-review/    # /design-review skill (design audit + fix loop)
135├── ship/            # Ship workflow skill
136├── review/          # PR review skill
137├── plan-ceo-review/ # /plan-ceo-review skill
138├── plan-eng-review/ # /plan-eng-review skill
139├── autoplan/        # /autoplan skill (auto-review pipeline: CEO → design → eng)
140├── benchmark/       # /benchmark skill (performance regression detection)
141├── canary/          # /canary skill (post-deploy monitoring loop)
142├── codex/           # /codex skill (multi-AI second opinion via OpenAI Codex CLI)
143├── land-and-deploy/ # /land-and-deploy skill (merge → deploy → canary verify)
144├── office-hours/    # /office-hours skill (YC Office Hours — startup diagnostic + builder brainstorm)
145├── investigate/     # /investigate skill (systematic root-cause debugging)
146├── spec/            # /spec skill (five-phase spec → GitHub issue, optional agent spawn, /ship auto-closes)
147├── retro/           # Retrospective skill (includes /retro global cross-project mode)
148├── bin/             # CLI utilities (gstack-repo-mode, gstack-slug, gstack-config, etc.)
149├── document-release/ # /document-release skill (post-ship doc updates + Diataxis coverage map)
150├── document-generate/ # /document-generate skill (Diataxis doc generator: tutorial/how-to/reference/explanation)
151├── cso/             # /cso skill (OWASP Top 10 + STRIDE security audit)
152├── design-consultation/ # /design-consultation skill (design system from scratch)
153├── design-shotgun/  # /design-shotgun skill (visual design exploration)
154├── open-gstack-browser/  # /open-gstack-browser skill (launch GStack Browser)
155├── connect-chrome/  # symlink → open-gstack-browser (backwards compat)
156├── design/          # Design binary CLI (GPT Image API)
157│   ├── src/         # CLI + commands (generate, variants, compare, serve, etc.)
158│   ├── test/        # Integration tests
159│   └── dist/        # Compiled binary
160├── extension/       # Chrome extension (side panel + activity feed + CSS inspector)
161├── lib/             # Shared libraries (worktree.ts, egress-receipt.ts, context-bill.ts, redact-engine.ts)
162├── docs/designs/    # Design documents
163├── setup-deploy/    # /setup-deploy skill (one-time deploy config)
164├── .github/         # CI workflows + Docker image
165│   ├── workflows/   # evals.yml (E2E on Ubicloud), skill-docs.yml, actionlint.yml
166│   └── docker/      # Dockerfile.ci (pre-baked toolchain + Playwright/Chromium)
167├── contrib/         # Contributor-only tools (never installed for users)
168│   └── add-host/    # /gstack-contrib-add-host skill
169├── setup            # One-time setup: build binary + symlink skills
170├── SKILL.md         # Generated from SKILL.md.tmpl (don't edit directly)
171├── SKILL.md.tmpl    # Template: edit this, run gen:skill-docs
172├── ETHOS.md         # Builder philosophy (Boil the Ocean, Search Before Building)
173└── package.json     # Build scripts for browse
174```
175 
176## SKILL.md workflow
177 
178SKILL.md files are **generated** from `.tmpl` templates. To update docs:
179 
1801. Edit the `.tmpl` file (e.g. `SKILL.md.tmpl` or `browse/SKILL.md.tmpl`)
1812. Run `bun run gen:skill-docs` (or `bun run build` which does it automatically)
1823. Commit both the `.tmpl` and generated `.md` files
183 
184To add a new browse command: add it to `browse/src/commands.ts` and rebuild.
185To add a snapshot flag: add it to `SNAPSHOT_FLAGS` in `browse/src/snapshot.ts` and rebuild.
186 
187**Token ceiling:** Generated SKILL.md files trip a warning above 160KB (~40K tokens).
188This is a "watch for feature bloat" guardrail, not a hard gate. Modern flagship
189models have 200K-1M context windows, so 40K is 4-20% of window, and prompt caching
190makes the marginal cost of larger skills small. The ceiling exists to catch runaway
191preamble/resolver growth, not to force compression on carefully-tuned big skills
192(`ship`, `plan-ceo-review`, `office-hours` legitimately pack 25-35K tokens of
193behavior). If you blow past 40K, the right fix is usually: (1) look at WHAT grew,
194(2) if one resolver added 10K+ in a single PR, question whether it belongs inline
195or as a reference doc, (3) only compress carefully-tuned prose as a last resort —
196cuts to the coverage audit, review army, or voice directive have real quality cost.
197 
198A second, harder ceiling guards the DISCOVERY surface: `test/catalog-budget.test.ts`
199caps the aggregate frontmatter `name` + `description` across all skills at 1,150
200token-equivalents (260-byte per-skill sub-cap), counted through the shared census
201in `test/helpers/skill-census.ts`. This one is enforced, not a warning — every
202host loads the full catalog every session, so growth here taxes every
203conversation. The failure message carries the re-measure + ratchet protocol.
204`bin/gstack-context-bill` shows the full token bill-of-materials for a skills
205tree (always-on vs per-invocation, `--diff`, `--budget`; `--exact` opts into the
206real tokenizer and POSTs file text to api.anthropic.com with an egress receipt).
207 
208**Merge conflicts on SKILL.md files:** NEVER resolve conflicts on generated SKILL.md
209files by accepting either side. Instead: (1) resolve conflicts on the `.tmpl` templates
210and `scripts/gen-skill-docs.ts` (the sources of truth), (2) run `bun run gen:skill-docs`
211to regenerate all SKILL.md files, (3) stage the regenerated files. Accepting one side's
212generated output silently drops the other side's template changes.
213 
214## Platform-agnostic design
215 
216Skills must NEVER hardcode framework-specific commands, file patterns, or directory
217structures. Instead:
218 
2191. **Read CLAUDE.md** for project-specific config (test commands, eval commands, etc.)
2202. **If missing, AskUserQuestion** — let the user tell you or let gstack search the repo
2213. **Persist the answer to CLAUDE.md** so we never have to ask again
222 
223This applies to test commands, eval commands, deploy commands, and any other
224project-specific behavior. The project owns its config; gstack reads it.
225 
226## Writing SKILL templates
227 
228SKILL.md.tmpl files are **prompt templates read by Claude**, not bash scripts.
229Each bash code block runs in a separate shell — variables do not persist between blocks.
230 
231Rules:
232- **Use natural language for logic and state.** Don't use shell variables to pass
233  state between code blocks. Instead, tell Claude what to remember and reference
234  it in prose (e.g., "the base branch detected in Step 0").
235- **Don't hardcode branch names.** Detect `main`/`master`/etc dynamically via
236  `gh pr view` or `gh repo view`. Use `{{BASE_BRANCH_DETECT}}` for PR-targeting
237  skills. Use "the base branch" in prose, `<base>` in code block placeholders.
238- **Keep bash blocks self-contained.** Each code block should work independently.
239  If a block needs context from a previous step, restate it in the prose above.
240- **Express conditionals as English.** Instead of nested `if/elif/else` in bash,
241  write numbered decision steps: "1. If X, do Y. 2. Otherwise, do Z."
242 
243## Writing style (V1)
244 
245Default output from every tier-≥2 skill follows the Writing Style section in
246`scripts/resolvers/preamble.ts`: jargon glossed on first use (curated list in
247`scripts/jargon-list.json`, baked at gen-skill-docs time), questions framed in
248outcome terms ("what breaks for your users if...") not implementation terms,
249short sentences, decisions close with user impact. Power users who want the
250tighter V0 prose set `gstack-config set explain_level terse` (binary switch,
251no middle mode). See `docs/designs/PLAN_TUNING_V1.md` for the full design
252rationale. The review pacing overhaul that originally tried to ride alongside
253writing-style was extracted to V1.1 — see `docs/designs/PACING_UPDATES_V0.md`.
254 
255## Browser interaction
256 
257When you need to interact with a browser (QA, dogfooding, cookie setup), use the
258`/browse` skill or run the browse binary directly via `$B <command>`. NEVER use
259`mcp__claude-in-chrome__*` tools — they are slow, unreliable, and not what this
260project uses.
261 
262**Sidebar architecture:** Before modifying `sidepanel.js`, `background.js`,
263`content.js`, `terminal-agent.ts`, or sidebar-related server endpoints,
264read `docs/designs/SIDEBAR_MESSAGE_FLOW.md`. The sidebar has one primary
265surface — the **Terminal** pane (interactive `claude` PTY) — with
266Activity / Refs / Inspector as debug overlays behind the footer's
267`debug` toggle. The chat queue path was ripped once the PTY proved out;
268`sidebar-agent.ts` and the `/sidebar-command` / `/sidebar-chat` /
269`/sidebar-agent/event` endpoints are gone. The doc covers the WS auth
270flow, dual-token model, and threat-model boundary — silent failures
271here usually trace to not understanding the cross-component flow.
272 
273**Embedder terminal-agent ownership** (v1.42.1.0+, identity-based kill v1.44.0.0+).
274`buildFetchHandler` in `browse/src/server.ts` accepts `ServerConfig.ownsTerminalAgent?:
275boolean` (default `true`). When `true`, factory shutdown runs the full teardown:
276identity-based kill via `killAgentByRecord(readAgentRecord(stateDir))` from
277`browse/src/terminal-agent-control.ts` plus `safeUnlinkQuiet` on
278`<stateDir>/terminal-port`, `<stateDir>/terminal-internal-token`, and
279`<stateDir>/terminal-agent-pid` (the per-boot agent record introduced in v1.44).
280Embedders (e.g. the gbrowser phoenix overlay) that pre-launch their own PTY
281server must pass `false` so their discovery files survive gstack teardown cycles.
282The flag is the third caller-owned teardown gate in `ServerConfig` (alongside
283`xvfb?` and `proxyBridge?`); polarity is inverted (explicit bool vs presence) and
284documented in the field's JSDoc. CLI `start()` always passes `true` explicitly —
285the static-grep test in `browse/test/server-embedder-terminal-port.test.ts` fails
286CI if a refactor drops it. Pre-v1.44 used `pkill -f terminal-agent\.ts` (regex
287match) which would kill sibling gstack sessions on the same host; the new
288`browse/test/terminal-agent-pid-identity.test.ts` static-grep tripwire fails CI
289if any source file re-introduces `pkill ... terminal-agent` or `spawnSync('pkill', ...)`.
290 
291**WebSocket auth uses Sec-WebSocket-Protocol, not cookies.** Browsers
292can't set `Authorization` on a WebSocket upgrade, but they CAN set
293`Sec-WebSocket-Protocol` via `new WebSocket(url, [token])`. The agent
294reads it, validates against `validTokens`, and MUST echo the protocol
295back in the upgrade response — without the echo, Chromium closes the
296connection immediately. `Set-Cookie: gstack_pty=...` is kept as a
297fallback for non-browser callers (the cross-port `SameSite=Strict`
298cookie path doesn't survive from a chrome-extension origin).
299 
300**Cross-pane PTY injection.** The toolbar's Cleanup button and the
301Inspector's "Send to Code" action both pipe text into the live claude
302PTY via `window.gstackInjectToTerminal(text)`, exposed by
303`sidepanel-terminal.js`. No `/sidebar-command` POST — the live REPL is
304the only execution surface in the sidebar now.
305 
306**`/health` MUST NOT surface any token — and it no longer does** (v1.63+).
307The historical headed-mode leak of `AUTH_TOKEN` is fixed: `GET /health` is
308liveness/status only in every mode. Token bootstrap is `POST /extension-token`,
309which validates the caller's Origin against the pinned extension identity
310(the `key` field in `extension/manifest.json` pins the extension ID —
311`GSTACK_EXTENSION_ID` in `browse/src/server.ts`, derivation reproducible via
312`bun browse/scripts/extension-id.ts`) plus a loopback Host. PTY auth still
313flows through `POST /pty-session` only. Don't add any token to `/health`.
314 
315**Transport-layer security** (v1.6.0.0+). When `pair-agent` starts an ngrok tunnel,
316the daemon binds two HTTP listeners: a local listener (127.0.0.1, full command
317surface, never forwarded) and a tunnel listener (locked allowlist: `/connect`,
318`/command` with a scoped token + 26-command browser-driving allowlist,
319`/sidebar-chat`). ngrok forwards only the tunnel port. Root tokens over the tunnel
320return 403. SSE endpoints use a 30-minute HttpOnly `gstack_sse` cookie minted via
321`POST /sse-session` (never valid against `/command`). Tunnel-surface rejections go
322to `~/.gstack/security/attempts.jsonl` via `tunnel-denial-log.ts`. Before editing
323`server.ts`, `sse-session-cookie.ts`, or `tunnel-denial-log.ts`, read
324[ARCHITECTURE.md](ARCHITECTURE.md#dual-listener-tunnel-architecture-v1600) —
325the module boundary (no imports from `token-registry.ts` into `sse-session-cookie.ts`)
326is load-bearing for scope isolation.
327 
328**Unicode sanitization at server egress** (v1.38.0.0+). Every server egress that
329ships page-content-derived strings MUST go through `JSON.stringify(payload,
330sanitizeReplacer)` for object payloads or `sanitizeLoneSurrogates(body)` for text
331bodies. Lone UTF-16 surrogate halves from CDP page content otherwise reach the
332Anthropic API as `\uD800`-style escapes and trigger a 400. Wired at four egress
333points today: `handleCommandInternal` (HTTP + batch via a sanitizing wrapper around
334`handleCommandInternalImpl`) and both SSE producers (`/activity/stream`,
335`/inspector/events`). Post-stringify regex is a no-op — `JSON.stringify` has
336already escaped the surrogate before regex could match, so the replacer must run
337inside the encoding pipeline. Before adding a new SSE/WebSocket writer or HTTP
338response in `server.ts`, read
339[ARCHITECTURE.md](ARCHITECTURE.md#unicode-sanitization-at-server-egress-v13800).
340`browse/test/server-sanitize-surrogates.test.ts` pins the wiring with invariant
341tests, so bypasses fail CI.
342 
343**Egress receipts at every off-machine sink** (v1.63.0.0+). Every gstack-initiated
344send off the machine MUST write a hash-chained receipt to
345`~/.gstack/security/egress.jsonl` BEFORE the send: TypeScript callers use
346`writeReceipt` from `lib/egress-receipt.ts`; shell scripts source
347`bin/gstack-egress-lib.sh` and use `_receipted_curl` / `_receipted_git`. Failure
348polarity is per-class: fail-closed for sensitive sinks (brain-sync, memory-ingest,
349gbrain-sync, telemetry, ngrok tunnels, mcp-verify, supabase-provision), fail-open
350+ stderr warning for user-facing ones (design OpenAI calls, update-check,
351dashboards, git-class ops). The new-sink scanner in
352`test/egress-receipt-wiring.test.ts` fails CI on an unreceipted `curl` /
353`git push` / `fetch` to a non-loopback host unless the file carries a reasoned
354entry in its `SCANNER_EXEMPT` list (user-directed page fetches, reachability
355probes, instruction strings, skill prose) — if you add a new off-machine sink,
356wire it through the helpers and add it to the enumerated sink list. Inspect with
357`bin/gstack-egress` (`list` | `verify`, exit 3 on tamper | `grants`). Threat
358model: forensic observability of ATTEMPTED egress, not an exfiltration control.
359 
360**SSE endpoint helper** (v1.51.0.0+). New SSE endpoints in `server.ts` MUST route
361through `createSseEndpoint(req, config)` from `browse/src/sse-helpers.ts`. The
362helper owns the cleanup contract (abort + enqueue-throw + heartbeat-throw, all
363idempotent) and bakes in `sanitizeLoneSurrogates` on every JSON.stringify, so
364new subscribers can't accidentally regress either invariant. Inline
365`ReadableStream` wiring leaked subscribers when the TCP connection died without
366firing `req.signal.abort` (Chromium MV3 service-worker suspend, intermediate
367proxy half-close). `/activity/stream`, `/inspector/events`, and `/memory`
368(SSE-eligible) all route through it. `browse/test/sse-helpers.test.ts` pins the
369cleanup contract.
370 
371**CDP session lifecycle** (v1.51.0.0+). Direct `page.context().newCDPSession(page)`
372calls outside `browse/src/cdp-bridge.ts` fail CI via the static-grep tripwire in
373`browse/test/cdp-session-cleanup.test.ts`. Use `withCdpSession(page, async (s) => {...})`
374for one-shot CDP work (try/finally detach) or `getOrCreateCdpSession(page, cache)`
375for cached sessions tied to a page's lifetime (close-detach via `Map<page, session>`).
376Three sites migrated: cdp-bridge frame events, write-commands archive capture,
377cdp-inspector. The helpers prevent the per-session leak class where successful-path
378detach happened but error-path detach was missed.
379 
380**Setup symlink hardening** (v1.38.0.0+). Every link site in `setup` MUST route
381through the `_link_or_copy SRC DST` helper near the `IS_WINDOWS` detection. On
382Windows without Developer Mode, plain `ln -snf` produces frozen file copies that
383don't refresh on `git pull` — silent staleness across every host adapter. The
384helper preserves `ln -snf` on Unix and switches to `cp -R` / `cp -f` on Windows.
385`test/setup-windows-fallback.test.ts` enforces a static invariant: a single raw
386`ln` call outside the helper body fails CI. Windows users get a one-line note
387from `_print_windows_copy_note_once` reminding them to re-run `./setup` after
388every `git pull`.
389 
390**Sidebar security stack** (layered defense against prompt injection):
391 
392| Layer | Module | Lives in |
393|-------|--------|----------|
394| L1-L3 | `content-security.ts` | both server and agent — datamarking, hidden element strip, ARIA regex, URL blocklist, envelope wrapping |
395| L4 | `security-classifier.ts` (TestSavantAI ONNX) | **sidebar-agent only** |
396| L4b | `security-classifier.ts` (Claude Haiku transcript) | **sidebar-agent only** |
397| L5 | `security.ts` (canary) | both — inject in compiled, check in agent |
398| L6 | `security.ts` (combineVerdict ensemble) | both |
399 
400**Critical constraint:** `security-classifier.ts` CANNOT be imported from the
401compiled browse binary. `@huggingface/transformers` v4 requires `onnxruntime-node`
402which fails to `dlopen` from Bun compile's temp extract dir. Only `security.ts`
403(pure-string operations — canary, verdict combiner, attack log, status) is safe
404for `server.ts`. See `~/.gstack/projects/garrytan-gstack/ceo-plans/2026-04-19-prompt-injection-guard.md`
405§"Pre-Impl Gate 1 Outcome" for full architectural decision.
406 
407**Thresholds** (in `security.ts`):
408- `BLOCK: 0.85` — single-layer score that would cause BLOCK if cross-confirmed
409- `WARN: 0.75` — cross-confirm threshold. When L4 AND L4b both >= 0.75 → BLOCK
410- `LOG_ONLY: 0.40` — gates transcript classifier (skip Haiku when all layers < 0.40)
411- `SOLO_CONTENT_BLOCK: 0.92` — single-layer threshold for label-less content classifiers
412  (testsavant, deberta). Intentionally higher than `BLOCK` because these layers can't
413  distinguish "this is an injection" from "this looks like phishing aimed at the user."
414  The transcript classifier keeps a separate, label-gated solo path at `BLOCK` (0.85).
415 
416**Ensemble rule:** BLOCK only when the ML content classifier AND the transcript
417classifier both report >= WARN. Single-layer high confidence degrades to WARN —
418this is the Stack Overflow instruction-writing FP mitigation. Canary leak
419always BLOCKs (deterministic).
420 
421**Env knobs:**
422- `GSTACK_SECURITY_OFF=1` — emergency kill switch. Classifier stays off even if
423  warmed. Canary is still injected; just the ML scan is skipped.
424- `GSTACK_SECURITY_ENSEMBLE=deberta` — opt-in DeBERTa-v3 ensemble. Adds
425  ProtectAI DeBERTa-v3-base-injection-onnx as L4c classifier for cross-model
426  agreement. 721MB first-run download. With ensemble enabled, BLOCK requires
427  2-of-3 ML classifiers agreeing at >= WARN (testsavant, deberta, transcript).
428  Without ensemble (default), BLOCK requires testsavant + transcript at >= WARN.
429- Classifier model cache: `~/.gstack/models/testsavant-small/` (112MB, first run only)
430  plus `~/.gstack/models/deberta-v3-injection/` (721MB, only when ensemble enabled)
431- Attack log: `~/.gstack/security/attempts.jsonl` (salted sha256 + domain only,
432  rotates at 10MB, 5 generations)
433- Per-device salt: `~/.gstack/security/device-salt` (0600)
434- Session state: `~/.gstack/security/session-state.json` (cross-process, atomic)
435 
436## Dev symlink awareness
437 
438When developing gstack, `.claude/skills/gstack` may be a symlink back to this
439working directory (gitignored). This means skill changes are **live immediately**,
440great for rapid iteration, risky during big refactors where half-written skills
441could break other Claude Code sessions using gstack concurrently.
442 
443**Check once per session:** Run `ls -la .claude/skills/gstack` to see if it's a
444symlink or a real copy. If it's a symlink to your working directory, be aware that:
445- Template changes + `bun run gen:skill-docs` immediately affect all gstack invocations
446- Breaking changes to SKILL.md.tmpl files can break concurrent gstack sessions
447- During large refactors, remove the symlink (`rm .claude/skills/gstack`) so the
448  global install at `~/.claude/skills/gstack/` is used instead
449 
450**Prefix setting:** Setup creates real directories (not symlinks) at the top level
451with a SKILL.md symlink inside (e.g., `qa/SKILL.md -> gstack/qa/SKILL.md`). This
452ensures Claude discovers them as top-level skills, not nested under `gstack/`.
453Names are either short (`qa`) or namespaced (`gstack-qa`), controlled by
454`skill_prefix` in `~/.gstack/config.yaml`. Pass `--no-prefix` or `--prefix` to
455skip the interactive prompt.
456 
457**Note:** Vendoring gstack into a project's repo is deprecated. Use global install
458+ `./setup --team` instead. See README.md for team mode instructions.
459 
460**For plan reviews:** When reviewing plans that modify skill templates or the
461gen-skill-docs pipeline, consider whether the changes should be tested in isolation
462before going live (especially if the user is actively using gstack in other windows).
463 
464**Upgrade migrations:** When a change modifies on-disk state (directory structure,
465config format, stale files) in ways that could break existing user installs, add a
466migration script to `gstack-upgrade/migrations/`. Read CONTRIBUTING.md's "Upgrade
467migrations" section for the format and testing requirements. The upgrade skill runs
468these automatically after `./setup` during `/gstack-upgrade`.
469 
470## Compiled binaries — never commit browse/dist/, design/dist/, or make-pdf/dist/
471 
472The `browse/dist/`, `design/dist/`, and `make-pdf/dist/` directories contain
473compiled Bun binaries (`browse`, `find-browse`, `design`, ~62MB each). These are
474Mach-O arm64 only — they do NOT work on Linux, Windows, or Intel Macs. The
475`./setup` script builds from source for every platform.
476 
477These directories are **untracked and gitignored** (`.gitignore:3-6`; the
478`browse/dist/` binaries were untracked in `64d5a3e4`, v0.11.16.0; the others were
479never tracked). They will NOT appear in `git status`. If a dist binary ever does
480show up in `git status`, something force-added it (`git add -f`) — do not commit
481it; unstage it and find out how it got there.
482 
483When staging files, always use specific filenames (`git add file1 file2`) — never
484`git add .` or `git add -A`, which can sweep in build outputs and junk.
485 
486## Redaction guard (PII / secrets / legal content)
487 
488Shared redaction engine catches credentials, PII, and legal/damaging content
489before it reaches an external sink (codex dispatch, GitHub issue/PR body, pushed
490commit). It is a **guardrail, not airtight enforcement** — `git push --no-verify`,
491direct `gh issue create`, and `GSTACK_REDACT_PREPUSH=skip` all bypass it. It
492catches accidents and carelessness, the 99% case. Do not claim it stops a
493determined leaker (a CHANGELOG line that does would fail a hostile screenshotter).
494 
495- **Engine + taxonomy:** `lib/redact-patterns.ts` (the single source of truth —
496  3 tiers; HIGH = genuinely-secret credentials that block, MEDIUM = PII/legal/
497  internal + high-FP credential shapes that confirm via AskUserQuestion, LOW =
498  FYI) and `lib/redact-engine.ts` (pure `scan()` + `applyRedactions()`).
499  Calibration matters: a gate that cries wolf gets ignored, so context-variable
500  shapes (Stripe `pk_live_`, Google `AIza`, JWT, env `*_KEY=`) sit at MEDIUM.
501- **CLI:** `bin/gstack-redact` (exit 0 clean / 2 MEDIUM / 3 HIGH; `--json`,
502  `--auto-redact`, `--repo-visibility`, `--from-file`). `bin/gstack-redact-prepush`
503  is the opt-in git hook.
504- **Skill docs are generated** from `scripts/resolvers/redact-doc.ts`
505  (`{{REDACT_TAXONOMY_TABLE}}`, `{{REDACT_INVOCATION_BLOCK:<sink>}}`) so /spec,
506  /cso, /ship, /document-release, /document-generate never drift from the engine.
507- **Scan-at-sink:** always scan the EXACT bytes that will be sent — write to a
508  temp file, scan that file, pass the SAME file to `gh`/`git`. Never scan a string
509  then re-render (that reopens a scan-vs-send gap).
510- **Visibility (no tier promotion):** resolve once per run, order = local config
511  (`gstack-config get redact_repo_visibility`, ~/.gstack so never committed) → gh
512  → glab → unknown(=public-strict). Public repos get STERNER per-finding
513  confirmation (no batch-acknowledge, no silent-proceed); MEDIUM is never
514  auto-promoted to HIGH.
515- **Tool-attributed fences:** wrap Codex/Greptile/eval output in ` ```codex-review `
516  / ` ```greptile ` fences so example credentials those tools quote WARN-degrade
517  instead of blocking. A live-format credential inside the fence still blocks.
518- **Config keys:** `redact_repo_visibility` (public|private|unknown, local-only
519  override for repos gh/glab can't read), `redact_prepush_hook` (true|false).
520  There is intentionally NO key to disable HIGH blocking.
521- **Audit:** the /spec semantic pass appends a content-free record (categories +
522  body sha256, no spec text) to `~/.gstack/security/semantic-reviews.jsonl` (0600).
523 
524## Commit style
525 
526**Always bisect commits.** Every commit should be a single logical change. When
527you've made multiple changes (e.g., a rename + a rewrite + new tests), split them
528into separate commits before pushing. Each commit should be independently
529understandable and revertable.
530 
531Examples of good bisection:
532- Rename/move separate from behavior changes
533- Test infrastructure (touchfiles, helpers) separate from test implementations
534- Template changes separate from generated file regeneration
535- Mechanical refactors separate from new features
536 
537When the user says "bisect commit" or "bisect and push," split staged/unstaged
538changes into logical commits and push.
539 
540## Slop-scan: AI code quality, not AI code hiding
541 
542We use [slop-scan](https://github.com/benvinegar/slop-scan) to catch patterns where
543AI-generated code is genuinely worse than what a human would write. We are NOT trying
544to pass as human code. We are AI-coded and proud of it. The goal is code quality.
545 
546```bash
547npx slop-scan scan .          # human-readable report
548npx slop-scan scan . --json   # machine-readable for diffing
549```
550 
551Config: `slop-scan.config.json` at repo root (currently excludes `**/vendor/**`).
552 
553### What to fix (genuine quality improvements)
554 
555- **Empty catches around file ops** — use `safeUnlink()` (ignores ENOENT, rethrows
556  EPERM/EIO). A swallowed EPERM in cleanup means silent data loss.
557- **Empty catches around process kills** — use `safeKill()` (ignores ESRCH, rethrows
558  EPERM). A swallowed EPERM means you think you killed something you didn't.
559- **Redundant `return await`** — remove when there's no enclosing try block. Saves a
560  microtask, signals intent.
561- **Typed exception catches** — `catch (err) { if (!(err instanceof TypeError)) throw err }`
562  is genuinely better than `catch {}` when the try block does URL parsing or DOM work.
563  You know what error you expect, so say so.
564 
565### What NOT to fix (linter gaming, not quality)
566 
567- **String-matching on error messages** — `err.message.includes('closed')` is brittle.
568  Playwright/Chrome can change wording anytime. If a fire-and-forget operation can fail
569  for ANY reason and you don't care, `catch {}` is the correct pattern.
570- **Adding comments to exempt pass-through wrappers** — "alias for active session" above
571  a method just to trip slop-scan's exemption rule is noise, not documentation.
572- **Converting extension catch-and-log to selective rethrow** — Chrome extensions crash
573  entirely on uncaught errors. If the catch logs and continues, that IS the right pattern
574  for extension code. Don't make it throw.
575- **Tightening best-effort cleanup paths** — shutdown, emergency cleanup, and disconnect
576  code should use `safeUnlinkQuiet()` (swallows ALL errors). A cleanup path that throws
577  on EPERM means the rest of cleanup doesn't run. That's worse.
578 
579### Utilities in `browse/src/error-handling.ts`
580 
581| Function | Use when | Behavior |
582|----------|----------|----------|
583| `safeUnlink(path)` | Normal file deletion | Ignores ENOENT, rethrows others |
584| `safeUnlinkQuiet(path)` | Shutdown/emergency cleanup | Swallows all errors |
585| `safeKill(pid, signal)` | Sending signals | Ignores ESRCH, rethrows others |
586| `isProcessAlive(pid)` | Boolean process checks | Returns true/false, never throws |
587 
588### Score tracking
589 
590Baseline (2026-04-09, before cleanup): 100 findings, 432.8 score, 2.38 score/file.
591After cleanup: 90 findings, 358.1 score, 1.96 score/file.
592 
593Don't chase the number. Fix patterns that represent actual code quality problems.
594Accept findings where the "sloppy" pattern is the correct engineering choice.
595 
596## Community PR guardrails
597 
598When reviewing or merging community PRs, **always AskUserQuestion** before accepting
599any commit that:
600 
6011. **Touches ETHOS.md** — this file is Garry's personal builder philosophy. No edits
602   from external contributors or AI agents, period.
6032. **Removes or softens promotional material** — YC references, founder perspective,
604   and product voice are intentional. PRs that frame these as "unnecessary" or
605   "too promotional" must be rejected.
6063. **Changes Garry's voice** — the tone, humor, directness, and perspective in skill
607   templates, CHANGELOG, and docs are not generic. PRs that rewrite voice to be
608   more "neutral" or "professional" must be rejected.
609 
610Even if the agent strongly believes a change improves the project, these three
611categories require explicit user approval via AskUserQuestion. No exceptions.
612No auto-merging. No "I'll just clean this up."
613 
614## Checking out PRs from garrytan-agents
615 
616When the user says "check out <PR link>" and the PR is from `garrytan-agents/gstack`
617(or any other fork that is NOT a collaborator on `garrytan/gstack`), do NOT just
618`gh pr checkout`. Fork PRs don't receive base-repo secrets (`ANTHROPIC_API_KEY`,
619`OPENAI_API_KEY`, etc.), so the eval/E2E CI jobs fail with empty-env auth errors
620regardless of what's set on the base repo.
621 
622**Workflow:** push the branch to `garrytan/gstack` (the base repo) and re-target
623the PR from there.
624 
625Concretely, after `gh pr checkout <N>`:
626 
6271. Note the original PR number and head branch name.
6282. Push the same branch to the base repo: `git push origin HEAD:<branch-name>`
629   (origin = `garrytan/gstack`, since the worktree is set up with that remote).
6303. Close the fork PR (`gh pr close <N> --comment "moving to base-repo branch for secret access"`).
6314. Open a new PR from the base-repo branch: `gh pr create --base main --head <branch-name>`.
6325. New PR's workflows will get secrets automatically.
633 
634Why not fix it on the fork side? `garrytan-agents` isn't a collaborator on
635`garrytan/gstack`. Adding it as a collaborator (option A) or flipping the
636repo-wide "send secrets to fork PRs" toggle (option B) would let secrets reach
637fork PRs from anyone — broader blast radius than just moving this one branch.
638Option C (this section) keeps secret-distribution scope tight.
639 
640If the user asks you to skip the move (e.g., "just leave it as a fork PR"),
641respect that — eval CI will fail with empty-env auth, but check-freshness,
642workflow-lint, and windows-tests will still pass on the fork PR.
643 
644## CHANGELOG + VERSION style
645 
646**Versioning invariant (workspace-aware ship).** VERSION is a monotonic ordered
647release identifier, not a strict semver commitment. The bump level
648(major/minor/patch/micro) expresses intent at ship time. Queue-advancing past a
649claimed version within the same bump level is explicitly permitted — if branch A
650claims v1.7.0.0 as a MINOR and branch B is also a MINOR, B lands at v1.8.0.0
651(still a MINOR relative to main). Downstream consumers must NOT rely on
652"MINOR = feature-only, PATCH = fix-only" as a strict contract. This is why
653`bin/gstack-next-version` advances within the chosen bump level rather than
654repicking the level when collisions happen.
655 
656**Scale-aware bumps — use common sense.** When the diff is big, bump MINOR (or
657MAJOR), not PATCH. PATCH is for bug fixes and small additions; MINOR is for
658substantial new capability or substantial reduction; MAJOR is for breaking
659changes. Rough guideposts (don't treat as rules, treat as smell-checks):
660 
661- **PATCH (X.Y.Z+1.0)**: bug fix, doc tweak, small additive change, single
662  test/file added. Net diff under ~500 lines, no new user-facing capability.
663- **MINOR (X.Y+1.0.0)**: new capability shipped (skill, harness, command, big
664  refactor), substantial code reduction (compression, migration), or coordinated
665  multi-file change. Net diff over ~2000 lines added/removed, OR a user-visible
666  feature you'd put in a tweet.
667- **MAJOR (X+1.0.0.0)**: breaking change to public surface (CLI flag rename,
668  skill removed, config format changed), OR a release big enough to be the
669  headline of a blog post.
670 
671If you find yourself debating "is 10K added + 24K removed really a PATCH?" — it
672isn't. Bump MINOR. Same for "this adds a whole new test harness with 6 new E2E
673tests + helper utilities" — MINOR. The bump level is communication to the user
674about what kind of release this is; don't undersell it.
675 
676When merging origin/main brings a higher VERSION, re-evaluate the bump level
677against the SCALE of your branch's work, not just whether main moved forward.
678If main bumped MINOR and your branch is also a substantial change, you bump
679MINOR again on top (e.g., main at v1.14.0.0, your branch lands v1.15.0.0).
680 
681**VERSION and CHANGELOG are branch-scoped.** Every feature branch that ships gets its
682own version bump and CHANGELOG entry. The entry describes what THIS branch adds —
683not what was already on main.
684 
685**The CHANGELOG entry is the diff between main and the shipping branch — what users
686get when they upgrade. NOT how the branch got there.** A reader landing on the entry
687should learn what they can do now that they couldn't before; they should not learn
688about the branch's internal version bumps, the bugs we caught and fixed mid-branch,
689the plan reviews we ran, or the commits we squashed. That is branch development
690narrative. It belongs in PR descriptions and commit messages, not CHANGELOG.
691 
692**Never reference branch-internal versions in a CHANGELOG entry.** If your branch
693bumped VERSION from v1.5.0.0 → v1.5.1.0 → v1.6.0.0 during development and only the
694final v1.6.0.0 ships to main, the entry must read as if v1.5.1.0 never existed.
695Concretely, NEVER write:
696- "v1.5.1.0 had a bug that v1.6.0.0 fixes" — readers don't know about v1.5.1.0; it's
697  a branch-internal artifact.
698- "The shipping headline of v1.5.1.0 was broken because..." — same reason. From main's
699  perspective, v1.5.1.0 was never released.
700- "Pre-fix tests encoded the broken behavior" — that's a contributor's victory lap,
701  not a user benefit.
702- "Two surgical edits, both in the dispatch path" — micro-narrative of the patch.
703 
704Instead, describe the released system: "Browser-skills run end-to-end with the
705expected tab-access semantics." If a property of the shipped system is worth calling
706out (e.g., "skill spawns get permissive tab access; pair-agent tunnel tokens require
707ownership"), document it as a property, not as a fix. The shipped system is what
708the user gets; the path to that system is invisible to them.
709 
710**When to write the CHANGELOG entry:**
711- At `/ship` time (Step 13), not during development or mid-branch.
712- The entry covers ALL commits on this branch vs the base branch.
713- Never fold new work into an existing CHANGELOG entry from a prior version that
714  already landed on main. If main has v0.10.0.0 and your branch adds features,
715  bump to v0.10.1.0 with a new entry — don't edit the v0.10.0.0 entry.
716 
717**Key questions before writing:**
7181. What branch am I on? What did THIS branch change?
7192. Is the base branch version already released? (If yes, bump and create new entry.)
7203. Does an existing entry on this branch already cover earlier work? (If yes, replace
721   it with one unified entry for the final version.)
722 
723**Merging main does NOT mean adopting main's version.** When you merge origin/main into
724a feature branch, main may bring new CHANGELOG entries and a higher VERSION. Your branch
725still needs its OWN version bump on top. If main is at v0.13.8.0 and your branch adds
726features, bump to v0.13.9.0 with a new entry. Never jam your changes into an entry that
727already landed on main. Your entry goes on top because your branch lands next.
728 
729**After merging main, always check:**
730- Does CHANGELOG have your branch's own entry separate from main's entries?
731- Is VERSION higher than main's VERSION?
732- Is your entry the topmost entry in CHANGELOG (above main's latest)?
733If any answer is no, fix it before continuing.
734 
735**After any CHANGELOG edit that moves, adds, or removes entries,** immediately run
736`grep "^## \[" CHANGELOG.md` to verify no duplicates and a sensible reverse-chronological
737order. Gaps between version numbers are fine. A branch that ships at v1.6.4.0 without
738a prior v1.5.2.0 or v1.5.3.0 entry on main is correct — those were branch-internal
739version numbers that never landed. Do not back-fill gaps with placeholder entries.
740 
741**Never orphan branch-internal versions.** If your branch bumped VERSION several times
742during development (v1.5.1.0 → v1.5.2.0 → v1.6.4.0, say) and those earlier entries were
743never released to main, the final ship consolidates ALL of them into a single entry at
744the final version (v1.6.4.0). Collapse them — delete the old entries and move their
745content into the final entry, re-version table columns accordingly. Readers see one
746release, not a branch diary. Gaps are fine (v1.6.3.0 → v1.6.4.0 with no v1.5.x
747in between on main is correct).
748 
749CHANGELOG.md is **for users**, not contributors. Write it like product release notes:
750 
751- Lead with what the user can now **do** that they couldn't before. Sell the feature.
752- Use plain language, not implementation details. "You can now..." not "Refactored the..."
753- **Never mention TODOS.md, internal tracking, eval infrastructure, or contributor-facing
754  details.** These are invisible to users and meaningless to them.
755- Put contributor/internal changes in a separate "For contributors" section at the bottom.
756- Every entry should make someone think "oh nice, I want to try that."
757- No jargon: say "every question now tells you which project and branch you're in" not
758  "AskUserQuestion format standardized across skill templates via preamble resolver."
759 
760**Only document what shipped between main and this change.** Readers do not care how
761we got here. Keep out of the CHANGELOG, always:
762 
763- Branch resyncs, merge commits with main, rebase activity.
764- Plan approvals, review outcomes (CEO / eng / design / outside-voice / codex findings),
765  AskUserQuestion decisions, scope negotiations.
766- "Work queued," "plan approved," "in-progress," "will ship later" — the CHANGELOG
767  documents what DID ship, not what MIGHT ship.
768- Version-bump housekeeping when no user-facing work actually landed.
769 
770If the diff between the base branch version and this version has no user-facing change
771(only merges, only CHANGELOG edits, only placeholder work), the honest entry is one
772sentence: "Version bump for branch-ahead discipline. No user-facing changes yet." Stop
773there. Do not pad. Do not explain the plan that will ship eventually. Do not narrate
774the branch's history. When real work lands, the entry will replace this at /ship time.
775 
776### Release-summary format (every `## [X.Y.Z]` entry)
777 
778Every version entry in `CHANGELOG.md` MUST start with a release-summary section in
779the GStack/Garry voice, one viewport's worth of prose + tables that lands like a
780verdict, not marketing. The itemized changelog (subsections, bullets, files) goes
781BELOW that summary, separated by a `### Itemized changes` header.
782 
783The release-summary section gets read by humans, by the auto-update agent, and by
784anyone deciding whether to upgrade. The itemized list is for agents that need to
785know exactly what changed.
786 
787Structure for the top of every `## [X.Y.Z]` entry:
788 
7891. **Two-line bold headline** (10-14 words total). Should land like a verdict, not
790   marketing. Sound like someone who shipped today and cares whether it works.
7912. **Lead paragraph** (3-5 sentences). What shipped, what changed for the user.
792   Specific, concrete, no AI vocabulary, no em dashes, no hype.
7933. **A "The X numbers that matter" section** with:
794   - One short setup paragraph naming the source of the numbers (real production
795     deployment OR a reproducible benchmark, name the file/command to run).
796   - A table of 3-6 key metrics with BEFORE / AFTER / Δ columns.
797   - A second optional table for per-category breakdown if relevant.
798   - 1-2 sentences interpreting the most striking number in concrete user terms.
7994. **A "What this means for [audience]" closing paragraph** (2-4 sentences) tying
800   the metrics to a real workflow shift. End with what to do.
801 
802Voice rules for the release summary:
803- No em dashes (use commas, periods, "...").
804- No AI vocabulary (delve, robust, comprehensive, nuanced, fundamental, etc.) or
805  banned phrases ("here's the kicker", "the bottom line", etc.).
806- Real numbers, real file names, real commands. Not "fast" but "~30s on 30K pages."
807- Short paragraphs, mix one-sentence punches with 2-3 sentence runs.
808- Connect to user outcomes: "the agent does ~3x less reading" beats "improved precision."
809- Be direct about quality. "Well-designed" or "this is a mess." No dancing.
810 
811Source material:
812- CHANGELOG previous entry for prior context.
813- Benchmark files or `/retro` output for headline numbers.
814- Recent commits (`git log <prev-version>..HEAD --oneline`) for what shipped.
815- Don't make up numbers. If a metric isn't in a benchmark or production data,
816  don't include it. Say "no measurement yet" if asked.
817 
818Target length: ~250-350 words for the summary. Should render as one viewport.
819 
820### Itemized changes (below the release summary)
821 
822Write `### Itemized changes` and continue with the detailed subsections (Added,
823Changed, Fixed, For contributors). Same rules as the user-facing voice guidance
824above, plus:
825 
826- **Always credit community contributions.** When an entry includes work from a
827  community PR, name the contributor with `Contributed by @username`. Contributors
828  did real work. Thank them publicly every time, no exceptions.
829 
830## AI effort compression
831 
832When estimating or discussing effort, always show both human-team and CC+gstack time:
833 
834| Task type | Human team | CC+gstack | Compression |
835|-----------|-----------|-----------|-------------|
836| Boilerplate / scaffolding | 2 days | 15 min | ~100x |
837| Test writing | 1 day | 15 min | ~50x |
838| Feature implementation | 1 week | 30 min | ~30x |
839| Bug fix + regression test | 4 hours | 15 min | ~20x |
840| Architecture / design | 2 days | 4 hours | ~5x |
841| Research / exploration | 1 day | 3 hours | ~3x |
842 
843Completeness is cheap. Don't recommend shortcuts when the complete implementation
844is achievable. Boil the ocean — the complete thing is the goal; only genuinely
845unrelated multi-quarter migrations are separate scope, never an excuse for a
846shortcut. See the Completeness Principle in the skill preamble for the full
847philosophy.
848 
849## Search before building
850 
851Before designing any solution that involves concurrency, unfamiliar patterns,
852infrastructure, or anything where the runtime/framework might have a built-in:
853 
8541. Search for "{runtime} {thing} built-in"
8552. Search for "{thing} best practice {current year}"
8563. Check official runtime/framework docs
857 
858Three layers of knowledge: tried-and-true (Layer 1), new-and-popular (Layer 2),
859first-principles (Layer 3). Prize Layer 3 above all. See ETHOS.md for the full
860builder philosophy.
861 
862## Local plans
863 
864Contributors can store long-range vision docs and design documents in `~/.gstack-dev/plans/`.
865These are local-only (not checked in). When reviewing TODOS.md, check `plans/` for candidates
866that may be ready to promote to TODOs or implement.
867 
868## E2E eval failure blame protocol
869 
870When an E2E eval fails during `/ship` or any other workflow, **never claim "not
871related to our changes" without proving it.** These systems have invisible couplings —
872a preamble text change affects agent behavior, a new helper changes timing, a
873regenerated SKILL.md shifts prompt context.
874 
875**Required before attributing a failure to "pre-existing":**
8761. Run the same eval on main (or base branch) and show it fails there too
8772. If it passes on main but fails on the branch — it IS your change. Trace the blame.
8783. If you can't run on main, say "unverified — may or may not be related" and flag it
879   as a risk in the PR body
880 
881"Pre-existing" without receipts is a lazy claim. Prove it or don't say it.
882 
883## Long-running tasks: don't give up
884 
885When running evals, E2E tests, or any long-running background task, **poll until
886completion**. Use `sleep 180 && echo "ready"` + `TaskOutput` in a loop every 3
887minutes. Never switch to blocking mode and give up when the poll times out. Never
888say "I'll be notified when it completes" and stop checking — keep the loop going
889until the task finishes or the user tells you to stop.
890 
891The full E2E suite can take 30-45 minutes. That's 10-15 polling cycles. Do all of
892them. Report progress at each check (which tests passed, which are running, any
893failures so far). The user wants to see the run complete, not a promise that
894you'll check later.
895 
896## Running evals as an agent: always detach (SIGTERM-proof)
897 
898When **you (an agent/harness)** launch a long eval/benchmark run, run it through
899`bin/gstack-detach` — NEVER as a plain backgrounded Bash task. A plain background
900task lives in the harness's process group, so a SIGTERM ("polite quit") on a turn
901boundary, a stopped Monitor, or an interruption kills the run mid-flight (observed:
902`script "test:gate" was terminated by signal SIGTERM` ~40 min into a run). On macOS
903the run can also die to idle-sleep. `gstack-detach` fixes both: a fresh session
904(escapes the group SIGTERM) wrapped in `caffeinate -i` (blocks idle-sleep).
905 
906- Use the `eval:bg*` scripts (`eval:bg`, `eval:bg:all`, `eval:bg:gate`,
907  `eval:bg:periodic`) — they wrap the eval command in `gstack-detach` with the
908  machine-wide `gstack-evals` lock (concurrent worktrees serialize instead of
909  saturating the shared model API), a per-tier watchdog, and a **run-scoped** log
910  under `~/.gstack-dev/eval-runs/` (no shared-`/tmp` collision). Each prints its
911  log path. `eval:bg:gate` / `eval:bg:periodic` run their tier through the
912  sharded paid runner (`scripts/test-paid-shards.ts`, also exposed as
913  `test:gate:sharded` / `test:periodic:sharded`): one Bun process per test
914  file, an external wall-clock timeout that kills the shard's process GROUP
915  (stray `claude`/`codex` grandchildren included), a per-shard
916  `GSTACK_EVAL_DIR=<evalDir>/shards/<slug>/` honored by the `EvalCollector`
917  constructor, and an aggregate that separates failed vs timed-out vs
918  never-started shards — the detach timeouts (25200s gate / 28800s periodic)
919  are sized against worst-case shard wall clock. `eval:list` / `eval:compare` /
920  `eval:summary` read the shard dirs too. Or call
921  `gstack-detach [--lock NAME] [--timeout SECS] [--label LBL] --
922  <cmd>` directly for any long agent job. Export `ANTHROPIC_API_KEY` first (never
923  pass keys in argv).
924- Then **poll the printed logfile** with a death-aware watcher: break on the
925  guaranteed `### gstack-detach EXIT=<code> ###` sentinel (success AND failure are
926  both marked, so silence is never mistaken for success). The detached run survives
927  even if your watcher gets reaped, so re-checking the log always works.
928- Why the lock: a shared dev box with several Conductor worktrees will rate-limit
929  the model API if two eval suites run at once (15-way concurrency each), which
930  mass-times-out E2E tests. The lock makes the second run WAIT, not collide.
931- Humans running `bun run test:evals` foreground in their own terminal don't need
932  this — Ctrl-C is intended there. Detachment is for agent-launched runs only.
933 
934## E2E test fixtures: extract, don't copy
935 
936**NEVER copy a full SKILL.md file into an E2E test fixture.** SKILL.md files are
9371500-2000 lines. When `claude -p` reads a file that large, context bloat causes
938timeouts, flaky turn limits, and tests that take 5-10x longer than necessary.
939 
940Instead, extract only the section the test actually needs:
941 
942```typescript
943// BAD — agent reads 1900 lines, burns tokens on irrelevant sections
944fs.copyFileSync(path.join(ROOT, 'ship', 'SKILL.md'), path.join(dir, 'ship-SKILL.md'));
945 
946// GOOD — agent reads ~60 lines, finishes in 38s instead of timing out
947const full = fs.readFileSync(path.join(ROOT, 'ship', 'SKILL.md'), 'utf-8');
948const start = full.indexOf('## Review Readiness Dashboard');
949const end = full.indexOf('\n---\n', start);
950fs.writeFileSync(path.join(dir, 'ship-SKILL.md'), full.slice(start, end > start ? end : undefined));
951```
952 
953Also when running targeted E2E tests to debug failures:
954- Run in **foreground** (`bun test ...`), not background with `&` and `tee`
955- Never `pkill` running eval processes and restart — you lose results and waste money
956- One clean run beats three killed-and-restarted runs
957 
958## Publishing native OpenClaw skills to ClawHub
959 
960Native OpenClaw skills live in `openclaw/skills/gstack-openclaw-*/SKILL.md`. These are
961hand-crafted methodology skills (not generated by the pipeline) published to ClawHub
962so any OpenClaw user can install them.
963 
964**Publishing:** The command is `clawhub publish` (NOT `clawhub skill publish`):
965 
966```bash
967clawhub publish openclaw/skills/gstack-openclaw-office-hours \
968  --slug gstack-openclaw-office-hours --name &quot;gstack Office Hours&quot; \
969  --version 1.0.0 --changelog &quot;description of changes&quot;
970```
971 
972Repeat for each skill: `gstack-openclaw-ceo-review`, `gstack-openclaw-investigate`,
973`gstack-openclaw-retro`. Bump `--version` on each update.
974 
975**Auth:** `clawhub login` (opens browser for GitHub auth). `clawhub whoami` to verify.
976 
977**Updating:** Same `clawhub publish` command with a higher `--version` and `--changelog`.
978 
979**Verification:** `clawhub search gstack` to confirm they're live.
980 
981## Deploying to the active skill
982 
983The active skill lives at `~/.claude/skills/gstack/`. After making changes:
984 
9851. Push your branch
9862. Fetch and reset in the skill directory: `cd ~/.claude/skills/gstack && git fetch origin && git reset --hard origin/main`
9873. Rebuild: `cd ~/.claude/skills/gstack && bun run build`
988 
989**If you use gbrain:** the `git reset --hard` in step 2 reverts the brain-aware
990(`GBRAIN_CONTEXT_LOAD` / `GBRAIN_SAVE_RESULTS`) blocks that `gstack-config
991gbrain-refresh` renders into the install (those generated blocks differ from
992`main` by design). After deploying, re-run `gstack-config gbrain-refresh` to
993restore them across all your projects' Claude sessions. It's idempotent.
994 
995Or copy the binaries directly:
996- `cp browse/dist/browse ~/.claude/skills/gstack/browse/dist/browse`
997- `cp design/dist/design ~/.claude/skills/gstack/design/dist/design`
998 
999## Skill routing
1000 
1001When the user's request matches an available skill, invoke it via the Skill tool. When in doubt, invoke the skill.
1002 
1003Key routing rules:
1004- Product ideas/brainstorming → invoke /office-hours
1005- Strategy/scope → invoke /plan-ceo-review
1006- Architecture → invoke /plan-eng-review
1007- Design system/plan review → invoke /design-consultation or /plan-design-review
1008- Full review pipeline → invoke /autoplan
1009- Bugs/errors → invoke /investigate
1010- QA/testing site behavior → invoke /qa or /qa-only
1011- Code review/diff check → invoke /review
1012- Visual polish → invoke /design-review
1013- Ship/deploy/PR → invoke /ship or /land-and-deploy
1014- Save progress → invoke /context-save
1015- Resume context → invoke /context-restore
1016 
1017## Cross-session decision memory
1018 
1019Durable decisions and their rationale are captured in an append-only, event-sourced
1020store at `~/.gstack/projects/<slug>/decisions.jsonl` so neither you nor the user
1021re-litigates a settled call or loses the "why" across sessions. This is the reliable,
1022file-only path: it works with gbrain OFF. (gbrain semantic recall is an optional
1023enhancement layered on top, never a dependency.)
1024 
1025- **Resurface** active decisions before re-deciding: `bin/gstack-decision-search`
1026  (`--recent N`, `--scope repo|branch|issue`, `--query KW`, `--all`, `--json`).
1027  Add `--semantic` (with `--query`) to append related hits from gbrain memory when
1028  it's up; it degrades silently to the reliable file results when gbrain is off.
1029  Session start already surfaces scope-relevant active decisions via Context Recovery.
1030  If a decision is listed, treat it as settled with its rationale; if you're about to
1031  reverse it, say so explicitly.
1032- **Capture** a DURABLE decision when you or the user make one:
1033  `bin/gstack-decision-log '{"decision":"...","rationale":"...","scope":"repo|branch|issue","source":"user|skill|agent","confidence":1-10}'`.
1034  Reverse a prior call with `--supersede <id>`; expunge an accidental secret with
1035  `--redact <id>`; rewrite the log to the active set with `--compact`. Non-interactive
1036  (never prompts), injection-sanitized, and HIGH-secret-blocking on write.
1037- **Durable means:** architecture choice, scope cut, tool/vendor choice, or a reversal
1038  of a prior call. NOT a turn-level edit, a phrasing tweak, or anything trivially
1039  re-derivable. Capture is curated at the source — log durable decisions only, or the
1040  store becomes noise.
1041 
1042## GBrain Search Guidance (configured by /sync-gbrain)
1043<!-- gstack-gbrain-search-guidance:start -->
1044 
1045GBrain is set up and synced on this machine. The agent should prefer gbrain
1046over Grep when the question is semantic or when you don't know the exact
1047identifier yet.
1048 
1049**This worktree is pinned to a worktree-scoped code source** via the
1050`.gbrain-source` file in the repo root (kubectl-style context). Any
1051`gbrain code-def`, `code-refs`, `code-callers`, `code-callees`, or `query`
1052call from anywhere under this worktree routes to that source by default —
1053no `--source` flag needed. Conductor sibling worktrees of the same repo
1054each have their own pin and their own indexed pages, so semantic results
1055match the actual code on disk in this worktree.
1056 
1057Two indexed corpora available via the `gbrain` CLI:
1058- This worktree's code (auto-pinned via `.gbrain-source`).
1059- `~/.gstack/` curated memory (registered as `gstack-brain-<user>` source via
1060  the existing federation pipeline).
1061 
1062Prefer gbrain when:
1063- "Where is X handled?" / semantic intent, no exact string yet:
1064    `gbrain search "<terms>"` or `gbrain query "<question>"`
1065- "Where is symbol Y defined?" / symbol-based code questions:
1066    `gbrain code-def <symbol>` or `gbrain code-refs <symbol>`
1067- "What calls Y?" / "What does Y depend on?":
1068    `gbrain code-callers <symbol>` / `gbrain code-callees <symbol>`
1069- "What did we decide last time?" / past plans, retros, learnings:
1070    `gbrain search "<terms>" --source gstack-brain-<user>`
1071 
1072Grep is still right for known exact strings, regex, multiline patterns, and
1073file globs. Run `/sync-gbrain` after meaningful code changes; for ongoing
1074auto-sync across all worktrees, run `gbrain autopilot --install` once per
1075machine — gbrain's daemon handles incremental refresh on a schedule.
1076 
1077Safety: don't run `/sync-gbrain` while `gbrain autopilot` is active — the
1078orchestrator refuses destructive source ops when it detects a running autopilot
1079to avoid racing it (#1734). Prefer registering user repos with `gbrain sources
1080add --path <dir>` (no `--url`): URL-managed sources can auto-reclone, and the
1081sync code walk for them requires an explicit `--allow-reclone` opt-in.
1082 
1083<!-- gstack-gbrain-search-guidance:end -->
1084