201-01 — Author a task contract

What you will build

A paper design for a governed task: stable task_id, v1/ folder layout, and contract.md sections consistent with an existing catalog task used as a reference.

Prerequisites

• Tutorial 101

Files you will touch (tutorial-safe)

Work on a feature branch; do not merge unfinished contracts to main without review.

Reference-only reads:

• src/forge_lcdl/contracts/llm_boolean_gate/v1/contract.md — compact generic task pattern
• src/forge_lcdl/tasks/catalog_v1.py — TASK_REGISTRY_V1 registration surface

Step 1 — Choose task_id

Pick snake_case that does not collide with existing folders under contracts/. For learning, rename away before landing—use something like tutorial_echo_stub locally only.

Step 2 — Create folder skeleton

src/forge_lcdl/contracts/<task_id>/v1/
  contract.md
  contract.json   # may start from generator; fill in next lesson

Step 3 — Draft contract.md sections

Mirror proven tasks:

1. Purpose — one paragraph.
2. Inputs — field table aligned with future JSON schema.
3. Outputs — success envelope (Ok payload keys).
4. Examples — at least one minimal JSON example each direction.
5. Failure modes — what Err carries (parse, schema, policy).

Step 4 — Registry awareness

Implementations register in TASK_REGISTRY_V1 (see catalog_v1.py). Until Python wiring exists, run_task cannot dispatch your ID—this lesson stops at documentation + sidecar readiness.

Expected output

A coherent contract.md draft you could show in PR description without claiming runtime registration yet.

Common failures

Verify

python3 scripts/audit_contract_docs.py

(Strict mode may still fail until contract.json matches—expected mid-tutorial.)

What changed

You can clone structure from generic catalog tasks instead of blank-page authoring.

Next step

201-02 — Add a ContractSpec sidecar.