KDD: deterministic contracts + mechanical verification for agent-built code

[MauricioPerera]

KDD — Knowledge-Driven Development

Repo: https://github.com/MauricioPerera/KDD

A methodology (with a working, MIT-licensed template repo) for governing code built by ephemeral AI agents with deterministic contracts and mechanical verification — no LLM in the required path. The thesis, in one line from the repo's own docs: the agent that implements is never the same one that decides "this is correct." Only real command output counts, never the agent's own word.

The three pillars

1. OKF (Open Knowledge Format) — everything is a node: a .md under knowledge/ with required YAML frontmatter (type, title, description, tags), one of 4 valid types (Task Contract, Data Model, Architecture, Concept), linked from index.md (an unindexed node is orphaned), content is linked not duplicated.
2. CCDD (Contract-Driven Development) — a task contract is a hybrid OKF node defining one function: intent / target / signature / test_command, a frozen oracle (tests_sha256 — the implementer can't quietly rewrite the tests to make broken code pass), and a touch_only perimeter checked against the real git diff, not a prompt instruction the model could ignore.
3. Layer 3 — business rules as declarative data over a shared rule engine (9 families, golden-set sealed by hash), with 7 domains built on top (security, compliance, privacy, accessibility, dependency EOL, observability, test coverage).

Two-level validation

Level 1: 18 mandatory gates, pure-stdlib Python, no network/LLM/subprocess except two documented exceptions (one of them is literally "run the test_command and check the exit code"). Level 2 (optional): a real cyclomatic-complexity gate via an MCP server with tree-sitter backends for 13 languages.

Why it exists

Compared to AGENTS.md-only setups (no verification mechanism of their own) or QA-by-another-LLM approaches (still model judgment, not a deterministic check), KDD's bet is that "the agent quietly drifted out of scope and nobody noticed" is a real risk worth the extra weight — while admitting it's overkill for a trivial one-person prototype.

Practical entry point for this community specifically

If you're running agents through dsh, there's a companion plugin — kdd-gates (announced separately in #4797) — that exposes the gates as native Tools (kdd_validate, kdd_seal, kdd_perimeter, kdd_preflight) instead of shelling out by hand.

To try KDD standalone: clone the repo, run python scripts/init_project.py --apply to strip the example artifacts and turn it into your own project (keeps the gates/tooling), then python scripts/preflight.py to see all 19 gates run.

[MauricioPerera]

Cross-reference: the dsh plugin exposing these gates as native Tools is announced separately in #4797.