Validation and Dashboards

This guide covers the current downstream workflow after mining:

source text
  -> patterns.yml
  -> compiled-pattern-spec.yml
  -> validation-index.json / .md
  -> validation-dashboard.html

Use it when you want to:

  • validate generated drafts against a compiled pattern spec
  • review failures across a whole folder of drafts
  • render an HTML dashboard without building a separate app

1. Start from mined patterns

Mine a source document into the evidence artifact:

mplm mine examples/example1.md --out patterns.yml --min-support 1

Compile that into the bridge spec used by validators and dashboards:

mplm compile-spec patterns.yml --out compiled-pattern-spec.yml

At this point you have:

  • patterns.yml: mined structural evidence
  • compiled-pattern-spec.yml: templates, generation programs, writer guides, and validation contracts

2. Choose the template or contract

Validation runs against one compiled template or contract at a time.

Typical options:

  • --template-id <template-id>
  • --contract-id <contract-id>

If the spec only contains one validation contract, you can omit both. If it contains several, provide one explicitly.

For the example corpus in this repo, the paragraph template compiled from examples/example1.md is:

tmpl-l3-s-s-s

3. Validate a batch of drafts

Validate a whole folder and write an aggregate bundle:

mplm validate-index compiled-pattern-spec.yml examples/dashboard-drafts \
  --template-id tmpl-l3-s-s-s \
  --out validation-index.json

This produces:

  • validation-index.json
  • validation-index_details/*.json

The aggregate JSON includes:

  • batch counts and average score
  • per-draft sort_key
  • per-draft severity_summary
  • failure frequency index
  • deep links into the detail bundle

If you prefer Markdown:

mplm validate-index compiled-pattern-spec.yml examples/dashboard-drafts \
  --template-id tmpl-l3-s-s-s \
  --out validation-index.md

4. Render the HTML dashboard from JSON

Once you have the JSON bundle, render the dashboard:

mplm render-dashboard validation-index.json --out validation-dashboard.html

Optional title override:

mplm render-dashboard validation-index.json \
  --out validation-dashboard.html \
  --title "Template Review"

What the dashboard gives you:

  • summary cards for pass/fail counts and average score
  • sortable and filterable draft queue
  • inline per-draft failed-check detail sections
  • links into the detail-report bundle when present
  • client-side CSV export for the currently filtered queue

If the dashboard is written to a different folder than the JSON bundle, links are automatically rebased.

5. Render the dashboard directly from a spec plus drafts

If you do not need a persisted JSON bundle first, render the dashboard directly:

mplm render-dashboard \
  --spec-path compiled-pattern-spec.yml \
  --drafts-root examples/dashboard-drafts \
  --template-id tmpl-l3-s-s-s \
  --out validation-dashboard.direct.html

Direct mode runs validation in memory and writes the HTML dashboard immediately.

Use direct mode when:

  • you want a fast one-step review artifact
  • you do not need the intermediate JSON bundle
  • you are iterating locally on a drafts folder

Use JSON-bundle mode when:

  • you want machine-readable artifacts for automation
  • you want linked per-draft detail reports
  • you want to archive or post-process the validation data

6. Example files in this repo

The repository already includes example artifacts you can inspect:

  • examples/dashboard-patterns.example.yml
  • examples/dashboard-compiled-spec.example.yml
  • examples/validation-index.example.json
  • examples/validation-dashboard.example.html
  • examples/validation-dashboard.direct.example.html

Example draft set:

  • examples/dashboard-drafts/pass.md
  • examples/dashboard-drafts/fail-structure.md
  • examples/dashboard-drafts/fail-policy.md
  • examples/dashboard-drafts/fail-lexical.md

7. Practical review loop

A typical workflow looks like this:

  1. Mine representative corpus text into patterns.yml.
  2. Compile a spec and identify the template you care about.
  3. Validate a batch of candidate drafts.
  4. Open the HTML dashboard and sort by review urgency.
  5. Export the filtered queue to CSV if you want to triage elsewhere.
  6. Revise drafts, then re-run validation.

8. Troubleshooting

If render-dashboard fails in direct mode:

  • make sure you passed both --spec-path and --drafts-root
  • provide --template-id or --contract-id if the spec has multiple contracts

If the dashboard shows no external detail links:

  • that is expected in direct mode
  • use validate-index --out validation-index.json first if you want a linked detail bundle

If no drafts are found:

  • check --exts
  • check whether you need --recursive