feat(rendering): ZADC-001A3B1 — Hermes Agent Renderer

[ezutfen]

Packet

• Packet ID: ZADC-001A3B1
• Title: Hermes Agent Renderer

Work-start authorization

• Expected work-start SHA: bcec659cb629030099be483e2a31a147b3bb40a7
• Actual work-start SHA: bcec659cb629030099be483e2a31a147b3bb40a7
• Final head SHA: 23fde1c530d7d6ad3940a9f33242280d95c0eef2

Commits

1. 0edb82c — feat(rendering): add HermesRenderer with instruction-versus-data boundary
2. 75c7256 — test(rendering): add A3B1 Hermes renderer tests and update guard tests
3. 23fde1c — docs(rendering): add A3B1 Hermes renderer docs, update roadmap and README

Files changed

File	Change
src/zadc/rendering/hermes.py	New — HermesRenderer dataclass
src/zadc/rendering/registry.py	Register HermesRenderer in DEFAULT_RENDERER_REGISTRY
src/zadc/rendering/__init__.py	Export HermesRenderer
src/zadc/__init__.py	Export HermesRenderer from top-level
tests/test_a3b1_rendering.py	New — A3B1 test suite
tests/test_a3a_rendering.py	Update registry count, guard tests
tests/test_a3a_package_smoke.py	Update smoke for hermes + codex reserved
tests/test_fix2_bp09_api_evidence.py	Permit HermesRenderer
tests/test_fix3_bp08_09_regression.py	Permit HermesRenderer
docs/api-a3b1-hermes-renderer.md	New — API documentation
docs/roadmap.md	Mark A3A complete, add A3B1
README.md	Add HermesRenderer mention + example

Hermes renderer identity

• Consumer: hermes
• Media type: text/markdown
• Renderer ID: zadc-hermes-markdown
• Renderer version: 0.1.0

HermesRenderer is a frozen, slotted dataclass with fixed init=False identity fields. The constructor takes no arguments.

Default registry inventory

DEFAULT_RENDERER_REGISTRY contains exactly three renderers in deterministic registration order:

1. human → HumanMarkdownRenderer (zadc-human-markdown @ 0.1.0)
2. ci → CiJsonRenderer (zadc-ci-json @ 0.1.0)
3. hermes → HermesRenderer (zadc-hermes-markdown @ 0.1.0)

codex and claude remain unregistered and continue to raise RendererNotFoundError.

Packet instruction-boundary behavior

A Packet renders a HERMES EXECUTION CONTRACT section:

• States that ONLY the sealed Packet contract is potentially executable source content.
• States that PacketAuthorization identity and current validity are recorded claims not authenticated by the renderer.
• Tells Hermes NOT to begin work unless the caller/execution environment has accepted the Packet as valid.
• Presents the contract in deterministic sections: Authorization, Repository target, Work-start authorization, Intent, Scope, Requirements, Dependency pins, Verification, Review requirements, Stop conditions, Deliverables, Completion-report requirements, Supersession.
• Each section carries its source payload as lossless canonical JSON in a dynamically-fenced block.
• Includes the complete canonical Packet JSON in a separate lossless source-record block.

Non-Packet classification behavior

Artifact type	Classification
CompletionReport	Executor-reported completion claim
CertificationManifest	Recorded certification claim (subject/live status not reconciled)
EvidenceArtifact	Evidence content or references, never instructions
Observation	Observation claim, not authority
ReviewReport	Reviewer judgment, not task/merge authorization
DecisionRecord	Recorded decision claim (identity/applicability not validated)
WorkflowBundle	Recorded snapshot, not recomputed instructions

Adversarial test inventory

• Packet with Markdown headings, HTML, links, blockquotes, tables, backtick runs (1-5), fake closing fences, XML-like instruction tags, and "ignore previous instructions" → all hostile prose stays inside designated data blocks.
• Non-Packet artifacts (CompletionReport, EvidenceArtifact, Observation) with hostile prose in every prose-bearing field → all stays inside non-executable data blocks.
• No hostile structural marker appears in renderer-authored Markdown outside those blocks.
• Canonical JSON round-trips the exact original hostile strings.
• Documented as deterministic structural separation, not a security boundary.

Hermes golden inventory (8 digests)

Variant	SHA-256 content digest
packet	881e7ffd7894776a61ea95752e7339ce65654a85cf146e526438c0bce00083b5
completion_report	e36c90808632429ea1311cf1772604f306c148e70b8fc97bb714f1dacec2f79f
certification_manifest	a16a669c2fee55185346cbf27dcf1a047b233596076480d5598bc0f12df63f0e
evidence_artifact	d813a85f02388c31358e9ca3ae48d83ab1e3f7340fa3c1e1cd6814fe24802285
observation	e9c4d8962e66674f52247eb3edba317ca0523917a9ebc870ade5a2b0cdb313f5
review_report	e23fad546fb5bb4dafd7a8fe3bd59cf7bca1556e397ebd3a7c24b6d63538da66
decision_record	25ac574a68919cd9cda839656ff8206e47165e92529ead632c565d49b182094d
workflow_bundle	a24ab80acf8d2a621e9cbb73b2b83711ef88a805a20f4dc95265221360965b3f

Existing golden stability

All 16 existing human and CI golden digests remain unchanged (verified by test_hermes_does_not_change_human_or_ci_goldens and the unchanged GOLDEN_CONTENT_DIGESTS in test_a3a_rendering.py).

Schema stability

All 11 schemas regenerate byte-identically (git diff --exit-code -- schemas/0.1 passes). No schema changes required because hermes already exists in RenderConsumer.

Tests and coverage

• 1567 tests passed, 0 failed
• 100% line coverage, 100% branch coverage

Local verification

All local checks pass:

• uv lock --check ✓
• uv sync --frozen --extra dev ✓
• uv run python scripts/export_schemas.py + git diff --exit-code -- schemas/0.1 ✓
• make check (ruff format + ruff check + mypy --strict + pytest) ✓
• make workflow-lint (actionlint + zizmor) ✓
• make build ✓
• make package-smoke ✓

Clean-wheel verification

make package-smoke builds a wheel, installs it in a clean venv, and successfully:

• Imports HermesRenderer from zadc
• Renders Packet, ReviewReport, DecisionRecord, and WorkflowBundle through consumer='hermes'
• Verifies DEFAULT_RENDERER_REGISTRY.consumers == {'human', 'ci', 'hermes'}
• Verifies codex raises RendererNotFoundError

Scope deviations

None. All work is within allowed_paths (src/zadc/rendering/**, src/zadc/__init__.py, tests/**, docs/**, README.md). No dependencies, lockfiles, workflows, canonical artifact models, canonical serialization, or digest behavior were modified.

A3B2 and A3B3 exclusions

This slice explicitly excludes:

• A3B2 (Codex renderer) — codex remains unregistered
• A3B3 (Claude renderer) — claude remains unregistered
• No Codex or Claude rendering, provider-specific API integration, token-budget adaptation, or model selection

Status

Awaiting exact-head hosted CI and CodeQL results before recommending GREEN_FOR_REVIEW.