Contract Check — Read-Only Pact Health

Own contract health evidence and rendering. The runner owns explicit test generation, local sync, normalization and provider verification. Release workflows consume this audit's mechanical evidence; do not create a second health collector.

This audit never runs tests, creates links, changes permissions, copies pacts, fixes CI, or writes tracking. Do not normalize project files before auditing or dismiss generated-looking diffs by eye. Only a reviewed project scripts/pact-normalize hook may compare temporary copies. Report findings and optional next-command pointers without confirmation prompts or automatic handoffs. A separate setup request belongs to the project setup contract.

Usage

/contract-check                 # full mechanical and semantic audit
/contract-check status          # same evidence, summary only
/contract-check stale           # content equality and timestamp diagnostics
/contract-check uncommitted     # provider-pact Git status
/contract-check sync-gaps        # intended → built → synced edges
/contract-check coverage        # bounded static CircleCI evidence
/contract-check matrix          # observed consumer/provider file relationships
/contract-check missing         # semantic missing-test review
/contract-check docs            # semantic documentation drift
/contract-check disabled        # semantic test-exclusion review
/contract-check <service>        # verified service, scoped presentation

full and all mean the default full audit. Reject unrecognized arguments instead of guessing commands or treating an unknown name as a service. This is not a setup/remediation interface.

Prerequisites and scope

The helper requires Bash 4+, GNU stat/date, standard shell utilities and the existing project integration documented in project setup. Automated discovery is limited to flat services with target/pacts/ consumer output and (src/)test/resources/pacts/ provider input. Do not claim support for arbitrary language layouts or nested workspace paths.

Run from the intended project. The helper honors an existing absolute RELEASE_PROJECT_ROOT when supplied by the release authority; otherwise it finds the nearest ancestor .mgit.conf. Verify that root before execution. Missing/invalid setup is UNKNOWN, not permission to create it.

Before checks that execute project-owned helpers, inspect scripts/mgit, scripts/pact-pairs, any scripts/pact-normalize hook, and their delegated commands. The Git and edge modes must be read-only, and the hook may rewrite only the temporary paths it receives. Unknown or mutating helpers make that check unavailable. Do not execute unreviewed project code merely because a file exists. coverage and matrix make no project helper calls; stale calls only the optional hook. Missing executable support means unavailable; do not install dependencies or repair permissions.

For a service view, confirm the service in project topology. Mechanical collection is project-wide; filter its findings to edges involving that service and scope semantic reads to it. Do not present full-project totals as service totals. If project-wide reads are outside authorization, report that mechanical scoping is unsupported rather than expanding access silently.

Collect once

Call the installed authority directly; no project symlink is needed for this audit:

~/.agents/skills/contract-check/scripts/contract-check.sh all

Replace all with the validated mechanical subcommand when only that check was requested. Full/status uses one all collection, reusing its matrix for semantic review. If a dependency is unsafe/unavailable, collect only independent safe checks and label omitted checks UNKNOWN. Never substitute an arbitrary project scripts/contract-check implementation.

CI results are static configuration text, not proof a job is enabled, scheduled, reachable, checks every file, or passed. Even tag-style OK requires project-specific validation of the selector and workflow. Other CI engines and dynamic forms remain unknown; see the supported conventions. No consumer output proves only that output is absent, not that tests were never run.

Semantic review

For full/status or the requested semantic mode:

• Missing tests: use project documentation, connector/client code and actual consumer tests to identify intended internal boundaries. Do not infer providers solely by stripping a filename suffix, assume every connector is internal, or use a fixed service/external-connector roster.
• Documentation: locate the project's authoritative Pact workflow documentation; compare its declared relationships with the collected matrix. Absence of generated files is not proof a documented relationship is obsolete. Missing documentation is unavailable evidence.
• Disabled tests: inspect build exclusions, selected test suites, Makefile recipes and CI paths. Distinguish intentional unit-test exclusions with an explicit contract target from contract tests that have no evidenced execution path. Do not execute a build to discover its configuration.

Mark uncertain mappings and unsupported layouts UNKNOWN. Keep semantic findings separate from mechanical findings and cite the relevant file/command evidence.

Report

Render one table: check, PASS/INFO/WARN/FAIL/UNKNOWN, evidence/limitations. Full audit adds finding rows by consumer/provider; status omits detail, not missing evidence. Preserve successful checks when another is unavailable. Static CI OK is informational, never a live verification PASS.

Recommended actions are pointers only: /contract-test consumer|sync|provider|full for a separately requested run, or an explicit coding/setup request for missing integration/tests/CI. Do not run them, normalize files, create tasks, or offer automatic remediation from this audit.