carrick-drift

The task skill that puts a producer's type, each consumer call site's expected type and the stored verdict side by side, one operation at a time.

carrick-drift compares producer API types, consumer expected types, and stored contract verdicts side by side to diagnose cross-service type discrepancies.

Invocation triggers

Agents execute carrick-drift in the following situations:

When verifying whether a producer and consumer still agree on interface types
Before modifying a request body, path parameter, or response payload shape
When investigating a compatibility error that lacks specific source locations

Tool sequence

Discover service pairs:
- get_service_graph(): Retrieves all cross-service dependency edges.
Inspect contract pairs:
- get_contract_pair(consumer_service, producer_service, method?, path?): Retrieves side-by-side type definitions, call site locations, and stored verdicts for each operation between the services.

Classification hierarchy

The skill classifies each operation by applying the following deterministic rules in priority order:

DRIFT: The stored verdict is incompatible. The finding details the mismatched property and direction.
PRODUCER UNTYPED: The producer lacks an extracted request type (on body-bearing methods) or response type.
CONSUMER UNTYPED: The consumer call site provides no type declaration for an operation that exposes types.
UNRESOLVED: The stored verdict is unresolved (due to dynamic or unextracted types).
NOT JUDGED: No stored verdict exists for the operation.
MATCH: The stored verdict is compatible.

On UNRESOLVED and NOT JUDGED rows, the skill performs a secondary structural inspection of the returned type texts, noting whether types are missing, have mismatched optionality, or declare different primitive types.

Interpretation rules and edge cases

Verdict scope: A stored verdict evaluates the contract between a consumer and producer service across that operation; all call sites on that operation share the verdict.
GET request bodies: HTTP GET operations do not declare request bodies and are not marked as untyped.
Date and string serialization: When JSON serialises Date objects to strings, Carrick notes the wire compatibility without flagging it as drift.

Example

Evaluating an operation with get_contract_pair:

{
  "consumer": "acme-gateway",
  "producer": "acme-orders",
  "operations": [
    {
      "operation": "POST /v1/orders {action=refund}",
      "producer": {
        "service": "acme-orders",
        "request": null,
        "response": null,
        "endpoint_source": "fact: declared operation"
      },
      "consumer": {
        "service": "acme-gateway",
        "call_sites": [
          {
            "file_location": "functions/gateway/src/api-client.ts:133",
            "expected_request": null,
            "expected_response": null,
            "call_source": "candidate: model"
          }
        ]
      },
      "untyped_sides": 4,
      "verdicts": [
        {
          "state": "unresolved",
          "scope": "pair",
          "scope_note": "One stored verdict covers the whole consumer/producer pair, not one call site: every call site listed on this operation shares it.",
          "scanner_version": "0.3.82",
          "response": {
            "verdict": "unverifiable",
            "resolved": false,
            "unresolved_reason": "the producer surface export is missing or renamed"
          }
        }
      ]
    }
  ],
  "types": []
}

The skill formats the result into a drift table:

operation	class	producer type	consumer type	call site	verdict
POST /v1/orders {action=refund}	PRODUCER UNTYPED	none extracted	none extracted	functions/gateway/src/api-client.ts:133	unresolved; the producer surface export is missing or renamed

Task skills covers the complete set of agent skills.
MCP tools documents get_service_graph, get_contract_pair, and check_compatibility.
PR comments describes automated drift checks on pull requests.