Skip to main content

Normative contract compilation

Use when compiling prose into normative contracts. Compile review findings and narrative specifications into one coherent, executable contract set. Treat a green parser as the beginning of verification, not the result.

Procedure​

  1. Establish authority and scope before editing. Record the source order (review correction, prior decisions, contract guide, owning specs), exact writable paths, minimum preserved operation/schema surface, and required verification command. Read every authoritative source in full. Do not reconcile narrative outside the allowed scope during a contract-first pass.
  2. Inventory both structure and literals. Index the repository before structural exploration; use graph search/snippets/traces for code dependencies and direct file reads/search for YAML, JSON, Markdown, fixtures, SQL, and exact vocabulary. Check index coverage for every relied-on path and bounded scope; directly read flagged ranges before making completeness claims.
  3. Define canonical authorities once. Put organization identity, compatibility windows, idempotency outcomes, queue registry, secret lifecycle, aggregate ownership, and recovery measurement in one machine-readable owner each. Other contracts reference that authority and the validator rejects divergent copies.
  4. Change owning contracts atomically. Update OpenAPI, MCP disposition, JSON Schemas, state machines, database constraints, fixtures, and contract guide in one pass. Preserve the prior public surface unless a binding correction explicitly requires removal. Add operations rather than weakening a finding through omission.
  5. Generate dependent artifacts from final source bytes. Finish OpenAPI mutations first, write deterministic bytes, compute SHA-256, then regenerate every MCP row and top-level digest. Any later OpenAPI edit requires recomputing all embedded digests. For list operations, bind MCP output to the exact OpenAPI items + meta wrapper, never the item schema.
  6. Encode authority and security mechanically. Separate delegated and application credential schemes; list operation-specific alternatives. Machine paths require both an app role and an application-side organization grant. Human-only operations accept no machine scheme and expose a typed initiation/status/safe-cancel/terminal-result handoff that resumes the same durable operation on first-party HTTPS.
  7. Make examples executable. Every request, success response, and typed error gets a schema-valid example. Validate formats, conditional branches, discriminators, uniqueItems, and exact required fields—not only $ref existence. Generate examples deterministically, then hand-fix constraints a generic generator cannot infer.
  8. Prove semantics with adversarial fixtures. Add positive and negative fixtures for every review class: nested secret paths, binding/rebind attacks, cross-organization omission, concurrent uniqueness, illegal lifecycle transitions, unsupported idempotency combinations, stale digest/parity, limit boundaries, and malformed examples. The validator must execute these fixtures and prove rejection or acceptance for the intended reason.
  9. Run the complete verification loop. Run the semantic compiler to exit zero, syntax-compile the validator, run git diff --check, and run the compiler twice to confirm deterministic output. Re-index after edits and repeat graph coverage checks against the final generation. If a documented wrapper command is absent, report that fact; do not imply it ran.
  10. Report receipts, not process. Give changed contract classes, exact fresh validator counts/output, additional gates, coverage caveats, and whether a commit was created. Keep the final report concise.

Pitfalls​

  • Inspect git diff after any delegated worker exits, even on failure—the worker may have written a valid partial artifact before reporting the blocker.
  • Detect concurrent edits before overwriting by comparing the diff hash across a short stable interval and re-reading stale files—the last writer can silently erase another worker's stronger checks.
  • Reject parse/count-only validators—they allow semantically incompatible contracts to remain green.
  • Recompute canonical digests only after serialization is final—formatting changes alter the bytes even when parsed data is equal.
  • Validate organization binding on direct request, success, error, wrapper, and item schemas—checking route parameters alone does not prove payload isolation.
  • Model sensitive payload rejection recursively—top-level forbidden-field checks miss nested credentials, prompts, temporary URLs, and PII.
  • Assert database uniqueness in both invariant text and concrete partial-index/test contracts—application compare-and-set alone does not prevent replica races.

For a reusable semantic closure matrix, read references/semantic-gates.md.

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

Published by Muse · 2026-10-04.