kite/.planning/phases/04-folders-sharing-quotas-document-ux/04-VALIDATION.md

---
phase: 4
slug: folders-sharing-quotas-document-ux
status: draft
nyquist_compliant: false
wave_0_complete: false
created: 2026-05-25
---

# Phase 4 — Validation Strategy

> Per-phase validation contract for feedback sampling during execution.

---

## Test Infrastructure

| Property | Value |
|----------|-------|
| **Framework** | pytest + pytest-asyncio (already configured) |
| **Config file** | `backend/pytest.ini` or `backend/pyproject.toml` |
| **Quick run command** | `pytest backend/tests/test_folders.py backend/tests/test_shares.py backend/tests/test_audit.py backend/tests/test_documents.py -x` |
| **Full suite command** | `cd backend && pytest -v` |
| **Estimated runtime** | ~60 seconds |

---

## Sampling Rate

- **After every task commit:** Run `pytest backend/tests/test_folders.py backend/tests/test_shares.py backend/tests/test_audit.py backend/tests/test_documents.py -x`
- **After every plan wave:** Run `cd backend && pytest -v`
- **Before `/gsd:verify-work`:** Full suite must be green
- **Max feedback latency:** 60 seconds

---

## Per-Task Verification Map

| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
| 4-01-01 | 01 | 1 | FOLD-01..05, SHARE-01..05, DOC-02, ADMIN-06, SEC-08, SEC-09 | T-4-00 / — | Wave 0 test stubs — all xfail(strict=False) | unit | `pytest backend/tests/ -x` | ❌ W0 | ⬜ pending |
| 4-02-01 | 02 | 2 | — | — | Alembic 0004 migration adds pdf_open_mode + GIN index; audit-logs bucket created | integration | `pytest backend/tests/test_migration.py -x -m integration` | ❌ W0 | ⬜ pending |
| 4-03-01 | 03 | 2 | FOLD-01 | T-4-01 | Create folder returns 201; duplicate name returns 409 | integration | `pytest backend/tests/test_folders.py::test_create_folder -x` | ❌ W0 | ⬜ pending |
| 4-03-02 | 03 | 2 | FOLD-01 | T-4-01 | Rename folder returns 200; wrong owner returns 404 | integration | `pytest backend/tests/test_folders.py::test_rename_folder -x` | ❌ W0 | ⬜ pending |
| 4-03-03 | 03 | 2 | FOLD-01 | T-4-01 | Delete empty folder returns 204 | integration | `pytest backend/tests/test_folders.py::test_delete_empty_folder -x` | ❌ W0 | ⬜ pending |
| 4-03-04 | 03 | 2 | FOLD-01, FOLD-02 | T-4-01 | Delete non-empty folder cascade-deletes all docs; quota decrements | integration | `pytest backend/tests/test_folders.py::test_delete_folder_cascade -x` | ❌ W0 | ⬜ pending |
| 4-03-05 | 03 | 2 | FOLD-02 | T-4-04 | Move document — ownership assertion on both doc and target folder (404) | integration | `pytest backend/tests/test_folders.py::test_move_wrong_owner_404 -x` | ❌ W0 | ⬜ pending |
| 4-03-06 | 03 | 2 | FOLD-03 | — | Breadcrumb path returned from folder endpoint | unit | `pytest backend/tests/test_folders.py::test_breadcrumb_path -x` | ❌ W0 | ⬜ pending |
| 4-03-07 | 03 | 2 | FOLD-04 | — | Document list sort by name/date/size returns correctly ordered results | integration | `pytest backend/tests/test_folders.py::test_document_sort -x` | ❌ W0 | ⬜ pending |
| 4-03-08 | 03 | 2 | FOLD-05 | T-4-05 | tsvector search returns matching docs; does not return other users' docs | integration (PostgreSQL) | `pytest backend/tests/test_folders.py::test_fts_search -x -m integration` | ❌ W0 | ⬜ pending |
| 4-04-01 | 04 | 3 | SHARE-01 | T-4-02 | Share by handle — success; handle not found returns 404 | integration | `pytest backend/tests/test_shares.py::test_share_success -x` | ❌ W0 | ⬜ pending |
| 4-04-02 | 04 | 3 | SHARE-02 | T-4-02 | Shared doc appears in recipient virtual folder; zero quota charged | integration | `pytest backend/tests/test_shares.py::test_shared_with_me -x` | ❌ W0 | ⬜ pending |
| 4-04-03 | 04 | 3 | SHARE-04 | T-4-02 | Revoke share — immediate; recipient can no longer access | integration | `pytest backend/tests/test_shares.py::test_revoke_share -x` | ❌ W0 | ⬜ pending |
| 4-04-04 | 04 | 3 | SHARE-01..04 | T-4-02 | Share IDOR — wrong owner cannot revoke (404) | security (negative) | `pytest backend/tests/test_shares.py::test_share_revoke_wrong_owner_404 -x` | ❌ W0 | ⬜ pending |
| 4-05-01 | 05 | 3 | DOC-02 | T-4-03 | PDF proxy streams bytes; no presigned URL in response; Content-Disposition: inline | integration | `pytest backend/tests/test_documents.py::test_content_stream_200 -x` | ❌ W0 | ⬜ pending |
| 4-05-02 | 05 | 3 | DOC-02 | T-4-03 | Range header → 206 with Content-Range header | integration | `pytest backend/tests/test_documents.py::test_content_stream_206_range -x` | ❌ W0 | ⬜ pending |
| 4-05-03 | 05 | 3 | DOC-02 | T-4-03 | Admin blocked from proxy (403) | security (negative) | `pytest backend/tests/test_documents.py::test_content_stream_admin_403 -x` | ❌ W0 | ⬜ pending |
| 4-05-04 | 05 | 3 | DOC-02 | T-4-03 | No presigned URL generated or returned in proxy response | security (negative) | `pytest backend/tests/test_documents.py::test_content_stream_no_presigned_url -x` | ❌ W0 | ⬜ pending |
| 4-06-01 | 06 | 4 | ADMIN-06 | T-4-06 | Audit log viewer returns paginated entries; filters work | integration | `pytest backend/tests/test_audit.py::test_audit_log_viewer -x` | ❌ W0 | ⬜ pending |
| 4-06-02 | 06 | 4 | ADMIN-06 | T-4-06 | Audit log entries contain no document content, filename, or extracted_text | security (negative) | `pytest backend/tests/test_audit.py::test_audit_log_no_doc_content -x` | ❌ W0 | ⬜ pending |
| 4-06-03 | 06 | 4 | ADMIN-06 | T-4-06 | Regular user cannot access audit log (403) | security (negative) | `pytest backend/tests/test_audit.py::test_audit_log_regular_user_403 -x` | ❌ W0 | ⬜ pending |
| 4-07-01 | 07 | 4 | SEC-08 | T-4-07 | credentials_enc absent from all API responses | security (negative) | `pytest backend/tests/test_security.py::test_credentials_enc_not_in_response -x` | ❌ W0 | ⬜ pending |
| 4-07-02 | 07 | 4 | SEC-09 | T-4-08 | Admin delete user triggers delete_user_files() before DB removal | integration | `pytest backend/tests/test_admin_api.py::test_delete_user_cleans_files -x` | ❌ W0 | ⬜ pending |

