Skip to content

docs(evidence): refresh EVIDENCE.md to v0.6.4 semantics + freshness tripwire#89

Merged
ericckzhou merged 1 commit into
devfrom
docs/evidence-protocol-freshness
Jun 7, 2026
Merged

docs(evidence): refresh EVIDENCE.md to v0.6.4 semantics + freshness tripwire#89
ericckzhou merged 1 commit into
devfrom
docs/evidence-protocol-freshness

Conversation

@ericckzhou

Copy link
Copy Markdown
Owner

@
Refreshes the artifact-contract doc where pre-0.6 wording went stale, and adds a coarse anti-entropy tripwire so the contract cant silently drift again. No runtime behavior changes.

Why

docs/EVIDENCE.md is the artifact contract — the document external readers trust about what a replay artifact is and what its verdicts claim. Stale claims there are higher-risk than a stale claim anywhere else in the repo. Several load-bearing places still carried pre-0.6 wording.

Changes — docs/EVIDENCE.md

  • §4.5 — verdict-preservation list now carries all nine Verdict members (was a stale five), pointing to the §7 claim table.
  • §2 — restated as the producer / read-only-consumer split (run / minimize produce; replay, inspect, diff, history, timeline, matrix, verify, export consume), replacing a mislabeled "five operations" list that actually had six bullets. doctor named as a diagnostic, not a protocol operation. Full command enumeration deliberately deferred to ARCHITECTURE.md to keep this doc protocol-level.
  • §4.2 — materialized-spec lineage documents that paraphrase preserves validity_score / validity_method for each accepted rewrite.
  • §4.1cli_invocation provenance cross-linked to its existing §6 semantic boundary rather than duplicated.
  • §4.5 — clarifies semantic-oracle effects are preserved through the assigned verdict and existing case/judgment fields, not as a separate stored oracle-results payload.

New guard — tests/meta/test_evidence_doc_freshness.py

Coarse tripwire: every Verdict member and every read-only consumer must be named in the doc. The docstring is explicit that this is not a prose validator — a document-wide substring scan cannot catch intra-document inconsistency (e.g. a stale per-section list while §7 stays complete); that class stays a review concern.

Verification

  • uv run pytest tests/meta/ → 17 passed
  • uv run ruff check on the new test → clean
  • "five operations" phrase confirmed removed
    @

…ripwire

Refresh the artifact-contract doc where pre-0.6 wording went stale:

- §4.5: all nine Verdict members (was a stale five)
- §2: producer/read-only-consumer split (was a mislabeled 'five operations')
- §4.2: paraphrase lineage preserves validity_score/validity_method
- §4.1: cross-link cli_invocation provenance to its §6 semantic boundary
- §4.5: oracle effects preserved through the verdict, not a separate payload

Add tests/meta/test_evidence_doc_freshness.py: a coarse tripwire asserting every Verdict member and every read-only consumer is named in the doc. No runtime behavior changes.
@ericckzhou ericckzhou merged commit f3d90e7 into dev Jun 7, 2026
1 check passed
@ericckzhou ericckzhou deleted the docs/evidence-protocol-freshness branch June 7, 2026 21:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant