frontmattering 0.5.5

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.

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.5 package fixes a runtime report-parity defect: the validate-only runtime now emits the same canonical selection + project evidence as the main CLI, so a runtime GO can no longer hide that Markdown existed outside the configured corpus (outside_selection_markdown_count). Both surfaces build these report fields from a single shared SelectionResult.report_fields(), and a CI gate plus a .pyz-executing test prevent the two report contracts from drifting again. It carries forward the 0.5.4 generated runtime CLI (whose surface and help stay in lock-step with the main 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. Operation-wide mutation transactions, a hermetic runtime, an execution-record verifier, and other items are deliberately deferred and tracked in docs/DEFERRED_ITEMS_LEDGER.md. Custom license text should still receive legal review before paid commercial sales.