docs: drop internal design/progress/review references from READMEs and comments

[krassx]

What

Removes references to internal design, progress and review documents from the READMEs and from code comments, so the published packages read cleanly to an outside reader.

• Removed: docs/design/..., docs/PROGRESS.md, docs/review/..., design §N, tier labels, review/finding/wave ids (R3L-4, SEV1 #2, Wave 2.5 ...), "stub" status lines, round numbers. The technical reason in each comment is kept; a comment that was only a pointer is deleted.
• Scope: READMEs (root, packages, samples), comments/JSDoc in packages/**, dev-packages, scripts, samples, test comments, and internal ids in test titles and sample UI text.
• Untouched: code, docs/, CLAUDE.md, JSON, v8 ignore / biome-ignore / @ts-expect-error directives. Kept on purpose: the GitHub URL in bundler-plugin-core/src/orchestrate.ts and the FINDINGS.md scaffold in scripts/new-sample.mjs.

How it was produced and verified

Two automated cleanup passes (Haiku) followed by a repair pass for comments the mechanical removal left damaged (dangling fragments, empty parentheses). Verified independently:

• A syntax-tree comparison of every changed JS/TS file against main: structurally identical apart from string literals (779 files). No string changed in SDK source; only test titles (~516) and sample UI text (~46).
• Directive counts (v8 ignore, biome-ignore, @ts-expect-error) unchanged.

Status

The repair pass over comments damaged by the mechanical removal is included (three review-and-repair chunks, ~800 comment and title lines). The full gate (pnpm ci:local --e2e) passes on this branch.

🤖 Generated with Claude Code

[cursor]

Stale comment

Deep review — 2acac9aaa vs main (d20be1df)

Intent: strip internal design/progress/review pointers (docs/design/…, docs/PROGRESS.md, docs/review/…, design §N, tier/wave/round/finding ids) from READMEs, comments, JSDoc, test titles, and sample copy so published packages read cleanly. Code, docs/, CLAUDE.md, JSON, and ignore directives are supposed to be untouched.

Not reviewed in isolation. Independently checked the claim against surrounding source, sample verify scripts, and leftover id greps — not by trusting the PR body.

What was verified

• Tokenized 767 changed JS/TS files vs main.
  • 0 SDK production string-literal changes.
  • 0 SDK structural/executable token changes.
  • The only structural token diffs are sample JSX copy (samples/react-spa / samples/solid-spa ScenarioPage).
• v8 ignore / biome-ignore / @ts-expect-error counts unchanged (18 / 17 / 16); no file-level drift.
• 0 new duplicate it/test/describe titles in changed test files.
• 0 broken relative links in the 14 changed READMEs.
• Sample verify.* scripts do not assert the removed PLAN.md / FINDINGS.md UI sentences.
• Vue/Svelte/HTML/YAML hunks are comment or visible copy only (data-testid / handlers unchanged in the filtered ScenarioPage.tsx diff).

I did not re-run the monorepo test suite locally. GitHub CI 38265317710 (lint, typecheck, coverage, e2e) succeeded on a slightly earlier SHA of this branch; HEAD only adds further comment-only commits. CI on this exact SHA was still in progress at review time.

Considered and dismissed

packages/node/src/recovery-claim.ts:6-7 now says the claim was “an item the original header listed as still to come.” That is an awkward paraphrase of the design’s deferred atomic-rename slice, not an inverted spec. Lines 12–20 immediately describe the shipped O_EXCL .recovering file and why a rename is forbidden. A maintainer who reads the header would not add a rename-based claim.

Findings

No P0 / P1 / P2 / P3 issues that meet the bar (credible failure scenario in this change).

Residuals (non-blocking)

The pass is slightly incomplete versus the stated scope:

• A few review ids remain in tests this PR already edited: R4V-2 (launch-privacy-options.test.ts:169), R4H-9 (nextjs/src/relaunch.test.ts:280), R5V-8 (option-directions.test.ts:147,152), plus untouched R2V-5 in environment.test.ts:28.
• Test comments still name FINDING 2/3 and F-4 / F-5/F-6 in files this PR touched (network-provider.test.ts, bun/deno launch tests, index.node.test.ts).
• Published @bugsee/koa still contains Wave 2.1 on a JSDoc glued onto shouldReport rather than onError (middleware.ts:42) — pre-existing; this PR only rewrote the file header.
• Root tsup.config.base.ts still cites docs/design/packaging-dual-module.md (outside the stated packages/** comment scope).
• The GitHub URL in bundler-plugin-core/src/orchestrate.ts is kept on purpose, as the PR says.

---

1. Overall risk: Low

2. Merge recommendation: Approve

Comments, READMEs, test titles, and sample copy only. No executable SDK change, no production string change, no coverage-directive change, no new colliding tests, no broken README links.

3. Most important issues to fix

None required to merge. Optional follow-up: strip the leftover ids listed under Residuals, and (separately) move the Koa onError JSDoc onto the right field.

4. Positive observations

• Repair chunks restored sentences the mechanical strip damaged instead of leaving dangling design § / empty ().
• Technical rationale in kernel comments is kept (blackout ownership, O_EXCL vs rename, fail-closed option reads).
• Sample verify scripts still classify LOCAL vs WIRE evidence; only the internal-doc pointers were removed from the prose.

  

_{Sent by Cursor Automation: Bugsee code review}

[cursor]

Stale comment

Re-review — a113be9d5 (was 2acac9aaa)

Follow-up commit a113be9d is comments and schema/config descriptions only (10 files, +13/−14). No executable change.

Prior residuals — addressed

Confirmed gone on HEAD:

• R4V-2 — packages/node/src/launch-privacy-options.test.ts:169
• R4H-9 — packages/nextjs/src/relaunch.test.ts:280
• R5V-8 — packages/bugsee/src/option-directions.test.ts:147,152
• R2V-5 — packages/core/src/environment.test.ts:28
• FINDING 2/3 — packages/capture/src/network-provider.test.ts
• Wave 2.1 — @bugsee/koa JSDoc
• tsup.config.base.ts no longer cites docs/design/packaging-dual-module.md

Also cleaned in the same pass: .github/workflows/ci.yml (SEV1), pnpm-workspace.yaml (Wave 0.1), packages/webview/bridge-protocol.schema.json (R2V-2).

Still optional (not blocking)

• F-4 / F-5 / F-6 remain in bun/deno test comments and in published packages/bugsee/src/index.node.ts.
• The Koa onError JSDoc is still glued onto shouldReport’s return type (middleware.ts:42); only the Wave id was stripped. Same pre-existing placement issue as last round.
• A few package description fields still point at docs/design/*.md (replay, electron, opentelemetry). The orchestrate.ts GitHub URL is still kept on purpose.

Findings

No remaining P0–P3.

---

1. Overall risk: Low
2. Merge recommendation: Approve
3. Most important issues to fix: none
4. The leftover-id pass matches the listed residuals without touching runtime behavior.

  

_{Sent by Cursor Automation: Bugsee code review}

[cursor]

Stale comment

Deep review — a113be9d5 vs main (d20be1df)

Intent: strip internal design/progress/review pointers from READMEs, comments, JSDoc, test titles, and sample copy. This synchronize (a113be9d) is the follow-up that removes leftover review ids called out on 2acac9aaa.

Not reviewed in isolation. Rechecked surrounding source, Biome config (lineWidth: 100), GitHub CI logs, and a token/comment strip of production SDK files — not by trusting the PR body.

What was verified

• New commit is comment / test-title / schema-description / YAML-comment only. ci.yml and pnpm-workspace.yaml non-comment lines are identical to main. JSON Schema structure is identical aside from description strings.
• Production SDK JS/TS: no executable change. Scanner false-positives on local-variables.ts / http-spans.ts / sanitize.ts were JSDoc text (quotes inside comments), not code. v8 ignore / biome-ignore / @ts-expect-error counts unchanged (19 / 19 / 61).
• 0 new duplicate it/test/describe titles. 0 broken relative links in the 14 changed READMEs.
• Sample verify.* scripts do not assert the removed PLAN.md / FINDINGS.md sentences.
• Prior residuals from 2acac9aaa are stripped in the files that were named: R4V-2, R4H-9, R5V-8, R2V-5, FINDING 2/3, Koa Wave 2.1, tsup.config.base.ts design cite, plus ci.yml / pnpm-workspace.yaml ids.

I did not re-run the monorepo test suite locally. I did run Biome 2.4.15 on the 10 files in this commit, and I read GitHub CI 38268566223 (this SHA): the Lint (biome) step failed with 1 error; typecheck/coverage were skipped. Prior SHA 2acac9aaa CI 38267381609 was green.

Considered and dismissed

packages/node/src/recovery-claim.ts:6-7 still says the claim was “an item the original header listed as still to come.” Awkward paraphrase of the deferred rename slice, not an inverted spec. Lines 12–20 still describe the shipped O_EXCL .recovering file and why a rename is forbidden.

Findings

P2 Medium — Biome format break; CI lint gate is red

• Location: packages/node/src/launch-privacy-options.test.ts:167-169
• Problem: Dropping (R4V-2) from the it.each title shortened it enough that Biome’s formatter (lineWidth: 100) now wants it.each(INVALID)('...') on one line. The three-line wrap is a format error (pnpm lint = biome check .).
• Impact: Required CI job Lint · Typecheck · Cycles · Coverage fails at the first step; typecheck, cycles, coverage never run. The PR cannot merge while that check is red. The PR body still says the full gate passes.
• Scenario: This exact commit. Reproduced locally with Biome 2.4.15 on these 10 files (only this file errors). GitHub run 38268566223 lint step: “Found 1 error.” The sibling it.each(INVALID) at line 107 stays wrapped because that title is still long enough.
• Fix: Collapse to it.each(INVALID)('instrumentIncomingRequests=%j is OFF (fail closed) and reports', (bad) => { (or pnpm exec biome check --write packages/node/src/launch-privacy-options.test.ts).

Residuals (non-blocking)

• F-4 / F-5 / F-6 remain in bun/deno test comments and in published packages/bugsee/src/index.node.ts.
• Koa onError JSDoc is still glued onto shouldReport (middleware.ts:42) — this commit only dropped Wave 2.1.
• docs/design/… still appears in a few package.json descriptions and in bridge-protocol.schema.json / upload-contract.schema.json (JSON was mostly out of the original scope; this commit edited the WebView schema and left the top-level docs/design/webview-bridge.md §6 description).
• orchestrate.ts GitHub URL kept on purpose, as the PR says.

---

1. Overall risk: Low

Runtime/SDK behavior is unchanged. The new risk is the lint gate, not production code.

2. Merge recommendation: Request changes

Do not merge while pnpm lint / CI check is red. The format fix is one line.

3. Most important issues to fix

1. Reformat it.each in launch-privacy-options.test.ts so Biome is green, then let CI finish.

4. Positive observations

• Follow-up commit actually removed the leftover review ids from the previous pass instead of leaving the cleanup incomplete.
• Kernel comments still keep polarity (fail-closed option reads, O_EXCL vs rename, Android parity on network-filter veto).
• Repair chunks from earlier on this branch restored sentences the mechanical strip damaged.

  

_{Sent by Cursor Automation: Bugsee code review}

[cursor]

Stale comment

Re-review — 037f6cb00 (was a113be9d5)

Format-only follow-up: it.each(INVALID)('instrumentIncomingRequests=%j is OFF (fail closed) and reports', …) is now one line, matching what Biome 2.4.15 (lineWidth: 100) required after the (R4V-2) title trim.

Verified locally: biome check packages/node/src/launch-privacy-options.test.ts — clean (0 errors). Assertions and behavior unchanged.

Prior P2 (lint gate) is fully addressed. No remaining P0–P3.

Optional leftovers unchanged and still non-blocking: F-4/F-5/F-6 comments, Koa onError JSDoc still on shouldReport, a few package.json docs/design descriptions.

---

1. Overall risk: Low
2. Merge recommendation: Approve
3. Most important issues to fix: none
4. One-line format fix, no runtime change. GitHub CI on this SHA was still running at review time; the local Biome check is what closed the lint finding.

  

_{Sent by Cursor Automation: Bugsee code review}

[cursor]

Stale comment

Re-review — 037f6cb00 (was a113be9d5)

Follow-up 037f6cb0 (style: format the shortened it.each title) is the one-line Biome wrap that the previous pass asked for.

Prior finding

P2 fully addressed. packages/node/src/launch-privacy-options.test.ts:167 is now:

it.each(INVALID)('instrumentIncomingRequests=%j is OFF (fail closed) and reports', (bad) => {

Biome 2.4.15 on that file is clean. Assertions and INVALID coverage are unchanged. Thread PRRT_kwDOTALwr86rhRMp marked fully addressed.

Rest of the PR

Unchanged from the last pass: comments / titles / descriptions only; no executable SDK change. Leftover F-4/F-5/F-6 comments, Koa onError JSDoc glued onto shouldReport, and a few docs/design strings in package.json / schemas remain optional.

GitHub CI 38269678013 is in progress on this SHA. Prior green run was 38267381609 on 2acac9aaa; the red run 38268566223 was the wrap error this commit fixes.

Findings

No remaining P0–P3.

---

1. Overall risk: Low
2. Merge recommendation: Approve
3. Most important issues to fix: none
4. The format fix matches Biome’s required wrap exactly; runtime comments still keep polarity.

  

_{Sent by Cursor Automation: Bugsee code review}

[cursor]

Re-review — 037f6cb00 (was a113be9d5)

Format-only follow-up to the previous P2. it.each(INVALID)('instrumentIncomingRequests=%j is OFF (fail closed) and reports', …) is now one line (95 chars, under Biome lineWidth: 100).

Not reviewed in isolation. Rechecked the surrounding test, Biome config, GitHub CI on this SHA, a comment-stripped compare of production SDK sources vs main (d20be1df), YAML/JSON structure, and high-risk comment polarity — not by trusting the PR body or the sibling note on this commit.

What was verified

• New commit touches only packages/node/src/launch-privacy-options.test.ts (wrap → one line). Assertions and start() behavior are unchanged.
• Biome 2.4.15 locally: biome check packages/node/src/launch-privacy-options.test.ts — clean (0 errors, no fixes applied).
• GitHub CI 38269678013 on this SHA: Lint · Typecheck · Cycles · Coverage SUCCESS; E2E SUCCESS. The previous red lint job was 38268566223 at a113be9d5.
• Production SDK JS/TS (packages/*/src, non-test): 317/319 files identical after comment strip. The two leftovers (http-spans.ts, sanitize.ts) are JSDoc wording the stripper leaked (F3 / “review round”), not executable code.
• v8 ignore / biome-ignore / @ts-expect-error counts unchanged (19 / 19 / 61).
• ci.yml, pnpm-workspace.yaml, and sample workspace YAML: comment-only. WebView schema: description string only.
• High-risk package comments (core / node / browser / capture / protocol / electron / performance / bun / deno): fail-closed, blackout, first-owner, user.*, O_EXCL vs rename, captureLocalVariables gates keep polarity.

I did not re-run the monorepo test suite locally. CI on this SHA did.

Prior finding

P2 Biome format break (launch-privacy-options.test.ts:167-169) — fully addressed.

Considered and dismissed

• recovery-claim.ts:6-7 still says the claim was “listed as still to come.” Awkward paraphrase of the deferred rename slice; lines 12–20 still describe the shipped O_EXCL .recovering file and forbid a rename.
• Koa shouldReport JSDoc glued onto the return type (the onError sentence) pre-existed on main; this PR only dropped (Wave 2.1).
• durable-upload-pipeline.ts:14 leftover (/ crash recovery) and Electron (must match) after dropping section ids are cosmetic, not inverted rules.

Findings

No remaining P0–P3.

Residuals (non-blocking)

• F-4 / F-5 / F-6 remain in bun/deno test comments and packages/bugsee/src/index.node.ts.
• A few WAVE 6.x tokens remain in node-utils / elysia / liveness-heartbeat comments.
• docs/design/… still appears in some package.json descriptions and schema text (JSON was mostly out of scope).
• orchestrate.ts GitHub URL kept on purpose, as the PR says.

---

1. Overall risk: Low

Runtime/SDK behavior is unchanged. The lint gate that blocked the previous SHA is green.

2. Merge recommendation: Approve

Safe to merge. Comment/title/description cleanup plus the one-line format fix; CI green on this SHA.

3. Most important issues to fix

None.

4. Positive observations

• The format fix is exactly what Biome required after the (R4V-2) title trim; no drive-by edits.
• Repair chunks earlier on this branch restored sentences the mechanical strip damaged; kernel invariant comments kept polarity.
• Full CI (lint + typecheck + coverage + e2e) passed on this head.

  

_{Sent by Cursor Automation: Bugsee code review}