schema-contract-design

Authors YAML math-correctness contracts with binding tests and pending lifecycle management.

1|Updated Dec 13, 2025
One-click install
npx skills add https://github.com/ZK-Theory/TDL --skill schema-contract-design-zk-theory
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: schema-contract-design
Source: https://github.com/ZK-Theory/TDL/tree/main/.agents/skills/schema-contract-design
Command: npx skills add https://github.com/ZK-Theory/TDL --skill schema-contract-design-zk-theory

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Recurring research-assurance checks often stay as informal review notes instead of enforced rules, so schema regressions (dropped fields, wrong types, unpinned literals) slip through commits. This Skill turns a stabilized audit finding into a binding contract artifact that fails the commit when violated. ## Core Features & Use Cases - Contract authoring: Creates formula, schema, invariant, or output_validation contracts under contracts/<topic>/<id>.yaml validated against the meta-schema with strict additionalProperties: false. - Binding test wiring: Enforces value-and-type assertions (not key presence), pinned literals, quantified tolerances, and fixtures constructible from committed files only. - Pending lifecycle and verification: Manages pending: true status, manifest registration, and validation via contract_binding_check.py --validate-only. - Use Case: After an audit finds a results JSON silently dropped fields needed for comparison tables, use this Skill to write a schema contract with explicit required_keys and a binding test so the pre-commit gate rejects any future regression. ## Quick Start Use the schema-contract-design skill to add a new schema contract for the comparison results JSON and wire its binding test.

Frequently Asked Questions about schema-contract-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new contract to a contracts/ directory?

Create a kebab-case YAML file under contracts/<topic>/<id>.yaml with id, kind, description, spec_citation, and binding keys, plus exactly one kind-specific block. Then register it in the relevant contracts/manifests/<scope>.yaml and run the validation hook.

What contract kinds does the meta-schema support?

Four kinds are supported: formula (mathematical expression plus invariants), schema (required/forbidden keys), invariant (non-formulaic condition-consequence), and output_validation (dispatching result files to schema contracts via globs).

Why does my binding test pass but not actually enforce the contract?

Presence-only assertions that check a key exists or a value is positive are not enforcement. The binding test must assert exact value and type, pin literals as equality-checkable tokens, and quantify any tolerance predicate explicitly.

Why does the contract gate fail in a fresh git worktree?

The binding test fixture likely reads a gitignored intermediate file that is absent in fresh checkouts. Fixtures must be built from committed files only, using fixed placeholder literals and pytest.skip guards for optional real-file assertions.

When should I set pending: true on a contract?

Set pending: true when the binding test has not yet landed on the base branch; the meta-schema gate still runs while gates 2-4 are skipped. Remove the flag as soon as the test lands to avoid pending-debt warnings.