From e5e01d1a7fc8f44d630cf187de102049974a0f37 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Thu, 3 Sep 2026 01:19:19 +0000 Subject: [PATCH] docs: file the fork-port residual deferrals and document the Chromium bootstrap knobs TODOS.md gains the seven items the CEO and eng reviews of the fork-port residual plan deliberately deferred (shared ownership helper, config-key reader tripwire, "pre-existing" vocabulary, opt-in reply_language, .auth.json writer removal, the fork-derived-change rule for CONTRIBUTING, hook slug parity audit), each with rationale, and updates the two residual bullets for PR #2232 and PR #2233 with their dispositions. README's Troubleshooting section explains the best-effort Chromium bootstrap and its three knobs. Co-Authored-By: Claude Fable 5.1 --- README.md | 11 +++++++++++ TODOS.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 63 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 898d4b4d4..e42700602 100644 --- a/README.md +++ b/README.md @@ -533,6 +533,17 @@ On Windows without Developer Mode (MSYS2 / Git Bash), `setup` falls back to file **Claude says it can't see the skills?** Make sure your project's `CLAUDE.md` has a gstack section. Add this: ``` + +**Chromium install failed or hung during `./setup`?** The browser is best-effort: +setup records the reason, finishes registering every skill, and prints which +skills need Chromium (`/qa`, `/qa-only`, `/design-review`, `/browse`, make-pdf, +`/pair-agent`). Fix the cause and re-run `./setup`. Knobs: +`GSTACK_PLAYWRIGHT_INSTALL_TIMEOUT=` raises the download bound +(default 600) on slow links; `GSTACK_SKIP_PLAYWRIGHT=1` skips the Chromium +install entirely (CI, no-browser boxes); `GSTACK_CHROMIUM_NO_SANDBOX=1` is the +fix when Chromium installs but cannot launch because the host blocks +unprivileged user namespaces (Ubuntu 24.04+ AppArmor default, #2157). + ## 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, diff --git a/TODOS.md b/TODOS.md index 13c84ff67..58ed3fbac 100644 --- a/TODOS.md +++ b/TODOS.md @@ -2,6 +2,49 @@ ## NEXT PRIORITY +### P2: fork-port residual wave deferrals (filed at Wave A, 2026-09-03) + +Filed from the time-attack/gstack residual evaluation +(docs/designs/fork-port-residual-2026-09/REPORT.md) and its CEO + eng reviews. +Waves B–E2 of that plan are scheduled work, not TODOs; these are the items the +reviews deliberately deferred, each with rationale: + +- **Shared `_gstack_owned_link` helper** — the readlink ownership gate now + exists in three places (setup:1040 cleanup, bin/gstack-uninstall:204, + bin/gstack-relink `_entry_is_ours`). Extract one sourced helper so the + destructive-path guard cannot drift. Effort S. Priority P2. Depends on: none. +- **Config-key reader tripwire** — `transcript_ingest_mode=off` sat unread for + months while setup-gbrain advertised it. A free test that asserts every key + in bin/gstack-config's default table is read by at least one binary (or is + explicitly listed as prose-only) makes a dead consent switch a red test. + Effort S. Priority P2. Depends on: Wave E1 landing the reader. +- **"Pre-existing" failure vocabulary** — scripts/resolvers/preamble/ + generate-test-failure-triage.ts classifies from `git diff --name-only` and + never asks for a base-branch run. Rewrite T1 to verified/unverified with the + base branch's CI status (`gh run list --branch `) as default evidence + and a failing-files-only worktree run as an opt-in. Effort M → S with CC. + Priority P2. Depends on: none. +- **Opt-in `reply_language` config key** (#679) — render into the Writing + Style section only when set; keep identifiers and commands in English; add + the mixed-language tests the issue asked for. Not an always-on voice line + (community-PR guardrail). Effort S. Priority P3. +- **Remove the `~/.gstack/.auth.json` writer** — browser-manager.ts:638-640 + says the component-baked GBrowser extension reads it. Confirm GBrowser + bootstraps via `POST /extension-token`; if so, delete the writer plus a + migration that removes the orphaned credential file. Effort S. Priority P3. + Depends on: GBrowser source check. +- **CONTRIBUTING rule for fork-derived changes** — a change lifted from a fork + enters upstream only behind a test verified red on upstream HEAD first, with + credit to the original author; cherry-picks allowed when the fork commit + carries that test. 34 of 48 top fork candidates died under refutation; the + rule is what made the survivors safe. Effort S. Priority P2. +- **Hook slug-derivation parity audit** — question-preference-hook keyed + project prefs by cwd basename while the writer keyed by owner-repo (Wave E1 + fixes it via `slugFromCacheOnly`). Audit question-log-hook and every other + Claude hook that buckets by project for the same mismatch. Effort S. + Priority P3. Depends on: Wave E1. + + ### P1: ZeroEntropy sunset — gbrain's default embedding provider dies Sept 4, 2026 (#2365) **What:** ZeroEntropy (acquired by Notion) shuts down September 4, 2026. gbrain's @@ -3944,10 +3987,15 @@ globs (D). What remains, re-filed individually: darwin-skipped handoff tests in browse/test/handoff.test.ts — verify whether the v1.67 XProtect + rebrand work un-blocks them, then un-skip or fix. Effort S. -- Transcript trust/scope/source isolation (PR 2232, issue 2140) — needs the - never-double-store review. Effort M. +- Transcript trust/scope/source isolation (PR 2232, issue 2140) — split: + the `transcript_ingest_mode` reader (off skips, B → --all-history, unset + unchanged) ships in fork-port Wave E1; repo-scoping and `--source-id` + isolation still need the never-double-store review plus a gbrain flag + probe. Close the PR after E1 with a pointer here. Effort M. - Versionless-repo onboarding (#1474, issues 2343/2334) — the #2501 JSON version-path half landed; the no-version-file-at-all flow did not. - Playwright bootstrap abort/timeout absorbs (PRs 2233/2359, issues - 1902/2136) — partially superseded by v1.67's bounded bootstrap; verify - and close or extract the remainder. + 1902/2136) — DONE in fork-port Wave A: the install is best-effort and + bounded (GSTACK_PLAYWRIGHT_INSTALL_TIMEOUT, default 600s), lock contention + is a reason code, skills always register. Close #2233, #1900, #1901, #1902, + #913 with the receipt (test/setup-playwright-best-effort.test.ts).