--- description: Unified contract health skill — drift mode (static cross-repo drift detection) and runtime mode (live compliance verification); replaces contract_verify (OMN-8073) version: 3.0.0 mode: full level: advanced debug: false category: verification tags: - contracts - drift - boundaries - cross-repo - health-check - runtime - verification author: OmniClaude Team composable: true args: - name: --mode description: "Operation mode: drift (static drift detection), runtime (live runtime verification), full (both). Default: drift" required: false - name: --drift description: "Shorthand for --mode drift" required: false - name: --runtime description: "Shorthand for --mode runtime" required: false - name: --full description: "Shorthand for --mode full (drift + runtime)" required: false - name: --repos description: "Comma-separated repo names (default: all 8 repos). Applies to drift mode only." required: false - name: --dry-run description: "Print findings only, no ticket creation" required: false - name: --severity-threshold description: "Min severity for tickets: BREAKING | ADDITIVE | NON_BREAKING (default: BREAKING). Applies to drift mode only." required: false - name: --sensitivity description: "Drift sensitivity: STRICT | STANDARD | LAX (default: STANDARD). Applies to drift mode only." required: false - name: --check-boundaries description: "Also validate Kafka boundary parity (default: true). Applies to drift mode only." required: false - name: --all description: "Run full 52-contract runtime verification (default: registration-only). Applies to runtime mode only." required: false --- # contract_sweep **Announce at start:** "I'm using the contract-sweep skill." Unified contract health skill combining two detection modes: 1. **Drift mode** (`--drift`) — Static cross-repo contract drift detection. Wraps the `check-drift` infrastructure from `onex_change_control` to scan all repos for contracts that have drifted from their pinned baselines and Kafka boundaries that have become stale. 2. **Runtime mode** (`--runtime`) — Live runtime contract compliance verification. Reads `contract.yaml` files from the `omnibase_infra` verification subsystem and verifies that the running system matches the declarations: registered handlers, subscribed topics, published events, and cross-contract references. 3. **Full mode** (`--full`) — Runs both drift and runtime modes sequentially. Default mode when no flag is specified: `--drift`. ## Usage ``` /contract-sweep --drift /contract-sweep --runtime /contract-sweep --full /contract-sweep --drift --dry-run /contract-sweep --drift --repos omnibase_infra,omnibase_core /contract-sweep --drift --severity-threshold ADDITIVE /contract-sweep --drift --sensitivity STRICT /contract-sweep --drift --check-boundaries false /contract-sweep --runtime --all ``` --- ## Drift Mode Cross-repo contract drift detection. Wraps the `check-drift` infrastructure from `onex_change_control` to scan all repos for contracts that have drifted from their pinned baselines and Kafka boundaries that have become stale. This mode combines two detection sub-modes: 1. **Contract drift** -- Uses `check_contract_drift.py` and the `handler_drift_analysis` handler from `onex_change_control` to compute canonical hashes of all contracts and compare them against pinned snapshots. When drift is detected, performs field-level analysis to classify changes as BREAKING, ADDITIVE, or NON_BREAKING. 2. **Boundary staleness** -- Validates that cross-repo Kafka topic boundaries declared in `kafka_boundaries.yaml` still match the actual producer/consumer files in each repo. ### Drift Detection Pipeline ### Step 1 — Parse arguments - `--repos` → comma-separated repo names (default: all 8) - `--dry-run` → findings only, no ticket creation - `--severity-threshold` → minimum severity for ticket creation (default: BREAKING) - `--sensitivity` → STRICT | STANDARD | LAX (default: STANDARD) - `--check-boundaries` → validate Kafka boundary YAML parity (default: true) ### Step 2 — Run contract drift check For each repo, run the `check_contract_drift.py` script from `onex_change_control`: ```bash cd /Volumes/PRO-G40/Code/omni_home/onex_change_control # local-path-ok: example command in documentation python3 scripts/validation/check_contract_drift.py \ --root /src \ --check ``` Drift is classified using `handler_drift_analysis`: ### Drift Classification | Severity | Root Keys | |----------|-----------| | BREAKING | `algorithm`, `input_schema`, `output_schema`, `type`, `required` | | ADDITIVE | New fields not in breaking paths | | NON_BREAKING | `description`, `docs`, `changelog`, `author` | Sensitivity controls what surfaces: STRICT = all, STANDARD = BREAKING+ADDITIVE, LAX = BREAKING only. ### Step 3 — Boundary staleness check (unless `--check-boundaries false`) Read `onex_change_control/boundaries/kafka_boundaries.yaml`. For each declared boundary verify: 1. Producer file still exists in the producer repo 2. Consumer file still exists in the consumer repo 3. Topic regex still matches content in both files 4. No undeclared cross-repo topics in code ### Boundary Staleness Checks When `--check-boundaries` is enabled (default), the skill also validates: 1. **Producer file exists** -- The declared producer file still exists in the producer repo 2. **Consumer file exists** -- The declared consumer file still exists in the consumer repo 3. **Topic pattern match** -- The topic regex still matches content in both files 4. **No undeclared cross-repo topics** -- Topics in code that cross repo boundaries but are not in the boundary manifest ### Severity and Ticket Creation | Drift Severity | Ticket Priority | Action | |---------------|-----------------|--------| | **BREAKING** | Critical | Always create ticket | | **ADDITIVE** | Major | Create if threshold <= ADDITIVE | | **NON_BREAKING** | Minor | Create if threshold <= NON_BREAKING | | **Stale boundary** | Critical | Always create ticket (boundary mismatch = potential runtime failure) | | **Undeclared boundary** | Major | Create if threshold <= ADDITIVE | Ticket dedup: keyed by `(repo, contract_path, drift_type)`. Before creating, search Linear for an open ticket matching the same key. If found, update or comment. If prior ticket is closed but same drift recurs, create new ticket referencing the prior closure. ### Drift Mode Output Written to `$ONEX_STATE_DIR/contract-sweep//report.yaml`: ```yaml run_id: "" timestamp: "" repos_scanned: ["omnibase_core", ...] sensitivity: "STANDARD" total_contracts: drift_findings: - repo: "" path: "" severity: "BREAKING" current_hash: "" pinned_hash: "" field_changes: - path: "input_schema.type" change_type: "modified" is_breaking: true summary: "" boundary_findings: - boundary_name: "" issue: "producer_file_missing" producer_repo: "" consumer_repo: "" message: "" by_severity: {BREAKING: 0, ADDITIVE: 0, NON_BREAKING: 0} stale_boundaries: 0 repos_not_found: [] baseline_missing: [] overall_status: "" tickets_created: [] ``` --- ## Runtime Mode Runtime contract compliance verification. Reads `contract.yaml` files from the `omnibase_infra` verification subsystem and verifies that the running system matches the declarations: registered handlers, subscribed topics, published events, and cross-contract references. ### Runtime Mode Execution ```bash # Registration-only (default) onex run-node node_contract_sweep \ --input '{"registration_only": true, "dry_run": false, "output_path": "$ONEX_STATE_DIR/contract-sweep//runtime-report.json"}' \ --timeout 300 # Full 52-contract verification (--all flag) onex run-node node_contract_sweep \ --input '{"registration_only": false, "dry_run": false, "output_path": "$ONEX_STATE_DIR/contract-sweep//runtime-report.json"}' \ --timeout 300 ``` On non-zero exit, a `SkillRoutingError` JSON envelope is returned — surface it directly, do not produce prose. ### Runtime Exit Codes | Code | Meaning | Action | |------|---------|--------| | 0 | PASS | All checks passed | | 1 | FAIL | One or more checks failed — route to failure-to-ticket | | 2 | QUARANTINE | Checks could not run (infra down, missing contracts) — warn only | ### Runtime Result Handling On PASS (exit 0): Print `CONTRACT_VERIFY: PASS (N checks passed)`. On FAIL (exit 1): Print failure summary and route to `auto_ticket_from_findings`. Do not create tickets for QUARANTINE results. ### Sustained PASS Auto-Close When runtime verification produces PASS for 2 consecutive runs: - Query open tickets with label `contract-verify` matching the now-passing checks - Auto-close with comment: `Sustained PASS across 2 consecutive runs. Auto-closing.` ### Deduplication Runtime failure tickets are keyed by `contract_name:check_type`. Repeated failures do not create duplicate tickets — they update or comment on the existing open ticket. --- Ticket Priority mapping: - BREAKING → Critical - ADDITIVE → Major - NON_BREAKING → Minor - **close-day**: Drift mode runs as end-of-day contract health check; runtime mode runs as Phase B6 - **integration-sweep**: Complementary (integration-sweep validates DoD; contract-sweep validates drift + runtime compliance) - **ci-watch**: Drift mode can be triggered after CI passes to verify no contract drift was introduced ## Repo List (Drift Mode) ```json { "skill": "contract-sweep", "status": "clean | drifted | breaking | error", "repos_scanned": 0, "drift_findings": [], "boundary_findings": [], "tickets_created": 0 } ``` ## Default Repos ``` omnibase_core, omnibase_infra, omniclaude, omniintelligence, omnimemory, omninode_infra, omnibase_spi, onex_change_control ``` ## Architecture ``` SKILL.md -> thin shell (this file) node_contract_sweep -> omnimarket/nodes/node_contract_sweep/ (compliance sweep: fields, topics, node_type) NodeContractDriftCompute -> omnimarket/nodes/node_contract_drift_compute/ (classification) check_drift -> onex_change_control/scripts/validation/check_contract_drift.py handler_drift_analysis -> onex_change_control/handlers/handler_drift_analysis.py boundaries -> onex_change_control/boundaries/kafka_boundaries.yaml ``` The skill wraps: - `onex run node_contract_sweep` (required-field + topic-naming compliance sweep, runtime mode) - `onex_change_control/scripts/validation/check_contract_drift.py` (hash-based drift, drift mode) - `onex_change_control/handlers/handler_drift_analysis.py` (field-level analysis, drift mode) - `onex_change_control/boundaries/kafka_boundaries.yaml` (boundary manifest, drift mode) - `omnibase_infra.verification.cli` (registration verification, runtime mode) ## See Also - `contract-compliance-check` skill -- Pre-merge seam validation (per-ticket, per-branch) - `NodeContractDriftCompute` in `onex_change_control` -- The underlying ONEX node - `kafka_boundaries.yaml` -- Cross-repo Kafka boundary manifest - OMN-5162 -- Original check-drift script - OMN-6725 -- contract-sweep drift tracking ticket - OMN-7040 -- contract-verify original ticket (merged into contract-sweep via OMN-8073) - OMN-8073 -- Merge contract_verify into contract_sweep