Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/CHECKPOINT_DELTA.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,13 @@
# Checkpoint Delta — CD06

## DIF-V2-WO-020 — Laboratório de retenção (2026-11-20) — PROPOSED

- **Status:** **PROPOSED — NOT PROMOTED**; PgTAP 229/229, policy 34/37, unit 318+3, E2E local PASS; CI `44694433465` PASS em `02d9cae`; auditoria delta final pendente. Sem merge/deploy.
- **Base:** `main` `59ec14c` (checkpoint WO-019 promovido); branch `feat/dif-v2-wo-020`.
- **Delivered:** posts versionados, variantes ligadas a hook/capa/final, snapshots idempotentes imutáveis, import CSV com NULL, experimentos A/B observacionais, dashboard/export/delete owner-only.
- **Limits:** sem API/scraping; comparação descritiva sem significância; CSV exporta último snapshot; sem UI de edição de variante/poda; sem dados de espectadores.
- **Gate:** CI + auditoria independente + autorização contínua do owner; WO-021 (#38) é a próxima.

## DIF-V2-WO-019 — Finais A/B e CTA cinematográfica (2026-11-20) — PROMOTED

- **Status:** **PROMOTED**; code/test head `ff00957`; CI `44676921244` PASS (307+3 unit, PgTAP 210/210, E2E 17/17, Sonar PASS), docs-only `1c914ea` CI `44678149983` PASS, policy 33/31; auditoria final **APPROVED WITH RESIDUALS**; squash-merged em `3b0f3b7` (PR #66); issue #36 fechada.
Expand Down
8 changes: 8 additions & 0 deletions docs/CONTEXT_LOCK.md
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,14 @@ Revalidate before any external action if `main` changes; the feature branch is r
- **Tests:** PgTAP **108/108**, policy **25 invariants/22 tables**, unit **116 + 2 skipped**, typecheck/lint/build PASS, real FFmpeg mux integration PASS, real Piper TTS opt-in PASS, 232-word synthetic TTS **94.552 s / −2,8 dBFS / −19,5 LUFS / 8,7 MB**; ARM64 **81 s de áudio em 8,86 s, RTF 0,109, 282 MB RSS**, hosted CI `43590151067` **SUCCESS** with E2E **12/12** (timeline narrada READY em 31,3s), owner-boundary narration 401 and responsive layout PASS.
- **Gate:** owner authorized merge/promotion on 2026-11-14; PR #55 squash-merged at `326c576`; issue #24 closed; checkpoint **PROMOTED**. WO-008 (#25) is next.

## V2 Context Lock — WO-020 (#37)

- **Base revalidated:** `main` `59ec14c` (checkpoint WO-019 promoted). Branch: `feat/dif-v2-wo-020`.
- **Issue inventory:** WO-001–019 **MERGED/CLOSED/PROMOTED**; WO-020/#37 em execução; WO-021 e OPS bloqueiam WO-014.
- **Scope:** métricas agregadas fornecidas manualmente/CSV; posts, variantes, snapshots, A/B observacional, export/delete, sem API social.
- **Delivered locally:** 6 tabelas owner-read/service-write; `/app/retention`; CSV/JSON export; stale/idempotência/immutabilidade; PgTAP 229; policy 34/37.
- **Gate:** CI, auditoria independente e autorização contínua do owner; checkpoint **PROPOSED**. WO-021 (#38) é a próxima.

## V2 Context Lock — WO-019 (#36)

- **Base revalidated:** `main` `c94409d` (checkpoint WO-018 promoted). Branch: `feat/dif-v2-wo-019`.
Expand Down
19 changes: 19 additions & 0 deletions docs/EVIDENCE_BUNDLE.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
# DIF Studio — Evidence Bundle

## V2 WO-020 — Laboratório de retenção (2026-11-20) — PROPOSED

- **Work Order:** `DIF-V2-WO-020` · issue #37 · epic #17
- **Base:** `main` `59ec14c` (checkpoint WO-019 promovido); branch `feat/dif-v2-wo-020`
- **Status:** implementação + provas locais; unit **318+3**, PgTAP **229/229**, policy 34/37, build e E2E local PASS; CI `44694433465` PASS em `02d9cae` (318+3 unit, PgTAP 229/229, E2E 18/18, Sonar PASS); auditoria delta pendente. Checkpoint **PROPOSED**.

| Check | Result | Evidence |
| ------- | ---------- | ------------------------------------------------------------------------------------ |
| Model | PASS local | posts versionados, variantes, snapshots imutáveis, imports e experimentos owner-only |
| Metrics | PASS local | fórmulas v1 com numerador/denominador; NULL ≠ zero; watch > duração rejeitado |
| Compare | PASS local | mesma plataforma, janelas ±20%, views ≥1000; senão NOT_COMPARABLE/INSUFFICIENT |
| UI | PASS local | `/app/retention` cadastra, importa CSV, mostra origem/denominador, compara e remove |
| Privacy | PASS local | owner-read/service-write; URLs nunca fetched; sem dados de espectadores |
| Export | PASS local | CSV/JSON owner-only, no-store, proteção de fórmula CSV |
| PgTAP | PASS local | 229/229 RLS, idempotência, supersedes, imutabilidade, experimento e cascata |
| Policy | PASS local | 34 invariantes / 37 tabelas; backup/restore incluem as 6 tabelas |
| CI | PENDENTE | quality/Sonar/E2E no head do PR |
| Limites | — | sem API/scraping; descritivo, não causal; sem significância; CSV = último snapshot |

## V2 WO-019 — Finais A/B e CTA cinematográfica (2026-11-20) — PROMOTED

- **Work Order:** `DIF-V2-WO-019` · issue #36 · epic #17
Expand Down
4 changes: 2 additions & 2 deletions docs/V2_EXECUTION_PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

- **Work Order:** `DIF-V2-WO-001` · issue #18
- **Epic:** #17 · issues #18–#45
- **Base atual:** `main` `3b0f3b7` (checkpoint WO-019 promovido); WO-020 em execução; plano original em `13467ab009e0eaaee1be6ba2e35678228cfbdf32`.
- **Base atual:** `main` `59ec14c` (checkpoint WO-019 promovido); WO-020 em execução; plano original em `13467ab009e0eaaee1be6ba2e35678228cfbdf32`.
- **Status:** **PROMOTED** — WO-001/002 **APPROVED/merged**; ADR-V2-002 **ACCEPTED**; WO-003/004/005 **APPROVED/merged** (`ac55d27`, `c6be101`, `dc405d8`); checkpoint V2 **PROMOTED**; WO-006 **APPROVED/merged** (`239f3ba`); WO-007 **APPROVED/merged** (`326c576`); WO-008 **APPROVED/merged** (`a633c3a`); WO-009 **APPROVED/merged** (`0b60321`); WO-010 **APPROVED/merged** (`1824061`); WO-011 **APPROVED WITH RESIDUALS/merged** (`d4a6a80`); WO-012 **APPROVED WITH RESIDUALS/merged** (`3edec2b`); WO-013 **APPROVED WITH RESIDUALS/merged (núcleo)** (`b1a1eaf`); WO-015 **APPROVED WITH RESIDUALS/merged** (`7c2ac4b`); WO-016 **APPROVED WITH RESIDUALS/merged** (`25089c3`); WO-017 **APPROVED WITH RESIDUALS/merged** (`ddaf0d2`); WO-018 **APPROVED WITH RESIDUALS/merged** (`62c30eb`); WO-019 **APPROVED WITH RESIDUALS/merged** (`3b0f3b7`); WO-020 em execução.
- **Fonte viva:** os corpos atuais das issues #18–#45 prevalecem sobre este plano.

Expand All @@ -29,7 +29,7 @@
| WO-017 | #34 | Continuidade visual + Character Identity Kit | ELEVATED | WO-003; WO-004; WO-011; WO-016 (quando disponível) | APPROVED WITH RESIDUALS / MERGED |
| WO-018 | #35 | Capas, posters e cards | STANDARD | WO-003; WO-004; WO-011; WO-012; WO-016 | PROMOTED (`62c30eb`) |
| WO-019 | #36 | Finais A/B cinematográficos e CTA canônica | STANDARD | WO-004; WO-010; WO-012 (proposta); V1 canon/choices | PROMOTED (`3b0f3b7`) |
| WO-020 | #37 | Laboratório de retenção, métricas manuais | STANDARD | WO-012; WO-015; WO-018; WO-019; WO-001; métricas V1 manuais | PLANNED |
| WO-020 | #37 | Laboratório de retenção, métricas manuais | STANDARD | WO-012; WO-015; WO-018; WO-019; WO-001; métricas V1 manuais | IN PROGRESS |
| WO-021 | #38 | Bíblia audiovisual, presets e herança | STANDARD | WO-004; WO-009; WO-011; WO-016; WO-018 | PLANNED |
| WO-022 | #39 | Smart Cutdowns 30/45/60 s | STANDARD | WO-004; WO-008; WO-012; WO-015; WO-019 | PLANNED |
| WO-023 | #40 | Clip Rescue reversível | ELEVATED | WO-003; WO-006; WO-012; WO-016; retenção mínima WO-001/003 | PLANNED |
Expand Down
71 changes: 71 additions & 0 deletions docs/V2_RETENTION_WO020.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# DIF-V2-WO-020 — Laboratório de retenção e métricas manuais

**Status:** implementação em `feat/dif-v2-wo-020`; CI `44694433465` PASS em `02d9cae` (318+3 unit, PgTAP 229/229, E2E 18/18, Sonar PASS), policy 34/37; auditoria delta final **PENDENTE**. Sem merge/deploy; checkpoint **PROPOSED**.
**Base:** `main` `59ec14c` (checkpoint WO-019 promovido).
**Escopo:** WO-020 (#37), dependente de WO-012/015/018/019 e do fluxo manual V1.

## Entregue

- Modelo privado owner-only: `published_posts`, `published_post_versions`, `creative_variants`, `analytics_snapshots`, `retention_imports` e `retention_experiments`.
- Posts com plataforma, URL validada (texto, nunca fetched), data de publicação e vínculo opcional a hook/capa/final aprovados do mesmo episódio.
- Snapshots append-only com revisão, `snapshot_hash`, `supersedes_snapshot_id`, origem MANUAL/CSV, período e métricas agregadas nuláveis (ausente ≠ zero).
- Fórmulas versionadas com numerador/denominador explícitos: engajamento por views, conclusão, watch time relativo e interações por 1000 views.
- Comparação A/B somente com mesma plataforma, janelas equivalentes e amostra ≥1000 views; caso contrário `NOT_COMPARABLE`/`INSUFFICIENT`. Texto sempre “observado/associação”, nunca causalidade.
- Import CSV com validação por linha, campos vazios → NULL, idempotência por hash, limites de tamanho e erros por linha.
- `/app/retention`: cadastro de posts/variantes, snapshots manuais, importação CSV, dashboard com origem/denominador, experimentos A/B observacionais, export CSV/JSON e remoção owner-only.
- Export CSV com proteção de fórmula (`= + - @`) e JSON com definições/versão; nada de dados de espectadores.
- Backup/restore e policy incluem as seis tabelas; 37 tabelas e 34 invariantes.

## Capacidade real versus planejada

- Nenhuma API social, scraping, login automatizado, leitura de dashboard ou coleta de comentários; todos os números são fornecidos manualmente/CSV.
- Métricas são agregadas; não há dados por espectador, segmentação de público ou atribuição de tráfego.
- A comparação A/B é descritiva: não estima significância, não controla confundidores e não prevê viralidade.
- O período é comparável quando mesma plataforma, duração da janela ±20% e views ≥1000 nas duas variantes; janelas diferentes geram aviso.
- Histórico de post é versionado; snapshots nunca são sobrescritos (retificação cria nova revisão com `supersedes`).
- Export CSV/JSON é owner-only; remoção apaga post, versões, variantes, snapshots e experimentos vinculados.

## Critérios de aceitação

| Critério | Estado | Evidência |
| ----------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| 2 vídeos/fixtures, plataformas distintas, períodos e A/B; dashboard mostra origem e denominador | PASS | E2E cria TikTok+Reels com snapshots, A/C TikTok para A/B, CSV, comparação observacional e cross-platform NOT_COMPARABLE |
| Métrica ausente não vira zero/conclusão; períodos distintos mostram incomparabilidade | PASS | NULL/partial → warnings/`INSUFFICIENT`; CSV sem interações INDISPONÍVEL; cross-platform alerta |
| Gráficos/resumo factual sem “viral”, “garantia” ou ranking especulativo | PASS | barras SVG de views/engajamento, histórico por post, comparação observacional; teste proíbe termos |
| Entrada repetida idempotente com histórico; edição não sobrescreve evidência | PASS | hash único, revisão append-only, duração/métrica pinadas, `supersedes` e histórico na UI |
| Export/exclusão sem vazar dados owner ou de usuários | PASS | rotas owner-only, export agregado, delete RPC; E2E anônimo 401 e remoção |

## Correções pós-auditoria independente

- **Interações parciais:** `PARTIAL_INTERACTIONS` é emitido e a comparação com cobertura de campos diferente retorna `INSUFFICIENT`/`INTERACTION_COVERAGE_MISMATCH`; NULL nunca vira zero.
- **Limites por owner:** variantes e snapshots são buscados com `.in('post_id', postIds)` depois dos posts, sem limite global que esconda o episódio.
- **Números estritos:** formulário e CSV rejeitam `1.000`, `1,5`, `1.234,5` e texto; apenas dígitos (e ponto decimal na conclusão). Erro por linha é exibido.
- **CSV injection:** células perigosas são citadas e cada linha recebe apóstrofo; vírgulas/quebras não criam registros sem escape.
- **Snapshot/experimento pinados:** `episode_duration_ms` e `metric_version` ficam no snapshot; experimentos guardam os snapshots A/B usados e rejeitam variantes do mesmo post; a UI mostra revisão/origem/período pinados e não cai para o latest se o pinado faltar.
- **Gráficos sem NULL→0:** barras de engajamento só incluem taxas calculáveis; CSV B sem interações não ganha barra 0% (E2E verifica 4 barras para 5 posts).
- **Paginação PostgREST:** variantes/snapshots são lidos com `.range()` em páginas de 1000 até esgotar, em vez de um `.limit(5000)` clampado.
- **Hash com duração:** `episode_duration_ms` entra no `snapshot_hash`, permitindo retificar apenas o denominador.
- **Histórico/gráficos:** dashboard tem barras SVG de views/engajamento, histórico por post com revisões/supersedes e select de retificação; A/B mostra variante, post, views, unidade, revisão/origem/período.
- **Resiliência:** snapshot histórico inválido gera warning e não derruba a página/export; conflito de revisão concorrente usa advisory lock e 409, não falso duplicado; hooks DRAFT não aparecem no formulário.

## Testes planejados/executados

- Unit: 11 testes — fórmulas com NULL/zero/amostra baixa/discrepância, interações parciais vs completas, watch =105% rejeitado, comparabilidade por plataforma/período/amostra/métrica, linguagem não causal, CSV quoted/CRLF, linha malformada, número ambíguo, injeção de fórmula com vírgula/newline.
- PgTAP 229: RLS owner/nonowner, escrita direta negada, post/versão, variante A/B em posts distintos, snapshot idempotente com duração pinada e supersedes, imutabilidade, experimento, delete em cascata.
- E2E: login/nav, cria posts TikTok+Reels com snapshots, variantes, experimento observacional, cross-platform `NOT_COMPARABLE`, CSV com NULL (sem barra 0%), origem MANUAL, export CSV/JSON, anônimo negado, remoção e screenshots 360/768/1440.
- Policy: 34 invariantes / 37 tabelas; backup/restore incluem as tabelas de retenção.

## Riscos e residuais

- Sem APIs oficiais, scraping ou coleta automática; dados podem ser incompletos ou enviesados pelo owner.
- Sem significância estatística, controle de confundidores ou atribuição de tráfego; comparação é descritiva.
- Sem dados por espectador, demografia ou comentários; somente agregados fornecidos.
- CSV não valida duplicidade de URL entre episódios diferentes (a chave é por owner+episódio+plataforma+URL).
- Sem UI de edição de post/variante; correções de post criam versão, variantes são imutáveis.
- Sem poda de snapshots/imports; limites de 5000 snapshots/post e 5000 linhas/CSV.
- Gráficos são barras SVG simples por último snapshot, não séries temporais completas; histórico aparece em lista por post.
- Export CSV inclui o último snapshot por post; JSON inclui as revisões carregadas (paginadas) e as 20 importações mais recentes. Não há export de `published_post_versions`.

## Gate

CI hosted, PgTAP, Evidence Bundle, Checkpoint Delta PROPOSED, auditoria independente e autorização contínua do owner antes de merge/promoção. **Sem deploy nesta etapa.**
61 changes: 61 additions & 0 deletions docs/evidence/wo-020/tests.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# WO-020 — evidence

Date: 2026-11-20 (America/Sao_Paulo)
Branch: `feat/dif-v2-wo-020` (base `main` `59ec14c`)

## Static

- `npm run check`: 0 errors / 0 warnings
- `npm run lint`: PASS
- `npm run audit:policy`: **34 invariants / 37 tables** PASS
- `npm run build`: PASS (@sveltejs/adapter-node)
- `npm run test:db`: **229/229** PgTAP PASS

## Unit / domain

- `retention.test.ts`: 11/11 — formula denominators, NULL vs zero, partial interactions vs full
coverage, low sample, completion discrepancy, watch =105% rejected, platform/period/sample/metric
comparability, non-causal language, CSV quoted/CRLF, malformed rows, ambiguous thousands,
formula injection with commas/newlines.
- Post-fix: snapshots load per episode post ids; latest is highest revision; A/B pins the snapshots
used and rejects variants from the same post.
- Unit suite: **318 passed + 3 skipped** locally.

## E2E

- `e2e/retention.spec.ts` local PASS: login, nav “Retenção”, TikTok and Reels posts, three variants,
manual snapshots, A/B observational comparison, CSV import with NULL interactions, CSV/JSON export,
anonymous 401, delete, screenshots 360/768/1440.
- Dashboard shows origin/period/denominator, marks missing values as `INDISPONÍVEL`, renders SVG
views bars plus engagement bars only for calculable rates (CSV B with NULL interactions has no
0% bar), and per-post snapshot history with supersedes/retification.
- Variants/snapshots are paginated with `.range()` (1000/page); experiments show the pinned
snapshot revision/source/period and fail closed when the pinned snapshot is absent.

## Database / retention

- `published_posts`, `published_post_versions`, `creative_variants`, `analytics_snapshots`,
`retention_imports`, `retention_experiments` are owner-read/service-write with forced RLS.
- Snapshots/versions/imports are immutable; snapshots are idempotent by `(post, snapshot_hash)`
that includes `episode_duration_ms`, pin `metric_version`, and retifications append a new revision
with `supersedes_snapshot_id`.
- Experiments pin `variant_a_snapshot_id`/`variant_b_snapshot_id` and reject variants from the same
post; concurrent snapshot revisions use an advisory lock.
- PgTAP: owner read, direct insert denied, second owner isolated, post version, variants A/B,
idempotent snapshot, supersedes, immutable update, experiment distinct variants, delete cascade.
- Quota: 5000 snapshots per post; 5000 CSV rows and 5 MB input.

## Privacy / security

- URLs are owner-provided text and never fetched; no scraping, login automation or social API.
- Only aggregate metrics are stored; no viewer-level, demographic or comment data.
- Export routes owner-only, `private, no-store`; CSV cells are quoted then prefixed per line
against formula injection.
- Deletion is owner-scoped and removes post, versions, variants, snapshots and linked experiments.

## Limits verified

- Comparisons are descriptive associations, not causal or significance tests.
- Different platforms or window lengths return `NOT_COMPARABLE`; low samples return `INSUFFICIENT`.
- CSV export contains the latest snapshot per post; full context and imports are in JSON.
- Post edits create a new version; variants are immutable and have no edit UI.
Loading