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).
Plans cover the post-D-13 architecture and the auto-start UX charter
expansion that landed during 2026-05-16 UAT:
- Plan 01-08 — WebM remux via ts-ebml@3.0.2 + webm-muxer@5.1.4. Replaces
the broken file-concat in mergeVideoSegments with a real single-EBML
remux. Drives the 2 RED tests in tests/offscreen/webm-playback.test.ts
to GREEN. Regenerates the canonical fixture against the remuxer.
5 tasks (4 TDD + 1 operator empirical checkpoint), wave 1.
- Plan 01-09 — Whole-desktop constraint (displaySurface:'monitor',
cursor:'always') + post-grant validation, chrome.action.onClicked
direct toolbar invocation, chrome.action badge state machine
(REC/OFF/ERROR), chrome.runtime.onStartup notification + recovery
notification on onUserStoppedSharing, popup scoped to SAVE-only.
17 new test assertions across 4 test files. smoke.sh updated to
auto-select an entire screen. 5 tasks (4 TDD + 1 operator empirical
checkpoint), wave 2 (depends on 01-08).
- Plan 01-10 — chrome.runtime.onInstalled welcome tab on first install
via chrome.storage.local guard; vanilla welcome.html/ts/css bundle
with single "Начать запись" button consuming install-time activation.
Uses centralized Logger pattern. 4 tasks (3 TDD + 1 operator empirical
checkpoint), wave 3 (depends on 01-09).
CONTEXT.md amendment block appended with 4 disambiguated decisions:
- D-14-remux: WebM remux supersedes D-13 file-concat
- D-15-display-surface: whole-desktop + cursor visibility lifted from
Phase 5 deferral
- D-16-toolbar: toolbar onClicked + popup SAVE-only + badge state
machine + onStartup/recovery notifications
- D-17-onboarding: welcome tab on first install (distinct from
D-17-port-lifecycle from Option C)
The earlier D-17 port-lifecycle heading also renamed to hyphenated
form for cross-ref consistency.
Plan-check loop: 3 iterations (initial + 2 revisions). Iteration 1
surfaced 11 findings (2 BLOCKER + 6 WARNING + 3 INFO); all addressed
via revision iter 1 with checker-recommended fixes. Iteration 2
surfaced 3 derivative regressions (literal-string grep anchors from
the iter-1 fixes did not match live CONTEXT.md); all addressed in iter
2 with empirically-validated literals. Iteration 3 PASSED clean.
Validation: gsd-sdk frontmatter.validate + verify.plan-structure both
return valid=True for all 3 plans. Plan 01-08 Task 4 verify-chain
grep tested end-to-end against live CONTEXT.md (exit 0).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two doc updates closing the debug session per the resolved pattern this
phase has established (cf. resolved/d12-blob-port-transfer-fails.md and
resolved/webm-playback-freeze.md):
1. **Move debug session to resolved/** with the Resolution section
filled in (root_cause, fix, verification, files_changed). Status
flipped tdd_red_confirmed -> resolved. Original investigation
notes + bisect results + Option C strategy spec all preserved
in-place — the file is the full provenance trail.
2. **Amend 01-CONTEXT.md D-17** with the new port lifecycle commitments.
Append-only (D-17 itself untouched) per the doc cascade rule
established earlier this phase ("amendments append, do not replace,
to preserve SPEC provenance"). The amendment narrates:
- What was Claude's-discretion at Phase 1 plan time has been
specified by Option C.
- The 290 s pre-emptive setTimeout reconnect (Pitfall 4) is RETIRED.
- The architectural commitments added: PING/PONG health probe,
request-id'd REQUEST_BUFFER/BUFFER, SW retry on port replacement,
outer 10 s hard-timeout, operator-visible EmptyVideoBufferError
surface.
- The 4 pinning contracts added (port-health-probe,
request-id-protocol, port-lifecycle-continuous, plus the
refactored port-reconnect-race).
Suite remains 11 files / 53 tests, all GREEN. Quality gates intact.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Plan 05 closes: src/background/index.ts is now a pure coordinator with
zero video-buffer state, T-1-04 mitigations on both onConnect and
onMessage, OFFSCREEN_READY handshake, port-based buffer fetch via
'video-keepalive' port, IDB orphan cleanup on install, and chrome.offscreen.hasDocument()
re-sync on SW respawn (audit P1 #8). 9/9 vitest tests still green;
tsc clean; no as any / @ts-ignore.
REQ-video-ring-buffer stays pending — Plan 07's ffprobe gate owns the
final completion marker.
- Add 01-03-SUMMARY.md documenting RED -> GREEN gate (Plan 02 tests now
pass), 3 Rule-3 auto-fixes (OffscreenLogger inline, defensive
bootstrap, SW dead-code removal), and Plan 04 / 05 handoff notes.
- Update STATE.md: advance plan counter to 4 of 7 (43%), append
metrics + 3 execution decisions, record session.
- Update ROADMAP.md: mark Plan 01-03 [x] complete.
REQ-video-ring-buffer remains NOT complete — still pending Plans 04
(port keepalive) and 07 (ffprobe acceptance gate).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Plan 01-01 (Wave-0 doc cascade) complete. Six tasks landed atomically
in commits 125c032, fb88830, b1ed2cb, 597d967, 32bc996, 4a5194e. Every
code-touching plan in Phase 1 (01-02..01-07) now reads a consistent
baseline: getDisplayMedia replaces tabCapture in DEC-003; long-lived
port replaces alarms in DEC-010; manifest.json carries the final
Phase-1 permissions set (desktopCapture, activeTab, downloads,
scripting, storage, offscreen).
SUMMARY: .planning/phases/01-stabilize-video-pipeline/01-01-SUMMARY.md
Renames "## Open Questions" header to "## Open Questions (RESOLVED)" and
adds inline RESOLVED markers to each of the three questions:
- Q1 (MediaRecorder timeslice cluster alignment) → D-12 ffprobe gate
(Plan 03 Task 2 + Plan 07 Task 1) + D-13 fallback (pre-staged skeleton
in src/offscreen/recorder.ts per Plan 03)
- Q2 (5-minute port lifetime cap) → Plan 04's 290 s pre-emptive reconnect
plus synchronous onDisconnect → connectPort reconnect path
- Q3 (crxjs path-emit behavior) → Plan 06 Task 2 runtime verification +
conditional src/background/index.ts edit
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two changes:
1. wave: 3 → 6 (cascade: max(wave(05)=4, wave(06)=5)+1 = 6).
2. Task 1 <automated> verify now prefixes the ffprobe invocation with
test -f tests/fixtures/last_30sec.webm && which ffprobe so the gate
fails fast with a clear signal if the human checkpoint never produced
the fixture (instead of ffprobe blowing up with a cryptic file-not-found).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three changes to resolve the blocker:
1. depends_on: ["03"] → ["03", "05"] — Plan 06 Task 2 conditionally edits
src/background/index.ts which Plan 05 writes; the original wave 2
collocation with Plan 05 was a same-wave file conflict.
2. wave: 2 → 5 (cascade: max(wave(03)=2, wave(05)=4)+1 = 5).
3. files_modified gains src/background/index.ts (Task 2 path-adjustment
edit is now declared in frontmatter so the executor sees the contract).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Plan 05 depends_on: ["03", "04"], so wave must be max(2, 3)+1 = 4, not 2
(cascade from Plan 04 wave change).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two changes:
1. wave: 1 → 2 (cascade after Plan 02 wave fix)
2. OffscreenLogger: ...args: any[] → ...args: unknown[] for strict-mode
hygiene. Existing Logger / ContentLogger are left on the legacy any[]
pattern (refactoring is out of Phase 1 scope) — divergence documented
via style_divergence_note frontmatter field.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Documents that all 6 tasks are doc-text-only edits with no TypeScript
compilation — cognitive load is substantially lower than code plans of
equal task count. Avoids fragmenting the atomic doc-cascade by splitting
into 01-01a / 01-01b.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Researched Chrome MV3 offscreen + DISPLAY_MEDIA, MediaRecorder cluster
alignment, SW port keepalive, crxjs offscreen entry, ffprobe verification.
Identified the D-12/D-13 fallback hinge: timeslice=2000ms does NOT force
keyframe alignment (Chrome kf_max_dist=100); Pattern 2 (age-trim) may need
to escalate to Pattern 3 (restart-segments) if ffprobe rejects.
Architecture verified against two in-the-wild production extensions
(Proscreen-S3, meeting_mate) using the exact CONTEXT.md D-01..D-05 path.
The OFFSCREEN_READY handshake (audit P1 #12) and long-lived port keepalive
(audit P1 #8) are wired together. .planning/phases/01-stabilize-video-pipeline/01-RESEARCH.md
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
