From b0ede5a67bf2fcd63d8d89489328aaa6c8a51434 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sat, 15 Aug 2026 08:01:39 -0700 Subject: [PATCH] docs: update project documentation for v1.65.0.0 README gains the two wave-2 CLIs (gstack-code-intelligence, gstack-verify-gate) in the standalone-binaries table, BROWSER.md documents BROWSE_PERSIST_STATE next to manual state save/load, CONTRIBUTING's CI section lists the new supply-chain gates, and CLAUDE.md's project tree reflects lib/code-intelligence/ and the added workflows. Co-Authored-By: Claude Fable 5 --- BROWSER.md | 12 ++++++++++++ CLAUDE.md | 4 ++-- CONTRIBUTING.md | 9 +++++++++ README.md | 2 ++ 4 files changed, 25 insertions(+), 2 deletions(-) diff --git a/BROWSER.md b/BROWSER.md index fde16b45e..d9937de2f 100644 --- a/BROWSER.md +++ b/BROWSER.md @@ -1095,6 +1095,18 @@ $B state load my-session # restore In-memory `load-html` content is intentionally NOT persisted (avoid leaking secrets to disk). +Manual save/load is one-shot. For state that survives daemon restarts +automatically, opt in with `BROWSE_PERSIST_STATE=1` in the daemon's +environment: the headless daemon snapshots cookies + per-tab +URL/localStorage/sessionStorage to `/session-state.json` (0600, +atomic writes) every 30 seconds and at clean shutdown, then restores it off +the boot path on the next launch. Default OFF — cookies on disk are a real +cost, so the user opts in. Headless only (headed mode's persistent Chromium +profile already owns its state). Loaded HTML and tab ownership are never +persisted, cookies for localhost, `.internal`, and cloud-metadata addresses +are dropped on restore, and a corrupt snapshot is quarantined to +`session-state.json.corrupt` so persistence can never block a launch. + ### Watch ```bash diff --git a/CLAUDE.md b/CLAUDE.md index 461914a1d..7e970d810 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -158,11 +158,11 @@ gstack/ │ ├── test/ # Integration tests │ └── dist/ # Compiled binary ├── extension/ # Chrome extension (side panel + activity feed + CSS inspector) -├── lib/ # Shared libraries (worktree.ts, egress-receipt.ts, context-bill.ts, redact-engine.ts) +├── lib/ # Shared libraries (worktree.ts, egress-receipt.ts, context-bill.ts, redact-engine.ts, code-intelligence/) ├── docs/designs/ # Design documents ├── setup-deploy/ # /setup-deploy skill (one-time deploy config) ├── .github/ # CI workflows + Docker image -│ ├── workflows/ # evals.yml (E2E on Ubicloud), skill-docs.yml, actionlint.yml +│ ├── workflows/ # evals.yml (E2E on Ubicloud), quality-gate.yml (secret scan), dependency-review.yml, osv-scanner.yml, skill-docs.yml, actionlint.yml │ └── docker/ # Dockerfile.ci (pre-baked toolchain + Playwright/Chromium) ├── contrib/ # Contributor-only tools (never installed for users) │ └── add-host/ # /gstack-contrib-add-host skill diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99aeb8673..5baf4692f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -271,6 +271,15 @@ Each dimension is scored 1-5. Threshold: every dimension must score **≥ 4**. T A GitHub Action (`.github/workflows/skill-docs.yml`) runs `bun run gen:skill-docs --dry-run` on every push and PR. If the generated SKILL.md files differ from what's committed, CI fails. This catches stale docs before they merge. +Supply-chain gates run alongside it: + +- **Quality gate** (`.github/workflows/quality-gate.yml`, every PR and push) — scans the diff's added lines for credentials using gstack's own redact engine (`.github/scripts/gate-secret-scan.mjs`). HIGH findings fail the job; MEDIUM findings surface as an advisory count. Fails closed if the scan can't produce a report. Also gates critical dependency advisories and runs ShellCheck on the setup/build boundaries. +- **Dependency review** (`.github/workflows/dependency-review.yml`) — reviews dependency changes on PRs that touch lockfiles. +- **OSV scanner** (`.github/workflows/osv-scanner.yml`) — weekly vulnerability scan against the OSV database (config in `.osv-scanner.toml`). +- **Dependabot** (`.github/dependabot.yml`) — grouped dependency update PRs. + +All third-party actions are pinned to commit SHAs. The PR template (`.github/PULL_REQUEST_TEMPLATE.md`) asks for evidence — tests run, eval output — not promises. + Tests run against the browse binary directly — they don't require dev mode. ## Editing SKILL.md files diff --git a/README.md b/README.md index 9ef4b0851..a7c9a0ece 100644 --- a/README.md +++ b/README.md @@ -245,6 +245,8 @@ Beyond the slash-command skills, gstack ships standalone CLIs for workflows that | `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-code-intelligence` | **Code-intelligence provider picker** — wraps GBrain, Sourcebot, and Graphify behind one interface: `options`/`status` to see what's available, `select` to pick one, `index`/`search` to use it. Makes a one-time indexing offer on large repos (1,000+ tracked files; a decline is persisted). Non-local providers refuse to index until you record per-repo consent (`consent yes\|no`), the per-repo trust policy's deny and read-only tiers veto write-class operations regardless of consent, and every off-machine send writes an egress receipt. Fully optional — with nothing selected, gstack falls back to grep. | +| `gstack-verify-gate` | **Verification stop hook (opt-in)** — blocks a Claude Code turn from ending until the project's declared verify command passes. Declare it on one line in CLAUDE.md: ``. Hooks bypass the permission system, so a declared command never runs until you trust it once per repo (`gstack-verify-gate --trust`); editing the command invalidates trust until re-granted, and every grant is audit-logged. Remove with `gstack-settings-hook remove-source --source verify-gate`. | | `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. |