Initial schemas and validation with extension workplan

workplans/MKTT-WP-0003-core-toolkit-implementation.md

@@ -52,7 +52,7 @@ sections, content blocks, parser tokens, API access, and `mkt parse`.
 
 ```task
 id: MKTT-WP-0003-T003
-status: todo
+status: done
 priority: high
 state_hub_task_id: "36a22def-d415-4c08-a793-836ee52e4308"
 ```
@@ -60,6 +60,9 @@ state_hub_task_id: "36a22def-d415-4c08-a793-836ee52e4308"
 Implement FR-010 through FR-012: define/derive schemas, validate documents,
 and report structured violations with file/location context.
 
+Initial implementation complete for Markdown schema loading, JSON Schema
+validation, structured violations, `mkt validate`, and `mkt schema validate`.
+
 ## P3.4 - Implement query and extraction
 
 ```task

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

@@ -0,0 +1,154 @@
+---
+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.