Contract Sweep

contract_sweep

Announce at start: "I'm using the contract-sweep skill."

If routing fails, surface SkillRoutingError directly; do not produce prose.

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. Compliance mode (--compliance) — Static field/topic/node_type compliance sweep of contract.yaml files via node_contract_sweep (omnimarket). Checks required fields, onex.{cmd|evt|intent}.producer.event.vN topic naming, and declared node_type against the canonical set. This is a pure filesystem check — it does NOT connect to a running system, and it has no "registration_only" or live-runtime probe mode (an earlier revision of this file documented a registration_only field and an onex run-node node_contract_sweep invocation that never existed on the node's actual request model, which is extra="forbid" and would reject that input outright — that fictional Runtime Mode section has been removed).

Default mode when no flag is specified: --drift.

Usage

/contract-sweep --drift
/contract-sweep --compliance --repos omnimarket
/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

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 ticket-creation severity (default: BREAKING)
• --sensitivity → STRICT | STANDARD | LAX (default: STANDARD)
• --check-boundaries → validate Kafka boundary YAML parity (default: true)

Step 2 — Run contract drift check

Run the check_contract_drift.py script from onex_change_control once per repo:

cd $ONEX_WORKTREES_ROOT/<ticket>/onex_change_control
python3 scripts/validation/check_contract_drift.py \
  --root <repo>/src \
  --check <snapshot-file>

Drift is classified using handler_drift_analysis:

Drift Classification

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

Ticket dedup: keyed by (repo, contract_path, drift_type). Before creating, search Linear using 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/<run-id>/report.yaml:

run_id: "<YYYYMMDD-HHMMSS>"
timestamp: "<ISO-8601>"
repos_scanned: ["omnibase_core", ...]
sensitivity: "STANDARD"
total_contracts: <count>
drift_findings:
  - repo: "<repo>"
    path: "<contract-path>"
    severity: "BREAKING"
    current_hash: "<sha256>"
    pinned_hash: "<sha256>"
    field_changes:
      - path: "input_schema.type"
        change_type: "modified"
        is_breaking: true
    summary: "<one-line>"
boundary_findings:
  - boundary_name: "<topic>"
    issue: "producer_file_missing"
    producer_repo: "<repo>"
    consumer_repo: "<repo>"
    message: "<description>"
by_severity: {BREAKING: 0, ADDITIVE: 0, NON_BREAKING: 0}
stale_boundaries: 0
repos_not_found: []
baseline_missing: []
overall_status: "<clean|drifted|breaking>"
tickets_created: []

Compliance Mode

Static field/topic/node_type compliance sweep via node_contract_sweep (omnimarket). This is a pure filesystem COMPUTE check — no live-runtime connection, no registration probe, no "registration_only" input. It reads contract.yaml files under the requested repos and checks: required fields (name, contract_version, node_type, node_version, description), node_type against the canonical set, and event_bus.publish_topics / subscribe_topics naming (onex.{cmd|evt|intent}.producer.event.vN).

Compliance Mode Execution

--repos is REQUIRED on the underlying CLI — there is no "scan everything" default. The census must come from a real filesystem probe run by the caller (a CI workflow step, scripts/ci/run_contract_sweep_gate.py, or an equivalent harness) — never an operator-typed convenience value and never prose in this file:

python -m omnimarket.nodes.node_contract_sweep --repos omnimarket  # local-path-ok: raw CLI script, not an onex-dispatchable node — this IS its real entrypoint

If dispatch/routing fails, surface SkillRoutingError directly; do not produce prose.

Prints a ContractSweepResult JSON to stdout (violations, contracts_checked, scanned_count, summary, status, missing_repos, scope_error).

Compliance Exit Codes

ERROR and FAIL both exit 1 — a caller distinguishing them should read status in the JSON body, not just the exit code.

Deduplication

Compliance failure tickets are keyed by node_name:violation_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

• integration-sweep: Complementary (integration-sweep validates DoD; contract-sweep validates drift + field/topic compliance)

• ci-watch: Drift mode can be triggered after CI passes to verify no contract drift was introduced

Repo List (Drift Mode)

{
  "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:

• python -m omnimarket.nodes.node_contract_sweep --repos <repo,...> (required-field + topic-naming compliance sweep, compliance mode — --repos is required, see above)
• 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)

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