Handbook

Schema catalog and ContractSpec mechanics

Forge LCDL uses overlapping “schema-shaped” artifacts. This page names each layer and how tooling validates them.

Updated 2026-07-06

Layers

Layer	Location	Stable?	Depth
Task Markdown contracts	`src/forge_lcdl/contracts/<task_id>/<version>/contract.md`	Canonical human narrative	N/A
ContractSpec sidecar	`contract.json` beside Markdown	Intended for tooling; optional today	Parsed by `contracts_api`
Task Python validators	`src/forge_lcdl/tasks/_v.py`	Runtime source of truth for task success	Explicit keys + gateways
Shared Pyd/dataclass-ish specs	e.g. `src/forge_lcdl/schemas/`	Evolving artifact helpers (`page_mechanics_v1`)	Depends on caller
Handbook mirror	`forge-lcdl-website` autodoc	Publish-only	Mirrors Markdown/HTML

Schema artifact layers

How human contract narrative, JSON sidecars, Python validators, and the handbook mirror relate in Forge LCDL.

contract.md (human narrative)Canonical operator-facing policy and task narrative.
contract.json (ContractSpec sidecar)Machine-readable sidecar for capabilities, policies, and JSON schemas.
Python task validators (runtime truth)Task modules enforce success keys and gateways at runtime.
published handbook HTML mirrorPublish-only mirror of contract Markdown for handbook readers.

  contract.md (human narrative)
      |
      v
  contract.json (ContractSpec sidecar)
      |
      v
  Python task validators (runtime truth)
      |
      v
  published handbook HTML mirror

Markdown remains authoritative for operators and nuanced policy. contract.json tracks capabilities, coarse policies, and JSON-Schema-shaped payloads for benchmarking, UI, or future validate_contract_* expansion.

Schema maturity (L0–L4)

Use these labels when evolving contract.json and CI gates. They describe tooling depth, not task quality.

Level	Sidecar	Markdown	JSON identity	Schema strictness	Typical CI
L0	Absent	Canonical	N/A	None	Docs-only
L1	Present	Canonical	`contract_markdown_path` matches layout	Object schemas + required lists (`audit_contract_docs.py --strict`)	Default strict audit
L2	Present	Matches examples in JSON	Top-level `task_id` / `version` mirror filesystem (`--require-contract-identity`)	One-level type checks in *`validate_contract_`**	Identity gate + strict audit
L3	Present	Deep examples aligned with tests	Same identity expectations	Deeper nesting / richer `properties` (track via `--schema-depth-report`)	Targeted pytest + audits
L4	Present	Same	Identity fields + optional `additionalProperties`: false on roots (when safe)	Automated tests validate curated examples and negative cases against sidecars	Full regression

Prompt pack alignment: treat L4 as requiring machine-checked examples/negative cases—not prose-only claims.

Board-game and chess-helper tasks use board_game_* and game_move_* IDs in this repo—there is no game_state_eval catalog entry; treat that label as obsolete or external (priority contracts).

Schema maturity ladder

L0 through L4 labels describe how contract.json sidecars gain tooling depth and CI rigor.

L0 — Markdown onlyCanonical contract with no contract.json sidecar yet.
L1 — strict contract.json sidecarSidecar present with object schemas and required lists enforced.
L2 — identity + depth checkstask_id and version mirror filesystem layout under --require-contract-identity.
L3 — examples aligned with testsDeep examples in Markdown and JSON match targeted pytest coverage.
L4 — closed-world schemas when safeOptional additionalProperties false plus machine-checked positive and negative cases.

  L0 — Markdown only
      |
      v
  L1 — strict contract.json sidecar
      |
      v
  L2 — identity + depth checks
      |
      v
  L3 — examples aligned with tests
      |
      v
  L4 — closed-world schemas when safe

ContractSpec (`contract.json`)

Use forge_lcdl.contracts_api.load_contract_spec. Known top-level keys are merged into ContractSpec (input_schema, output_schema, capabilities, rag_policy, …). Anything else—including examples arrays not yet modeled as native fields—is preserved under ContractSpec.extensions.

Backward compatibility strategy:

Omit contract.json altogether — callers still get synthesized specs (CONTRACT-SPEC.md).
Add fields incrementally (capabilities, richer schemas). Unknown keys accumulate in extensions.
Bump contract_spec_format cautiously (2 is current sentinel).

Validation today (validate_contract_input / validate_contract_output) is intentionally shallow (requires dict, checks required keys exist, validates listed properties[].type at one level only).

lmeta flow schema (AutomationFlow)

The lmeta / AutomationFlow orchestration profile is a separate schema-shaped artifact from task ContractSpecs. Its structure is enforced at runtime by forge_lcdl.flow.schema (validate_source / validate_flow, MAX_AUTOMATION_FLOW_VERSION) and mirrored as JSON Schema for external tooling in forge-cdp-manager (flows/automation-flow-v{2,3,4}.schema.json).

v3 — operator refs, composition (kind: unit, forgeSubflow, include), inheritance.
v4 — opt-in governed-LLM decision layer: forgeDecide / forgeConsensus refs, the guard state, a per-state budget block, and inline on_error / timeout_ms on forgeLcdlRun. Each version is a strict superset; features are gated by automationFlowVersion and rejected in lower-version flows. See AutomationFlow v4 spec and the Decision break-in guide.

The governed automation_situation_arbitrate task backing the break-in is an ordinary ContractSpec (tri-state decided|ambiguous|escalate) with deterministic post-validation (out-of-set action → SchemaFailure).

Stability labels (informal until registry metadata exists)

Treat catalog tasks pw_* and stable generic_*/game helpers referenced from forge-certificators as integration-critical: prefer additive schema tightening + changelog bullets in contract.md.

Bench-only or exploratory tasks inherit ALPHA framing from docs/ALPHA-ROADMAP.md.

RAG / citations / caching fields

Higher-level policies live in ContractSpec but runner + task code decides enforcement:

capabilities — hints such as uses_llm, supports_rag, returns_citations.
rag_policy, inference_policy, prompt_cache_policy — defaults for benchmarks + docs; LcdlClient overlays consumer policies.

Human-only Markdown-only contracts may omit JSON entirely while adoption catches up (scripts/audit_contract_docs.py lists gaps).

Where to deepen next

Use audit_contract_docs.py --strict (locally / CI gate). --require-contract-identity enforces task_id / version fields on every sidecar. --strict-depth fails when those keys disagree with paths. --strict-md tightens Markdown templates.

Relationship to MCP / Cursor: MCP-SIDECAR.md and CURSOR-INTEGRATION.md.

Forge LCDL