---
id: MKTT-WP-0004
type: workplan
title: "Practical Document Contract Framework"
domain: markitect
status: proposed
owner: markitect-tool
topic_slug: markitect
created: "2026-05-03"
updated: "2026-05-03"
---

# MKTT-WP-0004: Practical Document Contract Framework

## Purpose

Improve the practical utility of `markitect-tool` by moving beyond generic
heading-count schema validation toward document contracts with section
specifications, fields/forms, context-aware rules, metric bands, optional LLM
assessments, and unified diagnostics.

## Background

Research and legacy comparison are captured in:

- `docs/practical-schema-framework-research.md`
- `docs/markitect-main-scope-assessment.md`
- `docs/markitect-main-test-migration-inventory.md`

## P4.1 - Define contract terminology and file format

```task
id: MKTT-WP-0004-T001
status: todo
priority: high
```

Define the first `DocumentContract` format in markdown/YAML:

- document type
- section specifications
- field/form specifications
- deterministic rules/assertions
- metric bands
- optional assessment rubrics
- diagnostic metadata

Keep it provider-neutral and readable by humans.

## P4.2 - Implement unified diagnostic model

```task
id: MKTT-WP-0004-T002
status: todo
priority: high
```

Create diagnostics with severity, code, message, source location, contract
location, rule id, and optional repair guidance. Use this model for JSON Schema
violations and all new contract checks.

## P4.3 - Implement section specifications

```task
id: MKTT-WP-0004-T003
status: todo
priority: high
```

Support required, recommended, optional, discouraged, and forbidden sections.
Support aliases, expected heading level, section type, ordering constraints,
and clear diagnostics.

## P4.4 - Implement metric bands

```task
id: MKTT-WP-0004-T004
status: todo
priority: medium
```

Support document-level and section-level bands for words, characters,
sentences, paragraphs, sections, list items, code blocks, and nesting depth.
Allow soft warnings and hard errors.

## P4.5 - Design form and context model

```task
id: MKTT-WP-0004-T005
status: todo
priority: medium
```

Specify fields, defaults, prefill sources, dynamic requiredness, conditional
visibility, calculations, and validation against external context. This task is
design-first; implementation can follow in a later workplan.

## P4.6 - Design LLM assessment adapter contract

```task
id: MKTT-WP-0004-T006
status: todo
priority: medium
```

Define provider-neutral request/response models for section-level rubrics:
criteria, inputs, context, score, pass/fail, reason, model metadata, and cache
keys. Do not bind core logic to any provider.

## P4.7 - Add practical CLI surface

```task
id: MKTT-WP-0004-T007
status: todo
priority: high
```

Add:

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

Ensure output is useful to humans and machines.

## P4.8 - Build use-case examples

```task
id: MKTT-WP-0004-T008
status: todo
priority: medium
```

Create examples for:

- ADR
- PRD/FRS
- workplan
- personalized/business letter
- concept note or entity profile

Each example should include contract, valid document, invalid document, and
expected diagnostics.

## Decision Point

This workplan should probably run before WP-0003 query/transform/cache work,
because it changes what "validation" means and establishes the diagnostic model
that later query/transform/generation features should reuse.

If postponed, continue WP-0003 with query/extraction only if we commit to
revisiting diagnostics and contract semantics before generation or LLM hooks.