feat: validator L3 (contract satisfaction) + L6 (waste detection) + deterministic query CLI

[viberesearch]

Completes the 6-level OrgSchema TDD-cascade validator by implementing the two previously-planned levels (the README noted L3/L6 as "planned for future releases") plus a deterministic query CLI.

Level 3 — Contract Satisfaction (errors)

L0 defines constraint_contracts (L0_con_*) and commitment_contracts (L0_com_*), and specs reference them via satisfies_constraint / satisfies_commitment. L3 enforces, deterministically:

1. Provider exists — each contract's validated_by file is present on disk (the parenthetical note form path (note) is handled). A contract pointing at a missing provider is an unmet contract.
2. No dangling / mistyped reference — every satisfies_constraint / satisfies_commitment annotation resolves to a declared contract of the matching kind (a commitment id under satisfies_constraint is a type mismatch).
3. No unmet contract — every declared contract is covered by an existing provider OR at least one referencing spec.

Contracts are binding (regulatory / self-imposed), so violations are errors, mirroring Level 2.

Level 6 — Waste Detection (warnings)

Surfaces declared units that are never consumed (advisory, like L4/L5):

• Orphaned roles — a role in organization.yaml: roles referenced by no process spec (substring match across structured + prose fields, conservative to avoid singular/plural false positives).
• Unconsumed products — a products/*.yaml that no signal lists in implemented_by and no other spec references by path or id.
• Empty contracts — a declared contract with missing/empty requires.
• Duplicate allocation — a product listed more than once in one signal's implemented_by.

Definitions are deliberately conservative (declared-here-consumed-nowhere) to keep noise low.

Deterministic Query CLI — orgschema-query

A plain deterministic query interface over L3/L6 — no natural-language / LLM layer. OrgSchema's constraint space is boolean (satisfied or not; consumed or not), so a deterministic query is the right interface, not a grounded NL→DSL pipeline. It re-uses the validator level functions, so query and validator never disagree.

orgschema-query --schema ./orgschema-demo
orgschema-query --schema ./orgschema-demo --check contracts|waste|all
orgschema-query --schema ./orgschema-demo --level 3|6
orgschema-query --schema ./orgschema-demo --format json

Exit 1 when an error-severity check (contracts) reports a violation, else 0. Added as a console_scripts entry point.

Quality

• 16 tests: positive + negative for L3 (satisfied / missing provider / dangling ref / type mismatch) and L6 (clean / orphaned role / unconsumed product / empty contract / duplicate allocation), plus CLI smoke tests (text, json, per-check, per-level, non-zero exit, missing dir).
• uv run black --check ., flake8 --select=E9,F63,F7,F82, mypy, and full pytest all green. Fleet pre-commit hook passed (black/flake8/mypy/trivy).
• Verified against orgschema-demo: all 6 levels pass with 0 false positives.

Spec ambiguity resolved

The README named L3/L6 but did not give field-level definitions. Definitions were derived faithfully from the existing data model (the L0 validated_by/requires contract fields and satisfies_constraint/satisfies_commitment references already present in the demo) and documented in the function docstrings and README.

🤖 Generated with Claude Code