transcription/.github/skills/evidence-provenance-auditor/skill.md

name, description

name	description
evidence-provenance-auditor	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/ver4/schema_v4.md
3. docs/ver4/requirements_v4.md
4. docs/ver4/error_handling_v4.md
5. docs/ver4/history.md (archive boundary)
6. docs-v4x-archive tag (historical context only)

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.

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-G).

Output Format

Use this structure:

• Verdict by invariant family (A-G)
• Findings with Location, Observed Behavior, Risk, Recommended Fix
• Drift table (Doc claim vs Code reality vs Action)
• Regression guards needed