From 13b9d834016f48fc4eedfc7516dfcb8b70fa44b0 Mon Sep 17 00:00:00 2001 From: curo1305 Date: Fri, 19 Jun 2026 06:10:55 +0200 Subject: [PATCH] docs(phase-12): update validation strategy --- .../12-VALIDATION.md | 107 ++++++++++++------ 1 file changed, 75 insertions(+), 32 deletions(-) diff --git a/.planning/phases/12-cloud-resource-foundation/12-VALIDATION.md b/.planning/phases/12-cloud-resource-foundation/12-VALIDATION.md index 4a47fff..73800ed 100644 --- a/.planning/phases/12-cloud-resource-foundation/12-VALIDATION.md +++ b/.planning/phases/12-cloud-resource-foundation/12-VALIDATION.md @@ -1,15 +1,16 @@ --- phase: 12 slug: cloud-resource-foundation -status: draft +status: complete nyquist_compliant: true -wave_0_complete: false +wave_0_complete: true created: 2026-06-18 +last_audited: 2026-06-19 --- # Phase 12 — Validation Strategy -> Per-phase validation contract for feedback sampling during execution. +> Post-execution validation contract and Nyquist audit evidence for the cloud resource foundation. --- @@ -17,47 +18,66 @@ created: 2026-06-18 | Property | Value | |----------|-------| -| **Framework** | pytest 8.x, Vitest 4.x, Vue Test Utils 2.x | +| **Framework** | pytest 9.x, Vitest 4.x, Vue Test Utils 2.x | | **Config file** | `backend/pytest.ini`, `frontend/vitest.config.js` | -| **Quick run command** | `cd backend && pytest -q tests/test_cloud.py tests/test_cloud_backends.py tests/test_cloud_capabilities.py tests/test_cloud_items.py` and focused frontend Vitest files | +| **Quick backend command** | `docker compose run --rm backend pytest -q tests/test_cloud.py tests/test_cloud_backends.py tests/test_cloud_capabilities.py tests/test_cloud_items.py tests/test_cloud_security.py` | +| **Quick frontend command** | `cd frontend && npm test -- --run src/components/storage/__tests__/StorageBrowser.capabilities.test.js src/components/ui/__tests__/BreadcrumbBar.test.js src/views/__tests__/CloudFolderView.test.js src/views/__tests__/CloudStorageView.test.js src/stores/__tests__/cloudConnections.test.js src/components/settings/__tests__/SettingsCloudTab.test.js` | | **Full suite command** | `cd backend && pytest -v`; `cd frontend && npm test`; `cd frontend && npm run build` | -| **Estimated runtime** | Establish baseline during Wave 0; keep focused feedback under 60 seconds | +| **Fresh focused runtime** | Backend 155 tests in 4.14 s; frontend 62 tests in 703 ms (2026-06-19) | --- ## Sampling Rate - **After every task commit:** Run the focused test file(s) named by that task. -- **After every plan wave:** Run backend and frontend full suites for all touched layers. -- **Before `/gsd:verify-work`:** Full backend suite, frontend suite, production build, and required PostgreSQL integration tests must be green. -- **Max feedback latency:** 60 seconds for focused task verification. +- **After every plan wave:** Run backend and frontend suites for all touched layers. +- **Before `/gsd:verify-work`:** Run the full backend suite, full frontend suite, production build, and required PostgreSQL integration tests. +- **Max observed focused feedback latency:** 4.14 seconds, excluding container startup. --- ## Per-Task Verification Map -| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status | -|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------| -| 12-01-01 | 01 | 1 | CONN-04, CLOUD-08 | T-12-06 | Capability discovery never mutates provider content | unit | `cd backend && pytest -q tests/test_cloud_capabilities.py` | ❌ W0 | ⬜ pending | -| 12-01-02 | 01 | 1 | CACHE-02, SYNC-01 | T-12-01, T-12-02 | Cloud item metadata is owner and connection scoped | unit + PostgreSQL integration | `cd backend && pytest -q tests/test_cloud_items.py` | ❌ W0 | ⬜ pending | -| 12-02-01 | 02 | 2 | CLOUD-01, SYNC-01 | T-12-01, T-12-07 | Connection-ID browse cannot cross owners and only reconciles complete listings | API integration | `cd backend && pytest -q tests/test_cloud.py tests/test_cloud_items.py` | Existing + W0 additions | ⬜ pending | -| 12-02-02 | 02 | 2 | CACHE-01 | T-12-09 | Browse performs no byte download, MinIO write, or quota mutation | negative integration | `cd backend && pytest -q tests/test_cloud.py -k 'no_bytes or quota'` | ❌ W0 | ⬜ pending | -| 12-03-01 | 03 | 2 | CONN-04, CLOUD-08 | T-12-10 | Unsupported controls remain safe, focusable, and explanatory on pointer/keyboard/touch | component | `cd frontend && npm test -- --run StorageBrowser` | Existing file needs expansion | ⬜ pending | -| 12-03-02 | 03 | 2 | CLOUD-01 | T-12-01 | Frontend routes and requests use connection UUID, including duplicate providers | store/view component | `cd frontend && npm test -- --run CloudFolderView CloudStorageView cloudConnections` | Partial/W0 | ⬜ pending | -| 12-04-01 | 04 | 3 | All Phase 12 | T-12-01..10 | Full owner/admin, regression, build, and PostgreSQL gates pass | integration/regression | full suite commands above | Existing + additions | ⬜ pending | +| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Evidence | File Exists | Status | +|---------|------|------|-------------|------------|-----------------|-----------|--------------------|-------------|--------| +| 12-01-01 | 01 | 1 | CONN-04, CLOUD-08 | T-12-06 | Capability discovery is normalized and never mutates provider content | unit | `tests/test_cloud_capabilities.py` | ✅ | ✅ green | +| 12-01-02 | 01 | 1 | CACHE-02, SYNC-01 | T-12-01, T-12-02 | Metadata/search state is owner and connection scoped without byte storage | unit + DB | `tests/test_cloud_items.py` schema, isolation, quota cases | ✅ | ✅ green | +| 12-01-03 | 01 | 1 | CACHE-02, SYNC-01 | T-12-07 | Reconciliation is stable and incomplete listings cannot delete unseen items | service | `tests/test_cloud_items.py` reconciliation cases | ✅ | ✅ green | +| 12-02-01 | 02 | 2 | CONN-04, SYNC-01 | T-12-04, T-12-06 | All providers normalize complete metadata/capability listings through read-only calls | adapter contract | `tests/test_cloud_backends.py` | ✅ | ✅ green | +| 12-02-02 | 02 | 2 | CLOUD-01, CLOUD-08 | T-12-01, T-12-03 | Connection-ID browse rejects foreign/admin access and excludes credentials | API integration | `tests/test_cloud.py`, `tests/test_cloud_security.py` | ✅ | ✅ green | +| 12-02-03 | 02 | 2 | CACHE-01, SYNC-01 | T-12-07, T-12-09 | Refresh retries safely, retains metadata on failure, and downloads no bytes | task/service | `tests/test_cloud_items.py` refresh/no-byte cases | ✅ | ✅ green | +| 12-03-01 | 03 | 3 | CONN-04, CLOUD-01 | T-12-01, T-12-11 | Routes/stores use connection UUID and session storage contains folder references only | store/view | cloudConnections, CloudStorageView, CloudFolderView, SettingsCloudTab tests | ✅ | ✅ green | +| 12-03-02 | 03 | 3 | CONN-04, CLOUD-08 | T-12-10 | Disabled controls are focusable/explanatory and suppress pointer/keyboard/touch actions | component | `StorageBrowser.capabilities.test.js` | ✅ | ✅ green | +| 12-03-03 | 03 | 3 | CLOUD-01, SYNC-01 | T-12-12 | Breadcrumb freshness states are accessible and cached rows stay usable | component | `BreadcrumbBar.test.js`, `CloudFolderView.test.js` | ✅ | ✅ green | +| 12-04-01 | 04 | 4 | All Phase 12 | T-12-01..10 | Dedicated owner/admin/credential/SSRF/no-byte negatives close cross-layer threats | integration/regression | `tests/test_cloud_security.py` plus focused suites | ✅ | ✅ green | +| 12-04-02 | 04 | 4 | CONN-04, CLOUD-08 | T-12-SC | Static/dependency security gates have no unresolved Phase 12 blocker | security gate | `SECURITY.md` Phase 12 evidence | ✅ | ✅ green | +| 12-04-03 | 04 | 4 | All Phase 12 | — | Documentation/version claims match tracked shipped behavior | source + suites | `12-VERIFICATION.md`, summaries, version source assertions | ✅ | ✅ green | -*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky* +*Status: ✅ green · ❌ red · ⚠️ partial/manual* + +--- + +## Requirement Coverage + +| Requirement | Status | Automated evidence | +|-------------|--------|--------------------| +| CONN-04 | COVERED | Capability contract tests, connection store/settings tests, StorageBrowser action-state tests | +| CLOUD-01 | COVERED | Connection-ID API tests and shared CloudStorageView/CloudFolderView/StorageBrowser tests | +| CLOUD-08 | COVERED | Unsupported/temporarily-unavailable state, message, pointer, Enter, Space, and touch suppression tests | +| CACHE-01 | COVERED | No-MinIO, no-byte-download, no-quota-mutation browse/refresh tests | +| CACHE-02 | COVERED | Cloud metadata/extracted text/topic/semantic fields and cross-connection isolation tests | +| SYNC-01 | COVERED | Provider normalization plus durable item/reconciliation/freshness tests | --- ## Wave 0 Requirements -- [ ] `backend/tests/test_cloud_capabilities.py` — capability normalization, reason states, safe discovery, item overrides. -- [ ] `backend/tests/test_cloud_items.py` — owner-scoped persistence, stable identity, reconciliation, metadata-only invariants. -- [ ] PostgreSQL fixtures/marker for unique constraints, foreign keys, UUIDs, indexes, and cascade behavior. -- [ ] Frontend test files for `CloudFolderView.vue` and `CloudStorageView.vue` if focused files do not already exist. -- [ ] Shared provider response fixtures for Google Drive, OneDrive, Nextcloud, and generic WebDAV normalization. -- [ ] Baseline focused and full-suite runtimes recorded before implementation begins. +- [x] `backend/tests/test_cloud_capabilities.py` — capability normalization, reason states, safe discovery, item overrides. +- [x] `backend/tests/test_cloud_items.py` — owner-scoped persistence, stable identity, reconciliation, metadata-only invariants. +- [x] Database constraint/isolation coverage for UUID ownership, unique connection/item identity, and cascade behavior. +- [x] `CloudFolderView.test.js` and `CloudStorageView.test.js` — thin shared-browser view integration. +- [x] Provider response fixtures for Google Drive, OneDrive, Nextcloud, and generic WebDAV normalization. +- [x] Focused runtime baseline recorded: backend 4.14 s, frontend 703 ms, excluding container startup. --- @@ -65,18 +85,41 @@ created: 2026-06-18 | Behavior | Requirement | Why Manual | Test Instructions | |----------|-------------|------------|-------------------| -| Tooltip placement and clarity across desktop/mobile viewports | CLOUD-08 | Visual polish and viewport clipping need rendered-browser review | Use Playwright at mobile and desktop widths; hover, keyboard-focus, and tap unsupported controls; verify explanation is readable and does not overlap adjacent UI | -| Cached-first folder transition preserves perceived continuity | CLOUD-01 | Perceived flicker and scroll stability benefit from browser observation | Seed cached metadata, delay provider refresh, navigate folders, and verify rows remain usable with only the subtle folder-level refresh indicator | +| Tooltip placement and clarity across desktop/mobile viewports | CLOUD-08 | Visual placement and viewport clipping require a rendered browser | Hover and keyboard-focus a gray/amber cloud action on desktop, then tap it on mobile; verify readable explanation, no overlap, and no underlying action | +| Cached-first transition and freshness presentation | CLOUD-01, SYNC-01 | Perceived flicker, layout stability, and continued row usability are visual qualities | Seed durable metadata, delay/fail provider refresh, navigate the folder, and verify rows remain interactive while refreshing/warning indicators and last-update copy render correctly | + +These checks supplement automated coverage; no Phase 12 requirement depends solely on manual verification. + +--- + +## Validation Audit 2026-06-19 + +| Metric | Count | +|--------|-------| +| Phase requirements audited | 6 | +| Automated requirements covered | 6 | +| Gaps found | 0 | +| Tests generated | 0 | +| Gaps escalated to manual-only | 0 | +| Supplementary manual visual checks retained | 2 | + +### Fresh Execution Evidence + +- Backend focused cloud suite: **155 passed**, 1 non-failing SlowAPI deprecation warning, 4.14 s. +- Frontend focused cloud/UI suite: **62 passed** across 6 files, 703 ms. +- Execution closeout evidence: backend 509 passed with one documented environment-only `libmagic` failure; frontend 323 passed; production build succeeded. +- Phase verification: `.planning/phases/12-cloud-resource-foundation/12-VERIFICATION.md` status `passed`, 12/12 must-haves verified with one documented package-lock tracking override. --- ## Validation Sign-Off -- [x] All proposed implementation tasks have an automated verification route or Wave 0 dependency. -- [x] Sampling continuity: no three consecutive tasks may occur without automated verification. -- [x] Wave 0 identifies every currently missing focused test/fixture. +- [x] Every Phase 12 requirement has targeted automated verification. +- [x] Every executed task has automated or explicit source/security evidence. +- [x] Sampling continuity contains no three-task gap. +- [x] Wave 0 files and fixtures exist. - [x] Commands use one-shot test modes, not watch mode. -- [x] Focused feedback target is under 60 seconds. +- [x] Focused feedback latency is below 60 seconds. - [x] `nyquist_compliant: true` is set in frontmatter. -**Approval:** pending plan-checker validation +**Approval:** approved 2026-06-19