frontmattering 0.5.6

Governed frontmatter, freshness tethers, and validate-only runtime gates for agent-facing Markdown

Frontmattering

Frontmattering makes Markdown safer for agents.

It adds governed frontmatter, task routing, body/frontmatter freshness tethers, and a vendorable validate-only runtime gate so an agent can consume a compact brief without silently relying on stale documentation.

Install

python -m pip install frontmattering
frontmattering --version
frontmattering doctor

First-hour path

frontmattering init . scaffolds a starter router under docs/, and frontmattering new creates governed documents. This block runs verbatim in an empty directory (it is executed as a release gate in CI):

frontmattering init . --set-id MYDOCS --title "My docs"
frontmattering new docs/10_GUIDE.md --profile guide --title "My guide"
frontmattering tether update --add .
frontmattering validate .
frontmattering brief .

Already have Markdown under docs/? Add governance to a file you already have with promote (one file per call):

frontmattering promote docs/YOUR_GUIDE.md --profile guide --in-place

Promoting a file outside the selected corpus fails before the file is touched (FRONTMATTERING-AUTHORING-TARGET-OUTSIDE-CORPUS).

For strict freshness enforcement, set validation_profile: trust in .frontmattering/project.yaml, then re-run frontmattering validate . and frontmattering brief ..

Runtime gate

frontmattering runtime pack --out frontmattering-runtime.pyz
python frontmattering-runtime.pyz validate docs --format json

The runtime artifact is validate-only. It does not expose init, promote, new, index, tether update, or authoring surfaces.

GO means every selected document passed — not that every Markdown file under the supplied path was selected. The report always names the boundary: selection.outside_selection_markdown_count (with selection.outside_selection_paths and …_sha256) counts Markdown discovered under the supplied path but outside the configured corpus. Note that discovery is relative to what you validate:

# corpus-only: validates docs/**/*.md; does not discover Markdown elsewhere
python frontmattering-runtime.pyz validate docs --format json

# whole-tree boundary audit: discovers all Markdown under . and reports what the corpus left out
python frontmattering-runtime.pyz validate . --format json | jq '.selection.outside_selection_markdown_count, .selection.outside_selection_paths'

Both the runtime and the main CLI emit the identical selection/project evidence, so either surface can gate on the boundary.

Prompt pack

The validator proves your frontmatter is valid, current, scoped, and tethered. It does not prove the frontmatter is good — a GO document can still carry a copied summary or a generic deepest intention. The governed prompt pack closes that gap: it makes authoring excellent, body-grounded frontmatter repeatable.

frontmattering prompt list
frontmattering prompt inspect author-category-frontmatter
frontmattering prompt render \
  --task author-category-frontmatter \
  --category self_protection_layer \
  --support-profile frontmattering_only \
  --corpus-root docs \
  --output rendered_prompt.md --receipt-out render_receipt.yaml

prompt render is deterministic: it composes the prompt from a packaged task template, a structured category profile, a support profile, and shared fragments, and binds the rendered bytes to every input's digest — including the authorizing manifest, renderer source, distribution, and serializer identity. The core CLI never executes an LLM — a rendered prompt proves only that the bytes were deterministically composed, not that a model ran or that an authoring result is semantically correct.

Run frontmattering prompt verify (also a doctor step) to confirm the packaged pack renders cleanly, reproduces its worked example, and conforms to its own shipped JSON schemas. Run frontmattering prompt verify-rendered --prompt rendered_prompt.md --receipt render_receipt.yaml --request render_request.yaml to verify a rendered prompt: it re-renders the canonical prompt from the request against the installed pack and compares byte-for-byte, rejecting a non-canonical or re-sealed prompt (FRONTMATTERING-PROMPT-NOT-CANONICAL) and any unauthorized task/category/profile.

This establishes reproducibility — the prompt is the canonical render of that request on this installed pack. It is not, on its own, provenance that the request was authorized: a producer who controls the request and re-renders honestly produces a valid prompt. Hostile-producer provenance requires signing the request/receipt under an independent authority (tracked as deferred in docs/DEFERRED_ITEMS_LEDGER.md).

License

Frontmattering is source-available. It is free for individual personal use within the scope of LICENSE.md. Professional, organizational, employer, client, CI/CD, hosted, managed-service, platform, consulting, or revenue-connected use is permitted for a 30-day evaluation period under LICENSE.md; continued use after the evaluation requires a paid commercial license.

Frontmattering is not open-source software under the Open Source Definition because professional and organizational use is restricted without a commercial license.

Runtime dependency status is recorded in THIRD_PARTY_NOTICES.md; project notices are recorded in NOTICE.

Claim boundary

A FRESH brief means the current body bytes and canonical trust-bearing frontmatter fields match their mechanical tether. It does not prove semantic summary correctness, human approval, external adoption, or production suitability.

A STALE or UNTETHERED summary must not be relied on without reading the body.

Publication status

This v0.5.6 package improves validation-boundary reporting: the selection payload now exposes the path identities of Markdown discovered outside the configured corpus (outside_selection_paths, bounded, with outside_selection_paths_sha256) alongside the existing count — the count gates, the identities enable repair — and both the main CLI and the packed runtime emit them. Because the report shape changed, the report contracts are versioned honestly (frontmattering_runtime_validate_only/v0_3, frontmattering_selection/v0_2), and the README now states plainly that GO means every selected document passed, not that every Markdown file under the supplied path was selected. It carries forward the 0.5.5 runtime report-parity fix, the 0.5.4 generated runtime CLI, the 0.5.3 complete CLI help, and the 0.5.2 prompt-evidence layer, and makes no CLI surface, validator trust-semantics, frontmatter-schema, or canonical-model (v0.1.5) changes. The strict corpus-completeness gate and other items remain deliberately deferred and tracked in docs/DEFERRED_ITEMS_LEDGER.md. Custom license text should still receive legal review before paid commercial sales.