generated from john/python-template
81 lines
3.0 KiB
Markdown
81 lines
3.0 KiB
Markdown
---
|
|
name: evidence-provenance-auditor
|
|
description: Deterministic reviewer for transcription evidence/provenance guarantees. Use when changes touch execution attempts, source storage, retries, transport evidence, artifact provenance, or evidence exports.
|
|
---
|
|
|
|
# Evidence & Provenance Auditor
|
|
|
|
Perform focused, deterministic audits of evidence integrity and provenance behavior.
|
|
|
|
## When to Use
|
|
|
|
- Reviewing changes in:
|
|
- `src/transcription/services/sources.py`
|
|
- `src/transcription/services/store.py`
|
|
- `src/transcription/services/workflows.py`
|
|
- `src/transcription/services/evidence.py`
|
|
- `src/transcription/db/models.py`
|
|
- Auditing evidence exports/imports or evidence-display behavior.
|
|
- Verifying no drift from canonical provenance invariants.
|
|
|
|
## Normative References (must be used)
|
|
|
|
1. `docs/invariant/ai_evidence_and_provenance.md`
|
|
2. `docs/schema.md`
|
|
3. `docs/requirements.md`
|
|
4. `docs/error_handling.md`
|
|
|
|
## Deterministic Pass/Fail Checks
|
|
|
|
### A. Append-only history
|
|
- Every provider call results in a new `ExecutionAttempt`.
|
|
- Runtime paths do not mutate historical attempts to represent new outcomes.
|
|
- Retry behavior appends attempts rather than rewriting prior rows.
|
|
|
|
### B. Projection vs authority separation
|
|
- `Source.raw_transcription` and preferred pointers are mutable projection surfaces.
|
|
- Attempt rows remain authoritative historical evidence.
|
|
- Candidate promotion updates projection pointers without rewriting history.
|
|
|
|
### C. Transport evidence semantics
|
|
- Transport evidence is correctly labeled as application-boundary capture.
|
|
- SDK snapshots/normalized metadata are not mislabeled as native upstream payload.
|
|
- No-response timeout/network states are explicit.
|
|
|
|
### D. Canonical source identity
|
|
- Canonical stored bytes/hash/size are internally consistent.
|
|
- If ingest normalization is applied, code/docs consistently represent resulting canonical identity.
|
|
- Post-ingest derivatives do not overwrite canonical source bytes.
|
|
|
|
### E. Secret safety
|
|
- No credentials/auth headers/cookies/unrestricted headers persisted.
|
|
- Header persistence uses explicit allowlist semantics.
|
|
|
|
### F. Route/path safety
|
|
- Print/export source access is record-validated.
|
|
- UI/media path construction does not expose local filesystem paths.
|
|
|
|
### G. Schema/docs alignment
|
|
- Evidence-related model fields and semantics align with canonical docs.
|
|
- Evidence model changes require same-change doc updates.
|
|
|
|
### H. Canonical authority boundaries
|
|
- Active guidance resolves against `docs/*` and current instruction files.
|
|
|
|
## Review Workflow
|
|
|
|
1. Read normative references first.
|
|
2. Inspect model + service + workflow write paths.
|
|
3. Inspect evidence read/display/export paths.
|
|
4. Report high-confidence findings with concrete path/line evidence.
|
|
5. Classify each finding by invariant family (A-H).
|
|
|
|
## Output Format
|
|
|
|
Use this structure:
|
|
|
|
- Verdict by invariant family (A-H)
|
|
- Findings with `Location`, `Observed Behavior`, `Risk`, `Recommended Fix`
|
|
- Drift table (`Doc claim` vs `Code reality` vs `Action`)
|
|
- Regression guards needed
|