generated from coulomb/repo-seed
155 lines
3.6 KiB
Markdown
155 lines
3.6 KiB
Markdown
---
|
|
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.
|