---
phase: "13"
plan: "06"
type: execute
wave: 4
depends_on:
  - "13-05"
files_modified:
  - backend/api/cloud/operations.py
  - backend/services/cloud_operations.py
  - backend/services/cloud_items.py
  - backend/tests/test_cloud_mutations.py
  - backend/tests/test_cloud_audit.py
autonomous: true
requirements:
  - CLOUD-03
  - CLOUD-09
must_haves:
  truths:
    - "Successful cloud upload does not return before authoritative metadata reconciliation completes."
    - "Upload success writes metadata-only audit rows, while skipped, canceled, or failed queue decisions stay silent."
    - "Upload freshness and navigation updates still route through `cloud_items.py` rather than a second reconcile path."
  artifacts:
    - path: "backend/services/cloud_operations.py"
      provides: "Authoritative upload success handling that routes back through centralized reconciliation and audit helpers."
    - path: "backend/services/cloud_items.py"
      provides: "Stable folder freshness and item identity updates after upload success."
  key_links:
    - from: "authoritative upload success"
      to: "cloud_items reconciliation"
      via: "service-layer follow-through before response return"
      pattern: "upload"
    - from: "authoritative upload success"
      to: "metadata-only audit rows"
      via: "same-transaction audit helper call"
      pattern: "cloud.item"
---

<objective>
Finish the bounded upload follow-through slice of Phase 13: reconcile successful uploads immediately, refresh affected folder state truthfully, and emit metadata-only audit rows only on authoritative success.

Purpose: Complete `CLOUD-09` for uploads before the shared frontend queue is wired to the backend.
Output: Passing upload reconciliation and audit suites with no duplicate reconcile path.
</objective>

<execution_context>
@$HOME/.codex/gsd-core/workflows/execute-plan.md
@$HOME/.codex/gsd-core/templates/summary.md
</execution_context>

<context>
@AGENTS.md
@.planning/phases/13-virtual-local-cloud-operations/13-CONTEXT.md
@backend/api/cloud/operations.py
@backend/services/cloud_operations.py
@backend/services/cloud_items.py
@backend/services/audit.py
@backend/tests/test_cloud_mutations.py
@backend/tests/test_cloud_audit.py
</context>

## Artifacts this phase produces

- Upload success follow-through in `backend/services/cloud_operations.py`.
- Authoritative upload reconciliation and folder freshness updates through `backend/services/cloud_items.py`.
- Passing upload mutation and audit suites for `CLOUD-03` and `CLOUD-09`.

## Pattern analogs

- `backend/services/cloud_items.py` — single reconciliation and freshness authority.
- `backend/services/audit.py` — metadata-only audit helper used inside the caller transaction.

<tasks>

<task type="auto" tdd="true">
  <name>Task 1: Route authoritative upload success through centralized reconciliation before returning</name>
  <files>backend/api/cloud/operations.py, backend/services/cloud_operations.py, backend/services/cloud_items.py, backend/tests/test_cloud_mutations.py</files>
  <read_first>
    - backend/services/cloud_operations.py
    - backend/services/cloud_items.py
    - backend/tests/test_cloud_mutations.py
    - .planning/phases/13-virtual-local-cloud-operations/13-CONTEXT.md
  </read_first>
  <behavior>
    - Test 1: successful upload updates current-folder navigation through centralized reconciliation before success returns
    - Test 2: upload freshness state stays truthful and does not bypass `cloud_items.py`
    - Test 3: failed, skipped, and canceled queue decisions do not mutate listing freshness as success
  </behavior>
  <action>
    Feed authoritative upload success back through `backend/services/cloud_items.py` immediately, update affected folder freshness truthfully, and keep stable row identity for the newly visible item before the route returns success. Do not bypass centralized reconciliation, do not mutate quota, and do not let skipped or canceled queue decisions look like successful overwrites.
  </action>
  <acceptance_criteria>
    - upload mutation suites pass with reconcile-before-return behavior
    - navigation refresh is tied to authoritative success only
    - upload follow-through still uses the single shared reconciliation path
  </acceptance_criteria>
  <verify>
    <automated>docker compose run --rm backend pytest -v tests/test_cloud_mutations.py -k "upload" -x</automated>
  </verify>
  <done>Successful uploads now refresh authoritative metadata and freshness before the API reports success.</done>
</task>

<task type="auto" tdd="true">
  <name>Task 2: Emit metadata-only audit rows only for authoritative upload success</name>
  <files>backend/services/cloud_operations.py, backend/tests/test_cloud_mutations.py, backend/tests/test_cloud_audit.py</files>
  <read_first>
    - backend/services/cloud_operations.py
    - backend/services/audit.py
    - backend/tests/test_cloud_audit.py
    - .planning/phases/13-virtual-local-cloud-operations/13-CONTEXT.md
  </read_first>
  <behavior>
    - Test 1: successful upload writes metadata-only audit rows in the caller transaction
    - Test 2: failed, skipped, canceled, and retry-needed queue outcomes do not produce false success audit events
    - Test 3: audit rows never include provider URLs, tokens, bytes, or document text
  </behavior>
  <action>
    Write metadata-only audit rows in the same request transaction only after authoritative upload success has reconciled metadata. Preserve the Phase 13 secrecy rules by keeping provider URLs, tokens, decrypted credentials, bytes, and document content out of the audit payload. Treat Skip, Cancel all, retryable error, and conflict-pause outcomes as non-success paths that must not emit a success audit event.
  </action>
  <acceptance_criteria>
    - upload audit suites pass
    - audit behavior is tied to authoritative success only
    - no upload audit row includes provider URLs, tokens, bytes, or document text
  </acceptance_criteria>
  <verify>
    <automated>docker compose run --rm backend pytest -v tests/test_cloud_mutations.py tests/test_cloud_audit.py -k "upload or audit" -x</automated>
  </verify>
  <done>Upload success now satisfies the metadata refresh and metadata-only audit half of `CLOUD-09`.</done>
</task>

</tasks>

<threat_model>
## Trust Boundaries

| Boundary | Description |
|----------|-------------|
| upload success → metadata state | Only authoritative success may update cloud metadata or folder freshness. |
| upload success → audit log | Only authoritative success may write an audit row, and it must stay metadata-only. |

## STRIDE Threat Register

| Threat ID | Category | Component | Disposition | Mitigation Plan |
|-----------|----------|-----------|-------------|-----------------|
| T-13-19 | T | upload reconciliation | mitigate | Mutation tests require reconcile-before-return and forbid success-state bypasses. |
| T-13-20 | I | upload audit payloads | mitigate | Audit suites verify metadata-only rows for successful uploads only. |
| T-13-21 | R | queue decision logging | mitigate | Tests require Skip, Cancel all, conflict-pause, and retry-needed outcomes to avoid false success events. |
</threat_model>

<verification>
- Pass the upload mutation and audit suites.
- Confirm every backend pytest invocation is a direct `docker compose run --rm backend pytest ...` command.
- Confirm upload success routes through centralized reconciliation before audit and before response return.
</verification>

<success_criteria>
- Successful uploads refresh navigation and folder freshness through the shared reconciliation layer.
- Successful uploads produce metadata-only audit rows promptly enough to satisfy `CLOUD-09`.
- The upload follow-through plan stays bounded to 5 files and does not absorb the frontend queue work.
</success_criteria>

<output>
Create `.planning/phases/13-virtual-local-cloud-operations/13-06-SUMMARY.md` when done
</output>