# Concurrent clinic-cli evidence writes

## Current Design

- `clinic-cli` data commands persist raw evidence under `evidences/*.json`.
- The same commands also merge a compact view into `evidences/workspace_evidence_report.json`.
- Backend postpass reads `workspace_evidence_report.json` and writes authored `analysis` plus `analysis_patch.json`.
- These writes currently use read-modify-write JSON updates without a workspace-level interprocess lock.

## Risks

- Concurrent commands that write the same raw file can lose one command's rows.
- Concurrent commands that write different evidence kinds can still overwrite the shared report.
- Backend postpass can race with CLI report writes and produce analysis from a partial snapshot.
- Download commands can also collide on binary output paths or unzip directories when different keys share the same filename.

## Target Contract

- Parallel Clinic data fetches are allowed.
- Within one workspace, evidence file writes are serialized at the file layer.
- The canonical source of truth remains workspace files under `evidences/`.
- `workspace_evidence_report.json` stays compact; raw metric chart data remains in `metrics.json`.
- Download artifacts are written atomically and use identity-specific paths for different payloads.
- No stdout fallback or frontend inference is introduced.

## Implementation Steps

1. Add a shared workspace evidence lock file at `evidences/.workspace_evidence.lock`.
2. Wrap `clinic-cli` raw evidence merge and compact report update in that lock.
3. Wrap backend authored-analysis merge in the same lock.
4. Write JSON through temp-file plus atomic replace to avoid partial reads.
5. Write downloaded files through temp-file plus atomic replace, and avoid shared output names for distinct downloads.
6. Add concurrent-write contract tests for raw and compact evidence.

## Verification Checklist

- `clinic-cli` concurrent metric writes keep all metric rows.
- Concurrent metric/log style writes keep both compact report sections.
- Diagnostic downloads with the same base filename but different keys keep distinct artifact paths.
- Backend analysis merge preserves existing raw evidence and writes `analysis_patch.json`.
- Targeted pytest suite passes.