docs(01-01): complete doc-cascade plan
Plan 01-01 (Wave-0 doc cascade) complete. Six tasks landed atomically in commits125c032,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
This commit is contained in:
189
.planning/phases/01-stabilize-video-pipeline/01-01-SUMMARY.md
Normal file
189
.planning/phases/01-stabilize-video-pipeline/01-01-SUMMARY.md
Normal file
@@ -0,0 +1,189 @@
|
||||
---
|
||||
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*
|
||||
Reference in New Issue
Block a user