zeugnis-contract-drift
Use when the user asks to audit type signatures, docstrings, or API/OpenAPI/GraphQL schemas against actual call-site or handler usage, wants to check for contract drift after a refactor, or wants zeugnis's contract-drift audit run. Scope is structural, machine-checkable declarations only. Not for prose documentation drift — claims in CLAUDE.md, README.md, ARCHITECTURE.md, DECISIONS.md or ADR files no longer matching the code: use befund-docs-drift for that. Verification runs by default and only skips if the user explicitly says skip_verification.
- License 许可
- MIT
- 最近更新
- 2026-11-02
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- zeugnis-contract-drift
- description
- Use when the user asks to audit type signatures, docstrings, or API/OpenAPI/GraphQL schemas against actual call-site or handler usage, wants to check for contract drift after a refactor, or wants zeugnis's contract-drift audit run. Scope is structural, machine-checkable declarations only. Not for prose documentation drift — claims in CLAUDE.md, README.md, ARCHITECTURE.md, DECISIONS.md or ADR files no longer matching the code: use befund-docs-drift for that. Verification runs by default and only skips if the user explicitly says skip_verification.
03 SKILL.md 正文
Find drift between machine-checkable contracts (type hints, function signatures, docstring parameter/return descriptions, API/OpenAPI/GraphQL schemas) and how code actually uses them. Never extract or verify prose documentation — only structural, machine-checkable declarations.
Steps
- Determine
repo_root, the contract source files (typed source, schema files) to scan, and any house rules the user mentioned. Determineskip_verification: defaultfalse. Only treat it astrueif the user explicitly said so in this request — silence, "just run it quickly," or similar is NOT an explicittrue. - Optionally build/reuse a symbol index (see "Shared symbol index" in
zeugnis-assertion-audit's SKILL.md — the same single-flight rule applies here). - Dispatch the
contract-auditoragent in Find mode: give it the contract source files and symbol index (if built) — if step 2 was skipped, tell the agent no symbol index exists and it should read the contract source files directly instead. Ask for{"findings": [...]}where each finding includesdeclaredLocationandactualUsageLocation(bothfile:line) in addition to the shared schema fields. Write its output to a scratch JSON file. - Unless
skip_verificationistrue: dispatch thecontract-auditoragent again in Verify mode, independently re-checking each Find-phase finding. Write{"findings": [{"evidence": "...", "confirmed": true|false}, ...]}to a second scratch file, with a literal boolean for every Find-phase finding: any other answer is kept asverification: "unverified"and counted inunverifiedCount. - Run:
Passpython3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/contract_drift.py" <repo_root> \ --find-json <path-from-step-3> \ [--verify-json <path-from-step-4>] \ [--skip-verification]--skip-verificationONLY if step 1 determined it should betrue— in that case, omit--verify-jsonentirely (there is nothing to verify). Otherwise--verify-jsonis required; the script refuses to run without it when--skip-verificationis absent. The script mapsconfidence: "High"findings toseverity: "High"and writesanalysis/zeugnis/reports/CONTRACT_DRIFT.mdandanalysis/zeugnis/contract_drift_summary.json. - Report the finding count to the user, and if
skip_verificationwastrue, say so explicitly in your summary — an unverified contract- drift report is weaker evidence and the user should know which one they got.
What NOT to do
- Do not default to skipping verification for speed — it must be an explicit user request, every time, not an assumption you make on their behalf.
- Do not report a docstring-only observation as a contract mismatch if it isn't tied to an actual type hint, signature, or schema — that's prose documentation drift, out of this skill's scope.
04 同仓库更多 Skills
toy-check
A skill that checks things in the repository and reports what it finds.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
zirkel-verify-assumptions
Checks exactly ONE named assumption against real evidence in at most 3 steps and reports one outcome: confidence raised (>=90), reading changed, or still unresolved. Use to resolve a single load-bearing uncertainty — typically a blocking entry surfaced by zirkel-clarify-scope: "verify this one assumption", "is it actually true that X", "check this before we rely on it". For multiple uncertainties, invoke once per uncertainty — the step budget is never shared.