201-02 — Add a ContractSpec sidecar

What you will build

A contract.json that satisfies audit_contract_docs.py --strict: identity, capabilities, schemas with properties + required, and documented examples.

Prerequisites

• 201-01
• Read ContractSpec

Files you will touch

Under your experimental contracts/<task_id>/v1/:

• contract.json (primary)
• Optional regeneration via scripts/generate_contract_sidecars.py when bootstrapping from templates

Step 1 — Scaffold JSON

Copy shape from a stable sibling such as llm_boolean_gate and adapt task_id, title, schemas—never blind-copy examples without aligning field names.

Required conceptual blocks:

• task_id / version (must match path segments)
• capabilities with uses_llm boolean
• input_schema / output_schema — type":"object", non-empty properties, non-empty required
• examples array (top-level or nested under extensions) per audit rules

Step 2 — Generate / normalize sidecars (optional)

python3 scripts/generate_contract_sidecars.py

Review diff—generator output is a starting point, not policy.

Step 3 — Strict audits

python3 scripts/audit_contract_docs.py --strict --strict-md

Fix violations iteratively; strict-md enforces Markdown headings heuristic on contract.md.

Expected output

Audit exits 0. Any violation prints Strict violations: with actionable lines.

Common failures

Verify

PYTHONPATH=src python3 - <<'PY'
from forge_lcdl.contracts_api import load_contract_spec
spec = load_contract_spec("llm_boolean_gate", "v1")
print(spec.input_schema["required"])
PY

Substitute your task_id once registered.

What changed

Sidecars become machine-checkable—matching enterprise gates in CI.

Next step

201-03 — Use operators.