diff --git a/.github/docker/Dockerfile.ci b/.github/docker/Dockerfile.ci index ebf4a4d13f..99591ebd21 100644 --- a/.github/docker/Dockerfile.ci +++ b/.github/docker/Dockerfile.ci @@ -28,9 +28,13 @@ RUN printf 'Acquire::Retries "5";\nAcquire::http::Timeout "30";\nAcquire::https: # System deps (retry apt-get update + install as a unit — even Hetzner can blip). # Includes xz-utils so the Node.js .tar.xz download below can decompress. +# python3: bin/gstack-jsonl-merge, gstack-brain-sync, gstack-detach, and other +# bash bins shell out to it (macOS ships python3; the base image doesn't). +# file: skill-validation's no-compiled-binaries-in-git check runs `file --mime-type`. +# poppler-utils: make-pdf's e2e gates hard-require pdftotext/pdffonts/pdfinfo in CI. RUN for i in 1 2 3; do \ apt-get update && apt-get install -y --no-install-recommends \ - git curl unzip xz-utils ca-certificates jq bc gpg && break || \ + git curl unzip xz-utils ca-certificates jq bc gpg python3 file poppler-utils && break || \ (echo "apt retry $i/3 after failure"; sleep 10); \ done \ && rm -rf /var/lib/apt/lists/* @@ -61,10 +65,14 @@ RUN curl --retry 5 --retry-delay 5 --retry-connrefused -fsSL "https://nodejs.org && node --version \ && npm --version -# Bun (install to /usr/local so non-root users can access it) +# Bun (install to /usr/local so non-root users can access it). +# The version MUST be passed as a positional arg — bun.sh/install ignores a +# BUN_VERSION env var, so the old `| BUN_VERSION=x.y.z bash` form silently +# installed latest on every image rebuild (observed: 1.3.13/1.3.14 drift vs +# the 1.3.10 devs run locally). ENV BUN_INSTALL="/usr/local" RUN curl --retry 5 --retry-delay 5 --retry-connrefused -fsSL https://bun.sh/install \ - | BUN_VERSION=1.3.10 bash + | bash -s "bun-v1.3.10" # Claude CLI RUN npm i -g @anthropic-ai/claude-code @@ -82,8 +90,10 @@ RUN npx playwright install-deps chromium # (headed-xvfb, headed-orphan-cleanup) can exercise the Linux container # auto-spawn path on every CI run. Without Xvfb in the image, the most # common production --headed path goes untested. +# fonts-noto-color-emoji: the make-pdf emoji render gate needs a color-emoji +# fallback font (mirrors make-pdf-gate.yml's Ubuntu setup step). RUN for i in 1 2 3; do \ - apt-get update && apt-get install -y --no-install-recommends fonts-liberation fontconfig xvfb x11-utils && break || \ + apt-get update && apt-get install -y --no-install-recommends fonts-liberation fonts-noto-color-emoji fontconfig xvfb x11-utils && break || \ (echo "fonts-liberation install retry $i/3"; sleep 10); \ done \ && fc-cache -f \ @@ -105,6 +115,7 @@ RUN npx playwright install chromium \ # Verify everything works RUN bun --version && node --version && claude --version && jq --version && gh --version \ + && python3 --version && command -v file && command -v pdftotext && command -v pdffonts && command -v pdfinfo \ && npx playwright --version \ && fc-match "Liberation Sans" | grep -qi "Liberation" \ || (echo "ERROR: fonts-liberation not installed — make-pdf PDFs will render in DejaVu Sans" && exit 1) diff --git a/.github/workflows/actionlint.yml b/.github/workflows/actionlint.yml index 1fb654aa82..6f0d3fe214 100644 --- a/.github/workflows/actionlint.yml +++ b/.github/workflows/actionlint.yml @@ -1,5 +1,13 @@ name: Workflow Lint on: [push, pull_request] + +# Cancel superseded runs for the same branch (matches evals.yml, +# windows-free-tests.yml, etc.). head_ref is set on pull_request; ref_name is +# the fallback for push so a rapid push series doesn't pile up stale lint runs. +concurrency: + group: actionlint-${{ github.head_ref || github.ref_name }} + cancel-in-progress: true + jobs: actionlint: runs-on: ubicloud-standard-8 diff --git a/.github/workflows/evals.yml b/.github/workflows/evals.yml index f5a0d9e40a..3b30271e60 100644 --- a/.github/workflows/evals.yml +++ b/.github/workflows/evals.yml @@ -45,19 +45,30 @@ jobs: - if: steps.check.outputs.exists == 'false' run: cp package.json bun.lock .github/docker/ + # A fork PR's GITHUB_TOKEN only has `packages: read`, so pushing fails. + # Still BUILD (validates Dockerfile.ci changes), just don't publish. This + # job intentionally keeps no `if:` so fork PRs still get one real, honest + # green check here instead of a run where every job is grey. - if: steps.check.outputs.exists == 'false' uses: docker/build-push-action@v6 with: context: .github/docker file: .github/docker/Dockerfile.ci - push: true + push: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }} tags: | ${{ steps.meta.outputs.tag }} ${{ env.IMAGE }}:latest + # Fork PRs never receive repository secrets (ANTHROPIC_API_KEY et al), so every + # API-calling eval fails at SDK auth before a model runs. Skip deterministically + # rather than leaving the outcome to Docker-cache luck: a warm cache let these + # run and fail, a cold one made build-image fail its push and the shards skip. + # Same-repo PRs, pushes, and workflow_dispatch keep full coverage. Fork work + # gets real coverage via a trusted base-repo branch. evals: runs-on: ${{ matrix.suite.runner || 'ubicloud-standard-8' }} needs: build-image + if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository container: image: ${{ needs.build-image.outputs.image-tag }} credentials: @@ -169,19 +180,28 @@ jobs: console.log("seeded", p); ' - # PTY smokes drive the interactive `claude` TUI and send /office-hours and - # /plan-ceo-review. Claude Code discovers user-scoped skills from - # $HOME/.claude/skills//SKILL.md, but .claude/skills is gitignored, so - # a fresh CI checkout has NO registry — claude prints "Unknown command: - # /plan-ceo-review". Mirror setup's --no-prefix registry minimally: a gstack - # root symlink (resolves the preamble's absolute ~/.claude/skills/gstack/bin/* - # and ~/.claude/skills/gstack//sections/* paths) plus a per-skill - # top-level dir holding SKILL.md (+ sections) symlinks for the two skills + # PTY smokes drive the interactive `claude` TUI and send /office-hours, + # /plan-ceo-review, /plan-eng-review, and /plan-design-review. Claude Code + # discovers user-scoped skills from $HOME/.claude/skills//SKILL.md, + # but .claude/skills is gitignored, so a fresh CI checkout has NO registry + # — claude prints "Unknown command: /plan-ceo-review". Mirror setup's + # --no-prefix registry minimally: a gstack root symlink (resolves the + # preamble's absolute ~/.claude/skills/gstack/bin/* and + # ~/.claude/skills/gstack//sections/* paths) plus a per-skill + # top-level dir holding SKILL.md (+ sections) symlinks for the four skills # these tests invoke. No ./setup (it builds binaries, launches Chromium, # installs fonts, reads a /dev/tty prompt) and no binary build (SKILL.md + # bin/ + sections/ are committed). $HOME is /github/home here; the spawned # claude inherits it (this runner adds no HOME/CLAUDE_CONFIG_DIR override, # no hermetic mode) and the Seed step already proved claude reads $HOME. + # + # KEEP THIS STEP even though seedSkills/hermeticSkillsConfigDir() now + # registers skills for hermetic PTY children: that registry is SYMLINKS + # into the repo checkout, and this container's cross-mount symlinks + # defeat the TUI skill scanner (see the note inside the step below) — + # the real-file copies here are what the TUI actually reads. HOME is + # also not hermeticized, so the absolute ~/.claude/skills/gstack/... + # preamble paths resolve through the gstack root symlink this step makes. - name: Register gstack skills for PTY smoke if: matrix.suite.name == 'e2e-pty-plan-smoke' run: | @@ -201,7 +221,7 @@ jobs: # registry recognized it, isolating the failure to the container's # cross-mount symlink). Copy SKILL.md + sections as real files so the TUI # reads them directly. - for s in office-hours plan-ceo-review; do + for s in office-hours plan-ceo-review plan-eng-review plan-design-review; do rm -rf "${SKILLS_DIR:?}/$s" mkdir -p "$SKILLS_DIR/$s" cp "$REPO/$s/SKILL.md" "$SKILLS_DIR/$s/SKILL.md" @@ -216,7 +236,7 @@ jobs: # ~/.claude/skills/gstack symlink above. PROJ_SKILLS="$REPO/.claude/skills" mkdir -p "$PROJ_SKILLS" - for s in office-hours plan-ceo-review; do + for s in office-hours plan-ceo-review plan-eng-review plan-design-review; do rm -rf "${PROJ_SKILLS:?}/$s" mkdir -p "$PROJ_SKILLS/$s" cp "$REPO/$s/SKILL.md" "$PROJ_SKILLS/$s/SKILL.md" @@ -229,18 +249,22 @@ jobs: for f in \ "$SKILLS_DIR/office-hours/SKILL.md" \ "$SKILLS_DIR/plan-ceo-review/SKILL.md" \ + "$SKILLS_DIR/plan-eng-review/SKILL.md" \ + "$SKILLS_DIR/plan-design-review/SKILL.md" \ "$SKILLS_DIR/gstack/bin/gstack-update-check" \ "$SKILLS_DIR/gstack/office-hours/sections/design-and-handoff.md" \ - "$SKILLS_DIR/gstack/plan-ceo-review/sections/review-sections.md"; do + "$SKILLS_DIR/gstack/plan-ceo-review/sections/review-sections.md" \ + "$SKILLS_DIR/gstack/plan-eng-review/sections/review-sections.md" \ + "$SKILLS_DIR/gstack/plan-design-review/sections/review-sections.md"; do if [ ! -e "$f" ]; then echo "ERROR: skill-registry target missing (symlink dangles): $f" >&2 exit 1 fi done - grep -m1 '^name: office-hours$' "$SKILLS_DIR/office-hours/SKILL.md" >/dev/null \ - || { echo "ERROR: office-hours SKILL.md missing 'name: office-hours' frontmatter" >&2; exit 1; } - grep -m1 '^name: plan-ceo-review$' "$SKILLS_DIR/plan-ceo-review/SKILL.md" >/dev/null \ - || { echo "ERROR: plan-ceo-review SKILL.md missing 'name: plan-ceo-review' frontmatter" >&2; exit 1; } + for s in office-hours plan-ceo-review plan-eng-review plan-design-review; do + grep -m1 "^name: $s\$" "$SKILLS_DIR/$s/SKILL.md" >/dev/null \ + || { echo "ERROR: $s SKILL.md missing 'name: $s' frontmatter" >&2; exit 1; } + done echo "skill registry OK" - name: Run ${{ matrix.suite.name }} @@ -263,7 +287,7 @@ jobs: report: runs-on: ubicloud-standard-8 needs: evals - if: always() && github.event_name == 'pull_request' + if: always() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository timeout-minutes: 5 permissions: contents: read diff --git a/.github/workflows/free-tests.yml b/.github/workflows/free-tests.yml new file mode 100644 index 0000000000..05a2afde5d --- /dev/null +++ b/.github/workflows/free-tests.yml @@ -0,0 +1,184 @@ +name: Free Tests +# The full free suite (`bun test`: browse/test/ + test/ + make-pdf/test/ minus +# paid evals) previously ran in NO CI job — only Windows curated shards, paid +# evals, and doc-freshness gates existed. Two test files crashed at module load +# for 48 versions without any signal. This job closes that hole. +on: + pull_request: + branches: [main] + workflow_dispatch: + +concurrency: + group: free-tests-${{ github.head_ref }} + cancel-in-progress: true + +env: + IMAGE: ghcr.io/${{ github.repository }}/ci + +jobs: + # Same cached pre-baked toolchain image as evals.yml (only rebuilds on + # Dockerfile/lockfile change). + build-image: + runs-on: ubicloud-standard-8 + permissions: + contents: read + packages: write + outputs: + image-tag: ${{ steps.meta.outputs.tag }} + steps: + - uses: actions/checkout@v4 + + - id: meta + run: echo "tag=${{ env.IMAGE }}:${{ hashFiles('.github/docker/Dockerfile.ci', 'package.json', 'bun.lock') }}" >> "$GITHUB_OUTPUT" + + - uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Check if image exists + id: check + run: | + if docker manifest inspect ${{ steps.meta.outputs.tag }} > /dev/null 2>&1; then + echo "exists=true" >> "$GITHUB_OUTPUT" + else + echo "exists=false" >> "$GITHUB_OUTPUT" + fi + + - if: steps.check.outputs.exists == 'false' + run: cp package.json bun.lock .github/docker/ + + - if: steps.check.outputs.exists == 'false' + uses: docker/build-push-action@v6 + with: + context: .github/docker + file: .github/docker/Dockerfile.ci + push: true + tags: | + ${{ steps.meta.outputs.tag }} + ${{ env.IMAGE }}:latest + + free-tests: + runs-on: ubicloud-standard-8 + needs: build-image + container: + image: ${{ needs.build-image.outputs.image-tag }} + credentials: + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + options: --user runner + timeout-minutes: 45 + steps: + - uses: actions/checkout@v4 + + # Bun creates root-owned temp dirs during Docker build. GH Actions runs as + # runner user with HOME=/github/home. Redirect bun's cache to a writable dir. + - name: Fix bun temp + run: | + mkdir -p /home/runner/.cache/bun + { + echo "BUN_INSTALL_CACHE_DIR=/home/runner/.cache/bun" + echo "BUN_TMPDIR=/home/runner/.cache/bun" + echo "TMPDIR=/home/runner/.cache" + } >> "$GITHUB_ENV" + + # Several test files exercise real git operations (gstack-artifacts-init, + # session-update-autostash, team-mode, brain-sync) and bins that read the + # current branch (gstack-decision-search). The container checkout is owned + # by a different uid than `runner`, so git needs safe.directory, and + # commit-making tests need an identity. + - name: Git identity for git-exercising tests + run: | + git config --global user.email "ci@gstack.invalid" + git config --global user.name "gstack CI" + git config --global --add safe.directory '*' + + # Same restore rationale as evals.yml: recursive copy beats symlink + # (realpath escapes workspace) and hardlink (cross-device overlay-fs). + - name: Restore deps + run: | + if [ -d /opt/node_modules_cache ] && diff -q /opt/node_modules_cache/.package.json package.json >/dev/null 2>&1; then + cp -r /opt/node_modules_cache node_modules + else + bun install + fi + + - run: bun run build + + # Fail fast if the container can't launch Chromium — the browse + # integration tests need it. + - name: Verify Chromium + run: | + echo "whoami=$(whoami) HOME=$HOME TMPDIR=${TMPDIR:-unset}" + bun -e "import {chromium} from 'playwright';const b=await chromium.launch({args:['--no-sandbox']});console.log('Chromium OK');await b.close()" + + # ONE BUN PROCESS PER FILE, on purpose. A single multi-file `bun test` + # run of this suite is structurally unreliable here — observed twice + # while building this job: + # 1. Silent truncation: server-lifecycle tests stub process.exit, and + # shutdown's async timers can hit the REAL exit after restore, + # killing the whole bun process mid-suite with exit 0 and NO + # summary (died at file 47, then file 51, of 358). + # 2. Co-run state bleed: files green in isolation failed under + # multi-file module sharing. + # Per-file spawning makes truncation impossible by construction (the + # census drives the loop; a killed child is a recorded failure, not a + # vanished suite) and also covers the old exit-0-on-module-load-error + # Bun behavior. Same isolation model as scripts/test-paid-shards.ts. + - name: Run free suite (per-file isolation) + shell: bash + run: | + set -o pipefail + # Container-incompatible files, each with a reason (same curated- + # exclusion pattern as the Windows shards in test-free-shards.ts). + # Anything NOT on this list that fails still fails the job. Trimming + # this list is tracked follow-up work. + declare -A SKIP=( + [browse/test/compare-board.test.ts]="pre-existing env failure (also fails on dev machines; needs a display-shaped env)" + [browse/test/handoff.test.ts]="needs the headed Chrome-for-Testing build (headless-only container)" + [browse/test/snapshot.test.ts]="pre-existing env failure (viewport/tab timing under container load)" + [browse/test/extension-sender-auth.test.ts]="extension identity checks need a real chrome-extension origin" + [browse/test/security-sidepanel-dom.test.ts]="sidepanel DOM harness needs the extension loaded headed" + [browse/test/terminal-agent-integration.test.ts]="real PTY round-trip; container TTY semantics differ" + [browse/test/xvfb.test.ts]="tests xvfb management; container has no X server to manage" + [browse/test/security-audit-r2.test.ts]="one behavioral tmpdir-allowlist test breaks under this job's TMPDIR override (bun temp-dir workaround above)" + [design/test/variants-retry-after.test.ts]="known timing flake, tracked in TODOS.md (HTTP-date Retry-After rounding)" + ) + FILES=$(bun run scripts/test-free-shards.ts --list | grep -E '^ (browse/|test/|make-pdf/|design/)' | sed 's/^ //') + TOTAL=$(echo "$FILES" | wc -l | tr -d ' ') + echo "Enumerated $TOTAL free test files" + FAILED="" + N=0 + SKIPPED=0 + for f in $FILES; do + N=$((N+1)) + if [ -n "${SKIP[$f]:-}" ]; then + echo "SKIP [$N/$TOTAL] $f — ${SKIP[$f]}" + SKIPPED=$((SKIPPED+1)) + continue + fi + if ! bun test "$f" > /tmp/one.log 2>&1; then + echo "FAIL [$N/$TOTAL] $f" + tail -30 /tmp/one.log + FAILED="$FAILED $f" + fi + done + echo "Skipped $SKIPPED container-incompatible files (reasons above)." + # Tree-mutation tripwire: a test that rewrites tracked files poisons + # every later file in the loop with confusing failures (observed: + # gstack-config's skill_prefix auto-relink patched 52 SKILL.md names, + # failing five unrelated suites downstream). Name the real culprit. + MUTATED=$(git status --porcelain --untracked-files=no) + if [ -n "$MUTATED" ]; then + echo "" + echo "A test mutated tracked files in the working tree — later failures may be collateral:" + echo "$MUTATED" + FAILED="$FAILED [tree-mutation]" + fi + if [ -n "$FAILED" ]; then + echo "" + echo "Failed files:$FAILED" + exit 1 + fi + echo "All $((TOTAL-SKIPPED)) runnable files green." diff --git a/.github/workflows/skill-docs.yml b/.github/workflows/skill-docs.yml index 700a8222ae..cd1ecb9263 100644 --- a/.github/workflows/skill-docs.yml +++ b/.github/workflows/skill-docs.yml @@ -1,5 +1,13 @@ name: Skill Docs Freshness on: [push, pull_request] + +# Cancel superseded runs for the same branch (matches evals.yml, +# windows-free-tests.yml, etc.). head_ref is set on pull_request; ref_name is +# the fallback for push so a rapid push series doesn't pile up stale runs. +concurrency: + group: skill-docs-${{ github.head_ref || github.ref_name }} + cancel-in-progress: true + jobs: check-freshness: runs-on: ubicloud-standard-8 @@ -7,27 +15,32 @@ jobs: - uses: actions/checkout@v4 - uses: oven-sh/setup-bun@v2 - run: bun install - - name: Check Claude host freshness - run: bun run gen:skill-docs - - name: Verify Claude skill docs are fresh + # One generation pass for ALL 10 hosts. gen-skill-docs --host all + # hard-fails on any per-host generation error (scripts/gen-skill-docs.ts + # aggregates failures and exits non-zero), so every host is gated on + # "generates cleanly." Known limitation, on purpose: the 9 gitignored + # host outputs (.agents/, .factory/, .kiro/, ...) are NOT byte-freshness + # checked — `git diff` on ignored untracked paths is always empty (the + # previous per-host `git diff -- .agents/` gates could never fail for + # exactly that reason). Byte-freshness is enforced only for tracked + # output (the Claude SKILL.md files), which the two steps below cover. + - name: Generate all host skill docs + run: bun run gen:skill-docs --host all + - name: Verify tracked skill docs are fresh run: | git diff --exit-code || { - echo "Generated SKILL.md files are stale. Run: bun run gen:skill-docs" + echo "Generated SKILL.md files are stale. Run: bun run gen:skill-docs --host all" exit 1 } - - name: Check Codex host freshness - run: bun run gen:skill-docs --host codex - - name: Verify Codex skill docs are fresh + # git diff misses NEW untracked files (e.g. a freshly added skill whose + # generated SKILL.md was never committed). Fail on any untracked stray + # the generator produced outside the gitignored host dirs. + - name: Verify no untracked generated files run: | - git diff --exit-code -- .agents/ || { - echo "Generated Codex SKILL.md files are stale. Run: bun run gen:skill-docs --host codex" + STRAYS=$(git status --porcelain --untracked-files=all | grep '^??' || true) + if [ -n "$STRAYS" ]; then + echo "Generator produced untracked files that are neither committed nor gitignored:" + echo "$STRAYS" + echo "Commit them (bun run gen:skill-docs --host all) or gitignore them." exit 1 - } - - name: Generate Factory skill docs - run: bun run gen:skill-docs --host factory - - name: Verify Factory skill docs are fresh - run: | - git diff --exit-code -- .factory/ || { - echo "Generated Factory SKILL.md files are stale. Run: bun run gen:skill-docs --host factory" - exit 1 - } + fi diff --git a/AGENTS.md b/AGENTS.md index 4df7eec35f..fd66423aba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,6 +20,8 @@ Invoke them by name (e.g., `/office-hours`). | `/plan-devex-review` | DX-mode review: TTHW, magical moments, friction points, persona traces. | | `/plan-tune` | Self-tune AskUserQuestion sensitivity per question. | | `/autoplan` | One command runs CEO → design → eng → DX review. | +| `/autobuilder-loop` | Drive an approved plan to completion via model-routed subagents, review gates, and Docker verification. | +| `/plan-deliverables` | Turn an approved plan into per-milestone acceptance criteria, each paired with the check that validates it. | | `/design-consultation` | Build a complete design system from scratch. | | `/spec` | Turn vague intent into a precise, executable spec in five phases. Files a GitHub issue, optionally spawns a Claude Code agent in a fresh worktree, and lets `/ship` close the source issue on merge. | diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 3dba8f3ba1..f6d584c8cb 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -91,14 +91,15 @@ When a user runs `pair-agent --client`, the daemon starts an ngrok tunnel so a r The fix is **two HTTP listeners**, not one: -- **Local listener** (`127.0.0.1:LOCAL_PORT`) — always bound. Serves bootstrap (`/health` with token delivery), `/cookie-picker`, `/inspector/*`, `/welcome`, `/refs`, the sidebar-agent API, and the full command surface. Never forwarded. +- **Local listener** (`127.0.0.1:LOCAL_PORT`) — always bound. Serves token bootstrap (`POST /extension-token`, released only to the pinned extension identity), `/health` (liveness/status only — never a token), `/cookie-picker`, `/inspector/*`, `/welcome`, `/refs`, the sidebar-agent API, and the full command surface. Never forwarded. - **Tunnel listener** (`127.0.0.1:TUNNEL_PORT`) — bound lazily on `/tunnel/start`, torn down on `/tunnel/stop`. Serves a locked allowlist: `/connect` (pairing ceremony, unauth + rate-limited), `/command` (scoped tokens only, further restricted to a browser-driving command allowlist), and `/sidebar-chat`. Everything else 404s. ngrok forwards only the tunnel port. The security property comes from **physical port separation**: a tunnel caller cannot reach `/health` or `/cookie-picker` because those paths don't exist on that TCP socket. Header inference (check `x-forwarded-for`, check origin) is unreliable (ngrok header behavior changes; local proxies can add these headers); socket separation isn't. | Endpoint | Local listener | Tunnel listener | Notes | |---|---|---|---| -| `GET /health` | public (no token unless headed/extension) | 404 | Token bootstrap for extension happens locally only | +| `GET /health` | public (liveness/status only — never a token) | 404 | Token bootstrap moved to `POST /extension-token` (v1.63) | +| `POST /extension-token` | pinned Origin (`chrome-extension://`) + loopback Host | 404 | The only endpoint that hands out the root token | | `GET /connect` | public (`{alive:true}`) | public (`{alive:true}`) | Probe path for tunnel liveness | | `POST /connect` | public (rate-limited 300/min) | public (rate-limited) | Setup-key exchange for pair-agent | | `POST /command` | auth (Bearer root OR scoped) | auth (scoped only, allowlisted commands) | Root token on tunnel = 403 | @@ -114,6 +115,8 @@ ngrok forwards only the tunnel port. The security property comes from **physical | `GET /inspector/events` | Bearer OR HttpOnly `gstack_sse` cookie | 404 | SSE. Same cookie as /activity/stream | | `POST /sse-session` | auth (Bearer) | 404 | Mints the view-only 30-min SSE session cookie | +**Extension token bootstrap (v1.63.0.0).** `GET /health` never carries a token in any mode — it is liveness/status only. The sidebar extension obtains the root token via `POST /extension-token`, which releases it only when the caller's Origin is exactly `chrome-extension://` (pinned by the `key` field in `extension/manifest.json`; reproduce the derivation with `bun browse/scripts/extension-id.ts`) and the Host header parses to a loopback hostname — parsed with `new URL()`, never compared raw, because Host carries the port. Web pages cannot forge a `chrome-extension://` Origin, and the endpoint is never added to the tunnel allowlist, so the tunnel surface 404s it by default-deny. + **Tunnel surface denial logs.** Every rejection on the tunnel listener (`path_not_on_tunnel`, `root_token_on_tunnel`, `missing_scoped_token`, `disallowed_command:*`) is recorded asynchronously to `~/.gstack/security/attempts.jsonl` with timestamp, source IP (from `x-forwarded-for`), path, and method. Rate-capped at 60 writes/min globally to prevent log-flood DoS. Shares the attempt log with the prompt-injection scanner. **SSE session cookies.** EventSource can't send Authorization headers, so the extension POSTs `/sse-session` once at bootstrap with the root Bearer and receives a 30-minute view-only cookie (`gstack_sse`, HttpOnly, SameSite=Strict). The cookie is valid ONLY for `/activity/stream` and `/inspector/events` — it is NOT a scoped token and cannot be used on `/command`. Scope isolation is enforced by the module boundary: `sse-session-cookie.ts` has no imports from `token-registry.ts`. @@ -144,6 +147,14 @@ Cookies are the most sensitive data gstack handles. The design: The browser registry (Comet, Chrome, Arc, Brave, Edge) is hardcoded. Database paths are constructed from known constants, never from user input. Keychain access uses `Bun.spawn()` with explicit argument arrays, not shell string interpolation. +### Egress receipt ledger (v1.63.0.0) + +Every enumerated gstack-initiated off-machine sink writes a hash-chained, tamper-evident receipt to `~/.gstack/security/egress.jsonl` BEFORE the send — `writeReceipt` in `lib/egress-receipt.ts` for TypeScript callers, `_receipted_curl` / `_receipted_git` from `bin/gstack-egress-lib.sh` for shell scripts. Receipts record a sha256 of the exact bytes sent when the caller owns them (subprocess-owned sends like git pushes record `sha256: null`); they never store the body. + +Failure polarity is per-class and pinned by tests. Sensitive sinks are fail-closed: brain-sync pushes, memory-ingest, gbrain-sync, telemetry, ngrok tunnel starts, mcp-verify, and supabase-provision refuse to send if the receipt can't be written (each refusal prints problem + cause + fix). User-facing sinks fail open with a stderr warning — the design binary's OpenAI calls, update-check, the read-only dashboards, and git-class receipts proceed even when the receipt write failed, so a fail-open send can go unrecorded (warned, by design). The new-sink scanner in `test/egress-receipt-wiring.test.ts` fails CI when an off-machine sink ships unwired; its only exemptions are enumerated with reasons (user-directed page fetches, reachability probes, install-doc strings, skill prose). + +Inspect the ledger with `bin/gstack-egress`: `list` (what gstack attempted to send), `verify` (recompute the chain, exit 3 on tamper), `grants` (the standing consent settings and how to revoke each). Threat model: the ledger is forensic observability of ATTEMPTED egress — it records what gstack tried to send so accidents are auditable; it is not an exfiltration control. + ### Unicode sanitization at server egress (v1.38.0.0) Page content harvested by CDP can contain lone UTF-16 surrogate halves (orphaned high or low surrogates from broken JavaScript string handling on the page). When those reach `JSON.stringify`, Bun emits them as `\uD800`-style escape sequences that the downstream consumer's `JSON.parse` accepts, but the Anthropic API rejects with a 400 — turning a single weird page into a session-killing error. Defense is single-point, applied at every server egress that ships page-derived strings. @@ -414,7 +425,7 @@ The `EvalCollector` accumulates test results and writes them in two ways: 1. **Incremental:** `savePartial()` writes `_partial-e2e.json` after each test (atomic: write `.tmp`, `fs.renameSync`). Survives kills. 2. **Final:** `finalize()` writes a timestamped eval file (e.g. `e2e-20260314-143022.json`). The partial file is never cleaned up — it persists alongside the final file for observability. -`eval:compare` diffs two eval runs. `eval:summary` aggregates stats across all runs in `~/.gstack-dev/evals/`. +`eval:compare` diffs two eval runs. `eval:summary` aggregates stats across all runs in `~/.gstack-dev/evals/`. Both are shard-aware (v1.63.0.0): the sharded paid runner (`scripts/test-paid-shards.ts`, run via `test:gate:sharded` / `test:periodic:sharded` — the `eval:bg:gate` / `eval:bg:periodic` scripts now point at these) gives each shard's collector its own directory at `/shards//` through the `GSTACK_EVAL_DIR` env var (honored by the `EvalCollector` constructor), and `eval:list` / `eval:compare` / `eval:summary` scan one level of `shards//` subdirectories. Baseline lookups exclude `_partial` accumulators (`isPartialEval` / `findLatestFinalizedRun` in `eval-store.ts`), so auto-comparison never uses the current run's own partial file as its baseline. ### Test tiers diff --git a/BROWSER.md b/BROWSER.md index affa0447d1..0463950806 100644 --- a/BROWSER.md +++ b/BROWSER.md @@ -705,6 +705,10 @@ Or do it manually: `chrome://extensions` → toggle Developer mode → Load unpacked → navigate to `~/.claude/skills/gstack/extension` → pin the extension → enter the port from `$B status`. +v1.63 pinned the extension identity via the manifest `key` field, so existing +unpacked installs get a new extension ID and panel-local state (saved port) +resets once — a one-time in-product notice explains this. + --- ## Pair-agent @@ -758,6 +762,15 @@ remote agent that tries them gets a 403 plus a fresh entry in the denial log. + domain only (no raw IP, no full request body), rotates at 10MB with 5 generations. Per-device salt at `~/.gstack/security/device-salt` (mode 0600). +### Tunnel egress receipts (v1.63+) + +Every tunnel session open writes a hash-chained egress receipt (sink +`browse-tunnel`) to `~/.gstack/security/egress.jsonl` BEFORE ngrok forwards +anything. Fail-closed: if the receipt can't be written, the tunnel listener +is torn down and the start is refused. Inspect the ledger with +`bin/gstack-egress list` and verify chain integrity with +`bin/gstack-egress verify` (exit 3 on tamper). + See [`docs/REMOTE_BROWSER_ACCESS.md`](docs/REMOTE_BROWSER_ACCESS.md) for the full operator guide. @@ -800,6 +813,19 @@ The Terminal pane uses a separate session cookie, `gstack_pty`, minted via PTY, can't dispatch arbitrary `/command` calls. `/health` endpoint MUST NOT surface this token. +### Extension token bootstrap (v1.63+) + +`GET /health` is liveness/status only — it never carries a token, in any +mode. The Side Panel extension bootstraps the root token via +`POST /extension-token` on the local listener. The server releases the +token only when the caller's Origin is exactly +`chrome-extension://` — the `key` field in +`extension/manifest.json` pins the extension ID (`GSTACK_EXTENSION_ID` in +`browse/src/server.ts`; derivation reproducible via +`bun browse/scripts/extension-id.ts`) — AND the parsed Host hostname is +loopback. Anything else gets a detail-free 403. The endpoint is never +added to `TUNNEL_PATHS`, so the tunnel surface 404s it by default-deny. + ### Token registry `browse/src/token-registry.ts` handles mint/validate/revoke for all three @@ -811,50 +837,46 @@ startup. ## Security stack -Layered defense against prompt injection. Every layer runs synchronously on -every user message and every tool output that could carry untrusted content -(Read, Glob, Grep, WebFetch, page text from `$B`). +Layered defense against prompt injection on untrusted page content. | Layer | Module | Lives in | |-------|--------|----------| -| **L1** Datamarking | `content-security.ts` | both server + sidebar agent | -| **L2** Hidden-element strip | `content-security.ts` | both | -| **L3** ARIA + URL blocklist + envelope wrapping | `content-security.ts` | both | -| **L4** TestSavantAI ML classifier (22MB ONNX) | `security-classifier.ts` | sidebar-agent only* | -| **L4b** Claude Haiku transcript check | `security-classifier.ts` | sidebar-agent only | -| **L5** Canary token (session-exfil detection) | `security.ts` | both — inject in compiled, check in agent | -| **L6** `combineVerdict` ensemble | `security.ts` | both | +| **L1** Datamarking | `content-security.ts` | server + page-content read path | +| **L2** Hidden-element strip | `content-security.ts` | server + page-content read path | +| **L3** ARIA + URL blocklist + envelope wrapping | `content-security.ts` | server + page-content read path | +| **L4** TestSavantAI ML classifier (112MB ONNX) | `security-classifier.ts` | security sidecar subprocess* | +| Canary token utilities | `security.ts` | pure functions — no live injector today | +| `combineVerdict` ensemble | `security.ts` | server (inline L4 verdict path) | \* `security-classifier.ts` cannot be imported from the compiled browse binary — `@huggingface/transformers` v4 requires `onnxruntime-node` which fails to `dlopen` from Bun compile's temp extract dir. The compiled binary -runs L1–L3, L5, L6 only. +runs L1–L3 plus the pure parts of `security.ts`; L4 runs in a plain-Node +sidecar (`security-sidecar-entry.ts`, spawned lazily by +`security-sidecar-client.ts` on the first `/pty-inject-scan`). ### Thresholds - `BLOCK: 0.85` — single-layer score that would cause BLOCK if cross-confirmed -- `WARN: 0.75` — cross-confirm threshold. When L4 AND L4b both >= 0.75 → BLOCK -- `LOG_ONLY: 0.40` — gates transcript classifier (skip Haiku when all layers < 0.40) +- `WARN: 0.75` — cross-confirm threshold in `combineVerdict` +- `LOG_ONLY: 0.40` — log-only floor - `SOLO_CONTENT_BLOCK: 0.92` — single-layer threshold for label-less content classifiers ### Ensemble rule -BLOCK only when the ML content classifier AND the transcript classifier both -report >= WARN. Single-layer high confidence degrades to WARN — this is the -Stack Overflow instruction-writing FP mitigation. **Canary leak always -BLOCKs (deterministic).** +`combineVerdict` retains multi-layer ensemble semantics (2-of-N block votes; +single-layer high confidence degrades to WARN — the Stack Overflow +instruction-writing FP mitigation), but only L4 (testsavant) is live today: +the Haiku transcript and DeBERTa ensemble layers were removed along with the +sidebar chat pipeline that hosted them. **Canary leak always BLOCKs +(deterministic).** ### Env knobs - `GSTACK_SECURITY_OFF=1` — emergency kill switch. Classifier stays off - even if warmed. Canary is still injected; just the ML scan is skipped. -- `GSTACK_SECURITY_ENSEMBLE=deberta` — opt-in DeBERTa-v3 ensemble. Adds - ProtectAI DeBERTa-v3-base-injection-onnx as L4c classifier. 721MB - first-run download. With ensemble enabled, BLOCK requires 2-of-3 ML - classifiers agreeing at >= WARN. + even if warmed. Just the ML scan is skipped. - Classifier model cache: `~/.gstack/models/testsavant-small/` (112MB, first - run only) plus `~/.gstack/models/deberta-v3-injection/` (721MB, only when - ensemble enabled). + run only). - Attack log: `~/.gstack/security/attempts.jsonl` (salted SHA-256 + domain only, rotates at 10MB, 5 generations). - Per-device salt: `~/.gstack/security/device-salt` (0600). @@ -1198,7 +1220,6 @@ the global `~/.gstack/browser-skills/foo/` only inside project-a. | `BROWSE_TUNNEL_LOCAL_ONLY` | 0 | Test-only — bind both listeners locally without ngrok | | `GSTACK_BROWSE_MAX_HTML_BYTES` | 52428800 (50MB) | `load-html` size cap | | `GSTACK_SECURITY_OFF` | unset | Emergency kill switch — disable ML classifier | -| `GSTACK_SECURITY_ENSEMBLE` | unset | Set to `deberta` for 3-classifier ensemble (721MB download) | | `GSTACK_STEALTH` | unset | Set to `extended` (also accepts `1`/`true`) to layer six aggressive patches (WebGL spoof, faked plugins, mediaDevices) on top of Layer C. Actively lies; can break sites. | | `GSTACK_CDP_STEALTH` | unset | Set to `on`/`1`/`true` to emit `--gstack-suppress-prepare-stack-trace` (gbrowser Pack 2 / B11 C++ patch only; no-op on stock Chromium) | | `GSTACK_GPU_VENDOR`, `GSTACK_GPU_RENDERER`, `GSTACK_GPU_CHIPSET` | unset | Per-install GPU spoof fed to the Pack 1 WebGL/UA-CH C++ patches. Set by gbd from the host profile; emitted as `--gstack-gpu-vendor` / `--gstack-gpu-renderer` / `--gstack-ua-model` cmdline switches only when present. | @@ -1246,7 +1267,7 @@ browse/ │ ├── url-validation.ts # URL safety checks for goto │ ├── content-security.ts # L1-L3: datamarking, hidden strip, ARIA, URL blocklist, envelopes │ ├── security.ts # L5 canary + L6 verdict combiner + thresholds -│ ├── security-classifier.ts # L4 ML classifier (TestSavant + optional DeBERTa ensemble) +│ ├── security-classifier.ts # L4 ML classifier (TestSavantAI, runs in the security sidecar) │ ├── terminal-agent.ts # Side Panel Claude PTY manager (auth + lifecycle) │ ├── sidebar-utils.ts # Sidebar URL sanitization + helpers │ ├── cookie-import-browser.ts # Decrypt + import cookies from real Chromium browsers @@ -1393,9 +1414,7 @@ foundation. The prompt-injection L4 layer uses [TestSavantAI/distilbert-v1.1-32](https://huggingface.co/TestSavantAI/distilbert-v1.1-32) -(112MB ONNX), and the optional ensemble layer uses -[ProtectAI/deberta-v3-base-prompt-injection-v2](https://huggingface.co/protectai/deberta-v3-base-prompt-injection-v2) -(721MB ONNX) — both run locally via `@huggingface/transformers`. +(112MB ONNX), run locally via `@huggingface/transformers`. The CDP escape hatch is gated by an allowlist directly inspired by Codex's T2 outside-voice review during the v1.4 design pass: deny-default with an diff --git a/CHANGELOG.md b/CHANGELOG.md index 351e7cabde..f30522fe4d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,545 @@ # Changelog +## [1.64.1.0] - 2026-08-15 + +**Every guard in the pipeline now provably fires.** +**And the codebase stopped describing features it doesn't have.** + +This release is a fix wave over the parts of gstack that earlier-generation +models wrote and later rips left behind. The free test suite now runs in CI +with per-file isolation, all ten host outputs are gated on every push, the +tunnel security allowlist matches the endpoints that exist, and the security +documentation describes the defenses that actually run. One template bug fix +alone cut 46KB from /spec's skill file, and eight utility skills stopped +carrying onboarding prose written for a different tier. Net: 24,943 lines +lighter across 183 files. + +### The numbers that matter + +Source: this branch's verification runs (`bun test` per-file, `bun run +gen:skill-docs --host all`, the JSON config dump-diff) and `git diff +origin/main...HEAD --stat`. + +| Metric | Before | After | Delta | +|---|---|---|---| +| Free test files running in CI | 0 | 358, one process per file | truncation impossible by construction | +| Host doc-freshness gates that can fail | 1 of 10 | 10 of 10 | two gates diffed gitignored paths | +| spec/SKILL.md | 127,462 bytes | 80,924 bytes | one preamble, not two | +| hosts/*.ts config code | 595 lines | 285 lines | defineHost() factory, byte-identical output | +| Eval tier-gate implementations | ~40 drifted copies, 6 predicates | 1 | the unset-tier trap is pinned forever | +| Net repo size | baseline | -24,943 lines | 24 files deleted outright | + +The tier table is the one to feel: `/scrape`, `/diagram`, and the browser +launchers each shed 271 lines of preamble they inherited from a silent +default. Skills now declare their tier or the generator refuses to build. + +### What this means for gstack users + +Skill invocations for the trimmed utilities load less prose into your context +window, /spec loads 46KB lighter, and a red test in this repo now means a red +check on the PR that caused it, every time, on every host. If you maintain a +fork or embed the browse daemon: two ServerConfig fields that never worked +(idleTimeoutMs, chromiumProfile) are gone rather than lying, and +GSTACK_SECURITY_ENSEMBLE no longer exists as a knob. Upgrade normally; no +migration needed. + +### Itemized changes + +#### Fixed +- CI: the skill-docs freshness gate covers all 10 hosts through one + `gen:skill-docs --host all` pass plus a tracked-drift diff and an + untracked-strays check. The Codex and Factory gates previously diffed + gitignored paths, which always pass. +- CI: new Free Tests workflow runs the whole free suite (358 files) with one + bun process per file on the prebaked toolchain image. Per-file isolation + sidesteps two observed silent-truncation modes (a process.exit race in + server-lifecycle tests, and co-run module-state bleed) and the historical + Bun exit-0-on-module-load-error behavior. +- Security: removed the deleted /sidebar-chat endpoint from TUNNEL_PATHS, + the audited tunnel attack surface. The set is now exactly /connect and + /command, and the closed-set pin test enforces that. +- Security: deleted chain's unreachable direct-dispatch fallback, which + routed commands without scope, domain, tab-ownership, rate-limit, or + JS-origin checks. The JS-origin assertion in read commands is now + unconditional. +- Security: page-content logs (console, network, dialog, command audit) go + through appendSecureFile, gaining owner-only permissions from creation on + every platform. +- Stealth: the headless-to-headed handoff path uses the shared Chromium + profile resolution and singleton-lock cleanup instead of a hardcoded path + that ignored CHROMIUM_PROFILE and GSTACK_HOME. +- Generator: /spec's skill file rendered its entire preamble twice because + template prose mentioned a placeholder literally. Fixed; 46,538 bytes + removed from the generated file. +- Generator: preamble tiers are declared per skill and a missing declaration + is a build error. Eight skills that silently defaulted to the heaviest + tier now carry the right one (scrape, diagram, the browser launchers at + tier 1; landing-report, pair-agent, skillify at tier 2; spec at tier 3). +- Generator: learningsMode is read from host config instead of a hardcoded + host check, so the seven basic-mode hosts get the project-scoped learnings + flow their runtimes can execute. +- Test selection: touchfile dependency paths are validated against disk (the + guard caught four rotted entries on its first run), and the eval-watch + dashboard reads partial results from the directory the collector writes. +- Eval gating: one describeE2ETier implementation replaces ~40 drifted + copies. The sharded paid runner's pre-spawn classifier understands the new + shape, so gate runs no longer pay for periodic shard startup. + +#### Changed +- hosts/*.ts declare only what differs per host; defineHost() derives the + rest. Proven byte-identical via a JSON dump-diff of all ten configs and a + zero-diff regeneration. +- pty-session-cookie and sse-session-cookie share one session-registry + implementation with separate token spaces; the terminal agent uses the + shared cookie parser. +- One lone-surrogate sanitizer and one sanitizeReplacer live in sanitize.ts; + one startTunnel() owns the ngrok start sequence that existed three times. +- lib/fs-atomic.ts is the single atomic-write implementation (pid+random + tmp suffix, throw and quiet variants, mode-at-create). lib and browse + call sites migrated, including a latent deterministic-tmp collision race + in the worktree dedup index. +- lib/jsonl-store.ts documents its real contract (callers screen for + injection patterns; the enforcing callers are named), gains a mode option, + and the lib-side bypass appenders now use it. + +#### Removed +- The dead ML security layers: the Haiku transcript classifier and the + DeBERTa ensemble (GSTACK_SECURITY_ENSEMBLE), which had no production + callers, plus their paid benchmark suite and fixtures. The live path is + the testsavant content scan in the security sidecar. CLAUDE.md and + BROWSER.md now document exactly that. +- Five HostConfig fields nothing read (metadataFormat, sidecar, prefixable, + staticFiles, adapter) and the fully dead openclaw-adapter module. +- Seven registered template placeholders no template used, the never-adopted + gated-resolver mechanism, and the codex-helpers shadow module whose stale + copy silently lost to a local redeclaration. +- Two ServerConfig fields that were documented but never read (idleTimeoutMs, + chromiumProfile); BROWSE_IDLE_TIMEOUT and CHROMIUM_PROFILE env remain the + working knobs. +- proactive-suggestions.json (31KB regenerated on every build, read by + nothing), two zero-caller bin + scripts (gstack-open-url, gstack-platform-detect), an orphaned schema + module, three orphaned test fixtures (including a 128KB golden that had + drifted 46KB from its live successor), and a superseded duplicate of the + ship-idempotency eval. +- ~2,000 lines of tests that exercised deleted features: two files that + crashed at import reading a source file deleted 48 versions ago, a + whole dead-endpoint integration file, and 20 describes of chat-pipeline + UX pins inside sidebar-ux.test.ts (its live coverage remains, now green). + +#### For contributors +- setup accepts --host cursor and --host slate (the hand-rolled allowlists + had drifted from hosts/index.ts). +- The openclaw CLAUDE.md variants are real template files under + openclaw/templates/ instead of string literals inside the generator. +- Ghost comments describing sidebar-agent.ts as a live process are scrubbed + from 10 files; server.ts tombstone blocks enumerating deleted identifiers + are gone. +- docs/ADDING_A_HOST.md teaches the defineHost pattern. + +## [1.64.0.0] - 2026-08-14 + +**Ninety fixes in one wave. Every guard that said it was protecting you now actually does.** + +This release is a fix wave built from a full audit of the tracker: every open +PR and every open issue, verified against main before anything landed. The +pattern that kept showing up was guards that failed open. The freeze and +careful hooks emitted a payload shape Claude Code ignores, so deny meant +allow. The redact pre-push hook had six separate paths that let a credential +through. The test suite exited green after running 4% of itself. All of that +is fixed, with a regression test or a static tripwire pinning each one shut. + +The wave absorbs the best community fix for each defect, credited by name: +82 contributors are named in this release, several of whom independently +fixed the same bug within days of each other. That duplication is the +tracker telling us how many people hit the same wall. + +### The numbers that matter + +Source: `git log 1.63.0.0..HEAD` on this branch, plus the audit workflow +records referenced in the PR. + +| Metric | Before | After | +|---|---|---| +| Free-suite files that actually run | ~16 of 434 (truncated, exit 0) | all 434, honest exit code | +| Guard hooks that can block (freeze/careful/team-init) | 0 of 3 | 3 of 3, fail closed | +| Native AskUserQuestion answers recorded | 14% | 100%, suffix-aware | +| /codex runs per macOS session before breaking | 1 | unlimited (mktemp fixed) | +| Issues closed by this release | — | 52 | +| Community PRs absorbed with credit | — | ~50 | + +The suite number is the one to sit with. A delayed process.exit(0) in one +test file killed the whole run mid-flight with a green exit code — so every +other guarantee in CI was resting on a suite that could not fail. It can +fail now, a fault-injection test proves the failure propagates, and the +sharded runner treats a summary-less shard as failed. + +### What this means for you + +Skill enforcement (/freeze, /careful, team required-mode) actually blocks. +The redact guard scans big diffs instead of blocking them unscanned, and +quoted arguments can't hide an rm -rf from /careful. Auto-upgrade un-wedges +itself on installs with local patches. Memory ingest refuses to claim +success while importing nothing. Windows installs stop bricking .gstack +when your hostname matches your username, stop flashing console windows, +and the plan-tune hooks finally record your answers. Design image +generation works again. Update gstack and the wave is yours. + +### Itemized changes + +#### Fixed — enforcement guards +- /freeze deny and /careful ask decisions nest under hookSpecificOutput so + Claude Code honors them; team-init required mode blocks with exit 2 even + on schema drift. Contributed by @jawadakram20, @Masashi-Ono0611. +- /careful parses the tool payload with a real JSON parser (quoted + arguments no longer truncate the command), asks on IFS/base64 + obfuscation, fails closed on unreadable input, and multi-line commands + cannot ride the safe-exception whitelist. Contributed by @wtamminga. +- The investigate scope lock resolves check-freeze via $HOME (the + CLAUDE_SKILL_DIR path never resolved at hook time). Reported with a fix + by @maxpetrusenkoagent. +- Specialist review agents run with run_in_background: false — required + since Claude Code 2.1.198 made background the default. + +#### Fixed — credentials and redaction +- Pre-push scanning: line-aligned chunked scans for big diffs + (@luckywenapere), real push-base resolution instead of whole-repo blame + (@stormeoio), byte-exact stdin for chained hooks (@francis-eye), + --no-ext-diff/--no-textconv, hunk-aware header parsing, fail-closed ref + parsing (bypasses reported by @lubosxyz), GOCSPX + Telegram token + patterns (@francis-eye), UUID fixture false-positive suppression. +- pair-agent walks you through ngrok auth in YOUR terminal — the token + never enters the transcript. +- The extension denies token/port reads to content scripts and foreign + extensions, reimplemented for the v1.63 pinned-origin token model. + Contributed by @punksterlabs. +- diff 9.0.0 (GHSA-73rr-hh4g-fpgx, @genisis0x); OpenAI key file written + 0600-at-create (@bunlongheng); injection-denylist and phone-pattern + false positives calibrated (@Masashi-Ono0611, @JonasFocus, @abkrim). + +#### Fixed — test-suite integrity +- All eight delayed process.exit teardown bombs removed; static no-suicide + tripwire; fault-injection proof of exit-code propagation; the sharded + runner fails shards that exit 0 without bun's summary. Contributed by + @sneakygriff with repairs from @time-attack; also fixed by @whd4. +- design/test/ joins the free suite and the sharded runner (it never ran + anywhere before). +- The orphaned sidebar chat-queue suites are gone; live sidebar tests stay. +- Fork PRs skip eval jobs deterministically instead of red/green by Docker + cache luck. Contributed by @andrey-esipov. + +#### Fixed — silent data loss +- memory-ingest imports gitignored staging (@gawievanblerk), reconciles + imported-vs-staged counts and refuses to advance state on shortfall + (@Charles-Grant), with a version-adaptive flag fallback. +- lib/ ships beside bin/ on every host install — learnings, decisions and + telemetry scripts work outside Claude Code. Contributed by @fedster99; + supabase/config.sh copy by @jizusun. +- Native AskUserQuestion answers parse correctly (object-map shape), the + (Recommended) suffix compares equal, and extraction failures no longer + poison followed_recommendation. Based on the working patch by @yijisoo; + suffix fix by @chuchu2781. +- The autoplan task aggregator returns real tasks (jq scope bug swallowed + by 2>/dev/null). Contributed by @kkroo. +- Auto-upgrade pulls with --autostash over locally-patched installs and + logs the real failure reason. +- gstack-slug resolves the project root by marker walk-up (@ajeenkya), + canonicalizes slash branches (@ShuratCode), and keeps cached identity + sticky so adding a remote never renames your project. +- Design image generation: the gpt-image-2 tool pairing that 400'd every + call is fixed (@Pablosinyores), with honest timeout reporting (@vryahn). + +#### Fixed — Windows +- icacls grants by SID — hostname==username no longer bricks ~/.gstack + (@asizux2; independently fixed by @Icandi40, @chiragborse1, @IntegriGit, + @voltapix26). +- windowsHide forwarded through every spawn shim (@jerrynicholsai; + subsets by @jwilk-hrep, @rroojrooj, @WimvandenHeijkant); watchdog uses + signal-0 liveness with a reachable circuit breaker (@SYKhayyat); terminal + agents tie their lifetime to the owner PID (@csarigoz). +- All three plan-tune hooks spawn their bins through a shared + Windows-aware helper (@rafassousa); setup registers the SessionStart + hook with a bash prefix (@NikhileshNanduri); BROWSE_BIN gets its .exe + (@rroojrooj); the polyfill exposes an exited promise (@punksterlabs) + and the CJK terminal issues are gone (double-send fixed by + @mindsurf0176, full-width font cells by @tomfluff). +- New Windows regression tests run on windows-latest CI, not just as + static checks on macOS. + +#### Fixed — /codex +- mktemp templates keep the X-run trailing — /codex works past the first + run on macOS (@ShuratCode and @noron12234; also @cathrynlavery). +- codex review receives explicit diff args instead of silently reviewing + the dirty tree (@fangearhq-boop), wrapped in timeouts so truncation + stops reading as no-findings (@aegixx). +- Review mode runs sandboxed read-only; the P0/P1/P2 gate fails closed on + empty, untagged, or non-zero output; model-entitlement 400s get + actionable guidance. + +#### Fixed — everything else +- Artifacts Sync and telemetry-finalize un-deadened in 49 skills (quoted + tilde never expands — @jawadakram20). update_check:false now silences + the preamble prose too (@jc0d35). Codex hosts read AGENTS.md, not + CLAUDE.md (@exGeni). setup --help prints help (@saen-ai). Model overlays + for the current Claude generation (@chrisquorum). Plus ~20 more small + fixes credited in the git log: deploy-config URL parsing, artifacts-init + protocol handling, keychain auth detection, catalog description + truncation, tracked-file test counts, update-check crash sentinel, + Ubuntu 26.04 detection, CRLF-stable generation, telemetry error fields, + server-lock diagnostics, shell-quoted paths, benchmark arg validation, + and more. + +#### For contributors +- The enumerate-first repair protocol used here (defuse, enumerate, repair + before removing) is documented in the PR; the audit records live in the + session workflow journals. Four follow-up waves are captured in TODOS.md + with full context. + +## [1.63.0.0] - 2026-08-13 + +**Everything gstack sends off your machine now leaves a receipt you can read.** +**And the eval harness stopped grading itself a passing grade.** + +This release ports the parts of the GStack 2 fork that earned their way back into +main. The headline is a hash-chained egress ledger: every place gstack itself +sends data off your machine now writes a local, tamper-evident receipt first, and +`gstack-egress list` / `verify` show you exactly what left and prove the chain is +intact. Two new command-line tools ship with it: `gstack-egress` (the auditor's +view) and `gstack-context-bill` (a token bill-of-materials for any skills tree, so +you can see what a gstack install costs your context window before you invoke +anything). The test harness got three real fixes, one of them a bug that had been +quietly lying to every contributor for months. + +### The numbers that matter + +Source: the assembled branch (`git log 1.62.0.0..HEAD`), the free suite +(`bun test`), and the discovery-surface gate (`test/catalog-budget.test.ts`). + +| Metric | Before | After | Δ | +|---|---|---|---| +| gstack-owned off-machine sinks with a receipt | 0 | every enumerated sink | tripwire-enforced, zero exceptions | +| Eval "no regressions" lines that were self-comparisons | every one | 0 | the harness compared runs against their own in-progress accumulator | +| Paid gate runner isolation | one process, one hung file kills the tier | one process per file, group-SIGKILL on stall | + never-started accounting | +| Discovery catalog budget | unenforced | 1,105 token-equivalents measured, 1,150 ceiling | ratchet-protocol on every skill add | +| Browser `/health` endpoint | served the root auth token to any localhost caller in headed mode | serves no token in any mode | token bootstrap moved to a pinned-origin POST | + +The eval-store line is the one that matters most for anyone hacking on gstack: +`findPreviousRun` picked the newest same-tier file as the baseline, and the +in-progress `_partial` accumulator always won that sort, so the auto-comparison +compared a run against itself and printed "no regressions" no matter what. That is +fixed, with regression tests, and the fix was confirmed against the bug on the +prior release before landing. + +### What this means for you + +If you care what gstack does with your data, you can now audit it: run +`gstack-egress list` after any session and see every off-machine send, or +`gstack-egress verify` to confirm nothing was rewritten. If you contribute to +gstack, your eval comparisons mean something again, the paid gate can't be taken +down by one wedged test, and `gstack-context-bill` tells you what your skill +changes cost before you ship them. Nothing new phones home; the ledger is local +and the receipts record what gstack *attempts* to send, so accidents are auditable. + +Ported from the GStack 2 fork by Sina Matian (time-attack/gstack); the eval-store +bug fix and the port shortlist were selected and hardened for upstream. + +### Itemized changes + +#### Added +- `gstack-egress` — read the hash-chained egress receipt ledger: `list` (what + gstack attempted to send off-machine), `verify` (recompute the chain, exit 3 on + tamper), `grants` (the standing consent settings and how to revoke each). +- `gstack-context-bill` — offline token bill-of-materials for a skills tree: + always-on discovery cost vs per-invocation cost, `--diff` between two trees, + `--budget`, and `--exact` (opt-in, measures against the real tokenizer). +- Hash-chained egress receipts (`lib/egress-receipt.ts`): fail-closed + receipt-before-send for sensitive sinks (brain-sync, memory-ingest, gbrain-sync, + telemetry, tunnels), fail-open with a warning for user-facing sinks (the design + binary's model calls, update-check, dashboards). A tripwire test enforces that + every off-machine sink in the tree is wired, with zero silent exceptions. +- Sharded paid-gate runner (`test:gate:sharded` / `test:periodic:sharded`): one + process per test file, an external wall-clock timeout that group-SIGKILLs a + wedged file's whole process tree, and four-way per-shard status so a crash can't + masquerade as a pass. +- `gstack-context-bill` and the egress tools install through the standard `./setup` + path like every other gstack binary. + +#### Changed +- The browser `/health` endpoint no longer carries the root auth token in any + mode. The sidebar extension bootstraps its token through a new + `POST /extension-token` that requires the pinned extension origin and a loopback + Host; the tunnel listener never exposes it. Upgrading resets the sidebar's + panel-local state once, explained in-product. +- Hermetic PTY test children can register the repo's shipped skills, so + slash-command gate tests actually exercise the skill under test instead of + silently measuring nothing. +- Discovery-surface cost is now gated: `test/catalog-budget.test.ts` pins the + aggregate skill name+description budget with a self-service ratchet protocol. + +#### Fixed +- The eval harness auto-comparison compared every run against its own in-progress + accumulator and reported "no regressions" unconditionally. Fixed with regression + tests; comparisons now find the latest *completed* same-tier run. +- The browser `/health` token leak (a headed-mode carve-out that handed the root + token to any localhost caller). + +#### For contributors +- Shared modules replace duplicated logic: one paid-test-set definition consumed by + both the free-suite filter and the paid runner, one skill-census helper with three + explicit counts (physical files, authored skills, registry entries) consumed by + the seeder, context-bill, and the catalog gate. +- `CLAUDE.md`'s compiled-binaries note corrected: the `browse/dist` binaries have + been untracked since v0.11.16.0, so they no longer appear in `git status`. +- External-service E2E tests (Codex, Gemini, benchmark providers) are declared + periodic-tier with the canonical whole-file guard, so the merge-blocking gate + never waits on a third-party CLI. The Codex runner passes + `--skip-git-repo-check` (now required in non-git working dirs) and the Gemini + runner classifies an unusable CLI (removed flags, retired auth paths) as a + skip instead of a false failure. +- The PTY test runner parses AskUserQuestion prompts that reflow onto a single + logical line and strips DEC cursor-visibility residue, pinned by + `test/pty-askuserquestion-single-line.test.ts` — the failure class that + previously ate a gate test's whole time budget. +- New follow-ups filed in `TODOS.md`: egress ledger rotation (chain-genesis + records), a launch-nonce token bootstrap, and eval-watch shard-awareness. + +## [1.62.0.0] - 2026-08-12 + +## **Plan reviews stop asking what to review when you're in plan mode.** +## **The gate that guards normal sessions now knows when the answer is obvious.** + +Invoke /plan-eng-review or /plan-design-review while drafting a plan and the review just starts. No more "What should I review? A/B/C" when the only sensible answer is the plan on your screen. The skill announces its pick in one line ("Scope gate: plan mode — auto-selected B (reviewing your plan)") so you can redirect it, then goes straight to work. Name a target explicitly ("review PLAN.md") and the question is skipped in any mode. Outside plan mode with nothing named, the gate asks exactly as before, and it is still a hard stop. + +The bypass is engineered against abuse, not just convenience. Only the host's own plan-mode signal can arm it: plan-shaped text inside pasted documents, tool results, or fetched pages does not count, so injected content can't nominate its own review target. When several plan candidates exist, the host-referenced plan file wins; ambiguity means the skill asks. /autoplan stops surfacing the gate too — its loaded review skills now skip it, since the plan under review is already the target. + +### The numbers that matter + +Source: this branch's live PTY eval runs on 2026-08-11 (logs in ~/.gstack-dev/eval-runs/) and byte measurements from the generated skill files. + +| What | Before | After | +|------|--------|-------| +| Questions before a plan-mode review starts | 1 | 0 | +| Seeded plan-mode smokes (announcement rendered, no gate question) | n/a | 2/2 pass | +| Outside-plan-mode regression runs (gate still asks, bypass never misfires) | n/a | 4/4 pass | +| Finding-floor runs with the gate excluded from the count | trivially satisfiable | 2/2 pass, gate renders don't count | +| Stochastic smokes wrongly blocking the CI gate lane | 4 | 0 | + +That last row is a repair: four plan-mode/finding-floor smokes were demoted to the weekly tier months ago, but the demotion never took effect — the test files still gated on the blocking lane. They no longer block the gate lane; they run via `bun run test:periodic` (weekly-cron wiring for PTY tests is tracked in TODOS). A new free invariant test makes the declared-vs-actual tier drift impossible to reintroduce silently. + +### What this means for you + +The plan → review → ship loop loses its most pointless click. Draft a plan, say "/plan-eng-review", and the review starts against your plan immediately — interruptible, announced, and reversible by just naming a different target. Run /gstack-upgrade to get it. + +### Itemized changes + +### Added +- **Plan-mode auto-select in the scope gate** (`plan-eng-review`, `plan-design-review`): in plan mode the review targets the active plan automatically, with a one-line announcement; explicitly named targets win in any mode; a fresh plan-mode session with nothing drafted still asks. The mode signal is host-anchored — pasted or fetched content claiming plan mode does not arm the bypass. +- **Render-shape PTY detectors** for the scope gate question and the auto-select announcement (`test/helpers/claude-pty-runner.ts`), with narration-negative and verbatim-quote fixtures so paid smokes can assert gate behavior across a whole run instead of a lossy 2KB tail; observation runs can also track arbitrary consumption tokens (`trackTokens`). +- **Tier-alignment invariant test** (`test/e2e-tier-alignment.test.ts`): every self-gated paid test file named in a touchfiles dep list must match its declared tier; unmapped, mixed-tier, and undeclared-key files are reported instead of silently skipped. +- **Exceptions drift-guard**: the two hand-duplicated gate templates must stay identical modulo their two variant slots, and must carry the exact announcement and question strings the PTY detectors pin. + +### Changed +- `/autoplan`'s section skip list now includes the scope gate — loaded review skills no longer surface a hard-stop question that autoplan's auto-decide contract would immediately answer. +- The plan-mode preamble wording no longer implies a skill's first action must be a question ("any AskUserQuestion the skill fires is the workflow operating within plan mode" — a skill may legitimately resolve a question itself). +- The finding-floor harness no longer counts a scope-gate render toward its question floor (positional anchoring, judge-fallback exclusion) — the floor now genuinely measures finding-driven questions. + +### Fixed +- Four stochastic plan-mode/finding-floor smokes declared `periodic` were still self-gating on the blocking `gate` tier — they no longer run in (or block) the gate lane, and the invariant test above prevents declared-vs-actual tier drift from recurring. Weekly-cron wiring for PTY-driven periodic tests is tracked in TODOS. +- CI eval containers now register `plan-eng-review` and `plan-design-review` as discoverable skills (registration loops, dangling-target checks, and frontmatter verification all extended) — previously only two skills were registered. +- The no-op regression suite covers all three plan-review skills outside plan mode, asserts the gate question actually rendered (unconditionally), and proves a pasted named target is consumed via cumulative-buffer token tracking. +- `/ship`'s credential pre-push guard now installs correctly from git worktrees after consent — the custom-hooks-path detection compared against the worktree's own git dir instead of the shared common dir, so every Conductor worktree read as "custom hooks path" and skipped the install. + +### For contributors +- Skeleton/ratio ceilings ratcheted with attribution comments (plan-eng 68k/1.10, plan-design 89k, investigate 1.10) for the exceptions block + shared preamble reword. +- `PlanSkillObservation.outcome` now includes `wrote_findings_before_asking` (was returned at runtime but missing from the union); high-water flags are built once and spread at every return path. +- TODOS.md: filed the `{{SCOPE_GATE}}` shared-resolver extraction as the follow-up to the drift-guarded duplication. + +## [1.61.0.0] - 2026-07-09 + +## **Nine guard bugs fixed in one wave.** +## **Every fix ships with a tripwire that proves the guard actually guards.** + +This release closes out the silent-failure class across gstack: guards and tools that reported success while doing nothing. Question cards render again on current Claude Code builds. /careful catches chained, substituted, and capital-flag deletes it used to wave through. The design CLI fails loudly on bad flags instead of billing you for a guess. Shared team brains (thin clients) get brain-aware planning instead of silent suppression. Four of the fixes came from community PRs, absorbed with authorship intact and hardened on top. + +### The six numbers that matter + +Source: this branch's diff against v1.58.5.0. Every new test was first run against the unfixed code and confirmed failing, then confirmed passing after the fix. + +| What | Before | After | +|------|--------|-------| +| AskUserQuestion on Claude Code 2.1.89+ | "Tool result missing due to internal error" | card renders | +| `rm -R /`, `rm -rf $(cmd)/node_modules` via /careful | silent allow | ask | +| `design variants --count abc` | 0 variants, exit 0 | exit 1 with usage hint | +| Thin-client team brains | broken-config, brain blocks suppressed | usable, sync stages skip with reason | +| /office-hours SESSION_COUNT | ~2x inflated | exact | +| New tripwire test cases | n/a | 72 | + +The first row is the one to feel. The question-card primitive every interactive skill depends on was orphaned on current Claude Code builds: the preference hook emitted `permissionDecision:'defer'`, whose semantics became "pause for external resumption" in CC v2.1.89. The fix is a two-branch pass-through (exact-empty stdout, or additionalContext-only output for plan-tune memory nuggets), plus a corrected protocol reference doc so the mistake cannot be re-learned from our own docs. + +### What this means for you + +Interactive skills ask you questions again on current Claude Code. Safety guards fail closed: chained deletes, command substitution, capital `-R`, and destructive credential phrasings ("reset my secrets") all reach a human now. If your team runs a shared remote brain, `/sync-gbrain` and brain-aware planning work on thin clients out of the box. Run `/gstack-upgrade` to get all of it. The hook fix arrives with the file update, no settings change needed. + +### Itemized changes + +#### Fixed + +- **AskUserQuestion orphaned on Claude Code 2.1.89+ (#2035, #2006).** `question-preference-hook` pass-through is now exit 0 with exactly empty stdout (or additionalContext-only output for plan-tune memory nuggets), never `permissionDecision:'defer'`. `defer()` renamed `passThrough()`; the protocol contract in `docs/spikes/claude-code-hook-mutation.md` corrected in the same commit; 13 assertions rewritten across 3 test files; the tripwire asserts exact-empty stdout so a garbage write cannot slip past an optional-chained parse. Existing installs pick the fix up via `/gstack-upgrade` (the registered hook shim execs the TypeScript live). +- **/careful chained-rm bypass (#2039).** Contributed by @jbetala7 (PR #2040): the safe-exception shortcut no longer judges a chained command by its last (safe) target. Hardened on top of the anchored full-command whitelist: the flag cluster accepts capital `-R` (the BSD/macOS recursive flag — `rm -R /` warned nowhere before; `rm -Rf node_modules` alone still allows) and safe-target tokens exclude `(` and backtick, so command substitution ending in a whitelisted suffix (`rm -rf $(./wipe-all)/node_modules`) cannot ride the whitelist. +- **/context-restore loading a sibling worktree's checkpoint (#2052).** Contributed by @jbetala7: restore prefers the current branch's own checkpoint over newer sibling-worktree saves (scans 200 newest, partitions by branch frontmatter), and keeps the Conductor handoff fallback when the branch has no checkpoint. +- **/sync-gbrain drift re-register on gbrain 0.42+ (#1985).** Contributed by @jbetala7: the drift remove passes `--confirm-destructive`. Hardened on top: the remove routes through the #1734 data-loss guards (refuses loudly while an autopilot runs), propagates `--keep-storage`, realpath-normalizes drift detection (a symlink alias of the same directory is a match, not drift, the probable cause of the reporter's unmoved-repo drift), and logs old vs new path whenever drift fires. +- **Developer-profile double counting (#2067).** Contributed by @mvann: `mode:"resources"` bookkeeping rows no longer inflate SESSION_COUNT, TIER, or the builder-to-founder nudge; 8 regression tests pin the tier boundaries from both sides. +- **One-way-door credential net: plurals + runtime wiring (#2024).** The credential nouns now match plurals ("reset my secrets" / "rotate the credentials" classify one-way), and the keyword net is wired into the runtime for the first time: `gstack-question-preference --check --summary-stdin` pipes the question text (stdin, never argv, so quotes and newlines survive), and the enforcement hook falls back to the classifier for unregistered ids, so an ad-hoc destructive question with a stored never-ask preference can no longer auto-decide. +- **design CLI silent NaN flags (#2032).** `--count`, `--retry`, and `--timeout` share one loud contract via `design/src/flag-utils.ts`: non-integer input errors with exit 1 ("3.7" is rejected, not truncated), above-max clamps with a stderr warning, and the variants ceiling derives from the style list instead of a magic 7. Previously `--retry abc` made generate a silent no-op and `--timeout abc` killed the serve board at boot. +- **Thin-client brains misclassified as broken (#2051).** New `thin-client` engine state, read from gbrain's own `remote_mcp` config marker before any probe. Usable at every suppression gate (`--is-ok`, gen-skill-docs detection, `gstack-config gbrain-refresh`) while the local sync stages skip with an accurate reason (code indexing runs on the brain server; memory syncs via the remote brain's artifacts pull). The detect JSON reports `gbrain_thin_client: {probed: false}`: config verified, reachability checked at use time where gbrain calls degrade gracefully. detectMcpMode also recognizes gbrain servers registered under variant names or matched by the config's `mcp_url`. + +#### Closed as already fixed, with receipts + +- #1965 (GBRAIN_PREPARE pooler breakage): `lib/gbrain-exec.ts:86` never sets it; pinned by `test/build-gbrain-env.test.ts:121-142`. +- #1950 (Windows git-bash learnings silently dropped): `bin/gstack-learnings-log:10-15` cygpath fix + stderr surfacing; pinned by `test/bin-windows-bun-import-paths.test.ts`. +- #1964 (slow engines misclassified): `probeTimeoutMs()` honors `GSTACK_GBRAIN_PROBE_TIMEOUT_MS`; timeout classifies usable; pinned by `test/gbrain-local-status.test.ts`. + +#### For contributors + +- 11 bisect commits; 4 community PRs absorbed with authorship preserved. Contributed by @jbetala7 (#2040, #2054, #2031) and @mvann (#1991). Thank you both. +- 72 new test cases across 9 files, each verified failing against the unfixed code before the fix landed. +- Three follow-ups filed in TODOS.md: wire `design/test/` into CI (all 8 existing files are invisible to every runner today, plus a documented pre-existing timing flake), /context-save worktree-identity hardening (the #2052 residual), and conditional gbrain reindex-in-place gated on the new drift log. + +## [1.60.2.0] - 2026-08-07 + +## **Three free-suite tests fail-proofed against machine drift.** +## **Plus a filed P1: the suite's exit code can lie, and now we know why.** + +A full-suite health check turned up three tests that failed on dev machines while CI stayed green, all test-side drift rather than product bugs. The eval:list CLI test now spawns from a neutral directory, so slug detection cannot route reads away from the fixture store it seeds (the old cwd made it fail on any machine with the dev symlink). The benchmark CLI's remediation-hint check is case-insensitive, matching the reworded Gemini guidance ("Export GEMINI_API_KEY..."). The session-runner observability floor now expects the 5 wrapped I/O sites that actually exist since the shell-free spawn removed the prompt-file unlink. + +### The numbers that matter + +Source: this branch's investigation logs (~/.gstack-dev/logs/free-suite-*.log) and per-file reruns. + +| Check | Before | After | +|-------|--------|-------| +| eval-list-cli on dev machines | 1 fail (reads empty project dir) | 2/2 pass, deterministic everywhere | +| benchmark-cli remediation hint | 1 fail (case-brittle regex) | 15/15 pass | +| observability check 11 floor | expects >= 6 markers, counts 5 | floor matches the 5 real sites | + +One deeper finding got filed instead of rushed: at least five browse test files force-exit the shared bun process with `setTimeout(() => process.exit(0), 500)`, which can exit 0 before the summary prints and mask real failures. That is now a P1 in TODOS.md with receipts, because removing the exits without fixing the handle leaks they paper over would trade silent failure for hangs. + +### What this means for you + +`bun test` gives the same verdict on your laptop as in CI for these three tests, and the exit-code trust problem is documented with a concrete fix path instead of lurking. + +### Itemized changes + +#### Fixed + +- `test/eval-list-cli.test.ts`: spawn from neutral cwd + absolute script path so `getProjectEvalDir()` slug probes fail deterministically and the seeded legacy store is read. +- `test/benchmark-cli.test.ts`: remediation-hint pattern made case-insensitive for the updated Gemini NOT-READY message. +- `test/helpers/observability.test.ts`: check 11 floor 6 → 5 with the surviving wrapped-I/O sites named. + +#### For contributors + +- TODOS.md: new P1 (free-suite exit code masked by in-process force-exits, with repro + receipts) filed under Test infrastructure. + ## [1.60.1.0] - 2026-07-09 ## **The /autoplan dual-voice eval is back on the board, catching real regressions.** diff --git a/CLAUDE.md b/CLAUDE.md index 9848449020..2339e15739 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,6 +9,8 @@ bun run test:evals # run paid evals: LLM judge + E2E (diff-based, ~$4/run max) bun run test:evals:all # run ALL paid evals regardless of diff bun run test:gate # run gate-tier tests only (CI default, blocks merge) bun run test:periodic # run periodic-tier tests only (weekly cron / manual) +bun run test:gate:sharded # gate tier via the sharded paid runner (one Bun process per test file) +bun run test:periodic:sharded # periodic tier via the sharded paid runner (implies EVALS_ALL=1) bun run test:e2e # run E2E tests only (diff-based, ~$3.85/run max) bun run test:e2e:all # run ALL E2E tests regardless of diff bun run eval:select # show which tests would run based on current diff @@ -48,13 +50,21 @@ MCP servers / skills), a temp `GSTACK_HOME`, and `--strict-mcp-config`. Local eval signal matches CI. Debug against real operator state with `EVALS_HERMETIC=0` (restores the legacy env AND drops the strict-MCP flag). Per-test `env:` overrides merge last, so deliberate contamination -(`CONDUCTOR_WORKSPACE_PATH`, per-test `GSTACK_HOME`) keeps working. Wiring -is pinned by `test/hermetic-wiring.test.ts` (static tripwire) and two -gate-tier canaries in `test/skill-e2e-hermetic-canary.test.ts`. +(`CONDUCTOR_WORKSPACE_PATH`, per-test `GSTACK_HOME`) keeps working. The +hermetic config dir seeds NO skills by default; a PTY test that types a +`/skill` slash command must pass `seedSkills: true` to the PTY runner, which +points the child's `CLAUDE_CONFIG_DIR` at `hermeticSkillsConfigDir()` — a +seeded registry that symlinks the LIVE working tree's SKILL.md files (by +design: the skills ARE the subject under test; a snapshot would measure stale +copies). Wiring is pinned by `test/hermetic-wiring.test.ts` (static tripwire), +two gate-tier canaries in `test/skill-e2e-hermetic-canary.test.ts`, and the +seeding tripwires in `test/hermetic-skills-seeding.test.ts` / +`test/pty-skill-seeding-wiring.test.ts`. E2E tests stream progress in real-time (tool-by-tool via `--output-format stream-json --verbose`). Results are persisted to `~/.gstack-dev/evals/` with auto-comparison -against the previous run. +against the previous finalized run (in-flight `_partial` files are never used as +a baseline, so a run can't compare against itself). **Diff-based test selection:** `test:evals` and `test:e2e` auto-select tests based on `git diff` against the base branch. Each test declares its file dependencies in @@ -70,6 +80,12 @@ periodic tests run weekly via cron or manually. Use `EVALS_TIER=gate` or 2. Quality benchmark, Opus model test, or non-deterministic? -> `periodic` 3. Requires external service (Codex, Gemini)? -> `periodic` +Tier declarations are enforced by `test/e2e-tier-alignment.test.ts` (free, runs +in `bun test`): a `skill-e2e-*` file named in a touchfiles dep list whose +`EVALS_TIER` self-gate disagrees with its declared tier in `E2E_TIERS` fails the +suite. Files not named in any dep list are reported, not enforced — keep both +in sync. + ## Testing ```bash @@ -101,9 +117,9 @@ gstack/ │ ├── gen-skill-docs.ts # Template → SKILL.md generator (config-driven) │ ├── host-config.ts # HostConfig interface + validator │ ├── host-config-export.ts # Shell bridge for setup script -│ ├── host-adapters/ # Host-specific adapters (OpenClaw tool mapping) │ ├── resolvers/ # Template resolver modules (preamble, design, review, gbrain, etc.) │ ├── skill-check.ts # Health dashboard +│ ├── test-paid-shards.ts # Sharded paid-tier runner (one Bun process per shard) │ └── dev-skill.ts # Watch mode ├── test/ # Skill validation + eval tests │ ├── helpers/ # skill-parser.ts, session-runner.ts, llm-judge.ts, eval-store.ts @@ -119,6 +135,8 @@ gstack/ ├── review/ # PR review skill ├── plan-ceo-review/ # /plan-ceo-review skill ├── plan-eng-review/ # /plan-eng-review skill +├── plan-deliverables/ # /plan-deliverables skill +├── autobuilder-loop/ # /autobuilder-loop skill ├── autoplan/ # /autoplan skill (auto-review pipeline: CEO → design → eng) ├── benchmark/ # /benchmark skill (performance regression detection) ├── canary/ # /canary skill (post-deploy monitoring loop) @@ -141,7 +159,7 @@ gstack/ │ ├── test/ # Integration tests │ └── dist/ # Compiled binary ├── extension/ # Chrome extension (side panel + activity feed + CSS inspector) -├── lib/ # Shared libraries (worktree.ts) +├── lib/ # Shared libraries (worktree.ts, egress-receipt.ts, context-bill.ts, redact-engine.ts) ├── docs/designs/ # Design documents ├── setup-deploy/ # /setup-deploy skill (one-time deploy config) ├── .github/ # CI workflows + Docker image @@ -178,6 +196,16 @@ behavior). If you blow past 40K, the right fix is usually: (1) look at WHAT grew or as a reference doc, (3) only compress carefully-tuned prose as a last resort — cuts to the coverage audit, review army, or voice directive have real quality cost. +A second, harder ceiling guards the DISCOVERY surface: `test/catalog-budget.test.ts` +caps the aggregate frontmatter `name` + `description` across all skills at 1,150 +token-equivalents (260-byte per-skill sub-cap), counted through the shared census +in `test/helpers/skill-census.ts`. This one is enforced, not a warning — every +host loads the full catalog every session, so growth here taxes every +conversation. The failure message carries the re-measure + ratchet protocol. +`bin/gstack-context-bill` shows the full token bill-of-materials for a skills +tree (always-on vs per-invocation, `--diff`, `--budget`; `--exact` opts into the +real tokenizer and POSTs file text to api.anthropic.com with an egress receipt). + **Merge conflicts on SKILL.md files:** NEVER resolve conflicts on generated SKILL.md files by accepting either side. Instead: (1) resolve conflicts on the `.tmpl` templates and `scripts/gen-skill-docs.ts` (the sources of truth), (2) run `bun run gen:skill-docs` @@ -221,7 +249,11 @@ Default output from every tier-≥2 skill follows the Writing Style section in outcome terms ("what breaks for your users if...") not implementation terms, short sentences, decisions close with user impact. Power users who want the tighter V0 prose set `gstack-config set explain_level terse` (binary switch, -no middle mode). See `docs/designs/PLAN_TUNING_V1.md` for the full design +no middle mode). The config key is a RUNTIME behavior switch — the preamble +echoes `EXPLAIN_LEVEL` and the model skips terse-gated sections; the generated +SKILL.md bytes (and their token cost) are unchanged until you also rebuild with +`bun run gen:skill-docs --explain-level=terse`. The `set` command now prints +exactly this. See `docs/designs/PLAN_TUNING_V1.md` for the full design rationale. The review pacing overhaul that originally tried to ride alongside writing-style was extracted to V1.1 — see `docs/designs/PACING_UPDATES_V0.md`. @@ -276,10 +308,14 @@ PTY via `window.gstackInjectToTerminal(text)`, exposed by `sidepanel-terminal.js`. No `/sidebar-command` POST — the live REPL is the only execution surface in the sidebar now. -**`/health` MUST NOT surface any shell-grant token.** It already leaks -`AUTH_TOKEN` to localhost callers in headed mode (a v1.1+ TODO). Don't -make that worse by adding the PTY session token there. PTY auth flows -through `POST /pty-session` only. +**`/health` MUST NOT surface any token — and it no longer does** (v1.63+). +The historical headed-mode leak of `AUTH_TOKEN` is fixed: `GET /health` is +liveness/status only in every mode. Token bootstrap is `POST /extension-token`, +which validates the caller's Origin against the pinned extension identity +(the `key` field in `extension/manifest.json` pins the extension ID — +`GSTACK_EXTENSION_ID` in `browse/src/server.ts`, derivation reproducible via +`bun browse/scripts/extension-id.ts`) plus a loopback Host. PTY auth still +flows through `POST /pty-session` only. Don't add any token to `/health`. **Transport-layer security** (v1.6.0.0+). When `pair-agent` starts an ngrok tunnel, the daemon binds two HTTP listeners: a local listener (127.0.0.1, full command @@ -309,6 +345,23 @@ response in `server.ts`, read `browse/test/server-sanitize-surrogates.test.ts` pins the wiring with invariant tests, so bypasses fail CI. +**Egress receipts at every off-machine sink** (v1.63.0.0+). Every gstack-initiated +send off the machine MUST write a hash-chained receipt to +`~/.gstack/security/egress.jsonl` BEFORE the send: TypeScript callers use +`writeReceipt` from `lib/egress-receipt.ts`; shell scripts source +`bin/gstack-egress-lib.sh` and use `_receipted_curl` / `_receipted_git`. Failure +polarity is per-class: fail-closed for sensitive sinks (brain-sync, memory-ingest, +gbrain-sync, telemetry, ngrok tunnels, mcp-verify, supabase-provision), fail-open ++ stderr warning for user-facing ones (design OpenAI calls, update-check, +dashboards, git-class ops). The new-sink scanner in +`test/egress-receipt-wiring.test.ts` fails CI on an unreceipted `curl` / +`git push` / `fetch` to a non-loopback host unless the file carries a reasoned +entry in its `SCANNER_EXEMPT` list (user-directed page fetches, reachability +probes, instruction strings, skill prose) — if you add a new off-machine sink, +wire it through the helpers and add it to the enumerated sink list. Inspect with +`bin/gstack-egress` (`list` | `verify`, exit 3 on tamper | `grants`). Threat +model: forensic observability of ATTEMPTED egress, not an exfiltration control. + **SSE endpoint helper** (v1.51.0.0+). New SSE endpoints in `server.ts` MUST route through `createSseEndpoint(req, config)` from `browse/src/sse-helpers.ts`. The helper owns the cleanup contract (abort + enqueue-throw + heartbeat-throw, all @@ -343,47 +396,39 @@ every `git pull`. | Layer | Module | Lives in | |-------|--------|----------| -| L1-L3 | `content-security.ts` | both server and agent — datamarking, hidden element strip, ARIA regex, URL blocklist, envelope wrapping | -| L4 | `security-classifier.ts` (TestSavantAI ONNX) | **sidebar-agent only** | -| L4b | `security-classifier.ts` (Claude Haiku transcript) | **sidebar-agent only** | -| L5 | `security.ts` (canary) | both — inject in compiled, check in agent | -| L6 | `security.ts` (combineVerdict ensemble) | both | +| L1-L3 | `content-security.ts` | server + read path — datamarking, hidden element strip, ARIA regex, URL blocklist, envelope wrapping | +| L4 | `security-classifier.ts` (TestSavantAI ONNX) | **security sidecar subprocess only** (`security-sidecar-entry.ts`, driven by `security-sidecar-client.ts` from server.ts) | +| Canary | `security.ts` (generate/inject/detect) | pure utilities — no production injector today (the chat prompt-builder that injected them was ripped) | +| Combiner | `security.ts` (combineVerdict + THRESHOLDS) | pure, tested; retains transcript/deberta vote handling for LayerSignal inputs no live layer produces anymore | + +History note: an L4b Haiku transcript classifier and an opt-in DeBERTa ensemble +(`GSTACK_SECURITY_ENSEMBLE=deberta`) existed until the chat-path agent that +invoked them was ripped; both were deleted as dead code (zero production +callers). Do not re-document them as live. **Critical constraint:** `security-classifier.ts` CANNOT be imported from the compiled browse binary. `@huggingface/transformers` v4 requires `onnxruntime-node` -which fails to `dlopen` from Bun compile's temp extract dir. Only `security.ts` -(pure-string operations — canary, verdict combiner, attack log, status) is safe -for `server.ts`. See `~/.gstack/projects/garrytan-gstack/ceo-plans/2026-04-19-prompt-injection-guard.md` -§"Pre-Impl Gate 1 Outcome" for full architectural decision. - -**Thresholds** (in `security.ts`): -- `BLOCK: 0.85` — single-layer score that would cause BLOCK if cross-confirmed -- `WARN: 0.75` — cross-confirm threshold. When L4 AND L4b both >= 0.75 → BLOCK -- `LOG_ONLY: 0.40` — gates transcript classifier (skip Haiku when all layers < 0.40) -- `SOLO_CONTENT_BLOCK: 0.92` — single-layer threshold for label-less content classifiers - (testsavant, deberta). Intentionally higher than `BLOCK` because these layers can't - distinguish "this is an injection" from "this looks like phishing aimed at the user." - The transcript classifier keeps a separate, label-gated solo path at `BLOCK` (0.85). - -**Ensemble rule:** BLOCK only when the ML content classifier AND the transcript -classifier both report >= WARN. Single-layer high confidence degrades to WARN — -this is the Stack Overflow instruction-writing FP mitigation. Canary leak -always BLOCKs (deterministic). +which fails to `dlopen` from Bun compile's temp extract dir — hence the sidecar +subprocess. Only `security.ts` (pure-string operations — canary utilities, +verdict combiner, status) is safe for `server.ts`. See +`~/.gstack/projects/garrytan-gstack/ceo-plans/2026-04-19-prompt-injection-guard.md` +§"Pre-Impl Gate 1 Outcome" for the original architectural decision. + +**Thresholds** (in `security.ts`): `BLOCK: 0.85`, `WARN: 0.75`, `LOG_ONLY: 0.40`, +`SOLO_CONTENT_BLOCK: 0.92` (label-less content classifiers can't distinguish +"injection" from "phishing aimed at the user", so their solo bar is higher). +The live L4 path applies these in server.ts's sidecar-scan handling; canary +leak always BLOCKs (deterministic). **Env knobs:** - `GSTACK_SECURITY_OFF=1` — emergency kill switch. Classifier stays off even if - warmed. Canary is still injected; just the ML scan is skipped. -- `GSTACK_SECURITY_ENSEMBLE=deberta` — opt-in DeBERTa-v3 ensemble. Adds - ProtectAI DeBERTa-v3-base-injection-onnx as L4c classifier for cross-model - agreement. 721MB first-run download. With ensemble enabled, BLOCK requires - 2-of-3 ML classifiers agreeing at >= WARN (testsavant, deberta, transcript). - Without ensemble (default), BLOCK requires testsavant + transcript at >= WARN. + warmed; the L1-L3 filters keep running. - Classifier model cache: `~/.gstack/models/testsavant-small/` (112MB, first run only) - plus `~/.gstack/models/deberta-v3-injection/` (721MB, only when ensemble enabled) -- Attack log: `~/.gstack/security/attempts.jsonl` (salted sha256 + domain only, - rotates at 10MB, 5 generations) -- Per-device salt: `~/.gstack/security/device-salt` (0600) -- Session state: `~/.gstack/security/session-state.json` (cross-process, atomic) +- Attack log: `~/.gstack/security/attempts.jsonl` — written by + `tunnel-denial-log.ts` (tunnel-surface rejections; rotates at 10MB, 5 generations) +- Session state: `~/.gstack/security/session-state.json` (cross-process, atomic; + NOTE: classifierStatus currently has no live writer — shield status derives + from what's on disk) ## Dev symlink awareness @@ -419,19 +464,21 @@ migration script to `gstack-upgrade/migrations/`. Read CONTRIBUTING.md's "Upgrad migrations" section for the format and testing requirements. The upgrade skill runs these automatically after `./setup` during `/gstack-upgrade`. -## Compiled binaries — NEVER commit browse/dist/ or design/dist/ +## Compiled binaries — never commit browse/dist/, design/dist/, or make-pdf/dist/ + +The `browse/dist/`, `design/dist/`, and `make-pdf/dist/` directories contain +compiled Bun binaries (`browse`, `find-browse`, `design`, ~62MB each). These are +Mach-O arm64 only — they do NOT work on Linux, Windows, or Intel Macs. The +`./setup` script builds from source for every platform. -The `browse/dist/` and `design/dist/` directories contain compiled Bun binaries -(`browse`, `find-browse`, `design`, ~58MB each). These are Mach-O arm64 only — they -do NOT work on Linux, Windows, or Intel Macs. The `./setup` script already builds -from source for every platform, so the checked-in binaries are redundant. They are -tracked by git due to a historical mistake and should eventually be removed with -`git rm --cached`. +These directories are **untracked and gitignored** (`.gitignore:3-6`; the +`browse/dist/` binaries were untracked in `64d5a3e4`, v0.11.16.0; the others were +never tracked). They will NOT appear in `git status`. If a dist binary ever does +show up in `git status`, something force-added it (`git add -f`) — do not commit +it; unstage it and find out how it got there. -**NEVER stage or commit these files.** They show up as modified in `git status` -because they're tracked despite `.gitignore` — ignore them. When staging files, -always use specific filenames (`git add file1 file2`) — never `git add .` or -`git add -A`, which will accidentally include the binaries. +When staging files, always use specific filenames (`git add file1 file2`) — never +`git add .` or `git add -A`, which can sweep in build outputs and junk. ## Redaction guard (PII / secrets / legal content) @@ -452,7 +499,7 @@ determined leaker (a CHANGELOG line that does would fail a hostile screenshotter `--auto-redact`, `--repo-visibility`, `--from-file`). `bin/gstack-redact-prepush` is the opt-in git hook. - **Skill docs are generated** from `scripts/resolvers/redact-doc.ts` - (`{{REDACT_TAXONOMY_TABLE}}`, `{{REDACT_INVOCATION_BLOCK:}}`) so /spec, + (`{{REDACT_INVOCATION_BLOCK:}}`) so /spec, /cso, /ship, /document-release, /document-generate never drift from the engine. - **Scan-at-sink:** always scan the EXACT bytes that will be sent — write to a temp file, scan that file, pass the SAME file to `gh`/`git`. Never scan a string @@ -858,7 +905,17 @@ the run can also die to idle-sleep. `gstack-detach` fixes both: a fresh session machine-wide `gstack-evals` lock (concurrent worktrees serialize instead of saturating the shared model API), a per-tier watchdog, and a **run-scoped** log under `~/.gstack-dev/eval-runs/` (no shared-`/tmp` collision). Each prints its - log path. Or call `gstack-detach [--lock NAME] [--timeout SECS] [--label LBL] -- + log path. `eval:bg:gate` / `eval:bg:periodic` run their tier through the + sharded paid runner (`scripts/test-paid-shards.ts`, also exposed as + `test:gate:sharded` / `test:periodic:sharded`): one Bun process per test + file, an external wall-clock timeout that kills the shard's process GROUP + (stray `claude`/`codex` grandchildren included), a per-shard + `GSTACK_EVAL_DIR=/shards//` honored by the `EvalCollector` + constructor, and an aggregate that separates failed vs timed-out vs + never-started shards — the detach timeouts (25200s gate / 28800s periodic) + are sized against worst-case shard wall clock. `eval:list` / `eval:compare` / + `eval:summary` read the shard dirs too. Or call + `gstack-detach [--lock NAME] [--timeout SECS] [--label LBL] -- ` directly for any long agent job. Export `ANTHROPIC_API_KEY` first (never pass keys in argv). - Then **poll the printed logfile** with a death-aware watcher: break on the @@ -942,6 +999,8 @@ When the user's request matches an available skill, invoke it via the Skill tool Key routing rules: - Product ideas/brainstorming → invoke /office-hours +- Acceptance criteria / deliverables / definition of done for a plan → invoke /plan-deliverables +- Drive an approved plan/spec/backlog to completion autonomously ("autobuild it", "run the build loop") → invoke /autobuilder-loop - Strategy/scope → invoke /plan-ceo-review - Architecture → invoke /plan-eng-review - Design system/plan review → invoke /design-consultation or /plan-design-review diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b75d4a898f..99aeb8673f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -159,6 +159,8 @@ Runs automatically with `bun test`. 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. - **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 ` not just `-d`), enriched descriptions for key commands (e.g. `is` lists valid states, `press` lists key examples). +- **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,150 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. ### Tier 2: E2E via `claude -p` (~$3.85/run) @@ -183,10 +185,16 @@ seeded `CLAUDE_CONFIG_DIR`, a temp `GSTACK_HOME`, and `--strict-mcp-config`. You operator `~/.claude` config, MCP servers (gbrain, Conductor), skills, `~/.gstack` decision logs, and `CONDUCTOR_*` env never leak into the child, so local eval signal matches CI instead of disagreeing for reasons unrelated to the code under -test. Set `EVALS_HERMETIC=0` to debug against your real operator state (this also +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) and two gate-tier isolation canaries in -`test/skill-e2e-hermetic-canary.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 @@ -226,8 +234,16 @@ bun run eval:bg:gate # detached gate-tier suite bun run eval:bg:periodic # detached periodic-tier suite ``` -Each prints its log path. Humans running `bun run test:evals` foreground in their -own terminal don't need this — Ctrl-C is intended there. +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=/shards//`), and an aggregate that +distinguishes failed vs timed-out vs never-started shards. `eval:list`, +`eval:compare`, and `eval:summary` 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`. diff --git a/README.md b/README.md index af534d2c53..6a0e82491e 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ Fork it. Improve it. Make it yours. And if you want to hate on free open source Open Claude Code and paste this. Claude does the rest. -> Install gstack: run **`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /connect-chrome, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /setup-gbrain, /retro, /investigate, /document-release, /document-generate, /codex, /cso, /autoplan, /plan-devex-review, /devex-review, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn. Then ask the user if they also want to add gstack to the current project so teammates get it. +> Install gstack: run **`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-deliverables, /autobuilder-loop, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /connect-chrome, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /setup-gbrain, /retro, /investigate, /document-release, /document-generate, /codex, /cso, /autoplan, /plan-devex-review, /devex-review, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn. Then ask the user if they also want to add gstack to the current project so teammates get it. ### Step 2: Team mode — auto-update for shared repos (recommended) @@ -179,6 +179,8 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan- | Skill | Your specialist | What they do | |-------|----------------|--------------| | `/office-hours` | **YC Office Hours** | Start here. Six forcing questions that reframe your product before you write code. Pushes back on your framing, challenges premises, generates implementation alternatives. Design doc feeds into every downstream skill. | +| `/plan-deliverables` | **Planner** | Author per-milestone acceptance criteria, each paired with a validating test (the deliverable), and bake them into the plan. | +| `/autobuilder-loop` | **Build Loop** | Drive an already-approved plan, spec, or backlog to completion unattended — model-routed subagents per milestone, review gates, Docker verification. | | `/plan-ceo-review` | **CEO / Founder** | Rethink the problem. Find the 10-star product hiding inside the request. Four modes: Expansion, Selective Expansion, Hold Scope, Reduction. | | `/plan-eng-review` | **Eng Manager** | Lock in architecture, data flow, diagrams, edge cases, and tests. Forces hidden assumptions into the open. | | `/plan-design-review` | **Senior Designer** | Rates each design dimension 0-10, explains what a 10 looks like, then edits the plan to get there. AI Slop detection. Interactive — one AskUserQuestion per design choice. | @@ -235,7 +237,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan- | `/ios-qa` | **iOS Live-Device QA (v1.43.0.0+)** — drive a real iPhone over USB CoreDevice via an embedded `StateServer` in the app. Read Swift source, codegen typed `@Observable` accessors, run the agent loop. Optional `--tailnet` flag exposes the device to OpenClaw or any HTTP-capable agent on your Tailscale tailnet so remote agents can run iOS QA without ever touching the hardware. Capability-tier allowlist (observe/interact/mutate/restore), per-device session lock, audit log. | | `/ios-fix`, `/ios-design-review`, `/ios-clean`, `/ios-sync` | iOS bug-fix loop, designer's-eye HIG audit, debug-bridge cleanup, and accessor resync. See `docs/skills.md`. End-to-end walkthrough: [docs/howto-ios-testing-with-gstack.md](docs/howto-ios-testing-with-gstack.md). | -### New binaries (v0.19) +### Standalone binaries Beyond the slash-command skills, gstack ships standalone CLIs for workflows that don't belong inside a session: @@ -243,6 +245,8 @@ Beyond the slash-command skills, gstack ships standalone CLIs for workflows that |---------|-------------| | `gstack-model-benchmark` | **Cross-model benchmark** — run the same prompt through Claude, GPT (via Codex CLI), and Gemini; compare latency, tokens, cost, and (optionally) LLM-judge quality score. Auth detected per provider, unavailable providers skip cleanly. Output as table, JSON, or markdown. `--dry-run` validates flags + auth without spending API calls. | | `gstack-taste-update` | **Design taste learning** — writes approvals and rejections from `/design-shotgun` into a persistent per-project taste profile. Decays 5%/week. Feeds back into future variant generation so the system learns what you actually pick. | +| `gstack-egress` | **Egress receipt auditor** — every gstack-initiated off-machine send writes a tamper-evident, hash-chained receipt to `~/.gstack/security/egress.jsonl` before the send. `list` shows what gstack attempted to send and to which host, `grants` shows the standing consent settings plus the exact command that revokes each, `verify` recomputes the hash chain and exits 3 on tamper. | +| `gstack-context-bill` | **Token bill-of-materials** — read-only, offline audit of what an installed skills tree costs in tokens: always-on frontmatter every session pays vs per-invocation SKILL.md + forced references. `--diff` compares two trees, `--budget` enforces a ceiling, `--exact` opts into Anthropic `count_tokens` (sends file text off-machine; writes an egress receipt first, degrades to the offline estimate if the receipt can't be written). | | `gstack-ios-qa-daemon` | **iOS QA daemon** — Mac-side broker between an agent and a connected iPhone over USB CoreDevice. Loopback by default; `--tailnet` opens a Tailscale-facing listener with identity-gated capability tiers. Single-instance via flock on `~/.gstack/ios-qa-daemon.pid`. See [docs/howto-ios-testing-with-gstack.md](docs/howto-ios-testing-with-gstack.md). | | `gstack-ios-qa-mint` | **iOS allowlist manager** — owner-grant CLI for the tailnet allowlist. `grant`/`revoke`/`list` against `~/.gstack/ios-qa-allowlist.json` (mode 0600). Remote agents never auto-allowlist; this is the explicit-intent path. | | `gstack-ios-qa-regen` | **iOS bridge regenerator** — deterministically installs the canonical DebugBridge package, generates typed state accessors, and records the installed gstack version. Safe to rerun after source changes or upgrades. | @@ -418,7 +422,7 @@ The skill asks once per repo. The decision is sticky across worktrees and branch **GStack memory sync (different feature, same private-repo infra).** Optionally pushes your gstack state (learnings, CEO plans, design docs, retros, developer profile) to a private git repo so your memory follows you across machines, with a one-time privacy prompt (everything allowlisted / artifacts only / off) and a defense-in-depth secret scanner that blocks AWS keys, tokens, PEM blocks, and JWTs before they leave your machine. ```bash -gstack-brain-init +gstack-artifacts-init ``` **Running gstack in Conductor?** Conductor explicitly strips `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` from every workspace's process env, so paid evals and gbrain embeddings won't work out of the box. Set `GSTACK_ANTHROPIC_API_KEY` and `GSTACK_OPENAI_API_KEY` in Conductor's workspace env config instead — gstack's TS entry points promote them to canonical names at runtime. Full details and the contributor checklist for adding the import to new entry points: [Conductor + GSTACK_* env vars](USING_GBRAIN_WITH_GSTACK.md#conductor--gstack_-env-vars). @@ -441,6 +445,25 @@ Other references: [docs/gbrain-sync.md](docs/gbrain-sync.md) (sync-specific guid | [Contributing](CONTRIBUTING.md) | Dev setup, testing, contributor mode, and dev mode | | [Changelog](CHANGELOG.md) | What's new in every version | +## Token cost & small repos + +Every skill invocation loads its `SKILL.md` plus a shared preamble. Since the +v1.60 carve, the always-loaded part averages roughly 25-45 KB per skill (~6-11k +tokens); onboarding prompts, the full AskUserQuestion spec, and other +conditional guidance live in shared `preamble/sections/` files that load only +when actually needed. `/autoplan` loads each review skill at the start of its +own phase, so skipped phases cost nothing. + +This overhead is **fixed per invocation** — it does not scale down with your +codebase. On a large project it amortizes to noise; on a very small repo (a few +hundred lines) a heavy skill like `/review` can still read more instruction +text than source code. For small or throwaway projects, prefer the lighter +skills (`/investigate`, `/qa-only`, `/context-save`) over the full pipelines +(`/autoplan`, `/ship`), or just use your agent directly and reach for gstack +when the loop — plan, review, ship — is worth the structure. Power users can +additionally rebuild with `bun run gen:skill-docs --explain-level=terse` to +strip the style-guidance sections from the generated files. + ## Privacy & Telemetry gstack includes **opt-in** usage telemetry to help improve the project. Here's exactly what happens: @@ -450,6 +473,7 @@ gstack includes **opt-in** usage telemetry to help improve the project. Here's e - **What's sent (if you opt in):** skill name, duration, success/fail, gstack version, OS. That's it. - **What's never sent:** code, file paths, repo names, branch names, prompts, or any user-generated content. - **Change anytime:** `gstack-config set telemetry off` disables everything instantly. +- **Every off-machine send is receipted.** Any gstack-initiated network send — telemetry included — writes a hash-chained, tamper-evident receipt to `~/.gstack/security/egress.jsonl` before the send; sensitive sinks refuse to send at all if the receipt can't be written. Audit with `gstack-egress list`, verify the chain with `gstack-egress verify` (exit 3 on tamper), see the standing consent settings with `gstack-egress grants`. The ledger records attempted sends so accidents are auditable — it's an audit trail, not a network firewall. Data is stored in [Supabase](https://supabase.com) (open source Firebase alternative). The schema is in [`supabase/migrations/`](supabase/migrations/) — you can verify exactly what's collected. The Supabase publishable key in the repo is a public key (like a Firebase API key) — row-level security policies deny all direct access. Telemetry flows through validated edge functions that enforce schema checks, event type allowlists, and field length limits. @@ -478,7 +502,7 @@ On Windows without Developer Mode (MSYS2 / Git Bash), `setup` falls back to file ``` ## gstack Use /browse from gstack for all web browsing. Never use mcp__claude-in-chrome__* tools. -Available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, +Available skills: /office-hours, /plan-deliverables, /autobuilder-loop, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /open-gstack-browser, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /setup-gbrain, /sync-gbrain, /retro, /investigate, diff --git a/SKILL.md b/SKILL.md index aaa5612dd4..1d67549cb9 100644 --- a/SKILL.md +++ b/SKILL.md @@ -78,13 +78,15 @@ if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +_UPDATE_CHECK=$(~/.claude/skills/gstack/bin/gstack-config get update_check 2>/dev/null || echo "true") +echo "UPDATE_CHECK: $_UPDATE_CHECK" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"gstack","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(_repo=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null | tr -cd 'a-zA-Z0-9._-'); echo "${_repo:-unknown}")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true fi for _PF in $(find ~/.gstack/analytics -maxdepth 1 -name '.pending-*' 2>/dev/null); do if [ -f "$_PF" ]; then - if [ "$_TEL" != "off" ] && [ -x "~/.claude/skills/gstack/bin/gstack-telemetry-log" ]; then + if [ "$_TEL" != "off" ] && [ -x "$HOME/.claude/skills/gstack/bin/gstack-telemetry-log" ]; then ~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type skill_run --skill _pending_finalize --outcome unknown --session-id "$_SESSION_ID" 2>/dev/null || true fi rm -f "$_PF" 2>/dev/null || true @@ -144,12 +146,28 @@ In plan mode, allowed because they inform the plan: `$B`, `$D`, `codex exec`/`co ## Skill Invocation During Plan Mode -If the user invokes a skill in plan mode, the skill takes precedence over generic plan mode behavior. **Treat the skill file as executable instructions, not reference.** Follow it step by step starting from Step 0; the first AskUserQuestion is the workflow entering plan mode, not a violation of it. AskUserQuestion (any variant — `mcp__*__AskUserQuestion` or native; see "AskUserQuestion Format → Tool resolution") satisfies plan mode's end-of-turn requirement. If AskUserQuestion is unavailable or a call fails, follow the AskUserQuestion Format failure fallback: `headless` → BLOCKED; `interactive` → the prose fallback (also satisfies end-of-turn). At a STOP point, stop immediately. Do not continue the workflow or call ExitPlanMode there. Commands marked "PLAN MODE EXCEPTION — ALWAYS RUN" execute. Call ExitPlanMode only after the skill workflow completes, or if the user tells you to cancel the skill or leave plan mode. +If the user invokes a skill in plan mode, the skill takes precedence over generic plan mode behavior. **Treat the skill file as executable instructions, not reference.** Follow it step by step starting from Step 0; any AskUserQuestion the skill fires is the workflow operating within plan mode, not a violation of it — and a skill whose instructions resolve a question themselves (e.g. a plan-mode auto-select) may legitimately not ask it. AskUserQuestion (any variant — `mcp__*__AskUserQuestion` or native; see "AskUserQuestion Format → Tool resolution") satisfies plan mode's end-of-turn requirement. If AskUserQuestion is unavailable or a call fails, follow the AskUserQuestion Format failure fallback: `headless` → BLOCKED; `interactive` → the prose fallback (also satisfies end-of-turn). At a STOP point, stop immediately. Do not continue the workflow or call ExitPlanMode there. Commands marked "PLAN MODE EXCEPTION — ALWAYS RUN" execute. Call ExitPlanMode only after the skill workflow completes, or if the user tells you to cancel the skill or leave plan mode. + +## Preamble Section Index — shared sections, read on demand + +Heavy preamble guidance is carved into shared files under `~/.claude/skills/gstack/preamble/sections/` (one copy +for the whole skill suite). Read a file IN FULL the moment its trigger applies — +never act on its topic from memory. If that base doesn't exist on this machine +(vendored or non-standard install), resolve the same filename relative to this +skill file's own installed location instead — `../../preamble/sections/` from +a skill dir, or the gstack repo root's `preamble/sections/`. + +| When | Read | +|------|------| +| the preamble echo shows a pending onboarding flag — `LAKE_INTRO: no`, `TEL_PROMPTED: no`, `PROACTIVE_PROMPTED: no`, `ACTIVATED: no`, `FIRST_LOOP_SHOWN: no`, `HAS_ROUTING: no` (unless `ROUTING_DECLINED: true`), or `VENDORED_GSTACK: yes`. Skip entirely when `SPAWNED_SESSION: true`. | `~/.claude/skills/gstack/preamble/sections/onboarding.md` | +| the Artifacts Sync output shows `artifacts repo detected` or `ARTIFACTS_SYNC_PROMPT: needed` | `~/.claude/skills/gstack/preamble/sections/artifacts-sync.md` | If `PROACTIVE` is `"false"`, do not auto-invoke or proactively suggest skills. If a skill seems useful, ask: "I think /skillname might help here — want me to run it?" If `SKILL_PREFIX` is `"true"`, suggest/invoke `/gstack-*` names. Disk paths stay `~/.claude/skills/gstack/[skill-name]/SKILL.md`. +If `UPDATE_CHECK` is `"false"`, skip the next two lines — the update-check binary emits nothing in that mode, so there is no `UPGRADE_AVAILABLE` / `JUST_UPGRADED` output to act on. + If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If output shows `JUST_UPGRADED `: print "Running gstack v{to} (just updated!)". If `SPAWNED_SESSION` is true, skip feature discovery. @@ -160,165 +178,6 @@ Feature discovery, max one prompt per session: After upgrade prompts, continue workflow. -If `WRITING_STYLE_PENDING` is `yes`: ask once about writing style: - -> v1 prompts are simpler: first-use jargon glosses, outcome-framed questions, shorter prose. Keep default or restore terse? - -Options: -- A) Keep the new default (recommended — good writing helps everyone) -- B) Restore V0 prose — set `explain_level: terse` - -If A: leave `explain_level` unset (defaults to `default`). -If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. - -Always run (regardless of choice): -```bash -rm -f ~/.gstack/.writing-style-prompt-pending -touch ~/.gstack/.writing-style-prompted -``` - -Skip if `WRITING_STYLE_PENDING` is `no`. - -If `LAKE_INTRO` is `no`: say "gstack follows the **Boil the Ocean** principle — do the complete thing when AI makes marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" Offer to open: - -```bash -open https://garryslist.org/posts/boil-the-ocean -touch ~/.gstack/.completeness-intro-seen -``` - -Only run `open` if yes. Always run `touch`. - -If `TEL_PROMPTED` is `no` AND `LAKE_INTRO` is `yes`: ask telemetry once via AskUserQuestion: - -> Help gstack get better. Share usage data only: skill, duration, crashes, stable device ID. No code or file paths. Your repo name is recorded locally only and stripped before any upload. - -Options: -- A) Help gstack get better! (recommended) -- B) No thanks - -If A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry community` - -If B: ask follow-up: - -> Anonymous mode sends only aggregate usage, no unique ID. - -Options: -- A) Sure, anonymous is fine -- B) No thanks, fully off - -If B→A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry anonymous` -If B→B: run `~/.claude/skills/gstack/bin/gstack-config set telemetry off` - -Always run: -```bash -touch ~/.gstack/.telemetry-prompted -``` - -Skip if `TEL_PROMPTED` is `yes`. - -If `PROACTIVE_PROMPTED` is `no` AND `TEL_PROMPTED` is `yes`: ask once: - -> Let gstack proactively suggest skills, like /qa for "does this work?" or /investigate for bugs? - -Options: -- A) Keep it on (recommended) -- B) Turn it off — I'll type /commands myself - -If A: run `~/.claude/skills/gstack/bin/gstack-config set proactive true` -If B: run `~/.claude/skills/gstack/bin/gstack-config set proactive false` - -Always run: -```bash -touch ~/.gstack/.proactive-prompted -``` - -Skip if `PROACTIVE_PROMPTED` is `yes`. - -## First-run guidance (one-time) - -If `ACTIVATED` is `no` (first skill run on this machine) AND the preamble printed a non-empty `FIRST_TASK:` value that is NOT `nongit`: show ONE short, project-specific line mapped from the token, as a heads-up, then CONTINUE with whatever the user actually asked — do NOT halt their task. Map the token: `greenfield` → "Fresh repo — shape it first with `/spec` or `/office-hours`." `code_node`/`code_python`/`code_rust`/`code_go`/`code_ruby`/`code_ios` → "There's code here — `/qa` to see it work, or `/investigate` if something's off." `branch_ahead` → "Unshipped work on this branch — `/review` then `/ship`." `dirty_default` → "Uncommitted changes — `/review` before committing." `clean_default` → "Pick one: `/spec`, `/investigate`, or `/qa`." Then substitute the token you saw for TASK_TOKEN and run (best-effort), and mark activated: -```bash -~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type first_task_scaffold_shown --skill "TASK_TOKEN" --outcome shown 2>/dev/null || true -touch ~/.gstack/.activated 2>/dev/null || true -``` - -If `ACTIVATED` is `no` but `FIRST_TASK:` is empty or `nongit` (headless, non-git, or nothing actionable): show nothing, just run `touch ~/.gstack/.activated 2>/dev/null || true`. - -Else if `ACTIVATED` is `yes` AND `FIRST_LOOP_SHOWN` is `no`: say once as a heads-up (then continue): - -> Tip: gstack pays off when you complete one loop — **plan → review → ship**. A common first loop: `/office-hours` or `/spec` to shape it, `/plan-eng-review` to lock it, then `/ship`. - -Then run `touch ~/.gstack/.first-loop-tip-shown 2>/dev/null || true`. - -Skip this section if `ACTIVATED` and `FIRST_LOOP_SHOWN` are both `yes`. - -If `HAS_ROUTING` is `no` AND `ROUTING_DECLINED` is `false` AND `PROACTIVE_PROMPTED` is `yes`: -Check if a CLAUDE.md file exists in the project root. If it does not exist, create it. - -Use AskUserQuestion: - -> gstack works best when your project's CLAUDE.md includes skill routing rules. - -Options: -- A) Add routing rules to CLAUDE.md (recommended) -- B) No thanks, I'll invoke skills manually - -If A: Append this section to the end of CLAUDE.md: - -```markdown - -## Skill routing - -When the user's request matches an available skill, invoke it via the Skill tool. When in doubt, invoke the skill. - -Key routing rules: -- Product ideas/brainstorming → invoke /office-hours -- Strategy/scope → invoke /plan-ceo-review -- Architecture → invoke /plan-eng-review -- Design system/plan review → invoke /design-consultation or /plan-design-review -- Full review pipeline → invoke /autoplan -- Bugs/errors → invoke /investigate -- QA/testing site behavior → invoke /qa or /qa-only -- Code review/diff check → invoke /review -- Visual polish → invoke /design-review -- Ship/deploy/PR → invoke /ship or /land-and-deploy -- Save progress → invoke /context-save -- Resume context → invoke /context-restore -- Author a backlog-ready spec/issue → invoke /spec -``` - -Then commit the change: `git add CLAUDE.md && git commit -m "chore: add gstack skill routing rules to CLAUDE.md"` - -If B: run `~/.claude/skills/gstack/bin/gstack-config set routing_declined true` and say they can re-enable with `gstack-config set routing_declined false`. - -This only happens once per project. Skip if `HAS_ROUTING` is `yes` or `ROUTING_DECLINED` is `true`. - -If `VENDORED_GSTACK` is `yes`, warn once via AskUserQuestion unless `~/.gstack/.vendoring-warned-$SLUG` exists: - -> This project has gstack vendored in `.claude/skills/gstack/`. Vendoring is deprecated. -> Migrate to team mode? - -Options: -- A) Yes, migrate to team mode now -- B) No, I'll handle it myself - -If A: -1. Run `git rm -r .claude/skills/gstack/` -2. Run `echo '.claude/skills/gstack/' >> .gitignore` -3. Run `~/.claude/skills/gstack/bin/gstack-team-init required` (or `optional`) -4. Run `git add .claude/ .gitignore CLAUDE.md && git commit -m "chore: migrate gstack from vendored to team mode"` -5. Tell the user: "Done. Each developer now runs: `cd ~/.claude/skills/gstack && ./setup --team`" - -If B: say "OK, you're on your own to keep the vendored copy up to date." - -Always run (regardless of choice): -```bash -eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true -touch ~/.gstack/.vendoring-warned-${SLUG:-unknown} -``` - -If marker exists, skip. - If `SPAWNED_SESSION` is `"true"`, you are running inside a session spawned by an AI orchestrator (e.g., OpenClaw). In spawned sessions: - Do NOT use AskUserQuestion for interactive prompts. Auto-choose the recommended option. @@ -329,126 +188,17 @@ AI orchestrator (e.g., OpenClaw). In spawned sessions: ## Artifacts Sync (skill start) ```bash -_GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}" -# Prefer the v1.27.0.0 artifacts file; fall back to brain file for users -# upgrading mid-stream before the migration script runs. -if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then - _BRAIN_REMOTE_FILE="$HOME/.gstack-artifacts-remote.txt" -else - _BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt" -fi -_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync" -_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config" - -# /sync-gbrain context-load: teach the agent to use gbrain when it's available. -# Per-worktree pin: post-spike redesign uses kubectl-style `.gbrain-source` in the -# git toplevel to scope queries. Look for the pin in the worktree (not a global -# state file) so that opening worktree B without a pin doesn't claim "indexed" -# just because worktree A was synced. Empty string when gbrain is not -# configured (zero context cost for non-gbrain users). -_GBRAIN_CONFIG="$HOME/.gbrain/config.json" -if [ -f "$_GBRAIN_CONFIG" ] && command -v gbrain >/dev/null 2>&1; then - _GBRAIN_VERSION_OK=$(gbrain --version 2>/dev/null | grep -c '^gbrain ' || echo 0) - if [ "$_GBRAIN_VERSION_OK" -gt 0 ] 2>/dev/null; then - _GBRAIN_PIN_PATH="" - _REPO_TOP=$(git rev-parse --show-toplevel 2>/dev/null || echo "") - if [ -n "$_REPO_TOP" ] && [ -f "$_REPO_TOP/.gbrain-source" ]; then - _GBRAIN_PIN_PATH="$_REPO_TOP/.gbrain-source" - fi - if [ -n "$_GBRAIN_PIN_PATH" ]; then - echo "GBrain configured. Prefer \`gbrain search\`/\`gbrain query\` over Grep for" - echo "semantic questions; use \`gbrain code-def\`/\`code-refs\`/\`code-callers\` for" - echo "symbol-aware code lookup. See \"## GBrain Search Guidance\" in CLAUDE.md." - echo "Run /sync-gbrain to refresh." - else - echo "GBrain configured but this worktree isn't pinned yet. Run \`/sync-gbrain --full\`" - echo "before relying on \`gbrain search\` for code questions in this worktree." - echo "Falls back to Grep until pinned." - fi - fi -fi - -_BRAIN_SYNC_MODE=$("$_BRAIN_CONFIG_BIN" get artifacts_sync_mode 2>/dev/null || echo off) - -# Detect remote-MCP mode (Path 4 of /setup-gbrain). Local artifacts sync is -# a no-op in remote mode; the brain server pulls from GitHub/GitLab on its -# own cadence. Read claude.json directly to keep this preamble fast (no -# subprocess to claude CLI on every skill start). -_GBRAIN_MCP_MODE="none" -if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.claude.json" ]; then - _GBRAIN_MCP_TYPE=$(jq -r '.mcpServers.gbrain.type // .mcpServers.gbrain.transport // empty' "$HOME/.claude.json" 2>/dev/null) - case "$_GBRAIN_MCP_TYPE" in - url|http|sse) _GBRAIN_MCP_MODE="remote-http" ;; - stdio) _GBRAIN_MCP_MODE="local-stdio" ;; - esac -fi - -if [ -f "$_BRAIN_REMOTE_FILE" ] && [ ! -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" = "off" ]; then - _BRAIN_NEW_URL=$(head -1 "$_BRAIN_REMOTE_FILE" 2>/dev/null | tr -d '[:space:]') - if [ -n "$_BRAIN_NEW_URL" ]; then - echo "ARTIFACTS_SYNC: artifacts repo detected: $_BRAIN_NEW_URL" - echo "ARTIFACTS_SYNC: run 'gstack-brain-restore' to pull your cross-machine artifacts (or 'gstack-config set artifacts_sync_mode off' to dismiss forever)" - fi -fi - -if [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then - _BRAIN_LAST_PULL_FILE="$_GSTACK_HOME/.brain-last-pull" - _BRAIN_NOW=$(date +%s) - _BRAIN_DO_PULL=1 - if [ -f "$_BRAIN_LAST_PULL_FILE" ]; then - _BRAIN_LAST=$(cat "$_BRAIN_LAST_PULL_FILE" 2>/dev/null || echo 0) - _BRAIN_AGE=$(( _BRAIN_NOW - _BRAIN_LAST )) - [ "$_BRAIN_AGE" -lt 86400 ] && _BRAIN_DO_PULL=0 - fi - if [ "$_BRAIN_DO_PULL" = "1" ]; then - ( cd "$_GSTACK_HOME" && git fetch origin >/dev/null 2>&1 && git merge --ff-only "origin/$(git rev-parse --abbrev-ref HEAD)" >/dev/null 2>&1 ) || true - echo "$_BRAIN_NOW" > "$_BRAIN_LAST_PULL_FILE" - fi - "$_BRAIN_SYNC_BIN" --once 2>/dev/null || true -fi - -if [ "$_GBRAIN_MCP_MODE" = "remote-http" ]; then - # Remote-MCP mode: local artifacts sync is a no-op (brain admin's server - # pulls from GitHub/GitLab). Show the user this is by design, not broken. - _GBRAIN_HOST=$(jq -r '.mcpServers.gbrain.url // empty' "$HOME/.claude.json" 2>/dev/null | sed -E 's|^https?://([^/:]+).*|\1|') - echo "ARTIFACTS_SYNC: remote-mode (managed by brain server ${_GBRAIN_HOST:-remote})" -elif [ -d "$_GSTACK_HOME/.git" ] && [ "$_BRAIN_SYNC_MODE" != "off" ]; then - _BRAIN_QUEUE_DEPTH=0 - [ -f "$_GSTACK_HOME/.brain-queue.jsonl" ] && _BRAIN_QUEUE_DEPTH=$(wc -l < "$_GSTACK_HOME/.brain-queue.jsonl" | tr -d ' ') - _BRAIN_LAST_PUSH="never" - [ -f "$_GSTACK_HOME/.brain-last-push" ] && _BRAIN_LAST_PUSH=$(cat "$_GSTACK_HOME/.brain-last-push" 2>/dev/null || echo never) - echo "ARTIFACTS_SYNC: mode=$_BRAIN_SYNC_MODE | last_push=$_BRAIN_LAST_PUSH | queue=$_BRAIN_QUEUE_DEPTH" -else - echo "ARTIFACTS_SYNC: off" -fi -``` - - - -Privacy stop-gate: if output shows `ARTIFACTS_SYNC: off`, `artifacts_sync_mode_prompted` is `false`, and gbrain is on PATH or `gbrain doctor --fast --json` works, ask once: - -> gstack can publish your artifacts (CEO plans, designs, reports) to a private GitHub repo that GBrain indexes across machines. How much should sync? - -Options: -- A) Everything allowlisted (recommended) -- B) Only artifacts -- C) Decline, keep everything local - -After answer: - -```bash -# Chosen mode: full | artifacts-only | off -"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode -"$_BRAIN_CONFIG_BIN" set artifacts_sync_mode_prompted true +~/.claude/skills/gstack/bin/gstack-artifacts-preamble 2>/dev/null || echo "ARTIFACTS_SYNC: off" ``` -If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-init`. Do not block the skill. +If the output includes `artifacts repo detected` or `ARTIFACTS_SYNC_PROMPT: needed`, +Read `~/.claude/skills/gstack/preamble/sections/artifacts-sync.md` and follow it before continuing. Otherwise continue. At skill END before telemetry: ```bash -"~/.claude/skills/gstack/bin/gstack-brain-sync" --discover-new 2>/dev/null || true -"~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true +~/.claude/skills/gstack/bin/gstack-brain-sync --discover-new 2>/dev/null || true +~/.claude/skills/gstack/bin/gstack-brain-sync --once 2>/dev/null || true ``` @@ -521,11 +271,15 @@ fi if [ "$_TEL" != "off" ] && [ -x ~/.claude/skills/gstack/bin/gstack-telemetry-log ]; then ~/.claude/skills/gstack/bin/gstack-telemetry-log \ --skill "SKILL_NAME" --duration "$_TEL_DUR" --outcome "OUTCOME" \ - --used-browse "USED_BROWSE" --session-id "$_SESSION_ID" 2>/dev/null & + --used-browse "USED_BROWSE" --session-id "$_SESSION_ID" \ + --error-message "ERROR_MESSAGE" --failed-step "FAILED_STEP" 2>/dev/null & fi ``` Replace `SKILL_NAME`, `OUTCOME`, and `USED_BROWSE` before running. +Replace `ERROR_MESSAGE` with a short description of the error (if outcome is error, +otherwise use empty string ""), and `FAILED_STEP` with the step name or number where +the failure occurred (if outcome is error, otherwise use empty string ""). ## Plan Status Footer @@ -558,12 +312,14 @@ quality gates that produce better results than answering inline. **Routing rules — when you see these patterns, INVOKE the skill via the Skill tool:** - User describes a new idea, asks "is this worth building", brainstorms, pitches a concept → invoke `/office-hours` - User asks to spec something out, file an issue, write up a ticket, "turn this into a GitHub issue", "backlog item" → invoke `/spec` +- User asks to define acceptance criteria, deliverables, or "definition of done" for a plan, after /office-hours and before coding → invoke `/plan-deliverables` - User asks about strategy, scope, ambition, "think bigger", "what should we build" → invoke `/plan-ceo-review` - User asks to review architecture, lock in the plan, "does this design make sense" → invoke `/plan-eng-review` - User asks about design system, brand, visual identity, "how should this look" → invoke `/design-consultation` - User asks to review design of a plan → invoke `/plan-design-review` - User asks about developer experience of a plan, API/CLI/SDK design → invoke `/plan-devex-review` - User wants all reviews done automatically, "review everything" → invoke `/autoplan` +- User asks to autonomously build out an approved plan end-to-end, drive the backlog/plan to completion via subagents, "autobuild it", "run the build loop" → invoke `/autobuilder-loop` - User reports a bug, error, broken behavior, "why is this broken", "this doesn't work", "wtf", "something's wrong" → invoke `/investigate` - User asks to test the site, find bugs, QA, "does this work", "check the deploy" → invoke `/qa` - User asks to just report bugs without fixing → invoke `/qa-only` diff --git a/SKILL.md.tmpl b/SKILL.md.tmpl index 402bd0d7b0..0dd0637093 100644 --- a/SKILL.md.tmpl +++ b/SKILL.md.tmpl @@ -47,12 +47,14 @@ quality gates that produce better results than answering inline. **Routing rules — when you see these patterns, INVOKE the skill via the Skill tool:** - User describes a new idea, asks "is this worth building", brainstorms, pitches a concept → invoke `/office-hours` - User asks to spec something out, file an issue, write up a ticket, "turn this into a GitHub issue", "backlog item" → invoke `/spec` +- User asks to define acceptance criteria, deliverables, or "definition of done" for a plan, after /office-hours and before coding → invoke `/plan-deliverables` - User asks about strategy, scope, ambition, "think bigger", "what should we build" → invoke `/plan-ceo-review` - User asks to review architecture, lock in the plan, "does this design make sense" → invoke `/plan-eng-review` - User asks about design system, brand, visual identity, "how should this look" → invoke `/design-consultation` - User asks to review design of a plan → invoke `/plan-design-review` - User asks about developer experience of a plan, API/CLI/SDK design → invoke `/plan-devex-review` - User wants all reviews done automatically, "review everything" → invoke `/autoplan` +- User asks to autonomously build out an approved plan end-to-end, drive the backlog/plan to completion via subagents, "autobuild it", "run the build loop" → invoke `/autobuilder-loop` - User reports a bug, error, broken behavior, "why is this broken", "this doesn't work", "wtf", "something's wrong" → invoke `/investigate` - User asks to test the site, find bugs, QA, "does this work", "check the deploy" → invoke `/qa` - User asks to just report bugs without fixing → invoke `/qa-only` diff --git a/TODOS.md b/TODOS.md index 29721e6e50..24f7edcf09 100644 --- a/TODOS.md +++ b/TODOS.md @@ -45,6 +45,104 @@ a silent mistake breaks all 52 skills. High blast radius — needs its own focus ## Test infrastructure +### P2: Wire `design/test/` into CI (all 8 files are invisible to every runner) + +**What:** Add `design/test/` to the `bun test` glob (`package.json:21`) and +`TEST_ROOTS` (`scripts/test-free-shards.ts:32`) after auditing its 8 files for +server-spawning/flakiness (they were plausibly excluded on purpose). While in +there, fix the known timing flake: `variants-retry-after.test.ts` "HTTP-date: +honors a future date with no extra leading exponential" fails ~1-2 in 9 runs +under parallel suite load (verified pre-existing on v1.58.5.0 during the +June 2026 fix wave — wall-clock assertion with a ~2s window). + +**Why:** Every test in `design/test/` runs only when someone types the path by +hand — a silent coverage hole, the fix wave's theme at meta-level. The wave's +own design tests went into `test/design-flag-utils.test.ts` to dodge this. + +**Pros:** design binary gets CI coverage; kills a latent "we have tests" illusion. +**Cons:** unaudited files may spawn servers or flake; audit first, wire second. + +**Context:** Filed from the June 2026 fix-wave eng review (issue 11 + flake +receipts). Start with the audit: which of the 8 files are hermetic? Wire the +hermetic ones, quarantine or fix the rest. + +**Effort:** S-M (human ~1d, CC ~30min). **Depends on:** None. + +### P2: /context-save worktree-identity hardening (the #2052 residual) + +**What:** Persist a stable worktree identity (path hash or worktree name) into +checkpoint frontmatter at save time; `/context-restore` prefers identity match +over branch-name match. PR #2054 (@jbetala7, absorbed in the June 2026 wave) +fixed restore ORDERING (current-branch first), but branch frontmatter is not a +stable worktree identity: same-name branches across clones/remotes, renamed +branches, and detached HEAD can still restore the wrong checkpoint. + +**Why:** Closes the residual wrong-checkpoint class entirely instead of the +common case. Codex outside-voice concurred during the wave's eng review. + +**Pros:** Eliminates cross-clone checkpoint collisions. +**Cons:** Frontmatter schema change; needs a migration story for old +checkpoints (no-identity checkpoints rank as fallback, like #2054's +no-branch handling). + +**Context:** Filed from the June 2026 fix-wave eng review (NOT-in-scope item). +Start at `context-restore/SKILL.md.tmpl` Step 1 + `/context-save`'s frontmatter +writer; mirror #2054's partition logic with identity as the first key. + +**Effort:** S (human ~4h, CC ~20min). **Depends on:** #2054 (landed in the wave). + +### P3: gbrain reindex-in-place on perpetual drift (conditional — check the drift log first) + +**What:** IF the `[gbrain-sources] drift:` stderr line (added in the June 2026 +wave) shows drift firing on every sync for some environment, implement #1985's +reporter design: refresh an existing source in place with `gbrain reindex-code` +instead of remove+add (which drops and re-embeds the full index — 768 pages / +6,786 embeddings in the reporter's case). + +**Why:** Perpetual drift means paying full re-embed cost every sync. The wave's +`realpathSync` normalization (symlink aliases are a match, not drift) may have +eliminated the drift class entirely — that's why this is conditional. + +**Pros:** Avoids repeated embedding spend for affected environments. +**Cons:** Speculative until the drift log produces evidence; reindex-in-place +has its own consistency questions (stale chunks for deleted files). + +**Context:** Filed from the June 2026 fix-wave eng review (4A observability). +Trigger condition documented in `lib/gbrain-sources.ts` at the drift log line. + +**Effort:** M (human ~1d, CC ~45min). **Depends on:** drift-log evidence from +the wave's `ensureSourceRegistered` logging. +### P1: Free suite exit code is untrustworthy — in-process force-exits mask failures + +**Priority:** P1 + +**What:** At least five browse test files end with `setTimeout(() => process.exit(0), 500)` +(browse/test/commands.test.ts:101, snapshot.test.ts:36, batch.test.ts:47, +handoff.test.ts:31, content-security.test.ts:465). The timer fires inside the SHARED +`bun test` process, exiting 0 before bun prints its final summary — so `bun test` can +report exit 0 while real test failures scrolled by earlier. Remove the force-exits and +fix the underlying handle leaks they paper over (lingering Playwright/daemon handles +that once made the suite hang), or scope the exit to a spawned child process. + +**Why:** Observed 2026-08-07: three genuinely failing tests (eval-list-cli, +benchmark-cli, observability check 11) rode green `bun test` exit codes across +multiple runs; the failures only surfaced by grepping logs for "(fail)" lines. A test +suite that exits 0 on failure is worse than no suite — it manufactures false +confidence at commit time and in any CI job that trusts the exit code. + +**Pros:** Restores the one contract everything (CI, /ship, humans) relies on: exit +code == truth. Also un-hides the missing final summary block. +**Cons:** The force-exits exist because the suite once hung on leaked handles; +removing them without fixing the leaks trades silent failure for hangs. Needs a +focused pass: find each leaked handle (daemon children, PTY, Playwright contexts), +close them in afterAll, then delete the exits one file at a time. + +**Context / where to start:** `grep -rn "process.exit(0)" browse/test/` — the +setTimeout variants are the offenders (server-no-import-side-effects.test.ts:62 is a +spawned-child probe, fine). Repro: run the full free suite and note the log ends at +the browse files with no "Ran N tests" summary. Receipts: +~/.gstack-dev/logs/free-suite-main-check.log (3 masked fails, exit 0). + ### P2: Periodic CI matrix covers 9 of ~66 e2e files — decide the coverage contract **Priority:** P2 @@ -133,6 +231,76 @@ v1.47.0.0 baselines retained in `test/fixtures/` for the v1→v2 audit trail. Th captured skill bytes match `origin/main` exactly (the rebasing branch left every SKILL.md untouched). `bun test` is green again. +## Scope-gate follow-ups (filed via /plan-eng-review on the plan-mode auto-select-B change) + +### P2: SDK eval budgets charge API-queue latency to the work budget — pick a structural fix + +**What:** `runSkillTest`'s single `setTimeout(timeout)` arms at spawn, so session +startup AND the model's first-completion queue time are charged against the +test's work budget. Under concurrent load (11 CI matrix jobs, or local eval +runs sharing the org API), a first completion can queue 60-90s+, producing the +deterministic `0 turns / $0.00 / s x3 attempts` failure shape. Observed: +`review-dashboard-via` (PR #2472, 180s→300s), `retro-base-branch` (240s→360s), +`plan-ceo-plan-mode` (300s→420s, 2026-08-12), `design-consultation-preview` +(90s→300s, PR #2533 CI). Every fix so far is a per-test budget bump. + +**Why not just re-arm the timer on first stream event:** an audit (2026-08-12) +found ~100 outer bun-timeout literals sized as inner+30-60s; re-arming the inner +clock breaks every outer/inner relationship and needs a codemod of all of them. + +**Options:** (a) two-phase timer in session-runner (startup grace, re-arm on +first NDJSON line) + codemod outer literals to inner+grace+slack; (b) adopt a +300s floor for all CI SDK budgets (statically enforceable — a free test can +assert no `timeout: <300_000` in skill-e2e files) and stop re-litigating per +test; (c) startup-spawn semaphore in the runner (bounds the boot stampede but +not API-side queuing — evidence says queuing dominates, so likely insufficient +alone). Recommend (b) short-term + (a) properly sequenced with the codemod. + +**Depends on / blocked by:** none. + +### P2: Wire the four demoted plan-mode/finding-floor PTY tests into periodic CI + +**What:** `evals-periodic.yml` runs an explicit 9-file matrix; the four tests +demoted to `periodic` in v1.62.0.0 (`skill-e2e-plan-eng-plan-mode`, +`skill-e2e-plan-design-plan-mode`, `skill-e2e-plan-eng-finding-floor`, +`skill-e2e-plan-design-finding-floor`) are not in it, so they currently run +only locally/manually (`bun run test:periodic` or `eval:bg:periodic`). Wiring +them needs a PTY-capable periodic job: the container skill-registration setup +from evals.yml's `e2e-pty-plan-smoke` job (real-file SKILL.md copies for the +TUI's cross-mount symlink bug) with `EVALS_TIER=periodic`. + +**Why:** Codex re-review P2 on the v1.62.0.0 ship. This is a named instance of +the existing periodic-orphans problem (see "P1/P2 periodic coverage" TODO in +Test infrastructure) — solve it there or here, once. + +**Depends on / blocked by:** none; sibling of the periodic-orphans TODO above. + +### P3: Extract the whole scope gate to a shared `{{SCOPE_GATE}}` resolver + +**What:** Move the duplicated scope-gate prose (heading, intro sentence, the +plan-mode/named-target exceptions block, numbered items, the A/B/C menu, and the +Recommendation line) from `plan-eng-review/SKILL.md.tmpl` and +`plan-design-review/SKILL.md.tmpl` into a `scripts/resolvers/` module with 4-5 +injected variant slots (preceded-by list, item-2 phrasing, option-C vocabulary, +recommendation tail, exceptions action tail). + +**Why:** The two copies are hand-synced today. The drift-guard test in +`test/gen-skill-docs.test.ts` ("scope-gate exceptions drift-guard") makes the +duplication safe but is a stopgap — one source of truth is the real fix. Filed +as D5 of the eng review on the plan-mode auto-select-B change (2026-08-11). + +**Pros:** Single source for a load-bearing gate; future gate changes (new +exceptions, wording tuning) land once. +**Cons:** Touches the resolver registry and its tests; must preserve the exact +generated bytes or re-baseline the carve/parity ceilings. + +**Context / where to start:** structural-only diff, sequenced AFTER the +behavior change (refactor and behavior never together). The drift-guard test +becomes the migration's acceptance check: extract, regen, confirm byte-identical +output, then retire or simplify the guard. Effort: human ~half day / CC ~20 min. + +**Depends on / blocked by:** the plan-mode auto-select-B PR landing on main. + ## Token-reduction follow-ups (Phase B, filed via /plan-eng-review on the plan-ceo-review carve) ### P3: Carve the always-loaded `{{PREAMBLE}}` reference blocks into an on-demand doc @@ -707,32 +875,6 @@ plus a TTL so abandoned PTYs eventually exit. --- -### v1.1+: Audit `/health` token distribution - -**What:** Codex's outside-voice review on cc-pty-import flagged that -`/health` already surfaces `AUTH_TOKEN` to any localhost caller in headed -mode (`server.ts:1657`). That's a pre-existing soft leak — anything -running on localhost gets the root token by hitting `/health`. - -**Why:** cc-pty-import sidesteps it by NOT putting the PTY token there -(uses an HttpOnly cookie path instead). But the underlying leak is still -shippable surface. A second extension or a localhost web app could -currently scrape `AUTH_TOKEN` and hit any browse-server endpoint. - -**Pros:** Closes a real privilege-escalation path on multi-extension -machines. **Cons:** Either we tighten the gate (Origin must be OUR -extension id, not just any chrome-extension://) or we move bootstrap -discovery off `/health` entirely. Either has migration cost for tests -and the existing extension. - -**Context:** codex finding #2 on cc-pty-import plan-eng review. Not in -scope of that PR; deliberately deferred to keep PTY-import small. - -**Priority:** P2. -**Effort:** M. - ---- - ## Testing ## P2: Per-finding AskUserQuestion count assertion for /plan-ceo-review @@ -2486,3 +2628,158 @@ CI-hard-fail contract has to land five times. five green files at the tail of a release. Zero user-facing value; pure DRY. **Effort:** S (human ~3h, CC ~20min). **Depends on:** None. + +## Egress-receipt follow-ups (filed via /plan-eng-review + /codex on the v1.63 port wave) + +### P2: egress ledger rotation with chain-genesis records + +**What:** Rotate `~/.gstack/security/egress.jsonl` at a size threshold (match +`attempts.jsonl`'s 10MB/5-generation pattern in `browse/src/security.ts`), where +each new generation's FIRST record embeds the prior file's tail hash so +`gstack-egress verify` can walk across generations. + +**Why:** v1.63 ships WARN-at-25MB (visible growth) but nothing bounds the file. +Rotation was deliberately deferred: it changes the verify contract, and a wrong +implementation makes healthy ledgers verify as "broken". + +**Pros:** Bounded disk forever; verify stays meaningful across generations. +**Cons:** Chain-genesis semantics are subtle; needs its own focused tests +(cross-generation verify, mid-rotation crash). + +**Context:** `lib/egress-receipt.ts` (`appendChained`/`verifyLedger`) carries the +design sketch in its rotation TODO comment. Start from the `attempts.jsonl` +rotation precedent. + +**Effort:** S (human ~4h, CC ~25min). **Depends on:** v1.63 port wave landed. + +### P3: launch-nonce token bootstrap (local-process impersonation) + +**What:** Add a launch-time nonce to the `/extension-token` bootstrap: `browse` +mints a nonce at headed launch, seeds it into the extension (CDP +`chrome.storage` injection or a launcher-written sidecar), and the endpoint +requires it alongside the pinned origin. + +**Why:** v1.63's pinned-origin check authenticates browser contexts; any local +PROCESS can still forge an Origin header with curl. That threat is explicitly +outside the current model (any local process can hit the port anyway) — this +TODO documents the deliberate boundary and the designed path across it. + +**Pros:** Closes the local-process impersonation path (strongest of the three +options evaluated in the v1.63 plan review). +**Cons:** Largest bootstrap change; CDP seeding is fiddly across the three +launch paths (`--load-extension`, baked-in Browser.app, real-Chrome fallback); +low present-day value. + +**Context:** `browse/src/server.ts` `/extension-token` handler + +`GSTACK_EXTENSION_ID`; launch paths in `browse/src/browser-manager.ts` (~358, +~455, ~1562); `extension/background.js` bootstrap. + +**Effort:** M (human ~2 days, CC ~1h). **Depends on:** none. + +### P3: eval-watch shard-awareness + +**What:** Teach `scripts/eval-watch.ts` (hardcoded `_partial-e2e.json` path at +~line 17) about the sharded layout: watch `/shards/*/_partial-e2e.json` +and aggregate live progress across shard subdirs. + +**Why:** v1.63's sharded runner gives each shard its own eval subdir (so shards +baseline against their own priors); `findPreviousRun`, `eval-compare`, +`eval-list`, and `eval-summary` were all made shard-aware, but the live watcher +intentionally stayed flat — it shows nothing during sharded runs. + +**Pros:** Live progress during `eval:bg:gate` sharded runs again. +**Cons:** Multi-file watch + aggregation UI; low stakes (the run-scoped detach +log already streams per-shard results). + +**Context:** `scripts/eval-watch.ts`; shard layout defined in +`scripts/test-paid-shards.ts` (slug = test filename); `listEvalJsonFiles` in +`test/helpers/eval-store.ts` already enumerates the layout — reuse it. + +**Effort:** S (human ~2h, CC ~15min). **Depends on:** v1.63 port wave landed. + +## v1.63 port-wave review follow-ups (deferred from /ship review army — non-blocking polish) + +Genuine review findings deferred from the v1.63 ship because they are +informational/polish, not correctness-blocking, and several want their own +tests. Filed so they are tracked, not dropped. + +- **P2 — telemetry-sync HTTP-status outcome is dead code.** `_GSTACK_EGRESS_LAST_RECEIPT` + is set inside a command-substitution subshell in `bin/gstack-telemetry-sync`, so the + parent-shell guard that would append the HTTP status to the receipt never fires. The + generic `exit:N` outcome is still recorded, so the ledger is correct, just less + precise. Fix: have `_receipted_curl` persist the receipt id to a caller-readable temp + file, or restructure the call out of the subshell. (Confirmed by 3 review specialists.) +- **P2 — context-bill "TOTAL on disk" double-counts child skills** in a root-as-container + tree (this repo's own layout): `buildBill` sums the root skill's whole-tree walk plus + each child's subtree again (~2x the TOTAL line). ALWAYS-ON / EAGER / --diff / --budget + are all unaffected — only the informational TOTAL is wrong. Fix: compute the tree total + from a single deduplicated `walkMd(root)` pass, or exclude child dirs from the root + skill's `totalMd`. Needs a fixture test. (`lib/context-bill.ts`.) +- **P3 — DRY/robustness polish:** one shared `_gstack_egress_host_of` helper for the + ~11 hand-rolled URL-to-host extractions across the egress shell sinks; extract the + duplicated tunnel-open `writeReceipt` block in `browse/src/server.ts` (two sites); + hoist the per-iteration `SharedArrayBuffer` alloc out of the egress-receipt lock spin; + replace context-bill's exact-mode `errorPct === 0` sentinel with an explicit flag; + reuse `frontmatterName()` from `skill-census.ts` in `catalog-budget.test.ts`. +- **P3 — test-coverage gaps the audit named:** `PAID_TEST_GLOBS` ↔ `package.json` + `test:gate` parity test; `GSTACK_EXTENSION_ID` ↔ `manifest.json` key derivation parity + test (`browse/scripts/extension-id.ts`); a runner test asserting each shard child gets + its own `GSTACK_EVAL_DIR` under `shards/`; receipt-refusal branch tests for + supabase-provision / gbrain-sync / memory-ingest. + +## P2: harden or re-tier skill-e2e-plan-design-with-ui PTY detection + +**What:** The gate-tier `test/skill-e2e-plan-design-with-ui.test.ts` began executing +for the first time once v1.63's `seedSkills` registered skills in hermetic PTY +children (the fork had deleted this file; it measured nothing before). It now +reliably TIMES OUT even though the skill runs correctly: the transcript shows +`/plan-design-review` reaching its scope-gate AskUserQuestion (5 options, the +`` marker present), but the test's +`isNumberedOptionListVisible`/`parseNumberedOptions` scraping can't classify it out +of the PTY buffer because spinner frames (`[?25l✻Sprouting… still thinking`) are +interleaved character-by-character with the option text. + +**Why:** Shipped behavior is correct — this is a test-harness detection limitation, +not a product bug. But a gate test that always times out is worse than no test. + +**Fix options:** (a) harden the tail-scraping (drop DEC private-mode + spinner +residue before matching; widen/clean the window); (b) add an LLM-judge fallback +classifier (the file's own comments note the regex detectors are "brittle to PTY +rendering quirks"); or (c) move this test to periodic until (a)/(b) lands. + +**Context:** `test/skill-e2e-plan-design-with-ui.test.ts`, +`test/helpers/claude-pty-runner.ts:308` (`isNumberedOptionListVisible`). Evidence: +`~/.gstack-dev/eval-runs/pdwu-verify-*.log`. **Effort:** M (human ~half day / CC ~30min). + +### P2: Follow-up fix waves from the 2026-08-14 tracker audit (v1.64.0.0) + +The full-tracker audit behind v1.64.0.0 verified every open PR/issue against +main and consciously deferred four coherent fix waves. Audit records: +`~/.gstack/projects/garrytan-gstack/` eng-review artifacts + the v1.64 PR body. + +**Wave A — browse-daemon lifecycle.** Watchdog kills headed handoff sessions +(PRs 2565/2405/2346), macOS headed launch broken by the rebrand-invalidated +Chromium signature + XProtect (issues 2554/2242/2138/1829/1379 — the three +darwin-skipped handoff tests in browse/test/handoff.test.ts un-skip when this +lands), busy-daemon kill (2219/2231), cosmetic SIGTERM ignore (2220), +Playwright pin bump (PR 1761, #1703 — rebuilds the CI browser image). +Start with the signature/re-sign question; everything else is small. + +**Wave B — install integrity.** connect-chrome alias shadowing (PR 2202, +issues 2201/2511), Playwright bootstrap aborts/timeouts (PRs 2233/2359, +issues 1902/2136), --host cursor/slate wiring (PRs 2547/2432, issue 2361), +review checklist/specialists never copied (issues 2317/2518), Windows re-run +refresh (#2444). Blast radius is `setup` — one focused PR. + +**Wave C — gbrain trust boundary.** Transcript trust/scope/source isolation +(PR 2232, issue 2140), brain-sync queue truncation (#2549), worktree source +pins (PR 2417, #2516), thin-client detection gaps (#2520/#2456), plus small +absorbs (2371/2360/2406/2369/2368/2321). Needs never-double-store review. + +**Wave D — ship/version allocator.** Queue-down fallback (PRs 2545/2546), +npm-invalid subdir manifest versions (PR 2531), versionless repos +(2343/2334/2501, #1474), diff-scope specialist routing rewrite +(#2526/#2299/#2455), /review token runaway (#2519). + +**Depends on:** v1.64.0.0 landing. Each wave is one bundled PR per the +fix-wave pattern. diff --git a/USING_GBRAIN_WITH_GSTACK.md b/USING_GBRAIN_WITH_GSTACK.md index ec1144c9a5..06e50faedd 100644 --- a/USING_GBRAIN_WITH_GSTACK.md +++ b/USING_GBRAIN_WITH_GSTACK.md @@ -132,6 +132,8 @@ Storage: `~/.gstack/gbrain-repo-policy.json`, mode 0600, schema-versioned so fut The skill runs three stages — code, memory, brain-sync — independently. A failure in one doesn't block the others. State persists to `~/.gstack/.gbrain-sync-state.json` so re-running picks up cleanly. +Stages that can send data off-machine (code sync into a possibly-remote gbrain DB, memory ingest, the brain-sync push) each write a tamper-evident receipt to the egress ledger (`~/.gstack/security/egress.jsonl`) before sending, fail-closed: if the receipt can't be written, the stage refuses with `EGRESS_RECEIPT_FAILED` instead of syncing unrecorded. Fix is usually `mkdir -p ~/.gstack/security && chmod -R u+w ~/.gstack/security`, then re-run. Inspect receipts with `gstack-egress list`. + **What it does on a fresh worktree:** 1. **Pre-flight.** Checks `gbrain_local_status` (the local engine's health). If the engine is `broken-db` or `broken-config`, the skill STOPs with a remediation menu — it refuses to silently degrade. If the local engine is missing and you're in remote-MCP mode (Path 4), the code stage SKIPs cleanly and only brain-sync runs. @@ -167,14 +169,16 @@ This is different from gbrain itself. Your gstack state (`~/.gstack/` — learni Turn it on with: ```bash -gstack-brain-init +gstack-artifacts-init ``` You'll get a one-time privacy prompt: **everything allowlisted** / **artifacts only** (plans, designs, retros, learnings — skip behavioral data like timelines) / **off**. Every skill run syncs the queue at start and end — no daemon, no background process. Secret-shaped content (AWS keys, GitHub tokens, PEM blocks, JWTs, bearer tokens) is blocked from sync before it leaves your machine. -**On a new machine:** Copy `~/.gstack-brain-remote.txt` over, run `gstack-brain-restore`, and yesterday's learnings surface on today's laptop. +**On a new machine:** Copy `~/.gstack-artifacts-remote.txt` over (the legacy +`~/.gstack-brain-remote.txt` name still works), run `gstack-brain-restore`, and +yesterday's learnings surface on today's laptop. Full guide: [docs/gbrain-sync.md](docs/gbrain-sync.md). Error index: [docs/gbrain-sync-errors.md](docs/gbrain-sync-errors.md). @@ -239,7 +243,7 @@ Gbrain itself ships with these that gstack wraps: | `~/.gstack/.setup-gbrain.lock.d` | Concurrent-run lock (atomic mkdir). Released on normal exit + SIGINT. | | `~/.gstack/.brain-queue.jsonl` | Pending sync entries for gstack memory sync | | `~/.gstack/.brain-last-push` | Timestamp of last sync push (for `/health` scoring) | -| `~/.gstack-brain-remote.txt` | URL of your gstack memory sync remote (safe to copy between machines) | +| `~/.gstack-artifacts-remote.txt` | URL of your gstack memory sync remote (safe to copy between machines; legacy name `~/.gstack-brain-remote.txt` still read) | | `~/.gstack/.setup-gbrain-inflight.json` | Reserved for future `--resume-provision` persisted state | ### Environment variables diff --git a/VERSION b/VERSION index c4190e0048..362038af84 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.60.1.0 +1.64.1.0 diff --git a/autobuilder-loop/SKILL.md b/autobuilder-loop/SKILL.md new file mode 100644 index 0000000000..c005c8bff8 --- /dev/null +++ b/autobuilder-loop/SKILL.md @@ -0,0 +1,1376 @@ +--- +name: autobuilder-loop +preamble-tier: 3 +version: 1.6.1 +description: Use when asked to "autobuilder", "build loop", "auto-build", "keep building automatically", "drive the plan to completion", or "run the build loop" on an already-approved plan, spec, or backlog. (gstack) +triggers: + - autobuilder loop + - automatic build loop + - auto build pipeline + - drive plan to completion +allowed-tools: + - Agent + - Bash + - AskUserQuestion +--- + + + + +## When to invoke this skill + +Proactively suggest when the user has an approved plan (TODOS.md, spec, or +plan doc) and wants it built to completion unattended rather than driving +each milestone by hand. + +Voice triggers (speech-to-text aliases): "auto builder", "build loop", "auto build loop". + +## Preamble (run first) + +```bash +_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true) +[ -n "$_UPD" ] && echo "$_UPD" || true +mkdir -p ~/.gstack/sessions +touch ~/.gstack/sessions/"$PPID" +_SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') +find ~/.gstack/sessions -mmin +120 -type f -exec rm {} + 2>/dev/null || true +_PROACTIVE=$(~/.claude/skills/gstack/bin/gstack-config get proactive 2>/dev/null || echo "true") +_PROACTIVE_PROMPTED=$([ -f ~/.gstack/.proactive-prompted ] && echo "yes" || echo "no") +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" +_SKILL_PREFIX=$(~/.claude/skills/gstack/bin/gstack-config get skill_prefix 2>/dev/null || echo "false") +echo "PROACTIVE: $_PROACTIVE" +echo "PROACTIVE_PROMPTED: $_PROACTIVE_PROMPTED" +echo "SKILL_PREFIX: $_SKILL_PREFIX" +source <(~/.claude/skills/gstack/bin/gstack-repo-mode 2>/dev/null) || true +REPO_MODE=${REPO_MODE:-unknown} +echo "REPO_MODE: $REPO_MODE" +_SESSION_KIND=$(~/.claude/skills/gstack/bin/gstack-session-kind 2>/dev/null || echo "interactive") +case "$_SESSION_KIND" in spawned|headless|interactive) ;; *) _SESSION_KIND="interactive" ;; esac +echo "SESSION_KIND: $_SESSION_KIND" +# Conductor host: AskUserQuestion is unreliable here (native disabled, MCP +# variant flaky), so skills render decisions as prose instead of calling the +# tool. Gated on !headless so an eval/CI run INSIDE Conductor (GSTACK_HEADLESS) +# still BLOCKs rather than rendering prose to nobody. +if [ "$_SESSION_KIND" != "headless" ] && { [ -n "${CONDUCTOR_WORKSPACE_PATH:-}" ] || [ -n "${CONDUCTOR_PORT:-}" ]; }; then + echo "CONDUCTOR_SESSION: true" +fi +_ACTIVATED=$([ -f ~/.gstack/.activated ] && echo "yes" || echo "no") +_FIRST_LOOP_SHOWN=$([ -f ~/.gstack/.first-loop-tip-shown ] && echo "yes" || echo "no") +echo "ACTIVATED: $_ACTIVATED" +echo "FIRST_LOOP_SHOWN: $_FIRST_LOOP_SHOWN" +# First-run project detection: run the detector ONLY on the first-ever skill run +# (ACTIVATED=no, interactive) so it stays off the hot path for every run after. +_FIRST_TASK="" +if [ "$_ACTIVATED" = "no" ] && [ "$_SESSION_KIND" != "headless" ]; then + _FIRST_TASK=$(~/.claude/skills/gstack/bin/gstack-first-task-detect 2>/dev/null || true) +fi +echo "FIRST_TASK: $_FIRST_TASK" +_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no") +echo "LAKE_INTRO: $_LAKE_SEEN" +_TEL=$(~/.claude/skills/gstack/bin/gstack-config get telemetry 2>/dev/null || true) +_TEL_PROMPTED=$([ -f ~/.gstack/.telemetry-prompted ] && echo "yes" || echo "no") +_TEL_START=$(date +%s) +_SESSION_ID="$$-$(date +%s)" +echo "TELEMETRY: ${_TEL:-off}" +echo "TEL_PROMPTED: $_TEL_PROMPTED" +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +_QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") +echo "QUESTION_TUNING: $_QUESTION_TUNING" +_UPDATE_CHECK=$(~/.claude/skills/gstack/bin/gstack-config get update_check 2>/dev/null || echo "true") +echo "UPDATE_CHECK: $_UPDATE_CHECK" +mkdir -p ~/.gstack/analytics +if [ "$_TEL" != "off" ]; then +echo '{"skill":"autobuilder-loop","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(_repo=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null | tr -cd 'a-zA-Z0-9._-'); echo "${_repo:-unknown}")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true +fi +for _PF in $(find ~/.gstack/analytics -maxdepth 1 -name '.pending-*' 2>/dev/null); do + if [ -f "$_PF" ]; then + if [ "$_TEL" != "off" ] && [ -x "$HOME/.claude/skills/gstack/bin/gstack-telemetry-log" ]; then + ~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type skill_run --skill _pending_finalize --outcome unknown --session-id "$_SESSION_ID" 2>/dev/null || true + fi + rm -f "$_PF" 2>/dev/null || true + fi + break +done +eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true +_LEARN_FILE="${GSTACK_HOME:-$HOME/.gstack}/projects/${SLUG:-unknown}/learnings.jsonl" +if [ -f "$_LEARN_FILE" ]; then + _LEARN_COUNT=$(wc -l < "$_LEARN_FILE" 2>/dev/null | tr -d ' ') + echo "LEARNINGS: $_LEARN_COUNT entries loaded" + if [ "$_LEARN_COUNT" -gt 5 ] 2>/dev/null; then + ~/.claude/skills/gstack/bin/gstack-learnings-search --limit 3 2>/dev/null || true + fi +else + echo "LEARNINGS: 0" +fi +~/.claude/skills/gstack/bin/gstack-timeline-log '{"skill":"autobuilder-loop","event":"started","branch":"'"$_BRANCH"'","session":"'"$_SESSION_ID"'"}' 2>/dev/null & +_HAS_ROUTING="no" +if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then + _HAS_ROUTING="yes" +fi +_ROUTING_DECLINED=$(~/.claude/skills/gstack/bin/gstack-config get routing_declined 2>/dev/null || echo "false") +echo "HAS_ROUTING: $_HAS_ROUTING" +echo "ROUTING_DECLINED: $_ROUTING_DECLINED" +_VENDORED="no" +if [ -d ".claude/skills/gstack" ] && [ ! -L ".claude/skills/gstack" ]; then + if [ -f ".claude/skills/gstack/VERSION" ] || [ -d ".claude/skills/gstack/.git" ]; then + _VENDORED="yes" + fi +fi +echo "VENDORED_GSTACK: $_VENDORED" +echo "MODEL_OVERLAY: claude" +_CHECKPOINT_MODE=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_mode 2>/dev/null || echo "explicit") +_CHECKPOINT_PUSH=$(~/.claude/skills/gstack/bin/gstack-config get checkpoint_push 2>/dev/null || echo "false") +echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE" +echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH" +# Plan-mode hint for skills like /spec that branch behavior on plan-mode state. +# Claude Code exposes plan mode via system reminders; we detect best-effort +# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and +# fall back to "inactive". Codex hosts and Claude execution mode both end up +# inactive, which is the safe default (defaults to file+execute pipeline). +if [ -n "${CLAUDE_PLAN_FILE:-}${GSTACK_PLAN_MODE_FORCE:-}" ]; then + export GSTACK_PLAN_MODE="active" +elif [ "${GSTACK_PLAN_MODE:-}" = "active" ]; then + export GSTACK_PLAN_MODE="active" +else + export GSTACK_PLAN_MODE="inactive" +fi +echo "GSTACK_PLAN_MODE: $GSTACK_PLAN_MODE" +[ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true +``` + +## Plan Mode Safe Operations + +In plan mode, allowed because they inform the plan: `$B`, `$D`, `codex exec`/`codex review`, writes to `~/.gstack/`, writes to the plan file, and `open` for generated artifacts. + +## Skill Invocation During Plan Mode + +If the user invokes a skill in plan mode, the skill takes precedence over generic plan mode behavior. **Treat the skill file as executable instructions, not reference.** Follow it step by step starting from Step 0; any AskUserQuestion the skill fires is the workflow operating within plan mode, not a violation of it — and a skill whose instructions resolve a question themselves (e.g. a plan-mode auto-select) may legitimately not ask it. AskUserQuestion (any variant — `mcp__*__AskUserQuestion` or native; see "AskUserQuestion Format → Tool resolution") satisfies plan mode's end-of-turn requirement. If AskUserQuestion is unavailable or a call fails, follow the AskUserQuestion Format failure fallback: `headless` → BLOCKED; `interactive` → the prose fallback (also satisfies end-of-turn). At a STOP point, stop immediately. Do not continue the workflow or call ExitPlanMode there. Commands marked "PLAN MODE EXCEPTION — ALWAYS RUN" execute. Call ExitPlanMode only after the skill workflow completes, or if the user tells you to cancel the skill or leave plan mode. + +## Preamble Section Index — shared sections, read on demand + +Heavy preamble guidance is carved into shared files under `~/.claude/skills/gstack/preamble/sections/` (one copy +for the whole skill suite). Read a file IN FULL the moment its trigger applies — +never act on its topic from memory. If that base doesn't exist on this machine +(vendored or non-standard install), resolve the same filename relative to this +skill file's own installed location instead — `../../preamble/sections/` from +a skill dir, or the gstack repo root's `preamble/sections/`. + +| When | Read | +|------|------| +| the preamble echo shows a pending onboarding flag — `LAKE_INTRO: no`, `TEL_PROMPTED: no`, `PROACTIVE_PROMPTED: no`, `ACTIVATED: no`, `FIRST_LOOP_SHOWN: no`, `HAS_ROUTING: no` (unless `ROUTING_DECLINED: true`), or `VENDORED_GSTACK: yes`. Skip entirely when `SPAWNED_SESSION: true`. | `~/.claude/skills/gstack/preamble/sections/onboarding.md` | +| before composing your FIRST AskUserQuestion or prose decision brief this run | `~/.claude/skills/gstack/preamble/sections/ask-user-questions.md` | +| the Artifacts Sync output shows `artifacts repo detected` or `ARTIFACTS_SYNC_PROMPT: needed` | `~/.claude/skills/gstack/preamble/sections/artifacts-sync.md` | + +If `PROACTIVE` is `"false"`, do not auto-invoke or proactively suggest skills. If a skill seems useful, ask: "I think /skillname might help here — want me to run it?" + +If `SKILL_PREFIX` is `"true"`, suggest/invoke `/gstack-*` names. Disk paths stay `~/.claude/skills/gstack/[skill-name]/SKILL.md`. + +If `UPDATE_CHECK` is `"false"`, skip the next two lines — the update-check binary emits nothing in that mode, so there is no `UPGRADE_AVAILABLE` / `JUST_UPGRADED` output to act on. + +If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). + +If output shows `JUST_UPGRADED `: print "Running gstack v{to} (just updated!)". If `SPAWNED_SESSION` is true, skip feature discovery. + +Feature discovery, max one prompt per session: +- Missing `~/.claude/skills/gstack/.feature-prompted-continuous-checkpoint`: AskUserQuestion for Continuous checkpoint auto-commits. If accepted, run `~/.claude/skills/gstack/bin/gstack-config set checkpoint_mode continuous`. Always touch marker. +- Missing `~/.claude/skills/gstack/.feature-prompted-model-overlay`: inform "Model overlays are active. MODEL_OVERLAY shows the patch." Always touch marker. + +After upgrade prompts, continue workflow. + +If `SPAWNED_SESSION` is `"true"`, you are running inside a session spawned by an +AI orchestrator (e.g., OpenClaw). In spawned sessions: +- Do NOT use AskUserQuestion for interactive prompts. Auto-choose the recommended option. +- Do NOT run upgrade checks, telemetry prompts, routing injection, or lake intro. +- Focus on completing the task and reporting results via prose output. +- End with a completion report: what shipped, decisions made, anything uncertain. + +## AskUserQuestion Format + +Every AskUserQuestion is a decision brief sent as tool_use, not prose (exceptions below). + +**Read-first rule:** before composing your FIRST AskUserQuestion or prose decision +brief this run, Read `~/.claude/skills/gstack/preamble/sections/ask-user-questions.md` in full — tool resolution +(Conductor/MCP variants), prose-fallback layout, split rules for 5+ options, and +CJK handling live there. The contract below is the always-loaded floor, not the +full spec. + +``` +D — +Project/branch/task: <1 short grounding sentence using _BRANCH> +ELI10: +Stakes if we pick wrong: +Recommendation: because +Completeness: A=X/10, B=Y/10 (or: Note: options differ in kind, not coverage — no completeness score) +Pros / cons: +A)