*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*

---

## Wave 0 Requirements

- [ ] `backend/tests/test_folders.py` — stubs for FOLD-01..05
- [ ] `backend/tests/test_shares.py` — stubs for SHARE-01..05 + IDOR security tests
- [ ] `backend/tests/test_audit.py` — stubs for ADMIN-06 + no-doc-content security tests
- [ ] `backend/tests/test_documents.py` — add proxy test stubs (test_content_stream_*) to existing file
- [ ] `backend/tests/test_security.py` — add SEC-08, SEC-09 test stubs (or in test_admin_api.py)
- [ ] Shared fixtures: `auth_user`, `admin_user`, `mock_minio` already established in Phase 3 conftest

---

## Manual-Only Verifications

| Behavior | Requirement | Why Manual | Test Instructions |
|----------|-------------|------------|-------------------|
| Breadcrumb ellipsis truncation at depth > 4 | FOLD-03 | Visual rendering; depth truncation requires human verification | Create nested folder chain > 4 levels deep; verify breadcrumb shows first + "..." + last 2 segments |
| PDF in-app modal rendering (iframe) | DOC-02, D-10 | Browser rendering; cannot be asserted in pytest | Set preference to `in_app`; click document; verify PDF opens in modal iframe |
| PDF new-tab opening | D-10 | Browser window.open behavior | Set preference to `new_tab`; click document; verify PDF opens in new tab |
| Share modal UX — handle input, share list, revoke | SHARE-01..04, D-05 | Vue component interaction; visual layout | Open share modal; enter handle; verify share appears in list; click Revoke; verify removal |
| Admin audit log CSV download | ADMIN-06, D-16 | File download via StreamingResponse | As admin; click CSV export; verify file downloads with correct columns; verify no doc content |
| Daily Celery beat audit export to MinIO | D-17 | Celery beat scheduling not testable without live Redis + MinIO + time passage | Trigger task manually via Celery CLI; verify CSV uploaded to `audit-logs` MinIO bucket |

---

## Validation Sign-Off

- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
- [ ] Wave 0 covers all MISSING references
- [ ] No watch-mode flags
- [ ] Feedback latency < 60s
- [ ] `nyquist_compliant: true` set in frontmatter

**Approval:** pending