Implement the Rust Frontmatter Model and Initial Validator #2266

Parent EPIC: #2264 - Refactor Semantic Link and Frontmatter Conventions

Blocked by: #2265 - Inventory and Resolve Markdown Frontmatter Contracts

Goal

Implement canonical Rust types for the approved Markdown frontmatter v1 contract, generate a machine-readable schema from those types, and provide a small read-only validator that gives humans and AI agents deterministic field, scalar-type, allowed-value, and compatibility diagnostics.

Background

The repository currently describes frontmatter types in prose. AI agents must infer whether a field is required, nullable, date-like, enum-like, profile-specific, or an open extension. The predecessor issue resolves those ambiguities and supplies accepted and rejected fixtures.

Rust types are the canonical executable source of truth because they can be reused by future Rust automation selected by EPIC #2003. A generated schema exposes the same model to editors, agents, and external tools without creating a separately maintained contract.

The first implementation uses the predecessor's provisional reference model:

• skill-links deserialize to validated skill names;
• related-artifacts deserialize to a narrow union of repository-relative file or directory paths, issue #<number> references, and established review-finding:pr-<number>-<id> references;
• a document's own issue and EPIC relationships remain dedicated metadata fields;
• no new path:, adr:, rust-item:, or other typed reference syntax is introduced.

Repository-aware checks such as target existence are separate from YAML deserialization and structural profile validation.

The repository already has a precedent for this shape of work: contrib/dev-tools/checks/clippy-allow-reasons is a non-published workspace crate invoked by pre-commit.sh through cargo run --package. It was approved under the same EPIC #2003 early-work exception and shows an integration point that needs no new runner. This issue should evaluate that precedent first and record why it does or does not fit before choosing another location.

Scope

In Scope

• Select a minimal, replaceable Rust package or existing integration point consistent with EPIC Overhaul: Automation Tools and AI Agent Guardrails #2003's approved early-work boundary.
• Parse YAML frontmatter from tracked Markdown files that contain it.
• Represent the approved universal envelope and strict issue and EPIC profiles with canonical Rust types.
• Preserve explicitly approved compatibility cases and unknown document classes according to the predecessor's rollout policy.
• Represent the provisional v1 skill-links and related-artifacts value types without extending the semantic-link ontology.
• Separate syntax, structural/profile, and repository-aware validation layers.
• Generate a machine-readable schema from the canonical Rust model and verify generated output does not drift. The drift check must be reproducible without network access and must not add a new required toolchain component beyond the workspace's existing Rust toolchain.
• Emit stable, actionable diagnostics containing at least the source path, diagnostic category, severity, field path when applicable, and explanation. Classify the binary as no-stdout-result under the repository CLI output contract ADR: stdout remains empty, stderr contains NDJSON records, and exit codes are 0 for pass, 1 for validation/runtime failure, and 2 for invalid invocation. TTY refusal does not apply to this output class.
• Accept explicit file or directory paths for focused use, a --staged mode for pre-commit, and a manual whole-tree mode. Pre-commit is the only integration tier in this issue; CI integration is deferred to Overhaul: Automation Tools and AI Agent Guardrails #2003.
• Add accepted/rejected fixture tests and mutation evidence for representative field, scalar, allowed-value, reference, and lifecycle/path failures.
• Integrate the check into pre-commit without adding CI integration, a shared runner, cache, policy engine, or orchestration framework.
• Document the temporary integration point and how the model and fixtures can move into the architecture later selected by Overhaul: Automation Tools and AI Agent Guardrails #2003.

Out of Scope

• Defining semantic-link relation types or a complete knowledge graph.
• Adding new typed path-reference syntax.
• Requiring frontmatter on every Markdown document.
• Strictly rejecting every unknown document class in the first rollout.
• Bulk migration or rewriting of historical documents.
• Selecting Overhaul: Automation Tools and AI Agent Guardrails #2003's final automation binary, package structure, JSONL event contract, caching, or local/CI policy composition.
• Integrating the validator into CI, pre-push, nightly, release, or agent policy profiles.
• Validating ordinary Markdown links, which remain Lychee's responsibility.
• Validating the externally owned top-level frontmatter of SKILL.md and agent-profile files beyond the repository-owned metadata.semantic-links extension.
• Auto-fixing or rewriting frontmatter. The check is read-only; any formatter is a separate, later decision.

Architectural Decisions

• Canonical representation: Rust types derived from the approved inventory contract.
• External representation: generated machine-readable schema; never edited as a second source of truth.
• Validation layers: frontmatter/YAML syntax, typed structural profile, then repository semantics.
• Initial architecture: an independently testable and replaceable check using an existing integration tier; final placement remains owned by EPIC Overhaul: Automation Tools and AI Agent Guardrails #2003.
• Output: no-stdout-result under the CLI output contract ADR; no plain-text output at any verbosity and no TTY refusal.
• Dependencies: choose the YAML and schema-generation crates under the repository's dependency freshness policy and record the choice in the issue; prefer crates already in the workspace lockfile when they meet the need.
• Related ADR: docs/adrs/20260519000000_define_global_cli_output_contract.md.
• ADRs to create: Create a root ADR only if implementation requires a durable repository-wide choice beyond the decisions already approved in the parent and predecessor specifications.

