# Document Contract Framework

Date: 2026-05-03

## Purpose

The contract framework makes markdown documents practically checkable. It keeps
Markdown as the authoring surface and uses fenced YAML as a structured extension
for rules that need machine interpretation.

The first implementation is deterministic. It checks document type, fields,
sections, ordering, metric bands, and text assertions. Forms, context, and LLM
rubrics are represented in the contract vocabulary as extension points before
runtime adapters are added.

## Contract File Shape

A contract is a Markdown document with optional frontmatter and one fenced YAML
block marked as `yaml contract`.

````markdown
---
title: ADR Contract
version: "1.0"
---

# ADR Contract

```yaml contract
id: adr-contract-v1
document:
  type: adr
  title: Architecture Decision Record
fields:
  status:
    type: string
    required: true
sections:
  - id: context
    title: Context
    presence: required
    level: 2
metrics:
  document:
    words:
      min: 100
      max: 1200
      severity: warning
```
````

Markdown carries the explanation. YAML carries the contract.

## Core Terms

| Term | Meaning |
| --- | --- |
| Document contract | The machine-readable agreement for one typed Markdown artifact. |
| Document type | A named kind such as `adr`, `prd`, `workplan`, or `business-letter`. |
| Section spec | A semantic section role with matching headings, presence, level, order, metrics, and assertions. |
| Field spec | A typed value expected in frontmatter or later external context. |
| Metric band | A soft or hard size/complexity target. |
| Assertion | A deterministic content expectation over document or section text. |
| Diagnostic | A structured finding with severity, code, source, contract location, rule id, and guidance. |

## Section Presence

Section specs support these presence values:

- `required`: missing section is an error.
- `recommended`: missing section is a warning.
- `optional`: section is allowed but not required.
- `discouraged`: present section is a warning.
- `forbidden`: present section is an error.

Headings are matched case-insensitively against `title`, `id`, `headings`, or
`aliases`.

## Metric Bands

Supported metrics are:

- `characters`
- `words`
- `sentences`
- `paragraphs`
- `sections`
- `headings`
- `list_items`
- `code_blocks`
- `max_heading_depth`
- `nesting_depth`

Document-level bands live under `metrics.document`. Section-level bands live
inside a section spec.

The current metrics layer follows the parser model: every heading-led region is
a section, including the document H1 title section.

## Assertions

Assertions currently support:

- `contains`
- `contains_any`
- `not_contains`
- `matches`
- `not_matches`

Assertions are deterministic and produce the same diagnostic model as sections,
fields, and metric bands. This is the bridge to later LLM rubrics: semantic
checks can become additional assessments without changing how failures are
reported.

## Forms And Context

Field specs are the first step toward form-backed Markdown generation. Runtime
form handling should build on the same field vocabulary:

- `id`
- `type`
- `required`
- `default`
- `source`
- `path`
- `enum`
- `pattern`
- `min` / `max`
- `min_length` / `max_length`

Dynamic requiredness, visibility, calculations, and prefill should be declared
as context-aware rules in later work. The contract should remain the source of
truth, while UI and generation layers act as adapters.

## LLM Assessment Extension

LLM-assisted checks should be declared as rubrics, scoped to document or section
roles. Core Markitect should not call a provider directly. A future adapter
should accept a provider-neutral request:

- contract id and rule id
- document or section text
- relevant fields and context
- rubric criteria
- cache key material

It should return:

- pass/fail
- score
- reason
- model/provider metadata
- diagnostics using the shared diagnostic model

## Deferred Runtime Work

The deterministic contract framework is ready now. The runtime engines are
deferred to `MKTT-WP-0005-runtime-context-and-assessment-engines.md`.

Pick that work up when one of these becomes true:

- contract checks need external user, project, or entity context
- generation needs reliable field prefill before rendering
- a UI or agent workflow needs form state, defaults, and dynamic requiredness
- deterministic section assertions are not enough and rubric-based semantic
  assessment becomes necessary

The intended order is context and form runtime first, deterministic dynamic
rules second, LLM assessment execution third.

## CLI

```text
mkt contract validate <contract.md>
mkt contract check <document.md> --contract <contract.md>
mkt metrics <document.md>
```