Skip to main content

Contract Governance

Documentation Map​

Contract Governance

Tool / Contract Summary​

This page explains how jhf-fabric owns and publishes contract truth. It is the documentation counterpart to the machine-readable artifacts in contracts/ and the route families under /api/v1/contracts/*.

Business Value​

  • keeps contract and policy truth deterministic across JHF repositories
  • gives downstream consumers a read-only source for governance, compatibility, and lifecycle posture
  • prevents local shadow logic for identity, access, readiness, and rollout decisions

Current Verified State​

The repository publishes:

  • registry, family, schema, and matrix artifacts under contracts/
  • contract-facing route families under /api/v1/contracts/*
  • governance and drift artifacts used by operators, CI, and downstream repos

Available Now​

Implemented contract/governance areas:

  • schema governance registry, family catalog, schema catalog, and producer/consumer matrix
  • contract drift reporting and compatibility checking
  • admission dry-run inputs and compatibility semantics
  • JARVIS adoption and closure posture
  • federation posture and provider federation posture
  • docs and wiki governance standards
  • entitlement policy and runtime memory claims policies
  • event catalog and async contract publication

Optional / Extended​

  • downstream adoption plans and cross-repo follow-through templates
  • preview-only provider federation synchronization
  • additive family growth when new downstream repos adopt existing governance rules

Planned / Not In Current Scope​

  • waves marked as planned-out-of-current-scope in docs/plans/PLAN_FABRIC_TRUTH.md
  • future external repo adoption that has not yet materialized into code or route output

Public Surfaces​

Primary contract governance routes:

  • GET /api/v1/contracts/registry
  • GET /api/v1/contracts/families
  • GET /api/v1/contracts/schemas
  • GET /api/v1/contracts/matrix
  • GET /api/v1/contracts/drift
  • POST /api/v1/contracts/compatibility/check
  • POST /api/v1/tools/admission/dry-run
  • GET /api/v1/contracts/jarvis
  • GET /api/v1/contracts/jarvis/readiness
  • GET /api/v1/contracts/jarvis/acceptance
  • GET /api/v1/contracts/jarvis/drift
  • GET /api/v1/contracts/federation
  • GET /api/v1/contracts/providers
  • GET /api/v1/contracts/wiki-governance

Primary contract artifacts:

  • contracts/registry/index.json
  • contracts/families/index.json
  • contracts/schemas/index.json
  • contracts/matrix/producer_consumer_matrix.json
  • contracts/drift/latest_drift_report.json
  • contracts/docs/wiki_governance.json
  • contracts/jarvis/jarvis_adoption_status.json

Contract Families​

Human-readable contract family docs live under docs/contracts/. Key families include:

  • naming and shared service baselines
  • schema governance waves and docs standards
  • entitlement policy and keystore entitlement contract
  • plane unified access and agent federation projections
  • support orchestration and voice contracts
  • runtime memory claims
  • versioning, release, regression, and publishing alignment
  • event spine families

Producer / Consumer Zuordnung​

Fabric is the producer for shared governance truth. Consumers include:

  • downstream JHF repos that materialize contract or policy decisions locally
  • Wiki.js documentation publishing and operator documentation readers
  • provider integrations that need a normalized compatibility and readiness vocabulary
  • CI and verification flows that gate releases against Fabric-defined expectations

Compatibility Window​

  • additive contract changes are preferred
  • breaking changes must be reflected in artifacts, route output, docs, and release policy together
  • contract compatibility checks are explicit and machine-readable

Lifecycle Status​

  • registry and contract surfaces are active
  • preview and dry-run families are clearly labeled as non-authoritative write execution paths
  • historic or future waves remain visible only as planned when not implemented

Readiness / Drift / Monitoring​

  • GET /api/v1/contracts/drift is the first drift checkpoint
  • readiness and acceptance are published for JARVIS and other major families where needed
  • governance readiness can be cross-checked via GET /api/v1/governance/readiness

Deployment / Verify​

Repo-local verification inputs:

  • contracts/
  • docs/contracts/
  • tests/test_schema_governance_wave*.py
  • tests/test_governance_plan_references.py
  • tests/test_jarvis_governance.py
  • tests/test_jarvis_adoption_status.py

Live verification examples:

  • GET /api/v1/contracts/registry
  • GET /api/v1/contracts/drift
  • GET /api/v1/contracts/jarvis
  • GET /api/v1/contracts/providers/drift

Known Limits​

  • governance docs and routes can describe additive future paths, but those paths must remain visibly non-current until implemented
  • provider and downstream consumer evidence can inform governance posture, but they do not replace Fabric contract ownership

Exceptions / Waivers​

  • derived consumer views are allowed only when they explicitly state that Fabric remains source of truth
  • preview contracts may exist for guarded handoff or provider planning without granting execution authority
  • contract and wave work is reflected through the HF-* issue docs under docs/issues/
  • governance plans live in docs/plans/PLAN_FABRIC_TRUTH.md and docs/plans/PLAN_FABRIC_JARVIS.md

License​