v0.3: consumer pin-and-gate pattern — reusable workflow + .github/checkid-contract.yml schema

[Daren9m]

Goal

Define the consumer-side pattern for pinning to a specific contractVersion and gating merges when CheckID's contract bumps incompatibly. Provide a reference implementation.

Depends on

• v0.2 contract version field (separate v0.2 issue)

The pattern

Each downstream consumer (M365-Assess, Az-Assess, EZ-CMMC, M365-Remediate) declares a pinned contract major version in its repo:

# .github/checkid-contract.yml
pinnedMajor: 1
allowMinorAhead: true
checkidRef: tags/v3.5.0  # or a SHA, or main

A consumer-side workflow on every PR:

1. Fetches data/registry.json from the pinned checkidRef.
2. Reads its contractVersion.
3. Fails if the major version differs from pinnedMajor.
4. Optionally fails if minor is ahead and allowMinorAhead: false.

When CheckID bumps major (breaking), the consumer pin no longer satisfies — consumer's PRs fail until they bump pinnedMajor (after migration).

Reference implementation

Ship the consumer-side workflow as a reusable workflow in this repo: .github/workflows/consumer-contract-gate.yml. Consumers reference it:

jobs:
  contract-gate:
    uses: Galvnyz/CheckID/.github/workflows/consumer-contract-gate.yml@main

Acceptance criteria

• .github/checkid-contract.yml schema documented
• consumer-contract-gate.yml reusable workflow shipped in this repo
• Reference doc: how to wire this in a consumer (docs/consumer-guide/contract-gate.md)
• At least one consumer integrated as proof — recommend M365-Assess first
• Workflow handles both pinned-tag and pinned-SHA + main-following modes
• CHANGELOG documents the new gate