Handbook
Task maturity matrix
Use this matrix when onboarding a new task_id or promoting an experimental task.
Updated
Per-task snapshot
Machine-readable columns (schema_depth, has_examples, supports_fake_transport, live_optional) are emitted in task catalog (generated draft) via scripts/generate_task_catalog_md.py. Treat that table as the authoritative wide index; this page explains what the levels mean.
Levels
| Level | Contract + schema | Tests | Ops hooks | Typical use |
|---|---|---|---|---|
| T0 — Draft | Markdown only / incomplete JSON | None | None | Spike |
| T1 — Typed | Full contract.json passes --strict |
Unit smoke | Offline CI | Internal tools |
| T2 — Validated | Examples aligned with implementation | Task tests + golden outputs | Docs linked | Shared library surface |
| T3 — Hardened | Nested schemas / documented failure modes | Property + regression suite | Benchmarks optional lane | Customer-facing |
| T4 — Attested | Versioned compatibility promises | CI blocking + manual review record | Live smoke job (isolated) | Regulated environments |
Promotion checklist
python3 scripts/audit_contract_docs.py --strict --strict-md- Task-specific tests under
tests/withfake_chat - Handbook row in Task catalog accurate
- API note if output shape affects consumers (API compatibility)