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 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-09-03 01:19:19 +00:00
co-authored by Claude Fable 5.1
parent 18d829fdbc
commit e5e01d1a7f
2 changed files with 63 additions and 4 deletions
+11
View File
@@ -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=<seconds>` 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,
+52 -4
View File
@@ -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 BE2 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 <base>`) 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).