Skip to main content

Report Contract Engineering

Use when reconciling canonical reporting contracts. Build customer-facing reports from one pure, deterministic, typed data contract shared by PDF, presentation, spreadsheet, CSV, and UI renderers.

Core invariants​

  • Treat application-domain calculations as authoritative. Never alter canonical math, omit valid outcomes, weaken tests, or add fixture/customer branches merely to reproduce a contradictory sample.
  • A golden fixture is executable contract evidence, not an independent source of business truth. Correct it when it conflicts with canonical behavior, then retain exact deep-equality testing.
  • Construct fixture inputs independently from the expected fixture. Production code must never import the fixture or identify sample customers.
  • Keep transformation pure: no I/O, clock reads, locale defaults, network calls, or renderer-specific lookup inside the canonical transformation.
  • Require an explicit issuance timestamp as input. Validate strict real-calendar ISO UTC (not merely Date.parse), use it as the sole source of report/revision dates, and prove identical input is invariant under different ambient clocks.
  • Normalize time explicitly to the required zone (normally UTC), and make ordering explicit for every customer-visible collection.
  • The complete raw golden fixture must validate against the declared JSON Schema and deep-equal generated output without stripping fixture-only metadata.
  • Scope workloads before computing findings, errors, permissions, limitations, actions, totals, dashboards, or exports.

Contract-first sequence​

  1. Read every governing spec, schema, fixture, template, and report-review artifact before editing.
  2. Trace the application's canonical calculations and curation semantics, including manual verdicts, suppression, not-applicable states, errors, and unknown coverage.
  3. Write RED tests for disputed arithmetic and semantics before reconciling the fixture.
  4. Implement or correct the pure report-data transformation.
  5. Regenerate or hand-correct the expected fixture from independent typed inputs without losing meaningful content used by renderers.
  6. Validate exact fixture equality plus focused semantic tests.
  7. Verify TypeScript interfaces, JSON schemas, runtime validators, documentation, and fixtures describe the same contract.
  8. Only then implement renderers and formatting. Every renderer consumes the same canonical object and must not recalculate facts.
  9. Run focused tests, full tests, typecheck, lint, production build, audit policy, and diff checks.
  10. Obtain exact-head independent review. Any mutation invalidates the verdict.

Canonical compliance and manual outcomes​

Define one effective-status function and reuse it everywhere.

  • A recorded manual Pass contributes to pass and evaluated totals.
  • A recorded manual Fail contributes to fail/evaluated totals and remediation output.
  • Manual Not applicable contributes to N/A, not evaluated.
  • Pending manual review remains manual-required/unknown and must not become reassuring coverage.
  • Suppressed findings appear only where the contract explicitly requires them, such as the full register.
  • Assert reconciliation equations and percentages directly; do not test only snapshots.

Error and permission causation​

Do not infer missing permissions from a resource's static resolvesWith suggestion alone.

  • Filter errors by selected workload first.
  • Classify permission failure only from confirmed code/message semantics.
  • Derive missingPermissions only from classified permission failures, then map, deduplicate, and deterministically sort.
  • Keep Appendix/error remediation suggestions available, but describe them as suggestions rather than proof of causation.
  • For neutral errors, use neutral inspect-address-retry guidance; never emit “grant 0 permissions.”
  • For mixed errors, use conditional wording: grant confirmed missing permissions where indicated and address other responses separately.
  • Reuse one derived coverage-action string across Limitations, Fix first, and Roadmap to prevent contradictory prose.
  • Give every Not collected register row authoritative Appendix pointers such as B-3 <full resource path>. Accept explicit stable finding/rule-to-error associations rather than guessing from text, and resolve pointers only after scope filtering and deterministic Appendix sorting.
  • Fail closed on missing, stale, out-of-scope, duplicate-key, empty, or duplicate-resource associations. Preserve all matching Appendix rows when duplicate errors share a resource; never use last-write-wins maps that silently lose evidence.
  • Run the representative golden input through every supported workload/WAF scope combination. For each result, assert every Not collected pointer resolves to an emitted in-scope Appendix row and that unselected-workload resource prefixes do not leak. Keep association resources in the finding's workload unless an explicit shared-dependency contract says otherwise.

Fixture quality​

