Documents the single-task Plan 03-04 closure end-to-end:
- A32 ships ~90 lines of best-effort RAM scaffolding per D-P3-04 +
RESEARCH Open Question 3 (host-side puppeteer.Page.metrics; no page-
side counterpart; no SAVE; no archive parse)
- Pitfall 2 mandatory diagnostic leads diagnostics array (T-03-04-01
Repudiation mitigation; three layers of operator-visible signal so
automation GREEN ≠ §10 #9 closure)
- UAT 32/32 → 33/33 GREEN; vitest 171/171 preserved; Tier-1
FORBIDDEN_HOOK_STRINGS unchanged at 12 (host-side API has no
production-bundle impact)
- Phase 4 inheritance path documented (per-target enumeration via
browser.targets() + createCDPSession + Performance.getMetrics for
SW + offscreen + harness page aggregate)
- Pre-existing parallel-vitest Tier-1-build-step race recurred once
(1/171); verified pre-existing across 03-02 + 03-03; not caused by
A32 changes; isolated re-run 13/13 GREEN
- Plan 03-05 wave dependency: VERIFICATION.md aggregator; will record
§10 #9 as `human_verification` regardless of A32 status
- Zero deviations: plan-spec verbatim implementation; the cleanest of
the four Wave-2/3/4 plans in Phase 3 by deviation count
Plan-checker iter-1 VERIFICATION PASSED with 1 cosmetic WARNING (Dimension 11
Research Resolution: Open Questions section heading lacked (RESOLVED) suffix
convention). Fixed inline: heading now reads "## Open Questions (RESOLVED)".
.plan-phase-preferences.md (created mid-/gsd-plan-phase first invocation to
preserve gate answers across the UI-SPEC detour) DELETED — purpose served;
this plan-phase invocation honored the saved research-first-light scope
brief.
state.record-session CLI bug recurred (status flipped to "completed" because
18/23 known plans done). Restored: status=ready_to_execute. percent: 78 is
correct now (5 Phase 3 plans counted; was 18/18=100 stale).
Phase 3 ready for execution: 5 plans validated, infrastructure inherited,
test baselines preserved.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Phase 3 is verification-only; /gsd-ui-phase 3 trigger on "page" keyword
is a false positive. UI-SPEC.md confirms no new user-facing UI surface
in scope; locks the Phase 1 design system (Lora + IBM Plex Sans + Loom
palette + Mokosh mark + tokens.css + 17 i18n keys) as read-only
inherited context; declares minimal probe-page conventions for
internal Puppeteer test fixtures (Plans 03-01..03-05 per D-P3-01).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
User invoked /gsd-plan-phase 3 and answered both gate questions before the
workflow correctly exited at the UI Design Contract gate (per workflow rule
that manual invocations cannot nested-Skill-spawn /gsd-ui-phase due to
AskUserQuestion-in-subcontext issue #1009).
Preferences saved at .plan-phase-preferences.md for the next plan-phase
invocation (after /gsd-ui-phase 3 produces UI-SPEC.md):
- UI gate: generate UI-SPEC.md first (chosen — most canonical; verification
caveat noted for /gsd-ui-phase to consider)
- Research gate: research first (light) — scope-limited to puppeteer.Page.metrics
+ rrweb alpha-pin status (NOT rrweb v2 upgrade implementation, NOT masking)
File auto-deletes when /gsd-plan-phase 3 honors these preferences.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Verifier returned human_needed with 4/5 truths VERIFIED (T1-T4) + T5 UNCERTAIN
because Plan 02-04 Task 4 contract literally typed checkpoint:human-verify gate=blocking
and the operator empirical "approved" ack wasn't on record.
T5 (operator clicks SAVE → ZIP produced in <5s with correct layout + Blob URL)
is OVERRIDDEN to VERIFIED based on:
1. User explicit delegation 2026-05-20: "why do i need to do all of this? It's on
you to test..." — established that automation covers what automation can cover.
2. New saved memory feedback-trust-harness-over-manual-uat.md (same session):
reserve operator empirical UAT for surfaces automation genuinely cannot verify
(brand judgment, ergonomics). For deep-pipeline Phase 2 work, every operator-
checklist surface IS harness-covered.
3. Harness assertion coverage of every step:
- (a) <5s latency → A25 empirical via Puppeteer
- (b) 5-entry archive layout → A28 set-equality
- (c) 8-field meta.json schema → A26 + tests/build/strict-meta-json-validation.test.ts
- (d) video playback → Phase 1 VERIFICATION.md empirical (D-13 unchanged)
- (e) blob: URL pattern → A24 empirical
4. Alpha distribution build covers real-world OS-archive-manager layer outside
in-session verification scope.
Plan 02-04 Task 4 was authored before the saved-memory principle was established;
the checkpoint contract reflects an older operating mode.
Status: passed (with 1 override applied; override_notes captured in frontmatter)
Score: 5/5
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
SUMMARY.md documents:
- 3 RED tests in tests/background/blob-url-download.test.ts flipped GREEN
(wire-format polarity guard, 6 MB latency + wire-format, revoke lifecycle).
- 6 files modified (3 prod source + 3 test files; +518 / -35 lines).
- Wire-format extension: 3 new PortMessageType variants on keepalivePort.
- Operator-facing improvement: archives >2 MB now download successfully
(was: silent failure with data:URL Network error).
- Rule 3 deviation: extended Plan 02-01 test helpers with the offscreen-side
CREATE_DOWNLOAD_URL → DOWNLOAD_URL → REVOKE_DOWNLOAD_URL round-trip
simulation pattern + capturedArchiveBytes bytes capture. This pattern
is reusable by Plan 02-03 and was anticipated in Plan 02-01 SUMMARY.
- Forward link: Plan 02-03 (meta.urls + tab-url-tracker) is unblocked;
Plan 02-04 (UAT harness A24+) is unblocked.
Verification:
- npx tsc --noEmit: clean
- npm run build: clean
- npm run build:test: clean
- tests/background/blob-url-download.test.ts: 3/3 GREEN
- Tier-1 FORBIDDEN_HOOK_STRINGS: 13/13 GREEN (unchanged)
- Full vitest: 163 passed / 8 failed (was 159 passed / 12 failed); +4 GREEN
net delta. 8 remaining RED are exactly Plan 02-03 territory.
Plan 02-01 Wave 0 RED gate closed. Three failing test files (16 it()
blocks total: 11 RED + 5 GREEN regression guards) pin the locked
decisions for Phase 2 ahead of Plans 02-02 + 02-03 implementation:
- blob-url-download.test.ts (3 RED) — D-P2-01 offscreen Blob URL
pipeline (closes audit P0-6: base64 data: URL → blob: URL).
- meta-json-urls-schema.test.ts (5 RED) — D-P2-02 meta.url → meta.urls
migration + F2 empty-tracker → urls:[] resolution.
- strict-meta-json-validation.test.ts (3 RED + 5 GREEN) — D-P2-03
strict 8-field schema validation with EXPECTED_KEYS pin including
planner-suggested `schemaVersion` 8th field.
Test count delta: 155 GREEN → 159 GREEN + 11 RED (+4 GREEN regression
guards, +11 RED test contracts). Vitest reporter:
Test Files 4 failed | 27 passed (31)
Tests 12 failed | 159 passed (171)
(12 failed = 3 + 5 + 3 RED from this plan + 1 pre-existing flaky
ffprobe test in webm-remux.test.ts — out of scope; documented in
SUMMARY.md Deferred Issues.)
Tier-1 grep gate: 13/13 GREEN preserved (this plan touches no
production code).
Planner-resolved tensions carried forward in SUMMARY.md:
- D-P2-03 'non-empty urls[]' vs CONTEXT.md permissive empty-array →
F2 resolved in favor of permissive (Test 3 of Task 3 relaxed).
- 8th field name `schemaVersion` → tentative planner pick;
Plan 02-03 implementer commits to schemaVersion: '2' const.
- tab-url-tracker module seam → planner-suggested name
`src/background/tab-url-tracker.ts` with getTabUrlsSeen() export.
- Plan claim 'ALL 8 fail' reconciled honestly: 3 RED + 5 GREEN
regression guards (timestamp/semver/totalEvents/buffer-seconds/
duration-minutes already match current 7-field shape).
Plan suggestions reconciled with reality:
- vitest env: 'node' not 'jsdom' (Node 24 has URL/Blob/performance
globals; jsdom not in devDeps). FileReader polyfill inline.
- Task 2 Test 1 source-text scan instead of tsc-compile-failure
(vitest.config.ts typecheck:{enabled:false}).
Per worktree-mode constraint: STATE.md, ROADMAP.md, REQUIREMENTS.md
NOT modified. The orchestrator owns those writes after all worktree
agents in Wave 0 complete.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Plan 01-12 closure SUMMARY landed at .planning/phases/01-stabilize-
video-pipeline/01-12-SUMMARY.md per the plan's <output> block + 01-13/
01-14 closure cadence. Mirrors the 01-13-SUMMARY frontmatter shape +
body sections (One-Liner / What Landed by Wave / Test Counts /
Deviations / Architectural Notes / Self-Check / Known Limitations /
Bridge to Phase 1 Closure).
Plan 01-12 design integration in one sentence: Lora self-hosted via
R2 designer substitution (Newsreader → Lora for Cyrillic coverage,
2026-05-19); src/shared/tokens.css canonical with 8 local @font-face
rules and zero remote URLs; 16 i18n keys across en + ru with parity;
branded Loom-mark icons replace Bug A placeholders; src/popup +
src/background migrated to chrome.i18n.getMessage with || <const>
fallback; UAT harness extended with A18-A22; pre-checkpoint bundle
gates established per feedback-pre-checkpoint-bundle-gates.md;
operator brand-fit ack received 2026-05-20 verbatim "all good".
Gate evidence (per Wave 7 pre-checkpoint 865d394 + this closure):
- vitest: 147/147 GREEN (re-verified on closure day; 26 test files)
- npm run test:uat: 21/21 GREEN (A0-A14 + A18-A22 + A23)
- npx tsc --noEmit: clean
- npm run build + npm run build:test: both clean
- MV3 CSP self-host: 0 googleapis / 0 https://fonts in dist/
- Tier-1 forbidden-strings: 13/13 GREEN (no new test-mode symbols)
- Operator brand-fit empirical ack 2026-05-20: "all good"
Closure linkage:
- Plan 01-12 functionally CLOSED (10/10 tasks; 7/7 waves)
- Plan 01-13 Task 9 (operator brand/design ack on loaded extension)
functionally CLOSED via this checkpoint (same operator + same
empirical surface coverage)
- Phase 1 design/brand contract CLOSED; only Plan 01-10 (welcome tab)
remains as the last Phase 1 functional plan
- Phase 2 inherits tokens.css + chrome.i18n patterns + OFL self-host
recipe + pre-checkpoint bundle gates as production conventions
Out-of-scope discovery (Wave 7 pre-checkpoint, logged for Phase 5
hardening, NOT a Plan 01-12 regression): setimmediate polyfill
`new Function` in SW chunk via vite-plugin-node-polyfills. Pre-existing
across Phase 1 history; logged at deferred-items.md. Suggested
follow-up: switch to a minimal Buffer shim or inline Buffer primitives
to drop the polyfill entirely.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Wave 7 pre-checkpoint bundle gates per feedback-pre-checkpoint-bundle-gates.md
revealed a pre-existing benign concern in the SW production bundle:
`vite-plugin-node-polyfills` (configured for Buffer in vite.config.ts)
bundles the upstream `setimmediate` package which contains a fallback
`new Function("" + I)` evaluated when setImmediate is called with a
non-function argument. Production source code does NOT call
setImmediate(string); the construct is dead at the runtime call-graph
level but Rollup conservatively preserves it (behind a runtime
typeof check, not a static dead branch).
Verified pre-existing across Phase 1 history via `git checkout main --
src/background/index.ts vite.config.ts && npm run build` — same
`new Function` count. Plan 01-12 made NO changes to the polyfill
configuration; this is logged for future tightening (Phase 5
hardening or a dedicated MV3 CSP audit plan), NOT for fix in this
plan per the deviation-rule SCOPE BOUNDARY.
All other pre-checkpoint bundle gates PASS:
- Tier-1 forbidden-strings: 13/13 GREEN (no new test-mode symbols)
- SW-bundle-import: 15/15 GREEN
- Node-globals (Buffer.*) in SW chunk: 0
- DOM-globals direct SW calls: none
- Manifest validation: PASS (__MSG_*__ + default_locale='en' +
16 i18n keys per locale; en+ru parity verified)
- Tokens.css MV3 CSP self-host: 0 googleapis / 0 https://fonts in dist/
- Icons rasterized: 8-bit RGBA at 406/784/1952 B
- vitest: 147/147 GREEN
- npm run test:uat: 21/21 GREEN (A1..A14 regression-free + A18..A22
new + A23 from 01-14)
- npx tsc --noEmit: clean
- npm run build + npm run build:test: clean
Surfacing Wave 7 operator brand-fit checkpoint to orchestrator next.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Plan-checker BLOCKER B-01-14-01: original plan's must_haves truth #5 understated
baseline regression risk. Adding `monitorTypeSurfaces: 'include'` as a sibling
constraint in src/offscreen/recorder.ts would have dropped vitest from 98/98
GREEN to 97/98 RED because tests/offscreen/display-surface-constraint.test.ts
Test 1 (line 223-226) uses strict deep-equality (toHaveBeenCalledWith, NOT
expect.objectContaining) on the constraints object — the test author's intent
(comment at line 221-222) is to catch future drops of ANY field.
Surgical revision per references/planner-revision.md (surgeon-not-architect):
- Frontmatter: add tests/offscreen/display-surface-constraint.test.ts to
files_modified list.
- must_haves truth #5: replace the "no existing unit test references the
constraints object" claim with a positive statement that the strict-deep-
equality assertion at lines 223-226 is updated in lockstep; preserves the
test author's "no objectContaining" discipline; explicit no-transient-RED
guarantee across commit boundaries.
- must_haves artifacts: new entry for the test file documenting the in-place
edit shape and the preserved test author comment.
- must_haves key_links: new link entry pairing the test assertion with the
source call site under the lockstep contract.
- Interfaces block: add the explicit "test-expectation lockstep update" code
fragment with the chosen key ordering (video → monitorTypeSurfaces → audio)
so the executor lands the source change and the test update with matching
shapes.
- Task 1 <files>: add tests/offscreen/display-surface-constraint.test.ts.
- Task 1 <action>: insert new Step 1b between Step 1 (source change) and
Step 2 (offscreen-hooks bridge) — full single-line edit spec at lines
223-226, preserve toHaveBeenCalledWith contract, preserve comment block,
same-commit guarantee.
- Task 1 verify-block expected outputs: explicitly call out that 98/98 GREEN
is preserved BECAUSE Step 1b lands (without it, 97/98 RED on the strict-
deep-equality assertion).
- Task 1 <done>: add line covering the lockstep test update + the no-transient-
RED guarantee.
- <verification> phase gate: add new check #2 (test-expectation lockstep)
between source-line correctness and A23 round-trip.
- <success_criteria>: add bullet for the lockstep test-expectation update.
- <output> SUMMARY contract: add "Revision linkage" bullet documenting that
the plan was revised once after the plan-checker flagged B-01-14-01.
Untouched (per checker's preserve-verbatim list):
- Source-line target (src/offscreen/recorder.ts:270)
- Harness wiring references (assertA3 686, driveA14 987, __mokoshHarness
1922+1942, drivers array 289-312, Total comment 354)
- FORBIDDEN_HOOK_STRINGS lockstep contract (both inventories)
- `_constraints` capture path
- Scope discipline (still 1 task, autonomous, no checkpoint)
- Research traceability (Plan 01-10 RESEARCH §5 + §Pitfall-5 + W3C §6.1)
- Threat model (T-01-14-04 mirrors Plan 01-13)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Plan 01-14 ships W3C Screen Capture monitorTypeSurfaces: 'include' (Chrome
119+) on the offscreen getDisplayMedia call, plus an A23 harness regression
assertion that verifies the constraint reaches the call site via the
existing offscreen-hooks bridge.
Scope: 1 source line + A23 wiring + Tier-1 grep gate inventory update
(lockstep extension of unit-gate + UAT A0 FORBIDDEN_HOOK_STRINGS).
Autonomous, single executor; no operator empirical checkpoint (UAT 16/16
harness coverage suffices per feedback-pre-checkpoint-bundle-gates.md).
Canonical sources:
- Plan 01-10 RESEARCH section 5 ('monitorTypeSurfaces: include' recommendation)
- Plan 01-10 RESEARCH section Pitfall-5 ('Misinterpreting displaySurface
as a hard constraint' — monitorTypeSurfaces is the picker-UI complement
to D-15's post-grant validation)
- W3C Screen Capture spec section 6.1 DisplayMediaStreamOptions
- developer.chrome.com/docs/web-platform/screen-sharing-controls
Decisions honored:
- D-01 (whole-desktop only via getDisplayMedia; reject window/tab) — the
new constraint is the picker-UI realization of D-01's intent.
- D-15 (post-grant displaySurface validation) — UNCHANGED; remains the
enforcement (this plan is belt-and-suspenders at the picker UI level).
Ceremony note: this plan replaces the prior AMENDMENT-A.md improvisation
path retired per 01-11-SUMMARY Architectural Notes. Canonical GSD ceremony
(plan -> checker -> executor -> SUMMARY).
Validations:
- gsd-sdk frontmatter.validate -> valid: true (8/8 required fields).
- gsd-sdk verify.plan-structure -> valid: true (1 task; hasFiles/hasAction
/hasVerify/hasDone all true).
- ROADMAP.md Phase 1 plans list extended with 01-14 entry.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Researcher (gsd-phase-researcher) returned HIGH-confidence verdicts on the
12-area brief from .continue-here.md:
Ask 1 (install-time auto-start): INFEASIBLE in unmanaged Chrome.
W3C Screen Capture spec §5.1 mandates transient user activation;
chrome.runtime.onInstalled confers none. Floor: 2 clicks
(toolbar/welcome-page → Share button on picker). Enterprise policy
ScreenCaptureWithoutGestureAllowedForOrigins exists (Chrome+Edge ≥ 123)
but only applies to managed-Chrome contexts with extension URL
whitelisted — does NOT apply to Load-Unpacked deployment; deferred-idea.
Ask 2 (auto-select desktop / skip picker): INFEASIBLE in unmanaged Chrome.
W3C spec mandates user MUST choose every time. displaySurface:'monitor'
is a hint (already applied src/offscreen/recorder.ts:270).
chooseDesktopMedia doesn't auto-accept on single-monitor setups AND
streamId not usable in MV3 offscreen documents (Chrome DevRel position).
Primary recommendation: KEEP Plan 01-10's current informational CTA
charter (commit 3a530c2 unchanged). Both architectures hit the same
2-click floor; informational CTA has lower maintenance surface AND
teaches operator where the toolbar icon lives (critical for day-2+
sessions).
Enhancement candidate (NOT required for 01-10): add
monitorTypeSurfaces:'include' (Chrome ≥ 119) to offscreen getDisplayMedia
constraints — single line, zero risk, removes tab/window panes from
picker entirely. Suggest as Plan 01-09 amendment OR mini-plan.
Open questions for orchestrator (3):
1. Confirm informational CTA charter (this research recommends YES)
2. Ship monitorTypeSurfaces:'include' as Plan 01-09 amendment vs deferred?
3. Are Repremium operators on Wayland Linux? (affects welcome-page copy)
File: .planning/phases/01-stabilize-video-pipeline/01-10-RESEARCH.md
(1092 lines; full W3C citations, Chromium issue links, prior art for
Loom/Screencastify/Veed/Awesome-Screenshot, ASCII flow diagrams,
edge-case enumeration for macOS/Wayland/incognito/managed-Chrome)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Plan 01-09 Amendment 3 (2026-05-19) — atomic documentation pass for
the save-does-not-stop-recording charter reversal.
Changes:
- .planning/phases/01-stabilize-video-pipeline/01-09-PLAN.md:
Amendment 3 block added above <success_criteria> (mirrors
Amendment 2 placement). Describes the reversed charter,
references the new debug record, points at the inverted
test file + harness A14.
- .planning/phases/01-stabilize-video-pipeline/01-13-SUMMARY.md:
"Subsequent Reversal (2026-05-19)" footer added. Notes that
npm run test:uat still 15/15 GREEN under the inverted A14
contract; vitest baseline preserved at 98 GREEN.
- .planning/STATE.md:
Plan 01-13 closure block extended with CHARTER REVERSAL bullet
citing the 4 commit SHAs (6ac23fd RED, 7645765 GREEN,
1baaf45 A14 invert, this commit docs).
- .planning/debug/resolved/01-09-save-stops-recording.md:
SUPERSEDED 2026-05-19 footer appended (audit trail; original
fix was technically correct against its charter, reversal is
UX iteration not technical defect).
- .planning/debug/resolved/01-09-save-does-not-stop-recording.md:
NEW debug record landed directly in resolved/ (no checkpoint
cycle — orchestrator-diagnosed reversal). Documents symptom,
charter clarification cycle, fix shape, RED→GREEN evidence
with commit SHAs + vitest/harness output, anti-regression
coverage at unit + E2E layers.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Lands the Wave 4 closure docs:
- 01-09-PLAN.md Amendment 2: harness PASS (npm run test:uat 14/14 GREEN at d793c9e)
now closes Plan 01-09 functional contract (original Task 5 steps 4, 5, 7-13, 15);
operator retains only step 1 (build) + step 14 (brand/design ack — Plan 01-13
Task 9 charter). Coverage map table pins each retired manual step to its
corresponding harness assertion (A1-A13).
- STATE.md sync: completed_plans 9->11, percent 92->~95, last_updated
2026-05-19T10:40:00Z; Current Position narrative replaced with Plan 01-13
landing summary + outstanding Phase 1 gates (Plan 01-13 Task 9 operator
checkpoint, Plan 01-10 welcome tab, Plan 01-12 design integration awaiting
designer reply).
Verification (post-edit, docs-only — no src/ touched):
- npm run test:uat: 14/14 GREEN at d793c9e baseline preserved
- npx vitest: 94/94 (the no-test-hooks-in-prod-bundle.test.ts default 5s timeout
flake is harness-side, not introduced by this commit; re-run with
--testTimeout=60000 passes)
- git status post-commit: clean
Followup: ROADMAP.md is missing entries for Plans 01-08 through 01-12 (these were
all added mid-phase across multiple sessions and the roadmap was never amended;
the Phase-1 Plans block lines 74-80 stops at 01-07 and the progress table line
238 shows the stale '7/7 Complete' count). Backfilling those entries is a
separate concern — out of scope for Plan 01-13 closure per plan-checker flag #4
(hold the line; do not inject). STATE.md notes the counter > total mismatch for
visibility.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes Plan 01-11 honestly per GSD spike-pivot pattern. Original
Approach A (Puppeteer sw.evaluate per RESEARCH §1+6) empirically
falsified across Wave 3 execution + feasibility research. Approach B
(extension-internal-page harness + offscreen synthetic stream) proven
via c647f61 prototype; full implementation moves to Plan 01-13.
What this commit does:
- ADDS 01-11-SUMMARY.md (spike-then-pivot framing per GSD artifact-
types.md PLAN→SUMMARY lifecycle; captures retained infrastructure,
falsified hypotheses, working prototype, bridge to 01-13)
- REVERTS frontmatter amendment block in 01-11-PLAN.md; replaces with
closed_as/pivoted_in/closure_note pointing at SUMMARY + 01-13
- DELETES 01-11-PLAN-AMENDMENT-A.md (improvised artifact type — not
recognized in GSD artifact-types.md; content folded into SUMMARY)
Lesson for orchestrator (captured in SUMMARY §Architectural Notes):
when a plan attempts an approach that proves infeasible, the right
move is honest SUMMARY + new plan, NOT in-place rewrite + AMENDMENT
artifact. The project's own pattern (01-08, 01-09, 01-10, 01-11
added mid-phase as new work surfaced) confirms add-new-plan-when-
scope-shifts is the established pattern.
Plan 01-09 closure via harness PASS NOT achieved by 01-11; still
requires operator UAT pending Plan 01-13 landing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Architectural pivot triggered by feasibility research prototype
(commit c647f61, A6 PASS 5/5 + Bug-B regression rewind verified).
Two empirical findings invalidate original architecture:
1. MV3 service workers BLOCK dynamic import. await import('test-hooks/
sw-hooks') in src/background/index.ts silently kills the SW —
chunk loads, await never resolves, no listeners register. Cited
Chromium es_modules.md + w3c/webextensions#212.
2. Puppeteer WebWorker.evaluate against MV3 SW only exposes chrome.
{loadTimes,csi} — not the extension chrome.* API surface.
The Wave 1 (cb1a729) SW-side hooks are fundamentally broken in test
builds (production unaffected — gated by __MOKOSH_UAT__ which is
false in prod). Executor must DELETE the SW-side dynamic import +
sw-hooks.ts entirely; offscreen-side hooks stay (offscreen IS a DOM
document; dynamic import works there).
Replacement (Verdict-A architecture, proven by prototype):
- Extension-internal harness page at chrome-extension://<id>/tests/
uat/extension-page-harness.html — privileged extension context
with FULL chrome.* API access
- Puppeteer drives the page via page.goto + page.evaluate
- For SW state: page calls chrome.runtime.sendMessage; SW responds
via production messaging
- For getDisplayMedia: offscreen-side installFakeDisplayMedia() patches
navigator.mediaDevices.getDisplayMedia → Canvas captureStream
synthetic MediaStream
A6 (Bug B regression catch) PROVEN. Industry-standard pattern (MetaMask,
eyeo, Chrome MV3 official testing docs all converge).
Effort remaining: ~7-10h subagent budget (Wave 0 + bonus debug-import
commits keep; Wave 1 hooks rewire 30min; Wave 2 scaffolding 1-2h;
Wave 3 13 more assertions 4-6h; Wave 4 closure 1h).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
13 research surfaces investigated per Plan 01-12 prompt. Key findings:
- BLOCKER §1: Newsreader has no Cyrillic glyphs (verified via Decision
Brief's own embedded @font-face subsets + Production Type README).
Russian display text in Newsreader will silently fall through to
serif fallback. Recommend §1 R1: add Cyrillic-capable OFL serif (PT
Serif / EB Garamond / Lora) to --mks-font-display stack.
- §3 + §4: Mark legibility at 16 px is VERIFIED OK. rsvg-convert
produces 406 / 784 / 1952 B PNGs at 16/48/128 — all clear Chrome
imageUtil floors. The 2x2 weave holds at 16 px.
- §10: 8 i18n strings extracted verbatim from Brief §02 (decoded via
Python JSON-decode of the bundler-template script). Recommended
__MSG_*__ key names + source-file mapping table included.
- §12: D-09 (smoke gating) is NEAR-NO-OP. smoke.sh is a standalone
bash script; nothing in src/ references it; dist/ carries no smoke
artifacts. Recommend documenting current state + adding optional
no-smoke-in-dist regression test.
- §13: tokens.css line 12 Google Fonts @import migration → 8 local
@font-face rules (Plex variable consolidation collapses the
estimated 12-18 down to 8).
All tooling verified installed on dev machine: rsvg-convert 2.60.0,
pyftsubset 4.63.0, woff2_compress, inkscape 1.4.4. No npm install
needed for execute-plan; only one-off font source TTF downloads.
7 assumptions logged for planner to surface (A1 default_locale, A2
popup DOM rework, A4 Cyrillic serif fallback are highest-impact).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Retires operator-as-assertion-library role from Plan 01-09 Task 5. Bug A
(notification icon API rejection) and Bug B (state-machine routing of
user-stopped-sharing) both escaped vitest unit coverage and cost ~4-6h of
operator UAT cycles in Phase 1. Plan 01-11 ships a Puppeteer-driven Node
harness with CDP attach to SW + offscreen contexts; the 14 assertions cover
the Plan 01-08/01-09 functional contract end-to-end.
Locked from research (RESEARCH §1-§11):
- Puppeteer 25.0.2 + tsx + node:assert/strict (no vitest browser mode)
- Two-bundle separation via vite.test.config.ts (mode 'test' + dist-test/)
- Hook gating: import.meta.env.MODE === 'test' + dynamic import (Vite
tree-shakes from production)
- Bug B trigger: track.dispatchEvent(new Event('ended')) — NOT track.stop()
(W3C spec + empirical probe7 — track.stop does NOT fire 'ended')
- Tier-1 grep gate (tests/background/no-test-hooks-in-prod-bundle.test.ts)
enforces zero __mokoshTest in production dist/
- Single browser, serial assertions, bail-on-first-failure (open question 4)
Wave structure (4 waves):
- Wave 0 (Task 1): puppeteer+tsx install, vite.test.config, build:test +
test:uat scripts, Tier-1 grep gate committed GREEN.
- Wave 1 (Task 2): gated SW + offscreen hooks at src/test-hooks/; production
bundle remains hook-free.
- Wave 2 (Task 3): harness scaffolding — tests/uat/lib/* + harness.test.ts
with assertion 0 wired GREEN + assertions 1-13 stubbed RED.
- Wave 3 (Tasks 4-7): wire 13 assertions in 4 logically-grouped bundles
(1-4 toolbar/displaySurface; 5-7 SAVE+BugB+ERROR; 8-10 BugA+icons+manifest;
11-13 buffer continuity + ffprobe + zip).
- Wave 4 (Tasks 8-9): amend Plan 01-09 Task 5 to redirect functional steps
to npm run test:uat; operator confirms brand/design.
Bug A + Bug B each have RED-on-regression canonical demos required in the
respective task's commit body — proves the harness CAN catch the regression,
not just passes under current conditions.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Original step 11 expected stop-sharing → ERROR badge + recovery
notification; under Bug B fix (b9eeeeb), user-stopped-sharing is
correctly routed → IDLE (badge OFF, no recovery notification) because
it's a deliberate lifecycle event, not an error.
Amendments:
- Step 11: badge OFF (not ERROR); no recovery notification; popup cleared
- Step 12: operator clicks toolbar directly (no notification to click)
- Step 14: failure-mode list updated to match new expectations
- Step 15 added: ERROR state coverage moved to separate genuine-error step
- Success criteria #3: split user-stopped-sharing (→ OFF) from genuine
errors (→ ERROR + recovery notification, preserved fallback)
See .planning/debug/resolved/01-09-recovery-flow.md for the debug record.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- D-14-remux WebM remux pipeline (ts-ebml parse + webm-muxer write)
replaces D-13 file-concat; single-EBML-headered output empirically
spans 29.954 s of 912 VP9 frames (matching the per-segment sum
301+300+311 with zero loss).
- All 5 RED unit tests in tests/background/webm-remux.test.ts flipped
GREEN; 2 SW-compat tests in webm-remux-deps.test.ts GREEN; 53 baseline
tests preserved. tsc exit 0. npm run build exit 0.
- mergeVideoSegments deleted from src/background/index.ts; only a
retirement comment naming Plan 01-08 D-14-remux remains.
EmptyVideoBufferError surface preserved (W-01 free-text rename only).
- CONTEXT.md amendment provenance verified intact (B-01 grep checks all
pass — no file mutation by this plan; the orchestrator landed the
amendment at plan-creation time in commit 2e499d7).
- 2 deviations documented (Rule 1: tsc-required codec field in
EncodedVideoChunkMetadata; Rule 3: stale comment cleanup in
decodeBufferSegments). No scope creep.
- Self-check: all 6 files + 4 task commits verified present.
- Task 5 = checkpoint:human-verify (operator regenerates
tests/fixtures/last_30sec.webm via ./smoke.sh, confirms Chrome + mpv
playback ~30 s, flips the 2 webm-playback duration tests GREEN).
