Skip to content

[Change] Doc Frontmatter Schema & Validation #461

@djm81

Description

@djm81

User Story

As a SpecFact maintainer, I want documentation pages to declare ownership and tracked source paths in YAML frontmatter, with automated validation in pre-commit and Hatch, so docs stay aligned with code and rollout can expand safely.

OpenSpec Change

  • Change folder: openspec/changes/doc-frontmatter-schema/
  • Parent Feature: #356 — Documentation & Discrepancy Remediation
  • Priority: P2
  • Depends on: none (foundational for ci-docs-sync-check)
  • Related: openspec/changes/ci-docs-sync-check/ (follow-up)

Scope

  • scripts/check_doc_frontmatter.py + scripts/check-doc-frontmatter.py — validate doc_owner, tracks, last_reviewed, exemption fields
  • Rollout via docs/.doc-frontmatter-enforced (expand paths over time); --all-docs for full-site check
  • hatch run doc-frontmatter-check; wired into docs-validate and pre-commit (check-doc-frontmatter)
  • Guide: docs/contributing/docs-sync.md; CONTRIBUTING updated; sample pages with full schema

Acceptance

  • Enforced-path validation passes on CI; tests cover unit + integration scenarios
  • openspec validate doc-frontmatter-schema --strict passes

Metadata

Metadata

Assignees

Labels

Projects

Status

Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions