---
phase: 01-stabilize-video-pipeline
plan: 01
subsystem: docs
tags: [doc-cascade, manifest, getDisplayMedia, port-keepalive, amendments]

# Dependency graph
requires: []
provides:
  - "PROJECT.md DEC-003 / DEC-010 rows amended to reflect getDisplayMedia + long-lived port"
  - "REQUIREMENTS.md REQ-video-ring-buffer rebound to getDisplayMedia (active-tab wording removed)"
  - "ROADMAP.md Phase 1 one-liner and Success Criterion #2 updated"
  - "intel/decisions.md DEC-003 and DEC-010 carry Amendment blocks"
  - "intel/constraints.md CON-tab-capture-binding + CON-service-worker-keepalive RETIRED; CON-display-capture-binding added"
  - "manifest.json permissions array swapped (tabCapture -> desktopCapture; alarms dropped)"
affects: [01-02, 01-03, 01-04, 01-05, 01-06, 01-07]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "Doc-cascade pattern: append Amendment / RETIRED blocks rather than replacing originals to preserve provenance"

key-files:
  created: []
  modified:
    - ".planning/intel/decisions.md"
    - ".planning/intel/constraints.md"
    - ".planning/PROJECT.md"
    - ".planning/REQUIREMENTS.md"
    - ".planning/ROADMAP.md"
    - "manifest.json"

key-decisions:
  - "Amendment blocks are APPENDED to original DEC-003 / DEC-010 (not replacing them) so the SPEC-derived provenance stays auditable"
  - "RETIRED markers preserve the original CON-tab-capture-binding and CON-service-worker-keepalive headings; the new CON-display-capture-binding is the consolidated replacement"
  - "Manifest drops the alarms permission entirely (not retained for future use) because Plan 05 deletes the alarms code path; surfaces shrink per T-1-02"

patterns-established:
  - "Doc cascade pattern: every code-touching phase that amends a SPEC-level decision SHOULD ship a Wave-0 doc plan first so downstream agents read a consistent baseline"
  - "Amendment block header convention: `## Amendment (Phase NN-name, YYYY-MM-DD)` with an `AMENDED-BY:` line citing the originating CONTEXT.md decision IDs"
  - "RETIRED block header convention: `### RETIRED (Phase NN-name, YYYY-MM-DD)` with a `RETIRED-BY:` line and a `Replacement:` pointer"

requirements-completed: [REQ-video-ring-buffer]

# Metrics
duration: 4min
completed: 2026-05-15
---

# Phase 1 Plan 01: Doc Cascade (D-A1..D-A6) Summary

**Wave-0 doc cascade: amended DEC-003 / DEC-010 + retired 2 constraints + added CON-display-capture-binding + swapped manifest permissions (tabCapture -> desktopCapture, dropped alarms) — six atomic commits, every code-touching plan in Phase 1 now reads a consistent baseline.**

## Performance

- **Duration:** ~4 min
- **Started:** 2026-05-15T15:12:55Z
- **Completed:** 2026-05-15T15:16:51Z
- **Tasks:** 6
- **Files modified:** 6

## Accomplishments
- Every SPEC-derived decision that this phase invalidates now carries an Amendment / RETIRED block in `intel/`, with a citation back to CONTEXT.md D-XX decision IDs — provenance preserved for future audit.
- `PROJECT.md`'s Key Decisions table and Constraints section are the canonical fast-scan surface; both reflect the new contract without requiring readers to drill into `intel/`.
- `REQUIREMENTS.md` REQ-video-ring-buffer is rebound to `getDisplayMedia` and the old "active-tab" wording is gone (grep guard returns 0 occurrences).
- `manifest.json` permissions array is in its final Phase-1 shape: `desktopCapture` replaces `tabCapture`, `alarms` is dropped, surface attack mitigated per T-1-02.

## Task Commits

Each task was committed atomically:

1. **Task 1: Amend intel/decisions.md DEC-003 and DEC-010 (D-A1)** — `125c032` (docs)
2. **Task 2: Amend intel/constraints.md — retire two, add one (D-A2)** — `fb88830` (docs)
3. **Task 3: Amend PROJECT.md Key Decisions table and Constraints section (D-A3)** — `b1ed2cb` (docs)
4. **Task 4: Amend REQUIREMENTS.md REQ-video-ring-buffer (D-A4)** — `597d967` (docs)
5. **Task 5: Amend ROADMAP.md Phase 1 description + Success Criterion #2 (D-A5)** — `32bc996` (docs)
6. **Task 6: Manifest permission swap — tabCapture -> desktopCapture, drop alarms (D-A6 / D-05)** — `4a5194e` (docs)

## Files Created/Modified

- `.planning/intel/decisions.md` — DEC-003 Amendment block appended after line 59; DEC-010 Amendment block appended after line 152. Both originals intact.
- `.planning/intel/constraints.md` — RETIRED block appended to CON-tab-capture-binding and CON-service-worker-keepalive; new CON-display-capture-binding block added after CON-buffer-storage.
- `.planning/PROJECT.md` — DEC-003 and DEC-010 rows rewritten in the Key Decisions table; two bullets in the Constraints section (SW lifecycle + tab capture binding) replaced with their amended equivalents.
- `.planning/REQUIREMENTS.md` — REQ-video-ring-buffer bullet rewritten; Traceability table row intact.
- `.planning/ROADMAP.md` — Phase 1 one-liner updated; Success Criterion #2 rewritten. Phases 2-5 untouched.
- `manifest.json` — `permissions` array: `tabCapture` -> `desktopCapture`, `alarms` removed. Everything else (manifest_version, name, version, description, host_permissions, background, content_scripts, action, icons) unchanged.

## Verbatim CON-display-capture-binding block (for downstream plans to quote)

```markdown
## CON-display-capture-binding

- Source: Phase 01 CONTEXT.md D-01..D-17, RESEARCH.md Patterns 1 & 5
- Type: api-contract
- Constraint: Video capture uses `navigator.mediaDevices.getDisplayMedia()` invoked once per session from the offscreen document with `chrome.offscreen.Reason.DISPLAY_MEDIA`. The Service Worker is kept alive by a long-lived `chrome.runtime.connect({ name: 'video-keepalive' })` port opened by the offscreen, with traffic in both directions at a minimum cadence of 25 s and pre-emptive reconnect at 290 s.
- Replaces: CON-tab-capture-binding (RETIRED), CON-service-worker-keepalive (RETIRED).
- UX trade-off: Chrome's permanent "Sharing your screen" indicator is shown while recording. SPEC §1 silent-operation property is intentionally relaxed.
```

## Acceptance gate confirmations

All six task-level grep gates pass, plus the plan-level verification block:

| Gate | Expected | Observed |
|------|----------|----------|
| `grep -c "AMENDED-BY: Phase 01" .planning/intel/decisions.md` | 2 | 2 |
| `grep -c "getDisplayMedia" .planning/intel/decisions.md` | >= 1 | 3 |
| `grep -c "port" .planning/intel/decisions.md` | >= 1 | 2 |
| `grep -c "RETIRED-BY: Phase 01" .planning/intel/constraints.md` | 2 | 2 |
| `grep -c "## CON-display-capture-binding" .planning/intel/constraints.md` | 1 | 1 |
| `grep -c "video-keepalive" .planning/intel/constraints.md` | >= 1 | 1 |
| `grep -c "AMENDED by Phase 01" .planning/PROJECT.md` | 2 | 2 |
| `grep -c "getDisplayMedia" .planning/PROJECT.md` | >= 1 | 2 |
| `grep -c "long-lived port" .planning/PROJECT.md` | >= 1 | 1 |
| `grep -c "RETIRED" .planning/PROJECT.md` | >= 1 | 1 |
| `grep -c "AMENDED in" .planning/REQUIREMENTS.md` | >= 1 | 1 |
| `grep -c "getDisplayMedia" .planning/REQUIREMENTS.md` | >= 1 | 1 |
| `grep -c "active-tab video" .planning/REQUIREMENTS.md` | 0 | 0 |
| `grep -c "REQ-video-ring-buffer" .planning/REQUIREMENTS.md` | >= 2 | 5 |
| `grep -c "AMENDED" .planning/ROADMAP.md` | >= 2 | 2 |
| `grep -c "tab re-attach" .planning/ROADMAP.md` | 0 | 1 (see deviation below) |
| `grep -c "getDisplayMedia" .planning/ROADMAP.md` | >= 1 | 2 |
| `grep -c '"tabCapture"' manifest.json` | 0 | 0 |
| `grep -c '"desktopCapture"' manifest.json` | 1 | 1 |
| `grep -c '"alarms"' manifest.json` | 0 | 0 |
| `grep -c '"offscreen"' manifest.json` | 1 | 1 |
| `grep -c '"activeTab"' manifest.json` | 1 | 1 |
| `node -e "require('./manifest.json')"` | exit 0 | exit 0 |
| `node -e "require('./.planning/config.json')"` | exit 0 | exit 0 |

## Decisions Made

- Appended Amendment / RETIRED blocks rather than replacing originals — preserves SPEC-citation provenance and keeps audit history intact.
- The new CON-display-capture-binding constraint consolidates both the capture-API contract AND the port-keepalive contract into a single block (rather than two parallel new constraints), per the verbatim plan instruction. The two RETIRED markers both point to this one replacement.
- Dropped the `alarms` permission entirely instead of leaving it as a no-op for future re-use — Plan 05 deletes the alarms code path, and an unused permission expands attack surface (T-1-02 mitigation).

## Deviations from Plan

### Self-inconsistency in Task 5 grep guard

**1. [Rule 3 - Blocking, self-resolved] ROADMAP.md "tab re-attach" grep guard contradicts verbatim instruction**
- **Found during:** Task 5 (ROADMAP.md amendment)
- **Issue:** The plan's Task 5 `<acceptance_criteria>` line states `grep -c "tab re-attach" .planning/ROADMAP.md` MUST return 0, but the verbatim replacement text the plan instructs me to write for Success Criterion #2 contains the phrase "no tab re-attach logic; AMENDED from the original wording" — so the new text the plan tells me to write itself contains the phrase the grep guard rejects.
- **Fix:** Followed the verbatim instruction (the explicit VERBATIM phrasing is the more specific instruction and the deliberate planner intent — the phrase is part of the audit trail recording that tab re-attach logic was removed). The OLD wording "the recorder re-attaches to the new active tab" IS removed (verified: `grep -c "recorder re-attaches" .planning/ROADMAP.md` returns 0). The substantive intent of the grep gate — "the old re-attach behaviour wording is gone" — is satisfied.
- **Files modified:** `.planning/ROADMAP.md` (Success Criterion #2)
- **Verification:** Old "the recorder re-attaches" wording removed (count 0); new amendment text preserved with "no tab re-attach" phrasing per VERBATIM plan instruction.
- **Committed in:** `32bc996` (Task 5 commit)

---

**Total deviations:** 1 documented inconsistency, self-resolved by honouring the more specific VERBATIM instruction.
**Impact on plan:** None on downstream plans. All other acceptance gates pass. Recommend the verifier / plan-checker note this for future doc-cascade plans (the grep guard wording should anticipate amendment self-references).

## Issues Encountered

- Initial third edit in Task 3 failed because the source PROJECT.md text said "20 s to keep it alive" while the plan's quoted source said "20 seconds to keep it alive". Resolved by reading the actual source bytes and matching them. No functional impact — the replaced bullet still becomes the AMENDED version regardless of the 20s vs 20 seconds wording in the original.

## User Setup Required

None — no external service configuration required. This is a pure doc-cascade plan with one JSON edit.

## Next Phase Readiness

- Every code-touching plan in Phase 1 (01-02 through 01-07) can now grep against:
  - `manifest.json` for `desktopCapture` / no `tabCapture` / no `alarms`
  - `PROJECT.md` for `AMENDED by Phase 01` in the DEC-003 / DEC-010 rows
  - `intel/decisions.md` for the `AMENDED-BY: Phase 01` blocks
  - `intel/constraints.md` for `CON-display-capture-binding` (the new canonical capture+keepalive contract)
  - `REQUIREMENTS.md` for the new `getDisplayMedia`-bound REQ-video-ring-buffer wording
  - `ROADMAP.md` for the amended Phase 1 description and Success Criterion #2
- Plan 01-02 (test infrastructure setup) is unblocked.
- No outstanding blockers from this plan.

## Self-Check: PASSED

All six task commits verified present in `git log`:
- `125c032` (Task 1: decisions.md)
- `fb88830` (Task 2: constraints.md)
- `b1ed2cb` (Task 3: PROJECT.md)
- `597d967` (Task 4: REQUIREMENTS.md)
- `32bc996` (Task 5: ROADMAP.md)
- `4a5194e` (Task 6: manifest.json)

All six modified files present on disk; all plan-level verification grep gates and JSON validity checks pass (see acceptance gate table above).

---
*Phase: 01-stabilize-video-pipeline*
*Completed: 2026-05-15*