Design and Ownership Review

The parser owns frontmatter extraction and YAML syntax reporting. Canonical model types own scalar representation and profile structure. Domain validators own cross-field invariants. Repository adapters own filesystem and repository lookups. The command surface owns discovery, diagnostic rendering, and exit status, but not the final orchestration contract reserved for #2003.

No network access, asynchronous readiness, or persistent resources are required. Tests use repository-local immutable fixtures or isolated temporary directories and must leave no tracked runtime state.

Split checkpoint. After the first passing issue-profile vertical slice (T3 plus the issue profile part of T4), stop and review the boundaries above. If the slice shows that schema generation (T6) or the existing-tier integration (T7) is independently reviewable and would otherwise make this issue's PR too large, split them into follow-up issues at that point rather than continuing. Record the decision in the progress log either way.

Implementation Plan

Status values: TODO, IN_PROGRESS, BLOCKED, DONE.

Commit Points

For every test-producing increment, follow the write-unit-test skill and record the required prose-first Arrange-Act-Assert design review before commit. Use signed Conventional Commits.

Acceptance Criteria

• AC1: Canonical Rust types represent the approved universal envelope and strict issue and EPIC profiles without duplicating an independently authored schema.
• AC2: Every accepted predecessor fixture parses and validates with its expected result; every rejected fixture produces the expected diagnostic category.
• AC3: Syntax, structural/profile, and repository-aware validation remain separate and are independently testable.
• AC4: The provisional reference model accepts only approved skill names, repository-relative paths, issue #<number> references, and review-finding: references in their respective fields and introduces no new typed relation syntax.
• AC5: A deterministic machine-readable schema is generated from the Rust model and a check fails when the tracked generated artifact drifts.
• AC6: Diagnostics identify the source path, category, severity, field path when applicable, and an actionable explanation; output and exit codes follow the CLI output contract ADR.
• AC7: The initial rollout validates every present Markdown frontmatter block, strictly enforces approved known profiles, and handles unknown classes and legacy documents according to the approved compatibility policy.
• AC8: Mutation evidence proves detection of malformed YAML, wrong scalar types, missing required fields, unknown allowed values, invalid provisional references, and representative lifecycle/path inconsistencies.
• AC9: The check uses an existing integration tier and remains replaceable; no shared runner, cache, policy engine, or final Overhaul: Automation Tools and AI Agent Guardrails #2003 architecture is introduced.
• AC10: Documentation identifies the canonical Rust source, generated artifact, temporary invocation, rollout behavior, and future Overhaul: Automation Tools and AI Agent Guardrails #2003 relocation boundary.
• AC11: The check is read-only and never modifies a document; a run against an unchanged tree leaves all tracked Markdown content and the Git index byte-identical.
• AC12: The staged-files and whole-tree modes produce consistent diagnostics for the same document.
• linter all and relevant Rust tests exit with code 0.
• Manual verification scenarios are executed and documented.
• Acceptance criteria are re-reviewed after implementation and reflect actual behavior.

Verification Plan

Automatic Checks

• Focused Rust unit tests for extraction, deserialization, profile validation, references, and diagnostics.
• Integration tests over accepted/rejected Markdown fixtures and isolated repository fixtures.
• Deterministic generated-schema drift check.
• Mutation checks for each failure class listed in AC8.
• cargo test --doc --workspace
• linter all
• Applicable pre-push checks before completion.

Manual Verification Scenarios

Status values: TODO, IN_PROGRESS, DONE, FAILED, BLOCKED.

Acceptance Verification

Risks and Trade-offs

• Combining model, schema generation, and validation can become too large. Preserve vertical slices and split the issue before implementation if the inventory reveals multiple independent document profile migrations.
• YAML implicit typing can turn date-like or boolean-like text into unexpected scalars. Fixtures must cover the approved quoting and coercion policy explicitly.
• Generated schemas cannot express every repository-aware invariant. Keep those checks in typed Rust validators and document that boundary rather than weakening the canonical model.
• Early integration may differ from Overhaul: Automation Tools and AI Agent Guardrails #2003's final architecture. Keep domain types, fixtures, and diagnostics independent from hook or CI orchestration so relocation does not alter semantics.
• Strict enforcement can create a large legacy backlog. Follow the approved prospective and compatibility modes instead of weakening diagnostics or rewriting history opportunistically.

Implementation Completion Review

After implementation, create implementation-retrospective.md if package placement, generated schema limitations, YAML behavior, compatibility findings, or #2003 integration materially differ from the specification. Otherwise record why the implementation confirmed the planned design.

References

• Parent EPIC: Refactor Semantic Link and Frontmatter Conventions #2264
• Parent automation EPIC: Overhaul: Automation Tools and AI Agent Guardrails #2003
• Blocked by: Inventory and Resolve Markdown Frontmatter Contracts #2265
• Related ADRs: docs/adrs/20260519000000_define_global_cli_output_contract.md
• Integration precedent: contrib/dev-tools/checks/clippy-allow-reasons/ (approved early work under EPIC Overhaul: Automation Tools and AI Agent Guardrails #2003 via Require Documented Clippy Allows #2157)