AGENT SKILL

check-source-contract

Validates a versioned source-fact contract deterministically with zero model calls. Use in local development or CI to detect extraction, grounding, finalization, answer-pattern, and source drift failures.

License 许可
Apache-2.0
所属仓库
reoring/shepherd
最近更新
2026-08-18
Stars
★ 0
Forks
0

01 前言 Front Matter

name
check-source-contract
description
Validates a versioned source-fact contract deterministically with zero model calls. Use in local development or CI to detect extraction, grounding, finalization, answer-pattern, and source drift failures.

03 SKILL.md 正文

Check Source Contract

Outcome

Prove that a versioned RLM contract matches the current tracked source without invoking an LLM provider. Return grounded facts, failure codes, answer preview, source revision, and CI-compatible exit status.

Use When

  • Authoring or reviewing an RLM contract.
  • Editing source covered by a contract.
  • Preflighting a query-large-source call.
  • Running local or CI source-drift checks.
  • Separating source/contract failures from model/provider failures.

First Action

The checker and skill locations are already resolved. Do not run ls, find, which, or cat SKILL.md. When src/shepherd-cli.ts exists from the current repository root, run the node src/shepherd-cli.ts check command immediately; otherwise use shepherd check.

Command

Installed package:

shepherd check "$REPO" --contract "$CONTRACT" --json

This repository checkout, from the repository root:

node src/shepherd-cli.ts check \
  "$REPO" --contract "$CONTRACT" --json

Use --isolation docker only when worker-isolation parity is part of the check.

Exit Contract

0: contract/source check passed
1: deterministic contract/source mismatch
2: usage, file, JSON, or runtime error

Never convert exit 1 into a warning when the user asked for a gate. Never retry with a model.

Result Review

On PASS verify:

  • all required facts are grounded
  • extractor failures are zero
  • runtime finalizer state matches the contract
  • answer pattern passes when configured
  • modelCalls is zero

On FAIL report:

  • failed fact ID
  • failure code
  • bounded source path
  • selected/captured counts
  • pending facts
  • answer/finalizer state

Do not change cardinality, anchors, or selectors only to make the check green. Read the owning source and decide whether source or contract should change.

Cross-Harness Use

The deterministic checker core remains the authority:

  • OMP and Pi: native /shepherd check executes immediately without an outer-agent model turn.
  • Claude: use the direct shell command for an explicit check; use /check-source-contract only when Claude must select the workflow.
  • CI: use the headless command without provider credentials.

Automatic skill selection necessarily spends an outer-agent decision; explicit checks should use the native or shell fast path.

Working Tree

Tracked-file content is read from the current working tree, so staged and unstaged edits are checked. Untracked files are absent until added to the Git index. Current source revision display is HEAD-based and may not identify dirty content uniquely.

Acceptance

  • Check performs zero model calls.
  • PASS/FAIL is deterministic for the same source and contract.
  • Contract drift exits 1.
  • Config/runtime errors exit 2.
  • Query execution is not attempted after a failed check.

04 同仓库更多 Skills

reoring
reoring/shepherd

query-large-source

Orchestrates conversational questions over large source through direct inspection tools and bounded Shepherd evidence queries.

★ 0
reoring
reoring/shepherd

check-sdk-wiring

Creates and verifies cross-file source contracts from handwritten SDK services to generated request builders. Use when preserving validation labels, client method wiring, HTTP methods, URL templates, headers, or idempotency behavior.

★ 0
reoring
reoring/shepherd

check-registration-inventory

Creates and verifies source contracts for plugin, controller, route, provider, or handler inventories. Use when an exact registration list, order, or cardinality is an architectural invariant checked locally or in CI.

★ 0
reoring
reoring/shepherd

check-generated-code

Creates bounded source contracts for important facts inside large generated files. Use when verifying request shapes, route tables, bindings, operation names, or headers without loading the full generated artifact into model context.

★ 0
reoring
reoring/shepherd

check-config-mappings

Creates and verifies source contracts for configuration defaults and constructor wiring. Use when checking zero-value defaults, config field assignments, timeout/retry settings, environment option mapping, or production constructor fields.

★ 0
reoring
reoring/shepherd

check-cli-registrations

Creates and verifies source contracts for CLI root and subcommand registrations. Use when preserving constructor wiring, source order, exact registration cardinality, or detecting command additions, removals, renames, and duplicates.

★ 0