gpt-5.3-codex review phase 2 - update instructions & skills

2026-08-19 18:22:06 -05:00
parent c261fbb3bd
commit b6a5a89a84
7 changed files with 187 additions and 28 deletions
@@ -0,0 +1,79 @@
+---
+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/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
@@ -39,7 +39,10 @@ When reviewing this repository, always include explicit pass/fail checks for:
 2. **UI boundary rule:** pages/components do not perform persistence access (`tests/test_ui_boundaries.py`).
 3. **Status vocabulary conformance:** `JobStatus`/`JobSourceStatus` usage matches current enums in `src/transcription/db/models.py`.
 4. **Evidence ownership conformance:** append-only attempt history is preserved and projection writes are not mistaken for history mutation (`src/transcription/services/sources.py`, `src/transcription/services/evidence.py`).
-5. **Canonical V4 authority:** findings must resolve against `docs/ver4/*` first, and treat `docs/ver4/history.md` plus `docs/ver4.x/*` as historical context.
+5. **Canonical V4 authority:** findings must resolve against `docs/ver4/*` first, and treat `docs/ver4/history.md` plus `docs-v4x-archive` as historical context.
+6. **Media boundary conformance:** print/export media is record-validated and UI media URL generation uses controlled resolver paths.
+7. **Eager-loading conformance:** service/UI read paths satisfy `lazy="raise"` expectations.
+8. **Cross-cutting error conformance:** service/API/UI translation and retry behavior align with `.github/instructions/error-handling.instructions.md`.

 ## Core Review Areas