A corrected fixture must remain useful for layout development. Preserve representative:

  • failures across severities and benchmarks;
  • manual pending, pass, fail, and N/A outcomes;
  • nullable and fallback evidence;
  • rich impact, remediation, effort, ownership, and review guidance;
  • collection errors of permission and non-permission classes;
  • long text and enough rows to exercise page breaks and tables;
  • stable UTC timestamps and deterministic ordering.

Do not replace rich fixture content with empty placeholders merely to make equality pass.

Schema parity​

Runtime behavior, TypeScript types, JSON Schema, specs, and fixtures must agree.

  • When runtime validation rejects whitespace, control characters, malformed separators, or size limits, encode the same constraints in JSON Schema.
  • Add schema-level tests that load the real schema pattern/limits and run the same valid/invalid boundary matrix as the runtime validator.
  • Document semantic derivation accurately, especially where static suggestions differ from proven causes.
  • Parse all changed JSON schemas as a gate.
  • Validate the complete raw fixture under the actual schema draft. If the schema is closed with additionalProperties: false, assert that fixture top-level keys exactly match declared properties; never hide drift by destructuring away $schema or other fixture-only fields before equality.

Paged HTML template layer​

Implement formatting only after the canonical contract and golden fixture are stable.

  • Port the approved reference template section by section; replace literals with escaped contract fields rather than redesigning it from memory.
  • Generate the contents list from sections actually rendered. Omit page-number columns when the renderer cannot provide reliable cross-references.
  • Keep the template pure and deterministic. It receives AssessmentReportData plus a narrow ReportAssets object and performs no DB, process, clock, locale-default, or network access.
  • Escape every attacker-influenced value, including evidence and collection-error text. Allow raw HTML only through small audited helpers for static fragments assembled from already-escaped values.
  • Validate asset URI schemes and dynamic attribute contexts; test text, attribute, URI, CSS, and script-breakout payloads separately. For data: image inputs, use an explicit MIME allowlist, require base64 encoding, impose a size bound, and reject SVG/HTML even when base64-encoded.
  • Bundle fonts, marks, and wordmarks locally with their licenses. Record source URLs and checksums; never depend on CDN access during rendering.
  • Preserve print constraints explicitly: Letter @page, header/footer clearance, repeating table headers, row/card break avoidance, heading orphan control, and long-string wrapping.
  • Compute the printable box from page size minus margins. Use box-sizing: border-box; any cover/min-height plus padding must fit inside that box. Treat table widths as a budget: declared columns must total at most 100%, and test the width sum to prevent silent horizontal clipping.
  • Treat customer-facing explanatory prose as part of the factual contract. A template must not turn neutral collection errors into permission/identity failures; use conditional wording such as “when confirmed” and preserve null remediation suggestions as blank/unknown rather than asserted causes.
  • Add per-section snapshots keyed by stable data-section attributes plus semantic assertions for omitted sections, scope isolation, placeholders, unresolved tokens, internal enums, null, and undefined.
  • Header/footer templates are separate security boundaries because Chromium renders them independently; embed only validated data URIs or escaped text and use native pageNumber/totalPages spans.
  • Template tests and static HTML inspection do not establish visual/PDF acceptance. Do not claim page fit, font rendering, blank-page absence, or header/footer placement until a real browser/PDF render is captured and inspected.

Review discipline​

  • Review from a clean detached worktree at the exact immutable candidate head and explicit base.
  • Give the reviewer read-only access to existing dependencies when available; do not rely on supplied receipts.
  • Require severity-ranked findings, acceptance disposition, commands/results, residual risks, and an exact verdict.
  • Remediate each finding with a regression test when behavior is involved; documentation-only mismatches still require a parity check.
  • Do not push or mark ready until exact-head review approves and final verification applies to that same head.
  • A reviewer that completes commands but exits without the required final verdict produced no verdict. Preserve its evidence, then run one fresh bounded retry against the same clean detached head; scope the retry to the prior report and exact delta rather than resuming an oversized session or repeating broad archaeology.
  • After pushing a reviewed remediation, read the PR head back from the remote API before launching exact-head review or claiming CI applies. Provider views can lag briefly after push.
  • Remove untracked agent/supervisor artifacts before identity and clean-state gates; never include those files in the product commit.

Supporting references​

Supporting files: this skill's supporting files are held in the docsite at docs/15-skills/_support/engineering/report-contract-engineering/ — fetch them fresh from jknash/docsite main alongside this page. Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/engineering/report-contract-engineering/ · view source · Imported 2026-10-04. Supporting files (references, scripts) remain in the source repository.

Published by Muse · 2026-10-04.