docs: bootstrap .planning/ via /gsd-ingest-docs (2 docs) /home/parf/projects/work/repremium/.planning/PROJECT.md /home/parf/projects/work/repremium/.planning/REQUIREMENTS.md /home/parf/projects/work/repremium/.planning/ROADMAP.md /home/parf/projects/work/repremium/.planning/STATE.md /home/parf/projects/work/repremium/.planning/intel /home/parf/projects/work/repremium/.planning/INGEST-CONFLICTS.md /home/parf/projects/work/repremium/.ingest-manifest.yaml
This commit is contained in:
155
.planning/PROJECT.md
Normal file
155
.planning/PROJECT.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# Mokosh
|
||||
|
||||
## What This Is
|
||||
|
||||
Mokosh is a Chrome Manifest V3 browser extension that silently and continuously
|
||||
records an operator's browser session — the last 30 seconds of active-tab video,
|
||||
the last 10 minutes of DOM events (via rrweb), and the last 10 minutes of user
|
||||
and runtime events — and, on a single button press, packages everything plus a
|
||||
screenshot into a self-contained ZIP delivered to the user's "Downloads" folder
|
||||
for handoff to support.
|
||||
|
||||
The name is taken from Mokosh (Мокошь), the Slavic goddess of fate and weaving:
|
||||
each operator session is a thread she weaves into the archive.
|
||||
|
||||
## Core Value
|
||||
|
||||
When an operator hits a bug, one click MUST produce a self-contained archive
|
||||
that lets support reproduce what happened — in under five seconds, with no
|
||||
server involved, and with the operator's passwords never appearing in the
|
||||
output.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Validated
|
||||
|
||||
<!-- Shipped and confirmed valuable. -->
|
||||
|
||||
(None yet — Phase 1 of the SPEC ships from a partially-broken first attempt;
|
||||
nothing is validated until SPEC §10 acceptance passes.)
|
||||
|
||||
### Active
|
||||
|
||||
<!-- Current scope. Building toward these. See REQUIREMENTS.md for IDs. -->
|
||||
|
||||
- [ ] Continuous 30 s active-tab video ring buffer (REQ-video-ring-buffer)
|
||||
- [ ] 10 min / 5 000-event rrweb DOM buffer with sensitive masking (REQ-rrweb-dom-buffer)
|
||||
- [ ] 10 min user/runtime event log with password filtering (REQ-user-event-log)
|
||||
- [ ] One-shot screenshot at export time (REQ-screenshot-on-export)
|
||||
- [ ] Russian-language popup with idle → "Сохраняю..." → "Готово! ✓" state machine (REQ-popup-ui)
|
||||
- [ ] ZIP archive layout `session_report_YYYY-MM-DD_HH-MM-SS.zip` (REQ-archive-layout)
|
||||
- [ ] `meta.json` schema (REQ-meta-json-schema)
|
||||
- [ ] Exact manifest permission set per SPEC §7 (REQ-manifest-permissions)
|
||||
- [ ] Click-to-download latency < 5 s (REQ-archive-export-latency)
|
||||
- [ ] Passwords never appear in rrweb snapshots or event log (REQ-password-confidentiality)
|
||||
- [ ] Extension installs unpacked into Chrome without errors (REQ-install-clean)
|
||||
|
||||
### Out of Scope
|
||||
|
||||
<!-- Explicit boundaries. Includes reasoning to prevent re-adding. -->
|
||||
|
||||
- Server upload of captured data — SPEC §9; reserved for Phase 2.
|
||||
- AI-driven diagnostics — SPEC §9; reserved for Phase 2.
|
||||
- Automatic ticket creation — SPEC §9; reserved for Phase 2.
|
||||
- Analytics dashboard — SPEC §9; reserved for Phase 2.
|
||||
- Audio recording — SPEC §9; reserved for Phase 2.
|
||||
- Persisting rolling buffers to `chrome.storage` / IndexedDB — CON-buffer-storage;
|
||||
buffers are in-memory only in Phase 1.
|
||||
|
||||
## Context
|
||||
|
||||
- **Source documents:** Russian-authored SPEC (`Тз расширение фаза1.md`) and a
|
||||
Russian-authored README. All user-facing UI strings ("Сохранить отчёт об
|
||||
ошибке", "Последние 30 сек видео + 10 мин лога", "Сохраняю...", "Готово! ✓")
|
||||
are part of the contract and MUST be preserved verbatim. Section identifiers
|
||||
and code use Latin script.
|
||||
- **Codebase state:** A partially-broken first attempt at the SPEC already
|
||||
exists under `src/` (background service worker, content script, popup) and
|
||||
`offscreen/`. An external audit identified 7 P0 defects that prevent SPEC §10
|
||||
acceptance. Phase 1 of this roadmap is remediation against the SPEC, not
|
||||
greenfield. See ROADMAP.md.
|
||||
- **Operator context (SPEC §1):** Operators work inside a browser and
|
||||
periodically make mistakes that are hard to diagnose after the fact. The
|
||||
extension runs silently in the background; the operator only interacts with
|
||||
it when they need to file a report.
|
||||
- **Build toolchain (DOC-only):** Vite + the `crxjs` plugin in TypeScript. The
|
||||
SPEC does not prescribe a build tool, so this is auto-overridable by a future
|
||||
ADR/SPEC.
|
||||
|
||||
## Constraints
|
||||
|
||||
- **Performance**: Click-to-archive-on-disk < 5 s (CON-archive-export-latency,
|
||||
SPEC §10 #6) — drives synchronous Blob assembly and avoidance of base64 data
|
||||
URLs.
|
||||
- **Memory**: Background RAM ceiling 50 MB (CON-ram-ceiling, SPEC §10 #9).
|
||||
Expected steady-state is ~3–10 MB; the ceiling is a hard upper bound, not a
|
||||
target.
|
||||
- **Video format**: `video/webm; codecs=vp9` @ 400 000 bps, `MediaRecorder`
|
||||
timeslice 2000 ms, single continuous recorder (CON-video-codec). The first
|
||||
chunk (WebM header) MUST be retained indefinitely (CON-webm-header-retention,
|
||||
DEC-009) — without it, the assembled file is not playable.
|
||||
- **Buffer windows**: Video 30 s rolling, rrweb 10 min / 5 000 events whichever
|
||||
is tighter, user-event log 10 min (CON-video-window, CON-rrweb-window,
|
||||
CON-event-log-window).
|
||||
- **Sensitive data**: `input[type=password]` and `[data-sensitive="true"]` MUST
|
||||
be masked in rrweb (via v2 `maskInputFn`) AND the event logger MUST drop
|
||||
password field values (CON-sensitive-data-masking).
|
||||
- **Service Worker lifecycle**: MV3 SW unloads after ~30 s idle; a
|
||||
`chrome.alarms` alarm fires every 20 s to keep it alive
|
||||
(CON-service-worker-keepalive).
|
||||
- **Tab capture binding**: `chrome.tabCapture` is tied to the active tab,
|
||||
requires a user gesture on first invocation, and MUST re-attach on tab
|
||||
activation/update events (CON-tab-capture-binding).
|
||||
- **Manifest permissions**: `tabCapture`, `activeTab`, `downloads`, `scripting`,
|
||||
`storage`; `host_permissions: ["<all_urls>"]` — exactly this set, no more, no
|
||||
less (CON-manifest-permissions).
|
||||
- **Storage strategy**: All Phase 1 rolling buffers live in memory only
|
||||
(CON-buffer-storage). `chrome.storage` is permitted but MUST NOT be used to
|
||||
persist rolling buffers.
|
||||
- **Network**: No server upload in Phase 1 (CON-no-server-upload). All export
|
||||
is local-only via `chrome.downloads`.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
<!-- Decisions that constrain future work. All 12 below are SPEC-Accepted
|
||||
acting as ADR-equivalents for Phase 1 per orchestrator instruction. They
|
||||
are LOCKED for Phase 1: any change requires a formal ADR. None are
|
||||
formally LOCKED in the ingest classification — a future ADR can revise
|
||||
any of them, but Phase 1 implementation MUST treat them as locked. -->
|
||||
|
||||
| Decision | Rationale | Outcome | Status |
|
||||
|----------|-----------|---------|--------|
|
||||
| **DEC-001**: Chrome Extension Manifest V3 | SPEC §2, §7 — required for `chrome.tabCapture`, `chrome.downloads`, `chrome.alarms`. | — Pending | locked (Phase 1) |
|
||||
| **DEC-002**: Service Worker as background coordinator | SPEC §2, §3, §8 — MV3 has no persistent background page; SW coordinates video buffer + archive packaging. | — Pending | locked (Phase 1) |
|
||||
| **DEC-003**: Tab video via `chrome.tabCapture` (vp9 / 400 kbps / 2000 ms) | SPEC §2, §4.1, §7 — only API that captures active-tab video; codec/bitrate/timeslice locked. | — Pending | locked (Phase 1) |
|
||||
| **DEC-004**: DOM capture via rrweb with `maskInputSelector` + 5 000-event cap | SPEC §2, §4.2 — rrweb is the only mature DOM-recording option; masking + cap are part of the privacy/memory contract. | — Pending | locked (Phase 1) |
|
||||
| **DEC-005**: Archive packaging via JSZip | SPEC §2, §3, §6 — only ZIP library bundled per SPEC. | — Pending | locked (Phase 1) |
|
||||
| **DEC-006**: File download via `chrome.downloads` | SPEC §2, §5, §7 — no server upload in Phase 1 (SPEC §9). | — Pending | locked (Phase 1) |
|
||||
| **DEC-007**: In-memory buffers only (no Phase 1 persistence) | SPEC §2, §4.1–§4.3 — rolling buffers in SW (video) and Content Script (rrweb + log). | — Pending | locked (Phase 1) |
|
||||
| **DEC-008**: Screenshot via `chrome.tabs.captureVisibleTab` | SPEC §4.4, §5 — captured at export time, not continuously. | — Pending | locked (Phase 1) |
|
||||
| **DEC-009**: WebM header chunk retained indefinitely | SPEC §4.1, §8 — WebM without its header is not playable. | — Pending | locked (Phase 1) |
|
||||
| **DEC-010**: Service Worker keepalive via `chrome.alarms` (20 s) | SPEC §8 — MV3 SW unloads at ~30 s idle; 20 s alarm cadence keeps it alive. | — Pending | locked (Phase 1) |
|
||||
| **DEC-011**: Manifest permissions set | SPEC §7 — `tabCapture`, `activeTab`, `downloads`, `scripting`, `storage` + `host_permissions: ["<all_urls>"]`. | — Pending | locked (Phase 1) |
|
||||
| **DEC-012**: Vite + crxjs + TypeScript build toolchain | README §"Технический стек" — DOC-level only; SPEC does not prescribe. | — Pending | locked (Phase 1) — auto-overridable by future ADR |
|
||||
|
||||
## Success Metric (Developer-Facing)
|
||||
|
||||
Phase 1 is "done" when all **9 SPEC §10 acceptance criteria** pass against an
|
||||
unpacked load of the build into Chrome:
|
||||
|
||||
1. Extension installs in Chrome without errors.
|
||||
2. Video buffer runs continuously on any tab.
|
||||
3. Buffer never holds more than 30 s of footage.
|
||||
4. rrweb records DOM events without errors on typical pages (forms, tables,
|
||||
modals).
|
||||
5. Event log captures clicks, navigation, and network errors.
|
||||
6. Archive downloads to "Downloads" in < 5 s after button press.
|
||||
7. Archive opens cleanly; `last_30sec.webm` plays back in a browser.
|
||||
8. Passwords do not appear in the event log or rrweb snapshots.
|
||||
9. Extension RAM consumption does not exceed 50 MB in the background.
|
||||
|
||||
The verbatim list lives in REQUIREMENTS.md under "Phase 1 Acceptance Criteria
|
||||
(SPEC §10 verbatim)".
|
||||
|
||||
---
|
||||
*Last updated: 2026-05-15 after initial bootstrap from intel synthesis*
|
||||
Reference in New Issue
Block a user