Contract framework with markdown-native contracts utilizing fenced YAML blocks

examples/documents/adr-invalid.md

@@ -0,0 +1,13 @@
+---
+document_type: adr
+---
+
+# Weak ADR
+
+## Context
+
+This is short.
+
+## Deprecated Approach
+
+This section should not be here.

examples/documents/adr-valid.md

@@ -0,0 +1,23 @@
+---
+document_type: adr
+status: accepted
+---
+
+# Use Markdown Contracts
+
+## Context
+
+The problem is that plain heading counts do not explain whether content is
+useful. Authors and agents need a contract that names the expected sections and
+the job each section must do.
+
+## Decision
+
+We will use markdown-native document contracts with deterministic diagnostics as
+the foundation for generation, validation, and later semantic assessment.
+
+## Consequences
+
+The tool can check author intent before generation or review work continues.
+Future adapters can add form prefill and LLM rubrics without replacing the core
+diagnostic model.

examples/documents/business-letter-invalid.md

@@ -0,0 +1,14 @@
+---
+document_type: business-letter
+recipient_name: Ada Lovelace
+---
+
+# Incomplete Letter
+
+## Greeting
+
+Hello,
+
+## Body
+
+Thanks.

examples/documents/business-letter-valid.md

@@ -0,0 +1,25 @@
+---
+document_type: business-letter
+recipient_name: Ada Lovelace
+sender_name: Markitect Team
+---
+
+# Follow-Up Letter
+
+## Greeting
+
+Dear Ada Lovelace,
+
+## Body
+
+Thank you for the thoughtful discussion about structured Markdown generation.
+We reviewed the requirements and will send a concise proposal that separates
+document contracts, field prefill, validation diagnostics, and optional semantic
+assessment. This keeps the implementation practical while leaving room for
+future automation.
+
+## Closing
+
+Kind regards,
+
+Markitect Team

examples/documents/concept-note-invalid.md

@@ -0,0 +1,15 @@
+---
+document_type: concept-note
+concept_id: contract-diagnostic-model
+status: maybe
+---
+
+# Contract Diagnostic Model
+
+## Definition
+
+A vague note.
+
+## Relationships
+
+It relates to other things.

examples/documents/concept-note-valid.md

@@ -0,0 +1,24 @@
+---
+document_type: concept-note
+concept_id: contract-diagnostic-model
+status: draft
+---
+
+# Contract Diagnostic Model
+
+## Definition
+
+A contract diagnostic model is the shared representation for validation,
+assessment, and repair findings emitted by Markitect pipeline tools.
+
+## Assertions
+
+The central claim is that authors and agents need one diagnostic vocabulary
+across structural checks, field checks, metric bands, and semantic assessments.
+Evidence comes from the way legacy Markitect scattered related failures across
+different subsystems.
+
+## Relationships
+
+The model relates to document contracts, form fields, section specifications,
+and future LLM rubric adapters.

examples/documents/prd-frs-invalid.md

@@ -0,0 +1,18 @@
+---
+document_type: prd-frs
+product: Markitect Tool
+---
+
+# Thin PRD
+
+## Problem
+
+The document is too vague.
+
+## Goals
+
+The goals are listed without criteria.
+
+## Implementation Plan
+
+Build something immediately.

examples/documents/prd-frs-valid.md

@@ -0,0 +1,31 @@
+---
+document_type: prd-frs
+product: Markitect Tool
+owner: Platform Architecture
+---
+
+# Markitect Tool PRD And FRS
+
+## Problem
+
+Markdown pipelines often check document shape without knowing whether the
+sections contain the content needed by authors, reviewers, and generation
+agents.
+
+## Goals
+
+The product should make document contracts testable. Success metrics include
+clear diagnostics, stable CLI behavior, and examples that show how contracts
+apply to real document types.
+
+## Functional Requirements
+
+- Load Markdown contract files with fenced YAML contract blocks.
+- Check required fields and section presence.
+- Report metric bands and deterministic assertions.
+- Produce machine-readable and human-readable diagnostics.
+
+## Non-Goals
+
+The first release does not execute provider-specific LLM calls or provide a UI
+form renderer.

examples/documents/workplan-invalid.md

@@ -0,0 +1,14 @@
+---
+document_type: workplan
+status: blocked
+---
+
+# Weak Workplan
+
+## Purpose
+
+There is not enough implementation shape here.
+
+## Tasks
+
+The task list is prose only.

examples/documents/workplan-valid.md

@@ -0,0 +1,26 @@
+---
+document_type: workplan
+id: MKTT-WP-EXAMPLE
+status: active
+---
+
+# Example Workplan
+
+## Purpose
+
+Establish a focused implementation slice with enough structure for State Hub,
+human review, and follow-on implementation.
+
+## Tasks
+
+```task
+id: MKTT-WP-EXAMPLE-T001
+status: todo
+priority: high
+```
+
+Implement the smallest practical behavior and verify it through the CLI.
+
+## Decision Point
+
+Continue only if diagnostics are clear enough for humans and agents.