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

---
phase: 4
slug: folders-sharing-quotas-document-ux
status: complete
nyquist_compliant: true
wave_0_complete: true
created: 2026-05-25
audited: 2026-05-31
---

# 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` |
| **Quick run command** | `pytest backend/tests/test_folders.py backend/tests/test_shares.py backend/tests/test_audit.py backend/tests/test_documents.py backend/tests/test_security.py -x` |
| **Full suite command** | `cd backend && python3 -m 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 && python3 -m 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 created across test_folders.py, test_shares.py, test_audit.py, test_documents.py, test_security.py | unit | `pytest backend/tests/ -x` | ✅ | ✅ green |
| 4-02-01 | 02 | 2 | STORE-01 | — | Alembic migration tests exist in test_alembic.py (SQLite-based xfail/skip — alembic not installed in local env) | integration | `pytest backend/tests/test_alembic.py -x` | ✅ | ⚠️ skipped (alembic not in test env) |
| 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_root_folder backend/tests/test_folders.py::test_create_folder_duplicate_name_409 -x` | ✅ | ✅ green |
| 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 backend/tests/test_folders.py::test_rename_folder_wrong_owner_404 -x` | ✅ | ✅ green |
| 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` | ✅ | ✅ green |
| 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_documents backend/tests/test_folders.py::test_delete_folder_cascade_quota -x` | ✅ | ✅ green |
| 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_document_wrong_owner_404 backend/tests/test_folders.py::test_move_document_to_other_users_folder_404 -x` | ✅ | ✅ green |
| 4-03-06 | 03 | 2 | FOLD-03 | — | Breadcrumb path returned from folder endpoint | unit | `pytest backend/tests/test_folders.py::test_get_folder_breadcrumb_single backend/tests/test_folders.py::test_get_folder_breadcrumb_deep -x` | ✅ | ✅ green |
| 4-03-07 | 03 | 2 | FOLD-04 | — | Document list sort by name/date/size returns correctly ordered results | integration | `pytest backend/tests/test_documents.py::test_document_sort_by_name_asc backend/tests/test_documents.py::test_document_sort_by_size_desc -x` | ✅ | ✅ green |
| 4-03-08 | 03 | 2 | FOLD-05 | T-4-05 | ?q= search returns 200 + user-isolated results; cross-user docs never leak | integration | `pytest backend/tests/test_documents.py::test_fts_search_returns_200 backend/tests/test_documents.py::test_fts_search_cross_user_isolation -x` | ✅ | ✅ green |
| 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 backend/tests/test_shares.py::test_share_handle_not_found -x` | ✅ | ✅ green |
| 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 backend/tests/test_shares.py::test_share_no_quota_impact -x` | ✅ | ✅ green |
| 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` | ✅ | ✅ green |
| 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` | ✅ | ✅ green |
| 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` | ✅ | ✅ green |
| 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` | ✅ | ✅ green |
| 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` | ✅ | ✅ green |
| 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` | ✅ | ✅ green |
| 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` | ✅ | ✅ green |
| 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` | ✅ | ✅ green |
| 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` | ✅ | ✅ green |
| 4-07-01 | 07 | 4 | SEC-08 | T-4-07 | credentials_enc absent from all API responses (documents list, document detail) | security (negative) | `pytest backend/tests/test_security.py::test_credentials_enc_not_in_response -x` | ✅ | ✅ green |
| 4-07-02 | 07 | 4 | SEC-09 | T-4-08 | Admin delete user triggers MinIO object deletion before DB removal | integration | `pytest backend/tests/test_security.py::test_delete_user_cleans_files -x` | ✅ | ✅ green |

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

---

## 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 |
| FTS PostgreSQL behavior | FOLD-05 | Test env uses SQLite; FTS clause is skipped on SQLite | On PostgreSQL, verify ?q=keyword returns only matching docs; verify cross-user isolation |

---

## Validation Sign-Off

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

**Approval:** 2026-05-31

---

## Validation Audit 2026-05-31

| Metric | Count |
|--------|-------|
| Tasks audited | 22 |
| COVERED (green) | 20 |
| PARTIAL (skipped/env) | 1 (4-02-01 alembic — SQLite env, not a code issue) |
| MISSING → resolved | 2 (4-03-07 FOLD-04, 4-03-08 FOLD-05) |
| PARTIAL → resolved | 2 (4-07-01 SEC-08, 4-07-02 SEC-09) |
| Impl bugs fixed | 1 (FTS try/except misplaced in api/documents.py — wrapped builder not execute) |
| Escalated | 0 |