File upload: progress, validation, and recovery

# Apply the “File upload: progress, validation, and recovery” guide in your agent

## Objective
An upload workflow connects a labeled native file picker to a transfer service, server validation, and controlled storage. Show measured transfer progress separately from server processing, and define cancellation and retry outcomes. The atlas documents this workflow; its UI components do not provide an upload service.

## Prerequisites
- Inspect the repository, documentation, and existing conventions.
- Confirm the need matches the guide scope: Specify file selection, trustworthy progress, server checks, storage permissions, cancellation, and retry.
- Preserve the correct decisions already in place.

## Guide steps
- 1. 1. Define the service boundary — An upload workflow needs a native file picker, a transfer service, server validation, and controlled storage. A button and progress bar only present actions and state; this guide does not add an upload service to the atlas.
- 2. 2. Make selection usable — Provide a labeled input type="file", visible format and size instructions, and a separate upload action. Keep native keyboard access; drag-and-drop may supplement it. Show the selected filename as text, size, and an explicit remove or replace action. Dismissing the picker must leave the current selection coherent.
- 3. 3. Separate transfer from processing — Define selected, transferring, checking, ready, rejected, interrupted, and canceled states. Derive a percentage only from a measurable byte total, for example upload progress events with lengthComputable. If the total is unknown, show indeterminate progress with a useful text label rather than inventing a percentage.
- 4. 4. Enforce acceptance on the server — Authenticate and authorize the operation. Enforce count and size limits, allowlisted extensions and inspected file content; do not trust a client MIME type or filename. Generate storage names, isolate files from executable web content, and apply malware scanning or content disarm where appropriate. Protect cookie-authenticated upload endpoints against CSRF.
- 5. 5. Cancel, retry, and verify — Cancellation stops the active client request where supported; it does not prove deletion of bytes already stored. Have the backend cancel or expire the upload session and report the final status. On interruption, keep metadata and offer retry; do not claim resumable transfer unless the protocol implements it. A reload can require selecting the file again.
- 6. Check the file behind the filename — In a test environment, submit a harmless text fixture renamed with an allowed image extension. The server must apply its documented type and content checks instead of trusting the browser’s selection filter or the supplied Content-Type.

## Acceptance criteria — Evidence to keep
- Ready follows server validation and storage confirmation.
- Cancel and retry have verified backend outcomes.
- Private retrieval and rejection rules are tested independently of UI.
- File selection, replacement, and removal are reachable using only the keyboard.
- Unknown byte totals show indeterminate progress instead of a fabricated percentage.
- Oversized and misleadingly named fixtures receive a specific rejection and a next action.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

• Requires · The real project context: repository, documentation, and existing constraints

# Anchor the guide in the project

## Objective
Turn the applied steps into durable repository conventions.

## Checks
- Link each decision made to the guide step that justifies it.
- Add the checklist to the relevant reviews.
- Record out-of-scope cases for the neighboring guides.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

sha256:5dffee3f0cee67ffa97dea65d04c63698642ce16f0e6f3cd8170aa03c57318e8

# Diagnose a failed application of the “File upload: progress, validation, and recovery” guide

## Observed symptom
[DESCRIBE THE SYMPTOM HERE]

## Observable checks
- Replay the steps in order and note the first one that diverges:
- 1. 1. Define the service boundary — An upload workflow needs a native file picker, a transfer service, server validation, and controlled storage. A button and progress bar only present actions and state; this guide does not add an upload service to the atlas.
- 2. 2. Make selection usable — Provide a labeled input type="file", visible format and size instructions, and a separate upload action. Keep native keyboard access; drag-and-drop may supplement it. Show the selected filename as text, size, and an explicit remove or replace action. Dismissing the picker must leave the current selection coherent.
- 3. 3. Separate transfer from processing — Define selected, transferring, checking, ready, rejected, interrupted, and canceled states. Derive a percentage only from a measurable byte total, for example upload progress events with lengthComputable. If the total is unknown, show indeterminate progress with a useful text label rather than inventing a percentage.
- 4. 4. Enforce acceptance on the server — Authenticate and authorize the operation. Enforce count and size limits, allowlisted extensions and inspected file content; do not trust a client MIME type or filename. Generate storage names, isolate files from executable web content, and apply malware scanning or content disarm where appropriate. Protect cookie-authenticated upload endpoints against CSRF.
- 5. 5. Cancel, retry, and verify — Cancellation stops the active client request where supported; it does not prove deletion of bytes already stored. Have the backend cancel or expire the upload session and report the final status. On interruption, keep metadata and offer retry; do not claim resumable transfer unless the protocol implements it. A reload can require selecting the file again.
- 6. Check the file behind the filename — In a test environment, submit a harmless text fixture renamed with an allowed image extension. The server must apply its documented type and content checks instead of trusting the browser’s selection filter or the supplied Content-Type.

## Possible causes
- A step was skipped or executed out of order.
- The actual need falls outside the guide scope.
- A checklist criterion was never verified.

## Bounded fixes
- Redo only the diverging step and what depends on it.
- Document the gap if the guide scope does not cover the need.

## Final verification — Evidence to keep
- Ready follows server validation and storage confirmation.
- Cancel and retry have verified backend outcomes.
- Private retrieval and rejection rules are tested independently of UI.
- File selection, replacement, and removal are reachable using only the keyboard.
- Unknown byte totals show indeterminate progress instead of a fabricated percentage.
- Oversized and misleadingly named fixtures receive a specific rejection and a next action.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

• Requires · The real project context: repository, documentation, and existing constraints

# Prevent the next drift

## Objective
Turn the first diverging step into an explicit project check.

## Checks
- Add a focused check on the step that diverged.
- Verify the checklist on a second real case.
- Document the scope limit you hit.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

sha256:7985ecc7a247bed01050b4e0a2ded236fbe28fa538ccf8c435742c700f704fd3