Contract framework with markdown-native contracts utilizing fenced YAML blocks

examples/contracts/adr.contract.md

@@ -0,0 +1,52 @@
+---
+title: ADR Contract
+version: "1.0"
+---
+
+# ADR Contract
+
+```yaml contract
+id: adr-contract-v1
+document:
+  type: adr
+  title: Architecture Decision Record
+fields:
+  status:
+    type: string
+    required: true
+    enum: [proposed, accepted, superseded]
+metrics:
+  document:
+    words:
+      min: 40
+      max: 900
+      severity: warning
+sections:
+  - id: context
+    title: Context
+    presence: required
+    level: 2
+    order:
+      before: decision
+    assertions:
+      - id: context-names-problem
+        contains_any: [problem, motivation, constraint]
+        severity: warning
+        guidance: Explain why the decision exists.
+  - id: decision
+    title: Decision
+    presence: required
+    level: 2
+    assertions:
+      - id: decision-commits
+        matches: "\\b(choose|adopt|use|will)\\b"
+        severity: error
+        guidance: State the actual decision, not only background.
+  - id: consequences
+    title: Consequences
+    presence: recommended
+    level: 2
+  - id: deprecated
+    title: Deprecated Approach
+    presence: forbidden
+```

examples/contracts/business-letter.contract.md

@@ -0,0 +1,43 @@
+---
+title: Business Letter Contract
+version: "0.1"
+---
+
+# Business Letter Contract
+
+```yaml contract
+id: business-letter-contract-v1
+document:
+  type: business-letter
+fields:
+  recipient_name:
+    type: string
+    required: true
+    source: context.recipient.name
+  sender_name:
+    type: string
+    required: true
+    source: context.sender.name
+sections:
+  - id: greeting
+    title: Greeting
+    presence: required
+    level: 2
+  - id: body
+    title: Body
+    presence: required
+    level: 2
+    metrics:
+      words:
+        min: 40
+        max: 350
+        severity: warning
+  - id: closing
+    title: Closing
+    presence: required
+    level: 2
+rubrics:
+  - id: tone-fit
+    scope: section.body
+    criteria: The body should match the relationship and communication purpose.
+```

examples/contracts/concept-note.contract.md

@@ -0,0 +1,43 @@
+---
+title: Concept Note Contract
+version: "0.1"
+---
+
+# Concept Note Contract
+
+```yaml contract
+id: concept-note-contract-v1
+document:
+  type: concept-note
+fields:
+  concept_id:
+    type: string
+    required: true
+  status:
+    type: string
+    required: true
+    enum: [draft, reviewed, accepted, archived]
+sections:
+  - id: definition
+    title: Definition
+    presence: required
+    level: 2
+  - id: assertions
+    title: Assertions
+    presence: required
+    level: 2
+    assertions:
+      - id: assertions-use-claims
+        contains_any: [claim, evidence, assumption]
+        severity: warning
+  - id: relationships
+    title: Relationships
+    presence: recommended
+    level: 2
+metrics:
+  document:
+    words:
+      min: 120
+      max: 1200
+      severity: warning
+```

examples/contracts/prd-frs.contract.md

@@ -0,0 +1,49 @@
+---
+title: PRD and FRS Contract
+version: "0.1"
+---
+
+# PRD And FRS Contract
+
+```yaml contract
+id: prd-frs-contract-v1
+document:
+  type: prd-frs
+fields:
+  product:
+    type: string
+    required: true
+  owner:
+    type: string
+    required: true
+metrics:
+  document:
+    words:
+      min: 300
+      max: 4000
+      severity: warning
+sections:
+  - id: problem
+    title: Problem
+    presence: required
+    level: 2
+  - id: goals
+    title: Goals
+    presence: required
+    level: 2
+    assertions:
+      - id: goals-are-testable
+        contains_any: [measure, metric, success]
+        severity: warning
+  - id: functional-requirements
+    title: Functional Requirements
+    presence: required
+    level: 2
+  - id: non-goals
+    title: Non-Goals
+    presence: recommended
+    level: 2
+  - id: implementation-plan
+    title: Implementation Plan
+    presence: discouraged
+```

examples/contracts/workplan.contract.md

@@ -0,0 +1,43 @@
+---
+title: Workplan Contract
+version: "0.1"
+---
+
+# Workplan Contract
+
+```yaml contract
+id: workplan-contract-v1
+document:
+  type: workplan
+fields:
+  id:
+    type: string
+    required: true
+  status:
+    type: string
+    required: true
+    enum: [proposed, active, done, deferred]
+sections:
+  - id: purpose
+    title: Purpose
+    presence: required
+    level: 2
+  - id: tasks
+    title: Tasks
+    presence: required
+    level: 2
+    assertions:
+      - id: tasks-have-task-blocks
+        contains: "status:"
+        severity: error
+  - id: decision-point
+    title: Decision Point
+    presence: recommended
+    level: 2
+metrics:
+  document:
+    sections:
+      min: 2
+      max: 12
+      severity: warning
+```

examples/diagnostics/adr-invalid.expected-diagnostics.md

@@ -0,0 +1,8 @@
+# Expected Diagnostics: adr-invalid.md
+
+- `contract.field.missing`: `status` is required.
+- `contract.metric.too_low`: the document is below the target word band.
+- `contract.assertion.contains_any_missing`: context does not mention problem, motivation, or constraint.
+- `contract.section.missing`: `decision` is required.
+- `contract.section.recommended_missing`: `consequences` is recommended.
+- `contract.section.forbidden`: `deprecated` is present.

examples/diagnostics/business-letter-invalid.expected-diagnostics.md

@@ -0,0 +1,5 @@
+# Expected Diagnostics: business-letter-invalid.md
+
+- `contract.field.missing`: `sender_name` is required.
+- `contract.section.missing`: `closing` is required.
+- `contract.metric.too_low`: the `Body` section is below the target word band.

examples/diagnostics/concept-note-invalid.expected-diagnostics.md

@@ -0,0 +1,5 @@
+# Expected Diagnostics: concept-note-invalid.md
+
+- `contract.field.enum`: `status` must be one of the allowed lifecycle values.
+- `contract.metric.too_low`: the document is below the target word band.
+- `contract.section.missing`: `assertions` is required.

examples/diagnostics/prd-frs-invalid.expected-diagnostics.md

@@ -0,0 +1,8 @@
+# Expected Diagnostics: prd-frs-invalid.md
+
+- `contract.field.missing`: `owner` is required.
+- `contract.metric.too_low`: the document is below the target word band.
+- `contract.assertion.contains_any_missing`: goals do not mention measure, metric, or success.
+- `contract.section.missing`: `functional-requirements` is required.
+- `contract.section.recommended_missing`: `non-goals` is recommended.
+- `contract.section.discouraged`: `implementation-plan` is discouraged in this contract.

examples/diagnostics/workplan-invalid.expected-diagnostics.md

@@ -0,0 +1,6 @@
+# Expected Diagnostics: workplan-invalid.md
+
+- `contract.field.missing`: `id` is required.
+- `contract.field.enum`: `status` must be one of the allowed lifecycle values.
+- `contract.assertion.contains_missing`: the `Tasks` section lacks task metadata.
+- `contract.section.recommended_missing`: `decision-point` is recommended.

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.