markitect-tool/workplans/MKTT-WP-0004-practical-contract-framework.md

id, type, title, domain, status, owner, topic_slug, planning_priority, planning_order, depends_on_workplans, created, updated, state_hub_workstream_id

id	type	title	domain	status	owner	topic_slug	planning_priority	planning_order	depends_on_workplans	created	updated	state_hub_workstream_id
MKTT-WP-0004	workplan	Practical Document Contract Framework	markitect	done	markitect-tool	markitect	complete	30	MKTT-WP-0001 MKTT-WP-0002	2026-05-03	2026-05-03	558787e1-d287-46a5-9214-634e8b90a858

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.

Implementation Result

Initial deterministic contract framework implemented:

• Markdown contract files with fenced yaml contract blocks.
• Shared diagnostic model with severity, code, source, contract location, rule id, details, and repair guidance.
• Contract validation, document contract checking, and metrics CLI commands.
• Required/recommended/optional/discouraged/forbidden section specs.
• Field specs for frontmatter values.
• Document-level and section-level metric bands.
• Deterministic content assertions.
• Design documentation for form/context and provider-neutral LLM rubric adapters.
• Example contracts, valid documents, invalid documents, and expected diagnostic notes for ADR, PRD/FRS, workplan, business letter, and concept note use cases.

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

id: MKTT-WP-0004-T001
status: done
priority: high
state_hub_task_id: "2065d56a-9371-4fd0-9a3d-7a69c718e851"

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

id: MKTT-WP-0004-T002
status: done
priority: high
state_hub_task_id: "3ed3af1b-c747-492c-acda-ecb4ee564a38"

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

id: MKTT-WP-0004-T003
status: done
priority: high
state_hub_task_id: "c4166e5a-53a5-4207-a3fb-b4ddf388cd5e"

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

id: MKTT-WP-0004-T004
status: done
priority: medium
state_hub_task_id: "304af70e-1a33-4ee2-bcbd-7b966436cf37"

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

id: MKTT-WP-0004-T005
status: done
priority: medium
state_hub_task_id: "1bcc82fe-b578-446c-86a7-938f732b24fa"

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.

Design captured in docs/contract-framework.md. Runtime form rendering, dynamic visibility, calculations, and context resolvers remain later adapter work.

P4.6 - Design LLM assessment adapter contract

id: MKTT-WP-0004-T006
status: done
priority: medium
state_hub_task_id: "bef295ba-fbc0-4df6-9cc4-040ed9b5f346"

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.

Provider-neutral adapter shape captured in docs/contract-framework.md. Execution, caching, and provider integration remain later work.

P4.7 - Add practical CLI surface

id: MKTT-WP-0004-T007
status: done
priority: high
state_hub_task_id: "9f61a5af-0b65-460a-8231-ec50279c5c6a"

Add:

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

id: MKTT-WP-0004-T008
status: done
priority: medium
state_hub_task_id: "7ec8c0f2-c598-4095-aefe-f6f97e84a470"

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.