docs(14.1): create phase plan — cloud/local file parity hardening
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
curo1305
co-authored by
Claude Sonnet 4.6
Claude Sonnet 4.6
parent
4873a22f9b
commit
f50cce61cb
@@ -0,0 +1,183 @@
|
||||
---
|
||||
phase: 14.1-cloud-local-file-parity-hardening
|
||||
plan: 05
|
||||
type: execute
|
||||
wave: 5
|
||||
depends_on: [14.1-01, 14.1-02, 14.1-03, 14.1-04]
|
||||
files_modified:
|
||||
- backend/main.py
|
||||
- frontend/package.json
|
||||
- CLAUDE.md
|
||||
- README.md
|
||||
autonomous: false
|
||||
requirements: [CLOUD-02, ANALYZE-01, ANALYZE-02, ANALYZE-03, ANALYZE-04, ANALYZE-05, ANALYZE-06, ANALYZE-07, CACHE-03, CACHE-04, CACHE-05]
|
||||
must_haves:
|
||||
truths:
|
||||
- "Full backend and frontend test suites pass with zero failures"
|
||||
- "Security gate passes: owner/admin negatives, no credential/object_key/provider URL leakage, dependency audits clean"
|
||||
- "CLAUDE.md and README reflect the cloud detail parity surface, route, and force re-analyze"
|
||||
- "App version is bumped per protocol and committed atomically"
|
||||
artifacts:
|
||||
- path: "CLAUDE.md"
|
||||
provides: "Updated current-state line, shared module map (DocumentDetailSurface, cloud detail route/endpoint), non-negotiable parity rules"
|
||||
contains: "DocumentDetailSurface"
|
||||
- path: "backend/main.py"
|
||||
provides: "Bumped version"
|
||||
contains: "version="
|
||||
- path: "frontend/package.json"
|
||||
provides: "Bumped version matching backend"
|
||||
contains: "version"
|
||||
key_links:
|
||||
- from: "CLAUDE.md"
|
||||
to: "frontend/src/components/storage/DocumentDetailSurface.vue"
|
||||
via: "shared module map documents the shared detail surface"
|
||||
pattern: "DocumentDetailSurface"
|
||||
- from: "backend/main.py"
|
||||
to: "frontend/package.json"
|
||||
via: "version strings match"
|
||||
pattern: "version"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Close out Phase 14.1: run the full backend + frontend test suites, run the mandatory security gate (owner/admin negatives, credential/object_key/provider-URL leakage scan, dependency + secret audits), update CLAUDE.md and README for the cloud detail parity surface, bump the app version per protocol, and commit/push atomically.
|
||||
|
||||
Purpose: Satisfies the Mandatory Cross-Cutting Gates (tests pass, security gate, dependency audits, docs/version updates, atomic commit) and the CLAUDE.md Documentation/Testing/Security/Git protocols before Phase 14.1 is marked complete. This is the only plan that touches docs and versions (no implementation logic).
|
||||
Output: Green full suites, passed security gate, updated CLAUDE.md/README, bumped version, one atomic commit pushed.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@$HOME/.claude/gsd-core/workflows/execute-plan.md
|
||||
@$HOME/.claude/gsd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/14.1-cloud-local-file-parity-hardening/14.1-CONTEXT.md
|
||||
@.planning/phases/14.1-cloud-local-file-parity-hardening/14.1-RESEARCH.md
|
||||
@CLAUDE.md
|
||||
@README.md
|
||||
@backend/main.py
|
||||
@frontend/package.json
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Full test suites + security gate + dependency/secret audits</name>
|
||||
<read_first>
|
||||
- CLAUDE.md (Testing Protocol, Security Protocol, Security gate checklist — the exact gate commands)
|
||||
- backend/tests/test_cloud_security.py (owner/admin/no-leak coverage that must include the new detail endpoint and force re-analyze)
|
||||
- backend/tests/test_cloud_detail_parity.py and backend/tests/test_cloud_reanalyze_force.py (Plan 01 suites — must be GREEN now)
|
||||
- frontend/src/views/__tests__/CloudDetailParity.test.js and frontend/src/components/storage/__tests__/StorageBrowser.parity.test.js (Plan 01 frontend suites — must be GREEN now)
|
||||
- .planning/phases/14.1-cloud-local-file-parity-hardening/14.1-RESEARCH.md (Security Domain ASVS V4/V8/V12 targets; Package Legitimacy Audit: no new packages)
|
||||
</read_first>
|
||||
<action>
|
||||
Run the full backend suite (cd backend && python -m pytest -v) and the full frontend suite (cd frontend && npm run test or npx vitest run) — both MUST pass with zero failures; fix any regressions introduced by Plans 02-04 at root cause (≤50 lines per fix per CLAUDE.md; larger means a separate plan). Run the security gate per the CLAUDE.md Security gate checklist: bandit -r backend/ (zero HIGH), pip audit (zero critical/high), npm audit --audit-level=high (zero high/critical). Verify the cloud detail endpoint and force re-analyze path are covered by owner/admin-negative and no-leak assertions — if test_cloud_security.py does not yet exercise the new detail route and force enqueue, add focused negative tests there (foreign user 404, admin 403, response excludes credentials/object_key/provider URL). Run an executable secret scan over the diff (the repo's existing secret-scan approach, e.g. trufflehog/git secrets if configured) and confirm no credentials, tokens, provider URLs, or object keys are present in code, tests, or planning artifacts. Confirm no provider bytes are downloaded during browse/detail/estimate (the metadata-only invariant) by confirming the relevant cache/analysis contract tests pass. Do NOT install new packages (RESEARCH: none required) — if any audit flags an existing CVE, fix by version bump in a separate chore commit before this closeout commit.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd backend && python -m pytest -q 2>&1 | tail -8 && bandit -r backend/ -lll 2>&1 | tail -5 && cd ../frontend && npx vitest run 2>&1 | tail -8 && npm audit --audit-level=high 2>&1 | tail -5</automated>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- Backend full suite: `cd backend && python -m pytest -q` reports 0 failed.
|
||||
- Frontend full suite: `cd frontend && npx vitest run` reports 0 failed.
|
||||
- bandit -r backend/ reports 0 HIGH severity findings.
|
||||
- npm audit --audit-level=high reports 0 high/critical vulnerabilities.
|
||||
- test_cloud_security.py (or test_cloud_detail_parity.py) includes the detail-endpoint and force-enqueue owner/admin/no-leak negatives: `grep -nE 'detail|force' backend/tests/test_cloud_security.py backend/tests/test_cloud_detail_parity.py` shows coverage.
|
||||
- No secrets/object keys/provider URLs in the diff (secret scan clean).
|
||||
</acceptance_criteria>
|
||||
<done>Full backend + frontend suites pass; bandit/pip/npm audits clean; detail + force re-analyze covered by owner/admin/no-leak negatives; secret scan clean.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking">
|
||||
<name>Checkpoint: Human verification of cloud/local file parity</name>
|
||||
<action>Human verifies the cloud detail view, browser row parity, force re-analyze confirmation, and unsupported-preview-keeps-download behavior against a running app. See what-built and how-to-verify below.</action>
|
||||
<what-built>
|
||||
Cloud/local file parity: a cloud detail view (route cloud-file-detail) backed by CloudItem, shared DocumentDetailSurface used by local + cloud detail, browser row parity (topics + analysis status + Re-analyze/Retry slots), force re-analyze with confirmation, and unsupported-preview-keeps-download-explicit behavior.
|
||||
</what-built>
|
||||
<how-to-verify>
|
||||
1. Start the app: `docker compose up` (or backend `uvicorn main:app --reload` + frontend `npm run dev`).
|
||||
2. Log in, open /cloud, navigate into a connected provider folder.
|
||||
3. Click a cloud file row — confirm it opens a DETAIL view (URL contains /cloud/.../item/...), NOT an immediate preview or download.
|
||||
4. On an un-analyzed cloud file: confirm the detail shows "No analysis yet" + an "Analyze file" action; trigger Analyze and watch status progress.
|
||||
5. On an analyzed cloud file: confirm extracted text, topic badges, analysis status, and a "Re-analyze" action appear (NO "Re-classify" text anywhere).
|
||||
6. Click Re-analyze on a current file: confirm a confirmation dialog appears ("Re-analyze this file? Existing extracted text and topics stay visible…") and proceeding re-runs analysis without losing prior text/topics.
|
||||
7. On a file whose preview is unsupported: confirm "Preview unavailable" + reason shows and Download stays active and does NOT auto-download.
|
||||
8. Open a LOCAL document at /document/:id and confirm the detail layout (header, topics, extracted text, Re-analyze) matches the cloud detail layout.
|
||||
9. In the browser grid, confirm cloud rows show topic badges + analysis status in the same place as local rows.
|
||||
</how-to-verify>
|
||||
<resume-signal>Type "approved" or describe any parity/behavior issues to fix</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Update CLAUDE.md + README, bump version, atomic commit + push</name>
|
||||
<read_first>
|
||||
- CLAUDE.md (Current state line in GSD Workflow section; shared module map tables backend + frontend; Documentation Protocol; Git Protocol; version bump rule)
|
||||
- README.md (Features section, env var table, version reference)
|
||||
- backend/main.py (FastAPI version="0.4.0")
|
||||
- frontend/package.json ("version": "0.4.0")
|
||||
- .planning/ROADMAP.md (Phase 14.1 plan checklist to tick)
|
||||
</read_first>
|
||||
<action>
|
||||
Update CLAUDE.md: change the "Current state" line in the GSD Workflow section to record Phase 14.1 complete (cloud/local file parity: cloud detail route + view, shared DocumentDetailSurface, browser row parity, force re-analyze, unsupported-preview keeps download explicit). Add to the FRONTEND shared module map a row for frontend/src/components/storage/DocumentDetailSurface.vue (shared detail surface used by DocumentView and CloudDetailView) and note CloudDetailView.vue + the cloud-file-detail route as thin data providers. Add to the BACKEND shared module map the CloudItemDetailOut schema and resolve_owned_cloud_item_detail (owner-scoped cloud detail + topics, metadata-only), the GET .../items/{id}/detail route, and the force flag on enqueue. Add non-negotiable rules: visible copy says "Re-analyze" not "Re-classify"; cloud row click opens the cloud detail route (no auto preview/download); cloud detail resolution is metadata-only (no byte hydration); CloudItemDetailOut/CloudItemOut remain allowlists excluding object_key/credentials_enc/provider URL. Update README.md if any user-facing feature/route/behavior changed (add cloud file detail view + Re-analyze to the Features section; no new env vars expected). Bump the version: per CLAUDE.md protocol, Phase 14.1 is an inserted hardening phase shipping user-facing changes — bump the PATCH segment in backend/main.py (version="0.4.0" → "0.4.1") and frontend/package.json ("0.4.0" → "0.4.1") so both match. Tick the Phase 14.1 plan checkboxes in ROADMAP.md. Stage explicitly and commit atomically per CLAUDE.md Git Protocol: `git add backend/ frontend/ CLAUDE.md README.md .planning/` then commit `feat(14.1): cloud/local file parity — shared detail surface, cloud detail route, force re-analyze`, then push. Do NOT use git add -A.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd backend && grep -c 'version="0.4.1"' main.py && cd ../frontend && grep -c '"version": "0.4.1"' package.json && cd .. && grep -c 'DocumentDetailSurface' CLAUDE.md && grep -c 'Phase 14.1' CLAUDE.md</automated>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- backend/main.py version is "0.4.1": `grep -c 'version="0.4.1"' backend/main.py` returns 1.
|
||||
- frontend/package.json version is "0.4.1": `grep -c '"version": "0.4.1"' frontend/package.json` returns 1.
|
||||
- CLAUDE.md documents the shared surface and phase completion: `grep -c 'DocumentDetailSurface' CLAUDE.md` >= 1 and the Current state line references Phase 14.1.
|
||||
- CLAUDE.md adds the cloud detail backend symbols: `grep -cE 'CloudItemDetailOut|resolve_owned_cloud_item_detail' CLAUDE.md` >= 1.
|
||||
- ROADMAP Phase 14.1 plans are checked off and a single atomic commit exists: `git log --oneline -1` shows the feat(14.1) message.
|
||||
- The commit is pushed (git status shows clean / ahead-by-0 after push).
|
||||
</acceptance_criteria>
|
||||
<done>CLAUDE.md + README updated, both versions bumped to 0.4.1, ROADMAP ticked, one atomic feat(14.1) commit created and pushed.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| diff → repo | committed code/tests/docs must contain no secrets, tokens, provider URLs, or object keys |
|
||||
| dependency tree → app | audits must show no high/critical CVEs |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|-------------|-----------------|
|
||||
| T-14.1-13 | Information Disclosure | committed artifacts | mitigate | Secret scan over diff; no credentials/object_key/provider URL in code/tests/planning |
|
||||
| T-14.1-14 | Tampering / Vulnerable deps | dependency tree | mitigate | bandit + pip audit + npm audit gate; no new packages added |
|
||||
| T-14.1-15 | Elevation of Privilege | detail + force endpoints (regression) | mitigate | Security gate re-runs owner/admin negatives on the new surfaces |
|
||||
| T-14.1-SC | Tampering | npm/pip installs | accept | No package installs this phase (RESEARCH Package Legitimacy Audit: none) |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- `cd backend && python -m pytest -q` → 0 failed; `cd frontend && npx vitest run` → 0 failed.
|
||||
- `bandit -r backend/ -lll`, `pip audit`, `npm audit --audit-level=high` → clean.
|
||||
- Versions match at 0.4.1; CLAUDE.md + README updated; ROADMAP ticked; atomic commit pushed.
|
||||
- Human checkpoint approved for visual/interaction parity.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- All gates green (tests, security, audits, secret scan).
|
||||
- Docs + versions updated and committed atomically; pushed.
|
||||
- Human verification of cloud/local parity approved.
|
||||
</success_criteria>
|
||||
|
||||
<artifacts_produced>
|
||||
## Artifacts this phase produces (Plan 05)
|
||||
|
||||
- Version bump: backend/main.py and frontend/package.json → 0.4.1.
|
||||
- Docs: CLAUDE.md updated (current-state line, shared module maps for DocumentDetailSurface + CloudItemDetailOut/resolve_owned_cloud_item_detail + cloud detail route, new non-negotiable parity rules); README Features section updated.
|
||||
- ROADMAP: Phase 14.1 plan checkboxes ticked.
|
||||
- One atomic `feat(14.1)` commit, pushed.
|
||||
</artifacts_produced>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/14.1-cloud-local-file-parity-hardening/14.1-05-SUMMARY.md` when done
|
||||
</output>
|
||||
Reference in New Issue
Block a user